braindump

Persistent memory for AI coding agents, served over MCP.

Agents forget what they learned about a codebase when a session ends. braindump gives them a place to write it down — free-form notes, the code symbols they've looked at, and typed links between the two — in a local graph database that survives across sessions, repos and agents. Nothing is pre-indexed: the graph grows as agents work.

Features

• Graph memory — Notes (learnings, gotchas, decisions, …), code Entitys (function/class/module, …) and free-form typed Links between any two nodes (CALLS, documents, caused-by, …), stored in an embedded Ladybug graph DB.

• Hybrid search — BM25 (camelCase-aware) + substring + local semantic embeddings (bge-small-en-v1.5), fused with reciprocal rank fusion and re-ranked by a cross-encoder (mxbai-rerank-xsmall-v1). Runs fully offline on CPU; falls back to keyword search if the models are unavailable.

• Staleness checks — every entity is tagged with the git commit it was described at; check_stale flags descriptions whose file has changed or been deleted since.

• Graph traversal — walk 1–3 hops from any node to answer "what calls X" or "what documents X".

• Safe under concurrency — per-project write queue, lock-wait retries across processes, and all-or-nothing multi-statement writes and imports.

• Export / import — the whole graph as JSON for backup or transfer.

Related MCP server: hive-memory

Install

Developed on Node.js 22.

git clone https://github.com/mmkumar5401/braindump-mcp.git
cd braindump-mcp
npm install
npm link        # puts `braindump` on your PATH

The embedding and re-ranking models (~80 MB) download on first search and are cached in ~/.agents/braindump/.models.

Use with an MCP client

Register the stdio server, e.g. in Claude Code:

claude mcp add braindump -- braindump mcp

Or in any client's JSON config:

{
  "mcpServers": {
    "braindump": { "command": "braindump", "args": ["mcp"] }
  }
}

The project is auto-detected from the working directory (the git repo root's folder name); every tool also accepts an explicit project.

Tools

CLI

Every MCP tool has a CLI equivalent:

braindump add "Ladybug rejects CONTAINS with an empty string" --kind gotcha --tags ladybug,search
braindump entity add --name openBraindump --file src/db.js --kind function \
  --description "Opens the per-project graph DB, waiting on another process's lock"
braindump search "database lock"
braindump neighbors "src/db.js::openBraindump" --depth 2
braindump stale
braindump export

Run braindump --help or braindump <command> --help for all options.

Storage

One database per project at ~/.agents/braindump/<project>/graph.lbdb. Set BRAINDUMP_MODELS=off to skip the models entirely (keyword search only).

Development

npm test                          # vitest
BRAINDUMP_MODELS=off npm test     # skip model downloads

License

MIT