Metadata-Version: 2.4
Name: instinct-mcp
Version: 1.4.1
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

[![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)

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.

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

Used in the wild: **1,400+ monthly downloads on PyPI as of 2026-04-25**.

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

```bash
instinct observe "seq:lint->fix->lint"
instinct observe "pref:commits=conventional" --cat preference
instinct observe "fix:utf8-encoding-windows" --cat fix_pattern
instinct observe "combo:pytest+coverage" --cat combo
```

Pattern prefixes are conventional, not magic: `seq:`, `pref:`, `fix:`, and
`combo:` keep the store searchable and easier to export.

## Tool Surface

Full MCP surface is larger than this table. A complete reference belongs in
[`docs/TOOLS.md`](docs/TOOLS.md) (TODO).

| 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

CLAUDE.md is good for hand-written rules. instinct is for patterns that should
earn their way into rules through repetition.

| Surface | Best fit | Different because |
|---|---|---|
| `instinct` | Coding-agent pattern memory | Local SQLite, confidence tiers, decay, cross-project promotion, MCP-native — works with any MCP-compatible agent. |
| [Mem0](https://github.com/mem0ai/mem0) | General LLM memory layer | Broader memory product (chat history, episodic facts); instinct is narrower and coding-agent focused on behavioral patterns. |
| [Letta](https://github.com/letta-ai/letta) (formerly MemGPT) | Stateful agent runtime | Full agent framework with memory built-in; instinct is a memory-only sidecar you bolt onto your existing agent. |
| [LangMem](https://github.com/langchain-ai/langmem) | Memory for LangChain | Tied to LangChain ecosystem; instinct is framework-agnostic via MCP. |
| [claude-mem](https://github.com/search?q=claude-mem&type=repositories) | Claude-specific memory experiments | instinct exposes MCP tools plus CLI exports across Claude, Cursor, Windsurf, Goose, and Codex. |
| [Pieces](https://pieces.app/) | Developer snippets and workflow context | instinct stores repeated behavioral patterns; Pieces stores artifacts (snippets, links, screenshots). |
| `CLAUDE.md` / `.cursorrules` | Hand-written rule files | Flat text, manual maintenance. instinct can export to these formats once a pattern matures. |

**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 it back automatically.

**When to reach for the others:** chat-history recall (Mem0), full agent runtime with built-in memory (Letta), LangChain integration (LangMem), or static hand-curated rules (CLAUDE.md / .cursorrules).

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

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