claude-db 0.9.1 → 0.10.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (161) hide show
  1. package/CHANGELOG.md +248 -0
  2. package/README.md +74 -113
  3. package/dist/capture/flush.d.ts +1 -0
  4. package/dist/capture/flush.js +4 -3
  5. package/dist/capture/git.js +2 -1
  6. package/dist/capture/index.d.ts +5 -1
  7. package/dist/capture/index.js +4 -1
  8. package/dist/capture/manual.js +1 -1
  9. package/dist/capture/progress.js +1 -0
  10. package/dist/capture/redact.d.ts +1 -0
  11. package/dist/capture/redact.js +17 -0
  12. package/dist/capture/reingest.d.ts +19 -0
  13. package/dist/capture/reingest.js +56 -0
  14. package/dist/capture/scrub.d.ts +11 -0
  15. package/dist/capture/scrub.js +48 -0
  16. package/dist/capture/summarize.js +3 -9
  17. package/dist/capture/transcript.d.ts +1 -0
  18. package/dist/capture/transcript.js +12 -3
  19. package/dist/capture/turn-extractor.d.ts +0 -1
  20. package/dist/capture/turn-extractor.js +10 -19
  21. package/dist/cli/commands/adoption.js +3 -3
  22. package/dist/cli/commands/distill.d.ts +1 -0
  23. package/dist/cli/commands/distill.js +67 -0
  24. package/dist/cli/commands/doctor.js +11 -3
  25. package/dist/cli/commands/insight.js +13 -4
  26. package/dist/cli/commands/maintain.d.ts +2 -1
  27. package/dist/cli/commands/maintain.js +53 -17
  28. package/dist/cli/commands/pick.d.ts +3 -0
  29. package/dist/cli/commands/pick.js +25 -0
  30. package/dist/cli/commands/setup.js +11 -2
  31. package/dist/cli/commands/sync.js +73 -12
  32. package/dist/cli/commands/transfer.d.ts +0 -5
  33. package/dist/cli/commands/transfer.js +1 -24
  34. package/dist/cli/commands/use.js +1 -1
  35. package/dist/cli/commands/view.js +30 -28
  36. package/dist/cli/index.js +13 -2
  37. package/dist/cli/install.d.ts +2 -0
  38. package/dist/cli/install.js +44 -21
  39. package/dist/cli/instructions.js +4 -2
  40. package/dist/cli/refresh.js +5 -1
  41. package/dist/cli/usage.js +4 -0
  42. package/dist/config/dir.d.ts +1 -0
  43. package/dist/config/dir.js +3 -0
  44. package/dist/config/index.d.ts +1 -1
  45. package/dist/config/index.js +1 -1
  46. package/dist/config/load.d.ts +4 -1
  47. package/dist/config/load.js +30 -13
  48. package/dist/config/schema.d.ts +19 -0
  49. package/dist/config/schema.js +17 -2
  50. package/dist/embed/index.d.ts +1 -1
  51. package/dist/embed/index.js +1 -1
  52. package/dist/embed/local.js +2 -1
  53. package/dist/facts/budget.d.ts +4 -0
  54. package/dist/facts/budget.js +12 -0
  55. package/dist/facts/claude-memory.d.ts +19 -0
  56. package/dist/facts/claude-memory.js +100 -0
  57. package/dist/facts/distill.d.ts +25 -0
  58. package/dist/facts/distill.js +141 -0
  59. package/dist/facts/model.d.ts +28 -0
  60. package/dist/facts/model.js +82 -0
  61. package/dist/facts/notice.d.ts +2 -0
  62. package/dist/facts/notice.js +22 -0
  63. package/dist/facts/ops.d.ts +23 -0
  64. package/dist/facts/ops.js +91 -0
  65. package/dist/facts/render.d.ts +4 -0
  66. package/dist/facts/render.js +13 -0
  67. package/dist/facts/start.d.ts +6 -0
  68. package/dist/facts/start.js +57 -0
  69. package/dist/graph/index.d.ts +2 -6
  70. package/dist/graph/index.js +2 -3
  71. package/dist/graph/languages/basic.js +1 -1
  72. package/dist/graph/languages/index.d.ts +1 -1
  73. package/dist/graph/parser.js +1 -1
  74. package/dist/graph/query/index.d.ts +0 -2
  75. package/dist/graph/query/index.js +0 -1
  76. package/dist/graph/scan/extract.js +1 -1
  77. package/dist/graph/scan/files.js +1 -1
  78. package/dist/graph/scan/index.d.ts +1 -2
  79. package/dist/graph/scan/index.js +1 -1
  80. package/dist/hooks/background.d.ts +3 -0
  81. package/dist/hooks/background.js +43 -0
  82. package/dist/hooks/compact.d.ts +8 -0
  83. package/dist/hooks/compact.js +42 -0
  84. package/dist/hooks/payload.d.ts +3 -0
  85. package/dist/hooks/payload.js +18 -1
  86. package/dist/hooks/pick-deliver.d.ts +2 -0
  87. package/dist/hooks/pick-deliver.js +16 -0
  88. package/dist/hooks/prompt-recall.d.ts +21 -0
  89. package/dist/hooks/prompt-recall.js +36 -0
  90. package/dist/hooks/relevance.d.ts +11 -3
  91. package/dist/hooks/relevance.js +56 -26
  92. package/dist/hooks/session-end.js +7 -1
  93. package/dist/hooks/session-start.js +31 -59
  94. package/dist/hooks/shown.d.ts +1 -0
  95. package/dist/hooks/shown.js +5 -2
  96. package/dist/hooks/start-legacy.d.ts +6 -0
  97. package/dist/hooks/start-legacy.js +47 -0
  98. package/dist/hooks/user-prompt.js +29 -25
  99. package/dist/mcp/server.js +13 -1
  100. package/dist/pick/pending.d.ts +17 -0
  101. package/dist/pick/pending.js +106 -0
  102. package/dist/pick/prompt.d.ts +14 -0
  103. package/dist/pick/prompt.js +80 -0
  104. package/dist/pick/run.d.ts +22 -0
  105. package/dist/pick/run.js +36 -0
  106. package/dist/pick/worker.d.ts +2 -0
  107. package/dist/pick/worker.js +32 -0
  108. package/dist/store/adapter.d.ts +1 -0
  109. package/dist/store/each.d.ts +5 -0
  110. package/dist/store/each.js +25 -0
  111. package/dist/store/mongo/docs.d.ts +2 -0
  112. package/dist/store/mongo/docs.js +4 -0
  113. package/dist/store/mongo/driver.js +3 -2
  114. package/dist/store/mongo/filters.d.ts +1 -0
  115. package/dist/store/mongo/filters.js +8 -0
  116. package/dist/store/mongo/index.d.ts +1 -0
  117. package/dist/store/mongo/index.js +5 -2
  118. package/dist/store/mongo/observations.d.ts +2 -1
  119. package/dist/store/mongo/observations.js +11 -1
  120. package/dist/store/mongo/search.js +12 -3
  121. package/dist/store/mongo/sessions.js +7 -1
  122. package/dist/store/mongo/vectorSearch.js +9 -11
  123. package/dist/store/postgres/driver.js +3 -2
  124. package/dist/store/postgres/filters.js +5 -0
  125. package/dist/store/postgres/index.d.ts +1 -0
  126. package/dist/store/postgres/index.js +3 -0
  127. package/dist/store/postgres/meta.js +2 -1
  128. package/dist/store/postgres/observations.d.ts +1 -0
  129. package/dist/store/postgres/observations.js +14 -3
  130. package/dist/store/postgres/rows.js +4 -0
  131. package/dist/store/postgres/schema.d.ts +2 -2
  132. package/dist/store/postgres/schema.js +4 -1
  133. package/dist/store/postgres/sessions.js +14 -7
  134. package/dist/store/session-time.d.ts +2 -0
  135. package/dist/store/session-time.js +5 -0
  136. package/dist/store/sqlite/filters.js +5 -0
  137. package/dist/store/sqlite/index.d.ts +1 -0
  138. package/dist/store/sqlite/index.js +27 -5
  139. package/dist/store/sqlite/observations.d.ts +1 -0
  140. package/dist/store/sqlite/observations.js +14 -1
  141. package/dist/store/sqlite/rows.js +4 -0
  142. package/dist/store/sqlite/schema.sql +3 -1
  143. package/dist/store/sqlite/search.js +7 -3
  144. package/dist/store/sqlite/sessions.js +13 -8
  145. package/dist/types.d.ts +5 -1
  146. package/dist/usages/find.js +5 -3
  147. package/dist/usages/index.d.ts +0 -1
  148. package/dist/util/claude-cli.d.ts +6 -0
  149. package/dist/util/claude-cli.js +38 -0
  150. package/dist/util/daily-budget.d.ts +7 -0
  151. package/dist/util/daily-budget.js +38 -0
  152. package/dist/util/day.d.ts +1 -0
  153. package/dist/util/day.js +11 -0
  154. package/dist/util/job-lock.d.ts +4 -0
  155. package/dist/util/job-lock.js +56 -0
  156. package/dist/util/prompt.d.ts +5 -0
  157. package/dist/util/prompt.js +31 -0
  158. package/docs/how-it-works.md +69 -3
  159. package/docs/setup-guide.md +339 -0
  160. package/docs/with-and-without.md +43 -36
  161. package/package.json +23 -7
