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.

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