brainbox — Claude Code MCP server: agent memory
Remembers which files your agent reads and edits together, then surfaces them before a search starts. Saves the usual grep round on repeat tasks.
claude mcp add brainbox -- npx -y brainbox-hebbianWhat brainbox does
brainbox keeps a local SQLite graph where files, tools and errors are nodes and whatever the agent touches in sequence becomes an edge. Ask for something and it walks outward from the files it already knows, a few hops at a time, then hands the agent a short list. Several ranking channels feed one result set, and each entry carries the connection that produced it, so you can look at the reasoning instead of trusting it.
Errors get their own path. A failing command, followed by edits and a clean rerun, leaves a fingerprint tied to the files that fixed it. Next time that fingerprint shows up, those files are recalled straight away. Routes you use often get stronger; stale ones fade.
Node 22 is the only requirement for the base mode. Until the embedding model is cached with brainbox models pull, recall runs on keywords alone — and if native modules refuse to build on your machine, the package still installs and stays in that mode. brainbox models status tells you which one is active. To skip the empty start, seed from git history: brainbox bootstrap --repo /path/to/project --imports. Installing npm install brainbox-hebbian writes the hooks and registers the server for you.
What it helps with
- surface the right files before the agent starts grepping
- link an error fingerprint to the edits that once fixed it
- keep the project memory on your own disk, no outside API
- seed connections from git history instead of waiting for sessions
- inspect why a particular file was recalled
Example prompts for the agent
- Show what brainbox remembers about
auth.tsand explain why it came up - I hit
TypeError: cannot read property— pull the files that fixed it last time - Seed the memory from the history of
/path/to/project, imports included
How to install brainbox
Platform CLI
claude mcp add brainbox -- npx -y brainbox-hebbianPlatform CLI
codex mcp add brainbox -- npx -y brainbox-hebbianConfig file
{
"mcpServers": {
"brainbox": {
"command": "npx",
"args": [
"-y",
"brainbox-hebbian"
]
}
}
}Config file
{
"servers": {
"brainbox": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"brainbox-hebbian"
]
}
}
}Platform CLI
gemini mcp add brainbox npx -y brainbox-hebbianStep by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about brainbox
How do I install brainbox in Claude Code?
Run claude mcp add brainbox -- npx -y brainbox-hebbian. The package writes its hooks into ~/.claude/settings.json during install.
What does brainbox do?
It records which files, tools and errors the agent touches close in time, then puts related files in front of it on the next task. The graph lives in a local SQLite database.
What happens if the embedding model is not downloaded?
Recall falls back to keyword search. The server installs and runs in that mode, and brainbox models status reports which mode you are in.
