# brainbox

Remembers which files your agent reads and edits together, then surfaces them before a search starts. Saves the usual grep round on repeat tasks.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 14
- Author: thebasedcapital
- License: MIT · policy=link-only · description only; the file stays with the author
- Source: https://github.com/thebasedcapital/brainbox
- Updated: 2026-10-09
- HTML: https://affpapa.org/en/nevibecode/mcp/brainbox

## What it 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.

## Requirements
- Needs: Node.js (commands run via npx)

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
claude mcp add brainbox -- npx -y brainbox-hebbian
```

### Codex

**Platform CLI**
```bash
codex mcp add brainbox -- npx -y brainbox-hebbian
```

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "brainbox": {
            "command": "npx",
            "args": [
                "-y",
                "brainbox-hebbian"
            ]
        }
    }
}
```

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "brainbox": {
            "type": "stdio",
            "command": "npx",
            "args": [
                "-y",
                "brainbox-hebbian"
            ]
        }
    }
}
```

### Gemini CLI

**Platform CLI**
```bash
gemini mcp add brainbox npx -y brainbox-hebbian
```

## When to use it
- 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
- Show what brainbox remembers about `auth.ts` and 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

## Similar
- [REA](https://affpapa.org/en/nevibecode/mcp/rea.md) — MCP server · ★ 386989
- [GitHub](https://affpapa.org/en/nevibecode/mcp/github.md) — MCP server · ★ 33918
- [Netdata](https://affpapa.org/en/nevibecode/mcp/netdata.md) — MCP server · ★ 81115
- [browser-use](https://affpapa.org/en/nevibecode/mcp/browser-use.md) — MCP server · ★ 119160
- [Codebase Memory](https://affpapa.org/en/nevibecode/mcp/codebase-memory.md) — MCP server · ★ 47392
- [mcp-server](https://affpapa.org/en/nevibecode/mcp/mcp-server.md) — MCP server · ★ 43872

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md