claude-db 0.1.1 → 0.2.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (41) hide show
  1. package/README.md +17 -2
  2. package/dist/capture/flush.d.ts +22 -0
  3. package/dist/capture/flush.js +45 -10
  4. package/dist/capture/identity.d.ts +6 -0
  5. package/dist/capture/identity.js +14 -0
  6. package/dist/capture/index.d.ts +5 -3
  7. package/dist/capture/index.js +4 -3
  8. package/dist/capture/manual.d.ts +21 -0
  9. package/dist/capture/manual.js +45 -0
  10. package/dist/capture/transcript.d.ts +12 -0
  11. package/dist/capture/transcript.js +69 -1
  12. package/dist/capture/turn-extractor.d.ts +1 -0
  13. package/dist/capture/turn-extractor.js +46 -9
  14. package/dist/cli/index.js +458 -67
  15. package/dist/cli/install.d.ts +15 -1
  16. package/dist/cli/install.js +127 -8
  17. package/dist/config/schema.d.ts +1 -0
  18. package/dist/config/schema.js +9 -1
  19. package/dist/context.js +24 -2
  20. package/dist/embed/builtin.js +3 -1
  21. package/dist/hooks/relevance.js +11 -4
  22. package/dist/hooks/session-end.js +2 -1
  23. package/dist/hooks/session-start.js +22 -3
  24. package/dist/mcp/server.js +56 -6
  25. package/dist/search/service.js +4 -1
  26. package/dist/store/adapter.d.ts +22 -6
  27. package/dist/store/adapter.js +10 -1
  28. package/dist/store/mongo/driver.d.ts +1 -0
  29. package/dist/store/mongo/index.d.ts +3 -2
  30. package/dist/store/mongo/index.js +57 -7
  31. package/dist/store/postgres/index.d.ts +22 -8
  32. package/dist/store/postgres/index.js +165 -21
  33. package/dist/store/sqlite/index.d.ts +3 -2
  34. package/dist/store/sqlite/index.js +112 -9
  35. package/dist/store/sqlite/schema.sql +4 -3
  36. package/dist/types.d.ts +28 -0
  37. package/dist/util/project.d.ts +9 -10
  38. package/dist/util/project.js +52 -13
  39. package/dist/util/vector.d.ts +11 -1
  40. package/dist/util/vector.js +14 -3
  41. package/package.json +2 -2
