@nhatnguyen9317/memory-mcp-server 1.1.5 → 1.3.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.
- package/CHANGELOG.md +74 -0
- package/GUIDELINES.md +86 -21
- package/README.md +156 -176
- package/dist/constants.js +30 -2
- package/dist/migrations/0005_memory_workspace.js +10 -0
- package/dist/migrations/index.js +2 -0
- package/dist/schemas/reasoning.js +33 -3
- package/dist/tools/memory.js +78 -50
- package/dist/tools/reasoning.js +259 -31
- package/dist/tools/telemetry.js +9 -2
- package/dist/utils.js +29 -3
- package/package.json +16 -3
package/dist/constants.js
CHANGED
|
@@ -2,8 +2,27 @@ import path from "node:path";
|
|
|
2
2
|
import os from "node:os";
|
|
3
3
|
/** Max characters returned in a single tool response before truncation. */
|
|
4
4
|
export const CHARACTER_LIMIT = 25000;
|
|
5
|
-
export const MCP_VERSION = "1.
|
|
6
|
-
|
|
5
|
+
export const MCP_VERSION = "1.3.0";
|
|
6
|
+
/**
|
|
7
|
+
* Diagnostics-event recording is opt-in: set MEMORY_TELEMETRY=on to enable.
|
|
8
|
+
* Read at call time so tests and long-lived processes can toggle it.
|
|
9
|
+
* Usage-feedback events are a first-party learning signal and are always
|
|
10
|
+
* recorded regardless of this flag (see recordToolUsageEvent).
|
|
11
|
+
*/
|
|
12
|
+
export function isTelemetryEnabled() {
|
|
13
|
+
return process.env.MEMORY_TELEMETRY === "on";
|
|
14
|
+
}
|
|
15
|
+
/**
|
|
16
|
+
* Hours after which an untouched in_progress reasoning session is
|
|
17
|
+
* auto-abandoned on the next reasoning_start_session call.
|
|
18
|
+
* Override with MEMORY_SESSION_TTL_HOURS; set to 0 (or negative) to disable.
|
|
19
|
+
*/
|
|
20
|
+
export const SESSION_TTL_HOURS = Number(process.env.MEMORY_SESSION_TTL_HOURS ?? 24);
|
|
21
|
+
/**
|
|
22
|
+
* Max related memories auto-recalled in the reasoning_start_session response.
|
|
23
|
+
* Override with MEMORY_AUTO_RECALL_LIMIT; set to 0 to disable auto-recall.
|
|
24
|
+
*/
|
|
25
|
+
export const AUTO_RECALL_LIMIT = Number(process.env.MEMORY_AUTO_RECALL_LIMIT ?? 3);
|
|
7
26
|
/**
|
|
8
27
|
* Location of the SQLite database file.
|
|
9
28
|
* Override with the MEMORY_DB_PATH environment variable, e.g. to keep
|
|
@@ -11,6 +30,15 @@ export const TELEMETRY_ENABLED = process.env.MEMORY_TELEMETRY !== "off";
|
|
|
11
30
|
*/
|
|
12
31
|
export const DB_PATH = process.env.MEMORY_DB_PATH ??
|
|
13
32
|
path.join(os.homedir(), ".memory-mcp-server", "memory.db");
|
|
33
|
+
/**
|
|
34
|
+
* Workspace identity for memory scoping. Claude Code/Codex launch the MCP
|
|
35
|
+
* server inside the project directory, so cwd identifies the project;
|
|
36
|
+
* MEMORY_WORKSPACE pins it explicitly when a client launches elsewhere.
|
|
37
|
+
* Read at call time (same pattern as isTelemetryEnabled) for testability.
|
|
38
|
+
*/
|
|
39
|
+
export function getWorkspace() {
|
|
40
|
+
return process.env.MEMORY_WORKSPACE ?? process.cwd();
|
|
41
|
+
}
|
|
14
42
|
export const DEFAULT_LIST_LIMIT = 20;
|
|
15
43
|
export const MAX_LIST_LIMIT = 200;
|
|
16
44
|
//# sourceMappingURL=constants.js.map
|
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
export const migration0005MemoryWorkspace = {
|
|
2
|
+
version: "0005_memory_workspace",
|
|
3
|
+
apply(db) {
|
|
4
|
+
db.exec(`
|
|
5
|
+
ALTER TABLE memories ADD COLUMN workspace TEXT;
|
|
6
|
+
CREATE INDEX IF NOT EXISTS idx_memories_workspace ON memories(workspace);
|
|
7
|
+
`);
|
|
8
|
+
},
|
|
9
|
+
};
|
|
10
|
+
//# sourceMappingURL=0005_memory_workspace.js.map
|
package/dist/migrations/index.js
CHANGED
|
@@ -3,11 +3,13 @@ import { migration0001Initial } from "./0001_initial.js";
|
|
|
3
3
|
import { migration0002ReasoningStepMarks } from "./0002_reasoning_step_marks.js";
|
|
4
4
|
import { migration0003ReasoningStepsFts } from "./0003_reasoning_steps_fts.js";
|
|
5
5
|
import { migration0004ToolUsageEvents } from "./0004_tool_usage_events.js";
|
|
6
|
+
import { migration0005MemoryWorkspace } from "./0005_memory_workspace.js";
|
|
6
7
|
const migrations = [
|
|
7
8
|
migration0001Initial,
|
|
8
9
|
migration0002ReasoningStepMarks,
|
|
9
10
|
migration0003ReasoningStepsFts,
|
|
10
11
|
migration0004ToolUsageEvents,
|
|
12
|
+
migration0005MemoryWorkspace,
|
|
11
13
|
];
|
|
12
14
|
export function runMigrations(db) {
|
|
13
15
|
db.exec(`
|
|
@@ -13,9 +13,28 @@ export const ReasoningStartSessionInputSchema = z
|
|
|
13
13
|
.describe("Optional identifier for the agent/persona running this session."),
|
|
14
14
|
})
|
|
15
15
|
.strict();
|
|
16
|
+
export const ReasoningStepEntrySchema = z
|
|
17
|
+
.object({
|
|
18
|
+
thought: z
|
|
19
|
+
.string()
|
|
20
|
+
.max(4000)
|
|
21
|
+
.optional()
|
|
22
|
+
.describe("The agent's reasoning/thinking at this step."),
|
|
23
|
+
action: z
|
|
24
|
+
.string()
|
|
25
|
+
.max(2000)
|
|
26
|
+
.optional()
|
|
27
|
+
.describe("The action taken at this step, if any (e.g. a tool call description)."),
|
|
28
|
+
observation: z
|
|
29
|
+
.string()
|
|
30
|
+
.max(4000)
|
|
31
|
+
.optional()
|
|
32
|
+
.describe("The result/observation from the action, if any."),
|
|
33
|
+
})
|
|
34
|
+
.strict();
|
|
16
35
|
// NOTE: kept as a plain ZodObject (no .refine()) so `.shape` stays available
|
|
17
|
-
// for registerTool's inputSchema. The "at least one field"
|
|
18
|
-
// in the tool handler instead.
|
|
36
|
+
// for registerTool's inputSchema. The "at least one field" and "single vs
|
|
37
|
+
// batch" rules are enforced in the tool handler instead.
|
|
19
38
|
export const ReasoningAddStepInputSchema = z
|
|
20
39
|
.object({
|
|
21
40
|
session_id: z
|
|
@@ -37,6 +56,12 @@ export const ReasoningAddStepInputSchema = z
|
|
|
37
56
|
.max(4000)
|
|
38
57
|
.optional()
|
|
39
58
|
.describe("The result/observation from the action, if any."),
|
|
59
|
+
steps: z
|
|
60
|
+
.array(ReasoningStepEntrySchema)
|
|
61
|
+
.min(1)
|
|
62
|
+
.max(20)
|
|
63
|
+
.optional()
|
|
64
|
+
.describe("Batch mode: log several steps in one call (each entry needs at least one of thought/action/observation). Use INSTEAD of the top-level thought/action/observation fields, e.g. to record the trace of work you just finished without one call per step."),
|
|
40
65
|
})
|
|
41
66
|
.strict();
|
|
42
67
|
export const ReasoningGetTraceInputSchema = z
|
|
@@ -131,7 +156,7 @@ export const ReasoningCompleteSessionInputSchema = z
|
|
|
131
156
|
memory_mode: z
|
|
132
157
|
.enum(["auto", "always", "never"])
|
|
133
158
|
.optional()
|
|
134
|
-
.describe("Preferred memory persistence mode. 'auto'
|
|
159
|
+
.describe("Preferred memory persistence mode. 'auto' (default) does not save on its own — a memory is only created when save_as_memory=true or memory_mode='always'; 'never' skips saving and requires not_saved_reason."),
|
|
135
160
|
memory_type: z
|
|
136
161
|
.enum(["fact", "preference", "episodic", "decision", "reasoning_summary"])
|
|
137
162
|
.optional()
|
|
@@ -154,6 +179,11 @@ export const ReasoningCompleteSessionInputSchema = z
|
|
|
154
179
|
.max(500)
|
|
155
180
|
.optional()
|
|
156
181
|
.describe("Required when memory_mode='never' to explain why the conclusion should not be kept as durable memory."),
|
|
182
|
+
used_memory_ids: z
|
|
183
|
+
.array(z.string().min(1))
|
|
184
|
+
.max(50)
|
|
185
|
+
.default([])
|
|
186
|
+
.describe("Ids of memories that were actually used/helpful during this session (e.g. ones returned in related_memories by reasoning_start_session). The server records a 'used' usage-feedback event for each, so recall usefulness can be measured."),
|
|
157
187
|
})
|
|
158
188
|
.strict();
|
|
159
189
|
//# sourceMappingURL=reasoning.js.map
|
package/dist/tools/memory.js
CHANGED
|
@@ -1,4 +1,5 @@
|
|
|
1
1
|
import { MemoryAdoptionReportInputSchema, MemoryAgentScorecardInputSchema, MemoryDeleteInputSchema, MemoryGetInputSchema, MemoryListInputSchema, MemoryRecordUsageFeedbackInputSchema, MemorySaveInputSchema, MemorySearchInputSchema, MemoryUpdateInputSchema, MemoryUsageReportInputSchema, } from "../schemas/memory.js";
|
|
2
|
+
import { getWorkspace, isTelemetryEnabled } from "../constants.js";
|
|
2
3
|
import { newId, nowIso, parseJsonArray, parseJsonObject, toFtsQuery, toLimitedJson, } from "../utils.js";
|
|
3
4
|
import { withTelemetry, } from "./telemetry.js";
|
|
4
5
|
function rowToRecord(row) {
|
|
@@ -14,16 +15,31 @@ function rowToRecord(row) {
|
|
|
14
15
|
updated_at: row.updated_at,
|
|
15
16
|
};
|
|
16
17
|
}
|
|
18
|
+
function escapeLikePattern(value) {
|
|
19
|
+
return value.replace(/[\\%_]/g, (char) => `\\${char}`);
|
|
20
|
+
}
|
|
17
21
|
function tagsFilterClauses(tags) {
|
|
18
22
|
if (!tags || tags.length === 0)
|
|
19
23
|
return { clause: "", params: [] };
|
|
20
|
-
const clause = tags.map(() => `tags LIKE
|
|
21
|
-
const params = tags.map((tag) => `%"${tag}"%`);
|
|
24
|
+
const clause = tags.map(() => `tags LIKE ? ESCAPE '\\'`).join(" AND ");
|
|
25
|
+
const params = tags.map((tag) => `%"${escapeLikePattern(tag)}"%`);
|
|
22
26
|
return { clause: ` AND ${clause}`, params };
|
|
23
27
|
}
|
|
24
28
|
function extractStructuredContent(result) {
|
|
25
29
|
return result.structuredContent ?? null;
|
|
26
30
|
}
|
|
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
|
+
}
|
|
27
43
|
function resultCount(result) {
|
|
28
44
|
const structured = extractStructuredContent(result);
|
|
29
45
|
if (structured?.total_returned !== undefined) {
|
|
@@ -33,8 +49,15 @@ function resultCount(result) {
|
|
|
33
49
|
return structured.results.length;
|
|
34
50
|
return result.content[0]?.text.startsWith("No memories found") ? 0 : 1;
|
|
35
51
|
}
|
|
36
|
-
|
|
37
|
-
|
|
52
|
+
/** Ids of memories returned by a search/list call, bounded so telemetry rows stay small. */
|
|
53
|
+
function returnedMemoryIds(result) {
|
|
54
|
+
const structured = extractStructuredContent(result);
|
|
55
|
+
if (!Array.isArray(structured?.results))
|
|
56
|
+
return [];
|
|
57
|
+
return structured.results
|
|
58
|
+
.slice(0, 20)
|
|
59
|
+
.map((row) => String(row.id))
|
|
60
|
+
.filter((id) => id !== "undefined");
|
|
38
61
|
}
|
|
39
62
|
function normalizeTextDate(value) {
|
|
40
63
|
if (!value)
|
|
@@ -88,18 +111,21 @@ function buildTelemetryWhere(params) {
|
|
|
88
111
|
}
|
|
89
112
|
return { clause: conditions.join(" AND "), args };
|
|
90
113
|
}
|
|
91
|
-
function buildSessionWhere(params
|
|
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 = "") {
|
|
92
118
|
const conditions = ["1=1"];
|
|
93
119
|
const args = [];
|
|
94
|
-
appendAgentFilter(conditions, args,
|
|
120
|
+
appendAgentFilter(conditions, args, `${columnPrefix}agent_id`, params.agent_id);
|
|
95
121
|
const dateFrom = normalizeDateBoundary(params.date_from, "start");
|
|
96
122
|
if (dateFrom) {
|
|
97
|
-
conditions.push(
|
|
123
|
+
conditions.push(`${columnPrefix}created_at >= ?`);
|
|
98
124
|
args.push(dateFrom);
|
|
99
125
|
}
|
|
100
126
|
const dateTo = normalizeDateBoundary(params.date_to, "end");
|
|
101
127
|
if (dateTo) {
|
|
102
|
-
conditions.push(
|
|
128
|
+
conditions.push(`${columnPrefix}created_at <= ?`);
|
|
103
129
|
args.push(dateTo);
|
|
104
130
|
}
|
|
105
131
|
return { clause: conditions.join(" AND "), args };
|
|
@@ -115,7 +141,7 @@ export function registerMemoryTools(server, database) {
|
|
|
115
141
|
const databaseProvider = () => resolveDatabase(database);
|
|
116
142
|
server.registerTool("memory_save", {
|
|
117
143
|
title: "Save Memory",
|
|
118
|
-
description: "Persist a piece of long-term memory so it can be recalled in future sessions.",
|
|
144
|
+
description: "Persist a piece of long-term memory so it can be recalled in future sessions. Tags describe topics ('sqlite', 'auth', 'perf'), not locations — do not put workspace or project names in tags; the server records the workspace automatically.",
|
|
119
145
|
inputSchema: MemorySaveInputSchema.shape,
|
|
120
146
|
annotations: {
|
|
121
147
|
readOnlyHint: false,
|
|
@@ -153,8 +179,8 @@ export function registerMemoryTools(server, database) {
|
|
|
153
179
|
const id = newId("mem");
|
|
154
180
|
const ts = nowIso();
|
|
155
181
|
activeDb
|
|
156
|
-
.prepare(`INSERT INTO memories (id, type, content, tags, agent_id, importance, metadata, created_at, updated_at)
|
|
157
|
-
VALUES (@id, @type, @content, @tags, @agent_id, @importance, @metadata, @created_at, @updated_at)`)
|
|
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)`)
|
|
158
184
|
.run({
|
|
159
185
|
id,
|
|
160
186
|
type: params.type,
|
|
@@ -163,6 +189,7 @@ export function registerMemoryTools(server, database) {
|
|
|
163
189
|
agent_id: params.agent_id ?? null,
|
|
164
190
|
importance: params.importance,
|
|
165
191
|
metadata: params.metadata ? JSON.stringify(params.metadata) : null,
|
|
192
|
+
workspace: getWorkspace(),
|
|
166
193
|
created_at: ts,
|
|
167
194
|
updated_at: ts,
|
|
168
195
|
});
|
|
@@ -207,15 +234,13 @@ export function registerMemoryTools(server, database) {
|
|
|
207
234
|
},
|
|
208
235
|
outputShape: {
|
|
209
236
|
result_count: resultCount(result),
|
|
210
|
-
|
|
237
|
+
memory_ids: returnedMemoryIds(result),
|
|
211
238
|
},
|
|
212
239
|
}),
|
|
213
240
|
}, async (params) => {
|
|
214
241
|
const activeDb = await resolveDatabase(database);
|
|
215
242
|
const { clause: tagClause, params: tagParams } = tagsFilterClauses(params.tags);
|
|
216
|
-
const conditions = [
|
|
217
|
-
"m.rowid IN (SELECT rowid FROM memories_fts WHERE memories_fts MATCH ?)",
|
|
218
|
-
];
|
|
243
|
+
const conditions = [];
|
|
219
244
|
const sqlParams = [toFtsQuery(params.query)];
|
|
220
245
|
if (params.type) {
|
|
221
246
|
conditions.push("m.type = ?");
|
|
@@ -225,10 +250,18 @@ export function registerMemoryTools(server, database) {
|
|
|
225
250
|
conditions.push("m.agent_id = ?");
|
|
226
251
|
sqlParams.push(params.agent_id);
|
|
227
252
|
}
|
|
253
|
+
if (tagClause) {
|
|
254
|
+
// tagClause is " AND <clauses>"; strip the prefix to compose here.
|
|
255
|
+
conditions.push(tagClause.slice(" AND ".length));
|
|
256
|
+
}
|
|
257
|
+
// rank (bm25) sorts best text match first; importance/recency break ties.
|
|
228
258
|
const rows = activeDb
|
|
229
259
|
.prepare(`SELECT m.* FROM memories m
|
|
230
|
-
|
|
231
|
-
|
|
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
|
|
232
265
|
LIMIT ? OFFSET ?`)
|
|
233
266
|
.all(...sqlParams, ...tagParams, params.limit, params.offset);
|
|
234
267
|
if (rows.length === 0) {
|
|
@@ -280,6 +313,7 @@ export function registerMemoryTools(server, database) {
|
|
|
280
313
|
outputShape: {
|
|
281
314
|
result_count: resultCount(result),
|
|
282
315
|
has_more: extractStructuredContent(result)?.has_more === true,
|
|
316
|
+
memory_ids: returnedMemoryIds(result),
|
|
283
317
|
},
|
|
284
318
|
}),
|
|
285
319
|
}, async (params) => {
|
|
@@ -522,7 +556,7 @@ export function registerMemoryTools(server, database) {
|
|
|
522
556
|
}));
|
|
523
557
|
server.registerTool("memory_usage_report", {
|
|
524
558
|
title: "Memory Usage Report",
|
|
525
|
-
description: "Aggregate tool usage events by tool, agent, client, version, operation type, status, or day.",
|
|
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.",
|
|
526
560
|
inputSchema: MemoryUsageReportInputSchema.shape,
|
|
527
561
|
annotations: {
|
|
528
562
|
readOnlyHint: true,
|
|
@@ -588,6 +622,7 @@ export function registerMemoryTools(server, database) {
|
|
|
588
622
|
const successEvents = summaryRow.success_events ?? 0;
|
|
589
623
|
const errorEvents = summaryRow.error_events ?? 0;
|
|
590
624
|
const output = {
|
|
625
|
+
...telemetryOffNote(),
|
|
591
626
|
summary: {
|
|
592
627
|
total_events: totalEvents,
|
|
593
628
|
success_events: successEvents,
|
|
@@ -609,7 +644,7 @@ export function registerMemoryTools(server, database) {
|
|
|
609
644
|
}));
|
|
610
645
|
server.registerTool("memory_adoption_report", {
|
|
611
646
|
title: "Memory Adoption Report",
|
|
612
|
-
description: "Summarize reasoning and memory adoption behavior using telemetry plus core session tables.",
|
|
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.",
|
|
613
648
|
inputSchema: MemoryAdoptionReportInputSchema.shape,
|
|
614
649
|
annotations: {
|
|
615
650
|
readOnlyHint: true,
|
|
@@ -641,15 +676,16 @@ export function registerMemoryTools(server, database) {
|
|
|
641
676
|
FROM reasoning_sessions
|
|
642
677
|
WHERE ${sessionFilter.clause}`)
|
|
643
678
|
.get(...sessionFilter.args);
|
|
679
|
+
const joinedSessionFilter = buildSessionWhere(params, "reasoning_sessions.");
|
|
644
680
|
const zeroStepRow = activeDb
|
|
645
681
|
.prepare(`SELECT COUNT(*) as zero_step_sessions
|
|
646
682
|
FROM reasoning_sessions
|
|
647
683
|
LEFT JOIN reasoning_steps
|
|
648
684
|
ON reasoning_steps.session_id = reasoning_sessions.id
|
|
649
|
-
WHERE ${
|
|
685
|
+
WHERE ${joinedSessionFilter.clause}
|
|
650
686
|
GROUP BY reasoning_sessions.id
|
|
651
687
|
HAVING COUNT(reasoning_steps.id) = 0`)
|
|
652
|
-
.all(...
|
|
688
|
+
.all(...joinedSessionFilter.args);
|
|
653
689
|
const completionEvents = activeDb
|
|
654
690
|
.prepare(`SELECT
|
|
655
691
|
COUNT(*) as total,
|
|
@@ -696,7 +732,6 @@ export function registerMemoryTools(server, database) {
|
|
|
696
732
|
FROM tool_usage_events
|
|
697
733
|
WHERE ${eventFilter.clause}
|
|
698
734
|
AND operation_type = 'feedback'
|
|
699
|
-
AND related_event_id IS NOT NULL
|
|
700
735
|
AND status = 'success'`)
|
|
701
736
|
.get(...eventFilter.args);
|
|
702
737
|
const agentBreakdown = activeDb
|
|
@@ -735,6 +770,7 @@ export function registerMemoryTools(server, database) {
|
|
|
735
770
|
riskFlags.push("no_positive_feedback_recorded");
|
|
736
771
|
}
|
|
737
772
|
const output = {
|
|
773
|
+
...telemetryOffNote(),
|
|
738
774
|
funnel: {
|
|
739
775
|
reasoning_started: reasoningStarted,
|
|
740
776
|
reasoning_completed: reasoningCompleted,
|
|
@@ -760,7 +796,7 @@ export function registerMemoryTools(server, database) {
|
|
|
760
796
|
}));
|
|
761
797
|
server.registerTool("memory_agent_scorecard", {
|
|
762
798
|
title: "Memory Agent Scorecard",
|
|
763
|
-
description: "Compare how different agents use memory and reasoning tools in practice.",
|
|
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.",
|
|
764
800
|
inputSchema: MemoryAgentScorecardInputSchema.shape,
|
|
765
801
|
annotations: {
|
|
766
802
|
readOnlyHint: true,
|
|
@@ -801,11 +837,13 @@ export function registerMemoryTools(server, database) {
|
|
|
801
837
|
.all(...telemetryFilter.args, ...sessionFilter.args, params.limit);
|
|
802
838
|
const results = rows.map((row) => {
|
|
803
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.
|
|
804
842
|
const agentSessionFilter = buildSessionWhere({
|
|
805
843
|
agent_id: agentId,
|
|
806
844
|
date_from: params.date_from,
|
|
807
845
|
date_to: params.date_to,
|
|
808
|
-
});
|
|
846
|
+
}, "reasoning_sessions.");
|
|
809
847
|
const agentEventFilter = buildTelemetryWhere({
|
|
810
848
|
agent_id: agentId,
|
|
811
849
|
date_from: params.date_from,
|
|
@@ -845,7 +883,6 @@ export function registerMemoryTools(server, database) {
|
|
|
845
883
|
FROM tool_usage_events
|
|
846
884
|
WHERE ${agentEventFilter.clause}
|
|
847
885
|
AND operation_type = 'feedback'
|
|
848
|
-
AND related_event_id IS NOT NULL
|
|
849
886
|
AND status = 'success'
|
|
850
887
|
AND json_extract(metadata, '$.usefulness') = 'used'`)
|
|
851
888
|
.get(...agentEventFilter.args);
|
|
@@ -896,7 +933,7 @@ export function registerMemoryTools(server, database) {
|
|
|
896
933
|
recommendations: recommendationMap[dominantBehavior],
|
|
897
934
|
};
|
|
898
935
|
});
|
|
899
|
-
const output = { results };
|
|
936
|
+
const output = { ...telemetryOffNote(), results };
|
|
900
937
|
return {
|
|
901
938
|
content: [{ type: "text", text: toLimitedJson(output) }],
|
|
902
939
|
structuredContent: output,
|
|
@@ -904,7 +941,7 @@ export function registerMemoryTools(server, database) {
|
|
|
904
941
|
}));
|
|
905
942
|
server.registerTool("memory_record_usage_feedback", {
|
|
906
943
|
title: "Record Memory Usage Feedback",
|
|
907
|
-
description: "Record whether a recalled memory was used, ignored, stale, or unsafe to use.",
|
|
944
|
+
description: "Record whether a recalled memory was used, ignored, stale, or unsafe to use. Feedback is a first-party learning signal for recall quality and is always persisted locally, regardless of the MEMORY_TELEMETRY setting.",
|
|
908
945
|
inputSchema: MemoryRecordUsageFeedbackInputSchema.shape,
|
|
909
946
|
annotations: {
|
|
910
947
|
readOnlyHint: false,
|
|
@@ -927,10 +964,7 @@ export function registerMemoryTools(server, database) {
|
|
|
927
964
|
reason_length: params.reason?.length ?? 0,
|
|
928
965
|
},
|
|
929
966
|
outputShape: {
|
|
930
|
-
recorded: result.
|
|
931
|
-
event_id: typeof result.structuredContent?.event_id === "string"
|
|
932
|
-
? result.structuredContent.event_id
|
|
933
|
-
: null,
|
|
967
|
+
recorded: result.structuredContent?.recorded === true,
|
|
934
968
|
},
|
|
935
969
|
metadata: {
|
|
936
970
|
usefulness: params.usefulness,
|
|
@@ -938,17 +972,6 @@ export function registerMemoryTools(server, database) {
|
|
|
938
972
|
},
|
|
939
973
|
}),
|
|
940
974
|
}, async (params) => {
|
|
941
|
-
if (!telemetryPersistenceEnabled()) {
|
|
942
|
-
return {
|
|
943
|
-
content: [
|
|
944
|
-
{
|
|
945
|
-
type: "text",
|
|
946
|
-
text: "Error: Telemetry persistence is disabled; memory feedback cannot be recorded.",
|
|
947
|
-
},
|
|
948
|
-
],
|
|
949
|
-
isError: true,
|
|
950
|
-
};
|
|
951
|
-
}
|
|
952
975
|
const activeDb = await resolveDatabase(database);
|
|
953
976
|
const existing = activeDb
|
|
954
977
|
.prepare(`SELECT id FROM memories WHERE id = ?`)
|
|
@@ -966,18 +989,23 @@ export function registerMemoryTools(server, database) {
|
|
|
966
989
|
}
|
|
967
990
|
if (params.event_id) {
|
|
968
991
|
const relatedEvent = activeDb
|
|
969
|
-
.prepare(`SELECT id
|
|
992
|
+
.prepare(`SELECT id, memory_id, output_shape
|
|
970
993
|
FROM tool_usage_events
|
|
971
|
-
WHERE id =
|
|
972
|
-
|
|
973
|
-
|
|
974
|
-
|
|
975
|
-
|
|
994
|
+
WHERE id = ?`)
|
|
995
|
+
.get(params.event_id);
|
|
996
|
+
const recalledIds = relatedEvent
|
|
997
|
+
? parseJsonObject(relatedEvent.output_shape)?.memory_ids
|
|
998
|
+
: undefined;
|
|
999
|
+
const verified = relatedEvent !== undefined &&
|
|
1000
|
+
(relatedEvent.memory_id === params.memory_id ||
|
|
1001
|
+
(Array.isArray(recalledIds) &&
|
|
1002
|
+
recalledIds.includes(params.memory_id)));
|
|
1003
|
+
if (!verified) {
|
|
976
1004
|
return {
|
|
977
1005
|
content: [
|
|
978
1006
|
{
|
|
979
1007
|
type: "text",
|
|
980
|
-
text: `Error: Related event '${params.event_id}' cannot be verified for memory '${params.memory_id}'. Use
|
|
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).`,
|
|
981
1009
|
},
|
|
982
1010
|
],
|
|
983
1011
|
isError: true,
|
|
@@ -985,7 +1013,7 @@ export function registerMemoryTools(server, database) {
|
|
|
985
1013
|
}
|
|
986
1014
|
}
|
|
987
1015
|
const output = {
|
|
988
|
-
|
|
1016
|
+
recorded: true,
|
|
989
1017
|
memory_id: params.memory_id,
|
|
990
1018
|
usefulness: params.usefulness,
|
|
991
1019
|
};
|