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
• Features
• Install
• Getting Started in 60s
• MCP Tools
• MCP Prompts
• 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

Features

• Auto-promote — patterns automatically promoted through maturity levels (raw → mature → rule → universal) based on confidence thresholds
• Auto-chain detection — automatically discovers sequential patterns (seq:A->B) from observation timestamps, no manual sequence definition needed (v1.4.0)
• Effectiveness scoring — tracks whether suggested patterns get confirmed by subsequent observations, calculates confirmation rates (v1.4.0)
• Confidence history — full timeline of how each pattern's confidence evolved over time
• Cross-project learning — rules observed in 2+ projects auto-promote to universal level
• Multi-platform export — export rules to CLAUDE.md, .cursorrules, .windsurfrules, or Codex format
• Agent Skill export — export rules as SKILL.md compatible with agentskills.io
• CLAUDE.md injection — idempotent inject/import rules to/from CLAUDE.md files
• Near-duplicate detection — find similar patterns and merge them via aliases
• Pattern aliasing — redirect observations from variant spellings to canonical patterns
• Full-text search — FTS5-powered search across patterns, metadata, and explanations
• Garbage collection — decay stale patterns, merge duplicates, clean orphans, rebuild indexes
• Backup & restore — SQLite-level backup and restore with health checks

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.

Other MCP Clients

.mcp.json (Claude Code project-level):

{
  "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"]
    }
  }
}

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

MCP Tools

MCP Prompts

CLI Reference

# Core
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 + detect chains
instinct stats                   # Summary statistics
instinct delete <pattern>        # Remove a pattern

# Analysis
instinct trending                # Fastest-growing patterns
instinct history <pattern>       # Confidence history over time
instinct effectiveness           # Suggestion confirmation rates
instinct detect-chains           # Auto-detect sequential chains

# Export
instinct export-rules            # Export rules as JSON
instinct export-claude-md        # Export rules as CLAUDE.md markdown
instinct export-skill            # Export rules as Agent Skill (SKILL.md)
instinct export-platform <fmt>   # Export for cursor/windsurf/codex
instinct export-all              # Export all instincts as JSON

# Import & Sync
instinct inject <path>           # Inject rules into CLAUDE.md (idempotent)
instinct import-claude-md <path> # Import patterns from CLAUDE.md
instinct import <file.json>      # Bulk import from JSON

# Maintenance
instinct gc                      # Garbage collection (decay + dedup + cleanup)
instinct decay                   # Reduce stale patterns
instinct dedup                   # Find/merge near-duplicate patterns
instinct alias <pat> <target>    # Create a pattern alias
instinct aliases                 # List all aliases

# Infrastructure
instinct serve                   # Start MCP server
instinct fingerprint             # Print project fingerprint for cwd
instinct backup                  # Create database backup
instinct restore <file>          # Restore from backup
instinct doctor                  # Run health checks

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)
  --explain "why this matters"

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 + detect chains
store.decay(days_inactive=90)                     # fade stale patterns

# Auto-chain detection
chains = store.detect_chains(window_minutes=5, min_occurrences=3)

# Effectiveness scoring
eff = store.effectiveness(days=30)

# 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
• Universal rules — patterns reaching rule level in 2+ projects auto-promote to universal, suggested across all projects

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

Storage

• Database: SQLite (WAL mode) at ~/.instinct/instinct.db
• Dependencies: Only mcp>=1.0.0
• Python: >= 3.11
• Config: Optional ~/.instinct/config.toml for threshold overrides

How It Compares

Repository Health

• CI matrix: Python 3.11–3.14 on Ubuntu + Windows
• CodeQL security scanning on push and pull request
• Dependabot tracks weekly updates (GitHub Actions + pip)
• Published on PyPI, MCP Registry, and Glama

License

MIT