Which integrations are available for this server?

Integrates with GitHub Actions for CI/CD workflows and Dependabot for dependency updates, with repository health monitoring and protected branch management. Provides CI/CD workflow integration with automated testing and security scanning through GitHub Actions workflows. Supports export and import of patterns to/from Markdown files (CLAUDE.md, SKILL.md) for agent instruction formatting. Supports pattern detection for pytest testing workflows, including test sequences and combination patterns with coverage tools. Provides Python-specific pattern learning and memory capabilities for AI coding agents working with Python projects and tools. Uses SQLite for pattern storage with full-text search capabilities, backup/restore functionality, and database health management. Supports TOML configuration format for MCP server setup with certain AI agent clients like Codex CLI.

instinct by yakuphanycl

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.

How It Works

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

Observe — record patterns as your agent works (tool sequences, preferences, recurring fixes)
Track — each re-observation increments confidence
Promote — confidence >= 5 becomes mature (suggested), >= 10 becomes rule (auto-applied)
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

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

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

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

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
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

License

MIT

instinct

Table of Contents