@remnic/core 1.0.0

package/dist/causal-chain.js

@@ -0,0 +1,24 @@
+import {
+  makeEdgeId,
+  readChainIndex,
+  resolveChainsDir,
+  scoreStitchCandidate,
+  stitchCausalChain,
+  validateCausalEdge,
+  writeChainIndex
+} from "./chunk-NTTLPF7F.js";
+import "./chunk-M5KEYE5E.js";
+import "./chunk-DT5TVLJE.js";
+import "./chunk-KWBU5S5U.js";
+import "./chunk-DGXUHMOV.js";
+import "./chunk-LPSF4OQH.js";
+export {
+  makeEdgeId,
+  readChainIndex,
+  resolveChainsDir,
+  scoreStitchCandidate,
+  stitchCausalChain,
+  validateCausalEdge,
+  writeChainIndex
+};
+//# sourceMappingURL=causal-chain.js.map

package/dist/causal-chain.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/causal-consolidation.d.ts

@@ -0,0 +1,71 @@
+import { GatewayConfig } from './types.js';
+
+/**
+ * causal-consolidation.ts — CMC Phase 2: LLM-Assisted Causal Consolidation
+ *
+ * Uses an LLM to analyze causal trajectory patterns across sessions.
+ * The LLM receives the causal chain graph as context — connected trajectories
+ * from different sessions — and identifies recurring behavioral patterns,
+ * preference signals, and actionable rules.
+ *
+ * This is the core CMC innovation: the LLM gets cross-session causal context
+ * that no other memory system provides. It can see that a user investigated
+ * a bug in session 1, attempted a fix in session 2, and succeeded in session 3 —
+ * and synthesize a rule or preference from that chain.
+ */
+
+interface CausalPatternCandidate {
+    id: string;
+    sourceType: "causal-pattern";
+    subject: string;
+    category: "principle" | "rule";
+    content: string;
+    score: number;
+    rationale: string;
+    outcome: null;
+    provenance: string[];
+    agent: string | null;
+    workflow: string | null;
+}
+interface ConsolidationConfig {
+    minRecurrence: number;
+    minSessions: number;
+    successThreshold: number;
+}
+interface LlmConsolidationResult {
+    rules: Array<{
+        content: string;
+        category: "rule" | "principle" | "preference";
+        confidence: number;
+        evidence: string[];
+    }>;
+    preferences: Array<{
+        statement: string;
+        confidence: number;
+        evidence: string[];
+    }>;
+}
+/**
+ * Run LLM-assisted consolidation: read trajectories, format causal context,
+ * ask LLM to identify patterns and preferences.
+ */
+declare function deriveCausalPromotionCandidates(options: {
+    memoryDir: string;
+    causalTrajectoryStoreDir?: string;
+    config: ConsolidationConfig;
+    gatewayConfig?: GatewayConfig;
+    gatewayAgentId?: string;
+}): Promise<CausalPatternCandidate[]>;
+/**
+ * Get LLM-synthesized preferences from causal trajectory analysis.
+ * Returns formatted preference statements for recall injection.
+ */
+declare function synthesizeCausalPreferencesViaLlm(options: {
+    memoryDir: string;
+    causalTrajectoryStoreDir?: string;
+    gatewayConfig?: GatewayConfig;
+    gatewayAgentId?: string;
+    minTrajectories?: number;
+}): Promise<string | null>;
+
+export { type CausalPatternCandidate, type ConsolidationConfig, type LlmConsolidationResult, deriveCausalPromotionCandidates, synthesizeCausalPreferencesViaLlm };

package/dist/causal-consolidation.js

