claude-db 0.13.0 → 0.14.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 (105) hide show
  1. package/CHANGELOG.md +56 -0
  2. package/dist/capture/cursors.d.ts +1 -3
  3. package/dist/capture/cursors.js +16 -35
  4. package/dist/capture/flush.d.ts +1 -3
  5. package/dist/capture/flush.js +34 -34
  6. package/dist/capture/progress.js +4 -2
  7. package/dist/capture/transcript.d.ts +1 -1
  8. package/dist/capture/transcript.js +6 -6
  9. package/dist/catchup/gather.js +1 -1
  10. package/dist/cli/commands/catchup.js +2 -1
  11. package/dist/cli/commands/graph.js +9 -10
  12. package/dist/cli/commands/insight.js +10 -1
  13. package/dist/cli/commands/memory.js +2 -1
  14. package/dist/cli/commands/setup.js +1 -2
  15. package/dist/cli/commands/sync.js +4 -1
  16. package/dist/cli/install.js +1 -2
  17. package/dist/cli/instructions.d.ts +1 -3
  18. package/dist/cli/instructions.js +5 -40
  19. package/dist/cli/refresh.js +2 -6
  20. package/dist/config/load.js +2 -1
  21. package/dist/config/schema.d.ts +0 -2
  22. package/dist/config/schema.js +0 -2
  23. package/dist/context.js +16 -7
  24. package/dist/daemon/client.d.ts +5 -3
  25. package/dist/daemon/client.js +43 -25
  26. package/dist/daemon/paths.d.ts +3 -1
  27. package/dist/daemon/pid.d.ts +3 -0
  28. package/dist/daemon/pid.js +20 -0
  29. package/dist/daemon/server.js +9 -7
  30. package/dist/embed/local.js +4 -1
  31. package/dist/facts/claude-memory.js +2 -2
  32. package/dist/facts/last-chat.d.ts +1 -1
  33. package/dist/facts/last-chat.js +5 -4
  34. package/dist/facts/model.d.ts +1 -1
  35. package/dist/facts/model.js +20 -16
  36. package/dist/facts/start-render.d.ts +13 -0
  37. package/dist/facts/start-render.js +43 -0
  38. package/dist/facts/start.d.ts +3 -6
  39. package/dist/facts/start.js +32 -46
  40. package/dist/graph/grammars.js +2 -1
  41. package/dist/graph/index.d.ts +1 -1
  42. package/dist/graph/index.js +1 -1
  43. package/dist/graph/query/index.d.ts +1 -0
  44. package/dist/graph/query/index.js +1 -0
  45. package/dist/graph/query/stale.js +19 -2
  46. package/dist/graph/query/usages.d.ts +12 -0
  47. package/dist/graph/query/usages.js +37 -0
  48. package/dist/graph/scan/cache.js +2 -1
  49. package/dist/graph/scan/files.js +2 -2
  50. package/dist/hooks/compact.d.ts +1 -0
  51. package/dist/hooks/compact.js +3 -2
  52. package/dist/hooks/detached.d.ts +0 -1
  53. package/dist/hooks/detached.js +2 -6
  54. package/dist/hooks/grep-symbols.d.ts +3 -1
  55. package/dist/hooks/grep-symbols.js +41 -2
  56. package/dist/hooks/handlers/prefer-usages.js +15 -10
  57. package/dist/hooks/handlers/session-end.js +4 -6
  58. package/dist/hooks/handlers/session-start.js +19 -40
  59. package/dist/hooks/handlers/turn-end.js +1 -1
  60. package/dist/hooks/handlers/user-prompt.js +5 -5
  61. package/dist/hooks/local.js +0 -1
  62. package/dist/hooks/payload.js +6 -5
  63. package/dist/hooks/pick-deliver.js +2 -1
  64. package/dist/hooks/prompt-recall.d.ts +4 -2
  65. package/dist/hooks/prompt-recall.js +10 -10
  66. package/dist/hooks/route.js +8 -3
  67. package/dist/hooks/run.d.ts +1 -2
  68. package/dist/mcp/tools/ids.d.ts +3 -0
  69. package/dist/mcp/tools/ids.js +6 -0
  70. package/dist/mcp/tools/memory.js +2 -1
  71. package/dist/mcp/tools/observations.js +3 -2
  72. package/dist/mcp/tools/search.js +4 -9
  73. package/dist/mcp/tools/usages.js +18 -44
  74. package/dist/pick/worker.js +1 -2
  75. package/dist/search/service.d.ts +5 -0
  76. package/dist/search/service.js +11 -5
  77. package/dist/store/postgres/filters.d.ts +1 -0
  78. package/dist/store/postgres/filters.js +3 -0
  79. package/dist/store/postgres/graph.js +3 -2
  80. package/dist/store/postgres/index.js +3 -1
  81. package/dist/store/postgres/meta.d.ts +1 -0
  82. package/dist/store/postgres/meta.js +4 -0
  83. package/dist/store/postgres/observations.js +3 -3
  84. package/dist/store/project-resolver.d.ts +1 -0
  85. package/dist/store/project-resolver.js +1 -1
  86. package/dist/store/scoped-store.js +3 -1
  87. package/dist/store/sqlite/filters.d.ts +1 -0
  88. package/dist/store/sqlite/filters.js +6 -2
  89. package/dist/store/sqlite/graph.js +3 -2
  90. package/dist/store/sqlite/observations.js +6 -7
  91. package/dist/util/claude-binary.js +5 -4
  92. package/dist/util/claude-cli.js +2 -1
  93. package/dist/util/claude-dir.d.ts +2 -0
  94. package/dist/util/claude-dir.js +8 -0
  95. package/dist/util/env.d.ts +2 -0
  96. package/dist/util/env.js +6 -0
  97. package/dist/util/shortid.d.ts +3 -0
  98. package/dist/util/shortid.js +11 -0
  99. package/docs/how-it-works.md +5 -10
  100. package/docs/setup-guide.md +1 -1
  101. package/package.json +7 -6
  102. package/dist/capture/flush-lock.d.ts +0 -11
  103. package/dist/capture/flush-lock.js +0 -108
  104. package/dist/hooks/start-legacy.d.ts +0 -6
  105. package/dist/hooks/start-legacy.js +0 -47
