Skip to content

Commit 6bda4c1

Browse files
committed
fix(memory): report entities that create_entities skipped
create_entities ignores entities whose name already exists (documented in the README), but its response only listed the created entities, so an agent that used it to record new facts about an existing entity saw no sign that its observations were dropped. Return the skipped names in structured content and say so in the text, pointing to add_observations.
1 parent f46d957 commit 6bda4c1

3 files changed

Lines changed: 96 additions & 4 deletions

File tree

‎src/memory/README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -62,7 +62,7 @@ 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 lists them in `skipped` (use `add_observations` to extend an existing entity)
6666

6767
- **create_relations**
6868
- Create multiple new relations between entities
Lines changed: 69 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,69 @@
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';
6+
7+
/**
8+
* create_entities ignores entities whose name already exists, as the README
9+
* documents. The agent only sees the tool description, though, so the response
10+
* must say which entities were skipped: otherwise their observations look
11+
* stored when nothing was written.
12+
*/
13+
describe('create reporting', () => {
14+
let manager: KnowledgeGraphManager;
15+
let testFilePath: string;
16+
17+
beforeEach(async () => {
18+
testFilePath = path.join(
19+
path.dirname(fileURLToPath(import.meta.url)),
20+
`test-create-reporting-${Date.now()}-${Math.random().toString(16).slice(2)}.jsonl`
21+
);
22+
manager = new KnowledgeGraphManager(testFilePath);
23+
await manager.createEntities([{ name: 'Alice', entityType: 'person', observations: ['works at Acme Corp'] }]);
24+
});
25+
26+
afterEach(async () => {
27+
try {
28+
await fs.unlink(testFilePath);
29+
} catch {
30+
// the file is gone already
31+
}
32+
});
33+
34+
it('names an entity skipped because it already exists', async () => {
35+
const requested: Entity[] = [
36+
{ name: 'Alice', entityType: 'person', observations: ['allergic to penicillin'] },
37+
{ name: 'Bob', entityType: 'person', observations: [] },
38+
];
39+
const created = await manager.createEntities(requested);
40+
expect(created.map(e => e.name)).toEqual(['Bob']);
41+
expect(skippedEntityNames(requested, created)).toEqual(['Alice']);
42+
});
43+
44+
it('names a repeat within the same batch', async () => {
45+
const requested: Entity[] = [
46+
{ name: 'Carol', entityType: 'person', observations: ['first'] },
47+
{ name: 'Carol', entityType: 'person', observations: ['second'] },
48+
];
49+
const created = await manager.createEntities(requested);
50+
expect(skippedEntityNames(requested, created)).toEqual(['Carol']);
51+
});
52+
53+
it('reports nothing skipped when every entity is new', async () => {
54+
const requested: Entity[] = [{ name: 'Dan', entityType: 'person', observations: [] }];
55+
const created = await manager.createEntities(requested);
56+
expect(skippedEntityNames(requested, created)).toEqual([]);
57+
});
58+
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.'
63+
);
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.'
67+
);
68+
});
69+
});

‎src/memory/index.ts‎

Lines changed: 26 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -82,6 +82,21 @@ export interface KnowledgeGraph {
8282
relations: Relation[];
8383
}
8484

85+
// Names of requested entities that createEntities did not create: the name
86+
// already existed, or repeated earlier in the same batch. createEntities
87+
// returns the created entities themselves, so identity tells them apart.
88+
export function skippedEntityNames(requested: Entity[], created: Entity[]): string[] {
89+
return requested.filter(e => !created.includes(e)).map(e => e.name);
90+
}
91+
92+
// Text telling the agent which entities create_entities skipped.
93+
export function skippedEntitiesNotice(skipped: string[]): string {
94+
const one = skipped.length === 1;
95+
return `Skipped ${skipped.length} ${one ? "entity that already exists" : "entities that already exist"}: ` +
96+
`${skipped.join(", ")}. ${one ? "Its" : "Their"} observations were not added; ` +
97+
"use add_observations for existing entities.";
98+
}
99+
85100
// The KnowledgeGraphManager class contains all operations to interact with the knowledge graph
86101
export class KnowledgeGraphManager {
87102
constructor(private memoryFilePath: string) {}
@@ -408,7 +423,8 @@ server.registerTool(
408423
entities: z.array(EntitySchema)
409424
},
410425
outputSchema: {
411-
entities: z.array(EntitySchema)
426+
entities: z.array(EntitySchema),
427+
skipped: z.array(z.string())
412428
},
413429
annotations: {
414430
readOnlyHint: false,
@@ -420,9 +436,16 @@ server.registerTool(
420436
async ({ entities }) => {
421437
const result = await knowledgeGraphManager.createEntities(entities);
422438
notifyGraphUpdated();
439+
// Existing names are ignored (see README). Say so: otherwise an agent
440+
// reads the response as its observations having been stored.
441+
const skipped = skippedEntityNames(entities, result);
442+
const content = [{ type: "text" as const, text: JSON.stringify(result, null, 2) }];
443+
if (skipped.length > 0) {
444+
content.push({ type: "text" as const, text: skippedEntitiesNotice(skipped) });
445+
}
423446
return {
424-
content: [{ type: "text" as const, text: JSON.stringify(result, null, 2) }],
425-
structuredContent: { entities: result }
447+
content,
448+
structuredContent: { entities: result, skipped }
426449
};
427450
}
428451
);

0 commit comments

Comments
 (0)