@@ -0,0 +1,211 @@
+import {
+  readChainIndex,
+  resolveChainsDir
+} from "./chunk-NTTLPF7F.js";
+import {
+  FallbackLlmClient
+} from "./chunk-KT4NEUNF.js";
+import "./chunk-LU3GQNDQ.js";
+import "./chunk-Y27UJK6V.js";
+import "./chunk-UZB5KHKX.js";
+import "./chunk-M5KEYE5E.js";
+import "./chunk-MARWOCVP.js";
+import "./chunk-DT5TVLJE.js";
+import {
+  log
+} from "./chunk-KWBU5S5U.js";
+import {
+  isRecord
+} from "./chunk-DGXUHMOV.js";
+import {
+  listJsonFiles,
+  readJsonFile
+} from "./chunk-LPSF4OQH.js";
+
+// src/causal-consolidation.ts
+import { createHash } from "crypto";
+import path from "path";
+async function readAllTrajectories(memoryDir, causalTrajectoryStoreDir) {
+  const root = causalTrajectoryStoreDir ? path.join(memoryDir, causalTrajectoryStoreDir) : path.join(memoryDir, "state", "causal-trajectories");
+  const trajectoriesDir = path.join(root, "trajectories");
+  const files = await listJsonFiles(trajectoriesDir).catch(() => []);
+  const results = [];
+  for (const filePath of files) {
+    try {
+      const raw = await readJsonFile(filePath);
+      if (isRecord(raw) && typeof raw.trajectoryId === "string") {
+        results.push(raw);
+      }
+    } catch {
+    }
+  }
+  return results;
+}
+function formatCausalContext(trajectories, chainIndex, maxChars = 8e3) {
+  const bySession = /* @__PURE__ */ new Map();
+  for (const t of trajectories) {
+    const list = bySession.get(t.sessionKey) ?? [];
+    list.push(t);
+    bySession.set(t.sessionKey, list);
+  }
+  const lines = [];
+  lines.push(`## Causal Trajectories (${trajectories.length} across ${bySession.size} sessions)`);
+  lines.push("");
+  for (const [sessionKey, sessionTrajs] of bySession) {
+    lines.push(`### Session: ${sessionKey}`);
+    for (const t of sessionTrajs.slice(0, 5)) {
+      const outcome = t.outcomeKind === "success" ? "+" : t.outcomeKind === "failure" ? "-" : "~";
+      lines.push(`[${outcome}] Goal: ${t.goal}`);
+      lines.push(`    Action: ${t.actionSummary}`);
+      lines.push(`    Outcome: ${t.outcomeSummary}`);
+      if (t.followUpSummary) lines.push(`    Follow-up: ${t.followUpSummary}`);
+      if (t.entityRefs?.length) lines.push(`    Entities: ${t.entityRefs.join(", ")}`);
+    }
+    lines.push("");
+  }
+  const edgeCount = Object.keys(chainIndex.edges).length;
+  if (edgeCount > 0) {
+    lines.push(`## Cross-Session Causal Chains (${edgeCount} connections)`);
+    lines.push("");
+    const trajectoryMap = new Map(trajectories.map((t) => [t.trajectoryId, t]));
+    const shown = /* @__PURE__ */ new Set();
+    for (const [edgeId, edge] of Object.entries(chainIndex.edges)) {
+      if (shown.size >= 10) break;
+      const from = trajectoryMap.get(edge.fromTrajectoryId);
+      const to = trajectoryMap.get(edge.toTrajectoryId);
+      if (!from || !to) continue;
+      lines.push(`${edge.edgeType}: "${from.goal}" (${from.sessionKey}) \u2192 "${to.goal}" (${to.sessionKey})`);
+      shown.add(edgeId);
+    }
+    lines.push("");
+  }
+  const result = lines.join("\n");
+  return result.length > maxChars ? result.slice(0, maxChars) + "\n[truncated]" : result;
+}
+var CONSOLIDATION_PROMPT = `You are analyzing a user's causal trajectory history across multiple sessions. Trajectories record what the user tried to do (goal), what they did (action), and what happened (outcome).
+
+Your job is to identify:
+1. BEHAVIORAL RULES: Recurring patterns where the same approach consistently succeeds or fails. These should be actionable guidance for future sessions.
+2. PREFERENCES: What the user cares about, prefers, or consistently chooses \u2014 even if never explicitly stated. Infer preferences from what they repeatedly do, retry until successful, or always include in their workflow.
+
+IMPORTANT:
+- Look for CROSS-SESSION patterns \u2014 things that repeat across different sessions are more significant than within-session patterns.
+- A user who retries the same goal across sessions has a strong implicit preference for that outcome.
+- Consistent action choices reveal preferences even when the user never says "I prefer X."
+- Frame preferences as "The user would prefer responses that..." when applicable.
+
+Output valid JSON only:
+{
+  "rules": [
+    {"content": "actionable rule text", "category": "rule|principle", "confidence": 0.0-1.0, "evidence": ["trajectory IDs"]}
+  ],
+  "preferences": [
+    {"statement": "The user would prefer...", "confidence": 0.0-1.0, "evidence": ["trajectory IDs"]}
+  ]
+}
+
+If no clear patterns exist, return {"rules": [], "preferences": []}.`;
+async function consolidateWithLlm(context, llm, agentId) {
+  const response = await llm.chatCompletion(
+    [
+      { role: "system", content: CONSOLIDATION_PROMPT },
+      { role: "user", content: context }
+    ],
+    { temperature: 0.2, maxTokens: 2e3, agentId }
+  );
+  if (!response?.content) {
+    return { rules: [], preferences: [] };
+  }
+  try {
+    let jsonStr = response.content.trim();
+    const fenceMatch = jsonStr.match(/```(?:json)?\s*\n?([\s\S]*?)\n?\s*```/);
+    if (fenceMatch) jsonStr = fenceMatch[1];
+    const parsed = JSON.parse(jsonStr);
+    return {
+      rules: Array.isArray(parsed.rules) ? parsed.rules.filter(
+        (r) => typeof r.content === "string" && r.content.length > 5
+      ) : [],
+      preferences: Array.isArray(parsed.preferences) ? parsed.preferences.filter(
+        (p) => typeof p.statement === "string" && p.statement.length > 5
+      ) : []
+    };
+  } catch {
+    log.warn("[cmc] failed to parse LLM consolidation response");
+    return { rules: [], preferences: [] };
+  }
+}
+function stablePatternId(content) {
+  const digest = createHash("sha256").update(`causal-pattern\0${content}`).digest("hex").slice(0, 16);
+  return `causal-pattern:${digest}`;
+}
+function llmResultToCandidates(result) {
+  const candidates = [];
+  for (const rule of result.rules) {
+    const category = rule.category === "principle" ? "principle" : "rule";
+    candidates.push({
+      id: stablePatternId(rule.content),
+      sourceType: "causal-pattern",
+      subject: rule.content.slice(0, 80),
+      category,
+      content: rule.content,
+      score: Math.min(1, rule.confidence ?? 0.7),
+      rationale: "LLM-identified causal pattern from cross-session trajectory analysis",
+      outcome: null,
+      provenance: (rule.evidence ?? []).slice(0, 5),
+      agent: null,
+      workflow: null
+    });
+  }
+  return candidates;
+}
+async function deriveCausalPromotionCandidates(options) {
+  try {
+    const trajectories = await readAllTrajectories(options.memoryDir, options.causalTrajectoryStoreDir);
+    if (trajectories.length < options.config.minRecurrence) return [];
+    const chainsDir = resolveChainsDir(options.memoryDir, options.causalTrajectoryStoreDir);
+    const chainIndex = await readChainIndex(chainsDir);
+    const context = formatCausalContext(trajectories, chainIndex);
+    const llm = new FallbackLlmClient(options.gatewayConfig);
+    if (!llm.isAvailable(options.gatewayAgentId)) {
+      log.debug("[cmc] no LLM available for consolidation \u2014 skipping");
+      return [];
+    }
+    const result = await consolidateWithLlm(context, llm, options.gatewayAgentId);
+    const candidates = llmResultToCandidates(result);
+    log.debug(`[cmc] LLM consolidation produced ${candidates.length} rule(s) and ${result.preferences.length} preference(s)`);
+    return candidates;
+  } catch (error) {
+    log.warn(`[cmc] consolidation failed (non-fatal): ${error instanceof Error ? error.message : String(error)}`);
+    return [];
+  }
+}
+async function synthesizeCausalPreferencesViaLlm(options) {
+  try {
+    const trajectories = await readAllTrajectories(options.memoryDir, options.causalTrajectoryStoreDir);
+    if (trajectories.length < (options.minTrajectories ?? 2)) return null;
+    const chainsDir = resolveChainsDir(options.memoryDir, options.causalTrajectoryStoreDir);
+    const chainIndex = await readChainIndex(chainsDir);
+    const context = formatCausalContext(trajectories, chainIndex);
+    const llm = new FallbackLlmClient(options.gatewayConfig);
+    if (!llm.isAvailable(options.gatewayAgentId)) return null;
+    const result = await consolidateWithLlm(context, llm, options.gatewayAgentId);
+    if (result.preferences.length === 0 && result.rules.length === 0) return null;
+    const lines = ["## Behavioral Insights (from Causal Chain Analysis)", ""];
+    for (const pref of result.preferences) {
+      lines.push(`- ${pref.statement}`);
+    }
+    for (const rule of result.rules) {
+      lines.push(`- ${rule.content}`);
+    }
+    lines.push("");
+    return lines.join("\n");
+  } catch (error) {
+    log.warn(`[cmc] preference synthesis failed (non-fatal): ${error instanceof Error ? error.message : String(error)}`);
+    return null;
+  }
+}
+export {
+  deriveCausalPromotionCandidates,
+  synthesizeCausalPreferencesViaLlm
+};
+//# sourceMappingURL=causal-consolidation.js.map

