@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.
@@ -1,6 +1,6 @@
1
- import { MemoryAdoptionReportInputSchema, MemoryAgentScorecardInputSchema, MemoryDeleteInputSchema, MemoryGetInputSchema, MemoryListInputSchema, MemoryRecordUsageFeedbackInputSchema, MemorySaveInputSchema, MemorySearchInputSchema, MemoryUpdateInputSchema, MemoryUsageReportInputSchema, } from "../schemas/memory.js";
2
- import { RECALL_RECENCY_DAYS, RECALL_WEIGHTS, getWorkspace, isTelemetryEnabled, } from "../constants.js";
3
- import { newId, nowIso, parseJsonArray, parseJsonObject, toLimitedJson, toSearchTerms, } 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. 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: "Full-text search over saved memories (content and tags). Any query term may match; results are ranked by term coverage, text relevance and recency (queries with 3+ terms need at least 2 to match). 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,
@@ -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: "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.",
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, 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).`,
1044
397
  },
1045
398
  ],
1046
399
  isError: true,