How it works
Claude Code writes every session to disk as JSONL. claude-db reads that transcript, so it can record why you did something and not only which files changed.
Capture
Save the previous turn
- read new lines from the session transcript
- keep turns that changed something
- store title + reasoning + files, with an embedding
Search memory using your prompt
- inject the best match above your message
Both steps are hooks, so they always run. Nothing depends on Claude deciding to look something up.
One observation is saved per turn, and only if the turn edited a file or ran a real command. Questions, grep and "ok" are skipped. A busy day produces 10 to 20 rows, not hundreds.
The six kinds
Each observation is classified as it is captured, and search can filter on the kind. The first rule that matches wins.
| Kind | Matched when the turn |
|---|---|
preference | states a standing rule: "from now on", "prefer", "always use", "never run" |
decision | weighs options: "instead of", "rather than", "chose", "decided", "trade-off" |
deadend | records a failure: "didn't work", "reverted", "abandoned", "gave up" |
bugfix | mentions a fix, bug, regression, error or crash |
pattern | changed files without matching any of the above |
context | changed no files |
What gets injected
- Recent session summaries and facts at the start of a chat.
- Above a prompt, at most two memories from earlier chats, picked by Claude Haiku.
- After
/compact, what this chat decided and left uncommitted.
How a prompt gets its memory:
- Search finds the ten closest memories from other chats. If none shares two content words with the prompt, nothing happens and Haiku is not called.
- Haiku reads them with the prompt and the end of Claude's last reply, and picks only memories that hold something specific for this task. Most prompts get none.
- Each pick carries one sentence copied from the memory. The code checks the sentence is really there.
- The pick runs in the background and reaches Claude with its first tool call. A turn with no tools does not get one.
Limits: 150 picks a day, and a failed call pauses picking for an hour, then six hours, then a day. Without Haiku, only a strong word match is shown. claude-db pick off turns it off, and claude-db pick shows today's count.
Facts
When a chat ends, one small Haiku call reads its saved rows and writes short facts: a rule, a decision with its reason, a dead end, a to do or a lasting fact. Each has a stable key, so a later chat updates or retires it. The raw rows stay as the evidence.
Facts open each chat in three short sections: about you, this project, and where you stopped. They are also what search finds. Only a rule about how you like to work follows you into every project. Everything else stays in its project.
- At most 30 calls a day, with the same pause on failure as picking.
claude-db distill offturns it off, andclaude-db distillshows what it has done.- Claude Code's own memory files are imported as facts too, at no cost.
Unfinished work
A captured turn is stored open and closes when every file it touched has been committed. Closing is one-way, so a finished task never comes back because a nearby line changed.
Staying current
Hooks are registered by absolute path into the installed package, so they always run the current code. At session start, claude-db refreshes any skill copies that differ from what shipped. Running npm install -g claude-db is enough, then restart Claude Code once.