claude-db 0.2.3 → 0.4.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.
@@ -33,6 +33,28 @@ export function instructionsPathFor(scope, project) {
33
33
  ? join(project, 'CLAUDE.local.md')
34
34
  : join(homedir(), '.claude', 'CLAUDE.md');
35
35
  }
36
+ /**
37
+ * Where the `/cdb-scan` skill is installed.
38
+ *
39
+ * A skill rather than a CLI command: surveying a codebase means reading it, and
40
+ * the agent is already sitting in the repo with the tools to do that. A command
41
+ * would need its own model, its own key and its own opinion about what matters.
42
+ */
43
+ export function skillPathFor(scope, project) {
44
+ const root = scope === 'project' ? join(project, '.claude') : join(homedir(), '.claude');
45
+ return join(root, 'skills', 'cdb-scan', 'SKILL.md');
46
+ }
47
+ function writeSkill(distDir, scope, project) {
48
+ const source = resolve(distDir, '..', 'skills', 'cdb-scan', 'SKILL.md');
49
+ const body = readText(source);
50
+ // Absent only in a partial checkout; the rest of the install still stands.
51
+ if (body.length > 0)
52
+ writeAtomic(skillPathFor(scope, project), body);
53
+ }
54
+ function removeSkill(scope, project) {
55
+ const path = skillPathFor(scope, project);
56
+ rmSync(dirname(path), { recursive: true, force: true });
57
+ }
36
58
  const BLOCK_START = '<!-- claude-db:start -->';
37
59
  const BLOCK_END = '<!-- claude-db:end -->';
