@tangle-network/agent-knowledge 5.0.4 → 6.1.0

package/dist/memory-C6KPRhoU.js

@@ -0,0 +1,4494 @@
+import { r as stableId, t as sha256 } from "./ids-DRqPZ42_.js";
+import { B as memoryWriteResultToSourceRecord, C as appendDurableJournalEvent, D as reconcileInterruptedMemoryPaidCalls, E as readActiveAttemptJournal, O as reserveRecoveryAttempts, S as appendAttemptJournalEvent, T as hasSettledPaidCall, _ as memoryRecoveryDelayMs, b as runBoundedMemoryLifecycle, f as acquireAgentMemoryRunLease, g as createMemoryExecutionPool, u as scoreMemoryBenchmarkArtifact, v as releaseMemoryAdapterCreatedAfterAbort, w as assertNoInterruptedPaidCalls, x as sleepForMemoryRecovery, y as resolveMemoryCleanupTimeoutMs, z as memoryHitToSourceRecord } from "./benchmarks-CmW6iORW.js";
+import { randomUUID } from "node:crypto";
+import { dirname, join } from "node:path";
+import { canonicalJson, mulberry32 } from "@tangle-network/agent-eval";
+import { z } from "zod";
+import { compareOptimizationMethods, createRunCostLedger, fsCampaignStorage, heldoutSignificance, resolveRunDir, runCampaign, surfaceHash } from "@tangle-network/agent-eval/campaign";
+//#region src/immutable-ref.ts
+const SHA256_REF = /^sha256:[a-f0-9]{64}$/;
+const GIT_REF = /^git:[a-f0-9]{40}$/;
+function assertImmutableRef(value, label) {
+	if (typeof value !== "string" || !SHA256_REF.test(value) && !GIT_REF.test(value)) throw new Error(`${label} must be lowercase sha256:<64 hex> or git:<40 hex>`);
+}
+//#endregion
+//#region src/optimization.ts
+/**
+* Runs one complete agent-eval method over a serialized knowledge candidate.
+* The method receives train and selection data; agent-eval owns final scoring.
+*/
+async function runSerializedKnowledgeOptimization(options) {
+	assertCompleteOptimizationMethod(options.method);
+	assertImmutableRef(options.executionRef, "knowledge optimization executionRef");
+	const codec = options.codec ?? jsonCandidateCodec();
+	const baseline = normalizeCandidate(options.baseline, codec, "baseline");
+	const dispatchRef = [
+		"knowledge-optimization",
+		options.executionRef,
+		baseline.surfaceHash,
+		surfaceHash(options.method.name)
+	].join(":");
+	assertPartitionContent(options.trainScenarios, options.selectionScenarios, options.finalScenarios, options.scenarioFingerprint ?? scenarioContentFingerprint);
+	const method = canonicalCandidateMethod(options.method, codec);
+	const { baseline: _baseline, method: _method, trainScenarios, selectionScenarios, finalScenarios, dispatchCandidate, executionRef: _executionRef, codec: _codec, scenarioFingerprint: _scenarioFingerprint, ...comparisonOptions } = options;
+	const optimizationRunOptions = {
+		...comparisonOptions.reps !== void 0 ? { reps: comparisonOptions.reps } : {},
+		...comparisonOptions.resumable !== void 0 ? { resumable: comparisonOptions.resumable } : {},
+		...comparisonOptions.labeledStore !== void 0 ? { labeledStore: comparisonOptions.labeledStore } : {},
+		...comparisonOptions.captureSource !== void 0 ? { captureSource: comparisonOptions.captureSource } : {},
+		...comparisonOptions.captureSourceVersionHash !== void 0 ? { captureSourceVersionHash: comparisonOptions.captureSourceVersionHash } : {},
+		...comparisonOptions.maxConcurrency !== void 0 ? { maxConcurrency: comparisonOptions.maxConcurrency } : {},
+		...comparisonOptions.dispatchTimeoutMs !== void 0 ? { dispatchTimeoutMs: comparisonOptions.dispatchTimeoutMs } : {},
+		...comparisonOptions.repo !== void 0 ? { repo: comparisonOptions.repo } : {},
+		...comparisonOptions.tracing !== void 0 ? { tracing: comparisonOptions.tracing } : {},
+		...comparisonOptions.expectUsage !== void 0 ? { expectUsage: comparisonOptions.expectUsage } : {},
+		...comparisonOptions.now !== void 0 ? { now: comparisonOptions.now } : {},
+		...comparisonOptions.buildTraceWriter !== void 0 ? { buildTraceWriter: comparisonOptions.buildTraceWriter } : {},
+		...comparisonOptions.storage !== void 0 ? { storage: comparisonOptions.storage } : {},
+		...comparisonOptions.cellPlacement !== void 0 ? { cellPlacement: comparisonOptions.cellPlacement } : {},
+		...comparisonOptions.optimizationRunOptions ?? {},
+		dispatchRef
+	};
+	const comparison = await compareOptimizationMethods({
+		...comparisonOptions,
+		dispatchRef,
+		optimizationRunOptions,
+		methods: [method],
+		baselineSurface: baseline.surface,
+		trainScenarios: trainScenarios.map((scenario) => structuredClone(scenario)),
+		selectionScenarios: selectionScenarios.map((scenario) => structuredClone(scenario)),
+		testScenarios: finalScenarios.map((scenario) => structuredClone(scenario)),
+		dispatchWithSurface: async (surface, scenario, context) => {
+			const candidate = normalizeSurface(surface, codec, "candidate");
+			return dispatchCandidate({
+				candidate: structuredClone(candidate.value),
+				candidateSurface: candidate.surface,
+				candidateSurfaceHash: candidate.surfaceHash,
+				scenario,
+				context
+			});
+		}
+	});
+	const winner = normalizeSurface(comparison.best.winnerSurface, codec, "winner");
+	return {
+		methodName: options.method.name,
+		baseline,
+		winner,
+		comparison
+	};
+}
+function assertCompleteOptimizationMethod(method) {
+	const candidate = method;
+	if (!candidate || typeof candidate.name !== "string" || candidate.name.trim().length === 0 || typeof candidate.optimize !== "function") throw new Error("knowledge optimization requires a complete OptimizationMethod with a non-empty name and optimize()");
+}
+function jsonCandidateCodec() {
+	return {
+		serialize: (candidate) => canonicalJson(candidate),
+		parse(surface) {
+			let parsed;
+			try {
+				parsed = JSON.parse(surface);
+			} catch (error) {
+				throw new Error("serialized knowledge candidate is not valid JSON", { cause: error });
+			}
+			return parsed;
+		}
+	};
+}
+function jsonObjectCandidateCodec() {
+	const codec = jsonCandidateCodec();
+	return {
+		serialize: codec.serialize,
+		parse(surface) {
+			const candidate = codec.parse(surface);
+			if (!candidate || typeof candidate !== "object" || Array.isArray(candidate)) throw new Error("serialized knowledge candidate must be a JSON object");
+			return candidate;
+		}
+	};
+}
+function scenarioContentFingerprint(scenario) {
+	const { id: _id, tags: _tags, split: _split, splitTag: _splitTag, ...content } = scenario;
+	return surfaceHash(canonicalJson(content));
+}
+function canonicalCandidateMethod(method, codec) {
+	return {
+		name: method.name,
+		async optimize(input) {
+			const result = await method.optimize(input);
+			const winner = normalizeSurface(result.winnerSurface, codec, `${method.name} winner`);
+			return {
+				...result,
+				winnerSurface: winner.surface
+			};
+		}
+	};
+}
+function normalizeCandidate(candidate, codec, label) {
+	let surface;
+	try {
+		surface = codec.serialize(candidate);
+	} catch (error) {
+		throw new Error(`${label} serializer failed`, { cause: error });
+	}
+	return normalizeSurface(surface, codec, label);
+}
+function normalizeSurface(surface, codec, label) {
+	if (typeof surface !== "string" || surface.trim().length === 0) throw new Error(`${label} must be a non-empty serialized string`);
+	let value;
+	try {
+		value = codec.parse(surface);
+	} catch (error) {
+		const detail = error instanceof Error ? `: ${error.message}` : "";
+		throw new Error(`${label} parser failed${detail}`, { cause: error });
+	}
+	let canonicalSurface;
+	try {
+		canonicalSurface = codec.serialize(value);
+	} catch (error) {
+		throw new Error(`${label} serializer failed after parsing`, { cause: error });
+	}
+	if (typeof canonicalSurface !== "string" || canonicalSurface.trim().length === 0) throw new Error(`${label} serializer must return a non-empty string`);
+	if (codec.serialize(codec.parse(canonicalSurface)) !== canonicalSurface) throw new Error(`${label} codec must round-trip to one canonical surface`);
+	return {
+		value: structuredClone(value),
+		surface: canonicalSurface,
+		surfaceHash: surfaceHash(canonicalSurface)
+	};
+}
+function assertPartitionContent(train, selection, final, fingerprint) {
+	if (!fingerprint) return;
+	const owner = /* @__PURE__ */ new Map();
+	for (const [name, scenarios] of [
+		["train", train],
+		["selection", selection],
+		["final", final]
+	]) for (const scenario of scenarios) {
+		const identity = fingerprint(scenario);
+		if (typeof identity !== "string" || identity.trim().length === 0) throw new Error(`scenarioFingerprint returned no identity for '${scenario.id}'`);
+		const prior = owner.get(identity);
+		if (prior) {
+			const scope = prior.partition === name ? `${name} partition duplicates` : `${prior.partition}/${name} partitions duplicate`;
+			throw new Error(`serialized knowledge optimization ${scope} scenario content at '${prior.scenarioId}'/'${scenario.id}'`);
+		}
+		owner.set(identity, {
+			partition: name,
+			scenarioId: scenario.id
+		});
+	}
+}
+//#endregion
+//#region src/memory/holdout.ts
+/**
+* Deterministic uniform [0,1) for assignment draws. The sha256 key derivation is ours — it makes
+* every draw replayable from the logged keys alone (design rule D5) — while the generator core is
+* the substrate's `mulberry32` (@tangle-network/agent-eval statistics vocabulary), seeded with the
+* top 32 bits of the digest, so the statistical machinery is reused rather than forked.
+*/
+function deterministicRng(key) {
+	return mulberry32(Number.parseInt(sha256(key).slice(0, 8), 16))();
+}
+function canonicalJson$1(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$1).join(",")}]`;
+	if (value !== null && typeof value === "object") return `{${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$1(v)}`).join(",")}}`;
+	return JSON.stringify(value);
+}
+/**
+* Value-hash of the knobs that DEFINE the experiment (epsilon + watchlist, order-independent).
+* Everything else on the config (callbacks, attribution stamps, privacy flags) does not change
+* which assignments are drawn, so it stays out of the hash.
+*/
+function retrievalHoldoutConfigHash(config) {
+	return sha256(canonicalJson$1({
+		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);
+	}
+}
+/**
+* Pure per-call holdout: takes post-filter hits, returns delivered hits plus the log event
+* and the next session state. Suppression only removes items (no backfill), and it happens
+* before rendering so a drop session's context is byte-identical to a natural smaller retrieval.
+*/
+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) {
+		session = (ctx.session?.sessionId === sessionId ? ctx.session : void 0) ?? {
+			sessionId,
+			callCount: 0,
+			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 picked = candidates[Math.min(Math.floor(rng(`${session.sessionId}#pick`) * candidates.length), candidates.length - 1)];
+		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 } : {}
+	};
+}
+/** Fields shared by randomized and bypass events: identity, attribution, config echo, eligibility. */
+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$1(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 } : {}
+	};
+}
+/**
+* Logs a holdout event for adapter context paths that answer WITHOUT going through the
+* search→render seam (Neo4j short-term conversation context, raw-string getContext results),
+* so a consumer with a holdout configured still sees every call and the fraction-under-experiment
+* denominator stays honest instead of silently losing these calls. No suppression is applied:
+* dropping is only meaningful for retrieved memory hits, never for conversation context.
+*/
+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;
+}
+const DEFAULT_MAX_TRACKED_SESSIONS = 1e4;
+const sessionRegistry = /* @__PURE__ */ new Map();
+/**
+* Clears all sticky-session state. For test isolation and experiment-epoch boundaries;
+* sessions in flight afterwards re-draw deterministically (same rng keys), so with the default
+* rng a reset is invisible in the logs unless eligibility sets changed in between.
+*/
+function resetRetrievalHoldoutRegistry() {
+	sessionRegistry.clear();
+}
+/**
+* Convenience wrapper that threads session state internally, keyed by the VALUE of the
+* experiment-defining knobs (configHash = epsilon + sorted watchlist) plus sessionId, so a fresh
+* config object per call — the natural pattern when options are built inline — keeps full
+* stickiness. Distinct experiments never share session state; two config objects with the same
+* epsilon/watchlist are the same experiment by definition.
+*/
+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;
+}
+/**
+* Maps retrieval-dropout events onto one `OffPolicyTrajectory` per session for use with
+* `inverseProbabilityWeighting`, `selfNormalizedImportanceWeighting`, or `doublyRobust`.
+* Randomization occurs once per session: the arm is selected with P(dropout) = epsilon and
+* the sticky target is drawn once,
+* uniformly over watchlist ∩ E at the session's first intersecting call.
+*
+* Session-level action space and behavior probabilities (they sum to 1 by construction):
+* - full delivery: `1 - epsilon`;
+* - drop candidate i of k = |watchlist ∩ E_first|: `epsilon / k` each (the draw event's logged
+*   `dropPropensity`);
+* - sessions whose eligibility sets never intersect the watchlist: probability 1, because full
+*   delivery was certain in either arm.
+*
+* Per-call events are repeated observations WITHIN one session-level randomization; per-call
+* IPW is statistically invalid for this design (per-call "propensities" imply an action
+* distribution summing to more than 1 and bias IPS downward). Calls where the sticky target is
+* absent from E, and adapter bypass calls, fold into the session summary (callCount /
+* bypassCallCount) instead of generating independent propensities.
+*
+* Join contract: `rewards` is keyed by `sessionIdHash` (sha256(sessionId) first 16 hex; compute
+* the same prefix over the outcome table's session ids, or log with
+* `includePlaintextIdentifiers: true` and join on raw ids upstream). Events are grouped per
+* (configHash, sessionIdHash) so different experiment configs are never pooled. Mixed-exposure
+* sessions (arm or target disagreement, e.g. after registry eviction) are excluded from the
+* trajectories and surfaced in `excluded` for analysis.
+*/
+function toOffPolicyTrajectory(events, options) {
+	if (options.qHatChosen === void 0 !== (options.vHatTarget === void 0)) throw new Error("qHatChosen and vHatTarget must be supplied together");
+	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`);
+		const qHatChosen = options.qHatChosen?.(summary);
+		const vHatTarget = options.vHatTarget?.(summary);
+		trajectories.push({
+			runId,
+			reward,
+			behaviorProb,
+			targetProb: options.targetProb?.(summary) ?? (summary.droppedId === null ? 1 : 0),
+			...options.qHatChosen === void 0 ? {} : { qHatChosen: qHatChosen ?? null },
+			...options.vHatTarget === void 0 ? {} : { vHatTarget: vHatTarget ?? null }
+		});
+		sessions.push(summary);
+	}
+	return {
+		trajectories,
+		sessions,
+		excluded,
+		unattributableEvents
+	};
+}
+//#endregion
+//#region 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");
+}
+//#endregion
+//#region src/memory/rank.ts
+/** Merges independently ranked memory lists without letting the first unscored list dominate. */
+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;
+}
+//#endregion
+//#region src/memory/branch.ts
+const DEFAULT_POLICY = {
+	read: ["private"],
+	write: "private"
+};
+const adapterLeases = /* @__PURE__ */ new WeakMap();
+/**
+* Isolates one candidate branch and records accepted writes for durable resume
+* or replay into a child branch, including a child backed by another provider.
+*/
+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 && canonicalJson(stripUndefined$1(options.policy)) !== canonicalJson(stripUndefined$1(snapshot.policy))) throw new Error("memory branch snapshot policy cannot change during resume; fork it instead");
+	if (snapshot && options.baseScope && canonicalJson(stripUndefined$1(options.baseScope)) !== canonicalJson(stripUndefined$1(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$3(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) => canonicalJson(stripUndefined$1(mergeScopes$3(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$3(baseScope, entry.input.scope);
+		touchedScopes.set(canonicalJson(stripUndefined$1(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);
+		operation.then(() => active.delete(operation), () => active.delete(operation));
+		return operation;
+	};
+	const trackRead = (operation) => {
+		reads.add(operation);
+		operation.then(() => reads.delete(operation), () => reads.delete(operation));
+		return track(operation);
+	};
+	const flushWrites = async () => {
+		const failures = (await Promise.allSettled([...pending])).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 failures = (await Promise.allSettled([...precedingWrites, ...precedingReads])).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$3(baseScope, searchOptions.scope);
+				const scopes = policy.read.map((visibility) => physicalScope(branchId, logicalScope, visibility));
+				return mergeRankedMemoryHits(await Promise.all(scopes.map(async (scope) => {
+					return (await options.adapter.search(query, {
+						...searchOptions,
+						scope,
+						holdout: void 0
+					})).map((hit) => ({
+						...hit,
+						metadata: {
+							...hit.metadata,
+							memoryBranchId: branchId,
+							memoryVisibility: scope.tags?.memoryVisibility
+						}
+					}));
+				})), 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$3(baseScope, logicalInput.scope);
+			if (allowedWriteScopeKeys && !allowedWriteScopeKeys.has(canonicalJson(stripUndefined$1(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(canonicalJson(stripUndefined$1(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);
+			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$3(baseScope, scope) : void 0;
+				const logicalScopes = /* @__PURE__ */ new Map();
+				if (requestedScope) {
+					logicalScopes.set(canonicalJson(stripUndefined$1(requestedScope)), requestedScope);
+					for (const touched of touchedScopes.values()) if (scopeMatches(touched, requestedScope)) logicalScopes.set(canonicalJson(stripUndefined$1(touched)), touched);
+				} else if (touchedScopes.size > 0) for (const [key, touched] of touchedScopes) logicalScopes.set(key, touched);
+				else logicalScopes.set(canonicalJson(stripUndefined$1(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(canonicalJson(stripUndefined$1(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$3(baseScope, journal[index].input.scope);
+						const physical = physicalScope(branchId, logical, policy.write);
+						if (clearedPhysicalScopes.has(canonicalJson(stripUndefined$1(physical)))) journal.splice(index, 1);
+					}
+					for (const [key, touched] of touchedScopes) {
+						const physical = physicalScope(branchId, touched, policy.write);
+						if (clearedPhysicalScopes.has(canonicalJson(stripUndefined$1(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;
+}
+/** Replays a durable journal into a fresh provider 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$3(options.snapshot.baseScope, options.baseScope),
+		lifetime: options.lifetime ?? options.snapshot.lifetime
+	});
+	try {
+		for (const entry of options.snapshot.journal) if (!(await child.write(entry.input)).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 canonicalJson(stripUndefined$1({
+		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(canonicalJson(stripUndefined$1(payload)))}`
+	};
+}
+function assertSnapshotDigest(snapshot) {
+	const { digest, ...payload } = snapshot;
+	const actual = `sha256:${sha256(canonicalJson(stripUndefined$1(payload)))}`;
+	if (actual !== digest) throw new Error(`memory branch snapshot digest mismatch: ${digest} != ${actual}`);
+}
+function mergeScopes$3(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$1(value) {
+	if (Array.isArray(value)) return value.map(stripUndefined$1);
+	if (typeof value !== "object" || value === null) return value;
+	return Object.fromEntries(Object.entries(value).filter(([, child]) => child !== void 0).map(([key, child]) => [key, stripUndefined$1(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)]));
+}
+//#endregion
+//#region src/memory/experiment/validation.ts
+function assertMemorySequences(sequences) {
+	for (const sequence of sequences) {
+		assertNonEmptyString(sequence.family, `memory experiment sequence ${sequence.id} family`);
+		if (sequence.steps.length === 0) throw new Error(`memory experiment sequence ${sequence.id} has no steps`);
+		assertUnique(sequence.steps.map((step) => step.id), `step in sequence ${sequence.id}`);
+		let probeCount = 0;
+		for (const step of sequence.steps) {
+			for (const write of step.writes ?? []) {
+				assertNonEmptyString(write.text, `memory experiment write in ${sequence.id}/${step.id}`);
+				if (write.id !== void 0) assertNonEmptyString(write.id, `memory experiment write id in ${sequence.id}/${step.id}`);
+			}
+			assertUnique((step.probes ?? []).map((probe) => probe.id), `probe in sequence ${sequence.id} step ${step.id}`);
+			for (const probe of step.probes ?? []) {
+				probeCount += 1;
+				assertNonEmptyString(probe.query, `memory experiment probe query ${sequence.id}/${step.id}/${probe.id}`);
+				if (probe.limit !== void 0 && (!Number.isSafeInteger(probe.limit) || probe.limit <= 0)) throw new Error(`memory experiment probe limit ${sequence.id}/${step.id}/${probe.id} must be a positive safe integer`);
+				assertMemoryFactMatchers(probe.requiredFacts ?? [], `${sequence.id}/${step.id}/${probe.id} requiredFacts`);
+				assertMemoryFactMatchers(probe.forbiddenFacts ?? [], `${sequence.id}/${step.id}/${probe.id} forbiddenFacts`);
+				assertStringList(probe.expectedEventIds, `${sequence.id}/${step.id}/${probe.id} event ids`);
+				assertStringList(probe.expectedActorIds, `${sequence.id}/${step.id}/${probe.id} actor ids`);
+				if (probe.referenceAnswer !== void 0) assertNonEmptyString(probe.referenceAnswer, `memory experiment reference answer ${sequence.id}/${step.id}/${probe.id}`);
+				if (!((probe.requiredFacts?.length ?? 0) > 0 || (probe.forbiddenFacts?.length ?? 0) > 0 || (probe.expectedEventIds?.length ?? 0) > 0 || (probe.expectedActorIds?.length ?? 0) > 0 || Boolean(probe.referenceAnswer?.trim()))) 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$1(record) {
+	return Object.fromEntries(Object.entries(record).filter(([, value]) => value !== void 0));
+}
+function uniqueStrings$1(values) {
+	return [...new Set(values.filter((value) => typeof value === "string"))];
+}
+function stringArray$1(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`);
+}
+//#endregion
+//#region src/memory/experiment/cases.ts
+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$1({
+			...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$1({
+					...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 } : {}
+			}]
+		}]
+	}));
+}
+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`
+			};
+		}
+	};
+}
+//#endregion
+//#region src/memory/experiment/cost.ts
+function createAgentMemoryCostRecorder(input) {
+	let observedCostUsd = 0;
+	let receiptCount = 0;
+	return {
+		record(actualCostUsd) {
+			if (!Number.isFinite(actualCostUsd) || actualCostUsd < 0) throw new Error(`${input.operation}: observed external cost must be non-negative and finite`);
+			const next = observedCostUsd + actualCostUsd;
+			if (exceedsMaximum(next, input.maximumCostUsd)) throw new Error(`${input.operation}: observed external cost ${next} exceeds declared maximum ${input.maximumCostUsd}`);
+			observedCostUsd = next;
+			receiptCount += 1;
+		},
+		receipt(externalCallAttempted) {
+			const base = {
+				model: input.candidateRef,
+				inputTokens: 0,
+				outputTokens: 0
+			};
+			if (input.maximumCostUsd === 0 || !externalCallAttempted) return {
+				...base,
+				actualCostUsd: 0
+			};
+			if (receiptCount === 0) return {
+				...base,
+				costUnknown: true
+			};
+			return {
+				...base,
+				actualCostUsd: observedCostUsd
+			};
+		}
+	};
+}
+function exceedsMaximum(actual, maximum) {
+	const tolerance = Number.EPSILON * Math.max(1, Math.abs(actual), Math.abs(maximum)) * 8;
+	return actual - maximum > tolerance;
+}
+//#endregion
+//#region src/memory/experiment/execution-context.ts
+function createAgentMemoryExecutionContext(dispatch, sequence) {
+	const privateValues = memoryEvaluationPrivateValues(dispatch.cellId, sequence);
+	const signal = relayAbortWithoutReason(dispatch.signal);
+	const cost = Object.freeze({ async runPaidCall(input) {
+		return sanitizePaidCallResult(await dispatch.cost.runPaidCall({
+			...input,
+			execute: (sourceSignal, callId) => withRedactedAbortSignal(sourceSignal, (redactedSignal) => input.execute(redactedSignal, callId))
+		}), privateValues);
+	} });
+	return {
+		context: Object.freeze({
+			signal: signal.signal,
+			cost
+		}),
+		dispose: signal.dispose
+	};
+}
+function sanitizePaidCallResult(result, privateValues) {
+	if (result.succeeded) return Object.freeze({
+		succeeded: true,
+		callId: result.callId,
+		value: result.value,
+		receipt: sanitizeCostReceipt(result.receipt, privateValues)
+	});
+	return Object.freeze({
+		succeeded: false,
+		...result.callId === void 0 ? {} : { callId: result.callId },
+		error: sanitizeError(result.error, privateValues),
+		...result.receipt === void 0 ? {} : { receipt: sanitizeCostReceipt(result.receipt, privateValues) }
+	});
+}
+function sanitizeCostReceipt(receipt, privateValues) {
+	const { tags: _tags, phase: _phase, error, ...visible } = receipt;
+	return Object.freeze({
+		...visible,
+		...error === void 0 ? {} : { error: redactPrivateValues(error, privateValues) }
+	});
+}
+function sanitizeError(error, privateValues) {
+	const sanitized = new Error(redactPrivateValues(error.message, privateValues));
+	sanitized.name = redactPrivateValues(error.name, privateValues);
+	return sanitized;
+}
+async function withRedactedAbortSignal(source, run) {
+	const relay = relayAbortWithoutReason(source);
+	try {
+		return await run(relay.signal);
+	} finally {
+		relay.dispose();
+	}
+}
+function relayAbortWithoutReason(source) {
+	const controller = new AbortController();
+	const abort = () => controller.abort(memoryExecutionAbortError());
+	if (source.aborted) abort();
+	else source.addEventListener("abort", abort, { once: true });
+	return {
+		signal: controller.signal,
+		dispose() {
+			source.removeEventListener("abort", abort);
+		}
+	};
+}
+function memoryExecutionAbortError() {
+	const error = /* @__PURE__ */ new Error("memory execution aborted");
+	error.name = "AbortError";
+	return error;
+}
+function memoryEvaluationPrivateValues(cellId, sequence) {
+	const values = /* @__PURE__ */ new Set([cellId, sequence.id]);
+	collectUnknownStrings(sequence.metadata, values);
+	for (const step of sequence.steps) {
+		values.add(step.id);
+		collectUnknownStrings(step.metadata, values);
+		for (const probe of step.probes ?? []) {
+			values.add(probe.id);
+			values.add(probe.query);
+			if (probe.referenceAnswer !== void 0) values.add(probe.referenceAnswer);
+			for (const matcher of [...probe.requiredFacts ?? [], ...probe.forbiddenFacts ?? []]) {
+				values.add(matcher.id);
+				for (const expected of matcher.anyOf) values.add(expected);
+			}
+			for (const expected of probe.expectedEventIds ?? []) values.add(expected);
+			for (const expected of probe.expectedActorIds ?? []) values.add(expected);
+		}
+	}
+	return [...values].filter(Boolean).sort((left, right) => right.length - left.length);
+}
+function collectUnknownStrings(value, output, seen = /* @__PURE__ */ new WeakSet()) {
+	if (typeof value === "string") {
+		output.add(value);
+		return;
+	}
+	if (!value || typeof value !== "object" || seen.has(value)) return;
+	seen.add(value);
+	if (Array.isArray(value)) {
+		for (const item of value) collectUnknownStrings(item, output, seen);
+		return;
+	}
+	for (const [key, item] of Object.entries(value)) {
+		output.add(key);
+		collectUnknownStrings(item, output, seen);
+	}
+}
+function redactPrivateValues(value, privateValues) {
+	let redacted = value;
+	for (const privateValue of privateValues) redacted = redacted.split(privateValue).join("[redacted]");
+	return redacted;
+}
+//#endregion
+//#region src/memory/experiment/metrics.ts
+function rankAgentMemoryExperiment(candidates, scenarios, campaign, costByCandidate) {
+	const scenarioById = new Map(scenarios.map((scenario) => [scenario.id, scenario]));
+	return 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$1(cells.map((cell) => !cell.error && cell.artifact ? cell.artifact.score : 0)),
+			passRate: mean$1(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)
+		};
+	}).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 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$1(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$1(values) {
+	return values.length === 0 ? 0 : values.reduce((sum, value) => sum + value, 0) / values.length;
+}
+function format(value) {
+	return Number.isFinite(value) ? value.toFixed(4) : "0.0000";
+}
+function normalizeUsd(value) {
+	return Number(value.toFixed(12));
+}
+//#endregion
+//#region src/memory/experiment/runtime.ts
+var AgentMemoryCleanupError = class extends AggregateError {
+	constructor(errors, message) {
+		super(errors, message);
+		this.name = "AgentMemoryCleanupError";
+	}
+};
+function trackExternalMemoryCalls(adapter, onExternalCall) {
+	return {
+		id: adapter.id,
+		branchIsolation: adapter.branchIsolation,
+		search(query, options) {
+			onExternalCall();
+			return adapter.search.call(adapter, query, options);
+		},
+		getContext(query, options) {
+			onExternalCall();
+			return adapter.getContext.call(adapter, query, options);
+		},
+		write(input) {
+			onExternalCall();
+			return adapter.write.call(adapter, input);
+		},
+		...adapter.clear ? { clear(scope) {
+			onExternalCall();
+			return adapter.clear.call(adapter, scope);
+		} } : {},
+		...adapter.flush ? { flush() {
+			onExternalCall();
+			return adapter.flush.call(adapter);
+		} } : {},
+		...adapter.close ? { close() {
+			onExternalCall();
+			return adapter.close.call(adapter);
+		} } : {}
+	};
+}
+function mergeScopes$2(base, extra) {
+	return {
+		...base ?? {},
+		...extra ?? {},
+		tags: {
+			...base?.tags ?? {},
+			...extra?.tags ?? {}
+		}
+	};
+}
+function memoryExperimentBaseScope(options, candidate, sequenceId) {
+	return mergeScopes$2(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) => mergeScopes$2(step.scope, write.scope)),
+			...(step.probes ?? []).map((probe) => mergeScopes$2(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);
+}
+//#endregion
+//#region src/memory/experiment/recovery.ts
+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) if ((input.candidateById.get(attempt.candidateId).externalCostUsdPerSequence ?? 0) > 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 failures = (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 costRecorder = createAgentMemoryCostRecorder({
+			candidateRef: candidate.ref,
+			maximumCostUsd: recoveryCostUsd,
+			operation: `${candidate.id}: memory recovery`
+		});
+		const recover = async () => {
+			await recoverMemoryAttempt({
+				options: input.options,
+				candidate,
+				sequence,
+				attempt,
+				lease: input.lease,
+				onExternalCall: () => {
+					externalRecoveryAttempted = true;
+				},
+				recordExternalCost: (actualCostUsd) => {
+					externalRecoveryAttempted = true;
+					costRecorder.record(actualCostUsd);
+				}
+			});
+			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 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.ref,
+				tags,
+				maximumCharge: { externallyEnforcedMaximumUsd: recoveryCostUsd },
+				execute: recover,
+				receipt: () => costRecorder.receipt(externalRecoveryAttempted),
+				receiptFromError: () => costRecorder.receipt(externalRecoveryAttempted)
+			});
+			if (!paid.succeeded) throw paid.error;
+		}
+	})))).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, recordExternalCost } = 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,
+			purpose: "recovery",
+			signal: abortController.signal,
+			maximumCostUsd: candidate.externalRecoveryCostUsdPerAttempt ?? 0,
+			markExternalCall: onExternalCall,
+			recordExternalCost
+		}));
+		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);
+		await sleepForMemoryRecovery(memoryRecoveryDelayMs(adapter), () => 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(/* @__PURE__ */ 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", canonicalJson({
+		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 {
+		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;
+	if (!(typeof event === "object" && event !== null && (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")) 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`);
+}
+//#endregion
+//#region src/memory/experiment/cell.ts
+async function runSequenceCell(input) {
+	const { options, candidate, scenario, context, runIdentity, storage, attemptLogPath, lease } = input;
+	const cleanupBranches = options.cleanupBranches ?? true;
+	const costUsd = candidate.externalCostUsdPerSequence ?? 0;
+	if (!Number.isFinite(costUsd) || costUsd < 0) throw new Error(`${candidate.id}: externalCostUsdPerSequence must be a non-negative finite number`);
+	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}:${randomUUID()}`);
+	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 costRecorder = createAgentMemoryCostRecorder({
+		candidateRef: candidate.ref,
+		maximumCostUsd: costUsd,
+		operation: `${candidate.id}: memory sequence`
+	});
+	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,
+				purpose: "execute",
+				signal: context.signal,
+				maximumCostUsd: costUsd,
+				markExternalCall: () => {
+					externalCallAttempted = true;
+				},
+				recordExternalCost: (actualCostUsd) => {
+					externalCallAttempted = true;
+					costRecorder.record(actualCostUsd);
+				}
+			});
+			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 [ordinal, step] of scenario.sequence.steps.entries()) {
+				context.signal.throwIfAborted();
+				await lease.assertOwned();
+				await writeStep(memory, step);
+				await lease.assertOwned();
+				if (options.executeStep) {
+					const execution = createAgentMemoryExecutionContext(context, scenario.sequence);
+					try {
+						await options.executeStep({
+							memory,
+							candidateId: candidate.id,
+							step: executionStep(step, ordinal),
+							context: execution.context
+						});
+					} finally {
+						execution.dispose();
+					}
+				}
+				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$1(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(/* @__PURE__ */ 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 paid = await context.cost.runPaidCall({
+		callId: memoryAttemptCostCallId(attempt, "execute", 0),
+		actor: `agent-knowledge:memory-experiment:${candidate.id}`,
+		model: candidate.ref,
+		maximumCharge: { externallyEnforcedMaximumUsd: costUsd },
+		execute,
+		receipt: () => costRecorder.receipt(externalCallAttempted),
+		receiptFromError: () => costRecorder.receipt(externalCallAttempted)
+	});
+	if (!paid.succeeded) throw paid.error;
+	return paid.value;
+}
+function executionStep(step, ordinal) {
+	return {
+		ordinal,
+		...step.instruction !== void 0 ? { instruction: step.instruction } : {},
+		...step.scope !== void 0 ? { scope: structuredClone(step.scope) } : {}
+	};
+}
+async function writeStep(memory, step) {
+	const writes = (step.writes ?? []).map((write) => ({
+		...write,
+		scope: mergeScopes$2(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 = mergeScopes$2(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$1([...context.hits.map((hit) => hit.metadata?.eventId), ...context.hits.flatMap((hit) => stringArray$1(hit.metadata?.eventIds))]),
+			usedMemoryIds: context.hits.map((hit) => hit.id),
+			actorIds: uniqueStrings$1([...context.hits.map((hit) => hit.metadata?.actorId), ...context.hits.flatMap((hit) => stringArray$1(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));
+}
+//#endregion
+//#region src/memory/experiment/run.ts
+const MEMORY_EXPERIMENT_IMPLEMENTATION_REF = "agent-knowledge:memory-experiment:v6";
+/** Runs ordered, branch-isolated memory histories across candidate systems. */
+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`);
+		if (candidate.externalCostAccounting !== void 0 && candidate.externalCostAccounting !== "exact") throw new Error(`${candidate.id}: externalCostAccounting must be 'exact'`);
+		if (((candidate.externalCostUsdPerSequence ?? 0) > 0 || (candidate.externalRecoveryCostUsdPerAttempt ?? 0) > 0) && candidate.externalCostAccounting !== "exact") throw new Error(`${candidate.id}: positive external charges require exact cost accounting`);
+		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 ?? 3;
+	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", canonicalJson({
+		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 ?? 3
+	});
+	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)}\n`);
+	storage.write(rankingMarkdownPath, renderAgentMemoryExperimentRanking(rows, totalCostUsd, unrankedRecoveryCostUsd));
+	return {
+		campaign,
+		rows,
+		totalCostUsd,
+		unrankedRecoveryCostUsd,
+		leaderCandidateId: rows.find((row) => row.cellsFailed === 0)?.candidateId,
+		rankingJsonPath,
+		rankingMarkdownPath,
+		attemptLogPath,
+		recoveryLogPath
+	};
+}
+function memoryExperimentDispatchRef(options) {
+	return stableId("memory_experiment", canonicalJson({
+		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,
+			externalCostAccounting: candidate.externalCostAccounting ?? "exact"
+		})).sort((a, b) => a.id.localeCompare(b.id))
+	}));
+}
+//#endregion
+//#region src/memory/graphiti.ts
+const DEFAULT_GRAPHITI_INGESTION_TIMEOUT_MS = 12e4;
+/** Connects the official Graphiti MCP server without coupling to its Python internals. */
+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 = mergeScopes$1(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 = mergeScopes$1(options.defaultScope, input.scope);
+			const groupId = graphitiGroupId(id, scope);
+			const eventKey = canonicalJson(stripUndefined({
+				id: input.id,
+				kind: input.kind,
+				text: input.text,
+				title: input.title,
+				role: input.role,
+				metadata: input.metadata
+			}));
+			const episodeUuid = input.id === void 0 ? randomUUID() : deterministicUuid(`${id}:${groupId}:${eventKey}`);
+			const name = input.title ?? `${input.kind}:${input.id ?? stableId("event", eventKey)}`;
+			const sourceDescription = canonicalJson(stripUndefined({
+				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, mergeScopes$1(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 payload = graphitiPayload(await client.callTool({
+		name,
+		arguments: args
+	}));
+	if (isRecord$1(payload) && typeof payload.error === "string") throw new Error(`Graphiti ${name}: ${payload.error}`);
+	return payload;
+}
+function graphitiPayload(raw) {
+	if (!isRecord$1(raw)) return raw;
+	if (raw.isError === true) throw new Error(`Graphiti MCP: ${toolText(raw) || "tool call failed"}`);
+	if (isRecord$1(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$1(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$1).map((part) => typeof part.text === "string" ? part.text : "").filter(Boolean).join("\n");
+}
+function normalizeGraphitiFacts(raw, adapterId) {
+	return (isRecord$1(raw) && Array.isArray(raw.facts) ? raw.facts.filter(isRecord$1) : []).flatMap((fact) => {
+		const text = stringField$2(fact, ["fact", "text"]);
+		if (!text) return [];
+		const factId = stringField$2(fact, ["uuid", "id"]) ?? stableId("fact", canonicalJson(stripUndefined({
+			adapterId,
+			text,
+			fact
+		})));
+		const episodeUuids = stringArray(fact.episodes ?? fact.episode_uuids);
+		const score = numberField$2(fact, ["score", "relevance_score"]);
+		const normalizedScore = normalizedScoreOf(score);
+		return [{
+			id: factId,
+			uri: `memory://${adapterId}/fact/${factId}`,
+			kind: "fact",
+			text,
+			...stringField$2(fact, ["name"]) ? { title: stringField$2(fact, ["name"]) } : {},
+			...stringField$2(fact, ["created_at"]) ? { createdAt: stringField$2(fact, ["created_at"]) } : {},
+			...stringField$2(fact, ["invalid_at"]) ? { validUntil: stringField$2(fact, ["invalid_at"]) } : stringField$2(fact, ["expired_at"]) ? { validUntil: stringField$2(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) {
+	return (isRecord$1(raw) && Array.isArray(raw.nodes) ? raw.nodes.filter(isRecord$1) : []).flatMap((node) => {
+		const name = stringField$2(node, ["name"]);
+		const text = stringField$2(node, ["summary"]) ?? name;
+		if (!text) return [];
+		const nodeId = stringField$2(node, ["uuid", "id"]) ?? stableId("node", canonicalJson(stripUndefined({
+			adapterId,
+			text,
+			node
+		})));
+		const score = numberField$2(node, ["score", "relevance_score"]);
+		const normalizedScore = normalizedScoreOf(score);
+		return [{
+			id: nodeId,
+			uri: `memory://${adapterId}/entity/${nodeId}`,
+			kind: "entity",
+			text,
+			...name ? { title: name } : {},
+			...stringField$2(node, ["created_at"]) ? { createdAt: stringField$2(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) => stringArray(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 = stringArray(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$1);
+		const first = descriptions[0];
+		hit.metadata = {
+			...hit.metadata,
+			sourceEpisodes,
+			...provenanceIncomplete || !scan.complete ? { provenanceIncomplete: true } : {},
+			...first ?? {},
+			eventIds: uniqueStrings(descriptions.map((value) => value.eventId)),
+			actorIds: uniqueStrings(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$1(raw) || !Array.isArray(raw.episodes)) return [];
+	return raw.episodes.filter(isRecord$1).flatMap((episode) => {
+		const uuid = stringField$2(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(canonicalJson(stripUndefined({
+		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;
+	}
+}
+function mergeScopes$1(base, extra) {
+	return {
+		...base ?? {},
+		...extra ?? {},
+		tags: {
+			...base?.tags ?? {},
+			...extra?.tags ?? {}
+		}
+	};
+}
+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 stringField$2(value, keys) {
+	for (const key of keys) {
+		const field = value[key];
+		if (typeof field === "string" && field.length > 0) return field;
+	}
+}
+function numberField$2(value, keys) {
+	for (const key of keys) {
+		const field = value[key];
+		if (typeof field === "number" && Number.isFinite(field)) return field;
+	}
+}
+function normalizedScoreOf(score) {
+	return score !== void 0 && score >= 0 && score <= 1 ? score : void 0;
+}
+function isRecord$1(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function stripUndefined(value) {
+	if (Array.isArray(value)) return value.map(stripUndefined);
+	if (!isRecord$1(value)) return value;
+	return Object.fromEntries(Object.entries(value).filter(([, child]) => child !== void 0).map(([key, child]) => [key, stripUndefined(child)]));
+}
+function graphitiMemoryAdapterIdentity(options) {
+	if (typeof options.backendRef !== "string" || !options.backendRef.trim()) throw new Error("Graphiti backendRef must be a non-empty string");
+	return `sha256:${sha256(canonicalJson(stripUndefined(options)))}`;
+}
+//#endregion
+//#region src/memory/improvement/candidate.ts
+async function buildCandidate(options, config, hash) {
+	const id = `memory-config-${hash}`;
+	const built = await options.createCandidate({
+		config,
+		candidateId: id,
+		surfaceHash: hash
+	});
+	assertImmutableRef(built.ref, `${id}: ref`);
+	assertDeclaredCost(built.externalCostUsdPerSequence, `${id}: externalCostUsdPerSequence`);
+	assertDeclaredCost(built.externalRecoveryCostUsdPerAttempt, `${id}: externalRecoveryCostUsdPerAttempt`);
+	if (built.externalCostAccounting !== "exact") throw new Error(`${id}: memory improvement requires exact external cost accounting`);
+	return {
+		...built,
+		id,
+		ref: built.ref
+	};
+}
+async function buildRegisteredCandidate(options, storage, runDir, config, hash) {
+	const candidate = await buildCandidate(options, config, hash);
+	const path = join(runDir, "memory-candidate-identities", `${hash}.json`);
+	const record = {
+		surfaceHash: hash,
+		candidateRef: candidate.ref
+	};
+	const stored = storage.read(path);
+	if (stored !== void 0) {
+		let parsed;
+		try {
+			parsed = JSON.parse(stored);
+		} catch (error) {
+			throw new Error(`invalid memory candidate identity '${path}'`, { cause: error });
+		}
+		if (canonicalJson(parsed) !== canonicalJson(record)) throw new Error(`memory config '${hash}' changed candidate identity within the same improvement run`);
+		return candidate;
+	}
+	if (storage.exists(path)) throw new Error(`cannot read memory candidate identity '${path}'`);
+	storage.ensureDir(dirname(path));
+	storage.write(path, `${JSON.stringify(record, null, 2)}\n`);
+	return candidate;
+}
+function assertDeclaredCost(value, label) {
+	if (typeof value !== "number" || !Number.isFinite(value) || value < 0) throw new Error(`${label} must be a declared non-negative finite number`);
+}
+function experimentOptions(options, storage, lease) {
+	return {
+		storage,
+		resumable: options.resumable,
+		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,
+		acquireRunLease: async () => ({
+			assertOwned: () => lease.assertOwned(),
+			release() {}
+		}),
+		now: options.now
+	};
+}
+//#endregion
+//#region src/memory/improvement/types.ts
+const DEFAULT_CRITICAL_DIMENSIONS = [
+	"memory_stale_safe",
+	"memory_actor_recall",
+	"memory_event_recall"
+];
+//#endregion
+//#region src/memory/improvement/promotion.ts
+function decidePromotion(input) {
+	const { options, finalEvaluation } = input;
+	const baselineScores = finalEvaluation.pairs.map((pair) => pair.baseline.score);
+	const winnerScores = finalEvaluation.pairs.map((pair) => pair.winner.score);
+	const baselineScore = mean(baselineScores);
+	const winnerScore = mean(winnerScores);
+	if (input.unchanged) return {
+		status: "no-change",
+		reasons: ["optimization selected the baseline configuration"],
+		baselineScore,
+		winnerScore,
+		lift: 0,
+		criticalDimensions: []
+	};
+	const significance = heldoutSignificance({
+		before: baselineScores,
+		after: winnerScores,
+		cellIds: finalEvaluation.pairs.map((pair) => `${pair.sequenceId}:${pair.rep}`)
+	}, options.significance);
+	const tolerance = options.criticalDimensionTolerance ?? .05;
+	const criticalDimensions = (options.criticalDimensions ?? DEFAULT_CRITICAL_DIMENSIONS).map((dimension) => {
+		const expectedN = applicableSequenceCount(options.finalSequences, dimension) * (options.reps ?? 1);
+		const comparison = heldoutSignificance(pairedDimension(finalEvaluation, dimension), {
+			...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 = [];
+	const totalCost = input.optimization.comparison.totalCost;
+	if (!input.optimization.comparison.totalCost.accountingComplete && !options.allowIncompleteCostAccounting) reasons.push("optimization or final cost accounting is incomplete");
+	const optimizerSource = input.optimization.comparison.best.provenance?.source;
+	if (optimizerSource && optimizerSource.evidence !== "observed") reasons.push("external optimizer package identity was not observed");
+	if (totalCost.totalCostUsd > (options.maxTotalCostUsd ?? 0)) reasons.push(`total cost ${totalCost.totalCostUsd} exceeds the configured limit ${options.maxTotalCostUsd ?? 0}`);
+	if (!significance.significant) reasons.push(significance.fewRuns ? `only ${significance.n} paired final cells; more are required` : "final lift is not confidently above the promotion threshold");
+	if (winnerScore < (options.minFinalScore ?? 0)) reasons.push(`winner final score ${winnerScore} 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 final histories` : `critical dimension ${dimension.dimension} was measured on ${dimension.n}/${dimension.expectedN} applicable paired final cells`);
+	else if (dimension.regressed) reasons.push(`${dimension.dimension} may regress beyond ${tolerance}`);
+	return {
+		status: reasons.length === 0 ? "promote" : "hold",
+		reasons,
+		baselineScore,
+		winnerScore,
+		lift: winnerScore - baselineScore,
+		significance,
+		criticalDimensions
+	};
+}
+function normalizedPromotionPolicy(options) {
+	return {
+		significance: {
+			deltaThreshold: options.significance?.deltaThreshold ?? 0,
+			minProductiveRuns: options.significance?.minProductiveRuns ?? 3,
+			confidence: options.significance?.confidence ?? .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 ?? .05,
+		minFinalScore: options.minFinalScore ?? 0,
+		maxTotalCostUsd: options.maxTotalCostUsd ?? 0,
+		allowIncompleteCostAccounting: options.allowIncompleteCostAccounting ?? false
+	};
+}
+function pairedDimension(result, dimension) {
+	const applicable = result.pairs.filter((pair) => (pair.baseline.dimensionSampleCounts[dimension] ?? 0) > 0 && (pair.winner.dimensionSampleCounts[dimension] ?? 0) > 0);
+	return {
+		before: applicable.map((pair) => pair.baseline.dimensions[dimension]),
+		after: applicable.map((pair) => pair.winner.dimensions[dimension]),
+		cellIds: applicable.map((pair) => `${pair.sequenceId}:${pair.rep}`)
+	};
+}
+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 mean(values) {
+	return values.reduce((sum, value) => sum + value, 0) / values.length;
+}
+//#endregion
+//#region src/memory/improvement/identity.ts
+function assertMemoryImprovementIdentity(options, storage, runDir, serialize) {
+	const path = join(runDir, "memory-improvement-manifest.json");
+	const identity = {
+		experimentId: options.experimentId,
+		implementationRef: options.implementationRef,
+		method: options.method.name,
+		activationRef: options.activation?.ref ?? null,
+		baselineConfig: serialize(options.baselineConfig),
+		executeStepRef: options.executeStepRef ?? null,
+		cleanupBranches: options.cleanupBranches ?? true,
+		promotionPolicy: normalizedPromotionPolicy(options),
+		seed: options.seed ?? 42,
+		reps: options.reps ?? 1,
+		maxTotalCostUsd: options.maxTotalCostUsd ?? null,
+		maximumEvaluationCostUsd: options.maximumEvaluationCostUsd ?? null,
+		allowIncompleteCostAccounting: options.allowIncompleteCostAccounting ?? false,
+		trainSequences: options.trainSequences,
+		selectionSequences: options.selectionSequences,
+		finalSequences: options.finalSequences
+	};
+	const identityHash = surfaceHash(canonicalJson(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(join(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)}\n`);
+		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 || canonicalJson(manifest.identity) !== canonicalJson(identity)) throw new Error(`memory improvement run '${runDir}' does not match its persisted inputs or implementation`);
+}
+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);
+	if (first !== serialize(parse(first))) throw new Error("memory config serializer and parser must round-trip exactly");
+}
+function memorySequenceFingerprint(sequence) {
+	const { id: _id, split: _split, tags: _tags, ...content } = sequence;
+	return surfaceHash(canonicalJson(content));
+}
+//#endregion
+//#region src/memory/improvement/evaluation.ts
+function memoryConfigCodec(options) {
+	const serializeRaw = options.serializeConfig ?? ((config) => canonicalJson(config));
+	const parseRaw = options.parseConfig ?? ((surface) => JSON.parse(surface));
+	return {
+		serialize: (config) => serializeMemoryConfig(serializeRaw, config),
+		parse: (surface) => parseMemoryConfig(parseRaw, surface)
+	};
+}
+function memoryConfigScenarios(sequences) {
+	return sequences.map(memoryConfigScenario);
+}
+async function evaluateMemoryCandidate(input) {
+	await input.lease.assertOwned();
+	const artifactPath = memoryArtifactPath(input.runDir, input.surfaceHash, input.scenario, input.rep, input.seed);
+	const stored = readStoredMemoryArtifact(input.storage, artifactPath, {
+		surfaceHash: input.surfaceHash,
+		candidateRef: input.candidate.ref,
+		scenario: input.scenario,
+		rep: input.rep,
+		seed: input.seed
+	});
+	if (stored) {
+		if (input.final) writeStoredMemoryArtifact(input.storage, memoryFinalArtifactPath(input.runDir, input.surfaceHash, input.scenario, input.rep), storedMemoryArtifactRecord(input, stored));
+		return stored;
+	}
+	const evaluationCostLimit = input.options.maximumEvaluationCostUsd ?? 0;
+	const evaluationId = stableId("memory_eval", canonicalJson({
+		surfaceHash: input.surfaceHash,
+		sequence: memorySequenceFingerprint(input.scenario.sequence),
+		rep: input.rep,
+		seed: input.seed
+	}));
+	const paid = await input.cost.runPaidCall({
+		actor: "agent-knowledge:memory-config-evaluation",
+		model: input.candidate.ref,
+		signal: input.signal,
+		maximumCharge: { externallyEnforcedMaximumUsd: evaluationCostLimit },
+		execute: async () => {
+			const experiment = await runAgentMemoryExperiment({
+				...experimentOptions(input.options, input.storage, input.lease),
+				experimentId: `${input.options.experimentId}:${evaluationId}`,
+				experimentRunId: evaluationId,
+				sequences: [input.scenario.sequence],
+				candidates: [input.candidate],
+				runDir: join(input.runDir, "evaluations", evaluationId),
+				seed: input.seed,
+				reps: 1,
+				maxConcurrency: 1,
+				costCeiling: evaluationCostLimit,
+				costPhase: `memory.config.${input.surfaceHash}`
+			});
+			const cell = experiment.campaign.cells[0];
+			if (!cell || cell.error || cell.artifact.candidateId !== input.candidate.id) throw new Error(`${input.surfaceHash}/${input.scenario.sequenceId}: memory config evaluation did not complete`);
+			const cost = experiment.campaign.aggregates.cost;
+			return {
+				artifact: cell.artifact,
+				costUsd: cell.cached ? 0 : experiment.totalCostUsd,
+				cost
+			};
+		},
+		receipt: (value) => ({
+			model: input.candidate.ref,
+			inputTokens: value.cost.inputTokens,
+			outputTokens: value.cost.outputTokens,
+			...value.cost.reasoningTokens !== void 0 ? { reasoningTokens: value.cost.reasoningTokens } : {},
+			cachedTokens: value.cost.cachedTokens,
+			...value.cost.cacheWriteTokens !== void 0 ? { cacheWriteTokens: value.cost.cacheWriteTokens } : {},
+			actualCostUsd: value.costUsd,
+			costUnknown: !value.cost.accountingComplete,
+			usageUnknown: !value.cost.usageComplete
+		})
+	});
+	if (!paid.succeeded) throw paid.error;
+	await input.lease.assertOwned();
+	const record = storedMemoryArtifactRecord(input, paid.value.artifact);
+	writeStoredMemoryArtifact(input.storage, artifactPath, record);
+	if (input.final) writeStoredMemoryArtifact(input.storage, memoryFinalArtifactPath(input.runDir, input.surfaceHash, input.scenario, input.rep), record);
+	return paid.value.artifact;
+}
+function loadFinalEvaluation(input) {
+	const pairs = [];
+	const reps = input.options.reps ?? 1;
+	for (const sequence of input.options.finalSequences) {
+		const scenario = memoryConfigScenario(sequence);
+		for (let rep = 0; rep < reps; rep += 1) {
+			const baseline = readStoredMemoryArtifact(input.storage, memoryFinalArtifactPath(input.runDir, input.baselineSurfaceHash, scenario, rep), {
+				surfaceHash: input.baselineSurfaceHash,
+				candidateRef: input.baselineCandidateRef,
+				scenario,
+				rep
+			});
+			const winner = readStoredMemoryArtifact(input.storage, memoryFinalArtifactPath(input.runDir, input.winnerSurfaceHash, scenario, rep), {
+				surfaceHash: input.winnerSurfaceHash,
+				candidateRef: input.winnerCandidateRef,
+				scenario,
+				rep
+			});
+			if (!baseline || !winner) throw new Error(`memory final artifact is missing for sequence '${sequence.id}' repetition ${rep}`);
+			pairs.push({
+				sequenceId: sequence.id,
+				rep,
+				baseline,
+				winner
+			});
+		}
+	}
+	return {
+		manifestHash: surfaceHash(canonicalJson({
+			baselineSurfaceHash: input.baselineSurfaceHash,
+			baselineCandidateRef: input.baselineCandidateRef,
+			winnerSurfaceHash: input.winnerSurfaceHash,
+			winnerCandidateRef: input.winnerCandidateRef,
+			pairs
+		})),
+		baselineCandidateRef: input.baselineCandidateRef,
+		winnerCandidateRef: input.winnerCandidateRef,
+		pairs
+	};
+}
+function memoryArtifactPath(runDir, candidateSurfaceHash, scenario, rep, seed) {
+	return join(runDir, "memory-config-artifacts", candidateSurfaceHash, stableId("sequence", scenario.sequenceId), `rep-${rep}-${stableId("seed", String(seed))}.json`);
+}
+function memoryFinalArtifactPath(runDir, candidateSurfaceHash, scenario, rep) {
+	return join(runDir, "memory-final-artifacts", candidateSurfaceHash, stableId("sequence", scenario.sequenceId), `rep-${rep}.json`);
+}
+function memoryConfigScenario(sequence) {
+	return {
+		id: sequence.id,
+		kind: "agent-memory-config-search",
+		sequenceId: sequence.id,
+		sequence
+	};
+}
+function readStoredMemoryArtifact(storage, path, expected) {
+	const stored = storage.read(path);
+	if (stored === void 0) {
+		if (storage.exists(path)) throw new Error(`cannot read memory config artifact '${path}'`);
+		return;
+	}
+	let record;
+	try {
+		record = JSON.parse(stored);
+	} catch (error) {
+		throw new Error(`invalid memory config artifact '${path}'`, { cause: error });
+	}
+	if (!record || typeof record !== "object" || Array.isArray(record)) throw new Error(`invalid memory config artifact '${path}'`);
+	const value = record;
+	if (!hasExactKeys(record, [
+		"surfaceHash",
+		"candidateRef",
+		"sequenceFingerprint",
+		"sequenceId",
+		"rep",
+		"seed",
+		"artifact"
+	]) || value.surfaceHash !== expected.surfaceHash || value.candidateRef !== expected.candidateRef || value.sequenceFingerprint !== memorySequenceFingerprint(expected.scenario.sequence) || value.sequenceId !== expected.scenario.sequenceId || value.rep !== expected.rep || !Number.isSafeInteger(value.seed) || expected.seed !== void 0 && value.seed !== expected.seed) throw new Error(`memory config artifact '${path}' does not match its evaluation cell`);
+	return parseMemoryArtifact(value.artifact, `memory-config-${expected.surfaceHash}`, expected.scenario.sequenceId, path);
+}
+function writeStoredMemoryArtifact(storage, path, record) {
+	const serialized = `${JSON.stringify(record, null, 2)}\n`;
+	const existing = storage.read(path);
+	if (existing !== void 0) {
+		if (canonicalJson(JSON.parse(existing)) !== canonicalJson(record)) throw new Error(`memory config artifact '${path}' conflicts with durable content`);
+		return;
+	}
+	if (storage.exists(path)) throw new Error(`cannot read memory config artifact '${path}'`);
+	storage.ensureDir(dirname(path));
+	storage.write(path, serialized);
+}
+function storedMemoryArtifactRecord(input, artifact) {
+	return {
+		surfaceHash: input.surfaceHash,
+		candidateRef: input.candidate.ref,
+		sequenceFingerprint: memorySequenceFingerprint(input.scenario.sequence),
+		sequenceId: input.scenario.sequenceId,
+		rep: input.rep,
+		seed: input.seed,
+		artifact
+	};
+}
+function parseMemoryArtifact(value, candidateId, sequenceId, path) {
+	if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error(`memory config artifact '${path}' has no artifact`);
+	const artifact = value;
+	if (artifact.candidateId !== candidateId || artifact.sequenceId !== sequenceId || typeof artifact.score !== "number" || !Number.isFinite(artifact.score) || artifact.score < 0 || artifact.score > 1 || typeof artifact.passed !== "boolean" || !isFiniteNumberRecord(artifact.dimensions) || !isNonnegativeIntegerRecord(artifact.dimensionSampleCounts) || !Array.isArray(artifact.probes) || typeof artifact.branchDigest !== "string" || !artifact.branchDigest || typeof artifact.journalEntries !== "number" || !Number.isSafeInteger(artifact.journalEntries) || artifact.journalEntries < 0 || typeof artifact.durationMs !== "number" || !Number.isFinite(artifact.durationMs) || artifact.durationMs < 0) throw new Error(`memory config artifact '${path}' is malformed`);
+	return artifact;
+}
+function isFiniteNumberRecord(value) {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+	return Object.values(value).every((entry) => typeof entry === "number" && Number.isFinite(entry));
+}
+function isNonnegativeIntegerRecord(value) {
+	return isFiniteNumberRecord(value) && Object.values(value).every((entry) => Number.isSafeInteger(entry) && entry >= 0);
+}
+function hasExactKeys(value, expected) {
+	const keys = Object.keys(value);
+	return keys.length === expected.length && keys.every((key) => expected.includes(key));
+}
+//#endregion
+//#region src/memory/improvement/activation.ts
+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 } : {}
+	};
+}
+async function assertActivatedMemoryWinner(input) {
+	const activationDriver = input.options.activation;
+	if (!activationDriver) throw new Error("an activated memory journal requires its activation driver");
+	await input.lease.assertOwned();
+	const currentConfig = await runBoundedMemoryLifecycle({
+		operation: `${activationDriver.ref}: confirm active memory configuration`,
+		timeoutMs: input.options.activationTimeoutMs ?? 6e4,
+		run: () => activationDriver.readCurrent()
+	});
+	await input.lease.assertOwned();
+	const currentHash = surfaceHash(memoryConfigCodec(input.options).serialize(currentConfig));
+	if (currentHash !== input.result.winnerSurfaceHash) throw new Error(`memory activation target '${activationDriver.ref}' drifted from measured winner '${input.result.winnerSurfaceHash}' to '${currentHash}'`);
+}
+async function activateMemoryWinner(input) {
+	const activationDriver = input.options.activation;
+	const activationTimeoutMs = input.options.activationTimeoutMs ?? 6e4;
+	if (!input.hadPreparedEvent) {
+		await input.lease.assertOwned();
+		input.storage.ensureDir(input.activationJournalDir);
+		appendMemoryActivationEvent(input.storage, input.activationJournalPath, {
+			...input.activationEventIdentity,
+			status: "prepared",
+			recordedAt: (input.options.now ?? (() => /* @__PURE__ */ new Date()))().toISOString()
+		});
+	}
+	await input.lease.assertOwned();
+	const currentConfig = await runBoundedMemoryLifecycle({
+		operation: `${activationDriver.ref}: read current memory configuration`,
+		timeoutMs: activationTimeoutMs,
+		run: () => activationDriver.readCurrent()
+	});
+	await input.lease.assertOwned();
+	const codec = memoryConfigCodec(input.options);
+	const currentHash = surfaceHash(codec.serialize(currentConfig));
+	if (currentHash !== input.result.baselineSurfaceHash && currentHash !== input.result.winnerSurfaceHash) throw new Error(`memory activation target '${activationDriver.ref}' changed concurrently; expected '${input.result.baselineSurfaceHash}' or '${input.result.winnerSurfaceHash}', found '${currentHash}'`);
+	let outcome;
+	if (currentHash === input.result.winnerSurfaceHash) {
+		outcome = input.hadPreparedEvent ? "recovered" : "already-current";
+		input.result.activation.status = "recovered";
+	} else {
+		let compareError;
+		try {
+			await runBoundedMemoryLifecycle({
+				operation: `${activationDriver.ref}: activate memory configuration`,
+				timeoutMs: activationTimeoutMs,
+				run: () => activationDriver.compareAndSet({
+					activationId: input.result.activation.id,
+					expectedConfig: input.result.baselineConfig,
+					expectedSurfaceHash: input.result.baselineSurfaceHash,
+					config: input.result.winnerConfig,
+					surfaceHash: input.result.winnerSurfaceHash,
+					decision: input.result.decision,
+					optimization: input.result.optimization,
+					finalEvaluation: input.result.finalEvaluation
+				})
+			});
+		} catch (error) {
+			compareError = error;
+		}
+		await input.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 '${input.result.activation.id}' failed and its live state could not be confirmed`);
+			throw error;
+		}
+		await input.lease.assertOwned();
+		const observedHash = surfaceHash(codec.serialize(observedConfig));
+		if (observedHash !== input.result.winnerSurfaceHash) {
+			const mismatch = /* @__PURE__ */ new Error(`memory activation '${input.result.activation.id}' did not install the measured winner; found '${observedHash}'`);
+			if (compareError) throw new AggregateError([compareError, mismatch], `memory activation '${input.result.activation.id}' failed without applying the measured winner`);
+			throw mismatch;
+		}
+		outcome = compareError ? "recovered" : "applied";
+		input.result.activation.status = compareError ? "recovered" : "activated";
+	}
+	await input.lease.assertOwned();
+	appendMemoryActivationEvent(input.storage, input.activationJournalPath, {
+		...input.activationEventIdentity,
+		status: "activated",
+		outcome,
+		recordedAt: (input.options.now ?? (() => /* @__PURE__ */ new Date()))().toISOString()
+	});
+}
+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`);
+	const expectedKeys = [
+		...Object.keys(expected),
+		"status",
+		"recordedAt",
+		...event.status === "activated" ? ["outcome"] : []
+	];
+	const actualKeys = Object.keys(event);
+	if (actualKeys.length !== expectedKeys.length || actualKeys.some((key) => !expectedKeys.includes(key))) throw new Error(`invalid memory activation journal '${path}' line ${line} fields`);
+	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;
+}
+//#endregion
+//#region src/memory/improvement/output.ts
+function writeMemoryImprovementResult(storage, experimentId, result) {
+	storage.write(result.resultJsonPath, `${JSON.stringify({
+		experimentId,
+		baselineSurfaceHash: result.baselineSurfaceHash,
+		winnerSurfaceHash: result.winnerSurfaceHash,
+		baselineSurface: result.baselineSurface,
+		winnerSurface: result.winnerSurface,
+		decision: result.decision,
+		method: result.optimization.methodName,
+		comparison: result.optimization.comparison,
+		finalEvaluation: result.finalEvaluation,
+		activation: result.activation,
+		totalCostUsd: result.totalCostUsd
+	}, null, 2)}\n`);
+}
+//#endregion
+//#region src/memory/improvement/validation.ts
+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`);
+	assertImmutableRef(options.implementationRef, "memory improvement implementationRef");
+	if (!options.method || typeof options.method.name !== "string" || !options.method.name.trim() || typeof options.method.optimize !== "function") throw new Error("memory improvement method must be a complete OptimizationMethod");
+	if (typeof options.createCandidate !== "function") throw new Error("memory improvement createCandidate must be a function");
+	if (options.activation !== void 0) {
+		assertImmutableRef(options.activation.ref, "memory improvement activation.ref");
+		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");
+	}
+	if (options.executeStep) assertImmutableRef(options.executeStepRef, "memory improvement executeStepRef");
+	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");
+	for (const [name, value] of [
+		["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`);
+	for (const [name, value] of [["maxTotalCostUsd", options.maxTotalCostUsd]]) if (value !== void 0 && (!Number.isFinite(value) || value < 0)) throw new Error(`memory improvement ${name} must be a non-negative finite number`);
+	if (options.maximumEvaluationCostUsd !== void 0 && (!Number.isFinite(options.maximumEvaluationCostUsd) || options.maximumEvaluationCostUsd <= 0)) throw new Error("memory improvement maximumEvaluationCostUsd must be a positive finite number");
+	if ((options.maxTotalCostUsd ?? 0) > 0 && options.maximumEvaluationCostUsd === void 0) throw new Error("memory improvement maximumEvaluationCostUsd is required when a spend limit is configured");
+	if (options.allowIncompleteCostAccounting !== void 0 && typeof options.allowIncompleteCostAccounting !== "boolean") throw new Error("memory improvement allowIncompleteCostAccounting must be boolean");
+	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.minFinalScore;
+	if (minimum !== void 0 && (!Number.isFinite(minimum) || minimum < 0 || minimum > 1)) throw new Error("memory improvement minFinalScore must be between 0 and 1");
+	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");
+	assertIndependentSequences(options.trainSequences, options.selectionSequences, options.finalSequences);
+}
+function assertIndependentSequences(train, selection, final) {
+	if (train.length === 0) throw new Error("memory improvement requires training sequences");
+	if (selection.length === 0) throw new Error("memory improvement requires selection sequences");
+	if (final.length < 2) throw new Error("memory improvement requires at least 2 final sequences");
+	const ids = /* @__PURE__ */ new Map();
+	const content = /* @__PURE__ */ new Map();
+	for (const [split, sequences] of [
+		["train", train],
+		["selection", selection],
+		["final", final]
+	]) for (const sequence of sequences) {
+		const priorId = ids.get(sequence.id);
+		if (priorId) throw new Error(`memory improvement ${priorId}/${split} sequences share id '${sequence.id}'`);
+		ids.set(sequence.id, split);
+		const fingerprint = memorySequenceFingerprint(sequence);
+		const priorContent = content.get(fingerprint);
+		if (priorContent) throw new Error(`memory improvement ${priorContent.split}/${split} histories duplicate content at '${priorContent.sequenceId}'/'${sequence.id}'`);
+		content.set(fingerprint, {
+			split,
+			sequenceId: sequence.id
+		});
+	}
+}
+//#endregion
+//#region src/memory/improvement/run.ts
+/** Optimizes memory configuration with an external method and activates only a fresh final win. */
+async function runAgentMemoryImprovement(options) {
+	assertMemoryImprovementOptions(options);
+	const storage = options.storage ?? fsCampaignStorage();
+	const runDir = resolveRunDir(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 codec = memoryConfigCodec(options);
+	assertMemoryConfigRoundTrip(options.baselineConfig, codec.serialize, codec.parse);
+	if (options.activation && !storage.append) throw new Error("memory activation requires CampaignStorage.append");
+	assertMemoryImprovementIdentity(options, storage, runDir, codec.serialize);
+	const trainScenarios = memoryConfigScenarios(options.trainSequences);
+	const selectionScenarios = memoryConfigScenarios(options.selectionSequences);
+	const finalScenarios = memoryConfigScenarios(options.finalSequences);
+	const finalScenarioIds = new Set(finalScenarios.map((scenario) => scenario.id));
+	const pending = /* @__PURE__ */ new Map();
+	const candidates = /* @__PURE__ */ new Map();
+	const candidateFor = (config, hash) => {
+		let candidate = candidates.get(hash);
+		if (!candidate) {
+			candidate = buildRegisteredCandidate(options, storage, runDir, config, hash);
+			candidates.set(hash, candidate);
+			candidate.catch(() => candidates.delete(hash));
+		}
+		return candidate;
+	};
+	const optimizationRunOptions = {
+		...options.optimizationRunOptions ?? {},
+		storage,
+		...options.reps !== void 0 ? { reps: options.reps } : {},
+		...options.resumable !== void 0 ? { resumable: options.resumable } : {},
+		...options.sequenceConcurrency !== void 0 ? { maxConcurrency: options.sequenceConcurrency } : {},
+		...options.dispatchTimeoutMs !== void 0 ? { dispatchTimeoutMs: options.dispatchTimeoutMs } : {},
+		expectUsage: "off"
+	};
+	const optimization = await runSerializedKnowledgeOptimization({
+		executionRef: options.implementationRef,
+		baseline: options.baselineConfig,
+		method: options.method,
+		trainScenarios,
+		selectionScenarios,
+		finalScenarios,
+		codec,
+		scenarioFingerprint: (scenario) => memorySequenceFingerprint(scenario.sequence),
+		dispatchCandidate: async ({ candidate, candidateSurfaceHash, scenario, context }) => {
+			const key = memoryArtifactPath(runDir, candidateSurfaceHash, scenario, context.rep, context.seed);
+			let operation = pending.get(key);
+			if (!operation) {
+				operation = candidateFor(candidate, candidateSurfaceHash).then((builtCandidate) => evaluateMemoryCandidate({
+					options,
+					storage,
+					runDir,
+					lease,
+					candidate: builtCandidate,
+					surfaceHash: candidateSurfaceHash,
+					scenario,
+					rep: context.rep,
+					seed: context.seed,
+					final: finalScenarioIds.has(scenario.id),
+					cost: context.cost,
+					signal: context.signal
+				}));
+				pending.set(key, operation);
+				operation.catch(() => pending.delete(key));
+			}
+			return operation;
+		},
+		judges: [agentMemorySequenceJudge()],
+		runDir,
+		repo: options.repo,
+		storage,
+		seed: options.seed,
+		reps: options.reps,
+		resumable: options.resumable,
+		costCeiling: options.maxTotalCostUsd ?? 0,
+		maxConcurrency: options.sequenceConcurrency,
+		dispatchTimeoutMs: options.dispatchTimeoutMs,
+		expectUsage: "off",
+		optimizationRunOptions,
+		now: options.now
+	});
+	await lease.assertOwned();
+	const [baselineCandidate, winnerCandidate] = await Promise.all([candidateFor(optimization.baseline.value, optimization.baseline.surfaceHash), candidateFor(optimization.winner.value, optimization.winner.surfaceHash)]);
+	const finalEvaluation = loadFinalEvaluation({
+		options,
+		storage,
+		runDir,
+		baselineSurfaceHash: optimization.baseline.surfaceHash,
+		baselineCandidateRef: baselineCandidate.ref,
+		winnerSurfaceHash: optimization.winner.surfaceHash,
+		winnerCandidateRef: winnerCandidate.ref
+	});
+	const decision = decidePromotion({
+		options,
+		optimization,
+		finalEvaluation,
+		unchanged: optimization.baseline.surfaceHash === optimization.winner.surfaceHash
+	});
+	const resultJsonPath = join(runDir, "memory-improvement-result.json");
+	const activationRef = options.activation?.ref ?? "not-configured";
+	const activationId = `memory-activation-${surfaceHash(canonicalJson({
+		experimentId: options.experimentId,
+		implementationRef: options.implementationRef,
+		method: optimization.methodName,
+		activationRef,
+		baselineSurfaceHash: optimization.baseline.surfaceHash,
+		winnerSurfaceHash: optimization.winner.surfaceHash,
+		finalEvaluationHash: finalEvaluation.manifestHash,
+		promotionPolicy: normalizedPromotionPolicy(options)
+	}))}`;
+	const activationJournalDir = join(runDir, "activations");
+	const activationJournalPath = join(activationJournalDir, `${activationId}.jsonl`);
+	const activationEligible = decision.status === "promote";
+	const activationEventIdentity = {
+		activationId,
+		experimentId: options.experimentId,
+		activationRef,
+		baselineSurfaceHash: optimization.baseline.surfaceHash,
+		winnerSurfaceHash: optimization.winner.surfaceHash,
+		finalEvaluationHash: finalEvaluation.manifestHash
+	};
+	const activationJournal = activationEligible ? 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 = {
+		optimization,
+		baselineConfig: optimization.baseline.value,
+		winnerConfig: optimization.winner.value,
+		baselineSurface: optimization.baseline.surface,
+		winnerSurface: optimization.winner.surface,
+		baselineSurfaceHash: optimization.baseline.surfaceHash,
+		winnerSurfaceHash: optimization.winner.surfaceHash,
+		decision,
+		finalEvaluation,
+		activation,
+		totalCostUsd: optimization.comparison.totalCost.totalCostUsd,
+		resultJsonPath
+	};
+	await lease.assertOwned();
+	if (activationJournal.activated) await assertActivatedMemoryWinner({
+		options,
+		lease,
+		result
+	});
+	writeMemoryImprovementResult(storage, options.experimentId, result);
+	if (activationEligible && !activationJournal.activated && options.activation) {
+		await activateMemoryWinner({
+			options,
+			storage,
+			lease,
+			result,
+			activationEventIdentity,
+			activationJournalDir,
+			activationJournalPath,
+			hadPreparedEvent: activationJournal.prepared
+		});
+		writeMemoryImprovementResult(storage, options.experimentId, result);
+	}
+	return result;
+}
+//#endregion
+//#region src/memory/mem0.ts
+/** Connects both the hosted Mem0 client and the open-source `Memory` class. */
+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 = mergeScopes(options.defaultScope, searchOptions.scope);
+			assertMem0ProviderScope(scope, options.mode, id, "search");
+			const requestedKinds = [...new Set(searchOptions.kinds ?? [])];
+			const kindQueries = requestedKinds.length > 0 ? requestedKinds : [void 0];
+			return mergeMem0Hits((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 } : {}
+			})))).flatMap((raw) => normalizeMem0Hits(raw, id, searchOptions)), searchOptions.limit);
+		},
+		async getContext(query, searchOptions = {}) {
+			return defaultGetMemoryContext(adapter, query, searchOptions);
+		},
+		async write(input) {
+			const scope = mergeScopes(options.defaultScope, input.scope);
+			assertMem0ProviderScope(scope, options.mode, id, "write");
+			pruneExpiredMem0PendingWrites(pendingWrites);
+			const writeId = input.id ?? randomUUID();
+			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 = compactRecord({
+				...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 = stringField$1(candidate, ["id"]);
+				if (providerId) pendingProbe.providerIds.add(providerId);
+			}
+			if (durableMutations.length === 0) pendingWrites.delete(pendingProbe);
+			const item = mutations[0] ?? items[0];
+			const itemId = stringField$1(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 = mergeScopes(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 items = extractMem0Items(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
+					}));
+					if (items.length === 0) {
+						const searchableByQuery = await searchableMem0IdsForCleanup(options, clearFilters, searchProbes);
+						const searchableIds = new Set([...searchableByQuery.values()].flatMap((ids) => [...ids]));
+						const unseenSearchIds = [...searchableIds].filter((memoryId) => !deletedIds.has(memoryId));
+						for (const [query, ids] of searchableByQuery) {
+							const known = searchProbes.get(query) ?? /* @__PURE__ */ new Set();
+							for (const memoryId of ids) known.add(memoryId);
+							searchProbes.set(query, known);
+							if (ids.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) => stringField$1(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 = stringField$1(item, ["id"]);
+						const text = stringField$1(item, [
+							"memory",
+							"text",
+							"content"
+						]) ?? stringField$1(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 = stringField$1(item, [
+			"memory",
+			"text",
+			"content"
+		]) ?? stringField$1(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 = numberField$1(item, [
+			"rerankScore",
+			"rerank_score",
+			"score"
+		]);
+		if (options.minScore !== void 0 && (score === void 0 || score < options.minScore)) return;
+		const memoryId = stringField$1(item, ["id"]) ?? stableId("mem", canonicalJson(compactRecord({
+			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,
+			...stringField$1(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: compactRecord({
+				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(isRecord);
+	if (!isRecord(raw)) return [];
+	for (const key of [
+		"results",
+		"memories",
+		"data"
+	]) if (Array.isArray(raw[key])) return raw[key].filter(isRecord);
+	return [raw];
+}
+function mem0Event(item) {
+	return (stringField$1(item, ["event"]) ?? stringField$1(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 = compactRecord({
+		...mem0CustomScopeMetadata(scope),
+		memoryKind: kind
+	});
+	return compactRecord({
+		...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]) => {
+			return extractMem0Items(await options.client.search(query, {
+				filters,
+				topK: Math.min(100, Math.max(10, expectedIds.size)),
+				...options.mode === "hosted" ? {
+					latestOnly: false,
+					showExpired: true
+				} : {}
+			})).map((item) => {
+				const memoryId = stringField$1(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 mergeScopes(base, extra) {
+	return {
+		...base ?? {},
+		...extra ?? {},
+		tags: {
+			...base?.tags ?? {},
+			...extra?.tags ?? {}
+		}
+	};
+}
+function sleep(ms) {
+	return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function compactRecord(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 isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function recordField(value, key) {
+	const field = value?.[key];
+	return isRecord(field) ? field : void 0;
+}
+function stringField$1(value, keys) {
+	for (const key of keys) {
+		const field = value?.[key];
+		if (typeof field === "string" && field.length > 0) return field;
+	}
+}
+function numberField$1(value, keys) {
+	for (const key of keys) {
+		const field = value?.[key];
+		if (typeof field === "number" && Number.isFinite(field)) return field;
+	}
+}
+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();
+	}
+}
+/** Stable identity useful for dispatch/cache keys without exposing client credentials. */
+function mem0MemoryAdapterIdentity(options) {
+	if (typeof options.backendRef !== "string" || !options.backendRef.trim()) throw new Error("Mem0 backendRef must be a non-empty string");
+	return `sha256:${sha256(canonicalJson(compactRecord(options)))}`;
+}
+//#endregion
+//#region src/memory/neo4j.ts
+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") result = await callRequired(nested(client, ["longTerm", "long_term"], client), ["addEntity"], [
+		input.entityName ?? input.title ?? input.text,
+		input.entityType ?? "custom",
+		neo4jEntityOptions(input)
+	]);
+	else if (input.kind === "preference") {
+		assertNeo4jBridgeCapability(transport, input.kind, adapterId);
+		result = await callRequired(nested(client, ["longTerm", "long_term"], client), ["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 {
+				assertNeo4jWriteSucceeded(await callRequired(reasoning, ["addStep"], [traceId, {
+					thought: input.text,
+					observation: stringMetadata(input.metadata, "observation"),
+					action: stringMetadata(input.metadata, "action")
+				}]), 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", canonicalJson({
+		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 = stringField(response, ["status"])?.toLowerCase();
+	if (response.success === false || response.ok === false || response.isError === true || status === "failed" || status === "error") {
+		const nestedError = record(response.error);
+		const detail = stringField(response, [
+			"error",
+			"message",
+			"detail"
+		]) ?? (nestedError ? stringField(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 supplied = [
+		"tenantId",
+		"userId",
+		"agentId",
+		"teamId",
+		"runId",
+		"sessionId",
+		"namespace"
+	].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);
+	}
+}
+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) {
+	return rawHitsFrom(value).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 kind = memoryKind(stringField(record(obj.metadata) ?? {}, ["agentKnowledgeKind"]) ?? stringField(obj, [
+		"kind",
+		"type",
+		"label"
+	]), obj);
+	const text = textFromHitObject(obj, kind);
+	if (!text) return null;
+	const id = stringField(obj, [
+		"id",
+		"memoryId",
+		"uuid"
+	]) ?? stableId("mem", text);
+	return {
+		id,
+		uri: stringField(obj, ["uri"]) ?? `memory://${adapterId}/${encodeURIComponent(id)}`,
+		kind,
+		text,
+		title: stringField(obj, [
+			"title",
+			"name",
+			"task",
+			"subject"
+		]),
+		score: numberField(obj, ["score"]),
+		normalizedScore: numberField(obj, ["normalizedScore", "normalized_score"]),
+		confidence: numberField(obj, ["confidence"]),
+		createdAt: stringField(obj, ["createdAt", "created_at"]),
+		validUntil: stringField(obj, ["validUntil", "valid_until"]),
+		lastVerifiedAt: stringField(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 = stringField(obj, [
+		"text",
+		"content",
+		"body",
+		"summary",
+		"preference",
+		"description"
+	]);
+	if (direct) return direct;
+	if (kind === "entity") return stringField(obj, ["name"]);
+	if (kind === "fact") {
+		const subject = stringField(obj, ["subject"]);
+		const predicate = stringField(obj, ["predicate"]);
+		const object = stringField(obj, ["object", "obj"]);
+		if (subject && predicate && object) return `${subject} ${predicate} ${object}`;
+	}
+	if (kind === "reasoning-trace") return [stringField(obj, ["task"]), stringField(obj, ["outcome"])].filter(Boolean).join("\n") || 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 ? stringField(obj, [
+		"id",
+		"memoryId",
+		"uuid"
+	]) : void 0;
+}
+function record(value) {
+	return value && typeof value === "object" && !Array.isArray(value) ? value : null;
+}
+function stringField(obj, names) {
+	for (const name of names) {
+		const value = obj[name];
+		if (typeof value === "string" && value.length > 0) return value;
+	}
+}
+function numberField(obj, names) {
+	for (const name of names) {
+		const value = obj[name];
+		if (typeof value === "number" && Number.isFinite(value)) return value;
+	}
+}
+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;
+}
+//#endregion
+//#region src/memory/schemas.ts
+const AgentMemoryKindSchema = z.enum([
+	"message",
+	"entity",
+	"fact",
+	"preference",
+	"observation",
+	"reasoning-trace"
+]);
+const 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()
+});
+const 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()
+});
+const 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()
+});
+//#endregion
+export { assertImmutableRef as A, resetRetrievalHoldoutRegistry as C, jsonObjectCandidateCodec as D, jsonCandidateCodec as E, runSerializedKnowledgeOptimization as O, emitRetrievalHoldoutBypass as S, toOffPolicyTrajectory as T, defaultGetMemoryContext as _, createNeo4jAgentMemoryAdapter as a, applySessionStickyRetrievalHoldout as b, runAgentMemoryImprovement as c, runAgentMemoryExperiment as d, agentMemorySequenceJudge as f, forkAgentMemoryBranchSnapshot as g, createAgentMemoryBranch as h, AgentMemoryWriteInputSchema as i, scenarioContentFingerprint as k, createGraphitiMemoryAdapter as l, buildAgentMemorySequencesFromBenchmarkCases as m, AgentMemoryKindSchema as n, createMem0MemoryAdapter as o, buildAgentMemorySequenceScenarios as p, AgentMemoryScopeSchema as r, mem0MemoryAdapterIdentity as s, AgentMemoryHitSchema as t, graphitiMemoryAdapterIdentity as u, renderMemoryContext as v, retrievalHoldoutConfigHash as w, deterministicRng as x, applyRetrievalHoldout as y };
+
+//# sourceMappingURL=memory-C6KPRhoU.js.map