package/CHANGELOG.md CHANGED
@@ -1,5 +1,253 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.10.1
4
+
5
+ ### Fixed
6
+
7
+ - **A second claude-db process no longer fails with `database is locked`.** The
8
+ SQLite database was opened with no wait time, so a hook that started while a
9
+ background job was writing (the clean-up or repair that runs after an update)
10
+ failed at once, and that session started without its memory block. The
11
+ connection now waits up to 3 seconds for the lock, which is under the 5 second
12
+ limit of the shortest hook. It showed up as one flaky macOS test after 0.10.0
13
+ was merged. SQLite only: Postgres and Mongo manage their own connections.
14
+
15
+ ## 0.10.0
16
+
17
+ ### Changed
18
+
19
+ - **Claude Haiku picks the memory shown with a prompt.** Search finds the ten
20
+ closest memories from other chats. If one shares two content words with the
21
+ prompt, Haiku reads them with the prompt and the end of Claude's previous
22
+ reply, and picks at most two, each with one sentence it must copy from the
23
+ memory; the code checks the sentence is there. The pick runs in the
24
+ background and reaches Claude with its first tool call, so typing is never
25
+ held up. Each line reads `- Oct 1: asked "<earlier question>": <copied
26
+ sentence> (id)`. Replaying the same 300 real prompts with old and new side by
27
+ side: 61% to 65% of shown memories judged useful on the final run of the
28
+ shipped code (70% on the labels the picks were studied with) against 23%, and
29
+ memory on 30% of prompts instead of 56%. Nothing from the current chat is
30
+ shown back to it.
31
+
32
+ - **At most 150 picks a day.** A failed call pauses picking for an hour.
33
+ Without Haiku (off, over the limit, or paused) only a strong word match is
34
+ shown: the closest memory, if it shares four content words with the prompt.
35
+ `claude-db pick [on|off]` turns it off or shows today's count, and `status`
36
+ reports it. Saved configs still on earlier defaults (`promptResults: 4`,
37
+ `minOverlap: 1`, or the 0.9 `promptResults: 3`) move to two memories; values
38
+ you changed are kept.
39
+
40
+ - **Prompts nobody typed get no memory.** Subagent reports, task
41
+ notifications, slash commands and local command output matched on noise,
42
+ useful once in eleven. Image paths are stripped before searching, since their
43
+ path words matched other image prompts and nothing else.
44
+
45
+ - **The recall cost is measured, not assumed.** `bench:ab` priced recall with
46
+ a fixed 180 tokens. It now replays real chats through the prompt hook
47
+ (`--recall-from <project>`) and runs this build rather than whatever
48
+ `claude-db` is on `PATH`, with Haiku picking as it ships (`--no-pick` for
49
+ words only). Measured on 300 prompts: ~20 tokens a prompt, with nothing
50
+ injected on 69% of them, so one lookup pays for 34 prompts of recall.
51
+
52
+ The old figures used the assumed 180 tokens a prompt. Recall now costs about
53
+ a ninth of that, and one lookup saves 685 tokens (1,338 by hand against 653
54
+ with it) instead of 597 (1,115 against 518):
55
+
56
+ | A session of | Recall cost, before | Recall cost, now | Lookups to break even, before | Lookups to break even, now |
57
+ | ------------ | ------------------: | ---------------: | ----------------------------: | -------------------------: |
58
+ | 1 prompt | 180 | 20 | 0.3 | 0.0 |
59
+ | 5 prompts | 900 | 101 | 1.5 | 0.1 |
60
+ | 10 prompts | 1,800 | 202 | 3.0 | 0.3 |
61
+ | 20 prompts | 3,600 | 405 | 6.0 | 0.6 |
62
+ | 60 prompts | 10,800 | 1,214 | 18.1 | 1.8 |
63
+
64
+ ### Added
65
+
66
+ - **Chats become facts.** When a chat ends, one Claude Haiku call reads its
67
+ saved rows and the facts already known, and writes back short rules,
68
+ decisions with their reasons, dead ends, to-dos and lasting facts. Each has a
69
+ stable key, so a later chat updates it in place, and Haiku retires a fact the
70
+ chat shows is no longer true. The start of a chat shows them as about you,
71
+ this project, and where you stopped (`- Decided (Oct 5): ...`), and `search`
72
+ finds them. Above a prompt, picks come from earlier chats: offered to Haiku,
73
+ facts were useful 60% of the time against 69% for chat rows. On by default,
74
+ through your own Claude
75
+ Code login, in the background: at most 30 calls a day, a day's pause after a
76
+ failed call, a long chat read in windows of about 40,000 characters, and
77
+ older chats from the last 90 days turned into facts newest first.
78
+ `claude-db distill [on|off]` turns it off or shows what it has done, and the
79
+ first session after updating says so once.
80
+
81
+ - **Only a rule follows you everywhere.** A rule about how you work is filed
82
+ under your git email and recalled in every project, and never reaches a
83
+ teammate on a shared database. Everything else stays in its project, whatever
84
+ scope the model asked for: on a real database it filed career details as
85
+ facts about the user.
86
+
87
+ - **Claude Code's own memory files are imported as facts,** at no AI cost, kept
88
+ current as the files change and retired when one is deleted. On the machine
89
+ where Claude already reads them they are not repeated.
90
+
91
+ - **A setup guide,** `docs/setup-guide.md`, ships with the package: requirements,
92
+ install, how to check it works, how to give a fresh install a head start, the
93
+ habits and settings that change results most, what each Haiku feature sends
94
+ and costs, teams, upkeep and troubleshooting.
95
+
96
+ - **Existing installs get the new tool-call hook on their own.** The session
97
+ start refresh that already kept the skill and instructions current now also
98
+ adds missing claude-db hooks, only in settings files that already point at
99
+ the same copy of claude-db. No reinstall is needed after updating.
100
+
101
+ - **`status` reports facts and how many chats are still waiting.**
102
+
103
+ - **`/compact` no longer loses the chat's own work.** The start hook sees
104
+ `source: compact`, saves the latest turns, and puts back what the chat decided
105
+ and left uncommitted under "Earlier in this chat". What the chat had been
106
+ shown before is forgotten, since compaction just dropped it.
107
+
108
+ - **MCP server instructions.** A short note on what `<memory>` lines are and
109
+ when to search, which Claude Code adds to the system prompt for global and
110
+ project installs alike.
111
+
112
+ - **`npm run bench:inject`** replays a project's prompts in time order through
113
+ the hook's own code and reports how many got memory, how much came from the
114
+ same chat, the cost per prompt, and with `--judge` how much was useful, as a
115
+ range over two Haiku passes.
116
+
117
+ ### Development
118
+
119
+ - **ESLint with type-aware rules, knip, c8, publint and arethetypeswrong.**
120
+ `npm run lint` runs the house rules and ESLint, `npm run knip` finds unused
121
+ code and packages, `npm run coverage` measures the suite, and
122
+ `npm run check:package` checks the packed tarball and its types. CI runs all
123
+ of them, and CodeQL scans every pull request. Fixing what they found removed
124
+ about a hundred unused imports, typed JSON that was `any`, and kept the cause
125
+ on rethrown errors.
126
+
127
+ - **Test fixtures cannot hold real secrets or personal paths, and the isolated
128
+ test scripts cannot touch your real home.** `npm run lint` now also runs
129
+ `check:fixtures`, which fails on token-like strings, known key prefixes and
130
+ personal home paths in tracked files. `npm run check:fixtures -- --local`
131
+ also compares docs and tests with your own saved memory and Claude Code
132
+ chats and lists any six-word run they share, so private text is caught
133
+ before a push. The scripts under `scripts/unit/isolated` now refuse to run
134
+ unless `runIsolated` started them in a temporary home: run by hand, they
135
+ used the real home and database.
136
+
137
+ - **The plan, the results and every finding from this work are in one document,**
138
+ `docs/memory-improvements.md`, dated 2026-10-06.
139
+
140
+ - **The MCP tools, the end-of-chat hook and the CLI are tested end to end,**
141
+ through the real server, hook and binary in a temporary home: install,
142
+ status, doctor, uninstall, remember, search, forget, export, import, reset,
143
+ prune, stats, projects, flush, view, pick and use.
144
+
145
+ - **`npm audit` is clean.** Five advisories in packages the MCP SDK pulls in
146
+ were patched within their existing ranges.
147
+
148
+ ### Fixed
149
+
150
+ - **The usefulness judge in `bench:inject` was close to chance.** It graded 20
151
+ items from different prompts per call and answered by position, so one slip
152
+ shifted every answer after it; its two passes agreed at kappa 0.14. It now
153
+ grades one prompt per call, labels every candidate by id without knowing
154
+ which were shown, sees the end of the previous reply, uses Sonnet by default,
155
+ and prints the agreement (kappa 0.80 on 2,521 pairs). Usefulness figures in
156
+ this release were re-measured with it.
157
+
158
+ - **Secrets written as `NAME=value` are redacted, including in memory already
159
+ saved.** Redaction caught a value after a name like `token` or `password`
160
+ only in quotes, so a pasted `GITHUB_TOKEN=...` or `DATABASE_PASSWORD=...` was
161
+ stored as typed. Unquoted values are now redacted too, when they have a
162
+ letter and are 8 or more characters, so `MAX_TOKENS=4096` is left alone. The
163
+ same redaction runs on memory text sent to Haiku and on every line shown with
164
+ a prompt. Memory saved earlier is cleaned once, in the background, on the
165
+ first session after updating, for each database; a cleaned chat summary is
166
+ marked newer so `sync` carries it. `claude-db redact` runs the same clean-up
167
+ on demand.
168
+
169
+ - **The real minimum is Node 22.16, and it is now enforced.** claude-db said
170
+ 22.5, and its install check let 22.5 through, but `node:sqlite` needs a flag
171
+ before 22.13 and has no full-text search (FTS5) before 22.16, so the default
172
+ database failed on every version below 22.16. Checked on real Node 22.5.1,
173
+ 22.12, 22.13, 22.15 and 22.16 binaries. The install check, `engines`, the docs
174
+ and CI now say 22.16, CI tests 22.16 itself, and an older Node now gets a
175
+ plain message instead of `no such module: fts5`.
176
+
177
+ - **`install --project` warns about `.mcp.json` when there is no `.gitignore`.**
178
+ It stayed quiet exactly when nothing kept the file out of a commit.
179
+
180
+ - **The driver install command is right for a global install.** The error and
181
+ four docs said `npm install pg` or `npm install mongodb`, which a globally
182
+ installed claude-db does not see. They now say `npm install -g pg` and
183
+ `npm install -g mongodb`, checked against a packed copy installed into a
184
+ throwaway prefix. The install page also named the wrong hooks and skill path.
185
+
186
+ - **`claude-db view` no longer crashes when loading fails.** It sent the
187
+ success header before loading the data, so a failure tried to send a second
188
+ header and the unhandled rejection stopped the viewer. It now builds the whole
189
+ response first.
190
+
191
+ - **A deleted source could still ship as compiled output.** The build never
192
+ cleared `dist/`, so a file removed from `src/` stayed in the package. The
193
+ build now removes compiled files whose source is gone.
194
+
195
+ - **Two store tests passed without testing anything.** `createStore` was never
196
+ imported, so the scheme routing checks caught their own `ReferenceError` and
197
+ passed. They now import it, and the unknown-scheme check requires the real
198
+ message.
199
+
200
+ - **`npm run lint` checks new files too,** not only files git already tracks.
201
+
202
+ - **`sync` now keeps the newer chat summary.** Chats record when their summary
203
+ was written, so a summary rebuilt on one side, or cleared on purpose, wins over
204
+ an older copy, and a chat already turned into facts is marked so on both
205
+ sides.
206
+
207
+ - **The privacy notes were out of date.** They said nothing leaves your machine
208
+ and that a configured database is the only network traffic; the daily update
209
+ check already contacted the npm registry. They now list every outside call and
210
+ how to turn each one off.
211
+
212
+ - **VS Code's notes about the open file no longer count as part of a prompt.**
213
+
214
+ - **A pasted image cost the user's own words.** Claude Code stores an image, a
215
+ skill's instructions and a subagent report as separate hidden messages after
216
+ the typed one, and capture started a new turn at each. The work was filed
217
+ under `Asked: [Image: source: ...]` and the request itself was dropped: 141 of
218
+ 551 rows in one real database. Hidden messages and task notifications no
219
+ longer start a turn, saved text has image paths removed and slash commands
220
+ read as `/name args`, and ids still come from the raw prompt so re-ingesting
221
+ updates rows in place.
222
+
223
+ - **Memory saved under the old rules is repaired once, in the background.** The
224
+ first session after updating runs `claude-db flush --repair`: every chat that
225
+ already has memory and whose transcript is still on disk is re-saved, and rows
226
+ it no longer produces are marked `replaced`. They stay in the database, and in
227
+ export and sync, but leave search, the timeline, `view` and `stats`. On the
228
+ database above: 140 rows replaced, 109 lost requests recovered, nothing else
229
+ touched. Chats Claude Code has already deleted keep their rows as they are.
230
+
231
+ - **`sync` carries status across.** It only copied rows the other side lacked,
232
+ so work closed or replaced on one machine stayed open on the other. Status now
233
+ moves forward on both sides, open to done to replaced, never back.
234
+
235
+ - **AI summaries never ran in VS Code,** which does not put `claude` on `PATH`.
236
+ Headless calls now use the running binary first. They also waited 3 seconds
237
+ for stdin on every call (8.5s down to 5.1s), and were saved as chats that
238
+ showed up in `/resume`; both are fixed, with a retry for older CLIs that do
239
+ not know `--no-session-persistence`.
240
+
241
+ - **`fatal: not a git repository` leaked from the hooks** in a folder that is
242
+ not a git repo.
243
+
244
+ - **Code blocks on the docs site showed a white scrollbar in dark mode.** The
245
+ page never told the browser its colour scheme, so wide code blocks, the home
246
+ demo and the command boxes drew the default light scrollbar over a dark
247
+ surface. The page now sets `color-scheme` for both themes, so the table and
248
+ sidebar scrollbars follow the theme too, and those three dark surfaces use a
249
+ thin scrollbar that matches them.
250
+
3
251
  ## 0.9.1
