instinct

💡 Found this useful? ⭐ Star the repo (helps others find it) and subscribe to weekly detection-engineering writeups at Detection Frontier.

PyPI Python CI CodeQL License MCP Coverage

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.

Status

Experimental — research sidecar. instinct is maintained as an agent-memory research layer alongside WRG-11's security work and is strategically deprioritized as a standalone product; it is not positioned as a head-to-head competitor to Mem0 or Letta (see How It Compares and Known limitations).

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).

pip install instinct-mcp

Live install stats: pypistats.org/packages/instinct-mcp.

Quick Start

For Claude Code:

pip install instinct-mcp
claude mcp add instinct -- instinct serve
instinct observe "seq:test->fix->test"

Then ask your agent for suggestions, or run:

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:

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 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:

{
  "mcpServers": {
    "instinct": {
      "command": "instinct",
      "args": ["serve"]
    }
  }
}

Codex CLI:

[mcp_servers.instinct]
command = "instinct"
args = ["serve"]

Cursor / Windsurf / HTTP clients:

{
  "mcpServers": {
    "instinct": {
      "command": "instinct",
      "args": ["serve", "--transport", "sse"]
    }
  }
}

Server options:

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.

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	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 (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	Memory utilities for LangChain / LangGraph	BaseStore (pluggable)	LangChain SDK only	User-managed	Namespace-based	N/A (library)	pip install langmem + LangChain stack
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	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 (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	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.

Known limitations

What instinct deliberately does not do (expanded in the honest-delta list above):

• No chat-history / episodic recall — it stores repeated behavioural patterns, not conversation turns (Mem0's territory).
• Not an agent runtime — memory-only sidecar; you bring your own agent loop (Letta's territory).
• No LangChain-native adapters — framework-agnostic via MCP only.
• No full-session capture/replay — only patterns explicitly passed to observe (claude-mem's territory).
• No snippet/artefact storage — patterns, not artefacts (Pieces' territory).
• Young project, minimal adoption — April 2026, single-digit GitHub stars at time of writing.

Recording and surfacing a pattern is two commands (see Quick Start and the CLI Reference):

instinct observe "seq:test->fix->test"
instinct suggest

Storage and Runtime

• Package: 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

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.

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, MCP Registry, and Glama.

License

MIT

---

Part of the WRG-11 ecosystem

• wrg-mcp-server — WRG tools as an MCP server
• wrg-skills — Claude Code skills, incl. instinct mirror

Full index → github.com/WRG-11