Skip to content

Commit d73f99e

Browse files
fix(memory): serialize graph mutations to prevent concurrent write race (modelcontextprotocol#4555)
createEntities, createRelations, addObservations, deleteEntities, deleteObservations, and deleteRelations each independently did load -> mutate -> save with no synchronization. Concurrent tool calls (e.g. multiple mutations dispatched from one LLM turn) could race: both read the same starting state, both write back their own copy, and whichever write landed last silently discarded the other's changes. Interleaved writes could also corrupt the file outright. Adds an in-process async mutex (KnowledgeGraphManager.withLock) that serializes all six mutation methods through a single queue. Read-only methods (readGraph, searchNodes, openNodes) are unaffected. Verified: reverting the fix and re-running the new concurrency tests reproduces the bug exactly (lost entities, lost relations, malformed JSONL lines). With the fix, all 39 tests pass. Fixes modelcontextprotocol#1819 Co-authored-by: olaservo <[email protected]>
1 parent 1ec570c commit d73f99e

2 files changed

Lines changed: 180 additions & 73 deletions

File tree

‎src/memory/__tests__/knowledge-graph.test.ts‎

Lines changed: 75 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -696,4 +696,79 @@ describe('KnowledgeGraphManager', () => {
696696
expect(graph.entities.map(e => e.name)).toEqual(['Alice', 'Bob']);
697697
});
698698
});
699+
700+
describe('concurrent mutations', () => {
701+
// Regression test for #1819: concurrent tool calls each independently
702+
// load the graph, mutate their own copy, and write it back. Without
703+
// serialization, whichever write lands last silently discards the
704+
// other's changes. All mutations below are fired without awaiting each
705+
// other first, simulating multiple tool calls landing close together.
706+
707+
it('should not lose entities created concurrently', async () => {
708+
const batch1: Entity[] = Array.from({ length: 10 }, (_, i) => ({
709+
name: `batch1-entity-${i}`,
710+
entityType: 'test',
711+
observations: [],
712+
}));
713+
const batch2: Entity[] = Array.from({ length: 10 }, (_, i) => ({
714+
name: `batch2-entity-${i}`,
715+
entityType: 'test',
716+
observations: [],
717+
}));
718+
719+
// Fire both concurrently instead of awaiting sequentially.
720+
await Promise.all([
721+
manager.createEntities(batch1),
722+
manager.createEntities(batch2),
723+
]);
724+
725+
const graph = await manager.readGraph();
726+
expect(graph.entities).toHaveLength(20);
727+
expect(graph.entities.map(e => e.name).sort()).toEqual(
728+
[...batch1, ...batch2].map(e => e.name).sort()
729+
);
730+
});
731+
732+
it('should not lose relations created concurrently with entity creation', async () => {
733+
await manager.createEntities([
734+
{ name: 'Alice', entityType: 'person', observations: [] },
735+
{ name: 'Bob', entityType: 'person', observations: [] },
736+
{ name: 'Carol', entityType: 'person', observations: [] },
737+
]);
738+
739+
await Promise.all([
740+
manager.createRelations([{ from: 'Alice', to: 'Bob', relationType: 'knows' }]),
741+
manager.createRelations([{ from: 'Bob', to: 'Carol', relationType: 'knows' }]),
742+
manager.addObservations([
743+
{ entityName: 'Alice', contents: ['likes coffee'] },
744+
]),
745+
]);
746+
747+
const graph = await manager.readGraph();
748+
expect(graph.relations).toHaveLength(2);
749+
expect(graph.entities.find(e => e.name === 'Alice')?.observations).toContain('likes coffee');
750+
});
751+
752+
it('should keep the file valid JSONL after many concurrent mutations', async () => {
753+
const operations = Array.from({ length: 25 }, (_, i) =>
754+
manager.createEntities([
755+
{ name: `stress-entity-${i}`, entityType: 'test', observations: [] },
756+
])
757+
);
758+
759+
await Promise.all(operations);
760+
761+
const raw = await fs.readFile(testFilePath, 'utf-8');
762+
const lines = raw.split('\n').filter(line => line.trim() !== '');
763+
764+
// Every line must parse as valid JSON; a corrupted interleaved write
765+
// would produce a truncated or malformed line here.
766+
for (const line of lines) {
767+
expect(() => JSON.parse(line)).not.toThrow();
768+
}
769+
770+
const graph = await manager.readGraph();
771+
expect(graph.entities).toHaveLength(25);
772+
});
773+
});
699774
});

‎src/memory/index.ts‎

