claude-db

Persistent memory for Claude Code. Bring your own database.

Documentation · Quick start · CLI reference

---

Every session starts from zero

You spent an hour yesterday explaining why the store uses three adapters, which approach you already tried and abandoned, and why that one function must not be touched. Today Claude knows none of it. So you explain it again.

claude-db fixes that, and the other half too. Claude re-derives your codebase every time, grepping a name and opening files to work out what calls what.

$ claude-db search "why does capture read the transcript"

83cf1246-eb14  decision  2026-08-19  Tested and written up.
    …the old defaults prompt was now cut why does capture read the transcript…
88fab24f-5e59  decision  2026-08-19  Finding 4's other half needs checking…
    …cannot work: 0.029483 "why does capture read…" <- highly relevant…

You never run that command. Claude gets the same context injected on every prompt, so it walks in already knowing. Nothing leaves your machine.

Install

npm install -g claude-db

cd your-project
claude-db install --project

Restart Claude Code. That's it: capture and recall are hooks, so they run without being asked.

--project scopes to one repo instead of every project on the machine. It writes .claude/settings.local.json and .mcp.json. Add .mcp.json to your .gitignore, since it holds a machine-specific path.

Map your code

Memory fills itself as you work. The code graph needs one command:

claude-db scan

Claude then gets four modes through MCP: text (a live grep, works with no scan at all), usages, explain and path. Re-running scan is cheap: it hashes files and re-parses only what changed.

TypeScript, TSX, JavaScript, Python, Go, Rust and Ruby are parsed properly, and every other language — Java, C, C++, C#, Swift, Kotlin, PHP, Elixir, shell and twenty more — is read by pattern, which finds declarations and name-matched references tagged INFERRED. Nothing else to install either way.

Use another database

SQLite by default, at ~/.claude-memory/memory.db. No setup, no network. Point it elsewhere to share memory across machines:

claude-db use "mongodb+srv://user:pass@cluster.mongodb.net/memory"
claude-db use "postgres://user:pass@host:5432/memory"

Install the driver you need (npm install mongodb or pg); neither ships by default.

With it, and without it

Asking who defines and calls closeObservations by hand means a grep, then opening three store adapters to see which hits are definitions. One explain call answers it already classified: 2.1x cheaper, measured across eight real symbols in this repo.

Recall is the standing cost of ~180 tokens a prompt, skipped entirely on 28% of prompts because the answer is already in context:

  every prompt costs      180 tokens of recall
  every lookup refunds    597 tokens   (1,115 by hand - 518 with)

  so one lookup pays for 3.3 prompts of recall

Check it on your own repo with npm run bench:ab and npm run bench:tokens from a clone. With and without has every number, including the symbols where plain grep wins.

Commands

cdb is a shorter alias for all of them. These are the ones you actually type:

Command	What it does
claude-db install [--project]	Register hooks and the MCP server
claude-db status	Is it wired up, and when did it last record anything
claude-db doctor [--deep]	Resolved config; --deep proves a full round trip
claude-db scan [--force]	Build the code graph for this repo
claude-db usages [--mode <m>] <symbol>	What uses a symbol: live git grep, or the code graph
claude-db use <url>	Switch database and verify it
claude-db view	See this project's memory live in the browser

Every other command, including search, remember, seed, sync, export, prune and reset, is in the CLI reference.

Install also adds a /cdb-scan skill: run it once on an existing project and Claude maps the codebase into memory, so search has something to find before you have any history.

Requirements

Node 22.5 or newer. That's the only hard requirement: SQLite comes from Node's builtin node:sqlite, so nothing compiles at install time.

Embeddings run locally with a zero-dependency embedder. For real semantic search, npm install @xenova/transformers and it upgrades itself.

Privacy

Nothing leaves your machine unless you point it at a remote database. .env, secrets/, node_modules and .git/ are never stored, text wrapped in ...</private> is stripped, and API keys and tokens are redacted before anything is written.

Documentation

claude-db.vercel.app/docs has the rest: the CLI reference, MCP tools, how it works, databases and troubleshooting.

Benchmarks has every number, including the symbols where plain grep wins. Releases are in the changelog.

Development

npm install
npm run build
npm test      # 415 checks
npm run lint  # house rules: no comments, no any, import extensions
npm run try