package/dist/causal-consolidation.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/causal-consolidation.ts"],"sourcesContent":["/**\n * causal-consolidation.ts — CMC Phase 2: LLM-Assisted Causal Consolidation\n *\n * Uses an LLM to analyze causal trajectory patterns across sessions.\n * The LLM receives the causal chain graph as context — connected trajectories\n * from different sessions — and identifies recurring behavioral patterns,\n * preference signals, and actionable rules.\n *\n * This is the core CMC innovation: the LLM gets cross-session causal context\n * that no other memory system provides. It can see that a user investigated\n * a bug in session 1, attempted a fix in session 2, and succeeded in session 3 —\n * and synthesize a rule or preference from that chain.\n */\n\nimport { createHash } from \"node:crypto\";\nimport type { CausalTrajectoryRecord } from \"./causal-trajectory.js\";\nimport { readChainIndex, resolveChainsDir, type CausalChainIndex, type CausalEdge } from \"./causal-chain.js\";\nimport { listJsonFiles, readJsonFile } from \"./json-store.js\";\nimport { isRecord } from \"./store-contract.js\";\nimport { FallbackLlmClient } from \"./fallback-llm.js\";\nimport type { GatewayConfig } from \"./types.js\";\nimport path from \"node:path\";\nimport { log } from \"./logger.js\";\n\n// ─── Types ───────────────────────────────────────────────────────────────────\n\nexport interface CausalPatternCandidate {\n  id: string;\n  sourceType: \"causal-pattern\";\n  subject: string;\n  category: \"principle\" | \"rule\";\n  content: string;\n  score: number;\n  rationale: string;\n  outcome: null;\n  provenance: string[];\n  agent: string | null;\n  workflow: string | null;\n}\n\nexport interface ConsolidationConfig {\n  minRecurrence: number;\n  minSessions: number;\n  successThreshold: number;\n}\n\nexport interface LlmConsolidationResult {\n  rules: Array<{\n    content: string;\n    category: \"rule\" | \"principle\" | \"preference\";\n    confidence: number;\n    evidence: string[];\n  }>;\n  preferences: Array<{\n    statement: string;\n    confidence: number;\n    evidence: string[];\n  }>;\n}\n\n// ─── Trajectory Reading ──────────────────────────────────────────────────────\n\nasync function readAllTrajectories(\n  memoryDir: string,\n  causalTrajectoryStoreDir?: string,\n): Promise<CausalTrajectoryRecord[]> {\n  const root = causalTrajectoryStoreDir\n    ? path.join(memoryDir, causalTrajectoryStoreDir)\n    : path.join(memoryDir, \"state\", \"causal-trajectories\");\n  const trajectoriesDir = path.join(root, \"trajectories\");\n\n  const files = await listJsonFiles(trajectoriesDir).catch(() => [] as string[]);\n  const results: CausalTrajectoryRecord[] = [];\n\n  for (const filePath of files) {\n    try {\n      const raw = await readJsonFile(filePath);\n      if (isRecord(raw) && typeof raw.trajectoryId === \"string\") {\n        results.push(raw as unknown as CausalTrajectoryRecord);\n      }\n    } catch {\n      // skip invalid\n    }\n  }\n\n  return results;\n}\n\n// ─── Context Formatting ──────────────────────────────────────────────────────\n\n/**\n * Format trajectories and their causal connections as a readable context\n * for the LLM. Groups by session and shows chain connections.\n */\nfunction formatCausalContext(\n  trajectories: CausalTrajectoryRecord[],\n  chainIndex: CausalChainIndex,\n  maxChars: number = 8000,\n): string {\n  // Group trajectories by session\n  const bySession = new Map<string, CausalTrajectoryRecord[]>();\n  for (const t of trajectories) {\n    const list = bySession.get(t.sessionKey) ?? [];\n    list.push(t);\n    bySession.set(t.sessionKey, list);\n  }\n\n  const lines: string[] = [];\n  lines.push(`## Causal Trajectories (${trajectories.length} across ${bySession.size} sessions)`);\n  lines.push(\"\");\n\n  // Format each session's trajectories\n  for (const [sessionKey, sessionTrajs] of bySession) {\n    lines.push(`### Session: ${sessionKey}`);\n    for (const t of sessionTrajs.slice(0, 5)) {\n      const outcome = t.outcomeKind === \"success\" ? \"+\" : t.outcomeKind === \"failure\" ? \"-\" : \"~\";\n      lines.push(`[${outcome}] Goal: ${t.goal}`);\n      lines.push(`    Action: ${t.actionSummary}`);\n      lines.push(`    Outcome: ${t.outcomeSummary}`);\n      if (t.followUpSummary) lines.push(`    Follow-up: ${t.followUpSummary}`);\n      if (t.entityRefs?.length) lines.push(`    Entities: ${t.entityRefs.join(\", \")}`);\n    }\n    lines.push(\"\");\n  }\n\n  // Format causal chain connections\n  const edgeCount = Object.keys(chainIndex.edges).length;\n  if (edgeCount > 0) {\n    lines.push(`## Cross-Session Causal Chains (${edgeCount} connections)`);\n    lines.push(\"\");\n\n    const trajectoryMap = new Map(trajectories.map((t) => [t.trajectoryId, t]));\n    const shown = new Set<string>();\n\n    for (const [edgeId, edge] of Object.entries(chainIndex.edges)) {\n      if (shown.size >= 10) break; // limit output size\n      const from = trajectoryMap.get(edge.fromTrajectoryId);\n      const to = trajectoryMap.get(edge.toTrajectoryId);\n      if (!from || !to) continue;\n\n      lines.push(`${edge.edgeType}: \"${from.goal}\" (${from.sessionKey}) → \"${to.goal}\" (${to.sessionKey})`);\n      shown.add(edgeId);\n    }\n    lines.push(\"\");\n  }\n\n  const result = lines.join(\"\\n\");\n  return result.length > maxChars ? result.slice(0, maxChars) + \"\\n[truncated]\" : result;\n}\n\n// ─── LLM Consolidation ──────────────────────────────────────────────────────\n\nconst CONSOLIDATION_PROMPT = `You are analyzing a user's causal trajectory history across multiple sessions. Trajectories record what the user tried to do (goal), what they did (action), and what happened (outcome).\n\nYour job is to identify:\n1. BEHAVIORAL RULES: Recurring patterns where the same approach consistently succeeds or fails. These should be actionable guidance for future sessions.\n2. PREFERENCES: What the user cares about, prefers, or consistently chooses — even if never explicitly stated. Infer preferences from what they repeatedly do, retry until successful, or always include in their workflow.\n\nIMPORTANT:\n- Look for CROSS-SESSION patterns — things that repeat across different sessions are more significant than within-session patterns.\n- A user who retries the same goal across sessions has a strong implicit preference for that outcome.\n- Consistent action choices reveal preferences even when the user never says \"I prefer X.\"\n- Frame preferences as \"The user would prefer responses that...\" when applicable.\n\nOutput valid JSON only:\n{\n  \"rules\": [\n    {\"content\": \"actionable rule text\", \"category\": \"rule|principle\", \"confidence\": 0.0-1.0, \"evidence\": [\"trajectory IDs\"]}\n  ],\n  \"preferences\": [\n    {\"statement\": \"The user would prefer...\", \"confidence\": 0.0-1.0, \"evidence\": [\"trajectory IDs\"]}\n  ]\n}\n\nIf no clear patterns exist, return {\"rules\": [], \"preferences\": []}.`;\n\nasync function consolidateWithLlm(\n  context: string,\n  llm: FallbackLlmClient,\n  agentId?: string,\n): Promise<LlmConsolidationResult> {\n  const response = await llm.chatCompletion(\n    [\n      { role: \"system\", content: CONSOLIDATION_PROMPT },\n      { role: \"user\", content: context },\n    ],\n    { temperature: 0.2, maxTokens: 2000, agentId },\n  );\n\n  if (!response?.content) {\n    return { rules: [], preferences: [] };\n  }\n\n  try {\n    // Extract JSON from response (may have markdown code fences)\n    let jsonStr = response.content.trim();\n    const fenceMatch = jsonStr.match(/```(?:json)?\\s*\\n?([\\s\\S]*?)\\n?\\s*```/);\n    if (fenceMatch) jsonStr = fenceMatch[1];\n\n    const parsed = JSON.parse(jsonStr);\n    return {\n      rules: Array.isArray(parsed.rules) ? parsed.rules.filter(\n        (r: any) => typeof r.content === \"string\" && r.content.length > 5,\n      ) : [],\n      preferences: Array.isArray(parsed.preferences) ? parsed.preferences.filter(\n        (p: any) => typeof p.statement === \"string\" && p.statement.length > 5,\n      ) : [],\n    };\n  } catch {\n    log.warn(\"[cmc] failed to parse LLM consolidation response\");\n    return { rules: [], preferences: [] };\n  }\n}\n\n// ─── Candidate Generation ────────────────────────────────────────────────────\n\nfunction stablePatternId(content: string): string {\n  const digest = createHash(\"sha256\")\n    .update(`causal-pattern\\0${content}`)\n    .digest(\"hex\")\n    .slice(0, 16);\n  return `causal-pattern:${digest}`;\n}\n\nfunction llmResultToCandidates(result: LlmConsolidationResult): CausalPatternCandidate[] {\n  const candidates: CausalPatternCandidate[] = [];\n\n  for (const rule of result.rules) {\n    const category = rule.category === \"principle\" ? \"principle\" : \"rule\";\n    candidates.push({\n      id: stablePatternId(rule.content),\n      sourceType: \"causal-pattern\",\n      subject: rule.content.slice(0, 80),\n      category,\n      content: rule.content,\n      score: Math.min(1, rule.confidence ?? 0.7),\n      rationale: \"LLM-identified causal pattern from cross-session trajectory analysis\",\n      outcome: null,\n      provenance: (rule.evidence ?? []).slice(0, 5),\n      agent: null,\n      workflow: null,\n    });\n  }\n\n  return candidates;\n}\n\n// ─── Public API ──────────────────────────────────────────────────────────────\n\n/**\n * Run LLM-assisted consolidation: read trajectories, format causal context,\n * ask LLM to identify patterns and preferences.\n */\nexport async function deriveCausalPromotionCandidates(options: {\n  memoryDir: string;\n  causalTrajectoryStoreDir?: string;\n  config: ConsolidationConfig;\n  gatewayConfig?: GatewayConfig;\n  gatewayAgentId?: string;\n}): Promise<CausalPatternCandidate[]> {\n  try {\n    const trajectories = await readAllTrajectories(options.memoryDir, options.causalTrajectoryStoreDir);\n    if (trajectories.length < options.config.minRecurrence) return [];\n\n    const chainsDir = resolveChainsDir(options.memoryDir, options.causalTrajectoryStoreDir);\n    const chainIndex = await readChainIndex(chainsDir);\n\n    // Format the causal context for the LLM\n    const context = formatCausalContext(trajectories, chainIndex);\n\n    // If no LLM available, fall back to empty (no deterministic fallback)\n    const llm = new FallbackLlmClient(options.gatewayConfig);\n    if (!llm.isAvailable(options.gatewayAgentId)) {\n      log.debug(\"[cmc] no LLM available for consolidation — skipping\");\n      return [];\n    }\n\n    // Call LLM for pattern analysis\n    const result = await consolidateWithLlm(context, llm, options.gatewayAgentId);\n    const candidates = llmResultToCandidates(result);\n\n    log.debug(`[cmc] LLM consolidation produced ${candidates.length} rule(s) and ${result.preferences.length} preference(s)`);\n    return candidates;\n  } catch (error) {\n    log.warn(`[cmc] consolidation failed (non-fatal): ${error instanceof Error ? error.message : String(error)}`);\n    return [];\n  }\n}\n\n/**\n * Get LLM-synthesized preferences from causal trajectory analysis.\n * Returns formatted preference statements for recall injection.\n */\nexport async function synthesizeCausalPreferencesViaLlm(options: {\n  memoryDir: string;\n  causalTrajectoryStoreDir?: string;\n  gatewayConfig?: GatewayConfig;\n  gatewayAgentId?: string;\n  minTrajectories?: number;\n}): Promise<string | null> {\n  try {\n    const trajectories = await readAllTrajectories(options.memoryDir, options.causalTrajectoryStoreDir);\n    if (trajectories.length < (options.minTrajectories ?? 2)) return null;\n\n    const chainsDir = resolveChainsDir(options.memoryDir, options.causalTrajectoryStoreDir);\n    const chainIndex = await readChainIndex(chainsDir);\n    const context = formatCausalContext(trajectories, chainIndex);\n\n    const llm = new FallbackLlmClient(options.gatewayConfig);\n    if (!llm.isAvailable(options.gatewayAgentId)) return null;\n\n    const result = await consolidateWithLlm(context, llm, options.gatewayAgentId);\n    if (result.preferences.length === 0 && result.rules.length === 0) return null;\n\n    const lines: string[] = [\"## Behavioral Insights (from Causal Chain Analysis)\", \"\"];\n\n    for (const pref of result.preferences) {\n      lines.push(`- ${pref.statement}`);\n    }\n\n    for (const rule of result.rules) {\n      lines.push(`- ${rule.content}`);\n    }\n\n    lines.push(\"\");\n    return lines.join(\"\\n\");\n  } catch (error) {\n    log.warn(`[cmc] preference synthesis failed (non-fatal): ${error instanceof Error ? error.message : String(error)}`);\n    return null;\n  }\n}\n"],"mappings":"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","names":[]}

