Client-scoped Memory Core session lifecycle

Context

Sub-epic #10691 defines the shared KB/MC team deployment MVP under #9999. A team deployment can run one shared Memory Core MCP server, a pool of MCP server instances, or local harnesses that spawn multiple MCP server processes. All of those shapes must produce the same session semantics.

Today, Memory Core has a process-global currentSessionId initialized at server boot and mutable through set_session_id. That default was acceptable for early local stdio usage, but it is the wrong owner for shared deployments and already causes friction in our local multi-harness reality.

The Problem

A Memory Core session represents a logical agent/harness run, not a Node.js MCP server process. In shared or pooled deployments, a server-process-global session ID can mix unrelated clients or fragment one logical client across server instances.

Symptoms and risks:

• Multiple agents connecting to one shared MCP server can accidentally write into the same process-global session.
• One agent reconnecting through a different MCP server instance can lose or fork its session unless every call passes an explicit sessionId.
• Local harnesses that start multiple MCP server instances already invalidate the assumption that server boot equals session start.
• Summarization cannot safely determine the active session if the active identity lives inside whichever server process happened to boot.

The Architectural Reality

Memory Core already accepts optional sessionId on add_memory, and set_session_id exists as an override primitive. The MVP needs to promote logical session context from optional recovery tool to the standard contract.

The target design should work identically for local stdio and shared remote MCP:

• Session ID is generated or negotiated by the client/harness run.
• The active session context is bound to the request/client context, not global server state.
• Tool calls that write session-owned data resolve the effective session from that context.
• set_session_id becomes a compatibility/resume helper, not global truth in shared mode.

The Fix

Design and implement a client-scoped session lifecycle contract for Memory Core:

1. Define where logical session IDs are generated for each supported transport/harness path.
2. Add request/client context plumbing so add_memory and session-owned write paths resolve the effective session without reading mutable process-global state.
3. Keep backward compatibility for explicit sessionId parameters during migration.
4. Update healthcheck or a dedicated diagnostic surface to show the effective session mode and current request-bound session when available.
5. Update docs for local and shared deployment behavior.

Acceptance Criteria

• Local stdio and remote/shared MCP deployments use the same logical session contract.
• add_memory writes to the client/logical-run session when no explicit sessionId is supplied.
• Multiple simultaneous clients connected to one Memory Core server cannot accidentally share a process-global current session.
• Reconnect/resume behavior is documented and does not require mutating process-global currentSessionId in shared mode.
• Existing sessionId-explicit calls remain backward compatible during migration.
• Tests cover at least two concurrent logical clients writing through the same Memory Core server instance without session collision.

Out of Scope

• Rewriting all MCP servers into thin wrappers around an SDK daemon.
• Final session summarization queue behavior; that is tracked separately under #10691.
• OAuth provider-specific implementation work; identity is already handled by provider-agnostic auth and is only consumed here as context metadata.

Avoided Traps / Gold Standards Rejected

• Rejected: rely on one MCP server process per agent. Remote deployment and current harness behavior both invalidate this.
• Rejected: keep set_session_id as global shared-mode truth. It is useful for compatibility but unsafe as the primary session owner.
• Gold standard retained: explicit provenance. Session records should retain sessionId, userId, and agent identity metadata so team-wide retrieval can attribute memory correctly.

Related

• Parent sub-epic: #10691
• Parent cloud epic: #9999
• Summarization coordinator sibling: to be linked under #10691
• Team/private retrieval: #10010

Origin Session ID: d9cd4943-3285-47a6-b629-c05a9a2a38e4

Retrieval Hint: "Memory Core client scoped session lifecycle currentSessionId shared MCP server"