Brainbox

Install · How it works · Results · Research · Integrations · Whitepaper

BrainBox is procedural memory for AI coding agents. It watches what the agent actually does and remembers it:

• which files get read and edited together
• which errors were fixed by which edits
• which tool chains the agent repeats

On the next task it puts the right files in front of the agent *before* it starts searching.

Not a vector database. Not RAG. Hebbian learning on a local SQLite graph. Zero API cost, no GPU, nothing leaves your machine.

Session 1   agent greps for auth.ts, reads it, edits it            ~2,000 tokens of searching

Session 5 BrainBox recalls auth.ts + session.ts up front search skipped Session 20 auth.ts → session.ts → token.ts is a superhighway instant recall

Paper

BrainBox: Local Behavioral Memory for Coding Agents (Bhavesh B, 2026). The DOI above covers all versions and resolves to the latest. Latest version: v0.2, doi:10.5281/zenodo.23250505.

@misc{b2026brainbox,

author = {B, Bhavesh}, title = {BrainBox: Local Behavioral Memory for Coding Agents}, year = {2026}, publisher = {Zenodo}, version = {v0.2}, doi = {10.5281/zenodo.23250505}, url = {https://doi.org/10.5281/zenodo.23250505} }

Install

npm install brainbox-hebbian

That's it. The postinstall script:

1. Adds a PostToolUse hook to ~/.claude/settings.json. It learns from every file read, edit, search and command.
2. Adds a UserPromptSubmit hook. It injects compact recall into prompts, or stays silent once it has learned you ignore it.
3. Adds a SessionEnd hook. It scores which recalled files you actually opened or edited and compiles procedures.
4. Registers the MCP server via claude mcp add, with 8 tools: record, recall, explain, error, resolve, predict_next, stats, decay.
5. Creates ~/.brainbox/ and starts a background download of the embedding model.

Hooks never download models. Until the model is cached (brainbox models pull), recall runs lexical-only. Embeddings come from the optional @huggingface/transformers dependency; if its native modules can't install on your machine (for example, sharp with a system libvips and no build tools), BrainBox still installs and runs with keyword search. brainbox models status shows which mode you are in.

Kill the cold start by seeding from git history and the code graph:

brainbox bootstrap --repo /path/to/project --imports

Uninstall: brainbox uninstall removes the hooks and the MCP server and keeps your database.

How it works

Every tool call is a neuron firing. Files, tools and errors become neurons, and things accessed close together become synapses. A prompt triggers recall, which fuses several ranking channels. A learned policy decides whether injecting is worth the tokens. Feedback on what you actually opened or edited flows back into the graph.

Fire together, wire together

Access auth.ts then session.ts across sessions and their synapse strengthens. SNAP plasticity makes strong synapses grow more slowly, so no single connection takes over. Links are directional (STDP): what you open *next* matters more than what came before.

Spreading activation

Recalling one file activates its neighbours for up to 3 hops. Each hop is damped by 1/√degree, so hub files don't flood the results. Each result carries the channel and the edge that produced it. brainbox_explain shows you exactly why a file was recalled.

Superhighways and decay

Paths you use often are myelinated into instant-recall superhighways. Recency and frequency follow the ACT-R base-level equation, B = ln Σ tⱼ^-0.5, and unused connections fade. Files recalled but ignored weaken only the edge that surfaced them.

Error → fix immune system

When a failed command is followed by edits and a passing rerun, BrainBox stores an error→fix procedure. The procedure is keyed by the error's fingerprint and tracks helpful/harmful outcomes. The next time that error appears, the fix files are recalled at once. Procedures are shown to the agent as quoted observations, never as instructions.

Results

brainbox eval replays real coding-agent trajectories in time order. Each task is scored on a fresh in-memory DB trained only on earlier tasks from the same repo, and every system ranks the same candidate set.

v0.1 lost to plain recency on next-file prediction. On the held-out SWE tasks the gap was −.207, 95% CI −.312…−.118. v0.2 is statistically tied with recency there. Next-tool prediction now beats every baseline significantly, and files-read recall leads on both data sources.

Known gap: on local sessions, ranking by edit frequency alone still beats BrainBox for *edited* files (Δ −.089, CI −.185…0).

Fitting the lexical and Hebbian channel weights to zero scored higher on dev, but recall then ignored the query, so the shipped weights keep them.

Full table, protocol and commands

Probes:

• P1: files edited or read for the task (query = task text)
• P2: next file, step by step
• P3: next tool (top 3)

Baselines: recency, frequency, BM25, EdgeBank and random. Confidence intervals are paired bootstrap 95% CIs, resampled by trajectory.

Datasets:

• Ranking weights were fit only on the dev repos (sqlglot, dvc, streamlink).
• SWE test is 40 held-out tasks from Pillow and conan.
• Local is 97 agent sessions across 5 projects, never used for fitting.

Scores are MRR (P3: MRR@3), with embeddings off.

npm run eval -- --source nebius --repos 5 --max-tasks-per-repo 20 --split test --embeddings off --engine new

npm run eval -- --source omp --repos 5 --max-tasks-per-repo 20 --embeddings off --engine old # v0.1 engine (needs a worktree, see src/eval)

Code search: on a 30-query code-search set, the default jina-embeddings-v2-base-code reaches Recall@5 0.867, against 0.667 for the previous MiniLM.

Built on research

Each v0.2 change maps to a recent paper and was measured with the replay eval:

Also in 0.2:

• Builds on Node 22–26 (better-sqlite3 v13).
• Hooks are written in Claude Code's nested settings format.
• The hook DB lock wait is capped at 100 ms.
• Procedure compilation is 470× faster