claude-db 0.4.1 → 0.5.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 (203) hide show
  1. package/CHANGELOG.md +411 -0
  2. package/README.md +62 -94
  3. package/dist/capture/command.d.ts +0 -14
  4. package/dist/capture/command.js +0 -23
  5. package/dist/capture/flush.d.ts +1 -50
  6. package/dist/capture/flush.js +4 -63
  7. package/dist/capture/git.js +0 -20
  8. package/dist/capture/identity.d.ts +0 -17
  9. package/dist/capture/identity.js +1 -21
  10. package/dist/capture/index.d.ts +1 -0
  11. package/dist/capture/index.js +1 -0
  12. package/dist/capture/manual.d.ts +0 -19
  13. package/dist/capture/manual.js +0 -0
  14. package/dist/capture/progress.d.ts +4 -0
  15. package/dist/capture/progress.js +33 -0
  16. package/dist/capture/transcript.d.ts +0 -45
  17. package/dist/capture/transcript.js +4 -70
  18. package/dist/capture/turn-extractor.d.ts +0 -15
  19. package/dist/capture/turn-extractor.js +1 -104
  20. package/dist/cli/args.d.ts +4 -0
  21. package/dist/cli/args.js +16 -0
  22. package/dist/cli/commands/doctor.d.ts +1 -0
  23. package/dist/cli/commands/doctor.js +76 -0
  24. package/dist/cli/commands/graph.d.ts +2 -0
  25. package/dist/cli/commands/graph.js +93 -0
  26. package/dist/cli/commands/insight.d.ts +3 -0
  27. package/dist/cli/commands/insight.js +129 -0
  28. package/dist/cli/commands/maintain.d.ts +3 -0
  29. package/dist/cli/commands/maintain.js +77 -0
  30. package/dist/cli/commands/memory.d.ts +3 -0
  31. package/dist/cli/commands/memory.js +77 -0
  32. package/dist/cli/commands/seed.d.ts +1 -0
  33. package/dist/cli/commands/seed.js +43 -0
  34. package/dist/cli/commands/setup.d.ts +4 -0
  35. package/dist/cli/commands/setup.js +156 -0
  36. package/dist/cli/commands/sync.d.ts +1 -0
  37. package/dist/cli/commands/sync.js +95 -0
  38. package/dist/cli/commands/transfer.d.ts +9 -0
  39. package/dist/cli/commands/transfer.js +129 -0
  40. package/dist/cli/commands/use.d.ts +1 -0
  41. package/dist/cli/commands/use.js +90 -0
  42. package/dist/cli/constants.d.ts +2 -0
  43. package/dist/cli/constants.js +4 -0
  44. package/dist/cli/files.d.ts +4 -0
  45. package/dist/cli/files.js +33 -0
  46. package/dist/cli/index.js +15 -1080
  47. package/dist/cli/install.d.ts +1 -59
  48. package/dist/cli/install.js +5 -194
  49. package/dist/cli/instructions.d.ts +5 -0
  50. package/dist/cli/instructions.js +55 -0
  51. package/dist/cli/paths.d.ts +5 -0
  52. package/dist/cli/paths.js +19 -0
  53. package/dist/cli/refresh.d.ts +1 -0
  54. package/dist/cli/refresh.js +25 -0
  55. package/dist/cli/usage.d.ts +1 -0
  56. package/dist/cli/usage.js +39 -0
  57. package/dist/config/load.d.ts +0 -5
  58. package/dist/config/load.js +1 -8
  59. package/dist/config/schema.js +2 -58
  60. package/dist/context.d.ts +0 -10
  61. package/dist/context.js +0 -16
  62. package/dist/embed/builtin.d.ts +0 -12
  63. package/dist/embed/builtin.js +0 -20
  64. package/dist/embed/embedder.d.ts +0 -14
  65. package/dist/embed/embedder.js +0 -1
  66. package/dist/embed/index.d.ts +0 -9
  67. package/dist/embed/index.js +0 -9
  68. package/dist/embed/local.d.ts +0 -8
  69. package/dist/embed/local.js +0 -12
  70. package/dist/graph/index.d.ts +7 -0
  71. package/dist/graph/index.js +4 -0
  72. package/dist/graph/languages/ecmascript.d.ts +4 -0
  73. package/dist/graph/languages/ecmascript.js +47 -0
  74. package/dist/graph/languages/go.d.ts +2 -0
  75. package/dist/graph/languages/go.js +15 -0
  76. package/dist/graph/languages/index.d.ts +6 -0
  77. package/dist/graph/languages/index.js +20 -0
  78. package/dist/graph/languages/python.d.ts +2 -0
  79. package/dist/graph/languages/python.js +15 -0
  80. package/dist/graph/languages/rules.d.ts +18 -0
  81. package/dist/graph/languages/rules.js +1 -0
  82. package/dist/graph/languages/rust.d.ts +2 -0
  83. package/dist/graph/languages/rust.js +16 -0
  84. package/dist/graph/parser.d.ts +31 -0
  85. package/dist/graph/parser.js +29 -0
  86. package/dist/graph/query/format.d.ts +2 -0
  87. package/dist/graph/query/format.js +41 -0
  88. package/dist/graph/query/index.d.ts +5 -0
  89. package/dist/graph/query/index.js +4 -0
  90. package/dist/graph/query/lookup.d.ts +21 -0
  91. package/dist/graph/query/lookup.js +35 -0
  92. package/dist/graph/query/path.d.ts +2 -0
  93. package/dist/graph/query/path.js +48 -0
  94. package/dist/graph/query/refresh.d.ts +2 -0
  95. package/dist/graph/query/refresh.js +21 -0
  96. package/dist/graph/scan/extract.d.ts +15 -0
  97. package/dist/graph/scan/extract.js +101 -0
  98. package/dist/graph/scan/files.d.ts +12 -0
  99. package/dist/graph/scan/files.js +51 -0
  100. package/dist/graph/scan/index.d.ts +18 -0
  101. package/dist/graph/scan/index.js +44 -0
  102. package/dist/graph/scan/resolve.d.ts +3 -0
  103. package/dist/graph/scan/resolve.js +48 -0
  104. package/dist/hooks/payload.d.ts +0 -8
  105. package/dist/hooks/payload.js +0 -6
  106. package/dist/hooks/relevance.d.ts +0 -17
  107. package/dist/hooks/relevance.js +55 -38
  108. package/dist/hooks/session-end.js +0 -11
  109. package/dist/hooks/session-start.js +33 -14
  110. package/dist/hooks/user-prompt.js +0 -18
  111. package/dist/mcp/render.d.ts +0 -20
  112. package/dist/mcp/render.js +0 -39
  113. package/dist/mcp/server.js +46 -25
  114. package/dist/search/rank.d.ts +0 -14
  115. package/dist/search/rank.js +0 -16
  116. package/dist/search/service.d.ts +1 -32
  117. package/dist/search/service.js +1 -36
  118. package/dist/store/adapter.d.ts +11 -44
  119. package/dist/store/adapter.js +1 -12
  120. package/dist/store/index.d.ts +0 -11
  121. package/dist/store/index.js +0 -11
  122. package/dist/store/mongo/docs.d.ts +61 -0
  123. package/dist/store/mongo/docs.js +106 -0
  124. package/dist/store/mongo/driver.d.ts +1 -15
  125. package/dist/store/mongo/driver.js +0 -15
  126. package/dist/store/mongo/filters.d.ts +6 -0
  127. package/dist/store/mongo/filters.js +18 -0
  128. package/dist/store/mongo/graph.d.ts +12 -0
  129. package/dist/store/mongo/graph.js +61 -0
  130. package/dist/store/mongo/helpers.d.ts +2 -0
  131. package/dist/store/mongo/helpers.js +8 -0
  132. package/dist/store/mongo/index.d.ts +16 -13
  133. package/dist/store/mongo/index.js +52 -295
  134. package/dist/store/mongo/observations.d.ts +10 -0
  135. package/dist/store/mongo/observations.js +97 -0
  136. package/dist/store/mongo/search.d.ts +6 -0
  137. package/dist/store/mongo/search.js +51 -0
  138. package/dist/store/mongo/sessions.d.ts +6 -0
  139. package/dist/store/mongo/sessions.js +24 -0
  140. package/dist/store/mongo/vectorSearch.d.ts +5 -0
  141. package/dist/store/mongo/vectorSearch.js +57 -0
  142. package/dist/store/postgres/driver.d.ts +19 -0
  143. package/dist/store/postgres/driver.js +13 -0
  144. package/dist/store/postgres/filters.d.ts +2 -0
  145. package/dist/store/postgres/filters.js +22 -0
  146. package/dist/store/postgres/graph.d.ts +11 -0
  147. package/dist/store/postgres/graph.js +115 -0
  148. package/dist/store/postgres/index.d.ts +20 -33
  149. package/dist/store/postgres/index.js +43 -428
  150. package/dist/store/postgres/insert.d.ts +3 -0
  151. package/dist/store/postgres/insert.js +59 -0
  152. package/dist/store/postgres/meta.d.ts +10 -0
  153. package/dist/store/postgres/meta.js +54 -0
  154. package/dist/store/postgres/observations.d.ts +10 -0
  155. package/dist/store/postgres/observations.js +139 -0
  156. package/dist/store/postgres/rows.d.ts +6 -0
  157. package/dist/store/postgres/rows.js +74 -0
  158. package/dist/store/postgres/schema.d.ts +3 -0
  159. package/dist/store/postgres/schema.js +84 -0
  160. package/dist/store/postgres/search.d.ts +3 -0
  161. package/dist/store/postgres/search.js +20 -0
  162. package/dist/store/postgres/sessions.d.ts +5 -0
  163. package/dist/store/postgres/sessions.js +26 -0
  164. package/dist/store/postgres/vectorSearch.d.ts +3 -0
  165. package/dist/store/postgres/vectorSearch.js +21 -0
  166. package/dist/store/sqlite/filters.d.ts +9 -0
  167. package/dist/store/sqlite/filters.js +77 -0
  168. package/dist/store/sqlite/graph.d.ts +11 -0
  169. package/dist/store/sqlite/graph.js +100 -0
  170. package/dist/store/sqlite/index.d.ts +12 -10
  171. package/dist/store/sqlite/index.js +41 -379
  172. package/dist/store/sqlite/observations.d.ts +10 -0
  173. package/dist/store/sqlite/observations.js +128 -0
  174. package/dist/store/sqlite/rows.d.ts +8 -0
  175. package/dist/store/sqlite/rows.js +84 -0
  176. package/dist/store/sqlite/schema.sql +42 -2
  177. package/dist/store/sqlite/search.d.ts +5 -0
  178. package/dist/store/sqlite/search.js +86 -0
  179. package/dist/store/sqlite/sessions.d.ts +5 -0
  180. package/dist/store/sqlite/sessions.js +21 -0
  181. package/dist/types.d.ts +47 -40
  182. package/dist/types.js +0 -4
  183. package/dist/update.d.ts +0 -20
  184. package/dist/update.js +4 -29
  185. package/dist/usages/find.d.ts +2 -8
  186. package/dist/usages/find.js +51 -54
  187. package/dist/usages/index.d.ts +1 -1
  188. package/dist/usages/index.js +1 -1
  189. package/dist/util/project.d.ts +0 -12
  190. package/dist/util/project.js +0 -24
  191. package/dist/util/scope.d.ts +0 -9
  192. package/dist/util/scope.js +0 -9
  193. package/dist/util/shortid.d.ts +0 -5
  194. package/dist/util/shortid.js +1 -19
  195. package/dist/util/snippet.d.ts +0 -26
  196. package/dist/util/snippet.js +0 -30
  197. package/dist/util/vector.d.ts +0 -12
  198. package/dist/util/vector.js +0 -12
  199. package/dist/util/warnings.d.ts +0 -11
  200. package/dist/util/warnings.js +0 -11
  201. package/docs/how-it-works.md +183 -0
  202. package/package.json +14 -3
  203. package/skills/cdb-scan/SKILL.md +31 -6
