@tangle-network/agent-knowledge 19.1.2 → 20.0.0

package/dist/memory-BH6oT1Qe.js

@@ -0,0 +1,2728 @@
+import { r as stableId, t as sha256 } from "./ids-Bevz_pXV.js";
+import { n as memoryWriteResultToSourceRecord, t as memoryHitToSourceRecord } from "./source-record-CdWvzvO6.js";
+import { canonicalJson, mulberry32 } from "@tangle-network/agent-eval";
+import { z } from "zod";
+import { randomUUID } from "node:crypto";
+import { setTimeout as setTimeout$1 } from "node:timers/promises";
+//#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$2(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$2(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$2(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$2(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$2(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$2(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$2(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$2(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$2(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/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/json.ts
+/** Optional object properties are absent on the wire; other unsupported values still fail. */
+function canonicalMemoryJson(value) {
+	return canonicalJson(omitUndefinedProperties(value));
+}
+function omitUndefinedProperties(value) {
+	if (Array.isArray(value)) return value.map(omitUndefinedProperties);
+	if (value !== null && typeof value === "object" && (Object.getPrototypeOf(value) === Object.prototype || Object.getPrototypeOf(value) === null)) return Object.fromEntries(Object.entries(value).filter(([, child]) => child !== void 0).map(([key, child]) => [key, omitUndefinedProperties(child)]));
+	return value;
+}
+//#endregion
+//#region src/memory/lifecycle.ts
+const DEFAULT_MEMORY_CLEANUP_TIMEOUT_MS = 18e4;
+var AgentMemoryLifecycleTimeoutError = class extends Error {
+	operation;
+	timeoutMs;
+	constructor(operation, timeoutMs) {
+		super(`${operation} did not finish within ${timeoutMs}ms`);
+		this.operation = operation;
+		this.timeoutMs = timeoutMs;
+		this.name = "AgentMemoryLifecycleTimeoutError";
+	}
+};
+var AgentMemoryLifecycleUnsafeError = class extends Error {
+	operation;
+	priorTimeout;
+	constructor(operation, priorTimeout) {
+		super(`${operation} cannot start because '${priorTimeout.operation}' is still running after its ${priorTimeout.timeoutMs}ms timeout`, { cause: priorTimeout });
+		this.operation = operation;
+		this.priorTimeout = priorTimeout;
+		this.name = "AgentMemoryLifecycleUnsafeError";
+	}
+};
+const timedOutResources = /* @__PURE__ */ new WeakMap();
+function resolveMemoryCleanupTimeoutMs(value, label) {
+	const timeoutMs = value ?? 18e4;
+	if (!Number.isSafeInteger(timeoutMs) || timeoutMs <= 0) throw new Error(`${label} cleanupTimeoutMs must be a positive safe integer`);
+	return timeoutMs;
+}
+async function runBoundedMemoryLifecycle(input) {
+	input.signal?.throwIfAborted();
+	if (input.cancellationTimeoutMs !== void 0 && (!Number.isSafeInteger(input.cancellationTimeoutMs) || input.cancellationTimeoutMs <= 0)) throw new Error(`${input.operation} cancellationTimeoutMs must be a positive safe integer`);
+	const priorTimeout = input.resource ? timedOutResources.get(input.resource) : void 0;
+	if (priorTimeout) throw new AgentMemoryLifecycleUnsafeError(input.operation, priorTimeout);
+	let timeout;
+	let cancellationTimeout;
+	let timeoutError;
+	let relayAbort;
+	const work = Promise.resolve().then(input.run);
+	if (input.resource) {
+		const resource = input.resource;
+		work.then(() => {
+			if (timeoutError && timedOutResources.get(resource) === timeoutError) timedOutResources.delete(resource);
+		}, () => {
+			if (timeoutError && timedOutResources.get(resource) === timeoutError) timedOutResources.delete(resource);
+		});
+	}
+	const deadline = new Promise((_, reject) => {
+		timeout = setTimeout(() => {
+			timeoutError = new AgentMemoryLifecycleTimeoutError(input.operation, input.timeoutMs);
+			if (input.resource) timedOutResources.set(input.resource, timeoutError);
+			input.abortController?.abort(timeoutError);
+			reject(timeoutError);
+		}, input.timeoutMs);
+	});
+	const signal = input.signal;
+	const cancellation = signal ? new Promise((_, reject) => {
+		relayAbort = () => {
+			const error = memoryLifecycleAbortError(input.operation);
+			input.abortController?.abort(error);
+			if (input.cancellationTimeoutMs === void 0) {
+				reject(signal.reason ?? error);
+				return;
+			}
+			cancellationTimeout = setTimeout(() => {
+				timeoutError = new AgentMemoryLifecycleTimeoutError(`${input.operation} cancellation`, input.cancellationTimeoutMs);
+				if (input.resource) timedOutResources.set(input.resource, timeoutError);
+				reject(timeoutError);
+			}, input.cancellationTimeoutMs);
+		};
+		if (signal.aborted) relayAbort();
+		else signal.addEventListener("abort", relayAbort, { once: true });
+	}) : void 0;
+	try {
+		return await Promise.race([
+			work,
+			deadline,
+			...cancellation ? [cancellation] : []
+		]);
+	} finally {
+		if (timeout) clearTimeout(timeout);
+		if (cancellationTimeout) clearTimeout(cancellationTimeout);
+		if (relayAbort) signal?.removeEventListener("abort", relayAbort);
+	}
+}
+function memoryLifecycleAbortError(operation) {
+	const error = /* @__PURE__ */ new Error(`${operation} aborted`);
+	error.name = "AbortError";
+	return error;
+}
+function memoryRecoveryDelayMs(adapter) {
+	const isolation = adapter.branchIsolation;
+	if (isolation?.mode !== "scoped" || isolation.processExitSafe !== false) return 0;
+	const delayMs = isolation.recoveryDelayMs;
+	if (typeof delayMs !== "number" || !Number.isSafeInteger(delayMs) || delayMs <= 0) throw new Error(`${adapter.id}: processExitSafe=false requires a positive recoveryDelayMs for abandoned writes`);
+	return delayMs;
+}
+async function sleepForMemoryRecovery(delayMs, assertOwned, timeoutMs = delayMs, operation = "memory recovery visibility wait", signal) {
+	if (delayMs <= 0) return;
+	if (!Number.isSafeInteger(timeoutMs) || timeoutMs <= 0) throw new Error(`${operation} timeout must be a positive safe integer`);
+	signal?.throwIfAborted();
+	await waitForMemoryRecoveryDelay(Math.min(delayMs, timeoutMs), signal, operation);
+	await assertOwned();
+	if (delayMs > timeoutMs) throw new AgentMemoryLifecycleTimeoutError(operation, timeoutMs);
+}
+async function waitForMemoryRecoveryDelay(delayMs, signal, operation) {
+	await new Promise((resolve, reject) => {
+		let timeout;
+		const abort = () => {
+			if (timeout) clearTimeout(timeout);
+			reject(signal?.reason ?? memoryLifecycleAbortError(operation));
+		};
+		timeout = setTimeout(() => {
+			signal?.removeEventListener("abort", abort);
+			resolve();
+		}, delayMs);
+		if (signal?.aborted) abort();
+		else signal?.addEventListener("abort", abort, { once: true });
+	});
+}
+function createMemoryExecutionPool(limit) {
+	let active = 0;
+	const waiters = [];
+	return { async run(operation) {
+		if (active >= limit) await new Promise((resolve) => waiters.push(resolve));
+		active += 1;
+		try {
+			return await operation();
+		} finally {
+			active -= 1;
+			waiters.shift()?.();
+		}
+	} };
+}
+//#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
+//#region src/memory/hindsight.ts
+var HindsightOperationUnknownError = class extends Error {
+	bankId;
+	operationId;
+	documentId;
+	constructor(bankId, operationId, documentId, options) {
+		super("Hindsight retain is unresolved; retry the same write id and bytes to reconcile it before checkpointing", options);
+		this.bankId = bankId;
+		this.operationId = operationId;
+		this.documentId = documentId;
+		this.name = "HindsightOperationUnknownError";
+	}
+};
+const operationSchema = z.object({
+	operation_id: z.string(),
+	status: z.enum([
+		"pending",
+		"processing",
+		"completed",
+		"failed",
+		"cancelled",
+		"not_found"
+	])
+});
+const documentSchema = z.object({
+	id: z.string(),
+	bank_id: z.string(),
+	original_text: z.string().nullable(),
+	document_metadata: z.record(z.string(), z.unknown()).nullable().optional()
+});
+const recallSchema = z.object({
+	results: z.array(z.object({
+		id: z.string().min(1),
+		text: z.string(),
+		type: z.string().nullable().optional(),
+		document_id: z.string().nullable().optional(),
+		chunk_id: z.string().nullable().optional(),
+		metadata: z.record(z.string(), z.string()).nullable().optional(),
+		source_fact_ids: z.array(z.string()).nullable().optional(),
+		scores: z.object({ final: z.number().nullable().optional() }).passthrough().nullable().optional()
+	})),
+	source_facts: z.record(z.string(), z.unknown()).nullable().optional(),
+	source_facts_truncated: z.boolean().nullable().optional()
+});
+/** Dedicated bank identity includes the entire logical scope, including the existing branch partition. */
+function hindsightMemoryBankId(input) {
+	if (!input.backendRef.trim() || !input.branchId.trim()) throw new Error("Hindsight requires backendRef and branchId");
+	if (!input.scope.namespace?.trim()) throw new Error("Hindsight memory requires an explicit stable play scope.namespace");
+	if (input.scope.tags?.memoryBranchId !== input.branchId) throw new Error("Hindsight memory scope must belong to its bound AgentMemoryBranch");
+	return `ak-${sha256(canonicalMemoryJson(input))}`;
+}
+/** Hindsight 0.10.2 adapter. Snapshots remain accepted-input journals, never provider database snapshots. */
+function createHindsightMemoryAdapter(options) {
+	if (!options.backendRef?.trim() || !options.branchId?.trim()) throw new Error("Hindsight requires backendRef and branchId");
+	const requestTimeoutMs = bounded(options.requestTimeoutMs ?? 15e3, 3e5, "requestTimeoutMs");
+	const ingestionTimeoutMs = bounded(options.ingestionTimeoutMs ?? 12e4, 6e5, "ingestionTimeoutMs");
+	const pollIntervalMs = bounded(options.pollIntervalMs ?? 1e3, 3e4, "pollIntervalMs");
+	const maxTextChars = bounded(options.maxTextChars ?? 8e3, 1e5, "maxTextChars");
+	const maxTokens = bounded(options.recallMaxTokens ?? 1e3, 16e3, "recallMaxTokens");
+	const id = `hindsight-0.10.2:${sha256(options.backendRef)}`;
+	const unresolved = /* @__PURE__ */ new Map();
+	let version;
+	async function request(method, path, body, timeoutMs = requestTimeoutMs) {
+		const abortController = new AbortController();
+		const response = await runBoundedMemoryLifecycle({
+			operation: `Hindsight ${method} ${path}`,
+			timeoutMs,
+			resource: options.client,
+			abortController,
+			run: () => options.client.request({
+				method,
+				path,
+				...body === void 0 ? {} : { body },
+				signal: abortController.signal
+			})
+		});
+		if (response.status !== 404 && (response.status < 200 || response.status >= 300)) throw new Error(`Hindsight ${method} failed with HTTP ${response.status}`);
+		return response;
+	}
+	async function checkVersion() {
+		version ??= (async () => {
+			const response = await request("GET", "/version");
+			const parsed = z.object({ api_version: z.literal("0.10.2") }).safeParse(response.body);
+			if (response.status !== 200 || !parsed.success) throw new Error("Hindsight adapter requires the qualified 0.10.2 API");
+		})();
+		await version;
+	}
+	function bank(scope) {
+		return hindsightMemoryBankId({
+			backendRef: options.backendRef,
+			branchId: options.branchId,
+			scope: scope ?? {}
+		});
+	}
+	function path(bankId, suffix) {
+		return `/v1/default/banks/${encodeURIComponent(bankId)}${suffix}`;
+	}
+	async function readDocument(bankId, documentId) {
+		const response = await request("GET", path(bankId, `/documents/${encodeURIComponent(documentId)}`));
+		return response.status === 404 ? null : documentSchema.parse(response.body);
+	}
+	async function readOperation(bankId, operationId, timeoutMs = requestTimeoutMs) {
+		const response = await request("GET", path(bankId, `/operations/${operationId}`), void 0, timeoutMs);
+		if (response.status === 404) return {
+			operation_id: operationId,
+			status: "not_found"
+		};
+		const operation = operationSchema.parse(response.body);
+		if (operation.operation_id !== operationId) throw new Error("Hindsight returned another operation identity");
+		return operation;
+	}
+	const adapter = {
+		id,
+		branchIsolation: {
+			mode: "instance",
+			branchId: options.branchId,
+			supportsLogicalScopes: true
+		},
+		async search(query, searchOptions = {}) {
+			const bankId = bank(searchOptions.scope);
+			if (!query.trim()) throw new Error("Hindsight recall requires a nonempty query");
+			const limit = searchOptions.limit ?? 10;
+			if (!Number.isSafeInteger(limit) || limit < 0 || limit > 100) throw new Error("Hindsight recall limit must be between 0 and 100");
+			if (searchOptions.minScore !== void 0 && !Number.isFinite(searchOptions.minScore)) throw new Error("Hindsight minScore must be finite");
+			if (limit === 0) return [];
+			await checkVersion();
+			const response = await request("POST", path(bankId, "/memories/recall"), {
+				query,
+				budget: "low",
+				max_tokens: maxTokens,
+				include: {
+					entities: null,
+					source_facts: { max_tokens: maxTokens }
+				}
+			});
+			if (response.status === 404) return [];
+			const result = recallSchema.parse(response.body);
+			return result.results.map((hit) => ({
+				id: hit.id,
+				uri: `hindsight://${bankId}/memories/${encodeURIComponent(hit.id)}`,
+				kind: hit.type === "world" ? "fact" : "observation",
+				text: hit.text,
+				...hit.scores?.final == null ? {} : { score: hit.scores.final },
+				metadata: {
+					provider: "hindsight",
+					backendRef: options.backendRef,
+					bankId,
+					branchId: options.branchId,
+					providerFactType: hit.type ?? null,
+					documentId: hit.document_id ?? null,
+					chunkId: hit.chunk_id ?? null,
+					provenance: hit.metadata ?? null,
+					sourceFactIds: hit.source_fact_ids ?? [],
+					sourceFacts: Object.fromEntries((hit.source_fact_ids ?? []).flatMap((key) => result.source_facts?.[key] === void 0 ? [] : [[key, result.source_facts[key]]])),
+					sourceFactsTruncated: result.source_facts_truncated ?? null,
+					evidenceStatus: "provider-derived; source attribution is not independent validation"
+				}
+			})).filter((hit) => (!searchOptions.kinds?.length || searchOptions.kinds.includes(hit.kind)) && (searchOptions.minScore === void 0 || hit.score !== void 0 && hit.score >= searchOptions.minScore)).slice(0, limit);
+		},
+		async getContext(query, searchOptions) {
+			return defaultGetMemoryContext(adapter, query, searchOptions);
+		},
+		async write(raw) {
+			const input = AgentMemoryWriteInputSchema.parse(raw);
+			if (!input.id?.trim()) throw new Error("Hindsight writes require a stable caller id");
+			if (input.text.length > maxTextChars) throw new Error(`Hindsight write exceeds ${maxTextChars} characters`);
+			const bankId = bank(input.scope);
+			const documentId = `ak-${sha256(input.id)}`;
+			const operationId = operationUuid(`${bankId}:${documentId}`);
+			const identity = `${bankId}:${operationId}`;
+			const { scope, ...sourceInput } = input;
+			const inputDigest = sha256(canonicalMemoryJson(sourceInput));
+			const expectedMetadata = {
+				ak_input_sha256: inputDigest,
+				ak_scope_sha256: sha256(canonicalMemoryJson(scope)),
+				ak_source: canonicalMemoryJson(sourceInput)
+			};
+			const verifyDocument = (document) => {
+				if (!document || document.id !== documentId || document.bank_id !== bankId || document.original_text !== input.text || document.document_metadata?.ak_input_sha256 !== inputDigest || document.document_metadata?.ak_scope_sha256 !== expectedMetadata.ak_scope_sha256) throw new Error("Hindsight document identity or bytes differ from this stable write id");
+			};
+			await checkVersion();
+			const prior = await readDocument(bankId, documentId);
+			if (prior) verifyDocument(prior);
+			let operation = await readOperation(bankId, operationId);
+			if (prior && operation.status === "not_found") {
+				const unknown = new HindsightOperationUnknownError(bankId, operationId, documentId);
+				unresolved.set(identity, unknown);
+				throw unknown;
+			}
+			const unknown = new HindsightOperationUnknownError(bankId, operationId, documentId);
+			unresolved.set(identity, unknown);
+			const deadline = Date.now() + ingestionTimeoutMs;
+			try {
+				if (operation.status === "not_found") {
+					const submitted = await request("POST", path(bankId, "/memories"), {
+						async: true,
+						operation_id: operationId,
+						items: [{
+							content: input.text,
+							document_id: documentId,
+							metadata: expectedMetadata,
+							tags: ["source:agent-knowledge"],
+							observation_scopes: "shared",
+							context: "Retained agent input. Claims of success or correctness remain attributed claims, not verified findings."
+						}]
+					});
+					if (!z.object({
+						success: z.literal(true),
+						bank_id: z.literal(bankId),
+						async: z.literal(true),
+						operation_id: z.literal(operationId)
+					}).parse(submitted.body).success) throw new Error("Hindsight rejected retain");
+				}
+				while (operation.status !== "completed") {
+					const remaining = deadline - Date.now();
+					if (remaining <= 0) throw unknown;
+					operation = await readOperation(bankId, operationId, Math.min(requestTimeoutMs, remaining));
+					if (operation.status === "failed" || operation.status === "cancelled") throw new Error(`Hindsight retain is ${operation.status}; possible partial provider state requires inspection`);
+					if (operation.status !== "completed") await setTimeout$1(Math.min(pollIntervalMs, Math.max(0, deadline - Date.now())));
+				}
+				verifyDocument(await readDocument(bankId, documentId));
+				unresolved.delete(identity);
+				return accepted("completed");
+			} catch (cause) {
+				throw new HindsightOperationUnknownError(bankId, operationId, documentId, { cause });
+			}
+			function accepted(operationStatus) {
+				unresolved.delete(identity);
+				const result = {
+					accepted: true,
+					id: input.id,
+					uri: `hindsight://${bankId}/documents/${documentId}`,
+					kind: input.kind,
+					metadata: {
+						provider: "hindsight",
+						bankId,
+						branchId: options.branchId,
+						operationId,
+						documentId,
+						inputDigest,
+						operationStatus,
+						cost: "unmeasured"
+					}
+				};
+				return {
+					...result,
+					sourceRecord: memoryWriteResultToSourceRecord(result, input.text, { scope })
+				};
+			}
+		},
+		async flush() {
+			if (unresolved.size) throw unresolved.values().next().value;
+		}
+	};
+	return adapter;
+}
+function operationUuid(value) {
+	const hex = sha256(value);
+	return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-5${hex.slice(13, 16)}-8${hex.slice(17, 20)}-${hex.slice(20, 32)}`;
+}
+function bounded(value, max, name) {
+	if (!Number.isSafeInteger(value) || value < 1 || value > max) throw new Error(`Hindsight ${name} must be an integer between 1 and ${max}`);
+	return value;
+}
+//#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/tools.ts
+const publications = /* @__PURE__ */ new WeakMap();
+function createPlayMemoryTools(options) {
+	if (!options.actorId?.trim()) throw new Error("play memory tools require a trusted actorId");
+	if (typeof options.onCheckpoint !== "function") throw new Error("play memory tools require durable checkpoint publication");
+	const maxTextChars = options.maxTextChars ?? 8e3;
+	const maxResults = options.maxResults ?? 20;
+	if (!Number.isSafeInteger(maxTextChars) || maxTextChars < 1 || maxTextChars > 1e5 || !Number.isSafeInteger(maxResults) || maxResults < 1 || maxResults > 100) throw new Error("invalid play memory tool bounds");
+	const prefix = options.namePrefix ?? "";
+	if (!/^[a-zA-Z0-9_-]*$/.test(prefix)) throw new Error("invalid memory tool namePrefix");
+	const recall = z.strictObject({
+		question: z.string().trim().min(1).max(8e3),
+		limit: z.int().min(1).max(maxResults).optional()
+	});
+	const record = z.strictObject({
+		id: z.string().trim().min(1).max(256),
+		kind: AgentMemoryKindSchema,
+		text: z.string().min(1).max(maxTextChars),
+		title: z.string().max(512).optional(),
+		sourceRefs: z.array(z.string().min(1).max(2048)).max(50).optional()
+	});
+	return [tool(`${prefix}memory_recall`, "Recall memory visible to this play. Returned memories are attributed provider evidence, not independently verified findings.", recall, async (input) => {
+		const context = await options.branch.getContext(input.question, { limit: input.limit ?? maxResults });
+		const content = {
+			branchId: options.branch.branchId,
+			adapterId: options.branch.id,
+			actorId: options.actorId,
+			query: input.question,
+			context
+		};
+		const receipt = {
+			...content,
+			receiptDigest: `sha256:${sha256(canonicalMemoryJson(content))}`
+		};
+		await options.recordRetrieval?.(receipt);
+		return {
+			...context,
+			receipt
+		};
+	}), tool(`${prefix}memory_record`, "Retain a sourced observation in this play and checkpoint its accepted input. Reuse the same id and bytes after an ambiguous response.", record, async (input) => {
+		const write = {
+			id: input.id,
+			kind: input.kind,
+			text: input.text,
+			...input.title === void 0 ? {} : { title: input.title },
+			metadata: {
+				actorId: options.actorId,
+				sourceRefs: input.sourceRefs ?? []
+			}
+		};
+		let state = publications.get(options.branch);
+		if (!state) {
+			state = { tail: Promise.resolve() };
+			publications.set(options.branch, state);
+		}
+		const shared = state;
+		const publication = shared.tail.catch(() => void 0).then(async () => {
+			if (shared.pending && canonicalMemoryJson(shared.pending.input) !== canonicalMemoryJson(write)) throw new Error("reconcile the prior memory write with its same id, bytes, and actor before another write");
+			if (!shared.pending) {
+				const existing = (await options.branch.snapshot()).journal.find((entry) => entry.input.id === input.id);
+				if (existing && canonicalMemoryJson(existing.input) !== canonicalMemoryJson(write)) throw new Error("memory write id already names different content or attribution");
+				shared.pending = {
+					input: write,
+					...existing ? { result: existing.result } : {}
+				};
+			}
+			const result = shared.pending.result ?? await options.branch.write(write);
+			shared.pending.result = result;
+			if (!result.accepted) {
+				shared.pending = void 0;
+				return {
+					...result,
+					checkpointDigest: null
+				};
+			}
+			const snapshot = await options.branch.snapshot();
+			await options.onCheckpoint(snapshot);
+			shared.pending = void 0;
+			return {
+				...result,
+				checkpointDigest: snapshot.digest
+			};
+		});
+		shared.tail = publication;
+		return publication;
+	})];
+}
+function tool(name, description, inputSchema, handler) {
+	return {
+		name,
+		description,
+		inputSchema,
+		inputSchemaJson: z.toJSONSchema(inputSchema),
+		handler: async (input) => handler(inputSchema.parse(input))
+	};
+}
+//#endregion
+export { resetRetrievalHoldoutRegistry as A, forkAgentMemoryBranchSnapshot as C, applySessionStickyRetrievalHoldout as D, applyRetrievalHoldout as E, toOffPolicyTrajectory as M, deterministicRng as O, createAgentMemoryBranch as S, renderMemoryContext as T, resolveMemoryCleanupTimeoutMs as _, HindsightOperationUnknownError as a, createGraphitiMemoryAdapter as b, AgentMemoryHitSchema as c, AgentMemoryWriteInputSchema as d, AgentMemoryLifecycleTimeoutError as f, memoryRecoveryDelayMs as g, createMemoryExecutionPool as h, mem0MemoryAdapterIdentity as i, retrievalHoldoutConfigHash as j, emitRetrievalHoldoutBypass as k, AgentMemoryKindSchema as l, DEFAULT_MEMORY_CLEANUP_TIMEOUT_MS as m, createNeo4jAgentMemoryAdapter as n, createHindsightMemoryAdapter as o, AgentMemoryLifecycleUnsafeError as p, createMem0MemoryAdapter as r, hindsightMemoryBankId as s, createPlayMemoryTools as t, AgentMemoryScopeSchema as u, runBoundedMemoryLifecycle as v, defaultGetMemoryContext as w, graphitiMemoryAdapterIdentity as x, sleepForMemoryRecovery as y };
+
+//# sourceMappingURL=memory-BH6oT1Qe.js.map