Brain MCP Server

Personal Knowledge Brain for developers. A local-first MCP server that gives AI assistants persistent, typed memory — with hybrid search, time-travel history, spaced repetition, and a secrets vault.

v0.3.0 — 37 tools · 4 vaults · 8 neuron types · 100% local SQLite

Why Brain MCP?

AI assistants forget everything between sessions. Brain MCP fixes that:

• Typed neurons — Not generic "memories". Decisions, lessons, concepts, entities, research, handoffs, sources, questions. Each type carries meaning and schema.
• Hybrid search — Full-text (FTS5) + semantic (vector embeddings) + graph traversal. Find things by words OR meaning OR relationships.
• 100% local — SQLite-based. No cloud, no API keys, no data leaving your machine.
• Time-travel — Full version history with diffs. See how any neuron evolved over time.
• Spaced repetition — Lessons auto-enroll in a SM-2 review schedule. /briefing shows what's due today.
• Anti-forgetting — Scans session transcripts for unrecorded decisions and lessons before closing.
• Secrets vault — Encrypted vault for sensitive neurons (tokens, passwords, private notes). MCP returns [PROTECTED] — only you can read them via CLI.
• Multi-session coordination — Claims, locks, signals for running multiple AI sessions without conflicts.
• Compact mode — Saves ~85% tokens in search results.

Quick Start

# 1. Register in your Claude config (~/.claude.json)
{
  "mcpServers": {
    "brain-local": {
      "command": "npx",
      "args": ["brain-mcp-server"]
    }
  }
}

# 2. Init the database
npx brain-mcp-server --init

# 3. Restart Claude Code — brain tools are now available

Databases are created at ~/.claude/brain-local/ (4 split files, see Architecture).

Tools — 37 total

Core CRUD

| Tool | Description | |------|-------------| | brain_search | Hybrid FTS5 + vector + graph search. Supports compact mode, date filters. | | brain_get | Get a neuron by ID with all its links and history. Air-gap neurons return [PROTECTED]. | | brain_list | List neurons. Filter by type, project, vault, author, date range, tags. | | brain_add | Create a neuron. Auto-detects secrets and routes to encrypted vault. | | brain_update | Update a neuron. Writes a versioned history entry. | | brain_archive | Soft-delete (reversible): status → archived. | | brain_restore | Restore an archived neuron back to active. | | brain_delete | Hard delete (permanent — use archive if unsure). |

Time-Travel

| Tool | Description | |------|-------------| | brain_timetravel | Full version history with diffs. Hash-chain verified. | | brain_history | List recent changes across all neurons. |

Anti-Forgetting

| Tool | Description | |------|-------------| | brain_propose_from_transcript | Scan a session transcript for unrecorded decisions and lessons. | | brain_create_summary | Save a compact session checkpoint before context compaction. |

Spaced Repetition (SM-2)

| Tool | Description | |------|-------------| | brain_spaced_review | Get neurons due for review today (learning + decision types). | | brain_spaced_update | Mark reviewed with confidence 0–100. SM-2 schedules next interval. |

Knowledge Graph

| Tool | Description | |------|-------------| | brain_link | Create a directed link between two neurons (supports, contradicts, related, derives_from, supersedes). | | brain_unlink | Remove one or all links between a neuron pair. | | brain_neighbors | BFS graph traversal — get all linked neurons up to N levels deep (max 4). | | brain_syntheses | List synthesis nodes (summaries of related neuron clusters). | | brain_synthesize | Generate a synthesis from a group of related neurons (requires Anthropic API key). |

Analytics & Maintenance

| Tool | Description | |------|-------------| | brain_stats | Global counts by type and vault, embedding coverage, most-linked neurons. | | brain_audit | Activity log: all create/update/archive/delete/review actions, filterable. | | brain_dbcheck | PRAGMA INTEGRITY_CHECK on all 4 databases. | | brain_vacuum | PRAGMA VACUUM on all 4 databases (reclaim disk space). | | brain_category_add | Create a category with vault_hint and llm_exposure policy. |

Import / Export

| Tool | Description | |------|-------------| | brain_export | Export neurons as JSON or Markdown with YAML frontmatter. | | brain_import | Import neurons from Markdown files (compatible with basic-memory format). |

Sync

| Tool | Description | |------|-------------| | brain_sync_candidates | List neurons tagged sync-candidate pending external sync. | | brain_mark_synced | Mark a neuron as synced to an external target. | | brain_sync_status | Show sync state: synced count, conflicts, last run. | | brain_sync_full | Run a full bidirectional sync. | | brain_sync_pull | Pull remote changes. | | brain_sync_push | Push local changes. |

Multi-session Coordination

