@muxoai/platform 1.4.2 → 1.4.3

package/dist/engine.js

@@ -1,8 +1,9 @@
 import crypto from "node:crypto";
 import { isStripeProjectsExclusiveProvider, normalizeStripeProjectsProviderSlug, wrapMuxoConnectUrl, } from "./composio-catalog.js";
 import { APPROVED_PLAN_STATUSES, approvalRequiredError, buildApprovalHumanHandoff, buildApprovalUrl, buildOAuthHumanHandoff, clampWaitSeconds, looksLikeToolSlug, unknownToolError, } from "./mcp-schema.js";
-import { completeCloudProvisioningWorkflow, createCloudProvisioningWorkflow, normalizeWorkflowTarget, workflowNotFoundError, } from "./durable-workflow.js";
+import { completeCloudProvisioningWorkflow, createCloudProvisioningWorkflow, exportTemporalEventHistory, normalizeWorkflowTarget, rollbackDurableWorkflow as runSagaRollbackOnWorkflow, signalDurableWorkflow as sendSignalToWorkflow, workflowNotFoundError, } from "./durable-workflow.js";
 import { buildMemoryKnowledgeGraph } from "./memory-graph.js";
+import { MUXO_COMMERCIAL_PLAYBOOKS, buildCommercialRoiReport, buildOtelTraceExport, buildPlaybookSagaExecution, compileWorkspacePolicyToCedarAndRego, evaluateCedarAndOpaPolicy, getCommercialPlaybook, } from "./oss-suite.js";
 import { resolveNaturalLanguageIntent, } from "./nl.js";
 import { DEFAULT_WORKSPACE_POLICY, buildLlmPolicyAndGovernanceBrief, compileNaturalLanguageGuardrailWithLlm, describePolicyInPlainEnglish, formatHumanFriendlyExplanation, parseNaturalLanguageGuardrail, simulatePolicyEvaluation, } from "./policy.js";
 import { ComposioInstantAdapter } from "./providers/composio-instant.js";
@@ -1130,18 +1131,25 @@ export class MuxoEngine {
     }
     /**
      * Synthesizes a Bi-Temporal Knowledge Graph (entities, active relationships, superseded historical relationships,
-     * Mermaid diagram, and human + technical explanations) directly from SQLite temporal_facts, memories, resources, and connections.
+     * Mermaid diagram, point-in-time `asOf` time-travel, 2-hop BFS subgraph, and human + technical explanations)
+     * directly from SQLite temporal_facts, memories, resources, and connections.
      */