Lines changed: 105 additions & 73 deletions
Original file line numberDiff line numberDiff line change
@@ -86,6 +86,26 @@ export interface KnowledgeGraph {
8686
export class KnowledgeGraphManager {
8787
constructor(private memoryFilePath: string) {}
8888

89+
// Serializes all read-modify-write graph mutations behind a single queue.
90+
// Without this, concurrent tool calls (e.g. multiple mutations dispatched
91+
// from one LLM turn) each independently load the graph, mutate their own
92+
// copy, and write it back — so whichever write lands last silently
93+
// overwrites the other's changes, and interleaved writes to the same file
94+
// can corrupt it outright. See #1819.
95+
private mutationQueue: Promise<unknown> = Promise.resolve();
96+
97+
private async withLock<T>(operation: () => Promise<T>): Promise<T> {
98+
const result = this.mutationQueue.then(operation, operation);
99+
// Always resolve the queue itself, even if this operation failed, so a
100+
// single failed mutation doesn't permanently wedge every call after it.
101+
// The failure still propagates normally to whoever awaited `result`.
102+
this.mutationQueue = result.then(
103+
() => undefined,
104+
() => undefined,
105+
);
106+
return result;
107+
}
108+
89109
private async loadGraph(): Promise<KnowledgeGraph> {
90110
try {
91111
const data = await fs.readFile(this.memoryFilePath, "utf-8");
@@ -180,98 +200,110 @@ export class KnowledgeGraphManager {
180200
}
181201

182202
async createEntities(entities: Entity[]): Promise<Entity[]> {
183-
const graph = await this.loadGraph();
184-
const newEntities = entities.filter((e, index) =>
185-
!graph.entities.some(existingEntity => existingEntity.name === e.name) &&
186-
// Also skip duplicates appearing earlier in this same batch
187-
!entities.slice(0, index).some(earlier => earlier.name === e.name)
188-
);
189-
graph.entities.push(...newEntities);
190-
await this.saveGraph(graph);
191-
return newEntities;
203+
return this.withLock(async () => {
204+
const graph = await this.loadGraph();
205+
const newEntities = entities.filter((e, index) =>
206+
!graph.entities.some(existingEntity => existingEntity.name === e.name) &&
207+
// Also skip duplicates appearing earlier in this same batch
208+
!entities.slice(0, index).some(earlier => earlier.name === e.name)
209+
);
210+
graph.entities.push(...newEntities);
211+
await this.saveGraph(graph);
212+
return newEntities;
213+
});
192214
}
193215

194216
async createRelations(relations: Relation[]): Promise<Relation[]> {
195-
const graph = await this.loadGraph();
196-
const entityNames = new Set(graph.entities.map(e => e.name));
217+
return this.withLock(async () => {
218+
const graph = await this.loadGraph();
219+
const entityNames = new Set(graph.entities.map(e => e.name));
197220

198-
relations.forEach(r => {
199-
if (!entityNames.has(r.from)) {
200-
throw new Error(`Entity with name ${r.from} not found`);
201-
}
202-
if (!entityNames.has(r.to)) {
203-
throw new Error(`Entity with name ${r.to} not found`);
204-
}
221+
relations.forEach(r => {
222+
if (!entityNames.has(r.from)) {
223+
throw new Error(`Entity with name ${r.from} not found`);
224+
}
225+
if (!entityNames.has(r.to)) {
226+
throw new Error(`Entity with name ${r.to} not found`);
227+
}
228+
});
229+
230+
const isSameRelation = (a: Relation, b: Relation) =>
231+
a.from === b.from &&
232+
a.to === b.to &&
233+
a.relationType === b.relationType;
234+
const newRelations = relations.filter((r, index) =>
235+
!graph.relations.some(existingRelation => isSameRelation(existingRelation, r)) &&
236+
// Also skip duplicates appearing earlier in this same batch
237+
!relations.slice(0, index).some(earlier => isSameRelation(earlier, r))
238+
);
239+
graph.relations.push(...newRelations);
240+
await this.saveGraph(graph);
241+
return newRelations;
205242
});
206-
207-
const isSameRelation = (a: Relation, b: Relation) =>
208-
a.from === b.from &&
209-
a.to === b.to &&
210-
a.relationType === b.relationType;
211-
const newRelations = relations.filter((r, index) =>
212-
!graph.relations.some(existingRelation => isSameRelation(existingRelation, r)) &&
213-
// Also skip duplicates appearing earlier in this same batch
214-
!relations.slice(0, index).some(earlier => isSameRelation(earlier, r))
215-
);
216-
graph.relations.push(...newRelations);
217-
await this.saveGraph(graph);
218-
return newRelations;
219243
}
220244

221245
async addObservations(observations: { entityName: string; contents: string[] }[]): Promise<{ entityName: string; addedObservations: string[] }[]> {
222-
const graph = await this.loadGraph();
223-
const results = observations.map(o => {
224-
const entity = graph.entities.find(e => e.name === o.entityName);
225-
if (!entity) {
226-
throw new Error(`Entity with name ${o.entityName} not found`);
227-
}
228-
const newObservations = o.contents.filter(content => !entity.observations.includes(content));
229-
entity.observations.push(...newObservations);
230-
return { entityName: o.entityName, addedObservations: newObservations };
246+
return this.withLock(async () => {
247+
const graph = await this.loadGraph();
248+
const results = observations.map(o => {
249+
const entity = graph.entities.find(e => e.name === o.entityName);
250+
if (!entity) {
251+
throw new Error(`Entity with name ${o.entityName} not found`);
252+
}
253+
const newObservations = o.contents.filter(content => !entity.observations.includes(content));
254+
entity.observations.push(...newObservations);
255+
return { entityName: o.entityName, addedObservations: newObservations };
256+
});
257+
await this.saveGraph(graph);
258+
return results;
231259
});
232-
await this.saveGraph(graph);
233-
return results;
234260
}
235261

236262
async deleteEntities(entityNames: string[]): Promise<{ deleted: string[]; notFound: string[] }> {
237-
const graph = await this.loadGraph();
238-
const present = new Set(graph.entities.map(e => e.name));
239-
const deleted = entityNames.filter(name => present.has(name));
240-
const notFound = entityNames.filter(name => !present.has(name));
241-
graph.entities = graph.entities.filter(e => !entityNames.includes(e.name));
242-
graph.relations = graph.relations.filter(r => !entityNames.includes(r.from) && !entityNames.includes(r.to));
243-
await this.saveGraph(graph);
244-
return { deleted, notFound };
263+
return this.withLock(async () => {
264+
const graph = await this.loadGraph();
265+
const present = new Set(graph.entities.map(e => e.name));
266+
const deleted = entityNames.filter(name => present.has(name));
267+
const notFound = entityNames.filter(name => !present.has(name));
268+
graph.entities = graph.entities.filter(e => !entityNames.includes(e.name));
269+
graph.relations = graph.relations.filter(r => !entityNames.includes(r.from) && !entityNames.includes(r.to));
270+
await this.saveGraph(graph);
271+
return { deleted, notFound };
272+
});
245273
}
246274

247275
async deleteObservations(deletions: { entityName: string; observations: string[] }[]): Promise<{ deletedCount: number; missingEntities: string[] }> {
248-
const graph = await this.loadGraph();
249-
let deletedCount = 0;
250-
const missingEntities: string[] = [];
251-
deletions.forEach(d => {
252-
const entity = graph.entities.find(e => e.name === d.entityName);
253-
if (entity) {
254-
const before = entity.observations.length;
255-
entity.observations = entity.observations.filter(o => !d.observations.includes(o));
256-
deletedCount += before - entity.observations.length;
257-
} else {
258-
missingEntities.push(d.entityName);
259-
}
276+
return this.withLock(async () => {
277+
const graph = await this.loadGraph();
278+
let deletedCount = 0;
279+
const missingEntities: string[] = [];
280+
deletions.forEach(d => {
281+
const entity = graph.entities.find(e => e.name === d.entityName);
282+
if (entity) {
283+
const before = entity.observations.length;
284+
entity.observations = entity.observations.filter(o => !d.observations.includes(o));
285+
deletedCount += before - entity.observations.length;
286+
} else {
287+
missingEntities.push(d.entityName);
288+
}
289+
});
290+
await this.saveGraph(graph);
291+
return { deletedCount, missingEntities };
260292
});
261-
await this.saveGraph(graph);
262-
return { deletedCount, missingEntities };
263293
}
264294

265295
async deleteRelations(relations: Relation[]): Promise<{ deletedCount: number }> {
266-
const graph = await this.loadGraph();
267-
const before = graph.relations.length;
268-
graph.relations = graph.relations.filter(r => !relations.some(delRelation =>
269-
r.from === delRelation.from &&
270-
r.to === delRelation.to &&
271-
r.relationType === delRelation.relationType
272-
));
273-
await this.saveGraph(graph);
274-
return { deletedCount: before - graph.relations.length };
296+
return this.withLock(async () => {
297+
const graph = await this.loadGraph();
298+
const before = graph.relations.length;
299+
graph.relations = graph.relations.filter(r => !relations.some(delRelation =>
300+
r.from === delRelation.from &&
301+
r.to === delRelation.to &&
302+
r.relationType === delRelation.relationType
303+
));
304+
await this.saveGraph(graph);
305+
return { deletedCount: before - graph.relations.length };
306+
});
275307
}
276308

277309
async readGraph(): Promise<KnowledgeGraph> {

0 commit comments

Comments
 (0)