Installation
Install the package once, then switch it on for a project.
Requirements
- Node 22.16 or newer (
node -v) - A git repository
- Claude Code, logged in
Nothing compiles at install time. SQLite comes from Node itself.
Install
npm install -g claude-dbEvery command also works as cdb.
Switch it on
Run install inside the project
cd your-project
claude-db install --project--project limits it to this repository. Run claude-db install without it to switch it on for every project on this machine. The folder you run it from does not matter in that case.
Restart Claude Code
Hooks and the MCP server load only when Claude Code starts. A session that is already open does not have them.
Add .mcp.json and CLAUDE.local.md to your .gitignore. They hold paths and rules that are personal to your machine.
What install adds
| Where | What it is |
|---|---|
.claude/settings.local.json | The hooks that capture and recall |
.mcp.json | The server that gives Claude the six MCP tools |
CLAUDE.local.md | A standing instruction to search memory before asking you |
.claude/skills/ | The skills: /cdb-scan, /catchup, /handoff |
A machine-wide install writes the same things under ~/.claude/ and ~/.claude.json instead. Memory is always one database for the whole machine, filed by project.
Check it works
claude-db doctor
claude-db statusdoctor should show wiring : ok and list the three skills. status fills in after your first real session. Nothing is saved for a chat that only asked questions, and that is normal.
For a full test, run claude-db doctor --deep. It writes one test memory, finds it, reads it back and deletes it.
Upgrade
npm install -g claude-dbRestart Claude Code. Your memory is kept.
Uninstall
claude-db uninstall --projectThis removes the hooks, the MCP entry, the instructions and the skills. Your memory is left on disk, so reinstalling picks up where you stopped. To delete the memory itself, see Privacy.