38
60
  const INSTRUCTIONS = [
@@ -52,6 +74,13 @@ const INSTRUCTIONS = [
52
74
  'Verifying against the code afterwards is right — memory records what was',
53
75
  'done, the source shows what is. Starting there is what wastes the memory.',
54
76
  '',
77
+ '`search` covers *why*: past decisions, bugs, reasoning. It does not know',
78
+ '*where* something is used right now — for that, call `find_usages` instead',
79
+ 'of grepping yourself, specifically before editing or removing a shared or',
80
+ 'exported name, and when asked what uses something. It re-derives the answer',
81
+ 'from the current source on every call, so it is never stale. Plain-text or',
82
+ 'log searching is still a job for grep.',
83
+ '',
55
84
  'When the user states a standing rule or preference, record it with',
56
85
  '`remember` so it survives this session.',
57
86
  BLOCK_END,
@@ -165,6 +194,7 @@ export function install(distDir, scope, project) {
165
194
  writeJson(path, settings);
166
195
  const server = resolve(distDir, 'mcp', 'server.js');
167
196
  writeInstructions(instructionsPathFor(scope, project));
197
+ writeSkill(distDir, scope, project);
168
198
  // A global install lands in ~/.claude.json, which holds all of Claude Code's
169
199
  // own state. Let its CLI own that file rather than round-tripping megabytes
170
200
  // of someone else's config through JSON.parse to add one key. The direct
@@ -225,6 +255,7 @@ export function uninstall(distDir, scope, project) {
225
255
  delete settings['hooks'];
226
256
  writeJson(path, settings);
227
257
  removeInstructions(instructionsPathFor(scope, project));
258
+ removeSkill(scope, project);
228
259
  // Symmetric with install: if the CLI put it there, the CLI takes it out.
229
260
  if (scope === 'global' && claudeMcp(['mcp', 'remove', 'memory', '-s', 'user'])) {
230
261
  return path;
@@ -0,0 +1,23 @@
1
+ import type { Observation, ObservationIndexEntry } from '../types.js';
2
+ /**
3
+ * How the three layers are shown to the agent.
4
+ *
5
+ * Split out of the server so it can be exercised without opening a stdio
6
+ * transport: this is the format every search result is paid in, and it had no
7
+ * test of any kind while the server module could only be imported by starting
8
+ * a server.
9
+ */
10
+ /**
11
+ * Layer 1. Every character here is multiplied by the number of results and
12
+ * paid on every search, so the format stays terse: short id, kind, month-day,
13
+ * title, and one indented line of the body around the match.
14
+ *
15
+ * The snippet is the half that was missing. Terseness only pays if the row can
16
+ * be chosen from what is shown, and a title often cannot carry that — fifteen
17
+ * results dated the same day, titled things like "Committed as 30daa92", leave
18
+ * a reader nothing to pick on, so they expand two at random and pay a full body
19
+ * for each guess. Sixty characters here saves several thousand there.
20
+ */
21
+ export declare function renderIndex(entries: ObservationIndexEntry[]): string;
22
+ /** Layer 3. Full detail for one observation, bounded by `chars`. */
23
+ export declare function renderFull(obs: Observation, chars: number): string;
@@ -0,0 +1,78 @@
1
+ import { toShortId } from '../util/shortid.js';
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
+ export function renderIndex(entries) {
23
+ if (entries.length === 0)
24
+ return 'No matching observations.';
25
+ const rows = entries.map((entry) => {
26
+ const date = new Date(entry.createdAt).toISOString().slice(5, 10);
27
+ 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
+ const worth = entry.snippet !== undefined && !echoesTitle(entry.snippet, entry.title);
31
+ return worth ? `${head}\n ${entry.snippet}` : head;
32
+ });
33
+ return `${entries.length} result(s):\n${rows.join('\n')}`;
34
+ }
35
+ /** Lowercased alphanumeric runs — the only form the two sides share. */
36
+ function words(text) {
37
+ return text.toLowerCase().match(/[a-z0-9]+/g) ?? [];
38
+ }
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
+ function echoesTitle(snippet, title) {
54
+ const tokens = words(snippet);
55
+ if (tokens.length === 0)
56
+ return true;
57
+ const inTitle = new Set(words(title));
58
+ 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
+ return shared / tokens.length >= 0.7;
62
+ }
63
+ /** Layer 3. Full detail for one observation, bounded by `chars`. */
64
+ export function renderFull(obs, chars) {
65
+ return [
66
+ `id: ${toShortId(obs.id)}`,
67
+ `kind: ${obs.kind}`,
68
+ `when: ${new Date(obs.createdAt).toISOString()}`,
69
+ obs.author ? `who: ${obs.author}` : null,
70
+ obs.files.length > 0 ? `files: ${obs.files.join(', ')}` : null,
71
+ '',
72
+ obs.title,
73
+ '',
74
+ clipBody(obs.body, chars),
75
+ ]
76
+ .filter((line) => line !== null)
77
+ .join('\n');
78
+ }
@@ -1,8 +1,2 @@
1
1
  #!/usr/bin/env node
2
- import type { ObservationIndexEntry } from '../types.js';
3
- /**
4
- * Layer 1 rendering. Every character here is multiplied by the number of
5
- * results and paid on every search, so the format is deliberately terse:
6
- * short id, kind, month-day, title. No padding, no separators, no year.
7
- */
8
- export declare function renderIndex(entries: ObservationIndexEntry[]): string;
2
+ export {};
@@ -8,7 +8,9 @@ import { z } from 'zod';
8
8
  import { remember } from '../capture/index.js';
9
9
  import { createContext } from '../context.js';
10
10
  import { toShortId } from '../util/shortid.js';
11
+ import { renderFull, renderIndex } from './render.js';
11
12
  import { resolveProject } from '../util/project.js';
13
+ import { findUsages, formatUsages } from '../usages/index.js';
12
14
  import { silenceSqliteWarning } from '../util/warnings.js';
13
15
  silenceSqliteWarning();
14
16
  const KINDS = [
@@ -36,21 +38,28 @@ function packageVersion() {
36
38
  const ctx = await createContext();
37
39
  const server = new McpServer({ name: 'claude-db', version: packageVersion() });
38
40
  server.tool('search', 'Layer 1. Search project memory and get a compact index of matches ' +
39
- '(id, kind, title, date) without bodies. Start here, then fetch details ' +
40
- 'for only the ids that look relevant.', {
41
+ '(id, kind, date, title, and a line of the matching body) without full ' +
42
+ 'bodies. Start here, and use the snippet to decide which ids are worth ' +
43
+ 'passing to get_observations rather than expanding on the title alone.', {
41
44
  query: z.string().describe('Natural language description of what you need'),
42
45
  project: z
43
46
  .string()
44
47
  .optional()
45
48
  .describe('Absolute project path; defaults to cwd. Pass "*" to search every project'),
46
49
  kind: z.enum(KINDS).optional(),
50
+ tag: z
51
+ .string()
52
+ .optional()
53
+ .describe('Limit to one repository or top-level directory, e.g. "backend". Useful ' +
54
+ 'when a workspace pools several repos under one project'),
47
55
  limit: z.number().int().min(1).max(50).default(10),
48
- }, async ({ query, project, kind, limit }) => {
56
+ }, async ({ query, project, kind, tag, limit }) => {
49
57
  const entries = await ctx.search.search({
50
58
  text: query,
51
59
  limit,
52
60
  ...(project === '*' ? {} : { project: resolveProject(project) }),
53
61
  ...(kind ? { kind } : {}),
62
+ ...(tag ? { tag } : {}),
54
63
  });
55
64
  return { content: [{ type: 'text', text: renderIndex(entries) }] };
56
65
  });
@@ -61,11 +70,19 @@ server.tool('remember', 'Record something the user stated outright that no trans
61
70
  text: z.string().describe('What to remember, in full. First line becomes the title'),
62
71
  kind: z.enum(KINDS).default('preference'),
63
72
  project: z.string().optional().describe('Absolute project path; defaults to cwd'),
64
- }, async ({ text, kind, project }) => {
73
+ key: z
74
+ .string()
75
+ .optional()
76
+ .describe('Stable name for a note meant to be kept current, e.g. "profile:stack". ' +
77
+ 'Remembering the same key again replaces it instead of adding a duplicate'),
78
+ tags: z.array(z.string()).max(5).optional().describe('Extra tags for filtering'),
79
+ }, async ({ text, kind, project, key, tags }) => {
65
80
  const observation = await remember(ctx, {
66
81
  project: resolveProject(project),
67
82
  text,
68
83
  kind,
84
+ ...(key ? { key } : {}),
85
+ ...(tags ? { tags } : {}),
69
86
  });
70
87
  return {
71
88
  content: [
@@ -94,40 +111,60 @@ server.tool('timeline', 'Layer 2. Show what happened immediately before and afte
94
111
  });
95
112
  server.tool('get_observations', 'Layer 3. Fetch full bodies for specific observation ids, using the short ' +
96
113
  'ids returned by search. Always batch every id you need into one call ' +
97
- 'rather than calling repeatedly.', { ids: z.array(z.string()).min(1).max(25) }, async ({ ids }) => {
114
+ 'rather than calling repeatedly.', {
115
+ ids: z.array(z.string()).min(1).max(25),
116
+ chars: z
117
+ .number()
118
+ .int()
119
+ .min(200)
120
+ .max(20000)
121
+ .default(2000)
122
+ .describe('Characters of each body to return. Bodies run to 4000 and this call ' +
123
+ 'takes 25 ids, so the default keeps a batch readable; raise it when a ' +
124
+ 'truncated answer says there is more'),
125
+ }, async ({ ids, chars }) => {
98
126
  const observations = await ctx.search.getObservations(ids);
99
- return { content: [{ type: 'text', text: observations.map(renderFull).join('\n\n---\n\n') }] };
127
+ return {
128
+ content: [
129
+ { type: 'text', text: observations.map((obs) => renderFull(obs, chars)).join('\n\n---\n\n') },
130
+ ],
131
+ };
132
+ });
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"'),
140
+ path: z
141
+ .string()
142
+ .optional()
143
+ .describe('Directory inside the repo to search from; defaults to cwd. Must be inside ' +
144
+ 'a git working tree. Different from the memory tools’ project param, which ' +
145
+ 'can point at a folder pooling several repos rather than being one itself'),
146
+ regex: z
147
+ .boolean()
148
+ .default(false)
149
+ .describe('Treat symbol as an extended regular expression instead of a literal name'),
150
+ context: z
151
+ .number()
152
+ .int()
153
+ .min(0)
154
+ .max(10)
155
+ .default(0)
156
+ .describe('Lines of surrounding context before/after each match'),
157
+ limit: z
158
+ .number()
159
+ .int()
160
+ .min(1)
161
+ .max(500)
162
+ .default(100)
163
+ .describe('Cap on matching lines returned; the result says how many more exist'),
164
+ }, async ({ symbol, path, regex, context, limit }) => {
165
+ const result = findUsages({ symbol, regex, context, limit, ...(path ? { path } : {}) });
166
+ return { content: [{ type: 'text', text: formatUsages(result) }] };
100
167
  });
101
- /**
102
- * Layer 1 rendering. Every character here is multiplied by the number of
103
- * results and paid on every search, so the format is deliberately terse:
104
- * short id, kind, month-day, title. No padding, no separators, no year.
105
- */
106
- export function renderIndex(entries) {
107
- if (entries.length === 0)
108
- return 'No matching observations.';
109
- const rows = entries.map((entry) => {
110
- const date = new Date(entry.createdAt).toISOString().slice(5, 10);
111
- return `${toShortId(entry.id)} ${entry.kind} ${date} ${entry.title}`;
112
- });
113
- return `${entries.length} result(s):\n${rows.join('\n')}`;
114
- }
115
- function renderFull(obs) {
116
- const date = new Date(obs.createdAt).toISOString();
117
- return [
118
- `id: ${toShortId(obs.id)}`,
119
- `kind: ${obs.kind}`,
120
- `when: ${date}`,
121
- obs.author ? `who: ${obs.author}` : null,
122
- obs.files.length > 0 ? `files: ${obs.files.join(', ')}` : null,
123
- '',
124
- obs.title,
125
- '',
126
- obs.body,
127
- ]
128
- .filter((line) => line !== null)
129
- .join('\n');
130
- }
131
168
  const transport = new StdioServerTransport();
132
169
  await server.connect(transport);
133
170
  for (const signal of ['SIGINT', 'SIGTERM']) {
@@ -42,6 +42,15 @@ export interface MemoryStore {
42
42
  list(filter: ListFilter): Promise<Observation[]>;
43
43
  /** Every project with memory in this database, most recently active first. */
44
44
  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
+ inventory(): Promise<string[]>;
45
54
  /** Lexical match. Returns scores on an adapter-defined scale. */
46
55
  searchKeyword(query: SearchQuery): Promise<ObservationIndexEntry[]>;
47
56
  /** Vector match. Return [] when the backend has no vector support. */
@@ -56,6 +65,7 @@ export interface MemoryStore {
56
65
  * SessionStart loses sessions whose work is still there.
57
66
  */
58
67
  export declare function isWholeScope(filter: RemoveFilter): boolean;
68
+ export declare function foreignNames(names: string[]): string[];
59
69
  export interface StoreFactory {
60
70
  /** Lowercase URI schemes this factory claims, e.g. ['mongodb','mongodb+srv']. */
61
71
  schemes: string[];
@@ -8,3 +8,11 @@
8
8
  export function isWholeScope(filter) {
9
9
  return !filter.ids && !filter.kind && filter.before === undefined;
10
10
  }
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+)?)?$/;
16
+ export function foreignNames(names) {
17
+ return names.filter((name) => name.length > 0 && !OURS.test(name));
18
+ }
@@ -29,6 +29,7 @@ export declare class MongoStore implements MemoryStore {
29
29
  remove(filter: RemoveFilter): Promise<number>;
30
30
  list(filter: ListFilter): Promise<Observation[]>;
31
31
  listProjects(): Promise<ProjectSummary[]>;
32
+ inventory(): Promise<string[]>;
32
33
  searchKeyword(query: SearchQuery): Promise<ObservationIndexEntry[]>;
33
34
  searchVector(vector: number[], query: SearchQuery): Promise<ObservationIndexEntry[]>;
34
35
  timeline(query: TimelineQuery): Promise<ObservationIndexEntry[]>;
@@ -1,7 +1,8 @@
1
1
  import { importMongo } from './driver.js';
2
- import { isWholeScope } from '../adapter.js';
2
+ import { foreignNames, isWholeScope } from '../adapter.js';
3
3
  import { cosine } from '../../util/vector.js';
4
4
  import { partitionIds } from '../../util/shortid.js';
5
+ import { toSnippet } from '../../util/snippet.js';
5
6
  /**
6
7
  * Works against any MongoDB: Atlas, self-hosted, or a local container.
7
8
  *
@@ -150,13 +151,37 @@ export class MongoStore {
150
151
  lastActive: row.last,
151
152
  }));
152
153
  }
154
+ async inventory() {
155
+ // Through `command` rather than `listCollections`, so the structural driver
156
+ // types this adapter compiles against stay as small as they are.
157
+ const res = await this.db.command({ listCollections: 1, nameOnly: true });
158
+ const batch = res['cursor']?.firstBatch ?? [];
159
+ return foreignNames(batch.map((doc) => String(doc['name'] ?? '')));
160
+ }
153
161
  async searchKeyword(query) {
154
162
  const filter = {
155
163
  $text: { $search: query.text },
156
164
  ...this.scopeFilter(query),
157
165
  };
166
+ // $text has no fragment operator, so unlike FTS5 and ts_headline this is
167
+ // the head of the body rather than the text around the match. Still enough
168
+ // to tell two same-titled rows apart, and it costs one projected field
169
+ // instead of shipping whole bodies to slice them here.
170
+ //
171
+ // Inclusion throughout: MongoDB rejects a projection that mixes included
172
+ // and excluded fields, so the previous `body: 0, embedding: 0` form cannot
173
+ // carry a computed one.
158
174
  const docs = await this.observations
159
- .find(filter, { projection: { score: { $meta: 'textScore' }, body: 0, embedding: 0 } })
175
+ .find(filter, {
176
+ projection: {
177
+ kind: 1,
178
+ title: 1,
179
+ project: 1,
180
+ createdAt: 1,
181
+ snippet: { $substrCP: ['$body', 0, 240] },
182
+ score: { $meta: 'textScore' },
183
+ },
184
+ })
160
185
  .sort({ score: { $meta: 'textScore' } })
161
186
  .limit(query.limit)
162
187
  .toArray();
@@ -232,6 +257,8 @@ export class MongoStore {
232
257
  filter['project'] = query.project;
233
258
  if (query.kind)
234
259
  filter['kind'] = query.kind;
260
+ if (query.tag)
261
+ filter['tags'] = query.tag;
235
262
  if (query.since !== undefined || query.until !== undefined) {
236
263
  const range = {};
237
264
  if (query.since !== undefined)
@@ -314,7 +341,7 @@ function toObservation(doc) {
314
341
  return obs;
315
342
  }
316
343
  function toIndexEntry(doc, score) {
317
- return {
344
+ const entry = {
318
345
  id: doc._id,
319
346
  kind: doc.kind,
320
347
  title: doc.title,
@@ -322,4 +349,8 @@ function toIndexEntry(doc, score) {
322
349
  createdAt: doc.createdAt,
323
350
  score,
324
351
  };
352
+ const snippet = toSnippet(doc.snippet);
353
+ if (snippet)
354
+ entry.snippet = snippet;
355
+ return entry;
325
356
  }
@@ -8,7 +8,21 @@ export declare class PostgresStore implements MemoryStore {
8
8
  private warnedDims;
9
9
  private constructor();
10
10
  static create(uri: string): Promise<PostgresStore>;
11
+ /**
12
+ * Every hook is its own process, so nothing here is ever pooled or reused:
13
+ * this ran in full on every single prompt. Against a managed Postgres, where
14
+ * one round trip measured 49ms at best and 1045ms at the median, four of them
15
+ * before the first real query is most of why a remote backend feels broken.
16
+ *
17
+ * The version row collapses that to one read on the steady-state path. It
18
+ * carries the vector state too, because otherwise proving the extension is
19
+ * available costs back the round trip just saved. Anything unexpected — no
20
+ * table, an older version, an unreadable row — falls through to the full DDL,
21
+ * so the worst case is exactly the behaviour this replaces.
22
+ */
11
23
  init(): Promise<void>;
24
+ private readMeta;
25
+ private writeMeta;
12
26
  /**
13
27
  * CREATE TABLE IF NOT EXISTS leaves an existing generated column alone, so a
14
28
  * database created before tags were indexed keeps the old expression. Rebuild
@@ -36,6 +50,7 @@ export declare class PostgresStore implements MemoryStore {
36
50
  remove(filter: RemoveFilter): Promise<number>;
37
51
  list(filter: ListFilter): Promise<Observation[]>;
38
52
  listProjects(): Promise<ProjectSummary[]>;
53
+ inventory(): Promise<string[]>;
39
54
  searchKeyword(query: SearchQuery): Promise<ObservationIndexEntry[]>;
40
55
  searchVector(vector: number[], query: SearchQuery): Promise<ObservationIndexEntry[]>;
41
56
  timeline(query: TimelineQuery): Promise<ObservationIndexEntry[]>;
@@ -1,5 +1,6 @@
1
- import { isWholeScope } from '../adapter.js';
1
+ import { foreignNames, isWholeScope } from '../adapter.js';
2
2
  import { partitionIds } from '../../util/shortid.js';
3
+ import { toSnippet } from '../../util/snippet.js';
3
4
  /**
4
5
  * Postgres backend. Uses tsvector for keyword search, and pgvector for
5
6
  * embeddings when the extension is available. If `CREATE EXTENSION vector`
@@ -16,6 +17,11 @@ const TSV_EXPRESSION = `
16
17
  setweight(to_tsvector('english', coalesce(title, '')), 'A') ||
17
18
  setweight(to_tsvector('english', coalesce(tags::text, '')), 'B') ||
18
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;
19
25
  export class PostgresStore {
20
26
  pool;
21
27
  kind = 'postgres';
@@ -30,9 +36,34 @@ export class PostgresStore {
30
36
  const pool = new pg.Pool({ connectionString: uri });
31
37
  return new PostgresStore(pool);
32
38
  }
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
+ */
33
51
  async init() {
52
+ const meta = await this.readMeta();
53
+ if (meta?.version === SCHEMA_VERSION) {
54
+ this.vectorEnabled = meta.vectorEnabled;
55
+ this.vectorDims = meta.vectorDims;
56
+ return;
57
+ }
34
58
  this.vectorEnabled = await this.tryEnableVector();
35
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
+
36
67
  CREATE TABLE IF NOT EXISTS sessions (
37
68
  id TEXT PRIMARY KEY,
38
69
  project TEXT NOT NULL,
@@ -60,6 +91,7 @@ export class PostgresStore {
60
91
  CREATE INDEX IF NOT EXISTS idx_obs_tsv ON observations USING GIN(tsv);
61
92
  CREATE INDEX IF NOT EXISTS idx_obs_project_time
62
93
  ON observations(project, created_at DESC);
94
+ CREATE INDEX IF NOT EXISTS idx_obs_tags ON observations USING GIN(tags);
63
95
 
64
96
  ALTER TABLE observations ADD COLUMN IF NOT EXISTS embedder TEXT;
65
97
  ALTER TABLE observations ADD COLUMN IF NOT EXISTS author TEXT;
@@ -67,6 +99,33 @@ export class PostgresStore {
67
99
  await this.ensureTagsIndexed();
68
100
  if (this.vectorEnabled)
69
101
  this.vectorDims = await this.readVectorDims();
102
+ await this.writeMeta();
103
+ }
104
+ 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
+ }
121
+ }
122
+ 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]);
70
129
  }
71
130
  /**
72
131
  * CREATE TABLE IF NOT EXISTS leaves an existing generated column alone, so a
@@ -111,7 +170,13 @@ export class PostgresStore {
111
170
  await this.pool.query(`ALTER TABLE observations ADD COLUMN IF NOT EXISTS embedding vector(${dims})`);
112
171
  await this.pool.query(`CREATE INDEX IF NOT EXISTS idx_obs_embedding
113
172
  ON observations USING hnsw (embedding vector_cosine_ops)`);
114
- this.vectorDims = dims;
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
+ this.vectorDims = await this.readVectorDims();
179
+ await this.writeMeta();
115
180
  }
116
181
  if (this.vectorDims !== dims && !this.warnedDims) {
117
182
  this.warnedDims = true;
@@ -290,6 +355,11 @@ export class PostgresStore {
290
355
  lastActive: Number(row['last']),
291
356
  }));
292
357
  }
358
+ 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'] ?? '')));
362
+ }
293
363
  async searchKeyword(query) {
294
364
  const conditions = ['tsv @@ q.tsq'];
295
365
  const values = [query.text];
@@ -304,7 +374,10 @@ export class PostgresStore {
304
374
  const res = await this.pool.query(`WITH q AS (
305
375
  SELECT replace(plainto_tsquery('english', $1)::text, '&', '|')::tsquery AS tsq
306
376
  )
307
- SELECT id, kind, title, project, created_at, ts_rank(tsv, q.tsq) AS score
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
308
381
  FROM observations, q
309
382
  WHERE ${conditions.join(' AND ')}
310
383
  ORDER BY score DESC
@@ -356,6 +429,11 @@ export class PostgresStore {
356
429
  values.push(query.kind);
357
430
  conditions.push(`kind = $${values.length}`);
358
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
+ }
359
437
  if (query.since !== undefined) {
360
438
  values.push(query.since);
361
439
  conditions.push(`created_at >= $${values.length}`);
@@ -422,7 +500,7 @@ function toObservation(row) {
422
500
  return obs;
423
501
  }
424
502
  function toIndexEntry(row) {
425
- return {
503
+ const entry = {
426
504
  id: row['id'],
427
505
  kind: row['kind'],
428
506
  title: row['title'],
@@ -430,4 +508,11 @@ function toIndexEntry(row) {
430
508
  createdAt: Number(row['created_at']),
431
509
  score: Number(row['score'] ?? 0),
432
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;
433
518
  }
@@ -25,6 +25,7 @@ export declare class SqliteStore implements MemoryStore {
25
25
  remove(filter: RemoveFilter): Promise<number>;
26
26
  list(filter: ListFilter): Promise<Observation[]>;
27
27
  listProjects(): Promise<ProjectSummary[]>;
28
+ inventory(): Promise<string[]>;
28
29
  searchKeyword(query: SearchQuery): Promise<ObservationIndexEntry[]>;
29
30
  searchVector(vector: number[], query: SearchQuery): Promise<ObservationIndexEntry[]>;
30
31
  timeline(query: TimelineQuery): Promise<ObservationIndexEntry[]>;