claude-db 0.1.1 → 0.2.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 (40) hide show
  1. package/README.md +17 -2
  2. package/dist/capture/flush.d.ts +22 -0
  3. package/dist/capture/flush.js +45 -10
  4. package/dist/capture/identity.d.ts +6 -0
  5. package/dist/capture/identity.js +14 -0
  6. package/dist/capture/index.d.ts +5 -3
  7. package/dist/capture/index.js +4 -3
  8. package/dist/capture/manual.d.ts +21 -0
  9. package/dist/capture/manual.js +40 -0
  10. package/dist/capture/transcript.d.ts +12 -0
  11. package/dist/capture/transcript.js +69 -1
  12. package/dist/capture/turn-extractor.js +40 -8
  13. package/dist/cli/index.js +376 -30
  14. package/dist/cli/install.d.ts +15 -1
  15. package/dist/cli/install.js +127 -8
  16. package/dist/config/schema.d.ts +1 -0
  17. package/dist/config/schema.js +9 -1
  18. package/dist/context.js +24 -2
  19. package/dist/embed/builtin.js +3 -1
  20. package/dist/hooks/relevance.js +11 -4
  21. package/dist/hooks/session-end.js +2 -1
  22. package/dist/hooks/session-start.js +22 -3
  23. package/dist/mcp/server.js +56 -6
  24. package/dist/search/service.js +4 -1
  25. package/dist/store/adapter.d.ts +22 -6
  26. package/dist/store/adapter.js +10 -1
  27. package/dist/store/mongo/driver.d.ts +1 -0
  28. package/dist/store/mongo/index.d.ts +3 -2
  29. package/dist/store/mongo/index.js +57 -7
  30. package/dist/store/postgres/index.d.ts +22 -8
  31. package/dist/store/postgres/index.js +165 -21
  32. package/dist/store/sqlite/index.d.ts +3 -2
  33. package/dist/store/sqlite/index.js +112 -9
  34. package/dist/store/sqlite/schema.sql +4 -3
  35. package/dist/types.d.ts +28 -0
  36. package/dist/util/project.d.ts +9 -10
  37. package/dist/util/project.js +52 -13
  38. package/dist/util/vector.d.ts +11 -1
  39. package/dist/util/vector.js +14 -3
  40. package/package.json +2 -2
package/dist/cli/index.js CHANGED
@@ -1,17 +1,19 @@
1
1
  #!/usr/bin/env node
2
- import { readdirSync, readFileSync, rmSync } from 'node:fs';
3
- import { homedir } from 'node:os';
4
- import { dirname, join, resolve } from 'node:path';
2
+ import { readFileSync, rmSync } from 'node:fs';
3
+ import { basename, dirname, join, resolve } from 'node:path';
5
4
  import { fileURLToPath } from 'node:url';
6
- import { flushSession, resetCursor } from '../capture/index.js';
5
+ import { embedObservations, flushSession, remember, resetCursor, transcriptsFor, } from '../capture/index.js';
7
6
  import { createContext } from '../context.js';
8
7
  import { CONFIG_DIR, CONFIG_PATH, loadConfig, saveConfig } from '../config/index.js';
9
- import { assertStableLocation, install, mcpPathFor, settingsPathFor, uninstall } from './install.js';
8
+ import { assertStableLocation, install, instructionsPathFor, mcpPathFor, settingsPathFor, uninstall, } from './install.js';
10
9
  import { resolveProject } from '../util/project.js';
11
10
  import { silenceSqliteWarning } from '../util/warnings.js';
12
11
  import { toShortId } from '../util/shortid.js';
13
12
  silenceSqliteWarning();
14
13
  const DIST_DIR = resolve(dirname(fileURLToPath(import.meta.url)), '..');
14
+ // Declared above the command switch below, which runs before the rest of this
15
+ // module's bindings initialise.
16
+ const BATCH = 500;
15
17
  const [command, ...args] = process.argv.slice(2);
