# 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](#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+.

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

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

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

```json
{
  "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

```bash
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](https://devartist.nl) · [LinkedIn](https://www.linkedin.com/in/henrycordes)