Metadata-Version: 2.4
Name: instinct-mcp
Version: 0.1.5
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: Issues, https://github.com/yakuphanycl/instinct/issues
Keywords: mcp,ai-agent,memory,instinct,claude-code,cursor,goose
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Libraries
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 -->
<p align="center">
  <h1 align="center">instinct</h1>
  <p align="center">
    <strong>Self-learning memory for AI coding agents</strong>
  </p>
  <p align="center">
    <a href="https://pypi.org/project/instinct-mcp/"><img alt="PyPI" src="https://img.shields.io/pypi/v/instinct-mcp?color=%2334D058&label=pypi"></a>
    <a href="https://pypi.org/project/instinct-mcp/"><img alt="Python" src="https://img.shields.io/pypi/pyversions/instinct-mcp"></a>
    <a href="https://github.com/yakuphanycl/instinct/blob/master/LICENSE"><img alt="License" src="https://img.shields.io/github/license/yakuphanycl/instinct"></a>
    <a href="https://github.com/yakuphanycl/instinct/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/yakuphanycl/instinct/actions/workflows/ci.yml/badge.svg?branch=master"></a>
    <a href="https://github.com/yakuphanycl/instinct/actions/workflows/codeql.yml"><img alt="CodeQL" src="https://github.com/yakuphanycl/instinct/actions/workflows/codeql.yml/badge.svg?branch=master"></a>
    <a href="https://modelcontextprotocol.io"><img alt="MCP" src="https://img.shields.io/badge/MCP-compatible-blue"></a>
  </p>
</p>

---

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](#how-it-works)
- [Install](#install)
- [Getting Started in 60s](#getting-started-in-60s)
- [Quick Start](#quick-start)
- [CLI Reference](#cli-reference)
- [Python Library](#python-library)
- [Cross-Project Learning](#cross-project-learning)
- [Storage](#storage)
- [How It Compares](#how-it-compares)
- [License](#license)

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

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

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

### Quick Verification

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

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

That's it. Your agent now has access to 8 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 |
| `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 |

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

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

## CLI Reference

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

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

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

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

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

| | instinct | Manual CLAUDE.md | .cursorrules |
|---|---|---|---|
| Learns automatically | Yes | No | No |
| Cross-session memory | Yes | Yes | Yes |
| Confidence scoring | Yes | No | No |
| Decay of stale patterns | Yes | No | No |
| Works across agents | Yes (MCP) | Claude only | Cursor only |
| Requires manual editing | No | Yes | Yes |

## License

[MIT](LICENSE)
