Skip to content

Commit 27148ef

Browse files
cliffhallclaude
andcommitted
feat(memory): add lightweight read modes to the read tools
read_graph, search_nodes and open_nodes take an optional observationLimit, which caps the observations returned per entity and adds each entity's total as observationCount (0 gives an overview of names, types and counts). read_graph also takes entityTypes, and search_nodes a limit on matches. Every option is optional, so a call without them, and the knowledge-graph resource, return what they did. read_graph's description also says when to use it rather than its siblings (#5202's guidance): its inputSchema is on the next line, so the two edits cannot sit in separate PRs without conflicting. Closes #3953 Co-Authored-By: Claude Opus 5.5 <[email protected]> Signed-off-by: cliffhall <[email protected]>
1 parent 446be48 commit 27148ef

5 files changed

Lines changed: 478 additions & 37 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": minor
3+
---
4+
5+
Add optional lightweight read modes, so a large graph need not be returned whole: `observationLimit` on `read_graph`, `search_nodes` and `open_nodes` caps the observations returned per entity and adds each entity's total as `observationCount` (`0` gives an overview of names, types and counts), `entityTypes` on `read_graph` keeps only entities of those types, and `limit` on `search_nodes` caps the number of matches. Calls without them return what they always have. The `read_graph` description now says when to use it rather than `search_nodes` or `open_nodes`.

‎src/memory/README.md‎

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -109,8 +109,11 @@ Example:
109109

110110
- **read_graph**
111111
- Read the entire knowledge graph
112-
- No input required
112+
- Optional input:
113+
- `entityTypes` (string[], at least one): return only entities of these types, and the relations that touch one of them
114+
- `observationLimit` (integer, 0 or more): see below
113115
- Returns complete graph structure with all entities and relations
116+
- With `observationLimit`, each entity carries at most that many observations (the first ones, in the order they were added) and an `observationCount` with its total. `observationLimit: 0` returns names, types and counts only: a cheap overview of a large graph, from which `open_nodes` reads the entities you need in full
114117

115118
- **search_nodes**
116119
- Search for nodes based on query
@@ -120,6 +123,9 @@ Example:
120123
- Entity types
121124
- Observation content
122125
- Returns matching entities and their relations
126+
- Optional input:
127+
- `limit` (integer, 1 or more): return at most this many matches (the first, in stored order), with the relations that touch them
128+
- `observationLimit` (integer, 0 or more): as for `read_graph`
123129

124130
- **open_nodes**
125131
- Retrieve specific nodes by name
@@ -128,6 +134,7 @@ Example:
128134
- Requested entities
129135
- Relations between requested entities
130136
- Silently skips non-existent nodes
137+
- Optional input: `observationLimit` (integer, 0 or more), as for `read_graph`
131138

132139
### Resources
133140

Lines changed: 249 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,249 @@
1+
// Tests for the read tools' optional inputs (#3953), driven through an SDK
2+
// Client over an in-memory transport: read_graph's entityTypes filter, the
3+
// observationLimit every read tool takes (with the observationCount it adds),
4+
// and search_nodes' limit. Each option is optional, so the default results
5+
// are pinned too: a call without them returns what it always has, and the
6+
// knowledge-graph resource never carries observationCount.
7+
import { describe, it, expect, beforeEach, afterEach } from "vitest";
8+
import type { Client } from "@modelcontextprotocol/client";
9+
import { call, connect, makeTempGraph, textOf } from "./helpers.js";
10+
import type { Connection } from "./helpers.js";
11+
12+
const alice = {
13+
name: "Alice",
14+
entityType: "person",
15+
observations: ["works at Acme Corp", "likes tea", "plays chess"],
16+
};
17+
const bob = {
18+
name: "Bob",
19+
entityType: "person",
20+
observations: ["likes programming"],
21+
};
22+
const acme = {
23+
name: "Acme Corp",
24+
entityType: "organization",
25+
observations: ["makes anvils", "founded in 1900"],
26+
};
27+
const empty = { name: "Nobody", entityType: "placeholder", observations: [] };
28+
const aliceKnowsBob = { from: "Alice", to: "Bob", relationType: "knows" };
29+
const aliceWorksAtAcme = {
30+
from: "Alice",
31+
to: "Acme Corp",
32+
relationType: "works_at",
33+
};
34+
const bobKnowsAlice = { from: "Bob", to: "Alice", relationType: "knows" };
35+
36+
describe("read tool options (#3953)", () => {
37+
let conn: Connection;
38+
let client: Client;
39+
let cleanup: () => Promise<void>;
40+
41+
beforeEach(async () => {
42+
const graph = await makeTempGraph();
43+
cleanup = graph.cleanup;
44+
conn = await connect(graph.filePath);
45+
client = conn.client;
46+
await call(client, "create_entities", {
47+
entities: [alice, bob, acme, empty],
48+
});
49+
await call(client, "create_relations", {
50+
relations: [aliceKnowsBob, aliceWorksAtAcme, bobKnowsAlice],
51+
});
52+
});
53+
54+
afterEach(async () => {
55+
await conn.close();
56+
await cleanup();
57+
});
58+
59+
// Call a tool and return its structured result, checking that the text
60+
// block carries the same graph.
61+
async function read(name: string, args: Record<string, unknown>) {
62+
const result = await call(client, name, args);
63+
expect(result.isError).toBeFalsy();
64+
expect(textOf(result)).toBe(
65+
JSON.stringify(result.structuredContent, null, 2),
66+
);
67+
return result.structuredContent;
68+
}
69+
70+
// The text of a call that must fail input validation.
71+
async function rejected(name: string, args: Record<string, unknown>) {
72+
const result = await call(client, name, args);
73+
expect(result.isError).toBe(true);
74+
return textOf(result);
75+
}
76+
77+
describe("defaults", () => {
78+
it("read_graph without options returns every observation and no counts", async () => {
79+
expect(await read("read_graph", {})).toEqual({
80+
entities: [alice, bob, acme, empty],
81+
relations: [aliceKnowsBob, aliceWorksAtAcme, bobKnowsAlice],
82+
});
83+
});
84+
85+
it("search_nodes and open_nodes without options return full entities", async () => {
86+
expect(await read("search_nodes", { query: "acme" })).toEqual({
87+
entities: [alice, acme],
88+
relations: [aliceKnowsBob, aliceWorksAtAcme, bobKnowsAlice],
89+
});
90+
expect(await read("open_nodes", { names: ["Bob"] })).toEqual({
91+
entities: [bob],
92+
relations: [aliceKnowsBob, bobKnowsAlice],
93+
});
94+
});
95+
96+
it("the knowledge-graph resource is unaffected", async () => {
97+
const { contents } = await client.readResource({
98+
uri: "memory://knowledge-graph",
99+
});
100+
const [content] = contents;
101+
expect("text" in content && JSON.parse(content.text)).toEqual({
102+
entities: [alice, bob, acme, empty],
103+
relations: [aliceKnowsBob, aliceWorksAtAcme, bobKnowsAlice],
104+
});
105+
});
106+
});
107+
108+
describe("observationLimit", () => {
109+
it("0 gives read_graph an overview of names, types and counts", async () => {
110+
expect(await read("read_graph", { observationLimit: 0 })).toEqual({
111+
entities: [
112+
{ ...alice, observations: [], observationCount: 3 },
113+
{ ...bob, observations: [], observationCount: 1 },
114+
{ ...acme, observations: [], observationCount: 2 },
115+
{ ...empty, observationCount: 0 },
116+
],
117+
relations: [aliceKnowsBob, aliceWorksAtAcme, bobKnowsAlice],
118+
});
119+
});
120+
121+
it("keeps the first observations, in the order they were added", async () => {
122+
expect(await read("read_graph", { observationLimit: 2 })).toEqual({
123+
entities: [
124+
{
125+
...alice,
126+
observations: ["works at Acme Corp", "likes tea"],
127+
observationCount: 3,
128+
},
129+
{ ...bob, observationCount: 1 },
130+
{ ...acme, observationCount: 2 },
131+
{ ...empty, observationCount: 0 },
132+
],
133+
relations: [aliceKnowsBob, aliceWorksAtAcme, bobKnowsAlice],
134+
});
135+
});
136+
137+
it("applies to search_nodes", async () => {
138+
expect(
139+
await read("search_nodes", { query: "acme", observationLimit: 1 }),
140+
).toEqual({
141+
entities: [
142+
{
143+
...alice,
144+
observations: ["works at Acme Corp"],
145+
observationCount: 3,
146+
},
147+
{ ...acme, observations: ["makes anvils"], observationCount: 2 },
148+
],
149+
relations: [aliceKnowsBob, aliceWorksAtAcme, bobKnowsAlice],
150+
});
151+
});
152+
153+
it("applies to open_nodes", async () => {
154+
expect(
155+
await read("open_nodes", {
156+
names: ["Alice", "Missing"],
157+
observationLimit: 1,
158+
}),
159+
).toEqual({
160+
entities: [
161+
{
162+
...alice,
163+
observations: ["works at Acme Corp"],
164+
observationCount: 3,
165+
},
166+
],
167+
relations: [aliceKnowsBob, aliceWorksAtAcme, bobKnowsAlice],
168+
});
169+
});
170+
171+
it.each([
172+
["read_graph", {}],
173+
["search_nodes", { query: "a" }],
174+
["open_nodes", { names: ["Alice"] }],
175+
])("%s rejects a negative or fractional limit", async (name, args) => {
176+
expect(await rejected(name, { ...args, observationLimit: -1 })).toContain(
177+
"observationLimit",
178+
);
179+
expect(
180+
await rejected(name, { ...args, observationLimit: 1.5 }),
181+
).toContain("observationLimit");
182+
});
183+
});
184+
185+
describe("read_graph entityTypes", () => {
186+
it("keeps entities of the given types and the relations that touch them", async () => {
187+
expect(
188+
await read("read_graph", { entityTypes: ["organization"] }),
189+
).toEqual({
190+
entities: [acme],
191+
relations: [aliceWorksAtAcme],
192+
});
193+
});
194+
195+
it("accepts several types, and combines with observationLimit", async () => {
196+
expect(
197+
await read("read_graph", {
198+
entityTypes: ["organization", "placeholder"],
199+
observationLimit: 0,
200+
}),
201+
).toEqual({
202+
entities: [
203+
{ ...acme, observations: [], observationCount: 2 },
204+
{ ...empty, observationCount: 0 },
205+
],
206+
relations: [aliceWorksAtAcme],
207+
});
208+
});
209+
210+
it("matches types exactly", async () => {
211+
expect(await read("read_graph", { entityTypes: ["Person"] })).toEqual({
212+
entities: [],
213+
relations: [],
214+
});
215+
});
216+
217+
it("rejects an empty list", async () => {
218+
expect(await rejected("read_graph", { entityTypes: [] })).toContain(
219+
"entityTypes",
220+
);
221+
});
222+
});
223+
224+
describe("search_nodes limit", () => {
225+
it("keeps the first matches and the relations that touch them", async () => {
226+
expect(await read("search_nodes", { query: "acme", limit: 1 })).toEqual({
227+
entities: [alice],
228+
relations: [aliceKnowsBob, aliceWorksAtAcme, bobKnowsAlice],
229+
});
230+
expect(await read("search_nodes", { query: "o", limit: 2 })).toEqual({
231+
entities: [alice, bob],
232+
relations: [aliceKnowsBob, aliceWorksAtAcme, bobKnowsAlice],
233+
});
234+
});
235+
236+
it("returns every match when the limit exceeds them", async () => {
237+
expect(await read("search_nodes", { query: "acme", limit: 10 })).toEqual({
238+
entities: [alice, acme],
239+
relations: [aliceKnowsBob, aliceWorksAtAcme, bobKnowsAlice],
240+
});
241+
});
242+
243+
it("rejects a limit below 1", async () => {
244+
expect(
245+
await rejected("search_nodes", { query: "a", limit: 0 }),
246+
).toContain("limit");
247+
});
248+
});
249+
});

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

Lines changed: 57 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -60,6 +60,39 @@ const graphOutputSchema = {
6060
additionalProperties: false,
6161
};
6262

63+
// The read tools' output (#3953): an entity may also carry observationCount.
64+
const readGraphOutputSchema = {
65+
...graphOutputSchema,
66+
properties: {
67+
...graphOutputSchema.properties,
68+
entities: {
69+
type: "array",
70+
items: {
71+
...entityItem(true),
72+
properties: {
73+
...entityItem(true).properties,
74+
observationCount: {
75+
type: "integer",
76+
minimum: 0,
77+
maximum: Number.MAX_SAFE_INTEGER,
78+
description:
79+
"How many observations the entity holds in total; present only when observationLimit was given",
80+
},
81+
},
82+
},
83+
},
84+
},
85+
};
86+
87+
// The observationLimit input every read tool takes (#3953).
88+
const observationLimitInput = {
89+
type: "integer",
90+
minimum: 0,
91+
maximum: Number.MAX_SAFE_INTEGER,
92+
description:
93+
"Return at most this many observations per entity (the first ones, in the order they were added) and add each entity's total as observationCount. Use 0 for names, types and counts only: a cheap overview of a large graph, after which open_nodes reads the entities you need in full. Omit to return every observation.",
94+
};
95+
6396
const statusOutputSchema = {
6497
type: "object",
6598
properties: { success: { type: "boolean" }, message: { type: "string" } },
@@ -270,13 +303,23 @@ const expectedTools = [
270303
{
271304
name: "read_graph",
272305
title: "Read Graph",
273-
description: "Read the entire knowledge graph",
306+
description:
307+
"Read the entire knowledge graph: every entity with its observations, and every relation. The result grows with the graph, so use this only when you need everything; prefer search_nodes to find entities by keyword and open_nodes to read entities whose names you know.",
274308
inputSchema: {
275309
type: "object",
276-
properties: {},
310+
properties: {
311+
entityTypes: {
312+
type: "array",
313+
items: { type: "string" },
314+
minItems: 1,
315+
description:
316+
"Return only entities whose entityType is one of these (exact match), and only the relations that touch one of them. Omit to return every entity.",
317+
},
318+
observationLimit: observationLimitInput,
319+
},
277320
$schema: JSON_SCHEMA_2020_12,
278321
},
279-
outputSchema: graphOutputSchema,
322+
outputSchema: readGraphOutputSchema,
280323
annotations: readAnnotations,
281324
execution,
282325
},
@@ -293,11 +336,19 @@ const expectedTools = [
293336
description:
294337
"The search query to match against entity names, types, and observation content",
295338
},
339+
limit: {
340+
type: "integer",
341+
minimum: 1,
342+
maximum: Number.MAX_SAFE_INTEGER,
343+
description:
344+
"Return at most this many matching entities (the first matches, in stored order), with the relations that touch them. Omit to return every match.",
345+
},
346+
observationLimit: observationLimitInput,
296347
},
297348
required: ["query"],
298349
$schema: JSON_SCHEMA_2020_12,
299350
},
300-
outputSchema: graphOutputSchema,
351+
outputSchema: readGraphOutputSchema,
301352
annotations: readAnnotations,
302353
execution,
303354
},
@@ -313,11 +364,12 @@ const expectedTools = [
313364
items: { type: "string" },
314365
description: "An array of entity names to retrieve",
315366
},
367+
observationLimit: observationLimitInput,
316368
},
317369
required: ["names"],
318370
$schema: JSON_SCHEMA_2020_12,
319371
},
320-
outputSchema: graphOutputSchema,
372+
outputSchema: readGraphOutputSchema,
321373
annotations: readAnnotations,
322374
execution,
323375
},

0 commit comments

Comments
 (0)