Skip to content

Commit 1520a8b

Browse files
authored
Merge pull request #5008 from modelcontextprotocol/v2/fix/4887-memory-report-skipped-entities
fix(memory): report entities that create_entities skipped (#4887)
2 parents 272d7f6 + bfe912b commit 1520a8b

5 files changed

Lines changed: 168 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+
`create_entities` now reports the entities it skipped because their name already exists (or repeats earlier in the same call): the structured result lists them in a new optional `skipped` array, a second text item names them and points to `add_observations`, and the tool description says so. Skipped entities are still not created and their observations are still not added (#4887).

‎src/memory/README.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -62,7 +62,8 @@ Example:
6262
- `name` (string): Entity identifier
6363
- `entityType` (string): Type classification
6464
- `observations` (string[]): Associated observations
65-
- Ignores entities with existing names
65+
- Ignores entities with existing names (and repeats of a name earlier in the same call); their observations are not added
66+
- Returns the created entities. When any were skipped, the structured result also lists their names in `skipped`, and a second text item says which were skipped (use `add_observations` to extend an existing entity)
6667

6768
- **create_relations**
6869
- Create multiple new relations between entities
Lines changed: 85 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,85 @@
1+
// Unit tests for the helpers behind create_entities' skip report (#4887).
2+
// create_entities ignores entities whose name already exists, as the README
3+
// documents. The agent only sees the tool description and the result, though,
4+
// so the result must say which entities were skipped: otherwise their
5+
// observations look stored when nothing was written.
6+
import { describe, it, expect, beforeEach, afterEach } from "vitest";
7+
import { promises as fs } from "fs";
8+
import path from "path";
9+
import { fileURLToPath } from "url";
10+
import {
11+
KnowledgeGraphManager,
12+
Entity,
13+
skippedEntityNames,
14+
skippedEntitiesNotice,
15+
} from "../index.js";
16+
17+
describe("create reporting", () => {
18+
let manager: KnowledgeGraphManager;
19+
let testFilePath: string;
20+
21+
beforeEach(async () => {
22+
testFilePath = path.join(
23+
path.dirname(fileURLToPath(import.meta.url)),
24+
`test-create-reporting-${Date.now()}-${Math.random().toString(16).slice(2)}.jsonl`,
25+
);
26+
manager = new KnowledgeGraphManager(testFilePath);
27+
await manager.createEntities([
28+
{
29+
name: "Alice",
30+
entityType: "person",
31+
observations: ["works at Acme Corp"],
32+
},
33+
]);
34+
});
35+
36+
afterEach(async () => {
37+
try {
38+
await fs.unlink(testFilePath);
39+
} catch {
40+
// the file is gone already
41+
}
42+
});
43+
44+
it("names an entity skipped because it already exists", async () => {
45+
const requested: Entity[] = [
46+
{
47+
name: "Alice",
48+
entityType: "person",
49+
observations: ["allergic to penicillin"],
50+
},
51+
{ name: "Bob", entityType: "person", observations: [] },
52+
];
53+
const created = await manager.createEntities(requested);
54+
expect(created.map((e) => e.name)).toEqual(["Bob"]);
55+
expect(skippedEntityNames(requested, created)).toEqual(["Alice"]);
56+
});
57+
58+
it("names a repeat within the same batch", async () => {
59+
const requested: Entity[] = [
60+
{ name: "Carol", entityType: "person", observations: ["first"] },
61+
{ name: "Carol", entityType: "person", observations: ["second"] },
62+
];
63+
const created = await manager.createEntities(requested);
64+
expect(skippedEntityNames(requested, created)).toEqual(["Carol"]);
65+
});
66+
67+
it("reports nothing skipped when every entity is new", async () => {
68+
const requested: Entity[] = [
69+
{ name: "Dan", entityType: "person", observations: [] },
70+
];
71+
const created = await manager.createEntities(requested);
72+
expect(skippedEntityNames(requested, created)).toEqual([]);
73+
});
74+
75+
it("words the notice for one and for several skipped entities", () => {
76+
expect(skippedEntitiesNotice(["Alice"])).toBe(
77+
"Skipped 1 entity that already exists: Alice. Its observations were not added; " +
78+
"use add_observations for existing entities.",
79+
);
80+
expect(skippedEntitiesNotice(["Alice", "Bob"])).toBe(
81+
"Skipped 2 entities that already exist: Alice, Bob. Their observations were not added; " +
82+
"use add_observations for existing entities.",
83+
);
84+
});
85+
});

‎src/memory/__tests__/tools.test.ts‎

Lines changed: 35 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -92,7 +92,8 @@ const expectedTools = [
9292
{
9393
name: "create_entities",
9494
title: "Create Entities",
95-
description: "Create multiple new entities in the knowledge graph",
95+
description:
96+
"Create multiple new entities in the knowledge graph. An entity whose name already exists, or repeats an earlier entity in the same call, is skipped and its observations are not added; the result lists the skipped names in `skipped`. Use add_observations to add observations to an existing entity.",
9697
inputSchema: {
9798
type: "object",
9899
properties: { entities: { type: "array", items: entityItem(false) } },
@@ -101,7 +102,10 @@ const expectedTools = [
101102
},
102103
outputSchema: {
103104
type: "object",
104-
properties: { entities: { type: "array", items: entityItem(true) } },
105+
properties: {
106+
entities: { type: "array", items: entityItem(true) },
107+
skipped: { type: "array", items: { type: "string" } },
108+
},
105109
required: ["entities"],
106110
$schema: DRAFT_07,
107111
additionalProperties: false,
@@ -419,22 +423,30 @@ describe("memory tools over the protocol", () => {
419423
expect(textOf(result)).toBe("[]");
420424
});
421425

422-
// KNOWN BUG #4887: pins current (wrong) behavior; the fix changes this assertion.
423-
it("keeps only the first of two same-named entities in one batch", async () => {
426+
it("keeps the first of two same-named entities in one batch and reports the second as skipped (#4887)", async () => {
424427
const second = { ...alice, entityType: "robot", observations: ["beeps"] };
425428
const result = await call(client, "create_entities", {
426429
entities: [alice, second],
427430
});
428-
expect(result.structuredContent).toEqual({ entities: [alice] });
431+
expect(result.isError).toBeUndefined();
432+
expect(result.structuredContent).toEqual({
433+
entities: [alice],
434+
skipped: ["Alice"],
435+
});
436+
expect(result.content).toEqual([
437+
{ type: "text", text: JSON.stringify([alice], null, 2) },
438+
{
439+
type: "text",
440+
text: "Skipped 1 entity that already exists: Alice. Its observations were not added; use add_observations for existing entities.",
441+
},
442+
]);
429443
expect(await readGraph()).toEqual({ entities: [alice], relations: [] });
430444
});
431445

432-
// KNOWN BUG #4887: pins current (wrong) behavior; the fix changes this assertion.
433-
// Characterizes #4887: create_entities silently drops the observations of
434-
// an entity whose name already exists. The call succeeds, reports nothing
435-
// created, and the new observation is lost. The fix for #4887 changes this
436-
// test.
437-
it("drops observations for an entity that already exists (#4887)", async () => {
446+
// #4887: create_entities still ignores an entity whose name already
447+
// exists, as documented, but now reports it as skipped so the caller
448+
// knows its observations were not stored.
449+
it("reports an entity that already exists as skipped (#4887)", async () => {
438450
await call(client, "create_entities", {
439451
entities: [
440452
{
@@ -452,12 +464,22 @@ describe("memory tools over the protocol", () => {
452464
entityType: "person",
453465
observations: ["Allergic to penicillin"],
454466
},
467+
bob,
455468
],
456469
});
457470

458471
expect(result.isError).toBeUndefined();
459-
expect(result.structuredContent).toEqual({ entities: [] });
460-
expect(textOf(result)).toBe("[]");
472+
expect(result.structuredContent).toEqual({
473+
entities: [bob],
474+
skipped: ["Alice"],
475+
});
476+
expect(result.content).toEqual([
477+
{ type: "text", text: JSON.stringify([bob], null, 2) },
478+
{
479+
type: "text",
480+
text: "Skipped 1 entity that already exists: Alice. Its observations were not added; use add_observations for existing entities.",
481+
},
482+
]);
461483
const opened = await call(client, "open_nodes", { names: ["Alice"] });
462484
expect(opened.structuredContent).toEqual({
463485
entities: [

‎src/memory/index.ts‎

Lines changed: 41 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -102,6 +102,26 @@ export interface KnowledgeGraph {
102102
relations: Relation[];
103103
}
104104

105+
// Names of requested entities that createEntities did not create: the name
106+
// already existed, or repeated earlier in the same batch. createEntities
107+
// returns the created entities themselves, so identity tells them apart.
108+
export function skippedEntityNames(
109+
requested: Entity[],
110+
created: Entity[],
111+
): string[] {
112+
return requested.filter((e) => !created.includes(e)).map((e) => e.name);
113+
}
114+
115+
// Text telling the agent which entities create_entities skipped.
116+
export function skippedEntitiesNotice(skipped: string[]): string {
117+
const one = skipped.length === 1;
118+
return (
119+
`Skipped ${skipped.length} ${one ? "entity that already exists" : "entities that already exist"}: ` +
120+
`${skipped.join(", ")}. ${one ? "Its" : "Their"} observations were not added; ` +
121+
"use add_observations for existing entities."
122+
);
123+
}
124+
105125
// The KnowledgeGraphManager class contains all operations to interact with the knowledge graph
106126
export class KnowledgeGraphManager {
107127
constructor(private memoryFilePath: string) {}
@@ -511,12 +531,15 @@ export function createServer(memoryFilePath: string): McpServer {
511531
"create_entities",
512532
{
513533
title: "Create Entities",
514-
description: "Create multiple new entities in the knowledge graph",
534+
description:
535+
"Create multiple new entities in the knowledge graph. An entity whose name already exists, or repeats an earlier entity in the same call, is skipped and its observations are not added; the result lists the skipped names in `skipped`. Use add_observations to add observations to an existing entity.",
515536
inputSchema: {
516537
entities: z.array(EntitySchema),
517538
},
518539
outputSchema: {
519540
entities: z.array(EntitySchema),
541+
// Present only when at least one requested entity was skipped.
542+
skipped: z.array(z.string()).optional(),
520543
},
521544
annotations: {
522545
readOnlyHint: false,
@@ -528,11 +551,24 @@ export function createServer(memoryFilePath: string): McpServer {
528551
async ({ entities }) => {
529552
const result = await knowledgeGraphManager.createEntities(entities);
530553
notifyGraphUpdated();
554+
// Existing names are ignored (see README). Say so: otherwise an agent
555+
// reads the response as its observations having been stored.
556+
const skipped = skippedEntityNames(entities, result);
557+
const content = [
558+
{ type: "text" as const, text: JSON.stringify(result, null, 2) },
559+
];
560+
if (skipped.length > 0) {
561+
content.push({
562+
type: "text" as const,
563+
text: skippedEntitiesNotice(skipped),
564+
});
565+
}
531566
return {
532-
content: [
533-
{ type: "text" as const, text: JSON.stringify(result, null, 2) },
534-
],
535-
structuredContent: { entities: result },
567+
content,
568+
structuredContent:
569+
skipped.length > 0
570+
? { entities: result, skipped }
571+
: { entities: result },
536572
};
537573
},
538574
);

0 commit comments

Comments
 (0)