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.

   Claude Code (one-liner):

   claude mcp add instinct -- instinct serve
   

   Cursor / Windsurf / Goose / other MCP clients — add to your client's MCP 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:

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

Maturity Levels

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

License

MIT