brain-vault

A personal knowledge brain for Claude Code — an Obsidian-style markdown vault exposed as an MCP server. Gives Claude persistent, long-term memory across sessions for all your projects.

Notes live as plain markdown files in a vault directory on your machine. The MCP server exposes 8 tools that let Claude read, write, search, and traverse the note graph. Tool descriptions are written as behavioral nudges so Claude builds up and consults the brain automatically — without you having to ask.

~/brain/
  MANIFEST.md              ← index of all projects
  projects/
    my-project/
      index.md             ← entry point (required)
      decisions.md
      context.md
  concepts/                ← reusable ideas, patterns, tech
  people/                  ← collaborators, contacts
  scratch/                 ← quick capture

Notes use standard markdown with YAML frontmatter:

---
type: project          # project | concept | person | decision | scratch
project: my-project
tags: [backend, auth]
created: 2026-03-21
updated: 2026-03-21
---

Relationships between notes are expressed as wikilinks: [[other-note]]. The server tracks backlinks automatically.

• Python 3.11+
• uv
• ripgrep (rg on PATH)
• Claude Code

1. Clone the repo

git clone https://github.com/dvnc0/brain-mcp
cd brain-mcp

2. Install dependencies

uv sync

3. Register with Claude Code

claude mcp add brain -s user -- uv run --project /path/to/brain-mcp --directory /path/to/brain-mcp python server.py

Then set the vault location (defaults to ~/brain if not set):

# Edit ~/.claude.json and add "env": {"BRAIN_DIR": "/path/to/your/vault"}
# under the brain mcpServers entry, or set it as a shell env var.

4. Verify

Restart Claude Code and run /mcp — you should see the `b