@nhatnguyen9317/memory-mcp-server 1.3.0 → 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,38 @@
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
+
22
+ ## 1.3.1 (2026-07-14)
23
+
24
+ Theme: contributor documentation catches up with the code, plus a one-command way to teach an agent to use this MCP.
25
+
26
+ ### Added
27
+
28
+ - **Contributor architecture docs**: `docs/architecture.md` (layering, module map, data flow, storage model) and `docs/roadmap.md` (shipped/planned release index) — previously only user-facing docs (`README.md`, `GUIDELINES.md`) existed for this repo. `docs/architecture.md`'s `Version:` line is now locked to `package.json`'s version by a new test, `src/__tests__/architecture-doc-version.test.ts`. `AGENTS.md`/`CLAUDE.md` gained Docs Conventions, Release Process, and Version-Sync Conventions sections formalizing where new docs go and what must stay in sync on every release.
29
+ - **`pre-merge-review` skill** (`.claude/skills/pre-merge-review/`): a structured build/test + docs/version-sync check to run before merging a branch.
30
+ - **`install-agents` CLI subcommand**: after installing the package, `npx @nhatnguyen9317/memory-mcp-server install-agents` writes the README's "Memory MCP Server" agent-guidance snippet into a user's global `~/.claude/CLAUDE.md` and `~/.codex/AGENTS.md`, idempotently (safe to re-run, backs up the existing file to `<path>.bak` first). For users who haven't installed the package yet, `scripts/install-agent-snippet.sh` does the same thing via `curl -fsSL <url> | bash`, no local Node install required first.
31
+
32
+ ### Changed
33
+
34
+ - Design specs and implementation plans moved into a single `docs/design/` and `docs/plans/` hierarchy (previously split across `docs/plan-improvement-performance/` and `docs/superpowers/` with inconsistent naming); one previously-untracked spec is now committed. No content changes, links preserved.
35
+
3
36
  ## 1.3.0 (2026-07-11)
4
37
 
5
38
  Theme: recall that stays right as the store grows — relevance ranking, provenance, and an always-on learning signal.
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/README.md CHANGED
@@ -163,22 +163,47 @@ The runtime agent never reads this README — it only sees tool names, schemas,
163
163
  and whatever it can call. The reliable pattern:
164
164
 
165
165
  1. Install the MCP (above).
166
- 2. Paste a short snippet into your own repo's `AGENTS.md` / client prompt:
166
+ 2. Paste a short snippet into your own repo's `AGENTS.md` / client prompt —
167
+ or install it into your **global** Claude Code / Codex CLI config
168
+ automatically:
169
+
170
+ ```bash
171
+ # after installing the package (above)
172
+ npx @nhatnguyen9317/memory-mcp-server install-agents
173
+
174
+ # or, without installing anything first
175
+ curl -fsSL https://raw.githubusercontent.com/ngquocnhat9317/memory-mcp-server/master/scripts/install-agent-snippet.sh | bash
176
+ ```
177
+
178
+ Both are idempotent (safe to re-run) and back up any file they touch to
179
+ `<path>.bak` first.
167
180
 
168
181
  ```md
169
- ## Memory MCP
182
+ <!-- MEMORY_MCP_SERVER_START -->
183
+ ## Memory MCP Server
170
184
 
171
- When the `memory` MCP server is available:
185
+ **Hard gate — before anything else, every session, no exceptions:** if
186
+ `memory_*` / `reasoning_*` tools are listed (even deferred/lazy-loaded — load
187
+ them first, don't skip because schemas aren't visible yet), call
188
+ `get_usage_guide` and follow it. Do this unconditionally, before judging
189
+ whether the task looks like it needs memory.
172
190
 
173
- - On first use, call `get_usage_guide` and follow it.
174
- - Non-trivial task? `reasoning_start_session` first — review the
175
- `related_memories` it returns before working; if one carries a `source`,
176
- you can replay its origin with `reasoning_get_trace`.
191
+ | Thought | Reality |
192
+ | --- | --- |
193
+ | "This task looks simple" | Check first, decide after — the guide says what counts as trivial |
194
+ | "Tools aren't loaded yet" | Load them, don't skip the gate |
195
+ | "I'll search directly instead" | `get_usage_guide` first — it defines when search vs. a reasoning session applies |
196
+
197
+ - Non-trivial task (multi-step, debugging, planning, trade-offs)?
198
+ `reasoning_start_session` first — review the `related_memories` it
199
+ returns before working; if one carries a `source`, you can replay its
200
+ origin with `reasoning_get_trace`.
177
201
  - Log meaningful steps with `reasoning_add_step` (batch mode `steps: [...]`
178
202
  is fine for recording finished work).
179
203
  - Always close with `reasoning_complete_session`; report helpful memories via
180
204
  `used_memory_ids`; pass `save_as_memory=true` for durable conclusions.
181
205
  - Never store secrets, tokens, or raw sensitive data.
206
+ <!-- MEMORY_MCP_SERVER_END -->
182
207
  ```
183
208
 
184
209
  ## Tool Surface
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.0";
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/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 transport = new StdioServerTransport();
25
- await server.connect(transport);
26
- console.error(`memory-mcp-server running via stdio (db: ${DB_PATH})`);
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
- console.error("Fatal error starting memory-mcp-server:", error);
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
@@ -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 ADDED
@@ -0,0 +1,30 @@
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 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(" ");
16
+ export async function runServer() {
17
+ const server = new McpServer({
18
+ name: "memory-mcp-server",
19
+ version: MCP_VERSION,
20
+ }, {
21
+ instructions: SERVER_INSTRUCTIONS,
22
+ });
23
+ registerMemoryTools(server);
24
+ registerReasoningTools(server);
25
+ registerUsageGuideTool(server);
26
+ const transport = new StdioServerTransport();
27
+ await server.connect(transport);
28
+ console.error(`memory-mcp-server running via stdio (db: ${DB_PATH})`);
29
+ }
30
+ //# sourceMappingURL=server.js.map
@@ -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.0",
3
+ "version": "1.3.2",
4
4
  "keywords": [
5
5
  "mcp",
6
6
  "model-context-protocol",
@@ -14,10 +14,20 @@
14
14
  "sqlite"
15
15
  ],
16
16
  "description": "MCP server for persisting agent long-term memory and step-by-step reasoning traces in SQLite",
17
+ "homepage": "https://github.com/ngquocnhat9317/memory-mcp-server/blob/master/README.md",
18
+ "repository": {
19
+ "type": "git",
20
+ "url": "git+https://github.com/ngquocnhat9317/memory-mcp-server.git"
21
+ },
22
+ "bugs": {
23
+ "url": "https://github.com/ngquocnhat9317/memory-mcp-server/issues"
24
+ },
17
25
  "type": "module",
18
26
  "main": "dist/index.js",
19
27
  "files": [
20
28
  "dist/index.js",
29
+ "dist/server.js",
30
+ "dist/install-agents.js",
21
31
  "dist/constants.js",
22
32
  "dist/db.js",
23
33
  "dist/migrations/*.js",