ai-memory-layer 2.0.1 → 3.0.0

package/dist/server/mcp-server.js

@@ -1,9 +1,52 @@
 import { createMemoryWithAsyncAdapter, } from '../core/quick.js';
+import { createMemoryRuntime } from '../core/runtime.js';
 import { normalizeScope } from '../contracts/identity.js';
+import { isMemoryDomainError } from '../contracts/errors.js';
+import { ASSOCIATION_TARGET_KINDS, ASSOCIATION_TYPES } from '../contracts/types.js';
+import { ACTOR_KINDS, CONTEXT_VIEW_POLICIES, MEMORY_VISIBILITY_CLASSES } from '../contracts/coordination.js';
 import { createSQLiteAdapterWithEmbeddings } from '../adapters/sqlite/index.js';
 import { wrapSyncAdapter } from '../adapters/sync-to-async.js';
+import { parseOptionalFiniteInteger, parseOptionalFiniteNumber, parseOptionalTemporalIdValue, } from './parsing.js';
 class McpValidationError extends Error {
 }
+const MAX_LIST_LIMIT = 100;
+const MANAGER_CACHE_LIMIT = 256;
+const SESSION_MANAGER_CACHE_LIMIT = 256;
+const RUNTIME_CACHE_LIMIT = 256;
+const DEFAULT_DIFF_MAX_EVENTS = 5000;
+const MAX_DIFF_MAX_EVENTS = 20000;
+const TEMPORAL_ENTITY_KINDS = [
+    'turn',
+    'working_memory',
+    'knowledge_memory',
+    'work_item',
+    'association',
+    'playbook',
+    'playbook_revision',
+    'session_state',
+    'work_claim',
+    'handoff',
+];
+function failMcpValidation(message) {
+    throw new McpValidationError(message);
+}
+function resolveDiffEventCaps(defaultMaxEvents, maxMaxEvents) {
+    const resolvedMax = maxMaxEvents ?? MAX_DIFF_MAX_EVENTS;
+    const resolvedDefault = defaultMaxEvents ?? DEFAULT_DIFF_MAX_EVENTS;
+    if (!Number.isInteger(resolvedMax) || resolvedMax < 1) {
+        throw new Error('memory-layer: maxDiffMaxEvents must be a positive integer');
+    }
+    if (!Number.isInteger(resolvedDefault) || resolvedDefault < 1) {
+        throw new Error('memory-layer: defaultDiffMaxEvents must be a positive integer');
+    }
+    if (resolvedDefault > resolvedMax) {
+        throw new Error('memory-layer: defaultDiffMaxEvents must not exceed maxDiffMaxEvents');
+    }
+    return {
+        defaultDiffMaxEvents: resolvedDefault,
+        maxDiffMaxEvents: resolvedMax,
+    };
+}
 const TOOLS = [
     {
         name: 'memory_store_turn',
@@ -37,6 +80,103 @@ const TOOLS = [
             type: 'object',
             properties: {
                 relevanceQuery: { type: 'string', description: 'Optional query to rank knowledge by relevance' },
+                view: {
+                    type: 'string',
+                    enum: ['local_only', 'local_plus_shared_collaboration', 'operator_supervisor', 'workspace_shared'],
+                    description: 'Optional context visibility/view policy',
+                },
+                viewer: { type: 'object', description: 'Optional viewer actor for operator/supervisor coordination views' },
+                includeCoordinationState: { type: 'boolean', description: 'Include coordination state in the response' },
+                includeDebug: { type: 'boolean', description: 'Include selection reasons and debug trace' },
+            },
+        },
+    },
+    {
+        name: 'memory_get_state_at',
+        description: 'Get exact temporal state and assembled context at a specific unix timestamp.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                asOf: { type: 'number', description: 'Unix timestamp to replay at' },
+                relevanceQuery: { type: 'string', description: 'Optional query to rank knowledge' },
+                view: {
+                    type: 'string',
+                    enum: ['local_only', 'local_plus_shared_collaboration', 'operator_supervisor', 'workspace_shared'],
+                    description: 'Optional context visibility/view policy',
+                },
+                viewer: { type: 'object', description: 'Optional viewer actor for operator/supervisor coordination views' },
+                includeCoordinationState: { type: 'boolean', description: 'Include coordination state in the response' },
+                includeDebug: { type: 'boolean', description: 'Include debug traces in the context payload' },
+            },
+            required: ['asOf'],
+        },
+    },
+    {
+        name: 'memory_get_timeline',
+        description: 'List memory events in chronological order.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                sessionId: { type: 'string', description: 'Optional session filter' },
+                entityKind: {
+                    type: 'string',
+                    enum: [...TEMPORAL_ENTITY_KINDS],
+                    description: 'Optional entity kind filter',
+                },
+                entityId: { type: 'string', description: 'Optional entity id filter' },
+                startAt: { type: 'number', description: 'Optional start unix timestamp' },
+                endAt: { type: 'number', description: 'Optional end unix timestamp' },
+                limit: { type: 'number', description: 'Optional page size' },
+                cursor: {
+                    anyOf: [{ type: 'number' }, { type: 'string' }],
+                    description: 'Optional event-id cursor',
+                },
+            },
+        },
+    },
+    {
+        name: 'memory_diff_state',
+        description: 'Summarize memory events between two unix timestamps.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                from: { type: 'number', description: 'Start unix timestamp (exclusive)' },
+                to: { type: 'number', description: 'End unix timestamp (inclusive)' },
+                sessionId: { type: 'string', description: 'Optional session filter' },
+                entityKind: {
+                    type: 'string',
+                    enum: [...TEMPORAL_ENTITY_KINDS],
+                    description: 'Optional entity kind filter',
+                },
+                entityId: { type: 'string', description: 'Optional entity id filter' },
+                maxEvents: {
+                    type: 'number',
+                    description: 'Optional maximum event count to accumulate. Defaults to the server-configured diff cap and must not exceed the configured maximum.',
+                },
+            },
+            required: ['from', 'to'],
+        },
+    },
+    {
+        name: 'memory_list_events',
+        description: 'List memory events in reverse chronological order for inspection.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                sessionId: { type: 'string', description: 'Optional session filter' },
+                entityKind: {
+                    type: 'string',
+                    enum: [...TEMPORAL_ENTITY_KINDS],
+                    description: 'Optional entity kind filter',
+                },
+                entityId: { type: 'string', description: 'Optional entity id filter' },
+                startAt: { type: 'number', description: 'Optional start unix timestamp' },
+                endAt: { type: 'number', description: 'Optional end unix timestamp' },
+                limit: { type: 'number', description: 'Optional page size' },
+                cursor: {
+                    anyOf: [{ type: 'number' }, { type: 'string' }],
+                    description: 'Optional event-id cursor',
+                },
             },
         },
     },
@@ -104,6 +244,148 @@ const TOOLS = [
             required: ['title'],
         },
     },
