Skip to content

Commit bb8aa6f

Browse files
cliffhallclaude
andcommitted
fix(memory): say in create_entities' description that existing names are skipped
Follow-up to the cherry-picked fix for #4887, for v2/main: - The tool description now says an entity whose name already exists (or repeats earlier in the call) is skipped, that its observations are not added, that the skipped names come back in `skipped`, and to use add_observations for an existing entity. - `skipped` is optional in the output schema and present only when something was skipped, so a call that skips nothing returns the same structured content as before. - The two KNOWN BUG #4887 pinning tests in tools.test.ts now assert the reported skip; the markers are gone. The tool-list test pins the new description and output schema. - README describes the skip report; changeset added. Co-Authored-By: Claude Opus 5.5 <[email protected]> Signed-off-by: cliffhall <[email protected]>
1 parent 9112039 commit bb8aa6f

5 files changed

Lines changed: 102 additions & 47 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, and lists them in `skipped` (use `add_observations` to extend an existing entity)
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: 43 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -1,26 +1,37 @@
1-
import { describe, it, expect, beforeEach, afterEach } from 'vitest';
2-
import { promises as fs } from 'fs';
3-
import path from 'path';
4-
import { fileURLToPath } from 'url';
5-
import { KnowledgeGraphManager, Entity, skippedEntityNames, skippedEntitiesNotice } from '../index.js';
1+
import { describe, it, expect, beforeEach, afterEach } from "vitest";
2+
import { promises as fs } from "fs";
3+
import path from "path";
4+
import { fileURLToPath } from "url";
5+
import {
6+
KnowledgeGraphManager,
7+
Entity,
8+
skippedEntityNames,
9+
skippedEntitiesNotice,
10+
} from "../index.js";
611

