instinct-mcp 1.4.1

Self-learning memory for AI coding agents — pattern detection, confidence scoring, auto-promotion via MCP

instinct

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.

pip install instinct-mcp

Used in the wild: 1,400+ monthly downloads on PyPI as of 2026-04-25.

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

instinct observe "seq:lint->fix->lint"
instinct observe "pref:commits=conventional" --cat preference
instinct observe "fix:utf8-encoding-windows" --cat fix_pattern
instinct observe "combo:pytest+coverage" --cat combo

Pattern prefixes are conventional, not magic: seq:, pref:, fix:, and combo: keep the store searchable and easier to export.

Tool Surface

Full MCP surface is larger than this table. A complete reference belongs in docs/TOOLS.md (TODO).

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

CLAUDE.md is good for hand-written rules. instinct is for patterns that should earn their way into rules through repetition.

Surface	Best fit	Different because
instinct	Coding-agent pattern memory	Local SQLite, confidence tiers, decay, cross-project promotion, MCP-native — works with any MCP-compatible agent.
Mem0	General LLM memory layer	Broader memory product (chat history, episodic facts); instinct is narrower and coding-agent focused on behavioral patterns.
Letta (formerly MemGPT)	Stateful agent runtime	Full agent framework with memory built-in; instinct is a memory-only sidecar you bolt onto your existing agent.
LangMem	Memory for LangChain	Tied to LangChain ecosystem; instinct is framework-agnostic via MCP.
claude-mem	Claude-specific memory experiments	instinct exposes MCP tools plus CLI exports across Claude, Cursor, Windsurf, Goose, and Codex.
Pieces	Developer snippets and workflow context	instinct stores repeated behavioral patterns; Pieces stores artifacts (snippets, links, screenshots).
CLAUDE.md / .cursorrules	Hand-written rule files	Flat text, manual maintenance. instinct can export to these formats once a pattern matures.

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 it back automatically.

When to reach for the others: chat-history recall (Mem0), full agent runtime with built-in memory (Letta), LangChain integration (LangMem), or static hand-curated rules (CLAUDE.md / .cursorrules).

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

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