instinct

PyPI Python CI CodeQL License MCP

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

Why Not Just CLAUDE.md?

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 tools.
Mem0	General AI memory layer	Broader memory product; instinct is narrower and coding-agent focused.
claude-mem	Claude-specific memory experiments	instinct exposes MCP tools plus CLI exports across multiple agents.
Pieces	Developer snippets and workflow context	instinct stores repeated behavioral patterns rather than a general knowledge library.

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