package/dist/causal-retrieval.d.ts

@@ -0,0 +1,44 @@
+import { CausalEdge } from './causal-chain.js';
+import './causal-trajectory.js';
+import './objective-state.js';
+
+/**
+ * causal-retrieval.ts — CMC Phase 3: Causal Retrieval Channel
+ *
+ * Walks upstream/downstream causal chains during recall to surface
+ * connected trajectories. Branching points (multiple outgoing edges
+ * with different outcomes) get a counterfactual boost as they represent
+ * decision points worth surfacing.
+ */
+
+interface CausalRetrievalConfig {
+    maxDepth: number;
+    maxChars: number;
+    counterfactualBoost: number;
+}
+interface CausalRetrievalResult {
+    trajectoryId: string;
+    direction: "upstream" | "downstream" | "seed";
+    depth: number;
+    score: number;
+    edgeType?: CausalEdge["edgeType"];
+    edgeConfidence?: number;
+    isCounterfactual: boolean;
+    summary: string;
+}
+declare function formatCausalRetrievalSection(results: CausalRetrievalResult[], maxChars: number): string | null;
+/**
+ * Retrieve causal chain context for a recall query.
+ * 1. Use existing causal trajectory search for seed trajectories
+ * 2. Walk upstream/downstream from seeds
+ * 3. Format as recall section
+ */
+declare function retrieveCausalChains(options: {
+    memoryDir: string;
+    causalTrajectoryStoreDir?: string;
+    query: string;
+    sessionKey?: string;
+    config: CausalRetrievalConfig;
+}): Promise<string | null>;
+
+export { type CausalRetrievalConfig, type CausalRetrievalResult, formatCausalRetrievalSection, retrieveCausalChains };

