brein

a brain that lives in your company.

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

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.