claude-db 0.2.2 → 0.3.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/README.md +16 -4
- package/dist/capture/flush.d.ts +20 -1
- package/dist/capture/flush.js +45 -5
- package/dist/capture/git.d.ts +2 -0
- package/dist/capture/git.js +96 -0
- package/dist/capture/index.d.ts +4 -3
- package/dist/capture/index.js +4 -3
- package/dist/capture/manual.d.ts +9 -0
- package/dist/capture/manual.js +0 -0
- package/dist/capture/transcript.d.ts +8 -0
- package/dist/capture/transcript.js +30 -0
- package/dist/capture/turn-extractor.d.ts +9 -1
- package/dist/capture/turn-extractor.js +74 -13
- package/dist/cli/index.js +409 -27
- package/dist/cli/install.d.ts +8 -0
- package/dist/cli/install.js +24 -0
- package/dist/config/schema.d.ts +5 -0
- package/dist/config/schema.js +12 -0
- package/dist/hooks/session-end.js +15 -0
- package/dist/hooks/session-start.js +5 -0
- package/dist/mcp/render.d.ts +23 -0
- package/dist/mcp/render.js +49 -0
- package/dist/mcp/server.d.ts +1 -7
- package/dist/mcp/server.js +37 -36
- package/dist/store/adapter.d.ts +10 -0
- package/dist/store/adapter.js +8 -0
- package/dist/store/mongo/index.d.ts +1 -0
- package/dist/store/mongo/index.js +34 -3
- package/dist/store/postgres/index.d.ts +15 -0
- package/dist/store/postgres/index.js +89 -4
- package/dist/store/sqlite/index.d.ts +1 -0
- package/dist/store/sqlite/index.js +32 -2
- package/dist/types.d.ts +16 -0
- package/dist/update.d.ts +38 -0
- package/dist/update.js +144 -0
- package/dist/util/snippet.d.ts +28 -0
- package/dist/util/snippet.js +52 -0
- package/package.json +2 -1
- package/skills/cdb-scan/SKILL.md +72 -0
package/dist/cli/index.js
CHANGED
|
@@ -1,12 +1,15 @@
|
|
|
1
1
|
#!/usr/bin/env node
|
|
2
|
-
import {
|
|
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';
|
|
6
7
|
import { createContext } from '../context.js';
|
|
8
|
+
import { createStore } from '../store/index.js';
|
|
7
9
|
import { CONFIG_DIR, CONFIG_PATH, loadConfig, saveConfig } from '../config/index.js';
|
|
8
|
-
import { assertStableLocation, install, instructionsPathFor, mcpPathFor, settingsPathFor, uninstall, } from './install.js';
|
|
10
|
+
import { assertStableLocation, install, instructionsPathFor, mcpPathFor, settingsPathFor, skillPathFor, uninstall, } from './install.js';
|
|
9
11
|
import { resolveProject } from '../util/project.js';
|
|
12
|
+
import { checkForUpdate, packageVersion } from '../update.js';
|
|
10
13
|
import { silenceSqliteWarning } from '../util/warnings.js';
|
|
11
14
|
import { toShortId } from '../util/shortid.js';
|
|
12
15
|
silenceSqliteWarning();
|
|
@@ -14,6 +17,14 @@ const DIST_DIR = resolve(dirname(fileURLToPath(import.meta.url)), '..');
|
|
|
14
17
|
// Declared above the command switch below, which runs before the rest of this
|
|
15
18
|
// module's bindings initialise.
|
|
16
19
|
const BATCH = 500;
|
|
20
|
+
/**
|
|
21
|
+
* How far capture may lag the work before it counts as broken.
|
|
22
|
+
*
|
|
23
|
+
* Not every turn produces an observation — a day of questions legitimately
|
|
24
|
+
* records nothing — so a tight threshold would cry wolf. Two full days of
|
|
25
|
+
* activity with nothing written is the shape every silent failure so far had.
|
|
26
|
+
*/
|
|
27
|
+
const STALL_MS = 48 * 60 * 60 * 1000;
|
|
17
28
|
const [command, ...args] = process.argv.slice(2);
|
|
18
29
|
// Every command runs inside this. A driver that cannot reach its database
|
|
19
30
|
// rejects deep inside an adapter, and with nothing catching it the CLI printed
|
|
@@ -40,7 +51,7 @@ async function run() {
|
|
|
40
51
|
await cmdUse(args);
|
|
41
52
|
break;
|
|
42
53
|
case 'doctor':
|
|
43
|
-
await cmdDoctor();
|
|
54
|
+
await cmdDoctor(args);
|
|
44
55
|
break;
|
|
45
56
|
case 'search':
|
|
46
57
|
await cmdSearch(args);
|
|
@@ -66,6 +77,9 @@ async function run() {
|
|
|
66
77
|
case 'stats':
|
|
67
78
|
await cmdStats();
|
|
68
79
|
break;
|
|
80
|
+
case 'update':
|
|
81
|
+
await cmdUpdate(args);
|
|
82
|
+
break;
|
|
69
83
|
case 'flush':
|
|
70
84
|
await cmdFlush();
|
|
71
85
|
break;
|
|
@@ -78,10 +92,167 @@ async function run() {
|
|
|
78
92
|
case 'merge':
|
|
79
93
|
await cmdMerge(args);
|
|
80
94
|
break;
|
|
95
|
+
case 'seed':
|
|
96
|
+
await cmdSeed(args);
|
|
97
|
+
break;
|
|
98
|
+
case 'sync':
|
|
99
|
+
await cmdSync(args);
|
|
100
|
+
break;
|
|
81
101
|
default:
|
|
82
102
|
usage();
|
|
83
103
|
}
|
|
84
104
|
}
|
|
105
|
+
/**
|
|
106
|
+
* Fills a cold memory from the history the repository already holds.
|
|
107
|
+
*
|
|
108
|
+
* The first weeks after an install are the worst time to be asking anyone to
|
|
109
|
+
* trust this: there is nothing in it, so every search comes back empty and the
|
|
110
|
+
* habit never forms. Git history is the one source available on day one, and
|
|
111
|
+
* unlike a generated summary it records what actually happened.
|
|
112
|
+
*/
|
|
113
|
+
async function cmdSeed(argv) {
|
|
114
|
+
if (!argv.includes('--from-git')) {
|
|
115
|
+
console.error('Usage: claude-db seed --from-git [--limit <n>]');
|
|
116
|
+
process.exit(1);
|
|
117
|
+
}
|
|
118
|
+
const limit = Number(valueOf(argv, '--limit') ?? 500);
|
|
119
|
+
if (!Number.isFinite(limit) || limit <= 0) {
|
|
120
|
+
console.error('--limit must be a positive number of commits.');
|
|
121
|
+
process.exit(1);
|
|
122
|
+
}
|
|
123
|
+
const project = resolveProject(undefined);
|
|
124
|
+
let observations;
|
|
125
|
+
try {
|
|
126
|
+
observations = observationsFromGit(project, limit);
|
|
127
|
+
}
|
|
128
|
+
catch (error) {
|
|
129
|
+
console.error(`Could not read git history: ${error instanceof Error ? error.message.split('\n')[0] : String(error)}`);
|
|
130
|
+
process.exit(1);
|
|
131
|
+
}
|
|
132
|
+
if (observations.length === 0) {
|
|
133
|
+
console.log(`No usable commits found in ${project}.`);
|
|
134
|
+
console.log('Merges, releases and commits touching no files are skipped.');
|
|
135
|
+
return;
|
|
136
|
+
}
|
|
137
|
+
const ctx = await createContext();
|
|
138
|
+
try {
|
|
139
|
+
for (let i = 0; i < observations.length; i += BATCH) {
|
|
140
|
+
const batch = observations.slice(i, i + BATCH);
|
|
141
|
+
await embedObservations(ctx, batch);
|
|
142
|
+
await ctx.store.insertObservations(batch);
|
|
143
|
+
}
|
|
144
|
+
}
|
|
145
|
+
finally {
|
|
146
|
+
await ctx.close();
|
|
147
|
+
}
|
|
148
|
+
// Ids come from the commit sha, so this is safe to repeat as history grows.
|
|
149
|
+
console.log(`Seeded ${observations.length} observation(s) from git history.`);
|
|
150
|
+
console.log(`Oldest: ${new Date(observations[observations.length - 1]?.createdAt ?? 0).toISOString().slice(0, 10)}`);
|
|
151
|
+
}
|
|
152
|
+
/**
|
|
153
|
+
* Two-way merge with another database.
|
|
154
|
+
*
|
|
155
|
+
* `export`/`import` only ever moves memory one way, which makes the second
|
|
156
|
+
* machine a copy rather than a peer. Content-derived ids make the real thing
|
|
157
|
+
* nearly free: an id present on one side and not the other is, by construction,
|
|
158
|
+
* memory the other side has never seen, so the merge needs no clocks, no
|
|
159
|
+
* conflict rules and no ordering.
|
|
160
|
+
*/
|
|
161
|
+
async function cmdSync(argv) {
|
|
162
|
+
const url = argv.find((arg) => typeof arg === 'string' && !arg.startsWith('-'));
|
|
163
|
+
const confirmed = argv.includes('--yes') || argv.includes('-y');
|
|
164
|
+
if (!url) {
|
|
165
|
+
console.error('Usage: claude-db sync <connection-string> [--yes]');
|
|
166
|
+
process.exit(1);
|
|
167
|
+
}
|
|
168
|
+
const local = await createContext();
|
|
169
|
+
if (local.config.database === url) {
|
|
170
|
+
await local.close();
|
|
171
|
+
console.error('That is the database memory already uses.');
|
|
172
|
+
process.exit(1);
|
|
173
|
+
}
|
|
174
|
+
const remote = await createStore(url);
|
|
175
|
+
try {
|
|
176
|
+
await remote.init();
|
|
177
|
+
// Ids only from the first pass. Holding both databases in memory at once
|
|
178
|
+
// is what would stop this working on the shared backend it exists for.
|
|
179
|
+
const localIds = new Set();
|
|
180
|
+
await eachRemoteObservation(local.store, (batch) => {
|
|
181
|
+
for (const obs of batch)
|
|
182
|
+
localIds.add(obs.id);
|
|
183
|
+
});
|
|
184
|
+
const remoteIds = new Set();
|
|
185
|
+
let pulled = 0;
|
|
186
|
+
await eachRemoteObservation(remote, async (batch) => {
|
|
187
|
+
for (const obs of batch)
|
|
188
|
+
remoteIds.add(obs.id);
|
|
189
|
+
const fresh = batch.filter((obs) => !localIds.has(obs.id));
|
|
190
|
+
if (fresh.length === 0)
|
|
191
|
+
return;
|
|
192
|
+
pulled += fresh.length;
|
|
193
|
+
if (confirmed)
|
|
194
|
+
await local.store.insertObservations(fresh);
|
|
195
|
+
});
|
|
196
|
+
let pushed = 0;
|
|
197
|
+
await eachRemoteObservation(local.store, async (batch) => {
|
|
198
|
+
const fresh = batch.filter((obs) => !remoteIds.has(obs.id));
|
|
199
|
+
if (fresh.length === 0)
|
|
200
|
+
return;
|
|
201
|
+
pushed += fresh.length;
|
|
202
|
+
if (confirmed)
|
|
203
|
+
await remote.insertObservations(fresh);
|
|
204
|
+
});
|
|
205
|
+
if (!confirmed) {
|
|
206
|
+
console.log(`This would pull ${pulled} and push ${pushed} observation(s).`);
|
|
207
|
+
console.log('\nNothing was transferred. Re-run with --yes to confirm.');
|
|
208
|
+
return;
|
|
209
|
+
}
|
|
210
|
+
// Sessions carry the recap injected at SessionStart, so memory that
|
|
211
|
+
// arrives without them reads as a pile of turns with no shape.
|
|
212
|
+
const sessions = await syncSessions(local.store, remote);
|
|
213
|
+
console.log(`Pulled ${pulled}, pushed ${pushed}, and reconciled ${sessions} session(s).`);
|
|
214
|
+
}
|
|
215
|
+
finally {
|
|
216
|
+
await remote.close();
|
|
217
|
+
await local.close();
|
|
218
|
+
}
|
|
219
|
+
}
|
|
220
|
+
/** Copies session records both ways for every project either side knows. */
|
|
221
|
+
async function syncSessions(local, remote) {
|
|
222
|
+
const projects = new Set();
|
|
223
|
+
for (const store of [local, remote]) {
|
|
224
|
+
for (const entry of await store.listProjects())
|
|
225
|
+
projects.add(entry.project);
|
|
226
|
+
}
|
|
227
|
+
let moved = 0;
|
|
228
|
+
for (const project of projects) {
|
|
229
|
+
for (const [from, to] of [[local, remote], [remote, local]]) {
|
|
230
|
+
for (const session of await from.recentSessions(project, 1000)) {
|
|
231
|
+
if (await to.getSession(session.id))
|
|
232
|
+
continue;
|
|
233
|
+
await to.upsertSession(session);
|
|
234
|
+
moved += 1;
|
|
235
|
+
}
|
|
236
|
+
}
|
|
237
|
+
}
|
|
238
|
+
return moved;
|
|
239
|
+
}
|
|
240
|
+
/** `eachObservation` against an arbitrary store rather than the local context. */
|
|
241
|
+
async function eachRemoteObservation(store, visit) {
|
|
242
|
+
let after = 0;
|
|
243
|
+
for (;;) {
|
|
244
|
+
const batch = await store.list({ after, limit: BATCH });
|
|
245
|
+
if (batch.length === 0)
|
|
246
|
+
return;
|
|
247
|
+
await visit(batch);
|
|
248
|
+
const last = batch[batch.length - 1];
|
|
249
|
+
if (!last)
|
|
250
|
+
return;
|
|
251
|
+
after = last.createdAt === after ? after + 1 : last.createdAt;
|
|
252
|
+
if (batch.length < BATCH)
|
|
253
|
+
return;
|
|
254
|
+
}
|
|
255
|
+
}
|
|
85
256
|
/** Shows how memory is partitioned, and which partition you are currently in. */
|
|
86
257
|
async function cmdProjects() {
|
|
87
258
|
const here = resolveProject(undefined);
|
|
@@ -246,9 +417,10 @@ async function cmdFlush() {
|
|
|
246
417
|
try {
|
|
247
418
|
for (const path of transcripts) {
|
|
248
419
|
const sessionId = basename(path, '.jsonl');
|
|
249
|
-
// Ignore any stored cursor: a manual flush is asking
|
|
420
|
+
// Ignore any stored cursor and the stored recap: a manual flush is asking
|
|
421
|
+
// for a full re-read, so both are rebuilt rather than extended.
|
|
250
422
|
resetCursor(sessionId);
|
|
251
|
-
const result = await flushSession(ctx, sessionId, project, path);
|
|
423
|
+
const result = await flushSession(ctx, sessionId, project, path, true);
|
|
252
424
|
if (result.observations > 0) {
|
|
253
425
|
console.log(`${sessionId.slice(0, 8)} ${String(result.observations).padStart(4)} observations`);
|
|
254
426
|
total += result.observations;
|
|
@@ -259,6 +431,9 @@ async function cmdFlush() {
|
|
|
259
431
|
await ctx.close();
|
|
260
432
|
}
|
|
261
433
|
console.log(`\n${total} observations from ${transcripts.length} transcript(s).`);
|
|
434
|
+
const swept = sweepCursors();
|
|
435
|
+
if (swept > 0)
|
|
436
|
+
console.log(`Swept ${swept} cursor(s) for transcripts that no longer exist.`);
|
|
262
437
|
}
|
|
263
438
|
/** `--project` limits the install to the current repo; default is machine-wide. */
|
|
264
439
|
function scopeFrom(args) {
|
|
@@ -279,6 +454,7 @@ async function cmdInstall(scope) {
|
|
|
279
454
|
console.log(`Scope : ${scope === 'project' ? `this project only (${project})` : 'all projects on this machine'}`);
|
|
280
455
|
console.log(`Settings : ${settingsPath}`);
|
|
281
456
|
console.log(`Guidance : ${instructionsPathFor(scope, project)}`);
|
|
457
|
+
console.log(`Skill : ${skillPathFor(scope, project)} (/cdb-scan)`);
|
|
282
458
|
console.log(`Config : ${CONFIG_PATH}`);
|
|
283
459
|
console.log(`Database : ${ctx.config.database}`);
|
|
284
460
|
console.log('\nRestart Claude Code to activate.');
|
|
@@ -344,11 +520,24 @@ async function cmdStatus() {
|
|
|
344
520
|
const mcpFile = [mcpPathFor('project', project), mcpPathFor('global', project)].find((candidate) => fileMentions(candidate, resolve(DIST_DIR, 'mcp', 'server.js')));
|
|
345
521
|
console.log(`mcp : ${mcpFile ? `registered (${mcpFile})` : 'NOT REGISTERED'}`);
|
|
346
522
|
console.log(`sessions : ${sessions.length} recorded for this project`);
|
|
523
|
+
const saved = (await ctx.store.listProjects()).find((entry) => entry.project === project);
|
|
524
|
+
const lastSaved = saved?.lastActive ?? 0;
|
|
525
|
+
const worked = workedAt(project);
|
|
526
|
+
console.log(`recorded : ${lastSaved > 0 ? ago(lastSaved) : 'never'}`);
|
|
347
527
|
if (active.length === 0) {
|
|
348
528
|
console.log('\nHooks are not registered, so nothing will ever be captured.');
|
|
349
529
|
console.log('Run this from the project you want to track:');
|
|
350
530
|
console.log(' claude-db install --project');
|
|
351
531
|
}
|
|
532
|
+
else if (hasStalled(lastSaved, worked)) {
|
|
533
|
+
console.log(`\nCapture looks stalled. This project was worked in ${ago(worked.last)},`);
|
|
534
|
+
console.log(lastSaved > 0
|
|
535
|
+
? `but the newest memory is from ${ago(lastSaved)}.`
|
|
536
|
+
: 'but nothing has ever been recorded for it.');
|
|
537
|
+
console.log('Nothing reports this on its own: hooks swallow their errors so a');
|
|
538
|
+
console.log('memory layer can never break a session. Check it end to end with:');
|
|
539
|
+
console.log(' claude-db doctor --deep');
|
|
540
|
+
}
|
|
352
541
|
else if (sessions.length === 0) {
|
|
353
542
|
console.log('\nInstalled, but nothing recorded yet. Memory is written as you');
|
|
354
543
|
console.log('work, on every prompt, and only for turns that changed something.');
|
|
@@ -359,6 +548,45 @@ async function cmdStatus() {
|
|
|
359
548
|
await ctx.close();
|
|
360
549
|
}
|
|
361
550
|
}
|
|
551
|
+
/** When this project's transcripts were first and last appended to. */
|
|
552
|
+
function workedAt(project) {
|
|
553
|
+
let first = Number.POSITIVE_INFINITY;
|
|
554
|
+
let last = 0;
|
|
555
|
+
for (const path of transcriptsFor(project)) {
|
|
556
|
+
try {
|
|
557
|
+
const { mtimeMs } = statSync(path);
|
|
558
|
+
first = Math.min(first, mtimeMs);
|
|
559
|
+
last = Math.max(last, mtimeMs);
|
|
560
|
+
}
|
|
561
|
+
catch {
|
|
562
|
+
// Deleted between listing and stat; nothing to learn from it.
|
|
563
|
+
}
|
|
564
|
+
}
|
|
565
|
+
return { first: Number.isFinite(first) ? first : 0, last };
|
|
566
|
+
}
|
|
567
|
+
/**
|
|
568
|
+
* Work happened and capture didn't — the signal every silent failure leaves.
|
|
569
|
+
*
|
|
570
|
+
* Measured from the last save, except when there has never been one: then the
|
|
571
|
+
* baseline is the *first* transcript, so an install done ten minutes ago reads
|
|
572
|
+
* as new rather than broken, while a project worked in for days with an empty
|
|
573
|
+
* database reads as broken, which it is.
|
|
574
|
+
*/
|
|
575
|
+
function hasStalled(lastSaved, worked) {
|
|
576
|
+
if (worked.last === 0)
|
|
577
|
+
return false;
|
|
578
|
+
return worked.last > (lastSaved > 0 ? lastSaved : worked.first) + STALL_MS;
|
|
579
|
+
}
|
|
580
|
+
function ago(when) {
|
|
581
|
+
const minutes = Math.max(0, Math.round((Date.now() - when) / 60_000));
|
|
582
|
+
const date = new Date(when).toISOString().slice(0, 10);
|
|
583
|
+
if (minutes < 90)
|
|
584
|
+
return `${minutes} minute(s) ago`;
|
|
585
|
+
const hours = Math.round(minutes / 60);
|
|
586
|
+
if (hours < 48)
|
|
587
|
+
return `${hours} hour(s) ago (${date})`;
|
|
588
|
+
return `${Math.round(hours / 24)} day(s) ago (${date})`;
|
|
589
|
+
}
|
|
362
590
|
/** True when a settings file contains one of our hook commands. */
|
|
363
591
|
function isInstalled(settingsPath) {
|
|
364
592
|
return fileMentions(settingsPath, resolve(DIST_DIR, 'hooks', 'session-end.js'));
|
|
@@ -387,15 +615,23 @@ async function cmdUse(argv) {
|
|
|
387
615
|
process.exit(1);
|
|
388
616
|
}
|
|
389
617
|
let kind = '';
|
|
618
|
+
let foreign = [];
|
|
619
|
+
let rows = 0;
|
|
390
620
|
try {
|
|
391
|
-
const
|
|
621
|
+
const store = await createStore(uri);
|
|
392
622
|
try {
|
|
393
|
-
if (!(await
|
|
623
|
+
if (!(await store.ping()))
|
|
394
624
|
throw new Error('connected, but it did not answer a ping');
|
|
395
|
-
kind =
|
|
625
|
+
kind = store.kind;
|
|
626
|
+
// Read before init(), which creates our two tables: after that there is
|
|
627
|
+
// no way to tell an empty memory database from someone's application
|
|
628
|
+
// database that we have just started writing into.
|
|
629
|
+
foreign = await store.inventory();
|
|
630
|
+
await store.init();
|
|
631
|
+
rows = await countObservations(store);
|
|
396
632
|
}
|
|
397
633
|
finally {
|
|
398
|
-
await
|
|
634
|
+
await store.close();
|
|
399
635
|
}
|
|
400
636
|
}
|
|
401
637
|
catch (error) {
|
|
@@ -407,18 +643,72 @@ async function cmdUse(argv) {
|
|
|
407
643
|
}
|
|
408
644
|
}
|
|
409
645
|
const config = loadConfig();
|
|
646
|
+
const previous = config.database;
|
|
410
647
|
config.database = uri;
|
|
411
648
|
saveConfig(config);
|
|
412
649
|
console.log(kind ? `Connected. Using ${kind}.` : 'Saved, unverified.');
|
|
650
|
+
if (foreign.length > 0) {
|
|
651
|
+
const shown = foreign.slice(0, 6).join(', ');
|
|
652
|
+
console.log(`\nNote: this database already holds ${foreign.length} other table(s)/collection(s):`);
|
|
653
|
+
console.log(` ${shown}${foreign.length > 6 ? ', ...' : ''}`);
|
|
654
|
+
console.log('claude-db has added its own next to them. An application database is a');
|
|
655
|
+
console.log('poor place to keep memory; point it elsewhere if that was not deliberate.');
|
|
656
|
+
}
|
|
657
|
+
if (kind && rows === 0)
|
|
658
|
+
await warnAboutStranding(previous, uri);
|
|
659
|
+
}
|
|
660
|
+
async function countObservations(store) {
|
|
661
|
+
return (await store.listProjects()).reduce((total, entry) => total + entry.observations, 0);
|
|
413
662
|
}
|
|
663
|
+
/**
|
|
664
|
+
* Switching backends leaves everything already recorded behind, in silence.
|
|
665
|
+
*
|
|
666
|
+
* Observed twice in one day: `use` pointed at Atlas, then at Aiven, and each
|
|
667
|
+
* time six hundred observations stayed in SQLite while the new backend started
|
|
668
|
+
* empty. `export`/`import` has always solved it, but only for someone who
|
|
669
|
+
* already knew there was something to solve.
|
|
670
|
+
*/
|
|
671
|
+
async function warnAboutStranding(previous, uri) {
|
|
672
|
+
if (!previous || previous === uri)
|
|
673
|
+
return;
|
|
674
|
+
let stranded = 0;
|
|
675
|
+
try {
|
|
676
|
+
const store = await createStore(previous);
|
|
677
|
+
try {
|
|
678
|
+
await store.init();
|
|
679
|
+
stranded = await countObservations(store);
|
|
680
|
+
}
|
|
681
|
+
finally {
|
|
682
|
+
await store.close();
|
|
683
|
+
}
|
|
684
|
+
}
|
|
685
|
+
catch {
|
|
686
|
+
return; // the old database is gone too; nothing to strand
|
|
687
|
+
}
|
|
688
|
+
if (stranded === 0)
|
|
689
|
+
return;
|
|
690
|
+
// The URL is shown only to identify which database, so its credentials are
|
|
691
|
+
// stripped: this is exactly the string people paste without thinking.
|
|
692
|
+
console.log(`\nThe database you just left (${redact(previous)})`);
|
|
693
|
+
console.log(`still holds ${stranded} observation(s), and this one is empty. Nothing moves`);
|
|
694
|
+
console.log('across on its own:');
|
|
695
|
+
console.log(' claude-db use <the previous url> && claude-db export --all > memory.jsonl');
|
|
696
|
+
console.log(' claude-db use <this url> && claude-db import memory.jsonl');
|
|
697
|
+
}
|
|
698
|
+
/** A driver error names the problem; these name the fix. */
|
|
414
699
|
function describe(error) {
|
|
415
700
|
const message = error instanceof Error ? error.message : String(error);
|
|
416
|
-
|
|
417
|
-
|
|
418
|
-
|
|
419
|
-
|
|
701
|
+
if (/ENOTFOUND|EAI_AGAIN/.test(message)) {
|
|
702
|
+
return `${message}\n(that host does not resolve — check the name, or whether the service still exists)`;
|
|
703
|
+
}
|
|
704
|
+
if (/self[- ]signed certificate|unable to verify the first certificate|SELF_SIGNED_CERT/i.test(message)) {
|
|
705
|
+
return (`${message}\n(managed Postgres signs with its own CA, which node does not trust by ` +
|
|
706
|
+
`default —\n append &sslmode=no-verify to the URL, or point &sslrootcert= at the CA ` +
|
|
707
|
+
`file\n the provider gives you)`);
|
|
708
|
+
}
|
|
709
|
+
return message;
|
|
420
710
|
}
|
|
421
|
-
async function cmdDoctor() {
|
|
711
|
+
async function cmdDoctor(argv) {
|
|
422
712
|
// No embedder timeout here: doctor is where you want to wait for a first
|
|
423
713
|
// model download, so that the hooks afterwards find it cached.
|
|
424
714
|
const base = loadConfig();
|
|
@@ -430,6 +720,7 @@ async function cmdDoctor() {
|
|
|
430
720
|
// embedder that cannot actually run is worse than printing nothing.
|
|
431
721
|
const embedder = await ctx.embedder();
|
|
432
722
|
const vectors = await probeEmbedder(embedder);
|
|
723
|
+
console.log(`version : ${packageVersion()}`);
|
|
433
724
|
console.log(`database : ${ctx.config.database}`);
|
|
434
725
|
console.log(`adapter : ${ctx.store.kind}`);
|
|
435
726
|
console.log(`reachable: ${reachable ? 'yes' : 'no'}`);
|
|
@@ -437,8 +728,58 @@ async function cmdDoctor() {
|
|
|
437
728
|
console.log(`embedder : ${embedder.id} (${embedder.dimensions}d)`);
|
|
438
729
|
console.log(`vectors : ${vectors}`);
|
|
439
730
|
console.log(`search : ${vectors.startsWith('working') ? 'hybrid (keyword + vector)' : 'keyword only'}`);
|
|
731
|
+
const healthy = argv.includes('--deep') ? await deepCheck(ctx) : true;
|
|
440
732
|
await ctx.close();
|
|
441
|
-
process.exit(reachable ? 0 : 1);
|
|
733
|
+
process.exit(reachable && healthy ? 0 : 1);
|
|
734
|
+
}
|
|
735
|
+
/**
|
|
736
|
+
* Proves capture, search and recall work *now*, instead of proving the database
|
|
737
|
+
* answers a ping.
|
|
738
|
+
*
|
|
739
|
+
* Every failure this tool has shipped was silent — hooks swallow their errors
|
|
740
|
+
* so a memory layer can never break a session — and each one left `doctor`
|
|
741
|
+
* reporting a healthy database it was no longer writing to. A round trip
|
|
742
|
+
* through the real adapter, embedder and index is the only thing that can tell
|
|
743
|
+
* the difference.
|
|
744
|
+
*/
|
|
745
|
+
async function deepCheck(ctx) {
|
|
746
|
+
const project = resolveProject(undefined);
|
|
747
|
+
// A single opaque token: FTS tokenises on non-word characters, so hyphens
|
|
748
|
+
// would split the canary into pieces other observations could match.
|
|
749
|
+
const canary = `zz${randomUUID().replace(/-/g, '')}`;
|
|
750
|
+
let ok = true;
|
|
751
|
+
const step = (label, passed, detail = '') => {
|
|
752
|
+
if (!passed)
|
|
753
|
+
ok = false;
|
|
754
|
+
console.log(` ${passed ? 'ok ' : 'FAIL'} ${label}${detail ? ` — ${detail}` : ''}`);
|
|
755
|
+
};
|
|
756
|
+
console.log('\ndeep check (writes one observation, then deletes it)');
|
|
757
|
+
let id = '';
|
|
758
|
+
try {
|
|
759
|
+
const written = await remember(ctx, {
|
|
760
|
+
project,
|
|
761
|
+
kind: 'context',
|
|
762
|
+
text: `claude-db self check ${canary}`,
|
|
763
|
+
});
|
|
764
|
+
id = written.id;
|
|
765
|
+
step('write', true, toShortId(id));
|
|
766
|
+
}
|
|
767
|
+
catch (error) {
|
|
768
|
+
step('write', false, error instanceof Error ? error.message : String(error));
|
|
769
|
+
return false;
|
|
770
|
+
}
|
|
771
|
+
try {
|
|
772
|
+
const found = await ctx.search.search({ text: canary, project, limit: 5 });
|
|
773
|
+
step('search', found.some((entry) => entry.id === id), `${found.length} result(s)`);
|
|
774
|
+
const [full] = await ctx.search.getObservations([id]);
|
|
775
|
+
step('expand', full?.body.includes(canary) === true);
|
|
776
|
+
}
|
|
777
|
+
finally {
|
|
778
|
+
// In a finally block so a failed search still takes the canary back out.
|
|
779
|
+
const deleted = await ctx.store.remove({ ids: [id] });
|
|
780
|
+
step('cleanup', deleted === 1, `${deleted} removed`);
|
|
781
|
+
}
|
|
782
|
+
return ok;
|
|
442
783
|
}
|
|
443
784
|
async function probeEmbedder(embedder) {
|
|
444
785
|
if (embedder.dimensions === 0)
|
|
@@ -455,9 +796,10 @@ async function probeEmbedder(embedder) {
|
|
|
455
796
|
}
|
|
456
797
|
async function cmdSearch(argv) {
|
|
457
798
|
const all = argv.includes('--all');
|
|
458
|
-
const
|
|
799
|
+
const tag = valueOf(argv, '--tag');
|
|
800
|
+
const query = withoutFlags(argv, ['--tag']).filter((arg) => arg !== '--all').join(' ');
|
|
459
801
|
if (!query.trim()) {
|
|
460
|
-
console.error('Usage: claude-db search [--all] <query>');
|
|
802
|
+
console.error('Usage: claude-db search [--all] [--tag <name>] <query>');
|
|
461
803
|
process.exit(1);
|
|
462
804
|
}
|
|
463
805
|
const ctx = await createContext();
|
|
@@ -466,6 +808,7 @@ async function cmdSearch(argv) {
|
|
|
466
808
|
// Scoping is right for injection, but "where did I solve this before" is
|
|
467
809
|
// inherently cross-project, and only the CLI can ask that question.
|
|
468
810
|
...(all ? {} : { project: resolveProject(undefined) }),
|
|
811
|
+
...(tag ? { tag } : {}),
|
|
469
812
|
limit: 10,
|
|
470
813
|
});
|
|
471
814
|
// Same short-id format the MCP tools emit, so ids copied from either place
|
|
@@ -474,21 +817,20 @@ async function cmdSearch(argv) {
|
|
|
474
817
|
const date = new Date(entry.createdAt).toISOString().slice(0, 10);
|
|
475
818
|
const where = all ? ` ${basename(entry.project)}` : '';
|
|
476
819
|
console.log(`${toShortId(entry.id)} ${entry.kind.padEnd(10)} ${date}${where} ${entry.title}`);
|
|
820
|
+
if (entry.snippet)
|
|
821
|
+
console.log(` ${entry.snippet}`);
|
|
477
822
|
}
|
|
478
823
|
if (results.length === 0)
|
|
479
824
|
console.log('No matching observations.');
|
|
480
825
|
await ctx.close();
|
|
481
826
|
}
|
|
482
827
|
async function cmdRemember(argv) {
|
|
483
|
-
const
|
|
484
|
-
const
|
|
485
|
-
const
|
|
486
|
-
|
|
487
|
-
: argv)
|
|
488
|
-
.join(' ')
|
|
489
|
-
.trim();
|
|
828
|
+
const kind = valueOf(argv, '--kind');
|
|
829
|
+
const key = valueOf(argv, '--key');
|
|
830
|
+
const tag = valueOf(argv, '--tag');
|
|
831
|
+
const text = withoutFlags(argv, ['--kind', '--key', '--tag']).join(' ').trim();
|
|
490
832
|
if (!text) {
|
|
491
|
-
console.error('Usage: claude-db remember [--kind <kind>] <text>');
|
|
833
|
+
console.error('Usage: claude-db remember [--kind <kind>] [--key <name>] [--tag <name>] <text>');
|
|
492
834
|
process.exit(1);
|
|
493
835
|
}
|
|
494
836
|
const ctx = await createContext();
|
|
@@ -497,6 +839,8 @@ async function cmdRemember(argv) {
|
|
|
497
839
|
project: resolveProject(undefined),
|
|
498
840
|
text,
|
|
499
841
|
...(kind ? { kind: kind } : {}),
|
|
842
|
+
...(key ? { key } : {}),
|
|
843
|
+
...(tag ? { tags: [tag] } : {}),
|
|
500
844
|
});
|
|
501
845
|
console.log(`Remembered ${toShortId(observation.id)} [${observation.kind}] ${observation.title}`);
|
|
502
846
|
}
|
|
@@ -703,27 +1047,65 @@ async function cmdStats() {
|
|
|
703
1047
|
await ctx.close();
|
|
704
1048
|
}
|
|
705
1049
|
}
|
|
1050
|
+
/**
|
|
1051
|
+
* Also the entry point the SessionEnd hook spawns detached, with --quiet.
|
|
1052
|
+
*/
|
|
1053
|
+
async function cmdUpdate(argv) {
|
|
1054
|
+
const quiet = argv.includes('--quiet');
|
|
1055
|
+
const config = loadConfig();
|
|
1056
|
+
// An explicit `claude-db update` means now, whatever the config says about
|
|
1057
|
+
// the background behaviour.
|
|
1058
|
+
const mode = quiet ? config.updates : 'auto';
|
|
1059
|
+
const result = await checkForUpdate(mode);
|
|
1060
|
+
if (quiet)
|
|
1061
|
+
return;
|
|
1062
|
+
if (result.installed)
|
|
1063
|
+
console.log(`Updated ${result.current} -> ${result.latest}.`);
|
|
1064
|
+
else if (result.latest && result.latest !== result.current) {
|
|
1065
|
+
console.log(`${result.latest} is available (running ${result.current}): ${result.reason}`);
|
|
1066
|
+
}
|
|
1067
|
+
else
|
|
1068
|
+
console.log(`Up to date (${result.current}).`);
|
|
1069
|
+
}
|
|
706
1070
|
function valueOf(argv, flag) {
|
|
707
1071
|
const index = argv.indexOf(flag);
|
|
708
1072
|
return index >= 0 ? argv[index + 1] : undefined;
|
|
709
1073
|
}
|
|
1074
|
+
/** Everything that is not one of the named flags or its value. */
|
|
1075
|
+
function withoutFlags(argv, flags) {
|
|
1076
|
+
const dropped = new Set();
|
|
1077
|
+
for (const flag of flags) {
|
|
1078
|
+
const at = argv.indexOf(flag);
|
|
1079
|
+
// Guarded: indexOf returns -1 for an absent flag, and dropping index 0
|
|
1080
|
+
// silently ate the first word of the text being remembered.
|
|
1081
|
+
if (at >= 0)
|
|
1082
|
+
dropped.add(at).add(at + 1);
|
|
1083
|
+
}
|
|
1084
|
+
return argv.filter((arg, index) => typeof arg === 'string' && !dropped.has(index));
|
|
1085
|
+
}
|
|
710
1086
|
function usage() {
|
|
711
1087
|
console.log(`claude-db
|
|
712
1088
|
|
|
713
1089
|
install [--project] Register hooks + MCP server with Claude Code
|
|
714
1090
|
uninstall [--project] Remove them again, leaving memory intact
|
|
715
1091
|
status Is it wired up, and has it recorded anything
|
|
716
|
-
doctor
|
|
1092
|
+
doctor [--deep] Show resolved config; --deep proves a full
|
|
1093
|
+
write, search, recall and delete round trip
|
|
717
1094
|
use [--force] <url> Point memory at a database, once it answers
|
|
718
1095
|
search [--all] <query> Search memory, this project or every project
|
|
1096
|
+
[--tag <name>] ...limited to one repo or top-level directory
|
|
719
1097
|
remember [--kind k] <text> Record something outright, e.g. a house rule
|
|
1098
|
+
[--key <name>] ...under a stable name, replacing any earlier one
|
|
720
1099
|
forget <id> [id...] Delete specific observations by id
|
|
721
1100
|
projects List every project with memory in this database
|
|
722
1101
|
merge [<old-path>] [--yes] Move memory from an old project path onto this one
|
|
723
1102
|
stats What this project's memory is made of
|
|
724
1103
|
flush Re-ingest every transcript for this project
|
|
1104
|
+
seed --from-git [--limit n] Fill a cold memory from this repo's history
|
|
725
1105
|
export [--all] > out.jsonl Dump memory as JSONL, for backup or migration
|
|
726
1106
|
import <file.jsonl> Load a dump back in (safe to repeat)
|
|
1107
|
+
sync <url> [--yes] Two-way merge with another database
|
|
1108
|
+
update Install a newer compatible release now
|
|
727
1109
|
reembed Re-embed everything with the current model
|
|
728
1110
|
prune --older-than <days> Delete old memory (dry run without --yes)
|
|
729
1111
|
reset [--project] --yes Delete stored memory (dry run without --yes)
|
package/dist/cli/install.d.ts
CHANGED
|
@@ -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
|
*
|
package/dist/cli/install.js
CHANGED
|
@@ -33,6 +33,28 @@ export function instructionsPathFor(scope, project) {
|
|
|
33
33
|
? join(project, 'CLAUDE.local.md')
|
|
34
34
|
: join(homedir(), '.claude', 'CLAUDE.md');
|
|
35
35
|
}
|
|
36
|
+
/**
|
|
37
|
+
* Where the `/cdb-scan` skill is installed.
|
|
38
|
+
*
|
|
39
|
+
* A skill rather than a CLI command: surveying a codebase means reading it, and
|
|
40
|
+
* the agent is already sitting in the repo with the tools to do that. A command
|
|
41
|
+
* would need its own model, its own key and its own opinion about what matters.
|
|
42
|
+
*/
|
|
43
|
+
export function skillPathFor(scope, project) {
|
|
44
|
+
const root = scope === 'project' ? join(project, '.claude') : join(homedir(), '.claude');
|
|
45
|
+
return join(root, 'skills', 'cdb-scan', 'SKILL.md');
|
|
46
|
+
}
|
|
47
|
+
function writeSkill(distDir, scope, project) {
|
|
48
|
+
const source = resolve(distDir, '..', 'skills', 'cdb-scan', 'SKILL.md');
|
|
49
|
+
const body = readText(source);
|
|
50
|
+
// Absent only in a partial checkout; the rest of the install still stands.
|
|
51
|
+
if (body.length > 0)
|
|
52
|
+
writeAtomic(skillPathFor(scope, project), body);
|
|
53
|
+
}
|
|
54
|
+
function removeSkill(scope, project) {
|
|
55
|
+
const path = skillPathFor(scope, project);
|
|
56
|
+
rmSync(dirname(path), { recursive: true, force: true });
|
|
57
|
+
}
|
|
36
58
|
const BLOCK_START = '<!-- claude-db:start -->';
|
|
37
59
|
const BLOCK_END = '<!-- claude-db:end -->';
|
|
38
60
|
const INSTRUCTIONS = [
|
|
@@ -165,6 +187,7 @@ export function install(distDir, scope, project) {
|
|
|
165
187
|
writeJson(path, settings);
|
|
166
188
|
const server = resolve(distDir, 'mcp', 'server.js');
|
|
167
189
|
writeInstructions(instructionsPathFor(scope, project));
|
|
190
|
+
writeSkill(distDir, scope, project);
|
|
168
191
|
// A global install lands in ~/.claude.json, which holds all of Claude Code's
|
|
169
192
|
// own state. Let its CLI own that file rather than round-tripping megabytes
|
|
170
193
|
// of someone else's config through JSON.parse to add one key. The direct
|
|
@@ -225,6 +248,7 @@ export function uninstall(distDir, scope, project) {
|
|
|
225
248
|
delete settings['hooks'];
|
|
226
249
|
writeJson(path, settings);
|
|
227
250
|
removeInstructions(instructionsPathFor(scope, project));
|
|
251
|
+
removeSkill(scope, project);
|
|
228
252
|
// Symmetric with install: if the CLI put it there, the CLI takes it out.
|
|
229
253
|
if (scope === 'global' && claudeMcp(['mcp', 'remove', 'memory', '-s', 'user'])) {
|
|
230
254
|
return path;
|