claude-db 0.9.1 → 0.10.1

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 (161) hide show
  1. package/CHANGELOG.md +248 -0
  2. package/README.md +74 -113
  3. package/dist/capture/flush.d.ts +1 -0
  4. package/dist/capture/flush.js +4 -3
  5. package/dist/capture/git.js +2 -1
  6. package/dist/capture/index.d.ts +5 -1
  7. package/dist/capture/index.js +4 -1
  8. package/dist/capture/manual.js +1 -1
  9. package/dist/capture/progress.js +1 -0
  10. package/dist/capture/redact.d.ts +1 -0
  11. package/dist/capture/redact.js +17 -0
  12. package/dist/capture/reingest.d.ts +19 -0
  13. package/dist/capture/reingest.js +56 -0
  14. package/dist/capture/scrub.d.ts +11 -0
  15. package/dist/capture/scrub.js +48 -0
  16. package/dist/capture/summarize.js +3 -9
  17. package/dist/capture/transcript.d.ts +1 -0
  18. package/dist/capture/transcript.js +12 -3
  19. package/dist/capture/turn-extractor.d.ts +0 -1
  20. package/dist/capture/turn-extractor.js +10 -19
  21. package/dist/cli/commands/adoption.js +3 -3
  22. package/dist/cli/commands/distill.d.ts +1 -0
  23. package/dist/cli/commands/distill.js +67 -0
  24. package/dist/cli/commands/doctor.js +11 -3
  25. package/dist/cli/commands/insight.js +13 -4
  26. package/dist/cli/commands/maintain.d.ts +2 -1
  27. package/dist/cli/commands/maintain.js +53 -17
  28. package/dist/cli/commands/pick.d.ts +3 -0
  29. package/dist/cli/commands/pick.js +25 -0
  30. package/dist/cli/commands/setup.js +11 -2
  31. package/dist/cli/commands/sync.js +73 -12
  32. package/dist/cli/commands/transfer.d.ts +0 -5
  33. package/dist/cli/commands/transfer.js +1 -24
  34. package/dist/cli/commands/use.js +1 -1
  35. package/dist/cli/commands/view.js +30 -28
  36. package/dist/cli/index.js +13 -2
  37. package/dist/cli/install.d.ts +2 -0
  38. package/dist/cli/install.js +44 -21
  39. package/dist/cli/instructions.js +4 -2
  40. package/dist/cli/refresh.js +5 -1
  41. package/dist/cli/usage.js +4 -0
  42. package/dist/config/dir.d.ts +1 -0
  43. package/dist/config/dir.js +3 -0
  44. package/dist/config/index.d.ts +1 -1
  45. package/dist/config/index.js +1 -1
  46. package/dist/config/load.d.ts +4 -1
  47. package/dist/config/load.js +30 -13
  48. package/dist/config/schema.d.ts +19 -0
  49. package/dist/config/schema.js +17 -2
  50. package/dist/embed/index.d.ts +1 -1
  51. package/dist/embed/index.js +1 -1
  52. package/dist/embed/local.js +2 -1
  53. package/dist/facts/budget.d.ts +4 -0
  54. package/dist/facts/budget.js +12 -0
  55. package/dist/facts/claude-memory.d.ts +19 -0
  56. package/dist/facts/claude-memory.js +100 -0
  57. package/dist/facts/distill.d.ts +25 -0
  58. package/dist/facts/distill.js +141 -0
  59. package/dist/facts/model.d.ts +28 -0
  60. package/dist/facts/model.js +82 -0
  61. package/dist/facts/notice.d.ts +2 -0
  62. package/dist/facts/notice.js +22 -0
  63. package/dist/facts/ops.d.ts +23 -0
  64. package/dist/facts/ops.js +91 -0
  65. package/dist/facts/render.d.ts +4 -0
  66. package/dist/facts/render.js +13 -0
  67. package/dist/facts/start.d.ts +6 -0
  68. package/dist/facts/start.js +57 -0
  69. package/dist/graph/index.d.ts +2 -6
  70. package/dist/graph/index.js +2 -3
  71. package/dist/graph/languages/basic.js +1 -1
  72. package/dist/graph/languages/index.d.ts +1 -1
  73. package/dist/graph/parser.js +1 -1
  74. package/dist/graph/query/index.d.ts +0 -2
  75. package/dist/graph/query/index.js +0 -1
  76. package/dist/graph/scan/extract.js +1 -1
  77. package/dist/graph/scan/files.js +1 -1
  78. package/dist/graph/scan/index.d.ts +1 -2
  79. package/dist/graph/scan/index.js +1 -1
  80. package/dist/hooks/background.d.ts +3 -0
  81. package/dist/hooks/background.js +43 -0
  82. package/dist/hooks/compact.d.ts +8 -0
  83. package/dist/hooks/compact.js +42 -0
  84. package/dist/hooks/payload.d.ts +3 -0
  85. package/dist/hooks/payload.js +18 -1
  86. package/dist/hooks/pick-deliver.d.ts +2 -0
  87. package/dist/hooks/pick-deliver.js +16 -0
  88. package/dist/hooks/prompt-recall.d.ts +21 -0
  89. package/dist/hooks/prompt-recall.js +36 -0
  90. package/dist/hooks/relevance.d.ts +11 -3
  91. package/dist/hooks/relevance.js +56 -26
  92. package/dist/hooks/session-end.js +7 -1
  93. package/dist/hooks/session-start.js +31 -59
  94. package/dist/hooks/shown.d.ts +1 -0
  95. package/dist/hooks/shown.js +5 -2
  96. package/dist/hooks/start-legacy.d.ts +6 -0
  97. package/dist/hooks/start-legacy.js +47 -0
  98. package/dist/hooks/user-prompt.js +29 -25
  99. package/dist/mcp/server.js +13 -1
  100. package/dist/pick/pending.d.ts +17 -0
  101. package/dist/pick/pending.js +106 -0
  102. package/dist/pick/prompt.d.ts +14 -0
  103. package/dist/pick/prompt.js +80 -0
  104. package/dist/pick/run.d.ts +22 -0
  105. package/dist/pick/run.js +36 -0
  106. package/dist/pick/worker.d.ts +2 -0
  107. package/dist/pick/worker.js +32 -0
  108. package/dist/store/adapter.d.ts +1 -0
  109. package/dist/store/each.d.ts +5 -0
  110. package/dist/store/each.js +25 -0
  111. package/dist/store/mongo/docs.d.ts +2 -0
  112. package/dist/store/mongo/docs.js +4 -0
  113. package/dist/store/mongo/driver.js +3 -2
  114. package/dist/store/mongo/filters.d.ts +1 -0
  115. package/dist/store/mongo/filters.js +8 -0
  116. package/dist/store/mongo/index.d.ts +1 -0
  117. package/dist/store/mongo/index.js +5 -2
  118. package/dist/store/mongo/observations.d.ts +2 -1
  119. package/dist/store/mongo/observations.js +11 -1
  120. package/dist/store/mongo/search.js +12 -3
  121. package/dist/store/mongo/sessions.js +7 -1
  122. package/dist/store/mongo/vectorSearch.js +9 -11
  123. package/dist/store/postgres/driver.js +3 -2
  124. package/dist/store/postgres/filters.js +5 -0
  125. package/dist/store/postgres/index.d.ts +1 -0
  126. package/dist/store/postgres/index.js +3 -0
  127. package/dist/store/postgres/meta.js +2 -1
  128. package/dist/store/postgres/observations.d.ts +1 -0
  129. package/dist/store/postgres/observations.js +14 -3
  130. package/dist/store/postgres/rows.js +4 -0
  131. package/dist/store/postgres/schema.d.ts +2 -2
  132. package/dist/store/postgres/schema.js +4 -1
  133. package/dist/store/postgres/sessions.js +14 -7
  134. package/dist/store/session-time.d.ts +2 -0
  135. package/dist/store/session-time.js +5 -0
  136. package/dist/store/sqlite/filters.js +5 -0
  137. package/dist/store/sqlite/index.d.ts +1 -0
  138. package/dist/store/sqlite/index.js +27 -5
  139. package/dist/store/sqlite/observations.d.ts +1 -0
  140. package/dist/store/sqlite/observations.js +14 -1
  141. package/dist/store/sqlite/rows.js +4 -0
  142. package/dist/store/sqlite/schema.sql +3 -1
  143. package/dist/store/sqlite/search.js +7 -3
  144. package/dist/store/sqlite/sessions.js +13 -8
  145. package/dist/types.d.ts +5 -1
  146. package/dist/usages/find.js +5 -3
  147. package/dist/usages/index.d.ts +0 -1
  148. package/dist/util/claude-cli.d.ts +6 -0
  149. package/dist/util/claude-cli.js +38 -0
  150. package/dist/util/daily-budget.d.ts +7 -0
  151. package/dist/util/daily-budget.js +38 -0
  152. package/dist/util/day.d.ts +1 -0
  153. package/dist/util/day.js +11 -0
  154. package/dist/util/job-lock.d.ts +4 -0
  155. package/dist/util/job-lock.js +56 -0
  156. package/dist/util/prompt.d.ts +5 -0
  157. package/dist/util/prompt.js +31 -0
  158. package/docs/how-it-works.md +69 -3
  159. package/docs/setup-guide.md +339 -0
  160. package/docs/with-and-without.md +43 -36
  161. package/package.json +23 -7
