Hebbian memory for AI agents. Learns file patterns, predicts next tools, saves tokens.
io.github.thebasedcapital/brainbox — MCP Server
This MCP server provides “Hebbian memory for AI agents,” designed to learn file patterns, predict next tools, and save tokens. It is positioned as procedural memory and an alternative approach to retrieval augmented generation (RAG), using “zero-cost-memory” concepts.
🛠️ Key Features
Learns file patterns for agent context
Predicts next tools to use
Saves tokens during operation
🚀 Use Cases
Agent-memory workflows for AI agents
AI coding scenarios involving tool selection
RAG-alternative procedural-memory setups
⚡ Developer Benefits
Supports MCP-based agent integration
Uses topics spanning agent-memory, ai-agents, and ai-coding
Aligns with “hebbian-learning” and “neuromorphic” terminology
⚠️ Limitations
No additional operational details, capabilities, or tool interfaces were provided in the source data
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.
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:
Adds a PostToolUse hook to ~/.claude/settings.json. It learns from every file read, edit, search and command.
Adds a UserPromptSubmit hook. It injects compact recall into prompts, or stays silent once it has learned you ignore it.
Adds a SessionEnd hook. 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:
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 --splittest --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.
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: