Metadata-Version: 2.4
Name: instinct-mcp
Version: 0.1.0
Summary: Self-learning memory for AI coding agents — pattern detection, confidence scoring, auto-promotion via MCP
License: MIT
Project-URL: Homepage, https://github.com/rg-WinstonRedGuard/instinct
Project-URL: Issues, https://github.com/rg-WinstonRedGuard/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

# instinct

Self-learning memory for AI coding agents.

instinct observes patterns from your AI agent sessions, tracks confidence over time, and auto-promotes recurring patterns into actionable suggestions. Works with any MCP-compatible agent (Claude Code, Cursor, Goose, Codex, etc.).

## How It Works

```
observe  ->  track  ->  promote  ->  suggest
```

1. **Observe** patterns during agent sessions (tool sequences, user preferences, recurring fixes)
2. **Track** confidence — each re-observation increments the counter
3. **Promote** automatically: confidence >= 5 becomes `mature`, >= 10 becomes `rule`
4. **Suggest** mature patterns to guide agent behavior without explicit instruction

## Install

```bash
pip install instinct-mcp
```

## Quick Start

### As MCP Server (recommended)

Add to your `.mcp.json` or Claude Code config:

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

Your AI agent now has access to these tools:

| Tool | Description |
|------|-------------|
| `observe` | Record a pattern (auto-increments on repeat) |
| `suggest` | Get mature patterns as guidance |
| `list_instincts` | Browse all patterns with filters |
| `consolidate` | Auto-promote by confidence threshold |
| `stats` | Summary statistics |
| `search_instincts` | Search by keyword |
| `export_rules` | Export rule-level patterns |

### As CLI

```bash
# Record patterns
instinct observe "seq:lint->fix->lint"
instinct observe "pref:style=black" --cat preference
instinct observe "fix:missing-import" --cat fix_pattern

# Check what's learned
instinct list
instinct suggest
instinct stats

# Lifecycle
instinct consolidate    # auto-promote
instinct decay          # reduce stale patterns
instinct export-rules   # get rule-level JSON
```

### As Python Library

```python
from instinct.store import InstinctStore

store = InstinctStore()

store.observe("seq:test->fix->test", source="claude-code")
store.observe("seq:test->fix->test")  # confidence = 2

suggestions = store.suggest()
stats = store.stats()
rules = store.export_rules()
```

## Pattern Naming Convention

| Prefix | Meaning | Example |
|--------|---------|---------|
| `seq:` | Tool/action sequence | `seq:lint->fix->lint` |
| `pref:` | User preference | `pref:style=black` |
| `fix:` | Recurring fix pattern | `fix:missing-import` |
| `combo:` | Things used together | `combo:pytest+coverage` |

## Maturity Levels

| Level | Confidence | Meaning |
|-------|-----------|---------|
| `raw` | < 5 | Observed but not actionable |
| `mature` | >= 5 | Ready to suggest |
| `rule` | >= 10 | Strong enough to auto-apply |

## Cross-Project Learning

instinct tracks a project fingerprint (hash of working directory). Patterns can be:
- **Project-specific** — only suggested in the same project
- **Global** — observed across projects, suggested everywhere

## Storage

SQLite database at `~/.instinct/instinct.db`. Zero external dependencies beyond MCP SDK.

## License

MIT
