Installation

One global package, then one command inside the repo you want it to remember. Capture and recall are hooks, so there is nothing to run afterwards.

Install

npm install -g claude-db

bash

Every command is also available as cdb, which is the same binary under a shorter name.

Wire it to a repo

Run install inside the project

cd your-project
claude-db install --project

bash

--project scopes everything to this one repo. Without it, the install is machine-wide and applies to every project you open.

Restart Claude Code

Hooks are read at startup, so a running session will not pick them up.

Ignore the machine-specific file

echo '.mcp.json' >> .gitignore

bash

.mcp.json holds an absolute path to the installed package, so it should not be committed.

What install writes

Path	What it is
`.claude/settings.local.json`	Registers the SessionStart, UserPromptSubmit and Stop hooks
`.mcp.json`	Registers the server exposing the six MCP tools
`CLAUDE.local.md`	A standing instruction to search memory before re-explaining
`~/.claude/skills/cdb-scan`	The skill that maps an existing codebase in one pass

A machine-wide install writes that instruction into ~/.claude/CLAUDE.md instead.

Why a memory file as well as hooks

Hook output is context the agent may or may not act on. A memory file is a rule for the whole session, which is what makes recall the default rather than something you have to ask for.

Verify

claude-db status        # wired up? when did it last record anything?
claude-db doctor        # resolved config, database, embedder
claude-db doctor --deep # proves a full write-read-search round trip

bash

Uninstall

claude-db uninstall --project

bash

This removes the hooks, the MCP entry and the instruction block. Your memory is left untouched on disk, so reinstalling picks up exactly where you left off. To delete the memory itself, see Privacy.

Edit this page on GitHub

PreviousIntroduction NextQuick start