Metadata-Version: 2.4
Name: brain-neural-core
Version: 1.0.7
Summary: Project Brain — Engineering memory for AI-assisted teams
Author-email: BrainLedger Solutions <brainledger.solutions@gmail.com>
License-Expression: FSL-1.1-ALv2
Project-URL: Homepage, https://brainledger.solutions
Project-URL: Playground, https://try.brainledger.solutions/
Keywords: ai,agents,engineering-memory,mcp,llm,code-context,git,developer-tools,knowledge-base
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Operating System :: OS Independent
Classifier: Environment :: Console
Classifier: Topic :: Software Development :: Version Control :: Git
Classifier: Topic :: Software Development :: Documentation
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE.md
Requires-Dist: GitPython>=3.1.43
Requires-Dist: python-dotenv>=1.0.1
Requires-Dist: click>=8.1.7
Requires-Dist: rich>=13.7.1
Requires-Dist: mcp<2,>=1.29
Provides-Extra: openai
Requires-Dist: openai>=1.35.0; extra == "openai"
Provides-Extra: anthropic
Requires-Dist: anthropic>=0.28.0; extra == "anthropic"
Provides-Extra: google
Requires-Dist: google-generativeai>=0.7.0; extra == "google"
Provides-Extra: groq
Requires-Dist: openai>=1.35.0; extra == "groq"
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Provides-Extra: all-cloud
Requires-Dist: openai>=1.35.0; extra == "all-cloud"
Requires-Dist: anthropic>=0.28.0; extra == "all-cloud"
Requires-Dist: google-generativeai>=0.7.0; extra == "all-cloud"
Provides-Extra: docs
Requires-Dist: python-docx>=1.1.0; extra == "docs"
Requires-Dist: pypdf>=4.0.0; extra == "docs"
Provides-Extra: all
Requires-Dist: openai>=1.35.0; extra == "all"
Requires-Dist: anthropic>=0.28.0; extra == "all"
Requires-Dist: google-generativeai>=0.7.0; extra == "all"
Requires-Dist: python-docx>=1.1.0; extra == "all"
Requires-Dist: pypdf>=4.0.0; extra == "all"
Dynamic: license-file

# Project Brain

![License: FSL-1.1-Apache-2.0](https://img.shields.io/badge/license-FSL--1.1--Apache--2.0-blue.svg)
![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)
![Status: Beta](https://img.shields.io/badge/status-beta-orange.svg)
![Local-first](https://img.shields.io/badge/architecture-local--first-2ea44f.svg)
![MCP server](https://img.shields.io/badge/MCP-server-8A2BE2.svg)

**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](https://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:

```bash
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](#manual-steps--if-you-prefer-to-run-each-piece-yourself) below.

```bash
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.

<details>
<summary><b>Installing from a source checkout?</b> Use the bundled installer scripts.</summary>

If you have cloned this repository, `scripts/install.ps1` (Windows PowerShell) and
`scripts/install.sh` (macOS / Linux) do the same install plus the things a bare `pip` line
cannot: they check prerequisites, install `pipx` if it is missing, remove a conflicting
older distribution, and hand off to `brain setup`. The PowerShell one also stops a running
MCP server first, because Windows will not replace a locked `.exe`.

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

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

Installing from PyPI instead? You do not need these — the same protections ship inside the
package as `brain upgrade` and `brain doctor`.

</details>

If you do switch, see [After a reboot, or an OS
update](#after-a-reboot-or-an-os-update) for the one-line fix.

### Upgrade

```bash
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:

```bash
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:

```bash
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:**

```bash
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](https://github.com/brainledger-solutions/brain-neural-core/blob/main/docs/UPGRADING.md) for what to do if that has already
happened.

### See where Brain is running

```bash
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.

```bash
# 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.

```bash
# 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](https://ollama.com), 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 upgrade` | Check what an upgrade needs, clear the blockers, print the exact command. |
| `brain manage` | Two screens: the installation on this host, and the projects Brain manages — with a proof-based verdict on whether capture is working. |
| `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:

  ```bash
  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.

```bash
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:

```bash
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?

```bash
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](https://github.com/brainledger-solutions/brain-neural-core/blob/main/docs/UPGRADING.md).

To see whether it is actually being used:

```bash
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:

| labelled by | repos | precision |
|---|---|---|
| the engine's own author | 2 | **77%** (50 items) |
| an independent labeller, on a repo never used for tuning | 1 | **86–90%** (20 items) |

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