+    {
+        name: 'memory_update_work_item',
+        description: 'Update an existing work item.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                id: { type: 'number' },
+                title: { type: 'string' },
+                detail: { type: 'string' },
+                status: { type: 'string', enum: ['open', 'in_progress', 'blocked', 'done'] },
+                visibility_class: { type: 'string', enum: ['private', 'shared_collaboration', 'workspace', 'tenant'] },
+                expectedVersion: { type: 'number' },
+            },
+            required: ['id'],
+        },
+    },
+    {
+        name: 'memory_claim_work_item',
+        description: 'Acquire or renew an exclusive claim on a work item.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                workItemId: { type: 'number' },
+                actor: { type: 'object' },
+                leaseSeconds: { type: 'number' },
+            },
+            required: ['workItemId', 'actor'],
+        },
+    },
+    {
+        name: 'memory_renew_work_claim',
+        description: 'Renew an exclusive claim on a work item.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                claimId: { type: 'number' },
+                actor: { type: 'object' },
+                leaseSeconds: { type: 'number' },
+            },
+            required: ['claimId', 'actor'],
+        },
+    },
+    {
+        name: 'memory_release_work_claim',
+        description: 'Release a claimed work item.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                claimId: { type: 'number' },
+                actor: { type: 'object' },
+                reason: { type: 'string' },
+            },
+            required: ['claimId', 'actor'],
+        },
+    },
+    {
+        name: 'memory_list_work_claims',
+        description: 'List current work claims.',
+        inputSchema: {
+            type: 'object',
+            properties: {},
+        },
+    },
+    {
+        name: 'memory_handoff_work_item',
+        description: 'Create a handoff for a work item.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                workItemId: { type: 'number' },
+                fromActor: { type: 'object' },
+                toActor: { type: 'object' },
+                summary: { type: 'string' },
+                contextBundleRef: { type: 'string' },
+                expiresAt: { type: 'number' },
+            },
+            required: ['workItemId', 'fromActor', 'toActor', 'summary'],
+        },
+    },
+    {
+        name: 'memory_accept_handoff',
+        description: 'Accept a handoff.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                handoffId: { type: 'number' },
+                actor: { type: 'object' },
+                reason: { type: 'string' },
+            },
+            required: ['handoffId', 'actor'],
+        },
+    },
+    {
+        name: 'memory_reject_handoff',
+        description: 'Reject a handoff.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                handoffId: { type: 'number' },
+                actor: { type: 'object' },
+                reason: { type: 'string' },
+            },
+            required: ['handoffId', 'actor'],
+        },
+    },
+    {
+        name: 'memory_cancel_handoff',
+        description: 'Cancel a handoff.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                handoffId: { type: 'number' },
+                actor: { type: 'object' },
+                reason: { type: 'string' },
+            },
+            required: ['handoffId', 'actor'],
+        },
+    },
+    {
+        name: 'memory_list_pending_handoffs',
+        description: 'List pending handoffs.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                direction: { type: 'string', enum: ['inbound', 'outbound', 'all'] },
+            },
+        },
+    },
+    {
+        name: 'memory_stream_changes',
+        description: 'List durable change events after an optional cursor.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                cursor: { anyOf: [{ type: 'number' }, { type: 'string' }] },
+                sessionId: { type: 'string' },
+                entityKind: { type: 'string', enum: [...TEMPORAL_ENTITY_KINDS] },
+                entityId: { type: 'string' },
+                limit: { type: 'number' },
+            },
+        },
+    },
     {
         name: 'memory_force_compact',
         description: 'Force compaction of conversation history into a summary.',
@@ -128,12 +410,403 @@ const TOOLS = [
             properties: {},
         },
     },