| Tool | Description | |------|-------------| | brain_status | Show active claims, locks, pending signals, and neuron counts per vault. | | brain_claim | Claim a scope (project, module) for exclusive work. | | brain_release | Release an active claim or lock. | | brain_signal | Send an async message to another session. | | brain_signals_pending | Read pending signals for this session (auto-marks as read). |

Neuron Types

| Type | Use for | Auto-enrolled in spaced review | |------|---------|-------------------------------| | decision | Architectural choices, trade-offs, "we chose X because Y" | ✅ 7-day initial interval | | learning | What worked, what didn't, post-mortems, lessons | ✅ 1-day initial interval | | research | Investigations, comparisons, findings with sources | — | | pattern | Code patterns, best practices, reusable solutions | — | | idea | Proposals, hypotheses, things to explore | — | | project | Project context, status, goals, blockers | — | | security | Security observations, threat models, credentials routing | — | | contact | People, teams, relationships, communication notes | — |

Architecture — 4 Vaults

Brain MCP splits storage into 4 SQLite files for separation of concerns:

~/.claude/brain-local/
├── public.db   — Neurons visible in search (concepts, decisions, lessons…)
├── work.db     — Work/private neurons (project-specific, less public)
├── vault.db    — Encrypted secrets (tokens, passwords, private notes)
└── meta.db     — Coordination: claims, locks, signals, context summaries, sync state

Why split? Each vault can be backed up, shared, or encrypted independently. vault.db contains AES-256-GCM encrypted neurons — the MCP server returns [PROTECTED] for vault neurons; only the vault CLI can decrypt them using a master key stored in macOS Keychain.

# Read vault neurons (human CLI only, never exposed via MCP)
node vault-list.mjs

Knowledge Graph

Neurons can be linked to each other. Links are directional and typed:

// Link at creation time
brain_add({
  type: "decision",
  title: "Use SQLite over DuckDB",
  content: "...",
  links: [{ id: "n_abc", kind: "related" }, { id: "n_def", kind: "supersedes" }]
})

// Add a link after creation
brain_link({ from_id: "n_abc", to_id: "n_def", kind: "supports" })

// Remove a specific link
brain_unlink({ from_id: "n_abc", to_id: "n_def", kind: "supports" })

// Remove all links between a pair
brain_unlink({ from_id: "n_abc", to_id: "n_def" })

// Traverse the graph
brain_neighbors({ id: "n_abc", depth: 2 })
// depth 1–4, default 2. Returns all linked neurons with all edges.

Link kinds: supports · contradicts · related · derives_from · supersedes

Search Modes

// Full-text search (fast, exact word matching with stemming)
brain_search({ query: "JWT authentication", mode: "fts" })

// Vector search (semantic — finds related concepts even without exact words)
// Requires Ollama running locally with nomic-embed-text pulled
brain_search({ query: "how do we verify users", mode: "vector" })

// Hybrid search (FTS5 + vector combined with RRF ranking — default)
brain_search({ query: "auth strategy", mode: "hybrid" })

// Compact mode — ~85% fewer tokens, ideal for quick lookups
brain_search({ query: "auth", compact: true })
// Returns pipe-delimited: "decision|Auth with JWT|We chose JWT because..."

// Filter by type, vault, or date range
brain_search({ query: "performance", type: "learning" })
brain_search({ query: "deploy", vault: "work", created_after: "2025-01-01" })
brain_search({ query: "database", type: "decision", created_before: "2025-06-01", limit: 10 })

Parameters:

| Parameter | Type | Default | Description | |-----------|------|---------|-------------| | query | string | required | Search query | | mode | string | hybrid | fts · vector · hybrid | | type | string | — | Filter by neuron type | | vault | string | — | Filter by vault: public · work · vault | | limit | number | 10 | Max results | | compact | boolean | false | Return pipe-delimited summary (85% token savings) | | created_after | string | — | ISO date filter (inclusive) | | created_before | string | — | ISO date filter (inclusive) |

Time-Travel

Every brain_update call writes a history entry with content hash. You can inspect the full evolution of any neuron:

brain_timetravel({ id: "n_1234567890_abc123" })
// Returns: list of versions with diffs, timestamps, hash chain

Spaced Repetition

When you add a learning (1-day initial interval) or decision (7-day initial interval) neuron, it auto-enrolls in SM-2 review. Check what's due and mark reviews:

// Get what's due for review today
brain_spaced_review()
// Returns: neurons due today, sorted by urgency

// Mark reviewed with a confidence score (0–100)
brain_spaced_update({ neuron_id: "n_...", confidence: 80, notes: "still solid" })
// confidence 0–59  → resets to 1-day interval (needs more repetition)
// confidence 60–100 → SM-2 progressive schedule (intervals grow over time)

