@nhatnguyen9317/memory-mcp-server 1.2.0 → 1.3.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +53 -0
- package/GUIDELINES.md +86 -21
- package/README.md +181 -180
- package/dist/constants.js +19 -2
- package/dist/index.js +19 -18
- package/dist/install-agents.js +74 -0
- package/dist/migrations/0005_memory_workspace.js +10 -0
- package/dist/migrations/index.js +2 -0
- package/dist/schemas/reasoning.js +27 -2
- package/dist/server.js +20 -0
- package/dist/tools/memory.js +49 -35
- package/dist/tools/reasoning.js +162 -39
- package/dist/tools/telemetry.js +9 -2
- package/dist/utils.js +23 -5
- package/package.json +24 -2
package/dist/constants.js
CHANGED
|
@@ -2,8 +2,16 @@ 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.1";
|
|
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
|
+
}
|
|
7
15
|
/**
|
|
8
16
|
* Hours after which an untouched in_progress reasoning session is
|
|
9
17
|
* auto-abandoned on the next reasoning_start_session call.
|
|
@@ -22,6 +30,15 @@ export const AUTO_RECALL_LIMIT = Number(process.env.MEMORY_AUTO_RECALL_LIMIT ??
|
|
|
22
30
|
*/
|
|
23
31
|
export const DB_PATH = process.env.MEMORY_DB_PATH ??
|
|
24
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
|
+
}
|
|
25
42
|
export const DEFAULT_LIST_LIMIT = 20;
|
|
26
43
|
export const MAX_LIST_LIMIT = 200;
|
|
27
44
|
//# sourceMappingURL=constants.js.map
|
package/dist/index.js
CHANGED
|
@@ -5,28 +5,29 @@
|
|
|
5
5
|
* An MCP server that gives an agent durable long-term memory and the
|
|
6
6
|
* ability to record/retrieve step-by-step reasoning traces, backed by
|
|
7
7
|
* a local SQLite database (with full-text search over memories).
|
|
8
|
+
*
|
|
9
|
+
* CLI subcommands (checked via argv before anything else loads, so
|
|
10
|
+
* `install-agents` never triggers the server's DB initialization):
|
|
11
|
+
* - (none) -> starts the MCP server over stdio
|
|
12
|
+
* - install-agents -> installs the README snippet into global agent config
|
|
8
13
|
*/
|
|
9
|
-
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
|
|
10
|
-
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
|
|
11
|
-
import { DB_PATH, MCP_VERSION } from "./constants.js";
|
|
12
|
-
import "./db.js"; // ensures schema is created before tools run
|
|
13
|
-
import { registerMemoryTools } from "./tools/memory.js";
|
|
14
|
-
import { registerReasoningTools } from "./tools/reasoning.js";
|
|
15
|
-
import { registerUsageGuideTool } from "./tools/usage-guide.js";
|
|
16
|
-
const server = new McpServer({
|
|
17
|
-
name: "memory-mcp-server",
|
|
18
|
-
version: MCP_VERSION,
|
|
19
|
-
});
|
|
20
|
-
registerMemoryTools(server);
|
|
21
|
-
registerReasoningTools(server);
|
|
22
|
-
registerUsageGuideTool(server);
|
|
23
14
|
async function main() {
|
|
24
|
-
const
|
|
25
|
-
|
|
26
|
-
|
|
15
|
+
const subcommand = process.argv[2];
|
|
16
|
+
if (subcommand === "install-agents") {
|
|
17
|
+
const { installAgents } = await import("./install-agents.js");
|
|
18
|
+
await installAgents();
|
|
19
|
+
}
|
|
20
|
+
else {
|
|
21
|
+
const { runServer } = await import("./server.js");
|
|
22
|
+
await runServer();
|
|
23
|
+
}
|
|
27
24
|
}
|
|
28
25
|
main().catch((error) => {
|
|
29
|
-
|
|
26
|
+
const label = process.argv[2] === "install-agents"
|
|
27
|
+
? "Fatal error running install-agents"
|
|
28
|
+
: "Fatal error starting memory-mcp-server";
|
|
29
|
+
console.error(`${label}:`, error);
|
|
30
30
|
process.exit(1);
|
|
31
31
|
});
|
|
32
|
+
export {};
|
|
32
33
|
//# sourceMappingURL=index.js.map
|
|
@@ -0,0 +1,74 @@
|
|
|
1
|
+
import { copyFileSync, existsSync, mkdirSync, readFileSync, writeFileSync, } from "node:fs";
|
|
2
|
+
import { homedir } from "node:os";
|
|
3
|
+
import { dirname, join } from "node:path";
|
|
4
|
+
import { fileURLToPath } from "node:url";
|
|
5
|
+
const START_MARKER = "<!-- MEMORY_MCP_SERVER_START -->";
|
|
6
|
+
const END_MARKER = "<!-- MEMORY_MCP_SERVER_END -->";
|
|
7
|
+
function targets() {
|
|
8
|
+
return [
|
|
9
|
+
{ name: "Claude Code", path: join(homedir(), ".claude", "CLAUDE.md") },
|
|
10
|
+
{ name: "Codex CLI", path: join(homedir(), ".codex", "AGENTS.md") },
|
|
11
|
+
];
|
|
12
|
+
}
|
|
13
|
+
/** Extracts the pasteable snippet (markers inclusive) from README.md content. */
|
|
14
|
+
export function extractSnippet(readmeContent) {
|
|
15
|
+
const start = readmeContent.indexOf(START_MARKER);
|
|
16
|
+
const end = readmeContent.indexOf(END_MARKER);
|
|
17
|
+
if (start === -1 || end === -1) {
|
|
18
|
+
throw new Error(`Could not find ${START_MARKER} / ${END_MARKER} markers in README.md`);
|
|
19
|
+
}
|
|
20
|
+
return readmeContent.slice(start, end + END_MARKER.length).trim();
|
|
21
|
+
}
|
|
22
|
+
/**
|
|
23
|
+
* Pure decision of the next file content, given the current content
|
|
24
|
+
* (null when the file does not exist yet) and the snippet to install.
|
|
25
|
+
* No filesystem access, so this is directly unit-testable.
|
|
26
|
+
*/
|
|
27
|
+
export function computeInstall(existingContent, snippet) {
|
|
28
|
+
if (existingContent === null) {
|
|
29
|
+
return { content: `${snippet}\n`, action: "created" };
|
|
30
|
+
}
|
|
31
|
+
const start = existingContent.indexOf(START_MARKER);
|
|
32
|
+
const end = existingContent.indexOf(END_MARKER);
|
|
33
|
+
if (start !== -1 && end !== -1) {
|
|
34
|
+
return {
|
|
35
|
+
content: existingContent.slice(0, start) +
|
|
36
|
+
snippet +
|
|
37
|
+
existingContent.slice(end + END_MARKER.length),
|
|
38
|
+
action: "updated",
|
|
39
|
+
};
|
|
40
|
+
}
|
|
41
|
+
const separator = existingContent.trim().length ? "\n\n" : "";
|
|
42
|
+
return {
|
|
43
|
+
content: `${existingContent}${separator}${snippet}\n`,
|
|
44
|
+
action: "appended",
|
|
45
|
+
};
|
|
46
|
+
}
|
|
47
|
+
/**
|
|
48
|
+
* Installs the README's Memory MCP Server snippet into the global config
|
|
49
|
+
* files of commonly-used agents (Claude Code, Codex CLI). Idempotent, and
|
|
50
|
+
* never touches project-scoped files.
|
|
51
|
+
*
|
|
52
|
+
* `overrides` exists so tests can point at a temp dir instead of the real
|
|
53
|
+
* home directory; production callers pass nothing.
|
|
54
|
+
*/
|
|
55
|
+
export async function installAgents(overrides = {}) {
|
|
56
|
+
const packageRoot = join(dirname(fileURLToPath(import.meta.url)), "..");
|
|
57
|
+
const readmePath = overrides.readmePath ?? join(packageRoot, "README.md");
|
|
58
|
+
const readmeContent = readFileSync(readmePath, "utf8");
|
|
59
|
+
const snippet = extractSnippet(readmeContent);
|
|
60
|
+
for (const target of overrides.targets ?? targets()) {
|
|
61
|
+
const exists = existsSync(target.path);
|
|
62
|
+
if (exists) {
|
|
63
|
+
copyFileSync(target.path, `${target.path}.bak`);
|
|
64
|
+
}
|
|
65
|
+
else {
|
|
66
|
+
mkdirSync(dirname(target.path), { recursive: true });
|
|
67
|
+
}
|
|
68
|
+
const existingContent = exists ? readFileSync(target.path, "utf8") : null;
|
|
69
|
+
const { content, action } = computeInstall(existingContent, snippet);
|
|
70
|
+
writeFileSync(target.path, content);
|
|
71
|
+
console.log(`[${action}] ${target.name} -> ${target.path}`);
|
|
72
|
+
}
|
|
73
|
+
}
|
|
74
|
+
//# sourceMappingURL=install-agents.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
|
package/dist/server.js
ADDED
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
|
|
2
|
+
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
|
|
3
|
+
import { DB_PATH, MCP_VERSION } from "./constants.js";
|
|
4
|
+
import "./db.js"; // ensures schema is created before tools run
|
|
5
|
+
import { registerMemoryTools } from "./tools/memory.js";
|
|
6
|
+
import { registerReasoningTools } from "./tools/reasoning.js";
|
|
7
|
+
import { registerUsageGuideTool } from "./tools/usage-guide.js";
|
|
8
|
+
export async function runServer() {
|
|
9
|
+
const server = new McpServer({
|
|
10
|
+
name: "memory-mcp-server",
|
|
11
|
+
version: MCP_VERSION,
|
|
12
|
+
});
|
|
13
|
+
registerMemoryTools(server);
|
|
14
|
+
registerReasoningTools(server);
|
|
15
|
+
registerUsageGuideTool(server);
|
|
16
|
+
const transport = new StdioServerTransport();
|
|
17
|
+
await server.connect(transport);
|
|
18
|
+
console.error(`memory-mcp-server running via stdio (db: ${DB_PATH})`);
|
|
19
|
+
}
|
|
20
|
+
//# sourceMappingURL=server.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) {
|
|
@@ -27,6 +28,18 @@ function tagsFilterClauses(tags) {
|
|
|
27
28
|
function extractStructuredContent(result) {
|
|
28
29
|
return result.structuredContent ?? null;
|
|
29
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
|
+
}
|
|
30
43
|
function resultCount(result) {
|
|
31
44
|
const structured = extractStructuredContent(result);
|
|
32
45
|
if (structured?.total_returned !== undefined) {
|
|
@@ -46,9 +59,6 @@ function returnedMemoryIds(result) {
|
|
|
46
59
|
.map((row) => String(row.id))
|
|
47
60
|
.filter((id) => id !== "undefined");
|
|
48
61
|
}
|
|
49
|
-
function telemetryPersistenceEnabled() {
|
|
50
|
-
return process.env.MEMORY_TELEMETRY !== "off";
|
|
51
|
-
}
|
|
52
62
|
function normalizeTextDate(value) {
|
|
53
63
|
if (!value)
|
|
54
64
|
return undefined;
|
|
@@ -101,18 +111,21 @@ function buildTelemetryWhere(params) {
|
|
|
101
111
|
}
|
|
102
112
|
return { clause: conditions.join(" AND "), args };
|
|
103
113
|
}
|
|
104
|
-
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 = "") {
|
|
105
118
|
const conditions = ["1=1"];
|
|
106
119
|
const args = [];
|
|
107
|
-
appendAgentFilter(conditions, args,
|
|
120
|
+
appendAgentFilter(conditions, args, `${columnPrefix}agent_id`, params.agent_id);
|
|
108
121
|
const dateFrom = normalizeDateBoundary(params.date_from, "start");
|
|
109
122
|
if (dateFrom) {
|
|
110
|
-
conditions.push(
|
|
123
|
+
conditions.push(`${columnPrefix}created_at >= ?`);
|
|
111
124
|
args.push(dateFrom);
|
|
112
125
|
}
|
|
113
126
|
const dateTo = normalizeDateBoundary(params.date_to, "end");
|
|
114
127
|
if (dateTo) {
|
|
115
|
-
conditions.push(
|
|
128
|
+
conditions.push(`${columnPrefix}created_at <= ?`);
|
|
116
129
|
args.push(dateTo);
|
|
117
130
|
}
|
|
118
131
|
return { clause: conditions.join(" AND "), args };
|
|
@@ -128,7 +141,7 @@ export function registerMemoryTools(server, database) {
|
|
|
128
141
|
const databaseProvider = () => resolveDatabase(database);
|
|
129
142
|
server.registerTool("memory_save", {
|
|
130
143
|
title: "Save Memory",
|
|
131
|
-
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.",
|
|
132
145
|
inputSchema: MemorySaveInputSchema.shape,
|
|
133
146
|
annotations: {
|
|
134
147
|
readOnlyHint: false,
|
|
@@ -166,8 +179,8 @@ export function registerMemoryTools(server, database) {
|
|
|
166
179
|
const id = newId("mem");
|
|
167
180
|
const ts = nowIso();
|
|
168
181
|
activeDb
|
|
169
|
-
.prepare(`INSERT INTO memories (id, type, content, tags, agent_id, importance, metadata, created_at, updated_at)
|
|
170
|
-
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)`)
|
|
171
184
|
.run({
|
|
172
185
|
id,
|
|
173
186
|
type: params.type,
|
|
@@ -176,6 +189,7 @@ export function registerMemoryTools(server, database) {
|
|
|
176
189
|
agent_id: params.agent_id ?? null,
|
|
177
190
|
importance: params.importance,
|
|
178
191
|
metadata: params.metadata ? JSON.stringify(params.metadata) : null,
|
|
192
|
+
workspace: getWorkspace(),
|
|
179
193
|
created_at: ts,
|
|
180
194
|
updated_at: ts,
|
|
181
195
|
});
|
|
@@ -226,9 +240,7 @@ export function registerMemoryTools(server, database) {
|
|
|
226
240
|
}, async (params) => {
|
|
227
241
|
const activeDb = await resolveDatabase(database);
|
|
228
242
|
const { clause: tagClause, params: tagParams } = tagsFilterClauses(params.tags);
|
|
229
|
-
const conditions = [
|
|
230
|
-
"m.rowid IN (SELECT rowid FROM memories_fts WHERE memories_fts MATCH ?)",
|
|
231
|
-
];
|
|
243
|
+
const conditions = [];
|
|
232
244
|
const sqlParams = [toFtsQuery(params.query)];
|
|
233
245
|
if (params.type) {
|
|
234
246
|
conditions.push("m.type = ?");
|
|
@@ -238,10 +250,18 @@ export function registerMemoryTools(server, database) {
|
|
|
238
250
|
conditions.push("m.agent_id = ?");
|
|
239
251
|
sqlParams.push(params.agent_id);
|
|
240
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.
|
|
241
258
|
const rows = activeDb
|
|
242
259
|
.prepare(`SELECT m.* FROM memories m
|
|
243
|
-
|
|
244
|
-
|
|
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
|
|
245
265
|
LIMIT ? OFFSET ?`)
|
|
246
266
|
.all(...sqlParams, ...tagParams, params.limit, params.offset);
|
|
247
267
|
if (rows.length === 0) {
|
|
@@ -536,7 +556,7 @@ export function registerMemoryTools(server, database) {
|
|
|
536
556
|
}));
|
|
537
557
|
server.registerTool("memory_usage_report", {
|
|
538
558
|
title: "Memory Usage Report",
|
|
539
|
-
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.",
|
|
540
560
|
inputSchema: MemoryUsageReportInputSchema.shape,
|
|
541
561
|
annotations: {
|
|
542
562
|
readOnlyHint: true,
|
|
@@ -602,6 +622,7 @@ export function registerMemoryTools(server, database) {
|
|
|
602
622
|
const successEvents = summaryRow.success_events ?? 0;
|
|
603
623
|
const errorEvents = summaryRow.error_events ?? 0;
|
|
604
624
|
const output = {
|
|
625
|
+
...telemetryOffNote(),
|
|
605
626
|
summary: {
|
|
606
627
|
total_events: totalEvents,
|
|
607
628
|
success_events: successEvents,
|
|
@@ -623,7 +644,7 @@ export function registerMemoryTools(server, database) {
|
|
|
623
644
|
}));
|
|
624
645
|
server.registerTool("memory_adoption_report", {
|
|
625
646
|
title: "Memory Adoption Report",
|
|
626
|
-
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.",
|
|
627
648
|
inputSchema: MemoryAdoptionReportInputSchema.shape,
|
|
628
649
|
annotations: {
|
|
629
650
|
readOnlyHint: true,
|
|
@@ -655,15 +676,16 @@ export function registerMemoryTools(server, database) {
|
|
|
655
676
|
FROM reasoning_sessions
|
|
656
677
|
WHERE ${sessionFilter.clause}`)
|
|
657
678
|
.get(...sessionFilter.args);
|
|
679
|
+
const joinedSessionFilter = buildSessionWhere(params, "reasoning_sessions.");
|
|
658
680
|
const zeroStepRow = activeDb
|
|
659
681
|
.prepare(`SELECT COUNT(*) as zero_step_sessions
|
|
660
682
|
FROM reasoning_sessions
|
|
661
683
|
LEFT JOIN reasoning_steps
|
|
662
684
|
ON reasoning_steps.session_id = reasoning_sessions.id
|
|
663
|
-
WHERE ${
|
|
685
|
+
WHERE ${joinedSessionFilter.clause}
|
|
664
686
|
GROUP BY reasoning_sessions.id
|
|
665
687
|
HAVING COUNT(reasoning_steps.id) = 0`)
|
|
666
|
-
.all(...
|
|
688
|
+
.all(...joinedSessionFilter.args);
|
|
667
689
|
const completionEvents = activeDb
|
|
668
690
|
.prepare(`SELECT
|
|
669
691
|
COUNT(*) as total,
|
|
@@ -748,6 +770,7 @@ export function registerMemoryTools(server, database) {
|
|
|
748
770
|
riskFlags.push("no_positive_feedback_recorded");
|
|
749
771
|
}
|
|
750
772
|
const output = {
|
|
773
|
+
...telemetryOffNote(),
|
|
751
774
|
funnel: {
|
|
752
775
|
reasoning_started: reasoningStarted,
|
|
753
776
|
reasoning_completed: reasoningCompleted,
|
|
@@ -773,7 +796,7 @@ export function registerMemoryTools(server, database) {
|
|
|
773
796
|
}));
|
|
774
797
|
server.registerTool("memory_agent_scorecard", {
|
|
775
798
|
title: "Memory Agent Scorecard",
|
|
776
|
-
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.",
|
|
777
800
|
inputSchema: MemoryAgentScorecardInputSchema.shape,
|
|
778
801
|
annotations: {
|
|
779
802
|
readOnlyHint: true,
|
|
@@ -814,11 +837,13 @@ export function registerMemoryTools(server, database) {
|
|
|
814
837
|
.all(...telemetryFilter.args, ...sessionFilter.args, params.limit);
|
|
815
838
|
const results = rows.map((row) => {
|
|
816
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.
|
|
817
842
|
const agentSessionFilter = buildSessionWhere({
|
|
818
843
|
agent_id: agentId,
|
|
819
844
|
date_from: params.date_from,
|
|
820
845
|
date_to: params.date_to,
|
|
821
|
-
});
|
|
846
|
+
}, "reasoning_sessions.");
|
|
822
847
|
const agentEventFilter = buildTelemetryWhere({
|
|
823
848
|
agent_id: agentId,
|
|
824
849
|
date_from: params.date_from,
|
|
@@ -908,7 +933,7 @@ export function registerMemoryTools(server, database) {
|
|
|
908
933
|
recommendations: recommendationMap[dominantBehavior],
|
|
909
934
|
};
|
|
910
935
|
});
|
|
911
|
-
const output = { results };
|
|
936
|
+
const output = { ...telemetryOffNote(), results };
|
|
912
937
|
return {
|
|
913
938
|
content: [{ type: "text", text: toLimitedJson(output) }],
|
|
914
939
|
structuredContent: output,
|
|
@@ -916,7 +941,7 @@ export function registerMemoryTools(server, database) {
|
|
|
916
941
|
}));
|
|
917
942
|
server.registerTool("memory_record_usage_feedback", {
|
|
918
943
|
title: "Record Memory Usage Feedback",
|
|
919
|
-
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.",
|
|
920
945
|
inputSchema: MemoryRecordUsageFeedbackInputSchema.shape,
|
|
921
946
|
annotations: {
|
|
922
947
|
readOnlyHint: false,
|
|
@@ -939,7 +964,7 @@ export function registerMemoryTools(server, database) {
|
|
|
939
964
|
reason_length: params.reason?.length ?? 0,
|
|
940
965
|
},
|
|
941
966
|
outputShape: {
|
|
942
|
-
recorded: result.
|
|
967
|
+
recorded: result.structuredContent?.recorded === true,
|
|
943
968
|
},
|
|
944
969
|
metadata: {
|
|
945
970
|
usefulness: params.usefulness,
|
|
@@ -947,17 +972,6 @@ export function registerMemoryTools(server, database) {
|
|
|
947
972
|
},
|
|
948
973
|
}),
|
|
949
974
|
}, async (params) => {
|
|
950
|
-
if (!telemetryPersistenceEnabled()) {
|
|
951
|
-
return {
|
|
952
|
-
content: [
|
|
953
|
-
{
|
|
954
|
-
type: "text",
|
|
955
|
-
text: "Error: Telemetry persistence is disabled; memory feedback cannot be recorded.",
|
|
956
|
-
},
|
|
957
|
-
],
|
|
958
|
-
isError: true,
|
|
959
|
-
};
|
|
960
|
-
}
|
|
961
975
|
const activeDb = await resolveDatabase(database);
|
|
962
976
|
const existing = activeDb
|
|
963
977
|
.prepare(`SELECT id FROM memories WHERE id = ?`)
|