claude-db 0.4.1 → 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 -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/dist/cli/index.js CHANGED
@@ -1,35 +1,19 @@
1
1
  #!/usr/bin/env node
2
- import { randomUUID } from 'node:crypto';
3
- import { readFileSync, rmSync, statSync } from 'node:fs';
4
- import { basename, dirname, join, resolve } from 'node:path';
5
- import { fileURLToPath } from 'node:url';
6
- import { embedObservations, flushSession, remember, observationsFromGit, redact, resetCursor, sweepCursors, transcriptsFor, } from '../capture/index.js';
7
- import { findUsages, formatUsages } from '../usages/index.js';
8
- import { createContext } from '../context.js';
9
- import { createStore } from '../store/index.js';
10
- import { CONFIG_DIR, CONFIG_PATH, loadConfig, saveConfig } from '../config/index.js';
11
- import { assertStableLocation, install, instructionsPathFor, mcpPathFor, settingsPathFor, skillPathFor, uninstall, } from './install.js';
12
- import { resolveProject } from '../util/project.js';
13
- import { checkForUpdate, packageVersion } from '../update.js';
2
+ import { scopeFrom } from './args.js';
3
+ import { usage } from './usage.js';
4
+ import { cmdInstall, cmdStatus, cmdUninstall } from './commands/setup.js';
5
+ import { cmdUse } from './commands/use.js';
6
+ import { cmdDoctor } from './commands/doctor.js';
7
+ import { cmdSync } from './commands/sync.js';
8
+ import { cmdForget, cmdRemember, cmdSearch } from './commands/memory.js';
9
+ import { cmdExport, cmdImport, cmdPrune, cmdReembed } from './commands/transfer.js';
10
+ import { cmdMerge, cmdProjects, cmdStats } from './commands/insight.js';
11
+ import { cmdFlush, cmdReset, cmdUpdate } from './commands/maintain.js';
12
+ import { cmdScan, cmdUsages } from './commands/graph.js';
13
+ import { cmdSeed } from './commands/seed.js';
14
14
  import { silenceSqliteWarning } from '../util/warnings.js';
15
- import { toShortId } from '../util/shortid.js';
16
15
  silenceSqliteWarning();
17
- const DIST_DIR = resolve(dirname(fileURLToPath(import.meta.url)), '..');
18
- // Declared above the command switch below, which runs before the rest of this
19
- // module's bindings initialise.
20
- const BATCH = 500;
21
- /**
22
- * How far capture may lag the work before it counts as broken.
23
- *
24
- * Not every turn produces an observation — a day of questions legitimately
25
- * records nothing — so a tight threshold would cry wolf. Two full days of
26
- * activity with nothing written is the shape every silent failure so far had.
27
- */
28
- const STALL_MS = 48 * 60 * 60 * 1000;
29
16
  const [command, ...args] = process.argv.slice(2);
30
- // Every command runs inside this. A driver that cannot reach its database
31
- // rejects deep inside an adapter, and with nothing catching it the CLI printed
32
- // a twenty-line Node stack trace at the user instead of saying what went wrong.
33
17
  try {
34
18
  await run();
35
19
  }
@@ -99,6 +83,9 @@ async function run() {
99
83
  case 'usages':
100
84
  await cmdUsages(args);
101
85
  break;
86
+ case 'scan':
87
+ await cmdScan(args);
88
+ break;
102
89
  case 'sync':
103
90
  await cmdSync(args);
104
91
  break;
@@ -106,1055 +93,3 @@ async function run() {
106
93
  usage();
107
94
  }
108
95
  }