@@ -1,4 +1,5 @@
1
- import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
1
+ import { execFileSync } from 'node:child_process';
2
+ import { mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
2
3
  import { dirname, join, resolve } from 'node:path';
3
4
  import { homedir } from 'node:os';
4
5
  /**
@@ -14,6 +15,76 @@ export function settingsPathFor(scope, project) {
14
15
  ? join(project, '.claude', 'settings.local.json')
15
16
  : join(homedir(), '.claude', 'settings.json');
16
17
  }
18
+ /**
19
+ * Where standing instructions go.
20
+ *
21
+ * Hook output is injected as conversation context, which the agent reads as
22
+ * information about the current turn. It is not a rule, so "you could search
23
+ * memory" competes with everything else in the transcript and loses. A memory
24
+ * file is part of the system prompt and governs the whole session, which is
25
+ * the only reliable way to make recall a default rather than a suggestion.
26
+ *
27
+ * Project scope writes CLAUDE.local.md rather than CLAUDE.md: it is personal
28
+ * and uncommitted, matching settings.local.json, so installing memory for
29
+ * yourself never tells a teammate's agent to call a server they do not have.
30
+ */
31
+ export function instructionsPathFor(scope, project) {
32
+ return scope === 'project'
33
+ ? join(project, 'CLAUDE.local.md')
34
+ : join(homedir(), '.claude', 'CLAUDE.md');
35
+ }
36
+ const BLOCK_START = '<!-- claude-db:start -->';
37
+ const BLOCK_END = '<!-- claude-db:end -->';
38
+ const INSTRUCTIONS = [
39
+ BLOCK_START,
40
+ '## Project memory',
41
+ '',
42
+ 'This project has persistent memory of past sessions, served by the `memory`',
43
+ 'MCP server. Session summaries are injected at startup and the best matching',
44
+ 'observation is injected above each prompt, but that is only ever a slice.',
45
+ '',
46
+ 'Before saying you lack context on this codebase, or asking the user to',
47
+ 're-explain a past decision, a failed approach, or why something is the way',
48
+ 'it is: call `search` first, then `get_observations` for the ids worth',
49
+ 'reading. Treat asking the user as the fallback, not the first move.',
50
+ '',
51
+ 'When the user states a standing rule or preference, record it with',
52
+ '`remember` so it survives this session.',
53
+ BLOCK_END,
54
+ ].join('\n');
55
+ /** Adds or refreshes our block, leaving everything else in the file intact. */
56
+ function writeInstructions(path) {
57
+ const rest = withoutBlock(readText(path)).trimEnd();
58
+ const body = rest.length > 0 ? `${rest}\n\n${INSTRUCTIONS}\n` : `${INSTRUCTIONS}\n`;
59
+ writeAtomic(path, body);
60
+ }
61
+ function removeInstructions(path) {
62
+ const existing = readText(path);
63
+ if (!existing.includes(BLOCK_START))
64
+ return;
65
+ const rest = withoutBlock(existing).trim();
66
+ // A file that held nothing but our block was ours to create, so take it with
67
+ // us rather than leaving an empty CLAUDE.md behind.
68
+ if (rest.length === 0)
69
+ rmSync(path, { force: true });
70
+ else
71
+ writeAtomic(path, `${rest}\n`);
72
+ }
73
+ function withoutBlock(text) {
74
+ const start = text.indexOf(BLOCK_START);
75
+ const end = text.indexOf(BLOCK_END);
76
+ if (start === -1 || end === -1 || end < start)
77
+ return text;
78
+ return `${text.slice(0, start)}${text.slice(end + BLOCK_END.length)}`.replace(/\n{3,}/g, '\n\n');
79
+ }
80
+ function readText(path) {
81
+ try {
82
+ return readFileSync(path, 'utf8');
83
+ }
84
+ catch {
85
+ return '';
86
+ }
87
+ }
17
88
  /**
18
89
  * MCP servers live in a different file from hooks.
19
90
  *
@@ -41,7 +112,7 @@ const HOOKS = [
41
112
  ['SessionEnd', 'session-end.js'],
42
113
  ];
43
114
  /**
44
- * Registers the four lifecycle hooks and the MCP server, merging into whatever
115
+ * Registers the three lifecycle hooks and the MCP server, merging into whatever
45
116
  * the user already has rather than overwriting it. Re-running is safe: a hook
46
117
  * whose command already appears is skipped rather than duplicated.
47
118
  */
@@ -88,17 +159,39 @@ export function install(distDir, scope, project) {
88
159
  // Never write mcpServers here; Claude Code ignores it in this file.
89
160
  delete settings['mcpServers'];
90
161
  writeJson(path, settings);
162
+ const server = resolve(distDir, 'mcp', 'server.js');
163
+ writeInstructions(instructionsPathFor(scope, project));
164
+ // A global install lands in ~/.claude.json, which holds all of Claude Code's
165
+ // own state. Let its CLI own that file rather than round-tripping megabytes
166
+ // of someone else's config through JSON.parse to add one key. The direct
167
+ // write stays as a fallback, since `claude` is not always on PATH, and it is
168
+ // the right thing for the project scope: .mcp.json is small and ours.
169
+ if (scope === 'global' && registerViaCli(server))
170
+ return path;
91
171
  const mcpPath = mcpPathFor(scope, project);
92
172
  const mcpConfig = readJson(mcpPath);
93
173
  const servers = (mcpConfig['mcpServers'] ?? {});
94
- servers['memory'] = {
95
- command: 'node',
96
- args: [resolve(distDir, 'mcp', 'server.js')],
97
- };
174
+ servers['memory'] = { command: 'node', args: [server] };
98
175
  mcpConfig['mcpServers'] = servers;
99
176
  writeJson(mcpPath, mcpConfig);
100
177
  return path;
101
178
  }
179
+ /** Both directions of the `claude mcp` CLI, false when it is unavailable. */
180
+ function claudeMcp(args) {
181
+ try {
182
+ execFileSync('claude', args, { stdio: 'ignore' });
183
+ return true;
184
+ }
185
+ catch {
186
+ return false;
187
+ }
188
+ }
189
+ function registerViaCli(server) {
190
+ // Removed first because `add` refuses an existing name, and re-running
191
+ // install has to stay safe.
192
+ claudeMcp(['mcp', 'remove', 'memory', '-s', 'user']);
193
+ return claudeMcp(['mcp', 'add', 'memory', '-s', 'user', '--', 'node', server]);
194
+ }
102
195
  /**
103
196
  * Removes only what `install` added, leaving unrelated hooks and servers in
104
197
  * place. Empty containers are pruned so an uninstall leaves no residue.
@@ -127,15 +220,24 @@ export function uninstall(distDir, scope, project) {
127
220
  else
128
221
  delete settings['hooks'];
129
222
  writeJson(path, settings);
223
+ removeInstructions(instructionsPathFor(scope, project));
224
+ // Symmetric with install: if the CLI put it there, the CLI takes it out.
225
+ if (scope === 'global' && claudeMcp(['mcp', 'remove', 'memory', '-s', 'user'])) {
226
+ return path;
227
+ }
130
228
  const mcpPath = mcpPathFor(scope, project);
131
229
  const mcpConfig = readJson(mcpPath);
230
+ // Captured before the delete below can empty it. Testing emptiness
231
+ // afterwards skipped the write for a config holding only our server, which
232
+ // is the common case, so uninstall silently left it registered.
233
+ const existed = Object.keys(mcpConfig).length > 0;
132
234
  const servers = (mcpConfig['mcpServers'] ?? {});
133
235
  delete servers['memory'];
134
236
  if (Object.keys(servers).length > 0)
135
237
  mcpConfig['mcpServers'] = servers;
136
238
  else
137
239
  delete mcpConfig['mcpServers'];
138
- if (Object.keys(mcpConfig).length > 0)
240
+ if (existed)
139
241
  writeJson(mcpPath, mcpConfig);
140
242
  return path;
141
243
  }
@@ -150,7 +252,24 @@ function readJson(path) {
150
252
  return {};
151
253
  }
152
254
  }
255
+ /**
256
+ * Written through a temporary file and renamed, because one of these targets
257
+ * is `~/.claude.json`, which holds all of Claude Code's own state. Truncating
258
+ * it and dying midway to add a single key would cost the user real data;
259
+ * rename is atomic, so the file is either the old one or the new one.
260
+ */
153
261
  function writeJson(path, value) {
262
+ writeAtomic(path, `${JSON.stringify(value, null, 2)}\n`);
263
+ }
264
+ function writeAtomic(path, content) {
154
265
  mkdirSync(dirname(path), { recursive: true });
155
- writeFileSync(path, `${JSON.stringify(value, null, 2)}\n`, 'utf8');
266
+ const temp = `${path}.${process.pid}.tmp`;
267
+ try {
268
+ writeFileSync(temp, content, 'utf8');
269
+ renameSync(temp, path);
270
+ }
271
+ catch (error) {
272
+ rmSync(temp, { force: true });
273
+ throw error;
274
+ }
156
275
  }
@@ -9,6 +9,7 @@ export declare const ConfigSchema: z.ZodObject<{
9
9
  none: "none";
10
10
  }>>;
11
11
  maxScanCandidates: z.ZodDefault<z.ZodNumber>;
12
+ timeoutMs: z.ZodDefault<z.ZodNumber>;
12
13
  }, z.core.$strip>>;
