claude-db 0.4.1 → 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 -194
  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 +46 -25
  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 +51 -54
  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,22 +1,13 @@
1
+ import * as observationsOps from './observations.js';
2
+ import * as searchOps from './search.js';
3
+ import * as sessionsOps from './sessions.js';
4
+ import * as graphOps from './graph.js';
1
5
  import { DatabaseSync } from 'node:sqlite';
2
- import { mkdirSync, readFileSync } from 'node:fs';
6
+ import { toFilePath, } from './filters.js';
3
7
  import { dirname, resolve } from 'node:path';
4
8
  import { fileURLToPath } from 'node:url';
5
- import { foreignNames, isWholeScope } from '../adapter.js';
6
- import { cosine, packVector, unpackVector } from '../../util/vector.js';
7
- import { scopeToken } from '../../util/scope.js';
8
- import { toSnippet } from '../../util/snippet.js';
9
- import { partitionIds } from '../../util/shortid.js';
10
- const HERE = dirname(fileURLToPath(import.meta.url));
11
- /**
12
- * Zero-config default backend, built on Node's own `node:sqlite`.
13
- *
14
- * Using the builtin rather than better-sqlite3 means no node-gyp, no prebuilt
15
- * binary to mismatch, and no install step that can fail on a user's machine.
16
- * Keyword search is FTS5; vectors are scored by exact brute-force cosine,
17
- * which stays comfortably fast past the ~100k observations one developer
18
- * accumulates and avoids an approximate index that would need tuning.
19
- */
9
+ import { mkdirSync, readFileSync } from 'node:fs';
10
+ export const HERE = dirname(fileURLToPath(import.meta.url));
20
11
  export class SqliteStore {
21
12
  db;
22
13
  kind = 'sqlite';
@@ -32,25 +23,23 @@ export class SqliteStore {
32
23
  this.db.exec(readFileSync(resolve(HERE, 'schema.sql'), 'utf8'));
33
24
  const row = this.db.prepare('PRAGMA user_version').get();
34
25
  const version = Number(row?.['user_version'] ?? 0);
35
- // Databases written before recursive_triggers was set carry orphaned FTS
36
- // rows for every re-ingested observation. One rebuild clears them.
37
26
  if (version < 1) {
38
27
  this.db.exec(`INSERT INTO observations_fts(observations_fts) VALUES('rebuild');`);
39
28
  }
40
- // CREATE TABLE IF NOT EXISTS leaves an existing table alone, so columns
41
- // added after the fact have to be applied here.
42
- if (version < 2) {
43
- for (const column of ['embedder TEXT', 'author TEXT']) {
29
+ if (version < 3) {
30
+ for (const column of [
31
+ 'embedder TEXT',
32
+ 'author TEXT',
33
+ "status TEXT NOT NULL DEFAULT 'done'",
34
+ ]) {
44
35
  try {
45
36
  this.db.exec(`ALTER TABLE observations ADD COLUMN ${column}`);
46
37
  }
47
- catch {
48
- // Already present, which is the normal case on a fresh database.
49
- }
38
+ catch { }
50
39
  }
51
40
  }
52
- if (version < 2)
53
- this.db.exec('PRAGMA user_version = 2');
41
+ if (version < 3)
42
+ this.db.exec('PRAGMA user_version = 3');
54
43
  }
55
44
  async close() {
56
45
  this.db.close();
@@ -59,384 +48,57 @@ export class SqliteStore {
59
48
  return this.db.prepare('SELECT 1 AS ok').get() !== undefined;
60
49
  }
61
50
  async upsertSession(session) {
62
- this.db
63
- .prepare(`INSERT INTO sessions (id, project, started_at, ended_at, summary)
64
- VALUES (?, ?, ?, ?, ?)
65
- ON CONFLICT(id) DO UPDATE SET
66
- project = excluded.project,
67
- ended_at = COALESCE(excluded.ended_at, sessions.ended_at),
68
- summary = COALESCE(excluded.summary, sessions.summary)`)
69
- .run(session.id, session.project, session.startedAt, session.endedAt ?? null, session.summary ?? null);
51
+ return sessionsOps.upsertSession(this.db, session);
70
52
  }
71
53
  async getSession(id) {
72
- const row = this.db.prepare('SELECT * FROM sessions WHERE id = ?').get(id);
73
- return row ? toSession(row) : null;
54
+ return sessionsOps.getSession(this.db, id);
74
55
  }
75
56
  async recentSessions(project, limit) {
76
- const rows = this.db
77
- .prepare(`SELECT * FROM sessions
78
- WHERE project = ? AND summary IS NOT NULL
79
- ORDER BY started_at DESC LIMIT ?`)
80
- .all(project, limit);
81
- return rows.map(toSession);
57
+ return sessionsOps.recentSessions(this.db, project, limit);
82
58
  }
83
59
  async insertObservations(observations) {
84
- if (observations.length === 0)
85
- return;
86
- const stmt = this.db.prepare(`INSERT OR REPLACE INTO observations
87
- (id, session_id, project, scope, kind, title, body, files, tags,
88
- created_at, embedding, embedder, author)
89
- VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`);
90
- this.db.exec('BEGIN');
91
- try {
92
- for (const obs of observations) {
93
- 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);
94
- }
95
- this.db.exec('COMMIT');
96
- }
97
- catch (error) {
98
- this.db.exec('ROLLBACK');
99
- throw error;
100
- }
60
+ return observationsOps.insertObservations(this.db, observations);
101
61
  }
102
62
  async getObservations(ids) {
103
- if (ids.length === 0)
104
- return [];
105
- const { exact, prefixes } = partitionIds(ids);
106
- const clauses = [];
107
- const params = [];
108
- if (exact.length > 0) {
109
- clauses.push(`id IN (${exact.map(() => '?').join(',')})`);
110
- params.push(...exact);
111
- }
112
- // GLOB with a trailing star is prefix-anchored, so SQLite can serve it
113
- // from the primary key index rather than scanning.
114
- for (const prefix of prefixes) {
115
- clauses.push('id GLOB ?');
116
- params.push(`${prefix}*`);
117
- }
118
- const rows = this.db
119
- .prepare(`SELECT * FROM observations WHERE ${clauses.join(' OR ')}`)
120
- .all(...params);
121
- return rows.map(toObservation);
63
+ return observationsOps.getObservations(this.db, ids);
122
64
  }
123
65
  async remove(filter) {
124
- if (filter.ids?.length === 0)
125
- return 0;
126
- const { where, params } = removeWhere(filter);
127
- const wipe = isWholeScope(filter);
128
- const count = this.db
129
- .prepare(`SELECT COUNT(*) AS n FROM observations ${where}`)
130
- .get(...params);
131
- this.db.exec('BEGIN');
132
- try {
133
- // The FTS mirror is kept in sync by triggers, so deleting rows here is
134
- // enough; dropping it manually would desynchronise the two.
135
- this.db.prepare(`DELETE FROM observations ${where}`).run(...params);
136
- if (wipe) {
137
- const scope = filter.project ? 'WHERE project = ?' : '';
138
- this.db
139
- .prepare(`DELETE FROM sessions ${scope}`)
140
- .run(...(filter.project ? [filter.project] : []));
141
- }
142
- this.db.exec('COMMIT');
143
- }
144
- catch (error) {
145
- this.db.exec('ROLLBACK');
146
- throw error;
147
- }
148
- // Only worth the rewrite when a whole scope went; forgetting one row does
149
- // not justify rebuilding the file.
150
- if (wipe)
151
- this.db.exec('VACUUM');
152
- return count?.n ?? 0;
66
+ return observationsOps.remove(this.db, filter);
153
67
  }
154
68
  async list(filter) {
155
- const conditions = [];
156
- const params = [];
157
- if (filter.project) {
158
- conditions.push('project = ?');
159
- params.push(filter.project);
160
- }
161
- if (filter.kind) {
162
- conditions.push('kind = ?');
163
- params.push(filter.kind);
164
- }
165
- if (filter.after !== undefined) {
166
- conditions.push('created_at > ?');
167
- params.push(filter.after);
168
- }
169
- params.push(filter.limit ?? 1000);
170
- const rows = this.db
171
- .prepare(`SELECT * FROM observations
172
- ${conditions.length > 0 ? `WHERE ${conditions.join(' AND ')}` : ''}
173
- ORDER BY created_at ASC LIMIT ?`)
174
- .all(...params);
175
- return rows.map(toObservation);
69
+ return observationsOps.list(this.db, filter);
176
70
  }
177
71
  async listProjects() {
178
- const rows = this.db
179
- .prepare(`SELECT project, COUNT(*) AS n, MAX(created_at) AS last
180
- FROM observations GROUP BY project ORDER BY last DESC`)
181
- .all();
182
- return rows.map((row) => ({
183
- project: row['project'],
184
- observations: Number(row['n']),
185
- lastActive: Number(row['last']),
186
- }));
72
+ return observationsOps.listProjects(this.db);
187
73
  }
188
74
  async inventory() {
189
- const rows = this.db
190
- .prepare(`SELECT name FROM sqlite_master
191
- WHERE type IN ('table', 'view') AND name NOT LIKE 'sqlite_%'`)
192
- .all();
193
- return foreignNames(rows.map((row) => String(row['name'] ?? '')));
75
+ return observationsOps.inventory(this.db);
194
76
  }
195
77
  async searchKeyword(query) {
196
- // The project constraint goes inside the MATCH expression, not the WHERE
197
- // clause. Filtering after the match makes FTS5 rank every project's
198
- // documents and discard all but one project's worth of that work.
199
- const match = toMatchExpression(query.text, query.project);
200
- if (match === null)
201
- return [];
202
- // Remaining filters are cheap and genuinely post-match.
203
- const conditions = ['observations_fts MATCH ?'];
204
- const params = [match];
205
- if (query.kind) {
206
- conditions.push('o.kind = ?');
207
- params.push(query.kind);
208
- }
209
- if (query.tag) {
210
- conditions.push(TAG_PREDICATE('o.'));
211
- params.push(query.tag);
212
- }
213
- if (query.since !== undefined) {
214
- conditions.push('o.created_at >= ?');
215
- params.push(query.since);
216
- }
217
- if (query.until !== undefined) {
218
- conditions.push('o.created_at <= ?');
219
- params.push(query.until);
220
- }
221
- params.push(query.limit);
222
- // bm25() is lower-is-better, so negate it into a descending score. Column
223
- // weights (title, body, tags, scope) make a hit in the one-sentence claim
224
- // outrank the same word buried in a long body; scope carries no weight
225
- // because it is a filter, not a relevance signal.
226
- // snippet() over column 1 (body) returns the matched fragment, which is
227
- // what makes a result choosable without expanding it. Markers are empty
228
- // because the fragment itself is the signal; single-quoted, since SQLite
229
- // reads a double-quoted literal as an identifier.
230
- const rows = this.db
231
- .prepare(`SELECT o.id, o.kind, o.title, o.project, o.created_at,
232
- snippet(observations_fts, 1, '', '', '…', 14) AS snippet,
233
- -bm25(observations_fts, 10.0, 1.0, 5.0, 0.0) AS score
234
- FROM observations_fts
235
- JOIN observations o ON o.rowid = observations_fts.rowid
236
- WHERE ${conditions.join(' AND ')}
237
- ORDER BY score DESC
238
- LIMIT ?`)
239
- .all(...params);
240
- return rows.map(toIndexEntry);
78
+ return searchOps.searchKeyword(this.db, query);
241
79
  }
242
80
  async searchVector(vector, query) {
243
- const conditions = ['embedding IS NOT NULL'];
244
- const params = [];
245
- appendScope(query, conditions, params, '');
246
- // NULL means the row predates the column, and the width check in cosine()
247
- // still guards it. Anything else is a different embedding space.
248
- if (query.embedder) {
249
- conditions.push('(embedder = ? OR embedder IS NULL)');
250
- params.push(query.embedder);
251
- }
252
- // Newest-first with a hard cap. The scan is linear in rows returned, so
253
- // this is what keeps p95 flat as history grows: recent memory stays
254
- // semantically searchable and older memory remains reachable by keyword.
255
- params.push(query.maxScanCandidates ?? 25000);
256
- const rows = this.db
257
- .prepare(`SELECT id, kind, title, project, created_at, embedding
258
- FROM observations WHERE ${conditions.join(' AND ')}
259
- ORDER BY created_at DESC LIMIT ?`)
260
- .all(...params);
261
- return rows
262
- .map((row) => ({
263
- id: row['id'],
264
- kind: row['kind'],
265
- title: row['title'],
266
- project: row['project'],
267
- createdAt: Number(row['created_at']),
268
- score: row['embedding']
269
- ? cosine(vector, unpackVector(toBuffer(row['embedding'])))
270
- : 0,
271
- }))
272
- .sort((a, b) => b.score - a.score)
273
- .slice(0, query.limit);
274
- }
275
- async timeline(query) {
276
- const anchor = this.db
277
- .prepare('SELECT project, created_at FROM observations WHERE id = ?')
278
- .get(query.observationId);
279
- if (!anchor)
280
- return [];
281
- const rows = this.db
282
- .prepare(`SELECT id, kind, title, project, created_at, 0 AS score FROM (
283
- SELECT * FROM observations
284
- WHERE project = ? AND created_at <= ?
285
- ORDER BY created_at DESC LIMIT ?
286
- )
287
- UNION
288
- SELECT id, kind, title, project, created_at, 0 AS score FROM (
289
- SELECT * FROM observations
290
- WHERE project = ? AND created_at > ?
291
- ORDER BY created_at ASC LIMIT ?
292
- )
293
- ORDER BY created_at ASC`)
294
- .all(anchor['project'], anchor['created_at'], query.before + 1, anchor['project'], anchor['created_at'], query.after);
295
- return rows.map(toIndexEntry);
296
- }
297
- }
298
- function removeWhere(filter) {
299
- const conditions = [];
300
- const params = [];
301
- if (filter.ids) {
302
- const { exact, prefixes } = partitionIds(filter.ids);
303
- const alternatives = [];
304
- if (exact.length > 0) {
305
- alternatives.push(`id IN (${exact.map(() => '?').join(',')})`);
306
- params.push(...exact);
307
- }
308
- for (const prefix of prefixes) {
309
- alternatives.push('id GLOB ?');
310
- params.push(`${prefix}*`);
311
- }
312
- conditions.push(`(${alternatives.join(' OR ')})`);
313
- }
314
- if (filter.project) {
315
- conditions.push('project = ?');
316
- params.push(filter.project);
317
- }
318
- if (filter.kind) {
319
- conditions.push('kind = ?');
320
- params.push(filter.kind);
81
+ return searchOps.searchVector(this.db, vector, query);
321
82
  }
322
- if (filter.before !== undefined) {
323
- conditions.push('created_at < ?');
324
- params.push(filter.before);
83
+ async closeObservations(ids) {
84
+ return observationsOps.closeObservations(this.db, ids);
325
85
  }
326
- return {
327
- where: conditions.length > 0 ? `WHERE ${conditions.join(' AND ')}` : '',
328
- params,
329
- };
330
- }
331
- /**
332
- * Exact membership in the stored JSON array, rather than a LIKE over the raw
333
- * text, so `api` cannot match `api-docs` and a tag containing `%` is harmless.
334
- */
335
- const TAG_PREDICATE = (prefix) => `EXISTS (SELECT 1 FROM json_each(${prefix}tags) WHERE value = ?)`;
336
- function appendScope(query, conditions, params, prefix) {
337
- if (query.project) {
338
- conditions.push(`${prefix}project = ?`);
339
- params.push(query.project);
86
+ async timeline(query) {
87
+ return searchOps.timeline(this.db, query);
340
88
  }
341
- if (query.kind) {
342
- conditions.push(`${prefix}kind = ?`);
343
- params.push(query.kind);
89
+ async upsertGraph(scan) {
90
+ return graphOps.upsertGraph(this.db, scan);
344
91
  }
345
- if (query.tag) {
346
- conditions.push(TAG_PREDICATE(prefix));
347
- params.push(query.tag);
92
+ async findSymbols(filter) {
93
+ return graphOps.findSymbols(this.db, filter);
348
94
  }
349
- if (query.since !== undefined) {
350
- conditions.push(`${prefix}created_at >= ?`);
351
- params.push(query.since);
95
+ async findEdges(filter) {
96
+ return graphOps.findEdges(this.db, filter);
352
97
  }
353
- if (query.until !== undefined) {
354
- conditions.push(`${prefix}created_at <= ?`);
355
- params.push(query.until);
98
+ async scannedFiles(project) {
99
+ return graphOps.scannedFiles(this.db, project);
356
100
  }
357
- }
358
- function toFilePath(uri) {
359
- if (!uri || uri.trim() === '') {
360
- return resolve(process.env['HOME'] ?? '.', '.claude-memory/memory.db');
101
+ async removeGraph(project, files) {
102
+ return graphOps.removeGraph(this.db, project, files);
361
103
  }
362
- const stripped = uri.replace(/^(sqlite|file):\/\//, '');
363
- return resolve(stripped === '' ? './memory.db' : stripped);
364
- }
365
- /**
366
- * Builds the FTS5 MATCH expression.
367
- *
368
- * FTS5 treats punctuation as query syntax, so raw user text can throw: every
369
- * token is quoted. Terms are OR'd so recall stays forgiving and bm25 sorts out
370
- * what actually mattered, but the whole disjunction is AND'd with the project
371
- * scope token so the engine never walks other projects' postings.
372
- *
373
- * Returns null when there is nothing searchable, so the caller can skip the
374
- * query entirely rather than issue one that matches everything.
375
- */
376
- function toMatchExpression(text, project) {
377
- // ponytail: unicode61 keeps a run of Han characters as one token, so CJK
378
- // matches phrases but not substrings. Vector recall covers the gap; swap in
379
- // an ICU or bigram tokenizer if that stops being enough.
380
- const tokens = text
381
- .toLowerCase()
382
- .split(/[^\p{L}\p{N}_]+/u)
383
- .filter((token) => token.length > 1);
384
- const scope = project ? `scope:${scopeToken(project)}` : null;
385
- if (tokens.length === 0)
386
- return scope;
387
- const terms = tokens.map((token) => `"${token}"`).join(' OR ');
388
- return scope ? `${scope} AND (${terms})` : terms;
389
- }
390
- function toBuffer(value) {
391
- if (Buffer.isBuffer(value))
392
- return value;
393
- if (value instanceof Uint8Array)
394
- return Buffer.from(value);
395
- return Buffer.alloc(0);
396
- }
397
- function toSession(row) {
398
- const session = {
399
- id: row['id'],
400
- project: row['project'],
401
- startedAt: Number(row['started_at']),
402
- };
403
- if (row['ended_at'] != null)
404
- session.endedAt = Number(row['ended_at']);
405
- if (row['summary'] != null)
406
- session.summary = row['summary'];
407
- return session;
408
- }
409
- function toObservation(row) {
410
- const obs = {
411
- id: row['id'],
412
- sessionId: row['session_id'],
413
- project: row['project'],
414
- kind: row['kind'],
415
- title: row['title'],
416
- body: row['body'],
417
- files: JSON.parse(row['files'] ?? '[]'),
418
- tags: JSON.parse(row['tags'] ?? '[]'),
419
- createdAt: Number(row['created_at']),
420
- };
421
- if (row['embedding'])
422
- obs.embedding = unpackVector(toBuffer(row['embedding']));
423
- if (row['embedder'] != null)
424
- obs.embedder = row['embedder'];
425
- if (row['author'] != null)
426
- obs.author = row['author'];
427
- return obs;
428
- }
429
- function toIndexEntry(row) {
430
- const entry = {
431
- id: row['id'],
432
- kind: row['kind'],
433
- title: row['title'],
434
- project: row['project'],
435
- createdAt: Number(row['created_at']),
436
- score: Number(row['score'] ?? 0),
437
- };
438
- const snippet = toSnippet(row['snippet']);
439
- if (snippet)
440
- entry.snippet = snippet;
441
- return entry;
442
104
  }
@@ -0,0 +1,10 @@
1
+ import type { DatabaseSync } from 'node:sqlite';
2
+ import type { ListFilter, Observation, RemoveFilter } from '../../types.js';
3
+ import type { ProjectSummary } from '../adapter.js';
4
+ export declare function insertObservations(db: DatabaseSync, observations: Observation[]): Promise<void>;
5
+ export declare function getObservations(db: DatabaseSync, ids: string[]): Promise<Observation[]>;
6
+ export declare function remove(db: DatabaseSync, filter: RemoveFilter): Promise<number>;
7
+ export declare function list(db: DatabaseSync, filter: ListFilter): Promise<Observation[]>;
8
+ export declare function listProjects(db: DatabaseSync): Promise<ProjectSummary[]>;
9
+ export declare function inventory(db: DatabaseSync): Promise<string[]>;
10
+ export declare function closeObservations(db: DatabaseSync, ids: string[]): Promise<number>;
@@ -0,0 +1,128 @@
1
+ import { foreignNames, isWholeScope } from '../adapter.js';
2
+ import { toObservation } from './rows.js';
3
+ import { removeWhere } from './filters.js';
4
+ import { partitionIds } from '../../util/shortid.js';
5
+ import { packVector } from '../../util/vector.js';
6
+ import { scopeToken } from '../../util/scope.js';
7
+ export async function insertObservations(db, observations) {
8
+ if (observations.length === 0)
9
+ return;
10
+ const stmt = db.prepare(`INSERT OR REPLACE INTO observations
11
+ (id, session_id, project, scope, kind, title, body, files, tags,
12
+ created_at, embedding, embedder, author, status)
13
+ VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`);
14
+ db.exec('BEGIN');
15
+ try {
16
+ for (const obs of observations) {
17
+ 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');
18
+ }
19
+ db.exec('COMMIT');
20
+ }
21
+ catch (error) {
22
+ db.exec('ROLLBACK');
23
+ throw error;
24
+ }
25
+ }
26
+ export async function getObservations(db, ids) {
27
+ if (ids.length === 0)
28
+ return [];
29
+ const { exact, prefixes } = partitionIds(ids);
30
+ const clauses = [];
31
+ const params = [];
32
+ if (exact.length > 0) {
33
+ clauses.push(`id IN (${exact.map(() => '?').join(',')})`);
34
+ params.push(...exact);
35
+ }
36
+ for (const prefix of prefixes) {
37
+ clauses.push('id GLOB ?');
38
+ params.push(`${prefix}*`);
39
+ }
40
+ const rows = db
41
+ .prepare(`SELECT * FROM observations WHERE ${clauses.join(' OR ')}`)
42
+ .all(...params);
43
+ return rows.map(toObservation);
44
+ }
45
+ export async function remove(db, filter) {
46
+ if (filter.ids?.length === 0)
47
+ return 0;
48
+ const { where, params } = removeWhere(filter);
49
+ const wipe = isWholeScope(filter);
50
+ const count = db
51
+ .prepare(`SELECT COUNT(*) AS n FROM observations ${where}`)
52
+ .get(...params);
53
+ db.exec('BEGIN');
54
+ try {
55
+ db.prepare(`DELETE FROM observations ${where}`).run(...params);
56
+ if (wipe) {
57
+ const scope = filter.project ? 'WHERE project = ?' : '';
58
+ const scopeParams = (filter.project ? [filter.project] : []);
59
+ db.prepare(`DELETE FROM sessions ${scope}`).run(...scopeParams);
60
+ for (const table of ['symbols', 'symbol_edges', 'scanned_files']) {
61
+ db.prepare(`DELETE FROM ${table} ${scope}`).run(...scopeParams);
62
+ }
63
+ }
64
+ db.exec('COMMIT');
65
+ }
66
+ catch (error) {
67
+ db.exec('ROLLBACK');
68
+ throw error;
69
+ }
70
+ if (wipe)
71
+ db.exec('VACUUM');
72
+ return count?.n ?? 0;
73
+ }
74
+ export async function list(db, filter) {
75
+ const conditions = [];
76
+ const params = [];
77
+ if (filter.project) {
78
+ conditions.push('project = ?');
79
+ params.push(filter.project);
80
+ }
81
+ if (filter.kind) {
82
+ conditions.push('kind = ?');
83
+ params.push(filter.kind);
84
+ }
85
+ if (filter.status) {
86
+ conditions.push('status = ?');
87
+ params.push(filter.status);
88
+ }
89
+ if (filter.after !== undefined) {
90
+ conditions.push('created_at > ?');
91
+ params.push(filter.after);
92
+ }
93
+ params.push(filter.limit ?? 1000);
94
+ const rows = db
95
+ .prepare(`SELECT * FROM observations
96
+ ${conditions.length > 0 ? `WHERE ${conditions.join(' AND ')}` : ''}
97
+ ORDER BY created_at ASC LIMIT ?`)
98
+ .all(...params);
99
+ return rows.map(toObservation);
100
+ }
101
+ export async function listProjects(db) {
102
+ const rows = db
103
+ .prepare(`SELECT project, COUNT(*) AS n, MAX(created_at) AS last
104
+ FROM observations GROUP BY project ORDER BY last DESC`)
105
+ .all();
106
+ return rows.map((row) => ({
107
+ project: row['project'],
108
+ observations: Number(row['n']),
109
+ lastActive: Number(row['last']),
110
+ }));
111
+ }
112
+ export async function inventory(db) {
113
+ const rows = db
114
+ .prepare(`SELECT name FROM sqlite_master
115
+ WHERE type IN ('table', 'view') AND name NOT LIKE 'sqlite_%'`)
116
+ .all();
117
+ return foreignNames(rows.map((row) => String(row['name'] ?? '')));
118
+ }
119
+ export async function closeObservations(db, ids) {
120
+ if (ids.length === 0)
121
+ return 0;
122
+ const holes = ids.map(() => '?').join(',');
123
+ const row = db
124
+ .prepare(`SELECT COUNT(*) AS n FROM observations WHERE status = 'open' AND id IN (${holes})`)
125
+ .get(...ids);
126
+ db.prepare(`UPDATE observations SET status = 'done' WHERE id IN (${holes})`).run(...ids);
127
+ return row?.n ?? 0;
128
+ }
@@ -0,0 +1,8 @@
1
+ import type { CodeEdge, CodeSymbol, Observation, ObservationIndexEntry, Session } from '../../types.js';
2
+ export type Row = Record<string, unknown>;
3
+ export declare function toBuffer(value: unknown): Buffer;
4
+ export declare function toSession(row: Row): Session;
5
+ export declare function toObservation(row: Row): Observation;
6
+ export declare function toIndexEntry(row: Row): ObservationIndexEntry;
7
+ export declare function toSymbol(row: Row): CodeSymbol;
8
+ export declare function toEdge(row: Row): CodeEdge;