109
- /**
110
- * Fills a cold memory from the history the repository already holds.
111
- *
112
- * The first weeks after an install are the worst time to be asking anyone to
113
- * trust this: there is nothing in it, so every search comes back empty and the
114
- * habit never forms. Git history is the one source available on day one, and
115
- * unlike a generated summary it records what actually happened.
116
- */
117
- async function cmdSeed(argv) {
118
- if (!argv.includes('--from-git')) {
119
- console.error('Usage: claude-db seed --from-git [--limit <n>]');
120
- process.exit(1);
121
- }
122
- const limit = Number(valueOf(argv, '--limit') ?? 500);
123
- if (!Number.isFinite(limit) || limit <= 0) {
124
- console.error('--limit must be a positive number of commits.');
125
- process.exit(1);
126
- }
127
- const project = resolveProject(undefined);
128
- let observations;
129
- try {
130
- observations = observationsFromGit(project, limit);
131
- }
132
- catch (error) {
133
- console.error(`Could not read git history: ${error instanceof Error ? error.message.split('\n')[0] : String(error)}`);
134
- process.exit(1);
135
- }
136
- if (observations.length === 0) {
137
- console.log(`No usable commits found in ${project}.`);
138
- console.log('Merges, releases and commits touching no files are skipped.');
139
- return;
140
- }
141
- const ctx = await createContext();
142
- try {
143
- for (let i = 0; i < observations.length; i += BATCH) {
144
- const batch = observations.slice(i, i + BATCH);
145
- await embedObservations(ctx, batch);
146
- await ctx.store.insertObservations(batch);
147
- }
148
- }
149
- finally {
150
- await ctx.close();
151
- }
152
- // Ids come from the commit sha, so this is safe to repeat as history grows.
153
- console.log(`Seeded ${observations.length} observation(s) from git history.`);
154
- console.log(`Oldest: ${new Date(observations[observations.length - 1]?.createdAt ?? 0).toISOString().slice(0, 10)}`);
155
- }
156
- /**
157
- * Live `git grep`, not a database lookup — the only command with no
158
- * `createContext()` call, since it touches no store and no embedder.
159
- *
160
- * Never a persisted index: this project has already shipped three
161
- * silent-staleness bugs, and a symbol index that drifts from an edit is the
162
- * same failure shape. Re-deriving the answer from the current source on every
163
- * call means there is nothing to invalidate.
164
- */
165
- async function cmdUsages(argv) {
166
- const regex = argv.includes('--regex');
167
- const path = valueOf(argv, '--path');
168
- const context = Number(valueOf(argv, '--context') ?? 0);
169
- const limit = Number(valueOf(argv, '--limit') ?? 100);
170
- const symbol = withoutFlags(argv, ['--path', '--context', '--limit'])
171
- .filter((arg) => arg !== '--regex')
172
- .join(' ')
173
- .trim();
174
- if (!symbol) {
175
- console.error('Usage: claude-db usages [--regex] [--context <n>] [--path <dir>] [--limit <n>] <symbol>');
176
- process.exit(1);
177
- }
178
- if (!Number.isFinite(context) || context < 0) {
179
- console.error('--context must be a non-negative number.');
180
- process.exit(1);
181
- }
182
- if (!Number.isFinite(limit) || limit <= 0) {
183
- console.error('--limit must be a positive number.');
184
- process.exit(1);
185
- }
186
- console.log(formatUsages(findUsages({ symbol, regex, context, limit, ...(path ? { path } : {}) })));
187
- }
188
- /**
189
- * Two-way merge with another database.
190
- *
191
- * `export`/`import` only ever moves memory one way, which makes the second
192
- * machine a copy rather than a peer. Content-derived ids make the real thing
193
- * nearly free: an id present on one side and not the other is, by construction,
194
- * memory the other side has never seen, so the merge needs no clocks, no
195
- * conflict rules and no ordering.
196
- */
197
- async function cmdSync(argv) {
198
- const url = argv.find((arg) => typeof arg === 'string' && !arg.startsWith('-'));
199
- const confirmed = argv.includes('--yes') || argv.includes('-y');
200
- if (!url) {
201
- console.error('Usage: claude-db sync <connection-string> [--yes]');
202
- process.exit(1);
203
- }
204
- const local = await createContext();
205
- if (local.config.database === url) {
206
- await local.close();
207
- console.error('That is the database memory already uses.');
208
- process.exit(1);
209
- }
210
- const remote = await createStore(url);
211
- try {
212
- await remote.init();
213
- // Ids only from the first pass. Holding both databases in memory at once
214
- // is what would stop this working on the shared backend it exists for.
215
- const localIds = new Set();
216
- await eachRemoteObservation(local.store, (batch) => {
217
- for (const obs of batch)
218
- localIds.add(obs.id);
219
- });
220
- const remoteIds = new Set();
221
- let pulled = 0;
222
- await eachRemoteObservation(remote, async (batch) => {
223
- for (const obs of batch)
224
- remoteIds.add(obs.id);
225
- const fresh = batch.filter((obs) => !localIds.has(obs.id));
226
- if (fresh.length === 0)
227
- return;
228
- pulled += fresh.length;
229
- if (confirmed)
230
- await local.store.insertObservations(fresh);
231
- });
232
- let pushed = 0;
233
- await eachRemoteObservation(local.store, async (batch) => {
234
- const fresh = batch.filter((obs) => !remoteIds.has(obs.id));
235
- if (fresh.length === 0)
236
- return;
237
- pushed += fresh.length;
238
- if (confirmed)
239
- await remote.insertObservations(fresh);
240
- });
241
- if (!confirmed) {
242
- console.log(`This would pull ${pulled} and push ${pushed} observation(s).`);
243
- console.log('\nNothing was transferred. Re-run with --yes to confirm.');
244
- return;
245
- }
246
- // Sessions carry the recap injected at SessionStart, so memory that
247
- // arrives without them reads as a pile of turns with no shape.
248
- const sessions = await syncSessions(local.store, remote);
249
- console.log(`Pulled ${pulled}, pushed ${pushed}, and reconciled ${sessions} session(s).`);
250
- }
251
- finally {
252
- await remote.close();
253
- await local.close();
254
- }
255
- }
256
- /** Copies session records both ways for every project either side knows. */
257
- async function syncSessions(local, remote) {
258
- const projects = new Set();
259
- for (const store of [local, remote]) {
260
- for (const entry of await store.listProjects())
261
- projects.add(entry.project);
262
- }
263
- let moved = 0;
264
- for (const project of projects) {
265
- for (const [from, to] of [[local, remote], [remote, local]]) {
266
- for (const session of await from.recentSessions(project, 1000)) {
267
- if (await to.getSession(session.id))
268
- continue;
269
- await to.upsertSession(session);
270
- moved += 1;
271
- }
272
- }
273
- }
274
- return moved;
275
- }
276
- /** `eachObservation` against an arbitrary store rather than the local context. */
277
- async function eachRemoteObservation(store, visit) {
278
- let after = 0;
279
- for (;;) {
280
- const batch = await store.list({ after, limit: BATCH });
281
- if (batch.length === 0)
282
- return;
283
- await visit(batch);
284
- const last = batch[batch.length - 1];
285
- if (!last)
286
- return;
287
- after = last.createdAt === after ? after + 1 : last.createdAt;
288
- if (batch.length < BATCH)
289
- return;
290
- }
291
- }
292
- /** Shows how memory is partitioned, and which partition you are currently in. */
293
- async function cmdProjects() {
294
- const here = resolveProject(undefined);
295
- const ctx = await createContext();
296
- try {
297
- const projects = await ctx.store.listProjects();
298
- if (projects.length === 0) {
299
- console.log('No memory stored yet.');
300
- return;
301
- }
302
- console.log(`database: ${ctx.config.database}\n`);
303
- for (const entry of projects) {
304
- const marker = entry.project === here ? '*' : ' ';
305
- const date = new Date(entry.lastActive).toISOString().slice(0, 10);
306
- console.log(`${marker} ${String(entry.observations).padStart(5)} ${date} ${entry.project}`);
307
- }
308
- console.log('\n* is the project you are in now. Searches only ever see one row.');
309
- }
310
- finally {
311
- await ctx.close();
312
- }
313
- }
314
- /**
315
- * Re-keys memory recorded under an old project path onto this one.
316
- *
317
- * Memory used to be keyed on the exact directory the agent was launched in, so
318
- * anyone who worked from `repo/frontend` accumulated a second, disjoint memory.
319
- * Keying on the repository root fixes that going forward but strands whatever
320
- * is already under the old path, and nothing about it is visible: the memory
321
- * simply does not appear.
322
- *
323
- * Re-inserting rather than issuing an UPDATE is deliberate. Observation ids are
324
- * content-derived and independent of the project, so writing the same rows with
325
- * a new project overwrites in place, and every derived field that depends on the
326
- * project — the FTS scope token above all — is recomputed on the way through.
327
- */
328
- async function cmdMerge(argv) {
329
- const into = resolveProject(undefined);
330
- const confirmed = argv.includes('--yes') || argv.includes('-y');
331
- const given = argv.find((arg) => typeof arg === 'string' && !arg.startsWith('-'));
332
- const ctx = await createContext();
333
- try {
334
- if (!given) {
335
- await listShards(ctx, into);
336
- return;
337
- }
338
- // Resolved but deliberately not run through resolveProject: that maps a
339
- // subdirectory to the repository root, which is the very key being merged
340
- // *into*, so the source would resolve to the destination and match nothing.
341
- const from = resolve(given);
342
- if (from === into) {
343
- console.error('Source and destination are the same project.');
344
- process.exit(1);
345
- }
346
- let moved = 0;
347
- const total = await eachObservation(ctx, { project: from }, async (batch) => {
348
- if (!confirmed)
349
- return;
350
- await ctx.store.insertObservations(batch.map((obs) => ({ ...obs, project: into })));
351
- moved += batch.length;
352
- });
353
- if (total === 0) {
354
- console.error(`No memory stored under ${from}.`);
355
- console.error('Run `claude-db projects` to see the exact paths in this database.');
356
- process.exit(1);
357
- }
358
- if (!confirmed) {
359
- console.log(`This would move ${total} observation(s):`);
360
- console.log(` from ${from}`);
361
- console.log(` into ${into}`);
362
- console.log('\nNothing was moved. Re-run with --yes to confirm.');
363
- return;
364
- }
365
- // Sessions carry the recap injected at SessionStart, so they follow their
366
- // observations. Only summarised ones are worth moving; the rest go with
367
- // the cleanup below.
368
- for (const session of await ctx.store.recentSessions(from, 1000)) {
369
- await ctx.store.upsertSession({ ...session, project: into });
370
- }
371
- const swept = await ctx.store.remove({ project: from });
372
- console.log(`Moved ${moved} observation(s) into ${into}.`);
373
- if (swept > 0)
374
- console.log(`Cleaned up ${swept} leftover row(s) under the old path.`);
375
- }
376
- finally {
377
- await ctx.close();
378
- }
379
- }
380
- /** Projects in this database that sit underneath the current one. */
381
- async function listShards(ctx, into) {
382
- const shards = (await ctx.store.listProjects()).filter((entry) => entry.project !== into && entry.project.startsWith(`${into}/`));
383
- if (shards.length === 0) {
384
- console.log(`No memory is stored under a subdirectory of ${into}.`);
385
- console.log('Nothing to merge.');
386
- return;
387
- }
388
- console.log(`Memory recorded under subdirectories of ${into}:\n`);
389
- for (const shard of shards) {
390
- console.log(` ${String(shard.observations).padStart(5)} ${shard.project}`);
391
- }
392
- console.log('\nMerge one in with:');
393
- console.log(` claude-db merge ${shards[0]?.project} --yes`);
394
- }
395
- /**
396
- * Deletes stored memory. Scoped to this project with `--project`, otherwise
397
- * everything in the configured database.
398
- *
399
- * Goes through the adapter rather than deleting a file, because on a shared
400
- * Postgres or Mongo there is no file to delete and removing the local config
401
- * directory would silently do nothing.
402
- */
403
- async function cmdReset(argv) {
404
- const scoped = argv.includes('--project') || argv.includes('-p');
405
- const confirmed = argv.includes('--yes') || argv.includes('-y');
406
- const project = resolveProject(undefined);
407
- const ctx = await createContext();
408
- try {
409
- const target = scoped ? project : ctx.config.database;
410
- // Confirmation is checked before the destructive call, not after: a dry
411
- // run that deletes is worse than having no dry run at all.
412
- if (!confirmed) {
413
- console.log(`This would delete ${scoped ? 'this project\'s' : 'ALL'} memory from:`);
414
- console.log(` ${target}`);
415
- console.log('\nNothing was deleted. Re-run with --yes to confirm.');
416
- return;
417
- }
418
- const deleted = await ctx.store.remove(scoped ? { project } : {});
419
- console.log(`Deleted ${deleted} observation(s) from ${target}.`);
420
- if (!scoped) {
421
- clearLocalState();
422
- console.log('Cleared transcript cursors so the next flush starts clean.');
423
- }
424
- }
425
- finally {
426
- await ctx.close();
427
- }
428
- }
429
- /**
430
- * Transcript cursors are local scratch state keyed to a database that no
431
- * longer has the rows. Leaving them behind makes the next flush skip turns it
432
- * believes were already stored.
433
- */
434
- function clearLocalState() {
435
- rmSync(join(CONFIG_DIR, 'cursors'), { recursive: true, force: true });
436
- }
437
- /**
438
- * Ingests every transcript for this project, including sessions still open.
439
- *
440
- * Recovery path for anything the hooks missed: sessions that predate the
441
- * install, sessions that were force-quit, or a database that was wiped. Safe
442
- * to run repeatedly because observation ids are content-derived.
443
- */
444
- async function cmdFlush() {
445
- const project = resolveProject(undefined);
446
- const transcripts = transcriptsFor(project);
447
- if (transcripts.length === 0) {
448
- console.error(`No transcripts found for ${project}`);
449
- process.exit(1);
450
- }
451
- const ctx = await createContext();
452
- let total = 0;
453
- try {
454
- for (const path of transcripts) {
455
- const sessionId = basename(path, '.jsonl');
456
- // Ignore any stored cursor and the stored recap: a manual flush is asking
457
- // for a full re-read, so both are rebuilt rather than extended.
458
- resetCursor(sessionId);
459
- const result = await flushSession(ctx, sessionId, project, path, true);
460
- if (result.observations > 0) {
461
- console.log(`${sessionId.slice(0, 8)} ${String(result.observations).padStart(4)} observations`);
462
- total += result.observations;
463
- }
464
- }
465
- }
466
- finally {
467
- await ctx.close();
468
- }
469
- console.log(`\n${total} observations from ${transcripts.length} transcript(s).`);
470
- const swept = sweepCursors();
471
- if (swept > 0)
472
- console.log(`Swept ${swept} cursor(s) for transcripts that no longer exist.`);
473
- }
474
- /** `--project` limits the install to the current repo; default is machine-wide. */
475
- function scopeFrom(args) {
476
- return args.includes('--project') || args.includes('-p') ? 'project' : 'global';
477
- }
478
- async function cmdInstall(scope) {
479
- const project = resolveProject(undefined);
480
- try {
481
- assertStableLocation(DIST_DIR);
482
- }
483
- catch (error) {
484
- console.error(error instanceof Error ? error.message : String(error));
485
- process.exit(1);
486
- }
487
- const settingsPath = install(DIST_DIR, scope, project);
488
- const ctx = await createContext();
489
- await ctx.close();
490
- console.log(`Scope : ${scope === 'project' ? `this project only (${project})` : 'all projects on this machine'}`);
491
- console.log(`Settings : ${settingsPath}`);
492
- console.log(`Guidance : ${instructionsPathFor(scope, project)}`);
493
- console.log(`Skill : ${skillPathFor(scope, project)} (/cdb-scan)`);
494
- console.log(`Config : ${CONFIG_PATH}`);
495
- console.log(`Database : ${ctx.config.database}`);
496
- console.log('\nRestart Claude Code to activate.');
497
- if (scope === 'project') {
498
- warnIfCommittable(project);
499
- console.log('Remove later with: claude-db uninstall --project');
500
- }
501
- }
502
- /**
503
- * `.mcp.json` is conventionally committed so a team shares MCP servers, but
504
- * ours points at an absolute path under this user's home directory. Committing
505
- * it hands teammates a server that cannot start. Warn rather than silently
506
- * editing .gitignore, since that file is the user's to manage.
507
- */
508
- function warnIfCommittable(project) {
509
- const gitignore = join(project, '.gitignore');
510
- let ignored = false;
511
- try {
512
- ignored = readFileSync(gitignore, 'utf8')
513
- .split('\n')
514
- .some((line) => line.trim().replace(/^\//, '') === '.mcp.json');
515
- }
516
- catch {
517
- return; // not a git repo, or no .gitignore: nothing to warn about
518
- }
519
- if (ignored)
520
- return;
521
- console.log('\nNote: .mcp.json holds an absolute path to this machine.');
522
- console.log('It would break for anyone else if committed. To keep it local:');
523
- console.log(" echo '.mcp.json' >> .gitignore");
524
- }
525
- function cmdUninstall(scope) {
526
- const project = resolveProject(undefined);
527
- const path = uninstall(DIST_DIR, scope, project);
528
- console.log(path
529
- ? `Removed hooks and MCP server from ${path}`
530
- : 'Nothing to remove: no settings file found.');
531
- console.log('Memory itself is untouched. Delete it with: rm -rf ~/.claude-memory');
532
- }
533
- /** Answers "is it actually wired up, and does it have anything in it?" */
534
- async function cmdStatus() {
535
- const project = resolveProject(undefined);
536
- const ctx = await createContext();
537
- try {
538
- const sessions = await ctx.store.recentSessions(project, 100);
539
- // Reading the database says nothing about whether the hooks were ever
540
- // registered, and "0 sessions" looks identical whether you have not worked
541
- // yet or never installed. Check both and say which.
542
- const wiring = [
543
- { scope: 'project', label: 'this project' },
544
- { scope: 'global', label: 'all projects' },
545
- ].map((entry) => ({
546
- ...entry,
547
- path: settingsPathFor(entry.scope, project),
548
- installed: isInstalled(settingsPathFor(entry.scope, project)),
549
- }));
550
- const active = wiring.filter((entry) => entry.installed);
551
- console.log(`project : ${project}`);
552
- console.log(`database : ${ctx.config.database}`);
553
- console.log(`hooks : ${active.length > 0
554
- ? active.map((entry) => entry.label).join(' + ')
555
- : 'NOT INSTALLED'}`);
556
- const mcpFile = [mcpPathFor('project', project), mcpPathFor('global', project)].find((candidate) => fileMentions(candidate, resolve(DIST_DIR, 'mcp', 'server.js')));
557
- console.log(`mcp : ${mcpFile ? `registered (${mcpFile})` : 'NOT REGISTERED'}`);
558
- console.log(`sessions : ${sessions.length} recorded for this project`);
559
- const saved = (await ctx.store.listProjects()).find((entry) => entry.project === project);
560
- const lastSaved = saved?.lastActive ?? 0;
561
- const worked = workedAt(project);
562
- console.log(`recorded : ${lastSaved > 0 ? ago(lastSaved) : 'never'}`);
563
- if (active.length === 0) {
564
- console.log('\nHooks are not registered, so nothing will ever be captured.');
565
- console.log('Run this from the project you want to track:');
566
- console.log(' claude-db install --project');
567
- }
568
- else if (hasStalled(lastSaved, worked)) {
569
- console.log(`\nCapture looks stalled. This project was worked in ${ago(worked.last)},`);
570
- console.log(lastSaved > 0
571
- ? `but the newest memory is from ${ago(lastSaved)}.`
572
- : 'but nothing has ever been recorded for it.');
573
- console.log('Nothing reports this on its own: hooks swallow their errors so a');
574
- console.log('memory layer can never break a session. Check it end to end with:');
575
- console.log(' claude-db doctor --deep');
576
- }
577
- else if (sessions.length === 0) {
578
- console.log('\nInstalled, but nothing recorded yet. Memory is written as you');
579
- console.log('work, on every prompt, and only for turns that changed something.');
580
- console.log('If you installed just now, restart Claude Code first.');
581
- }
582
- }
583
- finally {
584
- await ctx.close();
585
- }
586
- }
587
- /** When this project's transcripts were first and last appended to. */
588
- function workedAt(project) {
589
- let first = Number.POSITIVE_INFINITY;
590
- let last = 0;
591
- for (const path of transcriptsFor(project)) {
592
- try {
593
- const { mtimeMs } = statSync(path);
594
- first = Math.min(first, mtimeMs);
595
- last = Math.max(last, mtimeMs);
596
- }
597
- catch {
598
- // Deleted between listing and stat; nothing to learn from it.
599
- }
600
- }
601
- return { first: Number.isFinite(first) ? first : 0, last };
602
- }
603
- /**
604
- * Work happened and capture didn't — the signal every silent failure leaves.
605
- *
606
- * Measured from the last save, except when there has never been one: then the
607
- * baseline is the *first* transcript, so an install done ten minutes ago reads
608
- * as new rather than broken, while a project worked in for days with an empty
609
- * database reads as broken, which it is.
610
- */
611
- function hasStalled(lastSaved, worked) {
612
- if (worked.last === 0)
613
- return false;
614
- return worked.last > (lastSaved > 0 ? lastSaved : worked.first) + STALL_MS;
615
- }
616
- function ago(when) {
617
- const minutes = Math.max(0, Math.round((Date.now() - when) / 60_000));
618
- const date = new Date(when).toISOString().slice(0, 10);
619
- if (minutes < 90)
620
- return `${minutes} minute(s) ago`;
621
- const hours = Math.round(minutes / 60);
622
- if (hours < 48)
623
- return `${hours} hour(s) ago (${date})`;
624
- return `${Math.round(hours / 24)} day(s) ago (${date})`;
625
- }
626
- /** True when a settings file contains one of our hook commands. */
627
- function isInstalled(settingsPath) {
628
- return fileMentions(settingsPath, resolve(DIST_DIR, 'hooks', 'session-end.js'));
629
- }
630
- function fileMentions(path, needle) {
631
- try {
632
- return readFileSync(path, 'utf8').includes(needle);
633
- }
634
- catch {
635
- return false;
636
- }
637
- }
638
- /**
639
- * Points memory at a database, but only once it answers.
640
- *
641
- * Saving first and connecting second is how this used to work, and a typo or a
642
- * decommissioned host left the config pointing at nothing. The command crashed,
643
- * and so did every hook after it — so the damage surfaced on some later prompt,
644
- * far from the cause, as memory quietly recording nothing at all.
645
- */
646
- async function cmdUse(argv) {
647
- const force = argv.includes('--force');
648
- const uri = argv.find((arg) => typeof arg === 'string' && !arg.startsWith('-'));
649
- if (!uri) {
650
- console.error('Usage: claude-db use [--force] <connection-string>');
651
- process.exit(1);
652
- }
653
- let kind = '';
654
- let foreign = [];
655
- let rows = 0;
656
- try {
657
- const store = await createStore(uri);
658
- try {
659
- if (!(await store.ping()))
660
- throw new Error('connected, but it did not answer a ping');
661
- kind = store.kind;
662
- // Read before init(), which creates our two tables: after that there is
663
- // no way to tell an empty memory database from someone's application
664
- // database that we have just started writing into.
665
- foreign = await store.inventory();
666
- await store.init();
667
- rows = await countObservations(store);
668
- }
669
- finally {
670
- await store.close();
671
- }
672
- }
673
- catch (error) {
674
- console.error(`Could not reach that database: ${describe(error)}`);
675
- if (!force) {
676
- console.error('\nNothing was changed; memory still uses the previous database.');
677
- console.error('Re-run with --force to save it anyway.');
678
- process.exit(1);
679
- }
680
- }
681
- const config = loadConfig();
682
- const previous = config.database;
683
- config.database = uri;
684
- saveConfig(config);
685
- console.log(kind ? `Connected. Using ${kind}.` : 'Saved, unverified.');
686
- if (foreign.length > 0) {
687
- const shown = foreign.slice(0, 6).join(', ');
688
- console.log(`\nNote: this database already holds ${foreign.length} other table(s)/collection(s):`);
689
- console.log(` ${shown}${foreign.length > 6 ? ', ...' : ''}`);
690
- console.log('claude-db has added its own next to them. An application database is a');
691
- console.log('poor place to keep memory; point it elsewhere if that was not deliberate.');
692
- }
693
- if (kind && rows === 0)
694
- await warnAboutStranding(previous, uri);
695
- }
696
- async function countObservations(store) {
697
- return (await store.listProjects()).reduce((total, entry) => total + entry.observations, 0);
698
- }
699
- /**
700
- * Switching backends leaves everything already recorded behind, in silence.
701
- *
702
- * Observed twice in one day: `use` pointed at Atlas, then at Aiven, and each
703
- * time six hundred observations stayed in SQLite while the new backend started
704
- * empty. `export`/`import` has always solved it, but only for someone who
705
- * already knew there was something to solve.
706
- */
707
- async function warnAboutStranding(previous, uri) {
708
- if (!previous || previous === uri)
709
- return;
710
- let stranded = 0;
711
- try {
712
- const store = await createStore(previous);
713
- try {
714
- await store.init();
715
- stranded = await countObservations(store);
716
- }
717
- finally {
718
- await store.close();
719
- }
720
- }
721
- catch {
722
- return; // the old database is gone too; nothing to strand
723
- }
724
- if (stranded === 0)
725
- return;
726
- // The URL is shown only to identify which database, so its credentials are
727
- // stripped: this is exactly the string people paste without thinking.
728
- console.log(`\nThe database you just left (${redact(previous)})`);
729
- console.log(`still holds ${stranded} observation(s), and this one is empty. Nothing moves`);
730
- console.log('across on its own:');
731
- console.log(' claude-db use <the previous url> && claude-db export --all > memory.jsonl');
732
- console.log(' claude-db use <this url> && claude-db import memory.jsonl');
733
- }
734
- /** A driver error names the problem; these name the fix. */
735
- function describe(error) {
736
- const message = error instanceof Error ? error.message : String(error);
737
- if (/ENOTFOUND|EAI_AGAIN/.test(message)) {
738
- return `${message}\n(that host does not resolve — check the name, or whether the service still exists)`;
739
- }
740
- if (/self[- ]signed certificate|unable to verify the first certificate|SELF_SIGNED_CERT/i.test(message)) {
741
- return (`${message}\n(managed Postgres signs with its own CA, which node does not trust by ` +
742
- `default —\n append &sslmode=no-verify to the URL, or point &sslrootcert= at the CA ` +
743
- `file\n the provider gives you)`);
744
- }
745
- return message;
746
- }
747
- async function cmdDoctor(argv) {
748
- // No embedder timeout here: doctor is where you want to wait for a first
749
- // model download, so that the hooks afterwards find it cached.
750
- const base = loadConfig();
751
- const ctx = await createContext({
752
- embeddings: { ...base.embeddings, timeoutMs: 0 },
753
- });
754
- const reachable = await ctx.store.ping();
755
- // Report measured capability, not configured intent. Printing "384d" for an
756
- // embedder that cannot actually run is worse than printing nothing.
757
- const embedder = await ctx.embedder();
758
- const vectors = await probeEmbedder(embedder);
759
- console.log(`version : ${packageVersion()}`);
760
- console.log(`database : ${ctx.config.database}`);
761
- console.log(`adapter : ${ctx.store.kind}`);
762
- console.log(`reachable: ${reachable ? 'yes' : 'no'}`);
763
- console.log(`requested: embeddings.provider = ${ctx.config.embeddings.provider}`);
764
- console.log(`embedder : ${embedder.id} (${embedder.dimensions}d)`);
765
- console.log(`vectors : ${vectors}`);
766
- console.log(`search : ${vectors.startsWith('working') ? 'hybrid (keyword + vector)' : 'keyword only'}`);
767
- const healthy = argv.includes('--deep') ? await deepCheck(ctx) : true;
768
- await ctx.close();
769
- process.exit(reachable && healthy ? 0 : 1);
770
- }
771
- /**
772
- * Proves capture, search and recall work *now*, instead of proving the database
773
- * answers a ping.
774
- *
775
- * Every failure this tool has shipped was silent — hooks swallow their errors
776
- * so a memory layer can never break a session — and each one left `doctor`
777
- * reporting a healthy database it was no longer writing to. A round trip
778
- * through the real adapter, embedder and index is the only thing that can tell
779
- * the difference.
780
- */
781
- async function deepCheck(ctx) {
782
- const project = resolveProject(undefined);
783
- // A single opaque token: FTS tokenises on non-word characters, so hyphens
784
- // would split the canary into pieces other observations could match.
785
- const canary = `zz${randomUUID().replace(/-/g, '')}`;
786
- let ok = true;
787
- const step = (label, passed, detail = '') => {
788
- if (!passed)
789
- ok = false;
790
- console.log(` ${passed ? 'ok ' : 'FAIL'} ${label}${detail ? ` — ${detail}` : ''}`);
791
- };
792
- console.log('\ndeep check (writes one observation, then deletes it)');
793
- let id = '';
794
- try {
795
- const written = await remember(ctx, {
796
- project,
797
- kind: 'context',
798
- text: `claude-db self check ${canary}`,
799
- });
800
- id = written.id;
801
- step('write', true, toShortId(id));
802
- }
803
- catch (error) {
804
- step('write', false, error instanceof Error ? error.message : String(error));
805
- return false;
806
- }
807
- try {
808
- const found = await ctx.search.search({ text: canary, project, limit: 5 });
809
- step('search', found.some((entry) => entry.id === id), `${found.length} result(s)`);
810
- const [full] = await ctx.search.getObservations([id]);
811
- step('expand', full?.body.includes(canary) === true);
812
- }
813
- finally {
814
- // In a finally block so a failed search still takes the canary back out.
815
- const deleted = await ctx.store.remove({ ids: [id] });
816
- step('cleanup', deleted === 1, `${deleted} removed`);
817
- }
818
- return ok;
819
- }
820
- async function probeEmbedder(embedder) {
821
- if (embedder.dimensions === 0)
822
- return 'disabled';
823
- try {
824
- const [vector] = await embedder.embed(['connectivity probe']);
825
- return vector && vector.length > 0
826
- ? `working (${vector.length}d)`
827
- : 'unavailable (empty vector)';
828
- }
829
- catch (error) {
830
- return `unavailable (${error instanceof Error ? error.message.split('.')[0] : 'error'})`;
831
- }
832
- }
833
- async function cmdSearch(argv) {
834
- const all = argv.includes('--all');
835
- const tag = valueOf(argv, '--tag');
836
- const query = withoutFlags(argv, ['--tag']).filter((arg) => arg !== '--all').join(' ');
837
- if (!query.trim()) {
838
- console.error('Usage: claude-db search [--all] [--tag <name>] <query>');
839
- process.exit(1);
840
- }
841
- const ctx = await createContext();
842
- const results = await ctx.search.search({
843
- text: query,
844
- // Scoping is right for injection, but "where did I solve this before" is
845
- // inherently cross-project, and only the CLI can ask that question.
846
- ...(all ? {} : { project: resolveProject(undefined) }),
847
- ...(tag ? { tag } : {}),
848
- limit: 10,
849
- });
850
- // Same short-id format the MCP tools emit, so ids copied from either place
851
- // work in the other.
852
- for (const entry of results) {
853
- const date = new Date(entry.createdAt).toISOString().slice(0, 10);
854
- const where = all ? ` ${basename(entry.project)}` : '';
855
- console.log(`${toShortId(entry.id)} ${entry.kind.padEnd(10)} ${date}${where} ${entry.title}`);
856
- if (entry.snippet)
857
- console.log(` ${entry.snippet}`);
858
- }
859
- if (results.length === 0)
860
- console.log('No matching observations.');
861
- await ctx.close();
862
- }
863
- async function cmdRemember(argv) {
864
- const kind = valueOf(argv, '--kind');
865
- const key = valueOf(argv, '--key');
866
- const tag = valueOf(argv, '--tag');
867
- const text = withoutFlags(argv, ['--kind', '--key', '--tag']).join(' ').trim();
868
- if (!text) {
869
- console.error('Usage: claude-db remember [--kind <kind>] [--key <name>] [--tag <name>] <text>');
870
- process.exit(1);
871
- }
872
- const ctx = await createContext();
873
- try {
874
- const observation = await remember(ctx, {
875
- project: resolveProject(undefined),
876
- text,
877
- ...(kind ? { kind: kind } : {}),
878
- ...(key ? { key } : {}),
879
- ...(tag ? { tags: [tag] } : {}),
880
- });
881
- console.log(`Remembered ${toShortId(observation.id)} [${observation.kind}] ${observation.title}`);
882
- }
883
- finally {
884
- await ctx.close();
885
- }
886
- }
887
- async function cmdForget(argv) {
888
- const ids = argv.filter((arg) => typeof arg === 'string' && arg.length > 0);
889
- if (ids.length === 0) {
890
- console.error('Usage: claude-db forget <id> [id...]');
891
- process.exit(1);
892
- }
893
- const ctx = await createContext();
894
- try {
895
- // Shown before deleting: a short id is a prefix match, and the only way to
896
- // be sure it means what you think is to read the titles back.
897
- const doomed = await ctx.store.getObservations(ids);
898
- for (const obs of doomed) {
899
- console.log(` ${toShortId(obs.id)} [${obs.kind}] ${obs.title}`);
900
- }
901
- const deleted = await ctx.store.remove({ ids });
902
- console.log(deleted > 0 ? `Forgot ${deleted} observation(s).` : 'No match.');
903
- }
904
- finally {
905
- await ctx.close();
906
- }
907
- }
908
- /** Pages rather than loading everything: a shared database can be large. */
909
- async function eachObservation(ctx, filter, visit) {
910
- let after = 0;
911
- let total = 0;
912
- for (;;) {
913
- const batch = await ctx.store.list({ ...filter, after, limit: BATCH });
914
- if (batch.length === 0)
915
- return total;
916
- await visit(batch);
917
- total += batch.length;
918
- const last = batch[batch.length - 1];
919
- if (!last)
920
- return total;
921
- // createdAt is not unique, so a batch that lands entirely on one timestamp
922
- // would loop forever. Nudging past it drops at most a co-timestamped tail.
923
- after = last.createdAt === after ? after + 1 : last.createdAt;
924
- if (batch.length < BATCH)
925
- return total;
926
- }
927
- }
928
- async function cmdExport(argv) {
929
- const all = argv.includes('--all');
930
- const ctx = await createContext();
931
- try {
932
- const count = await eachObservation(ctx, all ? {} : { project: resolveProject(undefined) }, (batch) => {
933
- for (const obs of batch)
934
- process.stdout.write(`${JSON.stringify(obs)}\n`);
935
- });
936
- process.stderr.write(`${count} observation(s) exported.\n`);
937
- }
938
- finally {
939
- await ctx.close();
940
- }
941
- }
942
- async function cmdImport(path) {
943
- if (!path) {
944
- console.error('Usage: claude-db import <file.jsonl>');
945
- process.exit(1);
946
- }
947
- const lines = readFileSync(path, 'utf8').split('\n').filter((line) => line.trim().length > 0);
948
- const ctx = await createContext();
949
- let imported = 0;
950
- try {
951
- for (let i = 0; i < lines.length; i += BATCH) {
952
- const batch = lines
953
- .slice(i, i + BATCH)
954
- .map((line) => JSON.parse(line))
955
- .filter((obs) => typeof obs.id === 'string' && typeof obs.project === 'string');
956
- await ctx.store.insertObservations(batch);
957
- imported += batch.length;
958
- }
959
- }
960
- finally {
961
- await ctx.close();
962
- }
963
- // Ids are content-derived, so re-importing the same file is a no-op rather
964
- // than a second copy of every memory.
965
- console.log(`Imported ${imported} observation(s).`);
966
- }
967
- async function cmdPrune(argv) {
968
- const days = Number(valueOf(argv, '--older-than') ?? NaN);
969
- const kind = valueOf(argv, '--kind');
970
- const confirmed = argv.includes('--yes') || argv.includes('-y');
971
- const all = argv.includes('--all');
972
- if (!Number.isFinite(days) || days <= 0) {
973
- console.error('Usage: claude-db prune --older-than <days> [--kind <kind>] [--all] --yes');
974
- process.exit(1);
975
- }
976
- const before = Date.now() - days * 86_400_000;
977
- const filter = {
978
- before,
979
- ...(all ? {} : { project: resolveProject(undefined) }),
980
- ...(kind ? { kind } : {}),
981
- };
982
- const ctx = await createContext();
983
- try {
984
- if (!confirmed) {
985
- // Counted by paging rather than one unbounded query, and against the
986
- // same predicate the delete uses, so the dry run cannot disagree with it.
987
- let matching = 0;
988
- await eachObservation(ctx, all ? {} : { project: resolveProject(undefined) }, (batch) => {
989
- for (const obs of batch) {
990
- if (obs.createdAt < before && (!kind || obs.kind === kind))
991
- matching += 1;
992
- }
993
- });
994
- console.log(`This would delete ${matching} observation(s) older than ${days} day(s)` +
995
- `${kind ? ` of kind ${kind}` : ''}.`);
996
- console.log('\nNothing was deleted. Re-run with --yes to confirm.');
997
- return;
998
- }
999
- const deleted = await ctx.store.remove(filter);
1000
- console.log(`Pruned ${deleted} observation(s).`);
1001
- }
1002
- finally {
1003
- await ctx.close();
1004
- }
1005
- }
1006
- /**
1007
- * Re-embeds everything with the currently configured model.
1008
- *
1009
- * Installing @xenova/transformers changes the embedding space from 256d to
1010
- * 384d, and `cosine` refuses to compare across widths, so without this an
1011
- * upgrade makes existing memory *less* searchable rather than more.
1012
- */
1013
- async function cmdReembed() {
1014
- const base = loadConfig();
1015
- const ctx = await createContext({ embeddings: { ...base.embeddings, timeoutMs: 0 } });
1016
- try {
1017
- const embedder = await ctx.embedder();
1018
- if (embedder.dimensions === 0) {
1019
- console.error('No embedder available; nothing to do.');
1020
- process.exit(1);
1021
- }
1022
- let updated = 0;
1023
- let skipped = 0;
1024
- const scanned = await eachObservation(ctx, {}, async (batch) => {
1025
- const stale = batch.filter((obs) => obs.embedder !== embedder.id);
1026
- skipped += batch.length - stale.length;
1027
- if (stale.length === 0)
1028
- return;
1029
- await embedObservations(ctx, stale);
1030
- await ctx.store.insertObservations(stale);
1031
- updated += stale.length;
1032
- process.stderr.write(`\r${updated} re-embedded...`);
1033
- });
1034
- process.stderr.write('\r');
1035
- console.log(`Scanned ${scanned}, re-embedded ${updated} with ${embedder.id}` +
1036
- `${skipped > 0 ? `, ${skipped} already current` : ''}.`);
1037
- }
1038
- finally {
1039
- await ctx.close();
1040
- }
1041
- }
1042
- async function cmdStats() {
1043
- const project = resolveProject(undefined);
1044
- const ctx = await createContext();
1045
- try {
1046
- const kinds = new Map();
1047
- const tags = new Map();
1048
- let embedded = 0;
1049
- let earliest = Number.POSITIVE_INFINITY;
1050
- let latest = 0;
1051
- const total = await eachObservation(ctx, { project }, (batch) => {
1052
- for (const obs of batch) {
1053
- kinds.set(obs.kind, (kinds.get(obs.kind) ?? 0) + 1);
1054
- for (const tag of obs.tags)
1055
- tags.set(tag, (tags.get(tag) ?? 0) + 1);
1056
- if (obs.embedding && obs.embedding.length > 0)
1057
- embedded += 1;
1058
- earliest = Math.min(earliest, obs.createdAt);
1059
- latest = Math.max(latest, obs.createdAt);
1060
- }
1061
- });
1062
- if (total === 0) {
1063
- console.log(`No memory stored for ${project}.`);
1064
- return;
1065
- }
1066
- const day = (ms) => new Date(ms).toISOString().slice(0, 10);
1067
- console.log(`project : ${project}`);
1068
- console.log(`observations: ${total}`);
1069
- console.log(`range : ${day(earliest)} to ${day(latest)}`);
1070
- console.log(`embedded : ${embedded} of ${total}`);
1071
- console.log('\nby kind');
1072
- for (const [kind, n] of [...kinds].sort((a, b) => b[1] - a[1])) {
1073
- console.log(` ${String(n).padStart(5)} ${kind}`);
1074
- }
1075
- if (tags.size > 0) {
1076
- console.log('\nby area');
1077
- for (const [tag, n] of [...tags].sort((a, b) => b[1] - a[1]).slice(0, 10)) {
1078
- console.log(` ${String(n).padStart(5)} ${tag}`);
1079
- }
1080
- }
1081
- }
1082
- finally {
1083
- await ctx.close();
1084
- }
1085
- }
1086
- /**
1087
- * Also the entry point the SessionEnd hook spawns detached, with --quiet.
1088
- */
1089
- async function cmdUpdate(argv) {
1090
- const quiet = argv.includes('--quiet');
1091
- const config = loadConfig();
1092
- // An explicit `claude-db update` means now, whatever the config says about
1093
- // the background behaviour.
1094
- const mode = quiet ? config.updates : 'auto';
1095
- const result = await checkForUpdate(mode);
1096
- if (quiet)
1097
- return;
1098
- if (result.installed)
1099
- console.log(`Updated ${result.current} -> ${result.latest}.`);
1100
- else if (result.latest && result.latest !== result.current) {
1101
- console.log(`${result.latest} is available (running ${result.current}): ${result.reason}`);
1102
- }
1103
- else
1104
- console.log(`Up to date (${result.current}).`);
1105
- }
1106
- function valueOf(argv, flag) {
1107
- const index = argv.indexOf(flag);
1108
- return index >= 0 ? argv[index + 1] : undefined;
1109
- }
1110
- /** Everything that is not one of the named flags or its value. */
1111
- function withoutFlags(argv, flags) {
1112
- const dropped = new Set();
1113
- for (const flag of flags) {
1114
- const at = argv.indexOf(flag);
1115
- // Guarded: indexOf returns -1 for an absent flag, and dropping index 0
1116
- // silently ate the first word of the text being remembered.
1117
- if (at >= 0)
1118
- dropped.add(at).add(at + 1);
1119
- }
1120
- return argv.filter((arg, index) => typeof arg === 'string' && !dropped.has(index));
1121
- }
1122
- function usage() {
1123
- console.log(`claude-db
1124
-
1125
- install [--project] Register hooks + MCP server with Claude Code
1126
- uninstall [--project] Remove them again, leaving memory intact
1127
- status Is it wired up, and has it recorded anything
1128
- doctor [--deep] Show resolved config; --deep proves a full
1129
- write, search, recall and delete round trip
1130
- use [--force] <url> Point memory at a database, once it answers
1131
- search [--all] <query> Search memory, this project or every project
1132
- [--tag <name>] ...limited to one repo or top-level directory
1133
- remember [--kind k] <text> Record something outright, e.g. a house rule
1134
- [--key <name>] ...under a stable name, replacing any earlier one
1135
- forget <id> [id...] Delete specific observations by id
1136
- projects List every project with memory in this database
1137
- merge [<old-path>] [--yes] Move memory from an old project path onto this one
1138
- stats What this project's memory is made of
1139
- flush Re-ingest every transcript for this project
1140
- seed --from-git [--limit n] Fill a cold memory from this repo's history
1141
- usages [--regex] <symbol> Find real usages via git grep, current source only
1142
- [--context n] [--path <dir>] [--limit n]
1143
- export [--all] > out.jsonl Dump memory as JSONL, for backup or migration
1144
- import <file.jsonl> Load a dump back in (safe to repeat)
1145
- sync <url> [--yes] Two-way merge with another database
1146
- update Install a newer compatible release now
1147
- reembed Re-embed everything with the current model
1148
- prune --older-than <days> Delete old memory (dry run without --yes)
1149
- reset [--project] --yes Delete stored memory (dry run without --yes)
1150
-
1151
- --project scope to the current repo via .claude/settings.local.json
1152
- instead of every project on this machine
1153
-
1154
- Connection strings:
1155
- mongodb+srv://user:pass@cluster.mongodb.net/memory
1156
- postgres://user:pass@host:5432/memory
1157
- /path/to/memory.db (SQLite, default)
1158
-
1159
- Or set CLAUDE_DB_URL in the environment to override config.json.`);
1160
- }