claude-db 0.12.4 → 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 (158) hide show
  1. package/CHANGELOG.md +93 -0
  2. package/dist/capture/cursors.d.ts +6 -0
  3. package/dist/capture/cursors.js +80 -0
  4. package/dist/capture/flush.d.ts +1 -3
  5. package/dist/capture/flush.js +35 -96
  6. package/dist/capture/index.d.ts +3 -3
  7. package/dist/capture/index.js +3 -3
  8. package/dist/capture/progress.js +4 -2
  9. package/dist/capture/reingest.d.ts +1 -0
  10. package/dist/capture/reingest.js +4 -1
  11. package/dist/capture/scrub.d.ts +1 -0
  12. package/dist/capture/scrub.js +4 -1
  13. package/dist/capture/transcript.d.ts +1 -1
  14. package/dist/capture/transcript.js +6 -6
  15. package/dist/capture/vectors.js +2 -1
  16. package/dist/catchup/gather.js +1 -1
  17. package/dist/cli/commands/catchup.js +2 -1
  18. package/dist/cli/commands/daemon.d.ts +1 -0
  19. package/dist/cli/commands/daemon.js +29 -0
  20. package/dist/cli/commands/distill.js +2 -1
  21. package/dist/cli/commands/graph.js +11 -11
  22. package/dist/cli/commands/insight.js +10 -1
  23. package/dist/cli/commands/maintain.js +3 -1
  24. package/dist/cli/commands/memory.js +2 -1
  25. package/dist/cli/commands/setup.js +1 -2
  26. package/dist/cli/commands/sync.js +4 -1
  27. package/dist/cli/index.js +4 -0
  28. package/dist/cli/install.js +1 -2
  29. package/dist/cli/instructions.d.ts +1 -3
  30. package/dist/cli/instructions.js +5 -40
  31. package/dist/cli/refresh.js +2 -6
  32. package/dist/cli/usage.js +1 -0
  33. package/dist/config/load.js +2 -1
  34. package/dist/config/schema.d.ts +4 -2
  35. package/dist/config/schema.js +6 -2
  36. package/dist/context.d.ts +1 -0
  37. package/dist/context.js +30 -6
  38. package/dist/daemon/client.d.ts +14 -0
  39. package/dist/daemon/client.js +106 -0
  40. package/dist/daemon/paths.d.ts +18 -0
  41. package/dist/daemon/paths.js +19 -0
  42. package/dist/daemon/pid.d.ts +3 -0
  43. package/dist/daemon/pid.js +20 -0
  44. package/dist/daemon/server.d.ts +2 -0
  45. package/dist/daemon/server.js +227 -0
  46. package/dist/embed/local.js +4 -1
  47. package/dist/facts/budget.d.ts +1 -0
  48. package/dist/facts/budget.js +4 -0
  49. package/dist/facts/claude-memory.js +3 -3
  50. package/dist/facts/distill.js +2 -2
  51. package/dist/facts/known.js +1 -1
  52. package/dist/facts/last-chat.d.ts +1 -1
  53. package/dist/facts/last-chat.js +5 -4
  54. package/dist/facts/model.d.ts +1 -1
  55. package/dist/facts/model.js +31 -16
  56. package/dist/facts/start-render.d.ts +13 -0
  57. package/dist/facts/start-render.js +43 -0
  58. package/dist/facts/start.d.ts +3 -6
  59. package/dist/facts/start.js +33 -47
  60. package/dist/graph/grammars.js +2 -1
  61. package/dist/graph/index.d.ts +1 -1
  62. package/dist/graph/index.js +1 -1
  63. package/dist/graph/query/index.d.ts +1 -0
  64. package/dist/graph/query/index.js +1 -0
  65. package/dist/graph/query/refresh.js +5 -1
  66. package/dist/graph/query/stale.js +19 -2
  67. package/dist/graph/query/usages.d.ts +12 -0
  68. package/dist/graph/query/usages.js +37 -0
  69. package/dist/graph/scan/cache.d.ts +1 -0
  70. package/dist/graph/scan/cache.js +3 -2
  71. package/dist/graph/scan/files.js +2 -2
  72. package/dist/graph/scan/persist.js +12 -16
  73. package/dist/hooks/compact.d.ts +3 -1
  74. package/dist/hooks/compact.js +4 -3
  75. package/dist/hooks/detached.js +2 -0
  76. package/dist/hooks/graph-presence.d.ts +3 -0
  77. package/dist/hooks/graph-presence.js +42 -0
  78. package/dist/hooks/grep-symbols.d.ts +3 -1
  79. package/dist/hooks/grep-symbols.js +41 -2
  80. package/dist/hooks/handlers/prefer-usages.d.ts +2 -0
  81. package/dist/hooks/handlers/prefer-usages.js +118 -0
  82. package/dist/hooks/handlers/session-end.d.ts +2 -0
  83. package/dist/hooks/handlers/session-end.js +60 -0
  84. package/dist/hooks/handlers/session-start.d.ts +2 -0
  85. package/dist/hooks/handlers/session-start.js +83 -0
  86. package/dist/hooks/handlers/turn-end.d.ts +2 -0
  87. package/dist/hooks/handlers/turn-end.js +31 -0
  88. package/dist/hooks/handlers/user-prompt.d.ts +2 -0
  89. package/dist/hooks/handlers/user-prompt.js +55 -0
  90. package/dist/hooks/local.d.ts +2 -0
  91. package/dist/hooks/local.js +22 -0
  92. package/dist/hooks/payload.d.ts +9 -4
  93. package/dist/hooks/payload.js +30 -20
  94. package/dist/hooks/pick-deliver.js +2 -1
  95. package/dist/hooks/prefer-usages.js +2 -118
  96. package/dist/hooks/prompt-recall.d.ts +4 -2
  97. package/dist/hooks/prompt-recall.js +10 -10
  98. package/dist/hooks/route.d.ts +2 -0
  99. package/dist/hooks/route.js +33 -0
  100. package/dist/hooks/run.d.ts +13 -0
  101. package/dist/hooks/run.js +12 -0
  102. package/dist/hooks/save-turn.d.ts +2 -0
  103. package/dist/hooks/save-turn.js +11 -0
  104. package/dist/hooks/session-end.js +2 -63
  105. package/dist/hooks/session-start.js +2 -90
  106. package/dist/hooks/turn-end.js +2 -25
  107. package/dist/hooks/turn-save.js +10 -15
  108. package/dist/hooks/user-prompt.js +2 -58
  109. package/dist/mcp/tools/ids.d.ts +3 -0
  110. package/dist/mcp/tools/ids.js +6 -0
  111. package/dist/mcp/tools/memory.js +2 -1
  112. package/dist/mcp/tools/observations.js +3 -2
  113. package/dist/mcp/tools/search.js +4 -9
  114. package/dist/mcp/tools/usages.js +18 -44
  115. package/dist/pick/worker.js +1 -2
  116. package/dist/search/service.d.ts +6 -0
  117. package/dist/search/service.js +27 -11
  118. package/dist/store/adapter.d.ts +7 -5
  119. package/dist/store/mongo/index.d.ts +3 -6
  120. package/dist/store/mongo/index.js +5 -0
  121. package/dist/store/mongo/observations.js +13 -1
  122. package/dist/store/postgres/driver.d.ts +10 -3
  123. package/dist/store/postgres/driver.js +12 -0
  124. package/dist/store/postgres/filters.d.ts +1 -0
  125. package/dist/store/postgres/filters.js +3 -0
  126. package/dist/store/postgres/graph.d.ts +3 -5
  127. package/dist/store/postgres/graph.js +59 -52
  128. package/dist/store/postgres/index.d.ts +3 -6
  129. package/dist/store/postgres/index.js +8 -5
  130. package/dist/store/postgres/insert.js +98 -50
  131. package/dist/store/postgres/meta.d.ts +1 -0
  132. package/dist/store/postgres/meta.js +4 -0
  133. package/dist/store/postgres/observations.js +3 -3
  134. package/dist/store/project-resolver.d.ts +4 -0
  135. package/dist/store/project-resolver.js +34 -23
  136. package/dist/store/scoped-store.js +4 -2
  137. package/dist/store/sqlite/filters.d.ts +1 -0
  138. package/dist/store/sqlite/filters.js +6 -2
  139. package/dist/store/sqlite/graph.d.ts +3 -5
  140. package/dist/store/sqlite/graph.js +45 -35
  141. package/dist/store/sqlite/index.d.ts +3 -6
  142. package/dist/store/sqlite/index.js +3 -0
  143. package/dist/store/sqlite/observations.js +12 -9
  144. package/dist/util/claude-binary.js +5 -4
  145. package/dist/util/claude-cli.js +2 -1
  146. package/dist/util/claude-dir.d.ts +2 -0
  147. package/dist/util/claude-dir.js +8 -0
  148. package/dist/util/env.d.ts +2 -0
  149. package/dist/util/env.js +6 -0
  150. package/dist/util/job-lock.d.ts +1 -0
  151. package/dist/util/job-lock.js +50 -10
  152. package/dist/util/shortid.d.ts +3 -0
  153. package/dist/util/shortid.js +11 -0
  154. package/docs/how-it-works.md +5 -10
  155. package/docs/setup-guide.md +6 -1
  156. package/package.json +7 -6
  157. package/dist/hooks/start-legacy.d.ts +0 -6
  158. package/dist/hooks/start-legacy.js +0 -47
