ai-memory-layer 2.0.1 → 3.0.0

package/dist/core/manager.js

@@ -1,17 +1,25 @@
+import { matchesScope, normalizeScope } from '../contracts/identity.js';
+import { ProviderUnavailableError, ResourceNotFoundError, ScopeMismatchError, ValidationError, } from '../contracts/errors.js';
 import { DEFAULT_CONTEXT_POLICY, DEFAULT_MONITOR_POLICY, } from '../contracts/policy.js';
-import { buildMemoryContext } from './context.js';
+import { buildDerivedShortTermState, buildMemoryContext, getContextWorkItems, resolveContextScopeLevel, resolveVisibleHandoffs, resolveVisibleKnowledge, resolveVisiblePlaybooks, resolveVisibleWorkClaims, resolveVisibleWorkItems, } from './context.js';
 import { compactTurns, extractKnowledge, } from './orchestrator.js';
 import { assessContext } from './monitor.js';
 import { runMaintenance } from './maintenance.js';
 import { emitMemoryEvent } from './telemetry.js';
 import { wrapSyncAdapter } from '../adapters/sync-to-async.js';
 import { estimateTokens } from './tokens.js';
-import { createCircuitBreaker } from './circuit-breaker.js';
+import { createCircuitBreaker, } from './circuit-breaker.js';
 import { DEFAULT_EXTRACTION_POLICY } from '../contracts/policy.js';
 import { assessKnowledgeReverification } from './trust.js';
 import { matchesKnowledgeSearchOptions, rankKnowledge } from './retrieval.js';
 import { computeNextReverificationAt, getDueReverificationKnowledge, resolveMaintenancePolicy, } from './knowledge-lifecycle.js';
