brain-mcp-server

# Brain MCP Server Personal Knowledge Brain for developers. A local-first MCP server that gives AI assistants persistent, typed memory with hybrid search. **The only MCP knowledge server with typed neurons, hybrid 3-way search, and compact mode.** ## Why Brain MCP? AI assistants forget everything between sessions. Brain MCP fixes that: - **Typed neurons** — Not generic "memories". Decisions, lessons, concepts, entities, sources, handoffs, questions. Each type carries meaning. - **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. - **Compact mode** — Saves ~85% tokens in search results. Your AI uses less context = cheaper and faster. - **Knowledge graph** — Bidirectional links between neurons. "This decision supports that concept." - **Multi-session** — Claims, locks, signals for coordinating multiple AI sessions. ## Quick Start ```bash # Register in your Claude config (~/.claude.json or claude_desktop_config.json) { "mcpServers": { "brain": { "command": "npx", "args": ["brain-mcp-server"] } } } ``` The database is created automatically at `~/.claude/brain-mcp/brain.db`. ## Tools ### Core (always available) | Tool | Description | |------|-------------| | `brain_search` | Search by text, vector, or hybrid. Compact mode available. | | `brain_get` | Get a neuron by ID with all its links. | | `brain_list` | List recent neurons. Filter by type, project. | | `brain_add` | Create a neuron with type, tags, and links. | ### Sync | Tool | Description | |------|-------------| | `brain_sync_candidates` | List neurons tagged for sync to external targets. | | `brain_mark_synced` | Mark a neuron as synced. | | `brain_export` | Export neurons in portable format. | ### Coordination | Tool | Description | |------|-------------| | `brain_status` | Show active claims, locks, and pending signals. | | `brain_claim` | Claim a scope (project, module) for exclusive work. | | `brain_release` | Release an active claim or lock. | | `brain_signal` | Send async message to another session. | | `brain_signals_pending` | Read pending signals. | ## Neuron Types | Type | Use for | |------|---------| | `decision` | Architectural choices, trade-offs, "we chose X because Y" | | `concept` | Ideas, patterns, mental models worth remembering | | `entity` | People, projects, tools, products | | `source` | Articles, docs, research findings with citations | | `lesson` | What worked, what didn't, post-mortems | | `handoff` | Context pass between sessions or teammates | | `question` | Open questions, backlog ideas, things to explore | ## Search Modes ``` # Full-text search (fast, exact word matching) brain_search({ query: "JWT authentication", mode: "fts" }) # Vector search (semantic, finds related concepts) brain_search({ query: "how do we verify users", mode: "vector" }) # Hybrid search (best of both — default) brain_search({ query: "auth strategy", mode: "hybrid" }) # Compact mode (saves ~85% tokens) brain_search({ query: "auth", compact: true }) # Returns: "decision|Auth with JWT|We chose JWT because..." ``` ## 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](https://ollama.ai): ```bash # Install Ollama, then pull the embedding model ollama pull nomic-embed-text # Brain MCP auto-detects Ollama and enables vector search ``` If Ollama is not available, Brain MCP gracefully falls back to FTS5-only search. ## Schema Brain MCP uses SQLite with 14 tables: - `brain_neurons` — The neurons (typed, tagged, versioned) - `brain_links` — Bidirectional knowledge graph - `brain_fts` — FTS5 full-text search index - `brain_embeddings` — Vector embeddings - `brain_embeddings_queue` — Async embedding processing - `brain_neurons_history` — Version history - `brain_activity_log` — Audit trail - `brain_sync_map` — External sync tracking - `brain_sync_conflicts` — Conflict resolution - `brain_handoffs` — Session/teammate handoffs - `brain_claims` — Scope coordination - `brain_locks` — Path locking - `brain_signals` — Async messaging - `brain_meta` — System metadata ## Comparison | Feature | Brain MCP | Mem0 | mcp-knowledge-graph | MemPalace | |---------|-----------|------|---------------------|-----------| | Typed neurons | 7 types | Generic facts | Entities only | Rooms/Halls | | Local-first | SQLite | Needs OpenAI key | JSON files | ChromaDB | | FTS search | FTS5 | BM25 | Keyword only | No | | Vector search | Ollama (optional) | OpenAI (required) | No | ChromaDB | | Knowledge graph | Bidirectional links | No | Yes | No | | Compact mode | 85% token savings | No | No | No | | Multi-session | Claims/Locks/Signals | No | No | No | | Setup | 0 config | API keys needed | 0 config | Python + ChromaDB | | Price | Free (MIT) | $0-249/mo | Free | Free | ## License MIT