Skip to content

Commit 0ae72ec

Browse files
fix(memory): serialize graph mutations to prevent concurrent write race
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
1 parent d31124c commit 0ae72ec

2 files changed

Lines changed: 152 additions & 45 deletions

File tree

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

Lines changed: 76 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -515,4 +515,79 @@ describe('KnowledgeGraphManager', () => {
515515
expect(result.relations[0]).not.toHaveProperty('type');
516516
});
517517
});
518-
});
518+
519+
describe('concurrent mutations', () => {
520+
// Regression test for #1819: concurrent tool calls each independently
521+
// load the graph, mutate their own copy, and write it back. Without
522+
// serialization, whichever write lands last silently discards the
523+
// other's changes. All mutations below are fired without awaiting each
524+
// other first, simulating multiple tool calls landing close together.
525+
526+
it('should not lose entities created concurrently', async () => {
527+
const batch1: Entity[] = Array.from({ length: 10 }, (_, i) => ({
528+
name: `batch1-entity-${i}`,
529+
entityType: 'test',
530+
observations: [],
531+
}));
532+
const batch2: Entity[] = Array.from({ length: 10 }, (_, i) => ({
533+
name: `batch2-entity-${i}`,
534+
entityType: 'test',
535+
observations: [],
536+
}));
537+
538+
// Fire both concurrently instead of awaiting sequentially.
539+
await Promise.all([
540+
manager.createEntities(batch1),
541+
manager.createEntities(batch2),
542+
]);
543+
544+
const graph = await manager.readGraph();
545+
expect(graph.entities).toHaveLength(20);
546+
expect(graph.entities.map(e => e.name).sort()).toEqual(
547+
[...batch1, ...batch2].map(e => e.name).sort()
548+
);
549+
});
550+
551+
it('should not lose relations created concurrently with entity creation', async () => {
552+
await manager.createEntities([
553+
{ name: 'Alice', entityType: 'person', observations: [] },
554+
{ name: 'Bob', entityType: 'person', observations: [] },
555+
{ name: 'Carol', entityType: 'person', observations: [] },
556+
]);
557+
558+
await Promise.all([
559+
manager.createRelations([{ from: 'Alice', to: 'Bob', relationType: 'knows' }]),
560+
manager.createRelations([{ from: 'Bob', to: 'Carol', relationType: 'knows' }]),
561+
manager.addObservations([
562+
{ entityName: 'Alice', contents: ['likes coffee'] },
563+
]),
564+
]);
565+
566+
const graph = await manager.readGraph();
567+
expect(graph.relations).toHaveLength(2);
568+
expect(graph.entities.find(e => e.name === 'Alice')?.observations).toContain('likes coffee');
569+
});
570+
571+
it('should keep the file valid JSONL after many concurrent mutations', async () => {
572+
const operations = Array.from({ length: 25 }, (_, i) =>
573+
manager.createEntities([
574+
{ name: `stress-entity-${i}`, entityType: 'test', observations: [] },
575+
])
576+
);
577+
578+
await Promise.all(operations);
579+
580+
const raw = await fs.readFile(testFilePath, 'utf-8');
581+
const lines = raw.split('\n').filter(line => line.trim() !== '');
582+
583+
// Every line must parse as valid JSON; a corrupted interleaved write
584+
// would produce a truncated or malformed line here.
585+
for (const line of lines) {
586+
expect(() => JSON.parse(line)).not.toThrow();
587+
}
588+
589+
const graph = await manager.readGraph();
590+
expect(graph.entities).toHaveLength(25);
591+
});
592+
});
593+
});

‎src/memory/index.ts‎

