instinct-mcp 1.0.0

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

instinct

Self-learning memory for AI coding agents

---

Your AI agent makes the same mistakes twice. It forgets your preferences between sessions. It doesn't learn from repetition.

instinct fixes this. It observes patterns from your agent sessions, tracks confidence over time, and auto-promotes recurring patterns into suggestions your agent follows — without you repeating yourself.

Works with any MCP-compatible agent: Claude Code, Cursor, Windsurf, Goose, Codex, and others.

Table of Contents

• How It Works
• Install
• Getting Started in 60s
• Quick Start
• CLI Reference
• Python Library
• Cross-Project Learning
• Storage
• How It Compares
• License

How It Works

         observe           track            promote           suggest
        ┌───────┐       ┌───────┐        ┌───────┐        ┌───────┐
  You   │Record │  +1   │ Count │  >=5   │Mature │  >=10  │ Rule  │
  work  │pattern├──────>│ hits  ├───────>│suggest├───────>│ auto- │
        └───────┘       └───────┘        └───────┘        │ apply │
                                                          └───────┘

1. Observe — record patterns as your agent works (tool sequences, preferences, recurring fixes)
2. Track — each re-observation increments confidence
3. Promote — confidence >= 5 becomes mature (suggested), >= 10 becomes rule (auto-applied)
4. Suggest — mature patterns guide agent behavior without explicit instruction

Install

pip install instinct-mcp

Getting Started in 60s

1. If you have not installed yet, run pip install instinct-mcp.

2. Add instinct to your MCP client config:

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

3. Record one pattern and request suggestions:

instinct observe "seq:test->fix->test"
instinct suggest

If suggest returns an empty list, keep observing recurring patterns. Suggestions appear once confidence reaches mature level.

Quick Verification

instinct observe "seq:test->fix->test"
instinct suggest

Repository Health

• CI and CodeQL run on push and pull request
• Dependabot tracks weekly updates (GitHub Actions + pip)
• Protected default branch (master) requires review and resolved conversations

Quick Start

1. Add to your agent

Claude Code — add to .mcp.json in your project root:

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

Codex CLI — add to ~/.codex/config.toml:

[mcp_servers.instinct]
command = "instinct"
args = ["serve"]

Cursor / Windsurf — add to your MCP configuration:

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

That's it. Your agent now has access to 8 tools:

Tool	What it does
observe	Record a pattern (auto-increments confidence on repeat)
suggest	Get mature patterns to guide current behavior
list_instincts	Browse all observed patterns with filters
get_instinct	Look up a specific pattern
consolidate	Promote patterns that crossed confidence thresholds
search_instincts	Full-text search across patterns and metadata
stats	Summary statistics of the instinct store
export_rules	Export rule-level patterns as structured data

2. Watch it learn

As you work, your agent starts noticing patterns:

Session 1:  observe("seq:test->fix->test")          → confidence 1 (raw)
Session 3:  observe("seq:test->fix->test")          → confidence 3 (raw)
Session 5:  observe("seq:test->fix->test")          → confidence 5 (mature ✓)
            suggest() → "When tests fail, apply fix and re-run tests"

After enough repetitions, instinct starts suggesting the pattern back — your agent adapts to how you work.

What Patterns Look Like

# Tool sequences your agent repeats
instinct observe "seq:lint->fix->lint"
instinct observe "seq:build->test->deploy"

# Your preferences it should remember
instinct observe "pref:style=black" --cat preference
instinct observe "pref:commits=conventional" --cat preference

# Fixes it keeps rediscovering
instinct observe "fix:missing-import" --cat fix_pattern
instinct observe "fix:utf8-encoding-windows" --cat fix_pattern

# Tools that work better together
instinct observe "combo:pytest+coverage" --cat combo

Naming Convention

Prefix	Use for	Example
seq:	Action sequences	seq:lint->fix->lint
pref:	User preferences	pref:style=black
fix:	Recurring fixes	fix:missing-import
combo:	Tool combinations	combo:pytest+coverage

Maturity Levels

Level	Confidence	Behavior
raw	< 5	Observed, stored, not yet actionable
mature	>= 5	Returned by suggest() — agent uses as guidance
rule	>= 10	Exported by export_rules() — strong enough to auto-apply

CLI Reference

instinct observe <pattern>       # Record/reinforce a pattern
instinct get <pattern>           # Look up a specific pattern
instinct list                    # List all instincts
instinct suggest                 # Get mature suggestions
instinct consolidate             # Auto-promote by confidence
instinct decay                   # Reduce stale patterns (default: 90 days inactive)
instinct stats                   # Summary statistics
instinct export-rules            # Export rules as JSON
instinct delete <pattern>        # Remove a pattern
instinct fingerprint             # Print project fingerprint for cwd
instinct serve                   # Start MCP server

All commands support --json for structured output.

Observe Options

instinct observe "seq:a->b" \
  --cat sequence              # Category: sequence|preference|fix_pattern|combo
  --source claude-code        # Which agent/tool recorded this
  --project auto              # Project fingerprint (auto-detected from cwd)

Server Options

instinct serve                              # stdio (default, for Claude Code)
instinct serve --transport sse              # SSE for remote/HTTP clients
instinct serve --transport streamable-http  # Streamable HTTP
instinct serve --port 3777                  # Custom port (default: 3777)

Python Library

from instinct.store import InstinctStore

store = InstinctStore()  # uses ~/.instinct/instinct.db

# Record patterns
store.observe("seq:test->fix->test", source="my-tool")
store.observe("seq:test->fix->test")  # confidence = 2

# Query
suggestions = store.suggest()                     # mature+ patterns
results     = store.search("test")                # full-text search
rules       = store.export_rules()                # rule-level only

# Lifecycle
store.consolidate()                               # promote by threshold
store.decay(days_inactive=90)                     # fade stale patterns

# Stats
print(store.stats())
# {'total': 42, 'raw': 30, 'mature': 10, 'rules': 2, 'avg_confidence': 4.2, ...}

Custom Database Path

store = InstinctStore(db_path="/path/to/custom.db")

Cross-Project Learning

instinct hashes your working directory into a project fingerprint. This means:

• Project-specific patterns are only suggested when you're in that project
• Global patterns (empty project field) are suggested everywhere

# See your current project's fingerprint
instinct fingerprint
# → a1b2c3d4e5f6

Storage

• Database: SQLite at ~/.instinct/instinct.db
• Dependencies: Only mcp>=1.0.0
• Size: ~650 lines of Python, zero bloat

How It Compares

	instinct	Manual CLAUDE.md	.cursorrules
Learns automatically	Yes	No	No
Cross-session memory	Yes	Yes	Yes
Confidence scoring	Yes	No	No
Decay of stale patterns	Yes	No	No
Works across agents	Yes (MCP)	Claude only	Cursor only
Requires manual editing	No	Yes	Yes

License

MIT