claude-db 0.4.0 → 0.5.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 (203) hide show
  1. package/CHANGELOG.md +399 -0
  2. package/README.md +62 -94
  3. package/dist/capture/command.d.ts +0 -14
  4. package/dist/capture/command.js +0 -23
  5. package/dist/capture/flush.d.ts +1 -50
  6. package/dist/capture/flush.js +4 -63
  7. package/dist/capture/git.js +0 -20
  8. package/dist/capture/identity.d.ts +0 -17
  9. package/dist/capture/identity.js +1 -21
  10. package/dist/capture/index.d.ts +1 -0
  11. package/dist/capture/index.js +1 -0
  12. package/dist/capture/manual.d.ts +0 -19
  13. package/dist/capture/manual.js +0 -0
  14. package/dist/capture/progress.d.ts +4 -0
  15. package/dist/capture/progress.js +33 -0
  16. package/dist/capture/transcript.d.ts +0 -45
  17. package/dist/capture/transcript.js +4 -70
  18. package/dist/capture/turn-extractor.d.ts +0 -15
  19. package/dist/capture/turn-extractor.js +1 -104
  20. package/dist/cli/args.d.ts +4 -0
  21. package/dist/cli/args.js +16 -0
  22. package/dist/cli/commands/doctor.d.ts +1 -0
  23. package/dist/cli/commands/doctor.js +76 -0
  24. package/dist/cli/commands/graph.d.ts +2 -0
  25. package/dist/cli/commands/graph.js +93 -0
  26. package/dist/cli/commands/insight.d.ts +3 -0
  27. package/dist/cli/commands/insight.js +129 -0
  28. package/dist/cli/commands/maintain.d.ts +3 -0
  29. package/dist/cli/commands/maintain.js +77 -0
  30. package/dist/cli/commands/memory.d.ts +3 -0
  31. package/dist/cli/commands/memory.js +77 -0
  32. package/dist/cli/commands/seed.d.ts +1 -0
  33. package/dist/cli/commands/seed.js +43 -0
  34. package/dist/cli/commands/setup.d.ts +4 -0
  35. package/dist/cli/commands/setup.js +156 -0
  36. package/dist/cli/commands/sync.d.ts +1 -0
  37. package/dist/cli/commands/sync.js +95 -0
  38. package/dist/cli/commands/transfer.d.ts +9 -0
  39. package/dist/cli/commands/transfer.js +129 -0
  40. package/dist/cli/commands/use.d.ts +1 -0
  41. package/dist/cli/commands/use.js +90 -0
  42. package/dist/cli/constants.d.ts +2 -0
  43. package/dist/cli/constants.js +4 -0
  44. package/dist/cli/files.d.ts +4 -0
  45. package/dist/cli/files.js +33 -0
  46. package/dist/cli/index.js +15 -1080
  47. package/dist/cli/install.d.ts +1 -59
  48. package/dist/cli/install.js +5 -193
  49. package/dist/cli/instructions.d.ts +5 -0
  50. package/dist/cli/instructions.js +55 -0
  51. package/dist/cli/paths.d.ts +5 -0
  52. package/dist/cli/paths.js +19 -0
  53. package/dist/cli/refresh.d.ts +1 -0
  54. package/dist/cli/refresh.js +25 -0
  55. package/dist/cli/usage.d.ts +1 -0
  56. package/dist/cli/usage.js +39 -0
  57. package/dist/config/load.d.ts +0 -5
  58. package/dist/config/load.js +1 -8
  59. package/dist/config/schema.js +2 -58
  60. package/dist/context.d.ts +0 -10
  61. package/dist/context.js +0 -16
  62. package/dist/embed/builtin.d.ts +0 -12
  63. package/dist/embed/builtin.js +0 -20
  64. package/dist/embed/embedder.d.ts +0 -14
  65. package/dist/embed/embedder.js +0 -1
  66. package/dist/embed/index.d.ts +0 -9
  67. package/dist/embed/index.js +0 -9
  68. package/dist/embed/local.d.ts +0 -8
  69. package/dist/embed/local.js +0 -12
  70. package/dist/graph/index.d.ts +7 -0
  71. package/dist/graph/index.js +4 -0
  72. package/dist/graph/languages/ecmascript.d.ts +4 -0
  73. package/dist/graph/languages/ecmascript.js +47 -0
  74. package/dist/graph/languages/go.d.ts +2 -0
  75. package/dist/graph/languages/go.js +15 -0
  76. package/dist/graph/languages/index.d.ts +6 -0
  77. package/dist/graph/languages/index.js +20 -0
  78. package/dist/graph/languages/python.d.ts +2 -0
  79. package/dist/graph/languages/python.js +15 -0
  80. package/dist/graph/languages/rules.d.ts +18 -0
  81. package/dist/graph/languages/rules.js +1 -0
  82. package/dist/graph/languages/rust.d.ts +2 -0
  83. package/dist/graph/languages/rust.js +16 -0
  84. package/dist/graph/parser.d.ts +31 -0
  85. package/dist/graph/parser.js +29 -0
  86. package/dist/graph/query/format.d.ts +2 -0
  87. package/dist/graph/query/format.js +41 -0
  88. package/dist/graph/query/index.d.ts +5 -0
  89. package/dist/graph/query/index.js +4 -0
  90. package/dist/graph/query/lookup.d.ts +21 -0
  91. package/dist/graph/query/lookup.js +35 -0
  92. package/dist/graph/query/path.d.ts +2 -0
  93. package/dist/graph/query/path.js +48 -0
  94. package/dist/graph/query/refresh.d.ts +2 -0
  95. package/dist/graph/query/refresh.js +21 -0
  96. package/dist/graph/scan/extract.d.ts +15 -0
  97. package/dist/graph/scan/extract.js +101 -0
  98. package/dist/graph/scan/files.d.ts +12 -0
  99. package/dist/graph/scan/files.js +51 -0
  100. package/dist/graph/scan/index.d.ts +18 -0
  101. package/dist/graph/scan/index.js +44 -0
  102. package/dist/graph/scan/resolve.d.ts +3 -0
  103. package/dist/graph/scan/resolve.js +48 -0
  104. package/dist/hooks/payload.d.ts +0 -8
  105. package/dist/hooks/payload.js +0 -6
  106. package/dist/hooks/relevance.d.ts +0 -17
  107. package/dist/hooks/relevance.js +55 -38
  108. package/dist/hooks/session-end.js +0 -11
  109. package/dist/hooks/session-start.js +33 -14
  110. package/dist/hooks/user-prompt.js +0 -18
  111. package/dist/mcp/render.d.ts +0 -20
  112. package/dist/mcp/render.js +0 -39
  113. package/dist/mcp/server.js +50 -27
  114. package/dist/search/rank.d.ts +0 -14
  115. package/dist/search/rank.js +0 -16
  116. package/dist/search/service.d.ts +1 -32
  117. package/dist/search/service.js +1 -36
  118. package/dist/store/adapter.d.ts +11 -44
  119. package/dist/store/adapter.js +1 -12
  120. package/dist/store/index.d.ts +0 -11
  121. package/dist/store/index.js +0 -11
  122. package/dist/store/mongo/docs.d.ts +61 -0
  123. package/dist/store/mongo/docs.js +106 -0
  124. package/dist/store/mongo/driver.d.ts +1 -15
  125. package/dist/store/mongo/driver.js +0 -15
  126. package/dist/store/mongo/filters.d.ts +6 -0
  127. package/dist/store/mongo/filters.js +18 -0
  128. package/dist/store/mongo/graph.d.ts +12 -0
  129. package/dist/store/mongo/graph.js +61 -0
  130. package/dist/store/mongo/helpers.d.ts +2 -0
  131. package/dist/store/mongo/helpers.js +8 -0
  132. package/dist/store/mongo/index.d.ts +16 -13
  133. package/dist/store/mongo/index.js +52 -295
  134. package/dist/store/mongo/observations.d.ts +10 -0
  135. package/dist/store/mongo/observations.js +97 -0
  136. package/dist/store/mongo/search.d.ts +6 -0
  137. package/dist/store/mongo/search.js +51 -0
  138. package/dist/store/mongo/sessions.d.ts +6 -0
  139. package/dist/store/mongo/sessions.js +24 -0
  140. package/dist/store/mongo/vectorSearch.d.ts +5 -0
  141. package/dist/store/mongo/vectorSearch.js +57 -0
  142. package/dist/store/postgres/driver.d.ts +19 -0
  143. package/dist/store/postgres/driver.js +13 -0
  144. package/dist/store/postgres/filters.d.ts +2 -0
  145. package/dist/store/postgres/filters.js +22 -0
  146. package/dist/store/postgres/graph.d.ts +11 -0
  147. package/dist/store/postgres/graph.js +115 -0
  148. package/dist/store/postgres/index.d.ts +20 -33
  149. package/dist/store/postgres/index.js +43 -428
  150. package/dist/store/postgres/insert.d.ts +3 -0
  151. package/dist/store/postgres/insert.js +59 -0
  152. package/dist/store/postgres/meta.d.ts +10 -0
  153. package/dist/store/postgres/meta.js +54 -0
  154. package/dist/store/postgres/observations.d.ts +10 -0
  155. package/dist/store/postgres/observations.js +139 -0
  156. package/dist/store/postgres/rows.d.ts +6 -0
  157. package/dist/store/postgres/rows.js +74 -0
  158. package/dist/store/postgres/schema.d.ts +3 -0
  159. package/dist/store/postgres/schema.js +84 -0
  160. package/dist/store/postgres/search.d.ts +3 -0
  161. package/dist/store/postgres/search.js +20 -0
  162. package/dist/store/postgres/sessions.d.ts +5 -0
  163. package/dist/store/postgres/sessions.js +26 -0
  164. package/dist/store/postgres/vectorSearch.d.ts +3 -0
  165. package/dist/store/postgres/vectorSearch.js +21 -0
  166. package/dist/store/sqlite/filters.d.ts +9 -0
  167. package/dist/store/sqlite/filters.js +77 -0
  168. package/dist/store/sqlite/graph.d.ts +11 -0
  169. package/dist/store/sqlite/graph.js +100 -0
  170. package/dist/store/sqlite/index.d.ts +12 -10
  171. package/dist/store/sqlite/index.js +41 -379
  172. package/dist/store/sqlite/observations.d.ts +10 -0
  173. package/dist/store/sqlite/observations.js +128 -0
  174. package/dist/store/sqlite/rows.d.ts +8 -0
  175. package/dist/store/sqlite/rows.js +84 -0
  176. package/dist/store/sqlite/schema.sql +42 -2
  177. package/dist/store/sqlite/search.d.ts +5 -0
  178. package/dist/store/sqlite/search.js +86 -0
  179. package/dist/store/sqlite/sessions.d.ts +5 -0
  180. package/dist/store/sqlite/sessions.js +21 -0
  181. package/dist/types.d.ts +47 -40
  182. package/dist/types.js +0 -4
  183. package/dist/update.d.ts +0 -20
  184. package/dist/update.js +4 -29
  185. package/dist/usages/find.d.ts +2 -8
  186. package/dist/usages/find.js +58 -45
  187. package/dist/usages/index.d.ts +1 -1
  188. package/dist/usages/index.js +1 -1
  189. package/dist/util/project.d.ts +0 -12
  190. package/dist/util/project.js +0 -24
  191. package/dist/util/scope.d.ts +0 -9
  192. package/dist/util/scope.js +0 -9
  193. package/dist/util/shortid.d.ts +0 -5
  194. package/dist/util/shortid.js +1 -19
  195. package/dist/util/snippet.d.ts +0 -26
  196. package/dist/util/snippet.js +0 -30
  197. package/dist/util/vector.d.ts +0 -12
  198. package/dist/util/vector.js +0 -12
  199. package/dist/util/warnings.d.ts +0 -11
  200. package/dist/util/warnings.js +0 -11
  201. package/docs/how-it-works.md +183 -0
  202. package/package.json +14 -3
  203. package/skills/cdb-scan/SKILL.md +31 -6