Lines changed: 76 additions & 44 deletions
Original file line numberDiff line numberDiff line change
@@ -69,6 +69,26 @@ export interface KnowledgeGraph {
6969
export class KnowledgeGraphManager {
7070
constructor(private memoryFilePath: string) {}
7171

72+
// Serializes all read-modify-write graph mutations behind a single queue.
73+
// Without this, concurrent tool calls (e.g. multiple mutations dispatched
74+
// from one LLM turn) each independently load the graph, mutate their own
75+
// copy, and write it back — so whichever write lands last silently
76+
// overwrites the other's changes, and interleaved writes to the same file
77+
// can corrupt it outright. See #1819.
78+
private mutationQueue: Promise<unknown> = Promise.resolve();
79+
80+
private async withLock<T>(operation: () => Promise<T>): Promise<T> {
81+
const result = this.mutationQueue.then(operation, operation);
82+
// Always resolve the queue itself, even if this operation failed, so a
83+
// single failed mutation doesn't permanently wedge every call after it.
84+
// The failure still propagates normally to whoever awaited `result`.
85+
this.mutationQueue = result.then(
86+
() => undefined,
87+
() => undefined,
88+
);
89+
return result;
90+
}
91+
7292
private async loadGraph(): Promise<KnowledgeGraph> {
7393
try {
7494
const data = await fs.readFile(this.memoryFilePath, "utf-8");
@@ -118,66 +138,78 @@ export class KnowledgeGraphManager {
118138
}
119139

120140
async createEntities(entities: Entity[]): Promise<Entity[]> {
121-
const graph = await this.loadGraph();
122-
const newEntities = entities.filter(e => !graph.entities.some(existingEntity => existingEntity.name === e.name));
123-
graph.entities.push(...newEntities);
124-
await this.saveGraph(graph);
125-
return newEntities;
141+
return this.withLock(async () => {
142+
const graph = await this.loadGraph();
143+
const newEntities = entities.filter(e => !graph.entities.some(existingEntity => existingEntity.name === e.name));
144+
graph.entities.push(...newEntities);
145+
await this.saveGraph(graph);
146+
return newEntities;
147+
});
126148
}
127149

128150
async createRelations(relations: Relation[]): Promise<Relation[]> {
129-
const graph = await this.loadGraph();
130-
const newRelations = relations.filter(r => !graph.relations.some(existingRelation =>
131-
existingRelation.from === r.from &&
132-
existingRelation.to === r.to &&
133-
existingRelation.relationType === r.relationType
134-
));
135-
graph.relations.push(...newRelations);
136-
await this.saveGraph(graph);
137-
return newRelations;
151+
return this.withLock(async () => {
152+
const graph = await this.loadGraph();
153+
const newRelations = relations.filter(r => !graph.relations.some(existingRelation =>
154+
existingRelation.from === r.from &&
155+
existingRelation.to === r.to &&
156+
existingRelation.relationType === r.relationType
157+
));
158+
graph.relations.push(...newRelations);
159+
await this.saveGraph(graph);
160+
return newRelations;
161+
});
138162
}
139163

140164
async addObservations(observations: { entityName: string; contents: string[] }[]): Promise<{ entityName: string; addedObservations: string[] }[]> {
141-
const graph = await this.loadGraph();
142-
const results = observations.map(o => {
143-
const entity = graph.entities.find(e => e.name === o.entityName);
144-
if (!entity) {
145-
throw new Error(`Entity with name ${o.entityName} not found`);
146-
}
147-
const newObservations = o.contents.filter(content => !entity.observations.includes(content));
148-
entity.observations.push(...newObservations);
149-
return { entityName: o.entityName, addedObservations: newObservations };
165+
return this.withLock(async () => {
166+
const graph = await this.loadGraph();
167+
const results = observations.map(o => {
168+
const entity = graph.entities.find(e => e.name === o.entityName);
169+
if (!entity) {
170+
throw new Error(`Entity with name ${o.entityName} not found`);
171+
}
172+
const newObservations = o.contents.filter(content => !entity.observations.includes(content));
173+
entity.observations.push(...newObservations);
174+
return { entityName: o.entityName, addedObservations: newObservations };
175+
});
176+
await this.saveGraph(graph);
177+
return results;
150178
});
151-
await this.saveGraph(graph);
152-
return results;
153179
}
154180

155181
async deleteEntities(entityNames: string[]): Promise<void> {
156-
const graph = await this.loadGraph();
157-
graph.entities = graph.entities.filter(e => !entityNames.includes(e.name));
158-
graph.relations = graph.relations.filter(r => !entityNames.includes(r.from) && !entityNames.includes(r.to));
159-
await this.saveGraph(graph);
182+
return this.withLock(async () => {
183+
const graph = await this.loadGraph();
184+
graph.entities = graph.entities.filter(e => !entityNames.includes(e.name));
185+
graph.relations = graph.relations.filter(r => !entityNames.includes(r.from) && !entityNames.includes(r.to));
186+
await this.saveGraph(graph);
187+
});
160188
}
161189

162190
async deleteObservations(deletions: { entityName: string; observations: string[] }[]): Promise<void> {
163-
const graph = await this.loadGraph();
164-
deletions.forEach(d => {
165-
const entity = graph.entities.find(e => e.name === d.entityName);
166-
if (entity) {
167-
entity.observations = entity.observations.filter(o => !d.observations.includes(o));
168-
}
191+
return this.withLock(async () => {
192+
const graph = await this.loadGraph();
193+
deletions.forEach(d => {
194+
const entity = graph.entities.find(e => e.name === d.entityName);
195+
if (entity) {
196+
entity.observations = entity.observations.filter(o => !d.observations.includes(o));
197+
}
198+
});
199+
await this.saveGraph(graph);
169200
});
170-
await this.saveGraph(graph);
171201
}
172202

173203
async deleteRelations(relations: Relation[]): Promise<void> {
174-
const graph = await this.loadGraph();
175-
graph.relations = graph.relations.filter(r => !relations.some(delRelation =>
176-
r.from === delRelation.from &&
177-
r.to === delRelation.to &&
178-
r.relationType === delRelation.relationType
179-
));
180-
await this.saveGraph(graph);
204+
return this.withLock(async () => {
205+
const graph = await this.loadGraph();
206+
graph.relations = graph.relations.filter(r => !relations.some(delRelation =>
207+
r.from === delRelation.from &&
208+
r.to === delRelation.to &&
209+
r.relationType === delRelation.relationType
210+
));
211+
await this.saveGraph(graph);
212+
});
181213
}
182214

183215
async readGraph(): Promise<KnowledgeGraph> {
@@ -599,4 +631,4 @@ async function main() {
599631
main().catch((error) => {
600632
console.error("Fatal error in main():", error);
601633
process.exit(1);
602-
});
634+
});

0 commit comments

Comments
 (0)