-import { normalizeScope } from '../contracts/identity.js';
+import { compareTemporalIds, normalizeTemporalId } from '../contracts/temporal.js';
+import { searchEpisodes, summarizeEpisode, reflect } from './episodic.js';
+import { searchCognitive } from './cognitive.js';
+import { traverseAssociations } from './associations.js';
+import { buildProfileFromKnowledge, getProfile } from './profile.js';
+import { createPlaybookFromTask, revisePlaybook, findRelevantPlaybooks, } from './playbook.js';
+import { createTemporalReplayAdapter, foldTemporalState, listAllMemoryEvents, listAllMemoryEventsBounded, listAllMemoryEventsCrossScope, normalizeReplayedTemporalState, normalizeHandoffAt, normalizeWorkClaimAt, } from './temporal.js';
 function resolveAdapter(config) {
     if (config.asyncAdapter) {
         return config.asyncAdapter;
@@ -19,7 +27,7 @@ function resolveAdapter(config) {
     if (config.adapter) {
         return wrapSyncAdapter(config.adapter);
     }
-    throw new Error("MemoryManagerConfig requires either 'adapter' or 'asyncAdapter'");
+    throw new ValidationError("MemoryManagerConfig requires either 'adapter' or 'asyncAdapter'");
 }
 function manualKnowledgeClassForFactType(factType) {
     switch (factType) {
@@ -35,6 +43,79 @@ function manualKnowledgeClassForFactType(factType) {
             return 'project_fact';
     }
 }
+/**
+ * Resolve an association endpoint (source or target) and verify it exists
+ * and belongs to the caller's normalized scope. Throws a descriptive error
+ * if the node is missing or cross-scope. This is the sole authority on
+ * association ID validity; HTTP/MCP layers should NOT rely on their own
+ * type checks for scope safety.
+ */
+async function assertAssociationEndpointInScope(adapter, norm, kind, id, role) {
+    const scopedMatch = (record) => record.tenant_id === norm.tenant_id &&
+        record.system_id === norm.system_id &&
+        record.workspace_id === norm.workspace_id &&
+        record.collaboration_id === norm.collaboration_id &&
+        record.scope_id === norm.scope_id;
+    if (kind === 'knowledge') {
+        const km = await adapter.getKnowledgeMemoryById(id);
+        if (!km) {
+            throw new ResourceNotFoundError(`addAssociation: ${role} knowledge ${id} does not exist`);
+        }
+        if (!scopedMatch(km)) {
+            throw new ScopeMismatchError(`addAssociation: ${role} knowledge ${id} is not in the current scope`);
+        }
+        return;
+    }
+    if (kind === 'playbook') {
+        const pb = await adapter.getPlaybookById(id);
+        if (!pb) {
+            throw new ResourceNotFoundError(`addAssociation: ${role} playbook ${id} does not exist`);
+        }
+        if (!scopedMatch(pb)) {
+            throw new ScopeMismatchError(`addAssociation: ${role} playbook ${id} is not in the current scope`);
+        }
+        return;
+    }
+    if (kind === 'working_memory') {
+        const wm = await adapter.getWorkingMemoryById(id);
+        if (!wm) {
+            throw new ResourceNotFoundError(`addAssociation: ${role} working_memory ${id} does not exist`);
+        }
+        if (!scopedMatch(wm)) {
+            throw new ScopeMismatchError(`addAssociation: ${role} working_memory ${id} is not in the current scope`);
+        }
+        return;
+    }
+    if (kind === 'work_item') {
+        const match = await adapter.getWorkItemById(id);
+        if (!match) {
+            throw new ResourceNotFoundError(`addAssociation: ${role} work_item ${id} does not exist in the current scope`);
+        }
+        if (match.tenant_id !== norm.tenant_id ||
+            match.system_id !== norm.system_id ||
+            match.workspace_id !== norm.workspace_id ||
+            match.collaboration_id !== norm.collaboration_id ||
+            match.scope_id !== norm.scope_id) {
+            throw new ScopeMismatchError(`addAssociation: ${role} work_item ${id} does not exist in the current scope`);
+        }
+        return;
+    }
+    // Exhaustiveness: AssociationTargetKind has no other members.
+    throw new ValidationError(`addAssociation: unknown ${role} kind '${kind}'`);
+}
+/**
+ * Merge archived and active turns by id, preserving order by turn id.
+ * Partially compacted sessions have both sets; summarizing from only one
+ * drops context, so callers should always pass the union through this.
+ */
+function mergeTurnsById(archived, active) {
+    const byId = new Map();
+    for (const t of archived)
+        byId.set(t.id, t);
+    for (const t of active)
+        byId.set(t.id, t);
+    return Array.from(byId.values()).sort((a, b) => a.id - b.id);
+}
 function knowledgeMatchesScope(knowledge, scope) {
     const normalized = normalizeScope(scope);
     return (knowledge.tenant_id === normalized.tenant_id &&
@@ -43,6 +124,9 @@ function knowledgeMatchesScope(knowledge, scope) {
         knowledge.collaboration_id === normalized.collaboration_id &&
         knowledge.scope_id === normalized.scope_id);
 }
+function delay(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
 export function createMemoryManager(config) {
     const asyncAdapter = resolveAdapter(config);
     const autoCompact = config.autoCompact ?? true;
@@ -87,6 +171,14 @@ export function createMemoryManager(config) {
             ...detail,
         });
     }
+    function emitRetrievalFallback(reason, detail = {}) {
+        emitMemoryEvent('manager', config.scope, { logger: config.logger, onEvent }, 0, {
+            action: 'retrieval_fallback',
+            reason,
+            strategy: 'lexical_only',
+            ...detail,
+        });
+    }
     async function withFailurePolicy(kind, run, fallback) {
         const strategy = config.failurePolicy?.[kind] ??
             (kind === 'extractor' ? 'disable_auto_extract' : 'throw');
@@ -138,7 +230,13 @@ export function createMemoryManager(config) {
         });
     }
     async function buildQueryVector(input) {
-        if (!config.embeddingGenerator || input.trim().length === 0) {
+        if (input.trim().length === 0) {
+            return undefined;
+        }
+        if (!config.embeddingGenerator) {
+            emitRetrievalFallback('embedding_generator_unavailable', {
+                stage: 'query_vector',
+            });
             return undefined;
         }
         try {
@@ -153,6 +251,10 @@ export function createMemoryManager(config) {
                 stage: 'query_vector',
                 error: String(error),
             });
+            emitRetrievalFallback('query_vector_unavailable', {
+                stage: 'query_vector',
+                error: String(error),
+            });
             return undefined;
         }
     }
@@ -198,10 +300,18 @@ export function createMemoryManager(config) {
             : await asyncAdapter.searchKnowledgeCrossScope(config.scope, level, query, options);
         const filteredLexical = lexical.filter((result) => matchesKnowledgeSearchOptions(result.item, options));
         if (!config.embeddingAdapter) {
+            emitRetrievalFallback('embedding_adapter_unavailable', {
+                stage: 'semantic_search',
+                scopeLevel: level,
+            });
             return filteredLexical;
         }
         const queryVector = await buildQueryVector(query);
         if (!queryVector) {
+            emitRetrievalFallback('query_vector_unavailable', {
+                stage: 'semantic_search',
+                scopeLevel: level,
+            });
             return filteredLexical;
         }
         let semantic;
@@ -227,6 +337,11 @@ export function createMemoryManager(config) {
                 error: String(error),
                 scopeLevel: level,
             });
+            emitRetrievalFallback('semantic_search_failed', {
+                stage: 'semantic_search',
+                error: String(error),
+                scopeLevel: level,
+            });
             return filteredLexical;
         }
         const lexicalRanks = new Map();
@@ -267,16 +382,17 @@ export function createMemoryManager(config) {
             .sort((a, b) => b.rank - a.rank || b.item.last_accessed_at - a.item.last_accessed_at)
             .slice(0, options?.limit ?? 10);
         if (config.contextPolicy?.touchSelectedKnowledge ?? true) {
-            for (const result of results) {
-                await asyncAdapter.touchKnowledgeMemory(result.item.id);
-            }
+            await asyncAdapter.touchKnowledgeMemories(results.map((result) => result.item.id));
         }
         return results;
     }
-    async function getContextInternal(relevanceQuery, asOf) {
+    async function getContextInternal(relevanceQuery, asOf, options) {
         const activeTurns = await asyncAdapter.getActiveTurns(config.scope, config.sessionId);
+        const relevantTurns = asOf == null
+            ? activeTurns
+            : activeTurns.filter((turn) => turn.created_at <= asOf);
         const queryVector = await buildQueryVector(relevanceQuery ??
-            activeTurns
+            relevantTurns
                 .slice(-4)
                 .map((turn) => turn.content)
                 .join('\n'));
@@ -289,10 +405,192 @@ export function createMemoryManager(config) {
             policy: config.contextPolicy,
             tokenEstimator,
             asOf,
+            view: options?.view,
+            viewer: options?.viewer,
+            includeCoordinationState: options?.includeCoordinationState,
             logger: config.logger,
             onEvent,
         });
     }
+    async function refreshSessionStateProjection() {
+        try {
+            const [activeTurns, workingMemoryCandidates, contextWorkItems, watermark] = await Promise.all([
+                asyncAdapter.getActiveTurns(config.scope, config.sessionId),
+                asyncAdapter.getActiveWorkingMemory(config.scope, config.sessionId),
+                // Session-state projection stays scope-local even when wider
+                // retrieval is configured; it is a fast resume artifact, not a full
+                // cross-scope context assembly.
+                getContextWorkItems(asyncAdapter, config.scope, undefined, 'scope'),
+                asyncAdapter.getTemporalWatermark('temporal'),
+            ]);
+            const shortTermState = buildDerivedShortTermState({
+                activeTurns,
+                workingMemoryCandidates,
+                contextWorkItems,
+                maxRecentSummaries: config.contextPolicy?.maxRecentSummaries ??
+                    DEFAULT_CONTEXT_POLICY.maxRecentSummaries,
+            });
+            await asyncAdapter.upsertSessionState({
+                ...normalizeScope(config.scope),
+                session_id: config.sessionId,
+                ...shortTermState.sessionState,
+                source_event_id: watermark?.last_event_id ?? null,
+            });
+        }
+        catch (error) {
+            config.logger?.warn?.('memory.session_state_projection_refresh_failed', {
+                error: String(error),
+                sessionId: config.sessionId,
+            });
+            emitMemoryEvent('manager', config.scope, { logger: config.logger, onEvent }, 0, {
+                action: 'session_state_projection_refresh_failed',
+                sessionId: config.sessionId,
+                error: String(error),
+            });
+        }
+    }
+    async function collectBestEffortTemporalState(asOf, options) {
+        const view = options?.view;
+        const effectiveScopeLevel = resolveContextScopeLevel(config.crossScopeLevel, view);
+        const [turns, workingMemory, knowledge, contextWorkItems, playbooks, associations, rawWorkClaims, rawHandoffs,] = await Promise.all([
+            asyncAdapter.getTurnsByTimeRange(config.scope, { end_at: asOf }),
+            asyncAdapter.getWorkingMemoryByTimeRange(config.scope, { end_at: asOf }),
+            effectiveScopeLevel && effectiveScopeLevel !== 'scope'
+                ? asyncAdapter.getActiveKnowledgeCrossScope(config.scope, effectiveScopeLevel)
+                : asyncAdapter.getActiveKnowledgeMemory(config.scope),
+            getContextWorkItems(asyncAdapter, config.scope, asOf, effectiveScopeLevel),
+            effectiveScopeLevel && effectiveScopeLevel !== 'scope'
+                ? asyncAdapter.getActivePlaybooksCrossScope(config.scope, effectiveScopeLevel)
+                : asyncAdapter.getActivePlaybooks(config.scope),
+            asyncAdapter.listAssociations(config.scope),
+            effectiveScopeLevel && effectiveScopeLevel !== 'scope'
+                ? asyncAdapter.listWorkClaimsCrossScope(config.scope, effectiveScopeLevel, {
+                    includeExpired: true,
+                    includeReleased: true,
+                })
+                : asyncAdapter.listWorkClaims(config.scope, {
+                    includeExpired: true,
+                    includeReleased: true,
+                }),
+            effectiveScopeLevel && effectiveScopeLevel !== 'scope'
+                ? asyncAdapter.listHandoffsCrossScope(config.scope, effectiveScopeLevel)
+                : asyncAdapter.listHandoffs(config.scope),
+        ]);
+        const visibleKnowledge = (view
+            ? resolveVisibleKnowledge(knowledge.filter((item) => item.created_at <= asOf), config.scope, view)
+            : knowledge.filter((item) => item.created_at <= asOf)).sort((a, b) => a.created_at - b.created_at || a.id - b.id);
+        const visibleWorkItems = (view ? resolveVisibleWorkItems(contextWorkItems, config.scope, view) : contextWorkItems).sort((a, b) => a.updated_at - b.updated_at || a.created_at - b.created_at || a.id - b.id);
+        const visiblePlaybooks = (view
+            ? resolveVisiblePlaybooks(playbooks.filter((item) => item.created_at <= asOf), config.scope, view)
+            : playbooks.filter((item) => item.created_at <= asOf)).sort((a, b) => a.updated_at - b.updated_at || a.created_at - b.created_at || a.id - b.id);
+        const visibleWorkClaims = (view
+            ? resolveVisibleWorkClaims(rawWorkClaims.map((claim) => normalizeWorkClaimAt(claim, asOf)), config.scope, view)
+            : rawWorkClaims.map((claim) => normalizeWorkClaimAt(claim, asOf))).sort((a, b) => a.claimed_at - b.claimed_at || a.id - b.id);
+        const visibleHandoffs = (view
+            ? resolveVisibleHandoffs(rawHandoffs.map((handoff) => normalizeHandoffAt(handoff, asOf)), config.scope, view)
+            : rawHandoffs.map((handoff) => normalizeHandoffAt(handoff, asOf))).sort((a, b) => a.created_at - b.created_at || a.id - b.id);
+        return {
+            turns: turns
+                .filter((turn) => turn.session_id === config.sessionId)
+                .sort((a, b) => a.created_at - b.created_at || a.id - b.id),
+            workingMemory: workingMemory
+                .filter((item) => item.session_id === config.sessionId)
+                .sort((a, b) => a.created_at - b.created_at || a.id - b.id),
+            knowledge: visibleKnowledge,
+            workItems: visibleWorkItems,
+            workClaims: visibleWorkClaims,
+            handoffs: visibleHandoffs,
+            associations: associations
+                .filter((association) => association.created_at <= asOf)
+                .sort((a, b) => a.created_at - b.created_at || a.id - b.id),
+            playbooks: visiblePlaybooks,
+        };
+    }
+    async function getTemporalCutoverAt() {
+        const watermark = await asyncAdapter.getTemporalWatermark('temporal');
+        return watermark?.cutover_at ?? null;
+    }
+    async function resolveChangeStreamCursorInternal(cursor) {
+        if (cursor != null)
+            return normalizeTemporalId(cursor);
+        return (await asyncAdapter.getTemporalWatermark('temporal'))?.last_event_id ?? '0';
+    }
+    async function buildReplayedContext(asOf, relevanceQuery, options, replayCutoff) {
+        const cutoverAt = await getTemporalCutoverAt();
+        if (cutoverAt == null || asOf < cutoverAt) {
+            return {
+                // Pre-cutover replay is best-effort only. The historical filters still
+                // apply, but semantic retrieval may consult the live embedding index
+                // because that index has no temporal dimension before the cutover.
+                context: await getContextInternal(relevanceQuery, asOf, options),
+                events: [],
+                state: null,
+                watermarkEventId: null,
+                exact: false,
+                cutoverAt,
+            };
+        }
+        const replayScopeLevel = resolveContextScopeLevel(config.crossScopeLevel, options?.view);
+        const events = replayScopeLevel != null && replayScopeLevel !== 'scope'
+            ? await listAllMemoryEventsCrossScope(asyncAdapter, config.scope, replayScopeLevel, {
+                endAt: asOf,
+                limit: 500,
+            })
+            : await listAllMemoryEvents(asyncAdapter, config.scope, {
+                endAt: asOf,
+                limit: 500,
+            });
+        const filteredEvents = replayCutoff?.throughEventId != null
+            ? events.filter((event) => compareTemporalIds(event.event_id, replayCutoff.throughEventId) <= 0)
+            : events;
+        const replayed = normalizeReplayedTemporalState(foldTemporalState(filteredEvents, { sessionId: config.sessionId }), asOf);
+        const replayAdapter = createTemporalReplayAdapter(replayed, asOf);
+        const inferredRelevanceQuery = replayed.turns
+            .slice(-4)
+            .map((turn) => turn.content)
+            .join('\n')
+            .trim();
+        const resolvedRelevanceQuery = relevanceQuery ?? (inferredRelevanceQuery || undefined);
+        // Exact replay stays on the replay adapter only, so no live semantic data
+        // can leak into the assembled historical context after temporal cutover.
+        const context = await buildMemoryContext(replayAdapter, config.scope, {
+            sessionId: config.sessionId,
+            relevanceQuery: resolvedRelevanceQuery,
+            crossScopeLevel: config.crossScopeLevel,
+            policy: config.contextPolicy,
+            tokenEstimator,
+            view: options?.view,
+            viewer: options?.viewer,
+            includeCoordinationState: options?.includeCoordinationState,
+            logger: config.logger,
+            onEvent,
+        });
+        return {
+            context,
+            events: filteredEvents,
+            state: replayed,
+            watermarkEventId: replayCutoff?.throughEventId ?? replayed.watermarkEventId,
+            exact: true,
+            cutoverAt,
+        };
+    }
+    function buildSessionBootstrapPayload(context, profile) {
+        return {
+            currentObjective: context.currentObjective,
+            sessionState: context.sessionState,
+            workingMemory: context.workingMemory,
+            relevantKnowledge: context.relevantKnowledge,
+            recentSummaries: context.recentSummaries,
+            activeObjectives: context.activeObjectives,
+            unresolvedWork: context.unresolvedWork,
+            coordinationState: context.coordinationState,
+            profile,
+        };
+    }
+    async function getHistoricalProfileAt(asOf) {
+        const bestEffort = await collectBestEffortTemporalState(asOf);
+        return buildProfileFromKnowledge(bestEffort.knowledge.filter((item) => matchesScope(item, config.scope)));
+    }
     async function executeCompaction(turns, trigger, retainedTurnCount, score) {
         await persistMonitorState('compacting', score, turns);
         const result = await withFailurePolicy('summarizer', () => compactTurns(asyncAdapter, config.scope, config.sessionId, turns, config.summarizer, trigger, retainedTurnCount, { logger: config.logger, onEvent }), () => null);
@@ -316,6 +614,7 @@ export function createMemoryManager(config) {
             await maybeEmbedKnowledge(extracted);
             extracted.forEach((knowledge) => emitKnowledgeChange('promoted', knowledge));
         }
+        await refreshSessionStateProjection();
         return result;
     }
     async function runCompaction(turns) {
@@ -342,9 +641,9 @@ export function createMemoryManager(config) {
         }
         return executeCompaction(turns, report.recommendation.action, Math.max(0, Math.min(report.recommendation.post_compaction_target_turns, turns.length - 1)), report.score_breakdown.total);
     }
-    async function insertManagedTurn(role, content, actor) {
+    async function insertManagedTurnRecord(role, content, actor) {
         const redactedContent = config.redactText ? config.redactText({ kind: 'turn', text: content }) : content;
-        const turn = await asyncAdapter.insertTurn({
+        return asyncAdapter.insertTurn({
             ...config.scope,
             session_id: config.sessionId,
             actor,
@@ -352,6 +651,9 @@ export function createMemoryManager(config) {
             content: redactedContent,
             token_estimate: tokenEstimator(redactedContent),
         });
+    }
+    async function insertManagedTurn(role, content, actor) {
+        const turn = await insertManagedTurnRecord(role, content, actor);
         emitMemoryEvent('manager', config.scope, { logger: config.logger, onEvent }, 0, {
             action: 'process_turn',
             role,
@@ -366,35 +668,175 @@ export function createMemoryManager(config) {
                 const activeTurns = await asyncAdapter.getActiveTurns(config.scope, config.sessionId);
                 await runCompaction(activeTurns);
             }
+            await refreshSessionStateProjection();
             return turn;
         },
         async processExchange(userContent, assistantContent, actors) {
-            const userTurn = await insertManagedTurn('user', userContent, actors?.user ?? 'user');
-            const assistantTurn = await insertManagedTurn('assistant', assistantContent, actors?.assistant ?? 'assistant');
+            const [userTurn, assistantTurn] = await asyncAdapter.transaction(async () => {
+                const createdUserTurn = await insertManagedTurnRecord('user', userContent, actors?.user ?? 'user');
+                const createdAssistantTurn = await insertManagedTurnRecord('assistant', assistantContent, actors?.assistant ?? 'assistant');
+                return [createdUserTurn, createdAssistantTurn];
+            });
+            emitMemoryEvent('manager', config.scope, { logger: config.logger, onEvent }, 0, {
+                action: 'process_turn',
+                role: 'user',
+                turnId: userTurn.id,
+            });
+            emitMemoryEvent('manager', config.scope, { logger: config.logger, onEvent }, 0, {
+                action: 'process_turn',
+                role: 'assistant',
+                turnId: assistantTurn.id,
+            });
             const compactionResult = autoCompact
                 ? await runCompaction(await asyncAdapter.getActiveTurns(config.scope, config.sessionId))
                 : null;
+            await refreshSessionStateProjection();
             return {
                 userTurn,
                 assistantTurn,
                 compactionResult,
             };
         },
-        async getContext(relevanceQuery) {
-            return getContextInternal(relevanceQuery);
+        async getContext(relevanceQuery, options) {
+            return getContextInternal(relevanceQuery, undefined, options);
+        },
+        async getContextAt(asOf, relevanceQuery, options) {
+            return (await buildReplayedContext(asOf, relevanceQuery, options)).context;
+        },
+        async getStateAt(asOf, options) {
+            const replay = await buildReplayedContext(asOf, options?.relevanceQuery, options);
+            const replayed = replay.exact
+                ? replay.state
+                : await collectBestEffortTemporalState(asOf, options);
+            return {
+                asOf,
+                exact: replay.exact,
+                cutoverAt: replay.cutoverAt,
+                watermarkEventId: replay.watermarkEventId,
+                context: replay.context,
+                sessionState: replay.context.sessionState,
+                turns: replayed.turns,
+                workingMemory: replayed.workingMemory,
+                knowledge: replayed.knowledge,
+                workItems: replayed.workItems,
+                workClaims: replayed.workClaims,
+                handoffs: replayed.handoffs,
+                coordinationState: replay.context.coordinationState,
+                associations: replayed.associations,
+                playbooks: replayed.playbooks,
+            };
+        },
+        async getTimeline(options) {
+            return asyncAdapter.listMemoryEvents(config.scope, {
+                sessionId: options?.sessionId,
+                entityKind: options?.entityKind,
+                entityId: options?.entityId,
+                startAt: options?.startAt,
+                endAt: options?.endAt,
+                limit: options?.limit,
+                cursor: options?.cursor,
+            });
         },
-        async getContextAt(asOf, relevanceQuery) {
-            return getContextInternal(relevanceQuery, asOf);
+        async diffState(from, to, options) {
+            const cutoverAt = await getTemporalCutoverAt();
+            const eventQuery = {
+                sessionId: options?.sessionId,
+                entityKind: options?.entityKind,
+                entityId: options?.entityId,
+                startAt: from + 1,
+                endAt: to,
+                limit: 500,
+            };
+            const events = options?.maxEvents != null
+                ? await listAllMemoryEventsBounded(asyncAdapter, config.scope, options.maxEvents, eventQuery)
+                : await listAllMemoryEvents(asyncAdapter, config.scope, eventQuery);
+            const byEntityKind = {};
+            const byEventType = {};
+            for (const event of events) {
+                byEntityKind[event.entity_kind] = (byEntityKind[event.entity_kind] ?? 0) + 1;
+                byEventType[event.event_type] = (byEventType[event.event_type] ?? 0) + 1;
+            }
+            return {
+                from,
+                to,
+                exact: cutoverAt != null && from >= cutoverAt && to >= cutoverAt,
+                cutoverAt,
+                watermarkRange: {
+                    fromEventId: events[0]?.event_id ?? null,
+                    toEventId: events[events.length - 1]?.event_id ?? null,
+                },
+                events,
+                summary: {
+                    totalEvents: events.length,
+                    byEntityKind,
+                    byEventType,
+                },
+            };
         },
-        async getSessionBootstrap(relevanceQuery) {
-            const context = await getContextInternal(relevanceQuery);
+        async listMemoryEvents(options) {
+            const timeline = await asyncAdapter.listMemoryEvents(config.scope, {
+                sessionId: options?.sessionId,
+                entityKind: options?.entityKind,
+                entityId: options?.entityId,
+                startAt: options?.startAt,
+                endAt: options?.endAt,
+                limit: options?.limit,
+                cursor: options?.cursor,
+            });
             return {
-                currentObjective: context.currentObjective,
-                workingMemory: context.workingMemory,
-                relevantKnowledge: context.relevantKnowledge,
-                recentSummaries: context.recentSummaries,
-                activeObjectives: context.activeObjectives,
-                unresolvedWork: context.unresolvedWork,
+                events: [...timeline.events].reverse(),
+                nextCursor: timeline.nextCursor,
+            };
+        },
+        async getSessionBootstrap(relevanceQuery, options) {
+            const context = await getContextInternal(relevanceQuery, undefined, options);
+            const profile = await getProfile(asyncAdapter, config.scope);
+            return buildSessionBootstrapPayload(context, profile);
+        },
+        async getSessionBootstrapAt(asOf, relevanceQuery, options) {
+            const replay = await buildReplayedContext(asOf, relevanceQuery, options);
+            const profile = replay.exact && replay.state
+                ? buildProfileFromKnowledge(replay.state.knowledge.filter((item) => matchesScope(item, config.scope)))
+                : await getHistoricalProfileAt(asOf);
+            return buildSessionBootstrapPayload(replay.context, profile);
+        },
+        async captureSnapshot(relevanceQuery, options) {
+            const frozenAt = Math.floor(Date.now() / 1000);
+            const watermark = await asyncAdapter.getTemporalWatermark('temporal');
+            if (!watermark || watermark.last_event_id === '0') {
+                const [context, profile] = await Promise.all([
+                    getContextInternal(relevanceQuery, undefined, options),
+                    getProfile(asyncAdapter, config.scope),
+                ]);
+                return {
+                    bootstrap: buildSessionBootstrapPayload(context, profile),
+                    context,
+                    frozenAt,
+                    watermarkEventId: null,
+                    profile,
+                };
+            }
+            const replay = await buildReplayedContext(watermark.updated_at, relevanceQuery, options, {
+                throughEventId: watermark.last_event_id,
+            });
+            const profile = replay.exact && replay.state
+                ? buildProfileFromKnowledge(replay.state.knowledge.filter((item) => matchesScope(item, config.scope)))
+                : await getHistoricalProfileAt(watermark.updated_at);
+            return {
+                bootstrap: buildSessionBootstrapPayload(replay.context, profile),
+                context: replay.context,
+                frozenAt,
+                watermarkEventId: replay.exact ? watermark.last_event_id : null,
+                profile,
+            };
+        },
+        async getRuntimeDiagnostics() {
+            return {
+                circuitBreakers: {
+                    summarizer: circuitBreakers.summarizer.getSnapshot(),
+                    extractor: circuitBreakers.extractor.getSnapshot(),
+                    embeddings: circuitBreakers.embeddings.getSnapshot(),
+                },
             };
         },
         async recall(timeRange) {
@@ -461,10 +903,11 @@ export function createMemoryManager(config) {
             emitKnowledgeChange('learned', knowledge);
             return knowledge;
         },
-        async trackWorkItem(title, kind = 'objective', status = 'open', detail) {
-            return asyncAdapter.insertWorkItem({
+        async trackWorkItem(title, kind = 'objective', status = 'open', detail, options) {
+            const workItem = await asyncAdapter.insertWorkItem({
                 ...config.scope,
                 session_id: config.sessionId,
+                visibility_class: options?.visibilityClass ?? 'private',
                 title: config.redactText ? config.redactText({ kind: 'work_item', text: title }) : title,
                 kind,
                 status,
@@ -472,6 +915,88 @@ export function createMemoryManager(config) {
                     ? config.redactText({ kind: 'work_item', text: detail })
                     : detail,
             });
+            await refreshSessionStateProjection();
+            return workItem;
+        },
+        async updateWorkItem(id, patch, options) {
+            const workItem = await asyncAdapter.updateWorkItem(id, patch, options);
+            await refreshSessionStateProjection();
+            return workItem;
+        },
+        async claimWorkItem(input) {
+            const workItem = await asyncAdapter.getWorkItemById(input.workItemId);
+            return asyncAdapter.claimWorkItem({
+                ...normalizeScope(config.scope),
+                work_item_id: input.workItemId,
+                actor: input.actor,
+                session_id: config.sessionId,
+                lease_seconds: input.leaseSeconds,
+                visibility_class: workItem?.visibility_class ?? 'private',
+            });
+        },
+        async renewWorkClaim(claimId, actor, leaseSeconds) {
+            return asyncAdapter.renewWorkClaim(claimId, actor, leaseSeconds);
+        },
+        async releaseWorkClaim(claimId, actor, reason) {
+            return asyncAdapter.releaseWorkClaim(claimId, actor, reason);
+        },
+        async listWorkClaims(options) {
+            return asyncAdapter.listWorkClaims(config.scope, {
+                actor: options?.actor,
+                sessionId: options?.sessionId,
+            });
+        },
+        async handoffWorkItem(input) {
+            const workItem = await asyncAdapter.getWorkItemById(input.workItemId);
+            return asyncAdapter.createHandoff({
+                ...normalizeScope(config.scope),
+                work_item_id: input.workItemId,
+                from_actor: input.fromActor,
+                to_actor: input.toActor,
+                session_id: config.sessionId,
+                summary: input.summary,
+                context_bundle_ref: input.contextBundleRef ?? null,
+                expires_at: input.expiresAt ?? null,
+                visibility_class: workItem?.visibility_class ?? 'private',
+            });
+        },
+        async acceptHandoff(handoffId, actor, reason) {
+            return asyncAdapter.acceptHandoff(handoffId, actor, reason);
+        },
+        async rejectHandoff(handoffId, actor, reason) {
+            return asyncAdapter.rejectHandoff(handoffId, actor, reason);
+        },
+        async cancelHandoff(handoffId, actor, reason) {
+            return asyncAdapter.cancelHandoff(handoffId, actor, reason);
+        },
+        async listPendingHandoffs(options) {
+            return asyncAdapter.listHandoffs(config.scope, {
+                actor: options?.actor,
+                direction: options?.direction,
+                statuses: ['pending'],
+            });
+        },
+        async resolveChangeStreamCursor(cursor) {
+            return resolveChangeStreamCursorInternal(cursor);
+        },
+        async *streamChanges(options) {
+            let cursor = await resolveChangeStreamCursorInternal(options?.cursor);
+            while (!options?.signal?.aborted) {
+                const page = await asyncAdapter.listMemoryEvents(config.scope, {
+                    cursor,
+                    sessionId: options?.sessionId,
+                    entityKind: options?.entityKind,
+                    entityId: options?.entityId,
+                    limit: 100,
+                });
+                for (const event of page.events) {
+                    cursor = event.event_id;
+                    yield event;
+                }
+                if (options?.signal?.aborted)
+                    break;
+                await delay(options?.pollIntervalMs ?? 250);
+            }
         },
         async inspectKnowledge(id) {
             const knowledge = await asyncAdapter.getKnowledgeMemoryById(id);
@@ -506,10 +1031,10 @@ export function createMemoryManager(config) {
         async reverifyKnowledge(id) {
             const knowledge = await asyncAdapter.getKnowledgeMemoryById(id);
             if (!knowledge) {
-                throw new Error(`Memory validation: knowledge memory ${id} was not found`);
+                throw new ResourceNotFoundError(`Memory validation: knowledge memory ${id} was not found`);
             }
             if (!knowledgeMatchesScope(knowledge, config.scope)) {
-                throw new Error(`Memory validation: knowledge memory ${id} does not belong to the requested scope`);
+                throw new ScopeMismatchError(`Memory validation: knowledge memory ${id} does not belong to the requested scope`);
             }
             const evidence = await asyncAdapter.listKnowledgeEvidenceForKnowledge(id);
             const policy = {
@@ -627,13 +1152,197 @@ export function createMemoryManager(config) {
                 expiredWorkingMemoryCount: report.expiredWorkingMemoryIds.length,
                 retiredKnowledgeCount: report.retiredKnowledgeIds.length,
                 deletedWorkItemCount: report.deletedWorkItemIds.length,
+                deletedAssociationCount: report.deletedAssociationIds.length,
                 reverifiedKnowledgeCount: report.reverifiedKnowledgeIds.length,
                 demotedKnowledgeCount: report.demotedKnowledgeIds.length,
             });
+            await refreshSessionStateProjection();
             return report;
         },
+        async searchEpisodes(options) {
+            if (!config.structuredClient) {
+                throw new ProviderUnavailableError('searchEpisodes requires a structuredClient in MemoryManagerConfig');
+            }
+            return searchEpisodes({
+                adapter: asyncAdapter,
+                scope: config.scope,
+                client: config.structuredClient,
+                telemetry: { logger: config.logger, onEvent },
+            }, options);
+        },
+        async summarizeEpisode(sessionId, options) {
+            if (!config.structuredClient) {
+                throw new ProviderUnavailableError('summarizeEpisode requires a structuredClient in MemoryManagerConfig');
+            }
+            const detailLevel = options?.detailLevel ?? 'overview';
+            // Fetch both active and all session working memories. Partially
+            // compacted sessions have BOTH archived history (covered by working
+            // memory turn ranges) and active turns; a recap built from only the
+            // active fragment silently drops earlier context, so we always merge
+            // archived + active and dedupe by turn id.
+            const activeTurns = await asyncAdapter.getActiveTurns(config.scope, sessionId);
+            const allSessionWm = await asyncAdapter.getWorkingMemoryBySession(sessionId, config.scope);
+            let archivedTurns = [];
+            if (allSessionWm.length > 0) {
+                const minStart = Math.min(...allSessionWm.map((wm) => wm.turn_id_start));
+                const maxEnd = Math.max(...allSessionWm.map((wm) => wm.turn_id_end));
+                archivedTurns = await asyncAdapter.getArchivedTurnRange(sessionId, minStart, maxEnd, config.scope);
+            }
+            const turns = mergeTurnsById(archivedTurns, activeTurns);
+            return summarizeEpisode({
+                adapter: asyncAdapter,
+                scope: config.scope,
+                client: config.structuredClient,
+                telemetry: { logger: config.logger, onEvent },
+            }, { turns, workingMemories: allSessionWm, sessionId, detailLevel, client: config.structuredClient });
+        },
+        async reflect(options) {
+            if (!config.structuredClient) {
+                throw new ProviderUnavailableError('reflect requires a structuredClient in MemoryManagerConfig');
+            }
+            return reflect({
+                adapter: asyncAdapter,
+                scope: config.scope,
+                client: config.structuredClient,
+                telemetry: { logger: config.logger, onEvent },
+            }, options);
+        },
+        async searchCognitive(options) {
+            return searchCognitive(asyncAdapter, config.scope, options);
+        },
+        async getProfile(options) {
+            return getProfile(asyncAdapter, config.scope, options);
+        },
+        async createPlaybook(input) {
+            return asyncAdapter.insertPlaybook({ ...input, ...config.scope });
+        },
+        async createPlaybookFromTask(input) {
+            if (!config.structuredClient) {
+                throw new ProviderUnavailableError('createPlaybookFromTask requires a structuredClient in MemoryManagerConfig');
+            }
+            return createPlaybookFromTask({ adapter: asyncAdapter, scope: config.scope, client: config.structuredClient }, input);
+        },
+        async revisePlaybook(playbookId, newInstructions, revisionReason, sourceSessionId) {
+            return revisePlaybook(asyncAdapter, config.scope, playbookId, newInstructions, revisionReason, sourceSessionId);
+        },
+        async getPlaybook(id) {
+            const playbook = await asyncAdapter.getPlaybookById(id);
+            if (!playbook)
+                return null;
+            const norm = normalizeScope(config.scope);
+            if (playbook.tenant_id !== norm.tenant_id ||
+                playbook.system_id !== norm.system_id ||
+                playbook.workspace_id !== norm.workspace_id ||
+                playbook.collaboration_id !== norm.collaboration_id ||
+                playbook.scope_id !== norm.scope_id) {
+                return null;
+            }
+            return playbook;
+        },
+        async listPlaybooks() {
+            return asyncAdapter.getActivePlaybooks(config.scope);
+        },
+        async searchPlaybooks(query, options) {
+            return findRelevantPlaybooks(asyncAdapter, config.scope, query, options);
+        },
+        async updatePlaybook(id, patch) {
+            const playbook = await asyncAdapter.getPlaybookById(id);
+            if (!playbook)
+                return null;
+            const norm = normalizeScope(config.scope);
+            if (playbook.tenant_id !== norm.tenant_id ||
+                playbook.system_id !== norm.system_id ||
+                playbook.workspace_id !== norm.workspace_id ||
+                playbook.collaboration_id !== norm.collaboration_id ||
+                playbook.scope_id !== norm.scope_id) {
+                return null;
+            }
+            return asyncAdapter.updatePlaybook(id, patch);
+        },
+        async recordPlaybookUse(id) {
+            const playbook = await asyncAdapter.getPlaybookById(id);
+            if (!playbook) {
+                throw new ResourceNotFoundError(`Playbook ${id} not found`);
+            }
+            const norm = normalizeScope(config.scope);
+            if (playbook.tenant_id !== norm.tenant_id ||
+                playbook.system_id !== norm.system_id ||
+                playbook.workspace_id !== norm.workspace_id ||
+                playbook.collaboration_id !== norm.collaboration_id ||
+                playbook.scope_id !== norm.scope_id) {
+                throw new ScopeMismatchError(`Playbook ${id} does not belong to the requested scope`);
+            }
+            return asyncAdapter.recordPlaybookUse(id);
+        },
+        async addAssociation(input) {
+            // Validate source/target IDs are positive integers. Callers (HTTP/MCP)
+            // only check typeof number, so this is the authoritative guard.
+            if (!Number.isInteger(input.source_id) || input.source_id <= 0) {
+                throw new ValidationError(`addAssociation: source_id must be a positive integer, got ${input.source_id}`);
+            }
+            if (!Number.isInteger(input.target_id) || input.target_id <= 0) {
+                throw new ValidationError(`addAssociation: target_id must be a positive integer, got ${input.target_id}`);
+            }
+            if (input.source_kind === input.target_kind && input.source_id === input.target_id) {
+                throw new ValidationError('addAssociation: self-referential associations are not allowed');
+            }
+            // Validate confidence is in [0, 1] when provided.
+            if (input.confidence !== undefined) {
+                if (typeof input.confidence !== 'number' ||
+                    Number.isNaN(input.confidence) ||
+                    input.confidence < 0 ||
+                    input.confidence > 1) {
+                    throw new ValidationError(`addAssociation: confidence must be a number in [0, 1], got ${input.confidence}`);
+                }
+            }
+            // Resolve source and target: both must exist and belong to the caller's
+            // scope. Without this, callers can create orphaned or cross-scope edges,
+            // polluting the graph and weakening isolation guarantees.
+            const norm = normalizeScope(config.scope);
+            await assertAssociationEndpointInScope(asyncAdapter, norm, input.source_kind, input.source_id, 'source');
+            await assertAssociationEndpointInScope(asyncAdapter, norm, input.target_kind, input.target_id, 'target');
+            return asyncAdapter.insertAssociation({
+                ...input,
+                ...norm,
+            });
+        },
+        async getAssociations(kind, id) {
+            const [from, to] = await Promise.all([
+                asyncAdapter.getAssociationsFrom(kind, id, config.scope),
+                asyncAdapter.getAssociationsTo(kind, id, config.scope),
+            ]);
+            return { from, to };
+        },
+        async traverseAssociations(kind, id, options) {
+            return traverseAssociations(asyncAdapter, config.scope, kind, id, options);
+        },
+        async removeAssociation(id) {
+            // Scope safety: verify the association belongs to the current scope by
+            // checking the association row's own scope columns. Scanning through
+            // active knowledge/playbooks/WM/work items would incorrectly reject
+            // associations attached to archived/expired/orphaned nodes, leaving
+            // stale edges permanently in the graph.
+            if (!Number.isInteger(id) || id <= 0) {
+                throw new ValidationError(`removeAssociation: id must be a positive integer, got ${id}`);
+            }
+            const association = await asyncAdapter.getAssociationById(id);
+            if (!association) {
+                throw new ResourceNotFoundError(`Association ${id} not found`);
+            }
+            const norm = normalizeScope(config.scope);
+            if (association.tenant_id !== norm.tenant_id ||
+                association.system_id !== norm.system_id ||
+                association.workspace_id !== norm.workspace_id ||
+                association.collaboration_id !== norm.collaboration_id ||
+                association.scope_id !== norm.scope_id) {
+                throw new ScopeMismatchError(`Association ${id} not found in the current scope`);
+            }
+            await asyncAdapter.deleteAssociation(id);
+        },
         async close() {
-            await asyncAdapter.close();
+            if (config.closeAdapter !== false) {
+                await asyncAdapter.close();
+            }
         },
     };
 }