@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 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-12.v5
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
- - `open_sessions_warning` / `open_sessions`: sessions you (or a previous
26
- run) forgot to close. Close finished ones with
27
- `reasoning_complete_session`; stale ones are auto-abandoned by the server.
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` (`decision`, `conflict`,
41
- `hypothesis`, `milestone`, `important`) when a future reviewer would want to
42
- jump straight to them.
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. Successful
51
- usage feedback is a learning signal for recall quality and is always
52
- recorded locally, regardless of the `MEMORY_TELEMETRY` setting (failed
53
- attempts, e.g. an unknown memory id, return a warning and are not recorded).
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 (optionally with `memory_mode='never'` + `not_saved_reason`) when it is
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 whether a recalled memory was
76
- used/ignored/stale — prefer `used_memory_ids` at completion for the common
77
- case; successful feedback is always persisted locally regardless of
78
- `MEMORY_TELEMETRY`
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 — with
94
- `MEMORY_TELEMETRY` off (the default) only usage-feedback events and session
95
- tables have data; full funnels and ratios need `MEMORY_TELEMETRY=on`
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.1";
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.
@@ -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. ['project-x','backend']."),
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);
@@ -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 chronologically or by importance.",
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 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.",
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,
@@ -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 have forgotten to close.
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 finished ones with reasoning_complete_session.`,
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
  : {}),
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@nhatnguyen9317/memory-mcp-server",
3
- "version": "1.3.1",
3
+ "version": "1.3.2",
4
4
  "keywords": [
5
5
  "mcp",
6
6
  "model-context-protocol",