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.
- package/README.md +17 -2
- package/dist/capture/flush.d.ts +22 -0
- package/dist/capture/flush.js +45 -10
- package/dist/capture/identity.d.ts +6 -0
- package/dist/capture/identity.js +14 -0
- package/dist/capture/index.d.ts +5 -3
- package/dist/capture/index.js +4 -3
- package/dist/capture/manual.d.ts +21 -0
- package/dist/capture/manual.js +45 -0
- package/dist/capture/transcript.d.ts +12 -0
- package/dist/capture/transcript.js +69 -1
- package/dist/capture/turn-extractor.d.ts +1 -0
- package/dist/capture/turn-extractor.js +46 -9
- package/dist/cli/index.js +458 -67
- package/dist/cli/install.d.ts +15 -1
- package/dist/cli/install.js +127 -8
- package/dist/config/schema.d.ts +1 -0
- package/dist/config/schema.js +9 -1
- package/dist/context.js +24 -2
- package/dist/embed/builtin.js +3 -1
- package/dist/hooks/relevance.js +11 -4
- package/dist/hooks/session-end.js +2 -1
- package/dist/hooks/session-start.js +22 -3
- package/dist/mcp/server.js +56 -6
- package/dist/search/service.js +4 -1
- package/dist/store/adapter.d.ts +22 -6
- package/dist/store/adapter.js +10 -1
- package/dist/store/mongo/driver.d.ts +1 -0
- package/dist/store/mongo/index.d.ts +3 -2
- package/dist/store/mongo/index.js +57 -7
- package/dist/store/postgres/index.d.ts +22 -8
- package/dist/store/postgres/index.js +165 -21
- package/dist/store/sqlite/index.d.ts +3 -2
- package/dist/store/sqlite/index.js +112 -9
- package/dist/store/sqlite/schema.sql +4 -3
- package/dist/types.d.ts +28 -0
- package/dist/util/project.d.ts +9 -10
- package/dist/util/project.js +52 -13
- package/dist/util/vector.d.ts +11 -1
- package/dist/util/vector.js +14 -3
- package/package.json +2 -2
package/dist/cli/install.js
CHANGED
|
@@ -1,4 +1,5 @@
|
|
|
1
|
-
import {
|
|
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
|
|
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 (
|
|
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
|
-
|
|
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
|
}
|
package/dist/config/schema.d.ts
CHANGED
|
@@ -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>>;
|
package/dist/config/schema.js
CHANGED
|
@@ -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
|
+
}
|
package/dist/embed/builtin.js
CHANGED
|
@@ -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(/[
|
|
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.
|
package/dist/hooks/relevance.js
CHANGED
|
@@ -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', '
|
|
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(/[
|
|
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
|
|
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
|
-
|
|
40
|
-
|
|
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 {
|
package/dist/mcp/server.js
CHANGED
|
@@ -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
|
-
*
|
|
15
|
-
* Tool descriptions spell out the intended order, because the saving
|
|
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:
|
|
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
|
|
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,
|
package/dist/search/service.js
CHANGED
|
@@ -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,
|
|
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
|
package/dist/store/adapter.d.ts
CHANGED
|
@@ -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
|
|
29
|
-
* Returns the number of observations removed.
|
|
28
|
+
* Deletes memory matching a filter, returning how many observations went.
|
|
30
29
|
*
|
|
31
|
-
*
|
|
32
|
-
*
|
|
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
|
-
|
|
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[];
|
package/dist/store/adapter.js
CHANGED
|
@@ -1 +1,10 @@
|
|
|
1
|
-
|
|
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
|
-
|
|
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[]>;
|