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,66 +1,27 @@
1
1
  import { toShortId } from '../util/shortid.js';
2
2
  import { clipBody } from '../util/snippet.js';
3
- /**
4
- * How the three layers are shown to the agent.
5
- *
6
- * Split out of the server so it can be exercised without opening a stdio
7
- * transport: this is the format every search result is paid in, and it had no
8
- * test of any kind while the server module could only be imported by starting
9
- * a server.
10
- */
11
- /**
12
- * Layer 1. Every character here is multiplied by the number of results and
13
- * paid on every search, so the format stays terse: short id, kind, month-day,
14
- * title, and one indented line of the body around the match.
15
- *
16
- * The snippet is the half that was missing. Terseness only pays if the row can
17
- * be chosen from what is shown, and a title often cannot carry that — fifteen
18
- * results dated the same day, titled things like "Committed as 30daa92", leave
19
- * a reader nothing to pick on, so they expand two at random and pay a full body
20
- * for each guess. Sixty characters here saves several thousand there.
21
- */
22
3
  export function renderIndex(entries) {
23
4
  if (entries.length === 0)
24
5
  return 'No matching observations.';
25
6
  const rows = entries.map((entry) => {
26
7
  const date = new Date(entry.createdAt).toISOString().slice(5, 10);
27
8
  const head = `${toShortId(entry.id)} ${entry.kind} ${date} ${entry.title}`;
28
- // Absent for a row only vector search found: it holds no query terms to
29
- // centre a fragment on. Dropped too when it only restates the title.
30
9
  const worth = entry.snippet !== undefined && !echoesTitle(entry.snippet, entry.title);
31
10
  return worth ? `${head}\n ${entry.snippet}` : head;
32
11
  });
33
12
  return `${entries.length} result(s):\n${rows.join('\n')}`;
34
13
  }
35
- /** Lowercased alphanumeric runs — the only form the two sides share. */
36
14
  function words(text) {
37
15
  return text.toLowerCase().match(/[a-z0-9]+/g) ?? [];
38
16
  }
39
- /**
40
- * True when a fragment says little the title has not already said.
41
- *
42
- * A search engine centres its window on the query match, and the title is taken
43
- * from the body, so on a short observation the two are frequently the same
44
- * sentence — the row then pays a second time for a line already shown. Observed
45
- * live: a title of "Added as section 3 of PLAN.md, with the later sections
46
- * renumbered" under a fragment reading "…Added as section 3 of [PLAN.md](PLAN.md),
47
- * with the later…".
48
- *
49
- * Compared as a bag of words rather than by substring, because that example is
50
- * exactly the case a substring test misses: the fragment comes from the raw body
51
- * and still carries the markdown the title had stripped.
52
- */
53
17
  function echoesTitle(snippet, title) {
54
18
  const tokens = words(snippet);
55
19
  if (tokens.length === 0)
56
20
  return true;
57
21
  const inTitle = new Set(words(title));
58
22
  const shared = tokens.filter((word) => inTitle.has(word)).length;
59
- // Not 1.0: the window carries the ellipses and a spill word or two from the
60
- // neighbouring sentence, so an exact echo never scores as one.
61
23
  return shared / tokens.length >= 0.7;
62
24
  }