4
252
 
5
253
  ### Fixed
package/README.md CHANGED
@@ -14,24 +14,24 @@
14
14
 
15
15
  ## Every session starts from zero
16
16
 
17
- You spent an hour yesterday explaining why the store uses three adapters, which
18
- approach you already tried and abandoned, and why that one function must not be
19
- touched. Today Claude knows none of it. So you explain it again.
17
+ You spent an hour yesterday explaining why the store has three adapters, which
18
+ approach you tried and dropped, and why one function must not be touched. Today
19
+ Claude knows none of it, so you explain it again.
20
20
 
21
- claude-db fixes that, and the other half too. Claude re-derives your codebase
22
- every time, grepping a name and opening files to work out what calls what.
21
+ claude-db gives Claude a memory that lasts, and a map of your code so it stops
22
+ working out what calls what from scratch.
23
23
 
24
- ```console
25
- $ claude-db search "why does capture read the transcript"
24
+ ## What you get
26
25
 
27
- 83cf1246-eb14 decision 2026-08-19 Tested and written up.
28
- …the old defaults prompt was now cut why does capture read the transcript…
29
- 88fab24f-5e59 decision 2026-08-19 Finding 4's other half needs checking…
30
- …cannot work: 0.029483 "why does capture read…" <- highly relevant…
31
- ```
32
-
33
- You never run that command. Claude gets the same context injected on every
34
- prompt, so it walks in already knowing. Nothing leaves your machine.
26
+ - **A memory that carries over.** When a chat ends, its decisions, dead ends and
27
+ rules are saved as short facts, and the next chat starts by seeing them.
28
+ - **The right memory with each prompt.** Claude Haiku picks the one or two
29
+ earlier memories that fit what you just asked. That costs about 20 tokens a
30
+ prompt on average, and nothing on 69% of prompts.
31
+ - **A code graph.** Who defines or calls a symbol, answered in one call: 2.0x
32
+ cheaper than grep and reading files, measured on eight real symbols.
33
+ - **Your own database.** SQLite by default, or Postgres or MongoDB to share
34
+ memory across machines. No cloud, no subscription.
35
35
 
