Project Brain

Engineering memory for AI-assisted teams. Project Brain captures the decisions, constraints, and hard-won lessons in your codebase — automatically, on every push — keeps them in version control alongside your code, and serves them to your AI coding agents so a session starts with what your team already decided instead of guessing at it.

It is deterministic by default (no LLM, API key, or network required) and conflict-aware: when new work contradicts a settled decision, Brain flags it and records how you resolved it.

---

Try it without installing: try.brainledger.solutions

Setup

Prerequisites: Python 3.10+ and Git must be on your PATH.

Install

Recommended — pipx. Brain is a command-line tool, so it belongs in its own isolated environment rather than in a project's site-packages:

pipx install brain-neural-core
brain --version                      # expect: brain, version 1.0.4

One command, if you'd rather not think about it. These do the same thing, plus they check your prerequisites, install pipx if it's missing, detect a conflicting older install, and hand off to brain setup:

.\scripts\install.ps1               # Windows PowerShell

./scripts/install.sh                 # macOS / Linux

Add -SkipSetup (or SKIP_SETUP=1) to install only. Add -Version 1.0.4 (or VERSION=1.0.4) to pin explicitly.

pip works too, if you already manage a virtualenv yourself:

pip install brain-neural-core

Pick one and stay with it. Switching between pip and pipx moves the executable, and the MCP config records its absolute path — see After a reboot, or an OS update for the one-line fix if you do.

Upgrade

pipx upgrade brain-neural-core        # or: pip install --upgrade brain-neural-core
brain --version                       # confirm the new version
brain doctor                          # confirm hooks + MCP still pass

Nothing else is needed — your .brain/ memory and AGENTS.md are untouched by an upgrade. If brain doctor reports the MCP handshake failing afterwards, the executable moved; run brain init in the repo to re-stamp the paths.

On a team, upgrade everyone together and pin the version:

pipx install brain-neural-core==1.0.4

This is not just tidiness. A memory item's identity is derived from its text, so when a release improves how a rule is worded, the new wording arrives as a new item rather than replacing the old one. Two teammates on different versions therefore commit two copies of the same rule. See docs/UPGRADING.md for what to do if that has already happened.

Quick path — one command after install

# 1. install  (see Install above for pipx / installer-script options)
pipx install brain-neural-core

# 2. wire repos, seed memory, and verify in one go
brain setup

brain setup walks you through each repo interactively, runs brain init and brain bootstrap for each one, then performs the step-6 brain doctor check. Steps 3 and 4 below (editor restart and approval) are still yours.

Manual steps — if you prefer to run each piece yourself

Six steps, once per repository. Run them in this order.

# 1. install  (see Install above for pipx / installer-script options)
pipx install brain-neural-core

# 2. wire this repo — git hooks + MCP config for your editor
cd your-repo
brain init

# 3. seed memory from the history you already have
brain bootstrap

4. Restart VS Code (or whichever editor you use — quit and reopen it).

An MCP server is only discovered when a session starts, so Brain is invisible to any editor window that was already open. This is the most common reason an agent reports no Brain tools.

5. Approve the server when your editor asks. An editor will not launch a local program just because a config file says so. In Claude Code, accept the trust this project prompt; in Cursor, Windsurf or Cline, enable project-brain in the MCP settings if it shows as disabled.

# 6. verify — this performs a real MCP handshake, it does not just check for files
brain doctor

Expect MCP handshake 10 tool(s), 2 prompt(s). If you see that, setup is done.

From here, keep using Git as before: git push captures new memory, git pull captures rationale from merged pull requests, and your agent is served the relevant memory before it edits a file.

Optional extras, not needed for the above: pipx install "brain-neural-core[openai]" — or [anthropic], [google], [groq] — enables the optional LLM enrichment pass (brain init --llm). On pip, the same spec works; with pipx on an ALREADY-installed Brain, add --force (pipx does not add extras to an existing install). [docs] reads .docx / .pdf, which are picked up by capture on push, not by brain bootstrap.

How it works

1. Capture. On every push/merge, Brain reads your commits and code and records structured engineering memory across seven kinds:

   Kind	What it captures
   Decision	why it was built this way
   Constraint	a limit or invariant the code must hold
   Business rule	a domain rule the code must reflect
   Historical failure	something that broke before — so it isn't repeated
   Trade-off	what was exchanged for what
   Intent	what a feature is meant to do
   Technical debt	a TODO/FIXME the team acknowledged and deferred

   The first six are rules: they go into AGENTS.md and are served to your agent before it edits a file. Technical debt is recorded, exported and counted, but deliberately kept out of both — it is acknowledged-but-deferred work, not a rule to obey.

   It runs locally and deterministically — nothing leaves your machine.