-    async getMemoryGraph(ctx, query) {
+    async getMemoryGraph(ctx, queryOrOptions) {
         const ws = this.store.getWorkspace(ctx.workspace.id);
-        const overview = await this.getMemoryOverview(ctx, query);
+        const opts = typeof queryOrOptions === "string"
+            ? { query: queryOrOptions }
+            : queryOrOptions || {};
+        const overview = await this.getMemoryOverview(ctx, opts.query);
         return buildMemoryKnowledgeGraph({
             workspace: ws,
             namespace: overview.namespace,
-            query,
+            query: opts.query,
+            asOf: opts.asOf || null,
+            focalEntity: opts.focalEntity || null,
+            maxHops: opts.maxHops,
             facts: this.store.listTemporalFacts(ws.id, {
                 includeHistorical: true,
-                query,
+                query: opts.query,
                 limit: 100,
             }),
             resources: this.store.listResources(ws.id),
@@ -2473,6 +2481,139 @@ export class MuxoEngine {
     listDurableWorkflows(workspaceId) {
         return Array.from(this.durableWorkflows.values()).filter((w) => w.workspaceId === workspaceId);
     }
+    getDurableWorkflow(ctx, workflowId) {
+        const wf = this.durableWorkflows.get(workflowId);
+        if (!wf || wf.workspaceId !== ctx.workspace.id) {
+            throw workflowNotFoundError(workflowId);
+        }
+        return wf;
+    }
+    getDurableWorkflowHistory(ctx, workflowId) {
+        const wf = this.getDurableWorkflow(ctx, workflowId);
+        return exportTemporalEventHistory(wf);
+    }
+    signalDurableWorkflow(ctx, workflowId, params) {
+        const wf = this.getDurableWorkflow(ctx, workflowId);
+        return sendSignalToWorkflow(wf, params);
+    }
+    rollbackDurableWorkflow(ctx, workflowId, params) {
+        const wf = this.getDurableWorkflow(ctx, workflowId);
+        return runSagaRollbackOnWorkflow(wf, params);
+    }
+    /**
+     * AWS Cedar & Open Policy Agent (OPA / Rego) Policy-as-Code Compiler & Evaluator.
+     */
+    getPolicyAsCodeBundle(ctx) {
+        const ws = this.store.getWorkspace(ctx.workspace.id);
+        return compileWorkspacePolicyToCedarAndRego(ws.policy, ws);
+    }
+    async evaluatePolicyAsCode(ctx, params) {
+        const ws = this.store.getWorkspace(ctx.workspace.id);
+        let resolvedSlug = String(params.toolSlug || "instant.web.search").trim();
+        let riskLevel = params.riskLevel;
+        let creditCost = params.creditCost;
+        let lane = params.lane;
+        try {
+            const tool = await this.inspectTool(resolvedSlug);
+            resolvedSlug = tool.slug;
+            if (!riskLevel)
+                riskLevel = tool.riskLevel;
+            if (typeof creditCost !== "number")
+                creditCost = tool.creditCost;
+            if (!lane)
+                lane = tool.lane;
+        }
+        catch {
+            // Fall back to slug prefix heuristics
+        }
+        return evaluateCedarAndOpaPolicy({
+            policy: ws.policy,
+            workspace: ws,
+            toolSlug: resolvedSlug,
+            input: params.input || {},
+            riskLevel,
+            creditCost,
+            lane,
+        });
+    }
+    /**
+     * OpenTelemetry (OTel GenAI / MCP Semantic Conventions) & Langfuse Trace Exporter.
+     */
+    exportOtelTraces(ctx, limit = 25) {
+        const ws = this.store.getWorkspace(ctx.workspace.id);
+        const runs = this.store.listRuns(ws.id, limit);
+        const receipts = this.store.listReceipts(ws.id, limit);
+        const plans = this.store.listPlans(ws.id, limit);
+        return buildOtelTraceExport({
+            workspace: ws,
+            runs,
+            receipts,
+            plans,
+        });
+    }
+    /**
+     * Turnkey Commercial Business Saga Playbooks.
+     */
+    listCommercialPlaybooks() {
+        return MUXO_COMMERCIAL_PLAYBOOKS;
+    }
+    runCommercialPlaybook(ctx, params) {
+        const ws = this.store.getWorkspace(ctx.workspace.id);
+        const playbook = getCommercialPlaybook(params.slug);
+        if (!playbook) {
+            const err = new Error(`Unknown commercial playbook '${params.slug}'. Available playbooks: ${MUXO_COMMERCIAL_PLAYBOOKS.map((p) => p.slug).join(", ")}`);
+            err.statusCode = 404;
+            err.code = "PLAYBOOK_NOT_FOUND";
+            throw err;
+        }
+        const wfId = `wf_saga_${Date.now()}_${crypto.randomBytes(4).toString("hex")}`;
+        const executed = buildPlaybookSagaExecution({
+            id: wfId,
+            workspaceId: ws.id,
+            workspaceSlug: ws.slug,
+            playbook,
+            input: params.input || {},
+        });
+        this.durableWorkflows.set(wfId, executed.workflow);
+        const savedFact = this.store.upsertTemporalFact({
+            workspaceId: ws.id,
+            subject: executed.temporalFact.subject,
+            predicate: executed.temporalFact.predicate,
+            object: executed.temporalFact.object,
+            summary: executed.temporalFact.summary,
+            confidence: 0.99,
+            sourceKind: "execution_outcome",
+            sourceReferenceId: executed.temporalFact.episodeId,
+        });
+        return {
+            ok: true,
+            playbook: executed.playbook,
+            workflow: executed.workflow,
+            temporalFact: savedFact,
+        };
+    }
+    /**
+     * FinOps & Commercial ROI Unit-Economics Analytics.
+     */
+    getCommercialRoiReport(ctx) {
+        const ws = this.store.getWorkspace(ctx.workspace.id);
+        const runs = this.store.listRuns(ws.id, 100);
+        const plans = this.store.listPlans(ws.id, 100);
+        const resources = this.store.listResources(ws.id);
+        const byokKeys = this.store.listByokKeys(ws.id);
+        const temporalFacts = this.store.listTemporalFacts(ws.id, {
+            includeHistorical: false,
+            limit: 100,
+        });
+        return buildCommercialRoiReport({
+            workspace: ws,
+            runs,
+            plans,
+            resources,
+            byokKeys,
+            temporalFacts,
+        });
+    }
     /**
      * Hybrid Semantic Vector + Bi-Temporal Recall (`@cf/baai/bge-base-en-v1.5` + Vectorize model).
      */

package/dist/index.d.ts

@@ -1,6 +1,9 @@
 export { getConfig, ROOT_DIR, type MuxoConfig } from "./config.js";
+export * from "./durable-workflow.js";
 export { MuxoEngine, type ExecutionContext } from "./engine.js";
 export { handleJsonRpcMcpRequest, MUXO_MCP_TOOLS, type McpToolDefinition } from "./mcp.js";
+export * from "./memory-graph.js";
+export * from "./oss-suite.js";
 export { MuxoClient, type MuxoClientOptions } from "./sdk.js";
 export { createMuxoServer } from "./server.js";
 export { MuxoStore } from "./store.js";

package/dist/index.js

@@ -1,6 +1,9 @@
 export { getConfig, ROOT_DIR } from "./config.js";
+export * from "./durable-workflow.js";
 export { MuxoEngine } from "./engine.js";
 export { handleJsonRpcMcpRequest, MUXO_MCP_TOOLS } from "./mcp.js";
+export * from "./memory-graph.js";
+export * from "./oss-suite.js";
 export { MuxoClient } from "./sdk.js";
 export { createMuxoServer } from "./server.js";
 export { MuxoStore } from "./store.js";

package/dist/mcp-schema.js

@@ -1057,6 +1057,11 @@ export const MUXO_MCP_TOOLS = [
                         "set_guardrail",
                         "reset_guardrails",
                         "check_policy",
+                        "cedar_policy",
+                        "otel_traces",
+                        "roi_analytics",
+                        "playbooks",
+                        "run_playbook",
                         "kill_switch",
                         "governance_status",
                         "scan_context",
@@ -1064,7 +1069,7 @@ export const MUXO_MCP_TOOLS = [
                         "switch_workspace",
                         "onboard_team",
                     ],
-                    description: "Control-plane operation: 'inspect' (default), 'remember' (save fact/preference), 'recall' (list memories), 'forget' (delete matching memories), 'memory_graph' (bi-temporal entity/relationship lineage), 'set_guardrail' (apply plain-English or structured parameter_rules guardrail), 'reset_guardrails' (restore default safe guardrails), 'check_policy' (dry-run evaluate tool_slug + input against policy and parameter guardrails before planning), 'kill_switch' (pause/resume agent execution), 'governance_status' (Microsoft 9-module status + LLM policy brief), 'scan_context' (OWASP ASI-06 check), 'list_workspaces', 'switch_workspace', or 'onboard_team'",
+                    description: "Control-plane operation: 'inspect' (default), 'remember' (save fact/preference), 'recall' (list memories), 'forget' (delete matching memories), 'memory_graph' (Graphiti bi-temporal entity/relationship lineage with optional as_of time-travel & focal_entity 2-hop BFS), 'set_guardrail' (apply plain-English or structured parameter_rules guardrail), 'reset_guardrails' (restore default safe guardrails), 'check_policy' (dry-run evaluate tool_slug + input against policy and parameter guardrails before planning), 'cedar_policy' (compile/evaluate AWS Cedar & OPA Rego policy-as-code), 'otel_traces' (export W3C OpenTelemetry GenAI/MCP spans & Langfuse batch), 'roi_analytics' (FinOps & BYOK unit-economics ROI report), 'playbooks' / 'run_playbook' (list or execute turnkey multi-step Temporal Saga playbooks), 'kill_switch' (pause/resume agent execution), 'governance_status' (Microsoft 9-module status + LLM policy brief), 'scan_context' (OWASP ASI-06 check), 'list_workspaces', 'switch_workspace', or 'onboard_team'",
                 },
                 prompt: {
                     type: "string",
@@ -1161,6 +1166,22 @@ export const MUXO_MCP_TOOLS = [
                     type: "boolean",
                     description: "If true, attach the Bi-Temporal Knowledge Graph (nodes, activeEdges, historicalEdges, mermaid) to the context response",
                 },
+                as_of: {
+                    type: "string",
+                    description: "Optional ISO-8601 timestamp for Graphiti point-in-time ('as-of') bi-temporal knowledge graph reconstruction",
+                },
+                focal_entity: {
+                    type: "string",
+                    description: "Optional entity ID or label for k-hop BFS neighborhood subgraph extraction",
+                },
+                max_hops: {
+                    type: "number",
+                    description: "Maximum BFS traversal hops around focal_entity (1 to 4, default 2)",
+                },
+                slug: {
+                    type: "string",
+                    description: "Optional playbook slug when action='run_playbook' (e.g. 'fullstack-cloud-bootstrap', 'competitor-seo-growth-brief', 'incident-containment-audit', 'customer-release-readiness')",
+                },
                 plan_id: {
                     type: "string",
                     description: "Optional plan ID to inspect context for",

package/dist/mcp.js

@@ -223,8 +223,53 @@ export async function dispatchMcpToolCall(engine, ctx, toolName, args = {}) {
                 : Array.isArray(args.parameterRules)
                     ? args.parameterRules
                     : undefined;
+            const asOf = args.as_of || args.asOf ? String(args.as_of || args.asOf) : null;
+            const focalEntity = args.focal_entity || args.focalEntity
+                ? String(args.focal_entity || args.focalEntity)
+                : null;
+            const rawMaxHops = args.max_hops ?? args.maxHops;
+            const maxHops = rawMaxHops !== undefined && rawMaxHops !== null
+                ? Number(rawMaxHops)
+                : undefined;
             if (action === "memory_graph") {
-                return engine.getMemoryGraph(ctx, query);
+                return engine.getMemoryGraph(ctx, {
+                    query,
+                    asOf,
+                    focalEntity,
+                    maxHops,
+                });
+            }
+            if (action === "cedar_policy" || action === "policy_as_code") {
+                if (args.tool_slug || args.slug) {
+                    return engine.evaluatePolicyAsCode(ctx, {
+                        toolSlug: String(args.tool_slug || args.slug),
+                        input: (args.input || args.arguments) || {},
+                    });
+                }
+                return engine.getPolicyAsCodeBundle(ctx);
+            }
+            if (action === "otel_traces" || action === "telemetry") {
+                return engine.exportOtelTraces(ctx, Number(args.limit || 25));
+            }
+            if (action === "roi_analytics" || action === "roi") {
+                return engine.getCommercialRoiReport(ctx);
+            }
+            if (action === "playbooks") {
+                return {
+                    ok: true,
+                    playbooks: engine.listCommercialPlaybooks(),
+                };
+            }
+            if (action === "run_playbook") {
+                const slug = String(args.slug ||
+                    args.playbook ||
+                    query ||
+                    prompt ||
+                    "fullstack-cloud-bootstrap").trim();
+                return engine.runCommercialPlaybook(ctx, {
+                    slug,
+                    input: (args.input || args.arguments) || {},
+                });
             }
             if (action === "governance_status") {
                 return engine.getGovernanceOverview(ctx);
@@ -343,7 +388,12 @@ export async function dispatchMcpToolCall(engine, ctx, toolName, args = {}) {
             }
             const runCtx = await engine.getRunContext(ctx, query);
             if (args.include_graph === true) {
-                const memoryGraph = await engine.getMemoryGraph(ctx, query);
+                const memoryGraph = await engine.getMemoryGraph(ctx, {
+                    query,
+                    asOf,
+                    focalEntity,
+                    maxHops,
+                });
                 return { ...runCtx, memoryGraph };
             }
             return runCtx;
@@ -425,7 +475,16 @@ export async function dispatchMcpToolCall(engine, ctx, toolName, args = {}) {
             return engine.forgetWorkspaceMemoryMatching(ctx, query);
         }
         case "memory_graph":
-            return engine.getMemoryGraph(ctx, args.query ? String(args.query) : undefined);
+            return engine.getMemoryGraph(ctx, {
+                query: args.query ? String(args.query) : undefined,
+                asOf: args.as_of || args.asOf ? String(args.as_of || args.asOf) : null,
+                focalEntity: args.focal_entity || args.focalEntity
+                    ? String(args.focal_entity || args.focalEntity)
+                    : null,
+                maxHops: args.max_hops !== undefined || args.maxHops !== undefined
+                    ? Number(args.max_hops ?? args.maxHops)
+                    : undefined,
+            });
         case "set_guardrail":
         case "configure_guardrails": {
             const rawParamRules = Array.isArray(args.parameter_rules)

package/dist/memory-graph.d.ts

@@ -1,4 +1,4 @@
-import type { ConnectionRecord, GovernancePolicy, MemoryKnowledgeGraph, ProvisionedResource, TemporalGraphFact } from "./types.js";
+import type { ConnectionRecord, GovernancePolicy, MemoryGraphEdge, MemoryGraphNode, MemoryKnowledgeGraph, ProvisionedResource, TemporalGraphFact } from "./types.js";
 export interface MemoryGraphInput {
     workspace: {
         id: string;
@@ -9,13 +9,37 @@ export interface MemoryGraphInput {
     };
     namespace: string;
     query?: string;
+    asOf?: string | null;
+    focalEntity?: string | null;
+    maxHops?: number;
     facts: TemporalGraphFact[];
     resources: Array<Pick<ProvisionedResource, "resourceName" | "status" | "providerName" | "serviceSlug">>;
     activeConnections: Array<Pick<ConnectionRecord, "id" | "providerSlug" | "providerName" | "createdAt">>;
     memoriesCount: number;
 }
 /**
- * Builds the bi-temporal knowledge graph (nodes, active/historical edges, Mermaid preview)
+ * Graphiti-style Point-in-Time ("As-Of") Bi-Temporal Fact Filter.
+ * Reconstructs which facts were active at `asOf` vs. already retired by `asOf`,
+ * excluding facts created after `asOf`.
+ */
+export declare function filterFactsAsOf(facts: TemporalGraphFact[], asOf?: string | null): {
+    scopedFacts: TemporalGraphFact[];
+    isActiveAtPointInTime: (fact: TemporalGraphFact) => boolean;
+};
+/**
+ * Graphiti-style Multi-Hop Subgraph Community Traversal (BFS).
+ * Finds all nodes and edges within `maxHops` (default 2) of a focal entity.
+ */
+export declare function traverseSubgraphBfs(nodes: MemoryGraphNode[], edges: MemoryGraphEdge[], focalQuery: string, maxHops?: number): {
+    focalEntity: string;
+    maxHops: number;
+    nodes: MemoryGraphNode[];
+    edges: MemoryGraphEdge[];
+    hopDistances: Record<string, number>;
+};
+/**
+ * Builds the Graphiti-inspired Bi-Temporal Knowledge Graph (nodes, active/historical edges,
+ * episodic provenance, point-in-time `asOf` time-travel, 2-hop BFS subgraph, and Mermaid preview)
  * from runtime-agnostic inputs so the Node engine and the Edge Worker render identical graphs.
  */
 export declare function buildMemoryKnowledgeGraph(input: MemoryGraphInput): MemoryKnowledgeGraph;

package/dist/memory-graph.js

@@ -1,11 +1,102 @@
 import { formatHumanFriendlyExplanation } from "./policy.js";
 /**
- * Builds the bi-temporal knowledge graph (nodes, active/historical edges, Mermaid preview)
+ * Graphiti-style Point-in-Time ("As-Of") Bi-Temporal Fact Filter.
+ * Reconstructs which facts were active at `asOf` vs. already retired by `asOf`,
+ * excluding facts created after `asOf`.
+ */
+export function filterFactsAsOf(facts, asOf) {
+    if (!asOf || !asOf.trim()) {
+        return {
+            scopedFacts: facts,
+            isActiveAtPointInTime: (fact) => fact.validTo === null,
+        };
+    }
+    const asOfMs = Date.parse(asOf);
+    if (!Number.isFinite(asOfMs)) {
+        return {
+            scopedFacts: facts,
+            isActiveAtPointInTime: (fact) => fact.validTo === null,
+        };
+    }
+    const scopedFacts = facts.filter((fact) => {
+        const validFromMs = Date.parse(fact.validFrom || fact.createdAt);
+        return !Number.isFinite(validFromMs) || validFromMs <= asOfMs;
+    });
+    return {
+        scopedFacts,
+        isActiveAtPointInTime: (fact) => {
+            if (!fact.validTo)
+                return true;
+            const validToMs = Date.parse(fact.validTo);
+            return Number.isFinite(validToMs) && validToMs > asOfMs;
+        },
+    };
+}
+/**
+ * Graphiti-style Multi-Hop Subgraph Community Traversal (BFS).
+ * Finds all nodes and edges within `maxHops` (default 2) of a focal entity.
+ */
+export function traverseSubgraphBfs(nodes, edges, focalQuery, maxHops = 2) {
+    const needle = focalQuery.trim().toLowerCase();
+    const clampedHops = Math.min(4, Math.max(1, Number(maxHops) || 2));
+    const seedNode = nodes.find((n) => n.id.toLowerCase() === needle) ||
+        nodes.find((n) => n.label.toLowerCase() === needle) ||
+        nodes.find((n) => n.id.toLowerCase().includes(needle) ||
+            n.label.toLowerCase().includes(needle)) ||
+        nodes[0];
+    if (!seedNode) {
+        return {
+            focalEntity: focalQuery,
+            maxHops: clampedHops,
+            nodes: [],
+            edges: [],
+            hopDistances: {},
+        };
+    }
+    const hopDistances = { [seedNode.id]: 0 };
+    const queue = [
+        { nodeId: seedNode.id, depth: 0 },
+    ];
+    while (queue.length > 0) {
+        const current = queue.shift();
+        if (current.depth >= clampedHops)
+            continue;
+        for (const edge of edges) {
+            let neighborId = null;
+            if (edge.source === current.nodeId)
+                neighborId = edge.target;
+            else if (edge.target === current.nodeId)
+                neighborId = edge.source;
+            if (neighborId && hopDistances[neighborId] === undefined) {
+                hopDistances[neighborId] = current.depth + 1;
+                queue.push({ nodeId: neighborId, depth: current.depth + 1 });
+            }
+        }
+    }
+    const subNodes = nodes
+        .filter((n) => hopDistances[n.id] !== undefined)
+        .map((n) => ({ ...n, hopDistance: hopDistances[n.id] }));
+    const subEdges = edges.filter((e) => hopDistances[e.source] !== undefined &&
+        hopDistances[e.target] !== undefined);
+    return {
+        focalEntity: seedNode.id,
+        maxHops: clampedHops,
+        nodes: subNodes,
+        edges: subEdges,
+        hopDistances,
+    };
+}
+/**
+ * Builds the Graphiti-inspired Bi-Temporal Knowledge Graph (nodes, active/historical edges,
+ * episodic provenance, point-in-time `asOf` time-travel, 2-hop BFS subgraph, and Mermaid preview)
  * from runtime-agnostic inputs so the Node engine and the Edge Worker render identical graphs.
  */
 export function buildMemoryKnowledgeGraph(input) {
     const ws = input.workspace;
     const query = input.query;
+    const asOf = input.asOf ?? null;
+    const maxHops = Math.min(4, Math.max(1, Number(input.maxHops || 2)));
+    const { scopedFacts, isActiveAtPointInTime } = filterFactsAsOf(input.facts, asOf);
     const nodeMap = new Map();
     const rootId = `workspace:${ws.slug}`;
     nodeMap.set(rootId, {
@@ -34,7 +125,9 @@ export function buildMemoryKnowledgeGraph(input) {
                         ? "tool"
                         : id.startsWith("guardrail:")
                             ? "guardrail"
-                            : fallbackKind;
+                            : id.startsWith("episode:")
+                                ? "episode"
+                                : fallbackKind;
         const label = id.includes(":")
             ? id.split(":").slice(1).join(":")
             : id.length > 36
@@ -50,8 +143,11 @@ export function buildMemoryKnowledgeGraph(input) {
         nodeMap.set(id, created);
         return created;
     };
-    const edges = input.facts.map((fact) => {
-        const status = fact.validTo === null ? "active" : "historical";
+    let episodesCount = 0;
+    const edges = scopedFacts.map((fact) => {
+        const status = isActiveAtPointInTime(fact)
+            ? "active"
+            : "historical";
         const objKind = fact.sourceKind === "preference"
             ? "preference"
             : fact.sourceKind === "policy_decision"
@@ -61,6 +157,15 @@ export function buildMemoryKnowledgeGraph(input) {
                     : "entity";
         ensureNode(fact.subject, status, "entity", fact.subject);
         ensureNode(fact.object, status, objKind, fact.summary);
+        const episodeId = fact.episodeId || fact.sourceReferenceId || null;
+        if (episodeId) {
+            const epNodeId = episodeId.startsWith("episode:")
+                ? episodeId
+                : `episode:${episodeId}`;
+            if (!nodeMap.has(epNodeId))
+                episodesCount += 1;
+            ensureNode(epNodeId, status, "episode", `Episodic provenance (${episodeId})`);
+        }
         return {
             id: fact.id,
             source: fact.subject,
@@ -72,7 +177,10 @@ export function buildMemoryKnowledgeGraph(input) {
             confidence: fact.confidence,
             status,
             validFrom: fact.validFrom,
-            validTo: fact.validTo,
+            validTo: status === "active" && asOf ? null : fact.validTo,
+            transactionFrom: fact.transactionFrom || fact.createdAt,
+            transactionTo: fact.transactionTo ?? fact.validTo,
+            episodeId,
             supersededById: fact.supersededById ?? null,
             sourceKind: fact.sourceKind,
             sourceReferenceId: fact.sourceReferenceId ?? null,
@@ -95,6 +203,9 @@ export function buildMemoryKnowledgeGraph(input) {
                 status: "active",
                 validFrom: conn.createdAt,
                 validTo: null,
+                transactionFrom: conn.createdAt,
+                transactionTo: null,
+                episodeId: conn.id,
                 supersededById: null,
                 sourceKind: "system",
                 sourceReferenceId: conn.id,
@@ -104,6 +215,10 @@ export function buildMemoryKnowledgeGraph(input) {
     const activeEdges = edges.filter((e) => e.status === "active");
     const historicalEdges = edges.filter((e) => e.status === "historical");
     const nodes = Array.from(nodeMap.values());
+    const focalTarget = input.focalEntity || query || null;
+    const subgraph = focalTarget
+        ? traverseSubgraphBfs(nodes, edges, focalTarget, maxHops)
+        : null;
     const safeMermaidId = (raw, idx) => `N${idx}_${raw.replace(/[^a-zA-Z0-9]/g, "_").slice(0, 14)}`;
     const nodeIndex = new Map();
     nodes.slice(0, 24).forEach((n, idx) => {
@@ -128,7 +243,7 @@ export function buildMemoryKnowledgeGraph(input) {
             mermaidLines.push(`  ${srcId} -.->|RETIRED: ${pred}| ${tgtId}`);
         }
     }
-    const headline = `Bi-Temporal Knowledge Graph (${ws.name}): ${activeEdges.length} active relationship${activeEdges.length === 1 ? "" : "s"}, ${historicalEdges.length} superseded historical relationship${historicalEdges.length === 1 ? "" : "s"} across ${nodes.length} node${nodes.length === 1 ? "" : "s"}.`;
+    const headline = `Bi-Temporal Knowledge Graph (${ws.name}${asOf ? ` as of ${asOf}` : ""}): ${activeEdges.length} active relationship${activeEdges.length === 1 ? "" : "s"}, ${historicalEdges.length} superseded historical relationship${historicalEdges.length === 1 ? "" : "s"} across ${nodes.length} node${nodes.length === 1 ? "" : "s"}.`;
     const activePreview = activeEdges
         .slice(0, 4)
         .map((e) => `${e.source} --[${e.predicate}]--> ${e.target}`)
@@ -142,7 +257,7 @@ export function buildMemoryKnowledgeGraph(input) {
             ? `Time-travel lineage: ${historicalEdges.length} older fact${historicalEdges.length === 1 ? " was" : "s were"} automatically retired when newer workspace settings or facts replaced them.`
             : "No superseded historical facts yet.",
     ].join(" ");
-    const technical = `workspace=${ws.id} | namespace=${input.namespace} | nodes=${nodes.length} | activeEdges=${activeEdges.length} | historicalEdges=${historicalEdges.length} | memories=${input.memoriesCount} | activePreview=[${activePreview || "none"}]`;
+    const technical = `workspace=${ws.id} | namespace=${input.namespace} | asOf=${asOf || "latest"} | nodes=${nodes.length} | activeEdges=${activeEdges.length} | historicalEdges=${historicalEdges.length} | episodes=${episodesCount} | memories=${input.memoriesCount} | activePreview=[${activePreview || "none"}]`;
     const explanation = formatHumanFriendlyExplanation({
         headline,
         nonTechnical,
@@ -154,11 +269,15 @@ export function buildMemoryKnowledgeGraph(input) {
         workspaceSlug: ws.slug,
         namespace: input.namespace,
         generatedAt: new Date().toISOString(),
+        asOf,
+        focalEntity: subgraph?.focalEntity ?? null,
+        maxHops,
         query: query ?? null,
         nodes,
         edges,
         activeEdges,
         historicalEdges,
+        subgraph,
         stats: {
             nodesCount: nodes.length,
             activeEdgesCount: activeEdges.length,
@@ -166,6 +285,7 @@ export function buildMemoryKnowledgeGraph(input) {
             memoriesCount: input.memoriesCount,
             resourcesCount: input.resources.length,
             connectionsCount: input.activeConnections.length,
+            episodesCount,
         },
         mermaid: mermaidLines.join("\n"),
         explanation,