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

Grace Period (7 days): No decay. Fresh memories stay at full strength.
Active Decay: Score decreases based on importance weight and time since last access.
Access Resets Clock: Every time a memory is recalled or found in search, its decay resets.
Critical = Permanent: Set importance to critical and the memory never decays.
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.

---

<p align="center"> <b>Built with ❤️ to give AI agents the memory they deserve.</b> </p>

mcp-ai-brain