🧠 mcp-ai-brain

Persistent memory for AI coding agents. Local-first. Zero API costs. Works everywhere.

AI agents forget everything between sessions. mcp-ai-brain fixes that.

A Model Context Protocol (MCP) server that gives your AI agent a persistent, searchable, privacy-first memory — powered by SQLite, FTS5, and biological-inspired decay.

✨ Features

| Feature | Description | |---------|-------------| | 🔍 Hybrid Search | Keyword (FTS5) + local vector embeddings via all-MiniLM-L6-v2, fused with RRF | | 🧬 Memory Decay | Ebbinghaus-inspired forgetting curve — unused memories lose relevance, critical ones never fade | | 📂 Project Scoping | Memories are scoped to projects — your web app context stays separate from your CLI tool context | | 🔒 Privacy-First | Everything stays on your machine. No cloud. No API calls. Your brain.db never leaves ~/.mcp-ai-brain/ | | ⚡ Zero Cost | No embeddings API needed. Runs all-MiniLM-L6-v2 locally via @xenova/transformers (~25MB, downloads once) | | 🤖 Auto-Learning | brain_session_end extracts facts automatically from your session summary. No manual remember calls needed | | 🎯 Proactive Context | brain_session_start_smart detects your workspace and loads the right memories automatically | | 🌐 Dashboard | Built-in web dashboard at localhost:3333 — view, search, edit memories in real-time | | 🔌 Universal | Works with Claude Desktop, Cursor, Windsurf, Cline, Antigravity, and any MCP-compatible tool |

🚀 Quick Start

Install

npm install -g mcp-ai-brain

Configure your AI tool

Add to your MCP config (e.g., claude_desktop_config.json, .cursor/mcp.json):

{
  "mcpServers": {
    "brain": {
      "command": "mcp-ai-brain"
    }
  }
}

That's it. Your AI now has a brain. 🧠

🛠️ Tools

brain_remember

Store a memory. Supports categorization, tagging, importance levels, and project scoping.

Categories: fact | decision | preference | architecture | bug | config | pattern | incident | workflow
Importance: critical (never decays) | high | normal | low

brain_recall

Retrieve memories by project, category, or importance — without needing a search query.

brain_search

Hybrid search using keyword matching (FTS5) + local vector embeddings (all-MiniLM-L6-v2). Results fused with Reciprocal Rank Fusion — semantic similarity works out of the box once the model downloads (~25MB, one-time).

brain_forget

Soft-delete a memory. It's excluded from search but can be restored.

brain_session_start

Start a session — loads top memories for your project, runs decay maintenance, and returns context.

brain_session_end

End a session — records what happened and for how long.

brain_projects_*

Manage the project registry (list, upsert, get, delete).

brain_stats

Brain diagnostics — memory counts, category breakdown, database path, vector status.

🧬 How Decay Works

Memories follow a biological forgetting curve:

1. Grace Period (7 days): No decay. Fresh memories stay at full strength.
2. Active Decay: Score decreases based on importance weight and time since last access.
3. Access Resets Clock: Every time a memory is recalled or found in search, its decay resets.
4. Critical = Permanent: Set importance to critical and the memory never decays.
5. Decayed ≠ Deleted: Decayed memories can be restored with brain_restore.

⚙️ Configuration

| Environment Variable | Default | Description | |---|---|---| | BRAIN_DB_PATH | ~/.mcp-ai-brain/brain.db | Custom database file location |

🏗️ Architecture

┌─────────────────────────────────┐
│        AI Agent (Claude, etc.)  │
│          via MCP Protocol       │
└────────────┬────────────────────┘
             │ stdio
┌────────────▼────────────────────┐
│       mcp-ai-brain server       │
│  ┌──────────┐  ┌─────────────┐  │
│  │ FTS5     │  │ MiniLM-L6v2 │  │
│  │ (keyword)│  │ (local vec) │  │
│  └────┬─────┘  └──────┬──────┘  │
│       │    RRF Fusion  │        │
│       └───────┬────────┘        │
│         ┌─────▼──────┐          │
│         │  SQLite DB  │          │
│         │  brain.db   │          │
│         └────────────┘          │
│  ┌──────────────────────────┐   │
│  │  Decay Engine            │   │
│  │  (Ebbinghaus curve)      │   │
│  └──────────────────────────┘   │
│  ┌──────────────────────────┐   │
│  │  Auto-Learning (v1.1)    │   │
│  │  Session summary → facts │   │
│  └──────────────────────────┘   │
└─────────────────────────────────┘

📊 What Your AI Agent Should Remember

| Category | Example | |----------|---------| | decision | "We chose NextJS over Remix because of Vercel deployment simplicity" | | architecture | "Auth flow: Firebase Auth → Custom Claims → Middleware guard" | | config | "Cron schedule: */10 * * * * (every 10 min, Vercel 300s timeout)" | | bug | "Safari iOS AudioContext requires user gesture — fixed with click handler" | | pattern | "All Firestore writes use transactions for multi-tenant isolation" | | preference | "User prefers dark mode UI with Inter font family" | | incident | "2024-01-15: Stripe webhook double-firing caused duplicate charges" |

🗺️ Roadmap

• [x] v1.0 — Core memory + keyword search (FTS5) + Ebbinghaus decay engine
• [x] v1.1 — Local embeddings (all-MiniLM-L6-v2 via @xenova/transformers) + Auto-Learning + Proactive Context + Web Dashboard
• [ ] v1.2 — Multi-agent support + relationship graph between memories
• [ ] v2.0 — Proactive suggestions + memory consolidation + export/import

🤝 Contributing

PRs welcome! See CONTRIBUTING.md for guidelines.

📄 License

MIT — see LICENSE.

🌍 Built With This

Real-world projects powered by mcp-ai-brain — demonstrating persistent AI memory in production:

| Project | What It Does | |---------|-------------| | 🎤 Ace Your Interviews | AI-powered real-time voice mock interviews — the only tool that simulates a real phone screen | | 📍 GeoQuote.ai | Instant contractor quoting platform — real-time pricing intelligence for homeowners | | 🎄 The Funny Christmas Shop | Hilarious holiday t-shirts with AI-generated designs, updated daily | | 📝 ChairFull.org | Office chair reviews and buying guides — AI-researched, human-curated | | 💰 VaultNest.org | Personal finance guides — savings, investing, and financial independence | | 🚛 FleetShield.org | Commercial trucking insurance guides for fleet owners | | ✈️ DutyPilot.org | Import duty and customs tariff guides for international shoppers | | 📖 ManualJPro.org | Product manual library — user guides and instruction manuals | | 🛒 Should I Buy It | AI buying-intent analysis — know before you spend |

Want your project listed here? Open a PR and add it to this table.

👤 About the Author

Built and maintained by Pravin Nawkar — a developer building AI-powered SaaS tools and content platforms.