brein is a local MCP server for a company memory that lives in git: markdown docs in your repo, readable and writable by AI agents. Works with Claude Code, Cursor, Codex, Hermes, and any stdio MCP client.

Website: https://brein.sh

Quickstart

npx brein init

Walks you through the brain repo, paths, eval, and MCP client config. Then restart your client and verify with brein doctor.

Requirements: Node, Python 3.11+, git, an MCP-capable client.

git clone https://github.com/brein-sh/brein && cd brein
uv sync
brein setup
brein mcp claude

CLI

brein setup [section]   # all sections, or one of: repo paths vector eval mcp
brein doctor            # ok/warn/fail health checks
brein mcp <client>      # claude | cursor | codex | generic
brein config            # show resolved config
brain-eval --limit 20   # local retrieval evals against $BRAIN_REPO

Tools exposed over MCP

Tool	Purpose
`brain_search(query, mode="hybrid")`	Keyword / vector / hybrid retrieval with optional rerank.
`brain_evidence(question)`	Ranked docs + snippets + excerpts + citations in one round-trip. The client agent writes the final answer.
`brain_update(file_path, content, commit_message, mode)`	Write to an allowed path, validate, commit, push.
`brain_audit()`	Repo cleanliness, doc/frontmatter counts, log + index health.
`brain_retrieval_log(...)`	Telemetry; search auto-logs.

For plain reads / listings, agents use their normal file tools (Read, Glob, Grep) against the brain repo directly — the MCP only mediates what plain tools can't do: semantic search and policy-gated writes.

Write policy: paths under docs/, skills/, templates/, plus AGENTS.md / README.md / CONTRIBUTING.md at the root. Secrets are pattern-blocked.

Configuration

brein setup writes ~/.brein/config.json. Environment variables override the file and are documented in src/brain_mcp/config.py. The big ones:

BRAIN_REPO — path to your brain git repo (required)
BRAIN_RETRIEVAL_LOG — JSONL telemetry path
BRAIN_VECTOR_INDEX — vector index cache path
BRAIN_EMBEDDING_MODEL — fastembed model (default BAAI/bge-small-en-v1.5)

Project layout

src/brain_mcp/          MCP server + `brein` CLI
src/brain_mcp/_scripts/ bundled helpers (eval, index, validate)

Contributing

Issues and PRs welcome. See CONTRIBUTING.md.

License

MIT. See LICENSE.

Brein

README