@nhatnguyen9317/memory-mcp-server 1.3.3 → 1.4.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/CHANGELOG.md +76 -1
- package/GUIDELINES.md +94 -133
- package/README.md +32 -36
- package/dist/constants.js +1 -1
- package/dist/migrations/0007_drop_reasoning_step_marks.js +9 -0
- package/dist/migrations/0008_session_recalled_memory_ids.js +9 -0
- package/dist/migrations/index.js +4 -0
- package/dist/schemas/memory.js +14 -127
- package/dist/schemas/reasoning.js +24 -73
- package/dist/server.js +2 -1
- package/dist/tools/memory.js +8 -655
- package/dist/tools/reasoning.js +148 -534
- package/dist/utils.js +100 -7
- package/package.json +1 -1
package/dist/tools/memory.js
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
|
-
import {
|
|
2
|
-
import { RECALL_RECENCY_DAYS, RECALL_WEIGHTS
|
|
3
|
-
import {
|
|
1
|
+
import { MemoryGetInputSchema, MemoryRecordUsageFeedbackInputSchema, MemorySearchInputSchema, MemoryUpdateInputSchema, } from "../schemas/memory.js";
|
|
2
|
+
import { RECALL_RECENCY_DAYS, RECALL_WEIGHTS } from "../constants.js";
|
|
3
|
+
import { nowIso, parseJsonArray, parseJsonObject, toLimitedJson, toSearchTerms, } from "../utils.js";
|
|
4
4
|
import { withTelemetry, } from "./telemetry.js";
|
|
5
5
|
function rowToRecord(row) {
|
|
6
6
|
return {
|
|
@@ -15,6 +15,7 @@ function rowToRecord(row) {
|
|
|
15
15
|
updated_at: row.updated_at,
|
|
16
16
|
};
|
|
17
17
|
}
|
|
18
|
+
/** Escapes LIKE wildcards; pair with `ESCAPE '\'`. */
|
|
18
19
|
function escapeLikePattern(value) {
|
|
19
20
|
return value.replace(/[\\%_]/g, (char) => `\\${char}`);
|
|
20
21
|
}
|
|
@@ -28,18 +29,6 @@ function tagsFilterClauses(tags) {
|
|
|
28
29
|
function extractStructuredContent(result) {
|
|
29
30
|
return result.structuredContent ?? null;
|
|
30
31
|
}
|
|
31
|
-
/**
|
|
32
|
-
* Reports aggregate tool_usage_events; with telemetry off only successful
|
|
33
|
-
* usage-feedback rows exist, so say so in the output itself — an agent
|
|
34
|
-
* reading only the JSON must not mistake empty funnels for real zeros.
|
|
35
|
-
*/
|
|
36
|
-
function telemetryOffNote() {
|
|
37
|
-
return isTelemetryEnabled()
|
|
38
|
-
? {}
|
|
39
|
-
: {
|
|
40
|
-
telemetry_note: "MEMORY_TELEMETRY is off (the default): only successful usage-feedback events are recorded, so counts other than feedback are incomplete. Set MEMORY_TELEMETRY=on for full data.",
|
|
41
|
-
};
|
|
42
|
-
}
|
|
43
32
|
function resultCount(result) {
|
|
44
33
|
const structured = extractStructuredContent(result);
|
|
45
34
|
if (structured?.total_returned !== undefined) {
|
|
@@ -49,7 +38,7 @@ function resultCount(result) {
|
|
|
49
38
|
return structured.results.length;
|
|
50
39
|
return result.content[0]?.text.startsWith("No memories found") ? 0 : 1;
|
|
51
40
|
}
|
|
52
|
-
/** Ids of memories returned by a search
|
|
41
|
+
/** Ids of memories returned by a search call, bounded so telemetry rows stay small. */
|
|
53
42
|
function returnedMemoryIds(result) {
|
|
54
43
|
const structured = extractStructuredContent(result);
|
|
55
44
|
if (!Array.isArray(structured?.results))
|
|
@@ -59,77 +48,6 @@ function returnedMemoryIds(result) {
|
|
|
59
48
|
.map((row) => String(row.id))
|
|
60
49
|
.filter((id) => id !== "undefined");
|
|
61
50
|
}
|
|
62
|
-
function normalizeTextDate(value) {
|
|
63
|
-
if (!value)
|
|
64
|
-
return undefined;
|
|
65
|
-
return value.trim();
|
|
66
|
-
}
|
|
67
|
-
function normalizeDateBoundary(value, boundary) {
|
|
68
|
-
const normalized = normalizeTextDate(value);
|
|
69
|
-
if (!normalized)
|
|
70
|
-
return undefined;
|
|
71
|
-
if (/^\d{4}-\d{2}-\d{2}$/.test(normalized)) {
|
|
72
|
-
return `${normalized}${boundary === "start" ? "T00:00:00.000Z" : "T23:59:59.999Z"}`;
|
|
73
|
-
}
|
|
74
|
-
const parsed = new Date(normalized);
|
|
75
|
-
if (Number.isNaN(parsed.getTime())) {
|
|
76
|
-
throw new Error(`Invalid date '${normalized}'. Expected YYYY-MM-DD or a valid date-time string.`);
|
|
77
|
-
}
|
|
78
|
-
return parsed.toISOString();
|
|
79
|
-
}
|
|
80
|
-
function appendAgentFilter(conditions, args, fieldName, agentId) {
|
|
81
|
-
if (agentId === null) {
|
|
82
|
-
conditions.push(`${fieldName} IS NULL`);
|
|
83
|
-
return;
|
|
84
|
-
}
|
|
85
|
-
if (agentId) {
|
|
86
|
-
conditions.push(`${fieldName} = ?`);
|
|
87
|
-
args.push(agentId);
|
|
88
|
-
}
|
|
89
|
-
}
|
|
90
|
-
function buildTelemetryWhere(params) {
|
|
91
|
-
const conditions = ["1=1"];
|
|
92
|
-
const args = [];
|
|
93
|
-
appendAgentFilter(conditions, args, "agent_id", params.agent_id);
|
|
94
|
-
if (params.client_name) {
|
|
95
|
-
conditions.push("client_name = ?");
|
|
96
|
-
args.push(params.client_name);
|
|
97
|
-
}
|
|
98
|
-
if (params.mcp_version) {
|
|
99
|
-
conditions.push("mcp_version = ?");
|
|
100
|
-
args.push(params.mcp_version);
|
|
101
|
-
}
|
|
102
|
-
const dateFrom = normalizeDateBoundary(params.date_from, "start");
|
|
103
|
-
if (dateFrom) {
|
|
104
|
-
conditions.push("created_at >= ?");
|
|
105
|
-
args.push(dateFrom);
|
|
106
|
-
}
|
|
107
|
-
const dateTo = normalizeDateBoundary(params.date_to, "end");
|
|
108
|
-
if (dateTo) {
|
|
109
|
-
conditions.push("created_at <= ?");
|
|
110
|
-
args.push(dateTo);
|
|
111
|
-
}
|
|
112
|
-
return { clause: conditions.join(" AND "), args };
|
|
113
|
-
}
|
|
114
|
-
function buildSessionWhere(params,
|
|
115
|
-
// Set when the query joins reasoning_steps: both tables have created_at,
|
|
116
|
-
// so unqualified column names are ambiguous.
|
|
117
|
-
columnPrefix = "") {
|
|
118
|
-
const conditions = ["1=1"];
|
|
119
|
-
const args = [];
|
|
120
|
-
appendAgentFilter(conditions, args, `${columnPrefix}agent_id`, params.agent_id);
|
|
121
|
-
const dateFrom = normalizeDateBoundary(params.date_from, "start");
|
|
122
|
-
if (dateFrom) {
|
|
123
|
-
conditions.push(`${columnPrefix}created_at >= ?`);
|
|
124
|
-
args.push(dateFrom);
|
|
125
|
-
}
|
|
126
|
-
const dateTo = normalizeDateBoundary(params.date_to, "end");
|
|
127
|
-
if (dateTo) {
|
|
128
|
-
conditions.push(`${columnPrefix}created_at <= ?`);
|
|
129
|
-
args.push(dateTo);
|
|
130
|
-
}
|
|
131
|
-
return { clause: conditions.join(" AND "), args };
|
|
132
|
-
}
|
|
133
51
|
let defaultDatabasePromise = null;
|
|
134
52
|
async function resolveDatabase(database) {
|
|
135
53
|
if (database)
|
|
@@ -139,77 +57,9 @@ async function resolveDatabase(database) {
|
|
|
139
57
|
}
|
|
140
58
|
export function registerMemoryTools(server, database) {
|
|
141
59
|
const databaseProvider = () => resolveDatabase(database);
|
|
142
|
-
server.registerTool("memory_save", {
|
|
143
|
-
title: "Save Memory",
|
|
144
|
-
description: "Persist a piece of long-term memory so it can be recalled in future sessions. Returns the created memory's id. Tags describe topics ('sqlite', 'auth', 'perf'), not locations — do not put workspace or project names in tags. Pass workspace (your project directory) so the memory is scoped to this project; if omitted the server records its own working directory, and '/' or the home directory are stored as unknown.",
|
|
145
|
-
inputSchema: MemorySaveInputSchema.shape,
|
|
146
|
-
annotations: {
|
|
147
|
-
readOnlyHint: false,
|
|
148
|
-
destructiveHint: false,
|
|
149
|
-
idempotentHint: false,
|
|
150
|
-
openWorldHint: false,
|
|
151
|
-
},
|
|
152
|
-
}, withTelemetry({
|
|
153
|
-
database: databaseProvider,
|
|
154
|
-
toolName: "memory_save",
|
|
155
|
-
operationType: "memory",
|
|
156
|
-
accessType: "write",
|
|
157
|
-
buildEvent: (params, result) => {
|
|
158
|
-
const structured = extractStructuredContent(result);
|
|
159
|
-
return {
|
|
160
|
-
agentId: params.agent_id ?? null,
|
|
161
|
-
memoryId: typeof structured?.id === "string" ? structured.id : null,
|
|
162
|
-
inputShape: {
|
|
163
|
-
content_length: params.content.length,
|
|
164
|
-
type: params.type,
|
|
165
|
-
tag_count: params.tags?.length ?? 0,
|
|
166
|
-
importance: params.importance,
|
|
167
|
-
},
|
|
168
|
-
outputShape: structured
|
|
169
|
-
? {
|
|
170
|
-
memory_id: structured.id,
|
|
171
|
-
type: structured.type,
|
|
172
|
-
tag_count: Array.isArray(structured.tags) ? structured.tags.length : 0,
|
|
173
|
-
}
|
|
174
|
-
: null,
|
|
175
|
-
};
|
|
176
|
-
},
|
|
177
|
-
}, async (params) => {
|
|
178
|
-
const activeDb = await resolveDatabase(database);
|
|
179
|
-
const id = newId("mem");
|
|
180
|
-
const ts = nowIso();
|
|
181
|
-
activeDb
|
|
182
|
-
.prepare(`INSERT INTO memories (id, type, content, tags, agent_id, importance, metadata, workspace, created_at, updated_at)
|
|
183
|
-
VALUES (@id, @type, @content, @tags, @agent_id, @importance, @metadata, @workspace, @created_at, @updated_at)`)
|
|
184
|
-
.run({
|
|
185
|
-
id,
|
|
186
|
-
type: params.type,
|
|
187
|
-
content: params.content,
|
|
188
|
-
tags: JSON.stringify(params.tags ?? []),
|
|
189
|
-
agent_id: params.agent_id ?? null,
|
|
190
|
-
importance: params.importance,
|
|
191
|
-
metadata: params.metadata ? JSON.stringify(params.metadata) : null,
|
|
192
|
-
workspace: getWorkspace(params.workspace),
|
|
193
|
-
created_at: ts,
|
|
194
|
-
updated_at: ts,
|
|
195
|
-
});
|
|
196
|
-
const row = activeDb
|
|
197
|
-
.prepare(`SELECT * FROM memories WHERE id = ?`)
|
|
198
|
-
.get(id);
|
|
199
|
-
const record = rowToRecord(row);
|
|
200
|
-
return {
|
|
201
|
-
content: [
|
|
202
|
-
{
|
|
203
|
-
type: "text",
|
|
204
|
-
text: `Memory saved with id ${id}.\n\n${toLimitedJson(record)}`,
|
|
205
|
-
},
|
|
206
|
-
],
|
|
207
|
-
structuredContent: record,
|
|
208
|
-
};
|
|
209
|
-
}));
|
|
210
60
|
server.registerTool("memory_search", {
|
|
211
61
|
title: "Search Memories",
|
|
212
|
-
description: "
|
|
62
|
+
description: "Recall saved memories on a topic other than your session title (reasoning_start_session already recalls the title). Any query term may match; queries with 3+ terms need at least 2. Ranked by term coverage, relevance and recency.",
|
|
213
63
|
inputSchema: MemorySearchInputSchema.shape,
|
|
214
64
|
annotations: {
|
|
215
65
|
readOnlyHint: true,
|
|
@@ -320,76 +170,6 @@ export function registerMemoryTools(server, database) {
|
|
|
320
170
|
structuredContent: output,
|
|
321
171
|
};
|
|
322
172
|
}));
|
|
323
|
-
server.registerTool("memory_list", {
|
|
324
|
-
title: "List Memories",
|
|
325
|
-
description: "List saved memories with optional filters (type, agent_id, tags, min_importance), sorted by created_at, updated_at (default, newest first), or importance.",
|
|
326
|
-
inputSchema: MemoryListInputSchema.shape,
|
|
327
|
-
annotations: {
|
|
328
|
-
readOnlyHint: true,
|
|
329
|
-
destructiveHint: false,
|
|
330
|
-
idempotentHint: true,
|
|
331
|
-
openWorldHint: false,
|
|
332
|
-
},
|
|
333
|
-
}, withTelemetry({
|
|
334
|
-
database: databaseProvider,
|
|
335
|
-
toolName: "memory_list",
|
|
336
|
-
operationType: "memory",
|
|
337
|
-
accessType: "read",
|
|
338
|
-
buildEvent: (params, result) => ({
|
|
339
|
-
agentId: params.agent_id ?? null,
|
|
340
|
-
inputShape: {
|
|
341
|
-
has_type: params.type !== undefined,
|
|
342
|
-
has_agent_id: params.agent_id !== undefined,
|
|
343
|
-
has_tags: (params.tags?.length ?? 0) > 0,
|
|
344
|
-
min_importance: params.min_importance ?? null,
|
|
345
|
-
sort_by: params.sort_by,
|
|
346
|
-
limit: params.limit,
|
|
347
|
-
},
|
|
348
|
-
outputShape: {
|
|
349
|
-
result_count: resultCount(result),
|
|
350
|
-
has_more: extractStructuredContent(result)?.has_more === true,
|
|
351
|
-
memory_ids: returnedMemoryIds(result),
|
|
352
|
-
},
|
|
353
|
-
}),
|
|
354
|
-
}, async (params) => {
|
|
355
|
-
const activeDb = await resolveDatabase(database);
|
|
356
|
-
const { clause: tagClause, params: tagParams } = tagsFilterClauses(params.tags);
|
|
357
|
-
const conditions = ["1=1"];
|
|
358
|
-
const sqlParams = [];
|
|
359
|
-
if (params.type) {
|
|
360
|
-
conditions.push("type = ?");
|
|
361
|
-
sqlParams.push(params.type);
|
|
362
|
-
}
|
|
363
|
-
if (params.agent_id) {
|
|
364
|
-
conditions.push("agent_id = ?");
|
|
365
|
-
sqlParams.push(params.agent_id);
|
|
366
|
-
}
|
|
367
|
-
if (params.min_importance !== undefined) {
|
|
368
|
-
conditions.push("importance >= ?");
|
|
369
|
-
sqlParams.push(params.min_importance);
|
|
370
|
-
}
|
|
371
|
-
const countRow = activeDb
|
|
372
|
-
.prepare(`SELECT COUNT(*) as c FROM memories WHERE ${conditions.join(" AND ")}${tagClause}`)
|
|
373
|
-
.get(...sqlParams, ...tagParams);
|
|
374
|
-
const rows = activeDb
|
|
375
|
-
.prepare(`SELECT * FROM memories WHERE ${conditions.join(" AND ")}${tagClause}
|
|
376
|
-
ORDER BY ${params.sort_by} DESC LIMIT ? OFFSET ?`)
|
|
377
|
-
.all(...sqlParams, ...tagParams, params.limit, params.offset);
|
|
378
|
-
const results = rows.map(rowToRecord);
|
|
379
|
-
const hasMore = countRow.c > params.offset + results.length;
|
|
380
|
-
const output = {
|
|
381
|
-
total: countRow.c,
|
|
382
|
-
total_returned: results.length,
|
|
383
|
-
offset: params.offset,
|
|
384
|
-
has_more: hasMore,
|
|
385
|
-
...(hasMore ? { next_offset: params.offset + results.length } : {}),
|
|
386
|
-
results,
|
|
387
|
-
};
|
|
388
|
-
return {
|
|
389
|
-
content: [{ type: "text", text: toLimitedJson(output) }],
|
|
390
|
-
structuredContent: output,
|
|
391
|
-
};
|
|
392
|
-
}));
|
|
393
173
|
server.registerTool("memory_get", {
|
|
394
174
|
title: "Get Memory",
|
|
395
175
|
description: "Retrieve a single memory by its id.",
|
|
@@ -436,7 +216,7 @@ export function registerMemoryTools(server, database) {
|
|
|
436
216
|
}));
|
|
437
217
|
server.registerTool("memory_update", {
|
|
438
218
|
title: "Update Memory",
|
|
439
|
-
description: "
|
|
219
|
+
description: "Correct a recalled memory that turned out wrong or outdated. Only the fields you pass change. `tags`/`metadata` replace the whole value; `tags_append`/`tags_remove`/`metadata_patch` change it incrementally. Pass at least one field.",
|
|
440
220
|
inputSchema: MemoryUpdateInputSchema.shape,
|
|
441
221
|
annotations: {
|
|
442
222
|
readOnlyHint: false,
|
|
@@ -547,433 +327,6 @@ export function registerMemoryTools(server, database) {
|
|
|
547
327
|
structuredContent: record,
|
|
548
328
|
};
|
|
549
329
|
}));
|
|
550
|
-
server.registerTool("memory_delete", {
|
|
551
|
-
title: "Delete Memory",
|
|
552
|
-
description: "Permanently delete a memory by id. Hard delete with no undo — prefer memory_update when the memory is merely wrong or outdated.",
|
|
553
|
-
inputSchema: MemoryDeleteInputSchema.shape,
|
|
554
|
-
annotations: {
|
|
555
|
-
readOnlyHint: false,
|
|
556
|
-
destructiveHint: true,
|
|
557
|
-
idempotentHint: true,
|
|
558
|
-
openWorldHint: false,
|
|
559
|
-
},
|
|
560
|
-
}, withTelemetry({
|
|
561
|
-
database: databaseProvider,
|
|
562
|
-
toolName: "memory_delete",
|
|
563
|
-
operationType: "memory",
|
|
564
|
-
accessType: "delete",
|
|
565
|
-
buildEvent: (params) => ({
|
|
566
|
-
memoryId: params.id,
|
|
567
|
-
outputShape: { deleted: true },
|
|
568
|
-
}),
|
|
569
|
-
}, async (params) => {
|
|
570
|
-
const activeDb = await resolveDatabase(database);
|
|
571
|
-
const result = activeDb.prepare(`DELETE FROM memories WHERE id = ?`).run(params.id);
|
|
572
|
-
if (result.changes === 0) {
|
|
573
|
-
return {
|
|
574
|
-
content: [
|
|
575
|
-
{
|
|
576
|
-
type: "text",
|
|
577
|
-
text: `Error: Memory '${params.id}' not found.`,
|
|
578
|
-
},
|
|
579
|
-
],
|
|
580
|
-
isError: true,
|
|
581
|
-
};
|
|
582
|
-
}
|
|
583
|
-
return {
|
|
584
|
-
content: [
|
|
585
|
-
{
|
|
586
|
-
type: "text",
|
|
587
|
-
text: `Memory '${params.id}' deleted.`,
|
|
588
|
-
},
|
|
589
|
-
],
|
|
590
|
-
};
|
|
591
|
-
}));
|
|
592
|
-
server.registerTool("memory_usage_report", {
|
|
593
|
-
title: "Memory Usage Report",
|
|
594
|
-
description: "Aggregate tool usage events by tool, agent, client, version, operation type, status, or day. With MEMORY_TELEMETRY off (the default) only usage-feedback events exist, so most groupings are empty; full aggregates need MEMORY_TELEMETRY=on.",
|
|
595
|
-
inputSchema: MemoryUsageReportInputSchema.shape,
|
|
596
|
-
annotations: {
|
|
597
|
-
readOnlyHint: true,
|
|
598
|
-
destructiveHint: false,
|
|
599
|
-
idempotentHint: true,
|
|
600
|
-
openWorldHint: false,
|
|
601
|
-
},
|
|
602
|
-
}, withTelemetry({
|
|
603
|
-
database: databaseProvider,
|
|
604
|
-
toolName: "memory_usage_report",
|
|
605
|
-
operationType: "report",
|
|
606
|
-
accessType: "derived",
|
|
607
|
-
buildEvent: (_params, result) => ({
|
|
608
|
-
outputShape: {
|
|
609
|
-
row_count: Array.isArray(extractStructuredContent(result)?.groups)
|
|
610
|
-
? (extractStructuredContent(result)?.groups).length
|
|
611
|
-
: 0,
|
|
612
|
-
},
|
|
613
|
-
}),
|
|
614
|
-
}, async (params) => {
|
|
615
|
-
const activeDb = await resolveDatabase(database);
|
|
616
|
-
const { clause, args } = buildTelemetryWhere(params);
|
|
617
|
-
const groupBySql = {
|
|
618
|
-
tool_name: "tool_name",
|
|
619
|
-
agent_id: "COALESCE(agent_id, 'unknown')",
|
|
620
|
-
client_name: "COALESCE(client_name, 'unknown')",
|
|
621
|
-
mcp_version: "mcp_version",
|
|
622
|
-
operation_type: "operation_type",
|
|
623
|
-
status: "status",
|
|
624
|
-
day: "substr(created_at, 1, 10)",
|
|
625
|
-
};
|
|
626
|
-
const summaryRow = activeDb
|
|
627
|
-
.prepare(`SELECT
|
|
628
|
-
COUNT(*) as total_events,
|
|
629
|
-
SUM(CASE WHEN status = 'success' THEN 1 ELSE 0 END) as success_events,
|
|
630
|
-
SUM(CASE WHEN status = 'error' THEN 1 ELSE 0 END) as error_events
|
|
631
|
-
FROM tool_usage_events
|
|
632
|
-
WHERE ${clause}`)
|
|
633
|
-
.get(...args);
|
|
634
|
-
const groups = activeDb
|
|
635
|
-
.prepare(`SELECT
|
|
636
|
-
${groupBySql[params.group_by]} as key,
|
|
637
|
-
COUNT(*) as event_count,
|
|
638
|
-
SUM(CASE WHEN status = 'success' THEN 1 ELSE 0 END) as success_count,
|
|
639
|
-
SUM(CASE WHEN status = 'error' THEN 1 ELSE 0 END) as error_count
|
|
640
|
-
FROM tool_usage_events
|
|
641
|
-
WHERE ${clause}
|
|
642
|
-
GROUP BY key
|
|
643
|
-
ORDER BY event_count DESC, key ASC
|
|
644
|
-
LIMIT ?`)
|
|
645
|
-
.all(...args, params.limit);
|
|
646
|
-
const topErrors = activeDb
|
|
647
|
-
.prepare(`SELECT
|
|
648
|
-
COALESCE(error_code, 'unknown') as error_code,
|
|
649
|
-
COUNT(*) as count
|
|
650
|
-
FROM tool_usage_events
|
|
651
|
-
WHERE ${clause} AND status = 'error'
|
|
652
|
-
GROUP BY error_code
|
|
653
|
-
ORDER BY count DESC, error_code ASC
|
|
654
|
-
LIMIT 10`)
|
|
655
|
-
.all(...args);
|
|
656
|
-
const totalEvents = summaryRow.total_events ?? 0;
|
|
657
|
-
const successEvents = summaryRow.success_events ?? 0;
|
|
658
|
-
const errorEvents = summaryRow.error_events ?? 0;
|
|
659
|
-
const output = {
|
|
660
|
-
...telemetryOffNote(),
|
|
661
|
-
summary: {
|
|
662
|
-
total_events: totalEvents,
|
|
663
|
-
success_events: successEvents,
|
|
664
|
-
error_events: errorEvents,
|
|
665
|
-
success_rate: totalEvents === 0 ? 0 : successEvents / totalEvents,
|
|
666
|
-
error_rate: totalEvents === 0 ? 0 : errorEvents / totalEvents,
|
|
667
|
-
},
|
|
668
|
-
groups,
|
|
669
|
-
top_errors: topErrors,
|
|
670
|
-
time_range: {
|
|
671
|
-
date_from: params.date_from ?? null,
|
|
672
|
-
date_to: params.date_to ?? null,
|
|
673
|
-
},
|
|
674
|
-
};
|
|
675
|
-
return {
|
|
676
|
-
content: [{ type: "text", text: toLimitedJson(output) }],
|
|
677
|
-
structuredContent: output,
|
|
678
|
-
};
|
|
679
|
-
}));
|
|
680
|
-
server.registerTool("memory_adoption_report", {
|
|
681
|
-
title: "Memory Adoption Report",
|
|
682
|
-
description: "Summarize reasoning and memory adoption behavior using telemetry plus core session tables. With MEMORY_TELEMETRY off (the default) only usage-feedback events and session tables have data, so funnel counts and ratios that need recall/search events require MEMORY_TELEMETRY=on.",
|
|
683
|
-
inputSchema: MemoryAdoptionReportInputSchema.shape,
|
|
684
|
-
annotations: {
|
|
685
|
-
readOnlyHint: true,
|
|
686
|
-
destructiveHint: false,
|
|
687
|
-
idempotentHint: true,
|
|
688
|
-
openWorldHint: false,
|
|
689
|
-
},
|
|
690
|
-
}, withTelemetry({
|
|
691
|
-
database: databaseProvider,
|
|
692
|
-
toolName: "memory_adoption_report",
|
|
693
|
-
operationType: "report",
|
|
694
|
-
accessType: "derived",
|
|
695
|
-
buildEvent: (_params, result) => ({
|
|
696
|
-
outputShape: {
|
|
697
|
-
row_count: Array.isArray(extractStructuredContent(result)?.agent_breakdown)
|
|
698
|
-
? (extractStructuredContent(result)?.agent_breakdown).length
|
|
699
|
-
: 0,
|
|
700
|
-
},
|
|
701
|
-
}),
|
|
702
|
-
}, async (params) => {
|
|
703
|
-
const activeDb = await resolveDatabase(database);
|
|
704
|
-
const sessionFilter = buildSessionWhere(params);
|
|
705
|
-
const eventFilter = buildTelemetryWhere(params);
|
|
706
|
-
const sessionSummary = activeDb
|
|
707
|
-
.prepare(`SELECT
|
|
708
|
-
COUNT(*) as reasoning_started,
|
|
709
|
-
SUM(CASE WHEN status = 'completed' THEN 1 ELSE 0 END) as reasoning_completed,
|
|
710
|
-
SUM(CASE WHEN status = 'abandoned' THEN 1 ELSE 0 END) as reasoning_abandoned
|
|
711
|
-
FROM reasoning_sessions
|
|
712
|
-
WHERE ${sessionFilter.clause}`)
|
|
713
|
-
.get(...sessionFilter.args);
|
|
714
|
-
const joinedSessionFilter = buildSessionWhere(params, "reasoning_sessions.");
|
|
715
|
-
const zeroStepRow = activeDb
|
|
716
|
-
.prepare(`SELECT COUNT(*) as zero_step_sessions
|
|
717
|
-
FROM reasoning_sessions
|
|
718
|
-
LEFT JOIN reasoning_steps
|
|
719
|
-
ON reasoning_steps.session_id = reasoning_sessions.id
|
|
720
|
-
WHERE ${joinedSessionFilter.clause}
|
|
721
|
-
GROUP BY reasoning_sessions.id
|
|
722
|
-
HAVING COUNT(reasoning_steps.id) = 0`)
|
|
723
|
-
.all(...joinedSessionFilter.args);
|
|
724
|
-
const completionEvents = activeDb
|
|
725
|
-
.prepare(`SELECT
|
|
726
|
-
COUNT(*) as total,
|
|
727
|
-
SUM(CASE WHEN json_extract(output_shape, '$.memory_id_present') = 1 THEN 1 ELSE 0 END) as with_memory,
|
|
728
|
-
SUM(CASE WHEN json_extract(output_shape, '$.memory_id_present') = 0 THEN 1 ELSE 0 END) as without_memory
|
|
729
|
-
FROM tool_usage_events
|
|
730
|
-
WHERE ${eventFilter.clause}
|
|
731
|
-
AND tool_name = 'reasoning_complete_session'
|
|
732
|
-
AND status = 'success'`)
|
|
733
|
-
.get(...eventFilter.args);
|
|
734
|
-
const skipReasonRows = activeDb
|
|
735
|
-
.prepare(`SELECT
|
|
736
|
-
COALESCE(json_extract(output_shape, '$.not_saved_reason_category'), 'none') as reason,
|
|
737
|
-
COUNT(*) as count
|
|
738
|
-
FROM tool_usage_events
|
|
739
|
-
WHERE ${eventFilter.clause}
|
|
740
|
-
AND tool_name = 'reasoning_complete_session'
|
|
741
|
-
AND status = 'success'
|
|
742
|
-
AND json_extract(output_shape, '$.not_saved_reason_category') IS NOT NULL
|
|
743
|
-
GROUP BY reason
|
|
744
|
-
ORDER BY count DESC, reason ASC`)
|
|
745
|
-
.all(...eventFilter.args);
|
|
746
|
-
const eventSummary = activeDb
|
|
747
|
-
.prepare(`SELECT
|
|
748
|
-
SUM(CASE WHEN tool_name = 'memory_save' AND status = 'success' THEN 1 ELSE 0 END) as direct_memory_saved,
|
|
749
|
-
SUM(CASE WHEN tool_name IN ('memory_search', 'memory_list', 'memory_get') AND status = 'success' THEN 1 ELSE 0 END) as memory_searched,
|
|
750
|
-
SUM(CASE WHEN tool_name = 'memory_update' AND status = 'success' THEN 1 ELSE 0 END) as memory_updated,
|
|
751
|
-
SUM(CASE
|
|
752
|
-
WHEN tool_name = 'memory_search' AND status = 'success'
|
|
753
|
-
THEN COALESCE(json_extract(output_shape, '$.result_count'), 0)
|
|
754
|
-
WHEN tool_name = 'memory_list' AND status = 'success'
|
|
755
|
-
THEN COALESCE(json_extract(output_shape, '$.result_count'), 0)
|
|
756
|
-
WHEN tool_name = 'memory_get' AND status = 'success'
|
|
757
|
-
AND COALESCE(json_extract(output_shape, '$.found'), 0) = 1
|
|
758
|
-
THEN 1
|
|
759
|
-
ELSE 0
|
|
760
|
-
END) as memory_recalled
|
|
761
|
-
FROM tool_usage_events
|
|
762
|
-
WHERE ${eventFilter.clause}`)
|
|
763
|
-
.get(...eventFilter.args);
|
|
764
|
-
const feedbackSummary = activeDb
|
|
765
|
-
.prepare(`SELECT
|
|
766
|
-
SUM(CASE WHEN json_extract(metadata, '$.usefulness') = 'used' THEN 1 ELSE 0 END) as used_count
|
|
767
|
-
FROM tool_usage_events
|
|
768
|
-
WHERE ${eventFilter.clause}
|
|
769
|
-
AND operation_type = 'feedback'
|
|
770
|
-
AND status = 'success'`)
|
|
771
|
-
.get(...eventFilter.args);
|
|
772
|
-
const agentBreakdown = activeDb
|
|
773
|
-
.prepare(`SELECT
|
|
774
|
-
COALESCE(agent_id, 'unknown') as agent_id,
|
|
775
|
-
COUNT(*) as event_count
|
|
776
|
-
FROM tool_usage_events
|
|
777
|
-
WHERE ${eventFilter.clause}
|
|
778
|
-
GROUP BY agent_id
|
|
779
|
-
ORDER BY event_count DESC, agent_id ASC
|
|
780
|
-
LIMIT ?`)
|
|
781
|
-
.all(...eventFilter.args, params.limit);
|
|
782
|
-
const versionBreakdown = activeDb
|
|
783
|
-
.prepare(`SELECT
|
|
784
|
-
mcp_version,
|
|
785
|
-
COUNT(*) as event_count
|
|
786
|
-
FROM tool_usage_events
|
|
787
|
-
WHERE ${eventFilter.clause}
|
|
788
|
-
GROUP BY mcp_version
|
|
789
|
-
ORDER BY event_count DESC, mcp_version ASC`)
|
|
790
|
-
.all(...eventFilter.args);
|
|
791
|
-
const reasoningStarted = sessionSummary.reasoning_started ?? 0;
|
|
792
|
-
const reasoningCompleted = sessionSummary.reasoning_completed ?? 0;
|
|
793
|
-
const zeroStepSessions = zeroStepRow.length;
|
|
794
|
-
const completedWithMemory = completionEvents.with_memory ?? 0;
|
|
795
|
-
const completedWithoutMemory = completionEvents.without_memory ?? 0;
|
|
796
|
-
const memorySaved = (eventSummary.direct_memory_saved ?? 0) + completedWithMemory;
|
|
797
|
-
const riskFlags = [];
|
|
798
|
-
if (reasoningStarted > 0 && zeroStepSessions / reasoningStarted > 0.25) {
|
|
799
|
-
riskFlags.push("high_zero_step_session_rate");
|
|
800
|
-
}
|
|
801
|
-
if (reasoningCompleted > 0 && completedWithMemory / reasoningCompleted < 0.3) {
|
|
802
|
-
riskFlags.push("low_completion_to_memory_rate");
|
|
803
|
-
}
|
|
804
|
-
if ((eventSummary.memory_searched ?? 0) > 0 && (feedbackSummary.used_count ?? 0) === 0) {
|
|
805
|
-
riskFlags.push("no_positive_feedback_recorded");
|
|
806
|
-
}
|
|
807
|
-
const output = {
|
|
808
|
-
...telemetryOffNote(),
|
|
809
|
-
funnel: {
|
|
810
|
-
reasoning_started: reasoningStarted,
|
|
811
|
-
reasoning_completed: reasoningCompleted,
|
|
812
|
-
reasoning_abandoned: sessionSummary.reasoning_abandoned ?? 0,
|
|
813
|
-
zero_step_sessions: zeroStepSessions,
|
|
814
|
-
completed_with_memory: completedWithMemory,
|
|
815
|
-
completed_without_memory: completedWithoutMemory,
|
|
816
|
-
skip_reason_count: skipReasonRows,
|
|
817
|
-
memory_saved: memorySaved,
|
|
818
|
-
memory_searched: eventSummary.memory_searched ?? 0,
|
|
819
|
-
memory_recalled: eventSummary.memory_recalled ?? 0,
|
|
820
|
-
memory_updated: eventSummary.memory_updated ?? 0,
|
|
821
|
-
feedback_used: feedbackSummary.used_count ?? 0,
|
|
822
|
-
},
|
|
823
|
-
agent_breakdown: agentBreakdown,
|
|
824
|
-
version_breakdown: versionBreakdown,
|
|
825
|
-
risk_flags: riskFlags,
|
|
826
|
-
};
|
|
827
|
-
return {
|
|
828
|
-
content: [{ type: "text", text: toLimitedJson(output) }],
|
|
829
|
-
structuredContent: output,
|
|
830
|
-
};
|
|
831
|
-
}));
|
|
832
|
-
server.registerTool("memory_agent_scorecard", {
|
|
833
|
-
title: "Memory Agent Scorecard",
|
|
834
|
-
description: "Compare how different agents use memory and reasoning tools in practice. With MEMORY_TELEMETRY off (the default) only usage-feedback events are recorded, so per-agent activity counts require MEMORY_TELEMETRY=on.",
|
|
835
|
-
inputSchema: MemoryAgentScorecardInputSchema.shape,
|
|
836
|
-
annotations: {
|
|
837
|
-
readOnlyHint: true,
|
|
838
|
-
destructiveHint: false,
|
|
839
|
-
idempotentHint: true,
|
|
840
|
-
openWorldHint: false,
|
|
841
|
-
},
|
|
842
|
-
}, withTelemetry({
|
|
843
|
-
database: databaseProvider,
|
|
844
|
-
toolName: "memory_agent_scorecard",
|
|
845
|
-
operationType: "report",
|
|
846
|
-
accessType: "derived",
|
|
847
|
-
buildEvent: (_params, result) => ({
|
|
848
|
-
outputShape: {
|
|
849
|
-
row_count: Array.isArray(extractStructuredContent(result)?.results)
|
|
850
|
-
? (extractStructuredContent(result)?.results).length
|
|
851
|
-
: 0,
|
|
852
|
-
},
|
|
853
|
-
}),
|
|
854
|
-
}, async (params) => {
|
|
855
|
-
const activeDb = await resolveDatabase(database);
|
|
856
|
-
const sessionFilter = buildSessionWhere(params);
|
|
857
|
-
const telemetryFilter = buildTelemetryWhere({
|
|
858
|
-
agent_id: params.agent_id,
|
|
859
|
-
date_from: params.date_from,
|
|
860
|
-
date_to: params.date_to,
|
|
861
|
-
});
|
|
862
|
-
const rows = activeDb
|
|
863
|
-
.prepare(`SELECT DISTINCT COALESCE(agent_id, 'unknown') as agent_id
|
|
864
|
-
FROM tool_usage_events
|
|
865
|
-
WHERE ${telemetryFilter.clause}
|
|
866
|
-
AND operation_type IN ('memory', 'reasoning', 'feedback')
|
|
867
|
-
UNION
|
|
868
|
-
SELECT DISTINCT COALESCE(agent_id, 'unknown') as agent_id
|
|
869
|
-
FROM reasoning_sessions
|
|
870
|
-
WHERE ${sessionFilter.clause}
|
|
871
|
-
LIMIT ?`)
|
|
872
|
-
.all(...telemetryFilter.args, ...sessionFilter.args, params.limit);
|
|
873
|
-
const results = rows.map((row) => {
|
|
874
|
-
const agentId = row.agent_id === "unknown" ? null : row.agent_id;
|
|
875
|
-
// Qualified so the same filter works in the reasoning_steps JOIN
|
|
876
|
-
// below; the prefix is harmless in the unjoined query.
|
|
877
|
-
const agentSessionFilter = buildSessionWhere({
|
|
878
|
-
agent_id: agentId,
|
|
879
|
-
date_from: params.date_from,
|
|
880
|
-
date_to: params.date_to,
|
|
881
|
-
}, "reasoning_sessions.");
|
|
882
|
-
const agentEventFilter = buildTelemetryWhere({
|
|
883
|
-
agent_id: agentId,
|
|
884
|
-
date_from: params.date_from,
|
|
885
|
-
date_to: params.date_to,
|
|
886
|
-
});
|
|
887
|
-
const sessionSummary = activeDb
|
|
888
|
-
.prepare(`SELECT
|
|
889
|
-
COUNT(*) as started,
|
|
890
|
-
SUM(CASE WHEN status = 'completed' THEN 1 ELSE 0 END) as completed
|
|
891
|
-
FROM reasoning_sessions
|
|
892
|
-
WHERE ${agentSessionFilter.clause}`)
|
|
893
|
-
.get(...agentSessionFilter.args);
|
|
894
|
-
const avgStepsRow = activeDb
|
|
895
|
-
.prepare(`SELECT AVG(step_count) as avg_steps
|
|
896
|
-
FROM (
|
|
897
|
-
SELECT reasoning_sessions.id, COUNT(reasoning_steps.id) as step_count
|
|
898
|
-
FROM reasoning_sessions
|
|
899
|
-
LEFT JOIN reasoning_steps
|
|
900
|
-
ON reasoning_steps.session_id = reasoning_sessions.id
|
|
901
|
-
WHERE ${agentSessionFilter.clause}
|
|
902
|
-
GROUP BY reasoning_sessions.id
|
|
903
|
-
)`)
|
|
904
|
-
.get(...agentSessionFilter.args);
|
|
905
|
-
const eventSummary = activeDb
|
|
906
|
-
.prepare(`SELECT
|
|
907
|
-
COUNT(*) as total_events,
|
|
908
|
-
SUM(CASE WHEN status = 'error' THEN 1 ELSE 0 END) as error_events,
|
|
909
|
-
SUM(CASE WHEN tool_name IN ('memory_search', 'memory_list', 'memory_get') AND status = 'success' THEN 1 ELSE 0 END) as search_events,
|
|
910
|
-
SUM(CASE WHEN tool_name = 'memory_save' AND status = 'success' THEN 1 ELSE 0 END) as direct_save_events,
|
|
911
|
-
SUM(CASE WHEN tool_name = 'reasoning_complete_session' AND status = 'success' AND json_extract(output_shape, '$.memory_id_present') = 1 THEN 1 ELSE 0 END) as completion_memory_events
|
|
912
|
-
FROM tool_usage_events
|
|
913
|
-
WHERE ${agentEventFilter.clause}
|
|
914
|
-
AND operation_type IN ('memory', 'reasoning', 'feedback')`)
|
|
915
|
-
.get(...agentEventFilter.args);
|
|
916
|
-
const feedbackUsed = activeDb
|
|
917
|
-
.prepare(`SELECT COUNT(*) as count
|
|
918
|
-
FROM tool_usage_events
|
|
919
|
-
WHERE ${agentEventFilter.clause}
|
|
920
|
-
AND operation_type = 'feedback'
|
|
921
|
-
AND status = 'success'
|
|
922
|
-
AND json_extract(metadata, '$.usefulness') = 'used'`)
|
|
923
|
-
.get(...agentEventFilter.args);
|
|
924
|
-
const sessionsStarted = sessionSummary.started ?? 0;
|
|
925
|
-
const sessionsCompleted = sessionSummary.completed ?? 0;
|
|
926
|
-
const saves = (eventSummary.direct_save_events ?? 0) +
|
|
927
|
-
(eventSummary.completion_memory_events ?? 0);
|
|
928
|
-
const searchRate = sessionsStarted === 0
|
|
929
|
-
? 0
|
|
930
|
-
: (eventSummary.search_events ?? 0) / sessionsStarted;
|
|
931
|
-
const saveRate = sessionsCompleted === 0 ? 0 : saves / sessionsCompleted;
|
|
932
|
-
const reuseRate = saves === 0 ? 0 : feedbackUsed.count / saves;
|
|
933
|
-
const errorRate = eventSummary.total_events === 0
|
|
934
|
-
? 0
|
|
935
|
-
: (eventSummary.error_events ?? 0) / eventSummary.total_events;
|
|
936
|
-
let dominantBehavior = "balanced";
|
|
937
|
-
if (sessionsStarted > 0 && saveRate < 0.3)
|
|
938
|
-
dominantBehavior = "reasoning-heavy";
|
|
939
|
-
if ((eventSummary.search_events ?? 0) === 0 && saves === 0) {
|
|
940
|
-
dominantBehavior = "memory-light";
|
|
941
|
-
}
|
|
942
|
-
if (searchRate > 1 && feedbackUsed.count === 0) {
|
|
943
|
-
dominantBehavior = "search-only";
|
|
944
|
-
}
|
|
945
|
-
if (saves > sessionsCompleted && reuseRate < 0.2) {
|
|
946
|
-
dominantBehavior = "noisy-writer";
|
|
947
|
-
}
|
|
948
|
-
if (errorRate > 0.2)
|
|
949
|
-
dominantBehavior = "error-prone";
|
|
950
|
-
const recommendationMap = {
|
|
951
|
-
balanced: "Current usage is balanced; keep validating save quality with feedback.",
|
|
952
|
-
"reasoning-heavy": "Persist more durable conclusions after completed sessions.",
|
|
953
|
-
"memory-light": "Use memory_search or memory_save when prior context or durable outcomes matter.",
|
|
954
|
-
"search-only": "Record feedback on recalled memories to measure usefulness.",
|
|
955
|
-
"noisy-writer": "Tighten save criteria and favor durable summaries over raw notes.",
|
|
956
|
-
"error-prone": "Audit failing tool calls and validate inputs before writes.",
|
|
957
|
-
};
|
|
958
|
-
return {
|
|
959
|
-
agent_id: row.agent_id,
|
|
960
|
-
sessions_started: sessionsStarted,
|
|
961
|
-
sessions_completed: sessionsCompleted,
|
|
962
|
-
avg_steps_per_session: avgStepsRow.avg_steps ?? 0,
|
|
963
|
-
save_rate: saveRate,
|
|
964
|
-
search_rate: searchRate,
|
|
965
|
-
reuse_rate: reuseRate,
|
|
966
|
-
error_rate: errorRate,
|
|
967
|
-
dominant_behavior: dominantBehavior,
|
|
968
|
-
recommendations: recommendationMap[dominantBehavior],
|
|
969
|
-
};
|
|
970
|
-
});
|
|
971
|
-
const output = { ...telemetryOffNote(), results };
|
|
972
|
-
return {
|
|
973
|
-
content: [{ type: "text", text: toLimitedJson(output) }],
|
|
974
|
-
structuredContent: output,
|
|
975
|
-
};
|
|
976
|
-
}));
|
|
977
330
|
server.registerTool("memory_record_usage_feedback", {
|
|
978
331
|
title: "Record Memory Usage Feedback",
|
|
979
332
|
description: "Record how a recalled memory turned out — usefulness is one of: used, ignored, irrelevant, stale, unsafe_to_use. For the common 'used' case, prefer used_memory_ids on reasoning_complete_session; call this tool directly for tasks without a session, or the moment a recalled memory turns out stale or wrong. Feedback is a first-party learning signal for recall quality and is always persisted locally, regardless of the MEMORY_TELEMETRY setting.",
|
|
@@ -1040,7 +393,7 @@ export function registerMemoryTools(server, database) {
|
|
|
1040
393
|
content: [
|
|
1041
394
|
{
|
|
1042
395
|
type: "text",
|
|
1043
|
-
text: `Error: Related event '${params.event_id}' cannot be verified for memory '${params.memory_id}'. Use an event that recalled this memory (memory_get
|
|
396
|
+
text: `Error: Related event '${params.event_id}' cannot be verified for memory '${params.memory_id}'. Use an event that recalled this memory (memory_get or memory_search).`,
|
|
1044
397
|
},
|
|
1045
398
|
],
|
|
1046
399
|
isError: true,
|