@tangle-network/agent-knowledge 4.0.0 → 4.0.1

package/dist/{chunk-UWOTQNBI.js → chunk-3CAAGJCE.js}

@@ -18,7 +18,7 @@ import {
   runBoundedMemoryLifecycle,
   scoreMemoryBenchmarkArtifact,
   sleepForMemoryRecovery
-} from "./chunk-DW6APRTX.js";
+} from "./chunk-BBCIB4UL.js";
 import {
   sha256,
   stableId
@@ -964,23 +964,127 @@ function cloneDurableValue(value) {
   );
 }
 
-// src/memory/experiment.ts
-import { randomUUID as randomUUID2 } from "crypto";
-import { join } from "path";
-import { canonicalJson as canonicalJson3 } from "@tangle-network/agent-eval";
-import {
-  createRunCostLedger,
-  fsCampaignStorage,
-  resolveRunDir,
-  runCampaign
-} from "@tangle-network/agent-eval/campaign";
-var MEMORY_EXPERIMENT_IMPLEMENTATION_REF = "agent-knowledge:memory-experiment:v6";
-var AgentMemoryCleanupError = class extends AggregateError {
-  constructor(errors, message) {
-    super(errors, message);
-    this.name = "AgentMemoryCleanupError";
+// src/memory/experiment/validation.ts
+function assertMemorySequences(sequences) {
+  for (const sequence of sequences) {
+    assertNonEmptyString(sequence.family, `memory experiment sequence ${sequence.id} family`);
+    if (sequence.steps.length === 0) {
+      throw new Error(`memory experiment sequence ${sequence.id} has no steps`);
+    }
+    assertUnique(
+      sequence.steps.map((step) => step.id),
+      `step in sequence ${sequence.id}`
+    );
+    let probeCount = 0;
+    for (const step of sequence.steps) {
+      for (const write of step.writes ?? []) {
+        assertNonEmptyString(write.text, `memory experiment write in ${sequence.id}/${step.id}`);
+        if (write.id !== void 0) {
+          assertNonEmptyString(write.id, `memory experiment write id in ${sequence.id}/${step.id}`);
+        }
+      }
+      assertUnique(
+        (step.probes ?? []).map((probe) => probe.id),
+        `probe in sequence ${sequence.id} step ${step.id}`
+      );
+      for (const probe of step.probes ?? []) {
+        probeCount += 1;
+        assertNonEmptyString(
+          probe.query,
+          `memory experiment probe query ${sequence.id}/${step.id}/${probe.id}`
+        );
+        if (probe.limit !== void 0 && (!Number.isSafeInteger(probe.limit) || probe.limit <= 0)) {
+          throw new Error(
+            `memory experiment probe limit ${sequence.id}/${step.id}/${probe.id} must be a positive safe integer`
+          );
+        }
+        assertMemoryFactMatchers(
+          probe.requiredFacts ?? [],
+          `${sequence.id}/${step.id}/${probe.id} requiredFacts`
+        );
+        assertMemoryFactMatchers(
+          probe.forbiddenFacts ?? [],
+          `${sequence.id}/${step.id}/${probe.id} forbiddenFacts`
+        );
+        assertStringList(probe.expectedEventIds, `${sequence.id}/${step.id}/${probe.id} event ids`);
+        assertStringList(probe.expectedActorIds, `${sequence.id}/${step.id}/${probe.id} actor ids`);
+        if (probe.referenceAnswer !== void 0) {
+          assertNonEmptyString(
+            probe.referenceAnswer,
+            `memory experiment reference answer ${sequence.id}/${step.id}/${probe.id}`
+          );
+        }
+        const hasTarget = (probe.requiredFacts?.length ?? 0) > 0 || (probe.forbiddenFacts?.length ?? 0) > 0 || (probe.expectedEventIds?.length ?? 0) > 0 || (probe.expectedActorIds?.length ?? 0) > 0 || Boolean(probe.referenceAnswer?.trim());
+        if (!hasTarget) {
+          throw new Error(
+            `memory experiment probe ${sequence.id}/${step.id}/${probe.id} has no measurable target`
+          );
+        }
+      }
+    }
+    if (probeCount === 0) {
+      throw new Error(`memory experiment sequence ${sequence.id} has no probes`);
+    }
   }
-};
+}
+function normalizeCleanupScope(scope) {
+  const normalized = compactScope(scope);
+  if (normalized.tags && Object.keys(normalized.tags).length === 0) {
+    delete normalized.tags;
+  }
+  return normalized;
+}
+function compactScope(scope) {
+  return Object.fromEntries(
+    Object.entries(scope).filter(([, value]) => value !== void 0)
+  );
+}
+function compactRecord(record2) {
+  return Object.fromEntries(Object.entries(record2).filter(([, value]) => value !== void 0));
+}
+function uniqueStrings(values) {
+  return [...new Set(values.filter((value) => typeof value === "string"))];
+}
+function stringArray(value) {
+  return Array.isArray(value) ? value.filter((entry) => typeof entry === "string") : [];
+}
+function assertUnique(values, label) {
+  const seen = /* @__PURE__ */ new Set();
+  for (const value of values) {
+    assertNonEmptyString(value, `memory experiment ${label} id`);
+    if (seen.has(value)) throw new Error(`duplicate memory experiment ${label} id: ${value}`);
+    seen.add(value);
+  }
+}
+function assertMemoryFactMatchers(matchers, label) {
+  assertUnique(
+    matchers.map((matcher) => matcher.id),
+    `${label} matcher`
+  );
+  for (const matcher of matchers) {
+    if (matcher.anyOf.length === 0) {
+      throw new Error(`memory experiment ${label} matcher ${matcher.id} requires anyOf`);
+    }
+    assertStringList(matcher.anyOf, `${label} matcher ${matcher.id} anyOf`);
+    assertStringList(matcher.sourceEventIds, `${label} matcher ${matcher.id} source event ids`);
+    if (matcher.weight !== void 0 && (!Number.isFinite(matcher.weight) || matcher.weight <= 0)) {
+      throw new Error(
+        `memory experiment ${label} matcher ${matcher.id} weight must be a positive finite number`
+      );
+    }
+  }
+}
+function assertStringList(values, label) {
+  if (values === void 0) return;
+  assertUnique(values, label);
+}
+function assertNonEmptyString(value, label) {
+  if (typeof value !== "string" || value.trim().length === 0) {
+    throw new Error(`${label} must be a non-empty string`);
+  }
+}
+
+// src/memory/experiment/cases.ts
 function buildAgentMemorySequencesFromBenchmarkCases(cases, options = {}) {
   const memoryAgentId = options.memoryAgentId ?? "benchmark-agent";
   return cases.map((testCase) => ({
@@ -1042,646 +1146,292 @@ function buildAgentMemorySequencesFromBenchmarkCases(cases, options = {}) {
     ]
   }));
 }
-async function runAgentMemoryExperiment(options) {
-  assertNonEmptyString(options.experimentId, "memory experiment experimentId");
-  assertNonEmptyString(options.runDir, "memory experiment runDir");
-  if (options.experimentRunId !== void 0) {
-    assertNonEmptyString(options.experimentRunId, "memory experiment experimentRunId");
-  }
-  if (options.sequences.length === 0) throw new Error("memory experiment requires sequences");
-  if (options.candidates.length === 0) throw new Error("memory experiment requires candidates");
-  if (options.executeStep && !options.executeStepRef) {
-    throw new Error("memory experiment executeStepRef is required when executeStep is configured");
-  }
-  assertUnique(
-    options.sequences.map((sequence) => sequence.id),
-    "sequence"
-  );
-  assertUnique(
-    [...options.candidates, ...options.recoveryCandidates ?? []].map((candidate) => candidate.id),
-    "candidate"
+function buildAgentMemorySequenceScenarios(sequences, candidates) {
+  return candidates.flatMap(
+    (candidate) => sequences.map((sequence) => ({
+      id: `${stableId("candidate", candidate.id)}:${sequence.id}`,
+      kind: "agent-memory-sequence",
+      candidateId: candidate.id,
+      sequenceId: sequence.id,
+      sequence,
+      seedGroup: sequence.id,
+      tags: [.../* @__PURE__ */ new Set([sequence.split ?? "dev", ...sequence.tags ?? [], candidate.id])]
+    }))
   );
-  assertMemorySequences(options.sequences);
-  for (const candidate of [...options.candidates, ...options.recoveryCandidates ?? []]) {
-    if (options.cleanupBranches === false && !candidate.disposeAdapter) {
-      throw new Error(
-        `${candidate.id}: cleanupBranches=false requires disposeAdapter to delete isolated external state`
-      );
-    }
-    if (candidate.externalCostUsdPerSequence !== void 0 && (!Number.isFinite(candidate.externalCostUsdPerSequence) || candidate.externalCostUsdPerSequence < 0)) {
-      throw new Error(
-        `${candidate.id}: externalCostUsdPerSequence must be a non-negative finite number`
-      );
-    }
-    if (candidate.externalRecoveryCostUsdPerAttempt !== void 0 && (!Number.isFinite(candidate.externalRecoveryCostUsdPerAttempt) || candidate.externalRecoveryCostUsdPerAttempt < 0)) {
-      throw new Error(
-        `${candidate.id}: externalRecoveryCostUsdPerAttempt must be a non-negative finite number`
-      );
+}
+function agentMemorySequenceJudge() {
+  return {
+    name: "agent-memory-sequence",
+    judgeVersion: "agent-knowledge:memory-sequence:v2",
+    dimensions: [
+      { key: "score", description: "mean memory probe score" },
+      { key: "passed", description: "1 when every memory probe passes" },
+      { key: "memory_fact_recall", description: "current memory fact coverage" },
+      { key: "memory_event_recall", description: "memory source event coverage" },
+      { key: "memory_actor_recall", description: "memory actor attribution coverage" },
+      { key: "memory_stale_safe", description: "1 when obsolete memory is not reused" }
+    ],
+    score({ artifact }) {
+      return {
+        composite: artifact.score,
+        dimensions: {
+          score: artifact.score,
+          passed: artifact.passed ? 1 : 0,
+          ...artifact.dimensions
+        },
+        notes: `${artifact.probes.filter((probe) => probe.passed).length}/${artifact.probes.length} probes passed`
+      };
     }
-    assertNonEmptyString(candidate.ref, `${candidate.id} ref`);
-  }
-  const storage = options.storage ?? fsCampaignStorage();
-  const runDir = resolveRunDir(options.runDir, options.repo);
-  if (!storage.append) {
-    throw new Error("memory experiment requires CampaignStorage.append for durable attempt state");
-  }
-  resolveMemoryCleanupTimeoutMs(options.cleanupTimeoutMs, "memory experiment");
-  const maxRecoveryAttempts = options.maxRecoveryAttempts ?? 1e3;
-  if (!Number.isSafeInteger(maxRecoveryAttempts) || maxRecoveryAttempts <= 0) {
-    throw new Error("memory experiment maxRecoveryAttempts must be a positive safe integer");
-  }
-  const maxRecoveryRetriesPerAttempt = options.maxRecoveryRetriesPerAttempt ?? DEFAULT_MEMORY_RECOVERY_RETRIES_PER_ATTEMPT;
-  if (!Number.isSafeInteger(maxRecoveryRetriesPerAttempt) || maxRecoveryRetriesPerAttempt <= 0) {
-    throw new Error(
-      "memory experiment maxRecoveryRetriesPerAttempt must be a positive safe integer"
-    );
-  }
-  storage.ensureDir(runDir);
-  const lease = await acquireAgentMemoryRunLease({
-    experimentId: options.experimentId,
-    runDir,
-    storage,
-    customStorage: options.storage !== void 0,
-    lockFileName: "memory-experiment.lock",
-    label: "memory experiment",
-    controllerMode: options.controllerMode,
-    acquireRunLease: options.acquireRunLease
-  });
-  let result;
-  let primaryError;
-  try {
-    await lease.assertOwned();
-    result = await runOwnedAgentMemoryExperiment(options, storage, runDir, lease);
-  } catch (error) {
-    primaryError = error;
-  }
-  let releaseError;
-  try {
-    await lease.release();
-  } catch (error) {
-    releaseError = error;
-  }
-  if (primaryError && releaseError) {
-    throw new AggregateError(
-      [primaryError, releaseError],
-      "memory experiment failed and its controller lease could not be released"
-    );
-  }
-  if (primaryError) throw primaryError;
-  if (releaseError) throw releaseError;
-  if (!result) throw new Error("memory experiment produced no result");
-  return result;
+  };
 }
-async function runOwnedAgentMemoryExperiment(options, storage, runDir, lease) {
-  const runIdentity = stableId(
-    "memory_run",
-    canonicalJson3({
-      experimentId: options.experimentId,
-      experimentRunId: options.experimentRunId ?? runDir
-    })
-  );
-  const maxConcurrency = options.maxConcurrency ?? 2;
-  if (!Number.isSafeInteger(maxConcurrency) || maxConcurrency <= 0) {
-    throw new Error("memory experiment maxConcurrency must be a positive safe integer");
-  }
-  const executionPool = createMemoryExecutionPool(maxConcurrency);
-  const dispatchedExecutions = [];
-  const candidateById = new Map(options.candidates.map((candidate) => [candidate.id, candidate]));
-  const recoveryCandidateById = new Map(
-    [...options.candidates, ...options.recoveryCandidates ?? []].map((candidate) => [
-      candidate.id,
-      candidate
-    ])
-  );
-  const sequenceById = new Map(options.sequences.map((sequence) => [sequence.id, sequence]));
-  const scenarios = buildAgentMemorySequenceScenarios(options.sequences, options.candidates);
-  const attemptLogPath = join(runDir, "memory-attempts.jsonl");
-  const recoveryLogPath = join(runDir, "memory-recovery-attempts.jsonl");
-  const costCeiling = options.costCeiling ?? options.costLedger?.costCeilingUsd ?? 0;
-  const costLedger = options.costLedger ?? createRunCostLedger({
-    storage,
-    runDir,
-    costCeilingUsd: costCeiling
-  });
-  if (costLedger.costCeilingUsd !== costCeiling) {
-    throw new Error("memory experiment costCeiling must match the shared cost ledger ceiling");
-  }
-  storage.ensureDir(runDir);
-  await recoverAbandonedMemoryAttempts({
-    options,
-    storage,
-    runDir,
-    attemptLogPath,
-    candidateById: recoveryCandidateById,
-    sequenceById,
-    lease,
-    maxConcurrency,
-    costLedger,
-    maxRecoveryAttempts: options.maxRecoveryAttempts ?? 1e3,
-    recoveryLogPath,
-    maxRecoveryRetriesPerAttempt: options.maxRecoveryRetriesPerAttempt ?? DEFAULT_MEMORY_RECOVERY_RETRIES_PER_ATTEMPT
+
+// src/memory/experiment/run.ts
+import { join } from "path";
+import { canonicalJson as canonicalJson4 } from "@tangle-network/agent-eval";
+import {
+  createRunCostLedger,
+  fsCampaignStorage,
+  resolveRunDir,
+  runCampaign
+} from "@tangle-network/agent-eval/campaign";
+
+// src/memory/experiment/cell.ts
+import { randomUUID as randomUUID2 } from "crypto";
+
+// src/memory/experiment/metrics.ts
+function rankAgentMemoryExperiment(candidates, scenarios, campaign, costByCandidate) {
+  const scenarioById = new Map(scenarios.map((scenario) => [scenario.id, scenario]));
+  const rows = candidates.map((candidate) => {
+    const candidateScenarios = scenarios.filter((scenario) => scenario.candidateId === candidate.id);
+    const cells = campaign.cells.filter(
+      (cell) => scenarioById.get(cell.scenarioId)?.candidateId === candidate.id
+    );
+    const successful = cells.filter((cell) => !cell.error && cell.artifact);
+    const dimensionRows = successful.map((cell) => cell.artifact.dimensions);
+    return {
+      rank: 0,
+      candidateId: candidate.id,
+      label: candidate.label ?? candidate.id,
+      scoreMean: mean(
+        cells.map((cell) => !cell.error && cell.artifact ? cell.artifact.score : 0)
+      ),
+      passRate: mean(cells.map((cell) => !cell.error && cell.artifact?.passed ? 1 : 0)),
+      totalSequences: candidateScenarios.length,
+      totalCells: cells.length,
+      totalProbes: successful.reduce((sum, cell) => sum + cell.artifact.probes.length, 0),
+      cellsFailed: cells.filter((cell) => Boolean(cell.error)).length,
+      totalCostUsd: normalizeUsd(costByCandidate.get(candidate.id) ?? 0),
+      durationMs: cells.reduce((sum, cell) => sum + cell.durationMs, 0),
+      dimensions: meanDimensions(dimensionRows)
+    };
   });
-  await lease.assertOwned();
-  let campaign;
-  let campaignError;
-  let settledExecutions = [];
-  try {
-    campaign = await runCampaign({
-      scenarios,
-      dispatch: (scenario, context) => {
-        const candidate = candidateById.get(scenario.candidateId);
-        if (!candidate) throw new Error(`unknown memory candidate ${scenario.candidateId}`);
-        const operation = executionPool.run(
-          () => runSequenceCell({
-            options,
-            candidate,
-            scenario,
-            context,
-            runIdentity,
-            storage,
-            attemptLogPath,
-            lease
-          })
-        );
-        dispatchedExecutions.push(operation);
-        return operation;
-      },
-      dispatchRef: memoryExperimentDispatchRef(options),
-      judges: [agentMemorySequenceJudge()],
-      runDir,
-      storage,
-      seed: options.seed,
-      reps: options.reps,
-      resumable: options.resumable,
-      costCeiling,
-      costLedger,
-      costPhase: options.costPhase,
-      maxConcurrency,
-      dispatchTimeoutMs: options.dispatchTimeoutMs,
-      expectUsage: "off",
-      now: options.now
-    });
-  } catch (error) {
-    campaignError = error;
-  } finally {
-    settledExecutions = await Promise.allSettled(dispatchedExecutions);
-  }
-  const cleanupFailures = settledExecutions.flatMap(
-    (settled) => settled.status === "rejected" && settled.reason instanceof AgentMemoryCleanupError ? [settled.reason] : []
+  return rows.sort(
+    (a, b) => Number(a.cellsFailed > 0) - Number(b.cellsFailed > 0) || b.scoreMean - a.scoreMean || b.passRate - a.passRate || a.totalCostUsd - b.totalCostUsd || a.candidateId.localeCompare(b.candidateId)
+  ).map((row, index) => ({ ...row, rank: index + 1 }));
+}
+function memoryExperimentCostByCandidate(costLedger, runDir, scenarios, candidateIdsInput) {
+  const candidateByScenario = new Map(
+    scenarios.map((scenario) => [scenario.id, scenario.candidateId])
   );
-  if (campaignError && cleanupFailures.length > 0) {
-    throw new AggregateError(
-      [campaignError, ...cleanupFailures],
-      "memory experiment failed and provider cleanup also failed"
-    );
+  const candidateIds = new Set(candidateIdsInput);
+  const totals = /* @__PURE__ */ new Map();
+  for (const receipt of costLedger.list()) {
+    if (receipt.tags?.runDir !== runDir) continue;
+    const scenarioCandidate = receipt.tags.scenarioId ? candidateByScenario.get(receipt.tags.scenarioId) : void 0;
+    const recoveryCandidate = receipt.tags.memoryRecovery === "attempt" && receipt.tags.candidateId ? receipt.tags.candidateId : void 0;
+    const candidateId = scenarioCandidate ?? recoveryCandidate;
+    if (!candidateId || !candidateIds.has(candidateId)) continue;
+    totals.set(candidateId, (totals.get(candidateId) ?? 0) + receipt.costUsd);
   }
-  if (campaignError) throw campaignError;
-  if (cleanupFailures.length > 0) {
-    throw new AggregateError(cleanupFailures, "memory experiment cleanup failed after dispatch");
+  return totals;
+}
+function renderAgentMemoryExperimentRanking(rows, totalCostUsd, unrankedRecoveryCostUsd) {
+  return [
+    "# Agent Memory Experiment",
+    "",
+    `- total cost: $${format(totalCostUsd)}`,
+    `- retired-candidate recovery cost: $${format(unrankedRecoveryCostUsd)}`,
+    "",
+    "| rank | candidate | sequences | cells | probes | failed | score | pass rate | cost | duration ms |",
+    "| ---: | --- | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: |",
+    ...rows.map(
+      (row) => `| ${row.rank} | ${row.label} | ${row.totalSequences} | ${row.totalCells} | ${row.totalProbes} | ${row.cellsFailed} | ${format(row.scoreMean)} | ${format(row.passRate)} | $${format(row.totalCostUsd)} | ${format(row.durationMs)} |`
+    ),
+    ""
+  ].join("\n");
+}
+function meanDimensions(rows) {
+  const values = /* @__PURE__ */ new Map();
+  for (const row of rows) {
+    for (const [key, value] of Object.entries(row)) {
+      if (!Number.isFinite(value)) continue;
+      const bucket = values.get(key) ?? [];
+      bucket.push(value);
+      values.set(key, bucket);
+    }
   }
-  if (!campaign) throw new Error("memory experiment produced no campaign result");
-  await lease.assertOwned();
-  const costByCandidate = memoryExperimentCostByCandidate(
-    costLedger,
-    campaign.runDir,
-    scenarios,
-    [...options.candidates, ...options.recoveryCandidates ?? []].map((candidate) => candidate.id)
-  );
-  const unrankedRecoveryCostUsd = normalizeUsd(
-    (options.recoveryCandidates ?? []).reduce(
-      (sum, candidate) => sum + (costByCandidate.get(candidate.id) ?? 0),
-      0
-    )
-  );
-  const totalCostUsd = normalizeUsd(
-    [...costByCandidate.values()].reduce((sum, cost) => sum + cost, 0)
-  );
-  const rows = rankAgentMemoryExperiment(options.candidates, scenarios, campaign, costByCandidate);
-  const rankingJsonPath = join(campaign.runDir, "memory-experiment-ranking.json");
-  const rankingMarkdownPath = join(campaign.runDir, "memory-experiment-ranking.md");
-  storage.write(
-    rankingJsonPath,
-    `${JSON.stringify(
-      { experimentId: options.experimentId, totalCostUsd, unrankedRecoveryCostUsd, rows },
-      null,
-      2
-    )}
-`
-  );
-  storage.write(
-    rankingMarkdownPath,
-    renderAgentMemoryExperimentRanking(rows, totalCostUsd, unrankedRecoveryCostUsd)
-  );
-  return {
-    campaign,
-    rows,
-    totalCostUsd,
-    unrankedRecoveryCostUsd,
-    leaderCandidateId: rows.find((row) => row.cellsFailed === 0)?.candidateId,
-    rankingJsonPath,
-    rankingMarkdownPath,
-    attemptLogPath,
-    recoveryLogPath
-  };
+  return Object.fromEntries([...values].map(([key, bucket]) => [key, mean(bucket)]));
 }
-function buildAgentMemorySequenceScenarios(sequences, candidates) {
-  return candidates.flatMap(
-    (candidate) => sequences.map((sequence) => ({
-      id: `${stableId("candidate", candidate.id)}:${sequence.id}`,
-      kind: "agent-memory-sequence",
-      candidateId: candidate.id,
-      sequenceId: sequence.id,
-      sequence,
-      seedGroup: sequence.id,
-      tags: [.../* @__PURE__ */ new Set([sequence.split ?? "dev", ...sequence.tags ?? [], candidate.id])]
-    }))
-  );
+function countDimensions(rows) {
+  const counts = /* @__PURE__ */ new Map();
+  for (const row of rows) {
+    for (const key of new Set(row)) counts.set(key, (counts.get(key) ?? 0) + 1);
+  }
+  return Object.fromEntries(counts);
 }
-function agentMemorySequenceJudge() {
-  return {
-    name: "agent-memory-sequence",
-    judgeVersion: "agent-knowledge:memory-sequence:v2",
-    dimensions: [
-      { key: "score", description: "mean memory probe score" },
-      { key: "passed", description: "1 when every memory probe passes" },
-      { key: "memory_fact_recall", description: "current memory fact coverage" },
-      { key: "memory_event_recall", description: "memory source event coverage" },
-      { key: "memory_actor_recall", description: "memory actor attribution coverage" },
-      { key: "memory_stale_safe", description: "1 when obsolete memory is not reused" }
-    ],
-    score({ artifact }) {
-      return {
-        composite: artifact.score,
-        dimensions: {
-          score: artifact.score,
-          passed: artifact.passed ? 1 : 0,
-          ...artifact.dimensions
-        },
-        notes: `${artifact.probes.filter((probe) => probe.passed).length}/${artifact.probes.length} probes passed`
-      };
-    }
+function mean(values) {
+  return values.length === 0 ? 0 : values.reduce((sum, value) => sum + value, 0) / values.length;
+}
+function format(value) {
+  return Number.isFinite(value) ? value.toFixed(4) : "0.0000";
+}
+function normalizeUsd(value) {
+  return Number(value.toFixed(12));
+}
+
+// src/memory/experiment/recovery.ts
+import { canonicalJson as canonicalJson3 } from "@tangle-network/agent-eval";
+
+// src/memory/experiment/runtime.ts
+var AgentMemoryCleanupError = class extends AggregateError {
+  constructor(errors, message) {
+    super(errors, message);
+    this.name = "AgentMemoryCleanupError";
+  }
+};
+function trackExternalMemoryCalls(adapter, onExternalCall) {
+  return {
+    id: adapter.id,
+    branchIsolation: adapter.branchIsolation,
+    search(query, options) {
+      onExternalCall();
+      return adapter.search.call(adapter, query, options);
+    },
+    getContext(query, options) {
+      onExternalCall();
+      return adapter.getContext.call(adapter, query, options);
+    },
+    write(input) {
+      onExternalCall();
+      return adapter.write.call(adapter, input);
+    },
+    ...adapter.clear ? {
+      clear(scope) {
+        onExternalCall();
+        return adapter.clear.call(adapter, scope);
+      }
+    } : {},
+    ...adapter.flush ? {
+      flush() {
+        onExternalCall();
+        return adapter.flush.call(adapter);
+      }
+    } : {},
+    ...adapter.close ? {
+      close() {
+        onExternalCall();
+        return adapter.close.call(adapter);
+      }
+    } : {}
   };
 }
-async function runSequenceCell(input) {
-  const { options, candidate, scenario, context, runIdentity, storage, attemptLogPath, lease } = input;
-  const cleanupBranches = options.cleanupBranches ?? true;
-  const costUsd = candidate.externalCostUsdPerSequence ?? 0;
-  if (!Number.isFinite(costUsd) || costUsd < 0) {
-    throw new Error(
-      `${candidate.id}: externalCostUsdPerSequence must be a non-negative finite number`
-    );
+function mergeScopes2(base, extra) {
+  return {
+    ...base ?? {},
+    ...extra ?? {},
+    tags: { ...base?.tags ?? {}, ...extra?.tags ?? {} }
+  };
+}
+function memoryExperimentBaseScope(options, candidate, sequenceId) {
+  return mergeScopes2(candidate.baseScope, {
+    tags: {
+      memoryExperimentId: options.experimentId,
+      memoryCandidateId: candidate.id,
+      memorySequenceId: sequenceId
+    }
+  });
+}
+function sequenceCleanupScopes(sequence) {
+  const scopes = /* @__PURE__ */ new Map();
+  for (const scope of sequence.cleanupScopes ?? []) {
+    const normalized = normalizeCleanupScope(scope);
+    scopes.set(JSON.stringify(normalized), normalized);
   }
-  if (!cleanupBranches && !candidate.disposeAdapter) {
+  for (const step of sequence.steps) {
+    const candidates = [
+      ...step.scope ? [step.scope] : [],
+      ...(step.writes ?? []).map((write) => mergeScopes2(step.scope, write.scope)),
+      ...(step.probes ?? []).map((probe) => mergeScopes2(step.scope, probe.scope))
+    ];
+    for (const scope of candidates) {
+      const normalized = normalizeCleanupScope(scope);
+      scopes.set(JSON.stringify(normalized), normalized);
+    }
+  }
+  return [...scopes.values()];
+}
+async function clearSequenceScopes(memory, sequence) {
+  for (const scope of sequenceCleanupScopes(sequence)) await memory.clear?.(scope);
+}
+
+// src/memory/experiment/recovery.ts
+async function recoverAbandonedMemoryAttempts(input) {
+  let attempts = readActiveMemoryAttempts(input.storage, input.attemptLogPath);
+  if (attempts.length > input.maxRecoveryAttempts) {
     throw new Error(
-      `${candidate.id}: cleanupBranches=false requires disposeAdapter to delete isolated external state`
+      `memory experiment has ${attempts.length} unfinished attempts; maxRecoveryAttempts is ${input.maxRecoveryAttempts}`
     );
   }
-  const cleanupTimeoutMs = resolveMemoryCleanupTimeoutMs(
-    options.cleanupTimeoutMs,
-    `${candidate.id}: memory sequence`
-  );
-  context.signal.throwIfAborted();
-  await lease.assertOwned();
-  const startedAt = Date.now();
-  const branchId = stableId(
-    "memory_branch",
-    `${runIdentity}:${context.cellId}:${context.seed}:${randomUUID2()}`
-  );
-  const attempt = memoryAttemptEvent({
-    status: "started",
-    branchId,
-    candidate,
-    sequence: scenario.sequence,
-    rep: context.rep,
-    seed: context.seed,
-    recovery: false,
-    cleanupBranches,
-    now: options.now
-  });
-  appendMemoryAttemptEvent(storage, attemptLogPath, attempt);
-  let externalCallAttempted = false;
-  const appendCleanedAttempt = (priorError) => {
-    try {
-      appendMemoryAttemptEvent(storage, attemptLogPath, {
+  for (const attempt of attempts) {
+    const candidate = input.candidateById.get(attempt.candidateId);
+    if (!candidate) {
+      throw new Error(
+        `cannot recover memory branch '${attempt.branchId}': candidate '${attempt.candidateId}' is missing; pass it in recoveryCandidates`
+      );
+    }
+    assertMemoryAttemptCandidateMatches(attempt, candidate);
+    if (!input.sequenceById.has(attempt.sequenceId)) {
+      throw new Error(
+        `cannot recover memory branch '${attempt.branchId}': sequence '${attempt.sequenceId}' is missing`
+      );
+    }
+    if ((input.options.cleanupBranches ?? true) !== attempt.cleanupBranches) {
+      throw new Error(`cannot recover memory branch '${attempt.branchId}': cleanupBranches changed`);
+    }
+  }
+  reconcileInterruptedMemoryPaidCalls(input.costLedger);
+  assertNoInterruptedPaidCalls(input.costLedger, "memory experiment recovery");
+  for (const attempt of attempts) {
+    const candidate = input.candidateById.get(attempt.candidateId);
+    const executionCostUsd = candidate.externalCostUsdPerSequence ?? 0;
+    if (executionCostUsd > 0 && !hasSettledPaidCall(input.costLedger, memoryAttemptCostCallId(attempt, "execute", 0))) {
+      appendMemoryAttemptEvent(input.storage, input.attemptLogPath, {
         ...attempt,
         status: "cleaned",
-        recordedAt: (options.now ?? (() => /* @__PURE__ */ new Date()))().toISOString()
+        recovery: true,
+        recordedAt: (input.options.now ?? (() => /* @__PURE__ */ new Date()))().toISOString()
       });
-    } catch (error) {
-      throw new AgentMemoryCleanupError(
-        [...priorError ? [priorError] : [], error],
-        `${candidate.id}: memory branch cleanup could not be recorded`
-      );
     }
-  };
-  const execute = async () => {
-    context.signal.throwIfAborted();
-    await lease.assertOwned();
-    let rawAdapter;
-    let adapter;
-    let memory;
-    let primaryError;
-    let completedArtifact;
-    let finalClearStarted = false;
-    let finalClearCompleted = false;
-    try {
-      const created = await candidate.createAdapter({
-        branchId,
-        sequence: scenario.sequence,
-        rep: context.rep,
-        seed: context.seed,
-        purpose: "execute",
-        signal: context.signal,
-        markExternalCall: () => {
-          externalCallAttempted = true;
-        }
-      });
-      if (!created) throw new Error(`${candidate.id}: createAdapter returned no execution adapter`);
-      rawAdapter = created;
-      adapter = trackExternalMemoryCalls(created, () => {
-        externalCallAttempted = true;
-      });
-      await lease.assertOwned();
-      context.signal.throwIfAborted();
-      if (cleanupBranches && !adapter.clear) {
-        throw new Error(
-          `${candidate.id}: cleanupBranches requires an adapter with scoped clear support`
-        );
-      }
-      memory = createAgentMemoryBranch({
-        adapter,
-        branchId,
-        lifetime: "attempt",
-        policy: candidate.policy,
-        allowedWriteScopes: sequenceCleanupScopes(scenario.sequence),
-        baseScope: memoryExperimentBaseScope(options, candidate, scenario.sequenceId)
-      });
-      const probes = [];
-      for (const step of scenario.sequence.steps) {
-        context.signal.throwIfAborted();
-        await lease.assertOwned();
-        await writeStep(memory, step);
-        await lease.assertOwned();
-        await options.executeStep?.({
-          memory,
-          candidateId: candidate.id,
-          sequence: scenario.sequence,
-          step,
-          context
-        });
-        context.signal.throwIfAborted();
-        await lease.assertOwned();
-        const stepProbes = await probeStep(memory, scenario.sequence, step);
-        await lease.assertOwned();
-        probes.push(...stepProbes);
-      }
-      const snapshot = await memory.snapshot();
-      await lease.assertOwned();
-      await options.onBranchSnapshot?.({
-        candidateId: candidate.id,
-        sequenceId: scenario.sequenceId,
-        cellId: context.cellId,
-        snapshot
-      });
-      await lease.assertOwned();
-      const dimensions = meanDimensions(probes.map((probe) => probe.dimensions));
-      const dimensionSampleCounts = countDimensions(
-        probes.map((probe) => probe.applicableDimensions)
-      );
-      const artifact = {
-        candidateId: candidate.id,
-        sequenceId: scenario.sequenceId,
-        score: mean(probes.map((probe) => probe.score)),
-        passed: probes.length > 0 && probes.every((probe) => probe.passed),
-        dimensions,
-        dimensionSampleCounts,
-        probes,
-        branchDigest: snapshot.digest,
-        journalEntries: snapshot.journal.length,
-        durationMs: Math.max(0, Date.now() - startedAt)
-      };
-      if (cleanupBranches) {
-        finalClearStarted = true;
-        await runBoundedMemoryLifecycle({
-          operation: `${candidate.id}: final branch cleanup`,
-          timeoutMs: cleanupTimeoutMs,
-          resource: adapter,
-          run: () => clearSequenceScopes(memory, scenario.sequence)
-        });
-        finalClearCompleted = true;
-        await lease.assertOwned();
-      }
-      completedArtifact = artifact;
-    } catch (error) {
-      primaryError = error;
-    }
-    const cleanupErrors = [];
-    let cleanupOwned = true;
-    let ownershipError;
-    try {
-      await lease.assertOwned();
-    } catch (error) {
-      cleanupOwned = false;
-      ownershipError = error;
-    }
-    if (finalClearStarted && !finalClearCompleted && primaryError) {
-      cleanupErrors.push(primaryError);
-    }
-    if (primaryError && cleanupOwned && !finalClearStarted && memory && cleanupBranches && adapter?.clear) {
-      try {
-        await runBoundedMemoryLifecycle({
-          operation: `${candidate.id}: failed branch cleanup`,
-          timeoutMs: cleanupTimeoutMs,
-          resource: adapter,
-          run: () => clearSequenceScopes(memory, scenario.sequence)
-        });
-      } catch (error) {
-        cleanupErrors.push(error);
-      }
-    }
-    if (adapter) {
-      try {
-        await runBoundedMemoryLifecycle({
-          operation: `${candidate.id}: adapter close`,
-          timeoutMs: cleanupTimeoutMs,
-          resource: adapter,
-          run: async () => {
-            if (memory && cleanupOwned) await memory.close?.();
-            else {
-              if (cleanupOwned) await adapter.flush?.();
-              await adapter.close?.();
-            }
-          }
-        });
-      } catch (error) {
-        cleanupErrors.push(error);
-      }
-      if (cleanupOwned) {
-        try {
-          await runBoundedMemoryLifecycle({
-            operation: `${candidate.id}: adapter disposal`,
-            timeoutMs: cleanupTimeoutMs,
-            resource: adapter,
-            run: () => {
-              if (candidate.disposeAdapter) externalCallAttempted = true;
-              return candidate.disposeAdapter?.(rawAdapter);
-            }
-          });
-        } catch (error) {
-          cleanupErrors.push(error);
-        }
-      }
-    } else {
-      cleanupErrors.push(
-        new Error(`${candidate.id}: adapter creation failed before cleanup could be confirmed`)
-      );
-    }
-    if (cleanupOwned && cleanupErrors.length === 0) appendCleanedAttempt(primaryError);
-    if (!cleanupOwned && cleanupErrors.length === 0) {
-      if (primaryError) throw primaryError;
-      throw ownershipError;
-    }
-    if (cleanupErrors.length > 0) {
-      const primaryMessage = primaryError instanceof Error ? primaryError.message : String(primaryError ?? "");
-      throw new AgentMemoryCleanupError(
-        [
-          ...primaryError && !cleanupErrors.includes(primaryError) ? [primaryError] : [],
-          ...ownershipError ? [ownershipError] : [],
-          ...cleanupErrors
-        ],
-        `${candidate.id}: memory branch cleanup failed${primaryMessage ? ` after: ${primaryMessage}` : ""}`
-      );
-    }
-    if (primaryError) throw primaryError;
-    if (!completedArtifact) throw new Error(`${candidate.id}: memory sequence produced no result`);
-    return completedArtifact;
-  };
-  if (costUsd === 0) {
-    let artifact;
-    let error;
-    try {
-      artifact = await execute();
-    } catch (caught) {
-      error = caught;
-    }
-    if (error) throw error;
-    if (!artifact) throw new Error(`${candidate.id}: memory sequence produced no result`);
-    return artifact;
-  }
-  const receipt = {
-    model: candidate.id,
-    inputTokens: 0,
-    outputTokens: 0,
-    actualCostUsd: costUsd
-  };
-  const paid = await context.cost.runPaidCall({
-    callId: memoryAttemptCostCallId(attempt, "execute", 0),
-    actor: `agent-knowledge:memory-experiment:${candidate.id}`,
-    model: candidate.id,
-    maximumCharge: { externallyEnforcedMaximumUsd: costUsd },
-    execute,
-    receipt: () => receipt,
-    receiptFromError: () => ({
-      ...receipt,
-      actualCostUsd: externalCallAttempted ? costUsd : 0
-    })
-  });
-  if (!paid.succeeded) throw paid.error;
-  return paid.value;
-}
-function trackExternalMemoryCalls(adapter, onExternalCall) {
-  return {
-    id: adapter.id,
-    branchIsolation: adapter.branchIsolation,
-    search(query, options) {
-      onExternalCall();
-      return adapter.search.call(adapter, query, options);
-    },
-    getContext(query, options) {
-      onExternalCall();
-      return adapter.getContext.call(adapter, query, options);
-    },
-    write(input) {
-      onExternalCall();
-      return adapter.write.call(adapter, input);
-    },
-    ...adapter.clear ? {
-      clear(scope) {
-        onExternalCall();
-        return adapter.clear.call(adapter, scope);
-      }
-    } : {},
-    ...adapter.flush ? {
-      flush() {
-        onExternalCall();
-        return adapter.flush.call(adapter);
-      }
-    } : {},
-    ...adapter.close ? {
-      close() {
-        onExternalCall();
-        return adapter.close.call(adapter);
-      }
-    } : {}
-  };
-}
-async function recoverAbandonedMemoryAttempts(input) {
-  let attempts = readActiveMemoryAttempts(input.storage, input.attemptLogPath);
-  if (attempts.length > input.maxRecoveryAttempts) {
-    throw new Error(
-      `memory experiment has ${attempts.length} unfinished attempts; maxRecoveryAttempts is ${input.maxRecoveryAttempts}`
-    );
-  }
-  for (const attempt of attempts) {
-    const candidate = input.candidateById.get(attempt.candidateId);
-    if (!candidate) {
-      throw new Error(
-        `cannot recover memory branch '${attempt.branchId}': candidate '${attempt.candidateId}' is missing; pass it in recoveryCandidates`
-      );
-    }
-    assertMemoryAttemptCandidateMatches(attempt, candidate);
-    if (!input.sequenceById.has(attempt.sequenceId)) {
-      throw new Error(
-        `cannot recover memory branch '${attempt.branchId}': sequence '${attempt.sequenceId}' is missing`
-      );
-    }
-    if ((input.options.cleanupBranches ?? true) !== attempt.cleanupBranches) {
-      throw new Error(`cannot recover memory branch '${attempt.branchId}': cleanupBranches changed`);
-    }
-  }
-  reconcileInterruptedMemoryPaidCalls(input.costLedger);
-  assertNoInterruptedPaidCalls(input.costLedger, "memory experiment recovery");
-  for (const attempt of attempts) {
-    const candidate = input.candidateById.get(attempt.candidateId);
-    const executionCostUsd = candidate.externalCostUsdPerSequence ?? 0;
-    if (executionCostUsd > 0 && !hasSettledPaidCall(input.costLedger, memoryAttemptCostCallId(attempt, "execute", 0))) {
-      appendMemoryAttemptEvent(input.storage, input.attemptLogPath, {
-        ...attempt,
-        status: "cleaned",
-        recovery: true,
-        recordedAt: (input.options.now ?? (() => /* @__PURE__ */ new Date()))().toISOString()
-      });
-    }
-  }
-  attempts = readActiveMemoryAttempts(input.storage, input.attemptLogPath);
-  const recoveryGenerations = reserveRecoveryAttempts({
-    storage: input.storage,
-    path: input.recoveryLogPath,
-    attemptIds: attempts.map((attempt) => attempt.branchId),
-    maxRetriesPerAttempt: input.maxRecoveryRetriesPerAttempt,
-    label: "memory recovery attempt log",
-    now: input.options.now
-  });
-  const pool = createMemoryExecutionPool(input.maxConcurrency);
-  const settled = await Promise.allSettled(
-    attempts.sort((left, right) => left.branchId.localeCompare(right.branchId)).map(
-      (attempt) => pool.run(async () => {
-        await input.lease.assertOwned();
-        const candidate = input.candidateById.get(attempt.candidateId);
-        if (!candidate) {
-          throw new Error(
-            `cannot recover memory branch '${attempt.branchId}': candidate '${attempt.candidateId}' is missing; pass it in recoveryCandidates`
-          );
+  }
+  attempts = readActiveMemoryAttempts(input.storage, input.attemptLogPath);
+  const recoveryGenerations = reserveRecoveryAttempts({
+    storage: input.storage,
+    path: input.recoveryLogPath,
+    attemptIds: attempts.map((attempt) => attempt.branchId),
+    maxRetriesPerAttempt: input.maxRecoveryRetriesPerAttempt,
+    label: "memory recovery attempt log",
+    now: input.options.now
+  });
+  const pool = createMemoryExecutionPool(input.maxConcurrency);
+  const settled = await Promise.allSettled(
+    attempts.sort((left, right) => left.branchId.localeCompare(right.branchId)).map(
+      (attempt) => pool.run(async () => {
+        await input.lease.assertOwned();
+        const candidate = input.candidateById.get(attempt.candidateId);
+        if (!candidate) {
+          throw new Error(
+            `cannot recover memory branch '${attempt.branchId}': candidate '${attempt.candidateId}' is missing; pass it in recoveryCandidates`
+          );
         }
         assertMemoryAttemptCandidateMatches(attempt, candidate);
         const sequence = input.sequenceById.get(attempt.sequenceId);
@@ -1972,418 +1722,687 @@ function assertMemoryAttemptCandidateMatches(attempt, candidate) {
     );
   }
 }
-async function writeStep(memory, step) {
-  const writes = (step.writes ?? []).map((write) => ({
-    ...write,
-    scope: mergeScopes2(step.scope, write.scope)
-  }));
-  if (step.parallelWrites) {
-    await Promise.all(writes.map((write) => memory.write(write)));
-    return;
-  }
-  for (const write of writes) await memory.write(write);
-}
-async function probeStep(memory, sequence, step) {
-  const run = async (probe) => {
-    const scope = mergeScopes2(step.scope, probe.scope);
-    const context = await memory.getContext(probe.query, { scope, limit: probe.limit });
-    const artifact = {
-      answer: context.text,
-      rememberedFacts: context.hits.map((hit) => hit.text),
-      citedEventIds: uniqueStrings([
-        ...context.hits.map((hit) => hit.metadata?.eventId),
-        ...context.hits.flatMap((hit) => stringArray(hit.metadata?.eventIds))
-      ]),
-      usedMemoryIds: context.hits.map((hit) => hit.id),
-      actorIds: uniqueStrings([
-        ...context.hits.map((hit) => hit.metadata?.actorId),
-        ...context.hits.flatMap((hit) => stringArray(hit.metadata?.actorIds))
-      ])
-    };
-    const evaluation = scoreMemoryBenchmarkArtifact(
-      {
-        id: `${sequence.id}:${step.id}:${probe.id}`,
-        family: sequence.family,
-        taskKind: probe.taskKind ?? "memory-recall",
-        split: sequence.split,
-        events: [],
-        prompt: probe.query,
-        requiredFacts: probe.requiredFacts && probe.requiredFacts.length > 0 ? probe.requiredFacts : probe.referenceAnswer ? [{ id: `${probe.id}:reference`, anyOf: [probe.referenceAnswer] }] : void 0,
-        forbiddenFacts: probe.forbiddenFacts,
-        expectedEventIds: probe.expectedEventIds,
-        expectedActorIds: probe.expectedActorIds,
-        referenceAnswer: probe.referenceAnswer
-      },
-      artifact
+
+// src/memory/experiment/cell.ts
+async function runSequenceCell(input) {
+  const { options, candidate, scenario, context, runIdentity, storage, attemptLogPath, lease } = input;
+  const cleanupBranches = options.cleanupBranches ?? true;
+  const costUsd = candidate.externalCostUsdPerSequence ?? 0;
+  if (!Number.isFinite(costUsd) || costUsd < 0) {
+    throw new Error(
+      `${candidate.id}: externalCostUsdPerSequence must be a non-negative finite number`
     );
-    return {
-      id: probe.id,
-      stepId: step.id,
-      query: probe.query,
-      score: evaluation.score,
-      passed: evaluation.passed,
-      dimensions: evaluation.dimensions,
-      applicableDimensions: evaluation.applicableDimensions ?? Object.keys(evaluation.dimensions),
-      notes: evaluation.notes,
-      hitIds: context.hits.map((hit) => hit.id)
-    };
-  };
-  if (step.parallelProbes === false) {
-    const results = [];
-    for (const probe of step.probes ?? []) results.push(await run(probe));
-    return results;
   }
-  return Promise.all((step.probes ?? []).map(run));
-}
-function rankAgentMemoryExperiment(candidates, scenarios, campaign, costByCandidate) {
-  const scenarioById = new Map(scenarios.map((scenario) => [scenario.id, scenario]));
-  const rows = candidates.map((candidate) => {
-    const candidateScenarios = scenarios.filter((scenario) => scenario.candidateId === candidate.id);
-    const cells = campaign.cells.filter(
-      (cell) => scenarioById.get(cell.scenarioId)?.candidateId === candidate.id
+  if (!cleanupBranches && !candidate.disposeAdapter) {
+    throw new Error(
+      `${candidate.id}: cleanupBranches=false requires disposeAdapter to delete isolated external state`
     );
-    const successful = cells.filter((cell) => !cell.error && cell.artifact);
-    const dimensionRows = successful.map((cell) => cell.artifact.dimensions);
-    return {
-      rank: 0,
-      candidateId: candidate.id,
-      label: candidate.label ?? candidate.id,
-      scoreMean: mean(
-        cells.map((cell) => !cell.error && cell.artifact ? cell.artifact.score : 0)
-      ),
-      passRate: mean(cells.map((cell) => !cell.error && cell.artifact?.passed ? 1 : 0)),
-      totalSequences: candidateScenarios.length,
-      totalCells: cells.length,
-      totalProbes: successful.reduce((sum, cell) => sum + cell.artifact.probes.length, 0),
-      cellsFailed: cells.filter((cell) => Boolean(cell.error)).length,
-      totalCostUsd: normalizeUsd(costByCandidate.get(candidate.id) ?? 0),
-      durationMs: cells.reduce((sum, cell) => sum + cell.durationMs, 0),
-      dimensions: meanDimensions(dimensionRows)
-    };
-  });
-  return rows.sort(
-    (a, b) => Number(a.cellsFailed > 0) - Number(b.cellsFailed > 0) || b.scoreMean - a.scoreMean || b.passRate - a.passRate || a.totalCostUsd - b.totalCostUsd || a.candidateId.localeCompare(b.candidateId)
-  ).map((row, index) => ({ ...row, rank: index + 1 }));
-}
-function memoryExperimentCostByCandidate(costLedger, runDir, scenarios, candidateIdsInput) {
-  const candidateByScenario = new Map(
-    scenarios.map((scenario) => [scenario.id, scenario.candidateId])
-  );
-  const candidateIds = new Set(candidateIdsInput);
-  const totals = /* @__PURE__ */ new Map();
-  for (const receipt of costLedger.list()) {
-    if (receipt.tags?.runDir !== runDir) continue;
-    const scenarioCandidate = receipt.tags.scenarioId ? candidateByScenario.get(receipt.tags.scenarioId) : void 0;
-    const recoveryCandidate = receipt.tags.memoryRecovery === "attempt" && receipt.tags.candidateId ? receipt.tags.candidateId : void 0;
-    const candidateId = scenarioCandidate ?? recoveryCandidate;
-    if (!candidateId || !candidateIds.has(candidateId)) continue;
-    totals.set(candidateId, (totals.get(candidateId) ?? 0) + receipt.costUsd);
   }
-  return totals;
-}
-function renderAgentMemoryExperimentRanking(rows, totalCostUsd, unrankedRecoveryCostUsd) {
-  return [
-    "# Agent Memory Experiment",
-    "",
-    `- total cost: $${format(totalCostUsd)}`,
-    `- retired-candidate recovery cost: $${format(unrankedRecoveryCostUsd)}`,
-    "",
-    "| rank | candidate | sequences | cells | probes | failed | score | pass rate | cost | duration ms |",
-    "| ---: | --- | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: |",
-    ...rows.map(
-      (row) => `| ${row.rank} | ${row.label} | ${row.totalSequences} | ${row.totalCells} | ${row.totalProbes} | ${row.cellsFailed} | ${format(row.scoreMean)} | ${format(row.passRate)} | $${format(row.totalCostUsd)} | ${format(row.durationMs)} |`
-    ),
-    ""
-  ].join("\n");
-}
-function memoryExperimentDispatchRef(options) {
-  return stableId(
-    "memory_experiment",
-    canonicalJson3({
-      implementationRef: MEMORY_EXPERIMENT_IMPLEMENTATION_REF,
-      experimentId: options.experimentId,
-      experimentRunId: options.experimentRunId ?? null,
-      executeStepRef: options.executeStepRef ?? "fixtures",
-      cleanupBranches: options.cleanupBranches ?? true,
-      candidates: options.candidates.map((candidate) => ({
-        id: candidate.id,
-        ref: candidate.ref,
-        policy: candidate.policy ?? null,
-        baseScope: candidate.baseScope ?? null,
-        externalCostUsdPerSequence: candidate.externalCostUsdPerSequence ?? 0,
-        externalRecoveryCostUsdPerAttempt: candidate.externalRecoveryCostUsdPerAttempt ?? 0
-      })).sort((a, b) => a.id.localeCompare(b.id))
-    })
+  const cleanupTimeoutMs = resolveMemoryCleanupTimeoutMs(
+    options.cleanupTimeoutMs,
+    `${candidate.id}: memory sequence`
   );
-}
-function meanDimensions(rows) {
-  const values = /* @__PURE__ */ new Map();
-  for (const row of rows) {
-    for (const [key, value] of Object.entries(row)) {
-      if (!Number.isFinite(value)) continue;
-      const bucket = values.get(key) ?? [];
-      bucket.push(value);
-      values.set(key, bucket);
-    }
-  }
-  return Object.fromEntries([...values].map(([key, bucket]) => [key, mean(bucket)]));
-}
-function countDimensions(rows) {
-  const counts = /* @__PURE__ */ new Map();
-  for (const row of rows) {
-    for (const key of new Set(row)) counts.set(key, (counts.get(key) ?? 0) + 1);
-  }
-  return Object.fromEntries(counts);
-}
-function mean(values) {
-  return values.length === 0 ? 0 : values.reduce((sum, value) => sum + value, 0) / values.length;
-}
-function mergeScopes2(base, extra) {
-  return {
-    ...base ?? {},
-    ...extra ?? {},
-    tags: { ...base?.tags ?? {}, ...extra?.tags ?? {} }
-  };
-}
-function memoryExperimentBaseScope(options, candidate, sequenceId) {
-  return mergeScopes2(candidate.baseScope, {
-    tags: {
-      memoryExperimentId: options.experimentId,
-      memoryCandidateId: candidate.id,
-      memorySequenceId: sequenceId
-    }
+  context.signal.throwIfAborted();
+  await lease.assertOwned();
+  const startedAt = Date.now();
+  const branchId = stableId(
+    "memory_branch",
+    `${runIdentity}:${context.cellId}:${context.seed}:${randomUUID2()}`
+  );
+  const attempt = memoryAttemptEvent({
+    status: "started",
+    branchId,
+    candidate,
+    sequence: scenario.sequence,
+    rep: context.rep,
+    seed: context.seed,
+    recovery: false,
+    cleanupBranches,
+    now: options.now
   });
-}
-function sequenceCleanupScopes(sequence) {
-  const scopes = /* @__PURE__ */ new Map();
-  for (const scope of sequence.cleanupScopes ?? []) {
-    const normalized = normalizeCleanupScope(scope);
-    scopes.set(JSON.stringify(normalized), normalized);
-  }
-  for (const step of sequence.steps) {
-    const candidates = [
-      ...step.scope ? [step.scope] : [],
-      ...(step.writes ?? []).map((write) => mergeScopes2(step.scope, write.scope)),
-      ...(step.probes ?? []).map((probe) => mergeScopes2(step.scope, probe.scope))
-    ];
-    for (const scope of candidates) {
-      const normalized = normalizeCleanupScope(scope);
-      scopes.set(JSON.stringify(normalized), normalized);
-    }
-  }
-  return [...scopes.values()];
-}
-async function clearSequenceScopes(memory, sequence) {
-  for (const scope of sequenceCleanupScopes(sequence)) await memory.clear?.(scope);
-}
-function assertMemorySequences(sequences) {
-  for (const sequence of sequences) {
-    assertNonEmptyString(sequence.family, `memory experiment sequence ${sequence.id} family`);
-    if (sequence.steps.length === 0) {
-      throw new Error(`memory experiment sequence ${sequence.id} has no steps`);
-    }
-    assertUnique(
-      sequence.steps.map((step) => step.id),
-      `step in sequence ${sequence.id}`
-    );
-    let probeCount = 0;
-    for (const step of sequence.steps) {
-      for (const write of step.writes ?? []) {
-        assertNonEmptyString(write.text, `memory experiment write in ${sequence.id}/${step.id}`);
-        if (write.id !== void 0) {
-          assertNonEmptyString(write.id, `memory experiment write id in ${sequence.id}/${step.id}`);
-        }
-      }
-      assertUnique(
-        (step.probes ?? []).map((probe) => probe.id),
-        `probe in sequence ${sequence.id} step ${step.id}`
+  appendMemoryAttemptEvent(storage, attemptLogPath, attempt);
+  let externalCallAttempted = false;
+  const appendCleanedAttempt = (priorError) => {
+    try {
+      appendMemoryAttemptEvent(storage, attemptLogPath, {
+        ...attempt,
+        status: "cleaned",
+        recordedAt: (options.now ?? (() => /* @__PURE__ */ new Date()))().toISOString()
+      });
+    } catch (error) {
+      throw new AgentMemoryCleanupError(
+        [...priorError ? [priorError] : [], error],
+        `${candidate.id}: memory branch cleanup could not be recorded`
       );
-      for (const probe of step.probes ?? []) {
-        probeCount += 1;
-        assertNonEmptyString(
-          probe.query,
-          `memory experiment probe query ${sequence.id}/${step.id}/${probe.id}`
-        );
-        if (probe.limit !== void 0 && (!Number.isSafeInteger(probe.limit) || probe.limit <= 0)) {
-          throw new Error(
-            `memory experiment probe limit ${sequence.id}/${step.id}/${probe.id} must be a positive safe integer`
-          );
+    }
+  };
+  const execute = async () => {
+    context.signal.throwIfAborted();
+    await lease.assertOwned();
+    let rawAdapter;
+    let adapter;
+    let memory;
+    let primaryError;
+    let completedArtifact;
+    let finalClearStarted = false;
+    let finalClearCompleted = false;
+    try {
+      const created = await candidate.createAdapter({
+        branchId,
+        sequence: scenario.sequence,
+        rep: context.rep,
+        seed: context.seed,
+        purpose: "execute",
+        signal: context.signal,
+        markExternalCall: () => {
+          externalCallAttempted = true;
         }
-        assertMemoryFactMatchers(
-          probe.requiredFacts ?? [],
-          `${sequence.id}/${step.id}/${probe.id} requiredFacts`
-        );
-        assertMemoryFactMatchers(
-          probe.forbiddenFacts ?? [],
-          `${sequence.id}/${step.id}/${probe.id} forbiddenFacts`
+      });
+      if (!created) throw new Error(`${candidate.id}: createAdapter returned no execution adapter`);
+      rawAdapter = created;
+      adapter = trackExternalMemoryCalls(created, () => {
+        externalCallAttempted = true;
+      });
+      await lease.assertOwned();
+      context.signal.throwIfAborted();
+      if (cleanupBranches && !adapter.clear) {
+        throw new Error(
+          `${candidate.id}: cleanupBranches requires an adapter with scoped clear support`
         );
-        assertStringList(probe.expectedEventIds, `${sequence.id}/${step.id}/${probe.id} event ids`);
-        assertStringList(probe.expectedActorIds, `${sequence.id}/${step.id}/${probe.id} actor ids`);
-        if (probe.referenceAnswer !== void 0) {
-          assertNonEmptyString(
-            probe.referenceAnswer,
-            `memory experiment reference answer ${sequence.id}/${step.id}/${probe.id}`
-          );
-        }
-        const hasTarget = (probe.requiredFacts?.length ?? 0) > 0 || (probe.forbiddenFacts?.length ?? 0) > 0 || (probe.expectedEventIds?.length ?? 0) > 0 || (probe.expectedActorIds?.length ?? 0) > 0 || Boolean(probe.referenceAnswer?.trim());
-        if (!hasTarget) {
-          throw new Error(
-            `memory experiment probe ${sequence.id}/${step.id}/${probe.id} has no measurable target`
-          );
+      }
+      memory = createAgentMemoryBranch({
+        adapter,
+        branchId,
+        lifetime: "attempt",
+        policy: candidate.policy,
+        allowedWriteScopes: sequenceCleanupScopes(scenario.sequence),
+        baseScope: memoryExperimentBaseScope(options, candidate, scenario.sequenceId)
+      });
+      const probes = [];
+      for (const step of scenario.sequence.steps) {
+        context.signal.throwIfAborted();
+        await lease.assertOwned();
+        await writeStep(memory, step);
+        await lease.assertOwned();
+        await options.executeStep?.({
+          memory,
+          candidateId: candidate.id,
+          sequence: scenario.sequence,
+          step,
+          context
+        });
+        context.signal.throwIfAborted();
+        await lease.assertOwned();
+        const stepProbes = await probeStep(memory, scenario.sequence, step);
+        await lease.assertOwned();
+        probes.push(...stepProbes);
+      }
+      const snapshot = await memory.snapshot();
+      await lease.assertOwned();
+      await options.onBranchSnapshot?.({
+        candidateId: candidate.id,
+        sequenceId: scenario.sequenceId,
+        cellId: context.cellId,
+        snapshot
+      });
+      await lease.assertOwned();
+      const dimensions = meanDimensions(probes.map((probe) => probe.dimensions));
+      const dimensionSampleCounts = countDimensions(
+        probes.map((probe) => probe.applicableDimensions)
+      );
+      const artifact = {
+        candidateId: candidate.id,
+        sequenceId: scenario.sequenceId,
+        score: mean(probes.map((probe) => probe.score)),
+        passed: probes.length > 0 && probes.every((probe) => probe.passed),
+        dimensions,
+        dimensionSampleCounts,
+        probes,
+        branchDigest: snapshot.digest,
+        journalEntries: snapshot.journal.length,
+        durationMs: Math.max(0, Date.now() - startedAt)
+      };
+      if (cleanupBranches) {
+        finalClearStarted = true;
+        await runBoundedMemoryLifecycle({
+          operation: `${candidate.id}: final branch cleanup`,
+          timeoutMs: cleanupTimeoutMs,
+          resource: adapter,
+          run: () => clearSequenceScopes(memory, scenario.sequence)
+        });
+        finalClearCompleted = true;
+        await lease.assertOwned();
+      }
+      completedArtifact = artifact;
+    } catch (error) {
+      primaryError = error;
+    }
+    const cleanupErrors = [];
+    let cleanupOwned = true;
+    let ownershipError;
+    try {
+      await lease.assertOwned();
+    } catch (error) {
+      cleanupOwned = false;
+      ownershipError = error;
+    }
+    if (finalClearStarted && !finalClearCompleted && primaryError) {
+      cleanupErrors.push(primaryError);
+    }
+    if (primaryError && cleanupOwned && !finalClearStarted && memory && cleanupBranches && adapter?.clear) {
+      try {
+        await runBoundedMemoryLifecycle({
+          operation: `${candidate.id}: failed branch cleanup`,
+          timeoutMs: cleanupTimeoutMs,
+          resource: adapter,
+          run: () => clearSequenceScopes(memory, scenario.sequence)
+        });
+      } catch (error) {
+        cleanupErrors.push(error);
+      }
+    }
+    if (adapter) {
+      try {
+        await runBoundedMemoryLifecycle({
+          operation: `${candidate.id}: adapter close`,
+          timeoutMs: cleanupTimeoutMs,
+          resource: adapter,
+          run: async () => {
+            if (memory && cleanupOwned) await memory.close?.();
+            else {
+              if (cleanupOwned) await adapter.flush?.();
+              await adapter.close?.();
+            }
+          }
+        });
+      } catch (error) {
+        cleanupErrors.push(error);
+      }
+      if (cleanupOwned) {
+        try {
+          await runBoundedMemoryLifecycle({
+            operation: `${candidate.id}: adapter disposal`,
+            timeoutMs: cleanupTimeoutMs,
+            resource: adapter,
+            run: () => {
+              if (candidate.disposeAdapter) externalCallAttempted = true;
+              return candidate.disposeAdapter?.(rawAdapter);
+            }
+          });
+        } catch (error) {
+          cleanupErrors.push(error);
         }
       }
+    } else {
+      cleanupErrors.push(
+        new Error(`${candidate.id}: adapter creation failed before cleanup could be confirmed`)
+      );
     }
-    if (probeCount === 0) {
-      throw new Error(`memory experiment sequence ${sequence.id} has no probes`);
+    if (cleanupOwned && cleanupErrors.length === 0) appendCleanedAttempt(primaryError);
+    if (!cleanupOwned && cleanupErrors.length === 0) {
+      if (primaryError) throw primaryError;
+      throw ownershipError;
+    }
+    if (cleanupErrors.length > 0) {
+      const primaryMessage = primaryError instanceof Error ? primaryError.message : String(primaryError ?? "");
+      throw new AgentMemoryCleanupError(
+        [
+          ...primaryError && !cleanupErrors.includes(primaryError) ? [primaryError] : [],
+          ...ownershipError ? [ownershipError] : [],
+          ...cleanupErrors
+        ],
+        `${candidate.id}: memory branch cleanup failed${primaryMessage ? ` after: ${primaryMessage}` : ""}`
+      );
+    }
+    if (primaryError) throw primaryError;
+    if (!completedArtifact) throw new Error(`${candidate.id}: memory sequence produced no result`);
+    return completedArtifact;
+  };
+  if (costUsd === 0) {
+    let artifact;
+    let error;
+    try {
+      artifact = await execute();
+    } catch (caught) {
+      error = caught;
     }
+    if (error) throw error;
+    if (!artifact) throw new Error(`${candidate.id}: memory sequence produced no result`);
+    return artifact;
   }
+  const receipt = {
+    model: candidate.id,
+    inputTokens: 0,
+    outputTokens: 0,
+    actualCostUsd: costUsd
+  };
+  const paid = await context.cost.runPaidCall({
+    callId: memoryAttemptCostCallId(attempt, "execute", 0),
+    actor: `agent-knowledge:memory-experiment:${candidate.id}`,
+    model: candidate.id,
+    maximumCharge: { externallyEnforcedMaximumUsd: costUsd },
+    execute,
+    receipt: () => receipt,
+    receiptFromError: () => ({
+      ...receipt,
+      actualCostUsd: externalCallAttempted ? costUsd : 0
+    })
+  });
+  if (!paid.succeeded) throw paid.error;
+  return paid.value;
 }
-function normalizeCleanupScope(scope) {
-  const normalized = compactScope(scope);
-  if (normalized.tags && Object.keys(normalized.tags).length === 0) {
-    delete normalized.tags;
+async function writeStep(memory, step) {
+  const writes = (step.writes ?? []).map((write) => ({
+    ...write,
+    scope: mergeScopes2(step.scope, write.scope)
+  }));
+  if (step.parallelWrites) {
+    await Promise.all(writes.map((write) => memory.write(write)));
+    return;
   }
-  return normalized;
+  for (const write of writes) await memory.write(write);
 }
-function compactScope(scope) {
-  return Object.fromEntries(
-    Object.entries(scope).filter(([, value]) => value !== void 0)
-  );
-}
-function compactRecord(record2) {
-  return Object.fromEntries(Object.entries(record2).filter(([, value]) => value !== void 0));
-}
-function uniqueStrings(values) {
-  return [...new Set(values.filter((value) => typeof value === "string"))];
-}
-function stringArray(value) {
-  return Array.isArray(value) ? value.filter((entry) => typeof entry === "string") : [];
-}
-function assertUnique(values, label) {
-  const seen = /* @__PURE__ */ new Set();
-  for (const value of values) {
-    assertNonEmptyString(value, `memory experiment ${label} id`);
-    if (seen.has(value)) throw new Error(`duplicate memory experiment ${label} id: ${value}`);
-    seen.add(value);
+async function probeStep(memory, sequence, step) {
+  const run = async (probe) => {
+    const scope = mergeScopes2(step.scope, probe.scope);
+    const context = await memory.getContext(probe.query, { scope, limit: probe.limit });
+    const artifact = {
+      answer: context.text,
+      rememberedFacts: context.hits.map((hit) => hit.text),
+      citedEventIds: uniqueStrings([
+        ...context.hits.map((hit) => hit.metadata?.eventId),
+        ...context.hits.flatMap((hit) => stringArray(hit.metadata?.eventIds))
+      ]),
+      usedMemoryIds: context.hits.map((hit) => hit.id),
+      actorIds: uniqueStrings([
+        ...context.hits.map((hit) => hit.metadata?.actorId),
+        ...context.hits.flatMap((hit) => stringArray(hit.metadata?.actorIds))
+      ])
+    };
+    const evaluation = scoreMemoryBenchmarkArtifact(
+      {
+        id: `${sequence.id}:${step.id}:${probe.id}`,
+        family: sequence.family,
+        taskKind: probe.taskKind ?? "memory-recall",
+        split: sequence.split,
+        events: [],
+        prompt: probe.query,
+        requiredFacts: probe.requiredFacts && probe.requiredFacts.length > 0 ? probe.requiredFacts : probe.referenceAnswer ? [{ id: `${probe.id}:reference`, anyOf: [probe.referenceAnswer] }] : void 0,
+        forbiddenFacts: probe.forbiddenFacts,
+        expectedEventIds: probe.expectedEventIds,
+        expectedActorIds: probe.expectedActorIds,
+        referenceAnswer: probe.referenceAnswer
+      },
+      artifact
+    );
+    return {
+      id: probe.id,
+      stepId: step.id,
+      query: probe.query,
+      score: evaluation.score,
+      passed: evaluation.passed,
+      dimensions: evaluation.dimensions,
+      applicableDimensions: evaluation.applicableDimensions ?? Object.keys(evaluation.dimensions),
+      notes: evaluation.notes,
+      hitIds: context.hits.map((hit) => hit.id)
+    };
+  };
+  if (step.parallelProbes === false) {
+    const results = [];
+    for (const probe of step.probes ?? []) results.push(await run(probe));
+    return results;
   }
+  return Promise.all((step.probes ?? []).map(run));
 }
-function assertMemoryFactMatchers(matchers, label) {
+
+// src/memory/experiment/run.ts
+var MEMORY_EXPERIMENT_IMPLEMENTATION_REF = "agent-knowledge:memory-experiment:v6";
+async function runAgentMemoryExperiment(options) {
+  assertNonEmptyString(options.experimentId, "memory experiment experimentId");
+  assertNonEmptyString(options.runDir, "memory experiment runDir");
+  if (options.experimentRunId !== void 0) {
+    assertNonEmptyString(options.experimentRunId, "memory experiment experimentRunId");
+  }
+  if (options.sequences.length === 0) throw new Error("memory experiment requires sequences");
+  if (options.candidates.length === 0) throw new Error("memory experiment requires candidates");
+  if (options.executeStep && !options.executeStepRef) {
+    throw new Error("memory experiment executeStepRef is required when executeStep is configured");
+  }
   assertUnique(
-    matchers.map((matcher) => matcher.id),
-    `${label} matcher`
+    options.sequences.map((sequence) => sequence.id),
+    "sequence"
   );
-  for (const matcher of matchers) {
-    if (matcher.anyOf.length === 0) {
-      throw new Error(`memory experiment ${label} matcher ${matcher.id} requires anyOf`);
+  assertUnique(
+    [...options.candidates, ...options.recoveryCandidates ?? []].map((candidate) => candidate.id),
+    "candidate"
+  );
+  assertMemorySequences(options.sequences);
+  for (const candidate of [...options.candidates, ...options.recoveryCandidates ?? []]) {
+    if (options.cleanupBranches === false && !candidate.disposeAdapter) {
+      throw new Error(
+        `${candidate.id}: cleanupBranches=false requires disposeAdapter to delete isolated external state`
+      );
     }
-    assertStringList(matcher.anyOf, `${label} matcher ${matcher.id} anyOf`);
-    assertStringList(matcher.sourceEventIds, `${label} matcher ${matcher.id} source event ids`);
-    if (matcher.weight !== void 0 && (!Number.isFinite(matcher.weight) || matcher.weight <= 0)) {
+    if (candidate.externalCostUsdPerSequence !== void 0 && (!Number.isFinite(candidate.externalCostUsdPerSequence) || candidate.externalCostUsdPerSequence < 0)) {
       throw new Error(
-        `memory experiment ${label} matcher ${matcher.id} weight must be a positive finite number`
+        `${candidate.id}: externalCostUsdPerSequence must be a non-negative finite number`
       );
     }
+    if (candidate.externalRecoveryCostUsdPerAttempt !== void 0 && (!Number.isFinite(candidate.externalRecoveryCostUsdPerAttempt) || candidate.externalRecoveryCostUsdPerAttempt < 0)) {
+      throw new Error(
+        `${candidate.id}: externalRecoveryCostUsdPerAttempt must be a non-negative finite number`
+      );
+    }
+    assertNonEmptyString(candidate.ref, `${candidate.id} ref`);
   }
-}
-function assertStringList(values, label) {
-  if (values === void 0) return;
-  assertUnique(values, label);
-}
-function assertNonEmptyString(value, label) {
-  if (typeof value !== "string" || value.trim().length === 0) {
-    throw new Error(`${label} must be a non-empty string`);
+  const storage = options.storage ?? fsCampaignStorage();
+  const runDir = resolveRunDir(options.runDir, options.repo);
+  if (!storage.append) {
+    throw new Error("memory experiment requires CampaignStorage.append for durable attempt state");
   }
+  resolveMemoryCleanupTimeoutMs(options.cleanupTimeoutMs, "memory experiment");
+  const maxRecoveryAttempts = options.maxRecoveryAttempts ?? 1e3;
+  if (!Number.isSafeInteger(maxRecoveryAttempts) || maxRecoveryAttempts <= 0) {
+    throw new Error("memory experiment maxRecoveryAttempts must be a positive safe integer");
+  }
+  const maxRecoveryRetriesPerAttempt = options.maxRecoveryRetriesPerAttempt ?? DEFAULT_MEMORY_RECOVERY_RETRIES_PER_ATTEMPT;
+  if (!Number.isSafeInteger(maxRecoveryRetriesPerAttempt) || maxRecoveryRetriesPerAttempt <= 0) {
+    throw new Error(
+      "memory experiment maxRecoveryRetriesPerAttempt must be a positive safe integer"
+    );
+  }
+  storage.ensureDir(runDir);
+  const lease = await acquireAgentMemoryRunLease({
+    experimentId: options.experimentId,
+    runDir,
+    storage,
+    customStorage: options.storage !== void 0,
+    lockFileName: "memory-experiment.lock",
+    label: "memory experiment",
+    controllerMode: options.controllerMode,
+    acquireRunLease: options.acquireRunLease
+  });
+  let result;
+  let primaryError;
+  try {
+    await lease.assertOwned();
+    result = await runOwnedAgentMemoryExperiment(options, storage, runDir, lease);
+  } catch (error) {
+    primaryError = error;
+  }
+  let releaseError;
+  try {
+    await lease.release();
+  } catch (error) {
+    releaseError = error;
+  }
+  if (primaryError && releaseError) {
+    throw new AggregateError(
+      [primaryError, releaseError],
+      "memory experiment failed and its controller lease could not be released"
+    );
+  }
+  if (primaryError) throw primaryError;
+  if (releaseError) throw releaseError;
+  if (!result) throw new Error("memory experiment produced no result");
+  return result;
 }
-function format(value) {
-  return Number.isFinite(value) ? value.toFixed(4) : "0.0000";
-}
-function normalizeUsd(value) {
-  return Number(value.toFixed(12));
-}
-
-// src/memory/graphiti.ts
-import { randomUUID as randomUUID3 } from "crypto";
-import { canonicalJson as canonicalJson4 } from "@tangle-network/agent-eval";
-var DEFAULT_GRAPHITI_INGESTION_TIMEOUT_MS = 12e4;
-function createGraphitiMemoryAdapter(options) {
-  assertGraphitiOptions(options);
-  const id = options.id ?? "graphiti";
-  const consistency = options.consistency ?? "visible";
-  const tools = graphitiToolNames(options);
-  const queued = /* @__PURE__ */ new Map();
-  const adapter = {
-    id,
-    branchIsolation: consistency === "visible" ? {
-      mode: "scoped",
-      processExitSafe: false,
-      recoveryDelayMs: options.ingestionTimeoutMs ?? DEFAULT_GRAPHITI_INGESTION_TIMEOUT_MS
-    } : {
-      mode: "unsupported",
-      reason: 'queued Graphiti writes can become visible after a process restart; use consistency="visible" for branch experiments'
-    },
-    async search(query, searchOptions = {}) {
-      if (searchOptions.minScore !== void 0 && !Number.isFinite(searchOptions.minScore)) {
-        throw new Error(`${id}: minScore must be finite`);
-      }
-      const scope = mergeScopes3(options.defaultScope, searchOptions.scope);
-      const groupId = graphitiGroupId(id, scope);
-      const modes = new Set(options.search ?? ["facts", "nodes"]);
-      const kinds = searchOptions.kinds && searchOptions.kinds.length > 0 ? new Set(searchOptions.kinds) : null;
-      const searchFacts = modes.has("facts") && (!kinds || kinds.has("fact"));
-      const searchNodes = modes.has("nodes") && (!kinds || kinds.has("entity"));
-      const limit = searchOptions.limit ?? 10;
-      if (!Number.isSafeInteger(limit) || limit < 0) {
-        throw new Error(`${id}: search limit must be a non-negative safe integer`);
-      }
-      if (limit === 0) return [];
-      const [factPayload, nodePayload] = await Promise.all([
-        searchFacts ? callGraphiti(options.client, tools.searchFacts, {
-          query,
-          group_ids: [groupId],
-          max_facts: limit
-        }) : void 0,
-        searchNodes ? callGraphiti(options.client, tools.searchNodes, {
-          query,
-          group_ids: [groupId],
-          max_nodes: limit,
-          ...searchOptions.metadata?.entityTypes ? { entity_types: searchOptions.metadata.entityTypes } : {}
-        }) : void 0
-      ]);
-      const hits = mergeRankedMemoryHits(
-        [normalizeGraphitiFacts(factPayload, id), normalizeGraphitiNodes(nodePayload, id)].map(
-          (group) => group.filter((hit) => {
-            if (searchOptions.minScore === void 0) return true;
-            const score = hit.normalizedScore ?? hit.score;
-            return score !== void 0 && score >= searchOptions.minScore;
-          })
-        ),
-        limit
-      );
-      await enrichGraphitiProvenance(options, groupId, hits);
-      return hits;
-    },
-    async getContext(query, searchOptions = {}) {
-      return defaultGetMemoryContext(adapter, query, searchOptions);
-    },
-    async write(input) {
-      const scope = mergeScopes3(options.defaultScope, input.scope);
-      const groupId = graphitiGroupId(id, scope);
-      const eventKey = canonicalJson4(
-        stripUndefined2({
-          id: input.id,
-          kind: input.kind,
-          text: input.text,
-          title: input.title,
-          role: input.role,
-          metadata: input.metadata
-        })
-      );
-      const episodeUuid = input.id === void 0 ? randomUUID3() : deterministicUuid(`${id}:${groupId}:${eventKey}`);
-      const name = input.title ?? `${input.kind}:${input.id ?? stableId("event", eventKey)}`;
-      const sourceDescription = canonicalJson4(
-        stripUndefined2({
-          adapter: "agent-knowledge",
-          memoryKind: input.kind,
+async function runOwnedAgentMemoryExperiment(options, storage, runDir, lease) {
+  const runIdentity = stableId(
+    "memory_run",
+    canonicalJson4({
+      experimentId: options.experimentId,
+      experimentRunId: options.experimentRunId ?? runDir
+    })
+  );
+  const maxConcurrency = options.maxConcurrency ?? 2;
+  if (!Number.isSafeInteger(maxConcurrency) || maxConcurrency <= 0) {
+    throw new Error("memory experiment maxConcurrency must be a positive safe integer");
+  }
+  const executionPool = createMemoryExecutionPool(maxConcurrency);
+  const dispatchedExecutions = [];
+  const candidateById = new Map(options.candidates.map((candidate) => [candidate.id, candidate]));
+  const recoveryCandidateById = new Map(
+    [...options.candidates, ...options.recoveryCandidates ?? []].map((candidate) => [
+      candidate.id,
+      candidate
+    ])
+  );
+  const sequenceById = new Map(options.sequences.map((sequence) => [sequence.id, sequence]));
+  const scenarios = buildAgentMemorySequenceScenarios(options.sequences, options.candidates);
+  const attemptLogPath = join(runDir, "memory-attempts.jsonl");
+  const recoveryLogPath = join(runDir, "memory-recovery-attempts.jsonl");
+  const costCeiling = options.costCeiling ?? options.costLedger?.costCeilingUsd ?? 0;
+  const costLedger = options.costLedger ?? createRunCostLedger({
+    storage,
+    runDir,
+    costCeilingUsd: costCeiling
+  });
+  if (costLedger.costCeilingUsd !== costCeiling) {
+    throw new Error("memory experiment costCeiling must match the shared cost ledger ceiling");
+  }
+  storage.ensureDir(runDir);
+  await recoverAbandonedMemoryAttempts({
+    options,
+    storage,
+    runDir,
+    attemptLogPath,
+    candidateById: recoveryCandidateById,
+    sequenceById,
+    lease,
+    maxConcurrency,
+    costLedger,
+    maxRecoveryAttempts: options.maxRecoveryAttempts ?? 1e3,
+    recoveryLogPath,
+    maxRecoveryRetriesPerAttempt: options.maxRecoveryRetriesPerAttempt ?? DEFAULT_MEMORY_RECOVERY_RETRIES_PER_ATTEMPT
+  });
+  await lease.assertOwned();
+  let campaign;
+  let campaignError;
+  let settledExecutions = [];
+  try {
+    campaign = await runCampaign({
+      scenarios,
+      dispatch: (scenario, context) => {
+        const candidate = candidateById.get(scenario.candidateId);
+        if (!candidate) throw new Error(`unknown memory candidate ${scenario.candidateId}`);
+        const operation = executionPool.run(
+          () => runSequenceCell({
+            options,
+            candidate,
+            scenario,
+            context,
+            runIdentity,
+            storage,
+            attemptLogPath,
+            lease
+          })
+        );
+        dispatchedExecutions.push(operation);
+        return operation;
+      },
+      dispatchRef: memoryExperimentDispatchRef(options),
+      judges: [agentMemorySequenceJudge()],
+      runDir,
+      storage,
+      seed: options.seed,
+      reps: options.reps,
+      resumable: options.resumable,
+      costCeiling,
+      costLedger,
+      costPhase: options.costPhase,
+      maxConcurrency,
+      dispatchTimeoutMs: options.dispatchTimeoutMs,
+      expectUsage: "off",
+      now: options.now
+    });
+  } catch (error) {
+    campaignError = error;
+  } finally {
+    settledExecutions = await Promise.allSettled(dispatchedExecutions);
+  }
+  const cleanupFailures = settledExecutions.flatMap(
+    (settled) => settled.status === "rejected" && settled.reason instanceof AgentMemoryCleanupError ? [settled.reason] : []
+  );
+  if (campaignError && cleanupFailures.length > 0) {
+    throw new AggregateError(
+      [campaignError, ...cleanupFailures],
+      "memory experiment failed and provider cleanup also failed"
+    );
+  }
+  if (campaignError) throw campaignError;
+  if (cleanupFailures.length > 0) {
+    throw new AggregateError(cleanupFailures, "memory experiment cleanup failed after dispatch");
+  }
+  if (!campaign) throw new Error("memory experiment produced no campaign result");
+  await lease.assertOwned();
+  const costByCandidate = memoryExperimentCostByCandidate(
+    costLedger,
+    campaign.runDir,
+    scenarios,
+    [...options.candidates, ...options.recoveryCandidates ?? []].map((candidate) => candidate.id)
+  );
+  const unrankedRecoveryCostUsd = normalizeUsd(
+    (options.recoveryCandidates ?? []).reduce(
+      (sum, candidate) => sum + (costByCandidate.get(candidate.id) ?? 0),
+      0
+    )
+  );
+  const totalCostUsd = normalizeUsd(
+    [...costByCandidate.values()].reduce((sum, cost) => sum + cost, 0)
+  );
+  const rows = rankAgentMemoryExperiment(options.candidates, scenarios, campaign, costByCandidate);
+  const rankingJsonPath = join(campaign.runDir, "memory-experiment-ranking.json");
+  const rankingMarkdownPath = join(campaign.runDir, "memory-experiment-ranking.md");
+  storage.write(
+    rankingJsonPath,
+    `${JSON.stringify(
+      { experimentId: options.experimentId, totalCostUsd, unrankedRecoveryCostUsd, rows },
+      null,
+      2
+    )}
+`
+  );
+  storage.write(
+    rankingMarkdownPath,
+    renderAgentMemoryExperimentRanking(rows, totalCostUsd, unrankedRecoveryCostUsd)
+  );
+  return {
+    campaign,
+    rows,
+    totalCostUsd,
+    unrankedRecoveryCostUsd,
+    leaderCandidateId: rows.find((row) => row.cellsFailed === 0)?.candidateId,
+    rankingJsonPath,
+    rankingMarkdownPath,
+    attemptLogPath,
+    recoveryLogPath
+  };
+}
+function memoryExperimentDispatchRef(options) {
+  return stableId(
+    "memory_experiment",
+    canonicalJson4({
+      implementationRef: MEMORY_EXPERIMENT_IMPLEMENTATION_REF,
+      experimentId: options.experimentId,
+      experimentRunId: options.experimentRunId ?? null,
+      executeStepRef: options.executeStepRef ?? "fixtures",
+      cleanupBranches: options.cleanupBranches ?? true,
+      candidates: options.candidates.map((candidate) => ({
+        id: candidate.id,
+        ref: candidate.ref,
+        policy: candidate.policy ?? null,
+        baseScope: candidate.baseScope ?? null,
+        externalCostUsdPerSequence: candidate.externalCostUsdPerSequence ?? 0,
+        externalRecoveryCostUsdPerAttempt: candidate.externalRecoveryCostUsdPerAttempt ?? 0
+      })).sort((a, b) => a.id.localeCompare(b.id))
+    })
+  );
+}
+
+// src/memory/graphiti.ts
+import { randomUUID as randomUUID3 } from "crypto";
+import { canonicalJson as canonicalJson5 } from "@tangle-network/agent-eval";
+var DEFAULT_GRAPHITI_INGESTION_TIMEOUT_MS = 12e4;
+function createGraphitiMemoryAdapter(options) {
+  assertGraphitiOptions(options);
+  const id = options.id ?? "graphiti";
+  const consistency = options.consistency ?? "visible";
+  const tools = graphitiToolNames(options);
+  const queued = /* @__PURE__ */ new Map();
+  const adapter = {
+    id,
+    branchIsolation: consistency === "visible" ? {
+      mode: "scoped",
+      processExitSafe: false,
+      recoveryDelayMs: options.ingestionTimeoutMs ?? DEFAULT_GRAPHITI_INGESTION_TIMEOUT_MS
+    } : {
+      mode: "unsupported",
+      reason: 'queued Graphiti writes can become visible after a process restart; use consistency="visible" for branch experiments'
+    },
+    async search(query, searchOptions = {}) {
+      if (searchOptions.minScore !== void 0 && !Number.isFinite(searchOptions.minScore)) {
+        throw new Error(`${id}: minScore must be finite`);
+      }
+      const scope = mergeScopes3(options.defaultScope, searchOptions.scope);
+      const groupId = graphitiGroupId(id, scope);
+      const modes = new Set(options.search ?? ["facts", "nodes"]);
+      const kinds = searchOptions.kinds && searchOptions.kinds.length > 0 ? new Set(searchOptions.kinds) : null;
+      const searchFacts = modes.has("facts") && (!kinds || kinds.has("fact"));
+      const searchNodes = modes.has("nodes") && (!kinds || kinds.has("entity"));
+      const limit = searchOptions.limit ?? 10;
+      if (!Number.isSafeInteger(limit) || limit < 0) {
+        throw new Error(`${id}: search limit must be a non-negative safe integer`);
+      }
+      if (limit === 0) return [];
+      const [factPayload, nodePayload] = await Promise.all([
+        searchFacts ? callGraphiti(options.client, tools.searchFacts, {
+          query,
+          group_ids: [groupId],
+          max_facts: limit
+        }) : void 0,
+        searchNodes ? callGraphiti(options.client, tools.searchNodes, {
+          query,
+          group_ids: [groupId],
+          max_nodes: limit,
+          ...searchOptions.metadata?.entityTypes ? { entity_types: searchOptions.metadata.entityTypes } : {}
+        }) : void 0
+      ]);
+      const hits = mergeRankedMemoryHits(
+        [normalizeGraphitiFacts(factPayload, id), normalizeGraphitiNodes(nodePayload, id)].map(
+          (group) => group.filter((hit) => {
+            if (searchOptions.minScore === void 0) return true;
+            const score = hit.normalizedScore ?? hit.score;
+            return score !== void 0 && score >= searchOptions.minScore;
+          })
+        ),
+        limit
+      );
+      await enrichGraphitiProvenance(options, groupId, hits);
+      return hits;
+    },
+    async getContext(query, searchOptions = {}) {
+      return defaultGetMemoryContext(adapter, query, searchOptions);
+    },
+    async write(input) {
+      const scope = mergeScopes3(options.defaultScope, input.scope);
+      const groupId = graphitiGroupId(id, scope);
+      const eventKey = canonicalJson5(
+        stripUndefined2({
+          id: input.id,
+          kind: input.kind,
+          text: input.text,
+          title: input.title,
+          role: input.role,
+          metadata: input.metadata
+        })
+      );
+      const episodeUuid = input.id === void 0 ? randomUUID3() : deterministicUuid(`${id}:${groupId}:${eventKey}`);
+      const name = input.title ?? `${input.kind}:${input.id ?? stableId("event", eventKey)}`;
+      const sourceDescription = canonicalJson5(
+        stripUndefined2({
+          adapter: "agent-knowledge",
+          memoryKind: input.kind,
           eventId: input.id,
           actorId: input.metadata?.actorId,
           sessionId: scope.sessionId,
@@ -2416,797 +2435,329 @@ function createGraphitiMemoryAdapter(options) {
           groupId,
           consistency,
           queued: consistency === "queued"
-        }
-      };
-      return {
-        ...result,
-        sourceRecord: memoryWriteResultToSourceRecord(result, input.text, { scope })
-      };
-    },
-    async clear(scope) {
-      const groupId = graphitiGroupId(id, mergeScopes3(options.defaultScope, scope));
-      for (const [episodeUuid, pending] of queued) {
-        if (pending.groupId !== groupId) continue;
-        await waitForGraphitiEpisode(options, groupId, episodeUuid);
-        queued.delete(episodeUuid);
-      }
-      await callGraphiti(options.client, tools.clearGraph, { group_ids: [groupId] });
-    },
-    async flush() {
-      for (const [episodeUuid, pending] of queued) {
-        await waitForGraphitiEpisode(options, pending.groupId, episodeUuid);
-        queued.delete(episodeUuid);
-      }
-    }
-  };
-  return adapter;
-}
-async function callGraphiti(client, name, args) {
-  const raw = await client.callTool({ name, arguments: args });
-  const payload = graphitiPayload(raw);
-  if (isRecord(payload) && typeof payload.error === "string") {
-    throw new Error(`Graphiti ${name}: ${payload.error}`);
-  }
-  return payload;
-}
-function graphitiPayload(raw) {
-  if (!isRecord(raw)) return raw;
-  if (raw.isError === true) throw new Error(`Graphiti MCP: ${toolText(raw) || "tool call failed"}`);
-  if (isRecord(raw.structuredContent)) return unwrapResult(raw.structuredContent);
-  const text = toolText(raw);
-  if (text) {
-    try {
-      return unwrapResult(JSON.parse(text));
-    } catch {
-      return { message: text };
-    }
-  }
-  return unwrapResult(raw);
-}
-function unwrapResult(value) {
-  if (isRecord(value) && Object.keys(value).length === 1 && "result" in value) {
-    return value.result;
-  }
-  return value;
-}
-function toolText(raw) {
-  if (!Array.isArray(raw.content)) return "";
-  return raw.content.filter(isRecord).map((part) => typeof part.text === "string" ? part.text : "").filter(Boolean).join("\n");
-}
-function normalizeGraphitiFacts(raw, adapterId) {
-  const facts = isRecord(raw) && Array.isArray(raw.facts) ? raw.facts.filter(isRecord) : [];
-  return facts.flatMap((fact) => {
-    const text = stringField(fact, ["fact", "text"]);
-    if (!text) return [];
-    const factId = stringField(fact, ["uuid", "id"]) ?? stableId("fact", canonicalJson4(stripUndefined2({ adapterId, text, fact })));
-    const episodeUuids = stringArray2(fact.episodes ?? fact.episode_uuids);
-    const score = numberField(fact, ["score", "relevance_score"]);
-    const normalizedScore = normalizedScoreOf(score);
-    return [
-      {
-        id: factId,
-        uri: `memory://${adapterId}/fact/${factId}`,
-        kind: "fact",
-        text,
-        ...stringField(fact, ["name"]) ? { title: stringField(fact, ["name"]) } : {},
-        ...stringField(fact, ["created_at"]) ? { createdAt: stringField(fact, ["created_at"]) } : {},
-        ...stringField(fact, ["invalid_at"]) ? { validUntil: stringField(fact, ["invalid_at"]) } : stringField(fact, ["expired_at"]) ? { validUntil: stringField(fact, ["expired_at"]) } : {},
-        ...score !== void 0 ? { score } : {},
-        ...normalizedScore !== void 0 ? { normalizedScore } : {},
-        metadata: {
-          provider: "graphiti",
-          groupId: fact.group_id,
-          sourceNodeUuid: fact.source_node_uuid,
-          targetNodeUuid: fact.target_node_uuid,
-          validAt: fact.valid_at,
-          invalidAt: fact.invalid_at,
-          episodeUuids,
-          attributes: fact.attributes
-        }
-      }
-    ];
-  });
-}
-function normalizeGraphitiNodes(raw, adapterId) {
-  const nodes = isRecord(raw) && Array.isArray(raw.nodes) ? raw.nodes.filter(isRecord) : [];
-  return nodes.flatMap((node) => {
-    const name = stringField(node, ["name"]);
-    const summary = stringField(node, ["summary"]);
-    const text = summary ?? name;
-    if (!text) return [];
-    const nodeId = stringField(node, ["uuid", "id"]) ?? stableId("node", canonicalJson4(stripUndefined2({ adapterId, text, node })));
-    const score = numberField(node, ["score", "relevance_score"]);
-    const normalizedScore = normalizedScoreOf(score);
-    return [
-      {
-        id: nodeId,
-        uri: `memory://${adapterId}/entity/${nodeId}`,
-        kind: "entity",
-        text,
-        ...name ? { title: name } : {},
-        ...stringField(node, ["created_at"]) ? { createdAt: stringField(node, ["created_at"]) } : {},
-        ...score !== void 0 ? { score } : {},
-        ...normalizedScore !== void 0 ? { normalizedScore } : {},
-        metadata: {
-          provider: "graphiti",
-          groupId: node.group_id,
-          labels: node.labels,
-          attributes: node.attributes
-        }
-      }
-    ];
-  });
-}
-async function enrichGraphitiProvenance(options, groupId, hits) {
-  const wanted = new Set(hits.flatMap((hit) => stringArray2(hit.metadata?.episodeUuids)));
-  if (wanted.size === 0) return;
-  const scan = await scanGraphitiEpisodes(
-    options,
-    groupId,
-    wanted,
-    options.provenanceEpisodeLimit ?? options.episodeScanLimit ?? 1e4
-  );
-  const episodes = scan.episodes;
-  const byId = new Map(episodes.map((episode) => [episode.uuid, episode]));
-  for (const hit of hits) {
-    const episodeUuids = stringArray2(hit.metadata?.episodeUuids);
-    const sourceEpisodes = episodeUuids.map((uuid) => byId.get(uuid)).filter((episode) => episode !== void 0);
-    const provenanceIncomplete = episodeUuids.some((uuid) => !byId.has(uuid));
-    if (sourceEpisodes.length === 0) {
-      if (provenanceIncomplete) {
-        hit.metadata = { ...hit.metadata, provenanceIncomplete: true };
-      }
-      continue;
-    }
-    const descriptions = sourceEpisodes.map((episode) => parseDescription(episode.source_description)).filter(isRecord);
-    const first = descriptions[0];
-    hit.metadata = {
-      ...hit.metadata,
-      sourceEpisodes,
-      ...provenanceIncomplete || !scan.complete ? { provenanceIncomplete: true } : {},
-      ...first ?? {},
-      eventIds: uniqueStrings2(descriptions.map((value) => value.eventId)),
-      actorIds: uniqueStrings2(descriptions.map((value) => value.actorId)),
-      ...typeof first?.eventId === "string" ? { eventId: first.eventId } : {},
-      ...typeof first?.actorId === "string" ? { actorId: first.actorId } : {}
-    };
-  }
-}
-async function getGraphitiEpisodes(options, groupId, limit) {
-  const raw = await callGraphiti(options.client, graphitiToolNames(options).getEpisodes, {
-    group_ids: [groupId],
-    max_episodes: limit
-  });
-  if (!isRecord(raw) || !Array.isArray(raw.episodes)) return [];
-  return raw.episodes.filter(isRecord).flatMap((episode) => {
-    const uuid = stringField(episode, ["uuid", "id"]);
-    return uuid ? [{ ...episode, uuid }] : [];
-  });
-}
-async function scanGraphitiEpisodes(options, groupId, wanted, maximum) {
-  let limit = Math.min(100, maximum);
-  for (; ; ) {
-    const episodes = await getGraphitiEpisodes(options, groupId, limit);
-    const foundAll = [...wanted].every((uuid) => episodes.some((episode) => episode.uuid === uuid));
-    if (foundAll || episodes.length < limit) return { episodes, complete: foundAll };
-    if (limit === maximum) return { episodes, complete: false };
-    limit = Math.min(maximum, limit * 2);
-  }
-}
-async function waitForGraphitiEpisode(options, groupId, episodeUuid) {
-  const timeoutMs = options.ingestionTimeoutMs ?? DEFAULT_GRAPHITI_INGESTION_TIMEOUT_MS;
-  const pollIntervalMs = options.pollIntervalMs ?? 500;
-  const maximum = options.episodeScanLimit ?? 1e4;
-  const deadline = Date.now() + timeoutMs;
-  let scanLimitReached = false;
-  for (; ; ) {
-    const scan = await scanGraphitiEpisodes(options, groupId, /* @__PURE__ */ new Set([episodeUuid]), maximum);
-    if (scan.complete) return;
-    scanLimitReached ||= scan.episodes.length >= maximum;
-    const remainingMs = deadline - Date.now();
-    if (remainingMs <= 0) break;
-    await new Promise((resolve) => setTimeout(resolve, Math.min(pollIntervalMs, remainingMs)));
-  }
-  if (scanLimitReached) {
-    throw new Error(
-      `Graphiti episode ${episodeUuid} is outside episodeScanLimit=${maximum}; raise the limit or use a smaller group`
-    );
-  }
-  throw new Error(`Graphiti episode ${episodeUuid} was not visible after ${timeoutMs}ms`);
-}
-function graphitiGroupId(adapterId, scope) {
-  return `ak_${sha256(
-    canonicalJson4(
-      stripUndefined2({
-        adapterId,
-        tenantId: scope.tenantId,
-        userId: scope.userId,
-        agentId: scope.agentId,
-        teamId: scope.teamId,
-        runId: scope.runId,
-        sessionId: scope.sessionId,
-        namespace: scope.namespace,
-        tags: scope.tags
-      })
-    )
-  ).slice(0, 32)}`;
-}
-function graphitiToolNames(options) {
-  return {
-    addMemory: options.toolNames?.addMemory ?? "add_memory",
-    searchFacts: options.toolNames?.searchFacts ?? "search_memory_facts",
-    searchNodes: options.toolNames?.searchNodes ?? "search_nodes",
-    getEpisodes: options.toolNames?.getEpisodes ?? "get_episodes",
-    clearGraph: options.toolNames?.clearGraph ?? "clear_graph"
-  };
-}
-function assertGraphitiOptions(options) {
-  if (options.id !== void 0 && (typeof options.id !== "string" || !options.id.trim())) {
-    throw new Error("Graphiti id must be a non-empty string");
-  }
-  if (options.backendRef !== void 0 && (typeof options.backendRef !== "string" || !options.backendRef.trim())) {
-    throw new Error("Graphiti backendRef must be a non-empty string");
-  }
-  if (options.consistency !== void 0 && !["queued", "visible"].includes(options.consistency)) {
-    throw new Error("Graphiti consistency must be queued or visible");
-  }
-  for (const [name, value] of [
-    ["ingestionTimeoutMs", options.ingestionTimeoutMs],
-    ["pollIntervalMs", options.pollIntervalMs],
-    ["episodeScanLimit", options.episodeScanLimit],
-    ["provenanceEpisodeLimit", options.provenanceEpisodeLimit]
-  ]) {
-    if (value !== void 0 && (!Number.isSafeInteger(value) || value <= 0)) {
-      throw new Error(`Graphiti ${name} must be a positive safe integer`);
-    }
-  }
-  for (const [name, value] of Object.entries(options.toolNames ?? {})) {
-    if (typeof value !== "string" || value.trim().length === 0) {
-      throw new Error(`Graphiti toolNames.${name} must be a non-empty string`);
-    }
-  }
-}
-function deterministicUuid(value) {
-  const hex = sha256(value);
-  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-5${hex.slice(13, 16)}-a${hex.slice(17, 20)}-${hex.slice(20, 32)}`;
-}
-function parseDescription(value) {
-  if (!value) return void 0;
-  try {
-    return JSON.parse(value);
-  } catch {
-    return void 0;
-  }
-}
-function mergeScopes3(base, extra) {
-  return {
-    ...base ?? {},
-    ...extra ?? {},
-    tags: { ...base?.tags ?? {}, ...extra?.tags ?? {} }
-  };
-}
-function uniqueStrings2(values) {
-  return [...new Set(values.filter((value) => typeof value === "string"))];
-}
-function stringArray2(value) {
-  return Array.isArray(value) ? value.filter((entry) => typeof entry === "string") : [];
-}
-function stringField(value, keys) {
-  for (const key of keys) {
-    const field = value[key];
-    if (typeof field === "string" && field.length > 0) return field;
-  }
-  return void 0;
-}
-function numberField(value, keys) {
-  for (const key of keys) {
-    const field = value[key];
-    if (typeof field === "number" && Number.isFinite(field)) return field;
-  }
-  return void 0;
-}
-function normalizedScoreOf(score) {
-  return score !== void 0 && score >= 0 && score <= 1 ? score : void 0;
-}
-function isRecord(value) {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-function stripUndefined2(value) {
-  if (Array.isArray(value)) return value.map(stripUndefined2);
-  if (!isRecord(value)) return value;
-  return Object.fromEntries(
-    Object.entries(value).filter(([, child]) => child !== void 0).map(([key, child]) => [key, stripUndefined2(child)])
-  );
-}
-function graphitiMemoryAdapterIdentity(options) {
-  if (typeof options.backendRef !== "string" || !options.backendRef.trim()) {
-    throw new Error("Graphiti backendRef must be a non-empty string");
-  }
-  return stableId("graphiti", canonicalJson4(stripUndefined2(options)));
-}
-
-// src/memory/improvement.ts
-import { join as join2 } from "path";
-import { canonicalJson as canonicalJson5 } from "@tangle-network/agent-eval";
-import {
-  campaignLineageStore,
-  createRunCostLedger as createRunCostLedger2,
-  fsCampaignStorage as fsCampaignStorage2,
-  heldoutSignificance,
-  memLineageStore,
-  resolveRunDir as resolveRunDir2,
-  runLineageLoop,
-  surfaceHash
-} from "@tangle-network/agent-eval/campaign";
-var DEFAULT_CRITICAL_DIMENSIONS = [
-  "memory_stale_safe",
-  "memory_actor_recall",
-  "memory_event_recall"
-];
-var MEMORY_IMPROVEMENT_IMPLEMENTATION_REF = "agent-knowledge:memory-improvement:v2";
-async function runAgentMemoryImprovement(options) {
-  if ("onPromote" in options) {
-    throw new Error(
-      "memory improvement onPromote was removed; use activation.readCurrent and activation.compareAndSet"
-    );
-  }
-  if (options.seeds.length === 0) throw new Error("memory improvement requires seed configs");
-  if (options.trainSequences.length === 0) {
-    throw new Error("memory improvement requires training sequences");
-  }
-  if (options.holdoutSequences.length === 0) {
-    throw new Error("memory improvement requires holdout sequences");
-  }
-  const trainIds = new Set(options.trainSequences.map((sequence) => sequence.id));
-  const overlap = options.holdoutSequences.map((sequence) => sequence.id).filter((id) => trainIds.has(id));
-  if (overlap.length > 0) {
-    throw new Error(`memory improvement train/holdout overlap: ${overlap.join(", ")}`);
-  }
-  const trainFingerprints = new Map(
-    options.trainSequences.map((sequence) => [memorySequenceFingerprint(sequence), sequence.id])
-  );
-  const duplicateHistories = options.holdoutSequences.flatMap((sequence) => {
-    const trainId = trainFingerprints.get(memorySequenceFingerprint(sequence));
-    return trainId ? [`${trainId}/${sequence.id}`] : [];
-  });
-  if (duplicateHistories.length > 0) {
-    throw new Error(
-      `memory improvement train/holdout histories duplicate content: ${duplicateHistories.join(", ")}`
-    );
-  }
-  if (typeof options.improvementRef !== "string" || !options.improvementRef.trim()) {
-    throw new Error("memory improvement improvementRef must be a non-empty string");
-  }
-  assertMemoryImprovementOptions(options);
-  const storage = options.storage ?? fsCampaignStorage2();
-  const runDir = resolveRunDir2(options.runDir, options.repo);
-  storage.ensureDir(runDir);
-  const lease = await acquireAgentMemoryRunLease({
-    experimentId: options.experimentId,
-    runDir,
-    storage,
-    customStorage: options.storage !== void 0,
-    lockFileName: "memory-improvement.lock",
-    label: "memory improvement",
-    controllerMode: options.controllerMode,
-    acquireRunLease: options.acquireRunLease
-  });
-  let result;
-  let primaryError;
-  try {
-    result = await runAgentMemoryImprovementOwned(options, storage, runDir, lease);
-  } catch (error) {
-    primaryError = error;
-  }
-  let releaseError;
-  try {
-    await lease.release();
-  } catch (error) {
-    releaseError = error;
-  }
-  if (primaryError && releaseError) {
-    throw new AggregateError(
-      [primaryError, releaseError],
-      "memory improvement failed and its controller lease could not be released"
-    );
-  }
-  if (primaryError) throw primaryError;
-  if (releaseError) throw releaseError;
-  if (!result) throw new Error("memory improvement produced no result");
-  return result;
-}
-async function runAgentMemoryImprovementOwned(options, storage, runDir, lease) {
-  await lease.assertOwned();
-  const serializeRaw = options.serializeConfig ?? ((config) => canonicalJson5(config));
-  const parseRaw = options.parseConfig ?? ((surface) => JSON.parse(surface));
-  const serialize = (config) => serializeMemoryConfig(serializeRaw, config);
-  const parse = (surface) => parseMemoryConfig(parseRaw, surface);
-  for (const seed of options.seeds) assertMemoryConfigRoundTrip(seed.config, serialize, parse);
-  if (options.activation && !storage.append) {
-    throw new Error("memory activation requires CampaignStorage.append");
-  }
-  if (options.resumable !== false && !options.lineageStore && !storage.append) {
-    throw new Error("resumable memory improvement requires CampaignStorage.append");
-  }
-  assertMemoryImprovementIdentity(options, storage, runDir, serialize);
-  const costLedger = createRunCostLedger2({
-    storage,
-    runDir,
-    costCeilingUsd: options.maxTotalCostUsd ?? 0
-  });
-  reconcileInterruptedRunPaidCalls(costLedger, "memory improvement run");
-  assertNoInterruptedPaidCalls(costLedger, "memory improvement recovery");
-  const trainScenarios = options.trainSequences.map((sequence) => ({
-    id: sequence.id,
-    kind: "agent-memory-config-search",
-    sequenceId: sequence.id
-  }));
-  const evaluations = /* @__PURE__ */ new Map();
-  const evaluateSurface = async (surface) => {
-    await lease.assertOwned();
-    const text = requireStringSurface(surface);
-    const config = parse(text);
-    const canonicalSurface = serialize(config);
-    const hash = surfaceHash(canonicalSurface);
-    let pending = evaluations.get(hash);
-    if (!pending) {
-      pending = (async () => {
-        const candidate = await buildCandidate(options, config, hash, `search-${hash}`);
-        await lease.assertOwned();
-        const experiment = await runAgentMemoryExperiment({
-          ...experimentOptions(options, costLedger, storage, lease),
-          experimentId: `${options.experimentId}:search:${hash}`,
-          sequences: options.trainSequences,
-          candidates: [candidate],
-          runDir: join2(runDir, "search", hash),
-          costPhase: `memory.search.${hash}`
-        });
-        await lease.assertOwned();
-        return experiment;
-      })();
-      evaluations.set(hash, pending);
-      void pending.catch(() => evaluations.delete(hash));
-    }
-    const result2 = await pending;
-    await lease.assertOwned();
-    const row = result2.rows[0];
-    if (!row || row.cellsFailed > 0) {
-      throw new Error(`${hash}: memory candidate did not complete every training cell`);
-    }
-    return {
-      score: row.scoreMean,
-      scoreVector: sequenceScores(result2, options.trainSequences, row.candidateId)
-    };
-  };
-  const lineageStore = options.lineageStore ?? (options.resumable === false ? memLineageStore() : campaignLineageStore(storage, join2(runDir, "lineage.jsonl")));
-  const lineageOptions = {
-    seeds: options.seeds.map((seed) => ({
-      surface: serialize(seed.config),
-      track: seed.track,
-      proposer: seed.proposer,
-      ...seed.vision !== void 0 ? { vision: seed.vision } : {}
-    })),
-    scenarios: trainScenarios,
-    proposer: withCostContext(options.proposer, costLedger, lease, "default"),
-    proposers: options.proposers ? Object.fromEntries(
-      Object.entries(options.proposers).map(([name, proposer]) => [
-        name,
-        withCostContext(proposer, costLedger, lease, name)
-      ])
-    ) : void 0,
-    scoreSurface: evaluateSurface,
-    governor: options.governor ? withGovernorCostContext(options.governor, costLedger, lease) : void 0,
-    budget: {
-      ...options.budget,
-      maxNodes: options.seeds.length + options.budget.maxSteps
-    },
-    store: lineageStore,
-    populationSize: options.populationSize,
-    candidateConcurrency: options.candidateConcurrency
-  };
-  const search = await runLineageLoop(lineageOptions);
-  await lease.assertOwned();
-  const best = search.best;
-  if (!best) throw new Error("memory improvement produced no measured config");
-  const baselineSurface = serialize(options.seeds[0].config);
-  const baselineHash = surfaceHash(baselineSurface);
-  const winnerConfig = parse(requireStringSurface(best.surface));
-  const winnerSurface = serialize(winnerConfig);
-  const winnerHash = surfaceHash(winnerSurface);
-  const baselineConfig = parse(baselineSurface);
-  let holdout;
-  let decision;
-  if (winnerHash === baselineHash) {
-    const baselineMeasurement = await evaluateSurface(baselineSurface);
-    decision = {
-      status: "no-change",
-      reasons: ["search did not find a config better than the baseline"],
-      baselineScore: baselineMeasurement.score,
-      winnerScore: baselineMeasurement.score,
-      lift: 0,
-      criticalDimensions: []
-    };
-  } else {
-    await lease.assertOwned();
-    const [baselineCandidate, winnerCandidate] = await Promise.all([
-      buildCandidate(options, baselineConfig, baselineHash, "baseline"),
-      buildCandidate(options, winnerConfig, winnerHash, "winner")
-    ]);
-    await lease.assertOwned();
-    holdout = await runAgentMemoryExperiment({
-      ...experimentOptions(options, costLedger, storage, lease),
-      experimentId: `${options.experimentId}:holdout`,
-      sequences: options.holdoutSequences,
-      candidates: [baselineCandidate, winnerCandidate],
-      runDir: join2(runDir, "holdout"),
-      costPhase: "memory.holdout"
-    });
-    decision = decidePromotion({
-      options,
-      result: holdout,
-      baselineId: baselineCandidate.id,
-      winnerId: winnerCandidate.id
-    });
-  }
-  const resultJsonPath = join2(runDir, "memory-improvement-result.json");
-  const activationRef = options.activation?.ref ?? "not-configured";
-  const activationId = `memory-activation-${surfaceHash(
-    canonicalJson5({
-      experimentId: options.experimentId,
-      improvementRef: options.improvementRef,
-      activationRef,
-      baselineSurfaceHash: baselineHash,
-      winnerSurfaceHash: winnerHash,
-      holdoutManifestHash: holdout?.campaign.manifestHash ?? null,
-      promotionPolicy: normalizedPromotionPolicy(options)
-    })
-  )}`;
-  const activationJournalDir = join2(runDir, "activations");
-  const activationJournalPath = join2(activationJournalDir, `${activationId}.jsonl`);
-  const activationEligible = decision.status === "promote" && holdout !== void 0;
-  const activationEventIdentity = holdout ? {
-    schema: 1,
-    activationId,
-    experimentId: options.experimentId,
-    activationRef,
-    baselineSurfaceHash: baselineHash,
-    winnerSurfaceHash: winnerHash,
-    holdoutManifestHash: holdout.campaign.manifestHash
-  } : void 0;
-  const activationJournal = activationEligible && activationEventIdentity ? readMemoryActivationJournal(storage, activationJournalPath, activationEventIdentity) : { prepared: false };
-  const activation = {
-    id: activationId,
-    status: !activationEligible ? "not-eligible" : activationJournal.activated ? "already-activated" : options.activation ? "pending" : "not-configured",
-    journalPath: activationJournalPath
-  };
-  const result = {
-    lineage: search.lineage,
-    baselineConfig,
-    winnerConfig,
-    baselineSurface,
-    winnerSurface,
-    baselineSurfaceHash: baselineHash,
-    winnerSurfaceHash: winnerHash,
-    decision,
-    activation,
-    ...holdout ? { holdout } : {},
-    totalCostUsd: costLedger.summary().totalCostUsd,
-    resultJsonPath
-  };
-  await lease.assertOwned();
-  writeMemoryImprovementResult(storage, options.experimentId, result);
-  if (activationEligible && !activationJournal.activated && activationEventIdentity && holdout && options.activation) {
-    const activationDriver = options.activation;
-    const activationTimeoutMs = options.activationTimeoutMs ?? 6e4;
-    const hadPreparedEvent = activationJournal.prepared;
-    if (!hadPreparedEvent) {
-      await lease.assertOwned();
-      storage.ensureDir(activationJournalDir);
-      appendMemoryActivationEvent(storage, activationJournalPath, {
-        ...activationEventIdentity,
-        status: "prepared",
-        recordedAt: (options.now ?? (() => /* @__PURE__ */ new Date()))().toISOString()
-      });
+        }
+      };
+      return {
+        ...result,
+        sourceRecord: memoryWriteResultToSourceRecord(result, input.text, { scope })
+      };
+    },
+    async clear(scope) {
+      const groupId = graphitiGroupId(id, mergeScopes3(options.defaultScope, scope));
+      for (const [episodeUuid, pending] of queued) {
+        if (pending.groupId !== groupId) continue;
+        await waitForGraphitiEpisode(options, groupId, episodeUuid);
+        queued.delete(episodeUuid);
+      }
+      await callGraphiti(options.client, tools.clearGraph, { group_ids: [groupId] });
+    },
+    async flush() {
+      for (const [episodeUuid, pending] of queued) {
+        await waitForGraphitiEpisode(options, pending.groupId, episodeUuid);
+        queued.delete(episodeUuid);
+      }
     }
-    await lease.assertOwned();
-    const currentConfig = await runBoundedMemoryLifecycle({
-      operation: `${activationDriver.ref}: read current memory configuration`,
-      timeoutMs: activationTimeoutMs,
-      run: () => activationDriver.readCurrent()
-    });
-    await lease.assertOwned();
-    const currentHash = surfaceHash(serialize(currentConfig));
-    if (currentHash !== baselineHash && currentHash !== winnerHash) {
-      throw new Error(
-        `memory activation target '${activationDriver.ref}' changed concurrently; expected '${baselineHash}' or '${winnerHash}', found '${currentHash}'`
-      );
+  };
+  return adapter;
+}
+async function callGraphiti(client, name, args) {
+  const raw = await client.callTool({ name, arguments: args });
+  const payload = graphitiPayload(raw);
+  if (isRecord(payload) && typeof payload.error === "string") {
+    throw new Error(`Graphiti ${name}: ${payload.error}`);
+  }
+  return payload;
+}
+function graphitiPayload(raw) {
+  if (!isRecord(raw)) return raw;
+  if (raw.isError === true) throw new Error(`Graphiti MCP: ${toolText(raw) || "tool call failed"}`);
+  if (isRecord(raw.structuredContent)) return unwrapResult(raw.structuredContent);
+  const text = toolText(raw);
+  if (text) {
+    try {
+      return unwrapResult(JSON.parse(text));
+    } catch {
+      return { message: text };
     }
-    let outcome;
-    if (currentHash === winnerHash) {
-      outcome = hadPreparedEvent ? "recovered" : "already-current";
-      activation.status = "recovered";
-    } else {
-      let compareError;
-      try {
-        await runBoundedMemoryLifecycle({
-          operation: `${activationDriver.ref}: activate memory configuration`,
-          timeoutMs: activationTimeoutMs,
-          run: () => activationDriver.compareAndSet({
-            activationId,
-            expectedConfig: baselineConfig,
-            expectedSurfaceHash: baselineHash,
-            config: winnerConfig,
-            surfaceHash: winnerHash,
-            decision,
-            lineage: search.lineage,
-            holdout
-          })
-        });
-      } catch (error) {
-        compareError = error;
-      }
-      await lease.assertOwned();
-      let observedConfig;
-      try {
-        observedConfig = await runBoundedMemoryLifecycle({
-          operation: `${activationDriver.ref}: confirm memory configuration`,
-          timeoutMs: activationTimeoutMs,
-          run: () => activationDriver.readCurrent()
-        });
-      } catch (error) {
-        if (compareError) {
-          throw new AggregateError(
-            [compareError, error],
-            `memory activation '${activationId}' failed and its live state could not be confirmed`
-          );
+  }
+  return unwrapResult(raw);
+}
+function unwrapResult(value) {
+  if (isRecord(value) && Object.keys(value).length === 1 && "result" in value) {
+    return value.result;
+  }
+  return value;
+}
+function toolText(raw) {
+  if (!Array.isArray(raw.content)) return "";
+  return raw.content.filter(isRecord).map((part) => typeof part.text === "string" ? part.text : "").filter(Boolean).join("\n");
+}
+function normalizeGraphitiFacts(raw, adapterId) {
+  const facts = isRecord(raw) && Array.isArray(raw.facts) ? raw.facts.filter(isRecord) : [];
+  return facts.flatMap((fact) => {
+    const text = stringField(fact, ["fact", "text"]);
+    if (!text) return [];
+    const factId = stringField(fact, ["uuid", "id"]) ?? stableId("fact", canonicalJson5(stripUndefined2({ adapterId, text, fact })));
+    const episodeUuids = stringArray2(fact.episodes ?? fact.episode_uuids);
+    const score = numberField(fact, ["score", "relevance_score"]);
+    const normalizedScore = normalizedScoreOf(score);
+    return [
+      {
+        id: factId,
+        uri: `memory://${adapterId}/fact/${factId}`,
+        kind: "fact",
+        text,
+        ...stringField(fact, ["name"]) ? { title: stringField(fact, ["name"]) } : {},
+        ...stringField(fact, ["created_at"]) ? { createdAt: stringField(fact, ["created_at"]) } : {},
+        ...stringField(fact, ["invalid_at"]) ? { validUntil: stringField(fact, ["invalid_at"]) } : stringField(fact, ["expired_at"]) ? { validUntil: stringField(fact, ["expired_at"]) } : {},
+        ...score !== void 0 ? { score } : {},
+        ...normalizedScore !== void 0 ? { normalizedScore } : {},
+        metadata: {
+          provider: "graphiti",
+          groupId: fact.group_id,
+          sourceNodeUuid: fact.source_node_uuid,
+          targetNodeUuid: fact.target_node_uuid,
+          validAt: fact.valid_at,
+          invalidAt: fact.invalid_at,
+          episodeUuids,
+          attributes: fact.attributes
         }
-        throw error;
       }
-      await lease.assertOwned();
-      const observedHash = surfaceHash(serialize(observedConfig));
-      if (observedHash !== winnerHash) {
-        const mismatch = new Error(
-          `memory activation '${activationId}' did not install the measured winner; found '${observedHash}'`
-        );
-        if (compareError) {
-          throw new AggregateError(
-            [compareError, mismatch],
-            `memory activation '${activationId}' failed without applying the measured winner`
-          );
+    ];
+  });
+}
+function normalizeGraphitiNodes(raw, adapterId) {
+  const nodes = isRecord(raw) && Array.isArray(raw.nodes) ? raw.nodes.filter(isRecord) : [];
+  return nodes.flatMap((node) => {
+    const name = stringField(node, ["name"]);
+    const summary = stringField(node, ["summary"]);
+    const text = summary ?? name;
+    if (!text) return [];
+    const nodeId = stringField(node, ["uuid", "id"]) ?? stableId("node", canonicalJson5(stripUndefined2({ adapterId, text, node })));
+    const score = numberField(node, ["score", "relevance_score"]);
+    const normalizedScore = normalizedScoreOf(score);
+    return [
+      {
+        id: nodeId,
+        uri: `memory://${adapterId}/entity/${nodeId}`,
+        kind: "entity",
+        text,
+        ...name ? { title: name } : {},
+        ...stringField(node, ["created_at"]) ? { createdAt: stringField(node, ["created_at"]) } : {},
+        ...score !== void 0 ? { score } : {},
+        ...normalizedScore !== void 0 ? { normalizedScore } : {},
+        metadata: {
+          provider: "graphiti",
+          groupId: node.group_id,
+          labels: node.labels,
+          attributes: node.attributes
         }
-        throw mismatch;
       }
-      outcome = compareError ? "recovered" : "applied";
-      activation.status = compareError ? "recovered" : "activated";
+    ];
+  });
+}
+async function enrichGraphitiProvenance(options, groupId, hits) {
+  const wanted = new Set(hits.flatMap((hit) => stringArray2(hit.metadata?.episodeUuids)));
+  if (wanted.size === 0) return;
+  const scan = await scanGraphitiEpisodes(
+    options,
+    groupId,
+    wanted,
+    options.provenanceEpisodeLimit ?? options.episodeScanLimit ?? 1e4
+  );
+  const episodes = scan.episodes;
+  const byId = new Map(episodes.map((episode) => [episode.uuid, episode]));
+  for (const hit of hits) {
+    const episodeUuids = stringArray2(hit.metadata?.episodeUuids);
+    const sourceEpisodes = episodeUuids.map((uuid) => byId.get(uuid)).filter((episode) => episode !== void 0);
+    const provenanceIncomplete = episodeUuids.some((uuid) => !byId.has(uuid));
+    if (sourceEpisodes.length === 0) {
+      if (provenanceIncomplete) {
+        hit.metadata = { ...hit.metadata, provenanceIncomplete: true };
+      }
+      continue;
     }
-    await lease.assertOwned();
-    appendMemoryActivationEvent(storage, activationJournalPath, {
-      ...activationEventIdentity,
-      status: "activated",
-      outcome,
-      recordedAt: (options.now ?? (() => /* @__PURE__ */ new Date()))().toISOString()
-    });
-    writeMemoryImprovementResult(storage, options.experimentId, result);
+    const descriptions = sourceEpisodes.map((episode) => parseDescription(episode.source_description)).filter(isRecord);
+    const first = descriptions[0];
+    hit.metadata = {
+      ...hit.metadata,
+      sourceEpisodes,
+      ...provenanceIncomplete || !scan.complete ? { provenanceIncomplete: true } : {},
+      ...first ?? {},
+      eventIds: uniqueStrings2(descriptions.map((value) => value.eventId)),
+      actorIds: uniqueStrings2(descriptions.map((value) => value.actorId)),
+      ...typeof first?.eventId === "string" ? { eventId: first.eventId } : {},
+      ...typeof first?.actorId === "string" ? { actorId: first.actorId } : {}
+    };
+  }
+}
+async function getGraphitiEpisodes(options, groupId, limit) {
+  const raw = await callGraphiti(options.client, graphitiToolNames(options).getEpisodes, {
+    group_ids: [groupId],
+    max_episodes: limit
+  });
+  if (!isRecord(raw) || !Array.isArray(raw.episodes)) return [];
+  return raw.episodes.filter(isRecord).flatMap((episode) => {
+    const uuid = stringField(episode, ["uuid", "id"]);
+    return uuid ? [{ ...episode, uuid }] : [];
+  });
+}
+async function scanGraphitiEpisodes(options, groupId, wanted, maximum) {
+  let limit = Math.min(100, maximum);
+  for (; ; ) {
+    const episodes = await getGraphitiEpisodes(options, groupId, limit);
+    const foundAll = [...wanted].every((uuid) => episodes.some((episode) => episode.uuid === uuid));
+    if (foundAll || episodes.length < limit) return { episodes, complete: foundAll };
+    if (limit === maximum) return { episodes, complete: false };
+    limit = Math.min(maximum, limit * 2);
+  }
+}
+async function waitForGraphitiEpisode(options, groupId, episodeUuid) {
+  const timeoutMs = options.ingestionTimeoutMs ?? DEFAULT_GRAPHITI_INGESTION_TIMEOUT_MS;
+  const pollIntervalMs = options.pollIntervalMs ?? 500;
+  const maximum = options.episodeScanLimit ?? 1e4;
+  const deadline = Date.now() + timeoutMs;
+  let scanLimitReached = false;
+  for (; ; ) {
+    const scan = await scanGraphitiEpisodes(options, groupId, /* @__PURE__ */ new Set([episodeUuid]), maximum);
+    if (scan.complete) return;
+    scanLimitReached ||= scan.episodes.length >= maximum;
+    const remainingMs = deadline - Date.now();
+    if (remainingMs <= 0) break;
+    await new Promise((resolve) => setTimeout(resolve, Math.min(pollIntervalMs, remainingMs)));
+  }
+  if (scanLimitReached) {
+    throw new Error(
+      `Graphiti episode ${episodeUuid} is outside episodeScanLimit=${maximum}; raise the limit or use a smaller group`
+    );
   }
-  return result;
+  throw new Error(`Graphiti episode ${episodeUuid} was not visible after ${timeoutMs}ms`);
 }
-function withCostContext(proposer, costLedger, lease, label) {
+function graphitiGroupId(adapterId, scope) {
+  return `ak_${sha256(
+    canonicalJson5(
+      stripUndefined2({
+        adapterId,
+        tenantId: scope.tenantId,
+        userId: scope.userId,
+        agentId: scope.agentId,
+        teamId: scope.teamId,
+        runId: scope.runId,
+        sessionId: scope.sessionId,
+        namespace: scope.namespace,
+        tags: scope.tags
+      })
+    )
+  ).slice(0, 32)}`;
+}
+function graphitiToolNames(options) {
   return {
-    kind: proposer.kind,
-    async propose(context) {
-      await lease.assertOwned();
-      const proposal = await proposer.propose({
-        ...context,
-        costLedger,
-        costPhase: `memory.proposal.${context.track?.id ?? label}`
-      });
-      await lease.assertOwned();
-      return proposal;
-    },
-    ...proposer.decide ? { decide: (input) => proposer.decide(input) } : {}
+    addMemory: options.toolNames?.addMemory ?? "add_memory",
+    searchFacts: options.toolNames?.searchFacts ?? "search_memory_facts",
+    searchNodes: options.toolNames?.searchNodes ?? "search_nodes",
+    getEpisodes: options.toolNames?.getEpisodes ?? "get_episodes",
+    clearGraph: options.toolNames?.clearGraph ?? "clear_graph"
   };
 }
-function withGovernorCostContext(governor, costLedger, lease) {
-  return {
-    async decide(context) {
-      await lease.assertOwned();
-      const decision = await governor.decide({
-        ...context,
-        costLedger,
-        costPhase: "memory.governor"
-      });
-      await lease.assertOwned();
-      return decision;
+function assertGraphitiOptions(options) {
+  if (options.id !== void 0 && (typeof options.id !== "string" || !options.id.trim())) {
+    throw new Error("Graphiti id must be a non-empty string");
+  }
+  if (options.backendRef !== void 0 && (typeof options.backendRef !== "string" || !options.backendRef.trim())) {
+    throw new Error("Graphiti backendRef must be a non-empty string");
+  }
+  if (options.consistency !== void 0 && !["queued", "visible"].includes(options.consistency)) {
+    throw new Error("Graphiti consistency must be queued or visible");
+  }
+  for (const [name, value] of [
+    ["ingestionTimeoutMs", options.ingestionTimeoutMs],
+    ["pollIntervalMs", options.pollIntervalMs],
+    ["episodeScanLimit", options.episodeScanLimit],
+    ["provenanceEpisodeLimit", options.provenanceEpisodeLimit]
+  ]) {
+    if (value !== void 0 && (!Number.isSafeInteger(value) || value <= 0)) {
+      throw new Error(`Graphiti ${name} must be a positive safe integer`);
     }
-  };
+  }
+  for (const [name, value] of Object.entries(options.toolNames ?? {})) {
+    if (typeof value !== "string" || value.trim().length === 0) {
+      throw new Error(`Graphiti toolNames.${name} must be a non-empty string`);
+    }
+  }
 }
-async function buildCandidate(options, config, hash, role) {
-  const built = await options.createCandidate({
-    config,
-    candidateId: `${role}-${hash}`,
-    surfaceHash: hash
-  });
-  return {
-    ...built,
-    id: `${role}-${hash}`,
-    ref: built.ref
-  };
+function deterministicUuid(value) {
+  const hex = sha256(value);
+  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-5${hex.slice(13, 16)}-a${hex.slice(17, 20)}-${hex.slice(20, 32)}`;
 }
-function experimentOptions(options, costLedger, storage, lease) {
+function parseDescription(value) {
+  if (!value) return void 0;
+  try {
+    return JSON.parse(value);
+  } catch {
+    return void 0;
+  }
+}
+function mergeScopes3(base, extra) {
   return {
-    storage,
-    seed: options.seed,
-    reps: options.reps,
-    resumable: options.resumable,
-    maxConcurrency: options.sequenceConcurrency,
-    dispatchTimeoutMs: options.dispatchTimeoutMs,
-    cleanupTimeoutMs: options.cleanupTimeoutMs,
-    maxRecoveryAttempts: options.maxRecoveryAttempts,
-    maxRecoveryRetriesPerAttempt: options.maxRecoveryRetriesPerAttempt,
-    executeStep: options.executeStep,
-    executeStepRef: options.executeStepRef,
-    onBranchSnapshot: options.onBranchSnapshot,
-    cleanupBranches: options.cleanupBranches ?? true,
-    costLedger,
-    acquireRunLease: async () => ({
-      assertOwned: () => lease.assertOwned(),
-      release() {
-      }
-    }),
-    now: options.now
+    ...base ?? {},
+    ...extra ?? {},
+    tags: { ...base?.tags ?? {}, ...extra?.tags ?? {} }
   };
 }
-function assertMemoryImprovementIdentity(options, storage, runDir, serialize) {
-  const path = join2(runDir, "memory-improvement-manifest.json");
-  const identity = {
-    schema: 6,
-    implementationRef: MEMORY_IMPROVEMENT_IMPLEMENTATION_REF,
-    experimentId: options.experimentId,
-    improvementRef: options.improvementRef,
-    activationRef: options.activation?.ref ?? null,
-    proposerKind: options.proposer.kind,
-    proposerKinds: Object.fromEntries(
-      Object.entries(options.proposers ?? {}).sort(([a], [b]) => a.localeCompare(b)).map(([name, proposer]) => [name, proposer.kind])
-    ),
-    populationSize: options.populationSize ?? 4,
-    budget: { maxSteps: options.budget.maxSteps },
-    executeStepRef: options.executeStepRef ?? null,
-    cleanupBranches: options.cleanupBranches ?? true,
-    promotionPolicy: normalizedPromotionPolicy(options),
-    seed: options.seed ?? null,
-    reps: options.reps ?? 1,
-    seeds: options.seeds.map((entry) => ({
-      config: serialize(entry.config),
-      track: entry.track,
-      vision: entry.vision ?? null,
-      proposer: entry.proposer
-    })),
-    trainSequences: options.trainSequences,
-    holdoutSequences: options.holdoutSequences
-  };
-  const identityHash = surfaceHash(canonicalJson5(identity));
-  const stored = storage.read(path);
-  if (stored === void 0) {
-    if (storage.exists(path)) throw new Error(`cannot read memory improvement manifest '${path}'`);
-    if (storage.exists(join2(runDir, "lineage.jsonl")) || storage.exists(join2(runDir, "memory-improvement-result.json"))) {
-      throw new Error(`memory improvement run '${runDir}' has state without an identity manifest`);
-    }
-    storage.write(path, `${JSON.stringify({ identityHash, identity }, null, 2)}
-`);
-    return;
+function uniqueStrings2(values) {
+  return [...new Set(values.filter((value) => typeof value === "string"))];
+}
+function stringArray2(value) {
+  return Array.isArray(value) ? value.filter((entry) => typeof entry === "string") : [];
+}
+function stringField(value, keys) {
+  for (const key of keys) {
+    const field = value[key];
+    if (typeof field === "string" && field.length > 0) return field;
   }
-  let manifest;
-  try {
-    manifest = JSON.parse(stored);
-  } catch (error) {
-    throw new Error(`invalid memory improvement manifest '${path}'`, { cause: error });
+  return void 0;
+}
+function numberField(value, keys) {
+  for (const key of keys) {
+    const field = value[key];
+    if (typeof field === "number" && Number.isFinite(field)) return field;
   }
-  if (!manifest || typeof manifest !== "object" || manifest.identityHash !== identityHash || canonicalJson5(manifest.identity) !== canonicalJson5(identity)) {
-    throw new Error(
-      `memory improvement run '${runDir}' does not match its persisted inputs or implementationRef`
-    );
+  return void 0;
+}
+function normalizedScoreOf(score) {
+  return score !== void 0 && score >= 0 && score <= 1 ? score : void 0;
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function stripUndefined2(value) {
+  if (Array.isArray(value)) return value.map(stripUndefined2);
+  if (!isRecord(value)) return value;
+  return Object.fromEntries(
+    Object.entries(value).filter(([, child]) => child !== void 0).map(([key, child]) => [key, stripUndefined2(child)])
+  );
+}
+function graphitiMemoryAdapterIdentity(options) {
+  if (typeof options.backendRef !== "string" || !options.backendRef.trim()) {
+    throw new Error("Graphiti backendRef must be a non-empty string");
   }
+  return stableId("graphiti", canonicalJson5(stripUndefined2(options)));
 }
+
+// src/memory/improvement/run.ts
+import { join as join3 } from "path";
+import { canonicalJson as canonicalJson7 } from "@tangle-network/agent-eval";
+import {
+  campaignLineageStore,
+  createRunCostLedger as createRunCostLedger2,
+  fsCampaignStorage as fsCampaignStorage2,
+  memLineageStore,
+  resolveRunDir as resolveRunDir2,
+  runLineageLoop,
+  surfaceHash as surfaceHash2
+} from "@tangle-network/agent-eval/campaign";
+
+// src/memory/improvement/activation.ts
 function appendMemoryActivationEvent(storage, path, event) {
   appendDurableJournalEvent({
     storage,
@@ -3274,27 +2825,94 @@ function parseMemoryActivationEvent(value, path, line, expected) {
   }
   return value;
 }
-function writeMemoryImprovementResult(storage, experimentId, result) {
-  storage.write(
-    result.resultJsonPath,
-    `${JSON.stringify(
-      {
-        experimentId,
-        baselineSurfaceHash: result.baselineSurfaceHash,
-        winnerSurfaceHash: result.winnerSurfaceHash,
-        baselineSurface: result.baselineSurface,
-        winnerSurface: result.winnerSurface,
-        decision: result.decision,
-        activation: result.activation,
-        totalCostUsd: result.totalCostUsd,
-        lineage: result.lineage.toGraph()
-      },
-      null,
-      2
-    )}
-`
-  );
+
+// src/memory/improvement/candidate.ts
+function withCostContext(proposer, costLedger, lease, label) {
+  return {
+    kind: proposer.kind,
+    async propose(context) {
+      await lease.assertOwned();
+      const proposal = await proposer.propose({
+        ...context,
+        costLedger,
+        costPhase: `memory.proposal.${context.track?.id ?? label}`
+      });
+      await lease.assertOwned();
+      return proposal;
+    },
+    ...proposer.decide ? { decide: (input) => proposer.decide(input) } : {}
+  };
+}
+function withGovernorCostContext(governor, costLedger, lease) {
+  return {
+    async decide(context) {
+      await lease.assertOwned();
+      const decision = await governor.decide({
+        ...context,
+        costLedger,
+        costPhase: "memory.governor"
+      });
+      await lease.assertOwned();
+      return decision;
+    }
+  };
+}
+async function buildCandidate(options, config, hash, role) {
+  const built = await options.createCandidate({
+    config,
+    candidateId: `${role}-${hash}`,
+    surfaceHash: hash
+  });
+  return {
+    ...built,
+    id: `${role}-${hash}`,
+    ref: built.ref
+  };
+}
+function experimentOptions(options, costLedger, storage, lease) {
+  return {
+    storage,
+    seed: options.seed,
+    reps: options.reps,
+    resumable: options.resumable,
+    maxConcurrency: options.sequenceConcurrency,
+    dispatchTimeoutMs: options.dispatchTimeoutMs,
+    cleanupTimeoutMs: options.cleanupTimeoutMs,
+    maxRecoveryAttempts: options.maxRecoveryAttempts,
+    maxRecoveryRetriesPerAttempt: options.maxRecoveryRetriesPerAttempt,
+    executeStep: options.executeStep,
+    executeStepRef: options.executeStepRef,
+    onBranchSnapshot: options.onBranchSnapshot,
+    cleanupBranches: options.cleanupBranches ?? true,
+    costLedger,
+    acquireRunLease: async () => ({
+      assertOwned: () => lease.assertOwned(),
+      release() {
+      }
+    }),
+    now: options.now
+  };
 }
+
+// src/memory/improvement/identity.ts
+import { join as join2 } from "path";
+import { canonicalJson as canonicalJson6 } from "@tangle-network/agent-eval";
+import {
+  surfaceHash
+} from "@tangle-network/agent-eval/campaign";
+
+// src/memory/improvement/promotion.ts
+import { heldoutSignificance } from "@tangle-network/agent-eval/campaign";
+
+// src/memory/improvement/types.ts
+var DEFAULT_CRITICAL_DIMENSIONS = [
+  "memory_stale_safe",
+  "memory_actor_recall",
+  "memory_event_recall"
+];
+var MEMORY_IMPROVEMENT_IMPLEMENTATION_REF = "agent-knowledge:memory-improvement:v2";
+
+// src/memory/improvement/promotion.ts
 function decidePromotion(input) {
   const { options, result, baselineId, winnerId } = input;
   const baselineRow = result.rows.find((row) => row.candidateId === baselineId);
@@ -3433,6 +3051,62 @@ function sequenceScores(result, sequences, candidateId) {
   }
   return sequences.map((sequence) => mean2(bySequence.get(sequence.id) ?? []));
 }
+function mean2(values) {
+  return values.length === 0 ? 0 : values.reduce((sum, value) => sum + value, 0) / values.length;
+}
+
+// src/memory/improvement/identity.ts
+function assertMemoryImprovementIdentity(options, storage, runDir, serialize) {
+  const path = join2(runDir, "memory-improvement-manifest.json");
+  const identity = {
+    schema: 6,
+    implementationRef: MEMORY_IMPROVEMENT_IMPLEMENTATION_REF,
+    experimentId: options.experimentId,
+    improvementRef: options.improvementRef,
+    activationRef: options.activation?.ref ?? null,
+    proposerKind: options.proposer.kind,
+    proposerKinds: Object.fromEntries(
+      Object.entries(options.proposers ?? {}).sort(([a], [b]) => a.localeCompare(b)).map(([name, proposer]) => [name, proposer.kind])
+    ),
+    populationSize: options.populationSize ?? 4,
+    budget: { maxSteps: options.budget.maxSteps },
+    executeStepRef: options.executeStepRef ?? null,
+    cleanupBranches: options.cleanupBranches ?? true,
+    promotionPolicy: normalizedPromotionPolicy(options),
+    seed: options.seed ?? null,
+    reps: options.reps ?? 1,
+    seeds: options.seeds.map((entry) => ({
+      config: serialize(entry.config),
+      track: entry.track,
+      vision: entry.vision ?? null,
+      proposer: entry.proposer
+    })),
+    trainSequences: options.trainSequences,
+    holdoutSequences: options.holdoutSequences
+  };
+  const identityHash = surfaceHash(canonicalJson6(identity));
+  const stored = storage.read(path);
+  if (stored === void 0) {
+    if (storage.exists(path)) throw new Error(`cannot read memory improvement manifest '${path}'`);
+    if (storage.exists(join2(runDir, "lineage.jsonl")) || storage.exists(join2(runDir, "memory-improvement-result.json"))) {
+      throw new Error(`memory improvement run '${runDir}' has state without an identity manifest`);
+    }
+    storage.write(path, `${JSON.stringify({ identityHash, identity }, null, 2)}
+`);
+    return;
+  }
+  let manifest;
+  try {
+    manifest = JSON.parse(stored);
+  } catch (error) {
+    throw new Error(`invalid memory improvement manifest '${path}'`, { cause: error });
+  }
+  if (!manifest || typeof manifest !== "object" || manifest.identityHash !== identityHash || canonicalJson6(manifest.identity) !== canonicalJson6(identity)) {
+    throw new Error(
+      `memory improvement run '${runDir}' does not match its persisted inputs or implementationRef`
+    );
+  }
+}
 function requireStringSurface(surface) {
   if (typeof surface !== "string" || surface.trim().length === 0) {
     throw new Error("memory config proposer must return a JSON string surface");
@@ -3469,8 +3143,33 @@ function assertMemoryConfigRoundTrip(config, serialize, parse) {
 }
 function memorySequenceFingerprint(sequence) {
   const { id: _id, split: _split, tags: _tags, ...content } = sequence;
-  return surfaceHash(canonicalJson5(content));
+  return surfaceHash(canonicalJson6(content));
+}
+
+// src/memory/improvement/output.ts
+function writeMemoryImprovementResult(storage, experimentId, result) {
+  storage.write(
+    result.resultJsonPath,
+    `${JSON.stringify(
+      {
+        experimentId,
+        baselineSurfaceHash: result.baselineSurfaceHash,
+        winnerSurfaceHash: result.winnerSurfaceHash,
+        baselineSurface: result.baselineSurface,
+        winnerSurface: result.winnerSurface,
+        decision: result.decision,
+        activation: result.activation,
+        totalCostUsd: result.totalCostUsd,
+        lineage: result.lineage.toGraph()
+      },
+      null,
+      2
+    )}
+`
+  );
 }
+
+// src/memory/improvement/validation.ts
 function assertMemoryImprovementOptions(options) {
   for (const [name, value] of [
     ["experimentId", options.experimentId],
@@ -3545,40 +3244,385 @@ function assertMemoryImprovementOptions(options) {
     if (typeof seed.track !== "string" || !seed.track.trim() || typeof seed.proposer !== "string" || !seed.proposer.trim()) {
       throw new Error("memory improvement seeds require non-empty track and proposer values");
     }
-    if (seed.vision !== void 0 && (typeof seed.vision !== "string" || !seed.vision.trim())) {
-      throw new Error("memory improvement seed vision must be a non-empty string when provided");
+    if (seed.vision !== void 0 && (typeof seed.vision !== "string" || !seed.vision.trim())) {
+      throw new Error("memory improvement seed vision must be a non-empty string when provided");
+    }
+  }
+  const dimensions = options.criticalDimensions ?? DEFAULT_CRITICAL_DIMENSIONS;
+  if (dimensions.some((dimension) => typeof dimension !== "string" || !dimension.trim())) {
+    throw new Error("memory improvement criticalDimensions must contain non-empty names");
+  }
+  if (new Set(dimensions).size !== dimensions.length) {
+    throw new Error("memory improvement criticalDimensions must be unique");
+  }
+  assertDistinctSequenceContent(options.trainSequences, "train");
+  assertDistinctSequenceContent(options.holdoutSequences, "holdout");
+}
+function assertDistinctSequenceContent(sequences, split) {
+  const idsByFingerprint = /* @__PURE__ */ new Map();
+  for (const sequence of sequences) {
+    const fingerprint = memorySequenceFingerprint(sequence);
+    const prior = idsByFingerprint.get(fingerprint);
+    if (prior) {
+      throw new Error(
+        `memory improvement ${split} histories duplicate content: ${prior}/${sequence.id}`
+      );
+    }
+    idsByFingerprint.set(fingerprint, sequence.id);
+  }
+}
+
+// src/memory/improvement/run.ts
+async function runAgentMemoryImprovement(options) {
+  if ("onPromote" in options) {
+    throw new Error(
+      "memory improvement onPromote was removed; use activation.readCurrent and activation.compareAndSet"
+    );
+  }
+  if (options.seeds.length === 0) throw new Error("memory improvement requires seed configs");
+  if (options.trainSequences.length === 0) {
+    throw new Error("memory improvement requires training sequences");
+  }
+  if (options.holdoutSequences.length === 0) {
+    throw new Error("memory improvement requires holdout sequences");
+  }
+  const trainIds = new Set(options.trainSequences.map((sequence) => sequence.id));
+  const overlap = options.holdoutSequences.map((sequence) => sequence.id).filter((id) => trainIds.has(id));
+  if (overlap.length > 0) {
+    throw new Error(`memory improvement train/holdout overlap: ${overlap.join(", ")}`);
+  }
+  const trainFingerprints = new Map(
+    options.trainSequences.map((sequence) => [memorySequenceFingerprint(sequence), sequence.id])
+  );
+  const duplicateHistories = options.holdoutSequences.flatMap((sequence) => {
+    const trainId = trainFingerprints.get(memorySequenceFingerprint(sequence));
+    return trainId ? [`${trainId}/${sequence.id}`] : [];
+  });
+  if (duplicateHistories.length > 0) {
+    throw new Error(
+      `memory improvement train/holdout histories duplicate content: ${duplicateHistories.join(", ")}`
+    );
+  }
+  if (typeof options.improvementRef !== "string" || !options.improvementRef.trim()) {
+    throw new Error("memory improvement improvementRef must be a non-empty string");
+  }
+  assertMemoryImprovementOptions(options);
+  const storage = options.storage ?? fsCampaignStorage2();
+  const runDir = resolveRunDir2(options.runDir, options.repo);
+  storage.ensureDir(runDir);
+  const lease = await acquireAgentMemoryRunLease({
+    experimentId: options.experimentId,
+    runDir,
+    storage,
+    customStorage: options.storage !== void 0,
+    lockFileName: "memory-improvement.lock",
+    label: "memory improvement",
+    controllerMode: options.controllerMode,
+    acquireRunLease: options.acquireRunLease
+  });
+  let result;
+  let primaryError;
+  try {
+    result = await runAgentMemoryImprovementOwned(options, storage, runDir, lease);
+  } catch (error) {
+    primaryError = error;
+  }
+  let releaseError;
+  try {
+    await lease.release();
+  } catch (error) {
+    releaseError = error;
+  }
+  if (primaryError && releaseError) {
+    throw new AggregateError(
+      [primaryError, releaseError],
+      "memory improvement failed and its controller lease could not be released"
+    );
+  }
+  if (primaryError) throw primaryError;
+  if (releaseError) throw releaseError;
+  if (!result) throw new Error("memory improvement produced no result");
+  return result;
+}
+async function runAgentMemoryImprovementOwned(options, storage, runDir, lease) {
+  await lease.assertOwned();
+  const serializeRaw = options.serializeConfig ?? ((config) => canonicalJson7(config));
+  const parseRaw = options.parseConfig ?? ((surface) => JSON.parse(surface));
+  const serialize = (config) => serializeMemoryConfig(serializeRaw, config);
+  const parse = (surface) => parseMemoryConfig(parseRaw, surface);
+  for (const seed of options.seeds) assertMemoryConfigRoundTrip(seed.config, serialize, parse);
+  if (options.activation && !storage.append) {
+    throw new Error("memory activation requires CampaignStorage.append");
+  }
+  if (options.resumable !== false && !options.lineageStore && !storage.append) {
+    throw new Error("resumable memory improvement requires CampaignStorage.append");
+  }
+  assertMemoryImprovementIdentity(options, storage, runDir, serialize);
+  const costLedger = createRunCostLedger2({
+    storage,
+    runDir,
+    costCeilingUsd: options.maxTotalCostUsd ?? 0
+  });
+  reconcileInterruptedRunPaidCalls(costLedger, "memory improvement run");
+  assertNoInterruptedPaidCalls(costLedger, "memory improvement recovery");
+  const trainScenarios = options.trainSequences.map((sequence) => ({
+    id: sequence.id,
+    kind: "agent-memory-config-search",
+    sequenceId: sequence.id
+  }));
+  const evaluations = /* @__PURE__ */ new Map();
+  const evaluateSurface = async (surface) => {
+    await lease.assertOwned();
+    const text = requireStringSurface(surface);
+    const config = parse(text);
+    const canonicalSurface = serialize(config);
+    const hash = surfaceHash2(canonicalSurface);
+    let pending = evaluations.get(hash);
+    if (!pending) {
+      pending = (async () => {
+        const candidate = await buildCandidate(options, config, hash, `search-${hash}`);
+        await lease.assertOwned();
+        const experiment = await runAgentMemoryExperiment({
+          ...experimentOptions(options, costLedger, storage, lease),
+          experimentId: `${options.experimentId}:search:${hash}`,
+          sequences: options.trainSequences,
+          candidates: [candidate],
+          runDir: join3(runDir, "search", hash),
+          costPhase: `memory.search.${hash}`
+        });
+        await lease.assertOwned();
+        return experiment;
+      })();
+      evaluations.set(hash, pending);
+      void pending.catch(() => evaluations.delete(hash));
+    }
+    const result2 = await pending;
+    await lease.assertOwned();
+    const row = result2.rows[0];
+    if (!row || row.cellsFailed > 0) {
+      throw new Error(`${hash}: memory candidate did not complete every training cell`);
     }
+    return {
+      score: row.scoreMean,
+      scoreVector: sequenceScores(result2, options.trainSequences, row.candidateId)
+    };
+  };
+  const lineageStore = options.lineageStore ?? (options.resumable === false ? memLineageStore() : campaignLineageStore(storage, join3(runDir, "lineage.jsonl")));
+  const lineageOptions = {
+    seeds: options.seeds.map((seed) => ({
+      surface: serialize(seed.config),
+      track: seed.track,
+      proposer: seed.proposer,
+      ...seed.vision !== void 0 ? { vision: seed.vision } : {}
+    })),
+    scenarios: trainScenarios,
+    proposer: withCostContext(options.proposer, costLedger, lease, "default"),
+    proposers: options.proposers ? Object.fromEntries(
+      Object.entries(options.proposers).map(([name, proposer]) => [
+        name,
+        withCostContext(proposer, costLedger, lease, name)
+      ])
+    ) : void 0,
+    scoreSurface: evaluateSurface,
+    governor: options.governor ? withGovernorCostContext(options.governor, costLedger, lease) : void 0,
+    budget: {
+      ...options.budget,
+      maxNodes: options.seeds.length + options.budget.maxSteps
+    },
+    store: lineageStore,
+    populationSize: options.populationSize,
+    candidateConcurrency: options.candidateConcurrency
+  };
+  const search = await runLineageLoop(lineageOptions);
+  await lease.assertOwned();
+  const best = search.best;
+  if (!best) throw new Error("memory improvement produced no measured config");
+  const baselineSurface = serialize(options.seeds[0].config);
+  const baselineHash = surfaceHash2(baselineSurface);
+  const winnerConfig = parse(requireStringSurface(best.surface));
+  const winnerSurface = serialize(winnerConfig);
+  const winnerHash = surfaceHash2(winnerSurface);
+  const baselineConfig = parse(baselineSurface);
+  let holdout;
+  let decision;
+  if (winnerHash === baselineHash) {
+    const baselineMeasurement = await evaluateSurface(baselineSurface);
+    decision = {
+      status: "no-change",
+      reasons: ["search did not find a config better than the baseline"],
+      baselineScore: baselineMeasurement.score,
+      winnerScore: baselineMeasurement.score,
+      lift: 0,
+      criticalDimensions: []
+    };
+  } else {
+    await lease.assertOwned();
+    const [baselineCandidate, winnerCandidate] = await Promise.all([
+      buildCandidate(options, baselineConfig, baselineHash, "baseline"),
+      buildCandidate(options, winnerConfig, winnerHash, "winner")
+    ]);
+    await lease.assertOwned();
+    holdout = await runAgentMemoryExperiment({
+      ...experimentOptions(options, costLedger, storage, lease),
+      experimentId: `${options.experimentId}:holdout`,
+      sequences: options.holdoutSequences,
+      candidates: [baselineCandidate, winnerCandidate],
+      runDir: join3(runDir, "holdout"),
+      costPhase: "memory.holdout"
+    });
+    decision = decidePromotion({
+      options,
+      result: holdout,
+      baselineId: baselineCandidate.id,
+      winnerId: winnerCandidate.id
+    });
   }
-  const dimensions = options.criticalDimensions ?? DEFAULT_CRITICAL_DIMENSIONS;
-  if (dimensions.some((dimension) => typeof dimension !== "string" || !dimension.trim())) {
-    throw new Error("memory improvement criticalDimensions must contain non-empty names");
-  }
-  if (new Set(dimensions).size !== dimensions.length) {
-    throw new Error("memory improvement criticalDimensions must be unique");
-  }
-  assertDistinctSequenceContent(options.trainSequences, "train");
-  assertDistinctSequenceContent(options.holdoutSequences, "holdout");
-}
-function assertDistinctSequenceContent(sequences, split) {
-  const idsByFingerprint = /* @__PURE__ */ new Map();
-  for (const sequence of sequences) {
-    const fingerprint = memorySequenceFingerprint(sequence);
-    const prior = idsByFingerprint.get(fingerprint);
-    if (prior) {
+  const resultJsonPath = join3(runDir, "memory-improvement-result.json");
+  const activationRef = options.activation?.ref ?? "not-configured";
+  const activationId = `memory-activation-${surfaceHash2(
+    canonicalJson7({
+      experimentId: options.experimentId,
+      improvementRef: options.improvementRef,
+      activationRef,
+      baselineSurfaceHash: baselineHash,
+      winnerSurfaceHash: winnerHash,
+      holdoutManifestHash: holdout?.campaign.manifestHash ?? null,
+      promotionPolicy: normalizedPromotionPolicy(options)
+    })
+  )}`;
+  const activationJournalDir = join3(runDir, "activations");
+  const activationJournalPath = join3(activationJournalDir, `${activationId}.jsonl`);
+  const activationEligible = decision.status === "promote" && holdout !== void 0;
+  const activationEventIdentity = holdout ? {
+    schema: 1,
+    activationId,
+    experimentId: options.experimentId,
+    activationRef,
+    baselineSurfaceHash: baselineHash,
+    winnerSurfaceHash: winnerHash,
+    holdoutManifestHash: holdout.campaign.manifestHash
+  } : void 0;
+  const activationJournal = activationEligible && activationEventIdentity ? readMemoryActivationJournal(storage, activationJournalPath, activationEventIdentity) : { prepared: false };
+  const activation = {
+    id: activationId,
+    status: !activationEligible ? "not-eligible" : activationJournal.activated ? "already-activated" : options.activation ? "pending" : "not-configured",
+    journalPath: activationJournalPath
+  };
+  const result = {
+    lineage: search.lineage,
+    baselineConfig,
+    winnerConfig,
+    baselineSurface,
+    winnerSurface,
+    baselineSurfaceHash: baselineHash,
+    winnerSurfaceHash: winnerHash,
+    decision,
+    activation,
+    ...holdout ? { holdout } : {},
+    totalCostUsd: costLedger.summary().totalCostUsd,
+    resultJsonPath
+  };
+  await lease.assertOwned();
+  writeMemoryImprovementResult(storage, options.experimentId, result);
+  if (activationEligible && !activationJournal.activated && activationEventIdentity && holdout && options.activation) {
+    const activationDriver = options.activation;
+    const activationTimeoutMs = options.activationTimeoutMs ?? 6e4;
+    const hadPreparedEvent = activationJournal.prepared;
+    if (!hadPreparedEvent) {
+      await lease.assertOwned();
+      storage.ensureDir(activationJournalDir);
+      appendMemoryActivationEvent(storage, activationJournalPath, {
+        ...activationEventIdentity,
+        status: "prepared",
+        recordedAt: (options.now ?? (() => /* @__PURE__ */ new Date()))().toISOString()
+      });
+    }
+    await lease.assertOwned();
+    const currentConfig = await runBoundedMemoryLifecycle({
+      operation: `${activationDriver.ref}: read current memory configuration`,
+      timeoutMs: activationTimeoutMs,
+      run: () => activationDriver.readCurrent()
+    });
+    await lease.assertOwned();
+    const currentHash = surfaceHash2(serialize(currentConfig));
+    if (currentHash !== baselineHash && currentHash !== winnerHash) {
       throw new Error(
-        `memory improvement ${split} histories duplicate content: ${prior}/${sequence.id}`
+        `memory activation target '${activationDriver.ref}' changed concurrently; expected '${baselineHash}' or '${winnerHash}', found '${currentHash}'`
       );
     }
-    idsByFingerprint.set(fingerprint, sequence.id);
+    let outcome;
+    if (currentHash === winnerHash) {
+      outcome = hadPreparedEvent ? "recovered" : "already-current";
+      activation.status = "recovered";
+    } else {
+      let compareError;
+      try {
+        await runBoundedMemoryLifecycle({
+          operation: `${activationDriver.ref}: activate memory configuration`,
+          timeoutMs: activationTimeoutMs,
+          run: () => activationDriver.compareAndSet({
+            activationId,
+            expectedConfig: baselineConfig,
+            expectedSurfaceHash: baselineHash,
+            config: winnerConfig,
+            surfaceHash: winnerHash,
+            decision,
+            lineage: search.lineage,
+            holdout
+          })
+        });
+      } catch (error) {
+        compareError = error;
+      }
+      await lease.assertOwned();
+      let observedConfig;
+      try {
+        observedConfig = await runBoundedMemoryLifecycle({
+          operation: `${activationDriver.ref}: confirm memory configuration`,
+          timeoutMs: activationTimeoutMs,
+          run: () => activationDriver.readCurrent()
+        });
+      } catch (error) {
+        if (compareError) {
+          throw new AggregateError(
+            [compareError, error],
+            `memory activation '${activationId}' failed and its live state could not be confirmed`
+          );
+        }
+        throw error;
+      }
+      await lease.assertOwned();
+      const observedHash = surfaceHash2(serialize(observedConfig));
+      if (observedHash !== winnerHash) {
+        const mismatch = new Error(
+          `memory activation '${activationId}' did not install the measured winner; found '${observedHash}'`
+        );
+        if (compareError) {
+          throw new AggregateError(
+            [compareError, mismatch],
+            `memory activation '${activationId}' failed without applying the measured winner`
+          );
+        }
+        throw mismatch;
+      }
+      outcome = compareError ? "recovered" : "applied";
+      activation.status = compareError ? "recovered" : "activated";
+    }
+    await lease.assertOwned();
+    appendMemoryActivationEvent(storage, activationJournalPath, {
+      ...activationEventIdentity,
+      status: "activated",
+      outcome,
+      recordedAt: (options.now ?? (() => /* @__PURE__ */ new Date()))().toISOString()
+    });
+    writeMemoryImprovementResult(storage, options.experimentId, result);
   }
-}
-function mean2(values) {
-  return values.length === 0 ? 0 : values.reduce((sum, value) => sum + value, 0) / values.length;
+  return result;
 }
 
 // src/memory/mem0.ts
 import { randomUUID as randomUUID4 } from "crypto";
-import { canonicalJson as canonicalJson6 } from "@tangle-network/agent-eval";
+import { canonicalJson as canonicalJson8 } from "@tangle-network/agent-eval";
 function createMem0MemoryAdapter(options) {
   assertMem0Options(options);
   const id = options.id ?? `mem0-${options.mode}`;
@@ -3894,7 +3938,7 @@ function normalizeMem0Hits(raw, adapterId, options) {
     if (options.minScore !== void 0 && (score === void 0 || score < options.minScore)) {
       return void 0;
     }
-    const memoryId = stringField2(item, ["id"]) ?? stableId("mem", canonicalJson6(compactRecord2({ adapterId, text, metadata, item })));
+    const memoryId = stringField2(item, ["id"]) ?? stableId("mem", canonicalJson8(compactRecord2({ adapterId, text, metadata, item })));
     const normalizedScore = score !== void 0 && score >= 0 && score <= 1 ? score : void 0;
     return {
       id: memoryId,
@@ -4093,11 +4137,11 @@ function mem0MemoryAdapterIdentity(options) {
   if (typeof options.backendRef !== "string" || !options.backendRef.trim()) {
     throw new Error("Mem0 backendRef must be a non-empty string");
   }
-  return stableId("mem0", canonicalJson6(compactRecord2(options)));
+  return stableId("mem0", canonicalJson8(compactRecord2(options)));
 }
 
 // src/memory/neo4j.ts
-import { canonicalJson as canonicalJson7 } from "@tangle-network/agent-eval";
+import { canonicalJson as canonicalJson9 } from "@tangle-network/agent-eval";
 function createNeo4jAgentMemoryAdapter(options) {
   assertNeo4jOptions(options);
   const client = options.client;
@@ -4362,7 +4406,7 @@ async function writeNeo4jMemory(client, input, adapterId, transport, isolatedIns
   assertNeo4jWriteSucceeded(result, adapterId, input.kind);
   const id = idFromResult(result) ?? input.id ?? stableId(
     "mem",
-    canonicalJson7({ adapterId, kind: input.kind, text: input.text, scope: input.scope ?? {} })
+    canonicalJson9({ adapterId, kind: input.kind, text: input.text, scope: input.scope ?? {} })
   );
   return {
     accepted: true,
@@ -4723,9 +4767,9 @@ export {
   createAgentMemoryBranch,
   forkAgentMemoryBranchSnapshot,
   buildAgentMemorySequencesFromBenchmarkCases,
-  runAgentMemoryExperiment,
   buildAgentMemorySequenceScenarios,
   agentMemorySequenceJudge,
+  runAgentMemoryExperiment,
   createGraphitiMemoryAdapter,
   graphitiMemoryAdapterIdentity,
   runAgentMemoryImprovement,
@@ -4737,4 +4781,4 @@ export {
   AgentMemoryHitSchema,
   AgentMemoryWriteInputSchema
 };
-//# sourceMappingURL=chunk-UWOTQNBI.js.map
+//# sourceMappingURL=chunk-3CAAGJCE.js.map