# 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)

```bash
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:

```bash
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:

```bash
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`.