+    {
+        name: 'memory_search_episodes',
+        description: 'Search episodic memory for past sessions matching a query. Returns structured recaps with objectives, actions, outcomes, and unresolved items.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                query: { type: 'string', description: 'Search query' },
+                detailLevel: {
+                    type: 'string',
+                    enum: ['abstract', 'overview', 'full'],
+                    description: 'Detail level for results (default: overview)',
+                },
+                limit: { type: 'number', description: 'Max results (default: 10)' },
+                timeRange: {
+                    type: 'object',
+                    properties: {
+                        start_at: { type: 'number', description: 'Unix timestamp lower bound' },
+                        end_at: { type: 'number', description: 'Unix timestamp upper bound' },
+                    },
+                    description: 'Optional time range filter',
+                },
+            },
+            required: ['query'],
+        },
+    },
+    {
+        name: 'memory_summarize_episode',
+        description: 'Summarize a specific session into a structured episodic recap.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                sessionId: { type: 'string', description: 'Session ID to summarize' },
+                detailLevel: {
+                    type: 'string',
+                    enum: ['abstract', 'overview', 'full'],
+                    description: 'Detail level (default: overview)',
+                },
+            },
+            required: ['sessionId'],
+        },
+    },
+    {
+        name: 'memory_reflect',
+        description: 'Synthesize an answer from episodic and declarative memory. Returns a coherent synthesis with source attribution.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                query: { type: 'string', description: 'Reflection query' },
+                detailLevel: {
+                    type: 'string',
+                    enum: ['abstract', 'overview', 'full'],
+                    description: 'Detail level (default: overview)',
+                },
+                includeEpisodic: { type: 'boolean', description: 'Include episodic memory (default: true)' },
+                includeDeclarative: { type: 'boolean', description: 'Include declarative memory (default: true)' },
+                limit: { type: 'number', description: 'Max sources (default: 10)' },
+                timeRange: {
+                    type: 'object',
+                    properties: {
+                        start_at: { type: 'number', description: 'Unix timestamp lower bound' },
+                        end_at: { type: 'number', description: 'Unix timestamp upper bound' },
+                    },
+                    description: 'Optional time range filter',
+                },
+            },
+            required: ['query'],
+        },
+    },
+    {
+        name: 'memory_search_cognitive',
+        description: 'Search memory using the cognitive taxonomy (episodic, semantic, procedural, working). Returns results grouped by cognitive type.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                query: { type: 'string', description: 'Search query' },
+                types: {
+                    type: 'array',
+                    items: { type: 'string', enum: ['episodic', 'semantic', 'procedural', 'working'] },
+                    description: 'Cognitive memory types to search (default: all)',
+                },
+                limit: { type: 'number', description: 'Max results (default: 10)' },
+                minimumTrustScore: { type: 'number', description: 'Minimum trust score filter' },
+                activeOnly: { type: 'boolean', description: 'Only return active memories (default: true)' },
+            },
+            required: ['query'],
+        },
+    },
+    {
+        name: 'memory_get_profile',
+        description: 'Get a materialized profile view built from trusted knowledge. Returns identity, preferences, communication, constraints, and workflows.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                view: {
+                    type: 'string',
+                    enum: ['user', 'operator', 'workspace'],
+                    description: 'Profile view type (default: user)',
+                },
+                sections: {
+                    type: 'array',
+                    items: { type: 'string', enum: ['identity', 'preferences', 'communication', 'constraints', 'workflows'] },
+                    description: 'Specific sections to include (default: all)',
+                },
+                minimumTrustScore: { type: 'number', description: 'Minimum trust score filter' },
+                includeProvisional: { type: 'boolean', description: 'Include provisional knowledge entries (default: false — profiles are trusted-only)' },
+                includeDisputed: { type: 'boolean', description: 'Include disputed knowledge entries (default: false)' },
+            },
+        },
+    },
+    {
+        name: 'memory_create_playbook',
+        description: 'Create a reusable playbook from a title, description, and instructions.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                title: { type: 'string', description: 'Playbook title' },
+                description: { type: 'string', description: 'What this playbook is for' },
+                instructions: { type: 'string', description: 'Step-by-step instructions' },
+                references: { type: 'array', items: { type: 'string' }, description: 'Referenced files, URLs, or tools' },
+                templates: { type: 'array', items: { type: 'string' }, description: 'Reusable templates or patterns' },
+                scripts: { type: 'array', items: { type: 'string' }, description: 'Commands or scripts' },
+                assets: { type: 'array', items: { type: 'string' }, description: 'Associated assets' },
+                tags: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    description: 'Optional tags for categorization',
+                },
+                status: {
+                    type: 'string',
+                    enum: ['draft', 'active', 'deprecated', 'archived'],
+                    description: 'Playbook status (default: draft)',
+                },
+            },
+            required: ['title', 'description', 'instructions'],
+        },
+    },
+    {
+        name: 'memory_search_playbooks',
+        description: 'Search for relevant playbooks by query. Returns ranked results.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                query: { type: 'string', description: 'Search query' },
+                limit: { type: 'number', description: 'Max results (default: 20)' },
+            },
+            required: ['query'],
+        },
+    },
+    {
+        name: 'memory_revise_playbook',
+        description: 'Revise a playbook by storing the current instructions as a revision and updating with new instructions.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                playbookId: { type: 'number', description: 'ID of the playbook to revise' },
+                newInstructions: { type: 'string', description: 'Updated instructions' },
+                revisionReason: { type: 'string', description: 'Why the playbook is being revised' },
+                sourceSessionId: { type: 'string', description: 'Optional session ID that triggered the revision' },
+            },
+            required: ['playbookId', 'newInstructions', 'revisionReason'],
+        },
+    },
+    {
+        name: 'memory_create_playbook_from_task',
+        description: 'Create a playbook by summarizing the turns of a completed task session into structured instructions.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                title: { type: 'string', description: 'Playbook title' },
+                description: { type: 'string', description: 'What this playbook is for' },
+                sessionId: { type: 'string', description: 'Session to derive the playbook from' },
+                tags: { type: 'array', items: { type: 'string' }, description: 'Optional tags' },
+                sourceWorkingMemoryId: {
+                    type: 'number',
+                    description: 'Optional working memory id that anchors the source task',
+                },
+            },
+            required: ['title', 'description', 'sessionId'],
+        },
+    },
+    {
+        name: 'memory_use_playbook',
+        description: 'Record that a playbook was used and return the full playbook record.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                playbookId: { type: 'number', description: 'ID of the playbook that was used' },
+            },
+            required: ['playbookId'],
+        },
+    },
+    {
+        name: 'memory_get_associations',
+        description: 'Get or traverse associations for a memory artifact. Use traverse mode for multi-hop graph expansion.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                kind: { type: 'string', enum: ['knowledge', 'playbook', 'working_memory', 'work_item'], description: 'Type of the source artifact' },
+                id: { type: 'number', description: 'ID of the source artifact' },
+                traverse: { type: 'boolean', description: 'If true, perform BFS traversal instead of direct lookup' },
+                maxDepth: { type: 'number', description: 'Max traversal depth (default 2, only used with traverse)' },
+                maxNodes: { type: 'number', description: 'Max nodes to return (default 20, only used with traverse)' },
+            },
+            required: ['kind', 'id'],
+        },
+    },
+    {
+        name: 'memory_add_association',
+        description: 'Create an association between two memory artifacts.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                source_kind: { type: 'string', enum: ['knowledge', 'playbook', 'working_memory', 'work_item'] },
+                source_id: { type: 'number' },
+                target_kind: { type: 'string', enum: ['knowledge', 'playbook', 'working_memory', 'work_item'] },
+                target_id: { type: 'number' },
+                association_type: { type: 'string', enum: ['related_to', 'supports', 'contradicts', 'supersedes', 'depends_on', 'solves', 'applies_to', 'derived_from'] },
+                confidence: { type: 'number', description: 'Confidence score 0-1 (default 0.5)' },
+            },
+            required: ['source_kind', 'source_id', 'target_kind', 'target_id', 'association_type'],
+        },
+    },
+    {
+        name: 'memory_remove_association',
+        description: 'Delete an association by ID.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                id: { type: 'number', description: 'Association ID to delete' },
+            },
+            required: ['id'],
+        },
+    },
+    {
+        name: 'memory_snapshot',
+        description: 'Manage session snapshots for cache-stable prompt injection. Actions: capture (freeze current state), refresh (recapture), get (return cached snapshot or null).',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                action: {
+                    type: 'string',
+                    enum: ['capture', 'refresh', 'get'],
+                    description: 'Snapshot action to perform',
+                },
+                sessionId: {
+                    type: 'string',
+                    description: 'Session ID the snapshot belongs to',
+                },
+                relevanceQuery: {
+                    type: 'string',
+                    description: 'Optional query to rank knowledge during capture/refresh',
+                },
+            },
+            required: ['action', 'sessionId'],
+        },
+    },
 ];
 function jsonResult(data) {
     return {
         content: [{ type: 'text', text: JSON.stringify(data, null, 2) }],
     };
 }