package/CHANGELOG.md CHANGED
@@ -1,5 +1,61 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.14.0
4
+
5
+ ### Added
6
+
7
+ - **A contract test runs the same checks on all three stores.** `npm test` runs it on SQLite, and CI on Postgres
8
+ and MongoDB.
9
+ - **`npm run bench:inject -- <project> --compare-rank` compares four search rankings** on your own chats, judged
10
+ by Haiku or by a labels file (`--labels`).
11
+
12
+ ### Changed
13
+
14
+ - **Install no longer writes to `CLAUDE.md`.** The MCP server's own instructions already tell Claude when to
15
+ search memory. A block an older version wrote into `CLAUDE.local.md` or `~/.claude/CLAUDE.md` is removed at the
16
+ next chat start, and your own text is kept.
17
+ - **A grep for a code symbol runs as usual.** The graph's answer is added next to it, only for a symbol lookup
18
+ inside the repository. `CLAUDE_DB_USAGES_HOOK=deny` brings back the old blocking.
19
+ - **The start of a chat shows each thing once.** One block replaces the three that could repeat a chat's
20
+ summary, its turns and its open work, and the next prompt's pick skips what the start already showed. The scan
21
+ hint and update notice are shown to you, not to Claude.
22
+ - **Shorter `find_usages` and `search` descriptions.**
23
+ - **`sync` says what it copies:** rows the other side is missing, and status changes. Edits and deletes do not
24
+ travel.
25
+ - **Saving a chat writes only what changed.** A save compares its rows with the stored ones, so a chat with
26
+ nothing new writes nothing. The per-chat lock and `.written` files are gone, and old ones are cleared.
27
+ - **`npm test` builds first.**
28
+ - **The `capture.tools` and `inject.sessions` settings are removed.** A config that still has them loads.
29
+
30
+ ### Fixed
31
+
32
+ - **`forget` refuses an empty, wildcard or too-short id.** One could delete memory in every project.
33
+ - **`claude-db merge <subfolder>` no longer deletes the project it merges into.**
34
+ - **Saving a turn no longer closes open work in other clones of the same repository.**
35
+ - **`get_observations` and `timeline` refuse ids that are not observation ids.** An empty id read every row.
36
+ - **`find_usages` takes its root from the project and uses `path` only as a filter**, so a path in another
37
+ repository no longer replaces this project's graph. `claude-db scan --path` does the same.
38
+ - **The code graph is read again after an upgrade**, and a deleted file no longer keeps it stale.
39
+ - **`find_usages` no longer lists false callers** on SQLite and Postgres for names that differ in case or
40
+ contain `_`.
41
+ - **A chat summary is no longer lost when a save stops halfway.**
42
+ - **With `CLAUDE_CONFIG_DIR` set, chats are found and their read positions are kept.**
43
+ - **Haiku calls no longer receive the start block or start a graph scan.**
44
+ - **A replaced row is no longer marked done on SQLite.**
45
+ - **MongoDB search reads `-word` and quotes as plain words.**
46
+ - **Postgres notices pgvector installed after its first run.**
47
+ - **Two rows with one id in one save keep the last one on every backend.**
48
+ - **An id prefix is matched literally on SQLite and Postgres.** `%` used to match every row.
49
+ - **The pick at a prompt always has Claude's previous reply.** A save already running for the chat could make
50
+ it skip.
51
+ - **With the daemon on, each hook uses its own environment.** `CLAUDE_CONFIG_DIR` and the `claude` binary for
52
+ Haiku calls came from the shell that started the daemon.
53
+ - **A stuck daemon no longer holds up a hook.** One that does not answer within 2 s is replaced, and the hook
54
+ does its own work. A hook used to wait up to 50 s.
55
+ - **A failed load of the embedding model is tried again after a minute**, instead of staying off for the life of
56
+ the process.
57
+ - **Facts about you follow a changed git email within a minute.**
58
+
3
59
  ## 0.13.0
4
60
 
5
61
  ### Added
@@ -1,7 +1,5 @@
1
- export declare function readWritten(sessionId: string): Map<string, string>;
2
- export declare function writeWritten(sessionId: string, prints: ReadonlyMap<string, string>): void;
3
1
  export declare function readCursor(sessionId: string): number;
