claude-db 0.2.3 → 0.4.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.
package/dist/cli/index.js CHANGED
@@ -1,11 +1,14 @@
1
1
  #!/usr/bin/env node
2
- import { readFileSync, rmSync } from 'node:fs';
2
+ import { randomUUID } from 'node:crypto';
3
+ import { readFileSync, rmSync, statSync } from 'node:fs';
3
4
  import { basename, dirname, join, resolve } from 'node:path';
4
5
  import { fileURLToPath } from 'node:url';
5
- import { embedObservations, flushSession, remember, resetCursor, transcriptsFor, } from '../capture/index.js';
6
+ import { embedObservations, flushSession, remember, observationsFromGit, redact, resetCursor, sweepCursors, transcriptsFor, } from '../capture/index.js';
7
+ import { findUsages, formatUsages } from '../usages/index.js';
6
8
  import { createContext } from '../context.js';
9
+ import { createStore } from '../store/index.js';
7
10
  import { CONFIG_DIR, CONFIG_PATH, loadConfig, saveConfig } from '../config/index.js';
8
- import { assertStableLocation, install, instructionsPathFor, mcpPathFor, settingsPathFor, uninstall, } from './install.js';
11
+ import { assertStableLocation, install, instructionsPathFor, mcpPathFor, settingsPathFor, skillPathFor, uninstall, } from './install.js';
9
12
  import { resolveProject } from '../util/project.js';
10
13
  import { checkForUpdate, packageVersion } from '../update.js';
11
14
  import { silenceSqliteWarning } from '../util/warnings.js';
@@ -15,6 +18,14 @@ const DIST_DIR = resolve(dirname(fileURLToPath(import.meta.url)), '..');
15
18
  // Declared above the command switch below, which runs before the rest of this
16
19
  // module's bindings initialise.
17
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;
18
29
  const [command, ...args] = process.argv.slice(2);
19
30
  // Every command runs inside this. A driver that cannot reach its database
20
31
  // rejects deep inside an adapter, and with nothing catching it the CLI printed
@@ -41,7 +52,7 @@ async function run() {
41
52
  await cmdUse(args);
42
53
  break;
43
54
  case 'doctor':
44
- await cmdDoctor();
55
+ await cmdDoctor(args);
45
56
  break;
46
57
  case 'search':
47
58
  await cmdSearch(args);
@@ -82,10 +93,202 @@ async function run() {
82
93
  case 'merge':
83
94
  await cmdMerge(args);
84
95
  break;
96
+ case 'seed':
97
+ await cmdSeed(args);
98
+ break;
99
+ case 'usages':
100
+ await cmdUsages(args);
101
+ break;
102
+ case 'sync':
103
+ await cmdSync(args);
104
+ break;
85
105
  default:
86
106
  usage();
87
107
  }
88
108
  }
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
+ }
89
292
  /** Shows how memory is partitioned, and which partition you are currently in. */