+function serializeContextResponse(context, options = {}) {
+    return {
+        currentObjective: context.currentObjective,
+        sessionState: context.sessionState,
+        activeTurnCount: context.activeTurns.length,
+        workingMemory: context.workingMemory
+            ? {
+                summary: context.workingMemory.summary,
+                key_entities: context.workingMemory.key_entities,
+                topic_tags: context.workingMemory.topic_tags,
+            }
+            : null,
+        relevantKnowledge: context.relevantKnowledge.map((knowledge) => ({
+            id: knowledge.id,
+            fact: knowledge.fact,
+            fact_type: knowledge.fact_type,
+            confidence: knowledge.confidence,
+        })),
+        activeObjectives: context.activeObjectives.map((objective) => ({
+            id: objective.id,
+            title: objective.title,
+            status: objective.status,
+            visibility_class: objective.visibility_class,
+        })),
+        associatedKnowledge: context.associatedKnowledge.map((knowledge) => ({
+            id: knowledge.id,
+            fact: knowledge.fact,
+            fact_type: knowledge.fact_type,
+            knowledge_class: knowledge.knowledge_class,
+            trust_score: knowledge.trust_score,
+        })),
+        unresolvedWork: context.unresolvedWork,
+        coordinationState: context.coordinationState
+            ? {
+                ownedClaims: context.coordinationState.ownedClaims.map(serializeWorkClaim),
+                pendingInboundHandoffs: context.coordinationState.pendingInboundHandoffs.map(serializeHandoffRecord),
+                pendingOutboundHandoffs: context.coordinationState.pendingOutboundHandoffs.map(serializeHandoffRecord),
+                sharedWorkItems: context.coordinationState.sharedWorkItems.map((item) => ({
+                    id: item.id,
+                    title: item.title,
+                    status: item.status,
+                    visibility_class: item.visibility_class,
+                })),
+            }
+            : null,
+        tokenEstimate: context.tokenEstimate,
+        ...(options.includeDebug
+            ? {
+                debugTrace: context.debugTrace,
+                knowledgeSelectionReasons: context.knowledgeSelectionReasons,
+            }
+            : {}),
+    };
+}
+function serializeActorRef(actor) {
+    return {
+        actor_kind: actor.actor_kind,
+        actor_id: actor.actor_id,
+        system_id: actor.system_id,
+        display_name: actor.display_name,
+        metadata: actor.metadata,
+    };
+}
+function serializeWorkClaim(claim) {
+    return {
+        id: claim.id,
+        work_item_id: claim.work_item_id,
+        actor: serializeActorRef(claim.actor),
+        session_id: claim.session_id,
+        claim_token: claim.claim_token,
+        status: claim.status,
+        claimed_at: claim.claimed_at,
+        expires_at: claim.expires_at,
+        released_at: claim.released_at,
+        release_reason: claim.release_reason,
+        source_event_id: claim.source_event_id,
+        visibility_class: claim.visibility_class,
+        version: claim.version,
+    };
+}
+function serializeHandoffRecord(handoff) {
+    return {
+        id: handoff.id,
+        work_item_id: handoff.work_item_id,
+        from_actor: serializeActorRef(handoff.from_actor),
+        to_actor: serializeActorRef(handoff.to_actor),
+        session_id: handoff.session_id,
+        summary: handoff.summary,
+        context_bundle_ref: handoff.context_bundle_ref,
+        status: handoff.status,
+        created_at: handoff.created_at,
+        accepted_at: handoff.accepted_at,
+        rejected_at: handoff.rejected_at,
+        canceled_at: handoff.canceled_at,
+        expires_at: handoff.expires_at,
+        decision_reason: handoff.decision_reason,
+        source_event_id: handoff.source_event_id,
+        visibility_class: handoff.visibility_class,
+        version: handoff.version,
+    };
+}
+function serializeTimelineResult(result) {
+    return {
+        events: result.events,
+        nextCursor: result.nextCursor,
+    };
+}
+function serializeTemporalState(state, options = {}) {
+    return {
+        asOf: state.asOf,
+        exact: state.exact,
+        cutoverAt: state.cutoverAt,
+        watermarkEventId: state.watermarkEventId,
+        context: serializeContextResponse(state.context, {
+            includeDebug: options.includeDebug,
+        }),
+        sessionState: state.sessionState,
+        turns: state.turns,
+        workingMemory: state.workingMemory,
+        knowledge: state.knowledge,
+        workItems: state.workItems,
+        workClaims: state.workClaims.map(serializeWorkClaim),
+        handoffs: state.handoffs.map(serializeHandoffRecord),
+        coordinationState: state.coordinationState
+            ? {
+                ownedClaims: state.coordinationState.ownedClaims.map(serializeWorkClaim),
+                pendingInboundHandoffs: state.coordinationState.pendingInboundHandoffs.map(serializeHandoffRecord),
+                pendingOutboundHandoffs: state.coordinationState.pendingOutboundHandoffs.map(serializeHandoffRecord),
+                sharedWorkItems: state.coordinationState.sharedWorkItems,
+            }
+            : null,
+        associations: state.associations,
+        playbooks: state.playbooks,
+    };
+}
 function errorResult(message) {
     return {
         content: [{ type: 'text', text: message }],
@@ -157,6 +830,25 @@ function optionalString(value, name) {
     }
     return value;
 }
+function parseContextViewPolicy(value, name = 'view') {
+    if (value == null)
+        return undefined;
+    return requireEnum(value, CONTEXT_VIEW_POLICIES, name);
+}
+function parseActorRef(value, name = 'actor') {
+    if (value == null)
+        return undefined;
+    if (!isRecord(value)) {
+        throw new McpValidationError(`Invalid field: ${name}`);
+    }
+    return {
+        actor_kind: requireEnum(value.actor_kind, ACTOR_KINDS, `${name}.actor_kind`),
+        actor_id: requireString(value.actor_id, `${name}.actor_id`),
+        system_id: value.system_id == null ? null : requireString(value.system_id, `${name}.system_id`),
+        display_name: value.display_name == null ? null : requireString(value.display_name, `${name}.display_name`),
+        metadata: isRecord(value.metadata) ? value.metadata : null,
+    };
+}
 function requireEnum(value, allowed, name) {
     if (typeof value !== 'string' || !allowed.includes(value)) {
         throw new McpValidationError(`Invalid field: ${name}`);
@@ -169,8 +861,29 @@ function parseLimit(value) {
     if (typeof value !== 'number' || !Number.isInteger(value)) {
         throw new McpValidationError('Invalid field: limit');
     }
+    if (value > MAX_LIST_LIMIT) {
+        throw new McpValidationError(`Invalid field: limit (maximum ${MAX_LIST_LIMIT})`);
+    }
     return value;
 }
+function parseOptionalNonNegativeInteger(value, name) {
+    if (value === undefined || value === null)
+        return undefined;
+    if (typeof value !== 'number' || !Number.isInteger(value) || value < 0) {
+        throw new McpValidationError(`Invalid field: ${name} (must be a non-negative integer)`);
+    }
+    return value;
+}
+function parseRequiredFiniteInteger(value, name, options = {}) {
+    const parsed = parseOptionalFiniteInteger(value, { name, ...options }, failMcpValidation);
+    if (parsed == null) {
+        throw new McpValidationError(`Missing or invalid field: ${name}`);
+    }
+    return parsed;
+}
+function parseOptionalTemporalId(value, name) {
+    return parseOptionalTemporalIdValue(value, name, failMcpValidation);
+}
 function resolveScopeInput(fallbackScope, args) {
     if (args.scope) {
         if (!isRecord(args.scope)) {
@@ -190,8 +903,24 @@ function resolveScopeInput(fallbackScope, args) {
  * For a ready-to-run stdio server, use `startMcpServer()`.
  */
 export function createMcpServerHandler(config = {}) {
+    const { defaultDiffMaxEvents, maxDiffMaxEvents } = resolveDiffEventCaps(config.defaultDiffMaxEvents, config.maxDiffMaxEvents);
     const managers = new Map();
+    const runtimes = new Map();
+    const sessionManagers = new Map();
+    const sessionRuntimes = new Map();
     let adapterPromise = null;
+    function touchCache(cache, key, value, limit, onEvict) {
+        cache.delete(key);
+        cache.set(key, value);
+        while (cache.size > limit) {
+            const oldestEntry = cache.entries().next().value;
+            if (!oldestEntry)
+                break;
+            const [oldestKey, oldestValue] = oldestEntry;
+            cache.delete(oldestKey);
+            onEvict?.(oldestKey, oldestValue);
+        }
+    }
     async function getAsyncAdapter() {
         if (!adapterPromise) {
             adapterPromise = (async () => {
@@ -200,6 +929,9 @@ export function createMcpServerHandler(config = {}) {
                     return {
                         asyncAdapter: wrapSyncAdapter(sqlite),
                         embeddingAdapter: sqlite.embeddings,
+                        close: async () => {
+                            sqlite.close();
+                        },
                     };
                 }
                 const moduleName = 'pg';
@@ -211,10 +943,13 @@ export function createMcpServerHandler(config = {}) {
                 const pool = new Pool({
                     connectionString: config.databaseUrl ?? process.env.MEMORY_DATABASE_URL,
                 });
-                const asyncAdapter = createPostgresAdapter(pool);
+                const asyncAdapter = createPostgresAdapter(pool, { ownsPool: false });
                 return {
                     asyncAdapter,
                     embeddingAdapter: createPostgresEmbeddingAdapter(pool),
+                    close: async () => {
+                        await pool.end();
+                    },
                 };
             })();
         }
@@ -225,11 +960,11 @@ export function createMcpServerHandler(config = {}) {
             ? `scope:${scopeInput}`
             : JSON.stringify(normalizeScope(scopeInput));
         const existing = managers.get(key);
-        if (existing)
+        if (existing) {
+            touchCache(managers, key, existing, MANAGER_CACHE_LIMIT);
             return existing;
+        }
         const baseOptions = {
-            adapter: 'sqlite',
-            path: config.dbPath ?? ':memory:',
             scope: scopeInput,
             summarizer: config.summarizer ?? 'extractive',
             extractor: config.extractor ?? 'regex',
@@ -237,17 +972,80 @@ export function createMcpServerHandler(config = {}) {
             qualityMode: config.qualityMode,
             qualityTier: config.qualityTier,
             crossScopeLevel: config.crossScopeLevel,
+            autoDetectWorkspace: config.autoDetectWorkspace,
+            structuredClient: config.structuredClient,
         };
         const adapterContext = await getAsyncAdapter();
         const manager = createMemoryWithAsyncAdapter({
             ...baseOptions,
             asyncAdapter: adapterContext.asyncAdapter,
             embeddingAdapter: adapterContext.embeddingAdapter,
+            closeAdapter: false,
+        });
+        touchCache(managers, key, manager, MANAGER_CACHE_LIMIT, (evictedKey) => {
+            runtimes.delete(evictedKey);
         });
-        managers.set(key, manager);
         return manager;
     }
-    const managerPromise = getManager(config.scope ?? 'default');
+    async function getRuntime(scopeInput) {
+        const key = typeof scopeInput === 'string'
+            ? `scope:${scopeInput}`
+            : JSON.stringify(normalizeScope(scopeInput));
+        const existing = runtimes.get(key);
+        if (existing) {
+            runtimes.delete(key);
+            runtimes.set(key, existing);
+            return existing;
+        }
+        const manager = await getManager(scopeInput);
+        const runtime = createMemoryRuntime(manager, { snapshotMode: true });
+        touchCache(runtimes, key, runtime, RUNTIME_CACHE_LIMIT);
+        return runtime;
+    }
+    /**
+     * Snapshot-specific runtime keyed by (scope, sessionId). The plain
+     * getRuntime/getManager pair binds each scope to a single session, which
+     * collapses snapshots across multiple URL-named sessions. Snapshot actions
+     * must route to a manager whose bound sessionId matches the caller.
+     */
+    async function getSessionRuntime(scopeInput, sessionId) {
+        const scopeKey = typeof scopeInput === 'string'
+            ? `scope:${scopeInput}`
+            : JSON.stringify(normalizeScope(scopeInput));
+        const key = `${scopeKey}|session:${sessionId}`;
+        const existing = sessionRuntimes.get(key);
+        if (existing) {
+            sessionRuntimes.delete(key);
+            sessionRuntimes.set(key, existing);
+            return existing;
+        }
+        const baseOptions = {
+            scope: scopeInput,
+            sessionId,
+            summarizer: config.summarizer ?? 'extractive',
+            extractor: config.extractor ?? 'regex',
+            preset: config.preset,
+            qualityMode: config.qualityMode,
+            qualityTier: config.qualityTier,
+            crossScopeLevel: config.crossScopeLevel,
+            autoDetectWorkspace: config.autoDetectWorkspace,
+            structuredClient: config.structuredClient,
+        };
+        const adapterContext = await getAsyncAdapter();
+        const manager = createMemoryWithAsyncAdapter({
+            ...baseOptions,
+            asyncAdapter: adapterContext.asyncAdapter,
+            embeddingAdapter: adapterContext.embeddingAdapter,
+            closeAdapter: false,
+        });
+        touchCache(sessionManagers, key, manager, SESSION_MANAGER_CACHE_LIMIT, (evictedKey, evictedManager) => {
+            sessionRuntimes.delete(evictedKey);
+            void evictedManager.close().catch(() => undefined);
+        });
+        const runtime = createMemoryRuntime(manager, { snapshotMode: true });
+        touchCache(sessionRuntimes, key, runtime, RUNTIME_CACHE_LIMIT);
+        return runtime;
+    }
     async function callTool(name, args) {
         try {
             const requestManager = await getManager(resolveScopeInput(config.scope, args));
@@ -266,30 +1064,68 @@ export function createMcpServerHandler(config = {}) {
                     });
                 }
                 case 'memory_get_context': {
-                    const context = await requestManager.getContext(args.relevanceQuery ? String(args.relevanceQuery) : undefined);
-                    return jsonResult({
-                        currentObjective: context.currentObjective,
-                        activeTurnCount: context.activeTurns.length,
-                        workingMemory: context.workingMemory
-                            ? {
-                                summary: context.workingMemory.summary,
-                                key_entities: context.workingMemory.key_entities,
-                                topic_tags: context.workingMemory.topic_tags,
-                            }
-                            : null,
-                        relevantKnowledge: context.relevantKnowledge.map((k) => ({
-                            id: k.id,
-                            fact: k.fact,
-                            fact_type: k.fact_type,
-                            confidence: k.confidence,
-                        })),
-                        activeObjectives: context.activeObjectives.map((o) => ({
-                            title: o.title,
-                            status: o.status,
-                        })),
-                        unresolvedWork: context.unresolvedWork,
-                        tokenEstimate: context.tokenEstimate,
+                    const context = await requestManager.getContext(args.relevanceQuery ? String(args.relevanceQuery) : undefined, {
+                        view: parseContextViewPolicy(args.view),
+                        viewer: parseActorRef(args.viewer, 'viewer'),
+                        includeCoordinationState: args.includeCoordinationState === true,
+                    });
+                    return jsonResult(serializeContextResponse(context, {
+                        includeDebug: args.includeDebug === true,
+                    }));
+                }
+                case 'memory_get_state_at': {
+                    const asOf = parseOptionalFiniteNumber(args.asOf, { name: 'asOf' }, failMcpValidation);
+                    if (asOf == null) {
+                        throw new McpValidationError('Missing or invalid field: asOf');
+                    }
+                    const state = await requestManager.getStateAt(asOf, {
+                        relevanceQuery: optionalString(args.relevanceQuery, 'relevanceQuery'),
+                        view: parseContextViewPolicy(args.view),
+                        viewer: parseActorRef(args.viewer, 'viewer'),
+                        includeCoordinationState: args.includeCoordinationState === true,
+                    });
+                    return jsonResult(serializeTemporalState(state, {
+                        includeDebug: args.includeDebug === true,
+                    }));
+                }
+                case 'memory_get_timeline': {
+                    const timeline = await requestManager.getTimeline({
+                        sessionId: optionalString(args.sessionId, 'sessionId'),
+                        entityKind: args.entityKind,
+                        entityId: optionalString(args.entityId, 'entityId'),
+                        startAt: parseOptionalFiniteNumber(args.startAt, { name: 'startAt' }, failMcpValidation),
+                        endAt: parseOptionalFiniteNumber(args.endAt, { name: 'endAt' }, failMcpValidation),
+                        limit: parseLimit(args.limit),
+                        cursor: parseOptionalTemporalId(args.cursor, 'cursor'),
+                    });
+                    return jsonResult(serializeTimelineResult(timeline));
+                }
+                case 'memory_diff_state': {
+                    const from = parseOptionalFiniteNumber(args.from, { name: 'from' }, failMcpValidation);
+                    const to = parseOptionalFiniteNumber(args.to, { name: 'to' }, failMcpValidation);
+                    const maxEvents = parseOptionalFiniteInteger(args.maxEvents, { name: 'maxEvents', min: 1, max: maxDiffMaxEvents }, failMcpValidation);
+                    if (from == null || to == null) {
+                        throw new McpValidationError('Missing or invalid fields: from/to');
+                    }
+                    const diff = await requestManager.diffState(from, to, {
+                        sessionId: optionalString(args.sessionId, 'sessionId'),
+                        entityKind: args.entityKind,
+                        entityId: optionalString(args.entityId, 'entityId'),
+                        maxEvents: maxEvents ?? defaultDiffMaxEvents,
                     });
+                    return jsonResult(diff);
+                }
+                case 'memory_list_events': {
+                    const events = await requestManager.listMemoryEvents({
+                        sessionId: optionalString(args.sessionId, 'sessionId'),
+                        entityKind: args.entityKind,
+                        entityId: optionalString(args.entityId, 'entityId'),
+                        startAt: parseOptionalFiniteNumber(args.startAt, { name: 'startAt' }, failMcpValidation),
+                        endAt: parseOptionalFiniteNumber(args.endAt, { name: 'endAt' }, failMcpValidation),
+                        limit: parseLimit(args.limit),
+                        cursor: parseOptionalTemporalId(args.cursor, 'cursor'),
+                    });
+                    return jsonResult(serializeTimelineResult(events));
                 }
                 case 'memory_search': {
                     const results = await requestManager.search(requireString(args.query, 'query'), args.limit != null ? { limit: parseLimit(args.limit) } : undefined);
@@ -330,9 +1166,112 @@ export function createMcpServerHandler(config = {}) {
                     return jsonResult({ stored: true, knowledgeId: fact.id });
                 }
                 case 'memory_track_work': {
-                    const item = await requestManager.trackWorkItem(requireString(args.title, 'title'), requireEnum(args.kind ?? 'objective', ['objective', 'unresolved_work', 'constraint'], 'kind'), requireEnum(args.status ?? 'open', ['open', 'in_progress', 'blocked', 'done'], 'status'), optionalString(args.detail, 'detail'));
+                    const item = await requestManager.trackWorkItem(requireString(args.title, 'title'), requireEnum(args.kind ?? 'objective', ['objective', 'unresolved_work', 'constraint'], 'kind'), requireEnum(args.status ?? 'open', ['open', 'in_progress', 'blocked', 'done'], 'status'), optionalString(args.detail, 'detail'), {
+                        visibilityClass: args.visibility_class == null
+                            ? undefined
+                            : requireEnum(args.visibility_class, MEMORY_VISIBILITY_CLASSES, 'visibility_class'),
+                    });
                     return jsonResult({ tracked: true, workItemId: item.id });
                 }
+                case 'memory_update_work_item': {
+                    const item = await requestManager.updateWorkItem(parseRequiredFiniteInteger(args.id, 'id', { min: 1 }), {
+                        title: args.title != null ? requireString(args.title, 'title') : undefined,
+                        detail: args.detail != null ? optionalString(args.detail, 'detail') ?? null : undefined,
+                        status: args.status != null
+                            ? requireEnum(args.status, ['open', 'in_progress', 'blocked', 'done'], 'status')
+                            : undefined,
+                        visibility_class: args.visibility_class != null
+                            ? requireEnum(args.visibility_class, MEMORY_VISIBILITY_CLASSES, 'visibility_class')
+                            : undefined,
+                    }, {
+                        expectedVersion: parseOptionalFiniteInteger(args.expectedVersion, { name: 'expectedVersion', min: 0 }, failMcpValidation),
+                    });
+                    return jsonResult({ workItem: item });
+                }
+                case 'memory_claim_work_item': {
+                    const actor = parseActorRef(args.actor, 'actor');
+                    if (!actor)
+                        throw new McpValidationError('Missing or invalid field: actor');
+                    const claim = await requestManager.claimWorkItem({
+                        workItemId: parseRequiredFiniteInteger(args.workItemId, 'workItemId', { min: 1 }),
+                        actor,
+                        leaseSeconds: parseOptionalFiniteInteger(args.leaseSeconds, { name: 'leaseSeconds', min: 1 }, failMcpValidation),
+                    });
+                    return jsonResult({ claim: serializeWorkClaim(claim) });
+                }
+                case 'memory_renew_work_claim': {
+                    const actor = parseActorRef(args.actor, 'actor');
+                    if (!actor)
+                        throw new McpValidationError('Missing or invalid field: actor');
+                    const claim = await requestManager.renewWorkClaim(parseRequiredFiniteInteger(args.claimId, 'claimId', { min: 1 }), actor, parseOptionalFiniteInteger(args.leaseSeconds, { name: 'leaseSeconds', min: 1 }, failMcpValidation));
+                    return jsonResult({ claim: claim ? serializeWorkClaim(claim) : null });
+                }
+                case 'memory_release_work_claim': {
+                    const actor = parseActorRef(args.actor, 'actor');
+                    if (!actor)
+                        throw new McpValidationError('Missing or invalid field: actor');
+                    const claim = await requestManager.releaseWorkClaim(parseRequiredFiniteInteger(args.claimId, 'claimId', { min: 1 }), actor, optionalString(args.reason, 'reason'));
+                    return jsonResult({ claim: claim ? serializeWorkClaim(claim) : null });
+                }
+                case 'memory_list_work_claims': {
+                    const claims = await requestManager.listWorkClaims();
+                    return jsonResult({ claims: claims.map(serializeWorkClaim) });
+                }
+                case 'memory_handoff_work_item': {
+                    const fromActor = parseActorRef(args.fromActor, 'fromActor');
+                    const toActor = parseActorRef(args.toActor, 'toActor');
+                    if (!fromActor || !toActor) {
+                        throw new McpValidationError('Missing or invalid field: fromActor/toActor');
+                    }
+                    const handoff = await requestManager.handoffWorkItem({
+                        workItemId: parseRequiredFiniteInteger(args.workItemId, 'workItemId', { min: 1 }),
+                        fromActor,
+                        toActor,
+                        summary: requireString(args.summary, 'summary'),
+                        contextBundleRef: optionalString(args.contextBundleRef, 'contextBundleRef') ?? null,
+                        expiresAt: parseOptionalFiniteInteger(args.expiresAt, { name: 'expiresAt', min: 0 }, failMcpValidation) ?? null,
+                    });
+                    return jsonResult({ handoff: serializeHandoffRecord(handoff) });
+                }
+                case 'memory_accept_handoff': {
+                    const actor = parseActorRef(args.actor, 'actor');
+                    if (!actor)
+                        throw new McpValidationError('Missing or invalid field: actor');
+                    const handoff = await requestManager.acceptHandoff(parseRequiredFiniteInteger(args.handoffId, 'handoffId', { min: 1 }), actor, optionalString(args.reason, 'reason'));
+                    return jsonResult({ handoff: handoff ? serializeHandoffRecord(handoff) : null });
+                }
+                case 'memory_reject_handoff': {
+                    const actor = parseActorRef(args.actor, 'actor');
+                    if (!actor)
+                        throw new McpValidationError('Missing or invalid field: actor');
+                    const handoff = await requestManager.rejectHandoff(parseRequiredFiniteInteger(args.handoffId, 'handoffId', { min: 1 }), actor, optionalString(args.reason, 'reason'));
+                    return jsonResult({ handoff: handoff ? serializeHandoffRecord(handoff) : null });
+                }
+                case 'memory_cancel_handoff': {
+                    const actor = parseActorRef(args.actor, 'actor');
+                    if (!actor)
+                        throw new McpValidationError('Missing or invalid field: actor');
+                    const handoff = await requestManager.cancelHandoff(parseRequiredFiniteInteger(args.handoffId, 'handoffId', { min: 1 }), actor, optionalString(args.reason, 'reason'));
+                    return jsonResult({ handoff: handoff ? serializeHandoffRecord(handoff) : null });
+                }
+                case 'memory_list_pending_handoffs': {
+                    const handoffs = await requestManager.listPendingHandoffs({
+                        direction: args.direction == null
+                            ? 'all'
+                            : requireEnum(args.direction, ['inbound', 'outbound', 'all'], 'direction'),
+                    });
+                    return jsonResult({ handoffs: handoffs.map(serializeHandoffRecord) });
+                }
+                case 'memory_stream_changes': {
+                    const events = await requestManager.listMemoryEvents({
+                        cursor: parseOptionalTemporalId(args.cursor, 'cursor'),
+                        sessionId: optionalString(args.sessionId, 'sessionId'),
+                        entityKind: optionalString(args.entityKind, 'entityKind'),
+                        entityId: optionalString(args.entityId, 'entityId'),
+                        limit: parseLimit(args.limit),
+                    });
+                    return jsonResult(serializeTimelineResult(events));
+                }
                 case 'memory_force_compact': {
                     const result = await requestManager.forceCompact();
                     return jsonResult({
@@ -341,13 +1280,18 @@ export function createMcpServerHandler(config = {}) {
                     });
                 }
                 case 'memory_get_health': {
-                    const context = await requestManager.getContext();
+                    const [context, diagnostics] = await Promise.all([
+                        requestManager.getContext(),
+                        requestManager.getRuntimeDiagnostics(),
+                    ]);
                     return jsonResult({
                         activeTurnCount: context.activeTurns.length,
                         tokenEstimate: context.tokenEstimate,
                         knowledgeCount: context.relevantKnowledge.length,
                         objectiveCount: context.activeObjectives.length,
                         unresolvedWorkCount: context.unresolvedWork.length,
+                        sessionStateUpdatedAt: context.sessionState.updatedAt,
+                        circuitBreakers: diagnostics.circuitBreakers,
                     });
                 }
                 case 'memory_run_maintenance': {
@@ -358,11 +1302,185 @@ export function createMcpServerHandler(config = {}) {
                         deletedWorkItems: report.deletedWorkItemIds.length,
                     });
                 }
+                case 'memory_search_episodes': {
+                    const episodeTimeRange = isRecord(args.timeRange)
+                        ? {
+                            start_at: parseOptionalFiniteNumber(args.timeRange.start_at, { name: 'timeRange.start_at' }, failMcpValidation),
+                            end_at: parseOptionalFiniteNumber(args.timeRange.end_at, { name: 'timeRange.end_at' }, failMcpValidation),
+                        }
+                        : undefined;
+                    const episodes = await requestManager.searchEpisodes({
+                        query: requireString(args.query, 'query'),
+                        detailLevel: args.detailLevel != null
+                            ? requireEnum(args.detailLevel, ['abstract', 'overview', 'full'], 'detailLevel')
+                            : undefined,
+                        limit: parseLimit(args.limit),
+                        timeRange: episodeTimeRange,
+                    });
+                    return jsonResult({ episodes });
+                }
+                case 'memory_summarize_episode': {
+                    const summary = await requestManager.summarizeEpisode(requireString(args.sessionId, 'sessionId'), args.detailLevel != null
+                        ? { detailLevel: requireEnum(args.detailLevel, ['abstract', 'overview', 'full'], 'detailLevel') }
+                        : undefined);
+                    return jsonResult(summary);
+                }
+                case 'memory_reflect': {
+                    const reflectTimeRange = isRecord(args.timeRange)
+                        ? {
+                            start_at: parseOptionalFiniteNumber(args.timeRange.start_at, { name: 'timeRange.start_at' }, failMcpValidation),
+                            end_at: parseOptionalFiniteNumber(args.timeRange.end_at, { name: 'timeRange.end_at' }, failMcpValidation),
+                        }
+                        : undefined;
+                    const result = await requestManager.reflect({
+                        query: requireString(args.query, 'query'),
+                        detailLevel: args.detailLevel != null
+                            ? requireEnum(args.detailLevel, ['abstract', 'overview', 'full'], 'detailLevel')
+                            : undefined,
+                        includeEpisodic: args.includeEpisodic != null ? Boolean(args.includeEpisodic) : undefined,
+                        includeDeclarative: args.includeDeclarative != null ? Boolean(args.includeDeclarative) : undefined,
+                        limit: parseLimit(args.limit),
+                        timeRange: reflectTimeRange,
+                    });
+                    return jsonResult(result);
+                }
+                case 'memory_search_cognitive': {
+                    const cognitiveResult = await requestManager.searchCognitive({
+                        query: requireString(args.query, 'query'),
+                        types: Array.isArray(args.types) ? args.types : undefined,
+                        limit: parseLimit(args.limit),
+                        minimumTrustScore: parseOptionalFiniteNumber(args.minimumTrustScore, { name: 'minimumTrustScore', min: 0, max: 1 }, failMcpValidation),
+                        activeOnly: args.activeOnly != null ? Boolean(args.activeOnly) : undefined,
+                    });
+                    return jsonResult(cognitiveResult);
+                }
+                case 'memory_get_profile': {
+                    const profile = await requestManager.getProfile({
+                        view: args.view != null
+                            ? requireEnum(args.view, ['user', 'operator', 'workspace'], 'view')
+                            : undefined,
+                        sections: Array.isArray(args.sections)
+                            ? args.sections.map((s) => requireEnum(s, ['identity', 'preferences', 'communication', 'constraints', 'workflows'], 'sections'))
+                            : undefined,
+                        minimumTrustScore: parseOptionalFiniteNumber(args.minimumTrustScore, { name: 'minimumTrustScore', min: 0, max: 1 }, failMcpValidation),
+                        includeProvisional: args.includeProvisional != null ? Boolean(args.includeProvisional) : undefined,
+                        includeDisputed: args.includeDisputed != null ? Boolean(args.includeDisputed) : undefined,
+                    });
+                    return jsonResult(profile);
+                }
+                case 'memory_create_playbook': {
+                    const playbook = await requestManager.createPlaybook({
+                        title: requireString(args.title, 'title'),
+                        description: requireString(args.description, 'description'),
+                        instructions: requireString(args.instructions, 'instructions'),
+                        references: Array.isArray(args.references) ? args.references.map(String) : undefined,
+                        templates: Array.isArray(args.templates) ? args.templates.map(String) : undefined,
+                        scripts: Array.isArray(args.scripts) ? args.scripts.map(String) : undefined,
+                        assets: Array.isArray(args.assets) ? args.assets.map(String) : undefined,
+                        tags: Array.isArray(args.tags) ? args.tags.map(String) : undefined,
+                        status: args.status != null
+                            ? requireEnum(args.status, ['draft', 'active', 'deprecated', 'archived'], 'status')
+                            : undefined,
+                    });
+                    return jsonResult({ playbook });
+                }
+                case 'memory_create_playbook_from_task': {
+                    const playbook = await requestManager.createPlaybookFromTask({
+                        title: requireString(args.title, 'title'),
+                        description: requireString(args.description, 'description'),
+                        sessionId: requireString(args.sessionId, 'sessionId'),
+                        tags: Array.isArray(args.tags) ? args.tags.map(String) : undefined,
+                        sourceWorkingMemoryId: parseOptionalFiniteInteger(args.sourceWorkingMemoryId, { name: 'sourceWorkingMemoryId', min: 1 }, failMcpValidation),
+                    });
+                    return jsonResult({ playbook });
+                }
+                case 'memory_search_playbooks': {
+                    const results = await requestManager.searchPlaybooks(requireString(args.query, 'query'), { limit: parseLimit(args.limit) });
+                    // Return full playbook records with rank so consumers get the
+                    // same shape as the HTTP /v1/playbooks search response.
+                    return jsonResult({
+                        playbooks: results.map((r) => ({ ...r.item, rank: r.rank })),
+                    });
+                }
+                case 'memory_revise_playbook': {
+                    const playbookId = parseRequiredFiniteInteger(args.playbookId, 'playbookId', { min: 1 });
+                    const result = await requestManager.revisePlaybook(playbookId, requireString(args.newInstructions, 'newInstructions'), requireString(args.revisionReason, 'revisionReason'), optionalString(args.sourceSessionId, 'sourceSessionId'));
+                    return jsonResult({ playbook: result.playbook, revision: result.revision });
+                }
+                case 'memory_use_playbook': {
+                    const playbookId = parseRequiredFiniteInteger(args.playbookId, 'playbookId', { min: 1 });
+                    await requestManager.recordPlaybookUse(playbookId);
+                    const playbook = await requestManager.getPlaybook(playbookId);
+                    return jsonResult({ playbook });
+                }
+                case 'memory_get_associations': {
+                    const kind = requireEnum(args.kind, ASSOCIATION_TARGET_KINDS, 'kind');
+                    const id = parseRequiredFiniteInteger(args.id, 'id', { min: 1 });
+                    if (args.traverse) {
+                        const graph = await requestManager.traverseAssociations(kind, id, {
+                            maxDepth: parseOptionalNonNegativeInteger(args.maxDepth, 'maxDepth'),
+                            maxNodes: parseOptionalNonNegativeInteger(args.maxNodes, 'maxNodes'),
+                        });
+                        return jsonResult(graph);
+                    }
+                    const assocs = await requestManager.getAssociations(kind, id);
+                    return jsonResult(assocs);
+                }
+                case 'memory_add_association': {
+                    const sourceId = typeof args.source_id === 'number' && Number.isInteger(args.source_id) && args.source_id > 0
+                        ? args.source_id
+                        : (() => { throw new McpValidationError('Missing or invalid field: source_id (must be positive integer)'); })();
+                    const targetId = typeof args.target_id === 'number' && Number.isInteger(args.target_id) && args.target_id > 0
+                        ? args.target_id
+                        : (() => { throw new McpValidationError('Missing or invalid field: target_id (must be positive integer)'); })();
+                    let confidence;
+                    if (args.confidence !== undefined && args.confidence !== null) {
+                        if (typeof args.confidence !== 'number' || Number.isNaN(args.confidence) || args.confidence < 0 || args.confidence > 1) {
+                            throw new McpValidationError('Invalid field: confidence (must be a number in [0, 1])');
+                        }
+                        confidence = args.confidence;
+                    }
+                    const association = await requestManager.addAssociation({
+                        source_kind: requireEnum(args.source_kind, ASSOCIATION_TARGET_KINDS, 'source_kind'),
+                        source_id: sourceId,
+                        target_kind: requireEnum(args.target_kind, ASSOCIATION_TARGET_KINDS, 'target_kind'),
+                        target_id: targetId,
+                        association_type: requireEnum(args.association_type, ASSOCIATION_TYPES, 'association_type'),
+                        confidence,
+                    });
+                    return jsonResult({ created: true, associationId: association.id });
+                }
+                case 'memory_remove_association': {
+                    const id = parseRequiredFiniteInteger(args.id, 'id', { min: 1 });
+                    await requestManager.removeAssociation(id);
+                    return jsonResult({ deleted: true });
+                }
+                case 'memory_snapshot': {
+                    const action = requireEnum(args.action, ['capture', 'refresh', 'get'], 'action');
+                    const sessionId = requireString(args.sessionId, 'sessionId');
+                    const runtime = await getSessionRuntime(resolveScopeInput(config.scope, args), sessionId);
+                    const relevanceQuery = optionalString(args.relevanceQuery, 'relevanceQuery');
+                    if (action === 'capture') {
+                        await runtime.startSession(relevanceQuery);
+                        const snapshot = runtime.getSnapshot();
+                        return jsonResult({ snapshot: snapshot ? { ...snapshot, sessionId } : null });
+                    }
+                    if (action === 'refresh') {
+                        const snapshot = await runtime.refreshSnapshot(relevanceQuery);
+                        return jsonResult({ snapshot: snapshot ? { ...snapshot, sessionId } : null });
+                    }
+                    // get
+                    const snapshot = runtime.getSnapshot();
+                    return jsonResult({ snapshot: snapshot ? { ...snapshot, sessionId } : null });
+                }
                 default:
                     return errorResult(`Unknown tool: ${name}`);
             }
         }
         catch (error) {
+            if (isMemoryDomainError(error)) {
+                return errorResult(`Error in ${name}: ${error.message}`);
+            }
             return errorResult(`Error in ${name}: ${error instanceof Error ? error.message : String(error)}`);
         }
     }
@@ -371,12 +1489,14 @@ export function createMcpServerHandler(config = {}) {
         callTool,
         manager: undefined,
         async close() {
-            const manager = await managerPromise;
-            for (const cachedManager of managers.values()) {
-                await cachedManager.close();
-            }
             managers.clear();
-            await manager.close();
+            sessionManagers.clear();
+            sessionRuntimes.clear();
+            runtimes.clear();
+            if (adapterPromise) {
+                const adapterContext = await adapterPromise;
+                await adapterContext.close();
+            }
         },
     };
 }
@@ -405,7 +1525,7 @@ export async function startMcpServer(config = {}) {
                         capabilities: { tools: {} },
                         serverInfo: {
                             name: 'memory-layer',
-                            version: '2.0.0',
+                            version: '3.0.0',
                         },
                     },
                 }) + '\n');