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.

From source

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.

Metadata

Release files for brein-mcp 0.5.35

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for brein-mcp 0.5.35
File	Size	Uploaded
brein_mcp-0.5.35.tar.gz	5.6 MB	Jun 28, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for brein-mcp 0.5.35
File	Interpreter	ABI	Platform	Reset
brein_mcp-0.5.35-py3-none-any.whl 92.4 kB Jun 28, 2026	Python 3	none	any	Details

Total release size: 5.7 MB

Release files / brein_mcp-0.5.35.tar.gz

Download URL	brein_mcp-0.5.35.tar.gz
Size	5.6 MB
Tags	Source
SHA-256 checksum How to use checksums	`7386c947a35792c499f74d14ffa37b88fc06296ebb2d25fe69ab20c60a74cfd2`
BLAKE2b-256 checksum How to use checksums	`6aae5b5546cd29a2885cfd2ea54c704355cd8c6975185c9f7aef139151de9aba`
Upload date	Jun 28, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.2.0 CPython/3.11.15`

Release files / brein_mcp-0.5.35-py3-none-any.whl

Download URL	brein_mcp-0.5.35-py3-none-any.whl
Size	92.4 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`24664948d41070ef8a90b1d1cca69b84e655810a7833da26319debd3d3a9d5a7`
BLAKE2b-256 checksum How to use checksums	`5249dc1b0addbf4c9639f8589dc19a6e03aa5d7a6e3bef4d86ed6a548ed33b9f`
Upload date	Jun 28, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.2.0 CPython/3.11.15`

Release history Release notifications | RSS feed

This release

0.5.35 This release

brein-mcp 0.5.35