16
18
  switch (command) {
17
19
  case 'install':
@@ -30,7 +32,28 @@ switch (command) {
30
32
  await cmdDoctor();
31
33
  break;
32
34
  case 'search':
33
- await cmdSearch(args.join(' '));
35
+ await cmdSearch(args);
36
+ break;
37
+ case 'remember':
38
+ await cmdRemember(args);
39
+ break;
40
+ case 'forget':
41
+ await cmdForget(args);
42
+ break;
43
+ case 'export':
44
+ await cmdExport(args);
45
+ break;
46
+ case 'import':
47
+ await cmdImport(args[0]);
48
+ break;
49
+ case 'prune':
50
+ await cmdPrune(args);
51
+ break;
52
+ case 'reembed':
53
+ await cmdReembed();
54
+ break;
55
+ case 'stats':
56
+ await cmdStats();
34
57
  break;
35
58
  case 'flush':
36
59
  await cmdFlush();
@@ -41,6 +64,9 @@ switch (command) {
41
64
  case 'projects':
42
65
  await cmdProjects();
43
66
  break;
67
+ case 'merge':
68
+ await cmdMerge(args);
69
+ break;
44
70
  default:
45
71
  usage();
46
72
  }
@@ -66,6 +92,87 @@ async function cmdProjects() {
66
92
  await ctx.close();
67
93
  }
68
94
  }
95
+ /**
96
+ * Re-keys memory recorded under an old project path onto this one.
97
+ *
98
+ * Memory used to be keyed on the exact directory the agent was launched in, so
99
+ * anyone who worked from `repo/frontend` accumulated a second, disjoint memory.
100
+ * Keying on the repository root fixes that going forward but strands whatever
101
+ * is already under the old path, and nothing about it is visible: the memory
102
+ * simply does not appear.
103
+ *
104
+ * Re-inserting rather than issuing an UPDATE is deliberate. Observation ids are
105
+ * content-derived and independent of the project, so writing the same rows with
106
+ * a new project overwrites in place, and every derived field that depends on the
107
+ * project — the FTS scope token above all — is recomputed on the way through.
108
+ */
109
+ async function cmdMerge(argv) {
110
+ const into = resolveProject(undefined);
111
+ const confirmed = argv.includes('--yes') || argv.includes('-y');
112
+ const given = argv.find((arg) => typeof arg === 'string' && !arg.startsWith('-'));
113
+ const ctx = await createContext();
114
+ try {
115
+ if (!given) {
116
+ await listShards(ctx, into);
117
+ return;
118
+ }
119
+ // Resolved but deliberately not run through resolveProject: that maps a
120
+ // subdirectory to the repository root, which is the very key being merged
121
+ // *into*, so the source would resolve to the destination and match nothing.
122
+ const from = resolve(given);
123
+ if (from === into) {
124
+ console.error('Source and destination are the same project.');
125
+ process.exit(1);
126
+ }
127
+ let moved = 0;
128
+ const total = await eachObservation(ctx, { project: from }, async (batch) => {
129
+ if (!confirmed)
130
+ return;
131
+ await ctx.store.insertObservations(batch.map((obs) => ({ ...obs, project: into })));
132
+ moved += batch.length;
133
+ });
134
+ if (total === 0) {
135
+ console.error(`No memory stored under ${from}.`);
136
+ console.error('Run `claude-db projects` to see the exact paths in this database.');
137
+ process.exit(1);
138
+ }
139
+ if (!confirmed) {
140
+ console.log(`This would move ${total} observation(s):`);
141
+ console.log(` from ${from}`);
142
+ console.log(` into ${into}`);
143
+ console.log('\nNothing was moved. Re-run with --yes to confirm.');
144
+ return;
145
+ }
146
+ // Sessions carry the recap injected at SessionStart, so they follow their
147
+ // observations. Only summarised ones are worth moving; the rest go with
148
+ // the cleanup below.
149
+ for (const session of await ctx.store.recentSessions(from, 1000)) {
150
+ await ctx.store.upsertSession({ ...session, project: into });
151
+ }
152
+ const swept = await ctx.store.remove({ project: from });
153
+ console.log(`Moved ${moved} observation(s) into ${into}.`);
154
+ if (swept > 0)
155
+ console.log(`Cleaned up ${swept} leftover row(s) under the old path.`);
156
+ }
157
+ finally {
158
+ await ctx.close();
159
+ }
160
+ }
161
+ /** Projects in this database that sit underneath the current one. */
162
+ async function listShards(ctx, into) {
163
+ const shards = (await ctx.store.listProjects()).filter((entry) => entry.project !== into && entry.project.startsWith(`${into}/`));
164
+ if (shards.length === 0) {
165
+ console.log(`No memory is stored under a subdirectory of ${into}.`);
166
+ console.log('Nothing to merge.');
167
+ return;
168
+ }
169
+ console.log(`Memory recorded under subdirectories of ${into}:\n`);
170
+ for (const shard of shards) {
171
+ console.log(` ${String(shard.observations).padStart(5)} ${shard.project}`);
172
+ }
173
+ console.log('\nMerge one in with:');
174
+ console.log(` claude-db merge ${shards[0]?.project} --yes`);
175
+ }
69
176
  /**
70
177
  * Deletes stored memory. Scoped to this project with `--project`, otherwise
71
178
  * everything in the configured database.
@@ -89,7 +196,7 @@ async function cmdReset(argv) {
89
196
  console.log('\nNothing was deleted. Re-run with --yes to confirm.');
90
197
  return;
91
198
  }
92
- const deleted = await ctx.store.clear(scoped ? project : undefined);
199
+ const deleted = await ctx.store.remove(scoped ? { project } : {});
93
200
  console.log(`Deleted ${deleted} observation(s) from ${target}.`);
94
201
  if (!scoped) {
95
202
  clearLocalState();
@@ -117,23 +224,19 @@ function clearLocalState() {
117
224
  */
118
225
  async function cmdFlush() {
119
226
  const project = resolveProject(undefined);
120
- const dir = transcriptDirFor(project);
121
- let files;
122
- try {
123
- files = readdirSync(dir).filter((name) => name.endsWith('.jsonl'));
124
- }
125
- catch {
126
- console.error(`No transcripts found at ${dir}`);
227
+ const transcripts = transcriptsFor(project);
228
+ if (transcripts.length === 0) {
229
+ console.error(`No transcripts found for ${project}`);
127
230
  process.exit(1);
128
231
  }
129
232
  const ctx = await createContext();
130
233
  let total = 0;
131
234
  try {
132
- for (const file of files) {
133
- const sessionId = file.replace(/\.jsonl$/, '');
235
+ for (const path of transcripts) {
236
+ const sessionId = basename(path, '.jsonl');
134
237
  // Ignore any stored cursor: a manual flush is asking for a full re-read.
135
238
  resetCursor(sessionId);
136
- const result = await flushSession(ctx, sessionId, project, join(dir, file));
239
+ const result = await flushSession(ctx, sessionId, project, path);
137
240
  if (result.observations > 0) {
138
241
  console.log(`${sessionId.slice(0, 8)} ${String(result.observations).padStart(4)} observations`);
139
242
  total += result.observations;
@@ -143,7 +246,7 @@ async function cmdFlush() {
143
246
  finally {
144
247
  await ctx.close();
145
248
  }
146
- console.log(`\n${total} observations from ${files.length} transcript(s).`);
249
+ console.log(`\n${total} observations from ${transcripts.length} transcript(s).`);
147
250
  }
148
251
  /** `--project` limits the install to the current repo; default is machine-wide. */
149
252
  function scopeFrom(args) {
@@ -163,6 +266,7 @@ async function cmdInstall(scope) {
163
266
  await ctx.close();
164
267
  console.log(`Scope : ${scope === 'project' ? `this project only (${project})` : 'all projects on this machine'}`);
165
268
  console.log(`Settings : ${settingsPath}`);
269
+ console.log(`Guidance : ${instructionsPathFor(scope, project)}`);
166
270
  console.log(`Config : ${CONFIG_PATH}`);
167
271
  console.log(`Database : ${ctx.config.database}`);
168
272
  console.log('\nRestart Claude Code to activate.');
@@ -234,8 +338,8 @@ async function cmdStatus() {
234
338
  console.log(' claude-db install --project');
235
339
  }
236
340
  else if (sessions.length === 0) {
237
- console.log('\nInstalled, but nothing recorded yet. Memory is written when a');
238
- console.log('session ENDS. Work in this project, close the session, then re-check.');
341
+ console.log('\nInstalled, but nothing recorded yet. Memory is written as you');
342
+ console.log('work, on every prompt, and only for turns that changed something.');
239
343
  console.log('If you installed just now, restart Claude Code first.');
240
344
  }
241
345
  }
@@ -247,10 +351,6 @@ async function cmdStatus() {
247
351
  function isInstalled(settingsPath) {
248
352
  return fileMentions(settingsPath, resolve(DIST_DIR, 'hooks', 'session-end.js'));
249
353
  }
250
- /** Claude Code stores transcripts under a dash-encoded absolute path. */
251
- function transcriptDirFor(project) {
252
- return join(homedir(), '.claude', 'projects', project.replace(/[/.]/g, '-'));
253
- }
254
354
  function fileMentions(path, needle) {
255
355
  try {
256
356
  return readFileSync(path, 'utf8').includes(needle);
@@ -274,7 +374,12 @@ async function cmdUse(uri) {
274
374
  console.log(ok ? `Connected. Using ${ctx.store.kind}.` : 'Saved, but ping failed.');
275
375
  }
276
376
  async function cmdDoctor() {
277
- const ctx = await createContext();
377
+ // No embedder timeout here: doctor is where you want to wait for a first
378
+ // model download, so that the hooks afterwards find it cached.
379
+ const base = loadConfig();
380
+ const ctx = await createContext({
381
+ embeddings: { ...base.embeddings, timeoutMs: 0 },
382
+ });
278
383
  const reachable = await ctx.store.ping();
279
384
  // Report measured capability, not configured intent. Printing "384d" for an
280
385
  // embedder that cannot actually run is worse than printing nothing.
@@ -303,27 +408,260 @@ async function probeEmbedder(embedder) {
303
408
  return `unavailable (${error instanceof Error ? error.message.split('.')[0] : 'error'})`;
304
409
  }
305
410
  }
306
- async function cmdSearch(query) {
411
+ async function cmdSearch(argv) {
412
+ const all = argv.includes('--all');
413
+ const query = argv.filter((arg) => arg !== '--all').join(' ');
307
414
  if (!query.trim()) {
308
- console.error('Usage: claude-db search <query>');
415
+ console.error('Usage: claude-db search [--all] <query>');
309
416
  process.exit(1);
310
417
  }
311
418
  const ctx = await createContext();
312
419
  const results = await ctx.search.search({
313
420
  text: query,
314
- project: resolveProject(undefined),
421
+ // Scoping is right for injection, but "where did I solve this before" is
422
+ // inherently cross-project, and only the CLI can ask that question.
423
+ ...(all ? {} : { project: resolveProject(undefined) }),
315
424
  limit: 10,
316
425
  });
317
426
  // Same short-id format the MCP tools emit, so ids copied from either place
318
427
  // work in the other.
319
428
  for (const entry of results) {
320
429
  const date = new Date(entry.createdAt).toISOString().slice(0, 10);
321
- console.log(`${toShortId(entry.id)} ${entry.kind.padEnd(10)} ${date} ${entry.title}`);
430
+ const where = all ? ` ${basename(entry.project)}` : '';
431
+ console.log(`${toShortId(entry.id)} ${entry.kind.padEnd(10)} ${date}${where} ${entry.title}`);
322
432
  }
323
433
  if (results.length === 0)
324
434
  console.log('No matching observations.');
325
435
  await ctx.close();
326
436
  }
437
+ async function cmdRemember(argv) {
438
+ const kindFlag = argv.indexOf('--kind');
439
+ const kind = kindFlag >= 0 ? argv[kindFlag + 1] : undefined;
440
+ const text = (kindFlag >= 0
441
+ ? argv.filter((_, index) => index !== kindFlag && index !== kindFlag + 1)
442
+ : argv)
443
+ .join(' ')
444
+ .trim();
445
+ if (!text) {
446
+ console.error('Usage: claude-db remember [--kind <kind>] <text>');
447
+ process.exit(1);
448
+ }
449
+ const ctx = await createContext();
450
+ try {
451
+ const observation = await remember(ctx, {
452
+ project: resolveProject(undefined),
453
+ text,
454
+ ...(kind ? { kind: kind } : {}),
455
+ });
456
+ console.log(`Remembered ${toShortId(observation.id)} [${observation.kind}] ${observation.title}`);
457
+ }
458
+ finally {
459
+ await ctx.close();
460
+ }
461
+ }
462
+ async function cmdForget(argv) {
463
+ const ids = argv.filter((arg) => typeof arg === 'string' && arg.length > 0);
464
+ if (ids.length === 0) {
465
+ console.error('Usage: claude-db forget <id> [id...]');
466
+ process.exit(1);
467
+ }
468
+ const ctx = await createContext();
469
+ try {
470
+ // Shown before deleting: a short id is a prefix match, and the only way to
471
+ // be sure it means what you think is to read the titles back.
472
+ const doomed = await ctx.store.getObservations(ids);
473
+ for (const obs of doomed) {
474
+ console.log(` ${toShortId(obs.id)} [${obs.kind}] ${obs.title}`);
475
+ }
476
+ const deleted = await ctx.store.remove({ ids });
477
+ console.log(deleted > 0 ? `Forgot ${deleted} observation(s).` : 'No match.');
478
+ }
479
+ finally {
480
+ await ctx.close();
481
+ }
482
+ }
483
+ /** Pages rather than loading everything: a shared database can be large. */
484
+ async function eachObservation(ctx, filter, visit) {
485
+ let after = 0;
486
+ let total = 0;
487
+ for (;;) {
488
+ const batch = await ctx.store.list({ ...filter, after, limit: BATCH });
489
+ if (batch.length === 0)
490
+ return total;
491
+ await visit(batch);
492
+ total += batch.length;
493
+ const last = batch[batch.length - 1];
494
+ if (!last)
495
+ return total;
496
+ // createdAt is not unique, so a batch that lands entirely on one timestamp
497
+ // would loop forever. Nudging past it drops at most a co-timestamped tail.
498
+ after = last.createdAt === after ? after + 1 : last.createdAt;
499
+ if (batch.length < BATCH)
500
+ return total;
501
+ }
502
+ }
503
+ async function cmdExport(argv) {
504
+ const all = argv.includes('--all');
505
+ const ctx = await createContext();
506
+ try {
507
+ const count = await eachObservation(ctx, all ? {} : { project: resolveProject(undefined) }, (batch) => {
508
+ for (const obs of batch)
509
+ process.stdout.write(`${JSON.stringify(obs)}\n`);
510
+ });
511
+ process.stderr.write(`${count} observation(s) exported.\n`);
512
+ }
513
+ finally {
514
+ await ctx.close();
515
+ }
516
+ }
517
+ async function cmdImport(path) {
518
+ if (!path) {
519
+ console.error('Usage: claude-db import <file.jsonl>');
520
+ process.exit(1);
521
+ }
522
+ const lines = readFileSync(path, 'utf8').split('\n').filter((line) => line.trim().length > 0);
523
+ const ctx = await createContext();
524
+ let imported = 0;
525
+ try {
526
+ for (let i = 0; i < lines.length; i += BATCH) {
527
+ const batch = lines
528
+ .slice(i, i + BATCH)
529
+ .map((line) => JSON.parse(line))
530
+ .filter((obs) => typeof obs.id === 'string' && typeof obs.project === 'string');
531
+ await ctx.store.insertObservations(batch);
532
+ imported += batch.length;
533
+ }
534
+ }
535
+ finally {
536
+ await ctx.close();
537
+ }
538
+ // Ids are content-derived, so re-importing the same file is a no-op rather
539
+ // than a second copy of every memory.
540
+ console.log(`Imported ${imported} observation(s).`);
541
+ }
542
+ async function cmdPrune(argv) {
543
+ const days = Number(valueOf(argv, '--older-than') ?? NaN);
544
+ const kind = valueOf(argv, '--kind');
545
+ const confirmed = argv.includes('--yes') || argv.includes('-y');
546
+ const all = argv.includes('--all');
547
+ if (!Number.isFinite(days) || days <= 0) {
548
+ console.error('Usage: claude-db prune --older-than <days> [--kind <kind>] [--all] --yes');
549
+ process.exit(1);
550
+ }
551
+ const before = Date.now() - days * 86_400_000;
552
+ const filter = {
553
+ before,
554
+ ...(all ? {} : { project: resolveProject(undefined) }),
555
+ ...(kind ? { kind } : {}),
556
+ };
557
+ const ctx = await createContext();
558
+ try {
559
+ if (!confirmed) {
560
+ // Counted by paging rather than one unbounded query, and against the
561
+ // same predicate the delete uses, so the dry run cannot disagree with it.
562
+ let matching = 0;
563
+ await eachObservation(ctx, all ? {} : { project: resolveProject(undefined) }, (batch) => {
564
+ for (const obs of batch) {
565
+ if (obs.createdAt < before && (!kind || obs.kind === kind))
566
+ matching += 1;
567
+ }
568
+ });
569
+ console.log(`This would delete ${matching} observation(s) older than ${days} day(s)` +
570
+ `${kind ? ` of kind ${kind}` : ''}.`);
571
+ console.log('\nNothing was deleted. Re-run with --yes to confirm.');
572
+ return;
573
+ }
574
+ const deleted = await ctx.store.remove(filter);
575
+ console.log(`Pruned ${deleted} observation(s).`);
576
+ }
577
+ finally {
578
+ await ctx.close();
579
+ }
580
+ }
581
+ /**
582
+ * Re-embeds everything with the currently configured model.
583
+ *
584
+ * Installing @xenova/transformers changes the embedding space from 256d to
585
+ * 384d, and `cosine` refuses to compare across widths, so without this an
586
+ * upgrade makes existing memory *less* searchable rather than more.
587
+ */
588
+ async function cmdReembed() {
589
+ const base = loadConfig();
590
+ const ctx = await createContext({ embeddings: { ...base.embeddings, timeoutMs: 0 } });
591
+ try {
592
+ const embedder = await ctx.embedder();
593
+ if (embedder.dimensions === 0) {
594
+ console.error('No embedder available; nothing to do.');
595
+ process.exit(1);
596
+ }
597
+ let updated = 0;
598
+ let skipped = 0;
599
+ const scanned = await eachObservation(ctx, {}, async (batch) => {
600
+ const stale = batch.filter((obs) => obs.embedder !== embedder.id);
601
+ skipped += batch.length - stale.length;
602
+ if (stale.length === 0)
603
+ return;
604
+ await embedObservations(ctx, stale);
605
+ await ctx.store.insertObservations(stale);
606
+ updated += stale.length;
607
+ process.stderr.write(`\r${updated} re-embedded...`);
608
+ });
609
+ process.stderr.write('\r');
610
+ console.log(`Scanned ${scanned}, re-embedded ${updated} with ${embedder.id}` +
611
+ `${skipped > 0 ? `, ${skipped} already current` : ''}.`);
612
+ }
613
+ finally {
614
+ await ctx.close();
615
+ }
616
+ }
617
+ async function cmdStats() {
618
+ const project = resolveProject(undefined);
619
+ const ctx = await createContext();
620
+ try {
621
+ const kinds = new Map();
622
+ const tags = new Map();
623
+ let embedded = 0;
624
+ let earliest = Number.POSITIVE_INFINITY;
625
+ let latest = 0;
626
+ const total = await eachObservation(ctx, { project }, (batch) => {
627
+ for (const obs of batch) {
628
+ kinds.set(obs.kind, (kinds.get(obs.kind) ?? 0) + 1);
629
+ for (const tag of obs.tags)
630
+ tags.set(tag, (tags.get(tag) ?? 0) + 1);
631
+ if (obs.embedding && obs.embedding.length > 0)
632
+ embedded += 1;
633
+ earliest = Math.min(earliest, obs.createdAt);
634
+ latest = Math.max(latest, obs.createdAt);
635
+ }
636
+ });
637
+ if (total === 0) {
638
+ console.log(`No memory stored for ${project}.`);
639
+ return;
640
+ }
641
+ const day = (ms) => new Date(ms).toISOString().slice(0, 10);
642
+ console.log(`project : ${project}`);
643
+ console.log(`observations: ${total}`);
644
+ console.log(`range : ${day(earliest)} to ${day(latest)}`);
645
+ console.log(`embedded : ${embedded} of ${total}`);
646
+ console.log('\nby kind');
647
+ for (const [kind, n] of [...kinds].sort((a, b) => b[1] - a[1])) {
648
+ console.log(` ${String(n).padStart(5)} ${kind}`);
649
+ }
650
+ if (tags.size > 0) {
651
+ console.log('\nby area');
652
+ for (const [tag, n] of [...tags].sort((a, b) => b[1] - a[1]).slice(0, 10)) {
653
+ console.log(` ${String(n).padStart(5)} ${tag}`);
654
+ }
655
+ }
656
+ }
657
+ finally {
658
+ await ctx.close();
659
+ }
660
+ }
661
+ function valueOf(argv, flag) {
662
+ const index = argv.indexOf(flag);
663
+ return index >= 0 ? argv[index + 1] : undefined;
664
+ }
327
665
  function usage() {
328
666
  console.log(`claude-db
329
667
 
@@ -332,9 +670,17 @@ function usage() {
332
670
  status Is it wired up, and has it recorded anything
333
671
  doctor Show resolved config and test connectivity
334
672
  use <connection-string> Point memory at any database and verify it
335
- search <query> Search memory for the current project
673
+ search [--all] <query> Search memory, this project or every project
674
+ remember [--kind k] <text> Record something outright, e.g. a house rule
675
+ forget <id> [id...] Delete specific observations by id
336
676
  projects List every project with memory in this database
677
+ merge [<old-path>] [--yes] Move memory from an old project path onto this one
678
+ stats What this project's memory is made of
337
679
  flush Re-ingest every transcript for this project
680
+ export [--all] > out.jsonl Dump memory as JSONL, for backup or migration
681
+ import <file.jsonl> Load a dump back in (safe to repeat)
682
+ reembed Re-embed everything with the current model
683
+ prune --older-than <days> Delete old memory (dry run without --yes)
338
684
  reset [--project] --yes Delete stored memory (dry run without --yes)
339
685
 
340
686
  --project scope to the current repo via .claude/settings.local.json
@@ -8,6 +8,20 @@ export type Scope = 'global' | 'project';
8
8
  * machine, and it is trivially reversible by deleting one file.
9
9
  */
10
10
  export declare function settingsPathFor(scope: Scope, project: string): string;
11
+ /**
12
+ * Where standing instructions go.
13
+ *
14
+ * Hook output is injected as conversation context, which the agent reads as
15
+ * information about the current turn. It is not a rule, so "you could search
16
+ * memory" competes with everything else in the transcript and loses. A memory
17
+ * file is part of the system prompt and governs the whole session, which is
18
+ * the only reliable way to make recall a default rather than a suggestion.
19
+ *
20
+ * Project scope writes CLAUDE.local.md rather than CLAUDE.md: it is personal
21
+ * and uncommitted, matching settings.local.json, so installing memory for
22
+ * yourself never tells a teammate's agent to call a server they do not have.
23
+ */
24
+ export declare function instructionsPathFor(scope: Scope, project: string): string;
11
25
  /**
12
26
  * MCP servers live in a different file from hooks.
13
27
  *
@@ -18,7 +32,7 @@ export declare function settingsPathFor(scope: Scope, project: string): string;
18
32
  */
19
33
  export declare function mcpPathFor(scope: Scope, project: string): string;
20
34
  /**
21
- * Registers the four lifecycle hooks and the MCP server, merging into whatever
35
+ * Registers the three lifecycle hooks and the MCP server, merging into whatever
22
36
  * the user already has rather than overwriting it. Re-running is safe: a hook
23
37
  * whose command already appears is skipped rather than duplicated.
24
38
  */