Brainbox

[BrainBox — muscle memory for coding agents]

[npm version] [GitHub stars] [Node 22+] [MCP: 8 tools] [Zero cost, local, SQLite] [MIT license]

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 searchingSession 5   BrainBox recalls auth.ts + session.ts up front         search skippedSession 20  auth.ts → session.ts → token.ts is a superhighway      instant recall

Paper

[DOI]

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

[BrainBox pipeline: tool calls → learn → recall → policy → inject, with a feedback loop]

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

[Hebbian learning: co-accessed files strengthen their synapse across sessions]

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

[Spreading activation from a seed file over three hops with fan-effect damping]

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

[Frequently used paths myelinate into superhighways while unused edges 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

[An error fingerprint is linked to the edits that fixed it and recalled the next time]

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

[v0.2 vs v0.1 vs best baseline on real agent trajectories]

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.

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

Built on research

[Recent papers mapped to the BrainBox subsystems they shaped]

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 on large histories.

Integrations

MCP server (any agent)

# 8 tools: record, recall (detail: compact|full), explain, error, resolve, predict_next, stats, decaynpx tsx node_modules/brainbox-hebbian/src/mcp.ts

Kilo / OpenCode (native plugin)

Add to ~/.config/kilo/config.json:

{  "plugin": ["node_modules/brainbox-hebbian/src/kilo-plugin.ts"]}

OpenClaw (NeuroVault)

BrainBox can run as an OpenClaw memory slot plugin. See NeuroVault for the reference implementation.

macOS daemon (opt-in)

A system-wide FSEvents file watcher that learns from VS Code, Xcode, vim and the shell, not just agents. It installs a LaunchAgent, so it requires an explicit opt-in:

brainbox daemon install   # installs LaunchAgent, starts watchingbrainbox daemon statusbrainbox daemon uninstall

CLI

brainbox recall "authentication login"brainbox record src/auth.ts --query "authentication"brainbox stats                 # includes stale-embedding counts + re-index commandsbrainbox error "TypeError: cannot read 'token'"brainbox predict Readbrainbox bootstrap --repo . --imports [--since <git-rev>]   # git history + tree-sitter code graphbrainbox extract-snippets [--force] [--no-embed]           # AST chunks → FTS5 + sqlite-vecbrainbox embed [--force]       # embed neurons with the active modelbrainbox models pull|status    # fetch / inspect the embedding modelbrainbox procedures [list|compile|show <id>|deprecate <id>]brainbox sleep                 # consolidation + procedure compilationbrainbox eval --source nebius|omp [...]                   # offline replay evaluationbrainbox hubs | stale | projects | sessions | streaks | graph | highways | decay

src/  hebbian.ts       # Engine: record, recall (rank fusion), STDP, n-gram tool prediction, decay, anti-recall  db.ts            # SQLite schema + migrations  policy.ts        # Recall event log + contextual UCB1 injection policy  adapter.ts       # Shared recall/injection orchestration for all hosts  snippets.ts      # AST chunking, FTS5 + sqlite-vec hybrid search  embeddings.ts    # Embedding model profiles, hook-safe loading  codegraph.ts     # Tree-sitter import/call/inherit graph  procedures.ts    # Procedural playbook mining + matching  bootstrap.ts     # Git history / code graph / session seeding  installer.ts     # Hooks + MCP registration, model prefetch  mcp.ts           # MCP server (8 tools)  hook.ts          # PostToolUse + SessionEnd hook  prompt-hook.ts   # UserPromptSubmit hook  kilo-plugin.ts   # Kilo/OpenCode native plugin  daemon.ts        # FSEvents file watcher (macOS, opt-in)  cli.ts           # CLI  eval/            # Offline trajectory replay evaluation  testkit.ts       # Test harness; test.ts + tests/*.test.tsscripts/visuals/   # JS generators for the README figures (tbcresearch.org ink style, light + dark)

Development

npm test                      # 147 testsnpx tsx src/test.ts "Ranking" # filter by suite/test namenpm run visuals               # regenerate assets/*.svg (light + dark) from scripts/visuals/scenes/*.mjsbash scripts/visuals/social.sh  # render assets/social-preview.png for GitHub's social preview

Requirements: Node.js 22+, on macOS or Linux. The FSEvents daemon is macOS-only; everything else is cross-platform.

If BrainBox saved your agent some searching, give it a ⭐ so others can find it.
Built by @thebasedcapital · MIT License