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
[](https://doi.org/10.5281/zenodo.18664906)
**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](https://doi.org/10.5281/zenodo.23250505).
```bibtex
@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
```bash
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:
```bash
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.
| Probe | SWE test: v0.1 | v0.2 | best baseline | local: v0.1 | v0.2 | best baseline |
|---|---:|---:|---:|---:|---:|---:|
| P1 edited files | .307 | **.307** | .216 BM25 | .737 | .703 | **.791 frequency** |
| P1 read files | .191 | **.267** | .206 BM25 | .372 | **.555** | .547 BM25 |
| P2 next file | .223 | .409 | **.430 recency** (Δ CI −.049…+.003) | .634 | **.702** | .701 recency (tie) |
| P3 next tool | .479 | **.767** | .748 frequency (Δ +.019, CI +.012…+.027) | .257 | **.686** | .662 recency (Δ CI +.010…+.036) |
```bash
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:
| Subsystem | What changed | Source |
|---|---|---|
| Ranking | ACT-R base-level activation replaces fixed decay. Recurrence and popularity candidates are added. Weighted reciprocal-rank fusion with weights fit on held-out dev repos. Directional STDP; n-gram tool prediction. | [ACT-R 2505.05083](https://arxiv.org/abs/2505.05083) · [Base3 2506.12764](https://arxiv.org/abs/2506.12764) · [2502.04910](https://arxiv.org/abs/2502.04910) |
| Code search | cAST-style AST chunks. FTS5 BM25 + `sqlite-vec` KNN, fused with RRF (k=60). Incremental by content hash. | [cAST 2506.15655](https://arxiv.org/abs/2506.15655) |
| Injection policy | A contextual UCB1 bandit picks SILENT / TOP1 / TOP3 / TOP5. Reward = files you open or edit, minus token cost. | [MemCon 2607.13591](https://arxiv.org/abs/2607.13591) |
| Attribution | Every recall is logged with the synapse that produced it; ignored recalls weaken only that edge. | [MemTrace 2605.28732](https://arxiv.org/abs/2605.28732) |
| Compact injection | Injects a compact `path:start-end — why` list; deleted files are never injected. | [FastContext 2606.14066](https://arxiv.org/abs/2606.14066) |
| Procedures | Deterministic mining of failed command → edits → passing rerun, plus multi-session workflows, with helpful/harmful counters. | [ACE 2510.04618](https://arxiv.org/abs/2510.04618) · [Mem^p 2508.06433](https://arxiv.org/abs/2508.06433) |
| Code graph | Tree-sitter import / call / inheritance edges (TS/JS, Python, Rust, Swift, Go), seeded as weak priors (≤ 0.35) that learned co-access outranks. | — |
| Evaluation | Offline replay of SWE-rebench OpenHands trajectories and local sessions, with baselines and paired CIs. | [SWE-rebench trajectories](https://huggingface.co/datasets/nebius/SWE-rebench-openhands-trajectories) |
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)
```bash
# 8 tools: record, recall (detail: compact|full), explain, error, resolve, predict_next, stats, decay
npx tsx node_modules/brainbox-hebbian/src/mcp.ts
```
### Kilo / OpenCode (native plugin)
Add to `~/.config/kilo/config.json`:
```json
{
"plugin": ["node_modules/brainbox-hebbian/src/kilo-plugin.ts"]
}
```
### OpenClaw (NeuroVault)
BrainBox can run as an OpenClaw memory slot plugin. See [NeuroVault](https://github.com/thebasedcapital/neurovault) for the reference implementation.
| Aspect | Claude Code | OpenClaw |
|---|---|---|
| Tool names | PascalCase (`Read`) | Lowercase (`read`) |
| Context injection | `UserPromptSubmit` hook | `before_agent_start` lifecycle |
| Learning trigger | `PostToolUse` hook | `after_tool_call` lifecycle |
| Embeddings | jina-embeddings-v2-base-code (configurable) | Keyword-only (lower confidence gate) |
### 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:
```bash
brainbox daemon install # installs LaunchAgent, starts watching
brainbox daemon status
brainbox daemon uninstall
```
## CLI
```bash
brainbox recall "authentication login"
brainbox record src/auth.ts --query "authentication"
brainbox stats # includes stale-embedding counts + re-index commands
brainbox error "TypeError: cannot read 'token'"
brainbox predict Read
brainbox bootstrap --repo . --imports [--since ] # git history + tree-sitter code graph
brainbox extract-snippets [--force] [--no-embed] # AST chunks → FTS5 + sqlite-vec
brainbox embed [--force] # embed neurons with the active model
brainbox models pull|status # fetch / inspect the embedding model
brainbox procedures [list|compile|show |deprecate ]
brainbox sleep # consolidation + procedure compilation
brainbox eval --source nebius|omp [...] # offline replay evaluation
brainbox hubs | stale | projects | sessions | streaks | graph | highways | decay
```
Configuration
| Variable | Purpose | Default |
|---|---|---|
| `BRAINBOX_DB` | SQLite path | `~/.brainbox/brainbox.db` |
| `BRAINBOX_DB_TIMEOUT_MS` | SQLite busy timeout | `5000` (hooks use `100`) |
| `BRAINBOX_EMBED_MODEL` | `minilm` \| `jina-code` \| `gemma` \| `gemma-q4` | `jina-code` |
| `BRAINBOX_MODEL_CACHE` | Model cache directory | Transformers.js default |
| `BRAINBOX_EMBEDDINGS` | `off` disables embeddings entirely | on |
| `BRAINBOX_POLICY` | `off` disables the learned injection policy (always TOP5) | on |
| `BRAINBOX_SESSION_ID` | Override session id for CLI/adapters | derived |
| `BRAINBOX_HOOK` | Set by hook entrypoints: local-only models, 1.2 s embedding deadline | unset |
Gemma profiles are subject to the [Gemma Terms of Use](https://ai.google.dev/gemma/terms).
Algorithm details
| Component | Mechanism (defaults in `DEFAULT_ENGINE_OPTIONS`) |
|-----------|-----------|
| Synapse formation | Sequential window (25 items), positional decay; directional STDP (later→earlier edge × 0.5) |
| Strengthening | SNAP sigmoid plasticity (midpoint 0.5, steepness 8); BCM myelination, 0.95 ceiling |
| Recency / frequency | ACT-R base level `B = ln Σ (Δt_h)^-0.5` over the last 50 accesses |
| File ranking | Weighted reciprocal-rank fusion. Channel weights: lexical (FTS5, scaled by verbatim query-term coverage) 4, Hebbian evidence 4, code snippets 4, frequency 2, recency 1, base level 0.5, recurrence 0.2. Session recency gets weight 30 when the query matches the current session. |
| Spreading | 3-hop BFS, fan-out cap 10, fan effect 1/sqrt(degree) |
| Tool prediction | Longest-suffix n-grams (n ≤ 3, min support 4) fused with frequency (0.5) |
| Code search | AST chunks; FTS5 BM25 + sqlite-vec KNN, RRF k=60 |
| Structural priors | import 0.2, call ≤ 0.35, inherit 0.3; never override learned co-access |
| Injection policy | UCB1 over SILENT/TOP1/TOP3/TOP5; reward = rank-weighted opens/edits − 2 per 1k tokens |
| Anti-recall | Ignored recalls weaken only the producing edge; `1 - (1 - 0.1)^streak`, floor 0.1 |
| Error learning | 2x boosted learning rate; error→fix procedures from failed→edited→passing reruns |
The [paper's source](./WHITEPAPER.md) (v0.2, [doi:10.5281/zenodo.23250505](https://doi.org/10.5281/zenodo.23250505)) describes the implementation and coverage-conditioned replay results, including uncertainty and provenance limitations. See [paper build and evidence notes](./paper/README.md) for the bibliography, aggregate evidence, LaTeX and PDF build.
Architecture
```
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.ts
scripts/visuals/ # JS generators for the README figures (tbcresearch.org ink style, light + dark)
```
## Development
```bash
npm test # 147 tests
npx tsx src/test.ts "Ranking" # filter by suite/test name
npm run visuals # regenerate assets/*.svg (light + dark) from scripts/visuals/scenes/*.mjs
bash 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