package/CHANGELOG.md ADDED
@@ -0,0 +1,411 @@
1
+ # Changelog
2
+
3
+ ## 0.5.1
4
+
5
+ ### Fixed
6
+
7
+ - **A turn that touched no files stayed open forever.** Work closes when every
8
+ file it touched has been committed, but a turn that only ran commands has no
9
+ files to land, so it could never close and sat in `status` and in the
10
+ SessionStart injection permanently. Those turns are now recorded as already
11
+ done, and a row with no outstanding files closes rather than being skipped.
12
+ Found by reading the list on a clean tree: four entries, none of them real
13
+ work
14
+
15
+ ## 0.5.0
16
+
17
+ `find_usages` could only ever answer "where does this string appear". It could
18
+ not say *how* two things relate — a call, an import, an inherit — or trace how
19
+ one symbol reaches another, and it re-paid the full search cost on every
20
+ question.
21
+
22
+ ### Added
23
+
24
+ - **A code graph, built by `claude-db scan`.** Every source file is parsed with
25
+ ast-grep and stored as symbols plus the relationships between them. Parsing
26
+ is local, deterministic and costs no tokens; a rescan re-parses only files
27
+ whose contents changed, so it is seconds the first time and milliseconds
28
+ after. TypeScript, TSX, JavaScript, Python, Go and Rust, with the parser
29
+ shipped as a prebuilt binary per platform so nothing compiles at install
30
+ - **Three new `find_usages` modes**, on the CLI and over MCP: `usages` lists
31
+ what references a symbol with the relation on each line, `explain` adds what
32
+ the symbol reaches, and `path` traces how two symbols connect. `text` remains
33
+ the default and still needs no scan
34
+ - **Every edge carries its confidence.** `EXTRACTED` means it was read literally
35
+ out of the syntax tree; `INFERRED` means the target was matched by name across
36
+ files, and carries a score. Name matching is the one guess this makes, so it
37
+ is labelled rather than presented as fact
38
+ - **A class links to the members it defines**, so a path can cross the class
39
+ boundary — `boot --> App --> start --> helper` rather than stopping dead at
40
+ the class, which is where the obvious chain used to break
41
+ - **Work is tracked as unfinished until it is committed.** A captured turn is
42
+ stored `open` and closes once every file it touched has landed in a commit,
43
+ which the existing flush already checks — there is no new hook to stop
44
+ firing. `claude-db status` lists what is still open, and SessionStart injects
45
+ the newest few, so a fresh chat can answer "what was I doing" instead of
46
+ searching for words that a prompt like "do the last task" does not contain.
47
+ Closing is one-way: touching a file again does not reopen finished work, and
48
+ rows written before this release stay `done` rather than all appearing
49
+ unfinished
50
+ - **Updating the package is now enough.** The skill and the standing
51
+ instruction were copied to disk at install time, so `npm i -g claude-db` left
52
+ them frozen at whatever shipped when install was last run — you had to
53
+ remember to re-run it. The hooks are registered by absolute path into the
54
+ package, so they always run the current code; SessionStart now compares those
55
+ copies against the packaged ones and repairs them. It only ever refreshes
56
+ what already exists, so nothing is installed behind your back and an
57
+ uninstalled skill is not resurrected
58
+ - **`/cdb-scan` now runs in two passes** — the deterministic graph first, then
59
+ the written `profile:*` notes on top of it
60
+
61
+ ### Fixed
62
+
63
+ - **A NUL byte in `src/capture/manual.ts` made the whole file invisible to**
64
+ **`find_usages`.** It was committed, renders as a space in every editor, and
65
+ made git classify a source file as binary — which `-I` then skipped, so a
66
+ lookup for `remember` returned 32 matches and omitted `remember()`'s own
67
+ definition. The separator is now written as an escape, which is byte-identical
68
+ so no stored id changed. A check now fails if any tracked source file contains
69
+ a NUL, since any such file would be invisible the same way
70
+ - **`--context` counted context lines as matches.** `git grep -z` replaces both
71
+ the match and context separators with the same NUL, so `-B`/`-A` output could
72
+ not be told apart from real hits: `total` was inflated, truncation was wrong,
73
+ and context lines consumed the `limit` budget. Context is now reconstructed
74
+ from disk after the real matches are known
75
+ - **A `path` pointing at a single file threw instead of scoping to it**, though
76
+ the tool documented that it accepted one — `git -C` requires a directory
77
+ - **MongoDB's Atlas vector path scored across embedding models.** Every other
78
+ search path filtered on the embedder that produced a vector; the indexed
79
+ Atlas path did not, so switching models silently ranked incomparable vectors
80
+
81
+ ### Changed
82
+
83
+ - Prettier now formats the project, with the config checked in
84
+ - The CLI, the three store adapters and the test scripts are split by
85
+ responsibility; no source file is over 250 lines
86
+
87
+ ### Upgrading
88
+
89
+ Nothing changes until you run `claude-db scan`, which builds the graph and adds
90
+ three tables. Postgres gains its tables on first connection after the upgrade.
91
+
92
+ This release adds real dependencies for the first time — the ast-grep parser
93
+ and graphology — so an install is roughly 23 MB larger. They are prebuilt, so
94
+ there is still no compile step.
95
+
96
+ ## 0.4.1
97
+
98
+ ### Fixed
99
+
100
+ - **`find_usages`'s `path` param only chose which repository to search, and**
101
+ **never actually scoped the search** — described as "directory to search
102
+ from," but no pathspec was ever passed to `git grep`, so a lookup scoped to
103
+ one folder still searched the whole repository. Caught by using the tool: a
104
+ search for `resolveProject` scoped to `src/usages/` (which does not use it)
105
+ still returned 41 matches from across the repo. An explicit `path` now
106
+ narrows the search for real; omitting it still searches the whole
107
+ repository, since a blast-radius check that silently narrowed by default
108
+ could hide a real usage and give false confidence nothing else depends on it
109
+ - The fix itself had the same bug this project keeps tripping on: comparing
110
+ `mkdtempSync`'s temp path against `git rev-parse --show-toplevel`'s result
111
+ failed on macOS, where `/var/folders/...` is a symlink to
112
+ `/private/var/folders/...` — the exact class of mismatch `resolveProject()`
113
+ already guards against with `realpathSync`. Applied the same fix here
114
+
115
+ ### Changed
116
+
117
+ - The standing instruction written at install sharpens the `find_usages`
118
+ boundary: it is the default for any symbol/identifier lookup, not only
119
+ before editing a shared name; grep still wins for plain text, log files,
120
+ comments, strings, and scoping with grep flags this tool does not expose
121
+
122
+ ## 0.4.0
123
+
124
+ Claude has had no better option than raw Bash `grep` for "what uses X" or "if
125
+ I change this, what breaks" — text matching with no idea whether a hit is the
126
+ definition, a real caller, or an unrelated word.
127
+
128
+ ### Added
129
+
130
+ - **`find_usages`**, a sixth MCP tool, plus `claude-db usages <symbol>`. Wraps
131
+ `git grep`, never a persisted index: this project has already shipped three
132
+ silent-staleness bugs, and a symbol index that drifts from an edit is the
133
+ same failure shape in a new place. A live grep re-derives the answer from
134
+ the current source on every call, so there is nothing to invalidate. Scope
135
+ resolution deliberately does not reuse `resolveProject()` — that can point
136
+ at a directory pooling several sibling repos for memory partitioning, which
137
+ `git grep` cannot search — and resolves its own repo root instead. No
138
+ usage-kind classification (import vs call vs type): the `classifyTurn`
139
+ `because` regression is the direct precedent for why that regex heuristic
140
+ goes wrong. The one exception is a best-effort `[definition?]` marker that
141
+ only annotates an already-shown line rather than filtering anything
142
+
143
+ ### Fixed
144
+
145
+ - **Untracked and binary files were mishandled in the first pass of the above**
146
+ before it shipped: a brand-new file that hasn't been `git add`ed yet is
147
+ exactly the blast-radius case the tool exists for, and was invisible
148
+ without `--untracked`; a binary file matching the term printed a headerless
149
+ line that corrupted the parser without `-I`. Both caught in review, both
150
+ covered by their own test
151
+ - A search-result snippet that only echoes words already in the title is now
152
+ dropped rather than shown, since it was paying for a line that told the
153
+ reader nothing new
154
+
155
+ ## 0.3.0
156
+
157
+ Every defect shipped so far was silent — hooks swallow their errors so a memory
158
+ layer can never break a session, which is the right call and means nothing ever
159
+ reports that capture has stopped. This release is mostly about the tool proving
160
+ it works, plus the first two answers to "it knows nothing yet".
161
+
162
+ ### Added
163
+
164
+ - **`status` reports when memory was last written**, and warns when this project
165
+ has been worked in for two days with nothing recorded. Work happening while
166
+ capture doesn't is the signal every failure so far has left, and nothing
167
+ surfaced it
168
+ - **`doctor --deep`** writes an observation, searches for it, expands it and
169
+ deletes it — through the real adapter, embedder and index. Reachability was
170
+ all `doctor` ever proved, and every silent failure had a reachable database
171
+ - **`claude-db seed --from-git`** builds memory from commit history: subject,
172
+ body, changed files, author and date. A fresh install knows nothing for weeks,
173
+ which is the worst moment to ask anyone to trust it. Merges and releases are
174
+ skipped, and ids come from the sha, so re-running adds rather than duplicates
175
+ - **`claude-db sync <url>`** two-way merges with another database. Content-derived
176
+ ids make it nearly free: an id on one side and not the other is memory the
177
+ other has never seen. Session recaps travel with it. Dry run without `--yes`
178
+ - **`/cdb-scan`**, installed alongside the hooks: Claude surveys the codebase
179
+ once into five notes — stack, layout, conventions, workflows, architecture.
180
+ Tagged `inferred`, because everything else in the database is a record of what
181
+ happened and this is a reading of the code
182
+ - **`search --tag <name>`**, and `tag` over MCP. Tags recorded the repository or
183
+ directory an observation touched and only ever nudged ranking, so a workspace
184
+ pooling several repositories could not ask about one of them
185
+ - **`remember --key <name>`**, and `key` over MCP: a stable identity, so a note
186
+ meant to be kept current is replaced rather than duplicated on every run
187
+
188
+ - **A snippet of the matching body in every search result.** The index was
189
+ built on the assumption that a title tells you which row holds the answer,
190
+ and it often does not: fifteen results dated the same day, titled things like
191
+ "Committed as 30daa92", leave nothing to choose on, so you expand two at
192
+ random and pay a full body for each guess. Measured over five real searches,
193
+ snippets add about 19 tokens a row and one avoided expansion saves about
194
+ 1000. FTS5 `snippet()` and `ts_headline` centre the fragment on the match;
195
+ MongoDB's `$text` has no equivalent and returns the head of the body. Rows
196
+ found by vector similarity alone carry none — there are no query terms in
197
+ them to centre on — and were 20% of results in that measurement
198
+ - **`get_observations` takes a `chars` limit**, default 2000. The cost argument
199
+ that made the index terse was never applied one layer down, where a single
200
+ call may ask for twenty-five bodies at once. The remainder is counted rather
201
+ than dropped in silence
202
+
203
+ ### Fixed
204
+
205
+ - **Titles still fell back to narration.** 0.2.2 skipped sentences that announce
206
+ the work; a sentence that merely says nothing still won, so "Working through
207
+ the improvements now." was a stored title. Titles now take the first sentence
208
+ carrying evidence — a filename, a number, a past-tense verb — and fall back
209
+ only when none does
210
+ - **`use` stranded your memory in silence.** Switching backends left everything
211
+ already recorded behind and started the new one empty. It now says so, and
212
+ says how to bring it across
213
+ - **`use` wrote into whatever it was pointed at.** One in anger resolved to a
214
+ live application database; two tables were created inside it without a word.
215
+ It now reports what else is in there, before adding anything
216
+ - **`kind` barely filtered.** `decision` matched on the bare word *because*,
217
+ which explains as readily as it decides — 98 of 471 stored decisions matched
218
+ on nothing else, and half the database was one kind. It now needs a weighed
219
+ alternative
220
+ - A certificate error from a managed Postgres now names the fix, not just the
221
+ problem
222
+ - Cursors for transcripts that no longer exist are swept during `flush`.
223
+ `clearCursor` landed in 0.2.0 and never covered anything written before it
224
+
225
+ ### Changed
226
+
227
+ - **Postgres `init()` costs one round trip instead of four.** Every hook is its
228
+ own process, so nothing is pooled and the whole setup ran again on every
229
+ prompt. Against a managed instance — 49ms at best, 1045ms at the median for a
230
+ single round trip — that was most of why a remote backend felt broken. A
231
+ version row now short-circuits it, and anything unexpected falls through to
232
+ the full setup
233
+
234
+ ### Upgrading
235
+
236
+ Postgres gains a `claude_db_meta` table on first connection, which is why this
237
+ is a minor release rather than a patch: `updates: auto` will report it and leave
238
+ it to you.
239
+
240
+ Titles and kinds are rewritten by re-ingesting, per project:
241
+
242
+ ```bash
243
+ cd <project> && claude-db flush
244
+ ```
245
+
246
+ ## 0.2.3
247
+
248
+ ### Added
249
+
250
+ - **Update notifications.** A newer release is reported once a day at session
251
+ start. The check runs detached at session end and writes a local file the next
252
+ session reads, so neither the network nor npm is ever on the prompt path
253
+ - `updates: notify | auto | off`. Notify is the default — installing on
254
+ someone's behalf means executing code they did not choose, in a process
255
+ holding their whole memory database. `auto` is available for anyone who wants
256
+ it, and stops at the caret boundary: 0.2.x takes 0.2.z but not 0.3.0, since a
257
+ release outside that range may migrate the database on first connection
258
+ - `claude-db update` to check and install on demand
259
+ - `doctor` reports the running version, which nothing did before
260
+
261
+ ## 0.2.2
262
+
263
+ ### Fixed
264
+
265
+ - **Titles announced the work instead of reporting it.** `buildTitle` took the
266
+ reply's opening sentence, which mid-task is a transition rather than an
267
+ outcome — "Now the use command and the top-level handler:", "Right — let me
268
+ do that properly". Measured on a real database, half of all titles read like
269
+ that. Since the title is the whole payload of a search result and of the
270
+ block injected above each prompt, a turn whose body held the answer was
271
+ unreachable. Titles now skip announcing sentences and take the first that
272
+ carries a claim
273
+
274
+ ### Changed
275
+
276
+ - The memory instructions written at install now ask the agent to search
277
+ **before re-deriving** something the project already knows — grepping or
278
+ reading git history to reconstruct a past decision — not only before saying
279
+ it lacks context, which never fires when it silently reconstructs instead
280
+
281
+ ### Upgrading
282
+
283
+ Existing titles are rewritten by re-ingesting, per project:
284
+
285
+ ```bash
286
+ cd <project> && claude-db flush
287
+ ```
288
+
289
+ Embeddings are recomputed as part of that; no separate `reembed` is needed.
290
+
291
+ ## 0.2.1
292
+
293
+ ### Fixed
294
+
295
+ - **`use` saved the connection string before testing it**, so a typo or a
296
+ retired host was written to the config permanently. Every hook then pointed
297
+ at a database that was not there, and because hooks swallow their errors,
298
+ memory silently stopped recording. It now connects and pings first, keeping
299
+ the previous database otherwise; `--force` saves unverified
300
+ - Errors from a database driver printed a raw stack trace instead of a message
301
+ - Credentials in a connection string (`user:password@host`) were not redacted,
302
+ and were stored verbatim in memory
303
+ - `remember` applied no redaction at all — dictated memory was stored raw
304
+
305
+ ## 0.2.0
306
+
307
+ Memory becomes writable, is keyed on the repository rather than the directory
308
+ you happened to launch from, and behaves the same on all three backends.
309
+
310
+ ### Fixed
311
+
312
+ - **SQLite orphaned an FTS row on every re-ingest.** `INSERT OR REPLACE` skips
313
+ the delete triggers that maintain the mirror unless `recursive_triggers` is
314
+ on. Existing databases repair themselves once, guarded by `user_version`
315
+ - **Postgres stored nothing on a default install.** The embedding column was
316
+ hardcoded to 384 dimensions while the built-in embedder produces 256, so
317
+ every insert failed and rolled the batch back. The column is now sized to the
318
+ vectors actually written
319
+ - **Postgres discarded corrections**, using `ON CONFLICT DO NOTHING` where the
320
+ other adapters overwrite, pinning every observation to its first, partial
321
+ capture
322
+ - **Postgres keyword search was narrower than the rest.** `plainto_tsquery`
323
+ ANDs every term, so a natural-language prompt matched nothing and per-prompt
324
+ injection never fired. Tags were not indexed there at all
325
+ - Vectors of different widths were compared and scored a meaningless number;
326
+ they now score zero and fall below the relevance floor
327
+ - Observation titles were never redacted, though they are injected above every
328
+ prompt
329
+ - Non-Latin prompts recalled nothing: three ASCII-only tokenisers, one of which
330
+ gave CJK text a zero vector
331
+ - `uninstall` left the MCP server registered when it was the only one
332
+ - `upsertSession` never updated `project` on SQLite or Postgres
333
+
334
+ ### Added
335
+
336
+ - `remember` and `forget`, as MCP tools and CLI verbs. Capture is inferred from
337
+ events, and a rule is not an event, so a standing preference was the one
338
+ thing that could never be recorded
339
+ - `export`, `import`, `prune`, `reembed`, `stats` and `merge`
340
+ - `search --all`, and `project: "*"` over MCP, for cross-project recall
341
+ - `author` and `embedder` recorded per observation
342
+ - Install writes standing memory instructions to `CLAUDE.local.md`, so recall
343
+ is a default rather than something to ask for each session
344
+
345
+ ### Changed
346
+
347
+ - Memory is keyed on the repository root, so working from a subdirectory no
348
+ longer starts a second, invisible memory. `$HOME` is refused, so a dotfiles
349
+ repo cannot collapse every project into one
350
+ - Session summaries carry across flushes and rank by kind
351
+ - Observations are tagged with the repository or top-level directory they
352
+ touched
353
+ - The embedder is bounded by `embeddings.timeoutMs`, so a first model download
354
+ cannot hang a prompt
355
+ - Redaction covers private keys, AWS keys, Slack tokens and JWTs
356
+ - A global install registers through `claude mcp add -s user` instead of
357
+ rewriting `~/.claude.json`, and every settings write is atomic
358
+ - `MemoryStore.clear()` is replaced by `remove(filter)`, alongside a new paged
359
+ `list(filter)`
360
+
361
+ ### Notes
362
+
363
+ Postgres and MongoDB are now covered by CI rather than by argument. The suite
364
+ is 138 checks.
365
+
366
+ ## 0.1.0
367
+
368
+ First release.
369
+
370
+ ### Capture
371
+
372
+ - Reads Claude Code session transcripts rather than watching tool calls, so
373
+ observations carry the prompt (intent) and the agent's reasoning, not just
374
+ file paths
375
+ - Groups a transcript into turns: a prompt plus everything until the next one
376
+ - Content-derived observation ids, so reprocessing rewrites rather than
377
+ duplicating
378
+ - Flushes on every prompt, so sessions that crash or never close are still
379
+ recorded
380
+ - Byte-offset cursor per session, so each flush parses only the new tail
381
+ - Shell commands filtered by an allowlist of consequential operations
382
+ (dependency changes, tests, builds, history-changing git, migrations,
383
+ infra). Exploration is dropped
384
+ - Secrets redacted and excluded paths dropped before anything is written
385
+
386
+ ### Storage
387
+
388
+ - One `MemoryStore` interface, three adapters: SQLite, MongoDB, Postgres
389
+ - Connection-string scheme selects the backend; drivers load lazily
390
+ - SQLite via Node's builtin `node:sqlite`: no native build step
391
+ - Project scoping indexed inside FTS rather than applied as a post-filter
392
+ - Brute-force vector scans bounded by `embeddings.maxScanCandidates`
393
+
394
+ ### Recall
395
+
396
+ - Three-layer progressive disclosure: `search`, `timeline`,
397
+ `get_observations`, exposed as MCP tools
398
+ - Hybrid retrieval fused by Reciprocal Rank Fusion, with a recency boost
399
+ - Automatic injection at session start and on every prompt, with the best
400
+ match expanded in full
401
+ - Relevance floor per embedder, so an unrelated prompt injects nothing
402
+ - Zero-dependency builtin embedder; optional upgrade to all-MiniLM-L6-v2
403
+
404
+ ### CLI
405
+
406
+ `install`, `uninstall`, `status`, `doctor`, `use`, `search`, `projects`,
407
+ `flush`, `reset`. Aliased as `cdb`.
408
+
409
+ - `--project` scopes to one repo instead of the whole machine
410
+ - `install` refuses to run from an npx cache, since hooks store absolute paths
411
+ - `reset` is a dry run unless given `--yes`
package/README.md CHANGED
@@ -16,6 +16,11 @@ re-explain the architecture, why you chose X over Y, and what already failed.
16
16
  claude-db records those decisions as you work and gives them back