@@ -1,27 +1,12 @@
1
- import { foreignNames, isWholeScope } from '../adapter.js';
2
- import { partitionIds } from '../../util/shortid.js';
3
- import { toSnippet } from '../../util/snippet.js';
4
- /**
5
- * Postgres backend. Uses tsvector for keyword search, and pgvector for
6
- * embeddings when the extension is available. If `CREATE EXTENSION vector`
7
- * is not permitted (common on locked-down managed instances) the store still
8
- * works, minus semantic recall, which the search service handles gracefully.
9
- */
10
- /**
11
- * Title outranks tags, tags outrank body — the same ordering FTS5 gets from its
12
- * column weights. Tags were missing here entirely, so an observation tagged
13
- * with the repository it touched was findable on SQLite and Mongo but not on
14
- * Postgres.
15
- */
16
- const TSV_EXPRESSION = `
17
- setweight(to_tsvector('english', coalesce(title, '')), 'A') ||
18
- setweight(to_tsvector('english', coalesce(tags::text, '')), 'B') ||
19
- setweight(to_tsvector('english', coalesce(body, '')), 'C')`;
20
- /**
21
- * Bumped whenever the DDL below changes, which makes every process re-run it
22
- * once. Only ever compared for equality.
23
- */
24
- const SCHEMA_VERSION = 1;
1
+ import * as insertOps from './insert.js';
2
+ import * as metaOps from './meta.js';
3
+ import * as vectorSearchOps from './vectorSearch.js';
4
+ import * as searchOps from './search.js';
5
+ import * as observationsOps from './observations.js';
6
+ import * as sessionsOps from './sessions.js';
7
+ import * as graphOps from './graph.js';
8
+ import { importPg } from './driver.js';
9
+ import { DDL, SCHEMA_VERSION } from './schema.js';
25
10
  export class PostgresStore {
26
11
  pool;
27
12
  kind = 'postgres';
@@ -36,18 +21,6 @@ export class PostgresStore {
36
21
  const pool = new pg.Pool({ connectionString: uri });
37
22
  return new PostgresStore(pool);
38
23
  }
39
- /**
40
- * Every hook is its own process, so nothing here is ever pooled or reused:
41
- * this ran in full on every single prompt. Against a managed Postgres, where
42
- * one round trip measured 49ms at best and 1045ms at the median, four of them
43
- * before the first real query is most of why a remote backend feels broken.
44
- *
45
- * The version row collapses that to one read on the steady-state path. It
46
- * carries the vector state too, because otherwise proving the extension is
47
- * available costs back the round trip just saved. Anything unexpected — no
48
- * table, an older version, an unreadable row — falls through to the full DDL,
49
- * so the worst case is exactly the behaviour this replaces.
50
- */
51
24
  async init() {
52
25
  const meta = await this.readMeta();
53
26
  if (meta?.version === SCHEMA_VERSION) {
@@ -56,111 +29,24 @@ export class PostgresStore {
56
29
  return;
57
30
  }
58
31
  this.vectorEnabled = await this.tryEnableVector();
59
- await this.pool.query(`
60
- CREATE TABLE IF NOT EXISTS claude_db_meta (
61
- id INT PRIMARY KEY,
62
- version INT NOT NULL,
63
- vector_enabled BOOLEAN NOT NULL DEFAULT FALSE,
64
- vector_dims INT
65
- );
66
-
67
- CREATE TABLE IF NOT EXISTS sessions (
68
- id TEXT PRIMARY KEY,
69
- project TEXT NOT NULL,
70
- started_at BIGINT NOT NULL,
71
- ended_at BIGINT,
72
- summary TEXT
73
- );
74
- CREATE INDEX IF NOT EXISTS idx_sessions_project
75
- ON sessions(project, started_at DESC);
76
-
77
- CREATE TABLE IF NOT EXISTS observations (
78
- id TEXT PRIMARY KEY,
79
- session_id TEXT NOT NULL,
80
- project TEXT NOT NULL,
81
- kind TEXT NOT NULL,
82
- title TEXT NOT NULL,
83
- body TEXT NOT NULL,
84
- files JSONB NOT NULL DEFAULT '[]'::jsonb,
85
- tags JSONB NOT NULL DEFAULT '[]'::jsonb,
86
- created_at BIGINT NOT NULL,
87
- embedder TEXT,
88
- author TEXT,
89
- tsv TSVECTOR GENERATED ALWAYS AS (${TSV_EXPRESSION}) STORED
90
- );
91
- CREATE INDEX IF NOT EXISTS idx_obs_tsv ON observations USING GIN(tsv);
92
- CREATE INDEX IF NOT EXISTS idx_obs_project_time
93
- ON observations(project, created_at DESC);
94
- CREATE INDEX IF NOT EXISTS idx_obs_tags ON observations USING GIN(tags);
95
-
96
- ALTER TABLE observations ADD COLUMN IF NOT EXISTS embedder TEXT;
97
- ALTER TABLE observations ADD COLUMN IF NOT EXISTS author TEXT;
98
- `);
32
+ await this.pool.query(DDL);
99
33
  await this.ensureTagsIndexed();
100
34
  if (this.vectorEnabled)
101
35
  this.vectorDims = await this.readVectorDims();
102
36
  await this.writeMeta();
103
37
  }
104
38
  async readMeta() {
105
- try {
106
- const res = await this.pool.query('SELECT version, vector_enabled, vector_dims FROM claude_db_meta WHERE id = 1');
107
- const row = res.rows[0];
108
- if (!row)
109
- return null;
110
- return {
111
- version: Number(row['version']),
112
- vectorEnabled: row['vector_enabled'] === true,
113
- vectorDims: row['vector_dims'] == null ? null : Number(row['vector_dims']),
114
- };
115
- }
116
- catch {
117
- // No table yet, or no permission to read it. Either way the caller does
118
- // the full setup, which is what happened before this existed.
119
- return null;
120
- }
39
+ return metaOps.readMeta(this.pool);
121
40
  }
122
41
  async writeMeta() {
123
- await this.pool.query(`INSERT INTO claude_db_meta (id, version, vector_enabled, vector_dims)
124
- VALUES (1, $1, $2, $3)
125
- ON CONFLICT (id) DO UPDATE SET
126
- version = EXCLUDED.version,
127
- vector_enabled = EXCLUDED.vector_enabled,
128
- vector_dims = EXCLUDED.vector_dims`, [SCHEMA_VERSION, this.vectorEnabled, this.vectorDims]);
42
+ return metaOps.writeMeta(this.pool, this.vectorEnabled, this.vectorDims);
129
43
  }
130
- /**
131
- * CREATE TABLE IF NOT EXISTS leaves an existing generated column alone, so a
132
- * database created before tags were indexed keeps the old expression. Rebuild
133
- * it once; dropping the column takes its index with it.
134
- */
135
44
  async ensureTagsIndexed() {
136
- const res = await this.pool.query(`SELECT pg_get_expr(d.adbin, d.adrelid) AS expr
137
- FROM pg_attrdef d
138
- JOIN pg_attribute a ON a.attrelid = d.adrelid AND a.attnum = d.adnum
139
- WHERE d.adrelid = 'observations'::regclass AND a.attname = 'tsv'`);
140
- const expr = String(res.rows[0]?.['expr'] ?? '');
141
- if (expr.length === 0 || expr.includes('tags'))
142
- return;
143
- await this.pool.query('ALTER TABLE observations DROP COLUMN tsv');
144
- await this.pool.query(`ALTER TABLE observations
145
- ADD COLUMN tsv TSVECTOR GENERATED ALWAYS AS (${TSV_EXPRESSION}) STORED`);
146
- await this.pool.query('CREATE INDEX IF NOT EXISTS idx_obs_tsv ON observations USING GIN(tsv)');
45
+ return metaOps.ensureTagsIndexed(this.pool);
147
46
  }
148
47
  async readVectorDims() {
149
- const res = await this.pool.query(`SELECT atttypmod AS dims FROM pg_attribute
150
- WHERE attrelid = 'observations'::regclass
151
- AND attname = 'embedding' AND NOT attisdropped`);
152
- const dims = Number(res.rows[0]?.['dims'] ?? -1);
153
- return dims > 0 ? dims : null;
48
+ return metaOps.readVectorDims(this.pool);
154
49
  }
155
- /**
156
- * Creates the embedding column sized to the vectors actually being stored,
157
- * since pgvector needs a fixed width but the width belongs to the embedder:
158
- * 256 for the builtin, 384 for MiniLM. Hardcoding 384 meant every insert on
159
- * a default install failed on a dimension mismatch and captured nothing.
160
- * Returns false when this width cannot be stored, and the caller keeps the
161
- * observation without a vector rather than losing it. `dims` is bounded
162
- * above because DDL cannot be parameterised.
163
- */
164
50
  async ensureVectorColumn(dims) {
165
51
  if (!this.vectorEnabled)
166
52
  return false;
@@ -170,11 +56,6 @@ export class PostgresStore {
170
56
  await this.pool.query(`ALTER TABLE observations ADD COLUMN IF NOT EXISTS embedding vector(${dims})`);
171
57
  await this.pool.query(`CREATE INDEX IF NOT EXISTS idx_obs_embedding
172
58
  ON observations USING hnsw (embedding vector_cosine_ops)`);
173
- // Read back rather than assumed: another process may have created the
174
- // column at a different width between this one reading the version row
175
- // and reaching here, and writing 384d values into a 256d column rolls
176
- // the whole batch back. One extra round trip, once, and only before the
177
- // first vector this process stores.
178
59
  this.vectorDims = await this.readVectorDims();
179
60
  await this.writeMeta();
180
61
  }
@@ -193,326 +74,60 @@ export class PostgresStore {
193
74
  return res.rowCount === 1;
194
75
  }
195
76
  async upsertSession(session) {
196
- await this.pool.query(`INSERT INTO sessions (id, project, started_at, ended_at, summary)
197
- VALUES ($1, $2, $3, $4, $5)
198
- ON CONFLICT (id) DO UPDATE SET
199
- project = EXCLUDED.project,
200
- ended_at = COALESCE(EXCLUDED.ended_at, sessions.ended_at),
201
- summary = COALESCE(EXCLUDED.summary, sessions.summary)`, [
202
- session.id,
203
- session.project,
204
- session.startedAt,
205
- session.endedAt ?? null,
206
- session.summary ?? null,
207
- ]);
77
+ return sessionsOps.upsertSession(this.pool, session);
208
78
  }
209
79
  async getSession(id) {
210
- const res = await this.pool.query('SELECT * FROM sessions WHERE id = $1', [id]);
211
- const row = res.rows[0];
212
- return row ? toSession(row) : null;
80
+ return sessionsOps.getSession(this.pool, id);
213
81
  }
214
82
  async recentSessions(project, limit) {
215
- const res = await this.pool.query(`SELECT * FROM sessions
216
- WHERE project = $1 AND summary IS NOT NULL
217
- ORDER BY started_at DESC LIMIT $2`, [project, limit]);
218
- return res.rows.map(toSession);
83
+ return sessionsOps.recentSessions(this.pool, project, limit);
219
84
  }
220
85
  async insertObservations(observations) {
221
- if (observations.length === 0)
222
- return;
223
- const width = observations.find((obs) => obs.embedding?.length)?.embedding?.length;
224
- const vectors = width !== undefined && (await this.ensureVectorColumn(width));
225
- const client = await this.pool.connect();
226
- try {
227
- await client.query('BEGIN');
228
- for (const obs of observations) {
229
- const columns = [
230
- 'id', 'session_id', 'project', 'kind', 'title', 'body',
231
- 'files', 'tags', 'created_at', 'embedder', 'author',
232
- ];
233
- const values = [
234
- obs.id, obs.sessionId, obs.project, obs.kind, obs.title, obs.body,
235
- JSON.stringify(obs.files), JSON.stringify(obs.tags), obs.createdAt,
236
- obs.embedder ?? null, obs.author ?? null,
237
- ];
238
- if (vectors && obs.embedding?.length === width) {
239
- columns.push('embedding');
240
- values.push(`[${obs.embedding.join(',')}]`);
241
- }
242
- const holes = values.map((_, i) => `$${i + 1}`).join(', ');
243
- const updates = columns
244
- .slice(1)
245
- .map((column) => `${column} = EXCLUDED.${column}`)
246
- .join(', ');
247
- await client.query(`INSERT INTO observations (${columns.join(', ')}) VALUES (${holes})
248
- ON CONFLICT (id) DO UPDATE SET ${updates}`, values);
249
- }
250
- await client.query('COMMIT');
251
- }
252
- catch (error) {
253
- await client.query('ROLLBACK');
254
- throw error;
255
- }
256
- finally {
257
- client.release();
258
- }
86
+ return insertOps.insertObservations(this.pool, (dims) => this.ensureVectorColumn(dims), observations);
259
87
  }
260
88
  async getObservations(ids) {
261
- if (ids.length === 0)
262
- return [];
263
- const { exact, prefixes } = partitionIds(ids);
264
- const clauses = [];
265
- const values = [];
266
- if (exact.length > 0) {
267
- values.push(exact);
268
- clauses.push(`id = ANY($${values.length}::text[])`);
269
- }
270
- for (const prefix of prefixes) {
271
- // Left-anchored LIKE uses the btree index on the text primary key.
272
- values.push(`${prefix.replace(/[%_]/g, '')}%`);
273
- clauses.push(`id LIKE $${values.length}`);
274
- }
275
- const res = await this.pool.query(`SELECT * FROM observations WHERE ${clauses.join(' OR ')}`, values);
276
- return res.rows.map(toObservation);
89
+ return observationsOps.getObservations(this.pool, ids);
277
90
  }
278
91
  async remove(filter) {
279
- if (filter.ids?.length === 0)
280
- return 0;
281
- const conditions = [];
282
- const values = [];
283
- if (filter.ids) {
284
- const { exact, prefixes } = partitionIds(filter.ids);
285
- const alternatives = [];
286
- if (exact.length > 0) {
287
- values.push(exact);
288
- alternatives.push(`id = ANY($${values.length}::text[])`);
289
- }
290
- for (const prefix of prefixes) {
291
- values.push(`${prefix.replace(/[%_]/g, '')}%`);
292
- alternatives.push(`id LIKE $${values.length}`);
293
- }
294
- conditions.push(`(${alternatives.join(' OR ')})`);
295
- }
296
- if (filter.project) {
297
- values.push(filter.project);
298
- conditions.push(`project = $${values.length}`);
299
- }
300
- if (filter.kind) {
301
- values.push(filter.kind);
302
- conditions.push(`kind = $${values.length}`);
303
- }
304
- if (filter.before !== undefined) {
305
- values.push(filter.before);
306
- conditions.push(`created_at < $${values.length}`);
307
- }
308
- const where = conditions.length > 0 ? `WHERE ${conditions.join(' AND ')}` : '';
309
- const client = await this.pool.connect();
310
- try {
311
- await client.query('BEGIN');
312
- const counted = await client.query(`SELECT COUNT(*)::int AS n FROM observations ${where}`, values);
313
- await client.query(`DELETE FROM observations ${where}`, values);
314
- if (isWholeScope(filter)) {
315
- await client.query(`DELETE FROM sessions ${filter.project ? 'WHERE project = $1' : ''}`, filter.project ? [filter.project] : []);
316
- }
317
- await client.query('COMMIT');
318
- return Number(counted.rows[0]?.['n'] ?? 0);
319
- }
320
- catch (error) {
321
- await client.query('ROLLBACK');
322
- throw error;
323
- }
324
- finally {
325
- client.release();
326
- }
92
+ return observationsOps.remove(this.pool, filter);
327
93
  }
328
94
  async list(filter) {
329
- const conditions = [];
330
- const values = [];
331
- if (filter.project) {
332
- values.push(filter.project);
333
- conditions.push(`project = $${values.length}`);
334
- }
335
- if (filter.kind) {
336
- values.push(filter.kind);
337
- conditions.push(`kind = $${values.length}`);
338
- }
339
- if (filter.after !== undefined) {
340
- values.push(filter.after);
341
- conditions.push(`created_at > $${values.length}`);
342
- }
343
- values.push(filter.limit ?? 1000);
344
- const res = await this.pool.query(`SELECT * FROM observations
345
- ${conditions.length > 0 ? `WHERE ${conditions.join(' AND ')}` : ''}
346
- ORDER BY created_at ASC LIMIT $${values.length}`, values);
347
- return res.rows.map(toObservation);
95
+ return observationsOps.list(this.pool, filter);
348
96
  }
349
97
  async listProjects() {
350
- const res = await this.pool.query(`SELECT project, COUNT(*)::int AS n, MAX(created_at) AS last
351
- FROM observations GROUP BY project ORDER BY last DESC`);
352
- return res.rows.map((row) => ({
353
- project: row['project'],
354
- observations: Number(row['n']),
355
- lastActive: Number(row['last']),
356
- }));
98
+ return observationsOps.listProjects(this.pool);
357
99
  }
358
100
  async inventory() {
359
- const res = await this.pool.query(`SELECT tablename AS name FROM pg_tables
360
- WHERE schemaname = ANY(current_schemas(false))`);
361
- return foreignNames(res.rows.map((row) => String(row['name'] ?? '')));
101
+ return observationsOps.inventory(this.pool);
362
102
  }
363
103
  async searchKeyword(query) {
364
- const conditions = ['tsv @@ q.tsq'];
365
- const values = [query.text];
366
- this.appendScope(query, conditions, values);
367
- values.push(query.limit);
368
- // plainto_tsquery ANDs every term, so a natural-language prompt only
369
- // matches a row containing all of it — which for a real prompt is nothing
370
- // at all, and injection would silently never fire. Flipping the operator on
371
- // its output keeps Postgres's own parsing, stemming and stopword removal
372
- // while giving the forgiving recall the other two adapters have; ts_rank
373
- // then sorts out what actually mattered.
374
- const res = await this.pool.query(`WITH q AS (
375
- SELECT replace(plainto_tsquery('english', $1)::text, '&', '|')::tsquery AS tsq
376
- )
377
- SELECT id, kind, title, project, created_at,
378
- ts_headline('english', body, q.tsq,
379
- 'MaxFragments=1, MaxWords=18, MinWords=5') AS snippet,
380
- ts_rank(tsv, q.tsq) AS score
381
- FROM observations, q
382
- WHERE ${conditions.join(' AND ')}
383
- ORDER BY score DESC
384
- LIMIT $${values.length}`, values);
385
- return res.rows.map(toIndexEntry);
104
+ return searchOps.searchKeyword(this.pool, query);
386
105
  }
387
106
  async searchVector(vector, query) {
388
- if (!this.vectorEnabled || this.vectorDims !== vector.length)
389
- return [];
390
- const conditions = ['embedding IS NOT NULL'];
391
- const values = [`[${vector.join(',')}]`];
392
- this.appendScope(query, conditions, values);
393
- if (query.embedder) {
394
- values.push(query.embedder);
395
- conditions.push(`(embedder = $${values.length} OR embedder IS NULL)`);
396
- }
397
- values.push(query.limit);
398
- const res = await this.pool.query(`SELECT id, kind, title, project, created_at,
399
- 1 - (embedding <=> $1::vector) AS score
400
- FROM observations
401
- WHERE ${conditions.join(' AND ')}
402
- ORDER BY embedding <=> $1::vector
403
- LIMIT $${values.length}`, values);
404
- return res.rows.map(toIndexEntry);
107
+ return vectorSearchOps.searchVector(this.pool, this.vectorEnabled, this.vectorDims, vector, query);
405
108
  }
406
- async timeline(query) {
407
- const anchorRes = await this.pool.query('SELECT project, created_at FROM observations WHERE id = $1', [query.observationId]);
408
- const anchor = anchorRes.rows[0];
409
- if (!anchor)
410
- return [];
411
- const res = await this.pool.query(`(SELECT id, kind, title, project, created_at, 0 AS score
412
- FROM observations
413
- WHERE project = $1 AND created_at <= $2
414
- ORDER BY created_at DESC LIMIT $3)
415
- UNION
416
- (SELECT id, kind, title, project, created_at, 0 AS score
417
- FROM observations
418
- WHERE project = $1 AND created_at > $2
419
- ORDER BY created_at ASC LIMIT $4)
420
- ORDER BY created_at ASC`, [anchor.project, anchor.created_at, query.before + 1, query.after]);
421
- return res.rows.map(toIndexEntry);
109
+ async closeObservations(ids) {
110
+ return observationsOps.closeObservations(this.pool, ids);
422
111
  }
423
- appendScope(query, conditions, values) {
424
- if (query.project) {
425
- values.push(query.project);
426
- conditions.push(`project = $${values.length}`);
427
- }
428
- if (query.kind) {
429
- values.push(query.kind);
430
- conditions.push(`kind = $${values.length}`);
431
- }
432
- if (query.tag) {
433
- // Containment rather than a text match, so `api` cannot match `api-docs`.
434
- values.push(JSON.stringify([query.tag]));
435
- conditions.push(`tags @> $${values.length}::jsonb`);
436
- }
437
- if (query.since !== undefined) {
438
- values.push(query.since);
439
- conditions.push(`created_at >= $${values.length}`);
440
- }
441
- if (query.until !== undefined) {
442
- values.push(query.until);
443
- conditions.push(`created_at <= $${values.length}`);
444
- }
112
+ async timeline(query) {
113
+ return observationsOps.timeline(this.pool, query);
445
114
  }
446
115
  async tryEnableVector() {
447
- try {
448
- await this.pool.query('CREATE EXTENSION IF NOT EXISTS vector');
449
- return true;
450
- }
451
- catch {
452
- return false;
453
- }
116
+ return metaOps.tryEnableVector(this.pool);
454
117
  }
455
- }
456
- async function importPg() {
457
- try {
458
- // Bypasses TypeScript's static resolution: `pg` is an optional peer and
459
- // may legitimately be absent at build time.
460
- const mod = (await import(/* @vite-ignore */ 'pg'));
461
- // pg is CommonJS; under NodeNext it may or may not arrive default-wrapped.
462
- if (mod.default?.Pool)
463
- return mod.default;
464
- if (mod.Pool)
465
- return { Pool: mod.Pool };
466
- throw new Error('unexpected pg module shape');
118
+ async upsertGraph(scan) {
119
+ return graphOps.upsertGraph(this.pool, scan);
467
120
  }
468
- catch {
469
- throw new Error('Postgres driver not installed. Run: npm install pg');
121
+ async findSymbols(filter) {
122
+ return graphOps.findSymbols(this.pool, filter);
123
+ }
124
+ async findEdges(filter) {
125
+ return graphOps.findEdges(this.pool, filter);
126
+ }
127
+ async scannedFiles(project) {
128
+ return graphOps.scannedFiles(this.pool, project);
129
+ }
130
+ async removeGraph(project, files) {
131
+ return graphOps.removeGraph(this.pool, project, files);
470
132
  }
471
- }
472
- function toSession(row) {
473
- const session = {
474
- id: row['id'],
475
- project: row['project'],
476
- startedAt: Number(row['started_at']),
477
- };
478
- if (row['ended_at'] != null)
479
- session.endedAt = Number(row['ended_at']);
480
- if (row['summary'] != null)
481
- session.summary = row['summary'];
482
- return session;
483
- }
484
- function toObservation(row) {
485
- const obs = {
486
- id: row['id'],
487
- sessionId: row['session_id'],
488
- project: row['project'],
489
- kind: row['kind'],
490
- title: row['title'],
491
- body: row['body'],
492
- files: row['files'] ?? [],
493
- tags: row['tags'] ?? [],
494
- createdAt: Number(row['created_at']),
495
- };
496
- if (row['embedder'] != null)
497
- obs.embedder = row['embedder'];
498
- if (row['author'] != null)
499
- obs.author = row['author'];
500
- return obs;
501
- }
502
- function toIndexEntry(row) {
503
- const entry = {
504
- id: row['id'],
505
- kind: row['kind'],
506
- title: row['title'],
507
- project: row['project'],
508
- createdAt: Number(row['created_at']),
509
- score: Number(row['score'] ?? 0),
510
- };
511
- // ts_headline wraps matches in <b> by default. Left at the default rather
512
- // than configured away, because an empty StartSel is not portable across
513
- // server versions; toSnippet strips them.
514
- const snippet = toSnippet(row['snippet']);
515
- if (snippet)
516
- entry.snippet = snippet;
517
- return entry;
518
133
  }
@@ -0,0 +1,3 @@
1
+ import type { Pool } from './driver.js';
2
+ import type { Observation } from '../../types.js';
3
+ export declare function insertObservations(pool: Pool, ensureVectorColumn: (dims: number) => Promise<boolean>, observations: Observation[]): Promise<void>;
@@ -0,0 +1,59 @@
1
+ export async function insertObservations(pool, ensureVectorColumn, observations) {
2
+ if (observations.length === 0)
3
+ return;
4
+ const width = observations.find((obs) => obs.embedding?.length)?.embedding?.length;
5
+ const vectors = width !== undefined && (await ensureVectorColumn(width));
6
+ const client = await pool.connect();
7
+ try {
8
+ await client.query('BEGIN');
9
+ for (const obs of observations) {
10
+ const columns = [
11
+ 'id',
12
+ 'session_id',
13
+ 'project',
14
+ 'kind',
15
+ 'title',
16
+ 'body',
17
+ 'files',
18
+ 'tags',
19
+ 'created_at',
20
+ 'embedder',
21
+ 'author',
22
+ 'status',
23
+ ];
24
+ const values = [
25
+ obs.id,
26
+ obs.sessionId,
27
+ obs.project,
28
+ obs.kind,
29
+ obs.title,
30
+ obs.body,
31
+ JSON.stringify(obs.files),
32
+ JSON.stringify(obs.tags),
33
+ obs.createdAt,
34
+ obs.embedder ?? null,
35
+ obs.author ?? null,
36
+ obs.status ?? 'done',
37
+ ];
38
+ if (vectors && obs.embedding?.length === width) {
39
+ columns.push('embedding');
40
+ values.push(`[${obs.embedding.join(',')}]`);
41
+ }
42
+ const holes = values.map((_, i) => `$${i + 1}`).join(', ');
43
+ const updates = columns
44
+ .slice(1)
45
+ .map((column) => `${column} = EXCLUDED.${column}`)
46
+ .join(', ');
47
+ await client.query(`INSERT INTO observations (${columns.join(', ')}) VALUES (${holes})
48
+ ON CONFLICT (id) DO UPDATE SET ${updates}`, values);
49
+ }
50
+ await client.query('COMMIT');
51
+ }
52
+ catch (error) {
53
+ await client.query('ROLLBACK');
54
+ throw error;
55
+ }
56
+ finally {
57
+ client.release();
58
+ }
59
+ }
@@ -0,0 +1,10 @@
1
+ import type { Pool } from './driver.js';
2
+ export declare function readMeta(pool: Pool): Promise<{
3
+ version: number;
4
+ vectorEnabled: boolean;
5
+ vectorDims: number | null;
6
+ } | null>;
7
+ export declare function ensureTagsIndexed(pool: Pool): Promise<void>;
8
+ export declare function readVectorDims(pool: Pool): Promise<number | null>;
9
+ export declare function tryEnableVector(pool: Pool): Promise<boolean>;
10
+ export declare function writeMeta(pool: Pool, vectorEnabled: boolean, vectorDims: number | null): Promise<void>;
@@ -0,0 +1,54 @@
1
+ import { SCHEMA_VERSION, TSV_EXPRESSION } from './schema.js';
2
+ export async function readMeta(pool) {
3
+ try {
4
+ const res = await pool.query('SELECT version, vector_enabled, vector_dims FROM claude_db_meta WHERE id = 1');
5
+ const row = res.rows[0];
6
+ if (!row)
7
+ return null;
8
+ return {
9
+ version: Number(row['version']),
10
+ vectorEnabled: row['vector_enabled'] === true,
11
+ vectorDims: row['vector_dims'] == null ? null : Number(row['vector_dims']),
12
+ };
13
+ }
14
+ catch {
15
+ return null;
16
+ }
17
+ }
18
+ export async function ensureTagsIndexed(pool) {
19
+ const res = await pool.query(`SELECT pg_get_expr(d.adbin, d.adrelid) AS expr
20
+ FROM pg_attrdef d
21
+ JOIN pg_attribute a ON a.attrelid = d.adrelid AND a.attnum = d.adnum
22
+ WHERE d.adrelid = 'observations'::regclass AND a.attname = 'tsv'`);
23
+ const expr = String(res.rows[0]?.['expr'] ?? '');
24
+ if (expr.length === 0 || expr.includes('tags'))
25
+ return;
26
+ await pool.query('ALTER TABLE observations DROP COLUMN tsv');
27
+ await pool.query(`ALTER TABLE observations
28
+ ADD COLUMN tsv TSVECTOR GENERATED ALWAYS AS (${TSV_EXPRESSION}) STORED`);
29
+ await pool.query('CREATE INDEX IF NOT EXISTS idx_obs_tsv ON observations USING GIN(tsv)');
30
+ }
31
+ export async function readVectorDims(pool) {
32
+ const res = await pool.query(`SELECT atttypmod AS dims FROM pg_attribute
33
+ WHERE attrelid = 'observations'::regclass
34
+ AND attname = 'embedding' AND NOT attisdropped`);
35
+ const dims = Number(res.rows[0]?.['dims'] ?? -1);
36
+ return dims > 0 ? dims : null;
37
+ }
38
+ export async function tryEnableVector(pool) {
39
+ try {
40
+ await pool.query('CREATE EXTENSION IF NOT EXISTS vector');
41
+ return true;
42
+ }
43
+ catch {
44
+ return false;
45
+ }
46
+ }
47
+ export async function writeMeta(pool, vectorEnabled, vectorDims) {
48
+ await pool.query(`INSERT INTO claude_db_meta (id, version, vector_enabled, vector_dims)
49
+ VALUES (1, $1, $2, $3)
50
+ ON CONFLICT (id) DO UPDATE SET
51
+ version = EXCLUDED.version,
52
+ vector_enabled = EXCLUDED.vector_enabled,
53
+ vector_dims = EXCLUDED.vector_dims`, [SCHEMA_VERSION, vectorEnabled, vectorDims]);
54
+ }