@remnic/plugin-openclaw 1.0.0

package/dist/calibration-KQXCC77L.js

@@ -0,0 +1,235 @@
+import {
+  FallbackLlmClient
+} from "./chunk-TJZ7KBCC.js";
+import {
+  listJsonFiles
+} from "./chunk-5LE4HTVL.js";
+import {
+  log
+} from "./chunk-DMGIUDBO.js";
+import "./chunk-MLKGABMK.js";
+
+// ../remnic-core/src/calibration.ts
+import { createHash } from "crypto";
+import path from "path";
+import { mkdir, readFile, writeFile } from "fs/promises";
+function calibrationDir(memoryDir) {
+  return path.join(memoryDir, "state", "calibration");
+}
+function calibrationIndexPath(memoryDir) {
+  return path.join(calibrationDir(memoryDir), "calibration-index.json");
+}
+async function readCalibrationIndex(memoryDir) {
+  try {
+    const raw = JSON.parse(await readFile(calibrationIndexPath(memoryDir), "utf8"));
+    return {
+      rules: Array.isArray(raw.rules) ? raw.rules : [],
+      updatedAt: typeof raw.updatedAt === "string" ? raw.updatedAt : (/* @__PURE__ */ new Date()).toISOString(),
+      totalCorrectionsAnalyzed: typeof raw.totalCorrectionsAnalyzed === "number" ? raw.totalCorrectionsAnalyzed : 0
+    };
+  } catch {
+    return { rules: [], updatedAt: (/* @__PURE__ */ new Date()).toISOString(), totalCorrectionsAnalyzed: 0 };
+  }
+}
+async function writeCalibrationIndex(memoryDir, index) {
+  const dir = calibrationDir(memoryDir);
+  await mkdir(dir, { recursive: true });
+  index.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
+  await writeFile(calibrationIndexPath(memoryDir), JSON.stringify(index, null, 2), "utf8");
+}
+async function readCorrections(memoryDir) {
+  const correctionsDir = path.join(memoryDir, "corrections");
+  const files = await listJsonFiles(correctionsDir).catch(() => {
+    return [];
+  });
+  const factsDir = path.join(memoryDir, "facts");
+  try {
+    const { readdir } = await import("fs/promises");
+    const dayDirs = (await readdir(factsDir)).filter((d) => /^\d{4}-\d{2}-\d{2}$/.test(d));
+    for (const day of dayDirs) {
+      const dayPath = path.join(factsDir, day);
+      const dayFiles = (await readdir(dayPath)).filter((f) => f.startsWith("correction-") && f.endsWith(".md")).map((f) => path.join(dayPath, f));
+      files.push(...dayFiles);
+    }
+  } catch {
+  }
+  try {
+    const { readdir } = await import("fs/promises");
+    const corrFiles = (await readdir(correctionsDir)).filter((f) => f.endsWith(".md")).map((f) => path.join(correctionsDir, f));
+    files.push(...corrFiles);
+  } catch {
+  }
+  const corrections = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const filePath of files) {
+    try {
+      const raw = await readFile(filePath, "utf8");
+      const fmMatch = raw.match(/^---\n([\s\S]*?)\n---\n([\s\S]*)$/);
+      if (!fmMatch) continue;
+      const content = fmMatch[2].trim();
+      if (!content || content.length < 10) continue;
+      const idMatch = fmMatch[1].match(/^id:\s*(.+)$/m);
+      const id = idMatch?.[1]?.trim() ?? path.basename(filePath, ".md");
+      if (seen.has(id)) continue;
+      seen.add(id);
+      const confMatch = fmMatch[1].match(/^confidence:\s*(.+)$/m);
+      const confidence = confMatch ? parseFloat(confMatch[1]) : 0.9;
+      const entityMatch = fmMatch[1].match(/^entityRef:\s*(.+)$/m);
+      const entityRefs = entityMatch ? [entityMatch[1].trim()] : [];
+      corrections.push({ id, content, created: "", confidence, entityRefs, tags: [] });
+    } catch {
+    }
+  }
+  return corrections;
+}
+var CLUSTER_PROMPT = `You are analyzing user corrections to an AI assistant. Each correction represents a moment where the assistant's prediction of what the user wanted was WRONG.
+
+Your job: Group these corrections into clusters where the SAME TYPE of misunderstanding is happening. Then for each cluster, synthesize a CalibrationRule.
+
+A CalibrationRule describes:
+- condition: When does this type of mistake happen?
+- modelTendency: What does the model tend to assume or do wrong?
+- userExpectation: What does the user actually want instead?
+- calibration: How should the model adjust its behavior?
+- ruleType: One of "model_tendency", "user_expectation", "scope_boundary", "verification_required"
+
+Focus on PATTERNS, not individual corrections. A cluster needs at least 2 corrections to be worth a rule.
+
+Output valid JSON only:
+{
+  "rules": [
+    {
+      "ruleType": "model_tendency",
+      "condition": "When discussing project scope or task boundaries",
+      "modelTendency": "The model tends to assume broader scope than the user intends",
+      "userExpectation": "The user prefers narrow, specific task definitions and wants to be asked before scope expansion",
+      "calibration": "When uncertain about scope, ask for clarification rather than assuming. Default to the narrower interpretation.",
+      "confidence": 0.85,
+      "evidenceIds": ["correction-id-1", "correction-id-2"]
+    }
+  ]
+}`;
+async function synthesizeCalibrationRules(corrections, llm, existingRules, agentId) {
+  if (corrections.length < 2) return [];
+  const correctionText = corrections.slice(0, 50).map((c, i) => `[${c.id}] ${c.content}`).join("\n\n");
+  const existingRulesText = existingRules.length > 0 ? `
+
+Existing calibration rules (avoid duplicating these):
+${existingRules.map((r) => `- ${r.condition}: ${r.calibration}`).join("\n")}` : "";
+  const response = await llm.chatCompletion(
+    [
+      { role: "system", content: CLUSTER_PROMPT },
+      { role: "user", content: `Here are ${corrections.length} corrections from this user:
+
+${correctionText}${existingRulesText}` }
+    ],
+    { temperature: 0.3, maxTokens: 3e3, agentId }
+  );
+  if (!response?.content) return [];
+  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);
+    if (!Array.isArray(parsed.rules)) return [];
+    const now = (/* @__PURE__ */ new Date()).toISOString();
+    return parsed.rules.filter((r) => r.condition && r.calibration && r.modelTendency).map((r) => ({
+      id: `cal-${createHash("sha256").update(r.condition + r.calibration).digest("hex").slice(0, 12)}`,
+      ruleType: r.ruleType ?? "model_tendency",
+      condition: String(r.condition),
+      modelTendency: String(r.modelTendency),
+      userExpectation: String(r.userExpectation ?? ""),
+      calibration: String(r.calibration),
+      confidence: typeof r.confidence === "number" ? r.confidence : 0.7,
+      evidenceCount: Array.isArray(r.evidenceIds) ? r.evidenceIds.length : 1,
+      evidenceCorrectionIds: Array.isArray(r.evidenceIds) ? r.evidenceIds : [],
+      createdAt: now,
+      lastReinforcedAt: now
+    }));
+  } catch {
+    log.warn("[calibration] failed to parse LLM response");
+    return [];
+  }
+}
+function buildCalibrationRecallSection(rules, query, maxChars = 1200) {
+  if (rules.length === 0) return null;
+  const lines = [
+    "## Model Calibration (learned from past corrections)",
+    "",
+    "Adjustments for this specific user, learned from patterns in their corrections:",
+    ""
+  ];
+  let totalChars = lines.join("\n").length;
+  for (const rule of rules) {
+    const line = `- **${rule.condition}**: ${rule.modelTendency} \u2192 Instead: ${rule.calibration}`;
+    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 runCalibrationConsolidation(options) {
+  try {
+    const llm = new FallbackLlmClient(options.gatewayConfig);
+    if (!llm.isAvailable(options.gatewayAgentId)) {
+      log.debug("[calibration] no LLM available \u2014 skipping consolidation");
+      return [];
+    }
+    const corrections = await readCorrections(options.memoryDir);
+    if (corrections.length < 3) {
+      log.debug(`[calibration] only ${corrections.length} corrections \u2014 need at least 3`);
+      return [];
+    }
+    const existingIndex = await readCalibrationIndex(options.memoryDir);
+    const newRules = await synthesizeCalibrationRules(corrections, llm, existingIndex.rules, options.gatewayAgentId);
+    if (newRules.length === 0) {
+      log.debug("[calibration] no new calibration rules synthesized");
+      return existingIndex.rules;
+    }
+    const ruleMap = new Map(existingIndex.rules.map((r) => [r.id, r]));
+    for (const rule of newRules) {
+      if (ruleMap.has(rule.id)) {
+        const existing = ruleMap.get(rule.id);
+        existing.lastReinforcedAt = (/* @__PURE__ */ new Date()).toISOString();
+        existing.evidenceCount += rule.evidenceCount;
+        existing.confidence = Math.min(1, existing.confidence + 0.05);
+      } else {
+        ruleMap.set(rule.id, rule);
+      }
+    }
+    const allRules = [...ruleMap.values()];
+    await writeCalibrationIndex(options.memoryDir, {
+      rules: allRules,
+      updatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+      totalCorrectionsAnalyzed: corrections.length
+    });
+    log.debug(`[calibration] synthesized ${newRules.length} new rule(s), ${allRules.length} total`);
+    return allRules;
+  } catch (error) {
+    log.warn(`[calibration] consolidation failed (non-fatal): ${error instanceof Error ? error.message : String(error)}`);
+    return [];
+  }
+}
+async function runCalibrationIfEnabled(options) {
+  if (!options.calibrationEnabled) {
+    return [];
+  }
+  return runCalibrationConsolidation({
+    memoryDir: options.memoryDir,
+    gatewayConfig: options.gatewayConfig
+  });
+}
+async function getCalibrationRulesForRecall(memoryDir) {
+  const index = await readCalibrationIndex(memoryDir);
+  return index.rules;
+}
+export {
+  buildCalibrationRecallSection,
+  getCalibrationRulesForRecall,
+  readCalibrationIndex,
+  runCalibrationConsolidation,
+  runCalibrationIfEnabled,
+  synthesizeCalibrationRules
+};

package/dist/causal-chain-LA3IQNL6.js

@@ -0,0 +1,22 @@
+import {
+  makeEdgeId,
+  readChainIndex,
+  resolveChainsDir,
+  scoreStitchCandidate,
+  stitchCausalChain,
+  validateCausalEdge,
+  writeChainIndex
+} from "./chunk-HSBPDYF4.js";
+import "./chunk-JGEKL3WH.js";
+import "./chunk-5LE4HTVL.js";
+import "./chunk-DMGIUDBO.js";
+import "./chunk-MLKGABMK.js";
+export {
+  makeEdgeId,
+  readChainIndex,
+  resolveChainsDir,
+  scoreStitchCandidate,
+  stitchCausalChain,
+  validateCausalEdge,
+  writeChainIndex
+};

package/dist/causal-consolidation-WINYJQJ4.js

@@ -0,0 +1,205 @@
+import {
+  readChainIndex,
+  resolveChainsDir
+} from "./chunk-HSBPDYF4.js";
+import {
+  isRecord
+} from "./chunk-JGEKL3WH.js";
+import {
+  FallbackLlmClient
+} from "./chunk-TJZ7KBCC.js";
+import {
+  listJsonFiles,
+  readJsonFile
+} from "./chunk-5LE4HTVL.js";
+import {
+  log
+} from "./chunk-DMGIUDBO.js";
+import "./chunk-MLKGABMK.js";
+
+// ../remnic-core/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
+};

package/dist/causal-retrieval-ITNQBUQM.js

@@ -0,0 +1,182 @@
+import {
+  searchCausalTrajectories
+} from "./chunk-BZ27H3BL.js";
+import {
+  readChainIndex,
+  resolveChainsDir
+} from "./chunk-HSBPDYF4.js";
+import "./chunk-JGEKL3WH.js";
+import "./chunk-5LE4HTVL.js";
+import {
+  log
+} from "./chunk-DMGIUDBO.js";
+import "./chunk-MLKGABMK.js";
+
+// ../remnic-core/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
+};