instinct

Self-learning memory for AI coding agents

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
• Install
• Getting Started in 60s
• Quick Start
• CLI Reference
• Python Library
• Cross-Project Learning
• Storage
• How It Compares
• 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

Install

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

   claude mcp add instinct -- instinct serve
   

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

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

3. Record one pattern and request suggestions:

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

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 ag

... View full README on GitHub