17
17
  automatically. Local by default, no account, no subscription.
18
18
 
19
+ It also maps your code: `claude-db scan` builds a graph of every symbol and how
20
+ they connect, so "what breaks if I change this" is a query instead of a grep.
21
+
22
+ ## Install
23
+
19
24
  ```bash
20
25
  npm install -g claude-db
21
26
 
@@ -23,117 +28,73 @@ cd your-project
23
28
  claude-db install --project
24
29
  ```
25
30
 
26
- Restart Claude Code. That's it.
31
+ Restart Claude Code. That's it — capture and recall are hooks, so they run
32
+ without being asked.
27
33
 
28
- ## How it works
29
-
30
- Claude Code already writes every session to disk as JSONL — your prompts, its
31
- replies, every tool call. claude-db reads that file, so it captures **why** you
32
- did something, not just which files changed.
34
+ `--project` scopes to one repo instead of every project on the machine. It
35
+ writes `.claude/settings.local.json` and `.mcp.json` — add `.mcp.json` to your
36
+ `.gitignore`, since it holds a machine-specific path.
33
37
 
34
- ```
35
- you send a prompt
36
- │
37
- ├─ 1. save the previous turn
38
- │ read new lines from the session transcript
39
- │ keep turns that changed something
40
- │ store title + reasoning + files, with an embedding
41
- │
42
- └─ 2. search memory using your prompt
43
- inject the best match above your message
44
- ```
38
+ ## Map your code
45
39
 
