[cliffhall]

Closes #3953

Description

Optional lightweight read modes for the memory server's three read tools, so a large graph need not be returned whole:

Tool	New optional input	Effect
read_graph, search_nodes, open_nodes	observationLimit (integer ≥ 0)	Each entity carries at most that many observations (the first ones, in the order they were added) and an observationCount with its total. 0 returns names, types and counts only: the "metadata only" overview the issue asks for
read_graph	entityTypes (string[], at least one)	Only entities of those types (exact match), and the relations that touch one of them
search_nodes	limit (integer ≥ 1)	At most that many matches (the first, in stored order), with the relations that touch them

Every option is optional: a call without them, and the memory://knowledge-graph resource, return exactly what they did. Inputs are Zod-validated, with a description on every field that says when to use it (observationLimit: 0 for an overview, then open_nodes for the entities you need). The read tools' outputSchema gains an optional observationCount on each entity, so structured results still validate. README and a minor changeset are included.

read_graph's description also changes here, carrying the #5202 guidance ("use this only when you need everything; prefer search_nodes … and open_nodes …"). Its description: and inputSchema: lines are adjacent, so they cannot be edited by two PRs that merge cleanly in either order; the #5202 PR changes the other two descriptions.

Server Details

• Server: memory (@modelcontextprotocol/server-memory)
• Changes to: tools read_graph, search_nodes, open_nodes (new optional inputs, optional observationCount in output, read_graph description), the manager's readGraph/searchNodes/openNodes, README, tests.

Motivation and Context

#3953: on a long-lived graph read_graph returns every observation of every entity, tens of thousands of tokens, with no way to load names first and observations selectively. The prototype #3959 by @surapuramakhil informed this; it differs in folding includeObservations and metadataOnly into observationLimit: 0 (one knob instead of three overlapping ones, and the counts the issue asks for), and in not adding observation paging.

Declined as beyond a reference-server-sized change: pagination cursors / observationOffset, archiving or splitting oversized observations into new entities, and sorting or "most recent first" selection. Each would be a capability of its own, not an optional knob on the existing reads.

How Has This Been Tested?

Protocol-level tests in __tests__/read-options.test.ts (an SDK Client over an in-memory transport) cover every option on every tool, their combinations, the defaults (unchanged results, no observationCount, the resource unaffected) and the validation errors; __tests__/tools.test.ts pins the new advertised schemas. Per-file coverage of index.ts: 98.9 statements, 99.3 branches, 98.1 functions, 99.2 lines.

Inspector CLI 2.12.0, against a seeded graph (Alice: 3 observations, Bob: 1, Acme Corp: 2; Alice knows Bob, Alice works_at Acme Corp), each call run with --protocol-era legacy (2025-11-25) and --protocol-era modern (2026-07-28), identical results in both:

• Before/after, read_graph {"observationLimit":0}: on v2/main the unknown argument is ignored and every observation comes back; on this branch: {"name":"Alice","entityType":"person","observations":[],"observationCount":3}, Bob 0/1, Acme Corp 0/2, both relations.
• read_graph {"entityTypes":["organization"]} → Acme Corp only, with Alice works_at Acme Corp.
• search_nodes {"query":"acme","limit":1,"observationLimit":1} → Alice only, ["works at Acme Corp"], observationCount: 3, and her two relations.
• open_nodes {"names":["Alice"],"observationLimit":2} → ["works at Acme Corp","likes tea"], observationCount: 3.
• read_graph {} → the full graph, no observationCount (default unchanged).
• search_nodes {"query":"a","limit":0} → isError: true, Input validation error: Invalid arguments for tool search_nodes: limit: Too small: expected number to be >=1.

LLM client: Claude Code 2.1.312 (claude -p --strict-mcp-config, local build, read tools allowed; no era switch, so the era could not be selected):

• "the graph may be large, so without loading every observation, list each entity's name, type and how many observations it has" → read_graph {"observationLimit":0}; answered with a table of names, types and counts (3/1/2), offering open_nodes for detail.
• "list only the organizations, with their relations" → read_graph {"entityTypes":["organization"],"observationLimit":0}; "one organization, Acme Corp, and its only relation is that Alice works_at Acme Corp".

npm run local:gate exits 0.

Breaking Changes

None. Every new input is optional and defaults to the old behavior; observationCount is an optional output field that appears only when observationLimit is passed.

Types of changes

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)
• Documentation update

Checklist

• I have read the MCP Protocol Documentation
• My changes follow MCP security best practices
• I have updated the server's README accordingly
• I have added a changeset (npm run changeset) if this changes what a TypeScript server publishes (minor: .changeset/memory-3953-lightweight-reads.md)
• I have tested this with an LLM client
• My code follows the repository's style guidelines
• New and existing tests pass locally
• I have added appropriate error handling (invalid option values are rejected by the input schema with a validation error naming the field)
• I have documented all environment variables and configuration options (not applicable: no new environment variables; the new tool inputs are in the README)

🤖 Generated with Claude Code

[changeset-bot]

🦋 Changeset detected

Latest commit: 27148ef

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@modelcontextprotocol/server-memory	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[Copilot]

🟢 Approval recommended

No active review issues are recorded for the lightweight memory-read changes.

No open issues 🎉

What changed in this PR

Adds optional lightweight reads to the memory server, addressing #3953 by letting clients retrieve an overview before loading full observations. Existing calls and the knowledge-graph resource retain their behavior.

Changes:

• Adds observation limits and counts to all three read tools, entity-type filtering to read_graph, and a result limit to search_nodes.
• Updates input validation, output schemas, documentation, and read_graph selection guidance.
• Adds protocol-level tests and a minor-release changeset.

File	Description
src/​memory/​README.md	Documents the optional inputs and overview-to-detail usage.
src/​memory/​index.ts	Implements read options, schemas, and tool wiring.
src/​memory/​__tests__/​tools.test.ts	Updates expected tool descriptions and advertised schemas.
src/​memory/​__tests__/​read-options.test.ts	Tests options, validation, defaults, and unchanged resource results.
.changeset/​memory-3953-lightweight-reads.md	Records the feature for a minor package release.

_{Review effort: Balanced}

[cliffhall]

Copilot round 1: clean (no findings, approval recommended). Review loop stops on this first clean round.