Brain add-on

The Brain MCP server gives Claude a memory that outlasts the conversation: a folder of markdown notes on your own server that Claude can search, read and write. Decisions, server details, client agreements and how-tos end up in the vault, and the next conversation starts by looking them up instead of asking you again.

Brain is an add-on for mcp-core, the self-hosted MCP server. mcp-core runs in Docker on your infrastructure, and the vault is a plain folder you mount into the container. The notes stay ordinary .md files. You can open them in any editor, back them up with your usual tools, or browse them in a markdown app next to Claude.

What can Claude do in a Brain vault?

The Brain MCP server gives Claude ten tools that cover the full life of a note:

• Read side: read a file, list the vault structure, search, and view the change history.
• Write side: write or update a file, append to a file, move or rename a file, rebuild the search index, and give a top-level folder a short description.
• Delete: remove a file that is no longer needed.

Search uses a fast index of summaries and headings first. If that finds nothing, it falls back to a full-content scan of every file. When you change files outside Claude, the reindex tool brings the index up to date.

Why is the Brain MCP server read-write by default?

It is read-write because a knowledge base Claude cannot write to has little value. Every other add-on on mcp-core starts read-only; Brain is the one exception. You can still add a seat with Brain set to read-only, for example to give a colleague look-up access to the vault without edit rights.

What makes read-write safe is versioning. With VERSIONING_ENABLED=true, every write, append, move and delete is committed to a git repository inside the vault. A bad edit is never an unrecoverable overwrite: Claude can show the history of one file or of the whole vault, and you can restore any earlier version with git.

Which guardrails does the vault have?

Paths are resolved inside VAULT_PATH and anything outside it is refused. The .git folder that holds the history can never be written, moved or deleted through the Brain tools. A logs folder is readable for Claude but protected against changes. These rules sit in the Brain MCP server itself, so they apply to every seat.

How do you set up the Brain MCP server?

You need a running mcp-core and a location for the vault, usually a mounted Docker volume. Then add three variables to your .env:

VAULT_PATH=/vault
VERSIONING_ENABLED=true
INDEX_MAX_AGE_DAYS=7

VAULT_PATH is required. VERSIONING_ENABLED is optional but recommended. INDEX_MAX_AGE_DAYS controls how often the search index is rebuilt. Run ./mcp-update.sh to apply the change. The Brain setup guide covers the volume mount and the first run.

How do you structure a vault?

Start with a handful of top-level folders, for example clients, servers, decisions and procedures. Ask Claude to add a one-line description to each. When you list the vault root, those descriptions show up, which helps Claude pick the right folder as the vault grows. Short, focused notes with clear headings search better than one long document.

Which add-ons work well with Brain?

The Brain MCP server is most useful next to a tool that produces information. With the Missive MCP server, Claude reads a customer thread and stores the agreement in the vault. With the Database add-on, it saves the SQL behind a recurring report so the next run starts from a known query.

For a broader explanation of the idea, read how to connect Claude to your notes.