package/dist/causal-retrieval.js

@@ -0,0 +1,184 @@
+import {
+  readChainIndex,
+  resolveChainsDir
+} from "./chunk-NTTLPF7F.js";
+import {
+  searchCausalTrajectories
+} from "./chunk-ORZMT74A.js";
+import "./chunk-M5KEYE5E.js";
+import "./chunk-DT5TVLJE.js";
+import {
+  log
+} from "./chunk-KWBU5S5U.js";
+import "./chunk-DGXUHMOV.js";
+import "./chunk-LPSF4OQH.js";
+
+// src/causal-retrieval.ts
+function walkUpstream(seedId, index, maxDepth, counterfactualBoost) {
+  const visited = /* @__PURE__ */ new Set([seedId]);
+  const results = [];
+  let frontier = [seedId];
+  for (let depth = 1; depth <= maxDepth; depth++) {
+    const nextFrontier = [];
+    for (const currentId of frontier) {
+      const incomingEdgeIds = index.incoming[currentId] ?? [];
+      for (const edgeId of incomingEdgeIds) {
+        const edge = index.edges[edgeId];
+        if (!edge) continue;
+        const fromId = edge.fromTrajectoryId;
+        if (visited.has(fromId)) continue;
+        visited.add(fromId);
+        const outgoingFromSource = index.outgoing[fromId] ?? [];
+        const isCounterfactual = outgoingFromSource.length > 1;
+        const depthDecay = 1 / depth;
+        let score = depthDecay * edge.confidence;
+        if (isCounterfactual) score += counterfactualBoost;
+        results.push({
+          trajectoryId: fromId,
+          depth,
+          score,
+          edgeType: edge.edgeType,
+          edgeConfidence: edge.confidence,
+          isCounterfactual
+        });
+        nextFrontier.push(fromId);
+      }
+    }
+    frontier = nextFrontier;
+    if (frontier.length === 0) break;
+  }
+  return results;
+}
+function walkDownstream(seedId, index, maxDepth, counterfactualBoost) {
+  const downstreamMaxDepth = Math.min(maxDepth, 2);
+  const visited = /* @__PURE__ */ new Set([seedId]);
+  const results = [];
+  let frontier = [seedId];
+  for (let depth = 1; depth <= downstreamMaxDepth; depth++) {
+    const nextFrontier = [];
+    for (const currentId of frontier) {
+      const outgoingEdgeIds = index.outgoing[currentId] ?? [];
+      const isCounterfactual = outgoingEdgeIds.length > 1;
+      for (const edgeId of outgoingEdgeIds) {
+        const edge = index.edges[edgeId];
+        if (!edge) continue;
+        const toId = edge.toTrajectoryId;
+        if (visited.has(toId)) continue;
+        visited.add(toId);
+        const depthDecay = 1 / (depth + 1);
+        let score = depthDecay * edge.confidence;
+        if (isCounterfactual) score += counterfactualBoost;
+        results.push({
+          trajectoryId: toId,
+          depth,
+          score,
+          edgeType: edge.edgeType,
+          edgeConfidence: edge.confidence,
+          isCounterfactual
+        });
+        nextFrontier.push(toId);
+      }
+    }
+    frontier = nextFrontier;
+    if (frontier.length === 0) break;
+  }
+  return results;
+}
+function formatRetrievalResult(result) {
+  const direction = result.direction === "upstream" ? "\u2191" : result.direction === "downstream" ? "\u2193" : "\u2022";
+  const counterfactual = result.isCounterfactual ? " [branching point]" : "";
+  const edgeInfo = result.edgeType ? ` (${result.edgeType})` : "";
+  return `- ${direction} ${result.summary}${edgeInfo}${counterfactual}`;
+}
+function formatCausalRetrievalSection(results, maxChars) {
+  if (results.length === 0) return null;
+  const lines = [
+    "## Causal Chain Context",
+    "",
+    "Related causal trajectories from connected sessions:",
+    ""
+  ];
+  let totalChars = lines.join("\n").length;
+  for (const result of results) {
+    const line = formatRetrievalResult(result);
+    if (totalChars + line.length + 1 > maxChars) break;
+    lines.push(line);
+    totalChars += line.length + 1;
+  }
+  if (lines.length <= 4) return null;
+  lines.push("");
+  return lines.join("\n");
+}
+async function retrieveCausalChains(options) {
+  try {
+    const { memoryDir, causalTrajectoryStoreDir, query, sessionKey, config: retrievalConfig } = options;
+    const seeds = await searchCausalTrajectories({
+      memoryDir,
+      causalTrajectoryStoreDir,
+      query,
+      maxResults: 3,
+      sessionKey
+    });
+    if (seeds.length === 0) return null;
+    const chainsDir = resolveChainsDir(memoryDir, causalTrajectoryStoreDir);
+    const chainIndex = await readChainIndex(chainsDir);
+    if (Object.keys(chainIndex.edges).length === 0) return null;
+    const allResults = [];
+    for (const seed of seeds) {
+      allResults.push({
+        trajectoryId: seed.record.trajectoryId,
+        direction: "seed",
+        depth: 0,
+        score: seed.score,
+        isCounterfactual: false,
+        summary: `[${seed.record.outcomeKind}] ${seed.record.goal} \u2192 ${seed.record.outcomeSummary}`
+      });
+      const upstream = walkUpstream(
+        seed.record.trajectoryId,
+        chainIndex,
+        retrievalConfig.maxDepth,
+        retrievalConfig.counterfactualBoost
+      );
+      for (const u of upstream) {
+        allResults.push({
+          trajectoryId: u.trajectoryId,
+          direction: "upstream",
+          depth: u.depth,
+          score: u.score,
+          edgeType: u.edgeType,
+          edgeConfidence: u.edgeConfidence,
+          isCounterfactual: u.isCounterfactual,
+          summary: `Depth ${u.depth}: trajectory ${u.trajectoryId.slice(0, 12)}`
+        });
+      }
+      const downstream = walkDownstream(
+        seed.record.trajectoryId,
+        chainIndex,
+        retrievalConfig.maxDepth,
+        retrievalConfig.counterfactualBoost
+      );
+      for (const d of downstream) {
+        allResults.push({
+          trajectoryId: d.trajectoryId,
+          direction: "downstream",
+          depth: d.depth,
+          score: d.score,
+          edgeType: d.edgeType,
+          edgeConfidence: d.edgeConfidence,
+          isCounterfactual: d.isCounterfactual,
+          summary: `Depth ${d.depth}: trajectory ${d.trajectoryId.slice(0, 12)}`
+        });
+      }
+    }
+    allResults.sort((a, b) => b.score - a.score);
+    return formatCausalRetrievalSection(allResults, retrievalConfig.maxChars);
+  } catch (error) {
+    log.warn(`[cmc] causal retrieval failed (non-fatal): ${error instanceof Error ? error.message : String(error)}`);
+    return null;
+  }
+}
+export {
+  formatCausalRetrievalSection,
+  retrieveCausalChains
+};
+//# sourceMappingURL=causal-retrieval.js.map

