Content
<p align="center">
<a href="https://brein.sh"><img src="assets/brain.gif" alt="brein" width="320"></a>
</p>
<h1 align="center">brein</h1>
<p align="center"><em>a brain that lives in your company.</em></p>
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
```bash
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.
<details><summary>From source</summary>
```bash
git clone https://github.com/brein-sh/brein && cd brein
uv sync
brein setup
brein mcp claude
```
</details>
## CLI
```bash
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`](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
```text
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`.
