Metadata-Version: 2.4
Name: brain-neural-core
Version: 1.0.4
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

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

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

```powershell
.\scripts\install.ps1               # Windows PowerShell
```

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

```bash
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](#after-a-reboot-or-an-os-update) for the one-line fix if you do.

### Upgrade

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

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

### Quick path — one command after install

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

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

```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 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 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](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 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.)*
