[cliffhall]

Closes #5153

Description

create_entities, create_relations and add_observations now declare idempotentHint: true, matching the three delete tools. Each already skips what is stored: an existing entity name, an existing relation, an observation the entity already has. So repeating a call with the same arguments has no additional effect on the graph, which is how the spec defines the hint. A repeat returns [], or skipped / empty addedObservations, rather than the items, and that does not break the hint.

The hint holds across repeated identical calls. It says nothing about duplicates inside a single call. That add_observations keeps a content repeated within one call is #5201, a separate PR. Skipping saveGraph on a no-op repeat (today the file is rewritten with identical content) is out of scope here.

Server Details

• Server: memory
• Changed: the annotations of three tools (idempotentHint false → true). No change to behavior, schemas or descriptions.

Motivation and Context

See #5153. The annotations under-reported what the tools do, so a client could not tell they are safe to repeat. (The spec still tells clients not to make decisions from an untrusted server's annotations alone.)

How Has This Been Tested?

Unit / protocol tests. In src/memory/__tests__/tools.test.ts, the writeAnnotations fixture now expects idempotentHint: true, and the lists the nine tools with their schemas and annotations test pins it. A new test, changes nothing when a write tool is repeated with the same arguments (#5153), runs each of the three write calls twice through an SDK client and checks that the graph after the repeat equals the graph after the first round. npm run local:gate exits 0.

Inspector CLI (@modelcontextprotocol/inspector@2.12.0 --cli node src/memory/dist/index.js -e MEMORY_FILE_PATH=<tmp>), run with both --protocol-era legacy (2025-11-25) and --protocol-era modern (2026-07-28). Both eras gave identical output:

• tools/list → before (v2/main): idempotentHint: false on all three. After:

  {"name":"create_entities","idempotentHint":true}
  {"name":"create_relations","idempotentHint":true}
  {"name":"add_observations","idempotentHint":true}
  

• create_entities with Alice, twice → {"entities":[Alice]}, then {"entities":[],"skipped":["Alice"]}
• add_observations plays chess on Alice, twice → addedObservations:["plays chess"], then addedObservations:[]
• read_graph → Alice with ["likes tea","plays chess"] exactly once each

LLM client (Claude Code claude -p, with only this build's memory server configured). Prompt: "create an entity Alice (person) with observation 'likes tea'. Then add the observation 'plays chess' to Alice. Then perform exactly the same create_entities call and the same add_observations call a second time. Finally read the graph." The model made all five calls. The repeats returned {"entities":[],"skipped":["Alice"]} and {"results":[{"entityName":"Alice","addedObservations":[]}]}, and its summary was: "Both repeated calls changed nothing, so the graph ends up with Alice and exactly two observations." The graph file held one Alice line with the two observations. (Claude Code does not show annotations to the model, so the hint itself comes from the Inspector tools/list above.)

Breaking Changes

None. No client configuration changes.

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 (ToolAnnotations: idempotentHint is defined by repeated calls having no additional effect on the environment)
• My changes follow MCP security best practices
• I have updated the server's README accordingly (not applicable: the README does not state tool annotations)
• I have added a changeset (npm run changeset) if this changes what a TypeScript server publishes (.changeset/memory-5153-idempotent-write-hints.md, patch)
• 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 (not applicable: annotations only, no new code paths)
• I have documented all environment variables and configuration options (not applicable: none added)

Additional context

Part of the memory v2.3.0 tracker #5273.

🤖 Generated with Claude Code

[changeset-bot]

🦋 Changeset detected

Latest commit: a41492e

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	Patch

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]

🟡 Changes recommended

The idempotency test can miss a regression because later repeats may undo earlier changes, and it does not assert that the initial calls succeeded.

1 open issue

• Compare graph state after each repeat and verify initial call success · New

What changed in this PR

This PR addresses #5153 by declaring the memory server’s three additive write tools idempotent, matching their existing behavior without changing schemas or runtime logic.

Changes:

• Sets idempotentHint: true on create_entities, create_relations, and add_observations.
• Updates annotation expectations and adds a protocol-level repeated-call test.
• Adds a patch changeset for the memory package.

File	Description
src/​memory/​index.ts	Enables the idempotency hint on three write tools.
src/​memory/​__tests__/​tools.test.ts	Updates expected annotations and tests repeated calls.
.changeset/​memory-5153-idempotent-write-hints.md	Records the annotation changes for a patch release.

_{Review effort: Balanced}

[cliffhall]

Copilot round 1: one finding, fixed.

• tools.test.ts repeated-call test: one comparison after all three repeats could hide a repeat that changed the graph if a later repeat undid the change. Fixed in a41492e. The initial calls now assert success, and the graph is compared before and after each repeat on its own. Gate green.

Requesting round 2.

[Copilot]

🔵 Needs a closer look

The new idempotent hints are missing from the memory server README, despite the documentation requirement for tool changes.

No open issues 🎉

1 previously missed issue

In code that hasn't changed since last review

Document idempotent hints for graph mutation tools

src/​memory/​index.ts:856

The new client-visible hints are not documented in src/memory/README.md, although AGENTS.md:421–422 requires a server README update when its tools change. Add a short note that create_entities, create_relations, and add_observations now advertise idempotentHint: true because identical repeated calls leave the graph unchanged.

1 resolved since last review

• Compare graph state after each repeat and verify initial call success

_{Review effort: Balanced}

[cliffhall]

Copilot round 2 (on a41492e): no open issues. The round-1 finding is listed as resolved.

• Declined: "Document idempotent hints for graph mutation tools" (previously missed, README; no thread, so answered here). src/memory/README.md documents each tool's inputs and behavior. It states no tool's annotations, the delete tools' idempotentHint: true included, and the behavior these hints describe (an existing entity, relation or observation is skipped) is already documented there. This PR leaves those behaviors alone, so the README is still accurate. Documenting annotations for every tool would be a new README section beyond what memory: create_entities, create_relations and add_observations could declare idempotentHint: true #5153 asks for. The checklist marks the README item "not applicable" for that reason.

That makes the round "out of scope only", so the review loop stops here.