712
/**
813
* create_entities ignores entities whose name already exists, as the README
914
* documents. The agent only sees the tool description, though, so the response
1015
* must say which entities were skipped: otherwise their observations look
1116
* stored when nothing was written.
1217
*/
13-
describe('create reporting', () => {
18+
describe("create reporting", () => {
1419
let manager: KnowledgeGraphManager;
1520
let testFilePath: string;
1621

1722
beforeEach(async () => {
1823
testFilePath = path.join(
1924
path.dirname(fileURLToPath(import.meta.url)),
20-
`test-create-reporting-${Date.now()}-${Math.random().toString(16).slice(2)}.jsonl`
25+
`test-create-reporting-${Date.now()}-${Math.random().toString(16).slice(2)}.jsonl`,
2126
);
2227
manager = new KnowledgeGraphManager(testFilePath);
23-
await manager.createEntities([{ name: 'Alice', entityType: 'person', observations: ['works at Acme Corp'] }]);
28+
await manager.createEntities([
29+
{
30+
name: "Alice",
31+
entityType: "person",
32+
observations: ["works at Acme Corp"],
33+
},
34+
]);
2435
});
2536

2637
afterEach(async () => {
@@ -31,39 +42,45 @@ describe('create reporting', () => {
3142
}
3243
});
3344

34-
it('names an entity skipped because it already exists', async () => {
45+
it("names an entity skipped because it already exists", async () => {
3546
const requested: Entity[] = [
36-
{ name: 'Alice', entityType: 'person', observations: ['allergic to penicillin'] },
37-
{ name: 'Bob', entityType: 'person', observations: [] },
47+
{
48+
name: "Alice",
49+
entityType: "person",
50+
observations: ["allergic to penicillin"],
51+
},
52+
{ name: "Bob", entityType: "person", observations: [] },
3853
];
3954
const created = await manager.createEntities(requested);
40-
expect(created.map(e => e.name)).toEqual(['Bob']);
41-
expect(skippedEntityNames(requested, created)).toEqual(['Alice']);
55+
expect(created.map((e) => e.name)).toEqual(["Bob"]);
56+
expect(skippedEntityNames(requested, created)).toEqual(["Alice"]);
4257
});
4358

44-
it('names a repeat within the same batch', async () => {
59+
it("names a repeat within the same batch", async () => {
4560
const requested: Entity[] = [
46-
{ name: 'Carol', entityType: 'person', observations: ['first'] },
47-
{ name: 'Carol', entityType: 'person', observations: ['second'] },
61+
{ name: "Carol", entityType: "person", observations: ["first"] },
62+
{ name: "Carol", entityType: "person", observations: ["second"] },
4863
];
4964
const created = await manager.createEntities(requested);
50-
expect(skippedEntityNames(requested, created)).toEqual(['Carol']);
65+
expect(skippedEntityNames(requested, created)).toEqual(["Carol"]);
5166
});
5267

53-
it('reports nothing skipped when every entity is new', async () => {
54-
const requested: Entity[] = [{ name: 'Dan', entityType: 'person', observations: [] }];
68+
it("reports nothing skipped when every entity is new", async () => {
69+
const requested: Entity[] = [
70+
{ name: "Dan", entityType: "person", observations: [] },
71+
];
5572
const created = await manager.createEntities(requested);
5673
expect(skippedEntityNames(requested, created)).toEqual([]);
5774
});
5875

59-
it('words the notice for one and for several skipped entities', () => {
60-
expect(skippedEntitiesNotice(['Alice'])).toBe(
61-
'Skipped 1 entity that already exists: Alice. Its observations were not added; ' +
62-
'use add_observations for existing entities.'
76+
it("words the notice for one and for several skipped entities", () => {
77+
expect(skippedEntitiesNotice(["Alice"])).toBe(
78+
"Skipped 1 entity that already exists: Alice. Its observations were not added; " +
79+
"use add_observations for existing entities.",
6380
);
64-
expect(skippedEntitiesNotice(['Alice', 'Bob'])).toBe(
65-
'Skipped 2 entities that already exist: Alice, Bob. Their observations were not added; ' +
66-
'use add_observations for existing entities.'
81+
expect(skippedEntitiesNotice(["Alice", "Bob"])).toBe(
82+
"Skipped 2 entities that already exist: Alice, Bob. Their observations were not added; " +
83+
"use add_observations for existing entities.",
6784
);
6885
});
6986
});

‎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: 17 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -105,16 +105,21 @@ export interface KnowledgeGraph {
105105
// Names of requested entities that createEntities did not create: the name
106106
// already existed, or repeated earlier in the same batch. createEntities
107107
// returns the created entities themselves, so identity tells them apart.
108-
export function skippedEntityNames(requested: Entity[], created: Entity[]): string[] {
109-
return requested.filter(e => !created.includes(e)).map(e => e.name);
108+
export function skippedEntityNames(
109+
requested: Entity[],
110+
created: Entity[],
111+
): string[] {
112+
return requested.filter((e) => !created.includes(e)).map((e) => e.name);
110113
}
111114

112115
// Text telling the agent which entities create_entities skipped.
113116
export function skippedEntitiesNotice(skipped: string[]): string {
114117
const one = skipped.length === 1;
115-
return `Skipped ${skipped.length} ${one ? "entity that already exists" : "entities that already exist"}: ` +
118+
return (
119+
`Skipped ${skipped.length} ${one ? "entity that already exists" : "entities that already exist"}: ` +
116120
`${skipped.join(", ")}. ${one ? "Its" : "Their"} observations were not added; ` +
117-
"use add_observations for existing entities.";
121+
"use add_observations for existing entities."
122+
);
118123
}
119124

120125
// The KnowledgeGraphManager class contains all operations to interact with the knowledge graph
@@ -503,13 +508,15 @@ export function createServer(memoryFilePath: string): McpServer {
503508
"create_entities",
504509
{
505510
title: "Create Entities",
506-
description: "Create multiple new entities in the knowledge graph",
511+
description:
512+
"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.",
507513
inputSchema: {
508514
entities: z.array(EntitySchema),
509515
},
510516
outputSchema: {
511517
entities: z.array(EntitySchema),
512-
skipped: z.array(z.string()),
518+
// Present only when at least one requested entity was skipped.
519+
skipped: z.array(z.string()).optional(),
513520
},
514521
annotations: {
515522
readOnlyHint: false,
@@ -535,7 +542,10 @@ export function createServer(memoryFilePath: string): McpServer {
535542
}
536543
return {
537544
content,
538-
structuredContent: { entities: result, skipped },
545+
structuredContent:
546+
skipped.length > 0
547+
? { entities: result, skipped }
548+
: { entities: result },
539549
};
540550
},
541551
);

0 commit comments

Comments
 (0)