brain-mcp

A local, private, free AI "second brain". Point it at any folder of Markdown notes (built for Obsidian vaults, works on any Markdown folder) and it becomes a searchable knowledge base for any MCP-compatible AI client — Claude Code, Claude Desktop, Cursor, etc. Hybrid search (semantic + keyword), incremental self-healing indexing, read/write tools. No API keys. No cloud. Nothing leaves your machine.

Quick start

1. Clone this repo.
2. Open the folder in Claude Code.
3. Say "set up the brain" (or run /setup-brain).

That's it. The agent reads SETUP.md and does everything: installs deps, ensures Ollama, auto-detects your Obsidian vault, registers the MCP server user-scoped, indexes, and verifies.

Manual install (fallback)

python -m venv .venv
# Windows:  .venv\Scripts\python -m pip install -r requirements.txt
# macOS/Linux:  .venv/bin/pip install -r requirements.txt

# Install Ollama from https://ollama.com, then:
ollama pull nomic-embed-text

python brain_cli.py setup

How it works

Markdown notes folder (the "vault")
   │
   ├─ chunk_file()   ── split by H1/H2 headings. Frontmatter + heading prefixed
   │                     onto every chunk so each is self-contextual.
   │                     CHUNK_CHARS=1600, OVERLAP_CHARS=200. sha256 per chunk.
   ├─ ollama_embed() ── batches of 32 → nomic-embed-text vectors
   ├─ Chroma (cosine HNSW) ← embeddings + {path, heading}
   └─ SQLite: chunks + chunks_fts (FTS5 porter unicode61), trigger-synced

semantic_search (Chroma) and keyword_search (FTS5) are merged with Reciprocal Rank Fusion (k=60). hybrid_search is the primary tool. Indexing is incremental (per-chunk sha256), self-healing (startup mtime scan, background reindex on writes, orphan cleanup), and concurrency-safe.

MCP tools

Tool	Purpose
hybrid_search_tool(query, top_k=5)	Primary — RRF-merged semantic + keyword search
semantic_search_tool(query, top_k=5)	Vector similarity only
keyword_search_tool(query, top_k=10)	FTS5 keyword only
read_note_tool(path)	Read a note's full content
list_recent_tool(days=7)	Recently modified notes
append_to_note_tool(path, content)	Append to an existing note
create_note_tool(path, content)	Create a new note
save_conversation_tool(title, gist)	Save a conversation to 06 Conversations/
ingest_file_tool(source)	Ingest a URL / PDF / document as a reference note
reindex_tool(path=None)	Reindex one file or the whole vault

Where data lives

The brain's own storage is decoupled from your notes. Index, database, config, and logs live in ~/.brain/ (override with the BRAIN_HOME env var) — never inside your notes folder.

Point at a different vault:

brain config --vault /path/to/notes      # persisted to ~/.brain/config.json
# or, ephemeral:
BRAIN_VAULT=/path/to/notes brain index

Vault resolution order: BRAIN_VAULT env → ~/.brain/config.json → Obsidian auto-detect → error.

Use it with other AI tools

setup registers the brain for Claude, then offers to also register it for Codex, Gemini CLI, Cursor, and Windsurf. Do it any time:

brain mcp                                  # interactive picker
brain mcp --client codex --client cursor   # non-interactive

It merges into each tool's MCP config without disturbing your other servers.

Performance

The embedding model is kept resident (keep_alive=-1 on every call and OLLAMA_KEEP_ALIVE=-1 persisted + passed to the MCP server). Without this, Ollama unloads the model after ~4 min idle and the next tool call stalls 10–30s on a cold reload. brain setup configures this automatically. Warm embedding latency is ~38ms vs ~2.2s cold. (size_vram=0 in ollama ps is a known reporting bug — judge by latency, not that field.)

Privacy

Everything runs locally. Embeddings are computed by Ollama on your machine. Chroma and SQLite are local files. No API keys, no telemetry, no cloud fallback. Nothing leaves your computer.

License

MIT — see LICENSE.