@@ -1,5 +1,5 @@
1
1
  import { toEdge, toSymbol } from './rows.js';
2
- export async function upsertGraph(db, scan) {
2
+ function writeGraphRows(db, scan) {
3
3
  const symbol = db.prepare(`INSERT OR REPLACE INTO symbols
4
4
  (id, project, name, kind, file, line, lang, signature)
5
5
  VALUES (?, ?, ?, ?, ?, ?, ?, ?)`);
@@ -9,24 +9,54 @@ export async function upsertGraph(db, scan) {
9
9
  VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`);
10
10
  const file = db.prepare(`INSERT OR REPLACE INTO scanned_files (project, path, hash, scanned_at)
11
11
  VALUES (?, ?, ?, ?)`);
12
+ for (const s of scan.symbols) {
13
+ symbol.run(s.id, s.project, s.name, s.kind, s.file, s.line, s.lang, s.signature);
14
+ }
15
+ for (const e of scan.edges) {
16
+ edge.run(e.id, e.project, e.srcId, e.srcName, e.dstId, e.dstName, e.relation, e.confidence, e.score, e.file, e.line);
17
+ }
18
+ for (const f of scan.files)
19
+ file.run(f.project, f.path, f.hash, f.scannedAt);
20
+ }
21
+ const DELETE_BATCH = 500;
22
+ function deleteGraphRows(db, project, files) {
23
+ const batches = files === null ? [null] : [];
24
+ for (let start = 0; files !== null && start < files.length; start += DELETE_BATCH) {
25
+ batches.push(files.slice(start, start + DELETE_BATCH));
26
+ }
27
+ let removed = 0;
28
+ for (const batch of batches) {
29
+ const holes = batch?.map(() => '?').join(',');
30
+ const where = batch ? `project = ? AND file IN (${holes})` : 'project = ?';
31
+ const cacheWhere = batch ? `project = ? AND path IN (${holes})` : 'project = ?';
32
+ const params = (batch ? [project, ...batch] : [project]);
33
+ removed += Number(db.prepare(`DELETE FROM symbols WHERE ${where}`).run(...params).changes);
34
+ db.prepare(`DELETE FROM symbol_edges WHERE ${where}`).run(...params);
35
+ db.prepare(`DELETE FROM scanned_files WHERE ${cacheWhere}`).run(...params);
36
+ }
37
+ return removed;
38
+ }
39
+ function inTransaction(db, work) {
12
40
  db.exec('BEGIN');
13
41
  try {
14
- for (const s of scan.symbols) {
15
- symbol.run(s.id, s.project, s.name, s.kind, s.file, s.line, s.lang, s.signature);
16
- }
17
- for (const e of scan.edges) {
18
- edge.run(e.id, e.project, e.srcId, e.srcName, e.dstId, e.dstName, e.relation, e.confidence, e.score, e.file, e.line);
19
- }
20
- for (const f of scan.files) {
21
- file.run(f.project, f.path, f.hash, f.scannedAt);
22
- }
42
+ const result = work();
23
43
  db.exec('COMMIT');
44
+ return result;
24
45
  }
25
46
  catch (error) {
26
47
  db.exec('ROLLBACK');
27
48
  throw error;
28
49
  }
29
50
  }
51
+ export async function upsertGraph(db, scan) {
52
+ inTransaction(db, () => writeGraphRows(db, scan));
53
+ }
54
+ export async function replaceGraph(db, project, files, scan) {
55
+ inTransaction(db, () => {
56
+ deleteGraphRows(db, project, files);
57
+ writeGraphRows(db, scan);
58
+ });
59
+ }
30
60
  export async function findSymbols(db, filter) {
31
61
  const conditions = ['project = ?'];
32
62
  const params = [filter.project];
@@ -74,8 +104,9 @@ export async function findEdges(db, filter) {
74
104
  }
75
105
  let where = sides.length > 0 ? ` AND (${sides.join(' OR ')})` : '';
76
106
  if (filter.dstName !== undefined) {
77
- where += ' AND (dst_name = ? OR dst_name LIKE ?)';
78
- params.push(filter.dstName, `%.${filter.dstName}`);
107
+ const suffix = `.${filter.dstName}`;
108
+ where += ' AND (dst_name = ? OR substr(dst_name, -length(?)) = ?)';
109
+ params.push(filter.dstName, suffix, suffix);
79
110
  }
80
111
  params.push(filter.limit ?? 2000);
81
112
  const rows = db
@@ -95,27 +126,6 @@ export async function scannedFiles(db, project, limit) {
95
126
  }));
96
127
  }
97
128
  export async function removeGraph(db, project, files) {
98
- const scoped = files && files.length > 0;
99
- const where = scoped
100
- ? `project = ? AND file IN (${files.map(() => '?').join(',')})`
101
- : 'project = ?';
102
- const params = scoped ? [project, ...files] : [project];
103
- const count = db
104
- .prepare(`SELECT COUNT(*) AS n FROM symbols WHERE ${where}`)
105
- .get(...params);
106
- db.exec('BEGIN');
107
- try {
108
- db.prepare(`DELETE FROM symbols WHERE ${where}`).run(...params);
109
- db.prepare(`DELETE FROM symbol_edges WHERE ${where}`).run(...params);
110
- const cacheWhere = scoped
111
- ? `project = ? AND path IN (${files.map(() => '?').join(',')})`
112
- : 'project = ?';
113
- db.prepare(`DELETE FROM scanned_files WHERE ${cacheWhere}`).run(...params);
114
- db.exec('COMMIT');
115
- }
116
- catch (error) {
117
- db.exec('ROLLBACK');
118
- throw error;
119
- }
120
- return count?.n ?? 0;
129
+ const scoped = files !== undefined && files.length > 0;
130
+ return inTransaction(db, () => deleteGraphRows(db, project, scoped ? files : null));
121
131
  }
@@ -1,5 +1,5 @@
1
1
  import type { CodeEdge, CodeSymbol, CountFilter, EdgeFilter, ListFilter, Observation, ObservationIndexEntry, ProjectFilter, RemoveFilter, ScannedFile, SearchQuery, Session, SymbolFilter, TimelineQuery } from '../../types.js';
2
- import type { MemoryStore, ProjectSummary } from '../adapter.js';
2
+ import type { GraphRows, MemoryStore, ProjectSummary } from '../adapter.js';
3
3
  export declare const HERE: string;
4
4
  export declare class SqliteStore implements MemoryStore {
5
5
  private readonly db;
@@ -28,11 +28,8 @@ export declare class SqliteStore implements MemoryStore {
28
28
  closeObservations(ids: string[]): Promise<number>;
29
29
  markReplaced(ids: string[]): Promise<number>;
30
30
  timeline(query: TimelineQuery): Promise<ObservationIndexEntry[]>;
31
- upsertGraph(scan: {
32
- symbols: CodeSymbol[];
33
- edges: CodeEdge[];
34
- files: ScannedFile[];
35
- }): Promise<void>;
31
+ upsertGraph(scan: GraphRows): Promise<void>;
32
+ replaceGraph(project: string, files: string[] | null, scan: GraphRows): Promise<void>;
36
33
  findSymbols(filter: SymbolFilter): Promise<CodeSymbol[]>;
37
34
  symbolNames(project: string, limit: number): Promise<string[]>;
38
35
  findEdges(filter: EdgeFilter): Promise<CodeEdge[]>;
@@ -127,6 +127,9 @@ export class SqliteStore {
127
127
  async upsertGraph(scan) {
128
128
  return graphOps.upsertGraph(this.db, scan);
129
129
  }
130
+ async replaceGraph(project, files, scan) {
131
+ return graphOps.replaceGraph(this.db, project, files, scan);
132
+ }
130
133
  async findSymbols(filter) {
131
134
  return graphOps.findSymbols(this.db, filter);
132
135
  }
@@ -1,6 +1,6 @@
1
1
  import { foreignNames, isWholeScope } from '../adapter.js';
2
2
  import { toObservation } from './rows.js';
3
- import { TAG_PREDICATE, excludeSessionsClause, projectClause, removeWhere } from './filters.js';
3
+ import { TAG_PREDICATE, excludeSessionsClause, globPrefix, projectClause, removeWhere, } from './filters.js';
4
4
  import { partitionIds } from '../../util/shortid.js';
5
5
  import { packVector } from '../../util/vector.js';
6
6
  import { scopeToken } from '../../util/scope.js';
@@ -11,11 +11,15 @@ export async function insertObservations(db, observations) {
11
11
  const stmt = db.prepare(`INSERT OR REPLACE INTO observations
12
12
  (id, session_id, project, scope, kind, title, body, files, tags,
13
13
  created_at, embedding, embedder, author, status)
14
- VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`);
14
+ VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?,
15
+ COALESCE((SELECT status FROM observations
16
+ WHERE id = ? AND status = 'done' AND ? = 'open' AND files = ?), ?))`);
15
17
  db.exec('BEGIN');
16
18
  try {
17
19
  for (const obs of observations) {
18
- stmt.run(obs.id, obs.sessionId, obs.project, scopeToken(obs.project), obs.kind, obs.title, obs.body, JSON.stringify(obs.files), JSON.stringify(obs.tags), obs.createdAt, obs.embedding ? packVector(obs.embedding) : null, obs.embedder ?? null, obs.author ?? null, obs.status ?? 'done');
20
+ const files = JSON.stringify(obs.files);
21
+ const status = obs.status ?? 'done';
22
+ stmt.run(obs.id, obs.sessionId, obs.project, scopeToken(obs.project), obs.kind, obs.title, obs.body, files, JSON.stringify(obs.tags), obs.createdAt, obs.embedding ? packVector(obs.embedding) : null, obs.embedder ?? null, obs.author ?? null, obs.id, status, files, status);
19
23
  }
20
24
  db.exec('COMMIT');
21
25
  }
@@ -36,7 +40,7 @@ export async function getObservations(db, ids) {
36
40
  }
37
41
  for (const prefix of prefixes) {
38
42
  clauses.push('id GLOB ?');
39
- params.push(`${prefix}*`);
43
+ params.push(globPrefix(prefix));
40
44
  }
41
45
  const rows = db
42
46
  .prepare(`SELECT * FROM observations WHERE ${clauses.join(' OR ')}`)
@@ -167,11 +171,10 @@ export async function closeObservations(db, ids) {
167
171
  if (ids.length === 0)
168
172
  return 0;
169
173
  const holes = ids.map(() => '?').join(',');
170
- const row = db
171
- .prepare(`SELECT COUNT(*) AS n FROM observations WHERE status = 'open' AND id IN (${holes})`)
172
- .get(...ids);
173
- db.prepare(`UPDATE observations SET status = 'done' WHERE id IN (${holes})`).run(...ids);
174
- return row?.n ?? 0;
174
+ const result = db
175
+ .prepare(`UPDATE observations SET status = 'done' WHERE status = 'open' AND id IN (${holes})`)
176
+ .run(...ids);
177
+ return Number(result.changes);
175
178
  }
176
179
  export async function markReplaced(db, ids) {
177
180
  if (ids.length === 0)
@@ -2,6 +2,7 @@ import { execFileSync } from 'node:child_process';
2
2
  import { accessSync, constants, mkdirSync, readFileSync, readlinkSync, statSync, writeFileSync, } from 'node:fs';
3
3
  import { basename, delimiter, isAbsolute, join } from 'node:path';
4
4
  import { CONFIG_DIR } from '../config/dir.js';
5
+ import { hookEnv } from './env.js';
5
6
  const REMEMBERED_FILE = join(CONFIG_DIR, 'claude-binary');
6
7
  const MAX_ANCESTORS = 8;
7
8
  function inspectOnLinux(pid) {
@@ -58,7 +59,7 @@ export function rememberedBinary(file = REMEMBERED_FILE) {
58
59
  return null;
59
60
  }
60
61
  }
61
- export function rememberClaudeBinary(env = process.env, file = REMEMBERED_FILE, find = findClaudeAncestor) {
62
+ export function rememberClaudeBinary(env = hookEnv(), file = REMEMBERED_FILE, find = findClaudeAncestor) {
62
63
  const known = rememberedBinary(file);
63
64
  const path = env['CLAUDE_CODE_EXECPATH'] || (known === null ? find() : null);
64
65
  if (!path || path === known)
@@ -69,7 +70,7 @@ export function rememberClaudeBinary(env = process.env, file = REMEMBERED_FILE,
69
70
  }
70
71
  catch { }
71
72
  }
72
- export function findOnPath(env = process.env) {
73
+ export function findOnPath(env = hookEnv()) {
73
74
  const names = process.platform === 'win32' ? ['claude.exe', 'claude.cmd'] : ['claude'];
74
75
  for (const dir of (env['PATH'] ?? '').split(delimiter)) {
75
76
  if (dir === '')
@@ -87,7 +88,7 @@ export function findOnPath(env = process.env) {
87
88
  }
88
89
  return null;
89
90
  }
90
- export function resolveClaude(env = process.env, lookup = {}) {
91
+ export function resolveClaude(env = hookEnv(), lookup = {}) {
91
92
  const { remembered = rememberedBinary, ancestor = findClaudeAncestor, onPath = findOnPath, } = lookup;
92
93
  const fromEnv = env['CLAUDE_CODE_EXECPATH'];
93
94
  if (fromEnv)
@@ -101,6 +102,6 @@ export function resolveClaude(env = process.env, lookup = {}) {
101
102
  const found = onPath(env);
102
103
  return found ? { path: found, source: 'PATH' } : null;
103
104
  }
104
- export function claudeBinary(env = process.env, lookup = {}) {
105
+ export function claudeBinary(env = hookEnv(), lookup = {}) {
105
106
  return resolveClaude(env, lookup)?.path ?? 'claude';
106
107
  }
@@ -1,5 +1,6 @@
1
1
  import { execFile } from 'node:child_process';
2
2
  import { claudeBinary } from './claude-binary.js';
3
+ import { hookEnv } from './env.js';
3
4
  const MAX_BUFFER = 1024 * 1024;
4
5
  const REASON_CHARS = 120;
5
6
  const OPTIONAL_FLAGS = [
@@ -69,7 +70,7 @@ function call(args, timeoutMs, env) {
69
70
  const child = execFile(claudeBinary(), args, {
70
71
  timeout: timeoutMs,
71
72
  maxBuffer: MAX_BUFFER,
72
- env: { ...process.env, ...env, CLAUDE_DB_CAPTURE: 'off' },
73
+ env: { ...hookEnv(), ...env, CLAUDE_DB_CAPTURE: 'off' },
73
74
  }, (error, stdout, stderr) => {
74
75
  if (!error) {
75
76
  done({ ok: true, stdout });
@@ -0,0 +1,2 @@
1
+ export declare function claudeConfigDir(): string;
2
+ export declare const claudeProjectsDir: () => string;
@@ -0,0 +1,8 @@
1
+ import { homedir } from 'node:os';
2
+ import { join } from 'node:path';
3
+ import { hookEnv } from './env.js';
4
+ export function claudeConfigDir() {
5
+ const custom = hookEnv()['CLAUDE_CONFIG_DIR'];
6
+ return custom ? custom : join(homedir(), '.claude');
7
+ }
8
+ export const claudeProjectsDir = () => join(claudeConfigDir(), 'projects');
@@ -0,0 +1,2 @@
1
+ export declare const hookEnv: () => NodeJS.ProcessEnv;
2
+ export declare function withHookEnv<T>(env: NodeJS.ProcessEnv | undefined, work: () => T): T;
@@ -0,0 +1,6 @@
1
+ import { AsyncLocalStorage } from 'node:async_hooks';
2
+ const requests = new AsyncLocalStorage();
3
+ export const hookEnv = () => requests.getStore() ?? process.env;
4
+ export function withHookEnv(env, work) {
5
+ return env ? requests.run(env, work) : work();
6
+ }
@@ -1,4 +1,5 @@
1
1
  export declare function jobMark(job: string, key: string): number;
2
2
  export declare function claimJob(job: string, key: string, now?: number): boolean;
3
+ export declare function keepJob(job: string, key: string): () => void;
3
4
  export declare function finishJob(job: string, key: string, mark: number): void;
4
5
  export declare function releaseJob(job: string, key: string): void;
@@ -1,4 +1,4 @@
1
- import { mkdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
1
+ import { mkdirSync, readFileSync, rmSync, statSync, utimesSync, writeFileSync } from 'node:fs';
2
2
  import { join } from 'node:path';
3
3
  import { CONFIG_DIR } from '../config/index.js';
4
4
  import { scopeToken } from './scope.js';
@@ -20,22 +20,62 @@ export function jobMark(job, key) {
20
20
  return 0;
21
21
  }
22
22
  }
23
+ const BREAKER_STALE_MS = 30_000;
24
+ const KEEP_EVERY_MS = 60_000;
25
+ function ageOf(path, now) {
26
+ try {
27
+ return now - statSync(path).mtimeMs;
28
+ }
29
+ catch {
30
+ return null;
31
+ }
32
+ }
33
+ function breakStaleLock(lock, now) {
34
+ const breaker = `${lock}.break`;
35
+ if (!tryLock(breaker, now)) {
36
+ const age = ageOf(breaker, now);
37
+ if (age === null || age < BREAKER_STALE_MS)
38
+ return false;
39
+ rmSync(breaker, { force: true });
40
+ if (!tryLock(breaker, now))
41
+ return false;
42
+ }
43
+ try {
44
+ const age = ageOf(lock, now);
45
+ if (age !== null && age < STALE_LOCK_MS)
46
+ return false;
47
+ rmSync(lock, { force: true });
48
+ return tryLock(lock, now);
49
+ }
50
+ finally {
51
+ rmSync(breaker, { force: true });
52
+ }
53
+ }
23
54
  export function claimJob(job, key, now = Date.now()) {
24
55
  const lock = lockPath(job, key);
25
56
  mkdirSync(jobDir(job), { recursive: true });
26
57
  if (tryLock(lock, now))
27
58
  return true;
28
- let lockedAt;
29
- try {
30
- lockedAt = statSync(lock).mtimeMs;
31
- }
32
- catch {
59
+ const age = ageOf(lock, now);
60
+ if (age === null)
33
61
  return tryLock(lock, now);
34
- }
35
- if (now - lockedAt < STALE_LOCK_MS)
62
+ if (age < STALE_LOCK_MS)
36
63
  return false;
37
- rmSync(lock, { force: true });
38
- return tryLock(lock, now);
64
+ return breakStaleLock(lock, now);
65
+ }
66
+ export function keepJob(job, key) {
67
+ const lock = lockPath(job, key);
68
+ const timer = setInterval(() => {
69
+ try {
70
+ const at = new Date();
71
+ utimesSync(lock, at, at);
72
+ }
73
+ catch {
74
+ clearInterval(timer);
75
+ }
76
+ }, KEEP_EVERY_MS);
77
+ timer.unref();
78
+ return () => clearInterval(timer);
39
79
  }
40
80
  export function finishJob(job, key, mark) {
41
81
  mkdirSync(jobDir(job), { recursive: true });
@@ -1,4 +1,7 @@
1
1
  export declare function toShortId(id: string): string;
2
+ export declare const INVALID_ID_HINT = "is not an observation id. Use the 8 to 36 hex characters search prints.";
3
+ export declare function isObservationId(id: string): boolean;
4
+ export declare function assertValidIds(ids: string[]): void;
2
5
  export declare function isShortId(id: string): boolean;
3
6
  export declare function partitionIds(ids: string[]): {
4
7
  exact: string[];
@@ -2,6 +2,17 @@ const SHORT_LENGTH = 13;
2
2
  export function toShortId(id) {
3
3
  return id.slice(0, SHORT_LENGTH);
4
4
  }
5
+ const VALID_ID = /^[0-9a-f-]{8,36}$/;
6
+ export const INVALID_ID_HINT = 'is not an observation id. Use the 8 to 36 hex characters search prints.';
7
+ export function isObservationId(id) {
8
+ return VALID_ID.test(id);
9
+ }
10
+ export function assertValidIds(ids) {
11
+ const bad = ids.find((id) => !isObservationId(id));
12
+ if (bad === undefined)
13
+ return;
14
+ throw new Error(`${JSON.stringify(bad)} ${INVALID_ID_HINT}`);
15
+ }
5
16
  export function isShortId(id) {
6
17
  return id.length < 36;
7
18
  }
@@ -29,12 +29,8 @@ A turn is also saved as soon as Claude finishes the reply, in the background, so
29
29
  another chat sees it without waiting for your next prompt. The save at the next
30
30
  prompt stays as the backup, for a reply you interrupted.
31
31
 
32
- Install also writes a short standing instruction into `CLAUDE.local.md` (or
33
- `~/.claude/CLAUDE.md` for a machine-wide install), telling Claude to search
34
- memory before asking you to re-explain something. Hook output is context the
35
- agent may or may not act on; a memory file is a rule for the whole session,
36
- which is what makes recall the default rather than something you have to ask
37
- for. `claude-db uninstall` takes the block back out.
32
+ The MCP server's own instructions tell Claude to search memory before asking
33
+ you to re-explain something. Install does not write to `CLAUDE.md`.
38
34
 
39
35
  **What gets saved.** One observation per turn, and only if that turn edited a
40
36
  file or ran a real command. Questions, `grep`, and "ok" are skipped. A busy day
@@ -153,8 +149,7 @@ database unfinished would be worse than saying nothing.
153
149
 
154
150
  ## Staying current
155
151
 
156
- `claude-db install` copies two things to disk: the `/cdb-scan` skill, and a
157
- standing instruction block in `CLAUDE.local.md`. Claude Code only reads skills
152
+ `claude-db install` copies the skills to disk. Claude Code only reads skills
158
153
  from `~/.claude/skills/`, so a copy has to exist there, but a copy drifts as
159
154
  soon as the package updates.
160
155
 
@@ -231,8 +226,8 @@ the backend, and `CLAUDE_DB_URL` overrides the config file.
231
226
 
232
227
  Search is hybrid, keyword plus vector, on all three backends. Ranking, fusion
233
228
  and token budgeting live in `src/search` rather than in the adapters, so recall
234
- behaves identically no matter which database is plugged in; only retrieval cost
235
- changes. Memory is partitioned by project path, so one database serves every
229
+ stays the same across databases, though keyword ranking differs per engine and
230
+ SQLite and MongoDB vector search scans only the newest rows up to a cap. Memory is partitioned by project path, so one database serves every
236
231
  repo you work in.
237
232
 
238
233
  MongoDB Atlas can index vector search instead of scanning brute-force, but
@@ -20,7 +20,7 @@ claude-db install --project
20
20
  Then restart Claude Code. Hooks and the MCP server load only when Claude Code starts.
21
21
 
22
22
  - Use `claude-db install` instead to switch it on for every project on this machine.
23
- - Keep `.mcp.json` and `CLAUDE.local.md` out of git. They hold personal paths and rules.
23
+ - Keep `.mcp.json` out of git. It holds a personal path.
24
24
 
25
25
  ## 3. Check it works
26
26
 
@@ -76,6 +76,11 @@ claude-db use "postgres://user:pass@host:5432/memory"
76
76
  For MongoDB, install `mongodb` and use a `mongodb+srv://` address. Clones of one repository share
77
77
  memory by git remote, so every machine must run 0.11.0 or newer.
78
78
 
79
+ On a remote database each hook pays to start node, open a connection and load the embedding model before
80
+ it does any work, about a second in all. `claude-db daemon on` keeps one process warm that the hooks hand
81
+ their work to, so the next hooks skip that cost. It stops after 15 idle minutes (`daemon.idleMinutes`)
82
+ and starts again with the next hook. `claude-db daemon off` turns it off.
83
+
79
84
  ## Upgrading
80
85
 
81
86
  ```bash
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "claude-db",
3
- "version": "0.12.4",
3
+ "version": "0.14.0",
4
4
  "description": "Free, open-source memory for Claude Code. Remembers why decisions were made and maps your code. Your own database (SQLite, Postgres or MongoDB), no cloud, no subscription.",
5
5
  "license": "Apache-2.0",
6
6
  "type": "module",
@@ -33,6 +33,7 @@
33
33
  "typecheck": "tsc --noEmit -p tsconfig.json",
34
34
  "lint": "node scripts/lint.mjs && eslint . && node scripts/check-fixtures.mjs",
35
35
  "check:fixtures": "node scripts/check-fixtures.mjs",
36
+ "pretest": "npm run build",
36
37
  "test": "node scripts/unit.mjs && node scripts/local.mjs && node scripts/filter.mjs && node scripts/transcript.mjs && node scripts/inject.mjs && node scripts/smoke.mjs",
37
38
  "coverage": "c8 npm test",
38
39
  "check:package": "npm run build && publint && attw --pack . --profile esm-only",
@@ -128,10 +129,10 @@
128
129
  "access": "public"
129
130
  },
130
131
  "optionalDependencies": {
131
- "claude-db-grammars-linux-x64": "0.12.4",
132
- "claude-db-grammars-linux-arm64": "0.12.4",
133
- "claude-db-grammars-darwin-x64": "0.12.4",
134
- "claude-db-grammars-darwin-arm64": "0.12.4",
135
- "claude-db-grammars-win32-x64": "0.12.4"
132
+ "claude-db-grammars-linux-x64": "0.14.0",
133
+ "claude-db-grammars-linux-arm64": "0.14.0",
134
+ "claude-db-grammars-darwin-x64": "0.14.0",
135
+ "claude-db-grammars-darwin-arm64": "0.14.0",
136
+ "claude-db-grammars-win32-x64": "0.14.0"
136
137
  }
137
138
  }
@@ -1,6 +0,0 @@
1
- import type { RecallContext } from '../context.js';
2
- export interface LegacyBlock {
3
- text: string;
4
- hasMemory: boolean;
5
- }
6
- export declare function legacyBlock(ctx: RecallContext, project: string, restored: ReadonlySet<string>): Promise<LegacyBlock>;
@@ -1,47 +0,0 @@
1
- import { openWork } from '../capture/index.js';
2
- import { toShortId } from '../util/shortid.js';
3
- export async function legacyBlock(ctx, project, restored) {
4
- const sessions = await ctx.store.recentSessions(project, ctx.config.inject.sessions);
5
- if (sessions.length === 0) {
6
- return {
7
- text: '<project-memory>none yet for this project; it is recorded as you work</project-memory>',
8
- hasMemory: false,
9
- };
10
- }
11
- const lines = ['<project-memory>'];
12
- let budget = ctx.config.inject.maxChars;
13
- for (const session of sessions) {
14
- const when = new Date(session.startedAt).toISOString().slice(0, 10);
15
- const line = `- [${when}] ${session.summary ?? ''}`;
16
- if (line.length > budget)
17
- break;
18
- budget -= line.length;
19
- lines.push(line);
20
- }
21
- const open = (await openWork(ctx.store, project)).filter((obs) => !restored.has(obs.id));
22
- if (open.length > 0) {
23
- lines.push('', 'Not committed yet, newest first:');
24
- for (const obs of open.slice(0, 3))
25
- lines.push(`- ${obs.title}`);
26
- }
27
- const rules = (await ctx.store.list({ project, kind: 'preference', limit: 100, newest: true, bodies: false }))
28
- .filter((obs) => obs.status !== 'replaced' && !restored.has(obs.id))
29
- .sort((a, b) => {
30
- const manual = Number(b.sessionId === 'manual') - Number(a.sessionId === 'manual');
31
- return manual !== 0 ? manual : b.createdAt - a.createdAt;
32
- })
33
- .slice(0, 8);
34
- if (rules.length > 0) {
35
- lines.push('', 'Standing rules on record — expand any id with get_observations:');
36
- for (const obs of rules) {
37
- const when = new Date(obs.createdAt).toISOString().slice(0, 10);
38
- const line = `- ${toShortId(obs.id)} [${when}] ${obs.title}`.slice(0, 140);
39
- if (line.length > budget)
40
- break;
41
- budget -= line.length;
42
- lines.push(line);
43
- }
44
- }
45
- lines.push('</project-memory>');
46
- return { text: lines.join('\n'), hasMemory: true };
47
- }