Skip to content

Commit 6393874

Browse files
fix(memory): add a cross-process file lock so separate server processes do not overwrite each other
modelcontextprotocol#4555 serialises mutations within one process. The server is stdio-only, so each client is its own process with its own queue: two editor windows or two git worktrees pointed at one MEMORY_FILE_PATH still overwrite each other's load->mutate->save. Measured on d73f99e with 20 writes split across two processes: exactly 10 survive, every time - each process serialises its own half correctly and the last one to write the file wins. Wrap each mutation in a sidecar lock (MEMORY_FILE_PATH.lock) created with O_EXCL, which is atomic on POSIX and Windows and needs no dependency. A lock older than 30s is treated as left by a crashed process and reclaimed. The in-process queue stays, so one process never contends with itself. Refs modelcontextprotocol#1819, modelcontextprotocol#3286
1 parent d73f99e commit 6393874

2 files changed

Lines changed: 107 additions & 1 deletion

File tree

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
import { describe, it, expect, beforeEach, afterEach } from 'vitest';
2+
import { promises as fs } from 'fs';
3+
import path from 'path';
4+
import os from 'os';
5+
import { KnowledgeGraphManager } from '../index.js';
6+
7+
/**
8+
* Regression tests for cross-process exclusion (#1819, #3286).
9+
*
10+
* The in-process mutation queue (#4555) serialises one instance's mutations,
11+
* but the server is stdio-only, so every client is its own process with its
12+
* own queue. Two instances on one file are a faithful stand-in: nothing but
13+
* the sidecar lock file separates them, exactly as with two processes.
14+
*/
15+
describe('KnowledgeGraphManager cross-process exclusion', () => {
16+
let testDir: string;
17+
let testFilePath: string;
18+
19+
beforeEach(async () => {
20+
testDir = await fs.mkdtemp(path.join(os.tmpdir(), 'mcp-memory-xproc-'));
21+
testFilePath = path.join(testDir, 'memory.jsonl');
22+
});
23+
24+
afterEach(async () => {
25+
await fs.rm(testDir, { recursive: true, force: true });
26+
});
27+
28+
const entity = (name: string) => ({ name, entityType: 'thing', observations: [] as string[] });
29+
30+
it('keeps every entity when two instances write the same file concurrently', async () => {
31+
const a = new KnowledgeGraphManager(testFilePath);
32+
const b = new KnowledgeGraphManager(testFilePath);
33+
await Promise.all(
34+
Array.from({ length: 20 }, (_, i) => (i % 2 ? b : a).createEntities([entity(`e${i}`)])),
35+
);
36+
const names = (await a.readGraph()).entities.map(e => e.name).sort();
37+
expect(names).toEqual(Array.from({ length: 20 }, (_, i) => `e${i}`).sort());
38+
});
39+
40+
it('removes its lock file after each mutation', async () => {
41+
const manager = new KnowledgeGraphManager(testFilePath);
42+
await manager.createEntities([entity('x')]);
43+
await expect(fs.stat(`${testFilePath}.lock`)).rejects.toMatchObject({ code: 'ENOENT' });
44+
});
45+
46+
it('reclaims a lock left behind by a crashed process', async () => {
47+
await fs.mkdir(testDir, { recursive: true });
48+
await fs.writeFile(`${testFilePath}.lock`, '');
49+
const old = new Date(Date.now() - 60_000);
50+
await fs.utimes(`${testFilePath}.lock`, old, old);
51+
const manager = new KnowledgeGraphManager(testFilePath);
52+
await manager.createEntities([entity('x')]);
53+
expect((await manager.readGraph()).entities).toHaveLength(1);
54+
});
55+
});

‎src/memory/index.ts‎

Lines changed: 52 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -95,7 +95,8 @@ export class KnowledgeGraphManager {
9595
private mutationQueue: Promise<unknown> = Promise.resolve();
9696

9797
private async withLock<T>(operation: () => Promise<T>): Promise<T> {
98-
const result = this.mutationQueue.then(operation, operation);
98+
const guarded = () => this.withFileLock(operation);
99+
const result = this.mutationQueue.then(guarded, guarded);
99100
// Always resolve the queue itself, even if this operation failed, so a
100101
// single failed mutation doesn't permanently wedge every call after it.
101102
// The failure still propagates normally to whoever awaited `result`.
@@ -106,6 +107,56 @@ export class KnowledgeGraphManager {
106107
return result;
107108
}
108109

110+
// Cross-process exclusion. The queue above serialises this instance's
111+
// mutations, but the server is stdio-only, so every client is its own
112+
// process: two editor windows or two git worktrees sharing MEMORY_FILE_PATH
113+
// each run their own queue and still overwrite each other's load→mutate→save
114+
// (#1819, #3286). Measured on this commit: 20 writes split across two
115+
// processes keep exactly 10 — each process serialises its own half and the
116+
// last one to write the file wins. A sidecar lock file created with O_EXCL is
117+
// atomic on POSIX and Windows and needs no dependency. A lock older than
118+
// LOCK_STALE_MS is treated as left behind by a crashed process.
119+
private static readonly LOCK_STALE_MS = 30_000;
120+
private static readonly LOCK_RETRY_MS = 15;
121+
private static readonly LOCK_TIMEOUT_MS = 10_000;
122+
123+
private get lockFilePath(): string {
124+
return `${this.memoryFilePath}.lock`;
125+
}
126+
127+
private async withFileLock<T>(operation: () => Promise<T>): Promise<T> {
128+
await fs.mkdir(path.dirname(this.memoryFilePath), { recursive: true }).catch(() => {});
129+
const deadline = Date.now() + KnowledgeGraphManager.LOCK_TIMEOUT_MS;
130+
for (;;) {
131+
let handle: fs.FileHandle;
132+
try {
133+
handle = await fs.open(this.lockFilePath, 'wx');
134+
} catch (error) {
135+
if ((error as NodeJS.ErrnoException).code !== 'EEXIST') throw error;
136+
try {
137+
const stat = await fs.stat(this.lockFilePath);
138+
if (Date.now() - stat.mtimeMs > KnowledgeGraphManager.LOCK_STALE_MS) {
139+
await fs.unlink(this.lockFilePath).catch(() => {});
140+
continue;
141+
}
142+
} catch {
143+
continue; // the holder released between open and stat; retry now
144+
}
145+
if (Date.now() > deadline) {
146+
throw new Error(`Timed out waiting for lock ${this.lockFilePath}`);
147+
}
148+
await new Promise(resolve => setTimeout(resolve, KnowledgeGraphManager.LOCK_RETRY_MS));
149+
continue;
150+
}
151+
try {
152+
return await operation();
153+
} finally {
154+
await handle.close().catch(() => {});
155+
await fs.unlink(this.lockFilePath).catch(() => {});
156+
}
157+
}
158+
}
159+
109160
private async loadGraph(): Promise<KnowledgeGraph> {
110161
try {
111162
const data = await fs.readFile(this.memoryFilePath, "utf-8");

0 commit comments

Comments
 (0)