63
- /** Layer 3. Full detail for one observation, bounded by `chars`. */
64
25
  export function renderFull(obs, chars) {
65
26
  return [
66
27
  `id: ${toShortId(obs.id)}`,
@@ -10,12 +10,11 @@ import { createContext } from '../context.js';
10
10
  import { toShortId } from '../util/shortid.js';
11
11
  import { renderFull, renderIndex } from './render.js';
12
12
  import { resolveProject } from '../util/project.js';
13
- import { findUsages, formatUsages } from '../usages/index.js';
13
+ import { findUsages, formatUsages, repoRootFor } from '../usages/index.js';
14
+ import { formatGraph, queryGraph, refreshGraph } from '../graph/index.js';
14
15
  import { silenceSqliteWarning } from '../util/warnings.js';
15
16
  silenceSqliteWarning();
16
- const KINDS = [
17
- 'decision', 'pattern', 'bugfix', 'context', 'deadend', 'preference',
18
- ];
17
+ const KINDS = ['decision', 'pattern', 'bugfix', 'context', 'deadend', 'preference'];
19
18
  function packageVersion() {
20
19
  try {
21
20
  const path = resolve(dirname(fileURLToPath(import.meta.url)), '..', '..', 'package.json');
@@ -25,16 +24,6 @@ function packageVersion() {
25
24
  return '0.0.0';
26
25
  }
27
26
  }
28
- /**
29
- * Three read tools mirroring the progressive disclosure layers, plus two that
30
- * write. Tool descriptions spell out the intended order, because the saving
31
- * only materializes if the agent filters at `search` before calling
32
- * `get_observations`.
33
- *
34
- * `remember` exists because capture is inferred from transcripts, and a rule
35
- * is not an event: "we always use pnpm here" produces no edit and no command,
36
- * so the one thing most worth keeping is the one thing never recorded.
37
- */
38
27
  const ctx = await createContext();
39
28
  const server = new McpServer({ name: 'claude-db', version: packageVersion() });
40
29
  server.tool('search', 'Layer 1. Search project memory and get a compact index of matches ' +
@@ -126,17 +115,36 @@ server.tool('get_observations', 'Layer 3. Fetch full bodies for specific observa
126
115
  const observations = await ctx.search.getObservations(ids);
127
116
  return {
128
117
  content: [
129
- { type: 'text', text: observations.map((obs) => renderFull(obs, chars)).join('\n\n---\n\n') },
118
+ {
119
+ type: 'text',
120
+ text: observations.map((obs) => renderFull(obs, chars)).join('\n\n---\n\n'),
121
+ },
130
122
  ],
131
123
  };
132
124
  });
133
- server.tool('find_usages', 'Find real usages of a symbol or component name via `git grep` — a live read ' +
134
- 'of the current source, not a stored index, so it is never stale. Returns ' +
135
- 'file:line and the matching line, with a best-effort [definition?] marker on ' +
136
- 'lines that look like a declaration. Use this before editing or removing a ' +
137
- 'shared or exported name, or to answer "what uses this" (structure). Use ' +
138
- '`search` instead for "why is this the way it is" (history).', {
139
- symbol: z.string().min(1).max(200).describe('Exact name to search for, e.g. "useAuth" or "CartButton"'),
125
+ server.tool('find_usages', 'Find real usages of a symbol, and how the code around it connects. ' +
126
+ '`mode: "text"` (default) is a live `git grep` — never stale, works with no ' +
127
+ 'setup, and returns file:line with a best-effort [definition?] marker. The ' +
128
+ 'other modes read the code graph built by `claude-db scan`, which knows a ' +
129
+ 'call from an import from an inherit: "usages" lists what references the ' +
130
+ 'symbol with the relation on each line, "explain" adds what the symbol ' +
131
+ 'reaches, and "path" traces how two symbols connect (pass the second as ' +
132
+ '`target`). Graph answers re-parse anything that changed before replying, ' +
133
+ 'so they cannot report a line the source has moved past. Every edge is ' +
134
+ 'tagged EXTRACTED (read literally from the syntax) or INFERRED (matched by ' +
135
+ 'name across files, with a score). Use `search` instead for "why is this ' +
136
+ 'the way it is" (history).', {
137
+ symbol: z
138
+ .string()
139
+ .min(1)
140
+ .max(200)
141
+ .describe('Exact name to search for, e.g. "useAuth" or "CartButton"'),
142
+ mode: z
143
+ .enum(['text', 'usages', 'explain', 'path'])
144
+ .default('text')
145
+ .describe('How to answer. "text" greps live and needs no scan; the rest query the ' +
146
+ 'stored graph and return nothing useful until `claude-db scan` has run'),
147
+ target: z.string().optional().describe('The second symbol, for mode "path" only'),
140
148
  path: z
141
149
  .string()
142
150
  .optional()
@@ -163,9 +171,22 @@ server.tool('find_usages', 'Find real usages of a symbol or component name via `
163
171
  .max(500)
164
172
  .default(100)
165
173
  .describe('Cap on matching lines returned; the result says how many more exist'),
166
- }, async ({ symbol, path, regex, context, limit }) => {
167
- const result = findUsages({ symbol, regex, context, limit, ...(path ? { path } : {}) });
168
- return { content: [{ type: 'text', text: formatUsages(result) }] };
174
+ }, async ({ symbol, mode, target, path, regex, context, limit }) => {
175
+ if (mode === 'text') {
176
+ const result = findUsages({ symbol, regex, context, limit, ...(path ? { path } : {}) });
177
+ return { content: [{ type: 'text', text: formatUsages(result) }] };
178
+ }
179
+ const root = repoRootFor(path ?? process.cwd());
180
+ const project = resolveProject(undefined);
181
+ const refreshed = await refreshGraph(ctx.store, root, project);
182
+ const answer = await queryGraph(ctx.store, project, {
183
+ mode,
184
+ symbol,
185
+ ...(target ? { target } : {}),
186
+ limit,
187
+ });
188
+ answer.refreshed = refreshed;
189
+ return { content: [{ type: 'text', text: formatGraph(answer, root) }] };
169
190
  });
170
191
  const transport = new StdioServerTransport();
171
192
  await server.connect(transport);
@@ -1,17 +1,3 @@
1
1
  import type { ObservationIndexEntry } from '../types.js';
2
- /**
3
- * Reciprocal Rank Fusion.
4
- *
5
- * Keyword scores (BM25, ts_rank) and vector scores (cosine) live on
6
- * incompatible scales, so normalizing them against each other is guesswork.
7
- * RRF sidesteps that by discarding magnitudes and fusing on rank position
8
- * alone: an item ranked 1st by either retriever scores 1/(k+1) from it.
9
- * That makes the blend robust with no per-backend tuning.
10
- */
11
2
  export declare function fuse(rankings: ObservationIndexEntry[][], limit: number): ObservationIndexEntry[];
12
- /**
13
- * Mild recency preference applied after fusion. Memory about a codebase decays
14
- * in usefulness: a decision from last week usually beats one from last year.
15
- * Half-life is deliberately long so old-but-relevant results still surface.
16
- */
17
3
  export declare function applyRecencyBoost(entries: ObservationIndexEntry[], now: number, halfLifeDays?: number): ObservationIndexEntry[];
@@ -1,14 +1,4 @@
1
- /** Damping constant from the original RRF paper. */
2
1
  const RRF_K = 60;
3
- /**
4
- * Reciprocal Rank Fusion.
5
- *
6
- * Keyword scores (BM25, ts_rank) and vector scores (cosine) live on
7
- * incompatible scales, so normalizing them against each other is guesswork.
8
- * RRF sidesteps that by discarding magnitudes and fusing on rank position
9
- * alone: an item ranked 1st by either retriever scores 1/(k+1) from it.
10
- * That makes the blend robust with no per-backend tuning.
11
- */
12
2
  export function fuse(rankings, limit) {
13
3
  const scores = new Map();
14
4
  const entries = new Map();
@@ -25,18 +15,12 @@ export function fuse(rankings, limit) {
25
15
  .slice(0, limit)
26
16
  .map(([id, score]) => ({ ...entries.get(id), score }));
27
17
  }
28
- /**
29
- * Mild recency preference applied after fusion. Memory about a codebase decays
30
- * in usefulness: a decision from last week usually beats one from last year.
31
- * Half-life is deliberately long so old-but-relevant results still surface.
32
- */
33
18
  export function applyRecencyBoost(entries, now, halfLifeDays = 45) {
34
19
  const halfLifeMs = halfLifeDays * 24 * 60 * 60 * 1000;
35
20
  return entries
36
21
  .map((entry) => {
37
22
  const age = Math.max(0, now - entry.createdAt);
38
23
  const decay = Math.pow(0.5, age / halfLifeMs);
39
- // Floor at 0.7 so recency nudges ordering without overpowering relevance.
40
24
  return { ...entry, score: entry.score * (0.7 + 0.3 * decay) };
41
25
  })
42
26
  .sort((a, b) => b.score - a.score);
@@ -1,44 +1,13 @@
1
1
  import type { Embedder } from '../embed/index.js';
2
2
  import type { MemoryStore } from '../store/adapter.js';
3
3
  import type { Observation, ObservationIndexEntry, SearchQuery, TimelineQuery } from '../types.js';
4
- /**
5
- * Three-layer progressive disclosure.
6
- *
7
- * Naive memory search returns whole records and burns thousands of tokens on
8
- * results the agent discards. Here retrieval is split so the agent pays for
9
- * detail only once it has decided what is relevant:
10
- *
11
- * 1. search() compact index, roughly 50-100 tokens per hit
12
- * 2. timeline() chronological neighbours of a promising hit
13
- * 3. getObservations() full bodies, for a hand-picked set of ids
14
- *
15
- * Filtering at layer 1 and expanding at layer 3 is where the ~10x saving comes
16
- * from versus returning full records up front.
17
- */
18
4
  export declare class SearchService {
19
5
  private readonly store;
20
- /** Lazily resolved: search must not force model construction. */
21
6
  private readonly embedder;
22
- /** Ceiling for brute-force vector scans on backends without an index. */
23
7
  private readonly maxScanCandidates;
24
- constructor(store: MemoryStore,
25
- /** Lazily resolved: search must not force model construction. */
26
- embedder: Embedder | (() => Promise<Embedder>),
27
- /** Ceiling for brute-force vector scans on backends without an index. */
28
- maxScanCandidates?: number);
29
- /** Layer 1. Hybrid keyword + vector retrieval, fused by rank. */
8
+ constructor(store: MemoryStore, embedder: Embedder | (() => Promise<Embedder>), maxScanCandidates?: number);
30
9
  search(query: SearchQuery): Promise<ObservationIndexEntry[]>;
31
- /**
32
- * Vector retrieval, isolated so its failure modes cannot take down search.
33
- *
34
- * The embedding model may be absent, still downloading, or unsupported by
35
- * the backend. In every one of those cases the correct behaviour is to
36
- * return no vector candidates and let keyword results stand, never to throw:
37
- * degraded recall beats no recall.
38
- */
39
10
  private vectorSearch;
40
- /** Layer 2. What was happening around a given observation. */
41
11
  timeline(query: TimelineQuery): Promise<ObservationIndexEntry[]>;
42
- /** Layer 3. Full detail, only for ids the caller already filtered down to. */
43
12
  getObservations(ids: string[]): Promise<Observation[]>;
44
13
  }
@@ -1,34 +1,14 @@
1
1
  import { applyRecencyBoost, fuse } from './rank.js';
2
- /**
3
- * Three-layer progressive disclosure.
4
- *
5
- * Naive memory search returns whole records and burns thousands of tokens on
6
- * results the agent discards. Here retrieval is split so the agent pays for
7
- * detail only once it has decided what is relevant:
8
- *
9
- * 1. search() compact index, roughly 50-100 tokens per hit
10
- * 2. timeline() chronological neighbours of a promising hit
11
- * 3. getObservations() full bodies, for a hand-picked set of ids
12
- *
13
- * Filtering at layer 1 and expanding at layer 3 is where the ~10x saving comes
14
- * from versus returning full records up front.
15
- */
16
2
  export class SearchService {
17
3
  store;
18
4
  embedder;
19
5
  maxScanCandidates;
20
- constructor(store,
21
- /** Lazily resolved: search must not force model construction. */
22
- embedder,
23
- /** Ceiling for brute-force vector scans on backends without an index. */
24
- maxScanCandidates = 25000) {
6
+ constructor(store, embedder, maxScanCandidates = 25000) {
25
7
  this.store = store;
26
8
  this.embedder = embedder;
27
9
  this.maxScanCandidates = maxScanCandidates;
28
10
  }
29
- /** Layer 1. Hybrid keyword + vector retrieval, fused by rank. */
30
11
  async search(query) {
31
- // Over-fetch from each retriever so fusion has room to disagree.
32
12
  const wide = {
33
13
  ...query,
34
14
  limit: query.limit * 3,
@@ -39,14 +19,6 @@ export class SearchService {
39
19
  const fused = fuse([keyword, vector].filter((r) => r.length > 0), query.limit);
40
20
  return applyRecencyBoost(fused, Date.now());
41
21
  }
42
- /**
43
- * Vector retrieval, isolated so its failure modes cannot take down search.
44
- *
45
- * The embedding model may be absent, still downloading, or unsupported by
46
- * the backend. In every one of those cases the correct behaviour is to
47
- * return no vector candidates and let keyword results stand, never to throw:
48
- * degraded recall beats no recall.
49
- */
50
22
  async vectorSearch(query) {
51
23
  try {
52
24
  const embedder = typeof this.embedder === 'function' ? await this.embedder() : this.embedder;
@@ -59,22 +31,15 @@ export class SearchService {
59
31
  ...query,
60
32
  embedder: embedder.id,
61
33
  });
62
- // Nearest-neighbour search always returns its top k, however poor the
63
- // match. Without a floor, an unrelated prompt still yields results, and
64
- // injecting those trains the reader to ignore memory entirely. Dropping
65
- // them here rather than after fusion keeps weak candidates from
66
- // borrowing rank credibility from the keyword list.
67
34
  return candidates.filter((entry) => entry.score >= embedder.minRelevance);
68
35
  }
69
36
  catch {
70
37
  return [];
71
38
  }
72
39
  }
73
- /** Layer 2. What was happening around a given observation. */
74
40
  async timeline(query) {
75
41
  return this.store.timeline(query);
76
42
  }
77
- /** Layer 3. Full detail, only for ids the caller already filtered down to. */
78
43
  async getObservations(ids) {
79
44
  return this.store.getObservations(ids);
80
45
  }
@@ -1,73 +1,40 @@
1
- import type { ListFilter, Observation, ObservationIndexEntry, RemoveFilter, SearchQuery, Session, TimelineQuery } from '../types.js';
1
+ import type { CodeEdge, CodeSymbol, EdgeFilter, ListFilter, Observation, ObservationIndexEntry, RemoveFilter, ScannedFile, SearchQuery, Session, SymbolFilter, TimelineQuery } from '../types.js';
2
2
  export interface ProjectSummary {
3
3
  project: string;
4
4
  observations: number;
5
5
  lastActive: number;
6
6
  }
7
- /**
8
- * The contract every database backend implements.
9
- *
10
- * Adapters own persistence only. Ranking, fusion and token budgeting live in
11
- * src/search so they stay identical no matter which database is plugged in.
12
- * An adapter that cannot do vectors returns [] from `searchVector`; the search
13
- * service degrades to keyword-only rather than failing.
14
- */
15
7
  export interface MemoryStore {
16
8
  readonly kind: string;
17
- /** Create collections/tables and indexes. Must be idempotent. */
18
9
  init(): Promise<void>;
19
10
  close(): Promise<void>;
20
- /** Cheap liveness probe used by `claude-db doctor`. */
21
11
  ping(): Promise<boolean>;
22
12
  upsertSession(session: Session): Promise<void>;
23
13
  getSession(id: string): Promise<Session | null>;
24
14
  recentSessions(project: string, limit: number): Promise<Session[]>;
25
15
  insertObservations(observations: Observation[]): Promise<void>;
26
16
  getObservations(ids: string[]): Promise<Observation[]>;
27
- /**
28
- * Deletes memory matching a filter, returning how many observations went.
29
- *
30
- * One method rather than three because `reset`, `prune` and `forget` differ
31
- * only in how they narrow. Belongs on the adapter rather than being handled
32
- * by deleting a file, because on a shared Postgres or Mongo there is none.
33
- *
34
- * Sessions are removed only for a whole-project or whole-database wipe; a
35
- * pruned or forgotten observation leaves its session intact.
36
- */
37
17
  remove(filter: RemoveFilter): Promise<number>;
38
- /**
39
- * Bulk read, oldest first, for export, re-embedding and statistics. Paged by
40
- * `after` + `limit` so a large database is never held in memory at once.
41
- */
42
18
  list(filter: ListFilter): Promise<Observation[]>;
43
- /** Every project with memory in this database, most recently active first. */
44
19
  listProjects(): Promise<ProjectSummary[]>;
45
- /**
46
- * Tables or collections in this database that belong to somebody else.
47
- *
48
- * Called by `use` before `init()` creates ours, because afterwards there is
49
- * no way to tell an empty memory database from an application database we
50
- * just added two tables to. One `use` in anger pointed at a live e-commerce
51
- * database and nothing said a word.
52
- */
53
20
  inventory(): Promise<string[]>;
54
- /** Lexical match. Returns scores on an adapter-defined scale. */
55
21
  searchKeyword(query: SearchQuery): Promise<ObservationIndexEntry[]>;
56
- /** Vector match. Return [] when the backend has no vector support. */
57
22
  searchVector(vector: number[], query: SearchQuery): Promise<ObservationIndexEntry[]>;
58
23
  timeline(query: TimelineQuery): Promise<ObservationIndexEntry[]>;
24
+ closeObservations(ids: string[]): Promise<number>;
25
+ upsertGraph(scan: {
26
+ symbols: CodeSymbol[];
27
+ edges: CodeEdge[];
28
+ files: ScannedFile[];
29
+ }): Promise<void>;
30
+ findSymbols(filter: SymbolFilter): Promise<CodeSymbol[]>;
31
+ findEdges(filter: EdgeFilter): Promise<CodeEdge[]>;
32
+ scannedFiles(project: string): Promise<ScannedFile[]>;
33
+ removeGraph(project: string, files?: string[]): Promise<number>;
59
34
  }
60
- /**
61
- * True when a filter names a whole project, or the whole database.
62
- *
63
- * Sessions follow their observations only in that case: pruning by date or
64
- * forgetting one row must leave the session record alone, or the recap at
65
- * SessionStart loses sessions whose work is still there.
66
- */
67
35
  export declare function isWholeScope(filter: RemoveFilter): boolean;
68
36
  export declare function foreignNames(names: string[]): string[];
69
37
  export interface StoreFactory {
70
- /** Lowercase URI schemes this factory claims, e.g. ['mongodb','mongodb+srv']. */
71
38
  schemes: string[];
72
39
  create(uri: string): Promise<MemoryStore>;
73
40
  }
@@ -1,18 +1,7 @@
1
- /**
2
- * True when a filter names a whole project, or the whole database.
3
- *
4
- * Sessions follow their observations only in that case: pruning by date or
5
- * forgetting one row must leave the session record alone, or the recap at
6
- * SessionStart loses sessions whose work is still there.
7
- */
8
1
  export function isWholeScope(filter) {
9
2
  return !filter.ids && !filter.kind && filter.before === undefined;
10
3
  }
11
- /**
12
- * Ours, on any backend: the two tables, SQLite's FTS shadow tables, and the
13
- * Postgres schema-version row.
14
- */
15
- const OURS = /^(claude_db_meta|sessions|observations)(_fts(_\w+)?)?$/;
4
+ const OURS = /^(claude_db_meta|sessions|observations|symbols|symbol_edges|scanned_files)(_fts(_\w+)?)?$/;
16
5
  export function foreignNames(names) {
17
6
  return names.filter((name) => name.length > 0 && !OURS.test(name));
18
7
  }
@@ -1,14 +1,3 @@
1
1
  import type { MemoryStore } from './adapter.js';
2
2
  export type { MemoryStore, StoreFactory } from './adapter.js';
3
- /**
4
- * Resolve a store from a connection URI. The scheme alone decides the backend,
5
- * so users configure one variable and never name an adapter explicitly.
6
- *
7
- * mongodb://... | mongodb+srv://... -> MongoDB
8
- * postgres://... | postgresql://... -> Postgres + pgvector
9
- * sqlite:///abs/path | ./file.db -> SQLite (default)
10
- *
11
- * Adapters are imported lazily so a user on Mongo never loads the Postgres
12
- * driver, and a missing optional dependency surfaces as a clear message.
13
- */
14
3
  export declare function createStore(uri: string): Promise<MemoryStore>;
@@ -1,14 +1,3 @@
1
- /**
2
- * Resolve a store from a connection URI. The scheme alone decides the backend,
3
- * so users configure one variable and never name an adapter explicitly.
4
- *
5
- * mongodb://... | mongodb+srv://... -> MongoDB
6
- * postgres://... | postgresql://... -> Postgres + pgvector
7
- * sqlite:///abs/path | ./file.db -> SQLite (default)
8
- *
9
- * Adapters are imported lazily so a user on Mongo never loads the Postgres
10
- * driver, and a missing optional dependency surfaces as a clear message.
11
- */
12
1
  export async function createStore(uri) {
13
2
  const scheme = parseScheme(uri);
14
3
  switch (scheme) {
@@ -0,0 +1,61 @@
1
+ import type { CodeEdge, CodeSymbol, Observation, ObservationIndexEntry, ObservationKind, Session } from '../../types.js';
2
+ import type { Doc } from './driver.js';
3
+ export interface SessionDoc extends Doc {
4
+ _id: string;
5
+ project: string;
6
+ startedAt: number;
7
+ endedAt?: number;
8
+ summary?: string;
9
+ }
10
+ export interface ObservationDoc extends Doc {
11
+ _id: string;
12
+ sessionId: string;
13
+ project: string;
14
+ kind: ObservationKind;
15
+ title: string;
16
+ body: string;
17
+ files: string[];
18
+ tags: string[];
19
+ createdAt: number;
20
+ embedding?: number[];
21
+ embedder?: string;
22
+ author?: string;
23
+ status?: Observation['status'];
24
+ }
25
+ export interface SymbolDoc extends Doc {
26
+ _id: string;
27
+ project: string;
28
+ name: string;
29
+ kind: CodeSymbol['kind'];
30
+ file: string;
31
+ line: number;
32
+ lang: string;
33
+ signature: string;
34
+ }
35
+ export interface EdgeDoc extends Doc {
36
+ _id: string;
37
+ project: string;
38
+ srcId: string;
39
+ srcName: string;
40
+ dstId: string;
41
+ dstName: string;
42
+ relation: CodeEdge['relation'];
43
+ confidence: CodeEdge['confidence'];
44
+ score: number;
45
+ file: string;
46
+ line: number;
47
+ }
48
+ export interface ScannedFileDoc extends Doc {
49
+ _id: string;
50
+ project: string;
51
+ path: string;
52
+ hash: string;
53
+ scannedAt: number;
54
+ }
55
+ export declare function upsertsOf<T extends object>(rows: T[], idOf: (row: T) => string): Doc[];
56
+ export declare function toSession(doc: SessionDoc): Session;
57
+ export declare function toDoc(obs: Observation): ObservationDoc;
58
+ export declare function toObservation(doc: ObservationDoc): Observation;
59
+ export declare function toIndexEntry(doc: Partial<ObservationDoc>, score: number): ObservationIndexEntry;
60
+ export declare function toSymbol(doc: SymbolDoc): CodeSymbol;
61
+ export declare function toEdge(doc: EdgeDoc): CodeEdge;
@@ -0,0 +1,106 @@
1
+ import { toSnippet } from '../../util/snippet.js';
2
+ export function upsertsOf(rows, idOf) {
3
+ return rows.map((row) => {
4
+ const replacement = { ...row, _id: idOf(row) };
5
+ delete replacement['id'];
6
+ return {
7
+ replaceOne: { filter: { _id: idOf(row) }, replacement, upsert: true },
8
+ };
9
+ });
10
+ }
11
+ export function toSession(doc) {
12
+ const session = {
13
+ id: doc._id,
14
+ project: doc.project,
15
+ startedAt: doc.startedAt,
16
+ };
17
+ if (doc.endedAt !== undefined)
18
+ session.endedAt = doc.endedAt;
19
+ if (doc.summary !== undefined)
20
+ session.summary = doc.summary;
21
+ return session;
22
+ }
23
+ export function toDoc(obs) {
24
+ const doc = {
25
+ _id: obs.id,
26
+ sessionId: obs.sessionId,
27
+ project: obs.project,
28
+ kind: obs.kind,
29
+ title: obs.title,
30
+ body: obs.body,
31
+ files: obs.files,
32
+ tags: obs.tags,
33
+ createdAt: obs.createdAt,
34
+ };
35
+ if (obs.embedding)
36
+ doc.embedding = obs.embedding;
37
+ if (obs.embedder)
38
+ doc.embedder = obs.embedder;
39
+ if (obs.author)
40
+ doc.author = obs.author;
41
+ doc.status = obs.status ?? 'done';
42
+ return doc;
43
+ }
44
+ export function toObservation(doc) {
45
+ const obs = {
46
+ id: doc._id,
47
+ sessionId: doc.sessionId,
48
+ project: doc.project,
49
+ kind: doc.kind,
50
+ title: doc.title,
51
+ body: doc.body,
52
+ files: doc.files ?? [],
53
+ tags: doc.tags ?? [],
54
+ createdAt: doc.createdAt,
55
+ };
56
+ if (doc.embedding)
57
+ obs.embedding = doc.embedding;
58
+ if (doc.embedder)
59
+ obs.embedder = doc.embedder;
60
+ if (doc.author)
61
+ obs.author = doc.author;
62
+ if (doc.status)
63
+ obs.status = doc.status;
64
+ return obs;
65
+ }
66
+ export function toIndexEntry(doc, score) {
67
+ const entry = {
68
+ id: doc._id,
69
+ kind: doc.kind,
70
+ title: doc.title,
71
+ project: doc.project,
72
+ createdAt: doc.createdAt,
73
+ score,
74
+ };
75
+ const snippet = toSnippet(doc.snippet);
76
+ if (snippet)
77
+ entry.snippet = snippet;
78
+ return entry;
79
+ }
80
+ export function toSymbol(doc) {
81
+ return {
82
+ id: doc._id,
83
+ project: doc.project,
84
+ name: doc.name,
85
+ kind: doc.kind,
86
+ file: doc.file,
87
+ line: doc.line,
88
+ lang: doc.lang,
89
+ signature: doc.signature ?? '',
90
+ };
91
+ }
92
+ export function toEdge(doc) {
93
+ return {
94
+ id: doc._id,
95
+ project: doc.project,
96
+ srcId: doc.srcId,
97
+ srcName: doc.srcName,
98
+ dstId: doc.dstId ?? '',
99
+ dstName: doc.dstName,
100
+ relation: doc.relation,
101
+ confidence: doc.confidence,
102
+ score: doc.score ?? 1,
103
+ file: doc.file,
104
+ line: doc.line,
105
+ };
106
+ }