package/dist/causal-retrieval.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/causal-retrieval.ts"],"sourcesContent":["/**\n * causal-retrieval.ts — CMC Phase 3: Causal Retrieval Channel\n *\n * Walks upstream/downstream causal chains during recall to surface\n * connected trajectories. Branching points (multiple outgoing edges\n * with different outcomes) get a counterfactual boost as they represent\n * decision points worth surfacing.\n */\n\nimport type { CausalTrajectoryRecord } from \"./causal-trajectory.js\";\nimport { searchCausalTrajectories } from \"./causal-trajectory.js\";\nimport {\n  readChainIndex,\n  resolveChainsDir,\n  type CausalChainIndex,\n  type CausalEdge,\n} from \"./causal-chain.js\";\nimport { log } from \"./logger.js\";\n\n// ─── Types ───────────────────────────────────────────────────────────────────\n\nexport interface CausalRetrievalConfig {\n  maxDepth: number;\n  maxChars: number;\n  counterfactualBoost: number;\n}\n\nexport interface CausalRetrievalResult {\n  trajectoryId: string;\n  direction: \"upstream\" | \"downstream\" | \"seed\";\n  depth: number;\n  score: number;\n  edgeType?: CausalEdge[\"edgeType\"];\n  edgeConfidence?: number;\n  isCounterfactual: boolean;\n  summary: string;\n}\n\n// ─── Graph Traversal ─────────────────────────────────────────────────────────\n\n/**\n * Walk upstream (incoming edges) from a seed trajectory.\n */\nfunction walkUpstream(\n  seedId: string,\n  index: CausalChainIndex,\n  maxDepth: number,\n  counterfactualBoost: number,\n): Array<{ trajectoryId: string; depth: number; score: number; edgeType: CausalEdge[\"edgeType\"]; edgeConfidence: number; isCounterfactual: boolean }> {\n  const visited = new Set<string>([seedId]);\n  const results: Array<{ trajectoryId: string; depth: number; score: number; edgeType: CausalEdge[\"edgeType\"]; edgeConfidence: number; isCounterfactual: boolean }> = [];\n\n  let frontier = [seedId];\n  for (let depth = 1; depth <= maxDepth; depth++) {\n    const nextFrontier: string[] = [];\n\n    for (const currentId of frontier) {\n      const incomingEdgeIds = index.incoming[currentId] ?? [];\n\n      for (const edgeId of incomingEdgeIds) {\n        const edge = index.edges[edgeId];\n        if (!edge) continue;\n\n        const fromId = edge.fromTrajectoryId;\n        if (visited.has(fromId)) continue;\n        visited.add(fromId);\n\n        // Check if this is a counterfactual branching point\n        const outgoingFromSource = index.outgoing[fromId] ?? [];\n        const isCounterfactual = outgoingFromSource.length > 1;\n\n        const depthDecay = 1 / depth;\n        let score = depthDecay * edge.confidence;\n        if (isCounterfactual) score += counterfactualBoost;\n\n        results.push({\n          trajectoryId: fromId,\n          depth,\n          score,\n          edgeType: edge.edgeType,\n          edgeConfidence: edge.confidence,\n          isCounterfactual,\n        });\n\n        nextFrontier.push(fromId);\n      }\n    }\n\n    frontier = nextFrontier;\n    if (frontier.length === 0) break;\n  }\n\n  return results;\n}\n\n/**\n * Walk downstream (outgoing edges) from a seed trajectory.\n * Max 2 hops downstream (less relevant than upstream context).\n */\nfunction walkDownstream(\n  seedId: string,\n  index: CausalChainIndex,\n  maxDepth: number,\n  counterfactualBoost: number,\n): Array<{ trajectoryId: string; depth: number; score: number; edgeType: CausalEdge[\"edgeType\"]; edgeConfidence: number; isCounterfactual: boolean }> {\n  const downstreamMaxDepth = Math.min(maxDepth, 2);\n  const visited = new Set<string>([seedId]);\n  const results: Array<{ trajectoryId: string; depth: number; score: number; edgeType: CausalEdge[\"edgeType\"]; edgeConfidence: number; isCounterfactual: boolean }> = [];\n\n  let frontier = [seedId];\n  for (let depth = 1; depth <= downstreamMaxDepth; depth++) {\n    const nextFrontier: string[] = [];\n\n    for (const currentId of frontier) {\n      const outgoingEdgeIds = index.outgoing[currentId] ?? [];\n\n      // Counterfactual: multiple outgoing = branching point\n      const isCounterfactual = outgoingEdgeIds.length > 1;\n\n      for (const edgeId of outgoingEdgeIds) {\n        const edge = index.edges[edgeId];\n        if (!edge) continue;\n\n        const toId = edge.toTrajectoryId;\n        if (visited.has(toId)) continue;\n        visited.add(toId);\n\n        const depthDecay = 1 / (depth + 1); // downstream penalized more\n        let score = depthDecay * edge.confidence;\n        if (isCounterfactual) score += counterfactualBoost;\n\n        results.push({\n          trajectoryId: toId,\n          depth,\n          score,\n          edgeType: edge.edgeType,\n          edgeConfidence: edge.confidence,\n          isCounterfactual,\n        });\n\n        nextFrontier.push(toId);\n      }\n    }\n\n    frontier = nextFrontier;\n    if (frontier.length === 0) break;\n  }\n\n  return results;\n}\n\n// ─── Section Formatting ──────────────────────────────────────────────────────\n\nfunction formatRetrievalResult(result: CausalRetrievalResult): string {\n  const direction = result.direction === \"upstream\" ? \"↑\" : result.direction === \"downstream\" ? \"↓\" : \"•\";\n  const counterfactual = result.isCounterfactual ? \" [branching point]\" : \"\";\n  const edgeInfo = result.edgeType ? ` (${result.edgeType})` : \"\";\n  return `- ${direction} ${result.summary}${edgeInfo}${counterfactual}`;\n}\n\nexport function formatCausalRetrievalSection(\n  results: CausalRetrievalResult[],\n  maxChars: number,\n): string | null {\n  if (results.length === 0) return null;\n\n  const lines: string[] = [\n    \"## Causal Chain Context\",\n    \"\",\n    \"Related causal trajectories from connected sessions:\",\n    \"\",\n  ];\n\n  let totalChars = lines.join(\"\\n\").length;\n\n  for (const result of results) {\n    const line = formatRetrievalResult(result);\n    if (totalChars + line.length + 1 > maxChars) break;\n    lines.push(line);\n    totalChars += line.length + 1;\n  }\n\n  if (lines.length <= 4) return null; // only header, no content\n  lines.push(\"\");\n  return lines.join(\"\\n\");\n}\n\n// ─── Public API ──────────────────────────────────────────────────────────────\n\n/**\n * Retrieve causal chain context for a recall query.\n * 1. Use existing causal trajectory search for seed trajectories\n * 2. Walk upstream/downstream from seeds\n * 3. Format as recall section\n */\nexport async function retrieveCausalChains(options: {\n  memoryDir: string;\n  causalTrajectoryStoreDir?: string;\n  query: string;\n  sessionKey?: string;\n  config: CausalRetrievalConfig;\n}): Promise<string | null> {\n  try {\n    const { memoryDir, causalTrajectoryStoreDir, query, sessionKey, config: retrievalConfig } = options;\n\n    // 1. Search for seed trajectories matching the query\n    const seeds = await searchCausalTrajectories({\n      memoryDir,\n      causalTrajectoryStoreDir,\n      query,\n      maxResults: 3,\n      sessionKey,\n    });\n\n    if (seeds.length === 0) return null;\n\n    // 2. Load chain index\n    const chainsDir = resolveChainsDir(memoryDir, causalTrajectoryStoreDir);\n    const chainIndex = await readChainIndex(chainsDir);\n\n    if (Object.keys(chainIndex.edges).length === 0) return null;\n\n    // 3. Walk chains from each seed\n    const allResults: CausalRetrievalResult[] = [];\n\n    for (const seed of seeds) {\n      // Add seed itself\n      allResults.push({\n        trajectoryId: seed.record.trajectoryId,\n        direction: \"seed\",\n        depth: 0,\n        score: seed.score,\n        isCounterfactual: false,\n        summary: `[${seed.record.outcomeKind}] ${seed.record.goal} → ${seed.record.outcomeSummary}`,\n      });\n\n      // Walk upstream\n      const upstream = walkUpstream(\n        seed.record.trajectoryId,\n        chainIndex,\n        retrievalConfig.maxDepth,\n        retrievalConfig.counterfactualBoost,\n      );\n      for (const u of upstream) {\n        allResults.push({\n          trajectoryId: u.trajectoryId,\n          direction: \"upstream\",\n          depth: u.depth,\n          score: u.score,\n          edgeType: u.edgeType,\n          edgeConfidence: u.edgeConfidence,\n          isCounterfactual: u.isCounterfactual,\n          summary: `Depth ${u.depth}: trajectory ${u.trajectoryId.slice(0, 12)}`,\n        });\n      }\n\n      // Walk downstream\n      const downstream = walkDownstream(\n        seed.record.trajectoryId,\n        chainIndex,\n        retrievalConfig.maxDepth,\n        retrievalConfig.counterfactualBoost,\n      );\n      for (const d of downstream) {\n        allResults.push({\n          trajectoryId: d.trajectoryId,\n          direction: \"downstream\",\n          depth: d.depth,\n          score: d.score,\n          edgeType: d.edgeType,\n          edgeConfidence: d.edgeConfidence,\n          isCounterfactual: d.isCounterfactual,\n          summary: `Depth ${d.depth}: trajectory ${d.trajectoryId.slice(0, 12)}`,\n        });\n      }\n    }\n\n    // 4. Sort by score and format\n    allResults.sort((a, b) => b.score - a.score);\n\n    return formatCausalRetrievalSection(allResults, retrievalConfig.maxChars);\n  } catch (error) {\n    log.warn(`[cmc] causal retrieval failed (non-fatal): ${error instanceof Error ? error.message : String(error)}`);\n    return null;\n  }\n}\n"],"mappings":"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","names":[]}

package/dist/causal-trajectory-graph.d.ts

@@ -0,0 +1,13 @@
+import { GraphEdge } from './graph.js';
+import { CausalTrajectoryRecord } from './causal-trajectory.js';
+import './objective-state.js';
+
+type CausalTrajectoryGraphStage = "goal" | "action" | "observation" | "outcome" | "follow_up";
+declare function causalTrajectoryGraphNodeId(trajectoryId: string, stage: CausalTrajectoryGraphStage): string;
+declare function buildCausalTrajectoryGraphEdges(record: CausalTrajectoryRecord): GraphEdge[];
+declare function appendCausalTrajectoryGraphEdges(options: {
+    memoryDir: string;
+    record: CausalTrajectoryRecord;
+}): Promise<void>;
+
+export { type CausalTrajectoryGraphStage, appendCausalTrajectoryGraphEdges, buildCausalTrajectoryGraphEdges, causalTrajectoryGraphNodeId };