Secrets Vault

# Initialize vault (one-time setup)
node setup-vault.mjs

# Add a vault neuron via MCP
brain_add({ type: "security", title: "API Key", content: "sk-...", vault: "vault" })
# → stored encrypted with AES-256-GCM, master key in Keychain

# MCP returns [PROTECTED] — the key never travels over MCP
brain_get({ id: "n_vault_..." })
# → { title: "API Key", content: "[PROTECTED]", vault: "vault" }

# Read vault neurons directly
node vault-list.mjs

Secret Detection

Brain MCP scans content before saving and blocks accidental secret storage:

brain_add({ content: "token: ghp_abc123..." })
// → Error: SECRET_DETECTED. Use vault=vault to store secrets safely.

Patterns detected: OpenAI/Anthropic keys (sk-*), GitHub tokens (ghp_*, ghs_*), AWS keys (AKIA*), Bearer tokens, UUIDs combined with keywords.

Anti-Forgetting

Before closing a session, scan the conversation for unrecorded decisions and lessons:

brain_propose_from_transcript({
  messages: [
    { role: "user", content: "We decided to use SQLite over Postgres because..." },
    { role: "assistant", content: "..." },
    { role: "user", content: "We learned that the FTS5 tokenizer needs..." }
  ],
  limit: 10
})
// Returns: proposed neurons {type, title, content, reason, confidence}
// Each proposal is a decision or lesson detected — none are saved until you call brain_add

Save a compact checkpoint before context gets compacted:

brain_create_summary({
  summary: "Implemented JWT refresh flow. Pending: add rate limiting. Next: write integration tests.",
  session_id: "session-2025-07-01"
})

Import / Export

// Export to JSON (portable)
brain_export({ vault: "work", format: "json" })

// Export to Markdown with YAML frontmatter
brain_export({ type: "decision", format: "markdown", project: "my-project" })

// Import from Markdown files
brain_import({
  files: [
    {
      filename: "auth-decision.md",
      content: "---\ntype: decision\ntitle: Use JWT\ntags: [auth, security]\n---\n\nWe chose JWT because..."
    }
  ],
  project: "my-project"
})
// Supported frontmatter fields: type, title, tags, vault, sensitivity, project

Backup

# Backup all 4 vaults (vault.db copied encrypted — key NOT included)
node backup-brain.mjs

# Rotates: keeps 7 days of backups automatically
# Output: ~/.claude/brain-local/backups/YYYY-MM-DD_HH-MM/

Optional: Semantic Search with Ollama

By default, Brain MCP uses FTS5 (full-text search) which works great without any setup.

For semantic search (find by meaning, not just words), install Ollama:

ollama pull nomic-embed-text
# Brain MCP auto-detects Ollama and enables vector search
# Ollama is started on-demand and stopped after 60s idle — no CPU waste

If Ollama is not running, Brain MCP falls back to FTS5-only search.

Comparison

| Feature | Brain MCP | Mem0 | mcp-knowledge-graph | mnemon-mcp | Obsidian MCP | |---------|-----------|------|---------------------|------------|--------------| | Typed neurons | 8 types | Generic | Entities only | No | Markdown notes | | Local-first | ✅ SQLite | ❌ Cloud | ✅ JSON | ✅ SQLite | ✅ Vault | | FTS search | ✅ FTS5 | BM25 | Keyword | ✅ FTS5 | ✅ | | Vector search | ✅ Ollama (opt) | ✅ OpenAI (req) | ❌ | ❌ | ❌ | | Knowledge graph | ✅ Bidirectional | ❌ | ✅ | ❌ | ❌ | | Time-travel | ✅ Hash-chain | ❌ | ❌ | ✅ | ❌ | | Spaced repetition | ✅ SM-2 | ❌ | ❌ | ❌ | Plugins only | | Secrets vault | ✅ AES-256-GCM | ❌ | ❌ | ❌ | ❌ | | Multi-session coord | ✅ Claims/Locks | ❌ | ❌ | ❌ | ❌ | | Secret detection | ✅ Pre-write | ❌ | ❌ | ❌ | ❌ | | Compact mode | ✅ 85% savings | ❌ | ❌ | ❌ | ❌ | | Setup | 0 config | API keys | 0 config | 0 config | Obsidian + plugin | | Price | Free (MIT) | $0–249/mo | Free | Free | Free |

Roadmap

• [ ] P2P sync (device-to-device without cloud hub)
• [ ] Brain Studio — visual 3D dashboard for exploring your neurons
• [ ] WebXR mode for Brain Studio

License

MIT — 0001-YIDev