Memory Core MCP tool handbook slice

Context

Release classification: post-release / boardless (MCP context-budget reduction; not a v13 release blocker).

#9953 is the broad MCP progressive-disclosure parent. #13268 / PR #13269 delivered the shared ToolService compact-description + lazy handbook seam and the file-system first slice. #13734 / PR #13735 migrated Knowledge Base, and #13736 / PR #13737 migrated GitHub Workflow.

Fresh measurement on 2026-06-21 shows memory-core is the next remaining primary MCP description surface after GitHub Workflow: 33 tools, about 8,475 always-loaded description characters. The largest operation descriptions are resume_session (883 chars), who_is_online (860 chars), add_memory (505 chars), record_turn_presence (496 chars), and query_recent_turns (465 chars).

Live latest-open sweep: checked the latest 20 open issues on 2026-06-21; no equivalent Memory Core MCP handbook migration leaf found. Exact live search for memory-core "tool handbook" found only the existing Knowledge Base and GitHub Workflow leaves plus broad parent #9953 / parent epic #9950. A2A recency sweep: latest 30 messages had no competing #9953 / memory-core handbook claim.

The Problem

ai/mcp/server/memory-core/openapi.yaml carries detailed operational guidance directly inside MCP operation descriptions. That detail is useful for high-risk Memory Core operations such as session resume validation, live availability projection, final-turn memory writes, and A2A mailbox operations. But today it is projected directly into tools/list, so every client pays the context cost even when it only needs routing-level descriptions.

The shared progressive-disclosure seam already exists. Memory Core should follow the same migration path as the completed File System, Knowledge Base, and GitHub Workflow slices: compact tools/list, keep detailed guidance available through get_mcp_tool_handbook, and preserve operation schemas/annotations/service mapping.

The Architectural Reality

• ai/mcp/ToolService.mjs already supports compactToolDescriptions, toolListDescriptionMaxLength, and getToolHandbook().
• ai/mcp/server/memory-core/toolService.mjs defines a plain serviceMapping for 33 OpenAPI operation ids and instantiates the shared ToolService without compact descriptions today.
• ai/mcp/server/memory-core/openapi.yaml is the Memory Core MCP contract and currently does not expose get_mcp_tool_handbook.
• test/playwright/unit/ai/mcp/server/McpServerListToolsSmoke.spec.mjs verifies cross-server tools/list shape and serviceMapping alignment.
• test/playwright/unit/ai/mcp/validation/OpenApiValidatorCompliance.spec.mjs catches OpenAPI schema regressions across active MCP servers.

The Fix

Migrate Memory Core onto the existing handbook seam:

1. Add get_mcp_tool_handbook to the Memory Core OpenAPI contract and service mapping.
2. Enable compact list descriptions for the Memory Core server with the existing ToolService options.
3. Add short routing summaries for the largest / most frequently loaded Memory Core tool descriptions.
4. Preserve full detailed guidance through lazy-loaded handbook content using existing OpenAPI descriptions or dedicated handbook metadata where needed.
5. Extend focused MCP smoke coverage to prove compact projection, valid handbook lookup, missing handbook lookup, and OpenAPI/serviceMapping compatibility.

Contract Ledger Matrix

Decision Record impact

Aligned with #10757, #13268, #13734, and #13736. No ADR change required.

Acceptance Criteria

• Memory Core MCP exposes get_mcp_tool_handbook through normal MCP tool dispatch.
• Memory Core tools/list emits compact routing descriptions while preserving schemas, annotations, and existing serviceMapping behavior.
• Detailed guidance for at least one high-context Memory Core tool remains available through the lazy-loaded handbook lookup.
• Unknown handbook ids return structured not-found output.
• Focused tests cover list compaction, valid handbook lookup, missing handbook lookup, and OpenAPI/serviceMapping compatibility.

Out of Scope

• Migrating neural-link or gitlab-workflow.
• Closing #9953.
• Changing the shared ToolService API created by #13268.
• Changing Memory Core tool semantics, auth/session behavior, recorder behavior, or A2A mailbox semantics.

Avoided Traps

• Do not add a second handbook mechanism. Reuse ToolService.getToolHandbook().
• Do not weaken any Memory Core write/final-turn semantics while adding the read-only handbook route.
• Do not remove schemas, annotations, or tool names from tools/list; the context win is description compaction only.
• Do not claim the broad #9953 parent is complete from this single server slice.

Related

Parent: #9953

Related: #10757, #13268, #13734, #13736, PR #13269, PR #13735, PR #13737

Origin Session ID: 747ae298-5a6e-4416-b90d-7786e184aa54

Retrieval Hint: Memory Core MCP get_mcp_tool_handbook compact tools/list descriptions #9953 #13268 #13734 #13736