@nhatnguyen9317/memory-mcp-server 1.3.2 → 1.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,6 +1,6 @@
1
- import { MemoryAdoptionReportInputSchema, MemoryAgentScorecardInputSchema, MemoryDeleteInputSchema, MemoryGetInputSchema, MemoryListInputSchema, MemoryRecordUsageFeedbackInputSchema, MemorySaveInputSchema, MemorySearchInputSchema, MemoryUpdateInputSchema, MemoryUsageReportInputSchema, } from "../schemas/memory.js";
2
- import { getWorkspace, isTelemetryEnabled } from "../constants.js";
3
- import { newId, nowIso, parseJsonArray, parseJsonObject, toFtsQuery, toLimitedJson, } from "../utils.js";
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/list call, bounded so telemetry rows stay small. */
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; the server records the workspace automatically.",
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(),
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: "Full-text search over saved memories (content and tags), ranked by relevance. Optional filters: type, agent_id, tags (results must contain all); paginate with limit (default 20, max 200) and offset.",
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,
@@ -240,30 +90,65 @@ export function registerMemoryTools(server, database) {
240
90
  }, async (params) => {
241
91
  const activeDb = await resolveDatabase(database);
242
92
  const { clause: tagClause, params: tagParams } = tagsFilterClauses(params.tags);
93
+ const terms = toSearchTerms(params.query);
243
94
  const conditions = [];
244
- const sqlParams = [toFtsQuery(params.query)];
245
95
  if (params.type) {
246
96
  conditions.push("m.type = ?");
247
- sqlParams.push(params.type);
248
97
  }
249
98
  if (params.agent_id) {
250
99
  conditions.push("m.agent_id = ?");
251
- sqlParams.push(params.agent_id);
252
100
  }
253
101
  if (tagClause) {
254
102
  // tagClause is " AND <clauses>"; strip the prefix to compose here.
255
103
  conditions.push(tagClause.slice(" AND ".length));
256
104
  }
257
- // rank (bm25) sorts best text match first; importance/recency break ties.
258
- const rows = activeDb
259
- .prepare(`SELECT m.* FROM memories m
260
- JOIN (
261
- SELECT rowid, rank FROM memories_fts WHERE memories_fts MATCH ?
262
- ) f ON m.rowid = f.rowid
263
- ${conditions.length > 0 ? `WHERE ${conditions.join(" AND ")}` : ""}
264
- ORDER BY f.rank ASC, m.importance DESC, m.updated_at DESC
265
- LIMIT ? OFFSET ?`)
266
- .all(...sqlParams, ...tagParams, params.limit, params.offset);
105
+ const filterParams = [];
106
+ if (params.type)
107
+ filterParams.push(params.type);
108
+ if (params.agent_id)
109
+ filterParams.push(params.agent_id);
110
+ // Any term may match (OR). `hits` counts how many distinct terms each
111
+ // memory matches (one FTS query per term); the same floor as
112
+ // auto-recall applies: 3+ terms need >= 2 matches, otherwise >= 1.
113
+ // The blended score (same weights as auto-recall, minus the workspace
114
+ // term) is computed here, not in JS, so LIMIT/OFFSET paginate over a
115
+ // stable total order. Window aggregates normalize bm25 within the
116
+ // final eligible set; rank is negative (more negative = better) and
117
+ // all-equal counts as best.
118
+ const floor = terms.length >= 3 ? 2 : 1;
119
+ const rows = terms.length === 0
120
+ ? []
121
+ : activeDb
122
+ .prepare(`WITH hits AS (
123
+ SELECT row_id, COUNT(*) AS matched FROM (
124
+ ${terms
125
+ .map(() => "SELECT rowid AS row_id FROM memories_fts WHERE memories_fts MATCH ?")
126
+ .join(" UNION ALL ")}
127
+ ) GROUP BY row_id
128
+ ),
129
+ eligible AS (
130
+ SELECT m.*, f.rank AS fts_rank, h.matched AS matched_terms
131
+ FROM memories m
132
+ JOIN (
133
+ SELECT rowid, rank FROM memories_fts WHERE memories_fts MATCH ?
134
+ ) f ON m.rowid = f.rowid
135
+ JOIN hits h ON h.row_id = m.rowid
136
+ WHERE h.matched >= ?${conditions.length > 0 ? ` AND ${conditions.join(" AND ")}` : ""}
137
+ )
138
+ SELECT * FROM eligible
139
+ ORDER BY
140
+ ${RECALL_WEIGHTS.coverage} * (matched_terms * 1.0 / ${terms.length})
141
+ + ${RECALL_WEIGHTS.bm25} * COALESCE(
142
+ (MAX(fts_rank) OVER () - fts_rank)
143
+ / NULLIF(MAX(fts_rank) OVER () - MIN(fts_rank) OVER (), 0),
144
+ 1.0)
145
+ + ${RECALL_WEIGHTS.recency} * COALESCE(
146
+ 1.0 / (1.0 + MAX(0.0, julianday('now') - julianday(updated_at))
147
+ / ${RECALL_RECENCY_DAYS}),
148
+ 0.0) DESC,
149
+ importance DESC, updated_at DESC, id ASC
150
+ LIMIT ? OFFSET ?`)
151
+ .all(...terms, terms.join(" OR "), floor, ...filterParams, ...tagParams, params.limit, params.offset);
267
152
  if (rows.length === 0) {
268
153
  return {
269
154
  content: [
@@ -285,76 +170,6 @@ export function registerMemoryTools(server, database) {
285
170
  structuredContent: output,
286
171
  };
287
172
  }));
288
- server.registerTool("memory_list", {
289
- title: "List Memories",
290
- description: "List saved memories with optional filters (type, agent_id, tags, min_importance), sorted by created_at, updated_at (default, newest first), or importance.",
291
- inputSchema: MemoryListInputSchema.shape,
292
- annotations: {
293
- readOnlyHint: true,
294
- destructiveHint: false,
295
- idempotentHint: true,
296
- openWorldHint: false,
297
- },
298
- }, withTelemetry({
299
- database: databaseProvider,
300
- toolName: "memory_list",
301
- operationType: "memory",
302
- accessType: "read",
303
- buildEvent: (params, result) => ({
304
- agentId: params.agent_id ?? null,
305
- inputShape: {
306
- has_type: params.type !== undefined,
307
- has_agent_id: params.agent_id !== undefined,
308
- has_tags: (params.tags?.length ?? 0) > 0,
309
- min_importance: params.min_importance ?? null,
310
- sort_by: params.sort_by,
311
- limit: params.limit,
312
- },
313
- outputShape: {
314
- result_count: resultCount(result),
315
- has_more: extractStructuredContent(result)?.has_more === true,
316
- memory_ids: returnedMemoryIds(result),
317
- },
318
- }),
319
- }, async (params) => {
320
- const activeDb = await resolveDatabase(database);
321
- const { clause: tagClause, params: tagParams } = tagsFilterClauses(params.tags);
322
- const conditions = ["1=1"];
323
- const sqlParams = [];
324
- if (params.type) {
325
- conditions.push("type = ?");
326
- sqlParams.push(params.type);
327
- }
328
- if (params.agent_id) {
329
- conditions.push("agent_id = ?");
330
- sqlParams.push(params.agent_id);
331
- }
332
- if (params.min_importance !== undefined) {
333
- conditions.push("importance >= ?");
334
- sqlParams.push(params.min_importance);
335
- }
336
- const countRow = activeDb
337
- .prepare(`SELECT COUNT(*) as c FROM memories WHERE ${conditions.join(" AND ")}${tagClause}`)
338
- .get(...sqlParams, ...tagParams);
339
- const rows = activeDb
340
- .prepare(`SELECT * FROM memories WHERE ${conditions.join(" AND ")}${tagClause}
341
- ORDER BY ${params.sort_by} DESC LIMIT ? OFFSET ?`)
342
- .all(...sqlParams, ...tagParams, params.limit, params.offset);
343
- const results = rows.map(rowToRecord);
344
- const hasMore = countRow.c > params.offset + results.length;
345
- const output = {
346
- total: countRow.c,
347
- total_returned: results.length,
348
- offset: params.offset,
349
- has_more: hasMore,
350
- ...(hasMore ? { next_offset: params.offset + results.length } : {}),
351
- results,
352
- };
353
- return {
354
- content: [{ type: "text", text: toLimitedJson(output) }],
355
- structuredContent: output,
356
- };
357
- }));
358
173
  server.registerTool("memory_get", {
359
174
  title: "Get Memory",
360
175
  description: "Retrieve a single memory by its id.",
@@ -401,7 +216,7 @@ export function registerMemoryTools(server, database) {
401
216
  }));
402
217
  server.registerTool("memory_update", {
403
218
  title: "Update Memory",
404
- description: "Update one or more fields of an existing memory. Partial update: only the fields you pass change; omitted fields are preserved. `tags`/`metadata` replace the whole value — use `tags_append`/`tags_remove`/`metadata_patch` for incremental changes. At least one updatable field is required.",
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.",
405
220
  inputSchema: MemoryUpdateInputSchema.shape,
406
221
  annotations: {
407
222
  readOnlyHint: false,
@@ -512,433 +327,6 @@ export function registerMemoryTools(server, database) {
512
327
  structuredContent: record,
513
328
  };
514
329
  }));
515
- server.registerTool("memory_delete", {
516
- title: "Delete Memory",
517
- description: "Permanently delete a memory by id. Hard delete with no undo — prefer memory_update when the memory is merely wrong or outdated.",
518
- inputSchema: MemoryDeleteInputSchema.shape,
519
- annotations: {
520
- readOnlyHint: false,
521
- destructiveHint: true,
522
- idempotentHint: true,
523
- openWorldHint: false,
524
- },
525
- }, withTelemetry({
526
- database: databaseProvider,
527
- toolName: "memory_delete",
528
- operationType: "memory",
529
- accessType: "delete",
530
- buildEvent: (params) => ({
531
- memoryId: params.id,
532
- outputShape: { deleted: true },
533
- }),
534
- }, async (params) => {
535
- const activeDb = await resolveDatabase(database);
536
- const result = activeDb.prepare(`DELETE FROM memories WHERE id = ?`).run(params.id);
537
- if (result.changes === 0) {
538
- return {
539
- content: [
540
- {
541
- type: "text",
542
- text: `Error: Memory '${params.id}' not found.`,
543
- },
544
- ],
545
- isError: true,
546
- };
547
- }
548
- return {
549
- content: [
550
- {
551
- type: "text",
552
- text: `Memory '${params.id}' deleted.`,
553
- },
554
- ],
555
- };
556
- }));
557
- server.registerTool("memory_usage_report", {
558
- title: "Memory Usage Report",
559
- 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.",
560
- inputSchema: MemoryUsageReportInputSchema.shape,
561
- annotations: {
562
- readOnlyHint: true,
563
- destructiveHint: false,
564
- idempotentHint: true,
565
- openWorldHint: false,
566
- },
567
- }, withTelemetry({
568
- database: databaseProvider,
569
- toolName: "memory_usage_report",
570
- operationType: "report",
571
- accessType: "derived",
572
- buildEvent: (_params, result) => ({
573
- outputShape: {
574
- row_count: Array.isArray(extractStructuredContent(result)?.groups)
575
- ? (extractStructuredContent(result)?.groups).length
576
- : 0,
577
- },
578
- }),
579
- }, async (params) => {
580
- const activeDb = await resolveDatabase(database);
581
- const { clause, args } = buildTelemetryWhere(params);
582
- const groupBySql = {
583
- tool_name: "tool_name",
584
- agent_id: "COALESCE(agent_id, 'unknown')",
585
- client_name: "COALESCE(client_name, 'unknown')",
586
- mcp_version: "mcp_version",
587
- operation_type: "operation_type",
588
- status: "status",
589
- day: "substr(created_at, 1, 10)",
590
- };
591
- const summaryRow = activeDb
592
- .prepare(`SELECT
593
- COUNT(*) as total_events,
594
- SUM(CASE WHEN status = 'success' THEN 1 ELSE 0 END) as success_events,
595
- SUM(CASE WHEN status = 'error' THEN 1 ELSE 0 END) as error_events
596
- FROM tool_usage_events
597
- WHERE ${clause}`)
598
- .get(...args);
599
- const groups = activeDb
600
- .prepare(`SELECT
601
- ${groupBySql[params.group_by]} as key,
602
- COUNT(*) as event_count,
603
- SUM(CASE WHEN status = 'success' THEN 1 ELSE 0 END) as success_count,
604
- SUM(CASE WHEN status = 'error' THEN 1 ELSE 0 END) as error_count
605
- FROM tool_usage_events
606
- WHERE ${clause}
607
- GROUP BY key
608
- ORDER BY event_count DESC, key ASC
609
- LIMIT ?`)
610
- .all(...args, params.limit);
611
- const topErrors = activeDb
612
- .prepare(`SELECT
613
- COALESCE(error_code, 'unknown') as error_code,
614
- COUNT(*) as count
615
- FROM tool_usage_events
616
- WHERE ${clause} AND status = 'error'
617
- GROUP BY error_code
618
- ORDER BY count DESC, error_code ASC
619
- LIMIT 10`)
620
- .all(...args);
621
- const totalEvents = summaryRow.total_events ?? 0;
622
- const successEvents = summaryRow.success_events ?? 0;
623
- const errorEvents = summaryRow.error_events ?? 0;
624
- const output = {
625
- ...telemetryOffNote(),
626
- summary: {
627
- total_events: totalEvents,
628
- success_events: successEvents,
629
- error_events: errorEvents,
630
- success_rate: totalEvents === 0 ? 0 : successEvents / totalEvents,
631
- error_rate: totalEvents === 0 ? 0 : errorEvents / totalEvents,
632
- },
633
- groups,
634
- top_errors: topErrors,
635
- time_range: {
636
- date_from: params.date_from ?? null,
637
- date_to: params.date_to ?? null,
638
- },
639
- };
640
- return {
641
- content: [{ type: "text", text: toLimitedJson(output) }],
642
- structuredContent: output,
643
- };
644
- }));
645
- server.registerTool("memory_adoption_report", {
646
- title: "Memory Adoption Report",
647
- 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.",
648
- inputSchema: MemoryAdoptionReportInputSchema.shape,
649
- annotations: {
650
- readOnlyHint: true,
651
- destructiveHint: false,
652
- idempotentHint: true,
653
- openWorldHint: false,
654
- },
655
- }, withTelemetry({
656
- database: databaseProvider,
657
- toolName: "memory_adoption_report",
658
- operationType: "report",
659
- accessType: "derived",
660
- buildEvent: (_params, result) => ({
661
- outputShape: {
662
- row_count: Array.isArray(extractStructuredContent(result)?.agent_breakdown)
663
- ? (extractStructuredContent(result)?.agent_breakdown).length
664
- : 0,
665
- },
666
- }),
667
- }, async (params) => {
668
- const activeDb = await resolveDatabase(database);
669
- const sessionFilter = buildSessionWhere(params);
670
- const eventFilter = buildTelemetryWhere(params);
671
- const sessionSummary = activeDb
672
- .prepare(`SELECT
673
- COUNT(*) as reasoning_started,
674
- SUM(CASE WHEN status = 'completed' THEN 1 ELSE 0 END) as reasoning_completed,
675
- SUM(CASE WHEN status = 'abandoned' THEN 1 ELSE 0 END) as reasoning_abandoned
676
- FROM reasoning_sessions
677
- WHERE ${sessionFilter.clause}`)
678
- .get(...sessionFilter.args);
679
- const joinedSessionFilter = buildSessionWhere(params, "reasoning_sessions.");
680
- const zeroStepRow = activeDb
681
- .prepare(`SELECT COUNT(*) as zero_step_sessions
682
- FROM reasoning_sessions
683
- LEFT JOIN reasoning_steps
684
- ON reasoning_steps.session_id = reasoning_sessions.id
685
- WHERE ${joinedSessionFilter.clause}
686
- GROUP BY reasoning_sessions.id
687
- HAVING COUNT(reasoning_steps.id) = 0`)
688
- .all(...joinedSessionFilter.args);
689
- const completionEvents = activeDb
690
- .prepare(`SELECT
691
- COUNT(*) as total,
692
- SUM(CASE WHEN json_extract(output_shape, '$.memory_id_present') = 1 THEN 1 ELSE 0 END) as with_memory,
693
- SUM(CASE WHEN json_extract(output_shape, '$.memory_id_present') = 0 THEN 1 ELSE 0 END) as without_memory
694
- FROM tool_usage_events
695
- WHERE ${eventFilter.clause}
696
- AND tool_name = 'reasoning_complete_session'
697
- AND status = 'success'`)
698
- .get(...eventFilter.args);
699
- const skipReasonRows = activeDb
700
- .prepare(`SELECT
701
- COALESCE(json_extract(output_shape, '$.not_saved_reason_category'), 'none') as reason,
702
- COUNT(*) as count
703
- FROM tool_usage_events
704
- WHERE ${eventFilter.clause}
705
- AND tool_name = 'reasoning_complete_session'
706
- AND status = 'success'
707
- AND json_extract(output_shape, '$.not_saved_reason_category') IS NOT NULL
708
- GROUP BY reason
709
- ORDER BY count DESC, reason ASC`)
710
- .all(...eventFilter.args);
711
- const eventSummary = activeDb
712
- .prepare(`SELECT
713
- SUM(CASE WHEN tool_name = 'memory_save' AND status = 'success' THEN 1 ELSE 0 END) as direct_memory_saved,
714
- SUM(CASE WHEN tool_name IN ('memory_search', 'memory_list', 'memory_get') AND status = 'success' THEN 1 ELSE 0 END) as memory_searched,
715
- SUM(CASE WHEN tool_name = 'memory_update' AND status = 'success' THEN 1 ELSE 0 END) as memory_updated,
716
- SUM(CASE
717
- WHEN tool_name = 'memory_search' AND status = 'success'
718
- THEN COALESCE(json_extract(output_shape, '$.result_count'), 0)
719
- WHEN tool_name = 'memory_list' AND status = 'success'
720
- THEN COALESCE(json_extract(output_shape, '$.result_count'), 0)
721
- WHEN tool_name = 'memory_get' AND status = 'success'
722
- AND COALESCE(json_extract(output_shape, '$.found'), 0) = 1
723
- THEN 1
724
- ELSE 0
725
- END) as memory_recalled
726
- FROM tool_usage_events
727
- WHERE ${eventFilter.clause}`)
728
- .get(...eventFilter.args);
729
- const feedbackSummary = activeDb
730
- .prepare(`SELECT
731
- SUM(CASE WHEN json_extract(metadata, '$.usefulness') = 'used' THEN 1 ELSE 0 END) as used_count
732
- FROM tool_usage_events
733
- WHERE ${eventFilter.clause}
734
- AND operation_type = 'feedback'
735
- AND status = 'success'`)
736
- .get(...eventFilter.args);
737
- const agentBreakdown = activeDb
738
- .prepare(`SELECT
739
- COALESCE(agent_id, 'unknown') as agent_id,
740
- COUNT(*) as event_count
741
- FROM tool_usage_events
742
- WHERE ${eventFilter.clause}
743
- GROUP BY agent_id
744
- ORDER BY event_count DESC, agent_id ASC
745
- LIMIT ?`)
746
- .all(...eventFilter.args, params.limit);
747
- const versionBreakdown = activeDb
748
- .prepare(`SELECT
749
- mcp_version,
750
- COUNT(*) as event_count
751
- FROM tool_usage_events
752
- WHERE ${eventFilter.clause}
753
- GROUP BY mcp_version
754
- ORDER BY event_count DESC, mcp_version ASC`)
755
- .all(...eventFilter.args);
756
- const reasoningStarted = sessionSummary.reasoning_started ?? 0;
757
- const reasoningCompleted = sessionSummary.reasoning_completed ?? 0;
758
- const zeroStepSessions = zeroStepRow.length;
759
- const completedWithMemory = completionEvents.with_memory ?? 0;
760
- const completedWithoutMemory = completionEvents.without_memory ?? 0;
761
- const memorySaved = (eventSummary.direct_memory_saved ?? 0) + completedWithMemory;
762
- const riskFlags = [];
763
- if (reasoningStarted > 0 && zeroStepSessions / reasoningStarted > 0.25) {
764
- riskFlags.push("high_zero_step_session_rate");
765
- }
766
- if (reasoningCompleted > 0 && completedWithMemory / reasoningCompleted < 0.3) {
767
- riskFlags.push("low_completion_to_memory_rate");
768
- }
769
- if ((eventSummary.memory_searched ?? 0) > 0 && (feedbackSummary.used_count ?? 0) === 0) {
770
- riskFlags.push("no_positive_feedback_recorded");
771
- }
772
- const output = {
773
- ...telemetryOffNote(),
774
- funnel: {
775
- reasoning_started: reasoningStarted,
776
- reasoning_completed: reasoningCompleted,
777
- reasoning_abandoned: sessionSummary.reasoning_abandoned ?? 0,
778
- zero_step_sessions: zeroStepSessions,
779
- completed_with_memory: completedWithMemory,
780
- completed_without_memory: completedWithoutMemory,
781
- skip_reason_count: skipReasonRows,
782
- memory_saved: memorySaved,
783
- memory_searched: eventSummary.memory_searched ?? 0,
784
- memory_recalled: eventSummary.memory_recalled ?? 0,
785
- memory_updated: eventSummary.memory_updated ?? 0,
786
- feedback_used: feedbackSummary.used_count ?? 0,
787
- },
788
- agent_breakdown: agentBreakdown,
789
- version_breakdown: versionBreakdown,
790
- risk_flags: riskFlags,
791
- };
792
- return {
793
- content: [{ type: "text", text: toLimitedJson(output) }],
794
- structuredContent: output,
795
- };
796
- }));
797
- server.registerTool("memory_agent_scorecard", {
798
- title: "Memory Agent Scorecard",
799
- 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.",
800
- inputSchema: MemoryAgentScorecardInputSchema.shape,
801
- annotations: {
802
- readOnlyHint: true,
803
- destructiveHint: false,
804
- idempotentHint: true,
805
- openWorldHint: false,
806
- },
807
- }, withTelemetry({
808
- database: databaseProvider,
809
- toolName: "memory_agent_scorecard",
810
- operationType: "report",
811
- accessType: "derived",
812
- buildEvent: (_params, result) => ({
813
- outputShape: {
814
- row_count: Array.isArray(extractStructuredContent(result)?.results)
815
- ? (extractStructuredContent(result)?.results).length
816
- : 0,
817
- },
818
- }),
819
- }, async (params) => {
820
- const activeDb = await resolveDatabase(database);
821
- const sessionFilter = buildSessionWhere(params);
822
- const telemetryFilter = buildTelemetryWhere({
823
- agent_id: params.agent_id,
824
- date_from: params.date_from,
825
- date_to: params.date_to,
826
- });
827
- const rows = activeDb
828
- .prepare(`SELECT DISTINCT COALESCE(agent_id, 'unknown') as agent_id
829
- FROM tool_usage_events
830
- WHERE ${telemetryFilter.clause}
831
- AND operation_type IN ('memory', 'reasoning', 'feedback')
832
- UNION
833
- SELECT DISTINCT COALESCE(agent_id, 'unknown') as agent_id
834
- FROM reasoning_sessions
835
- WHERE ${sessionFilter.clause}
836
- LIMIT ?`)
837
- .all(...telemetryFilter.args, ...sessionFilter.args, params.limit);
838
- const results = rows.map((row) => {
839
- const agentId = row.agent_id === "unknown" ? null : row.agent_id;
840
- // Qualified so the same filter works in the reasoning_steps JOIN
841
- // below; the prefix is harmless in the unjoined query.
842
- const agentSessionFilter = buildSessionWhere({
843
- agent_id: agentId,
844
- date_from: params.date_from,
845
- date_to: params.date_to,
846
- }, "reasoning_sessions.");
847
- const agentEventFilter = buildTelemetryWhere({
848
- agent_id: agentId,
849
- date_from: params.date_from,
850
- date_to: params.date_to,
851
- });
852
- const sessionSummary = activeDb
853
- .prepare(`SELECT
854
- COUNT(*) as started,
855
- SUM(CASE WHEN status = 'completed' THEN 1 ELSE 0 END) as completed
856
- FROM reasoning_sessions
857
- WHERE ${agentSessionFilter.clause}`)
858
- .get(...agentSessionFilter.args);
859
- const avgStepsRow = activeDb
860
- .prepare(`SELECT AVG(step_count) as avg_steps
861
- FROM (
862
- SELECT reasoning_sessions.id, COUNT(reasoning_steps.id) as step_count
863
- FROM reasoning_sessions
864
- LEFT JOIN reasoning_steps
865
- ON reasoning_steps.session_id = reasoning_sessions.id
866
- WHERE ${agentSessionFilter.clause}
867
- GROUP BY reasoning_sessions.id
868
- )`)
869
- .get(...agentSessionFilter.args);
870
- const eventSummary = activeDb
871
- .prepare(`SELECT
872
- COUNT(*) as total_events,
873
- SUM(CASE WHEN status = 'error' THEN 1 ELSE 0 END) as error_events,
874
- SUM(CASE WHEN tool_name IN ('memory_search', 'memory_list', 'memory_get') AND status = 'success' THEN 1 ELSE 0 END) as search_events,
875
- SUM(CASE WHEN tool_name = 'memory_save' AND status = 'success' THEN 1 ELSE 0 END) as direct_save_events,
876
- 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
877
- FROM tool_usage_events
878
- WHERE ${agentEventFilter.clause}
879
- AND operation_type IN ('memory', 'reasoning', 'feedback')`)
880
- .get(...agentEventFilter.args);
881
- const feedbackUsed = activeDb
882
- .prepare(`SELECT COUNT(*) as count
883
- FROM tool_usage_events
884
- WHERE ${agentEventFilter.clause}
885
- AND operation_type = 'feedback'
886
- AND status = 'success'
887
- AND json_extract(metadata, '$.usefulness') = 'used'`)
888
- .get(...agentEventFilter.args);
889
- const sessionsStarted = sessionSummary.started ?? 0;
890
- const sessionsCompleted = sessionSummary.completed ?? 0;
891
- const saves = (eventSummary.direct_save_events ?? 0) +
892
- (eventSummary.completion_memory_events ?? 0);
893
- const searchRate = sessionsStarted === 0
894
- ? 0
895
- : (eventSummary.search_events ?? 0) / sessionsStarted;
896
- const saveRate = sessionsCompleted === 0 ? 0 : saves / sessionsCompleted;
897
- const reuseRate = saves === 0 ? 0 : feedbackUsed.count / saves;
898
- const errorRate = eventSummary.total_events === 0
899
- ? 0
900
- : (eventSummary.error_events ?? 0) / eventSummary.total_events;
901
- let dominantBehavior = "balanced";
902
- if (sessionsStarted > 0 && saveRate < 0.3)
903
- dominantBehavior = "reasoning-heavy";
904
- if ((eventSummary.search_events ?? 0) === 0 && saves === 0) {
905
- dominantBehavior = "memory-light";
906
- }
907
- if (searchRate > 1 && feedbackUsed.count === 0) {
908
- dominantBehavior = "search-only";
909
- }
910
- if (saves > sessionsCompleted && reuseRate < 0.2) {
911
- dominantBehavior = "noisy-writer";
912
- }
913
- if (errorRate > 0.2)
914
- dominantBehavior = "error-prone";
915
- const recommendationMap = {
916
- balanced: "Current usage is balanced; keep validating save quality with feedback.",
917
- "reasoning-heavy": "Persist more durable conclusions after completed sessions.",
918
- "memory-light": "Use memory_search or memory_save when prior context or durable outcomes matter.",
919
- "search-only": "Record feedback on recalled memories to measure usefulness.",
920
- "noisy-writer": "Tighten save criteria and favor durable summaries over raw notes.",
921
- "error-prone": "Audit failing tool calls and validate inputs before writes.",
922
- };
923
- return {
924
- agent_id: row.agent_id,
925
- sessions_started: sessionsStarted,
926
- sessions_completed: sessionsCompleted,
927
- avg_steps_per_session: avgStepsRow.avg_steps ?? 0,
928
- save_rate: saveRate,
929
- search_rate: searchRate,
930
- reuse_rate: reuseRate,
931
- error_rate: errorRate,
932
- dominant_behavior: dominantBehavior,
933
- recommendations: recommendationMap[dominantBehavior],
934
- };
935
- });
936
- const output = { ...telemetryOffNote(), results };
937
- return {
938
- content: [{ type: "text", text: toLimitedJson(output) }],
939
- structuredContent: output,
940
- };
941
- }));
942
330
  server.registerTool("memory_record_usage_feedback", {
943
331
  title: "Record Memory Usage Feedback",
944
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.",
@@ -1005,7 +393,7 @@ export function registerMemoryTools(server, database) {
1005
393
  content: [
1006
394
  {
1007
395
  type: "text",
1008
- text: `Error: Related event '${params.event_id}' cannot be verified for memory '${params.memory_id}'. Use an event that recalled this memory (memory_get, memory_search, or memory_list).`,
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).`,
1009
397
  },
1010
398
  ],
1011
399
  isError: true,