Metadata-Version: 2.4
Name: instinct-mcp
Version: 1.4.4
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/WRG-11/instinct
Project-URL: Repository, https://github.com/WRG-11/instinct
Project-URL: Issues, https://github.com/WRG-11/instinct/issues
Project-URL: Changelog, https://github.com/WRG-11/instinct/blob/main/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.WRG-11/instinct -->
# instinct

> 💡 **Found this useful?** ⭐ Star the repo (helps others find it) and subscribe to weekly detection-engineering writeups at [Detection Frontier](https://detection-frontier.kit.com/subscribe).

[![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/)
[![CI](https://github.com/WRG-11/instinct/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/WRG-11/instinct/actions/workflows/ci.yml)
[![CodeQL](https://github.com/WRG-11/instinct/actions/workflows/codeql.yml/badge.svg?branch=main)](https://github.com/WRG-11/instinct/actions/workflows/codeql.yml)
[![License](https://img.shields.io/github/license/WRG-11/instinct)](https://github.com/WRG-11/instinct/blob/main/LICENSE)
[![MCP](https://img.shields.io/badge/MCP-compatible-blue)](https://modelcontextprotocol.io)
[![Coverage](https://img.shields.io/badge/coverage-84%25-brightgreen)](#)

> **Self-learning memory for AI coding agents: record repeated patterns, score them by confidence, and surface mature guidance back through MCP.**

- Records tool sequences, user preferences, recurring fixes, and useful tool combinations.
- Promotes repeated observations from `raw` to `mature`, `rule`, and cross-project `universal`.
- Exports learned rules for Claude, Cursor, Windsurf, Codex, CLAUDE.md, and Agent Skills.

**Current release**: `1.4.1` (April 2026; transferred to WRG-11 org). Python `>=3.11`. SQLite WAL storage at `~/.instinct/instinct.db`. Single runtime dep (`mcp>=1.0.0`).

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

Live install stats: [pypistats.org/packages/instinct-mcp](https://pypistats.org/packages/instinct-mcp).

## Quick Start

For Claude Code:

```bash
pip install instinct-mcp
claude mcp add instinct -- instinct serve
instinct observe "seq:test->fix->test"
```

Then ask your agent for suggestions, or run:

```bash
instinct suggest
```

Suggestions appear once a pattern reaches `mature` confidence. By default,
`mature` starts at confidence 5 and `rule` starts at confidence 10.

## What It Learns

You feed instinct one `observe` call per recurring behaviour you want it to remember.
Each call increments confidence on the matching pattern; once confidence reaches the
`mature` threshold (default: 5), the pattern shows up in `suggest` and can be exported
back into your agent's rule files. Four prefix conventions help organise + search the
store:

```bash
instinct observe "seq:lint->fix->lint"               # tool-sequence patterns
instinct observe "pref:commits=conventional"         # user preferences
instinct observe "fix:utf8-encoding-windows"         # recurring fixes
instinct observe "combo:pytest+coverage"             # tool combinations
```

Pattern prefixes are conventional, not magic: `seq:`, `pref:`, `fix:`, and
`combo:` keep the store searchable and easier to export. Add `--cat <category>`
to override the auto-inferred category if needed.

## Tool Surface

A representative slice of the MCP tool surface; see the
[CLI Reference section](#cli-reference) below for the complete command list.

| Tool / command | Use it for |
|---|---|
| `observe` | Record or reinforce one pattern; repeats increment confidence. |
| `suggest` | Return mature patterns for current agent guidance. |
| `consolidate` | Promote thresholds and run automatic chain detection. |
| `session_summary` | End-of-session digest with recent observations and top suggestions. |
| `detect_chains` | Discover sequential patterns from confidence-log timestamps. |
| `effectiveness` | Measure which suggestions were reinforced by later observations. |
| `export_platform` | Export rules for Claude, Cursor, Windsurf, Codex, or CLAUDE.md. |
| `gc` | Decay stale patterns, find duplicates, clean orphan aliases, rebuild FTS. |

## MCP Client Setup

Claude Code project-level `.mcp.json`:

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

Codex CLI:

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

Cursor / Windsurf / HTTP clients:

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

Server options:

```bash
instinct serve                              # stdio, default
instinct serve --transport sse              # SSE
instinct serve --transport streamable-http  # streamable HTTP
instinct serve --port 3777
```

## How It Compares

instinct is one of several memory layers for AI agents. The categories overlap, but
each project optimises for something different. This table is a head-to-head feature
matrix; raw adoption metrics, source URLs, and methodology live in
[`docs/comparison-benchmarks.md`](docs/comparison-benchmarks.md).

| Project | Primary surface | Storage | Protocol | Confidence tiers / auto-promote | Cross-project promotion | Export targets | Setup friction |
|---|---|---|---|---|---|---|---|
| **`instinct`** | Coding-agent behavioural patterns (seq / pref / fix / combo) | Local SQLite WAL | MCP-native + CLI | Yes -- `raw` -> `mature` -> `rule` -> `universal` | Yes (universal tier) | Claude, Cursor, Windsurf, Codex, CLAUDE.md, Agent Skills | `pip install instinct-mcp` (1 line) |
| [Mem0](https://github.com/mem0ai/mem0) | General LLM memory (chat history, episodic facts) | Pluggable vector backend (Qdrant, pgvector, Chroma, ...) | Python / TS SDK + REST | No tier model; importance scoring | Via `user_id` / `agent_id` namespacing | SDK consumption (no flat-file export) | SDK + backend choice |
| [Letta](https://github.com/letta-ai/letta) (formerly MemGPT) | Stateful agent runtime with built-in memory | Postgres / SQLite via runtime | Letta SDK + REST + MCP | Managed by agent (memory blocks) | Agent-level isolation | N/A (runtime, not exporter) | Server / Docker, framework-level |
| [LangMem](https://github.com/langchain-ai/langmem) | Memory utilities for LangChain / LangGraph | `BaseStore` (pluggable) | LangChain SDK only | User-managed | Namespace-based | N/A (library) | `pip install langmem` + LangChain stack |
| [claude-mem](https://github.com/thedotmack/claude-mem) | Session capture + AI-compressed context re-injection | Local context files | Claude Code hooks + multi-tool | No tier model; full-session capture | Per-project session files | Context files for Claude / Codex / Copilot / Gemini / OpenCode | `npm` install + hook wiring |
| [Engram](https://github.com/Gentleman-Programming/engram) | Persistent memory for coding agents (generic) | Local SQLite + FTS5 | MCP + HTTP + CLI + TUI | No (raw storage) | Per-project DB | Generic memory store | Single Go binary |
| [ByteRover CLI](https://github.com/campfirein/byterover-cli) (formerly Cipher) | Portable memory layer for autonomous coding agents | Local + cloud hybrid | MCP + CLI (`brv`) | Not advertised | Yes | Multi-agent compatible | `brv` CLI install |
| [Pieces](https://pieces.app/) | Developer snippets and workflow artefacts | Local Pieces OS + optional cloud | Proprietary SDK + IDE extensions | ML-tagged (not user-visible tier model) | Yes | IDE-native panels | Desktop app + IDE plugin |
| `CLAUDE.md` / `.cursorrules` | Hand-written rule files | Flat text in repo | Loaded by the agent | Manual (you decide what's a rule) | Manual (you copy the file) | Itself a target format | Edit a file |

**When to reach for instinct:** your agent makes the same correction or follows the
same workflow more than 3 times and you don't want to keep retyping. instinct records
once, promotes after repetition, and surfaces the pattern back automatically through
MCP.

**Where instinct loses today (honest delta):**

- **Adoption / maturity.** instinct is new (April 2026, 2 GitHub stars at time of
  writing). Mem0, Letta, and claude-mem each have 5-6 figures of stars and years of
  iteration. If you need a battle-tested project with a large community, instinct is
  not it yet.
- **Chat-history recall.** Mem0 stores episodic conversational facts and recalls them
  by query. instinct does not store conversation turns; it stores repeated
  behavioural patterns.
- **Full agent runtime.** Letta gives you the whole agent loop (planner, memory,
  tools, state). instinct is a memory-only sidecar; you still bring your own agent.
- **LangChain-native integration.** LangMem ships first-class `BaseStore` adapters
  and reducers for LangGraph. instinct is framework-agnostic via MCP, which costs you
  some LangChain-specific ergonomics.
- **Session capture and replay.** claude-mem snapshots and compresses entire Claude
  Code sessions for later context injection. instinct stores only the patterns the
  agent (or you) chose to `observe`.
- **Snippets and artefacts.** Pieces stores code snippets, screenshots, and links.
  instinct stores patterns, not artefacts.

If any of those is your primary need, reach for the project that owns it. Reach for
instinct when you want a small, local, MCP-native pattern store that promotes
repeated behaviours into exportable rules.

## Storage and Runtime

- Package: [`instinct-mcp`](https://pypi.org/project/instinct-mcp/)
- Python: `>=3.11`
- Runtime dependency: `mcp>=1.0.0`
- Database: SQLite WAL at `~/.instinct/instinct.db`
- Config: optional `~/.instinct/config.toml`
- Current release in this repo: `1.4.1`

## CLI Reference

```bash
instinct observe <pattern>          # record/reinforce
instinct suggest                    # mature suggestions
instinct list                       # browse all patterns
instinct history <pattern>          # confidence timeline
instinct effectiveness              # suggestion confirmation rates
instinct export-platform codex      # export for an agent/editor
instinct gc                         # decay + dedup + cleanup
instinct doctor                     # DB health checks
```

All core commands support `--json` where structured output is useful.

## Recent Releases

- `1.4.1`: repository transferred to `WRG-11` org + URL/metadata refresh (no behavioural changes).
- `1.4.0`: auto-chain detection and effectiveness scoring.
- `1.3.0`: platform export, MCP prompts, and `gc`.
- `1.2.0`: auto-promote on observe, confidence history, universal rules, CLAUDE.md import.
- `1.1.0`: Agent Skill export, CLAUDE.md injection, near-duplicate detection.

See [CHANGELOG.md](CHANGELOG.md).

## Repository Health

- CI matrix: Python 3.11-3.14 on Ubuntu and Windows.
- CodeQL security scanning on push and pull request.
- Dependabot tracks GitHub Actions and pip updates weekly.
- Published on [PyPI](https://pypi.org/project/instinct-mcp/), [MCP Registry](https://registry.modelcontextprotocol.io), and [Glama](https://glama.ai/mcp/servers/WRG-11/instinct).

## License

[MIT](LICENSE)
