Troubleshooting
Start with two commands: claude-db status shows whether it is wired up, and claude-db doctor shows what it resolved.
claude-db doctor
claude-db doctor --deep--deep writes one test memory, searches for it, reads it back and deletes it. Each step reports ok or FAIL, so you can see which half is broken.
Nothing is being captured
| Check | Fix |
|---|---|
| Did you restart Claude Code? | Hooks are read at startup, so a running session never sees them |
Was install run in this repo? | claude-db install --project from the repository root |
| Has any turn changed a file? | Questions and read-only commands are skipped by design |
Memory rarely shows up
- A fresh install has no history. Run the head start steps.
- Prompts of one or two words, or filler like "ok", get nothing.
- Run
claude-db pick. It says if picking is off, paused after a failed call, or past today's limit. - A turn with no tool calls never shows a pick.
A moved repository looks empty
A repository with a git remote keeps its memory wherever it is cloned. With no remote, bring it across:
claude-db merge /old/path/to/project --yesdoctor says reachable: no
For Postgres or MongoDB, install the driver, and check CLAUDE_DB_URL is not set to something old.
npm install -g pg
npm install -g mongodbfind_usages has no graph
Build the graph once with claude-db scan. Until then, text mode still works, because it is a live git grep.
Search got worse after adding the embedder
Re-embed the old rows at the new size:
claude-db reembedIf reembed runs low on memory, set { "embeddings": { "batchSize": 4 } } in the config. The default is 8.
Nothing here deletes memory
uninstall leaves your database alone. Only forget, prune and reset delete anything, and
the last two are dry runs without --yes.