2. Store. Memory lives in version control (AGENTS.md + a .brain/ folder), so it travels with the repository and merges cleanly across your team.

3. Serve. Brain ships an MCP server that hands the relevant memory to your AI agent before it edits a file — so the agent respects your prior decisions instead of relitigating them.

4. Stay conflict-aware. When a newly-captured decision contradicts a settled one, Brain surfaces it — in your agent's chat and in brain review. Accepting the new one supersedes the old: the resolution is recorded (what replaced what, when, and by whom), and the retired decision is kept as history but no longer served.

Deterministic by default. Capture, conflict detection, and serving all run with no LLM, key, or network. An optional enrichment pass (bring your own key — local via Ollama, or a cloud provider) adds deeper, inferred memory; enable it with brain init --llm.

Commands

Command	What it does
brain init	Set up Brain in the current repo (capture + AI-tool config). One-time.
brain setup	Check the machine, wire one or more repos, and verify an agent can reach Brain.
brain bootstrap	Seed memory from your existing history. One-time deep scan.
brain status	What Brain knows about this repo, at a glance.
brain review	Review proposed memory — accept (and supersede conflicts) or reject.
brain search <words>	Search your memory by keyword — the claim, its rationale, its file.
brain value	Whether Brain has actually changed anything for you, and where it hasn't.
brain context --file <path>	Show the memory relevant to a file (what your agent receives).
brain view	Project the memory into a risk & knowledge report, a one-page brief, or a team-adoption rollup.
brain pending	Show memory queued for the next push, before it is shared.
brain add	Manually record a decision, rule, or constraint.
brain forget <text-or-id>	Remove a captured item that is wrong, and stop it coming back.
brain export	Export captured memory to a shareable text file.
brain verify	Retire memory whose source file is gone, report stale items, and rebuild AGENTS.md if it has drifted from .brain/memory/.
brain doctor	Verify the setup and diagnose issues.
brain uninstall	Remove Brain's wiring from a repo (memory is kept unless you ask).

Capture on git push / git pull is automatic after brain init — you rarely run it by hand. Run brain --help for the full list.

Connect your AI tool (MCP)

brain init writes the config for Cursor, Claude Code, Windsurf and Cline (step 2 above); any MCP-capable client can point at the bundled brain-mcp-server. Steps 4 and 5 of Setup — restart the editor, approve the server — are the parts that cannot be automated from here.

Per-editor detail for step 5:

• Claude Code — reads .mcp.json at the repo root and prompts you to trust the project the first time you open it. Accept it, then run /mcp; project-brain should be listed. If it is never offered, register it at user scope instead:

  claude mcp add project-brain brain-mcp-server -e "BRAIN_REPO_ROOT=/path/to/your-repo"
  claude mcp list          # project-brain should appear
  

• Cursor / Windsurf / Cline — open the MCP settings and enable project-brain if it shows as disabled or pending. brain init wrote .cursor/mcp.json, .windsurf/mcp.json or .cline/mcp_settings.json.

Two commands you can run inside the chat

Once the server is connected, your editor lists Brain's prompts alongside its own — in Claude Code they appear as /mcp__project-brain__…:

prompt	what it does
value	Reports what Brain has actually changed in this repo, in the chat. Same figures as brain value.
why (file)	Explains why a file is the way it is, using only recorded memory — and says so plainly where nothing was recorded, rather than inferring a rationale from the code.

Like tools, prompts are fixed when a session starts, so they appear after the next restart.

After a reboot, or an OS update

Nothing to restart. The MCP server is not a background service — your IDE launches brain-mcp-server on demand over stdio and it exits with the session. A reboot leaves no state to recover, and the first agent session afterwards starts it fresh.

What does break the link is anything that moves the executable, because the config records its absolute path: pipx reinstall, a Python minor upgrade, switching between pip and pipx, or recreating a venv. Symptom: the agent has no Brain tools, and brain doctor reports the handshake failing.

brain init          # re-stamps the paths in this repo
brain doctor        # confirm the handshake passes again

Git hooks are stamped the same way, so re-running brain init after any environment change fixes capture and MCP together.

Is Brain actually capturing?

A hook file existing is not a hook running, so Brain records a heartbeat each time capture runs and reports it plainly:

brain doctor        # per repo, with the reason
brain status        # push count and last capture date

what you see	what it means
capture is running	the hook ran at the current commit — working
capture is STALE	it ran before, but commits have landed since without capture
capture never ran here	no heartbeat at all — expected in a fresh clone, since git hooks are never cloned