36
36
  ## Install
37
37
 
@@ -42,134 +42,95 @@ cd your-project
42
42
  claude-db install --project
43
43
  ```
44
44
 
45
- Restart Claude Code. That's it: capture and recall are hooks, so they run
46
- without being asked.
45
+ Restart Claude Code. Capture and recall are hooks, so there is nothing else to
46
+ run.
47
47
 
48
- `--project` scopes to one repo instead of every project on the machine. It
49
- writes `.claude/settings.local.json` and `.mcp.json`. Add `.mcp.json` to your
50
- `.gitignore`, since it holds a machine-specific path.
48
+ `--project` limits it to this repo instead of every project on the machine. Add
49
+ `.mcp.json` to your `.gitignore`, since it holds a path that only exists on your
50
+ machine.
51
51
 
52
- ## Map your code
52
+ A fresh install has no history yet. `claude-db scan` builds the code graph, and
53
+ the `/cdb-scan` skill maps an existing codebase into memory, so search has
54
+ something to find on day one. The [setup guide](./docs/setup-guide.md) covers
55
+ the settings and habits that give the best results.
53
56
 
54
- Memory fills itself as you work. The code graph needs one command:
57
+ ## Commands
55
58
 
56
- ```bash
57
- claude-db scan
58
- ```
59
+ `cdb` is a shorter alias for all of them.
59
60
 
60
- Claude then gets four modes through MCP: `text` (a live grep, works with no
61
- scan at all), `usages`, `explain` and `path`. Re-running `scan` is cheap: it
62
- hashes files and re-parses only what changed.
61
+ | Command | What it does |
62
+ | ------------------------------- | ----------------------------------------------------- |
63
+ | `claude-db install [--project]` | Register the hooks and the MCP server |
64
+ | `claude-db status` | Is it wired up, and when did it last record anything |
65
+ | `claude-db doctor [--deep]` | Show the resolved config; `--deep` tests a round trip |
66
+ | `claude-db scan` | Build the code graph for this repo |
67
+ | `claude-db use <url>` | Switch database and verify it |
68
+ | `claude-db distill [on\|off]` | Turn chats into facts with Haiku |
69
+ | `claude-db pick [on\|off]` | Let Haiku pick the memory shown with each prompt |
70
+ | `claude-db view` | See this project's memory in the browser |
63
71
 
64
- TypeScript, TSX, JavaScript, Python, Go, Rust and Ruby are parsed properly, and
65
- every other language — Java, C, C++, C#, Swift, Kotlin, PHP, Elixir, shell and
66
- twenty more — is read by pattern, which finds declarations and name-matched
67
- references tagged `INFERRED`. Nothing else to install either way.
72
+ Every other command, including `search`, `remember`, `sync` and `export`, is in
73
+ the [CLI reference](https://claude-db.vercel.app/docs/cli).
68
74
 
69
75
  ## Use another database
70
76
 
71
- SQLite by default, at `~/.claude-memory/memory.db`. No setup, no network. Point
72
- it elsewhere to share memory across machines:
73
-
74
77
  ```bash
