instinct-mcp 0.1.0

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

instinct

Self-learning memory for AI coding agents.

instinct observes patterns from your AI agent sessions, tracks confidence over time, and auto-promotes recurring patterns into actionable suggestions. Works with any MCP-compatible agent (Claude Code, Cursor, Goose, Codex, etc.).

How It Works

observe  ->  track  ->  promote  ->  suggest

1. Observe patterns during agent sessions (tool sequences, user preferences, recurring fixes)
2. Track confidence — each re-observation increments the counter
3. Promote automatically: confidence >= 5 becomes mature, >= 10 becomes rule
4. Suggest mature patterns to guide agent behavior without explicit instruction

Install

pip install instinct-mcp

Quick Start

As MCP Server (recommended)

Add to your .mcp.json or Claude Code config:

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

Your AI agent now has access to these tools:

Tool	Description
observe	Record a pattern (auto-increments on repeat)
suggest	Get mature patterns as guidance
list_instincts	Browse all patterns with filters
consolidate	Auto-promote by confidence threshold
stats	Summary statistics
search_instincts	Search by keyword
export_rules	Export rule-level patterns

As CLI

# Record patterns
instinct observe "seq:lint->fix->lint"
instinct observe "pref:style=black" --cat preference
instinct observe "fix:missing-import" --cat fix_pattern

# Check what's learned
instinct list
instinct suggest
instinct stats

# Lifecycle
instinct consolidate    # auto-promote
instinct decay          # reduce stale patterns
instinct export-rules   # get rule-level JSON

As Python Library

from instinct.store import InstinctStore

store = InstinctStore()

store.observe("seq:test->fix->test", source="claude-code")
store.observe("seq:test->fix->test")  # confidence = 2

suggestions = store.suggest()
stats = store.stats()
rules = store.export_rules()

Pattern Naming Convention

Prefix	Meaning	Example
seq:	Tool/action sequence	seq:lint->fix->lint
pref:	User preference	pref:style=black
fix:	Recurring fix pattern	fix:missing-import
combo:	Things used together	combo:pytest+coverage

Maturity Levels

Level	Confidence	Meaning
raw	< 5	Observed but not actionable
mature	>= 5	Ready to suggest
rule	>= 10	Strong enough to auto-apply

Cross-Project Learning

instinct tracks a project fingerprint (hash of working directory). Patterns can be:

• Project-specific — only suggested in the same project
• Global — observed across projects, suggested everywhere

Storage

SQLite database at ~/.instinct/instinct.db. Zero external dependencies beyond MCP SDK.

License

MIT