ai-brain-mcp

An MCP server that exposes a markdown knowledge vault (Obsidian-style) as agent-readable memory: search, read, graph, guarded capture. One stdio server, every Claude surface.

It deliberately has no embeddings and no vector database. See Why no RAG.

What it gives an agent

Tool	Purpose
brain_map	Boot context: the root routing docs, every note with size and tags, and the tag index. One call, ~1.2k tokens for a 350 KB vault.
brain_search	Lexical search across title, tags, headings and body. Ranked, with line-numbered snippets. Filter by tag or folder.
brain_read	Read a note by wikilink name or path. section pulls one heading. Oversize notes return an annotated outline instead of their body.
brain_graph	Outgoing wikilinks (resolved, broken, ambiguous), backlinks, and notes sharing the same tags.
brain_capture	The only write path. Appends to the capture queue. Canonical notes are unreachable.

The intended loop is brain_map once per session, then brain_search to locate and brain_read to pull. The agent reasons about what it needs instead of receiving whatever a similarity score returned.

The read budget

The pathological case in a personal vault is one monolithic note. brain_read refuses to dump anything over AI_BRAIN_READ_BUDGET and returns the heading tree annotated with per-section sizes:

⚠ This note is 17.6 KB, above the 7.8 KB read budget, so here is its outline.
  Call brain_read again with `section` to pull one part.

## Outline
- Large Project — 17.5 KB
  - Architecture — 7.2 KB
    - Data Layer — 2.2 KB
    - Transport Layer — 2.3 KB
  - Operations — 7.2 KB
    - Deploy Notes — 2.3 KB
    - Rollback Notes — 2.3 KB
  - Open Questions — 2.8 KB
  - Further Reading

The agent now knows exactly what to pull, and a 128 KB note costs ~800 tokens to triage instead of ~33,000 to read. Section reads honour the same budget, so a top-level heading spanning the whole file is not a back door around it.

Safety as code, not as prompt

Vault rules like "never delete" and "never overwrite a canonical note" are enforced structurally rather than asked for in a system prompt:

• There is no delete tool and no canonical write tool. A confused model cannot produce one.
• brain_capture reaches only the two configured capture directories, always appends, never overwrites.
• Every filesystem access goes through one safeJoin choke point that rejects traversal.

Install

Requires Node 20+.

git clone https://github.com/HenryCordes/ai-brain-mcp
cd ai-brain-mcp
npm install     # builds via prepare
npm test        # 36 end-to-end checks against a fixture vault, no setup needed

Check it against your own vault (read-only, never writes):

npm run doctor -- ~/AI-Brain

connected · 5 tools: brain_map, brain_search, brain_read, brain_graph, brain_capture
root: /Users/you/AI-Brain · 49 notes · 351.3 KB
map payload: ~1209 tokens

3 note(s) over the read budget, served as outlines:
  Projects/Large Project.md · 128.3 KB · ⚠ large: read by section

Claude Code

claude mcp add --scope user ai-brain -- node /absolute/path/to/ai-brain-mcp/dist/src/index.js ~/AI-Brain

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json on macOS, %APPDATA%\Claude\claude_desktop_config.json on Windows:

{
  "mcpServers": {
    "ai-brain": {
      "command": "/absolute/path/to/node",
      "args": ["/absolute/path/to/ai-brain-mcp/dist/src/index.js", "/absolute/path/to/vault"]
    }
  }
}

Use an absolute path for command. The desktop app does not inherit your shell PATH, so a bare node fails to resolve under nvm or Homebrew. node -e 'console.log(process.execPath)' prints the right value.

Cowork

Nothing extra. Cowork sessions proxy the MCP servers registered in Claude Desktop, so once the entry above exists the same tools appear there. One server, one vault, every surface, with no exported snapshot to keep in sync.

Configuration

Setting	Default	Meaning
first CLI argument	—	Vault root. Wins over the env var.
AI_BRAIN_VAULT	~/AI-Brain	Vault root.
AI_BRAIN_READ_BUDGET	24000	Characters above which brain_read returns an outline.
AI_BRAIN_ROOT_DOCS	CLAUDE.md,Home.md	Docs brain_map loads verbatim as boot context.
AI_BRAIN_CAPTURE_INCOMING	meta/Inbox/incoming	Capture target for raw material.
AI_BRAIN_CAPTURE_PROPOSALS	meta/Inbox/proposals	Capture target for drafted note edits.

Skipped during indexing: .obsidian, .git, .trash, node_modules.

Your vault is a runtime argument, never repo content. Nothing from it is copied into this project.

Why no RAG

Embeddings earn their keep when you physically cannot look at everything. A 600 KB vault is roughly 150k tokens: the whole corpus fits in a single context window, and a full in-memory scan of it takes single-digit milliseconds. That is faster than a vector round trip, and the agent can see why a note matched rather than trusting a cosine score it cannot inspect.

The structure a RAG pipeline would try to recover statistically — folders, frontmatter tags, wikilinks, heading hierarchy — is already hand-authored in a vault like this. Indexing it away and approximating it back is a net loss.

What actually hurts at this scale is not recall, it is one 128 KB note that an agent can only read all-or-nothing. That is a chunking problem, and the read budget solves it without an embedding model anywhere in the stack.

If a vault outgrows this, src/search.ts is the single seam: swap its body for BM25 or a hybrid index. The tool contract above it does not change, so nothing downstream has to be re-taught.

Architecture

src/config.ts   vault root, ignore list, capture allowlist, safeJoin
src/vault.ts    index (notes, tags, links, headings), wikilink resolution, sections
src/search.ts   in-memory ranked lexical search   ← the swappable seam
src/capture.ts  the only write path, queue-only, append-only
src/tools.ts    MCP tool surface and output formatting
src/index.ts    stdio wiring
src/doctor.ts   install check against a real vault
test/smoke.ts   end-to-end over the real protocol, against test/fixtures/vault

The index refreshes itself by fingerprinting (path, mtime, size) on every call. At this scale a rescan is cheaper than any cache-invalidation scheme, so there is no staleness to reason about.

Development

npm run dev     # tsc --watch
npm test        # build, then the full suite against a disposable fixture copy

Tests drive the server as a real MCP client over stdio, so they exercise the protocol rather than the internal functions. The fixture vault covers tags, wikilinks, a broken link, an ambiguous note name, headings inside fenced code, an ignored .obsidian directory, and an oversized note.

License

MIT

---

Built by Henry Cordes — devartist.nl · LinkedIn