75
- claude-db use "mongodb+srv://user:pass@cluster.mongodb.net/memory"
76
78
  claude-db use "postgres://user:pass@host:5432/memory"
79
+ claude-db use "mongodb+srv://user:pass@cluster.mongodb.net/memory"
77
80
  ```
78
81
 
79
- Install the driver you need (`npm install mongodb` or `pg`); neither ships by
80
- default.
81
-
82
- ## With it, and without it
83
-
84
- Asking _who defines and calls `closeObservations`_ by hand means a grep, then
85
- opening three store adapters to see which hits are definitions. One `explain`
86
- call answers it already classified: **2.1x cheaper**, measured across eight
87
- real symbols in this repo.
88
-
89
- Recall is the standing cost of ~180 tokens a prompt, skipped entirely on 28% of
90
- prompts because the answer is already in context:
91
-
92
- ```
93
- every prompt costs 180 tokens of recall
94
- every lookup refunds 597 tokens (1,115 by hand - 518 with)
95
-
96
- so one lookup pays for 3.3 prompts of recall
97
- ```
98
-
99
- Check it on your own repo with `npm run bench:ab` and `npm run bench:tokens`
100
- from a clone. [With and without](./docs/with-and-without.md) has every number,
101
- including the symbols where plain grep wins.
102
-
103
- ## Commands
82
+ Install the driver first, with `npm install -g pg` or `npm install -g mongodb`.
83
+ Neither ships by default.
104
84
 
105
- `cdb` is a shorter alias for all of them. These are the ones you actually type:
85
+ ## Privacy
106
86
 
107
- | Command | What it does |
108
- | ---------------------------------------- | ------------------------------------------------------ |
109
- | `claude-db install [--project]` | Register hooks and the MCP server |
110
- | `claude-db status` | Is it wired up, and when did it last record anything |
111
- | `claude-db doctor [--deep]` | Resolved config; `--deep` proves a full round trip |
112
- | `claude-db scan [--force]` | Build the code graph for this repo |
113
- | `claude-db usages [--mode <m>] <symbol>` | What uses a symbol: live `git grep`, or the code graph |
114
- | `claude-db use <url>` | Switch database and verify it |
115
- | `claude-db view` | See this project's memory live in the browser |
87
+ Memory stays in your own database. Three things use the network, and each has
88
+ an off switch:
116
89
 
117
- Every other command, including `search`, `remember`, `seed`, `sync`, `export`,
118
- `prune` and `reset`, is in the [CLI reference](https://claude-db.vercel.app/docs/cli).
90
+ - **When a chat ends**, its saved, redacted text is sent once to Claude Haiku
91
+ through your own login, to make facts. Turn it off with `claude-db distill off`.
92
+ - **When a prompt has related memory**, the prompt, the end of Claude's last
93
+ reply and up to ten saved excerpts go to Haiku, so it can pick what to show.
94
+ Turn it off with `claude-db pick off`.
95
+ - **Once a day**, the npm registry is asked for the latest version. Turn it off
96
+ with `"updates": "off"` in the config.
119
97
 
120
- Install also adds a `/cdb-scan` skill: run it once on an existing project and
121
- Claude maps the codebase into memory, so search has something to find before
122
- you have any history.
98
+ `.env`, `secrets/`, `node_modules` and `.git/` are never stored. Text inside
99
+ `<private>...</private>` is stripped, and API keys and tokens are redacted
100
+ before anything is written or sent.
123
101
 
124
102
  ## Requirements
125
103
 
126
- Node 22.5 or newer. That's the only hard requirement: SQLite comes from Node's
127
- builtin `node:sqlite`, so nothing compiles at install time.
128
-
129
- Embeddings run locally with a zero-dependency embedder. For real semantic
130
- search, `npm install @xenova/transformers` and it upgrades itself.
131
-
132
- ## Privacy
133
-
134
- Nothing leaves your machine unless you point it at a remote database.
135
- `.env`, `secrets/`, `node_modules` and `.git/` are never stored, text wrapped
136
- in `<private>...</private>` is stripped, and API keys and tokens are redacted
137
- before anything is written.
104
+ Node 22.16 or newer. SQLite comes from Node's builtin `node:sqlite`, so nothing
105
+ compiles at install time. For real semantic search, run
106
+ `npm install -g @xenova/transformers` and the embedder upgrades itself.
138
107
 
139
108
  ## Documentation
140
109
 
141
- **[claude-db.vercel.app/docs](https://claude-db.vercel.app/docs)** has the rest:
142
- the [CLI reference](https://claude-db.vercel.app/docs/cli),
143
- [MCP tools](https://claude-db.vercel.app/docs/mcp-tools),
144
- [how it works](https://claude-db.vercel.app/docs/how-it-works),
145
- [databases](https://claude-db.vercel.app/docs/databases) and
146
- [troubleshooting](https://claude-db.vercel.app/docs/troubleshooting).
110
+ - [Documentation site](https://claude-db.vercel.app/docs): the
111
+ [CLI reference](https://claude-db.vercel.app/docs/cli),
112
+ [MCP tools](https://claude-db.vercel.app/docs/mcp-tools),
113
+ [how it works](https://claude-db.vercel.app/docs/how-it-works),
114
+ [databases](https://claude-db.vercel.app/docs/databases) and
115
+ [troubleshooting](https://claude-db.vercel.app/docs/troubleshooting)
116
+ - [Setup guide](./docs/setup-guide.md): settings, habits and costs
117
+ - [With and without](./docs/with-and-without.md) and
118
+ [benchmarks](https://claude-db.vercel.app/docs/benchmarks): every number,
119
+ including the symbols where plain grep wins
120
+ - [Changelog](./CHANGELOG.md)
147
121
 
148
- [Benchmarks](https://claude-db.vercel.app/docs/benchmarks) has every number,
149
- including the symbols where plain grep wins. Releases are in the
150
- [changelog](./CHANGELOG.md).
151
-
152
- ## Development
122
+ ## Contributing
153
123
 
154
124
  ```bash
