@nhatnguyen9317/memory-mcp-server 1.3.1 → 1.3.2
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 +19 -0
- package/GUIDELINES.md +64 -21
- package/dist/constants.js +1 -1
- package/dist/schemas/memory.js +1 -1
- package/dist/server.js +10 -0
- package/dist/tools/memory.js +6 -6
- package/dist/tools/reasoning.js +2 -2
- package/package.json +1 -1
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,24 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## 1.3.2 (2026-07-18)
|
|
4
|
+
|
|
5
|
+
Theme: guide-contract alignment — `GUIDELINES.md`, tool descriptions, and server instructions now match what the code actually does, locked in by a new docs-consistency test; conflict-check and step-marking guidance tightened from soft suggestions into concrete triggers after live-store telemetry showed near-zero adoption.
|
|
6
|
+
|
|
7
|
+
### Added
|
|
8
|
+
|
|
9
|
+
- **Server-level `instructions`**: `runServer()` now passes an `instructions` string to the `McpServer` constructor (`src/server.ts`) summarizing the core reasoning/memory loop (start session → log steps → complete with conclusion/`used_memory_ids`; `save_as_memory` is opt-in; never store secrets), so MCP clients that surface server instructions show this guidance without an extra tool call.
|
|
10
|
+
- **`src/__tests__/docs-consistency.test.ts`**: locks two invariants against drift — every registered tool name must appear in `GUIDELINES.md`, and the guide must not contradict specific schema contracts (`memory_mode='never'` requires `not_saved_reason`; the `session_id` vs `step_id` distinction between `reasoning_add_step`/`reasoning_complete_session` and `reasoning_mark_step`).
|
|
11
|
+
|
|
12
|
+
### Changed
|
|
13
|
+
|
|
14
|
+
- **`GUIDELINES.md` bumped `2026-07-12.v5` → `2026-07-17.v6` → `2026-07-18.v7`**. v6: added trivial-vs-multi-step examples, clarified that `open_sessions` belonging to other agents/runs should be left alone, documented the `thought`/`action`/`observation` step fields, made `conclusion` required even when abandoning a session, clarified `memory_record_usage_feedback`'s five usefulness values and its no-session use case, added `memory_type`/`memory_importance` selection guidance, documented `get_usage_guide` in the Tool Reference, and clarified the `MEMORY_TELEMETRY` env var's scope. v7 (this release): live-store telemetry showed the conflict-check and mark-step guidance were soft suggestions that never fired even though their preconditions occurred in most sessions — both are now concrete, explicit steps (an IF/THEN conflict check on `related_memories`, and a listed set of trigger conditions for `reasoning_mark_step`) instead of vague "when it seems useful" phrasing.
|
|
15
|
+
- **Tool description clarity pass** (`src/schemas/memory.ts`, `src/tools/memory.ts`, `src/tools/reasoning.ts`): `memory_save` documents that it returns the created id; `memory_search`/`memory_list` document their filters and pagination; `memory_update` documents partial-update semantics and the append/remove/patch fields; `memory_delete` warns it is a hard, unrecoverable delete; `memory_record_usage_feedback` documents its five usefulness values; tag guidance reworded to "topics, not workspace or project names."
|
|
16
|
+
- `src/__tests__/reasoning-audit-tools.test.ts`: `guide_version`/`guidance_version` assertions synced to `2026-07-18.v7`.
|
|
17
|
+
|
|
18
|
+
### Notes
|
|
19
|
+
|
|
20
|
+
- Live-store telemetry (`MEMORY_TELEMETRY=on`) showed the manual memory CRUD surface (`memory_save`/`search`/`list`/`delete`) and the entire reasoning audit tier (`reasoning_get_trace`/`list_sessions`/`search_steps`/`list_milestones`/`get_session_outline`/`mark_step`) at zero real-world calls, while the automatic recall → save → feedback pipeline shows a 63% memory reuse rate. Recorded as an owner monitoring decision in `docs/design/2026-07-12-spec-v1.3.5-recall-refinements.md` §8.1: keep observing with the tightened guide; remove the affected tools in a future release if usage stays near zero.
|
|
21
|
+
|
|
3
22
|
## 1.3.1 (2026-07-14)
|
|
4
23
|
|
|
5
24
|
Theme: contributor documentation catches up with the code, plus a one-command way to teach an agent to use this MCP.
|
package/GUIDELINES.md
CHANGED
|
@@ -1,17 +1,24 @@
|
|
|
1
1
|
# Memory MCP Guidelines
|
|
2
2
|
|
|
3
|
-
Version: 2026-07-
|
|
3
|
+
Version: 2026-07-18.v7
|
|
4
4
|
|
|
5
5
|
This file is the single source of truth for how an agent should use this MCP.
|
|
6
6
|
It is organized around the three moments of a task where this MCP matters.
|
|
7
|
+
Tool schemas and descriptions are the source of truth for parameter contracts
|
|
8
|
+
(required fields, types, enums); this guide covers policy — when and why.
|
|
7
9
|
|
|
8
10
|
## Moment 1 — Task Start
|
|
9
11
|
|
|
10
12
|
1. Decide the task size first:
|
|
11
13
|
- Trivial one-step lookup: do NOT open a reasoning session and do NOT call
|
|
12
14
|
memory tools unless prior recall is genuinely needed. Stop here.
|
|
15
|
+
(Examples: read one config value, answer a question from context you
|
|
16
|
+
already have.)
|
|
13
17
|
- Anything multi-step, uncertain, or involving debugging, planning, review,
|
|
14
18
|
or trade-offs: call `reasoning_start_session` with a specific title.
|
|
19
|
+
(Examples: any bug hunt, any change touching more than one file.)
|
|
20
|
+
The title doubles as the recall query — favor concrete keywords
|
|
21
|
+
(component, module, error names) over generic phrasing.
|
|
15
22
|
2. Read what the server hands back — this is free recall, act on it:
|
|
16
23
|
- `related_memories`: saved knowledge matched to your title, ranked by
|
|
17
24
|
text relevance and biased toward your current workspace. Weak one-word
|
|
@@ -22,45 +29,75 @@ It is organized around the three moments of a task where this MCP matters.
|
|
|
22
29
|
— when you need to verify how a conclusion was reached, replay its origin
|
|
23
30
|
with `reasoning_get_trace(source.session_id)`. Remember which ones
|
|
24
31
|
actually help — you will report them at completion.
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
32
|
+
If `related_memories` has 2 or more entries, do not act on the first one
|
|
33
|
+
blindly: skim all the snippets for contradictions before proceeding.
|
|
34
|
+
- Agree or don't overlap → use the most relevant one(s) directly.
|
|
35
|
+
- Conflict, or you're unsure → call
|
|
36
|
+
`reasoning_get_trace(source.session_id)` on the newer, same-workspace
|
|
37
|
+
one *before* deciding, not after. Once resolved, clean up the losing
|
|
38
|
+
memory with `memory_update` or `memory_delete`.
|
|
39
|
+
- `open_sessions_warning` / `open_sessions`: sessions left in_progress.
|
|
40
|
+
Close the ones YOU opened and finished with
|
|
41
|
+
`reasoning_complete_session`. Leave sessions you don't recognize alone —
|
|
42
|
+
they may belong to another agent or a parallel run; stale ones are
|
|
43
|
+
auto-abandoned by the server. A completed or abandoned session cannot be
|
|
44
|
+
reopened: to resume interrupted work, start a new session and reference
|
|
45
|
+
the old one in the title or an early step.
|
|
28
46
|
3. Only call `memory_search` yourself when you need recall on a topic that is
|
|
29
47
|
NOT the session title (the server already searched the title for you).
|
|
30
48
|
|
|
31
49
|
## Moment 2 — During The Task
|
|
32
50
|
|
|
51
|
+
Every `reasoning_add_step` and `reasoning_complete_session` call requires the
|
|
52
|
+
`session_id` returned by `reasoning_start_session`; `reasoning_mark_step`
|
|
53
|
+
instead takes the `step_id` returned by `reasoning_add_step`.
|
|
54
|
+
|
|
33
55
|
- Log decisions, hypotheses, rejected options, conflicts, and meaningful
|
|
34
56
|
observations with `reasoning_add_step`. Routine mechanical actions do not
|
|
35
|
-
need steps.
|
|
57
|
+
need steps. Within a step: `thought` = your reasoning, `action` = what you
|
|
58
|
+
did, `observation` = what resulted — fill whichever apply (at least one).
|
|
36
59
|
- Prefer batch mode when it lowers friction: `reasoning_add_step` with
|
|
37
60
|
`steps: [{thought/action/observation}, ...]` logs up to 20 steps in one
|
|
38
61
|
call — ideal for recording a stretch of work you just finished instead of
|
|
39
62
|
pausing after every step. A post-hoc trace is far better than an empty one.
|
|
40
|
-
- Mark pivotal steps with `reasoning_mark_step`
|
|
41
|
-
|
|
42
|
-
|
|
63
|
+
- Mark pivotal steps with `reasoning_mark_step` in the same turn you log
|
|
64
|
+
them with `reasoning_add_step` — don't defer it, deferred marks get
|
|
65
|
+
forgotten. Call it whenever the step you just logged was any of: a choice
|
|
66
|
+
between alternatives (`decision`), an option you rejected (`decision`),
|
|
67
|
+
a genuine contradiction you found (`conflict`), an unverified guess you're
|
|
68
|
+
about to test (`hypothesis`), or a result that changed the direction of the
|
|
69
|
+
task (`milestone`). If none of these apply, skip it — not every step needs
|
|
70
|
+
a mark.
|
|
43
71
|
|
|
44
72
|
## Moment 3 — Task End
|
|
45
73
|
|
|
46
74
|
Always close the session with `reasoning_complete_session`:
|
|
47
75
|
|
|
48
|
-
- `conclusion`: the actual answer/decision, written to be reusable.
|
|
76
|
+
- `conclusion`: the actual answer/decision, written to be reusable. Required
|
|
77
|
+
even when abandoning — one line stating why the task was dropped is enough.
|
|
49
78
|
- `used_memory_ids`: ids of memories (e.g. from `related_memories`) that
|
|
50
|
-
genuinely helped. Report honestly, including reporting none.
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
79
|
+
genuinely helped. Report honestly, including reporting none. This is the
|
|
80
|
+
"used" feedback path when you have a session; call
|
|
81
|
+
`memory_record_usage_feedback` directly instead when there is no session to
|
|
82
|
+
close, or the moment you discover a recalled memory is stale or wrong. A
|
|
83
|
+
failed report (e.g. an unknown memory id) returns a warning and is not
|
|
84
|
+
recorded.
|
|
54
85
|
- Saving the conclusion as durable memory is opt-in: pass
|
|
55
86
|
`save_as_memory=true` or `memory_mode='always'`. The default (`auto`) does
|
|
56
87
|
NOT save on its own. Save when the conclusion would help a future task;
|
|
57
|
-
skip
|
|
88
|
+
skip with `memory_mode='never'` (requires `not_saved_reason`) when it is
|
|
58
89
|
one-off noise.
|
|
90
|
+
- When persisting, pick a `memory_type` (`fact`, `preference`, `episodic`,
|
|
91
|
+
`decision`, `reasoning_summary`) and a `memory_importance` (1–5 scale;
|
|
92
|
+
anchors: 5 = convention or decision affecting every task in the workspace,
|
|
93
|
+
3 = reusable pattern within one area, 1 = minor context note).
|
|
59
94
|
- If the task was dropped without a real conclusion, complete with
|
|
60
95
|
`status='abandoned'` instead of leaving the session open.
|
|
61
96
|
|
|
62
97
|
## Tool Reference
|
|
63
98
|
|
|
99
|
+
- `get_usage_guide`: returns this guide (with its version) at runtime
|
|
100
|
+
|
|
64
101
|
Durable memory:
|
|
65
102
|
|
|
66
103
|
- `memory_save`: store durable facts, decisions, preferences, or summaries.
|
|
@@ -72,10 +109,10 @@ Durable memory:
|
|
|
72
109
|
- `memory_get`: fetch one memory by exact id
|
|
73
110
|
- `memory_update`: correct an existing memory in place
|
|
74
111
|
- `memory_delete`: remove unsafe, duplicated, or wrong memory
|
|
75
|
-
- `memory_record_usage_feedback`: record
|
|
76
|
-
used
|
|
77
|
-
|
|
78
|
-
`
|
|
112
|
+
- `memory_record_usage_feedback`: record how a recalled memory turned out
|
|
113
|
+
(`used`, `ignored`, `irrelevant`, `stale`, `unsafe_to_use`) — prefer
|
|
114
|
+
`used_memory_ids` at completion for the common case; use this tool directly
|
|
115
|
+
for no-session tasks and for non-`used` reports
|
|
79
116
|
|
|
80
117
|
Reasoning traces:
|
|
81
118
|
|
|
@@ -90,12 +127,18 @@ Audit & reports (mostly for reviewers and operators, not everyday tasks):
|
|
|
90
127
|
`reasoning_get_session_outline`, `reasoning_search_steps`: navigate traces
|
|
91
128
|
by their pivotal moments
|
|
92
129
|
- `memory_usage_report`, `memory_adoption_report`, `memory_agent_scorecard`:
|
|
93
|
-
telemetry-backed views of how memory/reasoning is actually being used
|
|
94
|
-
|
|
95
|
-
|
|
130
|
+
telemetry-backed views of how memory/reasoning is actually being used
|
|
131
|
+
- Telemetry note: `MEMORY_TELEMETRY` is a server-side env var (`on`/`off`,
|
|
132
|
+
default `off`); agents cannot change it. Successful usage feedback and
|
|
133
|
+
session data are always recorded locally regardless of the setting — only
|
|
134
|
+
the full funnels and ratios in the reports above need `MEMORY_TELEMETRY=on`.
|
|
96
135
|
|
|
97
136
|
## Do Not Store
|
|
98
137
|
|
|
138
|
+
This list applies to durable memory — `memory_save` and conclusions persisted
|
|
139
|
+
via `save_as_memory`. Reasoning steps may summarize tool output briefly, but
|
|
140
|
+
secrets are banned everywhere.
|
|
141
|
+
|
|
99
142
|
- secrets, tokens, or credentials
|
|
100
143
|
- full hidden chain-of-thought
|
|
101
144
|
- transient debugging noise
|
package/dist/constants.js
CHANGED
|
@@ -2,7 +2,7 @@ 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.3.
|
|
5
|
+
export const MCP_VERSION = "1.3.2";
|
|
6
6
|
/**
|
|
7
7
|
* Diagnostics-event recording is opt-in: set MEMORY_TELEMETRY=on to enable.
|
|
8
8
|
* Read at call time so tests and long-lived processes can toggle it.
|
package/dist/schemas/memory.js
CHANGED
|
@@ -30,7 +30,7 @@ export const MemorySaveInputSchema = z
|
|
|
30
30
|
.array(z.string().min(1).max(50))
|
|
31
31
|
.max(20)
|
|
32
32
|
.default([])
|
|
33
|
-
.describe("Short lowercase labels for filtering/search, e.g. ['
|
|
33
|
+
.describe("Short lowercase topic labels for filtering/search, e.g. ['sqlite','backend'] — topics, not workspace or project names."),
|
|
34
34
|
importance: z
|
|
35
35
|
.number()
|
|
36
36
|
.int()
|
package/dist/server.js
CHANGED
|
@@ -5,10 +5,20 @@ import "./db.js"; // ensures schema is created before tools run
|
|
|
5
5
|
import { registerMemoryTools } from "./tools/memory.js";
|
|
6
6
|
import { registerReasoningTools } from "./tools/reasoning.js";
|
|
7
7
|
import { registerUsageGuideTool } from "./tools/usage-guide.js";
|
|
8
|
+
export const SERVER_INSTRUCTIONS = [
|
|
9
|
+
"Memory MCP: durable memory (memory_*) plus reasoning traces (reasoning_*).",
|
|
10
|
+
"Call get_usage_guide for the full policy guide before first use.",
|
|
11
|
+
"Core loop: reasoning_start_session at task start (skip for trivial one-step lookups); log pivotal steps with reasoning_add_step; always finish with reasoning_complete_session (conclusion + used_memory_ids).",
|
|
12
|
+
"Every reasoning_add_step/complete_session call requires the session_id returned by reasoning_start_session; reasoning_mark_step takes the step_id returned by reasoning_add_step.",
|
|
13
|
+
"Saving a conclusion as memory is opt-in (save_as_memory=true); memory_mode='never' requires not_saved_reason.",
|
|
14
|
+
"Tool schemas are the source of truth for parameter contracts. Never store secrets, tokens, or credentials.",
|
|
15
|
+
].join(" ");
|
|
8
16
|
export async function runServer() {
|
|
9
17
|
const server = new McpServer({
|
|
10
18
|
name: "memory-mcp-server",
|
|
11
19
|
version: MCP_VERSION,
|
|
20
|
+
}, {
|
|
21
|
+
instructions: SERVER_INSTRUCTIONS,
|
|
12
22
|
});
|
|
13
23
|
registerMemoryTools(server);
|
|
14
24
|
registerReasoningTools(server);
|
package/dist/tools/memory.js
CHANGED
|
@@ -141,7 +141,7 @@ export function registerMemoryTools(server, database) {
|
|
|
141
141
|
const databaseProvider = () => resolveDatabase(database);
|
|
142
142
|
server.registerTool("memory_save", {
|
|
143
143
|
title: "Save Memory",
|
|
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.",
|
|
144
|
+
description: "Persist a piece of long-term memory so it can be recalled in future sessions. Returns the created memory's id. Tags describe topics ('sqlite', 'auth', 'perf'), not locations — do not put workspace or project names in tags; the server records the workspace automatically.",
|
|
145
145
|
inputSchema: MemorySaveInputSchema.shape,
|
|
146
146
|
annotations: {
|
|
147
147
|
readOnlyHint: false,
|
|
@@ -209,7 +209,7 @@ export function registerMemoryTools(server, database) {
|
|
|
209
209
|
}));
|
|
210
210
|
server.registerTool("memory_search", {
|
|
211
211
|
title: "Search Memories",
|
|
212
|
-
description: "Full-text search over saved memories (content and tags), ranked by relevance.",
|
|
212
|
+
description: "Full-text search over saved memories (content and tags), ranked by relevance. Optional filters: type, agent_id, tags (results must contain all); paginate with limit (default 20, max 200) and offset.",
|
|
213
213
|
inputSchema: MemorySearchInputSchema.shape,
|
|
214
214
|
annotations: {
|
|
215
215
|
readOnlyHint: true,
|
|
@@ -287,7 +287,7 @@ export function registerMemoryTools(server, database) {
|
|
|
287
287
|
}));
|
|
288
288
|
server.registerTool("memory_list", {
|
|
289
289
|
title: "List Memories",
|
|
290
|
-
description: "List saved memories with optional filters, sorted
|
|
290
|
+
description: "List saved memories with optional filters (type, agent_id, tags, min_importance), sorted by created_at, updated_at (default, newest first), or importance.",
|
|
291
291
|
inputSchema: MemoryListInputSchema.shape,
|
|
292
292
|
annotations: {
|
|
293
293
|
readOnlyHint: true,
|
|
@@ -401,7 +401,7 @@ export function registerMemoryTools(server, database) {
|
|
|
401
401
|
}));
|
|
402
402
|
server.registerTool("memory_update", {
|
|
403
403
|
title: "Update Memory",
|
|
404
|
-
description: "Update one or more fields of an existing memory.",
|
|
404
|
+
description: "Update one or more fields of an existing memory. Partial update: only the fields you pass change; omitted fields are preserved. `tags`/`metadata` replace the whole value — use `tags_append`/`tags_remove`/`metadata_patch` for incremental changes. At least one updatable field is required.",
|
|
405
405
|
inputSchema: MemoryUpdateInputSchema.shape,
|
|
406
406
|
annotations: {
|
|
407
407
|
readOnlyHint: false,
|
|
@@ -514,7 +514,7 @@ export function registerMemoryTools(server, database) {
|
|
|
514
514
|
}));
|
|
515
515
|
server.registerTool("memory_delete", {
|
|
516
516
|
title: "Delete Memory",
|
|
517
|
-
description: "Permanently delete a memory by id.",
|
|
517
|
+
description: "Permanently delete a memory by id. Hard delete with no undo — prefer memory_update when the memory is merely wrong or outdated.",
|
|
518
518
|
inputSchema: MemoryDeleteInputSchema.shape,
|
|
519
519
|
annotations: {
|
|
520
520
|
readOnlyHint: false,
|
|
@@ -941,7 +941,7 @@ export function registerMemoryTools(server, database) {
|
|
|
941
941
|
}));
|
|
942
942
|
server.registerTool("memory_record_usage_feedback", {
|
|
943
943
|
title: "Record Memory Usage Feedback",
|
|
944
|
-
description: "Record
|
|
944
|
+
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.",
|
|
945
945
|
inputSchema: MemoryRecordUsageFeedbackInputSchema.shape,
|
|
946
946
|
annotations: {
|
|
947
947
|
readOnlyHint: false,
|
package/dist/tools/reasoning.js
CHANGED
|
@@ -228,7 +228,7 @@ Args:
|
|
|
228
228
|
|
|
229
229
|
Returns: JSON with the new session's id (pass it to reasoning_add_step and reasoning_complete_session), plus:
|
|
230
230
|
- related_memories: up to a few saved memories relevant to the title, auto-recalled by the server — ranked by text relevance, softly preferring the current workspace; weak one-word matches are filtered out, so a short or empty list is normal. Review them before starting work; if one helps, report it later via used_memory_ids on reasoning_complete_session. Memories persisted from a past reasoning session carry a 'source' field ({session_id, session_title, created_at}); pass source.session_id to reasoning_get_trace to replay how that conclusion was reached.
|
|
231
|
-
- open_sessions / open_sessions_warning: other in_progress sessions you may
|
|
231
|
+
- open_sessions / open_sessions_warning: other in_progress sessions. Close the ones you opened and finished; leave sessions you don't recognize alone (they may belong to another agent or run).
|
|
232
232
|
- auto_abandoned_sessions: count of stale in_progress sessions the server just cleaned up, if any.
|
|
233
233
|
|
|
234
234
|
Examples:
|
|
@@ -286,7 +286,7 @@ Examples:
|
|
|
286
286
|
related_memories: relatedMemories,
|
|
287
287
|
...(openSessions.length > 0
|
|
288
288
|
? {
|
|
289
|
-
open_sessions_warning: `You have ${openSessions.length} other in_progress session(s). Close
|
|
289
|
+
open_sessions_warning: `You have ${openSessions.length} other in_progress session(s). Close the ones you opened and finished with reasoning_complete_session; leave sessions you don't recognize alone.`,
|
|
290
290
|
open_sessions: openSessions,
|
|
291
291
|
}
|
|
292
292
|
: {}),
|