Summary
BrainBox implements Hebbian learning for Claude Code and other MCP clients, treating files and tools as neurons that form synapses when accessed together. It hooks PostToolUse to passively learn patterns, then injects predicted files into UserPromptSubmit prompts automatically. Six MCP tools expose manual operations: record, recall, error (for error-fix associations), predict_next, stats, and decay. The engine uses SNAP plasticity to prevent connection dominance and BCM sliding thresholds for myelination. An optional macOS daemon watches file changes across all editors via FSEvents. Bootstrap from git history to seed the network with commit co-changes instead of starting cold. Useful when your agent repeatedly searches for the same file clusters or you want token savings from skipping grep operations.
Keeps your Mac awake while Claude Code, Codex or Cursor works. Lets it sleep when they are done.
Try free for 7 days →
Block distracting apps from your iPhone permanently without a 3rd party app. Free and open source.
Block now (100% free) →
Notes, actions and memory. Without a meeting bot. First month 100% off.
Download for free →
belt cli automatically finds the best tools and skills for your agent. image, video, music, tts...
one prompt install →
Free an open-source skills that make AI coding agents easier to understand, verify, and control.
Download for free →
Connect your Claude agent to live crypto prices and trading routes via 1inch
Get the MCP →
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:
- Adds a
PostToolUsehook to~/.claude/settings.json. It learns from every file read, edit, search and command. - Adds a
UserPromptSubmithook. It injects compact recall into prompts, or stays silent once it has learned you ignore it. - Adds a
SessionEndhook. It scores which recalled files you actually opened or edited and compiles procedures. - Registers the MCP server via
claude mcp add, with 8 tools:record,recall,explain,error,resolve,predict_next,stats,decay. - 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.
| 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) |
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 · Base3 2506.12764 · 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 |
| Injection policy | A contextual UCB1 bandit picks SILENT / TOP1 / TOP3 / TOP5. Reward = files you open or edit, minus token cost. | MemCon 2607.13591 |
| Attribution | Every recall is logged with the synapse that produced it; ignored recalls weaken only that edge. | MemTrace 2605.28732 |
| Compact injection | Injects a compact path:start-end — why list; deleted files are never injected. | FastContext 2606.14066 |
| Procedures | Deterministic mining of failed command → edits → passing rerun, plus multi-session workflows, with helpful/harmful counters. | ACE 2510.04618 · Mem^p 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 |
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, decay
npx 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.
| 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:
brainbox daemon install # installs LaunchAgent, starts watching
brainbox daemon status
brainbox daemon uninstall
CLI
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-rev>] # 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 <id>|deprecate <id>]
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.
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 (v0.2, doi:10.5281/zenodo.23250505) describes the implementation and coverage-conditioned replay results, including uncertainty and provenance limitations. See paper build and evidence notes 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
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
Featured
Keeps your Mac awake while Claude Code, Codex or Cursor works. Lets it sleep when they are done.
Try free for 7 days →Block distracting apps from your iPhone permanently without a 3rd party app. Free and open source.
Block now (100% free) →Notes, actions and memory. Without a meeting bot. First month 100% off.
Download for free →belt cli automatically finds the best tools and skills for your agent. image, video, music, tts...
one prompt install →Free an open-source skills that make AI coding agents easier to understand, verify, and control.
Download for free →Connect your Claude agent to live crypto prices and trading routes via 1inch
Get the MCP →Categories
Registryactive
Packagebrainbox-hebbian
TransportSTDIO
UpdatedFeb 22, 2026
