<!-- mcp-name: io.github.yakuphanycl/instinct --> <div align="center">

instinct

Self-learning memory for AI coding agents

</div>

---

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.

<p align="center"> <img src="demo/demo.svg" alt="instinct demo — observe, track, suggest" width="700"> </p>

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

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
universal	rule + 2 projects	Cross-project rule, suggested everywhere

MCP 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 + detect chains
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
alias_pattern	Create an alias to merge duplicate patterns
import_patterns	Bulk import patterns from a list of dicts
session_summary	End-of-session snapshot with auto-consolidation
trending	Show fastest-growing patterns in recent period
export_claude_md	Export rules formatted for CLAUDE.md
export_skill	Export rules as Agent Skill (SKILL.md / agentskills.io)
inject_claude_md	Inject rules into a CLAUDE.md file (idempotent)
find_duplicates	Find near-duplicate patterns for merging
import_claude_md	Import patterns from a CLAUDE.md file
history	Confidence history for a pattern over time
export_platform	Export rules for Cursor, Windsurf, Codex, etc.
gc	Garbage collection: decay + dedup + orphan cleanup + FTS rebuild
detect_chains	Auto-detect sequential pattern chains from timestamps
effectiveness	Show suggestion effectiveness scores (confirmation rates)

MCP Prompts

Prompt	What it does
instinct_rules	Get all instinct rules as agent instructions
instinct_suggestions	Get mature pattern suggestions for the current project

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

	instinct	Manual CLAUDE.md	.cursorrules
Learns automatically	Yes	No	No
Cross-session memory	Yes	Yes	Yes
Confidence scoring	Yes	No	No
Auto-chain detection	Yes	No	No
Effectiveness tracking	Yes	No	No
Decay of stale patterns	Yes	No	No
Cross-project learning	Yes	No	No
Works across agents	Yes (MCP)	Claude only	Cursor only
Multi-platform export	Yes	N/A	N/A
Requires manual editing	No	Yes	Yes

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