🧠 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

Related MCP server: LumenCore

🚀 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

🏗️ 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

🗺️ Roadmap

• v1.0 — Core memory + keyword search (FTS5) + Ebbinghaus decay engine

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

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.