@@ -1,11 +1,17 @@
1
1
  import { toIndexEntry } from './docs.js';
2
- import { scopeFilter } from './filters.js';
2
+ import { scopeFilter, visibleFilter } from './filters.js';
3
3
  import * as searchOps from './search.js';
4
4
  import { cosine } from '../../util/vector.js';
5
5
  export async function searchVector(observations, cache, vector, query) {
6
6
  if (cache.atlasVectorIndex === null) {
7
7
  cache.atlasVectorIndex = await searchOps.hasAtlasVectorIndex(observations);
8
8
  }
9
+ const refine = {
10
+ ...(query.embedder
11
+ ? { $or: [{ embedder: query.embedder }, { embedder: { $exists: false } }] }
12
+ : {}),
13
+ ...visibleFilter(query),
14
+ };
9
15
  if (cache.atlasVectorIndex) {
10
16
  const docs = await observations
11
17
  .aggregate([
@@ -19,13 +25,7 @@ export async function searchVector(observations, cache, vector, query) {
19
25
  filter: scopeFilter(query),
20
26
  },
21
27
  },
22
- ...(query.embedder
23
- ? [
24
- {
25
- $match: { $or: [{ embedder: query.embedder }, { embedder: { $exists: false } }] },
26
- },
27
- ]
28
- : []),
28
+ ...(Object.keys(refine).length > 0 ? [{ $match: refine }] : []),
29
29
  {
30
30
  $project: {
31
31
  kind: 1,
@@ -42,9 +42,7 @@ export async function searchVector(observations, cache, vector, query) {
42
42
  const docs = await observations
43
43
  .find({
44
44
  embedding: { $exists: true },
45
- ...(query.embedder
46
- ? { $or: [{ embedder: query.embedder }, { embedder: { $exists: false } }] }
47
- : {}),
45
+ ...refine,
48
46
  ...scopeFilter(query),
49
47
  }, { projection: { kind: 1, title: 1, project: 1, createdAt: 1, embedding: 1 } })
50
48
  .sort({ createdAt: -1 })
@@ -1,6 +1,7 @@
1
+ const PG = 'pg';
1
2
  export async function importPg() {
2
3
  try {
3
- const mod = (await import('pg'));
4
+ const mod = (await import(PG));
4
5
  if (mod.default?.Pool)
5
6
  return mod.default;
6
7
  if (mod.Pool)
@@ -8,6 +9,6 @@ export async function importPg() {
8
9
  throw new Error('unexpected pg module shape');
9
10
  }
10
11
  catch {
11
- throw new Error('Postgres driver not installed. Run: npm install pg');
12
+ throw new Error('Postgres driver not installed. Run: npm install -g pg');
12
13
  }
13
14
  }
@@ -1,4 +1,5 @@
1
1
  export function appendScope(query, conditions, values) {
2
+ conditions.push("status <> 'replaced'");
2
3
  if (query.project) {
3
4
  values.push(query.project);
4
5
  conditions.push(`project = $${values.length}`);
@@ -19,4 +20,8 @@ export function appendScope(query, conditions, values) {
19
20
  values.push(query.until);
20
21
  conditions.push(`created_at <= $${values.length}`);
21
22
  }
23
+ if (query.excludeSessions && query.excludeSessions.length > 0) {
24
+ values.push(query.excludeSessions);
25
+ conditions.push(`session_id <> ALL($${values.length}::text[])`);
26
+ }
22
27
  }
@@ -35,6 +35,7 @@ export declare class PostgresStore implements MemoryStore {
35
35
  searchKeyword(query: SearchQuery): Promise<ObservationIndexEntry[]>;
36
36
  searchVector(vector: number[], query: SearchQuery): Promise<ObservationIndexEntry[]>;
37
37
  closeObservations(ids: string[]): Promise<number>;
38
+ markReplaced(ids: string[]): Promise<number>;
38
39
  timeline(query: TimelineQuery): Promise<ObservationIndexEntry[]>;
39
40
  tryEnableVector(): Promise<boolean>;
40
41
  upsertGraph(scan: {
@@ -132,6 +132,9 @@ export class PostgresStore {
132
132
  async closeObservations(ids) {
133
133
  return observationsOps.closeObservations(this.pool, ids);
134
134
  }
135
+ async markReplaced(ids) {
136
+ return observationsOps.markReplaced(this.pool, ids);
137
+ }
135
138
  async timeline(query) {
136
139
  return observationsOps.timeline(this.pool, query);
137
140
  }
@@ -20,7 +20,8 @@ export async function ensureTagsIndexed(pool) {
20
20
  FROM pg_attrdef d
21
21
  JOIN pg_attribute a ON a.attrelid = d.adrelid AND a.attnum = d.adnum
22
22
  WHERE d.adrelid = 'observations'::regclass AND a.attname = 'tsv'`);
23
- const expr = String(res.rows[0]?.['expr'] ?? '');
23
+ const value = res.rows[0]?.['expr'];
24
+ const expr = typeof value === 'string' ? value : '';
24
25
  if (expr.includes('tags'))
25
26
  return;
26
27
  const client = await pool.connect();
@@ -8,3 +8,4 @@ export declare function listProjects(pool: Pool): Promise<ProjectSummary[]>;
8
8
  export declare function inventory(pool: Pool): Promise<string[]>;
9
9
  export declare function timeline(pool: Pool, query: TimelineQuery): Promise<ObservationIndexEntry[]>;
10
10
  export declare function closeObservations(pool: Pool, ids: string[]): Promise<number>;
11
+ export declare function markReplaced(pool: Pool, ids: string[]): Promise<number>;
@@ -79,6 +79,10 @@ export async function list(pool, filter) {
79
79
  values.push(filter.project);
80
80
  conditions.push(`project = $${values.length}`);
81
81
  }
82
+ if (filter.sessionId) {
83
+ values.push(filter.sessionId);
84
+ conditions.push(`session_id = $${values.length}`);
85
+ }
82
86
  if (filter.kind) {
83
87
  values.push(filter.kind);
84
88
  conditions.push(`kind = $${values.length}`);
@@ -116,7 +120,7 @@ export async function listProjects(pool) {
116
120
  export async function inventory(pool) {
117
121
  const res = await pool.query(`SELECT tablename AS name FROM pg_tables
118
122
  WHERE schemaname = ANY(current_schemas(false))`);
119
- return foreignNames(res.rows.map((row) => String(row['name'] ?? '')));
123
+ return foreignNames(res.rows.map((row) => (typeof row['name'] === 'string' ? row['name'] : '')));
120
124
  }
121
125
  export async function timeline(pool, query) {
122
126
  const anchorRes = await pool.query('SELECT project, created_at FROM observations WHERE id = $1', [
@@ -127,12 +131,12 @@ export async function timeline(pool, query) {
127
131
  return [];
128
132
  const res = await pool.query(`(SELECT id, kind, title, project, created_at, 0 AS score
129
133
  FROM observations
130
- WHERE project = $1 AND created_at <= $2
134
+ WHERE project = $1 AND created_at <= $2 AND status <> 'replaced'
131
135
  ORDER BY created_at DESC LIMIT $3)
132
136
  UNION
133
137
  (SELECT id, kind, title, project, created_at, 0 AS score
134
138
  FROM observations
135
- WHERE project = $1 AND created_at > $2
139
+ WHERE project = $1 AND created_at > $2 AND status <> 'replaced'
136
140
  ORDER BY created_at ASC LIMIT $4)
137
141
  ORDER BY created_at ASC`, [anchor.project, anchor.created_at, query.before + 1, query.after]);
138
142
  return res.rows.map(toIndexEntry);
@@ -144,3 +148,10 @@ export async function closeObservations(pool, ids) {
144
148
  WHERE status = 'open' AND id = ANY($1::text[])`, [ids]);
145
149
  return res.rowCount ?? 0;
146
150
  }
151
+ export async function markReplaced(pool, ids) {
152
+ if (ids.length === 0)
153
+ return 0;
154
+ const res = await pool.query(`UPDATE observations SET status = 'replaced'
155
+ WHERE status <> 'replaced' AND id = ANY($1::text[])`, [ids]);
156
+ return res.rowCount ?? 0;
157
+ }
@@ -9,6 +9,10 @@ export function toSession(row) {
9
9
  session.endedAt = Number(row['ended_at']);
10
10
  if (row['summary'] != null)
11
11
  session.summary = row['summary'];
12
+ if (row['updated_at'] != null)
13
+ session.updatedAt = Number(row['updated_at']);
14
+ if (row['distilled_at'] != null)
15
+ session.distilledAt = Number(row['distilled_at']);
12
16
  return session;
13
17
  }
14
18
  function toVector(value) {
@@ -1,3 +1,3 @@
1
1
  export declare const TSV_EXPRESSION = "\n setweight(to_tsvector('english', coalesce(title, '')), 'A') ||\n setweight(to_tsvector('english', coalesce(tags::text, '')), 'B') ||\n setweight(to_tsvector('english', coalesce(body, '')), 'C')";
2
- export declare const SCHEMA_VERSION = 3;
3
- export declare const DDL = "\n CREATE TABLE IF NOT EXISTS claude_db_meta (\n id INT PRIMARY KEY,\n version INT NOT NULL,\n vector_enabled BOOLEAN NOT NULL DEFAULT FALSE,\n vector_dims INT\n );\n\n CREATE TABLE IF NOT EXISTS sessions (\n id TEXT PRIMARY KEY,\n project TEXT NOT NULL,\n started_at BIGINT NOT NULL,\n ended_at BIGINT,\n summary TEXT\n );\n CREATE INDEX IF NOT EXISTS idx_sessions_project\n ON sessions(project, started_at DESC);\n\n CREATE TABLE IF NOT EXISTS observations (\n id TEXT PRIMARY KEY,\n session_id TEXT NOT NULL,\n project TEXT NOT NULL,\n kind TEXT NOT NULL,\n title TEXT NOT NULL,\n body TEXT NOT NULL,\n files JSONB NOT NULL DEFAULT '[]'::jsonb,\n tags JSONB NOT NULL DEFAULT '[]'::jsonb,\n created_at BIGINT NOT NULL,\n embedder TEXT,\n author TEXT,\n tsv TSVECTOR GENERATED ALWAYS AS (\n setweight(to_tsvector('english', coalesce(title, '')), 'A') ||\n setweight(to_tsvector('english', coalesce(tags::text, '')), 'B') ||\n setweight(to_tsvector('english', coalesce(body, '')), 'C')) STORED\n );\n CREATE INDEX IF NOT EXISTS idx_obs_tsv ON observations USING GIN(tsv);\n CREATE INDEX IF NOT EXISTS idx_obs_project_time\n ON observations(project, created_at DESC);\n CREATE INDEX IF NOT EXISTS idx_obs_tags ON observations USING GIN(tags);\n\n ALTER TABLE observations ADD COLUMN IF NOT EXISTS embedder TEXT;\n ALTER TABLE observations ADD COLUMN IF NOT EXISTS author TEXT;\n ALTER TABLE observations ADD COLUMN IF NOT EXISTS status TEXT NOT NULL DEFAULT 'done';\n\n CREATE TABLE IF NOT EXISTS symbols (\n id TEXT PRIMARY KEY,\n project TEXT NOT NULL,\n name TEXT NOT NULL,\n kind TEXT NOT NULL,\n file TEXT NOT NULL,\n line INT NOT NULL,\n lang TEXT NOT NULL,\n signature TEXT NOT NULL DEFAULT ''\n );\n CREATE INDEX IF NOT EXISTS idx_symbols_lookup ON symbols(project, name);\n CREATE INDEX IF NOT EXISTS idx_symbols_file ON symbols(project, file);\n\n CREATE TABLE IF NOT EXISTS symbol_edges (\n id TEXT PRIMARY KEY,\n project TEXT NOT NULL,\n src_id TEXT NOT NULL,\n src_name TEXT NOT NULL,\n dst_id TEXT NOT NULL DEFAULT '',\n dst_name TEXT NOT NULL,\n relation TEXT NOT NULL,\n confidence TEXT NOT NULL,\n score REAL NOT NULL DEFAULT 1.0,\n file TEXT NOT NULL,\n line INT NOT NULL\n );\n CREATE INDEX IF NOT EXISTS idx_edges_src ON symbol_edges(project, src_id);\n CREATE INDEX IF NOT EXISTS idx_edges_dst ON symbol_edges(project, dst_id);\n CREATE INDEX IF NOT EXISTS idx_edges_file ON symbol_edges(project, file);\n\n CREATE TABLE IF NOT EXISTS scanned_files (\n project TEXT NOT NULL,\n path TEXT NOT NULL,\n hash TEXT NOT NULL,\n scanned_at BIGINT NOT NULL,\n PRIMARY KEY (project, path)\n );\n";
2
+ export declare const SCHEMA_VERSION = 4;
3
+ export declare const DDL = "\n CREATE TABLE IF NOT EXISTS claude_db_meta (\n id INT PRIMARY KEY,\n version INT NOT NULL,\n vector_enabled BOOLEAN NOT NULL DEFAULT FALSE,\n vector_dims INT\n );\n\n CREATE TABLE IF NOT EXISTS sessions (\n id TEXT PRIMARY KEY,\n project TEXT NOT NULL,\n started_at BIGINT NOT NULL,\n ended_at BIGINT,\n summary TEXT\n );\n CREATE INDEX IF NOT EXISTS idx_sessions_project\n ON sessions(project, started_at DESC);\n\n CREATE TABLE IF NOT EXISTS observations (\n id TEXT PRIMARY KEY,\n session_id TEXT NOT NULL,\n project TEXT NOT NULL,\n kind TEXT NOT NULL,\n title TEXT NOT NULL,\n body TEXT NOT NULL,\n files JSONB NOT NULL DEFAULT '[]'::jsonb,\n tags JSONB NOT NULL DEFAULT '[]'::jsonb,\n created_at BIGINT NOT NULL,\n embedder TEXT,\n author TEXT,\n tsv TSVECTOR GENERATED ALWAYS AS (\n setweight(to_tsvector('english', coalesce(title, '')), 'A') ||\n setweight(to_tsvector('english', coalesce(tags::text, '')), 'B') ||\n setweight(to_tsvector('english', coalesce(body, '')), 'C')) STORED\n );\n CREATE INDEX IF NOT EXISTS idx_obs_tsv ON observations USING GIN(tsv);\n CREATE INDEX IF NOT EXISTS idx_obs_project_time\n ON observations(project, created_at DESC);\n CREATE INDEX IF NOT EXISTS idx_obs_tags ON observations USING GIN(tags);\n\n ALTER TABLE observations ADD COLUMN IF NOT EXISTS embedder TEXT;\n ALTER TABLE observations ADD COLUMN IF NOT EXISTS author TEXT;\n ALTER TABLE observations ADD COLUMN IF NOT EXISTS status TEXT NOT NULL DEFAULT 'done';\n\n ALTER TABLE sessions ADD COLUMN IF NOT EXISTS updated_at BIGINT;\n ALTER TABLE sessions ADD COLUMN IF NOT EXISTS distilled_at BIGINT;\n\n CREATE TABLE IF NOT EXISTS symbols (\n id TEXT PRIMARY KEY,\n project TEXT NOT NULL,\n name TEXT NOT NULL,\n kind TEXT NOT NULL,\n file TEXT NOT NULL,\n line INT NOT NULL,\n lang TEXT NOT NULL,\n signature TEXT NOT NULL DEFAULT ''\n );\n CREATE INDEX IF NOT EXISTS idx_symbols_lookup ON symbols(project, name);\n CREATE INDEX IF NOT EXISTS idx_symbols_file ON symbols(project, file);\n\n CREATE TABLE IF NOT EXISTS symbol_edges (\n id TEXT PRIMARY KEY,\n project TEXT NOT NULL,\n src_id TEXT NOT NULL,\n src_name TEXT NOT NULL,\n dst_id TEXT NOT NULL DEFAULT '',\n dst_name TEXT NOT NULL,\n relation TEXT NOT NULL,\n confidence TEXT NOT NULL,\n score REAL NOT NULL DEFAULT 1.0,\n file TEXT NOT NULL,\n line INT NOT NULL\n );\n CREATE INDEX IF NOT EXISTS idx_edges_src ON symbol_edges(project, src_id);\n CREATE INDEX IF NOT EXISTS idx_edges_dst ON symbol_edges(project, dst_id);\n CREATE INDEX IF NOT EXISTS idx_edges_file ON symbol_edges(project, file);\n\n CREATE TABLE IF NOT EXISTS scanned_files (\n project TEXT NOT NULL,\n path TEXT NOT NULL,\n hash TEXT NOT NULL,\n scanned_at BIGINT NOT NULL,\n PRIMARY KEY (project, path)\n );\n";
@@ -2,7 +2,7 @@ export const TSV_EXPRESSION = `
2
2
  setweight(to_tsvector('english', coalesce(title, '')), 'A') ||
3
3
  setweight(to_tsvector('english', coalesce(tags::text, '')), 'B') ||
4
4
  setweight(to_tsvector('english', coalesce(body, '')), 'C')`;
5
- export const SCHEMA_VERSION = 3;
5
+ export const SCHEMA_VERSION = 4;
6
6
  export const DDL = `
7
7
  CREATE TABLE IF NOT EXISTS claude_db_meta (
8
8
  id INT PRIMARY KEY,
@@ -44,6 +44,9 @@ export const DDL = `
44
44
  ALTER TABLE observations ADD COLUMN IF NOT EXISTS author TEXT;
45
45
  ALTER TABLE observations ADD COLUMN IF NOT EXISTS status TEXT NOT NULL DEFAULT 'done';
46
46
 
47
+ ALTER TABLE sessions ADD COLUMN IF NOT EXISTS updated_at BIGINT;
48
+ ALTER TABLE sessions ADD COLUMN IF NOT EXISTS distilled_at BIGINT;
49
+
47
50
  CREATE TABLE IF NOT EXISTS symbols (
48
51
  id TEXT PRIMARY KEY,
49
52
  project TEXT NOT NULL,
@@ -1,16 +1,21 @@
1
1
  import { toSession } from './rows.js';
2
+ import { summaryTime } from '../session-time.js';
2
3
  export async function upsertSession(pool, session) {
3
- await pool.query(`INSERT INTO sessions (id, project, started_at, ended_at, summary)
4
- VALUES ($1, $2, $3, $4, $5)
4
+ await pool.query(`INSERT INTO sessions (id, project, started_at, ended_at, summary, updated_at, distilled_at)
5
+ VALUES ($1, $2, $3, $4, $5, $6, $7)
5
6
  ON CONFLICT (id) DO UPDATE SET
6
- project = EXCLUDED.project,
7
- ended_at = COALESCE(EXCLUDED.ended_at, sessions.ended_at),
8
- summary = COALESCE(EXCLUDED.summary, sessions.summary)`, [
7
+ project = EXCLUDED.project,
8
+ ended_at = COALESCE(EXCLUDED.ended_at, sessions.ended_at),
9
+ summary = COALESCE(EXCLUDED.summary, sessions.summary),
10
+ updated_at = COALESCE(EXCLUDED.updated_at, sessions.updated_at),
11
+ distilled_at = COALESCE(EXCLUDED.distilled_at, sessions.distilled_at)`, [
9
12
  session.id,
10
13
  session.project,
11
14
  session.startedAt,
12
15
  session.endedAt ?? null,
13
16
  session.summary ?? null,
17
+ summaryTime(session),
18
+ session.distilledAt ?? null,
14
19
  ]);
15
20
  }
16
21
  export async function getSession(pool, id) {
@@ -19,7 +24,7 @@ export async function getSession(pool, id) {
19
24
  return row ? toSession(row) : null;
20
25
  }
21
26
  export async function clearSummary(pool, id) {
22
- const result = await pool.query('UPDATE sessions SET summary = NULL WHERE id = $1 AND summary IS NOT NULL', [id]);
27
+ const result = await pool.query('UPDATE sessions SET summary = NULL, updated_at = $2 WHERE id = $1 AND summary IS NOT NULL', [id, Date.now()]);
23
28
  return (result.rowCount ?? 0) > 0;
24
29
  }
25
30
  export async function recentSessions(pool, project, limit) {
@@ -30,5 +35,7 @@ export async function recentSessions(pool, project, limit) {
30
35
  }
31
36
  export async function sessionProjects(pool) {
32
37
  const res = await pool.query('SELECT DISTINCT project FROM sessions');
33
- return res.rows.map((row) => String(row['project'] ?? '')).filter((p) => p.length > 0);
38
+ return res.rows
39
+ .map((row) => (typeof row['project'] === 'string' ? row['project'] : ''))
40
+ .filter((p) => p.length > 0);
34
41
  }
@@ -0,0 +1,2 @@
1
+ import type { Session } from '../types.js';
2
+ export declare function summaryTime(session: Session): number | null;
@@ -0,0 +1,5 @@
1
+ export function summaryTime(session) {
2
+ if (session.updatedAt !== undefined)
3
+ return session.updatedAt;
4
+ return session.summary !== undefined ? Date.now() : null;
5
+ }
@@ -37,6 +37,7 @@ export function removeWhere(filter) {
37
37
  }
38
38
  export const TAG_PREDICATE = (prefix) => `EXISTS (SELECT 1 FROM json_each(${prefix}tags) WHERE value = ?)`;
39
39
  export function appendScope(query, conditions, params, prefix) {
40
+ conditions.push(`${prefix}status != 'replaced'`);
40
41
  if (query.project) {
41
42
  conditions.push(`${prefix}project = ?`);
42
43
  params.push(query.project);
@@ -57,6 +58,10 @@ export function appendScope(query, conditions, params, prefix) {
57
58
  conditions.push(`${prefix}created_at <= ?`);
58
59
  params.push(query.until);
59
60
  }
61
+ if (query.excludeSessions && query.excludeSessions.length > 0) {
62
+ conditions.push(`${prefix}session_id NOT IN (${query.excludeSessions.map(() => '?').join(',')})`);
63
+ params.push(...query.excludeSessions);
64
+ }
60
65
  }
61
66
  export function toMatchExpression(text, project) {
62
67
  const tokens = meaningfulTokens(text);
@@ -23,6 +23,7 @@ export declare class SqliteStore implements MemoryStore {
23
23
  searchKeyword(query: SearchQuery): Promise<ObservationIndexEntry[]>;
24
24
  searchVector(vector: number[], query: SearchQuery): Promise<ObservationIndexEntry[]>;
25
25
  closeObservations(ids: string[]): Promise<number>;
26
+ markReplaced(ids: string[]): Promise<number>;
26
27
  timeline(query: TimelineQuery): Promise<ObservationIndexEntry[]>;
27
28
  upsertGraph(scan: {
28
29
  symbols: CodeSymbol[];
@@ -3,11 +3,12 @@ import * as searchOps from './search.js';
3
3
  import * as sessionsOps from './sessions.js';
4
4
  import * as graphOps from './graph.js';
5
5
  import { DatabaseSync } from 'node:sqlite';
6
- import { toFilePath, } from './filters.js';
6
+ import { toFilePath } from './filters.js';
7
7
  import { dirname, resolve } from 'node:path';
8
8
  import { fileURLToPath } from 'node:url';
9
9
  import { mkdirSync, readFileSync } from 'node:fs';
10
10
  export const HERE = dirname(fileURLToPath(import.meta.url));
11
+ const BUSY_TIMEOUT_MS = 3000;
11
12
  export class SqliteStore {
12
13
  db;
13
14
  kind = 'sqlite';
@@ -17,10 +18,20 @@ export class SqliteStore {
17
18
  static async create(uri) {
18
19
  const path = toFilePath(uri);
19
20
  mkdirSync(dirname(path), { recursive: true });
20
- return new SqliteStore(new DatabaseSync(path));
21
+ const db = new DatabaseSync(path);
22
+ db.exec(`PRAGMA busy_timeout = ${BUSY_TIMEOUT_MS}`);
23
+ return new SqliteStore(db);
21
24
  }
22
25
  async init() {
23
- this.db.exec(readFileSync(resolve(HERE, 'schema.sql'), 'utf8'));
26
+ try {
27
+ this.db.exec(readFileSync(resolve(HERE, 'schema.sql'), 'utf8'));
28
+ }
29
+ catch (error) {
30
+ if (!/no such module: fts5/i.test(String(error)))
31
+ throw error;
32
+ throw new Error(`This Node's SQLite has no full-text search (FTS5), which claude-db needs. ` +
33
+ `Use Node 22.16 or newer; this is ${process.versions.node}.`, { cause: error });
34
+ }
24
35
  const row = this.db.prepare('PRAGMA user_version').get();
25
36
  const version = Number(row?.['user_version'] ?? 0);
26
37
  if (version < 1) {
@@ -38,8 +49,16 @@ export class SqliteStore {
38
49
  catch { }
39
50
  }
40
51
  }
41
- if (version < 3)
42
- this.db.exec('PRAGMA user_version = 3');
52
+ if (version < 4) {
53
+ for (const column of ['updated_at INTEGER', 'distilled_at INTEGER']) {
54
+ try {
55
+ this.db.exec(`ALTER TABLE sessions ADD COLUMN ${column}`);
56
+ }
57
+ catch { }
58
+ }
59
+ }
60
+ if (version < 4)
61
+ this.db.exec('PRAGMA user_version = 4');
43
62
  }
44
63
  async close() {
45
64
  this.db.close();
@@ -89,6 +108,9 @@ export class SqliteStore {
89
108
  async closeObservations(ids) {
90
109
  return observationsOps.closeObservations(this.db, ids);
91
110
  }
111
+ async markReplaced(ids) {
112
+ return observationsOps.markReplaced(this.db, ids);
113
+ }
92
114
  async timeline(query) {
93
115
  return searchOps.timeline(this.db, query);
94
116
  }
@@ -8,3 +8,4 @@ export declare function list(db: DatabaseSync, filter: ListFilter): Promise<Obse
8
8
  export declare function listProjects(db: DatabaseSync): Promise<ProjectSummary[]>;
9
9
  export declare function inventory(db: DatabaseSync): Promise<string[]>;
10
10
  export declare function closeObservations(db: DatabaseSync, ids: string[]): Promise<number>;
11
+ export declare function markReplaced(db: DatabaseSync, ids: string[]): Promise<number>;
@@ -78,6 +78,10 @@ export async function list(db, filter) {
78
78
  conditions.push('project = ?');
79
79
  params.push(filter.project);
80
80
  }
81
+ if (filter.sessionId) {
82
+ conditions.push('session_id = ?');
83
+ params.push(filter.sessionId);
84
+ }
81
85
  if (filter.kind) {
82
86
  conditions.push('kind = ?');
83
87
  params.push(filter.kind);
@@ -121,7 +125,7 @@ export async function inventory(db) {
121
125
  .prepare(`SELECT name FROM sqlite_master
122
126
  WHERE type IN ('table', 'view') AND name NOT LIKE 'sqlite_%'`)
123
127
  .all();
124
- return foreignNames(rows.map((row) => String(row['name'] ?? '')));
128
+ return foreignNames(rows.map((row) => (typeof row['name'] === 'string' ? row['name'] : '')));
125
129
  }
126
130
  export async function closeObservations(db, ids) {
127
131
  if (ids.length === 0)
@@ -133,3 +137,12 @@ export async function closeObservations(db, ids) {
133
137
  db.prepare(`UPDATE observations SET status = 'done' WHERE id IN (${holes})`).run(...ids);
134
138
  return row?.n ?? 0;
135
139
  }
140
+ export async function markReplaced(db, ids) {
141
+ if (ids.length === 0)
142
+ return 0;
143
+ const holes = ids.map(() => '?').join(',');
144
+ const result = db
145
+ .prepare(`UPDATE observations SET status = 'replaced' WHERE status != 'replaced' AND id IN (${holes})`)
146
+ .run(...ids);
147
+ return Number(result.changes);
148
+ }
@@ -17,6 +17,10 @@ export function toSession(row) {
17
17
  session.endedAt = Number(row['ended_at']);
18
18
  if (row['summary'] != null)
19
19
  session.summary = row['summary'];
20
+ if (row['updated_at'] != null)
21
+ session.updatedAt = Number(row['updated_at']);
22
+ if (row['distilled_at'] != null)
23
+ session.distilledAt = Number(row['distilled_at']);
20
24
  return session;
21
25
  }
22
26
  export function toObservation(row) {
@@ -7,7 +7,9 @@ CREATE TABLE IF NOT EXISTS sessions (
7
7
  project TEXT NOT NULL,
8
8
  started_at INTEGER NOT NULL,
9
9
  ended_at INTEGER,
10
- summary TEXT
10
+ summary TEXT,
11
+ updated_at INTEGER,
12
+ distilled_at INTEGER
11
13
  );
12
14
 
13
15
  CREATE INDEX IF NOT EXISTS idx_sessions_project
@@ -5,7 +5,7 @@ export async function searchKeyword(db, query) {
5
5
  const match = toMatchExpression(query.text, query.project);
6
6
  if (match === null)
7
7
  return [];
8
- const conditions = ['observations_fts MATCH ?'];
8
+ const conditions = ['observations_fts MATCH ?', "o.status != 'replaced'"];
9
9
  const params = [match];
10
10
  if (query.kind) {
11
11
  conditions.push('o.kind = ?');
@@ -23,6 +23,10 @@ export async function searchKeyword(db, query) {
23
23
  conditions.push('o.created_at <= ?');
24
24
  params.push(query.until);
25
25
  }
26
+ if (query.excludeSessions && query.excludeSessions.length > 0) {
27
+ conditions.push(`o.session_id NOT IN (${query.excludeSessions.map(() => '?').join(',')})`);
28
+ params.push(...query.excludeSessions);
29
+ }
26
30
  params.push(query.limit);
27
31
  const rows = db
28
32
  .prepare(`SELECT o.id, o.kind, o.title, o.project, o.created_at,
@@ -71,13 +75,13 @@ export async function timeline(db, query) {
71
75
  const rows = db
72
76
  .prepare(`SELECT id, kind, title, project, created_at, 0 AS score FROM (
73
77
  SELECT * FROM observations
74
- WHERE project = ? AND created_at <= ?
78
+ WHERE project = ? AND created_at <= ? AND status != 'replaced'
75
79
  ORDER BY created_at DESC LIMIT ?
76
80
  )
77
81
  UNION
78
82
  SELECT id, kind, title, project, created_at, 0 AS score FROM (
79
83
  SELECT * FROM observations
80
- WHERE project = ? AND created_at > ?
84
+ WHERE project = ? AND created_at > ? AND status != 'replaced'
81
85
  ORDER BY created_at ASC LIMIT ?
82
86
  )
83
87
  ORDER BY created_at ASC`)
@@ -1,16 +1,19 @@
1
1
  import { toSession } from './rows.js';
2
+ import { summaryTime } from '../session-time.js';
2
3
  export async function upsertSession(db, session) {
3
- db.prepare(`INSERT INTO sessions (id, project, started_at, ended_at, summary)
4
- VALUES (?, ?, ?, ?, ?)
4
+ db.prepare(`INSERT INTO sessions (id, project, started_at, ended_at, summary, updated_at, distilled_at)
5
+ VALUES (?, ?, ?, ?, ?, ?, ?)
5
6
  ON CONFLICT(id) DO UPDATE SET
6
- project = excluded.project,
7
- ended_at = COALESCE(excluded.ended_at, sessions.ended_at),
8
- summary = COALESCE(excluded.summary, sessions.summary)`).run(session.id, session.project, session.startedAt, session.endedAt ?? null, session.summary ?? null);
7
+ project = excluded.project,
8
+ ended_at = COALESCE(excluded.ended_at, sessions.ended_at),
9
+ summary = COALESCE(excluded.summary, sessions.summary),
10
+ updated_at = COALESCE(excluded.updated_at, sessions.updated_at),
11
+ distilled_at = COALESCE(excluded.distilled_at, sessions.distilled_at)`).run(session.id, session.project, session.startedAt, session.endedAt ?? null, session.summary ?? null, summaryTime(session), session.distilledAt ?? null);
9
12
  }
10
13
  export async function clearSummary(db, id) {
11
14
  const result = db
12
- .prepare('UPDATE sessions SET summary = NULL WHERE id = ? AND summary IS NOT NULL')
13
- .run(id);
15
+ .prepare('UPDATE sessions SET summary = NULL, updated_at = ? WHERE id = ? AND summary IS NOT NULL')
16
+ .run(Date.now(), id);
14
17
  return Number(result.changes) > 0;
15
18
  }
16
19
  export async function getSession(db, id) {
@@ -27,5 +30,7 @@ export async function recentSessions(db, project, limit) {
27
30
  }
28
31
  export async function sessionProjects(db) {
29
32
  const rows = db.prepare('SELECT DISTINCT project FROM sessions').all();
30
- return rows.map((row) => String(row['project'] ?? '')).filter((project) => project.length > 0);
33
+ return rows
34
+ .map((row) => (typeof row['project'] === 'string' ? row['project'] : ''))
35
+ .filter((project) => project.length > 0);
31
36
  }
package/dist/types.d.ts CHANGED
@@ -5,8 +5,10 @@ export interface Session {
5
5
  startedAt: number;
6
6
  endedAt?: number;
7
7
  summary?: string;
8
+ updatedAt?: number;
9
+ distilledAt?: number;
8
10
  }
9
- export type ObservationStatus = 'open' | 'done';
11
+ export type ObservationStatus = 'open' | 'done' | 'replaced';
10
12
  export interface Observation {
11
13
  id: string;
12
14
  sessionId: string;
@@ -38,6 +40,7 @@ export interface SearchQuery {
38
40
  tag?: string;
39
41
  since?: number;
40
42
  until?: number;
43
+ excludeSessions?: string[];
41
44
  limit: number;
42
45
  maxScanCandidates?: number;
43
46
  embedder?: string;
@@ -50,6 +53,7 @@ export interface RemoveFilter {
50
53
  }
51
54
  export interface ListFilter {
52
55
  project?: string;
56
+ sessionId?: string;
53
57
  kind?: ObservationKind;
54
58
  status?: ObservationStatus;
55
59
  after?: number;
@@ -21,9 +21,9 @@ export function findUsages(input) {
21
21
  return { root, matches: [], total: 0, truncated: false };
22
22
  if (/maxBuffer/i.test(err.message)) {
23
23
  throw new Error(`too many matches for "${input.symbol}" to read at once — narrow it ` +
24
- '(a longer name, --path to a subdirectory, or --regex to anchor it tighter)');
24
+ '(a longer name, --path to a subdirectory, or --regex to anchor it tighter)', { cause: error });
25
25
  }
26
- throw new Error((err.stderr ?? err.message).trim().split('\n')[0]);
26
+ throw new Error((err.stderr ?? err.message).trim().split('\n')[0], { cause: error });
27
27
  }
28
28
  const parsed = parseGrepOutput(raw).map((row) => ({
29
29
  ...row,
@@ -47,7 +47,9 @@ export function repoRootFor(start) {
47
47
  }
48
48
  catch (error) {
49
49
  const stderr = error.stderr?.trim();
50
- throw new Error(`${start} is not inside a git working tree${stderr ? ` (${stderr})` : ''}`);
50
+ throw new Error(`${start} is not inside a git working tree${stderr ? ` (${stderr})` : ''}`, {
51
+ cause: error,
52
+ });
51
53
  }
52
54
  }
53
55
  function buildArgs({ symbol, regex }) {
@@ -1,2 +1 @@
1
1
  export { findUsages, formatUsages, repoRootFor } from './find.js';
2
- export type { FindUsagesInput, UsagesResult, UsageMatch } from './find.js';
@@ -0,0 +1,6 @@
1
+ export interface HeadlessOptions {
2
+ flags?: readonly (readonly string[])[];
3
+ env?: Readonly<Record<string, string>>;
4
+ }
5
+ export declare function claudeBinary(env?: NodeJS.ProcessEnv): string;
6
+ export declare function runHeadless(prompt: string, model: string, timeoutMs: number, options?: HeadlessOptions): Promise<string | null>;
@@ -0,0 +1,38 @@
1
+ import { execFile } from 'node:child_process';
2
+ const MAX_BUFFER = 1024 * 1024;
3
+ const OPTIONAL_FLAGS = [
4
+ ['--effort', 'low'],
5
+ ['--no-session-persistence'],
6
+ ];
7
+ const UNKNOWN_OPTION = /unknown option '(--[\w-]+)'/i;
8
+ export function claudeBinary(env = process.env) {
9
+ return env['CLAUDE_CODE_EXECPATH'] || 'claude';
10
+ }
11
+ export async function runHeadless(prompt, model, timeoutMs, options = {}) {
12
+ let optional = [...OPTIONAL_FLAGS, ...(options.flags ?? [])];
13
+ for (;;) {
14
+ const result = await call(['-p', prompt, '--model', model, ...optional.flat()], timeoutMs, options.env ?? {});
15
+ if (result.stdout !== null)
16
+ return result.stdout;
17
+ const rejected = UNKNOWN_OPTION.exec(result.stderr)?.[1];
18
+ const remaining = optional.filter((flags) => flags[0] !== rejected);
19
+ if (remaining.length === optional.length)
20
+ return null;
21
+ optional = remaining;
22
+ }
23
+ }
24
+ function call(args, timeoutMs, env) {
25
+ return new Promise((done) => {
26
+ try {
27
+ const child = execFile(claudeBinary(), args, {
28
+ timeout: timeoutMs,
29
+ maxBuffer: MAX_BUFFER,
30
+ env: { ...process.env, ...env, CLAUDE_DB_CAPTURE: 'off' },
31
+ }, (error, stdout, stderr) => done({ stdout: error ? null : stdout, stderr: String(stderr) }));
32
+ child.stdin?.end();
33
+ }
34
+ catch {
35
+ done({ stdout: null, stderr: '' });
36
+ }
37
+ });
38
+ }
@@ -0,0 +1,7 @@
1
+ export interface BudgetUsage {
2
+ used: number;
3
+ pausedUntil: number;
4
+ }
5
+ export declare function budgetUsage(name: string, now?: number): BudgetUsage;
6
+ export declare function takeBudget(name: string, limit: number, count: number, now?: number): boolean;
7
+ export declare function pauseBudget(name: string, ms: number, now?: number): void;