Brainbox MCP server

BrainBox

Hebbian memory for AI coding agents. Learns which files you access together, which errors lead to which fixes, and which tool chains you use most — then recalls them instantly.

Not a vector database. Not RAG. Procedural memory.

If BrainBox saved you tokens, give it a star — it helps others find it.

Built by @thebasedcapital

Session 1:  agent greps for auth.ts, reads it, edits it (2000 tokens)
Session 5:  agent recalls auth.ts directly, skips search (500 tokens saved)
Session 20: auth.ts is a superhighway — instant recall, zero search cost

Install

npm install brainbox-hebbian

That's it. The postinstall script automatically:

1. Adds PostToolUse hook to ~/.claude/settings.json (learns from every file read/edit/search)
2. Adds UserPromptSubmit hook (injects neural recall into prompts automatically)
3. Registers the MCP server via claude mcp add (6 tools for manual recall/recording)
4. Creates ~/.brainbox/ database directory

BrainBox learns passively from your next Claude Code session. No configuration needed.

What does NOT happen automatically

The macOS daemon (system-wide FSEvents file watcher) is completely separate and opt-in:

# Only if you want BrainBox to learn from VS Code, Xcode, vim, shell, etc.
brainbox daemon install   # installs LaunchAgent, starts watching
brainbox daemon status    # check if running
brainbox daemon uninstall # remove completely

The daemon watches file changes across all your editors — not just Claude Code. It requires explicit opt-in because it registers a LaunchAgent and monitors your configured project directories.

Uninstall

brainbox uninstall  # removes hooks + MCP server, preserves database

Seed from git history (recommended)

Kill cold start by bootstrapping from your existing git history:

brainbox bootstrap --repo /path/to/project --imports

This seeds the neural network from git commit co-changes and import graphs so BrainBox starts with knowledge instead of from zero.

How It Works

BrainBox implements neuroscience-inspired learning:

• Neurons — files, tools, and errors you interact with
• Synapses — connections formed when things are accessed together ("neurons that fire together wire together")
• Myelination — frequently-used paths get faster (like muscle memory)
• Spreading activation — recalling one file activates related files
• Decay — unused connections weaken naturally, keeping the network clean

Hebbian Learning in Action (click to play)

https://github.com/thebasedcapital/brainbox/raw/main/assets/brainbox-animation.mp4

Spreading Activation — recalling one file activates related files through synaptic connections

https://github.com/thebasedcapital/brainbox/raw/main/assets/brainbox-spreading.mp4

Superhighway Formation — frequently-used pathways become instant-recall superhighways

https://github.com/thebasedcapital/brainbox/raw/main/assets/brainbox-superhighway.mp4

Error-Fix Immune System — remembers which files fixed which errors

Shortened. The full README is on GitHub.