Instinct

instinct

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

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

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.

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.

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