@tangle-network/agent-knowledge 3.2.1 → 4.0.0

package/dist/chunk-UWOTQNBI.js

@@ -0,0 +1,4740 @@
+import {
+  DEFAULT_MEMORY_RECOVERY_RETRIES_PER_ATTEMPT,
+  acquireAgentMemoryRunLease,
+  appendAttemptJournalEvent,
+  appendDurableJournalEvent,
+  assertNoInterruptedPaidCalls,
+  createMemoryExecutionPool,
+  hasSettledPaidCall,
+  memoryHitToSourceRecord,
+  memoryRecoveryDelayMs,
+  memoryWriteResultToSourceRecord,
+  readActiveAttemptJournal,
+  reconcileInterruptedMemoryPaidCalls,
+  reconcileInterruptedRunPaidCalls,
+  releaseMemoryAdapterCreatedAfterAbort,
+  reserveRecoveryAttempts,
+  resolveMemoryCleanupTimeoutMs,
+  runBoundedMemoryLifecycle,
+  scoreMemoryBenchmarkArtifact,
+  sleepForMemoryRecovery
+} from "./chunk-DW6APRTX.js";
+import {
+  sha256,
+  stableId
+} from "./chunk-YMKHCTS2.js";
+
+// src/memory/holdout.ts
+import { randomUUID } from "crypto";
+import { mulberry32 } from "@tangle-network/agent-eval";
+function deterministicRng(key) {
+  return mulberry32(Number.parseInt(sha256(key).slice(0, 8), 16))();
+}
+function canonicalJson(value) {
+  if (typeof value === "bigint") {
+    throw new TypeError("canonicalJson: bigint values are not supported in holdout hashing");
+  }
+  if (value === void 0) return "null";
+  if (Array.isArray(value)) return `[${value.map(canonicalJson).join(",")}]`;
+  if (value !== null && typeof value === "object") {
+    const entries = Object.entries(value).filter(([, v]) => v !== void 0).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0).map(([k, v]) => `${JSON.stringify(k)}:${canonicalJson(v)}`);
+    return `{${entries.join(",")}}`;
+  }
+  return JSON.stringify(value);
+}
+function retrievalHoldoutConfigHash(config) {
+  return sha256(
+    canonicalJson({ epsilon: config.epsilon, watchlist: [...config.watchlist ?? []].sort() })
+  ).slice(0, 16);
+}
+function assertValidHoldoutConfig(config) {
+  const { epsilon, watchlist } = config;
+  if (typeof epsilon !== "number" || !Number.isFinite(epsilon) || epsilon < 0 || epsilon > 1) {
+    throw new Error(`retrieval holdout epsilon must be a number in [0, 1], got ${String(epsilon)}`);
+  }
+  if (watchlist !== void 0 && (!Array.isArray(watchlist) || watchlist.some((id) => typeof id !== "string"))) {
+    throw new Error("retrieval holdout watchlist must be an array of item-id strings");
+  }
+}
+function safeEmit(config, event) {
+  try {
+    config.onEvent(event);
+  } catch (error) {
+    console.error(
+      "[agent-knowledge] retrieval holdout onEvent sink threw; retrieval continues",
+      error
+    );
+  }
+}
+function applyRetrievalHoldout(hits, config, ctx = {}) {
+  assertValidHoldoutConfig(config);
+  const rng = config.rng ?? deterministicRng;
+  const sessionId = ctx.sessionId ?? ctx.scope?.sessionId;
+  const holdoutEligible = typeof sessionId === "string" && sessionId.length > 0;
+  const base = holdoutEventBase(hits, config, ctx);
+  let session;
+  if (holdoutEligible) {
+    const prior = ctx.session?.sessionId === sessionId ? ctx.session : void 0;
+    session = prior ?? {
+      sessionId,
+      callCount: 0,
+      // The epsilon coin depends only on sessionId, so assignment is independent of task
+      // features by construction and exactly replayable (design rules D1 + D5).
+      sessionHoldout: rng(`${sessionId}#holdout`) < config.epsilon,
+      targetId: null,
+      pickPropensity: null
+    };
+    session = { ...session, callCount: session.callCount + 1 };
+  }
+  const watchlistEligible = base.watchlistEligible;
+  if (session?.sessionHoldout && session.targetId === null && watchlistEligible.length > 0) {
+    const candidates = [...watchlistEligible].sort();
+    const index = Math.min(
+      Math.floor(rng(`${session.sessionId}#pick`) * candidates.length),
+      candidates.length - 1
+    );
+    const picked = candidates[index];
+    if (picked !== void 0) {
+      session = { ...session, targetId: picked, pickPropensity: 1 / candidates.length };
+    }
+  }
+  const targetId = session?.sessionHoldout ? session.targetId ?? null : null;
+  const droppedId = targetId !== null && hits.some((hit) => hit.id === targetId) ? targetId : null;
+  const delivered = droppedId === null ? hits : hits.filter((hit) => hit.id !== droppedId);
+  const pickPropensity = session?.sessionHoldout ? session.pickPropensity ?? null : null;
+  const event = {
+    ...base,
+    callIndex: session?.callCount ?? 0,
+    holdoutEligible,
+    sessionHoldout: session?.sessionHoldout ?? false,
+    sessionTargetId: targetId,
+    droppedId,
+    pickPropensity,
+    dropPropensity: pickPropensity !== null ? config.epsilon * pickPropensity : null,
+    deliveredIds: delivered.map((hit) => hit.id)
+  };
+  safeEmit(config, event);
+  return droppedId === null ? { delivered: hits, event, ...session !== void 0 ? { session } : {} } : { delivered, event, ...session !== void 0 ? { session } : {} };
+}
+function holdoutEventBase(hits, config, ctx) {
+  const sessionId = ctx.sessionId ?? ctx.scope?.sessionId;
+  const watchlist = config.watchlist ?? [];
+  const watchlistSet = new Set(watchlist);
+  const plaintext = config.includePlaintextIdentifiers === true;
+  return {
+    v: 1,
+    eventId: randomUUID(),
+    ts: (/* @__PURE__ */ new Date()).toISOString(),
+    ...config.adapterId !== void 0 ? { adapterId: config.adapterId } : {},
+    ...plaintext && sessionId !== void 0 ? { sessionId } : {},
+    ...ctx.taskId !== void 0 ? { taskId: ctx.taskId } : {},
+    ...sessionId !== void 0 ? { sessionIdHash: sha256(sessionId).slice(0, 16) } : {},
+    ...ctx.query !== void 0 ? { queryHash: sha256(ctx.query).slice(0, 16) } : {},
+    ...plaintext && ctx.scope !== void 0 ? { scope: ctx.scope } : {},
+    ...ctx.scope !== void 0 ? { scopeHash: sha256(canonicalJson(ctx.scope)).slice(0, 16) } : {},
+    config: {
+      epsilon: config.epsilon,
+      watchlist: [...watchlist],
+      ...config.configVersion !== void 0 ? { configVersion: config.configVersion } : {}
+    },
+    configHash: retrievalHoldoutConfigHash(config),
+    eligible: hits.map((hit, index) => ({
+      id: hit.id,
+      rank: index + 1,
+      ...typeof (hit.normalizedScore ?? hit.score) === "number" ? { score: hit.normalizedScore ?? hit.score } : {},
+      kind: hit.kind,
+      contentHash: sha256(hit.text).slice(0, 16)
+    })),
+    watchlistEligible: hits.filter((hit) => watchlistSet.has(hit.id)).map((hit) => hit.id),
+    ...config.corpusVersion !== void 0 ? { corpusVersion: config.corpusVersion } : {}
+  };
+}
+function emitRetrievalHoldoutBypass(hits, config, ctx, bypassReason) {
+  assertValidHoldoutConfig(config);
+  const event = {
+    ...holdoutEventBase(hits, config, ctx),
+    callIndex: 0,
+    holdoutEligible: false,
+    sessionHoldout: false,
+    sessionTargetId: null,
+    droppedId: null,
+    pickPropensity: null,
+    dropPropensity: null,
+    deliveredIds: hits.map((hit) => hit.id),
+    bypassReason
+  };
+  safeEmit(config, event);
+  return event;
+}
+var DEFAULT_MAX_TRACKED_SESSIONS = 1e4;
+var sessionRegistry = /* @__PURE__ */ new Map();
+function resetRetrievalHoldoutRegistry() {
+  sessionRegistry.clear();
+}
+function applySessionStickyRetrievalHoldout(hits, config, ctx = {}) {
+  assertValidHoldoutConfig(config);
+  const sessionId = ctx.sessionId ?? ctx.scope?.sessionId;
+  const configHash = retrievalHoldoutConfigHash(config);
+  let sessions = sessionRegistry.get(configHash);
+  if (!sessions) {
+    sessions = /* @__PURE__ */ new Map();
+    sessionRegistry.set(configHash, sessions);
+  }
+  const prior = sessionId !== void 0 ? sessions.get(sessionId) : void 0;
+  const result = applyRetrievalHoldout(hits, config, {
+    ...ctx,
+    ...prior ? { session: prior } : {}
+  });
+  if (sessionId !== void 0 && result.session) {
+    const cap = config.maxTrackedSessions ?? DEFAULT_MAX_TRACKED_SESSIONS;
+    if (!sessions.has(sessionId) && sessions.size >= cap) {
+      const oldest = sessions.keys().next().value;
+      if (oldest !== void 0) sessions.delete(oldest);
+    }
+    sessions.set(sessionId, result.session);
+  }
+  return result;
+}
+function toOffPolicyTrajectory(events, options) {
+  const groups = /* @__PURE__ */ new Map();
+  let unattributableEvents = 0;
+  for (const event of events) {
+    if (event.sessionIdHash === void 0) {
+      unattributableEvents += 1;
+      continue;
+    }
+    const key = `${event.configHash}:${event.sessionIdHash}`;
+    const group = groups.get(key);
+    if (group) group.push(event);
+    else groups.set(key, [event]);
+  }
+  const trajectories = [];
+  const sessions = [];
+  const excluded = [];
+  for (const [runId, group] of groups) {
+    const ordered = [...group].sort((a, b) => a.callIndex - b.callIndex || a.ts.localeCompare(b.ts));
+    const randomized = ordered.filter((event) => event.holdoutEligible);
+    const firstEvent = ordered[0];
+    if (firstEvent?.sessionIdHash === void 0) continue;
+    const base = {
+      runId,
+      configHash: firstEvent.configHash,
+      sessionIdHash: firstEvent.sessionIdHash,
+      callCount: randomized.length,
+      bypassCallCount: ordered.length - randomized.length
+    };
+    const first = randomized[0];
+    if (first === void 0) {
+      excluded.push({
+        ...base,
+        sessionHoldout: false,
+        sessionTargetId: null,
+        droppedId: null,
+        firstCandidateCount: 0,
+        behaviorProb: 1,
+        mixedExposure: false,
+        exclusionReason: "no-randomized-calls"
+      });
+      continue;
+    }
+    const targets = new Set(
+      randomized.map((event) => event.sessionTargetId).filter((target) => target !== null)
+    );
+    const arms = new Set(randomized.map((event) => event.sessionHoldout));
+    const mixedExposure = targets.size > 1 || arms.size > 1;
+    const dropEvent = randomized.find((event) => event.droppedId !== null);
+    const firstIntersecting = randomized.find((event) => event.watchlistEligible.length > 0);
+    const sessionTargetId = dropEvent?.sessionTargetId ?? [...targets][0] ?? null;
+    let behaviorProb;
+    if (dropEvent !== void 0) {
+      if (dropEvent.dropPropensity === null) {
+        throw new Error(`holdout event ${dropEvent.eventId} recorded a drop without dropPropensity`);
+      }
+      behaviorProb = dropEvent.dropPropensity;
+    } else if (!mixedExposure && sessionTargetId !== null) {
+      throw new Error(
+        `holdout session ${base.sessionIdHash} has a drawn target but no drop event: the event batch is missing this session draw call`
+      );
+    } else if (firstIntersecting === void 0) {
+      behaviorProb = 1;
+    } else {
+      behaviorProb = 1 - first.config.epsilon;
+    }
+    const summary = {
+      ...base,
+      sessionHoldout: first.sessionHoldout,
+      sessionTargetId,
+      droppedId: dropEvent?.droppedId ?? null,
+      firstCandidateCount: firstIntersecting ? new Set(firstIntersecting.watchlistEligible).size : 0,
+      behaviorProb,
+      mixedExposure,
+      ...mixedExposure ? { exclusionReason: "mixed-exposure" } : {}
+    };
+    if (mixedExposure) {
+      excluded.push(summary);
+      continue;
+    }
+    const reward = options.rewards[summary.sessionIdHash];
+    if (reward === void 0) {
+      throw new Error(
+        `no reward for session ${summary.sessionIdHash}: filter events to scored sessions before converting`
+      );
+    }
+    trajectories.push({
+      runId,
+      reward,
+      behaviorProb,
+      targetProb: options.targetProb?.(summary) ?? (summary.droppedId === null ? 1 : 0),
+      qHat: options.qHat?.(summary) ?? null
+    });
+    sessions.push(summary);
+  }
+  return { trajectories, sessions, excluded, unattributableEvents };
+}
+
+// src/memory/adapter.ts
+async function defaultGetMemoryContext(adapter, query, options = {}) {
+  const hits = await adapter.search(query, options);
+  const delivered = options.holdout ? applySessionStickyRetrievalHoldout(hits, options.holdout, {
+    query,
+    ...options.scope !== void 0 ? { scope: options.scope } : {},
+    ...options.scope?.tags?.taskId !== void 0 ? { taskId: options.scope.tags.taskId } : {}
+  }).delivered : hits;
+  return {
+    query,
+    hits: delivered,
+    sourceRecords: delivered.map((hit) => memoryHitToSourceRecord(hit, { scope: options.scope })),
+    text: renderMemoryContext(delivered)
+  };
+}
+function renderMemoryContext(hits) {
+  return hits.map((hit, index) => {
+    const label = hit.title ?? `${hit.kind}:${hit.id}`;
+    const score = typeof hit.normalizedScore === "number" ? ` score=${hit.normalizedScore.toFixed(3)}` : "";
+    return [`[${index + 1}] ${label}${score}`, hit.text].join("\n");
+  }).join("\n\n");
+}
+
+// src/memory/branch.ts
+import { canonicalJson as canonicalJson2 } from "@tangle-network/agent-eval";
+
+// src/memory/rank.ts
+function mergeRankedMemoryHits(groups, limit) {
+  const byIdentity = /* @__PURE__ */ new Map();
+  let encounter = 0;
+  for (const [groupIndex, group] of groups.entries()) {
+    for (const [rank, hit] of group.entries()) {
+      const key = JSON.stringify([hit.uri, hit.text]);
+      const score = memoryHitScore(hit);
+      const prior = byIdentity.get(key);
+      if (!prior) {
+        byIdentity.set(key, {
+          hit,
+          score,
+          reciprocalRank: 1 / (60 + rank + 1),
+          bestRank: rank,
+          firstGroup: groupIndex,
+          encounter
+        });
+      } else {
+        prior.reciprocalRank += 1 / (60 + rank + 1);
+        prior.bestRank = Math.min(prior.bestRank, rank);
+        if (score !== void 0 && (prior.score === void 0 || score > prior.score)) {
+          prior.hit = hit;
+          prior.score = score;
+        }
+      }
+      encounter += 1;
+    }
+  }
+  return [...byIdentity.values()].sort(
+    (left, right) => right.reciprocalRank - left.reciprocalRank || Number(right.score !== void 0) - Number(left.score !== void 0) || (right.score ?? 0) - (left.score ?? 0) || left.bestRank - right.bestRank || left.firstGroup - right.firstGroup || left.encounter - right.encounter
+  ).map(({ hit }) => hit).slice(0, limit ?? Number.POSITIVE_INFINITY);
+}
+function memoryHitScore(hit) {
+  const score = hit.normalizedScore ?? hit.score;
+  return score !== void 0 && Number.isFinite(score) ? score : void 0;
+}
+
+// src/memory/branch.ts
+var DEFAULT_POLICY = {
+  read: ["private"],
+  write: "private"
+};
+var adapterLeases = /* @__PURE__ */ new WeakMap();
+function createAgentMemoryBranch(options) {
+  if (typeof options.branchId !== "string" || !options.branchId.trim()) {
+    throw new Error("memory branchId must be a non-empty string");
+  }
+  const snapshot = options.snapshot;
+  if (snapshot && snapshot.branchId !== options.branchId) {
+    throw new Error(
+      `memory branch snapshot belongs to ${snapshot.branchId}, not ${options.branchId}`
+    );
+  }
+  if (snapshot && snapshot.adapterId !== options.adapter.id) {
+    throw new Error(
+      `memory branch snapshot uses ${snapshot.adapterId}, not ${options.adapter.id}; fork it to replay into another adapter`
+    );
+  }
+  if (snapshot?.lifetime === "attempt") {
+    throw new Error(
+      "memory branch attempt snapshots cannot be resumed; replay them into a fresh branch instead"
+    );
+  }
+  if (options.lifetime !== void 0 && !["resumable", "attempt"].includes(options.lifetime)) {
+    throw new Error("memory branch lifetime must be resumable or attempt");
+  }
+  if (snapshot) {
+    assertDurableValue(snapshot, `${options.branchId}: branch snapshot`);
+    assertSnapshotDigest(snapshot);
+  }
+  if (snapshot && options.policy && canonicalJson2(stripUndefined(options.policy)) !== canonicalJson2(stripUndefined(snapshot.policy))) {
+    throw new Error("memory branch snapshot policy cannot change during resume; fork it instead");
+  }
+  if (snapshot && options.baseScope && canonicalJson2(stripUndefined(options.baseScope)) !== canonicalJson2(stripUndefined(snapshot.baseScope))) {
+    throw new Error("memory branch snapshot scope cannot change during resume; fork it instead");
+  }
+  if (snapshot && options.lifetime && options.lifetime !== snapshot.lifetime) {
+    throw new Error("memory branch snapshot lifetime cannot change during resume; fork it instead");
+  }
+  const branchId = options.branchId;
+  const parentBranchId = options.parentBranchId ?? snapshot?.parentBranchId;
+  const lifetime = options.lifetime ?? snapshot?.lifetime ?? "resumable";
+  const policy = normalizePolicy(options.policy ?? snapshot?.policy ?? DEFAULT_POLICY);
+  assertBranchIsolation(options.adapter, branchId, policy, lifetime);
+  const mergedBaseScope = mergeScopes(void 0, snapshot?.baseScope ?? options.baseScope);
+  assertDurableValue(mergedBaseScope, `${branchId}: base scope`);
+  const baseScope = cloneDurableValue(mergedBaseScope);
+  const allowedWriteScopeKeys = options.allowedWriteScopes ? new Set(
+    options.allowedWriteScopes.map(
+      (scope) => canonicalJson2(stripUndefined(mergeScopes(baseScope, scope)))
+    )
+  ) : void 0;
+  const journal = [...snapshot?.journal ?? []].map(cloneJournalEntry);
+  let nextSequence = journal.reduce((max, entry) => Math.max(max, entry.sequence + 1), 0);
+  const queues = /* @__PURE__ */ new Map();
+  const pending = /* @__PURE__ */ new Set();
+  const reads = /* @__PURE__ */ new Set();
+  const active = /* @__PURE__ */ new Set();
+  const touchedScopes = /* @__PURE__ */ new Map();
+  for (const entry of journal) {
+    const scope = mergeScopes(baseScope, entry.input.scope);
+    touchedScopes.set(canonicalJson2(stripUndefined(scope)), scope);
+  }
+  let mutationBarrier = Promise.resolve();
+  const releaseAdapter = retainAdapter(options.adapter, branchId);
+  let lifecycle = "open";
+  let closePromise;
+  const assertOpen = (operation) => {
+    if (lifecycle !== "open") throw new Error(`${branchId}: cannot ${operation} a closed branch`);
+  };
+  const track = (operation) => {
+    active.add(operation);
+    void operation.then(
+      () => active.delete(operation),
+      () => active.delete(operation)
+    );
+    return operation;
+  };
+  const trackRead = (operation) => {
+    reads.add(operation);
+    void operation.then(
+      () => reads.delete(operation),
+      () => reads.delete(operation)
+    );
+    return track(operation);
+  };
+  const flushWrites = async () => {
+    const results = await Promise.allSettled([...pending]);
+    const failures = results.flatMap(
+      (result) => result.status === "rejected" ? [result.reason] : []
+    );
+    if (failures.length === 1) throw failures[0];
+    if (failures.length > 1) {
+      throw new AggregateError(failures, `${branchId}: pending memory writes failed`);
+    }
+  };
+  const flushAll = async () => {
+    await flushWrites();
+    await options.adapter.flush?.();
+  };
+  const runExclusive = async (operation, exclusiveOptions = {}) => {
+    const precedingBarrier = mutationBarrier;
+    const precedingWrites = [...pending];
+    const precedingReads = [...reads];
+    let releaseBarrier;
+    const ownBarrier = new Promise((resolve) => {
+      releaseBarrier = resolve;
+    });
+    mutationBarrier = precedingBarrier.then(() => ownBarrier);
+    await precedingBarrier;
+    const settled = await Promise.allSettled([...precedingWrites, ...precedingReads]);
+    const failures = settled.flatMap(
+      (result) => result.status === "rejected" ? [result.reason] : []
+    );
+    try {
+      if ((exclusiveOptions.failOnOperationError ?? true) && failures.length > 0) {
+        if (failures.length === 1) throw failures[0];
+        throw new AggregateError(failures, `${branchId}: pending memory operations failed`);
+      }
+      if (exclusiveOptions.flushAdapter ?? true) await options.adapter.flush?.();
+      return await operation();
+    } finally {
+      releaseBarrier();
+    }
+  };
+  const branch = {
+    id: `${options.adapter.id}:branch:${stableId("branch", branchId)}`,
+    branchId,
+    lifetime,
+    ...parentBranchId !== void 0 ? { parentBranchId } : {},
+    policy,
+    async search(query, searchOptions = {}) {
+      assertOpen("search");
+      const precedingBarrier = mutationBarrier;
+      return trackRead(
+        (async () => {
+          await precedingBarrier;
+          const logicalScope = mergeScopes(baseScope, searchOptions.scope);
+          const scopes = policy.read.map(
+            (visibility) => physicalScope(branchId, logicalScope, visibility)
+          );
+          const groups = await Promise.all(
+            scopes.map(async (scope) => {
+              const hits = await options.adapter.search(query, {
+                ...searchOptions,
+                scope,
+                holdout: void 0
+              });
+              return hits.map((hit) => ({
+                ...hit,
+                metadata: {
+                  ...hit.metadata,
+                  memoryBranchId: branchId,
+                  memoryVisibility: scope.tags?.memoryVisibility
+                }
+              }));
+            })
+          );
+          return mergeRankedMemoryHits(groups, searchOptions.limit);
+        })()
+      );
+    },
+    async getContext(query, searchOptions = {}) {
+      assertOpen("read context from");
+      return track(defaultGetMemoryContext(branch, query, searchOptions));
+    },
+    async write(input) {
+      assertOpen("write to");
+      const sequence = nextSequence;
+      nextSequence += 1;
+      assertDurableValue(input, `${branch.id}: write input`);
+      const logicalInput = cloneWriteInput(input);
+      logicalInput.id ??= stableId("memory_write", `${branchId}:${sequence}`);
+      const logicalScope = mergeScopes(baseScope, logicalInput.scope);
+      if (allowedWriteScopeKeys && !allowedWriteScopeKeys.has(canonicalJson2(stripUndefined(logicalScope)))) {
+        throw new Error(
+          `${branch.id}: write scope was not declared in the experiment sequence cleanupScopes`
+        );
+      }
+      const scope = physicalScope(branchId, logicalScope, policy.write);
+      const queueKey = writeQueueKey(branchId, logicalScope, policy.write);
+      touchedScopes.set(canonicalJson2(stripUndefined(logicalScope)), logicalScope);
+      const previous = queues.get(queueKey) ?? Promise.resolve();
+      const precedingBarrier = mutationBarrier;
+      let resultPromise;
+      const queued = Promise.all([previous.catch(() => void 0), precedingBarrier]).then(
+        async () => {
+          const result = await options.adapter.write({ ...logicalInput, scope });
+          if (result.accepted) {
+            assertDurableValue(result, `${branch.id}: write result`);
+            journal.push({
+              sequence,
+              input: logicalInput,
+              result: cloneWriteResult(result)
+            });
+          }
+          return result;
+        }
+      );
+      resultPromise = queued;
+      const tail = queued.then(
+        () => void 0,
+        () => void 0
+      );
+      queues.set(queueKey, tail);
+      pending.add(resultPromise);
+      void resultPromise.then(
+        () => {
+          pending.delete(resultPromise);
+          if (queues.get(queueKey) === tail) queues.delete(queueKey);
+        },
+        () => {
+          pending.delete(resultPromise);
+          if (queues.get(queueKey) === tail) queues.delete(queueKey);
+        }
+      );
+      return track(resultPromise);
+    },
+    async clear(scope) {
+      assertOpen("clear");
+      return track(
+        runExclusive(
+          async () => {
+            if (!options.adapter.clear) {
+              throw new Error(`${options.adapter.id}: adapter does not support scoped clear`);
+            }
+            const flushErrors = [];
+            try {
+              await options.adapter.flush?.();
+            } catch (error) {
+              flushErrors.push(error);
+            }
+            const requestedScope = scope ? mergeScopes(baseScope, scope) : void 0;
+            const logicalScopes = /* @__PURE__ */ new Map();
+            if (requestedScope) {
+              logicalScopes.set(canonicalJson2(stripUndefined(requestedScope)), requestedScope);
+              for (const touched of touchedScopes.values()) {
+                if (scopeMatches(touched, requestedScope)) {
+                  logicalScopes.set(canonicalJson2(stripUndefined(touched)), touched);
+                }
+              }
+            } else if (touchedScopes.size > 0) {
+              for (const [key, touched] of touchedScopes) logicalScopes.set(key, touched);
+            } else {
+              logicalScopes.set(canonicalJson2(stripUndefined(baseScope)), baseScope);
+            }
+            const visibilities = /* @__PURE__ */ new Set([...policy.read, policy.write]);
+            const physicalScopes = /* @__PURE__ */ new Map();
+            for (const logicalScope of logicalScopes.values()) {
+              for (const visibility of visibilities) {
+                const physical = physicalScope(branchId, logicalScope, visibility);
+                physicalScopes.set(canonicalJson2(stripUndefined(physical)), physical);
+              }
+            }
+            const clearErrors = [];
+            const clearedPhysicalScopes = /* @__PURE__ */ new Set();
+            for (const [key, physical] of physicalScopes) {
+              try {
+                await options.adapter.clear(physical);
+                clearedPhysicalScopes.add(key);
+              } catch (error) {
+                clearErrors.push(error);
+              }
+            }
+            if (clearedPhysicalScopes.size > 0) {
+              for (let index = journal.length - 1; index >= 0; index -= 1) {
+                const logical = mergeScopes(baseScope, journal[index].input.scope);
+                const physical = physicalScope(branchId, logical, policy.write);
+                if (clearedPhysicalScopes.has(canonicalJson2(stripUndefined(physical)))) {
+                  journal.splice(index, 1);
+                }
+              }
+              for (const [key, touched] of touchedScopes) {
+                const physical = physicalScope(branchId, touched, policy.write);
+                if (clearedPhysicalScopes.has(canonicalJson2(stripUndefined(physical)))) {
+                  touchedScopes.delete(key);
+                }
+              }
+            }
+            const failures = [...flushErrors, ...clearErrors];
+            if (failures.length === 1) throw failures[0];
+            if (failures.length > 1) {
+              throw new AggregateError(failures, `${branchId}: memory clear failed`);
+            }
+          },
+          { failOnOperationError: false, flushAdapter: false }
+        )
+      );
+    },
+    async flush() {
+      assertOpen("flush");
+      return track(runExclusive(async () => void 0));
+    },
+    close() {
+      if (closePromise) return closePromise;
+      lifecycle = "closing";
+      closePromise = (async () => {
+        const errors = [];
+        const operations = await Promise.allSettled([...active]);
+        for (const result of operations) {
+          if (result.status === "rejected") errors.push(result.reason);
+        }
+        try {
+          await flushAll();
+        } catch (error) {
+          errors.push(error);
+        }
+        try {
+          await releaseAdapter();
+        } catch (error) {
+          errors.push(error);
+        }
+        lifecycle = "closed";
+        if (errors.length === 1) throw errors[0];
+        if (errors.length > 1) throw new AggregateError(errors, `${branch.id}: close failed`);
+      })();
+      return closePromise;
+    },
+    async snapshot() {
+      assertOpen("snapshot");
+      return track(
+        runExclusive(async () => {
+          return createSnapshot({
+            branchId,
+            lifetime,
+            adapterId: options.adapter.id,
+            policy,
+            baseScope,
+            journal,
+            ...parentBranchId !== void 0 ? { parentBranchId } : {}
+          });
+        })
+      );
+    },
+    async fork(forkOptions) {
+      assertOpen("fork");
+      if (forkOptions.branchId === branchId) {
+        throw new Error(`memory branch ${branchId}: child branchId must differ from its parent`);
+      }
+      return track(
+        (async () => forkAgentMemoryBranchSnapshot({
+          snapshot: await branch.snapshot(),
+          adapter: forkOptions.adapter ?? options.adapter,
+          branchId: forkOptions.branchId,
+          policy: forkOptions.policy,
+          baseScope: forkOptions.baseScope,
+          lifetime: forkOptions.lifetime
+        }))()
+      );
+    }
+  };
+  return branch;
+}
+async function forkAgentMemoryBranchSnapshot(options) {
+  assertDurableValue(options.snapshot, `${options.snapshot.branchId}: branch snapshot`);
+  assertSnapshotDigest(options.snapshot);
+  if (options.branchId === options.snapshot.branchId) {
+    throw new Error(`memory branch ${options.branchId}: child branchId must differ from its parent`);
+  }
+  const child = createAgentMemoryBranch({
+    adapter: options.adapter,
+    branchId: options.branchId,
+    parentBranchId: options.snapshot.branchId,
+    policy: options.policy ?? options.snapshot.policy,
+    baseScope: mergeScopes(options.snapshot.baseScope, options.baseScope),
+    lifetime: options.lifetime ?? options.snapshot.lifetime
+  });
+  try {
+    for (const entry of options.snapshot.journal) {
+      const result = await child.write(entry.input);
+      if (!result.accepted) {
+        throw new Error(
+          `memory branch ${options.branchId}: adapter rejected replay of journal entry ${entry.sequence}`
+        );
+      }
+    }
+    await child.flush?.();
+    return child;
+  } catch (error) {
+    const cleanupErrors = [];
+    try {
+      await child.clear?.();
+    } catch (cleanupError) {
+      cleanupErrors.push(cleanupError);
+    }
+    try {
+      await child.close?.();
+    } catch (cleanupError) {
+      cleanupErrors.push(cleanupError);
+    }
+    if (cleanupErrors.length > 0) {
+      throw new AggregateError(
+        [error, ...cleanupErrors],
+        `memory branch ${options.branchId}: replay and cleanup failed`
+      );
+    }
+    throw error;
+  }
+}
+function assertBranchIsolation(adapter, branchId, policy, lifetime) {
+  const isolation = adapter.branchIsolation;
+  if (!isolation) {
+    throw new Error(
+      `${adapter.id}: cannot isolate memory branch '${branchId}': adapter must declare branchIsolation`
+    );
+  }
+  if (isolation.mode === "unsupported") {
+    throw new Error(
+      `${adapter.id}: cannot isolate memory branch '${branchId}': ${isolation.reason}`
+    );
+  }
+  if (isolation.mode === "scoped" && isolation.processExitSafe === false && lifetime !== "attempt") {
+    throw new Error(
+      `${adapter.id}: memory branch '${branchId}' must use lifetime='attempt' because provider writes can outlive the worker process`
+    );
+  }
+  if (isolation.mode === "scoped" && isolation.processExitSafe === false && (!Number.isSafeInteger(isolation.recoveryDelayMs) || isolation.recoveryDelayMs <= 0)) {
+    throw new Error(`${adapter.id}: processExitSafe=false requires a positive recoveryDelayMs`);
+  }
+  if (isolation.mode === "instance" && isolation.branchId !== branchId) {
+    throw new Error(
+      `${adapter.id}: adapter instance belongs to branch '${isolation.branchId}', not '${branchId}'`
+    );
+  }
+  if (isolation.mode === "instance" && isolation.supportsLogicalScopes !== true && (policy.write !== "shared" || policy.read.length !== 1 || policy.read[0] !== "shared")) {
+    throw new Error(
+      `${adapter.id}: dedicated branch instances without logical scope isolation support only shared memory policy`
+    );
+  }
+}
+function retainAdapter(adapter, branchId) {
+  const existing = adapterLeases.get(adapter);
+  if (existing?.closed) throw new Error(`${adapter.id}: adapter is already closed`);
+  const state = existing ?? { references: 0, closed: false, activeBranchIds: /* @__PURE__ */ new Set() };
+  if (state.activeBranchIds.has(branchId)) {
+    throw new Error(`${adapter.id}: memory branch '${branchId}' already has an open handle`);
+  }
+  state.activeBranchIds.add(branchId);
+  state.references += 1;
+  adapterLeases.set(adapter, state);
+  let released = false;
+  return async () => {
+    if (released) return;
+    released = true;
+    state.activeBranchIds.delete(branchId);
+    state.references -= 1;
+    if (state.references > 0) return;
+    if (!adapter.close) {
+      adapterLeases.delete(adapter);
+      return;
+    }
+    state.closed = true;
+    state.closePromise ??= adapter.close();
+    await state.closePromise;
+  };
+}
+function physicalScope(branchId, logical, visibility) {
+  if (visibility === "private" && !logical.agentId) {
+    throw new Error("private memory requires scope.agentId");
+  }
+  if (visibility === "team" && !logical.teamId) {
+    throw new Error("team memory requires scope.teamId");
+  }
+  const principal = visibility === "private" ? logical.agentId : visibility === "team" ? logical.teamId : "all";
+  const namespace = [
+    logical.namespace ?? "default",
+    stableId("branch", branchId),
+    visibility,
+    stableId("principal", principal)
+  ].join("/");
+  const physical = {
+    ...logical,
+    namespace,
+    tags: {
+      ...logical.tags ?? {},
+      memoryBranchId: branchId,
+      memoryVisibility: visibility,
+      logicalNamespace: logical.namespace ?? "default"
+    }
+  };
+  if (visibility === "shared") {
+    delete physical.agentId;
+    delete physical.teamId;
+  } else if (visibility === "team") {
+    delete physical.agentId;
+  }
+  return physical;
+}
+function writeQueueKey(branchId, logical, visibility) {
+  return canonicalJson2(
+    stripUndefined({
+      branchId,
+      visibility,
+      tenantId: logical.tenantId,
+      userId: logical.userId,
+      agentId: logical.agentId,
+      fallbackTeamId: logical.agentId === void 0 ? logical.teamId : void 0,
+      fallbackPrincipal: logical.agentId === void 0 && logical.teamId === void 0 ? "unattributed" : void 0
+    })
+  );
+}
+function normalizePolicy(policy) {
+  const allowed = /* @__PURE__ */ new Set(["private", "team", "shared"]);
+  if (!allowed.has(policy.write) || policy.read.some((visibility) => !allowed.has(visibility))) {
+    throw new Error("memory sharing policy contains an unsupported visibility");
+  }
+  const read = [...new Set(policy.read)];
+  if (read.length === 0) throw new Error("memory sharing policy must read at least one visibility");
+  return { read, write: policy.write };
+}
+function createSnapshot(input) {
+  const payload = cloneDurableValue({
+    ...input,
+    journal: [...input.journal].sort((a, b) => a.sequence - b.sequence)
+  });
+  assertDurableValue(payload, `${input.branchId}: branch snapshot`);
+  return {
+    ...payload,
+    digest: `sha256:${sha256(canonicalJson2(stripUndefined(payload)))}`
+  };
+}
+function assertSnapshotDigest(snapshot) {
+  const { digest, ...payload } = snapshot;
+  const actual = `sha256:${sha256(canonicalJson2(stripUndefined(payload)))}`;
+  if (actual !== digest)
+    throw new Error(`memory branch snapshot digest mismatch: ${digest} != ${actual}`);
+}
+function mergeScopes(base, extra) {
+  return {
+    ...base ?? {},
+    ...extra ?? {},
+    tags: { ...base?.tags ?? {}, ...extra?.tags ?? {} }
+  };
+}
+function scopeMatches(actual, requested) {
+  for (const key of [
+    "tenantId",
+    "userId",
+    "agentId",
+    "teamId",
+    "runId",
+    "sessionId",
+    "namespace"
+  ]) {
+    if (requested[key] !== void 0 && actual[key] !== requested[key]) return false;
+  }
+  for (const [key, value] of Object.entries(requested.tags ?? {})) {
+    if (actual.tags?.[key] !== value) return false;
+  }
+  return true;
+}
+function stripUndefined(value) {
+  if (Array.isArray(value)) return value.map(stripUndefined);
+  if (typeof value !== "object" || value === null) return value;
+  return Object.fromEntries(
+    Object.entries(value).filter(([, child]) => child !== void 0).map(([key, child]) => [key, stripUndefined(child)])
+  );
+}
+function cloneWriteInput(input) {
+  return cloneDurableValue(input);
+}
+function cloneWriteResult(result) {
+  return cloneDurableValue(result);
+}
+function cloneJournalEntry(entry) {
+  return {
+    sequence: entry.sequence,
+    input: cloneWriteInput(entry.input),
+    result: cloneWriteResult(entry.result)
+  };
+}
+function assertDurableValue(value, label, seen = /* @__PURE__ */ new WeakSet()) {
+  if (value === null || typeof value === "string" || typeof value === "boolean" || typeof value === "number" && Number.isFinite(value)) {
+    return;
+  }
+  if (value === void 0) return;
+  if (typeof value !== "object") {
+    throw new Error(`${label} must contain only JSON-compatible values`);
+  }
+  if (seen.has(value)) throw new Error(`${label} must not contain cycles`);
+  seen.add(value);
+  if (Array.isArray(value)) {
+    for (const child of value) {
+      if (child === void 0) {
+        throw new Error(`${label} arrays must not contain undefined values`);
+      }
+      assertDurableValue(child, label, seen);
+    }
+  } else {
+    const prototype = Object.getPrototypeOf(value);
+    if (prototype !== Object.prototype && prototype !== null) {
+      throw new Error(`${label} must contain only plain objects`);
+    }
+    for (const child of Object.values(value)) assertDurableValue(child, label, seen);
+  }
+  seen.delete(value);
+}
+function cloneDurableValue(value) {
+  if (Array.isArray(value)) return value.map((child) => cloneDurableValue(child));
+  if (typeof value !== "object" || value === null) return value;
+  return Object.fromEntries(
+    Object.entries(value).map(([key, child]) => [key, cloneDurableValue(child)])
+  );
+}
+
+// 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";
+  }
+};
+function buildAgentMemorySequencesFromBenchmarkCases(cases, options = {}) {
+  const memoryAgentId = options.memoryAgentId ?? "benchmark-agent";
+  return cases.map((testCase) => ({
+    id: testCase.id,
+    family: testCase.family,
+    ...testCase.split !== void 0 ? { split: testCase.split } : {},
+    ...testCase.tags !== void 0 ? { tags: testCase.tags } : {},
+    metadata: compactRecord({
+      ...testCase.metadata ?? {},
+      taskKind: testCase.taskKind,
+      source: testCase.source
+    }),
+    steps: [
+      ...testCase.events.map((event, eventIndex) => ({
+        id: `event:${event.id}`,
+        scope: compactScope(
+          options.eventScope?.({ event, case: testCase, eventIndex }) ?? {
+            agentId: memoryAgentId,
+            sessionId: testCase.id
+          }
+        ),
+        writes: [
+          {
+            id: event.id,
+            kind: "observation",
+            text: event.text,
+            metadata: compactRecord({
+              ...event.metadata ?? {},
+              eventId: event.id,
+              actorId: event.actorId,
+              sessionId: event.sessionId,
+              timestamp: event.timestamp
+            })
+          }
+        ],
+        metadata: { eventIndex }
+      })),
+      {
+        id: "probe",
+        scope: compactScope(
+          options.probeScope?.(testCase) ?? {
+            agentId: memoryAgentId,
+            sessionId: testCase.id
+          }
+        ),
+        probes: [
+          {
+            id: "answer",
+            query: testCase.prompt,
+            taskKind: testCase.taskKind,
+            ...testCase.requiredFacts !== void 0 ? { requiredFacts: testCase.requiredFacts } : {},
+            ...testCase.forbiddenFacts !== void 0 ? { forbiddenFacts: testCase.forbiddenFacts } : {},
+            ...testCase.expectedEventIds !== void 0 ? { expectedEventIds: testCase.expectedEventIds } : {},
+            ...testCase.expectedActorIds !== void 0 ? { expectedActorIds: testCase.expectedActorIds } : {},
+            ...testCase.referenceAnswer !== void 0 ? { referenceAnswer: testCase.referenceAnswer } : {}
+          }
+        ]
+      }
+    ]
+  }));
+}
+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"
+  );
+  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`
+      );
+    }
+    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
+  });
+  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 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 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`
+      };
+    }
+  };
+}
+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`
+    );
+  }
+  if (!cleanupBranches && !candidate.disposeAdapter) {
+    throw new Error(
+      `${candidate.id}: cleanupBranches=false requires disposeAdapter to delete isolated external state`
+    );
+  }
+  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, {
+        ...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`
+      );
+    }
+  };
+  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`
+          );
+        }
+        assertMemoryAttemptCandidateMatches(attempt, candidate);
+        const sequence = input.sequenceById.get(attempt.sequenceId);
+        if (!sequence) {
+          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`
+          );
+        }
+        const recoveryCostUsd = candidate.externalRecoveryCostUsdPerAttempt ?? 0;
+        const recoveryGeneration = recoveryGenerations.get(attempt.branchId);
+        if (recoveryGeneration === void 0) {
+          throw new Error(`missing recovery generation for memory branch '${attempt.branchId}'`);
+        }
+        let externalRecoveryAttempted = false;
+        const recover = async () => {
+          await recoverMemoryAttempt({
+            options: input.options,
+            candidate,
+            sequence,
+            attempt,
+            lease: input.lease,
+            onExternalCall: () => {
+              externalRecoveryAttempted = true;
+            }
+          });
+          appendMemoryAttemptEvent(input.storage, input.attemptLogPath, {
+            ...attempt,
+            status: "cleaned",
+            recovery: true,
+            recordedAt: (input.options.now ?? (() => /* @__PURE__ */ new Date()))().toISOString()
+          });
+        };
+        if (recoveryCostUsd === 0) {
+          await recover();
+        } else {
+          const tags = memoryRecoveryCostTags(input.runDir, candidate.id, attempt.branchId);
+          const receipt = {
+            model: candidate.id,
+            inputTokens: 0,
+            outputTokens: 0,
+            actualCostUsd: recoveryCostUsd
+          };
+          const paid = await input.costLedger.runPaidCall({
+            callId: memoryAttemptCostCallId(attempt, "recovery", recoveryGeneration),
+            channel: "driver",
+            phase: `${input.options.costPhase ?? "memory.experiment"}.recovery`,
+            actor: `agent-knowledge:memory-recovery:${candidate.id}`,
+            model: candidate.id,
+            tags,
+            maximumCharge: { externallyEnforcedMaximumUsd: recoveryCostUsd },
+            execute: recover,
+            receipt: () => ({
+              ...receipt,
+              actualCostUsd: externalRecoveryAttempted ? recoveryCostUsd : 0
+            }),
+            receiptFromError: () => ({
+              ...receipt,
+              actualCostUsd: externalRecoveryAttempted ? recoveryCostUsd : 0
+            })
+          });
+          if (!paid.succeeded) throw paid.error;
+        }
+      })
+    )
+  );
+  const failures = settled.flatMap(
+    (result) => result.status === "rejected" ? [result.reason] : []
+  );
+  if (failures.length === 1) throw failures[0];
+  if (failures.length > 1) {
+    throw new AggregateError(failures, "multiple abandoned memory branches failed recovery");
+  }
+}
+async function recoverMemoryAttempt(input) {
+  const { options, candidate, sequence, attempt, lease, onExternalCall } = input;
+  const cleanupBranches = attempt.cleanupBranches;
+  const cleanupTimeoutMs = resolveMemoryCleanupTimeoutMs(
+    options.cleanupTimeoutMs,
+    `${candidate.id}: abandoned branch recovery`
+  );
+  let rawAdapter;
+  let adapter;
+  let memory;
+  let primaryError;
+  try {
+    const abortController = new AbortController();
+    const creation = Promise.resolve().then(
+      () => candidate.createAdapter({
+        branchId: attempt.branchId,
+        sequence,
+        rep: attempt.rep,
+        seed: attempt.seed,
+        purpose: "recovery",
+        signal: abortController.signal,
+        markExternalCall: onExternalCall
+      })
+    );
+    releaseMemoryAdapterCreatedAfterAbort({
+      creation,
+      signal: abortController.signal,
+      dispose: candidate.disposeAdapter ? async (created) => {
+        onExternalCall();
+        await candidate.disposeAdapter?.(created);
+      } : void 0
+    });
+    const recovered = await runBoundedMemoryLifecycle({
+      operation: `${candidate.id}: recovery adapter creation`,
+      timeoutMs: cleanupTimeoutMs,
+      abortController,
+      run: () => creation
+    });
+    await lease.assertOwned();
+    if (recovered === null) return;
+    rawAdapter = recovered;
+    adapter = trackExternalMemoryCalls(recovered, onExternalCall);
+    const recoveryDelayMs = memoryRecoveryDelayMs(adapter);
+    await sleepForMemoryRecovery(
+      recoveryDelayMs,
+      () => lease.assertOwned(),
+      cleanupTimeoutMs,
+      `${candidate.id}: abandoned branch recovery visibility wait`
+    );
+    if (cleanupBranches) {
+      if (!adapter.clear) {
+        throw new Error(
+          `${candidate.id}: abandoned branch recovery requires an adapter with scoped clear support`
+        );
+      }
+      memory = createAgentMemoryBranch({
+        adapter,
+        branchId: attempt.branchId,
+        lifetime: "attempt",
+        policy: candidate.policy,
+        allowedWriteScopes: sequenceCleanupScopes(sequence),
+        baseScope: memoryExperimentBaseScope(options, candidate, sequence.id)
+      });
+      await runBoundedMemoryLifecycle({
+        operation: `${candidate.id}: abandoned branch cleanup`,
+        timeoutMs: cleanupTimeoutMs,
+        resource: adapter,
+        run: () => clearSequenceScopes(memory, sequence)
+      });
+      await lease.assertOwned();
+    }
+  } catch (error) {
+    primaryError = error;
+  }
+  const cleanupErrors = [];
+  let cleanupOwned = true;
+  try {
+    await lease.assertOwned();
+  } catch (error) {
+    cleanupOwned = false;
+    cleanupErrors.push(error);
+  }
+  if (adapter) {
+    try {
+      await runBoundedMemoryLifecycle({
+        operation: `${candidate.id}: recovery adapter close`,
+        timeoutMs: cleanupTimeoutMs,
+        resource: adapter,
+        run: async () => {
+          if (memory && cleanupOwned) {
+            await memory.close?.();
+          } else {
+            if (cleanupOwned && adapter.flush) {
+              await adapter.flush();
+            }
+            await adapter.close?.();
+          }
+        }
+      });
+    } catch (error) {
+      cleanupErrors.push(error);
+    }
+    if (cleanupOwned) {
+      try {
+        if (candidate.disposeAdapter) onExternalCall();
+        await runBoundedMemoryLifecycle({
+          operation: `${candidate.id}: recovery adapter disposal`,
+          timeoutMs: cleanupTimeoutMs,
+          resource: adapter,
+          run: () => candidate.disposeAdapter?.(rawAdapter)
+        });
+      } catch (error) {
+        cleanupErrors.push(error);
+      }
+    }
+  } else {
+    cleanupErrors.push(
+      new Error(
+        `${candidate.id}: recovery adapter creation failed before cleanup could be confirmed`
+      )
+    );
+  }
+  if (!cleanupOwned || primaryError || cleanupErrors.length > 0) {
+    throw new AgentMemoryCleanupError(
+      [...primaryError ? [primaryError] : [], ...cleanupErrors],
+      `${candidate.id}: abandoned memory branch '${attempt.branchId}' recovery failed`
+    );
+  }
+}
+function memoryAttemptCostCallId(attempt, purpose, generation) {
+  return stableId(
+    "memory_cost_call",
+    canonicalJson3({
+      purpose,
+      generation,
+      branchId: attempt.branchId,
+      candidateId: attempt.candidateId,
+      candidateRef: attempt.candidateRef,
+      externalCostUsdPerSequence: attempt.externalCostUsdPerSequence,
+      externalRecoveryCostUsdPerAttempt: attempt.externalRecoveryCostUsdPerAttempt,
+      sequenceId: attempt.sequenceId,
+      rep: attempt.rep,
+      seed: attempt.seed
+    })
+  );
+}
+function memoryRecoveryCostTags(runDir, candidateId, branchId) {
+  return {
+    runDir,
+    candidateId,
+    branchId,
+    memoryRecovery: "attempt"
+  };
+}
+function memoryAttemptEvent(input) {
+  return {
+    schema: 2,
+    status: input.status,
+    branchId: input.branchId,
+    candidateId: input.candidate.id,
+    candidateRef: input.candidate.ref,
+    sequenceId: input.sequence.id,
+    rep: input.rep,
+    seed: input.seed,
+    cleanupBranches: input.cleanupBranches ?? true,
+    externalCostUsdPerSequence: input.candidate.externalCostUsdPerSequence ?? 0,
+    externalRecoveryCostUsdPerAttempt: input.candidate.externalRecoveryCostUsdPerAttempt ?? 0,
+    recordedAt: (input.now ?? (() => /* @__PURE__ */ new Date()))().toISOString(),
+    recovery: input.recovery
+  };
+}
+function appendMemoryAttemptEvent(storage, path, event) {
+  appendAttemptJournalEvent({
+    storage,
+    path,
+    event,
+    label: "memory attempt log"
+  });
+}
+function readActiveMemoryAttempts(storage, path) {
+  return readActiveAttemptJournal({
+    storage,
+    path,
+    label: "memory attempt log",
+    parse: parseMemoryAttemptEvent,
+    id: (event) => event.branchId,
+    sameAttempt: sameMemoryAttempt
+  });
+}
+function parseMemoryAttemptEvent(value, path, line) {
+  const event = value;
+  const valid = typeof event === "object" && event !== null && event.schema === 2 && (event.status === "started" || event.status === "cleaned") && typeof event.branchId === "string" && event.branchId.length > 0 && typeof event.candidateId === "string" && event.candidateId.length > 0 && typeof event.candidateRef === "string" && event.candidateRef.length > 0 && typeof event.sequenceId === "string" && event.sequenceId.length > 0 && Number.isSafeInteger(event.rep) && Number.isSafeInteger(event.seed) && typeof event.cleanupBranches === "boolean" && typeof event.externalCostUsdPerSequence === "number" && Number.isFinite(event.externalCostUsdPerSequence) && event.externalCostUsdPerSequence >= 0 && typeof event.externalRecoveryCostUsdPerAttempt === "number" && Number.isFinite(event.externalRecoveryCostUsdPerAttempt) && event.externalRecoveryCostUsdPerAttempt >= 0 && typeof event.recordedAt === "string" && !Number.isNaN(Date.parse(event.recordedAt)) && typeof event.recovery === "boolean";
+  if (!valid) throw new Error(`invalid memory attempt event in '${path}' line ${line}`);
+  return value;
+}
+function sameMemoryAttempt(left, right) {
+  return left.branchId === right.branchId && left.candidateId === right.candidateId && left.candidateRef === right.candidateRef && left.sequenceId === right.sequenceId && left.rep === right.rep && left.seed === right.seed && left.cleanupBranches === right.cleanupBranches && left.externalCostUsdPerSequence === right.externalCostUsdPerSequence && left.externalRecoveryCostUsdPerAttempt === right.externalRecoveryCostUsdPerAttempt;
+}
+function assertMemoryAttemptCandidateMatches(attempt, candidate) {
+  if (candidate.ref !== attempt.candidateRef) {
+    throw new Error(
+      `cannot recover memory branch '${attempt.branchId}': candidate ref changed from '${attempt.candidateRef}' to '${candidate.ref}'`
+    );
+  }
+  const executionCost = candidate.externalCostUsdPerSequence ?? 0;
+  const recoveryCost = candidate.externalRecoveryCostUsdPerAttempt ?? 0;
+  if (executionCost !== attempt.externalCostUsdPerSequence || recoveryCost !== attempt.externalRecoveryCostUsdPerAttempt) {
+    throw new Error(
+      `cannot recover memory branch '${attempt.branchId}': candidate cost settings changed; start a new run or restore the recorded costs`
+    );
+  }
+}
+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
+    );
+    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
+    );
+    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))
+    })
+  );
+}
+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
+    }
+  });
+}
+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}`
+      );
+      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`);
+  }
+}
+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,
+          eventId: input.id,
+          actorId: input.metadata?.actorId,
+          sessionId: scope.sessionId,
+          role: input.role,
+          scope,
+          metadata: input.metadata ?? {}
+        })
+      );
+      await callGraphiti(options.client, tools.addMemory, {
+        name,
+        episode_body: input.text,
+        group_id: groupId,
+        source: input.kind === "message" ? "message" : "text",
+        source_description: sourceDescription,
+        uuid: episodeUuid,
+        ...typeof input.metadata?.timestamp === "string" ? { reference_time: input.metadata.timestamp } : {}
+      });
+      queued.set(episodeUuid, { groupId, name });
+      if (consistency === "visible") {
+        await waitForGraphitiEpisode(options, groupId, episodeUuid);
+        queued.delete(episodeUuid);
+      }
+      const result = {
+        accepted: true,
+        id: episodeUuid,
+        uri: `memory://${id}/${episodeUuid}`,
+        kind: input.kind,
+        metadata: {
+          provider: "graphiti",
+          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()
+      });
+    }
+    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}'`
+      );
+    }
+    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 = 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`
+          );
+        }
+        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);
+  }
+  return result;
+}
+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
+  };
+}
+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;
+  }
+  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 || canonicalJson5(manifest.identity) !== canonicalJson5(identity)) {
+    throw new Error(
+      `memory improvement run '${runDir}' does not match its persisted inputs or implementationRef`
+    );
+  }
+}
+function appendMemoryActivationEvent(storage, path, event) {
+  appendDurableJournalEvent({
+    storage,
+    path,
+    event,
+    label: "memory activation journal"
+  });
+}
+function readMemoryActivationJournal(storage, path, expected) {
+  const stored = storage.read(path);
+  if (stored === void 0) {
+    if (storage.exists(path)) throw new Error(`cannot read memory activation journal '${path}'`);
+    return { prepared: false };
+  }
+  let prepared = false;
+  let activated;
+  for (const [index, line] of stored.split("\n").entries()) {
+    if (!line) continue;
+    let raw;
+    try {
+      raw = JSON.parse(line);
+    } catch (error) {
+      throw new Error(`invalid memory activation journal '${path}' line ${index + 1}`, {
+        cause: error
+      });
+    }
+    const event = parseMemoryActivationEvent(raw, path, index + 1, expected);
+    if (event.status === "prepared") {
+      if (prepared || activated) {
+        throw new Error(`memory activation journal '${path}' repeats its prepared event`);
+      }
+      prepared = true;
+      continue;
+    }
+    if (!prepared || activated) {
+      throw new Error(`memory activation journal '${path}' has an out-of-order activated event`);
+    }
+    activated = event;
+  }
+  return { prepared, ...activated ? { activated } : {} };
+}
+function parseMemoryActivationEvent(value, path, line, expected) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error(`invalid memory activation journal '${path}' line ${line}`);
+  }
+  const event = value;
+  for (const [key, expectedValue] of Object.entries(expected)) {
+    if (event[key] !== expectedValue) {
+      throw new Error(
+        `memory activation journal '${path}' line ${line} does not match the measured winner`
+      );
+    }
+  }
+  if (event.status !== "prepared" && event.status !== "activated") {
+    throw new Error(`invalid memory activation journal '${path}' line ${line} status`);
+  }
+  if (typeof event.recordedAt !== "string" || !Number.isFinite(Date.parse(event.recordedAt))) {
+    throw new Error(`invalid memory activation journal '${path}' line ${line} recordedAt`);
+  }
+  if (event.status === "activated" && event.outcome !== "applied" && event.outcome !== "recovered" && event.outcome !== "already-current") {
+    throw new Error(`invalid memory activation journal '${path}' line ${line} outcome`);
+  }
+  if (event.status === "prepared" && event.outcome !== void 0) {
+    throw new Error(`invalid memory activation journal '${path}' line ${line} prepared outcome`);
+  }
+  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
+    )}
+`
+  );
+}
+function decidePromotion(input) {
+  const { options, result, baselineId, winnerId } = input;
+  const baselineRow = result.rows.find((row) => row.candidateId === baselineId);
+  const winnerRow = result.rows.find((row) => row.candidateId === winnerId);
+  if (!baselineRow || !winnerRow) throw new Error("holdout result is missing a comparison arm");
+  const paired = pairedArtifacts(result, baselineId, winnerId, (artifact) => artifact.score);
+  const significance = heldoutSignificance(paired, options.significance);
+  const tolerance = options.criticalDimensionTolerance ?? 0.05;
+  const criticalDimensions = (options.criticalDimensions ?? DEFAULT_CRITICAL_DIMENSIONS).map(
+    (dimension) => {
+      const expectedN = applicableSequenceCount(options.holdoutSequences, dimension) * (options.reps ?? 1);
+      const dimensionPairs = pairedArtifacts(
+        result,
+        baselineId,
+        winnerId,
+        (artifact) => (artifact.dimensionSampleCounts?.[dimension] ?? 0) > 0 ? artifact.dimensions[dimension] : void 0
+      );
+      const comparison = heldoutSignificance(dimensionPairs, {
+        ...options.significance,
+        deltaThreshold: 0
+      });
+      return {
+        dimension,
+        n: comparison.n,
+        expectedN,
+        measured: expectedN > 0 && comparison.n === expectedN,
+        meanDelta: comparison.bootstrap.mean,
+        low: comparison.bootstrap.low,
+        high: comparison.bootstrap.high,
+        tolerance,
+        regressed: expectedN > 0 && comparison.n === expectedN && comparison.bootstrap.low < -tolerance
+      };
+    }
+  );
+  const reasons = [];
+  if (baselineRow.cellsFailed > 0 || winnerRow.cellsFailed > 0) {
+    reasons.push("at least one holdout cell failed");
+  }
+  if (!significance.significant) {
+    reasons.push(
+      significance.fewRuns ? `only ${significance.n} paired holdout cells; more are required` : "holdout lift is not confidently above the promotion threshold"
+    );
+  }
+  if (winnerRow.scoreMean < (options.minHoldoutScore ?? 0)) {
+    reasons.push(`winner holdout score ${winnerRow.scoreMean} is below the required minimum`);
+  }
+  for (const dimension of criticalDimensions) {
+    if (!dimension.measured) {
+      reasons.push(
+        dimension.expectedN === 0 ? `critical dimension ${dimension.dimension} has no applicable holdout histories` : `critical dimension ${dimension.dimension} was measured on ${dimension.n}/${dimension.expectedN} applicable paired holdout cells`
+      );
+    } else if (dimension.regressed) {
+      reasons.push(`${dimension.dimension} may regress beyond ${tolerance}`);
+    }
+  }
+  return {
+    status: reasons.length === 0 ? "promote" : "hold",
+    reasons,
+    baselineScore: baselineRow.scoreMean,
+    winnerScore: winnerRow.scoreMean,
+    lift: winnerRow.scoreMean - baselineRow.scoreMean,
+    significance,
+    criticalDimensions
+  };
+}
+function applicableSequenceCount(sequences, dimension) {
+  return sequences.filter(
+    (sequence) => sequence.steps.some(
+      (step) => (step.probes ?? []).some((probe) => probeAppliesToDimension(probe, dimension))
+    )
+  ).length;
+}
+function probeAppliesToDimension(probe, dimension) {
+  switch (dimension) {
+    case "memory_fact_recall":
+    case "memory_required_fact_count":
+    case "memory_matched_fact_count":
+      return Boolean(
+        probe.requiredFacts && probe.requiredFacts.length > 0 || probe.referenceAnswer
+      );
+    case "memory_event_recall":
+      return Boolean(probe.expectedEventIds && probe.expectedEventIds.length > 0);
+    case "memory_actor_recall":
+      return Boolean(probe.expectedActorIds && probe.expectedActorIds.length > 0);
+    case "memory_stale_safe":
+    case "memory_stale_rate":
+    case "memory_forbidden_fact_count":
+    case "memory_matched_forbidden_fact_count":
+      return Boolean(probe.forbiddenFacts && probe.forbiddenFacts.length > 0);
+    default:
+      return true;
+  }
+}
+function normalizedPromotionPolicy(options) {
+  return {
+    significance: {
+      deltaThreshold: options.significance?.deltaThreshold ?? 0,
+      minProductiveRuns: options.significance?.minProductiveRuns ?? 3,
+      confidence: options.significance?.confidence ?? 0.95,
+      resamples: options.significance?.resamples ?? 2e3,
+      seed: options.significance?.seed ?? 1337,
+      statistic: options.significance?.statistic ?? "mean"
+    },
+    criticalDimensions: [...options.criticalDimensions ?? DEFAULT_CRITICAL_DIMENSIONS],
+    criticalDimensionTolerance: options.criticalDimensionTolerance ?? 0.05,
+    minHoldoutScore: options.minHoldoutScore ?? 0
+  };
+}
+function pairedArtifacts(result, baselineId, winnerId, select) {
+  const baseline = artifactValues(result, baselineId, select);
+  const winner = artifactValues(result, winnerId, select);
+  const keys = [...baseline.keys()].filter((key) => winner.has(key)).sort();
+  return {
+    before: keys.map((key) => baseline.get(key)),
+    after: keys.map((key) => winner.get(key)),
+    cellIds: keys
+  };
+}
+function artifactValues(result, candidateId, select) {
+  const values = /* @__PURE__ */ new Map();
+  for (const cell of result.campaign.cells) {
+    if (cell.error || cell.artifact.candidateId !== candidateId) continue;
+    const value = select(cell.artifact);
+    if (value === void 0 || !Number.isFinite(value)) continue;
+    values.set(`${cell.artifact.sequenceId}:${cell.rep}`, value);
+  }
+  return values;
+}
+function sequenceScores(result, sequences, candidateId) {
+  const bySequence = /* @__PURE__ */ new Map();
+  for (const cell of result.campaign.cells) {
+    if (cell.error || cell.artifact.candidateId !== candidateId) continue;
+    const bucket = bySequence.get(cell.artifact.sequenceId) ?? [];
+    bucket.push(cell.artifact.score);
+    bySequence.set(cell.artifact.sequenceId, bucket);
+  }
+  return sequences.map((sequence) => mean2(bySequence.get(sequence.id) ?? []));
+}
+function requireStringSurface(surface) {
+  if (typeof surface !== "string" || surface.trim().length === 0) {
+    throw new Error("memory config proposer must return a JSON string surface");
+  }
+  return surface;
+}
+function serializeMemoryConfig(serialize, config) {
+  let surface;
+  try {
+    surface = serialize(config);
+  } catch (error) {
+    throw new Error("memory config serializer failed", { cause: error });
+  }
+  if (typeof surface !== "string" || surface.trim().length === 0) {
+    throw new Error("memory config serializer must return a non-empty string");
+  }
+  return surface;
+}
+function parseMemoryConfig(parse, surface) {
+  try {
+    const config = parse(surface);
+    if (config === void 0) throw new Error("parser returned undefined");
+    return config;
+  } catch (error) {
+    throw new Error("memory config surface could not be parsed", { cause: error });
+  }
+}
+function assertMemoryConfigRoundTrip(config, serialize, parse) {
+  const first = serialize(config);
+  const second = serialize(parse(first));
+  if (first !== second) {
+    throw new Error("memory config serializer and parser must round-trip seed configs exactly");
+  }
+}
+function memorySequenceFingerprint(sequence) {
+  const { id: _id, split: _split, tags: _tags, ...content } = sequence;
+  return surfaceHash(canonicalJson5(content));
+}
+function assertMemoryImprovementOptions(options) {
+  for (const [name, value] of [
+    ["experimentId", options.experimentId],
+    ["runDir", options.runDir]
+  ]) {
+    if (typeof value !== "string" || !value.trim()) {
+      throw new Error(`memory improvement ${name} must be a non-empty string`);
+    }
+  }
+  if (typeof options.proposer?.kind !== "string" || !options.proposer.kind.trim()) {
+    throw new Error("memory improvement proposer.kind must be a non-empty string");
+  }
+  if (typeof options.proposer?.propose !== "function") {
+    throw new Error("memory improvement proposer.propose must be a function");
+  }
+  if (options.governor !== void 0 && typeof options.governor.decide !== "function") {
+    throw new Error("memory improvement governor.decide must be a function");
+  }
+  if (options.activation !== void 0) {
+    if (typeof options.activation.ref !== "string" || !options.activation.ref.trim()) {
+      throw new Error("memory improvement activation.ref must be a non-empty string");
+    }
+    if (typeof options.activation.readCurrent !== "function") {
+      throw new Error("memory improvement activation.readCurrent must be a function");
+    }
+    if (typeof options.activation.compareAndSet !== "function") {
+      throw new Error("memory improvement activation.compareAndSet must be a function");
+    }
+  }
+  for (const [name, proposer] of Object.entries(options.proposers ?? {})) {
+    if (!name.trim()) throw new Error("memory improvement proposer labels must be non-empty");
+    if (!proposer || typeof proposer.kind !== "string" || !proposer.kind.trim() || typeof proposer.propose !== "function") {
+      throw new Error(`memory improvement proposer '${name}' is invalid`);
+    }
+  }
+  if (options.serializeConfig !== void 0 && typeof options.serializeConfig !== "function") {
+    throw new Error("memory improvement serializeConfig must be a function");
+  }
+  if (options.parseConfig !== void 0 && typeof options.parseConfig !== "function") {
+    throw new Error("memory improvement parseConfig must be a function");
+  }
+  if (!Number.isSafeInteger(options.budget.maxSteps) || options.budget.maxSteps < 0) {
+    throw new Error("memory improvement budget.maxSteps must be a non-negative safe integer");
+  }
+  for (const [name, value] of [
+    ["populationSize", options.populationSize],
+    ["candidateConcurrency", options.candidateConcurrency],
+    ["sequenceConcurrency", options.sequenceConcurrency],
+    ["reps", options.reps],
+    ["maxRecoveryAttempts", options.maxRecoveryAttempts],
+    ["maxRecoveryRetriesPerAttempt", options.maxRecoveryRetriesPerAttempt]
+  ]) {
+    if (value !== void 0 && (!Number.isSafeInteger(value) || value <= 0)) {
+      throw new Error(`memory improvement ${name} must be a positive safe integer`);
+    }
+  }
+  if (options.maxTotalCostUsd !== void 0 && (!Number.isFinite(options.maxTotalCostUsd) || options.maxTotalCostUsd < 0)) {
+    throw new Error("memory improvement maxTotalCostUsd must be a non-negative finite number");
+  }
+  if (options.activationTimeoutMs !== void 0 && (!Number.isSafeInteger(options.activationTimeoutMs) || options.activationTimeoutMs <= 0)) {
+    throw new Error("memory improvement activationTimeoutMs must be a positive safe integer");
+  }
+  const tolerance = options.criticalDimensionTolerance;
+  if (tolerance !== void 0 && (!Number.isFinite(tolerance) || tolerance < 0 || tolerance > 1)) {
+    throw new Error("memory improvement criticalDimensionTolerance must be between 0 and 1");
+  }
+  const minimum = options.minHoldoutScore;
+  if (minimum !== void 0 && (!Number.isFinite(minimum) || minimum < 0 || minimum > 1)) {
+    throw new Error("memory improvement minHoldoutScore must be between 0 and 1");
+  }
+  for (const seed of options.seeds) {
+    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");
+    }
+  }
+  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);
+  }
+}
+function mean2(values) {
+  return values.length === 0 ? 0 : values.reduce((sum, value) => sum + value, 0) / values.length;
+}
+
+// src/memory/mem0.ts
+import { randomUUID as randomUUID4 } from "crypto";
+import { canonicalJson as canonicalJson6 } from "@tangle-network/agent-eval";
+function createMem0MemoryAdapter(options) {
+  assertMem0Options(options);
+  const id = options.id ?? `mem0-${options.mode}`;
+  const pendingWrites = /* @__PURE__ */ new Set();
+  const adapter = {
+    id,
+    branchIsolation: options.mode === "oss" ? { mode: "scoped" } : {
+      mode: "scoped",
+      processExitSafe: false,
+      recoveryDelayMs: options.ingestionTimeoutMs ?? 3e4
+    },
+    async search(query, searchOptions = {}) {
+      assertMem0SearchOptions(searchOptions, id);
+      if (searchOptions.limit === 0) return [];
+      const scope = mergeScopes4(options.defaultScope, searchOptions.scope);
+      assertMem0ProviderScope(scope, options.mode, id, "search");
+      const requestedKinds = [...new Set(searchOptions.kinds ?? [])];
+      const kindQueries = requestedKinds.length > 0 ? requestedKinds : [void 0];
+      const payloads = await Promise.all(
+        kindQueries.map(
+          (kind) => options.client.search(query, {
+            filters: mem0Filters(scope, options.appId, kind),
+            topK: searchOptions.limit,
+            threshold: searchOptions.minScore,
+            ...options.rerank !== void 0 ? { rerank: options.rerank } : {},
+            ...options.mode === "hosted" && options.latestOnly !== void 0 ? { latestOnly: options.latestOnly } : {}
+          })
+        )
+      );
+      return mergeMem0Hits(
+        payloads.flatMap((raw) => normalizeMem0Hits(raw, id, searchOptions)),
+        searchOptions.limit
+      );
+    },
+    async getContext(query, searchOptions = {}) {
+      return defaultGetMemoryContext(adapter, query, searchOptions);
+    },
+    async write(input) {
+      const scope = mergeScopes4(options.defaultScope, input.scope);
+      assertMem0ProviderScope(scope, options.mode, id, "write");
+      pruneExpiredMem0PendingWrites(pendingWrites);
+      const writeId = input.id ?? randomUUID4();
+      const writeFilters = mem0Filters(scope, options.appId);
+      const pendingProbe = {
+        text: input.text,
+        providerIds: /* @__PURE__ */ new Set(),
+        filters: writeFilters,
+        expiresAt: Number.POSITIVE_INFINITY
+      };
+      pendingWrites.add(pendingProbe);
+      const scopeMetadata = mem0ScopeMetadata(scope, options.appId);
+      const metadata = compactRecord2({
+        ...input.metadata,
+        agentKnowledgeWriteId: writeId,
+        memoryKind: input.kind,
+        memoryTitle: input.title,
+        entityName: input.entityName,
+        entityType: input.entityType,
+        category: input.category,
+        predicate: input.predicate,
+        subject: input.subject,
+        object: input.object,
+        confidence: input.confidence,
+        originalRole: input.role,
+        ...scopeMetadata
+      });
+      const entity = mem0Entity(scope, options.appId);
+      let raw;
+      try {
+        raw = await options.client.add([{ role: mem0Role(input.role), content: input.text }], {
+          ...entity,
+          metadata,
+          infer: options.infer ?? true,
+          ...options.mode === "oss" ? { filters: writeFilters } : {}
+        });
+      } finally {
+        pendingProbe.expiresAt = Date.now() + (options.ingestionTimeoutMs ?? 3e4);
+      }
+      if (options.mode === "hosted" && !Array.isArray(raw)) {
+        throw new Error(
+          `${id}: hosted Mem0 add returned an unsupported response; mem0ai 3.x must return a memory array`
+        );
+      }
+      const items = extractMem0Items(raw);
+      const mutations = items.filter((candidate) => mem0Event(candidate) !== "NOOP");
+      const durableMutations = mutations.filter((candidate) => mem0Event(candidate) !== "DELETE");
+      for (const candidate of durableMutations) {
+        const providerId = stringField2(candidate, ["id"]);
+        if (providerId) pendingProbe.providerIds.add(providerId);
+      }
+      if (durableMutations.length === 0) {
+        pendingWrites.delete(pendingProbe);
+      }
+      const item = mutations[0] ?? items[0];
+      const itemId = stringField2(item, ["id"]) ?? writeId;
+      const event = mem0Event(item);
+      const events = [...new Set(mutations.map(mem0Event).filter(Boolean))];
+      const result = {
+        accepted: mutations.length > 0,
+        id: itemId,
+        uri: `memory://${id}/${encodeURIComponent(itemId)}`,
+        kind: input.kind,
+        metadata: {
+          provider: "mem0",
+          mode: options.mode,
+          ...event ? { event } : {},
+          ...events.length > 1 ? { events } : {}
+        }
+      };
+      return {
+        ...result,
+        sourceRecord: memoryWriteResultToSourceRecord(result, input.text, { scope })
+      };
+    },
+    async clear(scope) {
+      const mergedScope = mergeScopes4(options.defaultScope, scope);
+      assertMem0ProviderScope(mergedScope, options.mode, id, "clear");
+      pruneExpiredMem0PendingWrites(pendingWrites);
+      const clearFilters = mem0Filters(mergedScope, options.appId);
+      if (Object.keys(clearFilters).length === 0) {
+        throw new Error(`${id}: refusing an unscoped Mem0 clear`);
+      }
+      if (options.client.getAll && options.client.delete) {
+        const pendingForClear = [...pendingWrites].filter(
+          (pending) => mem0FiltersInclude(pending.filters, clearFilters)
+        );
+        const deletedIds = /* @__PURE__ */ new Set();
+        const searchProbes = /* @__PURE__ */ new Map();
+        const observedPending = /* @__PURE__ */ new Set();
+        for (const pending of pendingForClear) {
+          const ids = searchProbes.get(pending.text) ?? /* @__PURE__ */ new Set();
+          for (const providerId of pending.providerIds) ids.add(providerId);
+          searchProbes.set(pending.text, ids);
+          if (pending.providerIds.size > 0) observedPending.add(pending);
+        }
+        for (const pending of pendingForClear) {
+          for (const providerId of pending.providerIds) {
+            if (deletedIds.has(providerId)) continue;
+            await options.client.delete(providerId);
+            deletedIds.add(providerId);
+          }
+        }
+        const visibilityTimeoutMs = options.ingestionTimeoutMs ?? 3e4;
+        const pollIntervalMs = options.pollIntervalMs ?? 250;
+        let visibilityDeadline = Date.now() + visibilityTimeoutMs;
+        for (let batch = 0; batch < 100; ) {
+          const raw = await options.client.getAll(
+            options.mode === "hosted" ? {
+              filters: mem0Filters(mergedScope, options.appId),
+              page: 1,
+              pageSize: 100,
+              latestOnly: false,
+              showExpired: true
+            } : {
+              filters: mem0Filters(mergedScope, options.appId),
+              topK: 100,
+              showExpired: true
+            }
+          );
+          const items = extractMem0Items(raw);
+          if (items.length === 0) {
+            const searchableByQuery = await searchableMem0IdsForCleanup(
+              options,
+              clearFilters,
+              searchProbes
+            );
+            const searchableIds = new Set(
+              [...searchableByQuery.values()].flatMap((ids2) => [...ids2])
+            );
+            const unseenSearchIds = [...searchableIds].filter(
+              (memoryId) => !deletedIds.has(memoryId)
+            );
+            for (const [query, ids2] of searchableByQuery) {
+              const known = searchProbes.get(query) ?? /* @__PURE__ */ new Set();
+              for (const memoryId of ids2) known.add(memoryId);
+              searchProbes.set(query, known);
+              if (ids2.size > 0) {
+                for (const pending of pendingForClear) {
+                  if (pending.text === query) observedPending.add(pending);
+                }
+              }
+            }
+            if (unseenSearchIds.length > 0) {
+              for (const memoryId of unseenSearchIds) {
+                await options.client.delete(memoryId);
+                deletedIds.add(memoryId);
+              }
+              batch += 1;
+              visibilityDeadline = Date.now() + visibilityTimeoutMs;
+              continue;
+            }
+            const unresolvedPending = pendingForClear.some(
+              (pending) => !observedPending.has(pending)
+            );
+            const needsQuietWindow = pendingForClear.some(
+              (pending) => pending.providerIds.size === 0
+            );
+            const remainingMs = visibilityDeadline - Date.now();
+            if (remainingMs <= 0) {
+              if (!unresolvedPending && searchableIds.size === 0) {
+                removeMem0PendingWrites(pendingWrites, pendingForClear);
+                return;
+              }
+              if (searchableIds.size > 0) {
+                throw new Error(
+                  `${id}: deleted Mem0 memories remained searchable after ${visibilityTimeoutMs}ms`
+                );
+              }
+              throw new Error(
+                `${id}: a Mem0 write never became visible for exact cleanup within ${visibilityTimeoutMs}ms`
+              );
+            }
+            if (!unresolvedPending && searchableIds.size === 0 && !needsQuietWindow) {
+              removeMem0PendingWrites(pendingWrites, pendingForClear);
+              return;
+            }
+            await sleep(Math.min(pollIntervalMs, remainingMs));
+            continue;
+          }
+          const rawIds = items.map((item) => stringField2(item, ["id"]));
+          if (!rawIds.every((memoryId) => memoryId !== void 0)) {
+            throw new Error(`${id}: Mem0 returned memories without ids during scoped clear`);
+          }
+          const ids = [...new Set(rawIds)];
+          for (const item of items) {
+            const memoryId = stringField2(item, ["id"]);
+            const text = stringField2(item, ["memory", "text", "content"]) ?? stringField2(recordField(item, "data"), ["memory", "text", "content"]);
+            if (!text) continue;
+            const idsForText = searchProbes.get(text) ?? /* @__PURE__ */ new Set();
+            idsForText.add(memoryId);
+            searchProbes.set(text, idsForText);
+            for (const pending of pendingForClear) {
+              if (pending.text === text || pending.providerIds.has(memoryId)) {
+                observedPending.add(pending);
+              }
+            }
+          }
+          const unseenIds = ids.filter((memoryId) => !deletedIds.has(memoryId));
+          if (unseenIds.length === 0) {
+            const remainingMs = visibilityDeadline - Date.now();
+            if (remainingMs <= 0) {
+              throw new Error(
+                `${id}: deleted Mem0 memories remained visible after ${visibilityTimeoutMs}ms`
+              );
+            }
+            await sleep(Math.min(pollIntervalMs, remainingMs));
+            continue;
+          }
+          for (const memoryId of unseenIds) {
+            await options.client.delete(memoryId);
+            deletedIds.add(memoryId);
+          }
+          batch += 1;
+          visibilityDeadline = Date.now() + visibilityTimeoutMs;
+        }
+        throw new Error(
+          `${id}: refused to clear more than ${deletedIds.size} Mem0 memories in one call`
+        );
+      }
+      throw new Error(`${id}: exact scoped clear requires Mem0 getAll plus per-memory delete`);
+    }
+  };
+  return adapter;
+}
+function assertMem0Options(options) {
+  if (options.id !== void 0 && (typeof options.id !== "string" || !options.id.trim())) {
+    throw new Error("Mem0 id must be a non-empty string");
+  }
+  if (options.appId !== void 0 && (typeof options.appId !== "string" || !options.appId.trim())) {
+    throw new Error("Mem0 appId must be a non-empty string");
+  }
+  if (options.backendRef !== void 0 && (typeof options.backendRef !== "string" || !options.backendRef.trim())) {
+    throw new Error("Mem0 backendRef must be a non-empty string");
+  }
+  for (const [name, value] of [
+    ["ingestionTimeoutMs", options.ingestionTimeoutMs],
+    ["pollIntervalMs", options.pollIntervalMs]
+  ]) {
+    if (value !== void 0 && (!Number.isSafeInteger(value) || value <= 0)) {
+      throw new Error(`Mem0 ${name} must be a positive safe integer`);
+    }
+  }
+}
+function assertMem0SearchOptions(options, adapterId) {
+  if (options.limit !== void 0 && (!Number.isSafeInteger(options.limit) || options.limit < 0)) {
+    throw new Error(`${adapterId}: search limit must be a non-negative safe integer`);
+  }
+  if (options.minScore !== void 0 && !Number.isFinite(options.minScore)) {
+    throw new Error(`${adapterId}: minScore must be finite`);
+  }
+}
+function assertMem0ProviderScope(scope, mode, adapterId, operation) {
+  if (scope.userId || scope.agentId || scope.runId || scope.namespace) return;
+  if (operation === "clear") {
+    throw new Error(
+      `${adapterId}: refusing an unscoped Mem0 clear; provide scope.userId, scope.agentId, scope.runId, or scope.namespace`
+    );
+  }
+  throw new Error(
+    `${adapterId}: Mem0 ${mode} ${operation} requires scope.userId, scope.agentId, scope.runId, or scope.namespace`
+  );
+}
+function normalizeMem0Hits(raw, adapterId, options) {
+  const limit = options.limit ?? Number.POSITIVE_INFINITY;
+  const kinds = options.kinds && options.kinds.length > 0 ? new Set(options.kinds) : null;
+  return extractMem0Items(raw).map((item) => {
+    const text = stringField2(item, ["memory", "text", "content"]) ?? stringField2(recordField(item, "data"), ["memory", "text", "content"]);
+    if (!text) return void 0;
+    const metadata = recordField(item, "metadata");
+    const kind = mem0Kind(metadata?.memoryKind ?? item?.memoryType);
+    if (kinds && !kinds.has(kind)) return void 0;
+    const score = numberField2(item, ["rerankScore", "rerank_score", "score"]);
+    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 normalizedScore = score !== void 0 && score >= 0 && score <= 1 ? score : void 0;
+    return {
+      id: memoryId,
+      uri: `memory://${adapterId}/${encodeURIComponent(memoryId)}`,
+      kind,
+      text,
+      ...stringField2(metadata, ["memoryTitle"]) ? { title: String(metadata.memoryTitle) } : {},
+      ...score !== void 0 ? { score } : {},
+      ...normalizedScore !== void 0 ? { normalizedScore } : {},
+      ...dateField(item, ["createdAt", "created_at"]) ? { createdAt: dateField(item, ["createdAt", "created_at"]) } : {},
+      ...dateField(item, ["expirationDate", "expiration_date"]) ? { validUntil: dateField(item, ["expirationDate", "expiration_date"]) } : {},
+      metadata: compactRecord2({
+        provider: "mem0",
+        ...metadata,
+        categories: item?.categories,
+        owner: item?.owner,
+        runId: item?.runId,
+        agentId: item?.agentId,
+        userId: item?.userId
+      })
+    };
+  }).filter((hit) => hit !== void 0).slice(0, limit);
+}
+function mergeMem0Hits(hits, limit) {
+  const unique = /* @__PURE__ */ new Map();
+  for (const [index, hit] of hits.entries()) {
+    const key = JSON.stringify([hit.uri, hit.text]);
+    const score = hit.normalizedScore ?? hit.score;
+    const finiteScore = score !== void 0 && Number.isFinite(score) ? score : void 0;
+    const prior = unique.get(key);
+    if (!prior) {
+      unique.set(key, { hit, index, score: finiteScore });
+    } else if (finiteScore !== void 0 && (prior.score === void 0 || finiteScore > prior.score)) {
+      unique.set(key, { hit, index: prior.index, score: finiteScore });
+    }
+  }
+  return [...unique.values()].sort(
+    (left, right) => Number(right.score !== void 0) - Number(left.score !== void 0) || (right.score ?? 0) - (left.score ?? 0) || left.index - right.index
+  ).map(({ hit }) => hit).slice(0, limit ?? Number.POSITIVE_INFINITY);
+}
+function extractMem0Items(raw) {
+  if (Array.isArray(raw)) return raw.filter(isRecord2);
+  if (!isRecord2(raw)) return [];
+  for (const key of ["results", "memories", "data"]) {
+    if (Array.isArray(raw[key])) return raw[key].filter(isRecord2);
+  }
+  return [raw];
+}
+function mem0Event(item) {
+  return (stringField2(item, ["event"]) ?? stringField2(recordField(item, "metadata"), ["event"]))?.toUpperCase();
+}
+function mem0Entity(scope, appId) {
+  return compactStringRecord({
+    userId: scope.userId,
+    agentId: scope.agentId,
+    appId,
+    runId: scope.namespace ?? scope.runId
+  });
+}
+function mem0Filters(scope, appId, kind) {
+  const entity = mem0EntityFilters(scope, appId);
+  const customMetadata = compactRecord2({
+    ...mem0CustomScopeMetadata(scope),
+    memoryKind: kind
+  });
+  return compactRecord2({ ...entity, ...customMetadata });
+}
+function mem0ScopeMetadata(scope, appId) {
+  return { ...mem0EntityFilters(scope, appId), ...mem0CustomScopeMetadata(scope) };
+}
+function mem0EntityFilters(scope, appId) {
+  return compactStringRecord({
+    user_id: scope.userId,
+    agent_id: scope.agentId,
+    run_id: scope.namespace ?? scope.runId,
+    app_id: appId
+  });
+}
+function mem0CustomScopeMetadata(scope) {
+  const metadata = compactStringRecord({
+    logical_run_id: scope.namespace ? scope.runId : void 0,
+    tenant_id: scope.tenantId,
+    team_id: scope.teamId,
+    session_id: scope.sessionId
+  });
+  for (const [key, value] of Object.entries(scope.tags ?? {})) {
+    metadata[`tag_${key}`] = value;
+  }
+  return metadata;
+}
+async function searchableMem0IdsForCleanup(options, filters, probes) {
+  const searchable = /* @__PURE__ */ new Map();
+  const entries = [...probes];
+  for (let offset = 0; offset < entries.length; offset += 8) {
+    const results = await Promise.all(
+      entries.slice(offset, offset + 8).map(async ([query, expectedIds]) => {
+        const raw = await options.client.search(query, {
+          filters,
+          topK: Math.min(100, Math.max(10, expectedIds.size)),
+          ...options.mode === "hosted" ? { latestOnly: false, showExpired: true } : {}
+        });
+        return extractMem0Items(raw).map((item) => {
+          const memoryId = stringField2(item, ["id"]);
+          if (!memoryId) {
+            throw new Error(
+              `${options.id ?? `mem0-${options.mode}`}: Mem0 search returned a memory without an id during clear verification`
+            );
+          }
+          return memoryId;
+        });
+      })
+    );
+    for (const [index, ids] of results.entries()) {
+      const query = entries[offset + index][0];
+      searchable.set(query, new Set(ids));
+    }
+  }
+  return searchable;
+}
+function mem0FiltersInclude(candidate, requested) {
+  return Object.entries(requested).every(([key, value]) => Object.is(candidate[key], value));
+}
+function removeMem0PendingWrites(pendingWrites, removed) {
+  for (const pending of removed) pendingWrites.delete(pending);
+}
+function pruneExpiredMem0PendingWrites(pendingWrites) {
+  const now = Date.now();
+  for (const pending of pendingWrites) {
+    if (pending.expiresAt <= now) pendingWrites.delete(pending);
+  }
+}
+function mem0Role(role) {
+  return role === "assistant" || role === "tool" ? "assistant" : "user";
+}
+function mem0Kind(value) {
+  switch (value) {
+    case "message":
+    case "entity":
+    case "fact":
+    case "preference":
+    case "observation":
+    case "reasoning-trace":
+      return value;
+    default:
+      return "fact";
+  }
+}
+function mergeScopes4(base, extra) {
+  return {
+    ...base ?? {},
+    ...extra ?? {},
+    tags: { ...base?.tags ?? {}, ...extra?.tags ?? {} }
+  };
+}
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function compactRecord2(input) {
+  return Object.fromEntries(Object.entries(input).filter(([, value]) => value !== void 0));
+}
+function compactStringRecord(input) {
+  return Object.fromEntries(
+    Object.entries(input).filter((entry) => entry[1] !== void 0)
+  );
+}
+function isRecord2(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function recordField(value, key) {
+  const field = value?.[key];
+  return isRecord2(field) ? field : void 0;
+}
+function stringField2(value, keys) {
+  for (const key of keys) {
+    const field = value?.[key];
+    if (typeof field === "string" && field.length > 0) return field;
+  }
+  return void 0;
+}
+function numberField2(value, keys) {
+  for (const key of keys) {
+    const field = value?.[key];
+    if (typeof field === "number" && Number.isFinite(field)) return field;
+  }
+  return void 0;
+}
+function dateField(value, keys) {
+  for (const key of keys) {
+    const field = value?.[key];
+    if (typeof field === "string" && field.length > 0) return field;
+    if (field instanceof Date && !Number.isNaN(field.valueOf())) return field.toISOString();
+  }
+  return void 0;
+}
+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)));
+}
+
+// src/memory/neo4j.ts
+import { canonicalJson as canonicalJson7 } from "@tangle-network/agent-eval";
+function createNeo4jAgentMemoryAdapter(options) {
+  assertNeo4jOptions(options);
+  const client = options.client;
+  const id = options.id ?? "neo4j-agent-memory";
+  const isolatedInstance = options.branchId !== void 0;
+  const adapter = {
+    id,
+    branchIsolation: options.branchId ? { mode: "instance", branchId: options.branchId, supportsLogicalScopes: false } : {
+      mode: "unsupported",
+      reason: "create a separate MemoryClient namespace per branch and pass branchId"
+    },
+    async search(query, searchOptions = {}) {
+      assertNeo4jSearchOptions(searchOptions, id);
+      return searchNeo4jMemory(
+        client,
+        query,
+        searchOptions,
+        id,
+        options.transport,
+        isolatedInstance
+      );
+    },
+    async getContext(query, searchOptions = {}) {
+      assertNeo4jSearchOptions(searchOptions, id);
+      assertNeo4jSearchKinds(searchOptions.kinds, options.transport, id);
+      const shortTerm = nested(client, ["shortTerm", "short_term"], {});
+      const sessionId = searchOptions.scope?.sessionId;
+      if (options.contextMode === "native" && options.transport !== "rest") {
+        throw new Error(`${id}: Neo4j native context requires transport="rest"`);
+      }
+      if (options.contextMode === "native" && !sessionId) {
+        throw new Error(`${id}: Neo4j native context requires scope.sessionId`);
+      }
+      if (options.contextMode === "native" && searchOptions.kinds?.some((kind) => kind !== "message" && kind !== "observation")) {
+        throw new Error(
+          `${id}: Neo4j native context only returns message and observation memory kinds`
+        );
+      }
+      if (options.contextMode === "native" && options.transport === "rest" && sessionId) {
+        assertNeo4jScopeSupported(
+          searchOptions.scope,
+          ["sessionId"],
+          id,
+          "native context read",
+          isolatedInstance
+        );
+        const conversationContext = await callRequired(shortTerm, ["getContext"], [sessionId]);
+        const hits = normalizeConversationContextHits(conversationContext, searchOptions, id);
+        const text = renderHits(hits);
+        if (searchOptions.holdout) {
+          emitRetrievalHoldoutBypass(
+            hits,
+            searchOptions.holdout,
+            holdoutBypassContext(query, searchOptions),
+            "short-term-context"
+          );
+        }
+        return {
+          query,
+          text,
+          hits,
+          sourceRecords: hits.map(
+            (hit) => memoryHitToSourceRecord(hit, { scope: searchOptions.scope })
+          ),
+          metadata: { adapter: id, rawContext: conversationContext }
+        };
+      }
+      return defaultGetMemoryContext(adapter, query, searchOptions);
+    },
+    async write(input) {
+      const result = await writeNeo4jMemory(client, input, id, options.transport, isolatedInstance);
+      return {
+        ...result,
+        sourceRecord: memoryWriteResultToSourceRecord(result, input.text, { scope: input.scope })
+      };
+    },
+    async close() {
+      await callOptional(client, ["close"], []);
+    }
+  };
+  return adapter;
+}
+function assertNeo4jOptions(options) {
+  if (typeof options.client !== "object" || options.client === null) {
+    throw new Error("Neo4j agent-memory client must be an object");
+  }
+  if (options.id !== void 0 && (typeof options.id !== "string" || !options.id.trim())) {
+    throw new Error("Neo4j agent-memory id must be a non-empty string");
+  }
+  if (options.branchId !== void 0 && (typeof options.branchId !== "string" || !options.branchId.trim())) {
+    throw new Error("Neo4j agent-memory branchId must be a non-empty string");
+  }
+  if (options.contextMode !== void 0 && !["search", "native"].includes(options.contextMode)) {
+    throw new Error("Neo4j agent-memory contextMode must be search or native");
+  }
+}
+function assertNeo4jSearchOptions(options, adapterId) {
+  if (options.limit !== void 0 && (!Number.isSafeInteger(options.limit) || options.limit < 0)) {
+    throw new Error(`${adapterId}: search limit must be a non-negative safe integer`);
+  }
+  if (options.minScore !== void 0 && !Number.isFinite(options.minScore)) {
+    throw new Error(`${adapterId}: minScore must be finite`);
+  }
+}
+function assertNeo4jSearchKinds(kinds, transport, adapterId) {
+  if (!kinds?.length) return;
+  const supported = new Set(
+    transport === "rest" ? ["message", "observation", "entity"] : ["message", "observation", "entity", "preference", "reasoning-trace"]
+  );
+  const unsupported = [...new Set(kinds.filter((kind) => !supported.has(kind)))];
+  if (unsupported.length > 0) {
+    throw new Error(
+      `${adapterId}: Neo4j ${transport} cannot search memory kinds: ${unsupported.join(", ")}`
+    );
+  }
+}
+function assertNeo4jBridgeCapability(transport, kind, adapterId) {
+  if (transport === "bridge") return;
+  throw new Error(
+    `${adapterId}: Neo4j REST cannot write ${kind}; use transport="bridge" or map it to an entity/message`
+  );
+}
+async function writeNeo4jMemory(client, input, adapterId, transport, isolatedInstance) {
+  const scope = input.scope ?? {};
+  const sessionId = scope.sessionId ?? input.metadata?.sessionId;
+  assertNeo4jScopeSupported(
+    input.scope,
+    input.kind === "message" || input.kind === "observation" ? ["sessionId"] : input.kind === "reasoning-trace" ? ["sessionId", "runId"] : [],
+    adapterId,
+    `${input.kind} write`,
+    isolatedInstance
+  );
+  if (!isolatedInstance && input.kind === "reasoning-trace" && scope.sessionId !== void 0 && scope.runId !== void 0) {
+    throw new Error(
+      `${adapterId}: Neo4j reasoning write cannot enforce both sessionId and runId; provide one`
+    );
+  }
+  let result;
+  if (input.kind === "message" || input.kind === "observation") {
+    if (transport === "rest" && typeof sessionId !== "string") {
+      throw new Error(
+        `${adapterId}: Neo4j REST message writes require scope.sessionId as the conversation id`
+      );
+    }
+    const shortTerm = nested(client, ["shortTerm", "short_term"], client);
+    const metadata = { ...input.metadata, agentKnowledgeKind: input.kind };
+    result = await callRequired(
+      shortTerm,
+      ["addMessage"],
+      [
+        sessionId,
+        neo4jMessageRole(input.role),
+        input.text,
+        { metadata, conversationId: sessionId }
+      ]
+    );
+  } else if (input.kind === "entity") {
+    const longTerm = nested(client, ["longTerm", "long_term"], client);
+    result = await callRequired(
+      longTerm,
+      ["addEntity"],
+      [
+        input.entityName ?? input.title ?? input.text,
+        input.entityType ?? "custom",
+        neo4jEntityOptions(input)
+      ]
+    );
+  } else if (input.kind === "preference") {
+    assertNeo4jBridgeCapability(transport, input.kind, adapterId);
+    const longTerm = nested(client, ["longTerm", "long_term"], client);
+    result = await callRequired(
+      longTerm,
+      ["addPreference"],
+      [input.category ?? "general", input.text, neo4jPreferenceOptions(input)]
+    );
+  } else if (input.kind === "reasoning-trace") {
+    const reasoning = nested(client, ["reasoning"], client);
+    const conversationId = sessionId ?? scope.runId;
+    if (transport === "rest") {
+      if (typeof conversationId !== "string") {
+        throw new Error(
+          `${adapterId}: Neo4j REST reasoning writes require scope.sessionId or scope.runId`
+        );
+      }
+      result = await callRequired(
+        reasoning,
+        ["recordStep"],
+        [
+          {
+            conversationId,
+            reasoning: input.text,
+            actionTaken: stringMetadata(input.metadata, "action") ?? input.title ?? "memory",
+            result: stringMetadata(input.metadata, "result") ?? stringMetadata(input.metadata, "observation") ?? stringMetadata(input.metadata, "outcome")
+          }
+        ]
+      );
+    } else {
+      const trace = await callRequired(
+        reasoning,
+        ["startTrace"],
+        [
+          conversationId ?? stableId("session", input.text),
+          stringMetadata(input.metadata, "task") ?? input.title ?? input.text
+        ]
+      );
+      assertNeo4jWriteSucceeded(trace, adapterId, "startTrace");
+      const traceId = idFromResult(trace);
+      if (!traceId) throw new Error(`${adapterId}: Neo4j startTrace returned no trace id`);
+      try {
+        const step = await callRequired(
+          reasoning,
+          ["addStep"],
+          [
+            traceId,
+            {
+              thought: input.text,
+              observation: stringMetadata(input.metadata, "observation"),
+              action: stringMetadata(input.metadata, "action")
+            }
+          ]
+        );
+        assertNeo4jWriteSucceeded(step, adapterId, "addStep");
+      } catch (error) {
+        try {
+          await callRequired(
+            reasoning,
+            ["completeTrace"],
+            [traceId, { outcome: "agent-knowledge addStep failed", success: false }]
+          );
+        } catch (cleanupError) {
+          throw new AggregateError(
+            [error, cleanupError],
+            `${adapterId}: Neo4j reasoning step and trace cleanup failed`
+          );
+        }
+        throw error;
+      }
+      result = await callRequired(
+        reasoning,
+        ["completeTrace"],
+        [
+          traceId,
+          {
+            outcome: stringMetadata(input.metadata, "outcome"),
+            success: typeof input.metadata?.success === "boolean" ? input.metadata.success : void 0
+          }
+        ]
+      );
+    }
+  } else {
+    assertNeo4jBridgeCapability(transport, input.kind, adapterId);
+    result = await callRequired(
+      nested(client, ["longTerm", "long_term"], client),
+      ["addFact"],
+      [
+        input.subject ?? input.title ?? input.kind,
+        input.predicate ?? "states",
+        input.object ?? input.text
+      ]
+    );
+  }
+  assertNeo4jWriteSucceeded(result, adapterId, input.kind);
+  const id = idFromResult(result) ?? input.id ?? stableId(
+    "mem",
+    canonicalJson7({ adapterId, kind: input.kind, text: input.text, scope: input.scope ?? {} })
+  );
+  return {
+    accepted: true,
+    id,
+    uri: `memory://${adapterId}/${encodeURIComponent(id)}`,
+    kind: input.kind,
+    metadata: { provider: "neo4j-agent-memory", transport }
+  };
+}
+function assertNeo4jWriteSucceeded(value, adapterId, operation) {
+  const response = record(value);
+  if (!response) return;
+  const status = stringField3(response, ["status"])?.toLowerCase();
+  if (response.success === false || response.ok === false || response.isError === true || status === "failed" || status === "error") {
+    const nestedError = record(response.error);
+    const detail = stringField3(response, ["error", "message", "detail"]) ?? (nestedError ? stringField3(nestedError, ["message", "detail"]) : void 0);
+    throw new Error(`${adapterId}: Neo4j ${operation} failed${detail ? `: ${detail}` : ""}`);
+  }
+}
+async function searchNeo4jMemory(client, query, options, adapterId, transport, isolatedInstance) {
+  const limit = options.limit ?? 10;
+  if (limit === 0) return [];
+  assertNeo4jSearchKinds(options.kinds, transport, adapterId);
+  const onlyConversationKinds = options.kinds !== void 0 && options.kinds.length > 0 && options.kinds.every((kind) => kind === "message" || kind === "observation");
+  assertNeo4jScopeSupported(
+    options.scope,
+    onlyConversationKinds ? ["sessionId"] : [],
+    adapterId,
+    "search",
+    isolatedInstance
+  );
+  const searches = [];
+  const kinds = options.kinds;
+  const includeKind = (kind) => !kinds?.length || kinds.includes(kind);
+  const shortTerm = nested(client, ["shortTerm", "short_term"], {});
+  const longTerm = nested(client, ["longTerm", "long_term"], {});
+  const reasoning = nested(client, ["reasoning"], {});
+  const wantsMessages = includeKind("message") || includeKind("observation");
+  const hasConversation = typeof options.scope?.sessionId === "string";
+  if (transport === "rest" && wantsMessages && !hasConversation && options.kinds?.some((kind) => kind === "message" || kind === "observation")) {
+    throw new Error(
+      `${adapterId}: Neo4j REST message search requires scope.sessionId as the conversation id`
+    );
+  }
+  if (wantsMessages && (transport === "bridge" || hasConversation)) {
+    const messageKinds = options.kinds?.filter(
+      (kind) => kind === "message" || kind === "observation"
+    ) ?? ["message", "observation"];
+    searches.push(
+      callRequired(shortTerm, ["searchMessages"], [query, searchMessagesOptions(options)]).then(
+        (result) => normalizeHits(result, { ...options, kinds: messageKinds }, adapterId)
+      )
+    );
+  }
+  if (includeKind("entity")) {
+    searches.push(
+      callRequired(longTerm, ["searchEntities"], [query, searchEntitiesOptions(options)]).then(
+        (result) => normalizeHits(result, { ...options, kinds: ["entity"] }, adapterId)
+      )
+    );
+  }
+  if (transport === "bridge" && includeKind("preference")) {
+    searches.push(
+      callRequired(
+        longTerm,
+        ["searchPreferences"],
+        [query, searchPreferencesOptions(options)]
+      ).then((result) => normalizeHits(result, { ...options, kinds: ["preference"] }, adapterId))
+    );
+  }
+  if (transport === "bridge" && includeKind("reasoning-trace")) {
+    searches.push(
+      callRequired(reasoning, ["getSimilarTraces"], [query, similarTracesOptions(options)]).then(
+        (result) => normalizeHits(result, { ...options, kinds: ["reasoning-trace"] }, adapterId)
+      )
+    );
+  }
+  return mergeRankedMemoryHits(await Promise.all(searches), limit);
+}
+function holdoutBypassContext(query, options) {
+  return {
+    query,
+    ...options.scope !== void 0 ? { scope: options.scope } : {},
+    ...options.scope?.tags?.taskId !== void 0 ? { taskId: options.scope.tags.taskId } : {}
+  };
+}
+function searchMessagesOptions(options) {
+  return {
+    limit: options.limit,
+    sessionId: options.scope?.sessionId,
+    conversationId: options.scope?.sessionId,
+    threshold: options.minScore
+  };
+}
+function searchEntitiesOptions(options) {
+  return {
+    limit: options.limit,
+    type: options.metadata?.type
+  };
+}
+function searchPreferencesOptions(options) {
+  return {
+    limit: options.limit,
+    category: options.metadata?.category
+  };
+}
+function similarTracesOptions(options) {
+  return {
+    limit: options.limit,
+    successOnly: options.metadata?.successOnly
+  };
+}
+function assertNeo4jScopeSupported(scope, allowedKeys, adapterId, operation, isolatedInstance) {
+  if (isolatedInstance || !scope) return;
+  const allowed = new Set(allowedKeys);
+  const scopeKeys = [
+    "tenantId",
+    "userId",
+    "agentId",
+    "teamId",
+    "runId",
+    "sessionId",
+    "namespace"
+  ];
+  const supplied = scopeKeys.filter((key) => scope[key] !== void 0);
+  if (scope.tags && Object.keys(scope.tags).length > 0) supplied.push("tags");
+  const unsupported = supplied.filter((key) => !allowed.has(key));
+  if (unsupported.length === 0) return;
+  throw new Error(
+    `${adapterId}: Neo4j ${operation} cannot enforce scope fields: ${unsupported.join(", ")}; create a dedicated client and pass branchId`
+  );
+}
+function neo4jEntityOptions(input) {
+  return {
+    description: input.metadata?.description ?? input.title
+  };
+}
+function neo4jPreferenceOptions(input) {
+  return {
+    context: input.metadata?.context ?? input.title
+  };
+}
+async function callOptional(target, names, args) {
+  for (const name of names) {
+    const fn = target[name];
+    if (typeof fn === "function") return await fn.apply(target, args);
+  }
+  return void 0;
+}
+async function callRequired(target, names, args) {
+  for (const name of names) {
+    const fn = target[name];
+    if (typeof fn === "function") return await fn.apply(target, args);
+  }
+  throw new Error(`Neo4j agent-memory client is missing method ${names.join(" or ")}`);
+}
+function nested(target, names, fallback) {
+  for (const name of names) {
+    const value = target[name];
+    if (value && typeof value === "object") return value;
+  }
+  return fallback;
+}
+function normalizeHits(value, options, adapterId) {
+  const rawHits = rawHitsFrom(value);
+  return rawHits.map((hit, index) => normalizeHit(hit, index, adapterId)).filter((hit) => hit !== null).filter(
+    (hit) => options.minScore === void 0 ? true : (hit.normalizedScore ?? hit.score ?? 0) >= options.minScore
+  ).filter((hit) => options.kinds?.length ? options.kinds.includes(hit.kind) : true).slice(0, options.limit ?? 10);
+}
+function normalizeHit(value, index, adapterId) {
+  if (typeof value === "string") {
+    return {
+      id: stableId("mem", value),
+      uri: `memory://${adapterId}/${stableId("mem", value)}`,
+      kind: "fact",
+      text: value,
+      normalizedScore: index === 0 ? 1 : void 0
+    };
+  }
+  const obj = record(value);
+  if (!obj) return null;
+  const metadata = record(obj.metadata) ?? {};
+  const kind = memoryKind(
+    stringField3(metadata, ["agentKnowledgeKind"]) ?? stringField3(obj, ["kind", "type", "label"]),
+    obj
+  );
+  const text = textFromHitObject(obj, kind);
+  if (!text) return null;
+  const id = stringField3(obj, ["id", "memoryId", "uuid"]) ?? stableId("mem", text);
+  return {
+    id,
+    uri: stringField3(obj, ["uri"]) ?? `memory://${adapterId}/${encodeURIComponent(id)}`,
+    kind,
+    text,
+    title: stringField3(obj, ["title", "name", "task", "subject"]),
+    score: numberField3(obj, ["score"]),
+    normalizedScore: numberField3(obj, ["normalizedScore", "normalized_score"]),
+    confidence: numberField3(obj, ["confidence"]),
+    createdAt: stringField3(obj, ["createdAt", "created_at"]),
+    validUntil: stringField3(obj, ["validUntil", "valid_until"]),
+    lastVerifiedAt: stringField3(obj, ["lastVerifiedAt", "last_verified_at"]),
+    metadata: obj
+  };
+}
+function memoryKind(value, obj = {}) {
+  if (value === "message" || value === "entity" || value === "fact" || value === "preference" || value === "observation" || value === "reasoning-trace") {
+    return value;
+  }
+  if ("role" in obj && "content" in obj) return "message";
+  if ("name" in obj && ("type" in obj || "entityType" in obj)) return "entity";
+  if ("preference" in obj && "category" in obj) return "preference";
+  if ("task" in obj && "steps" in obj) return "reasoning-trace";
+  return "fact";
+}
+function rawHitsFrom(value) {
+  if (Array.isArray(value)) return value;
+  const obj = record(value);
+  if (!obj) return typeof value === "string" ? [value] : [];
+  if (Array.isArray(obj.hits)) return obj.hits;
+  if (Array.isArray(obj.results)) return obj.results;
+  if (Array.isArray(obj.messages)) return obj.messages;
+  if (Array.isArray(obj.recentMessages)) return obj.recentMessages;
+  if (Array.isArray(obj.observations)) return obj.observations;
+  if (Array.isArray(obj.reflections)) return obj.reflections;
+  if (typeof obj.content === "string" || typeof obj.text === "string") return [obj];
+  return [];
+}
+function textFromHitObject(obj, kind) {
+  const direct = stringField3(obj, [
+    "text",
+    "content",
+    "body",
+    "summary",
+    "preference",
+    "description"
+  ]);
+  if (direct) return direct;
+  if (kind === "entity") return stringField3(obj, ["name"]);
+  if (kind === "fact") {
+    const subject = stringField3(obj, ["subject"]);
+    const predicate = stringField3(obj, ["predicate"]);
+    const object = stringField3(obj, ["object", "obj"]);
+    if (subject && predicate && object) return `${subject} ${predicate} ${object}`;
+  }
+  if (kind === "reasoning-trace") {
+    const task = stringField3(obj, ["task"]);
+    const outcome = stringField3(obj, ["outcome"]);
+    return [task, outcome].filter(Boolean).join("\n") || void 0;
+  }
+  return void 0;
+}
+function normalizeConversationContextHits(value, options, adapterId) {
+  const obj = record(value);
+  if (!obj) return normalizeHits(value, options, adapterId);
+  const raw = [
+    ...rawHitsFrom(obj.reflections).map((hit) => tagContextHit(hit, "observation", "Reflection")),
+    ...rawHitsFrom(obj.observations).map((hit) => tagContextHit(hit, "observation", "Observation")),
+    ...rawHitsFrom(obj.recentMessages).map((hit) => tagContextHit(hit, "message"))
+  ];
+  return raw.length > 0 ? normalizeHits(raw, options, adapterId) : normalizeHits(value, options, adapterId);
+}
+function tagContextHit(value, kind, title) {
+  return value && typeof value === "object" && !Array.isArray(value) ? { kind, title, ...value } : { kind, title, content: value };
+}
+function renderHits(hits) {
+  return hits.map((hit) => hit.text).join("\n\n");
+}
+function idFromResult(value) {
+  const obj = record(value);
+  return obj ? stringField3(obj, ["id", "memoryId", "uuid"]) : void 0;
+}
+function record(value) {
+  return value && typeof value === "object" && !Array.isArray(value) ? value : null;
+}
+function stringField3(obj, names) {
+  for (const name of names) {
+    const value = obj[name];
+    if (typeof value === "string" && value.length > 0) return value;
+  }
+  return void 0;
+}
+function numberField3(obj, names) {
+  for (const name of names) {
+    const value = obj[name];
+    if (typeof value === "number" && Number.isFinite(value)) return value;
+  }
+  return void 0;
+}
+function neo4jMessageRole(role) {
+  return role === "tool" ? "assistant" : role ?? "user";
+}
+function stringMetadata(metadata, key) {
+  const value = metadata?.[key];
+  return typeof value === "string" && value.length > 0 ? value : void 0;
+}
+
+// src/memory/schemas.ts
+import { z } from "zod";
+var AgentMemoryKindSchema = z.enum([
+  "message",
+  "entity",
+  "fact",
+  "preference",
+  "observation",
+  "reasoning-trace"
+]);
+var AgentMemoryScopeSchema = z.object({
+  tenantId: z.string().optional(),
+  userId: z.string().optional(),
+  agentId: z.string().optional(),
+  teamId: z.string().optional(),
+  runId: z.string().optional(),
+  sessionId: z.string().optional(),
+  namespace: z.string().optional(),
+  tags: z.record(z.string(), z.string()).optional()
+});
+var AgentMemoryHitSchema = z.object({
+  id: z.string().min(1),
+  uri: z.string().min(1),
+  kind: AgentMemoryKindSchema,
+  text: z.string().min(1),
+  title: z.string().optional(),
+  score: z.number().optional(),
+  normalizedScore: z.number().optional(),
+  confidence: z.number().optional(),
+  createdAt: z.string().optional(),
+  validUntil: z.string().optional(),
+  lastVerifiedAt: z.string().optional(),
+  metadata: z.record(z.string(), z.unknown()).optional()
+});
+var AgentMemoryWriteInputSchema = z.object({
+  kind: AgentMemoryKindSchema,
+  text: z.string().min(1),
+  id: z.string().optional(),
+  title: z.string().optional(),
+  role: z.enum(["system", "user", "assistant", "tool"]).optional(),
+  entityName: z.string().optional(),
+  entityType: z.string().optional(),
+  category: z.string().optional(),
+  predicate: z.string().optional(),
+  subject: z.string().optional(),
+  object: z.string().optional(),
+  confidence: z.number().min(0).max(1).optional(),
+  scope: AgentMemoryScopeSchema.optional(),
+  metadata: z.record(z.string(), z.unknown()).optional()
+});
+
+export {
+  deterministicRng,
+  retrievalHoldoutConfigHash,
+  applyRetrievalHoldout,
+  emitRetrievalHoldoutBypass,
+  resetRetrievalHoldoutRegistry,
+  applySessionStickyRetrievalHoldout,
+  toOffPolicyTrajectory,
+  defaultGetMemoryContext,
+  renderMemoryContext,
+  createAgentMemoryBranch,
+  forkAgentMemoryBranchSnapshot,
+  buildAgentMemorySequencesFromBenchmarkCases,
+  runAgentMemoryExperiment,
+  buildAgentMemorySequenceScenarios,
+  agentMemorySequenceJudge,
+  createGraphitiMemoryAdapter,
+  graphitiMemoryAdapterIdentity,
+  runAgentMemoryImprovement,
+  createMem0MemoryAdapter,
+  mem0MemoryAdapterIdentity,
+  createNeo4jAgentMemoryAdapter,
+  AgentMemoryKindSchema,
+  AgentMemoryScopeSchema,
+  AgentMemoryHitSchema,
+  AgentMemoryWriteInputSchema
+};
+//# sourceMappingURL=chunk-UWOTQNBI.js.map