46
- Both steps are hooks, so they always run. Nothing depends on Claude deciding to
47
- look something up.
40
+ ```bash
41
+ claude-db scan
48
42
 
49
- Install also writes a short standing instruction into `CLAUDE.local.md` (or
50
- `~/.claude/CLAUDE.md` for a machine-wide install), telling Claude to search
51
- memory before asking you to re-explain something. Hook output is context the
52
- agent may or may not act on; a memory file is a rule for the whole session,
53
- which is what makes recall the default rather than something you have to ask
54
- for. `claude-db uninstall` takes the block back out.
43
+ claude-db usages --mode explain resolveProject
44
+ claude-db usages --mode path cmdScan observationId
45
+ ```
55
46
 
56
- **What gets saved.** One observation per turn, and only if that turn edited a
57
- file or ran a real command. Questions, `grep`, and "ok" are skipped. A busy day
58
- produces 10 to 20 rows, not hundreds.
47
+ Claude gets the same four modes through MCP: `text` (a live grep, no scan
48
+ needed), `usages`, `explain` and `path`. Answers re-check the working tree
49
+ before replying, so they never report a line the source has moved past.
59
50
 
60
- **What gets injected.** Recent session summaries at startup, plus the single
61
- best match in full on each prompt. Roughly 350 tokens when something relevant
62
- exists, zero when it doesn't.
51
+ Works out of the box on TypeScript, TSX, JavaScript, Python, Go and Rust — the
52
+ parser ships with the package, so there is nothing else to install.
63
53
 
