@nhatnguyen9317/memory-mcp-server 1.1.2 → 1.2.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 +35 -0
- package/GUIDELINES.md +2 -2
- package/README.md +4 -0
- package/dist/constants.js +12 -1
- package/dist/schemas/reasoning.js +6 -1
- package/dist/tools/memory.js +30 -16
- package/dist/tools/reasoning.js +115 -10
- package/dist/utils.js +11 -3
- package/package.json +3 -2
package/CHANGELOG.md
ADDED
|
@@ -0,0 +1,35 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
## 1.2.0 (2026-07-10)
|
|
4
|
+
|
|
5
|
+
Theme: close the memory value loop — recall becomes automatic, cleanup becomes automatic, and usefulness becomes measurable.
|
|
6
|
+
|
|
7
|
+
### Added
|
|
8
|
+
|
|
9
|
+
- **Auto-recall in `reasoning_start_session`**: the response now includes `related_memories` — up to 3 saved memories relevant to the session title (id, type, importance, tags, snippet), matched via full-text search. Configure the limit with `MEMORY_AUTO_RECALL_LIMIT` (default 3, `0` disables). Recall is best-effort: a failed lookup never blocks session creation.
|
|
10
|
+
- **Stale-session cleanup**: `in_progress` sessions untouched for longer than `MEMORY_SESSION_TTL_HOURS` (default 24, `0` disables) are automatically marked `abandoned` (conclusion `auto-abandoned: stale session`) the next time `reasoning_start_session` is called. The response reports `auto_abandoned_sessions` when cleanup happened, and lists up to 5 other still-open sessions under `open_sessions` with an `open_sessions_warning`.
|
|
11
|
+
- **Usage feedback at completion**: `reasoning_complete_session` accepts `used_memory_ids` (string[], max 50) — ids of memories that actually helped during the session. The server records a `used` usage-feedback telemetry event per id; unknown ids produce warnings instead of errors. The response includes `used_memory_feedback_recorded`.
|
|
12
|
+
- **Recall telemetry**: `memory_search` and `memory_list` events now record the returned memory ids (bounded to 20) in `output_shape.memory_ids`, so recalled-but-unused memories become measurable.
|
|
13
|
+
- `CHANGELOG.md`, GitHub Actions CI (`npm test` on Node 22), and direct unit tests for the memory CRUD tools.
|
|
14
|
+
|
|
15
|
+
### Changed
|
|
16
|
+
|
|
17
|
+
- **`memory_record_usage_feedback` verification widened**: `event_id` may now reference any event that recalled the memory — `memory_get`, `memory_search`, or `memory_list` (previously only `memory_get`, which made verified feedback impossible in practice). Feedback without `event_id` is unchanged.
|
|
18
|
+
- **Adoption/scorecard reports** count feedback events regardless of `related_event_id`, so feedback recorded via `reasoning_complete_session` is included.
|
|
19
|
+
- **`memory_record_usage_feedback` output**: returns `{recorded: true, memory_id, usefulness}` instead of an `event_id` field that was always `null`.
|
|
20
|
+
- Documentation now matches actual behavior of `memory_mode='auto'`: it does **not** save a memory on its own; a memory is only created with `save_as_memory=true` or `memory_mode='always'`. (Behavior unchanged — the docs were wrong.) GUIDELINES version bumped to `2026-07-10.v1`.
|
|
21
|
+
- Tag filters (`tags` on search/list) treat `%`, `_`, and `\` literally instead of as SQL LIKE wildcards.
|
|
22
|
+
|
|
23
|
+
### Fixed
|
|
24
|
+
|
|
25
|
+
- Telemetry `not_saved_reason_category` now correctly records `zero_step` for zero-step completions (substring mismatch made it unreachable).
|
|
26
|
+
- Stale internal references to better-sqlite3; two accidentally tracked temp `.db` files removed from git.
|
|
27
|
+
|
|
28
|
+
### Upgrade notes
|
|
29
|
+
|
|
30
|
+
- Existing dangling `in_progress` sessions will be auto-abandoned on your first `reasoning_start_session` after upgrading. This is intended cleanup; set `MEMORY_SESSION_TTL_HOURS=0` before starting the server if you want to keep them open.
|
|
31
|
+
- No schema migration required; the SQLite database is fully compatible.
|
|
32
|
+
|
|
33
|
+
## 1.1.5 and earlier
|
|
34
|
+
|
|
35
|
+
See git history.
|
package/GUIDELINES.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Memory MCP Guidelines
|
|
2
2
|
|
|
3
|
-
Version: 2026-07-
|
|
3
|
+
Version: 2026-07-10.v1
|
|
4
4
|
|
|
5
5
|
This file is the single source of truth for how an agent should use this MCP.
|
|
6
6
|
|
|
@@ -28,7 +28,7 @@ This file is the single source of truth for how an agent should use this MCP.
|
|
|
28
28
|
- `memory_delete`: remove unsafe, duplicated, or wrong memory
|
|
29
29
|
- `reasoning_start_session`: open live trace capture for a non-trivial task
|
|
30
30
|
- `reasoning_add_step`: log a decision, hypothesis, rejected option, or meaningful observation
|
|
31
|
-
- `reasoning_complete_session`: close the session and optionally persist only the conclusion
|
|
31
|
+
- `reasoning_complete_session`: close the session and optionally persist only the conclusion; the conclusion is saved as a memory only when you pass `save_as_memory=true` or `memory_mode='always'` — the default (`auto`) does not save on its own
|
|
32
32
|
|
|
33
33
|
## Do Not Store
|
|
34
34
|
|
package/README.md
CHANGED
|
@@ -30,6 +30,10 @@ High-level split:
|
|
|
30
30
|
|
|
31
31
|
No native addon build is required.
|
|
32
32
|
|
|
33
|
+
> Note: `node:sqlite` is still an experimental Node.js API on Node 22. The server
|
|
34
|
+
> works reliably, but Node prints an `ExperimentalWarning` to stderr on startup,
|
|
35
|
+
> and the API surface may change between Node releases.
|
|
36
|
+
|
|
33
37
|
## Install
|
|
34
38
|
|
|
35
39
|
```bash
|
package/dist/constants.js
CHANGED
|
@@ -2,8 +2,19 @@ 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.
|
|
5
|
+
export const MCP_VERSION = "1.2.0";
|
|
6
6
|
export const TELEMETRY_ENABLED = process.env.MEMORY_TELEMETRY !== "off";
|
|
7
|
+
/**
|
|
8
|
+
* Hours after which an untouched in_progress reasoning session is
|
|
9
|
+
* auto-abandoned on the next reasoning_start_session call.
|
|
10
|
+
* Override with MEMORY_SESSION_TTL_HOURS; set to 0 (or negative) to disable.
|
|
11
|
+
*/
|
|
12
|
+
export const SESSION_TTL_HOURS = Number(process.env.MEMORY_SESSION_TTL_HOURS ?? 24);
|
|
13
|
+
/**
|
|
14
|
+
* Max related memories auto-recalled in the reasoning_start_session response.
|
|
15
|
+
* Override with MEMORY_AUTO_RECALL_LIMIT; set to 0 to disable auto-recall.
|
|
16
|
+
*/
|
|
17
|
+
export const AUTO_RECALL_LIMIT = Number(process.env.MEMORY_AUTO_RECALL_LIMIT ?? 3);
|
|
7
18
|
/**
|
|
8
19
|
* Location of the SQLite database file.
|
|
9
20
|
* Override with the MEMORY_DB_PATH environment variable, e.g. to keep
|
|
@@ -131,7 +131,7 @@ export const ReasoningCompleteSessionInputSchema = z
|
|
|
131
131
|
memory_mode: z
|
|
132
132
|
.enum(["auto", "always", "never"])
|
|
133
133
|
.optional()
|
|
134
|
-
.describe("Preferred memory persistence mode. 'auto'
|
|
134
|
+
.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
135
|
memory_type: z
|
|
136
136
|
.enum(["fact", "preference", "episodic", "decision", "reasoning_summary"])
|
|
137
137
|
.optional()
|
|
@@ -154,6 +154,11 @@ export const ReasoningCompleteSessionInputSchema = z
|
|
|
154
154
|
.max(500)
|
|
155
155
|
.optional()
|
|
156
156
|
.describe("Required when memory_mode='never' to explain why the conclusion should not be kept as durable memory."),
|
|
157
|
+
used_memory_ids: z
|
|
158
|
+
.array(z.string().min(1))
|
|
159
|
+
.max(50)
|
|
160
|
+
.default([])
|
|
161
|
+
.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
162
|
})
|
|
158
163
|
.strict();
|
|
159
164
|
//# sourceMappingURL=reasoning.js.map
|
package/dist/tools/memory.js
CHANGED
|
@@ -14,11 +14,14 @@ function rowToRecord(row) {
|
|
|
14
14
|
updated_at: row.updated_at,
|
|
15
15
|
};
|
|
16
16
|
}
|
|
17
|
+
function escapeLikePattern(value) {
|
|
18
|
+
return value.replace(/[\\%_]/g, (char) => `\\${char}`);
|
|
19
|
+
}
|
|
17
20
|
function tagsFilterClauses(tags) {
|
|
18
21
|
if (!tags || tags.length === 0)
|
|
19
22
|
return { clause: "", params: [] };
|
|
20
|
-
const clause = tags.map(() => `tags LIKE
|
|
21
|
-
const params = tags.map((tag) => `%"${tag}"%`);
|
|
23
|
+
const clause = tags.map(() => `tags LIKE ? ESCAPE '\\'`).join(" AND ");
|
|
24
|
+
const params = tags.map((tag) => `%"${escapeLikePattern(tag)}"%`);
|
|
22
25
|
return { clause: ` AND ${clause}`, params };
|
|
23
26
|
}
|
|
24
27
|
function extractStructuredContent(result) {
|
|
@@ -33,6 +36,16 @@ function resultCount(result) {
|
|
|
33
36
|
return structured.results.length;
|
|
34
37
|
return result.content[0]?.text.startsWith("No memories found") ? 0 : 1;
|
|
35
38
|
}
|
|
39
|
+
/** Ids of memories returned by a search/list call, bounded so telemetry rows stay small. */
|
|
40
|
+
function returnedMemoryIds(result) {
|
|
41
|
+
const structured = extractStructuredContent(result);
|
|
42
|
+
if (!Array.isArray(structured?.results))
|
|
43
|
+
return [];
|
|
44
|
+
return structured.results
|
|
45
|
+
.slice(0, 20)
|
|
46
|
+
.map((row) => String(row.id))
|
|
47
|
+
.filter((id) => id !== "undefined");
|
|
48
|
+
}
|
|
36
49
|
function telemetryPersistenceEnabled() {
|
|
37
50
|
return process.env.MEMORY_TELEMETRY !== "off";
|
|
38
51
|
}
|
|
@@ -207,7 +220,7 @@ export function registerMemoryTools(server, database) {
|
|
|
207
220
|
},
|
|
208
221
|
outputShape: {
|
|
209
222
|
result_count: resultCount(result),
|
|
210
|
-
|
|
223
|
+
memory_ids: returnedMemoryIds(result),
|
|
211
224
|
},
|
|
212
225
|
}),
|
|
213
226
|
}, async (params) => {
|
|
@@ -280,6 +293,7 @@ export function registerMemoryTools(server, database) {
|
|
|
280
293
|
outputShape: {
|
|
281
294
|
result_count: resultCount(result),
|
|
282
295
|
has_more: extractStructuredContent(result)?.has_more === true,
|
|
296
|
+
memory_ids: returnedMemoryIds(result),
|
|
283
297
|
},
|
|
284
298
|
}),
|
|
285
299
|
}, async (params) => {
|
|
@@ -696,7 +710,6 @@ export function registerMemoryTools(server, database) {
|
|
|
696
710
|
FROM tool_usage_events
|
|
697
711
|
WHERE ${eventFilter.clause}
|
|
698
712
|
AND operation_type = 'feedback'
|
|
699
|
-
AND related_event_id IS NOT NULL
|
|
700
713
|
AND status = 'success'`)
|
|
701
714
|
.get(...eventFilter.args);
|
|
702
715
|
const agentBreakdown = activeDb
|
|
@@ -845,7 +858,6 @@ export function registerMemoryTools(server, database) {
|
|
|
845
858
|
FROM tool_usage_events
|
|
846
859
|
WHERE ${agentEventFilter.clause}
|
|
847
860
|
AND operation_type = 'feedback'
|
|
848
|
-
AND related_event_id IS NOT NULL
|
|
849
861
|
AND status = 'success'
|
|
850
862
|
AND json_extract(metadata, '$.usefulness') = 'used'`)
|
|
851
863
|
.get(...agentEventFilter.args);
|
|
@@ -928,9 +940,6 @@ export function registerMemoryTools(server, database) {
|
|
|
928
940
|
},
|
|
929
941
|
outputShape: {
|
|
930
942
|
recorded: result.isError !== true,
|
|
931
|
-
event_id: typeof result.structuredContent?.event_id === "string"
|
|
932
|
-
? result.structuredContent.event_id
|
|
933
|
-
: null,
|
|
934
943
|
},
|
|
935
944
|
metadata: {
|
|
936
945
|
usefulness: params.usefulness,
|
|
@@ -966,18 +975,23 @@ export function registerMemoryTools(server, database) {
|
|
|
966
975
|
}
|
|
967
976
|
if (params.event_id) {
|
|
968
977
|
const relatedEvent = activeDb
|
|
969
|
-
.prepare(`SELECT id
|
|
978
|
+
.prepare(`SELECT id, memory_id, output_shape
|
|
970
979
|
FROM tool_usage_events
|
|
971
|
-
WHERE id =
|
|
972
|
-
|
|
973
|
-
|
|
974
|
-
|
|
975
|
-
|
|
980
|
+
WHERE id = ?`)
|
|
981
|
+
.get(params.event_id);
|
|
982
|
+
const recalledIds = relatedEvent
|
|
983
|
+
? parseJsonObject(relatedEvent.output_shape)?.memory_ids
|
|
984
|
+
: undefined;
|
|
985
|
+
const verified = relatedEvent !== undefined &&
|
|
986
|
+
(relatedEvent.memory_id === params.memory_id ||
|
|
987
|
+
(Array.isArray(recalledIds) &&
|
|
988
|
+
recalledIds.includes(params.memory_id)));
|
|
989
|
+
if (!verified) {
|
|
976
990
|
return {
|
|
977
991
|
content: [
|
|
978
992
|
{
|
|
979
993
|
type: "text",
|
|
980
|
-
text: `Error: Related event '${params.event_id}' cannot be verified for memory '${params.memory_id}'. Use
|
|
994
|
+
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
995
|
},
|
|
982
996
|
],
|
|
983
997
|
isError: true,
|
|
@@ -985,7 +999,7 @@ export function registerMemoryTools(server, database) {
|
|
|
985
999
|
}
|
|
986
1000
|
}
|
|
987
1001
|
const output = {
|
|
988
|
-
|
|
1002
|
+
recorded: true,
|
|
989
1003
|
memory_id: params.memory_id,
|
|
990
1004
|
usefulness: params.usefulness,
|
|
991
1005
|
};
|
package/dist/tools/reasoning.js
CHANGED
|
@@ -1,6 +1,7 @@
|
|
|
1
1
|
import { ReasoningAddStepInputSchema, ReasoningCompleteSessionInputSchema, ReasoningGetSessionOutlineInputSchema, ReasoningGetTraceInputSchema, ReasoningListMilestonesInputSchema, ReasoningListSessionsInputSchema, ReasoningMarkStepInputSchema, ReasoningSearchStepsInputSchema, ReasoningStartSessionInputSchema, } from "../schemas/reasoning.js";
|
|
2
|
-
import {
|
|
3
|
-
import {
|
|
2
|
+
import { AUTO_RECALL_LIMIT, SESSION_TTL_HOURS } from "../constants.js";
|
|
3
|
+
import { handleToolError, newId, nowIso, parseJsonArray, toFtsOrQuery, toFtsQuery, toLimitedJson, } from "../utils.js";
|
|
4
|
+
import { recordToolUsageEvent, withTelemetry } from "./telemetry.js";
|
|
4
5
|
function sessionRowToRecord(row, stepCount) {
|
|
5
6
|
return {
|
|
6
7
|
id: row.id,
|
|
@@ -117,6 +118,43 @@ async function resolveDatabase(database) {
|
|
|
117
118
|
defaultDatabasePromise ??= import("../db.js").then((module) => module.db);
|
|
118
119
|
return defaultDatabasePromise;
|
|
119
120
|
}
|
|
121
|
+
function abandonStaleSessions(database, now) {
|
|
122
|
+
if (SESSION_TTL_HOURS <= 0)
|
|
123
|
+
return 0;
|
|
124
|
+
const cutoff = new Date(Date.now() - SESSION_TTL_HOURS * 3_600_000).toISOString();
|
|
125
|
+
const result = database
|
|
126
|
+
.prepare(`UPDATE reasoning_sessions
|
|
127
|
+
SET status = 'abandoned',
|
|
128
|
+
conclusion = COALESCE(conclusion, 'auto-abandoned: stale session'),
|
|
129
|
+
updated_at = ?
|
|
130
|
+
WHERE status = 'in_progress' AND updated_at < ?`)
|
|
131
|
+
.run(now, cutoff);
|
|
132
|
+
return Number(result.changes);
|
|
133
|
+
}
|
|
134
|
+
function recallRelatedMemories(database, title) {
|
|
135
|
+
if (AUTO_RECALL_LIMIT <= 0)
|
|
136
|
+
return [];
|
|
137
|
+
try {
|
|
138
|
+
const rows = database
|
|
139
|
+
.prepare(`SELECT m.id, m.type, m.content, m.tags, m.importance
|
|
140
|
+
FROM memories m
|
|
141
|
+
WHERE m.rowid IN (SELECT rowid FROM memories_fts WHERE memories_fts MATCH ?)
|
|
142
|
+
ORDER BY m.importance DESC, m.updated_at DESC
|
|
143
|
+
LIMIT ?`)
|
|
144
|
+
.all(toFtsOrQuery(title), AUTO_RECALL_LIMIT);
|
|
145
|
+
return rows.map((row) => ({
|
|
146
|
+
id: row.id,
|
|
147
|
+
type: row.type,
|
|
148
|
+
importance: row.importance,
|
|
149
|
+
tags: parseJsonArray(row.tags),
|
|
150
|
+
snippet: compactSnippetText(row.content),
|
|
151
|
+
}));
|
|
152
|
+
}
|
|
153
|
+
catch {
|
|
154
|
+
// Recall is best-effort; a bad FTS query must never block session creation.
|
|
155
|
+
return [];
|
|
156
|
+
}
|
|
157
|
+
}
|
|
120
158
|
export function registerReasoningTools(server, database) {
|
|
121
159
|
const databaseProvider = () => resolveDatabase(database);
|
|
122
160
|
server.registerTool("reasoning_start_session", {
|
|
@@ -127,7 +165,10 @@ Args:
|
|
|
127
165
|
- title (string, required): Short description of the task/question, e.g. "Diagnose flaky checkout test".
|
|
128
166
|
- agent_id (string, optional): Identifier for the agent/persona running this session.
|
|
129
167
|
|
|
130
|
-
Returns: JSON with the new session's id
|
|
168
|
+
Returns: JSON with the new session's id (pass it to reasoning_add_step and reasoning_complete_session), plus:
|
|
169
|
+
- related_memories: up to a few saved memories relevant to the title, auto-recalled by the server. Review them before starting work; if one helps, report it later via used_memory_ids on reasoning_complete_session.
|
|
170
|
+
- open_sessions / open_sessions_warning: other in_progress sessions you may have forgotten to close.
|
|
171
|
+
- auto_abandoned_sessions: count of stale in_progress sessions the server just cleaned up, if any.
|
|
131
172
|
|
|
132
173
|
Examples:
|
|
133
174
|
- Use when: starting to debug a complex issue, plan a multi-step task, or work through a decision with tradeoffs.
|
|
@@ -151,6 +192,13 @@ Examples:
|
|
|
151
192
|
: null,
|
|
152
193
|
outputShape: {
|
|
153
194
|
session_id: result.structuredContent?.session_id ?? null,
|
|
195
|
+
related_memory_count: Array.isArray(result.structuredContent?.related_memories)
|
|
196
|
+
? result.structuredContent.related_memories.length
|
|
197
|
+
: 0,
|
|
198
|
+
open_session_count: Array.isArray(result.structuredContent?.open_sessions)
|
|
199
|
+
? result.structuredContent.open_sessions.length
|
|
200
|
+
: 0,
|
|
201
|
+
auto_abandoned_sessions: result.structuredContent?.auto_abandoned_sessions ?? 0,
|
|
154
202
|
},
|
|
155
203
|
}),
|
|
156
204
|
}, async (params) => {
|
|
@@ -158,20 +206,41 @@ Examples:
|
|
|
158
206
|
const activeDb = await resolveDatabase(database);
|
|
159
207
|
const id = newId("sess");
|
|
160
208
|
const ts = nowIso();
|
|
209
|
+
const autoAbandoned = abandonStaleSessions(activeDb, ts);
|
|
161
210
|
activeDb
|
|
162
211
|
.prepare(`INSERT INTO reasoning_sessions (id, title, agent_id, status, conclusion, created_at, updated_at)
|
|
163
212
|
VALUES (?, ?, ?, 'in_progress', NULL, ?, ?)`)
|
|
164
213
|
.run(id, params.title, params.agent_id ?? null, ts, ts);
|
|
214
|
+
const openSessions = activeDb
|
|
215
|
+
.prepare(`SELECT id, title, updated_at FROM reasoning_sessions
|
|
216
|
+
WHERE status = 'in_progress' AND id != ?
|
|
217
|
+
ORDER BY updated_at DESC
|
|
218
|
+
LIMIT 5`)
|
|
219
|
+
.all(id);
|
|
220
|
+
const relatedMemories = recallRelatedMemories(activeDb, params.title);
|
|
165
221
|
const output = {
|
|
166
222
|
session_id: id,
|
|
167
223
|
title: params.title,
|
|
168
224
|
status: "in_progress",
|
|
225
|
+
related_memories: relatedMemories,
|
|
226
|
+
...(openSessions.length > 0
|
|
227
|
+
? {
|
|
228
|
+
open_sessions_warning: `You have ${openSessions.length} other in_progress session(s). Close finished ones with reasoning_complete_session.`,
|
|
229
|
+
open_sessions: openSessions,
|
|
230
|
+
}
|
|
231
|
+
: {}),
|
|
232
|
+
...(autoAbandoned > 0
|
|
233
|
+
? { auto_abandoned_sessions: autoAbandoned }
|
|
234
|
+
: {}),
|
|
169
235
|
};
|
|
236
|
+
const recallNote = relatedMemories.length > 0
|
|
237
|
+
? ` Found ${relatedMemories.length} related memories — review them before starting.`
|
|
238
|
+
: "";
|
|
170
239
|
return {
|
|
171
240
|
content: [
|
|
172
241
|
{
|
|
173
242
|
type: "text",
|
|
174
|
-
text: `Reasoning session started with id ${id}
|
|
243
|
+
text: `Reasoning session started with id ${id}.${recallNote}\n\n${toLimitedJson(output)}`,
|
|
175
244
|
},
|
|
176
245
|
],
|
|
177
246
|
structuredContent: output,
|
|
@@ -850,13 +919,14 @@ Args:
|
|
|
850
919
|
- conclusion (string, required): The final answer/decision reached.
|
|
851
920
|
- status ('completed'|'abandoned', default 'completed'): Use 'abandoned' if the task was dropped without a real conclusion.
|
|
852
921
|
- save_as_memory (boolean, default false): If true, also create a memory with this conclusion.
|
|
853
|
-
- memory_mode ('auto'|'always'|'never', optional):
|
|
922
|
+
- memory_mode ('auto'|'always'|'never', optional): 'auto' (default) does NOT save a memory 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.
|
|
854
923
|
- memory_type (optional): Memory type to use when a completion is persisted.
|
|
855
924
|
- memory_importance (optional): Importance to use when a completion is persisted.
|
|
856
925
|
- memory_tags (string[], default []): Tags for the created memory.
|
|
857
926
|
- not_saved_reason (optional): Required when memory_mode='never'.
|
|
927
|
+
- used_memory_ids (string[], default []): Ids of memories that actually helped during this session (e.g. from related_memories returned by reasoning_start_session). The server records a 'used' usage-feedback event for each.
|
|
858
928
|
|
|
859
|
-
Returns: JSON with the updated session, created memory id if any, and skip warnings when memory is not saved.
|
|
929
|
+
Returns: JSON with the updated session, created memory id if any, usage-feedback count, and skip warnings when memory is not saved.
|
|
860
930
|
|
|
861
931
|
Error Handling:
|
|
862
932
|
- Returns "Error: Session '<id>' not found" if the id does not exist.
|
|
@@ -886,7 +956,7 @@ Error Handling:
|
|
|
886
956
|
reasonCategory = "caller_request";
|
|
887
957
|
else if (params.status === "abandoned")
|
|
888
958
|
reasonCategory = "not_completed";
|
|
889
|
-
else if (notSavedReason?.includes("
|
|
959
|
+
else if (notSavedReason?.includes("no reasoning steps")) {
|
|
890
960
|
reasonCategory = "zero_step";
|
|
891
961
|
}
|
|
892
962
|
return {
|
|
@@ -900,6 +970,7 @@ Error Handling:
|
|
|
900
970
|
memory_type: params.memory_type ?? null,
|
|
901
971
|
memory_importance: params.memory_importance ?? null,
|
|
902
972
|
tag_count: params.memory_tags?.length ?? 0,
|
|
973
|
+
used_memory_count: params.used_memory_ids?.length ?? 0,
|
|
903
974
|
},
|
|
904
975
|
outputShape: {
|
|
905
976
|
memory_id_present: typeof structured?.memory_id === "string",
|
|
@@ -973,6 +1044,36 @@ Error Handling:
|
|
|
973
1044
|
}), ts, ts);
|
|
974
1045
|
return nextMemoryId;
|
|
975
1046
|
});
|
|
1047
|
+
const usedMemoryWarnings = [];
|
|
1048
|
+
let usedMemoryFeedbackRecorded = 0;
|
|
1049
|
+
for (const usedMemoryId of new Set(params.used_memory_ids ?? [])) {
|
|
1050
|
+
const exists = activeDb
|
|
1051
|
+
.prepare(`SELECT id FROM memories WHERE id = ?`)
|
|
1052
|
+
.get(usedMemoryId);
|
|
1053
|
+
if (!exists) {
|
|
1054
|
+
usedMemoryWarnings.push(`Memory '${usedMemoryId}' not found; usage feedback skipped.`);
|
|
1055
|
+
continue;
|
|
1056
|
+
}
|
|
1057
|
+
const feedbackEventId = await recordToolUsageEvent(activeDb, {
|
|
1058
|
+
toolName: "memory_record_usage_feedback",
|
|
1059
|
+
operationType: "feedback",
|
|
1060
|
+
accessType: "write",
|
|
1061
|
+
status: "success",
|
|
1062
|
+
agentId: session.agent_id,
|
|
1063
|
+
sessionId: params.session_id,
|
|
1064
|
+
memoryId: usedMemoryId,
|
|
1065
|
+
metadata: {
|
|
1066
|
+
usefulness: "used",
|
|
1067
|
+
source: "reasoning_complete_session",
|
|
1068
|
+
},
|
|
1069
|
+
});
|
|
1070
|
+
if (feedbackEventId) {
|
|
1071
|
+
usedMemoryFeedbackRecorded += 1;
|
|
1072
|
+
}
|
|
1073
|
+
else {
|
|
1074
|
+
usedMemoryWarnings.push(`Telemetry is disabled; usage feedback for '${usedMemoryId}' was not recorded.`);
|
|
1075
|
+
}
|
|
1076
|
+
}
|
|
976
1077
|
const updatedRow = activeDb
|
|
977
1078
|
.prepare(`SELECT * FROM reasoning_sessions WHERE id = ?`)
|
|
978
1079
|
.get(params.session_id);
|
|
@@ -981,9 +1082,13 @@ Error Handling:
|
|
|
981
1082
|
session: record,
|
|
982
1083
|
memory_id: memoryId,
|
|
983
1084
|
not_saved_reason: notSavedReason,
|
|
984
|
-
|
|
985
|
-
|
|
986
|
-
|
|
1085
|
+
used_memory_feedback_recorded: usedMemoryFeedbackRecorded,
|
|
1086
|
+
warnings: [
|
|
1087
|
+
...(stepCount === 0 && params.status === "completed"
|
|
1088
|
+
? ["Session completed with zero reasoning steps."]
|
|
1089
|
+
: []),
|
|
1090
|
+
...usedMemoryWarnings,
|
|
1091
|
+
],
|
|
987
1092
|
};
|
|
988
1093
|
return {
|
|
989
1094
|
content: [{ type: "text", text: toLimitedJson(output) }],
|
package/dist/utils.js
CHANGED
|
@@ -30,12 +30,20 @@ export function parseJsonObject(text) {
|
|
|
30
30
|
}
|
|
31
31
|
/** FTS5 MATCH queries break on raw punctuation; wrap terms as a safe prefix query. */
|
|
32
32
|
export function toFtsQuery(raw) {
|
|
33
|
-
const terms = raw
|
|
33
|
+
const terms = ftsTerms(raw);
|
|
34
|
+
return terms.length ? terms.join(" ") : '""';
|
|
35
|
+
}
|
|
36
|
+
/** Like toFtsQuery but matches ANY term — used for fuzzy recall by title. */
|
|
37
|
+
export function toFtsOrQuery(raw) {
|
|
38
|
+
const terms = ftsTerms(raw);
|
|
39
|
+
return terms.length ? terms.join(" OR ") : '""';
|
|
40
|
+
}
|
|
41
|
+
function ftsTerms(raw) {
|
|
42
|
+
return raw
|
|
34
43
|
.trim()
|
|
35
44
|
.split(/\s+/)
|
|
36
45
|
.filter(Boolean)
|
|
37
46
|
.map((t) => `"${t.replace(/"/g, '""')}"*`);
|
|
38
|
-
return terms.length ? terms.join(" ") : '""';
|
|
39
47
|
}
|
|
40
48
|
/** Serialize a value to text, truncating with a clear message if it exceeds CHARACTER_LIMIT. */
|
|
41
49
|
export function toLimitedJson(value) {
|
|
@@ -50,7 +58,7 @@ export function toLimitedJson(value) {
|
|
|
50
58
|
}
|
|
51
59
|
export function handleToolError(error) {
|
|
52
60
|
if (error instanceof Error) {
|
|
53
|
-
//
|
|
61
|
+
// node:sqlite constraint violations
|
|
54
62
|
if (error.message.includes("CHECK constraint failed")) {
|
|
55
63
|
return `Error: Invalid value provided (${error.message}). Check allowed ranges/enums in the tool description.`;
|
|
56
64
|
}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@nhatnguyen9317/memory-mcp-server",
|
|
3
|
-
"version": "1.
|
|
3
|
+
"version": "1.2.0",
|
|
4
4
|
"description": "MCP server for persisting agent long-term memory and step-by-step reasoning traces in SQLite",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"main": "dist/index.js",
|
|
@@ -14,7 +14,8 @@
|
|
|
14
14
|
"dist/types.js",
|
|
15
15
|
"dist/utils.js",
|
|
16
16
|
"README.md",
|
|
17
|
-
"GUIDELINES.md"
|
|
17
|
+
"GUIDELINES.md",
|
|
18
|
+
"CHANGELOG.md"
|
|
18
19
|
],
|
|
19
20
|
"bin": {
|
|
20
21
|
"memory-mcp-server": "dist/index.js"
|