155
125
  npm install
156
126
  npm run build
157
- npm test # 415 checks
158
- npm run lint # house rules: no comments, no any, import extensions
159
- npm run try # simulate a session, touches nothing
160
- npm run format
161
- ```
162
-
163
- Releases publish from CI on a version tag:
164
-
165
- ```bash
166
- npm version patch
167
- git push --follow-tags
127
+ npm test
128
+ npm run lint
168
129
  ```
169
130
 
170
- [CONTRIBUTING.md](./CONTRIBUTING.md) has the conventions, the test setup, and
171
- how to add a language to the code graph. Security reports go through
172
- [SECURITY.md](./SECURITY.md), privately.
131
+ [CONTRIBUTING.md](./CONTRIBUTING.md) has the conventions, the test setup, how to
132
+ add a language to the code graph, and how releases are made. Security reports go
133
+ through [SECURITY.md](./SECURITY.md), privately.
173
134
 
174
135
  ## License
175
136
 
@@ -3,6 +3,7 @@ import type { Observation } from '../types.js';
3
3
  export interface FlushResult {
4
4
  observations: number;
5
5
  summary: string | null;
6
+ lastReply: string;
6
7
  }
7
8
  export declare function flushSession(ctx: RecallContext, sessionId: string, project: string, transcriptPath?: string, rebuild?: boolean): Promise<FlushResult>;
8
9
  export declare function embedObservations(ctx: RecallContext, observations: Observation[]): Promise<void>;
@@ -8,16 +8,17 @@ export async function flushSession(ctx, sessionId, project, transcriptPath, rebu
8
8
  const path = transcriptPath ?? transcriptPathFor(project, sessionId);
9
9
  const cursor = readCursor(sessionId);
10
10
  const { turns, nextOffset } = readTranscript(path, cursor);
11
+ const lastReply = turns.at(-1)?.reasoning ?? '';
11
12
  if (turns.length === 0) {
12
13
  await closeLandedWork(ctx.store, project);
13
14
  writeCursor(sessionId, nextOffset);
14
- return { observations: 0, summary: null };
15
+ return { observations: 0, summary: null, lastReply };
15
16
  }
16
17
  const observations = observationsFromTurns(turns, sessionId, project, ctx.config);
17
18
  if (observations.length === 0) {
18
19
  await closeLandedWork(ctx.store, project);
19
20
  writeCursor(sessionId, nextOffset);
20
- return { observations: 0, summary: null };
21
+ return { observations: 0, summary: null, lastReply };
21
22
  }
22
23
  await embedObservations(ctx, observations);
23
24
  await ctx.store.insertObservations(observations);
@@ -31,7 +32,7 @@ export async function flushSession(ctx, sessionId, project, transcriptPath, rebu
31
32
  summary,
32
33
  });
33
34
  writeCursor(sessionId, nextOffset);
34
- return { observations: observations.length, summary };
35
+ return { observations: observations.length, summary, lastReply };
35
36
  }
36
37
  export async function embedObservations(ctx, observations) {
37
38
  try {
@@ -1,7 +1,8 @@
1
1
  import { execFileSync } from 'node:child_process';
2
2
  import { join } from 'node:path';
3
3
  import { observationId } from './identity.js';
4
- import { classifyTurn, redact, topLevelDirs } from './turn-extractor.js';
4
+ import { redact } from './redact.js';
5
+ import { classifyTurn, topLevelDirs } from './turn-extractor.js';
5
6
  const RECORD = '';
6
7
  const FIELD = '';
7
8
  const NOT_WORTH_KEEPING = /^(v?\d+\.\d+\.\d+|merge |revert "|bump |release |chore\(release\)|\d+\.\d+\.\d+$)/i;
@@ -5,8 +5,12 @@ export type { RememberInput } from './manual.js';
5
5
  export { readTranscript, sessionIdsOnDisk, transcriptPathFor, transcriptsFor, } from './transcript.js';
6
6
  export type { Turn, TranscriptRead } from './transcript.js';
7
7
  export { observationsFromGit } from './git.js';
8
- export { observationsFromTurns, redact } from './turn-extractor.js';
8
+ export { observationsFromTurns } from './turn-extractor.js';
9
+ export { redact } from './redact.js';
10
+ export { claimScrub, finishScrub, releaseScrub, scrubSecrets } from './scrub.js';
9
11
  export { flushSession, resetCursor, clearCursor, sweepCursors, summarize, embedObservations, } from './flush.js';
10
12
  export type { FlushResult } from './flush.js';
11
13
  export { closeLandedWork, openWork } from './progress.js';
14
+ export { REINGEST_VERSION, claimReingest, finishReingest, reingestDone, reingestProject, rememberedTranscripts, reingestSession, releaseReingest, } from './reingest.js';
15
+ export type { ProjectReingest, SessionReingest } from './reingest.js';
12
16
  export { aiSummary, buildSummaryPrompt, validateSummary } from './summarize.js';
@@ -3,7 +3,10 @@ export { currentAuthor, observationId } from './identity.js';
3
3
  export { remember } from './manual.js';
4
4
  export { readTranscript, sessionIdsOnDisk, transcriptPathFor, transcriptsFor, } from './transcript.js';
5
5
  export { observationsFromGit } from './git.js';
6
- export { observationsFromTurns, redact } from './turn-extractor.js';
6
+ export { observationsFromTurns } from './turn-extractor.js';
7
+ export { redact } from './redact.js';
8
+ export { claimScrub, finishScrub, releaseScrub, scrubSecrets } from './scrub.js';
7
9
  export { flushSession, resetCursor, clearCursor, sweepCursors, summarize, embedObservations, } from './flush.js';
8
10
  export { closeLandedWork, openWork } from './progress.js';
11
+ export { REINGEST_VERSION, claimReingest, finishReingest, reingestDone, reingestProject, rememberedTranscripts, reingestSession, releaseReingest, } from './reingest.js';
9
12
  export { aiSummary, buildSummaryPrompt, validateSummary } from './summarize.js';
@@ -1,6 +1,6 @@
1
1
  import { embedObservations } from './flush.js';
2
2
  import { currentAuthor, observationId } from './identity.js';
3
- import { redact } from './turn-extractor.js';
3
+ import { redact } from './redact.js';
4
4
  export async function remember(ctx, input) {
5
5
  const createdAt = Date.now();
6
6
  const author = currentAuthor();
@@ -7,6 +7,7 @@ function uncommittedFiles(project) {
7
7
  const raw = execFileSync('git', ['-C', project, 'status', '--porcelain', '-z'], {
8
8
  encoding: 'utf8',
9
9
  maxBuffer: MAX_BUFFER,
10
+ stdio: ['ignore', 'pipe', 'ignore'],
10
11
  });
11
12
  const files = new Set();
12
13
  const fields = raw.split('\0');
@@ -0,0 +1 @@
1
+ export declare function redact(text: string): string;
@@ -0,0 +1,17 @@
1
+ const PRIVATE_BLOCK = /<private>[\s\S]*?(?:<\/private>|$)/gi;
2
+ const PRIVATE_KEY = /-----BEGIN [A-Z ]*PRIVATE KEY-----[\s\S]*?-----END [A-Z ]*PRIVATE KEY-----/g;
3
+ const SECRET_NAME = '[A-Za-z0-9_]*(?:token|secret|password|passwd|api[_-]?key|access[_-]?key)[A-Za-z0-9_]*';
4
+ const UNQUOTED_SECRET = new RegExp(`\\b(${SECRET_NAME})(\\s*[:=]\\s*)(?=[^\\s"'\`,;]*[A-Za-z])[^\\s"'\`,;\\[]{8,}`, 'gi');
5
+ export function redact(text) {
6
+ return text
7
+ .replace(PRIVATE_BLOCK, '[redacted]')
8
+ .replace(PRIVATE_KEY, '[redacted-private-key]')
9
+ .replace(/\/\/[^\s:/@]+:[^\s@]+@/g, '//[redacted]@')
10
+ .replace(/\b(sk-[A-Za-z0-9_-]{16,})\b/g, '[redacted-key]')
11
+ .replace(/\b(gh[pousr]_[A-Za-z0-9]{16,})\b/g, '[redacted-token]')
12
+ .replace(/\bAKIA[0-9A-Z]{16}\b/g, '[redacted-key]')
13
+ .replace(/\bxox[baprs]-[A-Za-z0-9-]{10,}/g, '[redacted-token]')
14
+ .replace(/\beyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}/g, '[redacted-jwt]')
15
+ .replace(/(?<=(password|secret|token|api[_-]?key)"?\s*[:=]\s*)"[^"]+"/gi, '"[redacted]"')
16
+ .replace(UNQUOTED_SECRET, '$1$2[redacted]');
17
+ }
@@ -0,0 +1,19 @@
1
+ import type { RecallContext } from '../context.js';
2
+ export declare const REINGEST_VERSION = 1;
3
+ export interface SessionReingest {
4
+ sessionId: string;
5
+ saved: number;
6
+ replaced: number;
7
+ }
8
+ export interface ProjectReingest {
9
+ transcripts: number;
10
+ saved: number;
11
+ replaced: number;
12
+ }
13
+ export declare function reingestSession(ctx: RecallContext, project: string, path: string): Promise<SessionReingest>;
14
+ export declare function rememberedTranscripts(ctx: RecallContext, project: string, paths?: string[]): Promise<string[]>;
15
+ export declare function reingestProject(ctx: RecallContext, project: string, paths?: string[], onSession?: (result: SessionReingest) => void): Promise<ProjectReingest>;
16
+ export declare function reingestDone(project: string): boolean;
17
+ export declare function claimReingest(project: string, now?: number): boolean;
18
+ export declare function finishReingest(project: string): void;
19
+ export declare function releaseReingest(project: string): void;