ai-memory-layer 2.0.1 → 3.0.0

package/dist/core/context.js

@@ -3,6 +3,70 @@ import { DEFAULT_CONTEXT_POLICY } from '../contracts/policy.js';
 import { estimateTokens } from './tokens.js';
 import { emitMemoryEvent } from './telemetry.js';
 import { getLineageScore, rankKnowledge } from './retrieval.js';
+const DEFAULT_MAX_ASSOCIATION_SEED_ITEMS = 8;
+const DEFAULT_MAX_ASSOCIATED_KNOWLEDGE_ITEMS = 12;
+const DEFAULT_RECENT_OUTPUT_LIMIT = 3;
+const BLOCKER_PATTERN = /\b(blocked|blocker|waiting on|pending|stuck|cannot proceed|can't proceed)\b/i;
+const ASSUMPTION_PATTERN = /\b(assume|assuming|assumption|likely|probably)\b/i;
+const DECISION_PATTERN = /\b(decide|decision|choose|choice|whether|should we|need to determine)\b/i;
+const TOOL_PATTERN = /\b(?:tool|command|script|query|search|fetch|deploy|build|test|lint|run)\b/i;
+function matchesVisibility(visibilityClass, item, scope) {
+    const left = normalizeScope(item);
+    const right = normalizeScope(scope);
+    if (left.tenant_id !== right.tenant_id)
+        return false;
+    switch (visibilityClass) {
+        case 'tenant':
+            return true;
+        case 'workspace':
+            return left.workspace_id === right.workspace_id;
+        case 'shared_collaboration':
+            return (left.workspace_id === right.workspace_id &&
+                left.collaboration_id.length > 0 &&
+                left.collaboration_id === right.collaboration_id);
+        case 'private':
+        default:
+            return (left.system_id === right.system_id &&
+                left.workspace_id === right.workspace_id &&
+                left.collaboration_id === right.collaboration_id &&
+                left.scope_id === right.scope_id);
+    }
+}
+function isVisibilityAllowed(visibilityClass, item, scope, view) {
+    if (!matchesVisibility(visibilityClass, item, scope)) {
+        return false;
+    }
+    if (view === 'local_only') {
+        return visibilityClass === 'private';
+    }
+    if (view === 'local_plus_shared_collaboration') {
+        return visibilityClass === 'private' || visibilityClass === 'shared_collaboration';
+    }
+    if (view === 'workspace_shared') {
+        return (visibilityClass === 'private' ||
+            visibilityClass === 'shared_collaboration' ||
+            visibilityClass === 'workspace');
+    }
+    return (visibilityClass === 'private' ||
+        visibilityClass === 'shared_collaboration' ||
+        visibilityClass === 'workspace' ||
+        visibilityClass === 'tenant');
+}
+export function resolveVisibleKnowledge(items, scope, view) {
+    return items.filter((item) => isVisibilityAllowed(item.visibility_class, item, scope, view));
+}
+export function resolveVisibleWorkItems(items, scope, view) {
+    return items.filter((item) => isVisibilityAllowed(item.visibility_class, item, scope, view));
+}
+export function resolveVisiblePlaybooks(items, scope, view) {
+    return items.filter((item) => isVisibilityAllowed(item.visibility_class, item, scope, view));
+}
+export function resolveVisibleWorkClaims(items, scope, view) {
+    return items.filter((item) => isVisibilityAllowed(item.visibility_class, item, scope, view));
+}
+export function resolveVisibleHandoffs(items, scope, view) {
+    return items.filter((item) => isVisibilityAllowed(item.visibility_class, item, scope, view));
+}
 function resolveContextPolicy(options) {
     const base = {
         ...DEFAULT_CONTEXT_POLICY,
@@ -82,7 +146,111 @@ function deriveUnresolvedWork(workingMemory, activeTurns, relevantKnowledge, wor
     }
     return [...unresolved];
 }
-function computeContextTokenEstimate(activeTurns, workingMemory, relevantKnowledge, recentSummaries, tokenEstimator = estimateTokens) {
+function compactSnippet(text, maxLength = 160) {
+    const normalized = text.replace(/\s+/g, ' ').trim();
+    if (normalized.length <= maxLength)
+        return normalized;
+    return `${normalized.slice(0, maxLength - 3).trimEnd()}...`;
+}
+function collectSignalSnippets(values, pattern, limit = 4) {
+    const matches = new Set();
+    for (const value of values) {
+        if (matches.size >= limit)
+            break;
+        if (pattern.test(value)) {
+            matches.add(compactSnippet(value));
+        }
+    }
+    return [...matches];
+}
+function deriveSessionState(workingMemory, activeTurns, activeObjectives, contextWorkItems, recentSummaries, currentObjective) {
+    const recentTexts = [
+        ...activeTurns.slice(-6).map((turn) => turn.content),
+        workingMemory?.summary ?? '',
+        ...recentSummaries.slice(0, 2).map((summary) => summary.summary),
+    ].filter((value) => value.trim().length > 0);
+    const blockers = [
+        ...contextWorkItems
+            .filter((item) => item.status === 'blocked')
+            .map((item) => compactSnippet(item.title)),
+        ...collectSignalSnippets(recentTexts, BLOCKER_PATTERN),
+    ];
+    const assumptions = collectSignalSnippets(recentTexts, ASSUMPTION_PATTERN);
+    const pendingDecisions = [
+        ...collectSignalSnippets(recentTexts, DECISION_PATTERN),
+        ...activeObjectives
+            .filter((item) => DECISION_PATTERN.test(item.title))
+            .map((item) => compactSnippet(item.title)),
+    ];
+    const activeTools = [
+        ...new Set([
+            ...activeTurns
+                .map((turn) => turn.actor)
+                .filter((actor) => actor.length > 0 && !['user', 'assistant', 'system'].includes(actor)),
+            ...activeTurns
+                .filter((turn) => TOOL_PATTERN.test(turn.content))
+                .map((turn) => compactSnippet(turn.content, 80)),
+        ]),
+    ].slice(0, 6);
+    const recentOutputs = activeTurns
+        .filter((turn) => turn.role !== 'user')
+        .slice(-DEFAULT_RECENT_OUTPUT_LIMIT)
+        .map((turn) => compactSnippet(turn.content));
+    const updatedAt = Math.max(0, ...activeTurns.map((turn) => turn.created_at), ...contextWorkItems.map((item) => item.updated_at), ...(workingMemory ? [workingMemory.created_at] : []), ...recentSummaries.map((summary) => summary.created_at));
+    return {
+        currentObjective,
+        blockers: [...new Set(blockers)].slice(0, 6),
+        assumptions: [...new Set(assumptions)].slice(0, 6),
+        pendingDecisions: [...new Set(pendingDecisions)].slice(0, 6),
+        activeTools,
+        recentOutputs,
+        updatedAt,
+    };
+}
+export function buildDerivedShortTermState(input) {
+    const workingMemory = [...input.workingMemoryCandidates]
+        .sort((a, b) => b.id - a.id)[0] ?? null;
+    const recentSummaries = input.workingMemoryCandidates
+        .filter((summary) => summary.id !== workingMemory?.id)
+        .slice(0, input.maxRecentSummaries ?? DEFAULT_CONTEXT_POLICY.maxRecentSummaries);
+    const activeObjectives = input.contextWorkItems.filter((item) => item.kind === 'objective');
+    const currentObjective = deriveCurrentObjective(workingMemory, input.activeTurns);
+    return {
+        workingMemory,
+        recentSummaries,
+        activeObjectives,
+        currentObjective,
+        activeState: deriveActiveState(workingMemory, input.activeTurns),
+        // The session-state projection intentionally computes a fast-resume subset
+        // even when relevantKnowledge is omitted by projection refresh.
+        unresolvedWork: deriveUnresolvedWork(workingMemory, input.activeTurns, input.relevantKnowledge ?? [], input.contextWorkItems),
+        sessionState: deriveSessionState(workingMemory, input.activeTurns, activeObjectives, input.contextWorkItems, recentSummaries, currentObjective),
+    };
+}
+function isWorkItemActiveAt(item, asOf) {
+    return item.created_at <= asOf && !(item.status === 'done' && item.updated_at <= asOf);
+}
+export async function getContextWorkItems(adapter, scope, asOf, level) {
+    if (asOf == null) {
+        return level && level !== 'scope'
+            ? adapter.getActiveWorkItemsCrossScope(scope, level)
+            : adapter.getActiveWorkItems(scope);
+    }
+    const workItems = level && level !== 'scope'
+        ? await adapter.getWorkItemsByTimeRangeCrossScope(scope, level, { end_at: asOf })
+        : await adapter.getWorkItemsByTimeRange(scope, { end_at: asOf });
+    return workItems
+        .filter((item) => isWorkItemActiveAt(item, asOf))
+        .sort((a, b) => b.updated_at - a.updated_at || b.created_at - a.created_at || b.id - a.id);
+}
+export function resolveContextScopeLevel(crossScopeLevel, view) {
+    if (view === 'operator_supervisor')
+        return crossScopeLevel ?? 'tenant';
+    if (view && view !== 'local_only')
+        return crossScopeLevel ?? 'workspace';
+    return crossScopeLevel;
+}
+function computeContextTokenEstimate(activeTurns, workingMemory, relevantKnowledge, recentSummaries, tokenEstimator = estimateTokens, playbooks = [], associatedKnowledge = []) {
     const turnTokens = activeTurns.reduce((acc, turn) => acc + turn.token_estimate, 0);
     const workingTokens = workingMemory
         ? tokenEstimator(workingMemory.summary) +
@@ -91,7 +259,9 @@ function computeContextTokenEstimate(activeTurns, workingMemory, relevantKnowled
         : 0;
     const knowledgeTokens = relevantKnowledge.reduce((acc, knowledge) => acc + tokenEstimator(knowledge.fact), 0);
     const summaryTokens = recentSummaries.reduce((acc, summary) => acc + tokenEstimator(summary.summary), 0);
-    return turnTokens + workingTokens + knowledgeTokens + summaryTokens;
+    const playbookTokens = playbooks.reduce((acc, pb) => acc + tokenEstimator(pb.title) + tokenEstimator(pb.description) + tokenEstimator(pb.instructions), 0);
+    const associatedTokens = associatedKnowledge.reduce((acc, knowledge) => acc + tokenEstimator(knowledge.fact), 0);
+    return turnTokens + workingTokens + knowledgeTokens + summaryTokens + playbookTokens + associatedTokens;
 }
 function dropLowestPriorityTurn(activeTurns) {
     if (activeTurns.length === 0)
@@ -208,26 +378,33 @@ export async function buildMemoryContext(adapter, scope, options) {
     const policy = resolveContextPolicy(options);
     const tokenEstimator = options?.tokenEstimator ?? estimateTokens;
     const asOf = options?.asOf;
+    const view = options?.view;
+    const effectiveScopeLevel = resolveContextScopeLevel(options?.crossScopeLevel, view);
     let activeTurns = await adapter.getActiveTurns(normalizedScope, options?.sessionId);
     if (asOf != null) {
         activeTurns = activeTurns.filter((turn) => turn.created_at <= asOf);
     }
-    const activeObjectives = (await adapter.getActiveWorkItems(normalizedScope)).filter((item) => item.kind === 'objective');
+    const contextWorkItems = view
+        ? resolveVisibleWorkItems(await getContextWorkItems(adapter, normalizedScope, asOf, effectiveScopeLevel), normalizedScope, view)
+        : await getContextWorkItems(adapter, normalizedScope, asOf, effectiveScopeLevel);
     const workingMemoryCandidates = await adapter.getActiveWorkingMemory(normalizedScope, options?.sessionId);
-    const workingMemory = [...workingMemoryCandidates]
-        .filter((item) => asOf == null || item.created_at <= asOf)
-        .sort((a, b) => b.id - a.id)[0] ?? null;
     const allWorkingMemory = workingMemoryCandidates.filter((item) => asOf == null || item.created_at <= asOf);
-    const recentSummaries = allWorkingMemory
-        .filter((summary) => summary.id !== workingMemory?.id)
-        .slice(0, policy.maxRecentSummaries);
-    const activeKnowledge = options?.crossScopeLevel
-        ? await adapter.getActiveKnowledgeCrossScope(normalizedScope, options.crossScopeLevel)
+    const initialShortTermState = buildDerivedShortTermState({
+        activeTurns,
+        workingMemoryCandidates: allWorkingMemory,
+        contextWorkItems,
+        maxRecentSummaries: policy.maxRecentSummaries,
+    });
+    const { activeObjectives, currentObjective, recentSummaries, workingMemory, } = initialShortTermState;
+    const activeKnowledge = effectiveScopeLevel && effectiveScopeLevel !== 'scope'
+        ? await adapter.getActiveKnowledgeCrossScope(normalizedScope, effectiveScopeLevel)
         : await adapter.getActiveKnowledgeMemory(normalizedScope);
-    const temporalKnowledge = activeKnowledge.filter((item) => asOf == null || item.created_at <= asOf);
+    const temporalKnowledge = view
+        ? resolveVisibleKnowledge(activeKnowledge.filter((item) => asOf == null || item.created_at <= asOf), normalizedScope, view)
+        : activeKnowledge.filter((item) => asOf == null || item.created_at <= asOf);
     const lexicalRanks = options?.relevanceQuery
-        ? normalizeLexicalRanks(options.crossScopeLevel
-            ? await adapter.searchKnowledgeCrossScope(normalizedScope, options.crossScopeLevel, options.relevanceQuery, {
+        ? normalizeLexicalRanks(effectiveScopeLevel && effectiveScopeLevel !== 'scope'
+            ? await adapter.searchKnowledgeCrossScope(normalizedScope, effectiveScopeLevel, options.relevanceQuery, {
                 limit: policy.maxKnowledgeItems * 2,
                 activeOnly: true,
             })
@@ -239,8 +416,8 @@ export async function buildMemoryContext(adapter, scope, options) {
     let semanticRanks = new Map();
     if (options?.embeddingAdapter && options.queryVector) {
         try {
-            const semanticResults = options.crossScopeLevel
-                ? await options.embeddingAdapter.findSimilarCrossScope(normalizedScope, options.crossScopeLevel, options.queryVector, {
+            const semanticResults = effectiveScopeLevel && effectiveScopeLevel !== 'scope'
+                ? await options.embeddingAdapter.findSimilarCrossScope(normalizedScope, effectiveScopeLevel, options.queryVector, {
                     limit: policy.maxKnowledgeItems * 2,
                     minSimilarity: policy.semanticMinSimilarity,
                 })
@@ -256,60 +433,300 @@ export async function buildMemoryContext(adapter, scope, options) {
             });
         }
     }
-    const scopedKnowledge = options?.crossScopeLevel && options.crossScopeLevel !== 'scope'
-        ? temporalKnowledge.filter((item) => item.scope_id === normalizedScope.scope_id ||
-            (normalizedScope.collaboration_id.length > 0 &&
-                item.collaboration_id === normalizedScope.collaboration_id) ||
-            getLineageScore(normalizedScope.scope_id, item.scope_id) >= policy.minimumLineageScore)
-        : temporalKnowledge;
+    const scopedKnowledge = view && view !== 'local_only'
+        ? temporalKnowledge
+        : effectiveScopeLevel && effectiveScopeLevel !== 'scope'
+            ? temporalKnowledge.filter((item) => item.scope_id === normalizedScope.scope_id ||
+                (normalizedScope.collaboration_id.length > 0 &&
+                    item.collaboration_id === normalizedScope.collaboration_id) ||
+                getLineageScore(normalizedScope.scope_id, item.scope_id) >= policy.minimumLineageScore)
+            : temporalKnowledge;
     const relevanceTexts = [
         options?.relevanceQuery ?? '',
         workingMemory?.summary ?? '',
         ...activeObjectives.map((item) => item.title),
     ].filter((value) => value.trim().length > 0);
-    const candidates = buildCandidates(scopedKnowledge, lexicalRanks, semanticRanks, policy, normalizedScope, relevanceTexts, options?.crossScopeLevel != null && options.crossScopeLevel !== 'scope');
+    const candidates = buildCandidates(scopedKnowledge, lexicalRanks, semanticRanks, policy, normalizedScope, relevanceTexts, effectiveScopeLevel != null && effectiveScopeLevel !== 'scope');
     const trustedCoreClasses = new Set(['identity', 'constraint', 'preference']);
-    let trustedCoreMemory = selectKnowledge(candidates.filter((candidate) => candidate.item.knowledge_state === 'trusted' &&
-        trustedCoreClasses.has(candidate.item.knowledge_class)), policy, 'trusted_core', Math.min(policy.trustedCoreLimit, Math.max(3, Math.floor(policy.maxKnowledgeItems / 2)))).relevantKnowledge;
+    const trustedCoreSelection = selectKnowledge(candidates.filter((candidate) => candidate.item.knowledge_state === 'trusted' &&
+        trustedCoreClasses.has(candidate.item.knowledge_class)), policy, 'trusted_core', Math.min(policy.trustedCoreLimit, Math.max(3, Math.floor(policy.maxKnowledgeItems / 2))));
+    let trustedCoreMemory = trustedCoreSelection.relevantKnowledge;
     const trustedCoreIds = new Set(trustedCoreMemory.map((item) => item.id));
-    let taskRelevantKnowledge = selectKnowledge(candidates.filter((candidate) => candidate.item.knowledge_state === 'trusted' && !trustedCoreIds.has(candidate.item.id)), policy, 'task_relevant', Math.min(policy.taskRelevantLimit, Math.max(0, policy.maxKnowledgeItems - trustedCoreMemory.length))).relevantKnowledge;
-    const provisionalKnowledge = selectKnowledge(candidates.filter((candidate) => candidate.item.knowledge_state === 'provisional'), policy, 'provisional', 4).relevantKnowledge;
-    const disputedKnowledge = selectKnowledge(candidates.filter((candidate) => candidate.item.knowledge_state === 'disputed'), policy, 'disputed', 4).relevantKnowledge;
+    const taskRelevantSelection = selectKnowledge(candidates.filter((candidate) => candidate.item.knowledge_state === 'trusted' && !trustedCoreIds.has(candidate.item.id)), policy, 'task_relevant', Math.min(policy.taskRelevantLimit, Math.max(0, policy.maxKnowledgeItems - trustedCoreMemory.length)));
+    let taskRelevantKnowledge = taskRelevantSelection.relevantKnowledge;
+    const provisionalSelection = selectKnowledge(candidates.filter((candidate) => candidate.item.knowledge_state === 'provisional'), policy, 'provisional', 4);
+    const provisionalKnowledge = provisionalSelection.relevantKnowledge;
+    const disputedSelection = selectKnowledge(candidates.filter((candidate) => candidate.item.knowledge_state === 'disputed'), policy, 'disputed', 4);
+    const disputedKnowledge = disputedSelection.relevantKnowledge;
     let relevantKnowledge = [...trustedCoreMemory, ...taskRelevantKnowledge];
     let knowledgeSelectionReasons = [
-        ...selectKnowledge(candidates.filter((candidate) => candidate.item.knowledge_state === 'trusted' &&
-            trustedCoreClasses.has(candidate.item.knowledge_class)), policy, 'trusted_core', trustedCoreMemory.length).knowledgeSelectionReasons,
-        ...selectKnowledge(candidates.filter((candidate) => candidate.item.knowledge_state === 'trusted' && !trustedCoreIds.has(candidate.item.id)), policy, 'task_relevant', taskRelevantKnowledge.length).knowledgeSelectionReasons,
-        ...selectKnowledge(candidates.filter((candidate) => candidate.item.knowledge_state === 'provisional'), policy, 'provisional', provisionalKnowledge.length).knowledgeSelectionReasons,
-        ...selectKnowledge(candidates.filter((candidate) => candidate.item.knowledge_state === 'disputed'), policy, 'disputed', disputedKnowledge.length).knowledgeSelectionReasons,
+        ...trustedCoreSelection.knowledgeSelectionReasons,
+        ...taskRelevantSelection.knowledgeSelectionReasons,
+        ...provisionalSelection.knowledgeSelectionReasons,
+        ...disputedSelection.knowledgeSelectionReasons,
     ];
+    const initiallySelectedIds = new Set(relevantKnowledge.map((item) => item.id));
+    const excludedKnowledge = candidates
+        .filter((candidate) => !initiallySelectedIds.has(candidate.item.id))
+        .map((candidate) => ({
+        knowledgeMemoryId: candidate.item.id,
+        reason: 'not_selected',
+        detail: `excluded:${candidate.item.knowledge_state}:${candidate.item.knowledge_class}`,
+    }));
+    const scopedKnowledgeById = new Map(scopedKnowledge.map((item) => [item.id, item]));
+    let relevantPlaybooks = options?.relevanceQuery
+        ? (effectiveScopeLevel && effectiveScopeLevel !== 'scope'
+            ? await adapter.searchPlaybooksCrossScope(normalizedScope, effectiveScopeLevel, options.relevanceQuery, { limit: 3, activeOnly: true })
+            : await adapter.searchPlaybooks(normalizedScope, options.relevanceQuery, {
+                limit: 3,
+                activeOnly: true,
+            })).map((hit) => hit.item)
+        : [];
+    relevantPlaybooks = view
+        ? resolveVisiblePlaybooks(relevantPlaybooks, normalizedScope, view)
+        : relevantPlaybooks;
+    // Single-hop association expansion via supports + related_to edges
+    const associationMinConfidence = options?.associationMinConfidence ?? 0.3;
+    const maxAssociationSeedItems = options?.maxAssociationSeedItems ?? DEFAULT_MAX_ASSOCIATION_SEED_ITEMS;
+    const maxAssociatedKnowledgeItems = options?.maxAssociatedKnowledgeItems ?? DEFAULT_MAX_ASSOCIATED_KNOWLEDGE_ITEMS;
+    const selectedIds = new Set(relevantKnowledge.map((k) => k.id));
+    const associatedKnowledge = [];
+    const associationTrace = {
+        seedKnowledgeIds: relevantKnowledge.slice(0, maxAssociationSeedItems).map((knowledge) => knowledge.id),
+        candidateKnowledgeIds: [],
+        includedKnowledgeIds: [],
+        truncatedKnowledgeIds: [],
+        maxSeedKnowledgeItems: maxAssociationSeedItems,
+        maxAssociatedKnowledgeItems,
+    };
+    if (relevantKnowledge.length > 0) {
+        const associationSeeds = relevantKnowledge.slice(0, maxAssociationSeedItems);
+        const associationResults = await Promise.all(associationSeeds.map(async (knowledge) => {
+            const associationScope = normalizeScope(knowledge);
+            const [from, to] = await Promise.all([
+                adapter.getAssociationsFrom('knowledge', knowledge.id, associationScope),
+                adapter.getAssociationsTo('knowledge', knowledge.id, associationScope),
+            ]);
+            return { from, to };
+        }));
+        const expandScores = new Map();
+        // Outbound: current node is source, neighbor is target
+        for (const { from: assocs } of associationResults) {
+            for (const a of assocs) {
+                if ((a.association_type === 'supports' || a.association_type === 'related_to') &&
+                    a.target_kind === 'knowledge' &&
+                    a.confidence >= associationMinConfidence &&
+                    !selectedIds.has(a.target_id)) {
+                    expandScores.set(a.target_id, Math.max(expandScores.get(a.target_id) ?? 0, a.confidence));
+                }
+            }
+        }
+        // Inbound: current node is target, neighbor is source
+        for (const { to: assocs } of associationResults) {
+            for (const a of assocs) {
+                if ((a.association_type === 'supports' || a.association_type === 'related_to') &&
+                    a.source_kind === 'knowledge' &&
+                    a.confidence >= associationMinConfidence &&
+                    !selectedIds.has(a.source_id)) {
+                    expandScores.set(a.source_id, Math.max(expandScores.get(a.source_id) ?? 0, a.confidence));
+                }
+            }
+        }
+        const candidateAssociationIds = [...expandScores.entries()]
+            .sort((a, b) => b[1] - a[1] || a[0] - b[0])
+            .map(([id]) => id);
+        associationTrace.candidateKnowledgeIds = candidateAssociationIds;
+        if (candidateAssociationIds.length > maxAssociatedKnowledgeItems) {
+            associationTrace.truncatedKnowledgeIds = candidateAssociationIds.slice(maxAssociatedKnowledgeItems);
+        }
+        for (const targetId of candidateAssociationIds.slice(0, maxAssociatedKnowledgeItems)) {
+            const knowledge = scopedKnowledgeById.get(targetId);
+            if (knowledge && knowledge.knowledge_state !== 'retired' && knowledge.knowledge_state !== 'superseded') {
+                associatedKnowledge.push(knowledge);
+            }
+        }
+        associationTrace.includedKnowledgeIds = associatedKnowledge.map((knowledge) => knowledge.id);
+    }
     let trimmedSummaries = [...recentSummaries];
-    let tokenEstimate = computeContextTokenEstimate(activeTurns, workingMemory, relevantKnowledge, trimmedSummaries, tokenEstimator);
+    let trimmedAssociated = [...associatedKnowledge];
+    const tokenTrimTrace = {
+        initialTokenEstimate: 0,
+        finalTokenEstimate: 0,
+        droppedTurnIds: [],
+        droppedSummaryIds: [],
+        droppedPlaybookIds: [],
+        droppedAssociatedKnowledgeIds: [],
+        droppedKnowledgeIds: [],
+    };
+    function recomputeTokens() {
+        return computeContextTokenEstimate(activeTurns, workingMemory, relevantKnowledge, trimmedSummaries, tokenEstimator, relevantPlaybooks, trimmedAssociated);
+    }
+    let tokenEstimate = recomputeTokens();
+    tokenTrimTrace.initialTokenEstimate = tokenEstimate;
     while (tokenEstimate > policy.tokenBudget && activeTurns.length > 0) {
+        const beforeIds = new Set(activeTurns.map((turn) => turn.id));
         activeTurns = dropLowestPriorityTurn(activeTurns);
-        tokenEstimate = computeContextTokenEstimate(activeTurns, workingMemory, relevantKnowledge, trimmedSummaries, tokenEstimator);
+        const afterIds = new Set(activeTurns.map((turn) => turn.id));
+        for (const id of beforeIds) {
+            if (!afterIds.has(id)) {
+                tokenTrimTrace.droppedTurnIds.push(id);
+            }
+        }
+        tokenEstimate = recomputeTokens();
     }
     while (tokenEstimate > policy.tokenBudget && trimmedSummaries.length > 0) {
+        const removed = trimmedSummaries[trimmedSummaries.length - 1];
+        if (removed)
+            tokenTrimTrace.droppedSummaryIds.push(removed.id);
         trimmedSummaries = trimmedSummaries.slice(0, -1);
-        tokenEstimate = computeContextTokenEstimate(activeTurns, workingMemory, relevantKnowledge, trimmedSummaries, tokenEstimator);
+        tokenEstimate = recomputeTokens();
+    }
+    // Trim playbooks (procedural guidance) before associated knowledge or core
+    // relevant knowledge. A few large playbooks can otherwise push the context
+    // over budget after every other lower-priority category has been trimmed.
+    // Drop the largest playbook first so we shed bytes aggressively rather
+    // than dropping smaller playbooks that may still be useful alongside a
+    // single outsized offender.
+    while (tokenEstimate > policy.tokenBudget && relevantPlaybooks.length > 0) {
+        const sizes = relevantPlaybooks.map((pb) => tokenEstimator(`${pb.title}\n${pb.description}\n${pb.instructions}`));
+        let worstIdx = 0;
+        for (let i = 1; i < sizes.length; i++) {
+            if (sizes[i] > sizes[worstIdx])
+                worstIdx = i;
+        }
+        const removed = relevantPlaybooks[worstIdx];
+        if (removed)
+            tokenTrimTrace.droppedPlaybookIds.push(removed.id);
+        relevantPlaybooks = relevantPlaybooks.filter((_, i) => i !== worstIdx);
+        tokenEstimate = recomputeTokens();
+    }
+    // Trim associated knowledge before core relevant knowledge
+    while (tokenEstimate > policy.tokenBudget && trimmedAssociated.length > 0) {
+        const removed = trimmedAssociated[trimmedAssociated.length - 1];
+        if (removed)
+            tokenTrimTrace.droppedAssociatedKnowledgeIds.push(removed.id);
+        trimmedAssociated = trimmedAssociated.slice(0, -1);
+        tokenEstimate = recomputeTokens();
     }
     while (tokenEstimate > policy.tokenBudget && relevantKnowledge.length > 0) {
+        const removed = relevantKnowledge[relevantKnowledge.length - 1];
+        if (removed) {
+            tokenTrimTrace.droppedKnowledgeIds.push(removed.id);
+            excludedKnowledge.push({
+                knowledgeMemoryId: removed.id,
+                reason: 'token_budget',
+                detail: 'trimmed:token_budget',
+            });
+        }
         relevantKnowledge = relevantKnowledge.slice(0, -1);
         trustedCoreMemory = trustedCoreMemory.filter((item) => relevantKnowledge.some((entry) => entry.id === item.id));
         taskRelevantKnowledge = taskRelevantKnowledge.filter((item) => relevantKnowledge.some((entry) => entry.id === item.id));
         const retainedIds = new Set(relevantKnowledge.map((item) => item.id));
         knowledgeSelectionReasons = knowledgeSelectionReasons.filter((entry) => retainedIds.has(entry.knowledgeMemoryId));
-        tokenEstimate = computeContextTokenEstimate(activeTurns, workingMemory, relevantKnowledge, trimmedSummaries, tokenEstimator);
+        tokenEstimate = recomputeTokens();
     }
+    tokenTrimTrace.finalTokenEstimate = tokenEstimate;
     if (policy.touchSelectedKnowledge) {
-        for (const knowledge of relevantKnowledge) {
-            await adapter.touchKnowledgeMemory(knowledge.id);
-        }
+        await adapter.touchKnowledgeMemories(relevantKnowledge.map((knowledge) => knowledge.id));
     }
-    const currentObjective = deriveCurrentObjective(workingMemory, activeTurns);
-    const activeState = deriveActiveState(workingMemory, activeTurns);
-    const allWorkItems = await adapter.getActiveWorkItems(normalizedScope);
-    const unresolvedWork = deriveUnresolvedWork(workingMemory, activeTurns, relevantKnowledge, allWorkItems);
+    const rawWorkClaims = options?.includeCoordinationState || view
+        ? await (effectiveScopeLevel && effectiveScopeLevel !== 'scope'
+            ? adapter.listWorkClaimsCrossScope(normalizedScope, effectiveScopeLevel, {
+                actor: options?.viewer
+                    ? {
+                        actor_kind: options.viewer.actor_kind,
+                        actor_id: options.viewer.actor_id,
+                    }
+                    : undefined,
+            })
+            : adapter.listWorkClaims(normalizedScope, {
+                actor: options?.viewer
+                    ? {
+                        actor_kind: options.viewer.actor_kind,
+                        actor_id: options.viewer.actor_id,
+                    }
+                    : undefined,
+            }))
+        : [];
+    const workClaims = view
+        ? resolveVisibleWorkClaims(rawWorkClaims, normalizedScope, view)
+        : rawWorkClaims;
+    const rawHandoffs = options?.includeCoordinationState || view
+        ? await (effectiveScopeLevel && effectiveScopeLevel !== 'scope'
+            ? adapter.listHandoffsCrossScope(normalizedScope, effectiveScopeLevel, {
+                actor: options?.viewer
+                    ? {
+                        actor_kind: options.viewer.actor_kind,
+                        actor_id: options.viewer.actor_id,
+                    }
+                    : undefined,
+            })
+            : adapter.listHandoffs(normalizedScope, {
+                actor: options?.viewer
+                    ? {
+                        actor_kind: options.viewer.actor_kind,
+                        actor_id: options.viewer.actor_id,
+                    }
+                    : undefined,
+            }))
+        : [];
+    const handoffs = view ? resolveVisibleHandoffs(rawHandoffs, normalizedScope, view) : rawHandoffs;
+    const coordinationState = options?.includeCoordinationState || view
+        ? {
+            ownedClaims: options?.viewer
+                ? workClaims.filter((claim) => claim.actor.actor_kind === options.viewer.actor_kind &&
+                    claim.actor.actor_id === options.viewer.actor_id &&
+                    claim.status === 'active')
+                : [],
+            pendingInboundHandoffs: options?.viewer
+                ? handoffs.filter((handoff) => handoff.status === 'pending' &&
+                    handoff.to_actor.actor_kind === options.viewer.actor_kind &&
+                    handoff.to_actor.actor_id === options.viewer.actor_id)
+                : [],
+            pendingOutboundHandoffs: options?.viewer
+                ? handoffs.filter((handoff) => handoff.status === 'pending' &&
+                    handoff.from_actor.actor_kind === options.viewer.actor_kind &&
+                    handoff.from_actor.actor_id === options.viewer.actor_id)
+                : [],
+            sharedWorkItems: contextWorkItems.filter((item) => item.visibility_class !== 'private'),
+        }
+        : null;
+    const shortTermState = buildDerivedShortTermState({
+        activeTurns,
+        workingMemoryCandidates: allWorkingMemory,
+        contextWorkItems,
+        relevantKnowledge,
+        maxRecentSummaries: policy.maxRecentSummaries,
+    });
+    const { activeState, sessionState: derivedSessionState, unresolvedWork, } = shortTermState;
+    const projectedSessionState = asOf == null && options?.sessionId
+        ? await adapter.getSessionState(normalizedScope, options.sessionId)
+        : null;
+    const sessionState = projectedSessionState && projectedSessionState.updatedAt >= derivedSessionState.updatedAt
+        ? {
+            currentObjective: projectedSessionState.currentObjective,
+            blockers: projectedSessionState.blockers,
+            assumptions: projectedSessionState.assumptions,
+            pendingDecisions: projectedSessionState.pendingDecisions,
+            activeTools: projectedSessionState.activeTools,
+            recentOutputs: projectedSessionState.recentOutputs,
+            updatedAt: projectedSessionState.updatedAt,
+        }
+        : derivedSessionState;
+    const debugTrace = {
+        scope: {
+            normalizedScope,
+            scopeSource: effectiveScopeLevel != null && effectiveScopeLevel !== 'scope'
+                ? 'cross_scope'
+                : 'local',
+            scopeLevel: effectiveScopeLevel ?? 'scope',
+            asOf: asOf ?? null,
+        },
+        selectedKnowledge: knowledgeSelectionReasons,
+        excludedKnowledge,
+        associationExpansion: associationTrace,
+        tokenTrimming: tokenTrimTrace,
+    };
     emitMemoryEvent('context_assembly', normalizedScope, options, Date.now() - startedAt, {
         mode: policy.mode,
         activeTurnCount: activeTurns.length,
@@ -318,10 +735,14 @@ export async function buildMemoryContext(adapter, scope, options) {
         recentSummaryCount: trimmedSummaries.length,
         tokenEstimate,
         relevanceQuery: options?.relevanceQuery ?? null,
-        crossScopeLevel: options?.crossScopeLevel ?? 'scope',
+        crossScopeLevel: effectiveScopeLevel ?? 'scope',
         currentObjective,
         unresolvedWorkCount: unresolvedWork.length,
+        sessionState,
         selectionReasons: knowledgeSelectionReasons,
+        excludedKnowledgeCount: excludedKnowledge.length,
+        associationExpansion: associationTrace,
+        tokenTrimming: tokenTrimTrace,
     });
     return {
         mode: policy.mode,
@@ -335,10 +756,15 @@ export async function buildMemoryContext(adapter, scope, options) {
         durableKnowledge: trustedCoreMemory,
         recentSummaries: trimmedSummaries,
         currentObjective,
+        sessionState,
         activeObjectives,
         activeState,
+        coordinationState,
+        relevantPlaybooks,
+        associatedKnowledge: trimmedAssociated,
         unresolvedWork,
         knowledgeSelectionReasons,
+        debugTrace,
         tokenEstimate,
     };
 }