Skip to content

Commit 642a911

Browse files
authored
fix(memory): write the knowledge graph atomically (modelcontextprotocol#4642)
* fix(memory): write the knowledge graph atomically `saveGraph()` wrote the graph straight to the memory file: await fs.writeFile(this.memoryFilePath, lines.join("\n")); `fs.writeFile` opens the target with `'w'`, which truncates it before any new bytes are written. If the process is interrupted between truncation and completion — SIGKILL, container or host stop, OOM kill, power loss — the memory file is left empty or half-written. That file is the only persistence layer for the knowledge graph, so the window is small but the loss is total and unrecoverable. The fix writes to a temporary file in the same directory and renames it over the target. `rename(2)` is atomic on POSIX filesystems: a reader sees either the complete old file or the complete new one, never an intermediate state. Keeping the temp file in the same directory ensures the rename stays on one filesystem, since cross-device renames fail with EXDEV. On failure the temp file is removed so no strays accumulate. Tests added in `__tests__/atomic-save.test.ts`: - the live memory file is never opened for truncating writes - a committed graph survives a write that fails midway - no temporary files remain after a successful write - the temporary file is cleaned up when the rename fails - graph contents still round-trip correctly across reloads The first and fourth fail against the previous implementation. Full suite: 55 passed (50 existing, 5 new). `tsc --noEmit` clean. Fixes modelcontextprotocol#4614 * fix(memory): use randomBytes for temp filename to avoid concurrent collision --------- Co-authored-by: teddiesloco <[email protected]>
1 parent 18ce197 commit 642a911

2 files changed

Lines changed: 157 additions & 1 deletion

File tree

Lines changed: 133 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,133 @@
1+
import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
2+
import { promises as fs } from 'fs';
3+
import path from 'path';
4+
import os from 'os';
5+
import { KnowledgeGraphManager, Entity } from '../index.js';
6+
7+
/**
8+
* Regression tests for durable persistence of the knowledge graph.
9+
*
10+
* saveGraph() previously called fs.writeFile() directly on the memory file.
11+
* fs.writeFile opens the target with 'w', which truncates it before any new
12+
* bytes are written. If the process dies between truncation and completion
13+
* (SIGKILL, container stop, OOM kill, power loss) the memory file — the sole
14+
* persistence layer for the graph — is left empty or half-written, and the
15+
* accumulated memory is unrecoverable.
16+
*
17+
* The fix writes to a temporary file in the same directory and then renames
18+
* it over the target. rename(2) is atomic on POSIX filesystems: a reader
19+
* either sees the complete old file or the complete new one, never a
20+
* truncated intermediate state.
21+
*/
22+
describe('KnowledgeGraphManager persistence durability', () => {
23+
let testDir: string;
24+
let testFilePath: string;
25+
26+
beforeEach(async () => {
27+
testDir = await fs.mkdtemp(path.join(os.tmpdir(), 'mcp-memory-atomic-'));
28+
testFilePath = path.join(testDir, 'memory.jsonl');
29+
});
30+
31+
afterEach(async () => {
32+
vi.restoreAllMocks();
33+
await fs.rm(testDir, { recursive: true, force: true });
34+
});
35+
36+
it('never truncates the live memory file in place', async () => {
37+
const manager = new KnowledgeGraphManager(testFilePath);
38+
await manager.createEntities([
39+
{ name: 'Alice', entityType: 'person', observations: ['works at Acme Corp'] },
40+
]);
41+
42+
// Any write that targets the live file directly is destructive: it
43+
// truncates committed data before the replacement is durable.
44+
const writeFileSpy = vi.spyOn(fs, 'writeFile');
45+
const openSpy = vi.spyOn(fs, 'open');
46+
47+
await manager.createEntities([
48+
{ name: 'Bob', entityType: 'person', observations: ['likes programming'] },
49+
]);
50+
51+
const destructiveTargets = [
52+
...writeFileSpy.mock.calls.map(call => call[0]),
53+
...openSpy.mock.calls.map(call => call[0]),
54+
].filter(target => target === testFilePath);
55+
56+
expect(destructiveTargets).toEqual([]);
57+
});
58+
59+
it('leaves the committed graph intact when the write fails midway', async () => {
60+
const manager = new KnowledgeGraphManager(testFilePath);
61+
await manager.createEntities([
62+
{ name: 'Alice', entityType: 'person', observations: ['works at Acme Corp'] },
63+
]);
64+
65+
const before = await fs.readFile(testFilePath, 'utf-8');
66+
expect(before).toContain('Alice');
67+
68+
// Simulate the process being interrupted while persisting the next write.
69+
vi.spyOn(fs, 'writeFile').mockImplementationOnce(async () => {
70+
throw new Error('ENOSPC: simulated interruption');
71+
});
72+
73+
await expect(
74+
manager.createEntities([
75+
{ name: 'Bob', entityType: 'person', observations: ['likes programming'] },
76+
])
77+
).rejects.toThrow();
78+
79+
vi.restoreAllMocks();
80+
81+
// The previously committed graph must survive untouched.
82+
expect(await fs.readFile(testFilePath, 'utf-8')).toBe(before);
83+
84+
const graph = await new KnowledgeGraphManager(testFilePath).readGraph();
85+
expect(graph.entities.map(e => e.name)).toEqual(['Alice']);
86+
});
87+
88+
it('does not leave temporary files behind after a successful write', async () => {
89+
const manager = new KnowledgeGraphManager(testFilePath);
90+
await manager.createEntities([
91+
{ name: 'Alice', entityType: 'person', observations: ['works at Acme Corp'] },
92+
]);
93+
94+
expect(await fs.readdir(testDir)).toEqual(['memory.jsonl']);
95+
});
96+
97+
it('cleans up the temporary file when the write fails', async () => {
98+
const manager = new KnowledgeGraphManager(testFilePath);
99+
await manager.createEntities([
100+
{ name: 'Alice', entityType: 'person', observations: ['works at Acme Corp'] },
101+
]);
102+
103+
vi.spyOn(fs, 'rename').mockImplementationOnce(async () => {
104+
throw new Error('EXDEV: simulated rename failure');
105+
});
106+
107+
await expect(
108+
manager.createEntities([
109+
{ name: 'Bob', entityType: 'person', observations: ['likes programming'] },
110+
])
111+
).rejects.toThrow();
112+
113+
vi.restoreAllMocks();
114+
expect(await fs.readdir(testDir)).toEqual(['memory.jsonl']);
115+
});
116+
117+
it('still persists graph contents correctly across reloads', async () => {
118+
const manager = new KnowledgeGraphManager(testFilePath);
119+
await manager.createEntities([
120+
{ name: 'Alice', entityType: 'person', observations: ['works at Acme Corp'] },
121+
{ name: 'Bob', entityType: 'person', observations: ['likes programming'] },
122+
]);
123+
await manager.createRelations([
124+
{ from: 'Alice', to: 'Bob', relationType: 'knows' },
125+
]);
126+
127+
const reloaded = await new KnowledgeGraphManager(testFilePath).readGraph();
128+
expect(reloaded.entities.map(e => e.name).sort()).toEqual(['Alice', 'Bob']);
129+
expect(reloaded.relations).toEqual([
130+
{ from: 'Alice', to: 'Bob', relationType: 'knows' },
131+
]);
132+
});
133+
});

‎src/memory/index.ts‎

Lines changed: 24 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,7 @@ import { SubscribeRequestSchema, UnsubscribeRequestSchema } from "@modelcontextp
66
import { z } from "zod";
77
import { promises as fs } from 'fs';
88
import path from 'path';
9+
import { randomBytes } from 'crypto';
910
import { fileURLToPath } from 'url';
1011

1112
// Define memory file path using environment variable with fallback
@@ -114,7 +115,29 @@ export class KnowledgeGraphManager {
114115
relationType: r.relationType
115116
})),
116117
];
117-
await fs.writeFile(this.memoryFilePath, lines.join("\n"));
118+
119+
// Write to a temporary file in the same directory, then rename it over
120+
// the target. fs.writeFile would truncate the memory file before writing,
121+
// so an interruption (SIGKILL, container stop, OOM, power loss) would
122+
// leave the only copy of the graph truncated and unrecoverable.
123+
// rename(2) is atomic on POSIX filesystems: readers see either the
124+
// complete old file or the complete new one, never a partial state.
125+
// The temp file is kept in the same directory so the rename stays on one
126+
// filesystem — renaming across mount points fails with EXDEV.
127+
const directory = path.dirname(this.memoryFilePath);
128+
const tempFilePath = path.join(
129+
directory,
130+
`${path.basename(this.memoryFilePath)}.${randomBytes(16).toString('hex')}.tmp`
131+
);
132+
133+
try {
134+
await fs.writeFile(tempFilePath, lines.join("\n"));
135+
await fs.rename(tempFilePath, this.memoryFilePath);
136+
} catch (error) {
137+
// Never leave a stray temp file behind on failure.
138+
await fs.unlink(tempFilePath).catch(() => {});
139+
throw error;
140+
}
118141
}
119142

120143
async createEntities(entities: Entity[]): Promise<Entity[]> {

0 commit comments

Comments
 (0)