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

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.

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