4
- export declare function advanceCursor(sessionId: string, from: number, to: number): void;
2
+ export declare function writeCursor(sessionId: string, offset: number): void;
5
3
  export declare function resetCursor(sessionId: string): void;
6
4
  export declare function clearCursor(sessionId: string): void;
7
5
  export declare function sweepCursorsDaily(now?: number): number;
@@ -1,34 +1,15 @@
1
- import { mkdirSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from 'node:fs';
1
+ import { mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
2
2
  import { dirname, join } from 'node:path';
3
3
  import { CONFIG_DIR } from '../config/index.js';
4
4
  import { sessionIdsOnDisk } from './transcript.js';
5
5
  const SWEEP_EVERY_MS = 24 * 60 * 60 * 1000;
6
+ const LEGACY_FILE = /\.(written|lock|lock\.break)$/;
6
7
  function cursorName(sessionId) {
7
8
  return `${sessionId.replace(/[^\w-]/g, '_')}.offset`;
8
9
  }
9
10
  function cursorPath(sessionId) {
10
11
  return join(CONFIG_DIR, 'cursors', cursorName(sessionId));
11
12
  }
12
- const writtenPath = (sessionId) => cursorPath(sessionId).replace(/\.offset$/, '.written');
13
- export function readWritten(sessionId) {
14
- try {
15
- const parsed = JSON.parse(readFileSync(writtenPath(sessionId), 'utf8'));
16
- if (!parsed || typeof parsed !== 'object')
17
- return new Map();
18
- return new Map(Object.entries(parsed).filter((entry) => typeof entry[1] === 'string'));
19
- }
20
- catch {
21
- return new Map();
22
- }
23
- }
24
- export function writeWritten(sessionId, prints) {
25
- const path = writtenPath(sessionId);
26
- try {
27
- mkdirSync(dirname(path), { recursive: true });
28
- writeFileSync(path, JSON.stringify(Object.fromEntries(prints)), 'utf8');
29
- }
30
- catch { }
31
- }
32
13
  export function readCursor(sessionId) {
33
14
  try {
34
15
  const value = Number.parseInt(readFileSync(cursorPath(sessionId), 'utf8'), 10);
@@ -38,13 +19,7 @@ export function readCursor(sessionId) {
38
19
  return 0;
39
20
  }
40
21
  }
41
- export function advanceCursor(sessionId, from, to) {
42
- const now = readCursor(sessionId);
43
- if (now !== from && now > to)
44
- return;
45
- writeCursor(sessionId, to);
46
- }
47
- function writeCursor(sessionId, offset) {
22
+ export function writeCursor(sessionId, offset) {
48
23
  const path = cursorPath(sessionId);
49
24
  try {
50
25
  mkdirSync(dirname(path), { recursive: true });
@@ -54,20 +29,20 @@ function writeCursor(sessionId, offset) {
54
29
  }
55
30
  export function resetCursor(sessionId) {
56
31
  writeCursor(sessionId, 0);
57
- rmSync(writtenPath(sessionId), { force: true });
58
32
  }
59
33
  export function clearCursor(sessionId) {
60
34
  rmSync(cursorPath(sessionId), { force: true });
61
35
  rmSync(cursorPath(sessionId).replace(/\.offset$/, '.shown'), { force: true });
62
- rmSync(writtenPath(sessionId), { force: true });
63
36
  }
64
37
  export function sweepCursorsDaily(now = Date.now()) {
65
38
  const marker = join(CONFIG_DIR, 'cursors', '.swept');
39
+ let lastSweep = 0;
66
40
  try {
67
- if (now - statSync(marker).mtimeMs < SWEEP_EVERY_MS)
68
- return 0;
41
+ lastSweep = Number(readFileSync(marker, 'utf8')) || 0;
69
42
  }
70
43
  catch { }
44
+ if (now - lastSweep < SWEEP_EVERY_MS)
45
+ return 0;
71
46
  try {
72
47
  mkdirSync(dirname(marker), { recursive: true });
73
48
  writeFileSync(marker, String(now), 'utf8');
@@ -86,10 +61,16 @@ export function sweepCursors() {
86
61
  catch {
87
62
  return 0;
88
63
  }
89
- const live = new Set(sessionIdsOnDisk().map((id) => id.replace(/[^\w-]/g, '_')));
90
- let removed = 0;
64
+ const legacy = files.filter((file) => LEGACY_FILE.test(file));
65
+ for (const file of legacy)
66
+ rmSync(join(dir, file), { force: true });
67
+ const onDisk = sessionIdsOnDisk();
68
+ if (onDisk === null)
69
+ return legacy.length;
70
+ const live = new Set(onDisk.map((id) => id.replace(/[^\w-]/g, '_')));
71
+ let removed = legacy.length;
91
72
  for (const file of files) {
92
- const match = /^(.+)\.(offset|shown|written)$/.exec(file);
73
+ const match = /^(.+)\.(offset|shown)$/.exec(file);
93
74
  if (!match?.[1] || live.has(match[1]))
94
75
  continue;
95
76
  rmSync(join(dir, file), { force: true });
@@ -1,13 +1,11 @@
1
1
  import type { RecallContext } from '../context.js';
2
2
  import type { Observation } from '../types.js';
3
- import type { FlushLockOptions } from './flush-lock.js';
4
3
  export interface FlushResult {
5
4
  observations: number;
6
5
  summary: string | null;
7
6
  lastReply: string;
8
- skipped?: boolean;
9
7
  }
10
- export declare function flushSession(ctx: RecallContext, sessionId: string, project: string, transcriptPath?: string, rebuild?: boolean, finalReply?: string, lock?: FlushLockOptions): Promise<FlushResult>;
8
+ export declare function flushSession(ctx: RecallContext, sessionId: string, project: string, transcriptPath?: string, rebuild?: boolean, finalReply?: string): Promise<FlushResult>;
11
9
  export declare function embedObservations(ctx: RecallContext, observations: Observation[]): Promise<void>;
12
10
  export declare function summarize(observations: Observation[], previous?: string): string;
13
11
  export { clearCursor, resetCursor, sweepCursors, sweepCursorsDaily } from './cursors.js';
@@ -1,46 +1,24 @@
1
- import { createHash } from 'node:crypto';
2
1
  import { readTranscript, transcriptPathFor } from './transcript.js';
3
2
  import { observationsFromTurns } from './turn-extractor.js';
4
3
  import { closeLandedWork } from './progress.js';
5
4
  import { noteMissingVectors } from './vectors.js';
6
- import { advanceCursor, readCursor, readWritten, writeWritten } from './cursors.js';
7
- import { withFlushLock } from './flush-lock.js';
8
- export async function flushSession(ctx, sessionId, project, transcriptPath, rebuild = false, finalReply = '', lock = {}) {
9
- const result = await withFlushLock(sessionId, () => flushUnlocked(ctx, sessionId, project, transcriptPath, rebuild, finalReply), lock);
10
- if (result.ran)
11
- return result.value;
12
- return { observations: 0, summary: null, lastReply: '', skipped: true };
13
- }
14
- async function flushUnlocked(ctx, sessionId, project, transcriptPath, rebuild, finalReply) {
5
+ import { readCursor, writeCursor } from './cursors.js';
6
+ const LOOKUP_CHUNK = 500;
7
+ export async function flushSession(ctx, sessionId, project, transcriptPath, rebuild = false, finalReply = '') {
15
8
  const path = transcriptPath ?? transcriptPathFor(project, sessionId);
16
- const cursor = readCursor(sessionId);
17
- const read = readTranscript(path, cursor);
18
- const { nextOffset } = read;
9
+ const read = readTranscript(path, readCursor(sessionId));
19
10
  const turns = withFinalReply(read.turns, finalReply);
20
11
  const lastReply = turns.at(-1)?.reasoning ?? '';
21
- if (turns.length === 0) {
22
- await closeLandedWork(ctx.store, project);
23
- advanceCursor(sessionId, cursor, nextOffset);
24
- return { observations: 0, summary: null, lastReply };
25
- }
26
12
  const observations = observationsFromTurns(turns, sessionId, project, ctx.config);
27
- if (observations.length === 0) {
28
- await closeLandedWork(ctx.store, project);
29
- advanceCursor(sessionId, cursor, nextOffset);
30
- return { observations: 0, summary: null, lastReply };
31
- }
32
- const written = rebuild ? new Map() : readWritten(sessionId);
33
- const prints = new Map(observations.map((obs) => [obs.id, printOf(obs)]));
34
- const fresh = observations.filter((obs) => written.get(obs.id) !== prints.get(obs.id));
35
- if (fresh.length === 0) {
13
+ const stored = rebuild
14
+ ? new Map()
15
+ : await storedRows(ctx.store, observations);
16
+ const changed = observations.filter((obs) => !sameRow(obs, stored.get(obs.id)));
17
+ if (changed.length === 0) {
36
18
  await closeLandedWork(ctx.store, project);
37
- advanceCursor(sessionId, cursor, nextOffset);
19
+ writeCursor(sessionId, read.nextOffset);
38
20
  return { observations: 0, summary: null, lastReply };
39
21
  }
40
- await embedObservations(ctx, fresh);
41
- await ctx.store.insertObservations(fresh);
42
- writeWritten(sessionId, prints);
43
- await closeLandedWork(ctx.store, project);
44
22
  const previous = rebuild ? null : await ctx.store.getSession(sessionId);
45
23
  const summary = summarize(observations, previous?.summary);
46
24
  await ctx.store.upsertSession({
@@ -49,9 +27,32 @@ async function flushUnlocked(ctx, sessionId, project, transcriptPath, rebuild, f
49
27
  startedAt: observations[0]?.createdAt ?? Date.now(),
50
28
  summary,
51
29
  });
52
- advanceCursor(sessionId, cursor, nextOffset);
30
+ await embedObservations(ctx, changed);
31
+ await ctx.store.insertObservations(changed);
32
+ await closeLandedWork(ctx.store, project);
33
+ writeCursor(sessionId, read.nextOffset);
53
34
  return { observations: observations.length, summary, lastReply };
54
35
  }
36
+ async function storedRows(store, observations) {
37
+ const ids = observations.map((obs) => obs.id);
38
+ const found = new Map();
39
+ for (let start = 0; start < ids.length; start += LOOKUP_CHUNK) {
40
+ for (const row of await store.getObservations(ids.slice(start, start + LOOKUP_CHUNK))) {
41
+ found.set(row.id, row);
42
+ }
43
+ }
44
+ return found;
45
+ }
46
+ const sameList = (a, b) => a.length === b.length && a.every((item, index) => item === b[index]);
47
+ function sameRow(fresh, stored) {
48
+ return (stored !== undefined &&
49
+ fresh.kind === stored.kind &&
50
+ fresh.title === stored.title &&
51
+ fresh.body === stored.body &&
52
+ fresh.createdAt === stored.createdAt &&
53
+ sameList(fresh.files, stored.files) &&
54
+ sameList(fresh.tags, stored.tags));
55
+ }
55
56
  export async function embedObservations(ctx, observations) {
56
57
  if (observations.length === 0)
57
58
  return;
@@ -109,5 +110,4 @@ export function summarize(observations, previous) {
109
110
  }
110
111
  return kept.join(' | ');
111
112
  }
112
- const printOf = (obs) => createHash('sha256').update(JSON.stringify(obs)).digest('base64url');
113
113
  export { clearCursor, resetCursor, sweepCursors, sweepCursorsDaily } from './cursors.js';
@@ -1,5 +1,5 @@
1
1
  import { execFileSync } from 'node:child_process';
2
- import { join } from 'node:path';
2
+ import { join, sep } from 'node:path';
3
3
  const MAX_BUFFER = 16 * 1024 * 1024;
4
4
  const OPEN_LIMIT = 500;
5
5
  function uncommittedFiles(project) {
@@ -29,6 +29,7 @@ function uncommittedFiles(project) {
29
29
  return null;
30
30
  }
31
31
  }
32
+ const isInside = (file, folder) => file.startsWith(folder + sep);
32
33
  export async function closeLandedWork(store, project) {
33
34
  const dirty = uncommittedFiles(project);
34
35
  if (!dirty)
@@ -48,7 +49,8 @@ export async function closeLandedWork(store, project) {
48
49
  if (batch.length === 0)
49
50
  break;
50
51
  for (const obs of batch) {
51
- if (obs.files.every((file) => !dirty.has(file)))
52
+ const mine = obs.files.every((file) => isInside(file, project));
53
+ if (mine && obs.files.every((file) => !dirty.has(file)))
52
54
  landed.push(obs.id);
53
55
  }
54
56
  const last = batch[batch.length - 1];
@@ -15,4 +15,4 @@ export declare function readTranscript(path: string, fromOffset?: number): Trans
15
15
  export declare function isSyntheticPrompt(text: string): boolean;
16
16
  export declare function transcriptPathFor(project: string, sessionId: string): string;
17
17
  export declare function transcriptsFor(project: string): string[];
18
- export declare function sessionIdsOnDisk(): string[];
18
+ export declare function sessionIdsOnDisk(): string[] | null;
@@ -1,7 +1,7 @@
1
1
  import { closeSync, fstatSync, openSync, readdirSync, readSync } from 'node:fs';
2
- import { homedir } from 'node:os';
3
2
  import { join } from 'node:path';
4
3
  import { isRelayedMessage } from '../util/prompt.js';
4
+ import { claudeProjectsDir } from '../util/claude-dir.js';
5
5
  import { resolveProject } from '../util/project.js';
6
6
  export function readTranscript(path, fromOffset = 0) {
7
7
  let fd;
@@ -132,10 +132,10 @@ function projectSlug(project) {
132
132
  return project.replace(/[^a-zA-Z0-9]/g, '-');
133
133
  }
134
134
  export function transcriptPathFor(project, sessionId) {
135
- return join(homedir(), '.claude', 'projects', projectSlug(project), `${sessionId}.jsonl`);
135
+ return join(claudeProjectsDir(), projectSlug(project), `${sessionId}.jsonl`);
136
136
  }
137
137
  export function transcriptsFor(project) {
138
- const root = join(homedir(), '.claude', 'projects');
138
+ const root = claudeProjectsDir();
139
139
  const slug = projectSlug(project);
140
140
  let candidates;
141
141
  try {
@@ -163,14 +163,14 @@ export function transcriptsFor(project) {
163
163
  return transcripts.sort();
164
164
  }
165
165
  export function sessionIdsOnDisk() {
166
- const root = join(homedir(), '.claude', 'projects');
166
+ const root = claudeProjectsDir();
167
167
  const ids = [];
168
168
  let dirs;
169
169
  try {
170
170
  dirs = readdirSync(root);
171
171
  }
172
- catch {
173
- return ids;
172
+ catch (error) {
173
+ return error.code === 'ENOENT' ? ids : null;
174
174
  }
175
175
  for (const dir of dirs) {
176
176
  try {
@@ -43,7 +43,7 @@ export async function gatherCatchup(ctx, project, current, now = Date.now()) {
43
43
  unfinished: unfinished.map((entry) => ({ at: entry.askedAt, request: entry.request })),
44
44
  chats: chats.map((chat) => ({
45
45
  at: chat.at,
46
- summary: chat.summary,
46
+ summary: chat.summary.join('; ') || null,
47
47
  work: chat.turns.map(turnLine),
48
48
  })),
49
49
  todos,
@@ -2,11 +2,12 @@ import { gatherCatchup } from '../../catchup/gather.js';
2
2
  import { renderCatchup } from '../../catchup/render.js';
3
3
  import { createContext } from '../../context.js';
4
4
  import { resolveProject } from '../../util/project.js';
5
+ import { hookEnv } from '../../util/env.js';
5
6
  export async function cmdCatchup() {
6
7
  const project = resolveProject(undefined);
7
8
  const ctx = await createContext();
8
9
  try {
9
- const current = process.env['CLAUDE_CODE_SESSION_ID'] || undefined;
10
+ const current = hookEnv()['CLAUDE_CODE_SESSION_ID'] || undefined;
10
11
  console.log(renderCatchup(await gatherCatchup(ctx, project, current)));
11
12
  }
12
13
  finally {
@@ -1,6 +1,6 @@
1
1
  import { createContext } from '../../context.js';
2
2
  import { findUsages, formatUsages, repoRootFor } from '../../usages/index.js';
3
- import { NO_GRAPH, NO_GRAPH_FOR_PATH, answerQuery, formatGraph, hasGraph, languageNames, refreshGraph, saveScan, scanRepository, suggestFor, } from '../../graph/index.js';
3
+ import { NO_GRAPH, NO_GRAPH_FOR_PATH, hasGraph, languageNames, refreshGraph, saveScan, scanRepository, suggestFor, usagesAnswer, } from '../../graph/index.js';
4
4
  import { PLATFORM } from '../../graph/grammars.js';
5
5
  import { GRAPH_JOB } from '../../graph/scan/job.js';
6
6
  import { keepJob, releaseJob } from '../../util/job-lock.js';
@@ -44,9 +44,8 @@ async function runRefresh(root, project) {
44
44
  }
45
45
  }
46
46
  export async function cmdScan(argv) {
47
- const path = valueOf(argv, '--path');
48
- const root = repoRootFor(path ?? process.cwd());
49
- const project = resolveProject(undefined);
47
+ const project = resolveProject(valueOf(argv, '--path'));
48
+ const root = repoRootFor(project);
50
49
  if (!argv.includes('--background')) {
51
50
  await runScan(root, project, argv.includes('--force'));
52
51
  return;
@@ -113,16 +112,16 @@ async function graphAnswer(store, input) {
113
112
  fail(NO_GRAPH_FOR_PATH);
114
113
  return `${NO_GRAPH}\n${await textAnswer(store, input)}`;
115
114
  }
116
- const root = repoRootFor(input.path ?? process.cwd());
117
115
  const mode = input.mode === 'text' ? 'usages' : input.mode;
118
- const answer = await answerQuery({
116
+ return usagesAnswer({
119
117
  store,
120
- root,
121
118
  project,
122
- query: { mode, symbol, ...(target ? { target } : {}), limit: input.limit },
123
- refresh: true,
119
+ mode,
120
+ symbol,
121
+ target,
122
+ limit: input.limit,
123
+ path: input.path,
124
124
  });
125
- return formatGraph(answer, root);
126
125
  }
127
126
  export async function cmdUsages(argv) {
128
127
  const input = usagesInput(argv);
@@ -115,7 +115,7 @@ export async function cmdMerge(argv) {
115
115
  for (const session of await ctx.store.recentSessions(from, 1000)) {
116
116
  await ctx.store.upsertSession({ ...session, project: into });
117
117
  }
118
- const swept = await ctx.store.remove({ project: from });
118
+ const swept = await ctx.store.remove({ ids: await storedUnder(ctx, from) });
119
119
  console.log(`Moved ${moved} observation(s) into ${into}.`);
120
120
  if (swept > 0)
121
121
  console.log(`Cleaned up ${swept} leftover row(s) under the old path.`);
@@ -124,6 +124,15 @@ export async function cmdMerge(argv) {
124
124
  await ctx.close();
125
125
  }
126
126
  }
127
+ async function storedUnder(ctx, name) {
128
+ const ids = [];
129
+ await eachObservation(ctx, { project: name }, (batch) => {
130
+ for (const obs of batch)
131
+ if (obs.project === name)
132
+ ids.push(obs.id);
133
+ });
134
+ return ids;
135
+ }
127
136
  async function listShards(ctx, into) {
128
137
  const shards = (await ctx.store.listProjects()).filter((entry) => entry.project !== into && entry.project.startsWith(`${into}/`));
129
138
  if (shards.length === 0) {
@@ -2,7 +2,7 @@ import { basename } from 'node:path';
2
2
  import { createContext } from '../../context.js';
3
3
  import { remember } from '../../capture/index.js';
4
4
  import { resolveProject } from '../../util/project.js';
5
- import { toShortId } from '../../util/shortid.js';
5
+ import { assertValidIds, toShortId } from '../../util/shortid.js';
6
6
  import { valueOf, withoutFlags } from '../args.js';
7
7
  export async function cmdSearch(argv) {
8
8
  const all = argv.includes('--all');
@@ -67,6 +67,7 @@ export async function cmdForget(argv) {
67
67
  console.error(' claude-db forget --session <session-id>');
68
68
  process.exit(1);
69
69
  }
70
+ assertValidIds(ids);
70
71
  const ctx = await createContext();
71
72
  try {
72
73
  const doomed = await ctx.store.getObservations(ids);
@@ -3,7 +3,7 @@ import { closeLandedWork, openWork, redact } from '../../capture/index.js';
3
3
  import { CONFIG_PATH } from '../../config/index.js';
4
4
  import { DIST_DIR } from '../constants.js';
5
5
  import { assertStableLocation, install, uninstall } from '../install.js';
6
- import { instructionsPathFor, mcpPathFor, settingsPathFor } from '../paths.js';
6
+ import { mcpPathFor, settingsPathFor } from '../paths.js';
7
7
  import { createContext } from '../../context.js';
8
8
  import { join, resolve } from 'node:path';
9
9
  import { readFileSync, statSync } from 'node:fs';
@@ -38,7 +38,6 @@ export async function cmdInstall(scope) {
38
38
  await ctx.close();
39
39
  console.log(`Scope : ${scope === 'project' ? `this project only (${project})` : 'all projects on this machine'}`);
40
40
  console.log(`Settings : ${settingsPath}`);
41
- console.log(`Guidance : ${instructionsPathFor(scope, project)}`);
42
41
  printSkills(skills);
43
42
  console.log(`Config : ${CONFIG_PATH}`);
44
43
  console.log(`Database : ${redact(ctx.config.database)}`);
@@ -1,6 +1,7 @@
1
1
  import { BATCH } from '../constants.js';
2
2
  import { createContext } from '../../context.js';
3
3
  import { createStore } from '../../store/index.js';
4
+ const SYNC_SCOPE = 'Sync adds rows the other side is missing and moves status forward. Edits and deletes do not travel.';
4
5
  export async function cmdSync(argv) {
5
6
  const url = argv.find((arg) => typeof arg === 'string' && !arg.startsWith('-'));
6
7
  const confirmed = argv.includes('--yes') || argv.includes('-y');
@@ -49,7 +50,8 @@ export async function cmdSync(argv) {
49
50
  if (!confirmed) {
50
51
  console.log(`This would pull ${pulled} and push ${pushed} observation(s), ` +
51
52
  `and bring ${moved} status(es) up to date.`);
52
- console.log('\nNothing was transferred. Re-run with --yes to confirm.');
53
+ console.log(`\n${SYNC_SCOPE}`);
54
+ console.log('Nothing was transferred. Re-run with --yes to confirm.');
53
55
  return;
54
56
  }
55
57
  await applyStatus(local.store, localBehind);
@@ -57,6 +59,7 @@ export async function cmdSync(argv) {
57
59
  const sessions = await syncSessions(local.store, remote);
58
60
  console.log(`Pulled ${pulled}, pushed ${pushed}, brought ${moved} status(es) up to date, ` +
59
61
  `and reconciled ${sessions} session(s).`);
62
+ console.log(SYNC_SCOPE);
60
63
  }
61
64
  finally {
62
65
  await remote.close();
@@ -3,7 +3,7 @@ import { installSkills, removeSkills } from './skills.js';
3
3
  import { resolve } from 'node:path';
4
4
  import { execFileSync } from 'node:child_process';
5
5
  import { readJson, writeJson, writeJsonOrRemove } from './files.js';
6
- import { removeInstructions, writeInstructions } from './instructions.js';
6
+ import { removeInstructions } from './instructions.js';
7
7
  import { toPosix } from '../util/paths.js';
8
8
  const HOOKS = [
9
9
  ['SessionStart', 'session-start.js'],
@@ -75,7 +75,6 @@ export function install(distDir, scope, project) {
75
75
  delete settings['mcpServers'];
76
76
  writeJson(path, settings);
77
77
  const server = resolve(distDir, 'mcp', 'server.js');
78
- writeInstructions(instructionsPathFor(scope, project));
79
78
  const skills = installSkills(distDir, scope, project);
80
79
  if (scope === 'global' && registerViaCli(server))
81
80
  return { settingsPath: path, skills };
@@ -1,5 +1,3 @@
1
1
  export declare const BLOCK_START = "<!-- claude-db:start -->";
2
2
  export declare const BLOCK_END = "<!-- claude-db:end -->";
3
- export declare const INSTRUCTIONS: string;
4
- export declare function writeInstructions(path: string): void;
5
- export declare function removeInstructions(path: string): void;
3
+ export declare function removeInstructions(path: string): boolean;
@@ -2,52 +2,17 @@ import { readText, writeAtomic } from './files.js';
2
2
  import { rmSync } from 'node:fs';
3
3
  export const BLOCK_START = '<!-- claude-db:start -->';
4
4
  export const BLOCK_END = '<!-- claude-db:end -->';
5
- export const INSTRUCTIONS = [
6
- BLOCK_START,
7
- '## Project memory',
8
- '',
9
- 'You have persistent memory of this project: your past sessions, decisions',
10
- 'and their reasoning, served by the `memory` MCP server. Session summaries',
11
- 'are injected at startup, and a `<memory>` block, added with a prompt or with',
12
- 'your first tool call after it, lists earlier work that fits the prompt, each',
13
- 'line ending in an id `get_observations` expands.',
14
- 'That is only ever a slice of what you know.',
15
- '',
16
- 'Recall the rest *before* re-deriving something you already learned. That',
17
- 'means before grepping or reading git history to reconstruct why something is',
18
- 'the way it is, before saying you lack context, and before asking the user to',
19
- 're-explain a past decision or a failed approach: call `search`, then',
20
- '`get_observations` for the ids worth reading.',
21
- '',
22
- 'Verifying against the code afterwards is right — memory records what was',
23
- 'done, the source shows what is. Starting there is what wastes the memory.',
24
- '',
25
- '`search` covers *why*: past decisions, bugs, reasoning. `find_usages` is',
26
- 'the default the moment a question is about a symbol or identifier — before',
27
- 'editing or removing a shared or exported name, or to look one up at all —',
28
- 'since it tags the likely definition and re-derives the answer from the',
29
- 'current source on every call, so it is never stale. grep still wins for',
30
- 'everything that is not a code identifier: plain text, log files, comments,',
31
- 'strings, and scoping with grep flags `find_usages` does not expose.',
32
- '',
33
- 'When the user states a standing rule or preference, record it with',
34
- '`remember` so it survives this session.',
35
- BLOCK_END,
36
- ].join('\n');
37
- export function writeInstructions(path) {
38
- const rest = withoutBlock(readText(path)).trimEnd();
39
- const body = rest.length > 0 ? `${rest}\n\n${INSTRUCTIONS}\n` : `${INSTRUCTIONS}\n`;
40
- writeAtomic(path, body);
41
- }
42
5
  export function removeInstructions(path) {
43
6
  const existing = readText(path);
44
- if (!existing.includes(BLOCK_START))
45
- return;
46
- const rest = withoutBlock(existing).trim();
7
+ const stripped = withoutBlock(existing);
8
+ if (stripped === existing)
9
+ return false;
10
+ const rest = stripped.trim();
47
11
  if (rest.length === 0)
48
12
  rmSync(path, { force: true });
49
13
  else
50
14
  writeAtomic(path, `${rest}\n`);
15
+ return true;
51
16
  }
52
17
  function withoutBlock(text) {
53
18
  const start = text.indexOf(BLOCK_START);
@@ -1,7 +1,6 @@
1
- import { BLOCK_START, INSTRUCTIONS, writeInstructions } from './instructions.js';
1
+ import { removeInstructions } from './instructions.js';
2
2
  import { refreshHooks } from './install.js';
3
3
  import { instructionsPathFor, settingsPathFor } from './paths.js';
4
- import { readText } from './files.js';
5
4
  import { refreshSkills } from './skills.js';
6
5
  export function refreshInstalled(distDir, project) {
7
6
  const refreshed = [];
@@ -11,11 +10,8 @@ export function refreshInstalled(distDir, project) {
11
10
  refreshed.push(settingsPath);
12
11
  refreshed.push(...refreshSkills(distDir, scope, project));
13
12
  const instructionsPath = instructionsPathFor(scope, project);
14
- const existing = readText(instructionsPath);
15
- if (existing.includes(BLOCK_START) && !existing.includes(INSTRUCTIONS)) {
16
- writeInstructions(instructionsPath);
13
+ if (removeInstructions(instructionsPath))
17
14
  refreshed.push(instructionsPath);
18
- }
19
15
  }
20
16
  return refreshed;
21
17
  }
@@ -2,6 +2,7 @@ import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
2
2
  import { dirname, join } from 'node:path';
3
3
  import { CONFIG_DIR } from './dir.js';
4
4
  import { ConfigSchema } from './schema.js';
5
+ import { hookEnv } from '../util/env.js';
5
6
  export { CONFIG_DIR };
6
7
  export const CONFIG_PATH = join(CONFIG_DIR, 'config.json');
7
8
  export const DEFAULT_DB_PATH = join(CONFIG_DIR, 'memory.db');
@@ -31,7 +32,7 @@ export function loadConfig() {
31
32
  }
32
33
  catch { }
33
34
  const config = ConfigSchema.parse(dropSupersededDefaults(fileConfig));
34
- const envUrl = process.env['CLAUDE_DB_URL']?.trim();
35
+ const envUrl = hookEnv()['CLAUDE_DB_URL']?.trim();
35
36
  return {
36
37
  ...config,
37
38
  database: envUrl && envUrl.length > 0 ? envUrl : config.database || DEFAULT_DB_PATH,
@@ -25,7 +25,6 @@ export declare const ConfigSchema: z.ZodObject<{
25
25
  remote: z.ZodDefault<z.ZodString>;
26
26
  }, z.core.$strip>>;
27
27
  capture: z.ZodPrefault<z.ZodObject<{
28
- tools: z.ZodDefault<z.ZodArray<z.ZodString>>;
29
28
  exclude: z.ZodDefault<z.ZodArray<z.ZodString>>;
30
29
  maxBodyChars: z.ZodDefault<z.ZodNumber>;
31
30
  scripted: z.ZodDefault<z.ZodBoolean>;
@@ -59,7 +58,6 @@ export declare const ConfigSchema: z.ZodObject<{
59
58
  dailyLimit: z.ZodDefault<z.ZodNumber>;
60
59
  }, z.core.$strip>>;
61
60
  inject: z.ZodPrefault<z.ZodObject<{
62
- sessions: z.ZodDefault<z.ZodNumber>;
63
61
  maxChars: z.ZodDefault<z.ZodNumber>;
64
62
  perPrompt: z.ZodDefault<z.ZodBoolean>;
65
63
  promptResults: z.ZodDefault<z.ZodNumber>;