64
- **What search returns.** An id, kind, date, title and one line of the matching
65
- body — enough to tell two similarly-titled rows apart without expanding either.
66
- Full bodies come only from `get_observations`, for ids you picked.
54
+ ## Use another database
67
55
 
68
- An example of one stored memory:
56
+ SQLite by default, at `~/.claude-memory/memory.db`. No setup, no network. Point
57
+ it elsewhere to share memory across machines:
69
58
 
59
+ ```bash
60
+ claude-db use "mongodb+srv://user:pass@cluster.mongodb.net/memory"
61
+ claude-db use "postgres://user:pass@host:5432/memory"
70
62
  ```
71
- [decision] Chose WebSocket over polling for live order updates
72
-
73
- Asked: the order feed keeps dropping
74
63
 
75
- Polling at 3s hammered the API and still lagged behind. Switched to a
76
- WebSocket subscription with exponential backoff and a replay flag, so no
77
- order is missed during a drop.
78
-
79
- Files: src/ws/client.ts, src/ws/reconnect.ts
80
- Ran: Test run: pnpm test
81
- ```
64
+ Install the driver you need (`npm install mongodb` or `pg`); neither ships by
65
+ default.
82
66
 
83
67
  ## Commands
84
68
 
85
69
  `cdb` is a shorter alias for all of them.
86
70
 
87
- | Command | What it does |
88
- | --- | --- |
89
- | `claude-db install [--project]` | Register hooks and the MCP server |
90
- | `claude-db uninstall [--project]` | Remove them, keeping your memory |
91
- | `claude-db status` | Is it wired up, and when did it last record anything |
92
- | `claude-db doctor [--deep]` | Resolved config; `--deep` proves a full round trip |
93
- | `claude-db search [--all] [--tag <name>] <query>` | Search this project's memory, or every project |
94
- | `claude-db remember [--key <name>] <text>` | Record a rule outright, e.g. "always use pnpm here" |
95
- | `claude-db forget <id>` | Delete specific observations by id |
96
- | `claude-db seed --from-git` | Fill a cold memory from this repo's history |
97
- | `claude-db usages [--regex] <symbol>` | Find real usages via `git grep`, live — not a stored index |
98
- | `claude-db stats` | What this project's memory is made of |
99
- | `claude-db projects` | Every project with memory stored |
100
- | `claude-db merge [<path>]` | Move memory from an old project path onto this one |
101
- | `claude-db use <url>` | Switch database and verify it |
102
- | `claude-db sync <url>` | Two-way merge with another database |
103
- | `claude-db flush` | Re-ingest every transcript for this project |
104
- | `claude-db export [--all]` | Dump memory as JSONL, for backup or migration |
105
- | `claude-db import <file>` | Load a dump back in; safe to repeat |
106
- | `claude-db reembed` | Re-embed everything with the current model |
107
- | `claude-db prune --older-than <days>` | Delete old memory (dry run without `--yes`) |
108
- | `claude-db reset [--project] --yes` | Delete memory (dry run without `--yes`) |
71
+ | Command | What it does |
72
+ | ------------------------------------------------- | ------------------------------------------------------ |
73
+ | `claude-db install [--project]` | Register hooks and the MCP server |
74
+ | `claude-db uninstall [--project]` | Remove them, keeping your memory |
75
+ | `claude-db status` | Is it wired up, and when did it last record anything |
76
+ | `claude-db doctor [--deep]` | Resolved config; `--deep` proves a full round trip |
77
+ | `claude-db search [--all] [--tag <name>] <query>` | Search this project's memory, or every project |
78
+ | `claude-db remember [--key <name>] <text>` | Record a rule outright, e.g. "always use pnpm here" |
79
+ | `claude-db forget <id>` | Delete specific observations by id |
80
+ | `claude-db seed --from-git` | Fill a cold memory from this repo's history |
81
+ | `claude-db scan [--force]` | Build the code graph for this repo |
82
+ | `claude-db usages [--mode <m>] <symbol>` | What uses a symbol: live `git grep`, or the code graph |
83
+ | `claude-db stats` | What this project's memory is made of |
84
+ | `claude-db projects` | Every project with memory stored |
85
+ | `claude-db merge [<path>]` | Move memory from an old project path onto this one |
86
+ | `claude-db use <url>` | Switch database and verify it |
87
+ | `claude-db sync <url>` | Two-way merge with another database |
88
+ | `claude-db flush` | Re-ingest every transcript for this project |
89
+ | `claude-db export [--all]` | Dump memory as JSONL, for backup or migration |
90
+ | `claude-db import <file>` | Load a dump back in; safe to repeat |
91
+ | `claude-db reembed` | Re-embed everything with the current model |
92
+ | `claude-db prune --older-than <days>` | Delete old memory (dry run without `--yes`) |
93
+ | `claude-db reset [--project] --yes` | Delete memory (dry run without `--yes`) |
109
94
 
110
95
  Install also adds a `/cdb-scan` skill: run it once on an existing project and
111
- Claude surveys the codebase into memory — stack, layout, conventions,
112
- workflows — so search has something to find before you have any history. Those
113
- notes are tagged `inferred`, because they are a reading of the code rather than
114
- a record of what happened.
115
-
116
- `--project` scopes to one repo instead of every project on the machine. It
117
- writes `.claude/settings.local.json` and `.mcp.json` — add `.mcp.json` to your
118
- `.gitignore`, since it holds a machine-specific path.
119
-
120
- ## Bring your own database
121
-
122
- SQLite by default, at `~/.claude-memory/memory.db`. No setup, no network.
123
-
124
- Only needed if you want memory shared across machines:
125
-
126
- ```bash
127
- claude-db use "mongodb+srv://user:pass@cluster.mongodb.net/memory"
128
- claude-db use "postgres://user:pass@host:5432/memory"
129
- ```
130
-
131
- The connection string picks the backend. Install the driver you need
132
- (`npm install mongodb` or `pg`); neither ships by default. `CLAUDE_DB_URL`
133
- overrides the config file if you prefer an env var.
134
-
135
- Search is hybrid — keyword plus vector — on all three. Memory is partitioned by
136
- project path, so one database serves every repo you work in.
96
+ Claude maps the codebase into memory, so search has something to find before
97
+ you have any history.
137
98
 
138
99
  ## Requirements
139
100
 
@@ -150,13 +111,20 @@ Nothing leaves your machine unless you point it at a remote database.
150
111
  in `<private>...</private>` is stripped, and API keys and tokens are redacted
151
112
  before anything is written.
152
113
 
114
+ ## Documentation
115
+
116
+ - [How it works](./docs/how-it-works.md) — what gets captured and injected, how
117
+ the code graph is built and kept current, and how the database backends differ
118
+ - [Changelog](./CHANGELOG.md)
119
+
153
120
  ## Development
154
121
 
155
122
  ```bash
156
123
  npm install
157
124
  npm run build
158
- npm test # 87 checks
125
+ npm test # 263 checks
159
126
  npm run try # simulate a session, touches nothing
127
+ npm run format
160
128
  ```
161
129
 
162
130
  Releases publish from CI on a version tag:
@@ -1,20 +1,6 @@
1
1
  import type { ObservationKind } from '../types.js';
2
2
  export interface CommandClassification {
3
3
  kind: ObservationKind;
4
- /** Short human label used as the observation title. */
5
4
  label: string;
6
5
  }
7
- /**
8
- * Decides whether a shell command is worth remembering.
9
- *
10
- * Agents run far more commands to *look* than to *change*, and the looking is
11
- * worthless later: nobody needs to recall that you grepped for easing curves
12
- * three weeks ago. Capturing it crowds out the handful that genuinely mattered.
13
- *
14
- * So this is an allowlist of consequential operations rather than a blocklist
15
- * of exploration. Exploration is unbounded in variety and impossible to
16
- * enumerate; the operations that change project state are a short, stable list.
17
- *
18
- * Returns null for anything unrecognised, which means "do not store".
19
- */
20
6
  export declare function classifyCommand(command: string): CommandClassification | null;