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.

How it works

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.

Requirements

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

Installation

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 brain server connected.

The vault directory, folder structure, and MANIFEST.md are created automatically on first startup. Just point BRAIN_DIR at any empty directory (or let it default to ~/brain).

Tools

Tool	When Claude uses it
brain_recent_tool	Start of every session — orients Claude to what's in flight
brain_context_tool(project)	Before asking you to re-explain a project
brain_read_tool(path)	Read a note + its wikilink neighbors
brain_search_tool(query)	Full-text search across all notes
brain_related_tool(path)	Find all notes that link to a given note
brain_write_tool(path, content, metadata)	End of session — persist decisions and learnings
brain_link_tool(from, to)	Add a wikilink between two notes
brain_suggest_links_tool(content)	Scan text and suggest existing notes to link

Path and frontmatter rules

The server enforces these at write time and returns an error if violated:

• All paths are relative to the vault root (no absolute paths)
• Must start with projects/, concepts/, people/, or scratch/
• Project notes must be at projects/<name>/<file>.md — not directly in projects/
• projects/<name>/index.md must be created before any other file in that project
• New notes require type and tags frontmatter fields
• Valid types: project, concept, person, decision, scratch

Configuration

Env var	Default	Description
BRAIN_DIR	~/brain	Path to your vault directory

Vault structure conventions

Every project needs an index.md — it's the entry point for brain_context_tool. Without it the tool can't traverse the project's note graph.

Suggested files per project:

• index.md — overview, status, links to sub-notes (required)
• decisions.md — key decisions and rationale
• context.md — background, constraints, stakeholders

Keep MANIFEST.md updated with one line per project — it's the map Claude reads to know what exists.

License

MIT