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

Brain is a command-line tool, so it belongs in its own isolated environment rather than in a project's site-packages. Two commands, and you are done:

pipx install brain-neural-core       # or: pip install brain-neural-core
brain setup                          # wire your repos, seed memory, verify the handshake

brain setup is the whole installation after the package: it walks each repository you choose, runs brain init and brain bootstrap for it, and finishes with the real MCP handshake check. Nothing else is required. If you would rather run the pieces yourself, see Manual steps below.

brain --version                      # expect: brain, version 1.0.7

pipx or pip — pick one and stay with it. Switching moves the executable, and the MCP config records its absolute path.

.\scripts\install.ps1               # add -SkipSetup to install only, -Version X.Y.Z to pin

./scripts/install.sh                 # SKIP_SETUP=1 / VERSION=X.Y.Z

If you do switch, see After a reboot, or an OS update for the one-line fix.

Upgrade

brain upgrade

That checks the two things that make an upgrade fail without a readable error, clears what it can, and prints the exact command for the environment it found:

• the legacy project-brain distribution, which shadows this one on PATH — so the upgrade appears to succeed and changes nothing, and pipx uninstall brain-neural-core does not remove it because the distribution name differs;
• a running MCP server, which on Windows locks the .exe pip must replace, failing mid-write and leaving a half-upgraded install. Almost always an editor holding it open.

It prints the command instead of running it, because the brain you just typed is itself the process holding that file. Run what it gives you, then:

brain doctor                          # real MCP handshake, not just a file check

Your .brain/ memory and AGENTS.md are untouched by an upgrade. If brain doctor reports the handshake failing afterwards, the executable moved — brain init re-stamps the paths.

brain upgrade --check reports without changing anything; -y stops a running server without asking.

Remove

Two separate things, deliberately. brain uninstall removes Brain's wiring from a repository — git hooks, MCP config, merge drivers, instruction mirrors — and keeps your captured memory, because .brain/memory/ is usually committed and deleting it changes the team's record:

brain uninstall --dry-run             # show what would go
brain uninstall                       # wiring only
brain uninstall --all                 # memory too

It does not remove the package, and prints the exact command for that instead — including the legacy-name trap, where pipx uninstall brain-neural-core silently leaves an older project-brain install in place and on PATH.

Replacing an old version? You do not need any of this. Use brain upgrade above; it handles the conflicting install and the locked executable for you.

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

pipx install brain-neural-core==1.0.7

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.

See where Brain is running

brain manage

Opens a local page with two screens.

Installation — which version of Brain is on this machine, how it got here, what the package index offers, and anything that would make an upgrade fail. It never claims you are up to date when it simply could not reach the index.

Projects — the projects Brain actually manages, each with a proof-based verdict on whether capture is working: the hooks, the interpreter they point at, whether an agent can reach the memory, when capture last ran on this machine, and whether anything failed quietly. Green means proven, not "no problem found".

It does not go looking through your other folders. Repositories without Brain are counted — so you know how many there are — and never listed or analysed. To add one, point the page at a folder: it measures that folder alone and tells you whether Brain is worth adding, including when the answer is no.

Loopback only; nothing leaves the machine. Removal previews what it would take out before it takes anything.

After brain setup — the two steps it cannot do for you

brain setup wires every repository, seeds memory, and runs the handshake check. Two things are still yours, and skipping them is the most common reason an agent reports no Brain tools:

Restart your editor. An MCP server is only discovered when a session starts, so Brain is invisible to any window that was already open.

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.

Then brain doctor should report MCP handshake 10 tool(s), 2 prompt(s). That is done.

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)
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

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__…:

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

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 65-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.7) 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 1,712 tests, run on Windows and Linux.

Extraction precision, by hand-labelling every item Brain captured against a rubric written before any item was judged:

The second row is the one that matters — the author of a heuristic is not a fair judge of it, so a repo was held out and labelled by someone else, and that it scored higher is evidence the rules are not merely fitted to the examples we looked at. Both are small samples: 20 judged items carries roughly a ±15 point error bar, so read "86–90%" as probably somewhere in the eighties, not a precise value. A further 36% of the held-out repo's items could not be judged at all, mostly configuration values — if a careful engineer cannot say whether some.key is set to 512 is a boundary or a free setting, an agent cannot either, and we count that as a real weakness rather than a labelling problem.

Recall — how much of a repository's memory Brain actually finds — is unmeasured. It would mean reading whole repositories to enumerate what should have been captured, and we have not done that work. Anyone quoting a recall number for a tool like this, ours included, should be asked how they measured it.

Robustness. The engine is re-run across a corpus of real repositories and compared per-repo against the previous run; the run is rejected if any noise class worsens. Most recent: 2026-08-31, all 65 repositories extracted, 5,374 items, no noise class worse than the previous run. That catches regressions and residue. It cannot tell us whether what we capture is useful — only labelling does that.

Large repositories are truncated. Brain keeps at most 253 items per kind (60 for technical debt), keeping the most important first — severity leads the ranking, so a critical rule is never evicted in favour of a tidier trivial one. On the corpus above, 15 of 65 repositories sit exactly at one of those caps, and for those we know only that Brain found more than it kept. Raise it with BRAIN_MAX_STORED_PER_KIND (0 means unlimited).

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.)