90
293
  async function cmdProjects() {
91
294
  const here = resolveProject(undefined);
@@ -250,9 +453,10 @@ async function cmdFlush() {
250
453
  try {
251
454
  for (const path of transcripts) {
252
455
  const sessionId = basename(path, '.jsonl');
253
- // Ignore any stored cursor: a manual flush is asking for a full re-read.
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.
254
458
  resetCursor(sessionId);
255
- const result = await flushSession(ctx, sessionId, project, path);
459
+ const result = await flushSession(ctx, sessionId, project, path, true);
256
460
  if (result.observations > 0) {
257
461
  console.log(`${sessionId.slice(0, 8)} ${String(result.observations).padStart(4)} observations`);
258
462
  total += result.observations;
@@ -263,6 +467,9 @@ async function cmdFlush() {
263
467
  await ctx.close();
264
468
  }
265
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.`);
266
473
  }
267
474
  /** `--project` limits the install to the current repo; default is machine-wide. */
268
475
  function scopeFrom(args) {
@@ -283,6 +490,7 @@ async function cmdInstall(scope) {
283
490
  console.log(`Scope : ${scope === 'project' ? `this project only (${project})` : 'all projects on this machine'}`);
284
491
  console.log(`Settings : ${settingsPath}`);
285
492
  console.log(`Guidance : ${instructionsPathFor(scope, project)}`);
493
+ console.log(`Skill : ${skillPathFor(scope, project)} (/cdb-scan)`);
286
494
  console.log(`Config : ${CONFIG_PATH}`);
287
495
  console.log(`Database : ${ctx.config.database}`);
288
496
  console.log('\nRestart Claude Code to activate.');
@@ -348,11 +556,24 @@ async function cmdStatus() {
348
556
  const mcpFile = [mcpPathFor('project', project), mcpPathFor('global', project)].find((candidate) => fileMentions(candidate, resolve(DIST_DIR, 'mcp', 'server.js')));
349
557
  console.log(`mcp : ${mcpFile ? `registered (${mcpFile})` : 'NOT REGISTERED'}`);
350
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'}`);
351
563
  if (active.length === 0) {
352
564
  console.log('\nHooks are not registered, so nothing will ever be captured.');
353
565
  console.log('Run this from the project you want to track:');
354
566
  console.log(' claude-db install --project');
355
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
+ }
356
577
  else if (sessions.length === 0) {
357
578
  console.log('\nInstalled, but nothing recorded yet. Memory is written as you');
358
579
  console.log('work, on every prompt, and only for turns that changed something.');
@@ -363,6 +584,45 @@ async function cmdStatus() {
363
584
  await ctx.close();
364
585
  }
365
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
+ }
366
626
  /** True when a settings file contains one of our hook commands. */
367
627
  function isInstalled(settingsPath) {
368
628
  return fileMentions(settingsPath, resolve(DIST_DIR, 'hooks', 'session-end.js'));
@@ -391,15 +651,23 @@ async function cmdUse(argv) {
391
651
  process.exit(1);
392
652
  }
393
653
  let kind = '';
654
+ let foreign = [];
655
+ let rows = 0;
394
656
  try {
395
- const ctx = await createContext({ database: uri });
657
+ const store = await createStore(uri);
396
658
  try {
397
- if (!(await ctx.store.ping()))
659
+ if (!(await store.ping()))
398
660
  throw new Error('connected, but it did not answer a ping');
399
- kind = ctx.store.kind;
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);
400
668
  }
401
669
  finally {
402
- await ctx.close();
670
+ await store.close();
403
671
  }
404
672
  }
405
673
  catch (error) {
@@ -411,18 +679,72 @@ async function cmdUse(argv) {
411
679
  }
412
680
  }
413
681
  const config = loadConfig();
682
+ const previous = config.database;
414
683
  config.database = uri;
415
684
  saveConfig(config);
416
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);
417
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. */
418
735
  function describe(error) {
419
736
  const message = error instanceof Error ? error.message : String(error);
420
- // A bare ENOTFOUND says nothing about what to do next.
421
- return /ENOTFOUND|EAI_AGAIN/.test(message)
422
- ? `${message}\n(that host does not resolve — check the name, or whether the service still exists)`
423
- : message;
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;
424
746
  }
425
- async function cmdDoctor() {
747
+ async function cmdDoctor(argv) {
426
748
  // No embedder timeout here: doctor is where you want to wait for a first
427
749
  // model download, so that the hooks afterwards find it cached.
428
750
  const base = loadConfig();
@@ -442,8 +764,58 @@ async function cmdDoctor() {
442
764
  console.log(`embedder : ${embedder.id} (${embedder.dimensions}d)`);
443
765
  console.log(`vectors : ${vectors}`);
444
766
  console.log(`search : ${vectors.startsWith('working') ? 'hybrid (keyword + vector)' : 'keyword only'}`);
767
+ const healthy = argv.includes('--deep') ? await deepCheck(ctx) : true;
445
768
  await ctx.close();
446
- process.exit(reachable ? 0 : 1);
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;
447
819
  }
448
820
  async function probeEmbedder(embedder) {
449
821
  if (embedder.dimensions === 0)
@@ -460,9 +832,10 @@ async function probeEmbedder(embedder) {
460
832
  }
461
833
  async function cmdSearch(argv) {
462
834
  const all = argv.includes('--all');
463
- const query = argv.filter((arg) => arg !== '--all').join(' ');
835
+ const tag = valueOf(argv, '--tag');
836
+ const query = withoutFlags(argv, ['--tag']).filter((arg) => arg !== '--all').join(' ');
464
837
  if (!query.trim()) {
465
- console.error('Usage: claude-db search [--all] <query>');
838
+ console.error('Usage: claude-db search [--all] [--tag <name>] <query>');
466
839
  process.exit(1);
467
840
  }
468
841
  const ctx = await createContext();
@@ -471,6 +844,7 @@ async function cmdSearch(argv) {
471
844
  // Scoping is right for injection, but "where did I solve this before" is
472
845
  // inherently cross-project, and only the CLI can ask that question.
473
846
  ...(all ? {} : { project: resolveProject(undefined) }),
847
+ ...(tag ? { tag } : {}),
474
848
  limit: 10,
475
849
  });
476
850
  // Same short-id format the MCP tools emit, so ids copied from either place
@@ -479,21 +853,20 @@ async function cmdSearch(argv) {
479
853
  const date = new Date(entry.createdAt).toISOString().slice(0, 10);
480
854
  const where = all ? ` ${basename(entry.project)}` : '';
481
855
  console.log(`${toShortId(entry.id)} ${entry.kind.padEnd(10)} ${date}${where} ${entry.title}`);
856
+ if (entry.snippet)
857
+ console.log(` ${entry.snippet}`);
482
858
  }
483
859
  if (results.length === 0)
484
860
  console.log('No matching observations.');
485
861
  await ctx.close();
486
862
  }
487
863
  async function cmdRemember(argv) {
488
- const kindFlag = argv.indexOf('--kind');
489
- const kind = kindFlag >= 0 ? argv[kindFlag + 1] : undefined;
490
- const text = (kindFlag >= 0
491
- ? argv.filter((_, index) => index !== kindFlag && index !== kindFlag + 1)
492
- : argv)
493
- .join(' ')
494
- .trim();
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();
495
868
  if (!text) {
496
- console.error('Usage: claude-db remember [--kind <kind>] <text>');
869
+ console.error('Usage: claude-db remember [--kind <kind>] [--key <name>] [--tag <name>] <text>');
497
870
  process.exit(1);
498
871
  }
499
872
  const ctx = await createContext();
@@ -502,6 +875,8 @@ async function cmdRemember(argv) {
502
875
  project: resolveProject(undefined),
503
876
  text,
504
877
  ...(kind ? { kind: kind } : {}),
878
+ ...(key ? { key } : {}),
879
+ ...(tag ? { tags: [tag] } : {}),
505
880
  });
506
881
  console.log(`Remembered ${toShortId(observation.id)} [${observation.kind}] ${observation.title}`);
507
882
  }
@@ -732,23 +1107,42 @@ function valueOf(argv, flag) {
732
1107
  const index = argv.indexOf(flag);
733
1108
  return index >= 0 ? argv[index + 1] : undefined;
734
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
+ }
735
1122
  function usage() {
736
1123
  console.log(`claude-db
737
1124
 
738
1125
  install [--project] Register hooks + MCP server with Claude Code
739
1126
  uninstall [--project] Remove them again, leaving memory intact
740
1127
  status Is it wired up, and has it recorded anything
741
- doctor Show resolved config and test connectivity
1128
+ doctor [--deep] Show resolved config; --deep proves a full
1129
+ write, search, recall and delete round trip
742
1130
  use [--force] <url> Point memory at a database, once it answers
743
1131
  search [--all] <query> Search memory, this project or every project
1132
+ [--tag <name>] ...limited to one repo or top-level directory
744
1133
  remember [--kind k] <text> Record something outright, e.g. a house rule
1134
+ [--key <name>] ...under a stable name, replacing any earlier one
745
1135
  forget <id> [id...] Delete specific observations by id
746
1136
  projects List every project with memory in this database
747
1137
  merge [<old-path>] [--yes] Move memory from an old project path onto this one
748
1138
  stats What this project's memory is made of
749
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]
750
1143
  export [--all] > out.jsonl Dump memory as JSONL, for backup or migration
751
1144
  import <file.jsonl> Load a dump back in (safe to repeat)
1145
+ sync <url> [--yes] Two-way merge with another database
752
1146
  update Install a newer compatible release now
753
1147
  reembed Re-embed everything with the current model
754
1148
  prune --older-than <days> Delete old memory (dry run without --yes)
@@ -22,6 +22,14 @@ export declare function settingsPathFor(scope: Scope, project: string): string;
22
22
  * yourself never tells a teammate's agent to call a server they do not have.
23
23
  */
24
24
  export declare function instructionsPathFor(scope: Scope, project: string): string;
25
+ /**
26
+ * Where the `/cdb-scan` skill is installed.
27
+ *
28
+ * A skill rather than a CLI command: surveying a codebase means reading it, and
29
+ * the agent is already sitting in the repo with the tools to do that. A command
30
+ * would need its own model, its own key and its own opinion about what matters.
31
+ */
32
+ export declare function skillPathFor(scope: Scope, project: string): string;
25
33
  /**
26
34
  * MCP servers live in a different file from hooks.
27
35
  *