13
14
  capture: z.ZodPrefault<z.ZodObject<{
14
15
  tools: z.ZodDefault<z.ZodArray<z.ZodString>>;
@@ -16,8 +16,16 @@ export const ConfigSchema = z.object({
16
16
  * vector index (pgvector, Atlas) ignore this.
17
17
  */
18
18
  maxScanCandidates: z.number().int().positive().default(25000),
19
+ /**
20
+ * How long to wait for the embedding model before giving up for this
21
+ * one invocation and falling back to keyword-only search. The model is
22
+ * fetched and loaded lazily inside a hook that runs on the critical path
23
+ * of a prompt, so an unbounded wait is a hung prompt. 0 disables the
24
+ * limit, which is what `doctor` uses to warm the model deliberately.
25
+ */
26
+ timeoutMs: z.number().int().nonnegative().default(3000),
19
27
  })
20
- .default({ provider: 'auto', maxScanCandidates: 25000 }),
28
+ .default({ provider: 'auto', maxScanCandidates: 25000, timeoutMs: 3000 }),
21
29
  capture: z
22
30
  .object({
23
31
  /** Tools whose invocations are worth remembering. */
package/dist/context.js CHANGED
@@ -1,5 +1,5 @@
1
1
  import { loadConfig } from './config/index.js';
2
- import { createEmbedder } from './embed/index.js';
2
+ import { createEmbedder, NoopEmbedder } from './embed/index.js';
3
3
  import { SearchService } from './search/index.js';
4
4
  import { createStore } from './store/index.js';
5
5
  /**
@@ -17,9 +17,31 @@ export async function createContext(overrides) {
17
17
  await store.init();
18
18
  let pending = null;
19
19
  const embedder = () => {
20
- pending ??= createEmbedder(config.embeddings.provider);
20
+ pending ??= withTimeout(createEmbedder(config.embeddings.provider).catch(() => new NoopEmbedder()), config.embeddings.timeoutMs);
21
21
  return pending;
22
22
  };
23
23
  const search = new SearchService(store, embedder, config.embeddings.maxScanCandidates);
24
24
  return { config, store, embedder, search, close: () => store.close() };
25
25
  }
26
+ /**
27
+ * The first use of a local model downloads ~25MB and loads it, inside a hook
28
+ * that is blocking the user's prompt. Bounding that turns a hung prompt into
29
+ * one prompt with keyword-only recall; the next invocation finds the model
30
+ * cached. Falls back to no embedder rather than to the builtin, so a timeout
31
+ * never mixes a second vector width into the database.
32
+ */
33
+ async function withTimeout(pending, ms) {
34
+ if (ms <= 0)
35
+ return pending;
36
+ let timer;
37
+ const limit = new Promise((settle) => {
38
+ timer = setTimeout(() => settle(new NoopEmbedder()), ms);
39
+ timer.unref?.();
40
+ });
41
+ try {
42
+ return await Promise.race([pending, limit]);
43
+ }
44
+ finally {
45
+ clearTimeout(timer);
46
+ }
47
+ }
@@ -22,9 +22,11 @@ export class BuiltinEmbedder {
22
22
  }
23
23
  vectorize(text) {
24
24
  const vector = new Array(DIMENSIONS).fill(0);
25
+ // Any script: ASCII-only shredded accented Latin and gave CJK a zero
26
+ // vector. CJK arrives as one long token, where the trigrams do the work.
25
27
  const words = text
26
28
  .toLowerCase()
27
- .split(/[^a-z0-9]+/i)
29
+ .split(/[^\p{L}\p{N}]+/u)
28
30
  .filter((word) => word.length > 1);
29
31
  for (const word of words) {
30
32
  // Whole word carries the most signal.
@@ -13,8 +13,13 @@ const TRIVIAL = new Set([
13
13
  const NOISE = new Set([
14
14
  'the', 'and', 'for', 'this', 'that', 'with', 'you', 'can', 'please', 'now',
15
15
  'what', 'why', 'how', 'when', 'where', 'are', 'was', 'were', 'have', 'has',
16
- 'not', '但', 'let', 'make', 'get', 'add', 'use', 'need', 'want', 'should',
16
+ 'not', 'let', 'make', 'get', 'add', 'use', 'need', 'want', 'should',
17
17
  ]);
18
+ /**
19
+ * Scripts written without spaces. "修复登录接口的超时问题" is one token, so the
20
+ * two-content-word bar has to be counted in characters instead.
21
+ */
22
+ const DENSE_SCRIPT = /[\p{Script=Han}\p{Script=Hiragana}\p{Script=Katakana}\p{Script=Hangul}]/gu;
18
23
  /**
19
24
  * Decides whether a prompt is worth a memory lookup at all.
20
25
  *
@@ -24,12 +29,14 @@ const NOISE = new Set([
24
29
  */
25
30
  export function isSearchable(prompt) {
26
31
  const normalized = prompt.trim().toLowerCase();
27
- if (normalized.length < 8)
28
- return false;
29
32
  if (TRIVIAL.has(normalized.replace(/[.!?]+$/, '')))
30
33
  return false;
34
+ if ((normalized.match(DENSE_SCRIPT)?.length ?? 0) >= 4)
35
+ return true;
36
+ if (normalized.length < 8)
37
+ return false;
31
38
  const content = normalized
32
- .split(/[^a-z0-9_]+/i)
39
+ .split(/[^\p{L}\p{N}_]+/u)
33
40
  .filter((word) => word.length > 2 && !NOISE.has(word));
34
41
  return content.length >= 2;
35
42
  }
@@ -1,5 +1,5 @@
1
1
  #!/usr/bin/env node
2
- import { flushSession } from '../capture/index.js';
2
+ import { clearCursor, flushSession } from '../capture/index.js';
3
3
  import { createContext } from '../context.js';
4
4
  import { readPayload, runHook } from './payload.js';
5
5
  import { resolveProject } from '../util/project.js';
@@ -28,6 +28,7 @@ await runHook(async () => {
28
28
  endedAt: Date.now(),
29
29
  ...(result.summary ? { summary: result.summary } : {}),
30
30
  });
31
+ clearCursor(sessionId);
31
32
  }
32
33
  finally {
33
34
  await ctx.close();
@@ -1,9 +1,24 @@
1
1
  #!/usr/bin/env node
2
+ import { readFileSync } from 'node:fs';
3
+ import { homedir } from 'node:os';
4
+ import { dirname, join, resolve } from 'node:path';
5
+ import { fileURLToPath } from 'node:url';
2
6
  import { createContext } from '../context.js';
3
7
  import { emitContext, readPayload, runHook } from './payload.js';
4
8
  import { resolveProject } from '../util/project.js';
5
9
  import { silenceSqliteWarning } from '../util/warnings.js';
6
10
  silenceSqliteWarning();
11
+ const SERVER = resolve(dirname(fileURLToPath(import.meta.url)), '..', 'mcp', 'server.js');
12
+ function mcpRegistered(project) {
13
+ return [join(project, '.mcp.json'), join(homedir(), '.claude.json')].some((path) => {
14
+ try {
15
+ return readFileSync(path, 'utf8').includes(SERVER);
16
+ }
17
+ catch {
18
+ return false;
19
+ }
20
+ });
21
+ }
7
22
  /**
8
23
  * SessionStart: prime the agent with what past sessions concluded.
9
24
  *
@@ -22,7 +37,7 @@ await runHook(async () => {
22
37
  // Costs ~12 tokens and disappears permanently after the first real session.
23
38
  if (sessions.length === 0) {
24
39
  emitContext('<project-memory>none yet for this project; ' +
25
- 'it is recorded when a session ends</project-memory>\n');
40
+ 'it is recorded as you work</project-memory>\n');
26
41
  return;
27
42
  }
28
43
  const lines = ['<project-memory>'];
@@ -36,8 +51,12 @@ await runHook(async () => {
36
51
  lines.push(line);
37
52
  }
38
53
  lines.push('</project-memory>');
39
- lines.push('Search this project\'s full history with the memory MCP tools before ' +
40
- 'asking the user to re-explain prior decisions.');
54
+ // Only advertise the tools when they are actually registered; pointing the
55
+ // agent at an MCP server that was never installed just wastes a turn.
56
+ if (mcpRegistered(project)) {
57
+ lines.push('Search this project\'s full history with the memory MCP tools before ' +
58
+ 'asking the user to re-explain prior decisions.');
59
+ }
41
60
  emitContext(`${lines.join('\n')}\n`);
42
61
  }
43
62
  finally {
@@ -1,7 +1,11 @@
1
1
  #!/usr/bin/env node
2
+ import { readFileSync } from 'node:fs';
3
+ import { dirname, resolve } from 'node:path';
4
+ import { fileURLToPath } from 'node:url';
2
5
  import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
3
6
  import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
4
7
  import { z } from 'zod';
8
+ import { remember } from '../capture/index.js';
5
9
  import { createContext } from '../context.js';
6
10
  import { toShortId } from '../util/shortid.js';
7
11
  import { resolveProject } from '../util/project.js';
@@ -10,30 +14,75 @@ silenceSqliteWarning();
10
14
  const KINDS = [
11
15
  'decision', 'pattern', 'bugfix', 'context', 'deadend', 'preference',
12
16
  ];
17
+ function packageVersion() {
18
+ try {
19
+ const path = resolve(dirname(fileURLToPath(import.meta.url)), '..', '..', 'package.json');
20
+ return JSON.parse(readFileSync(path, 'utf8')).version ?? '0.0.0';
21
+ }
22
+ catch {
23
+ return '0.0.0';
24
+ }
25
+ }
13
26
  /**
14
- * Exposes memory as three tools that mirror the progressive disclosure layers.
15
- * Tool descriptions spell out the intended order, because the saving only
16
- * materializes if the agent filters at `search` before calling
27
+ * Three read tools mirroring the progressive disclosure layers, plus two that
28
+ * write. Tool descriptions spell out the intended order, because the saving
29
+ * only materializes if the agent filters at `search` before calling
17
30
  * `get_observations`.
31
+ *
32
+ * `remember` exists because capture is inferred from transcripts, and a rule
33
+ * is not an event: "we always use pnpm here" produces no edit and no command,
34
+ * so the one thing most worth keeping is the one thing never recorded.
18
35
  */
19
36
  const ctx = await createContext();
20
- const server = new McpServer({ name: 'claude-db', version: '0.1.0' });
37
+ const server = new McpServer({ name: 'claude-db', version: packageVersion() });
21
38
  server.tool('search', 'Layer 1. Search project memory and get a compact index of matches ' +
22
39
  '(id, kind, title, date) without bodies. Start here, then fetch details ' +
23
40
  'for only the ids that look relevant.', {
24
41
  query: z.string().describe('Natural language description of what you need'),
25
- project: z.string().optional().describe('Absolute project path; defaults to cwd'),
42
+ project: z
43
+ .string()
44
+ .optional()
45
+ .describe('Absolute project path; defaults to cwd. Pass "*" to search every project'),
26
46
  kind: z.enum(KINDS).optional(),
27
47
  limit: z.number().int().min(1).max(50).default(10),
28
48
  }, async ({ query, project, kind, limit }) => {
29
49
  const entries = await ctx.search.search({
30
50
  text: query,
31
51
  limit,
32
- project: resolveProject(project),
52
+ ...(project === '*' ? {} : { project: resolveProject(project) }),
33
53
  ...(kind ? { kind } : {}),
34
54
  });
35
55
  return { content: [{ type: 'text', text: renderIndex(entries) }] };
36
56
  });
57
+ server.tool('remember', 'Record something the user stated outright that no transcript would capture: ' +
58
+ 'a standing rule, preference or constraint ("always use pnpm here"). Use this ' +
59
+ 'when the user says to remember something, not for work you just did — that ' +
60
+ 'is captured automatically.', {
61
+ text: z.string().describe('What to remember, in full. First line becomes the title'),
62
+ kind: z.enum(KINDS).default('preference'),
63
+ project: z.string().optional().describe('Absolute project path; defaults to cwd'),
64
+ }, async ({ text, kind, project }) => {
65
+ const observation = await remember(ctx, {
66
+ project: resolveProject(project),
67
+ text,
68
+ kind,
69
+ });
70
+ return {
71
+ content: [
72
+ {
73
+ type: 'text',
74
+ text: `Remembered ${toShortId(observation.id)} [${observation.kind}] ${observation.title}`,
75
+ },
76
+ ],
77
+ };
78
+ });
79
+ server.tool('forget', 'Delete observations by id, for memory that is wrong or obsolete. Ids come ' +
80
+ 'from search. This cannot be undone, so confirm with the user first.', { ids: z.array(z.string()).min(1).max(25) }, async ({ ids }) => {
81
+ const deleted = await ctx.store.remove({ ids });
82
+ return {
83
+ content: [{ type: 'text', text: `Forgot ${deleted} observation(s).` }],
84
+ };
85
+ });
37
86
  server.tool('timeline', 'Layer 2. Show what happened immediately before and after a given ' +
38
87
  'observation, to understand the context a decision was made in.', {
39
88
  observation_id: z.string(),
@@ -69,6 +118,7 @@ function renderFull(obs) {
69
118
  `id: ${toShortId(obs.id)}`,
70
119
  `kind: ${obs.kind}`,
71
120
  `when: ${date}`,
121
+ obs.author ? `who: ${obs.author}` : null,
72
122
  obs.files.length > 0 ? `files: ${obs.files.join(', ')}` : null,
73
123
  '',
74
124
  obs.title,
@@ -55,7 +55,10 @@ export class SearchService {
55
55
  const [embedding] = await embedder.embed([query.text]);
56
56
  if (!embedding || embedding.length === 0)
57
57
  return [];
58
- const candidates = await this.store.searchVector(embedding, query);
58
+ const candidates = await this.store.searchVector(embedding, {
59
+ ...query,
60
+ embedder: embedder.id,
61
+ });
59
62
  // Nearest-neighbour search always returns its top k, however poor the
60
63
  // match. Without a floor, an unrelated prompt still yields results, and
61
64
  // injecting those trains the reader to ignore memory entirely. Dropping
@@ -1,4 +1,4 @@
1
- import type { Observation, ObservationIndexEntry, SearchQuery, Session, TimelineQuery } from '../types.js';
1
+ import type { ListFilter, Observation, ObservationIndexEntry, RemoveFilter, SearchQuery, Session, TimelineQuery } from '../types.js';
2
2
  export interface ProjectSummary {
3
3
  project: string;
4
4
  observations: number;
@@ -25,13 +25,21 @@ export interface MemoryStore {
25
25
  insertObservations(observations: Observation[]): Promise<void>;
26
26
  getObservations(ids: string[]): Promise<Observation[]>;
27
27
  /**
28
- * Deletes memory, scoped to one project or everything when omitted.
29
- * Returns the number of observations removed.
28
+ * Deletes memory matching a filter, returning how many observations went.
30
29
  *
31
- * Belongs on the adapter rather than being handled by deleting a file,
32
- * because on a shared Postgres or Mongo there is no file to delete.
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
+ 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.
33
41
  */
34
- clear(project?: string): Promise<number>;
42
+ list(filter: ListFilter): Promise<Observation[]>;
35
43
  /** Every project with memory in this database, most recently active first. */
36
44
  listProjects(): Promise<ProjectSummary[]>;
37
45
  /** Lexical match. Returns scores on an adapter-defined scale. */
@@ -40,6 +48,14 @@ export interface MemoryStore {
40
48
  searchVector(vector: number[], query: SearchQuery): Promise<ObservationIndexEntry[]>;
41
49
  timeline(query: TimelineQuery): Promise<ObservationIndexEntry[]>;
42
50
  }
51
+ /**
52
+ * True when a filter names a whole project, or the whole database.
53
+ *
54
+ * Sessions follow their observations only in that case: pruning by date or
55
+ * forgetting one row must leave the session record alone, or the recap at
56
+ * SessionStart loses sessions whose work is still there.
57
+ */
58
+ export declare function isWholeScope(filter: RemoveFilter): boolean;
43
59
  export interface StoreFactory {
44
60
  /** Lowercase URI schemes this factory claims, e.g. ['mongodb','mongodb+srv']. */
45
61
  schemes: string[];
@@ -1 +1,10 @@
1
- export {};
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
+ export function isWholeScope(filter) {
9
+ return !filter.ids && !filter.kind && filter.before === undefined;
10
+ }
@@ -16,6 +16,7 @@ export interface FindCursor<T> {
16
16
  }
17
17
  export interface Collection<T> {
18
18
  createIndex(spec: Doc, options?: Doc): Promise<string>;
19
+ countDocuments(filter: Doc): Promise<number>;
19
20
  findOne(filter: Doc, options?: Doc): Promise<T | null>;
20
21
  find(filter: Doc, options?: Doc): FindCursor<T>;
21
22
  updateOne(filter: Doc, update: Doc, options?: Doc): Promise<unknown>;
@@ -1,5 +1,5 @@
1
1
  import type { MemoryStore, ProjectSummary } from '../adapter.js';
2
- import type { Observation, ObservationIndexEntry, SearchQuery, Session, TimelineQuery } from '../../types.js';
2
+ import type { ListFilter, Observation, ObservationIndexEntry, RemoveFilter, SearchQuery, Session, TimelineQuery } from '../../types.js';
3
3
  /**
4
4
  * Works against any MongoDB: Atlas, self-hosted, or a local container.
5
5
  *
@@ -26,7 +26,8 @@ export declare class MongoStore implements MemoryStore {
26
26
  recentSessions(project: string, limit: number): Promise<Session[]>;
27
27
  insertObservations(observations: Observation[]): Promise<void>;
28
28
  getObservations(ids: string[]): Promise<Observation[]>;
29
- clear(project?: string): Promise<number>;
29
+ remove(filter: RemoveFilter): Promise<number>;
30
+ list(filter: ListFilter): Promise<Observation[]>;
30
31
  listProjects(): Promise<ProjectSummary[]>;
31
32
  searchKeyword(query: SearchQuery): Promise<ObservationIndexEntry[]>;
32
33
  searchVector(vector: number[], query: SearchQuery): Promise<ObservationIndexEntry[]>;