instinct

<!-- mcp-name: io.github.WRG-11/instinct --> # instinct > 💡 **Found this useful?** ⭐ Star the repo (helps others find it) and subscribe to weekly detection-engineering writeups at [Detection Frontier](https://detection-frontier.kit.com/subscribe). [](https://pypi.org/project/instinct-mcp/) [](https://pypi.org/project/instinct-mcp/) [](https://github.com/WRG-11/instinct/actions/workflows/ci.yml) [](https://github.com/WRG-11/instinct/actions/workflows/codeql.yml) [](https://github.com/WRG-11/instinct/blob/main/LICENSE) [](https://modelcontextprotocol.io) [](#) > **Self-learning memory for AI coding agents: record repeated patterns, score them by confidence, and surface mature guidance back through MCP.** - Records tool sequences, user preferences, recurring fixes, and useful tool combinations. - Promotes repeated observations from `raw` to `mature`, `rule`, and cross-project `universal`. - Exports learned rules for Claude, Cursor, Windsurf, Codex, CLAUDE.md, and Agent Skills. **Current release**: `1.4.4` (April 2026; transferred to WRG-11 org). Python `>=3.11`. SQLite WAL storage at `~/.instinct/instinct.db`. Single runtime dep (`mcp>=1.0.0`). ```bash pip install instinct-mcp ``` Live install stats: [pypistats.org/packages/instinct-mcp](https://pypistats.org/packages/instinct-mcp). ## Quick Start For Claude Code: ```bash pip install instinct-mcp claude mcp add instinct -- instinct serve instinct observe "seq:test->fix->test" ``` Then ask your agent for suggestions, or run: ```bash instinct suggest ``` Suggestions appear once a pattern reaches `mature` confidence. By default, `mature` starts at confidence 5 and `rule` starts at confidence 10. ## What It Learns You feed instinct one `observe` call per recurring behaviour you want it to remember. Each call increments confidence on the matching pattern; once confidence reaches the `mature` threshold (default: 5), the pattern shows up in `suggest` and can be exported back into your agent's rule files. Four prefix conventions help organise + search the store: ```bash instinct observe "seq:lint->fix->lint" # tool-sequence patterns instinct observe "pref:commits=conventional" # user preferences instinct observe "fix:utf8-encoding-windows" # recurring fixes instinct observe "combo:pytest+coverage" # tool combinations ``` Pattern prefixes are conventional, not magic: `seq:`, `pref:`, `fix:`, and `combo:` keep the store searchable and easier to export. Add `--cat <category>` to override the auto-inferred category if needed. ## Tool Surface A representative slice of the MCP tool surface; see the [CLI Reference section](#cli-reference) below for the complete command list. | Tool / command | Use it for | |---|---| | `observe` | Record or reinforce one pattern; repeats increment confidence. | | `suggest` | Return mature patterns for current agent guidance. | | `consolidate` | Promote thresholds and run automatic chain detection. | | `session_summary` | End-of-session digest with recent observations and top suggestions. | | `detect_chains` | Discover sequential patterns from confidence-log timestamps. | | `effectiveness` | Measure which suggestions were reinforced by later observations. | | `export_platform` | Export rules for Claude, Cursor, Windsurf, Codex, or CLAUDE.md. | | `gc` | Decay stale patterns, find duplicates, clean orphan aliases, rebuild FTS. | ## MCP Client Setup Claude Code project-level `.mcp.json`: ```json { "mcpServers": { "instinct": { "command": "instinct", "args": ["serve"] } } } ``` Codex CLI: ```toml [mcp_servers.instinct] command = "instinct" args = ["serve"] ``` Cursor / Windsurf / HTTP clients: ```json { "mcpServers": { "instinct": { "command": "instinct", "args": ["serve", "--transport", "sse"] } } } ``` Server options: ```bash instinct serve # stdio, default instinct serve --transport sse # SSE instinct serve --transport streamable-http # streamable HTTP instinct serve --port 3777 ``` ## How It Compares instinct is one of several memory layers for AI agents. The categories overlap, but each project optimises for something different. This table is a head-to-head feature matrix; raw adoption metrics, source URLs, and methodology live in [`docs/comparison-benchmarks.md`](docs/comparison-benchmarks.md). | Project | Primary surface | Storage | Protocol | Confidence tiers / auto-promote | Cross-project promotion | Export targets | Setup friction | |---|---|---|---|---|---|---|---| | **`instinct`** | Coding-agent behavioural patterns (seq / pref / fix / combo) | Local SQLite WAL | MCP-native + CLI | Yes -- `raw` -> `mature` -> `rule` -> `universal` | Yes (universal tier) | Claude, Cursor, Windsurf, Codex, CLAUDE.md, Agent Skills | `pip install instinct-mcp` (1 line) | | [Mem0](https://github.com/mem0ai/mem0) | General LLM memory (chat history, episodic facts) | Pluggable vector backend (Qdrant, pgvector, Chroma, ...) | Python / TS SDK + REST | No tier model; importance scoring | Via `user_id` / `agent_id` namespacing | SDK consumption (no flat-file export) | SDK + backend choice | | [Letta](https://github.com/letta-ai/letta) (formerly MemGPT) | Stateful agent runtime with built-in memory | Postgres / SQLite via runtime | Letta SDK + REST + MCP | Managed by agent (memory blocks) | Agent-level isolation | N/A (runtime, not exporter) | Server / Docker, framework-level | | [LangMem](https://github.com/langchain-ai/langmem) | Memory utilities for LangChain / LangGraph | `BaseStore` (pluggable) | LangChain SDK only | User-managed | Namespace-based | N/A (library) | `pip install langmem` + LangChain stack | | [claude-mem](https://github.com/thedotmack/claude-mem) | Session capture + AI-compressed context re-injection | Local context files | Claude Code hooks + multi-tool | No tier model; full-session capture | Per-project session files | Context files for Claude / Codex / Copilot / Gemini / OpenCode | `npm` install + hook wiring | | [Engram](https://github.com/Gentleman-Programming/engram) | Persistent memory for coding agents (generic) | Local SQLite + FTS5 | MCP + HTTP + CLI + TUI | No (raw storage) | Per-project DB | Generic memory store | Single Go binary | | [ByteRover CLI](https://github.com/campfirein/byterover-cli) (formerly Cipher) | Portable memory layer for autonomous coding agents | Local + cloud hybrid | MCP + CLI (`brv`) | Not advertised | Yes | Multi-agent compatible | `brv` CLI install | | [Pieces](https://pieces.app/) | Developer snippets and workflow artefacts | Local Pieces OS + optional cloud | Proprietary SDK + IDE extensions | ML-tagged (not user-visible tier model) | Yes | IDE-native panels | Desktop app + IDE plugin | | `CLAUDE.md` / `.cursorrules` | Hand-written rule files | Flat text in repo | Loaded by the agent | Manual (you decide what's a rule) | Manual (you copy the file) | Itself a target format | Edit a file | **When to reach for instinct:** your agent makes the same correction or follows the same workflow more than 3 times and you don't want to keep retyping. instinct records once, promotes after repetition, and surfaces the pattern back automatically through MCP. **Where instinct loses today (honest delta):** - **Adoption / maturity.** instinct is new (April 2026, 2 GitHub stars at time of writing). Mem0, Letta, and claude-mem each have 5-6 figures of stars and years of iteration. If you need a battle-tested project with a large community, instinct is not it yet. - **Chat-history recall.** Mem0 stores episodic conversational facts and recalls them by query. instinct does not store conversation turns; it stores repeated behavioural patterns. - **Full agent runtime.** Letta gives you the whole agent loop (planner, memory, tools, state). instinct is a memory-only sidecar; you still bring your own agent. - **LangChain-native integration.** LangMem ships first-class `BaseStore` adapters and reducers for LangGraph. instinct is framework-agnostic via MCP, which costs you some LangChain-specific ergonomics. - **Session capture and replay.** claude-mem snapshots and compresses entire Claude Code sessions for later context injection. instinct stores only the patterns the agent (or you) chose to `observe`. - **Snippets and artefacts.** Pieces stores code snippets, screenshots, and links. instinct stores patterns, not artefacts. If any of those is your primary need, reach for the project that owns it. Reach for instinct when you want a small, local, MCP-native pattern store that promotes repeated behaviours into exportable rules. ## Storage and Runtime - Package: [`instinct-mcp`](https://pypi.org/project/instinct-mcp/) - Python: `>=3.11` - Runtime dependency: `mcp>=1.0.0` - Database: SQLite WAL at `~/.instinct/instinct.db` - Config: optional `~/.instinct/config.toml` - Current release in this repo: `1.4.4` ## CLI Reference ```bash instinct observe <pattern> # record/reinforce instinct suggest # mature suggestions instinct list # browse all patterns instinct history <pattern> # confidence timeline instinct effectiveness # suggestion confirmation rates instinct export-platform codex # export for an agent/editor instinct gc # decay + dedup + cleanup instinct doctor # DB health checks ``` All core commands support `--json` where structured output is useful. ## Recent Releases - `1.4.4`: repository transferred to `WRG-11` org + URL/metadata refresh (no behavioural changes). - `1.4.0`: auto-chain detection and effectiveness scoring. - `1.3.0`: platform export, MCP prompts, and `gc`. - `1.2.0`: auto-promote on observe, confidence history, universal rules, CLAUDE.md import. - `1.1.0`: Agent Skill export, CLAUDE.md injection, near-duplicate detection. See [CHANGELOG.md](CHANGELOG.md). ## Repository Health - CI matrix: Python 3.11-3.14 on Ubuntu and Windows. - CodeQL security scanning on push and pull request. - Dependabot tracks GitHub Actions and pip updates weekly. - Published on [PyPI](https://pypi.org/project/instinct-mcp/), [MCP Registry](https://registry.modelcontextprotocol.io), and [Glama](https://glama.ai/mcp/servers/WRG-11/instinct). ## License [MIT](LICENSE)