Metadata-Version: 2.4
Name: instinct-mcp
Version: 1.4.0
Summary: Self-learning memory for AI coding agents — pattern detection, confidence scoring, auto-promotion via MCP
License-Expression: MIT
Project-URL: Homepage, https://github.com/yakuphanycl/instinct
Project-URL: Repository, https://github.com/yakuphanycl/instinct
Project-URL: Issues, https://github.com/yakuphanycl/instinct/issues
Project-URL: Changelog, https://github.com/yakuphanycl/instinct/blob/master/CHANGELOG.md
Keywords: mcp,ai-agent,memory,instinct,claude-code,cursor,goose,codex
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Typing :: Typed
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mcp>=1.0.0
Dynamic: license-file

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

# instinct

**Self-learning memory for AI coding agents**

[![PyPI](https://img.shields.io/pypi/v/instinct-mcp?color=%2334D058&label=pypi)](https://pypi.org/project/instinct-mcp/)
[![Python](https://img.shields.io/pypi/pyversions/instinct-mcp)](https://pypi.org/project/instinct-mcp/)
[![License](https://img.shields.io/github/license/yakuphanycl/instinct)](https://github.com/yakuphanycl/instinct/blob/master/LICENSE)
[![CI](https://github.com/yakuphanycl/instinct/actions/workflows/ci.yml/badge.svg?branch=master)](https://github.com/yakuphanycl/instinct/actions/workflows/ci.yml)
[![CodeQL](https://github.com/yakuphanycl/instinct/actions/workflows/codeql.yml/badge.svg?branch=master)](https://github.com/yakuphanycl/instinct/actions/workflows/codeql.yml)
[![MCP](https://img.shields.io/badge/MCP-compatible-blue)](https://modelcontextprotocol.io)
[![Glama](https://glama.ai/mcp/servers/yakuphanycl/instinct/badges/score.svg)](https://glama.ai/mcp/servers/yakuphanycl/instinct)

</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](#how-it-works)
- [Features](#features)
- [Install](#install)
- [Getting Started in 60s](#getting-started-in-60s)
- [MCP Tools](#mcp-tools)
- [MCP Prompts](#mcp-prompts)
- [CLI Reference](#cli-reference)
- [Python Library](#python-library)
- [Cross-Project Learning](#cross-project-learning)
- [Storage](#storage)
- [How It Compares](#how-it-compares)
- [License](#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

```bash
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):

   ```bash
   claude mcp add instinct -- instinct serve
   ```

   **Cursor / Windsurf / Goose / other MCP clients** — add to your client's MCP config:

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

3. Record one pattern and request suggestions:

```bash
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):

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

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

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

**Cursor / Windsurf** — add to your MCP configuration:

```json
{
  "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

```bash
# 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

```bash
# 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

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

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

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

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

```bash
# 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](https://pypi.org/project/instinct-mcp/), [MCP Registry](https://registry.modelcontextprotocol.io), and [Glama](https://glama.ai/mcp/servers/yakuphanycl/instinct)

## License

[MIT](LICENSE)
