Skip to content

Commit 91d3745

Browse files
cliffhallclaude
andcommitted
fix(memory): stop startup when the memory.json migration fails
Only a missing legacy memory.json now means there is nothing to migrate. A rename failure, or an existence check that fails with anything other than ENOENT, propagates as an error naming both paths and the cause, so main() exits instead of serving an empty memory.jsonl while the user's graph sits unread. Closes #5203 Co-Authored-By: Claude Opus 5.5 <[email protected]> Signed-off-by: cliffhall <[email protected]>
1 parent 846cc6c commit 91d3745

4 files changed

Lines changed: 118 additions & 19 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+
A failed `memory.json` to `memory.jsonl` migration now stops startup with an error naming both paths and the cause, instead of being silently ignored and starting the server on an empty graph.

‎src/memory/README.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -242,6 +242,8 @@ On Windows, use:
242242

243243
- `MEMORY_FILE_PATH`: Path to the memory storage JSONL file (default: `memory.jsonl` in the server directory)
244244

245+
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.
246+
245247
#### Sharing one memory file between clients
246248

247249
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__/file-path.test.ts‎

Lines changed: 71 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -183,6 +183,77 @@ describe("ensureMemoryFilePath", () => {
183183
const migratedContent = await fs.readFile(newMemoryPath, "utf-8");
184184
expect(migratedContent).toBe(testContent);
185185
});
186+
187+
// #5203: a failed rename used to be read as "no legacy file", so the
188+
// server started on an empty memory.jsonl and the graph vanished from view.
189+
it("throws, naming both paths and the cause, when the migration rename fails", async () => {
190+
const testContent = '{"type":"entity","name":"kept"}';
191+
await fs.writeFile(oldMemoryPath, testContent);
192+
193+
const consoleErrorSpy = vi
194+
.spyOn(console, "error")
195+
.mockImplementation(() => {});
196+
const cause = Object.assign(new Error("EACCES: permission denied"), {
197+
code: "EACCES",
198+
});
199+
const renameSpy = vi.spyOn(fs, "rename").mockRejectedValueOnce(cause);
200+
201+
try {
202+
const failure = await ensureMemoryFilePath(testDir).then(
203+
() => null,
204+
(error: unknown) => error,
205+
);
206+
207+
expect(failure).toBeInstanceOf(Error);
208+
const message = (failure as Error).message;
209+
expect(message).toContain(oldMemoryPath);
210+
expect(message).toContain(newMemoryPath);
211+
expect(message).toContain("EACCES: permission denied");
212+
expect((failure as Error).cause).toBe(cause);
213+
214+
// The legacy graph is untouched and no empty replacement was created.
215+
expect(await fs.readFile(oldMemoryPath, "utf-8")).toBe(testContent);
216+
await expect(fs.access(newMemoryPath)).rejects.toThrow();
217+
expect(consoleErrorSpy).not.toHaveBeenCalledWith(
218+
expect.stringContaining("COMPLETED"),
219+
);
220+
} finally {
221+
renameSpy.mockRestore();
222+
consoleErrorSpy.mockRestore();
223+
}
224+
});
225+
226+
it("reports a non-Error rename rejection by its string form", async () => {
227+
await fs.writeFile(oldMemoryPath, "{}");
228+
const consoleErrorSpy = vi
229+
.spyOn(console, "error")
230+
.mockImplementation(() => {});
231+
const renameSpy = vi
232+
.spyOn(fs, "rename")
233+
.mockRejectedValueOnce("rename refused");
234+
235+
try {
236+
await expect(ensureMemoryFilePath(testDir)).rejects.toThrow(
237+
/memory\.json to .*memory\.jsonl: rename refused/,
238+
);
239+
} finally {
240+
renameSpy.mockRestore();
241+
consoleErrorSpy.mockRestore();
242+
}
243+
});
244+
245+
it("propagates an existence-check failure other than ENOENT", async () => {
246+
const denied = Object.assign(new Error("EACCES: permission denied"), {
247+
code: "EACCES",
248+
});
249+
const accessSpy = vi.spyOn(fs, "access").mockRejectedValueOnce(denied);
250+
251+
try {
252+
await expect(ensureMemoryFilePath(testDir)).rejects.toBe(denied);
253+
} finally {
254+
accessSpy.mockRestore();
255+
}
256+
});
186257
});
187258

188259
describe("defaultMemoryPath", () => {

‎src/memory/index.ts‎

Lines changed: 40 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -62,27 +62,48 @@ export async function ensureMemoryFilePath(
6262
const oldMemoryPath = path.join(baseDir, "memory.json");
6363
const newMemoryPath = path.join(baseDir, "memory.jsonl");
6464

65+
// Only a missing legacy file means there is nothing to migrate. Any other
66+
// failure, from the existence checks or the rename itself, propagates and
67+
// stops startup: carrying on would serve an empty memory.jsonl while the
68+
// user's graph sat unread in memory.json (#5203).
69+
if (!(await pathExists(oldMemoryPath))) {
70+
return newMemoryPath;
71+
}
72+
if (await pathExists(newMemoryPath)) {
73+
// Both files exist, use new one (no migration needed)
74+
return newMemoryPath;
75+
}
76+
77+
// Old file exists, new file doesn't - migrate
78+
console.error(
79+
"DETECTED: Found legacy memory.json file, migrating to memory.jsonl for JSONL format compatibility",
80+
);
6581
try {
66-
// Check if old file exists and new file doesn't
67-
await fs.access(oldMemoryPath);
68-
try {
69-
await fs.access(newMemoryPath);
70-
// Both files exist, use new one (no migration needed)
71-
return newMemoryPath;
72-
} catch {
73-
// Old file exists, new file doesn't - migrate
74-
console.error(
75-
"DETECTED: Found legacy memory.json file, migrating to memory.jsonl for JSONL format compatibility",
76-
);
77-
await fs.rename(oldMemoryPath, newMemoryPath);
78-
console.error(
79-
"COMPLETED: Successfully migrated memory.json to memory.jsonl",
80-
);
81-
return newMemoryPath;
82+
await fs.rename(oldMemoryPath, newMemoryPath);
83+
} catch (error) {
84+
const reason = error instanceof Error ? error.message : String(error);
85+
throw new Error(
86+
`Failed to migrate legacy memory file ${oldMemoryPath} to ${newMemoryPath}: ${reason}. ` +
87+
"The server will not start on an empty graph; fix the cause and restart, " +
88+
"or set MEMORY_FILE_PATH to choose a file explicitly.",
89+
{ cause: error },
90+
);
91+
}
92+
console.error("COMPLETED: Successfully migrated memory.json to memory.jsonl");
93+
return newMemoryPath;
94+
}
95+
96+
// True when filePath exists, false when it does not (ENOENT). Any other error,
97+
// such as a permission failure, is rethrown rather than read as "missing".
98+
async function pathExists(filePath: string): Promise<boolean> {
99+
try {
100+
await fs.access(filePath);
101+
return true;
102+
} catch (error) {
103+
if ((error as NodeJS.ErrnoException).code === "ENOENT") {
104+
return false;
82105
}
83-
} catch {
84-
// Old file doesn't exist, use new path
85-
return newMemoryPath;
106+
throw error;
86107
}
87108
}
88109

0 commit comments

Comments
 (0)