claude-db 0.4.0 → 0.5.0

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