brain status also reports the other half — whether anything has actually read the memory:

Served to agents
  Retrievals (7 days):      24
  Last retrieval:           2026-08-05 09:12 UTC
  Most used:                get_context x18, search_memory x4

none recorded on this machine means either no agent has queried Brain yet, or MCP isn't reachable — brain doctor performs a real handshake and tells you which. This reads the local, per-developer log, so it reflects your machine, not the team's.

That last one is the case people miss: cloning a Brain-enabled repo brings the memory but not the hooks. Run brain init in the clone, make a commit and push, and the state moves to capture is running.

For a repo where capture must not silently stop, brain setup --ci installs a GitHub Actions workflow that reports when memory has not been updated alongside a change.

Is it worth keeping?

brain value

Counts the times Brain changed an outcome — a rule that blocks, an approach already rejected in this repo, a contradiction caught before it landed — and keeps those apart from raw retrieval counts, which only prove a tool ran.

Did it change anything?
  ✓  Changed the outcome           9 time(s)
  Blocking rules supplied:      14
  Rejected approaches raised:    3
  Contradictions caught:         2

Activity  ·  context, not value
  Agent retrievals (30d):       12
  ...

Memory
  Items:                        58
  Carrying a rationale:          6 of 58 (10%) - the WHY an agent cannot re-derive

That last figure is usually low, and this sample is not flattering it: across our 58-repository corpus only about 2% of captured items carry a rationale. Most memory records what a rule is, not why it exists — which is a real limitation, and one brain value is designed to show you rather than hide.

It will also tell you when the answer is unflattering. Read, but not steering means your agent is pulling memory but none of it was consequential — usually because the captured items restate the code instead of recording a why. No evidence yet means nothing has queried Brain at all, which is most often MCP not being authorised in your editor; brain doctor performs a real handshake and tells you which.

Working as a team

Captured memory collates by itself — AGENTS.md and .brain/memory/ are committed, so everyone on the repo shares it through normal git pull / git push, and brain init registers merge drivers that union concurrent capture instead of conflicting.

Each teammate still runs the whole of Setup once per clone — all six steps, including the editor restart. Git does not clone hooks, and MCP config is per-machine, so a fresh clone captures nothing and serves nothing until they do. They can skip step 3 (brain bootstrap); the memory is already committed.

Keep the whole team on the same version. Item identity is derived from item text, so a release that improves a rule's wording produces a new item rather than superseding the old one — and two teammates on different versions will commit two copies of the same rule, which the union merge driver then faithfully preserves. Pin it (pipx install brain-neural-core==1.0.4) and upgrade together; see docs/UPGRADING.md.

To see whether it is actually being used:

brain view --lens team

Team totals
  Developers reporting:    4
  Memory contributed:      82
  Conflicts caught:        4
  Agent retrievals:        267

By developer
  developer               contributed  conflicts  retrievals   last active
  Arjun Sharma                     58          3         142    2026-08-05
  Priya Nair                        9          0           0    2026-07-30
  !  not retrieving   1 developer(s) contribute memory but never read it

Each developer's machine writes one shard to .brain/metrics/<name>.json on push. One file per person means shards never merge-conflict. They hold counts and a date only — never your queries, file paths, or per-call times — and a developer showing contributions but zero retrievals almost always has MCP unauthorised in their editor, which brain doctor on that machine will confirm.

Status

Beta. The deterministic capture path, MCP serving and conflict handling are in daily use and covered by over 1,300 tests, run on Windows and Linux.

Every release is regression-tested against a 58-repository corpus, and extraction quality is checked by hand-labelling what Brain captured from repositories held out from development. On the most recent of those, 86–90% of captured items were judged correct by a reviewer who did not write the extraction rules. That is a small sample, so treat it as indicative rather than precise; how much of a repository's memory Brain finds is not something we have measured.

Extraction is not perfect — expect to prune the occasional item with brain review / brain forget, and please report anything that looks wrong.

Brain is built for working codebases. Pointed at a tutorial or textbook repository, it will mine the subject matter being taught as though it were the project's own decisions.

In progress: richer rationale on captured items, and better handling of plain configuration values. Memory is plain JSON in your repo, so nothing is ever locked in.

License

Source-available under FSL-1.1-Apache-2.0 — free for internal and most uses. The full text ships as LICENSE.md inside the package.

(PyPI and pip show display this licence as FSL-1.1-ALv2. Same licence, two registries: the Functional Source License names itself FSL-1.1-Apache-2.0, while FSL-1.1-ALv2 is its SPDX identifier, and Python package metadata must use SPDX.)