@nhatnguyen9317/memory-mcp-server 1.3.0 → 1.3.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +14 -0
- package/README.md +32 -7
- package/dist/constants.js +1 -1
- package/dist/index.js +19 -18
- package/dist/install-agents.js +74 -0
- package/dist/server.js +20 -0
- package/package.json +11 -1
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,19 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## 1.3.1 (2026-07-14)
|
|
4
|
+
|
|
5
|
+
Theme: contributor documentation catches up with the code, plus a one-command way to teach an agent to use this MCP.
|
|
6
|
+
|
|
7
|
+
### Added
|
|
8
|
+
|
|
9
|
+
- **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.
|
|
10
|
+
- **`pre-merge-review` skill** (`.claude/skills/pre-merge-review/`): a structured build/test + docs/version-sync check to run before merging a branch.
|
|
11
|
+
- **`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.
|
|
12
|
+
|
|
13
|
+
### Changed
|
|
14
|
+
|
|
15
|
+
- 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.
|
|
16
|
+
|
|
3
17
|
## 1.3.0 (2026-07-11)
|
|
4
18
|
|
|
5
19
|
Theme: recall that stays right as the store grows — relevance ranking, provenance, and an always-on learning signal.
|
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
|
-
|
|
182
|
+
<!-- MEMORY_MCP_SERVER_START -->
|
|
183
|
+
## Memory MCP Server
|
|
170
184
|
|
|
171
|
-
|
|
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
|
-
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
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.
|
|
5
|
+
export const MCP_VERSION = "1.3.1";
|
|
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
|
|
25
|
-
|
|
26
|
-
|
|
15
|
+
const subcommand = process.argv[2];
|
|
16
|
+
if (subcommand === "install-agents") {
|
|
17
|
+
const { installAgents } = await import("./install-agents.js");
|
|
18
|
+
await installAgents();
|
|
19
|
+
}
|
|
20
|
+
else {
|
|
21
|
+
const { runServer } = await import("./server.js");
|
|
22
|
+
await runServer();
|
|
23
|
+
}
|
|
27
24
|
}
|
|
28
25
|
main().catch((error) => {
|
|
29
|
-
|
|
26
|
+
const label = process.argv[2] === "install-agents"
|
|
27
|
+
? "Fatal error running install-agents"
|
|
28
|
+
: "Fatal error starting memory-mcp-server";
|
|
29
|
+
console.error(`${label}:`, error);
|
|
30
30
|
process.exit(1);
|
|
31
31
|
});
|
|
32
|
+
export {};
|
|
32
33
|
//# sourceMappingURL=index.js.map
|
|
@@ -0,0 +1,74 @@
|
|
|
1
|
+
import { copyFileSync, existsSync, mkdirSync, readFileSync, writeFileSync, } from "node:fs";
|
|
2
|
+
import { homedir } from "node:os";
|
|
3
|
+
import { dirname, join } from "node:path";
|
|
4
|
+
import { fileURLToPath } from "node:url";
|
|
5
|
+
const START_MARKER = "<!-- MEMORY_MCP_SERVER_START -->";
|
|
6
|
+
const END_MARKER = "<!-- MEMORY_MCP_SERVER_END -->";
|
|
7
|
+
function targets() {
|
|
8
|
+
return [
|
|
9
|
+
{ name: "Claude Code", path: join(homedir(), ".claude", "CLAUDE.md") },
|
|
10
|
+
{ name: "Codex CLI", path: join(homedir(), ".codex", "AGENTS.md") },
|
|
11
|
+
];
|
|
12
|
+
}
|
|
13
|
+
/** Extracts the pasteable snippet (markers inclusive) from README.md content. */
|
|
14
|
+
export function extractSnippet(readmeContent) {
|
|
15
|
+
const start = readmeContent.indexOf(START_MARKER);
|
|
16
|
+
const end = readmeContent.indexOf(END_MARKER);
|
|
17
|
+
if (start === -1 || end === -1) {
|
|
18
|
+
throw new Error(`Could not find ${START_MARKER} / ${END_MARKER} markers in README.md`);
|
|
19
|
+
}
|
|
20
|
+
return readmeContent.slice(start, end + END_MARKER.length).trim();
|
|
21
|
+
}
|
|
22
|
+
/**
|
|
23
|
+
* Pure decision of the next file content, given the current content
|
|
24
|
+
* (null when the file does not exist yet) and the snippet to install.
|
|
25
|
+
* No filesystem access, so this is directly unit-testable.
|
|
26
|
+
*/
|
|
27
|
+
export function computeInstall(existingContent, snippet) {
|
|
28
|
+
if (existingContent === null) {
|
|
29
|
+
return { content: `${snippet}\n`, action: "created" };
|
|
30
|
+
}
|
|
31
|
+
const start = existingContent.indexOf(START_MARKER);
|
|
32
|
+
const end = existingContent.indexOf(END_MARKER);
|
|
33
|
+
if (start !== -1 && end !== -1) {
|
|
34
|
+
return {
|
|
35
|
+
content: existingContent.slice(0, start) +
|
|
36
|
+
snippet +
|
|
37
|
+
existingContent.slice(end + END_MARKER.length),
|
|
38
|
+
action: "updated",
|
|
39
|
+
};
|
|
40
|
+
}
|
|
41
|
+
const separator = existingContent.trim().length ? "\n\n" : "";
|
|
42
|
+
return {
|
|
43
|
+
content: `${existingContent}${separator}${snippet}\n`,
|
|
44
|
+
action: "appended",
|
|
45
|
+
};
|
|
46
|
+
}
|
|
47
|
+
/**
|
|
48
|
+
* Installs the README's Memory MCP Server snippet into the global config
|
|
49
|
+
* files of commonly-used agents (Claude Code, Codex CLI). Idempotent, and
|
|
50
|
+
* never touches project-scoped files.
|
|
51
|
+
*
|
|
52
|
+
* `overrides` exists so tests can point at a temp dir instead of the real
|
|
53
|
+
* home directory; production callers pass nothing.
|
|
54
|
+
*/
|
|
55
|
+
export async function installAgents(overrides = {}) {
|
|
56
|
+
const packageRoot = join(dirname(fileURLToPath(import.meta.url)), "..");
|
|
57
|
+
const readmePath = overrides.readmePath ?? join(packageRoot, "README.md");
|
|
58
|
+
const readmeContent = readFileSync(readmePath, "utf8");
|
|
59
|
+
const snippet = extractSnippet(readmeContent);
|
|
60
|
+
for (const target of overrides.targets ?? targets()) {
|
|
61
|
+
const exists = existsSync(target.path);
|
|
62
|
+
if (exists) {
|
|
63
|
+
copyFileSync(target.path, `${target.path}.bak`);
|
|
64
|
+
}
|
|
65
|
+
else {
|
|
66
|
+
mkdirSync(dirname(target.path), { recursive: true });
|
|
67
|
+
}
|
|
68
|
+
const existingContent = exists ? readFileSync(target.path, "utf8") : null;
|
|
69
|
+
const { content, action } = computeInstall(existingContent, snippet);
|
|
70
|
+
writeFileSync(target.path, content);
|
|
71
|
+
console.log(`[${action}] ${target.name} -> ${target.path}`);
|
|
72
|
+
}
|
|
73
|
+
}
|
|
74
|
+
//# sourceMappingURL=install-agents.js.map
|
package/dist/server.js
ADDED
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
|
|
2
|
+
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
|
|
3
|
+
import { DB_PATH, MCP_VERSION } from "./constants.js";
|
|
4
|
+
import "./db.js"; // ensures schema is created before tools run
|
|
5
|
+
import { registerMemoryTools } from "./tools/memory.js";
|
|
6
|
+
import { registerReasoningTools } from "./tools/reasoning.js";
|
|
7
|
+
import { registerUsageGuideTool } from "./tools/usage-guide.js";
|
|
8
|
+
export async function runServer() {
|
|
9
|
+
const server = new McpServer({
|
|
10
|
+
name: "memory-mcp-server",
|
|
11
|
+
version: MCP_VERSION,
|
|
12
|
+
});
|
|
13
|
+
registerMemoryTools(server);
|
|
14
|
+
registerReasoningTools(server);
|
|
15
|
+
registerUsageGuideTool(server);
|
|
16
|
+
const transport = new StdioServerTransport();
|
|
17
|
+
await server.connect(transport);
|
|
18
|
+
console.error(`memory-mcp-server running via stdio (db: ${DB_PATH})`);
|
|
19
|
+
}
|
|
20
|
+
//# sourceMappingURL=server.js.map
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@nhatnguyen9317/memory-mcp-server",
|
|
3
|
-
"version": "1.3.
|
|
3
|
+
"version": "1.3.1",
|
|
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",
|