Skip to content

Commit 3a412f5

Browse files
cliffhallclaude
andcommitted
feat(memory): warn when the memory file is inside node_modules
Under npx or an npm install the default memory.jsonl sits inside a node_modules tree, where a reinstall, an update or a cleared npx cache can delete it. The server now prints a warning on stderr at startup when the memory file it resolves is inside node_modules, and the README recommends setting MEMORY_FILE_PATH to an absolute path the user owns, says why, and states the atomic-save and lock guarantees that already exist. The default path is unchanged (#4117). Co-Authored-By: Claude Opus 5.5 <[email protected]> Signed-off-by: cliffhall <[email protected]>
1 parent 446be48 commit 3a412f5

5 files changed

Lines changed: 124 additions & 3 deletions

File tree

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
"@modelcontextprotocol/server-memory": patch
3+
---
4+
5+
Warn on stderr at startup when the memory file is inside a `node_modules` directory, where reinstalling or updating the server, or clearing the npx cache, can delete it, and recommend in the README setting `MEMORY_FILE_PATH` to an absolute path you own. The default path is unchanged.

‎src/memory/README.md‎

Lines changed: 11 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -240,10 +240,20 @@ On Windows, use:
240240
}
241241
```
242242

243-
- `MEMORY_FILE_PATH`: Path to the memory storage JSONL file (default: `memory.jsonl` in the server directory)
243+
- `MEMORY_FILE_PATH`: Path to the memory storage JSONL file (default: `memory.jsonl` in the server directory). A leading `~` expands to your home directory; a relative path resolves against the server directory. Set it to an absolute path you own; see [Choosing where the graph is stored](#choosing-where-the-graph-is-stored).
244244

245245
When `MEMORY_FILE_PATH` is not set and the server directory still holds a legacy `memory.json` but no `memory.jsonl`, the server renames `memory.json` to `memory.jsonl` at startup. If that rename fails, the server exits with an error naming both paths and the cause, rather than starting on an empty graph; fix the cause (a permission problem, say) and restart, or set `MEMORY_FILE_PATH` to choose a file explicitly.
246246

247+
#### Choosing where the graph is stored
248+
249+
**Set `MEMORY_FILE_PATH` to an absolute path you own**, such as `~/memory.jsonl`, as in the configuration above. The default `memory.jsonl` sits in the server's own directory, next to its code. Under `npx` or an npm install, that directory is inside a `node_modules` tree, which npm manages as its own: reinstalling or updating the server, or clearing the npx cache, can delete the file and the knowledge graph in it. A relative `MEMORY_FILE_PATH` resolves against that same directory, so it has the same problem.
250+
251+
- When the memory file it resolves is inside a `node_modules` directory, the server prints a warning on stderr at startup naming the file; most clients show a server's stderr in its log. Move the file to the new path when you set the variable, or the server starts on an empty graph.
252+
- The directory must already exist: the server creates the memory file, not the directories above it.
253+
- The default stays where it is so that existing graphs keep loading. The [Docker](#docker) setup above keeps it in a named volume mounted over `/app/dist`, so the graph there survives restarts and draws no warning.
254+
255+
Saves are atomic. Every write tool writes the whole graph to a temporary file in the same directory and renames it over the memory file, so a server stopped or killed mid-save leaves the previous graph intact rather than a half-written file. The file's permission bits are kept across the rename. Writes from several processes are serialized by a lock, described next.
256+
247257
#### Sharing one memory file between clients
248258

249259
Each MCP client starts its own server process, so two clients using the same `MEMORY_FILE_PATH` (or both using the default) are two processes writing one file. Every write tool takes an exclusive lock file, `<memory file>.lock`, next to the memory file while it reads, changes and saves the graph, so writes from different processes take turns and none is lost. The lock file exists only while a write is in progress, so the directory holding the memory file must be writable (it already must be, for the atomic save).

‎src/memory/__tests__/entry-point.test.ts‎

Lines changed: 25 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
// Tests for the memory server's startup path (#4854): main() run in-process
2-
// over an in-memory transport, so its MEMORY_FILE_PATH handling is covered,
2+
// over an in-memory transport, so its MEMORY_FILE_PATH handling and its
3+
// warning for a graph file inside node_modules (#4117) are covered,
34
// and isMainModule(), the guard that keeps importing index.ts from starting a
45
// stdio server. The bin itself is exercised over real stdio by
56
// stdio-smoke.test.ts.
@@ -52,11 +53,34 @@ describe("main", () => {
5253
expect(errorSpy).toHaveBeenCalledWith(
5354
"Knowledge Graph MCP Server running on stdio",
5455
);
56+
// A file outside node_modules draws no location warning (#4117).
57+
expect(errorSpy).not.toHaveBeenCalledWith(
58+
expect.stringContaining("node_modules"),
59+
);
5560
} finally {
5661
await client.close();
5762
await server.close();
5863
}
5964
});
65+
66+
it("warns on stderr when the graph file is inside node_modules (#4117)", async () => {
67+
const installDir = path.join(dir, "node_modules", "server-memory", "dist");
68+
await fs.mkdir(installDir, { recursive: true });
69+
const graphPath = path.join(installDir, "memory.jsonl");
70+
process.env.MEMORY_FILE_PATH = graphPath;
71+
const errorSpy = vi.spyOn(console, "error").mockImplementation(() => {});
72+
73+
const server = await main(InMemoryTransport.createLinkedPair()[1]);
74+
try {
75+
expect(errorSpy).toHaveBeenCalledWith(
76+
expect.stringMatching(
77+
/^WARNING: the memory file .*memory\.jsonl is inside a node_modules directory/,
78+
),
79+
);
80+
} finally {
81+
await server.close();
82+
}
83+
});
6084
});
6185

6286
describe("isMainModule", () => {

‎src/memory/__tests__/file-path.test.ts‎

Lines changed: 53 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
// Tests for how the memory server picks its graph file: MEMORY_FILE_PATH
2-
// handling, the memory.json -> memory.jsonl migration, and "~" expansion.
2+
// handling, the memory.json -> memory.jsonl migration, "~" expansion, and the
3+
// startup warning for a graph file npm could delete (#4117).
34
//
45
// Every test runs ensureMemoryFilePath against its own temporary directory.
56
// Vitest runs test files in parallel, so files written beside the source are
@@ -14,6 +15,7 @@ import {
1415
ensureMemoryFilePath,
1516
defaultMemoryPath,
1617
expandHome,
18+
memoryFileLocationWarning,
1719
} from "../index.js";
1820

1921
describe("ensureMemoryFilePath", () => {
@@ -292,3 +294,53 @@ describe("expandHome", () => {
292294
);
293295
});
294296
});
297+
298+
describe("memoryFileLocationWarning", () => {
299+
it("warns about a file inside an npx or npm install's node_modules", () => {
300+
const installed = path.join(
301+
os.homedir(),
302+
".npm",
303+
"_npx",
304+
"abc123",
305+
"node_modules",
306+
"@modelcontextprotocol",
307+
"server-memory",
308+
"dist",
309+
"memory.jsonl",
310+
);
311+
const warning = memoryFileLocationWarning(installed);
312+
expect(warning).toContain(installed);
313+
expect(warning).toContain("node_modules");
314+
expect(warning).toContain("MEMORY_FILE_PATH");
315+
});
316+
317+
it("warns about a Windows path inside node_modules on any platform", () => {
318+
expect(
319+
memoryFileLocationWarning(
320+
"C:\\Users\\me\\AppData\\npm\\node_modules\\@modelcontextprotocol\\server-memory\\dist\\memory.jsonl",
321+
),
322+
).toContain("node_modules");
323+
});
324+
325+
it("does not warn about a file outside node_modules", () => {
326+
expect(
327+
memoryFileLocationWarning(path.join(os.homedir(), "memory.jsonl")),
328+
).toBeUndefined();
329+
});
330+
331+
it("does not warn about a directory whose name only contains node_modules", () => {
332+
expect(
333+
memoryFileLocationWarning(
334+
path.join(os.homedir(), "my_node_modules_notes", "memory.jsonl"),
335+
),
336+
).toBeUndefined();
337+
});
338+
339+
it("does not warn about the Docker image's /app/dist, which the setup mounts as a volume", () => {
340+
expect(
341+
memoryFileLocationWarning(
342+
path.join(path.sep, "app", "dist", "memory.jsonl"),
343+
),
344+
).toBeUndefined();
345+
});
346+
});

‎src/memory/index.ts‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -107,6 +107,32 @@ async function pathExists(filePath: string): Promise<boolean> {
107107
}
108108
}
109109

110+
// The startup warning for a memory file inside a node_modules tree, or
111+
// undefined for any other path. npx and npm install the server under
112+
// node_modules, so the default memory.jsonl beside dist/index.js lands there,
113+
// and npm treats that tree as its own: a reinstall, an update or a cleared npx
114+
// cache can delete the file and the graph in it (#4117). The default is not
115+
// moved, since that would strand every existing graph; the warning says how to
116+
// choose a durable path instead. Only node_modules is matched, not the server's
117+
// directory as such: the Docker setup mounts a volume over /app/dist, and a
118+
// source checkout's dist survives a rebuild, so there the default is durable.
119+
export function memoryFileLocationWarning(
120+
memoryFilePath: string,
121+
): string | undefined {
122+
// Both separators, so a Windows path is matched on any platform.
123+
const segments = path.resolve(memoryFilePath).split(/[\\/]/);
124+
if (!segments.includes("node_modules")) {
125+
return undefined;
126+
}
127+
return (
128+
`WARNING: the memory file ${memoryFilePath} is inside a node_modules directory, ` +
129+
"which npm manages: reinstalling or updating the server, or clearing the npx cache, " +
130+
"can delete it and the knowledge graph it holds. Set MEMORY_FILE_PATH to an absolute " +
131+
"path outside node_modules, in a directory that exists (for example ~/memory.jsonl), " +
132+
"and move this file there to keep the graph."
133+
);
134+
}
135+
110136
// We are storing our memory using entities, relations, and observations in a graph structure
111137
export interface Entity {
112138
name: string;
@@ -1241,6 +1267,10 @@ export function registerKnowledgeGraphSubscriptions(
12411267
// including one that stops the transport from starting, is reported on stderr.
12421268
export async function main(transport?: Transport): Promise<StdioServerHandle> {
12431269
const memoryFilePath = await ensureMemoryFilePath();
1270+
const locationWarning = memoryFileLocationWarning(memoryFilePath);
1271+
if (locationWarning) {
1272+
console.error(locationWarning);
1273+
}
12441274
const handle = serveStdio(({ era }) => createServer(memoryFilePath, era), {
12451275
transport,
12461276
// serveStdio reports a transport that fails, including one that cannot

0 commit comments

Comments
 (0)