mnemocyte 0.3.0 → 0.4.0

package/dist/index.mjs

@@ -1,8 +1,8 @@
 import { n as isMnemocyteError, t as MnemocyteError } from "./errors-B_7ZdjEO.mjs";
 import { drizzle } from "drizzle-orm/postgres-js";
 import postgres from "postgres";
-import { and, count, countDistinct, desc, eq, gt, inArray, isNotNull, isNull, lt, or, sql } from "drizzle-orm";
-import { customType, index, integer, jsonb, pgTable, real, text, timestamp } from "drizzle-orm/pg-core";
+import { and, count, countDistinct, eq, inArray, isNotNull, isNull, lt, or, sql } from "drizzle-orm";
+import { PgDialect, customType, index, integer, jsonb, pgTable, real, text, timestamp } from "drizzle-orm/pg-core";
 //#region \0rolldown/runtime.js
 var __defProp = Object.defineProperty;
 var __exportAll = (all, no_symbols) => {
@@ -18,7 +18,7 @@ var __exportAll = (all, no_symbols) => {
 //#region src/db/vector.ts
 function formatVectorComponent(value) {
 	if (!Number.isFinite(value)) throw new Error("Vector values must be finite numbers.");
-	return Object.is(value, -0) ? "0" : value.toFixed(17);
+	return Object.is(value, -0) ? "0" : value.toString();
 }
 //#endregion
 //#region src/db/schema.ts
@@ -72,7 +72,8 @@ const eventsTable = pgTable("mnemocyte_events", {
 }, (table) => [index("mnemocyte_events_entity_time_idx").on(table.entityId, table.timestamp)]);
 const metaTable = pgTable("mnemocyte_meta", {
 	key: text("key").primaryKey(),
-	embeddingDimensions: integer("embedding_dimensions").notNull()
+	embeddingDimensions: integer("embedding_dimensions").notNull(),
+	embeddingModel: text("embedding_model")
 });
 //#endregion
 //#region src/db/index.ts
@@ -89,6 +90,7 @@ function createDatabase(databaseUrl) {
 	} catch (error) {
 		throw new MnemocyteError("databaseUrl must be a valid Postgres connection URL.", "CONFIG", error);
 	}
+	if (url.protocol !== "postgres:" && url.protocol !== "postgresql:") throw new MnemocyteError("databaseUrl must use the postgres: or postgresql: protocol.", "CONFIG");
 	const ssl = parseSslFromUrl(url);
 	const isPooler = url.port === "6543" || url.searchParams.get("pgbouncer") === "true";
 	const client = postgres(databaseUrl, {
@@ -106,6 +108,179 @@ function createDatabase(databaseUrl) {
 	};
 }
 //#endregion
+//#region src/resilience.ts
+/**
+* Default per-provider-call timeout. Disabled by default so that callers
+* who do not configure {@link ProviderResilienceConfig.timeoutMs} are
+* unaffected.
+*/
+const DEFAULT_TIMEOUT_MS = 0;
+/** Default number of retry attempts on transient provider failures. */
+const DEFAULT_RETRIES = 0;
+/** Default base backoff delay used between retry attempts. */
+const DEFAULT_BASE_DELAY_MS = 100;
+/** Default ceiling for retry backoff delay. */
+const DEFAULT_MAX_DELAY_MS = 2e3;
+/**
+* Throw a {@link MnemocyteError} with code `"ABORTED"` if `signal` is
+* already aborted. Safe to call with `undefined`.
+*/
+function throwIfAborted(signal) {
+	if (signal?.aborted) throw new MnemocyteError("Operation was aborted.", "ABORTED", signal.reason);
+}
+/**
+* Heuristic default for whether an error should be retried.
+*
+* Conservative by design: only retries on common transient failure
+* indicators (network errors, 5xx-ish messages, `ECONN*` etc.). Never
+* retries on validation, configuration, or {@link MnemocyteError} of
+* code `"VALIDATION"` / `"CONFIG"` / `"CONFLICT"` / `"ABORTED"`.
+*/
+function defaultShouldRetry(error) {
+	if (error instanceof MnemocyteError) {
+		if (error.code === "VALIDATION" || error.code === "CONFIG" || error.code === "CONFLICT" || error.code === "ABORTED") return false;
+		return true;
+	}
+	if (typeof error === "object" && error !== null && "status" in error && typeof error.status === "number" && [
+		429,
+		500,
+		502,
+		503,
+		504
+	].includes(error.status)) return true;
+	if (error instanceof Error) {
+		const message = error.message.toLowerCase();
+		if (message.includes("econn") || message.includes("etimedout") || message.includes("network") || message.includes("timeout") || message.includes("temporarily") || message.includes("rate limit") || message.includes("503") || message.includes("502") || message.includes("504") || message.includes("500")) return true;
+	}
+	return false;
+}
+/**
+* Compute the backoff delay for the given retry attempt, using exponential
+* growth capped at {@link ProviderResilienceConfig.maxDelayMs}.
+*
+* `attempt` is 1-indexed: the delay before the first retry uses
+* `attempt = 1`, before the second retry `attempt = 2`, etc.
+*/
+function computeDelayMs(attempt, baseDelayMs, maxDelayMs) {
+	const exponential = baseDelayMs * 2 ** (attempt - 1);
+	return Math.max(0, Math.min(maxDelayMs, exponential));
+}
+/**
+* Promise-based `setTimeout` that rejects with an `"ABORTED"`
+* {@link MnemocyteError} if `signal` aborts while waiting.
+*/
+function delay(ms, signal) {
+	if (ms <= 0) {
+		throwIfAborted(signal);
+		return Promise.resolve();
+	}
+	return new Promise((resolve, reject) => {
+		const timer = setTimeout(() => {
+			signal?.removeEventListener("abort", onAbort);
+			resolve();
+		}, ms);
+		const onAbort = () => {
+			clearTimeout(timer);
+			reject(new MnemocyteError("Operation was aborted.", "ABORTED", signal?.reason));
+		};
+		if (signal) {
+			if (signal.aborted) {
+				clearTimeout(timer);
+				reject(new MnemocyteError("Operation was aborted.", "ABORTED", signal.reason));
+				return;
+			}
+			signal.addEventListener("abort", onAbort, { once: true });
+		}
+	});
+}
+function timeoutError(timeoutMs) {
+	return new MnemocyteError(`Provider call timed out after ${timeoutMs}ms.`, "TIMEOUT");
+}
+/**
+* Run one provider attempt with a signal linked to the caller's signal and
+* Mnemocyte's configured timeout. Timeout aborts are actively propagated to
+* providers that honor `AbortSignal`.
+*/
+function runAttempt(action, timeoutMs, signal) {
+	if (timeoutMs <= 0 && !signal) return action(void 0);
+	return new Promise((resolve, reject) => {
+		let settled = false;
+		const controller = new AbortController();
+		const timer = timeoutMs > 0 ? setTimeout(() => {
+			if (settled) return;
+			settled = true;
+			signal?.removeEventListener("abort", onAbort);
+			controller.abort(timeoutError(timeoutMs));
+			reject(timeoutError(timeoutMs));
+		}, timeoutMs) : void 0;
+		const onAbort = () => {
+			if (settled) return;
+			settled = true;
+			if (timer) clearTimeout(timer);
+			controller.abort(signal?.reason);
+			reject(new MnemocyteError("Operation was aborted.", "ABORTED", signal?.reason));
+		};
+		if (signal) {
+			if (signal.aborted) {
+				if (timer) clearTimeout(timer);
+				settled = true;
+				controller.abort(signal.reason);
+				reject(new MnemocyteError("Operation was aborted.", "ABORTED", signal.reason));
+				return;
+			}
+			signal.addEventListener("abort", onAbort, { once: true });
+		}
+		action(controller.signal).then((value) => {
+			if (settled) return;
+			settled = true;
+			if (timer) clearTimeout(timer);
+			signal?.removeEventListener("abort", onAbort);
+			resolve(value);
+		}, (error) => {
+			if (settled) return;
+			settled = true;
+			if (timer) clearTimeout(timer);
+			signal?.removeEventListener("abort", onAbort);
+			reject(error);
+		});
+	});
+}
+/**
+* Run `action` with timeout, retry, and abort handling derived from
+* `options.resilience` and `options.signal`. Each retry attempt receives
+* a fresh `AbortSignal` linked to the caller's signal — so callers may
+* abort mid-retry and the in-flight attempt will cancel promptly if the
+* underlying provider honours signals.
+*
+* Errors from {@link MnemocyteError} with code `"VALIDATION"` /
+* `"CONFIG"` / `"CONFLICT"` / `"ABORTED"` are never retried.
+*/
+async function withResilience(action, options = {}) {
+	const config = options.resilience ?? {};
+	const timeoutMs = config.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+	const retries = Math.max(0, config.retries ?? DEFAULT_RETRIES);
+	const baseDelayMs = Math.max(0, config.baseDelayMs ?? DEFAULT_BASE_DELAY_MS);
+	const maxDelayMs = Math.max(baseDelayMs, config.maxDelayMs ?? DEFAULT_MAX_DELAY_MS);
+	const shouldRetry = config.shouldRetry ?? defaultShouldRetry;
+	const externalSignal = options.signal;
+	throwIfAborted(externalSignal);
+	const maxAttempts = retries + 1;
+	let lastError;
+	for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
+		throwIfAborted(externalSignal);
+		try {
+			return await runAttempt(action, timeoutMs, externalSignal);
+		} catch (error) {
+			lastError = error;
+			if (error instanceof MnemocyteError && error.code === "ABORTED") throw error;
+			if (attempt >= maxAttempts) throw error;
+			if (!shouldRetry(error, attempt)) throw error;
+			await delay(computeDelayMs(attempt, baseDelayMs, maxDelayMs), externalSignal);
+		}
+	}
+	throw lastError;
+}
+//#endregion
 //#region src/memory/json.ts
 function invalidJsonValue(path, cause) {
 	return new MnemocyteError(`${path} must contain only JSON-compatible value data.`, "VALIDATION", cause);
@@ -152,10 +327,6 @@ function cloneJsonObject(value, path = "metadata") {
 		throw invalidJsonValue(path, error);
 	}
 }
-/** Assert that a runtime value is a JSON-compatible object. */
-function validateJsonObject(value, path = "metadata") {
-	cloneJsonObject(value, path);
-}
 //#endregion
 //#region src/memory/records.ts
 function normalizeTags(tags) {
@@ -239,6 +410,9 @@ function clampScore(value) {
 	if (!Number.isFinite(value)) return 0;
 	return Math.max(0, Math.min(1, value));
 }
+function toVectorScore(cosineSimilarity) {
+	return clampScore(cosineSimilarity);
+}
 function normalizeWeights(weights) {
 	const merged = {
 		...DEFAULT_RETRIEVAL_WEIGHTS,
@@ -321,6 +495,10 @@ function markdownFence(value) {
 	const longestBacktickRun = Math.max(0, ...Array.from(value.matchAll(/`+/g), (match) => match[0].length));
 	return "`".repeat(Math.max(3, longestBacktickRun + 1));
 }
+function plainFence(values) {
+	const longestEqualsRun = Math.max(0, ...values.flatMap((value) => Array.from(value.matchAll(/=+/g), (match) => match[0].length)));
+	return "=".repeat(Math.max(8, longestEqualsRun + 1));
+}
 function formatMarkdown(memories, query, omittedCount) {
 	const lines = [
 		"# Memory Context",
@@ -337,6 +515,11 @@ function formatMarkdown(memories, query, omittedCount) {
 	return lines.join("\n");
 }
 function formatPlain(memories, query, omittedCount) {
+	const formattedMemories = memories.map((memory) => ({
+		memory,
+		metadata: formatMetadata(memory)
+	}));
+	const fence = plainFence([query, ...formattedMemories.flatMap(({ memory, metadata }) => [metadata, memory.content])]);
 	const lines = [
 		"MEMORY CONTEXT",
 		"",
@@ -344,7 +527,7 @@ function formatPlain(memories, query, omittedCount) {
 		"",
 		"RELEVANT MEMORIES"
 	];
-	for (const [index, memory] of memories.entries()) lines.push("", `--- MEMORY ${index + 1} START ---`, formatMetadata(memory), memory.content, `--- MEMORY ${index + 1} END ---`);
+	for (const [index, { memory, metadata }] of formattedMemories.entries()) lines.push("", `${fence} MEMORY ${index + 1} START ${fence}`, metadata, memory.content, `${fence} MEMORY ${index + 1} END ${fence}`);
 	if (omittedCount > 0) lines.push("", `[${omittedCount} memories omitted to fit token budget]`);
 	return lines.join("\n");
 }
@@ -364,6 +547,7 @@ function formatContext(memories, query, format, omittedCount = 0) {
 }
 //#endregion
 //#region src/context/tokens.ts
+const TRUNCATION_MARKER = "[truncated to fit token budget]";
 const heuristicTokenCounter = { count(text) {
 	return Math.ceil(text.length / 4);
 } };
@@ -374,13 +558,18 @@ function trimToTokenBudget(text, maxTokens, tokenCounter) {
 	let best = "";
 	while (low <= high) {
 		const mid = Math.floor((low + high) / 2);
-		const output = `${text.slice(0, mid).trimEnd()}\n[truncated to fit token budget]`;
+		const output = `${text.slice(0, mid).trimEnd()}\n${TRUNCATION_MARKER}`;
 		if (tokenCounter.count(output) <= maxTokens) {
 			best = output;
 			low = mid + 1;
 		} else high = mid - 1;
 	}
-	return best || "[truncated to fit token budget]";
+	if (best) return best;
+	for (let length = 31; length > 0; length -= 1) {
+		const markerFragment = TRUNCATION_MARKER.slice(0, length);
+		if (tokenCounter.count(markerFragment) <= maxTokens) return markerFragment;
+	}
+	return "";
 }
 //#endregion
 //#region src/context/builder.ts
@@ -419,230 +608,71 @@ async function emitObservation(config, event) {
 		await config.observability?.onEvent?.(event);
 	} catch {
 		return;
-	}
-}
-async function observe(config, backend, operation, metadata, action, successMetadata) {
-	const startedAt = Date.now();
-	await emitObservation(config, withMetadata({
-		operation,
-		phase: "start",
-		backend,
-		timestamp: new Date(startedAt)
-	}, metadata));
-	try {
-		const result = await action();
-		await emitObservation(config, withMetadata({
-			operation,
-			phase: "success",
-			backend,
-			timestamp: /* @__PURE__ */ new Date(),
-			durationMs: Date.now() - startedAt
-		}, {
-			...metadata,
-			...successMetadata?.(result)
-		}));
-		return result;
-	} catch (error) {
-		await emitObservation(config, withMetadata({
-			operation,
-			phase: "error",
-			backend,
-			timestamp: /* @__PURE__ */ new Date(),
-			durationMs: Date.now() - startedAt,
-			error
-		}, metadata));
-		throw error;
-	}
-}
-/**
-* Ordering of {@link ImportanceLevel} from least to most important. Used
-* by `prune({ maxImportance })` to compare a memory's importance against
-* the caller-supplied ceiling.
-*/
-const IMPORTANCE_RANK = {
-	low: 0,
-	normal: 1,
-	high: 2,
-	critical: 3
-};
-//#endregion
-//#region src/resilience.ts
-/**
-* Default per-provider-call timeout. Disabled by default so that callers
-* who do not configure {@link ProviderResilienceConfig.timeoutMs} are
-* unaffected.
-*/
-const DEFAULT_TIMEOUT_MS = 0;
-/** Default number of retry attempts on transient provider failures. */
-const DEFAULT_RETRIES = 0;
-/** Default base backoff delay used between retry attempts. */
-const DEFAULT_BASE_DELAY_MS = 100;
-/** Default ceiling for retry backoff delay. */
-const DEFAULT_MAX_DELAY_MS = 2e3;
-/**
-* Throw a {@link MnemocyteError} with code `"ABORTED"` if `signal` is
-* already aborted. Safe to call with `undefined`.
-*/
-function throwIfAborted(signal) {
-	if (signal?.aborted) throw new MnemocyteError("Operation was aborted.", "ABORTED", signal.reason);
-}
-/**
-* Heuristic default for whether an error should be retried.
-*
-* Conservative by design: only retries on common transient failure
-* indicators (network errors, 5xx-ish messages, `ECONN*` etc.). Never
-* retries on validation, configuration, or {@link MnemocyteError} of
-* code `"VALIDATION"` / `"CONFIG"` / `"ABORTED"`.
-*/
-function defaultShouldRetry(error) {
-	if (error instanceof MnemocyteError) {
-		if (error.code === "VALIDATION" || error.code === "CONFIG" || error.code === "ABORTED") return false;
-		return true;
-	}
-	if (typeof error === "object" && error !== null && "status" in error && typeof error.status === "number" && [
-		429,
-		500,
-		502,
-		503,
-		504
-	].includes(error.status)) return true;
-	if (error instanceof Error) {
-		const message = error.message.toLowerCase();
-		if (message.includes("econn") || message.includes("etimedout") || message.includes("network") || message.includes("timeout") || message.includes("temporarily") || message.includes("rate limit") || message.includes("503") || message.includes("502") || message.includes("504") || message.includes("500")) return true;
-	}
-	return false;
-}
-/**
-* Compute the backoff delay for the given retry attempt, using exponential
-* growth capped at {@link ProviderResilienceConfig.maxDelayMs}.
-*
-* `attempt` is 1-indexed: the delay before the first retry uses
-* `attempt = 1`, before the second retry `attempt = 2`, etc.
-*/
-function computeDelayMs(attempt, baseDelayMs, maxDelayMs) {
-	const exponential = baseDelayMs * 2 ** (attempt - 1);
-	return Math.max(0, Math.min(maxDelayMs, exponential));
-}
-/**
-* Promise-based `setTimeout` that rejects with an `"ABORTED"`
-* {@link MnemocyteError} if `signal` aborts while waiting.
-*/
-function delay(ms, signal) {
-	if (ms <= 0) {
-		throwIfAborted(signal);
-		return Promise.resolve();
-	}
-	return new Promise((resolve, reject) => {
-		const timer = setTimeout(() => {
-			signal?.removeEventListener("abort", onAbort);
-			resolve();
-		}, ms);
-		const onAbort = () => {
-			clearTimeout(timer);
-			reject(new MnemocyteError("Operation was aborted.", "ABORTED", signal?.reason));
-		};
-		if (signal) {
-			if (signal.aborted) {
-				clearTimeout(timer);
-				reject(new MnemocyteError("Operation was aborted.", "ABORTED", signal.reason));
-				return;
-			}
-			signal.addEventListener("abort", onAbort, { once: true });
-		}
-	});
-}
-function timeoutError(timeoutMs) {
-	return new MnemocyteError(`Provider call timed out after ${timeoutMs}ms.`, "TIMEOUT");
-}
-/**
-* Run one provider attempt with a signal linked to the caller's signal and
-* Mnemocyte's configured timeout. Timeout aborts are actively propagated to
-* providers that honor `AbortSignal`.
-*/
-function runAttempt(action, timeoutMs, signal) {
-	if (timeoutMs <= 0 && !signal) return action(void 0);
-	return new Promise((resolve, reject) => {
-		let settled = false;
-		const controller = new AbortController();
-		const timer = timeoutMs > 0 ? setTimeout(() => {
-			if (settled) return;
-			settled = true;
-			signal?.removeEventListener("abort", onAbort);
-			controller.abort(timeoutError(timeoutMs));
-			reject(timeoutError(timeoutMs));
-		}, timeoutMs) : void 0;
-		const onAbort = () => {
-			if (settled) return;
-			settled = true;
-			if (timer) clearTimeout(timer);
-			controller.abort(signal?.reason);
-			reject(new MnemocyteError("Operation was aborted.", "ABORTED", signal?.reason));
-		};
-		if (signal) {
-			if (signal.aborted) {
-				if (timer) clearTimeout(timer);
-				settled = true;
-				controller.abort(signal.reason);
-				reject(new MnemocyteError("Operation was aborted.", "ABORTED", signal.reason));
-				return;
-			}
-			signal.addEventListener("abort", onAbort, { once: true });
-		}
-		action(controller.signal).then((value) => {
-			if (settled) return;
-			settled = true;
-			if (timer) clearTimeout(timer);
-			signal?.removeEventListener("abort", onAbort);
-			resolve(value);
-		}, (error) => {
-			if (settled) return;
-			settled = true;
-			if (timer) clearTimeout(timer);
-			signal?.removeEventListener("abort", onAbort);
-			reject(error);
+	}
+}
+async function observeFromStartedAt(config, backend, operation, metadata, startedAt, action, successMetadata) {
+	await emitObservation(config, withMetadata({
+		operation,
+		phase: "start",
+		backend,
+		timestamp: new Date(startedAt)
+	}, metadata));
+	try {
+		const result = await action();
+		await emitObservation(config, withMetadata({
+			operation,
+			phase: "success",
+			backend,
+			timestamp: /* @__PURE__ */ new Date(),
+			durationMs: Date.now() - startedAt
+		}, {
+			...metadata,
+			...successMetadata?.(result)
+		}));
+		return result;
+	} catch (error) {
+		await emitObservation(config, withMetadata({
+			operation,
+			phase: "error",
+			backend,
+			timestamp: /* @__PURE__ */ new Date(),
+			durationMs: Date.now() - startedAt,
+			error
+		}, metadata));
+		throw error;
+	}
+}
+function observe(config, backend, operation, metadata, action, successMetadata) {
+	return observeFromStartedAt(config, backend, operation, metadata, Date.now(), action, successMetadata);
+}
+function observePrepared(config, backend, operation, metadata, prepare, action, successMetadata) {
+	const startedAt = Date.now();
+	try {
+		const prepared = prepare();
+		return observeFromStartedAt(config, backend, operation, metadata, startedAt, () => action(prepared), successMetadata);
+	} catch (error) {
+		return observeFromStartedAt(config, backend, operation, metadata, startedAt, async () => {
+			throw error;
 		});
-	});
+	}
 }
 /**
-* Run `action` with timeout, retry, and abort handling derived from
-* `options.resilience` and `options.signal`. Each retry attempt receives
-* a fresh `AbortSignal` linked to the caller's signal — so callers may
-* abort mid-retry and the in-flight attempt will cancel promptly if the
-* underlying provider honours signals.
-*
-* Errors from {@link MnemocyteError} with code `"VALIDATION"` /
-* `"CONFIG"` / `"ABORTED"` are never retried.
+* Ordering of {@link ImportanceLevel} from least to most important. Used
+* by `prune({ maxImportance })` to compare a memory's importance against
+* the caller-supplied ceiling.
 */
-async function withResilience(action, options = {}) {
-	const config = options.resilience ?? {};
-	const timeoutMs = config.timeoutMs ?? DEFAULT_TIMEOUT_MS;
-	const retries = Math.max(0, config.retries ?? DEFAULT_RETRIES);
-	const baseDelayMs = Math.max(0, config.baseDelayMs ?? DEFAULT_BASE_DELAY_MS);
-	const maxDelayMs = Math.max(baseDelayMs, config.maxDelayMs ?? DEFAULT_MAX_DELAY_MS);
-	const shouldRetry = config.shouldRetry ?? defaultShouldRetry;
-	const externalSignal = options.signal;
-	throwIfAborted(externalSignal);
-	const maxAttempts = retries + 1;
-	let lastError;
-	for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
-		throwIfAborted(externalSignal);
-		try {
-			return await runAttempt(action, timeoutMs, externalSignal);
-		} catch (error) {
-			lastError = error;
-			if (error instanceof MnemocyteError && error.code === "ABORTED") throw error;
-			if (attempt >= maxAttempts) throw error;
-			if (!shouldRetry(error, attempt)) throw error;
-			await delay(computeDelayMs(attempt, baseDelayMs, maxDelayMs), externalSignal);
-		}
-	}
-	throw lastError;
-}
+const IMPORTANCE_RANK = {
+	low: 0,
+	normal: 1,
+	high: 2,
+	critical: 3
+};
 //#endregion
 //#region src/memory/embeddings.ts
 function validateEmbedding(embedding, dimensions) {
 	if (embedding.length !== dimensions) throw new MnemocyteError("Embedder returned an embedding with unexpected dimensions.", "EMBEDDING");
 	if (embedding.some((component) => !Number.isFinite(component))) throw new MnemocyteError("Embedder returned an embedding with non-finite values.", "EMBEDDING");
+	if (embedding.every((component) => component === 0)) throw new MnemocyteError("Embedder returned an embedding with zero norm.", "EMBEDDING");
 }
 async function embedOne(embedder, text, options = {}) {
 	let embeddings;
@@ -677,7 +707,48 @@ async function embedMany(embedder, texts, options = {}) {
 	return embeddings;
 }
 //#endregion
+//#region src/memory/store.ts
+function hasPruneSelector(filter) {
+	return filter.entityId !== void 0 || filter.expired === true || filter.superseded === true || filter.createdBefore !== void 0 || filter.notAccessedSince !== void 0 || filter.types !== void 0 && filter.types.length > 0 || filter.tags !== void 0 && filter.tags.length > 0 || filter.maxImportance !== void 0;
+}
+function assertPruneFilterHasSelector(filter) {
+	if (!hasPruneSelector(filter)) throw new MnemocyteError("prune requires at least one selector (entityId, expired, superseded, createdBefore, notAccessedSince, types, tags, or maxImportance).", "VALIDATION");
+}
+//#endregion
 //#region src/memory/validation.ts
+const MEMORY_TYPES = [
+	"fact",
+	"preference",
+	"instruction",
+	"backstory",
+	"episode",
+	"session"
+];
+const IMPORTANCE_LEVELS$1 = [
+	"low",
+	"normal",
+	"high",
+	"critical"
+];
+function isMemoryType(value) {
+	return typeof value === "string" && MEMORY_TYPES.includes(value);
+}
+function isImportanceLevel(value) {
+	return typeof value === "string" && IMPORTANCE_LEVELS$1.includes(value);
+}
+function assertMemoryType(value, field) {
+	if (!isMemoryType(value)) throw new MnemocyteError(`${field} must be a known memory type.`, "VALIDATION");
+}
+function assertImportanceLevel(value, field) {
+	if (!isImportanceLevel(value)) throw new MnemocyteError(`${field} must be a known importance level.`, "VALIDATION");
+}
+function assertMemoryTypeArray(value, field) {
+	if (!Array.isArray(value)) throw new MnemocyteError(`${field} must be an array.`, "VALIDATION");
+	for (const item of value) if (!isMemoryType(item)) throw new MnemocyteError(`${field} must contain only known memory types.`, "VALIDATION");
+}
+function assertValidDate(value, field) {
+	if (!(value instanceof Date) || !Number.isFinite(value.getTime())) throw new MnemocyteError(`${field} must be a valid Date.`, "VALIDATION");
+}
 function assertNonEmptyString(value, field, code = "VALIDATION") {
 	if (typeof value !== "string" || value.trim().length === 0) throw new MnemocyteError(`${field} must be a non-empty string.`, code);
 }
@@ -716,20 +787,39 @@ function validateRetrievalConfig(config) {
 	if (config.accessSaturation !== void 0) assertPositiveFiniteConfigValue(config.accessSaturation, "retrieval.accessSaturation");
 	if (config.candidateMultiplier !== void 0 && (!Number.isInteger(config.candidateMultiplier) || config.candidateMultiplier < 1)) throw new MnemocyteError("retrieval.candidateMultiplier must be an integer greater than or equal to 1.", "CONFIG");
 }
+function validateProviderResilienceConfig(config) {
+	if (config === void 0) return;
+	if (typeof config !== "object" || config === null || Array.isArray(config)) throw new MnemocyteError("provider must be an object.", "CONFIG");
+	for (const [field, value] of [
+		["provider.timeoutMs", config.timeoutMs],
+		["provider.baseDelayMs", config.baseDelayMs],
+		["provider.maxDelayMs", config.maxDelayMs]
+	]) if (value !== void 0 && (!Number.isFinite(value) || value < 0)) throw new MnemocyteError(`${field} must be a non-negative finite number.`, "CONFIG");
+	if (config.retries !== void 0 && (!Number.isInteger(config.retries) || config.retries < 0)) throw new MnemocyteError("provider.retries must be a non-negative integer.", "CONFIG");
+	if (config.shouldRetry !== void 0 && typeof config.shouldRetry !== "function") throw new MnemocyteError("provider.shouldRetry must be a function.", "CONFIG");
+}
 function validateBuildContextInput(input) {
 	if (input.maxTokens !== void 0 && (!Number.isInteger(input.maxTokens) || input.maxTokens < 1)) throw new MnemocyteError("maxTokens must be a positive integer when supplied.", "VALIDATION");
 }
 function validateRememberInput(input) {
 	assertNonEmptyString(input.entityId, "entityId");
 	assertNonEmptyString(input.content, "content");
-	if (input.metadata !== void 0) validateJsonObject(input.metadata);
+	if (input.type !== void 0) assertMemoryType(input.type, "type");
+	if (input.importance !== void 0) assertImportanceLevel(input.importance, "importance");
+	if (input.tags !== void 0) {
+		if (!Array.isArray(input.tags)) throw new MnemocyteError("tags must be an array.", "VALIDATION");
+		for (const tag of input.tags) if (typeof tag !== "string") throw new MnemocyteError("tags must contain only strings.", "VALIDATION");
+	}
+	if (input.source !== void 0 && typeof input.source !== "string") throw new MnemocyteError("source must be a string.", "VALIDATION");
 	if (input.confidence !== void 0 && (!Number.isFinite(input.confidence) || input.confidence < 0 || input.confidence > 1)) throw new MnemocyteError("confidence must be a number between 0 and 1.", "VALIDATION");
+	if (input.expiresAt !== void 0) assertValidDate(input.expiresAt, "expiresAt");
 }
 function validateRecallInput(input) {
 	assertNonEmptyString(input.entityId, "entityId");
 	assertNonEmptyString(input.query, "query");
 	if (input.limit !== void 0) assertLimit(input.limit);
 	if (input.minScore !== void 0) assertMinScore(input.minScore);
+	if (input.types !== void 0) assertMemoryTypeArray(input.types, "types");
 }
 function contextInputToRecallInput(input) {
 	return {
@@ -744,13 +834,49 @@ function contextInputToRecallInput(input) {
 	};
 }
 /**
-* Validate a {@link PruneInput} and throw a `"VALIDATION"`
-* {@link MnemocyteError} when no selector is supplied. Mnemocyte
-* deliberately rejects `prune({})` to avoid surprise full-table deletes.
+* Validate and normalize a {@link PruneInput}. Throws a `"VALIDATION"`
+* {@link MnemocyteError} for malformed fields or when normalization leaves no
+* effective selector, preventing surprise full-table deletes.
 */
 function validatePruneInput(input) {
 	if (input.entityId !== void 0) assertNonEmptyString(input.entityId, "entityId");
-	if (!(input.entityId !== void 0 || input.expired === true || input.superseded === true || input.createdBefore !== void 0 || input.notAccessedSince !== void 0 || input.types !== void 0 && input.types.length > 0 || input.tags !== void 0 && input.tags.length > 0 || input.maxImportance !== void 0)) throw new MnemocyteError("prune requires at least one selector (entityId, expired, superseded, createdBefore, notAccessedSince, types, tags, or maxImportance).", "VALIDATION");
+	for (const [field, value] of [
+		["expired", input.expired],
+		["superseded", input.superseded],
+		["dryRun", input.dryRun]
+	]) if (value !== void 0 && typeof value !== "boolean") throw new MnemocyteError(`${field} must be a boolean.`, "VALIDATION");
+	for (const [field, value] of [["createdBefore", input.createdBefore], ["notAccessedSince", input.notAccessedSince]]) if (value !== void 0) assertValidDate(value, field);
+	let types;
+	if (input.types !== void 0) {
+		assertMemoryTypeArray(input.types, "types");
+		const normalized = new Set(input.types);
+		if (normalized.size > 0) types = [...normalized];
+	}
+	let tags;
+	if (input.tags !== void 0) {
+		if (!Array.isArray(input.tags)) throw new MnemocyteError("tags must be an array.", "VALIDATION");
+		const normalized = /* @__PURE__ */ new Set();
+		for (const value of input.tags) {
+			if (typeof value !== "string" || value.trim().length === 0) throw new MnemocyteError("tags must contain only non-empty strings.", "VALIDATION");
+			normalized.add(value.trim());
+		}
+		if (normalized.size > 0) tags = [...normalized];
+	}
+	if (input.maxImportance !== void 0) assertImportanceLevel(input.maxImportance, "maxImportance");
+	if (input.signal !== void 0 && (typeof input.signal !== "object" || input.signal === null || typeof input.signal.aborted !== "boolean" || typeof input.signal.addEventListener !== "function" || typeof input.signal.removeEventListener !== "function")) throw new MnemocyteError("signal must be an AbortSignal.", "VALIDATION");
+	const filter = {
+		...input.entityId === void 0 ? {} : { entityId: input.entityId },
+		...input.expired === true ? { expired: true } : {},
+		...input.superseded === true ? { superseded: true } : {},
+		...input.createdBefore === void 0 ? {} : { createdBefore: new Date(input.createdBefore) },
+		...input.notAccessedSince === void 0 ? {} : { notAccessedSince: new Date(input.notAccessedSince) },
+		...types === void 0 ? {} : { types },
+		...tags === void 0 ? {} : { tags },
+		...input.maxImportance === void 0 ? {} : { maxImportance: input.maxImportance },
+		dryRun: input.dryRun === true
+	};
+	assertPruneFilterHasSelector(filter);
+	return filter;
 }
 /**
 * Validate a {@link FindDuplicatesInput} and throw a `"VALIDATION"`
@@ -762,6 +888,7 @@ function validateFindDuplicatesInput(input) {
 		if (!Number.isFinite(input.threshold) || input.threshold < 0 || input.threshold > 1) throw new MnemocyteError("threshold must be a number between 0 and 1.", "VALIDATION");
 	}
 	if (input.limit !== void 0) assertLimit(input.limit);
+	if (input.types !== void 0) assertMemoryTypeArray(input.types, "types");
 }
 /**
 * Validate a {@link ConsolidateInput} and throw a `"VALIDATION"`
@@ -782,6 +909,16 @@ function validateConsolidateInput(input) {
 function validateListAuditLogInput(input) {
 	assertNonEmptyString(input.entityId, "entityId");
 	if (input.limit !== void 0) assertLimit(input.limit);
+	for (const [field, cursor] of [["beforeCursor", input.beforeCursor], ["afterCursor", input.afterCursor]]) {
+		if (cursor === void 0) continue;
+		assertAuditLogCursor(cursor, field);
+	}
+}
+function assertAuditLogCursor(value, field) {
+	if (typeof value !== "object" || value === null) throw new MnemocyteError(`${field} must be an audit-log cursor.`, "VALIDATION");
+	const cursor = value;
+	assertValidDate(cursor.timestamp, `${field}.timestamp`);
+	assertNonEmptyString(cursor.id, `${field}.id`);
 }
 //#endregion
 //#region src/memory/client-core.ts
@@ -794,6 +931,17 @@ function providerOptions(config, signal) {
 		...config.provider === void 0 ? {} : { resilience: config.provider }
 	};
 }
+function storeOptions(signal) {
+	return signal === void 0 ? void 0 : { signal };
+}
+function snapshotRememberInput(input) {
+	return {
+		...input,
+		...input.tags === void 0 ? {} : { tags: Array.isArray(input.tags) ? [...input.tags] : input.tags },
+		metadata: cloneJsonObject(input.metadata ?? {}),
+		...input.expiresAt === void 0 ? {} : { expiresAt: input.expiresAt instanceof Date ? new Date(input.expiresAt) : input.expiresAt }
+	};
+}
 function createStoredMemory(config, input, embedding, now) {
 	return {
 		id: createId(),
@@ -803,7 +951,7 @@ function createStoredMemory(config, input, embedding, now) {
 		importance: input.importance ?? "normal",
 		tags: normalizeTags(input.tags),
 		source: input.source ?? null,
-		metadata: cloneJsonObject(input.metadata ?? {}),
+		metadata: input.metadata,
 		confidence: input.confidence ?? 1,
 		embeddingModel: config.embedder.model,
 		embeddingDimensions: config.embedder.dimensions,
@@ -822,10 +970,35 @@ function auditEvent(entityId, description, metadata, timestamp = /* @__PURE__ */
 		id: createEventId(),
 		entityId,
 		description,
-		metadata: cloneJsonObject(metadata),
+		metadata,
 		timestamp
 	};
 }
+function normalizeStoreRows(expected, returned, operation) {
+	const expectedIds = new Set(expected.map((memory) => memory.id));
+	const returnedById = /* @__PURE__ */ new Map();
+	for (const row of returned) {
+		if (!expectedIds.has(row.id)) throw new MnemocyteError(`${operation} returned an unknown ID.`, "DB");
+		if (returnedById.has(row.id)) throw new MnemocyteError(`${operation} returned a duplicate ID.`, "DB");
+		returnedById.set(row.id, row);
+	}
+	return expected.map((row) => {
+		const returnedRow = returnedById.get(row.id);
+		if (!returnedRow) throw new MnemocyteError(`${operation} did not return every requested ID.`, "DB");
+		return returnedRow;
+	});
+}
+function normalizePruneEntityDeletions(result, expectedEntityId) {
+	const seenEntityIds = /* @__PURE__ */ new Set();
+	let detailedDeletedCount = 0;
+	for (const detail of result.deletedByEntity) {
+		if (detail.entityId.length === 0 || !Number.isInteger(detail.deletedCount) || detail.deletedCount <= 0 || seenEntityIds.has(detail.entityId) || expectedEntityId !== void 0 && detail.entityId !== expectedEntityId) throw new MnemocyteError("Memory prune returned invalid per-entity deletion details.", "DB");
+		seenEntityIds.add(detail.entityId);
+		detailedDeletedCount += detail.deletedCount;
+	}
+	if (detailedDeletedCount !== result.deletedCount || result.dryRun && result.deletedByEntity.length > 0) throw new MnemocyteError("Memory prune deletion details did not match the deleted count.", "DB");
+	return [...result.deletedByEntity].sort((a, b) => a.entityId.localeCompare(b.entityId));
+}
 function toDuplicatePair(pair) {
 	return {
 		a: cloneMemory(pair.a),
@@ -834,9 +1007,58 @@ function toDuplicatePair(pair) {
 	};
 }
 function createMemoryClient(config, store) {
-	let closed = false;
+	let state = "open";
+	let activeOperations = 0;
+	let operationsDrainedPromise;
+	let resolveOperationsDrained;
+	let closePromise;
 	function assertOpen() {
-		if (closed) throw new MnemocyteError("Mnemocyte client is closed.", "DB");
+		if (state === "closed") throw new MnemocyteError("Mnemocyte client is closed.", "DB");
+	}
+	function beginOperation() {
+		if (state !== "open") throw new MnemocyteError("Mnemocyte client is closed.", "DB");
+		activeOperations += 1;
+		let completed = false;
+		return () => {
+			if (completed) return;
+			completed = true;
+			activeOperations -= 1;
+			if (activeOperations === 0 && resolveOperationsDrained) {
+				const resolve = resolveOperationsDrained;
+				resolveOperationsDrained = void 0;
+				operationsDrainedPromise = void 0;
+				resolve();
+			}
+		};
+	}
+	function runOperation(operationName, metadata, operation) {
+		let complete;
+		try {
+			complete = beginOperation();
+		} catch (error) {
+			return observe(config, store.backend, operationName, metadata, async () => {
+				throw error;
+			});
+		}
+		try {
+			return operation().then((result) => {
+				complete();
+				return result;
+			}, (error) => {
+				complete();
+				throw error;
+			});
+		} catch (error) {
+			complete();
+			return Promise.reject(error);
+		}
+	}
+	function waitForActiveOperations() {
+		if (activeOperations === 0) return Promise.resolve();
+		if (!operationsDrainedPromise) operationsDrainedPromise = new Promise((resolve) => {
+			resolveOperationsDrained = resolve;
+		});
+		return operationsDrainedPromise;
 	}
 	async function ensureSchema() {
 		await store.ensureSchema();
@@ -850,38 +1072,34 @@ function createMemoryClient(config, store) {
 			await store.addAuditEvents(events);
 		} catch {}
 	}
-	async function remember(input) {
-		const preparedInput = {
-			...input,
-			metadata: cloneJsonObject(input.metadata ?? {})
-		};
-		return observe(config, store.backend, "remember", { entityId: preparedInput.entityId }, async () => {
+	function remember(input) {
+		return runOperation("remember", { entityId: input.entityId }, () => observePrepared(config, store.backend, "remember", { entityId: input.entityId }, () => snapshotRememberInput(input), async (preparedInput) => {
 			assertOpen();
 			validateRememberInput(preparedInput);
 			await ensureEmbeddingCompatibility();
-			const embedding = await embedOne(config.embedder, preparedInput.content, providerOptions(config, preparedInput.signal));
-			const [memory] = await store.insertMemories([createStoredMemory(config, preparedInput, embedding, /* @__PURE__ */ new Date())]);
-			if (!memory) throw new MnemocyteError("Memory insert returned no rows.", "DB");
+			const stored = [createStoredMemory(config, preparedInput, await embedOne(config.embedder, preparedInput.content, providerOptions(config, preparedInput.signal)), /* @__PURE__ */ new Date())];
+			const [memory] = normalizeStoreRows(stored, await store.insertMemories(stored), "Memory insert");
+			if (!memory) throw new MnemocyteError("Memory insert did not return the inserted ID.", "DB");
 			await recordAudit([auditEvent(memory.entityId, "memory.created", {
 				memoryId: memory.id,
 				type: memory.type,
 				importance: memory.importance
 			})]);
-			return cloneMemory(memory);
+			return memory;
 		}, (memory) => ({
 			memoryId: memory.id,
 			count: 1
-		}));
+		})));
 	}
-	async function rememberMany(input) {
-		const positional = isPositionalRememberManyInput(input);
-		const inputs = positional ? input : input.inputs;
-		const signal = positional ? input[0]?.signal : input.signal;
-		const preparedInputs = inputs.map((item) => ({
-			...item,
-			metadata: cloneJsonObject(item.metadata ?? {})
-		}));
-		return observe(config, store.backend, "rememberMany", { count: preparedInputs.length }, async () => {
+	function rememberMany(input) {
+		const count = isPositionalRememberManyInput(input) ? input.length : input.inputs.length;
+		return runOperation("rememberMany", { count }, () => observePrepared(config, store.backend, "rememberMany", { count }, () => {
+			const positional = isPositionalRememberManyInput(input);
+			return {
+				preparedInputs: (positional ? input : input.inputs).map(snapshotRememberInput),
+				signal: positional ? input[0]?.signal : input.signal
+			};
+		}, async ({ preparedInputs, signal }) => {
 			assertOpen();
 			if (preparedInputs.length === 0) return [];
 			for (const item of preparedInputs) validateRememberInput(item);
@@ -889,86 +1107,101 @@ function createMemoryClient(config, store) {
 			const embeddings = await embedMany(config.embedder, preparedInputs.map((item) => item.content), providerOptions(config, signal));
 			const now = /* @__PURE__ */ new Date();
 			const stored = preparedInputs.map((item, idx) => createStoredMemory(config, item, embeddings[idx], now));
-			const memories = await store.insertMemories(stored);
+			const memories = normalizeStoreRows(stored, await store.insertMemories(stored), "Memory insert");
 			await recordAudit(memories.map((memory) => auditEvent(memory.entityId, "memory.created", {
 				memoryId: memory.id,
 				type: memory.type,
 				importance: memory.importance
 			})));
-			return memories.map(cloneMemory);
+			return memories;
+		}, (result) => ({ count: result.length })));
+	}
+	function recall(input) {
+		return observe(config, store.backend, "recall", { entityId: input.entityId }, async () => {
+			assertOpen();
+			validateRecallInput(input);
+			const limit = input.limit ?? config.defaults?.limit ?? 10;
+			const minScore = input.minScore ?? config.defaults?.minScore ?? 0;
+			assertLimit(limit);
+			assertMinScore(minScore);
+			await ensureEmbeddingCompatibility();
+			const queryEmbedding = await embedOne(config.embedder, input.query, providerOptions(config, input.signal));
+			const candidateMultiplier = config.retrieval?.candidateMultiplier ?? 3;
+			const candidateLimit = Math.max(limit, limit * candidateMultiplier);
+			const scoreLexical = createLexicalScorer(input.query);
+			const scoringConfig = createScoringConfig(config.retrieval);
+			const [vectorCandidates, lexicalCandidates] = await Promise.all([store.vectorSearch({
+				...input,
+				embedding: queryEmbedding,
+				limit: candidateLimit,
+				minVectorScore: 0
+			}), store.lexicalSearch({
+				...input,
+				limit: candidateLimit
+			})]);
+			const merged = /* @__PURE__ */ new Map();
+			for (const candidate of vectorCandidates) merged.set(candidate.memory.id, {
+				memory: candidate.memory,
+				vectorScore: candidate.vectorScore,
+				lexicalScore: scoreLexical(candidate.memory.content)
+			});
+			const lexicalOnly = lexicalCandidates.filter((candidate) => !merged.has(candidate.memory.id));
+			const lexicalOnlyEmbeddings = await store.getMemoryEmbeddings(lexicalOnly.map((candidate) => candidate.memory.id));
+			for (const candidate of lexicalCandidates) {
+				const existing = merged.get(candidate.memory.id);
+				if (existing) {
+					existing.lexicalScore = candidate.lexicalScore;
+					continue;
+				}
+				const embedding = lexicalOnlyEmbeddings.get(candidate.memory.id);
+				const similarity = embedding ? cosineSimilarity(embedding, queryEmbedding) : 0;
+				merged.set(candidate.memory.id, {
+					memory: candidate.memory,
+					vectorScore: toVectorScore(similarity),
+					lexicalScore: candidate.lexicalScore
+				});
+			}
+			const scored = Array.from(merged.values()).map((entry) => toScoredMemoryWithConfig(entry.memory, Math.max(0, entry.vectorScore), Math.max(0, entry.lexicalScore), input, scoringConfig)).filter((memory) => memory.score >= minScore).sort((a, b) => b.score - a.score).slice(0, limit);
+			const accessUpdates = normalizeStoreRows(scored, await store.markMemoriesAccessed(scored.map((memory) => memory.id)), "Memory access update");
+			return scored.map((memory, index) => {
+				const update = accessUpdates[index];
+				if (!update) throw new MnemocyteError("Memory access update did not return every requested ID.", "DB");
+				return {
+					...memory,
+					lastAccessedAt: new Date(update.lastAccessedAt),
+					accessCount: update.accessCount,
+					updatedAt: new Date(update.updatedAt)
+				};
+			});
 		}, (result) => ({ count: result.length }));
 	}
-	const client = {
+	return {
 		remember,
 		rememberMany,
-		async recall(input) {
-			return observe(config, store.backend, "recall", { entityId: input.entityId }, async () => {
-				assertOpen();
-				validateRecallInput(input);
-				const limit = input.limit ?? config.defaults?.limit ?? 10;
-				const minScore = input.minScore ?? config.defaults?.minScore ?? 0;
-				assertLimit(limit);
-				assertMinScore(minScore);
-				await ensureEmbeddingCompatibility();
-				const queryEmbedding = await embedOne(config.embedder, input.query, providerOptions(config, input.signal));
-				const candidateMultiplier = config.retrieval?.candidateMultiplier ?? 3;
-				const candidateLimit = Math.max(limit, limit * candidateMultiplier);
-				const scoreLexical = createLexicalScorer(input.query);
-				const scoringConfig = createScoringConfig(config.retrieval);
-				const [vectorCandidates, lexicalCandidates] = await Promise.all([store.vectorSearch({
-					...input,
-					embedding: queryEmbedding,
-					limit: candidateLimit,
-					minScore: 0
-				}), store.lexicalSearch({
-					...input,
-					limit: candidateLimit
-				})]);
-				const merged = /* @__PURE__ */ new Map();
-				for (const candidate of vectorCandidates) merged.set(candidate.memory.id, {
-					memory: candidate.memory,
-					vectorScore: candidate.vectorScore,
-					lexicalScore: scoreLexical(candidate.memory.content)
-				});
-				const lexicalOnly = lexicalCandidates.filter((candidate) => !merged.has(candidate.memory.id));
-				const lexicalOnlyEmbeddings = await store.getMemoryEmbeddings(lexicalOnly.map((candidate) => candidate.memory.id));
-				for (const candidate of lexicalCandidates) {
-					const existing = merged.get(candidate.memory.id);
-					if (existing) {
-						existing.lexicalScore = candidate.lexicalScore;
-						continue;
-					}
-					const embedding = lexicalOnlyEmbeddings.get(candidate.memory.id);
-					const similarity = embedding ? cosineSimilarity(embedding, queryEmbedding) : 0;
-					merged.set(candidate.memory.id, {
-						memory: candidate.memory,
-						vectorScore: Math.max(0, similarity),
-						lexicalScore: candidate.lexicalScore
-					});
-				}
-				const scored = Array.from(merged.values()).map((entry) => toScoredMemoryWithConfig(entry.memory, Math.max(0, entry.vectorScore), Math.max(0, entry.lexicalScore), input, scoringConfig)).filter((memory) => memory.score >= minScore).sort((a, b) => b.score - a.score).slice(0, limit);
-				await store.markMemoriesAccessed(scored.map((memory) => memory.id));
-				return scored;
-			}, (result) => ({ count: result.length }));
+		recall(input) {
+			return runOperation("recall", { entityId: input.entityId }, () => recall(input));
 		},
-		async buildContext(input) {
-			return observe(config, store.backend, "buildContext", { entityId: input.entityId }, async () => {
+		buildContext(input) {
+			return runOperation("buildContext", { entityId: input.entityId }, () => observe(config, store.backend, "buildContext", { entityId: input.entityId }, async () => {
 				assertOpen();
 				validateBuildContextInput(input);
 				return buildContext({
 					input,
 					recall: (contextInput) => {
 						const recallInput = contextInputToRecallInput(contextInput);
-						return client.recall(input.signal === void 0 ? recallInput : {
+						return recall(input.signal === void 0 ? recallInput : {
 							...recallInput,
 							signal: input.signal
 						});
 					}
 				});
-			});
+			}));
 		},
-		async forget(input) {
-			return observe(config, store.backend, "forget", {
+		forget(input) {
+			return runOperation("forget", {
+				entityId: input.entityId,
+				memoryId: input.memoryId
+			}, () => observe(config, store.backend, "forget", {
 				entityId: input.entityId,
 				memoryId: input.memoryId
 			}, async () => {
@@ -978,73 +1211,81 @@ function createMemoryClient(config, store) {
 				await ensureSchema();
 				if (!await store.deleteMemory(input.entityId, input.memoryId)) throw new MnemocyteError("Memory was not found.", "NOT_FOUND");
 				await recordAudit([auditEvent(input.entityId, "memory.deleted", { memoryId: input.memoryId })]);
-			});
+			}));
 		},
-		async forgetAll(input) {
-			return observe(config, store.backend, "forgetAll", { entityId: input.entityId }, async () => {
+		forgetAll(input) {
+			return runOperation("forgetAll", { entityId: input.entityId }, () => observe(config, store.backend, "forgetAll", { entityId: input.entityId }, async () => {
 				assertOpen();
 				assertNonEmptyString(input.entityId, "entityId");
 				await ensureSchema();
 				const deletedCount = await store.deleteMemoriesForEntity(input.entityId);
 				await recordAudit([auditEvent(input.entityId, "entity.cleared", { count: deletedCount })]);
 				return deletedCount;
-			}, (count) => ({ count })).then(() => void 0);
+			}, (count) => ({ count })).then(() => void 0));
 		},
-		async prune(input) {
-			return observe(config, store.backend, "prune", input.entityId === void 0 ? {} : { entityId: input.entityId }, async () => {
+		prune(input) {
+			return runOperation("prune", input.entityId === void 0 ? {} : { entityId: input.entityId }, () => observe(config, store.backend, "prune", input.entityId === void 0 ? {} : { entityId: input.entityId }, async () => {
 				assertOpen();
-				validatePruneInput(input);
+				throwIfAborted(input.signal);
+				const filter = validatePruneInput(input);
 				await ensureSchema();
-				const result = await store.prune(input);
-				if (result.deletedCount > 0 && input.entityId !== void 0 && result.dryRun === false) await recordAudit([auditEvent(input.entityId, "memory.pruned", { count: result.deletedCount })]);
-				return result;
-			}, (result) => ({ count: result.deletedCount }));
+				const result = await store.prune(filter, storeOptions(input.signal));
+				const deletedByEntity = normalizePruneEntityDeletions(result, input.entityId);
+				if (result.deletedCount > 0 && result.dryRun === false) await recordAudit(deletedByEntity.map((detail) => auditEvent(detail.entityId, "memory.pruned", { count: detail.deletedCount })));
+				return {
+					matchedCount: result.matchedCount,
+					deletedCount: result.deletedCount,
+					dryRun: result.dryRun
+				};
+			}, (result) => ({ count: result.deletedCount })));
 		},
-		async findDuplicates(input) {
-			return observe(config, store.backend, "findDuplicates", { entityId: input.entityId }, async () => {
+		findDuplicates(input) {
+			return runOperation("findDuplicates", { entityId: input.entityId }, () => observe(config, store.backend, "findDuplicates", { entityId: input.entityId }, async () => {
 				assertOpen();
+				throwIfAborted(input.signal);
 				validateFindDuplicatesInput(input);
 				await ensureEmbeddingCompatibility();
-				return (await store.findDuplicatePairs(input)).map(toDuplicatePair);
-			}, (result) => ({ count: result.length }));
+				return (await store.findDuplicatePairs(input, storeOptions(input.signal))).map(toDuplicatePair);
+			}, (result) => ({ count: result.length })));
 		},
-		async listAuditLog(input) {
-			return observe(config, store.backend, "listAuditLog", { entityId: input.entityId }, async () => {
+		listAuditLog(input) {
+			return runOperation("listAuditLog", { entityId: input.entityId }, () => observe(config, store.backend, "listAuditLog", { entityId: input.entityId }, async () => {
 				assertOpen();
+				throwIfAborted(input.signal);
 				validateListAuditLogInput(input);
 				await ensureSchema();
-				return (await store.listAuditLog(input)).map((event) => ({
-					id: event.id,
-					entityId: event.entityId,
-					description: event.description,
-					metadata: cloneJsonObject(event.metadata),
-					timestamp: new Date(event.timestamp)
-				}));
-			}, (result) => ({ count: result.length }));
+				return await store.listAuditLog(input, storeOptions(input.signal));
+			}, (result) => ({ count: result.length })));
 		},
-		async stats(input) {
-			return observe(config, store.backend, "stats", input?.entityId ? { entityId: input.entityId } : {}, async () => {
+		stats(input) {
+			return runOperation("stats", input?.entityId ? { entityId: input.entityId } : {}, () => observe(config, store.backend, "stats", input?.entityId ? { entityId: input.entityId } : {}, async () => {
 				assertOpen();
 				await ensureSchema();
 				return store.stats(input, /* @__PURE__ */ new Date());
-			});
+			}));
 		},
-		experimental: { async consolidate(input) {
-			return observe(config, store.backend, "consolidate", {
+		experimental: { consolidate(input) {
+			return runOperation("consolidate", {
+				entityId: input.entityId,
+				memoryId: input.survivorId
+			}, () => observe(config, store.backend, "consolidate", {
 				entityId: input.entityId,
 				memoryId: input.survivorId
 			}, async () => {
 				assertOpen();
+				throwIfAborted(input.signal);
 				validateConsolidateInput(input);
 				await ensureSchema();
-				const survivor = await store.getMemory(input.entityId, input.survivorId);
+				const survivor = await store.getMemory(input.entityId, input.survivorId, storeOptions(input.signal));
+				throwIfAborted(input.signal);
 				if (!survivor) throw new MnemocyteError("Survivor memory was not found.", "NOT_FOUND");
 				if (survivor.supersededBy !== null) throw new MnemocyteError("Survivor memory is itself superseded.", "VALIDATION");
-				const targets = await store.loadConsolidationTargets(input.entityId, input.supersededIds);
+				const targets = await store.loadConsolidationTargets(input.entityId, input.supersededIds, storeOptions(input.signal));
+				throwIfAborted(input.signal);
 				const foundIds = new Set(targets.map((target) => target.id));
 				for (const id of input.supersededIds) if (!foundIds.has(id)) throw new MnemocyteError("Superseded memory was not found.", "NOT_FOUND");
-				const losers = targets.filter((target) => target.supersededBy === null);
-				if (losers.length === 0) return {
+				if (targets.some((target) => target.supersededBy !== null && target.supersededBy !== survivor.id)) throw new MnemocyteError("Superseded memory already belongs to a different survivor.", "CONFLICT");
+				if (targets.filter((target) => target.supersededBy === null).length === 0) return {
 					survivorId: survivor.id,
 					supersededCount: 0,
 					supersededIds: []
@@ -1053,28 +1294,40 @@ function createMemoryClient(config, store) {
 					entityId: input.entityId,
 					survivorId: survivor.id,
 					survivorTags: survivor.tags,
-					supersededIds: losers.map((loser) => loser.id),
+					supersededIds: input.supersededIds,
 					mergeTags: input.mergeTags !== false,
 					now: /* @__PURE__ */ new Date(),
 					auditEnabled: config.audit?.enabled === true
-				});
+				}, storeOptions(input.signal));
 				return {
 					survivorId: survivor.id,
 					supersededCount: result.supersededIds.length,
 					supersededIds: result.supersededIds
 				};
-			}, (result) => ({ count: result.supersededCount }));
+			}, (result) => ({ count: result.supersededCount })));
 		} },
-		async close() {
-			return observe(config, store.backend, "close", {}, async () => {
-				if (!closed) {
-					closed = true;
+		close() {
+			if (closePromise) return closePromise;
+			state = "closing";
+			closePromise = observe(config, store.backend, "close", {}, async () => {
+				await waitForActiveOperations();
+				try {
 					await store.close();
+					state = "closed";
+				} catch (error) {
+					state = "open";
+					closePromise = void 0;
+					throw error;
 				}
 			});
+			return closePromise;
 		}
 	};
-	return client;
+}
+//#endregion
+//#region src/memory/deletion.ts
+function memoryHasDependentsError(cause) {
+	return new MnemocyteError("Memory cannot be deleted while other memories reference it as their consolidation survivor.", "CONFLICT", cause);
 }
 //#endregion
 //#region src/memory/filters.ts
@@ -1082,7 +1335,7 @@ function isExpired(memory, now) {
 	return memory.expiresAt !== null && memory.expiresAt.getTime() <= now.getTime();
 }
 /**
-* Test whether `memory` matches a {@link PruneInput}. All specified
+* Test whether `memory` matches a validated prune filter. All specified
 * selectors are AND-combined; unspecified selectors do not restrict.
 *
 * `now` is supplied by the caller so callers can share a consistent
@@ -1126,12 +1379,6 @@ function matchesRecallFilter(memory, input, now) {
 }
 //#endregion
 //#region src/memory/in-memory.ts
-function cloneStoredMemory(memory) {
-	return {
-		...cloneMemory(memory),
-		embedding: [...memory.embedding]
-	};
-}
 function cloneAuditEvent(event) {
 	return {
 		id: event.id,
@@ -1141,6 +1388,15 @@ function cloneAuditEvent(event) {
 		timestamp: new Date(event.timestamp)
 	};
 }
+function compareAuditPositions(a, b) {
+	const timestampDifference = a.timestamp.getTime() - b.timestamp.getTime();
+	if (timestampDifference !== 0) return timestampDifference;
+	if (a.id === b.id) return 0;
+	return a.id < b.id ? -1 : 1;
+}
+function assertNoDependentMemories(memories, targetIds) {
+	for (const memory of memories.values()) if (memory.supersededBy !== null && targetIds.has(memory.supersededBy)) throw memoryHasDependentsError();
+}
 function createInMemoryStore() {
 	const memories = /* @__PURE__ */ new Map();
 	const auditLog = [];
@@ -1151,19 +1407,18 @@ function createInMemoryStore() {
 		async insertMemories(rows) {
 			const inserted = [];
 			for (const row of rows) {
-				const stored = cloneStoredMemory(row);
-				memories.set(stored.id, stored);
-				inserted.push(cloneMemory(stored));
+				memories.set(row.id, row);
+				inserted.push(cloneMemory(row));
 			}
 			return inserted;
 		},
 		async vectorSearch(input) {
 			const now = /* @__PURE__ */ new Date();
-			const minScore = input.minScore ?? 0;
+			const minVectorScore = input.minVectorScore ?? 0;
 			return Array.from(memories.values()).filter((memory) => matchesRecallFilter(memory, input, now)).map((memory) => ({
 				memory: cloneMemory(memory),
-				vectorScore: Math.max(0, cosineSimilarity(memory.embedding, input.embedding))
-			})).filter((candidate) => candidate.vectorScore >= minScore).sort((a, b) => b.vectorScore - a.vectorScore).slice(0, input.limit);
+				vectorScore: toVectorScore(cosineSimilarity(memory.embedding, input.embedding))
+			})).filter((candidate) => candidate.vectorScore >= minVectorScore).sort((a, b) => b.vectorScore - a.vectorScore).slice(0, input.limit);
 		},
 		async lexicalSearch(input) {
 			const now = /* @__PURE__ */ new Date();
@@ -1183,50 +1438,82 @@ function createInMemoryStore() {
 		},
 		async markMemoriesAccessed(memoryIds) {
 			const now = /* @__PURE__ */ new Date();
+			const updates = [];
 			for (const id of memoryIds) {
 				const memory = memories.get(id);
 				if (memory) {
 					memory.lastAccessedAt = now;
 					memory.accessCount += 1;
 					memory.updatedAt = now;
+					updates.push({
+						id: memory.id,
+						lastAccessedAt: now,
+						accessCount: memory.accessCount,
+						updatedAt: now
+					});
 				}
 			}
+			return updates;
 		},
 		async deleteMemory(entityId, memoryId) {
 			const memory = memories.get(memoryId);
 			if (!memory || memory.entityId !== entityId) return false;
+			assertNoDependentMemories(memories, new Set([memoryId]));
 			return memories.delete(memoryId);
 		},
 		async deleteMemoriesForEntity(entityId) {
-			let deleted = 0;
-			for (const [id, memory] of memories) if (memory.entityId === entityId) {
-				memories.delete(id);
-				deleted += 1;
-			}
-			return deleted;
+			const targetIds = new Set(Array.from(memories.values()).filter((memory) => memory.entityId === entityId).map((memory) => memory.id));
+			assertNoDependentMemories(memories, targetIds);
+			for (const id of targetIds) memories.delete(id);
+			return targetIds.size;
 		},
-		async prune(input) {
+		async prune(input, options) {
+			throwIfAborted(options?.signal);
+			assertPruneFilterHasSelector(input);
 			const now = /* @__PURE__ */ new Date();
 			const matched = [];
-			for (const memory of memories.values()) if (matchesPruneFilter(memory, input, now)) matched.push(memory.id);
+			for (const memory of memories.values()) {
+				throwIfAborted(options?.signal);
+				if (matchesPruneFilter(memory, input, now)) matched.push(memory);
+			}
 			const dryRun = input.dryRun === true;
-			if (!dryRun) for (const id of matched) memories.delete(id);
+			let deletedByEntity = [];
+			if (!dryRun) {
+				throwIfAborted(options?.signal);
+				assertNoDependentMemories(memories, new Set(matched.map((memory) => memory.id)));
+				const deletedCounts = /* @__PURE__ */ new Map();
+				for (const memory of matched) {
+					memories.delete(memory.id);
+					deletedCounts.set(memory.entityId, (deletedCounts.get(memory.entityId) ?? 0) + 1);
+				}
+				deletedByEntity = Array.from(deletedCounts, ([entityId, deletedCount]) => ({
+					entityId,
+					deletedCount
+				})).sort((a, b) => a.entityId.localeCompare(b.entityId));
+			}
 			return {
 				matchedCount: matched.length,
 				deletedCount: dryRun ? 0 : matched.length,
-				dryRun
+				dryRun,
+				deletedByEntity
 			};
 		},
-		async findDuplicatePairs(input) {
+		async findDuplicatePairs(input, options) {
+			throwIfAborted(options?.signal);
 			const threshold = input.threshold ?? .95;
 			const limit = input.limit ?? 100;
 			const now = /* @__PURE__ */ new Date();
-			const candidates = Array.from(memories.values()).filter((memory) => matchesDuplicateFilter(memory, input, now));
+			const candidates = Array.from(memories.values()).filter((memory) => {
+				throwIfAborted(options?.signal);
+				return matchesDuplicateFilter(memory, input, now);
+			});
 			const pairs = [];
 			for (let i = 0; i < candidates.length; i += 1) {
+				throwIfAborted(options?.signal);
 				const a = candidates[i];
 				if (a === void 0) continue;
 				for (let j = i + 1; j < candidates.length; j += 1) {
+					throwIfAborted(options?.signal);
 					const b = candidates[j];
 					if (b === void 0) continue;
 					const similarity = Math.max(0, Math.min(1, cosineSimilarity(a.embedding, b.embedding)));
@@ -1243,27 +1530,29 @@ function createInMemoryStore() {
 		async addAuditEvents(events) {
 			auditLog.push(...events.map(cloneAuditEvent));
 		},
-		async listAuditLog(input) {
+		async listAuditLog(input, options) {
+			throwIfAborted(options?.signal);
 			const limit = input.limit ?? 50;
-			return auditLog.map((event, idx) => ({
-				event,
-				idx
-			})).filter(({ event }) => {
+			return auditLog.filter((event) => {
+				throwIfAborted(options?.signal);
 				if (event.entityId !== input.entityId) return false;
 				if (input.before !== void 0 && event.timestamp.getTime() >= input.before.getTime()) return false;
 				if (input.after !== void 0 && event.timestamp.getTime() <= input.after.getTime()) return false;
+				if (input.beforeCursor !== void 0 && compareAuditPositions(event, input.beforeCursor) >= 0) return false;
+				if (input.afterCursor !== void 0 && compareAuditPositions(event, input.afterCursor) <= 0) return false;
 				return true;
 			}).sort((a, b) => {
-				const dt = b.event.timestamp.getTime() - a.event.timestamp.getTime();
-				return dt === 0 ? b.idx - a.idx : dt;
-			}).slice(0, limit).map(({ event }) => cloneAuditEvent(event));
+				return compareAuditPositions(b, a);
+			}).slice(0, limit).map(cloneAuditEvent);
 		},
-		async getMemory(entityId, memoryId) {
+		async getMemory(entityId, memoryId, options) {
+			throwIfAborted(options?.signal);
 			const memory = memories.get(memoryId);
 			return memory && memory.entityId === entityId ? cloneMemory(memory) : null;
 		},
-		async loadConsolidationTargets(entityId, ids) {
+		async loadConsolidationTargets(entityId, ids, options) {
 			return ids.flatMap((id) => {
+				throwIfAborted(options?.signal);
 				const memory = memories.get(id);
 				if (!memory || memory.entityId !== entityId) return [];
 				return [{
@@ -1273,40 +1562,50 @@ function createInMemoryStore() {
 				}];
 			});
 		},
-		async consolidate(input) {
+		async consolidate(input, options) {
+			throwIfAborted(options?.signal);
 			const survivor = memories.get(input.survivorId);
 			const newlySuperseded = [];
+			const targets = [];
 			for (const id of input.supersededIds) {
+				throwIfAborted(options?.signal);
 				const memory = memories.get(id);
 				if (!memory || memory.entityId !== input.entityId) continue;
-				if (memory.supersededBy !== null) continue;
-				memory.supersededBy = input.survivorId;
-				memory.supersededAt = input.now;
-				memory.updatedAt = input.now;
-				newlySuperseded.push(memory.id);
+				targets.push(memory);
 			}
+			if (targets.some((memory) => memory.supersededBy !== null && memory.supersededBy !== input.survivorId)) throw new MnemocyteError("Superseded memory already belongs to a different survivor.", "CONFLICT");
+			for (const memory of targets) if (memory.supersededBy === null) newlySuperseded.push(memory);
+			let mergedSurvivorTags;
 			if (survivor && input.mergeTags && newlySuperseded.length > 0) {
 				const mergedTags = new Set(input.survivorTags);
-				for (const id of newlySuperseded) {
-					const memory = memories.get(id);
-					if (memory) for (const tag of memory.tags) mergedTags.add(tag);
-				}
-				if (mergedTags.size !== survivor.tags.length) {
-					survivor.tags = [...mergedTags];
-					survivor.updatedAt = input.now;
+				for (const memory of newlySuperseded) {
+					throwIfAborted(options?.signal);
+					for (const tag of memory.tags) mergedTags.add(tag);
 				}
+				if (mergedTags.size !== survivor.tags.length) mergedSurvivorTags = [...mergedTags];
 			}
-			if (input.auditEnabled) for (const id of newlySuperseded) auditLog.push({
+			const auditEvents = input.auditEnabled ? newlySuperseded.map((memory) => ({
 				id: createEventId(),
 				entityId: input.entityId,
 				description: "memory.superseded",
 				metadata: {
-					memoryId: id,
+					memoryId: memory.id,
 					supersededBy: input.survivorId
 				},
 				timestamp: input.now
-			});
-			return { supersededIds: newlySuperseded };
+			})) : [];
+			throwIfAborted(options?.signal);
+			for (const memory of newlySuperseded) {
+				memory.supersededBy = input.survivorId;
+				memory.supersededAt = input.now;
+				memory.updatedAt = input.now;
+			}
+			if (survivor && mergedSurvivorTags) {
+				survivor.tags = mergedSurvivorTags;
+				survivor.updatedAt = input.now;
+			}
+			if (input.auditEnabled) auditLog.push(...auditEvents);
+			return { supersededIds: newlySuperseded.map((memory) => memory.id) };
 		},
 		async stats(input, now) {
 			const allMemories = Array.from(memories.values());
@@ -1339,20 +1638,78 @@ function createInMemoryClient(config) {
 	return createMemoryClient(config, createInMemoryStore());
 }
 //#endregion
+//#region src/db/cancellation.ts
+const postgresDialect = new PgDialect();
+async function awaitCancelableQuery(query, signal) {
+	throwIfAborted(signal);
+	if (!signal) return await query;
+	const onAbort = () => {
+		query.cancel();
+	};
+	signal.addEventListener("abort", onAbort, { once: true });
+	try {
+		return await query;
+	} catch (error) {
+		if (signal.aborted) throw new MnemocyteError("Operation was aborted.", "ABORTED", signal.reason);
+		throw error;
+	} finally {
+		signal.removeEventListener("abort", onAbort);
+	}
+}
+async function executeCancelableSql(db, statement, signal) {
+	const query = postgresDialect.sqlToQuery(statement);
+	const client = db.$client;
+	if (!client) throw new MnemocyteError("Cancelable Postgres query requires the postgres.js client.", "DB");
+	return await awaitCancelableQuery(client.unsafe(query.sql, query.params), signal);
+}
+//#endregion
 //#region src/db/queries/events.ts
+function timestampParam$1(value) {
+	return sql`${value.toISOString()}::timestamptz`;
+}
 async function insertEvent(db, row) {
 	const inserted = (await db.insert(eventsTable).values(row).returning())[0];
 	if (!inserted) throw new MnemocyteError("Event insert returned no rows.", "DB");
 	return inserted;
 }
-async function listEvents(db, filter) {
-	return db.select().from(eventsTable).where(and(eq(eventsTable.entityId, filter.entityId), filter.before ? lt(eventsTable.timestamp, filter.before) : void 0, filter.after ? gt(eventsTable.timestamp, filter.after) : void 0)).orderBy(desc(eventsTable.timestamp)).limit(filter.limit ?? 50);
+async function listEvents(db, filter, signal) {
+	return executeCancelableSql(db, sql`
+			SELECT
+				id,
+				entity_id AS "entityId",
+				description,
+				metadata,
+				timestamp
+			FROM mnemocyte_events
+			WHERE entity_id = ${filter.entityId}
+				${filter.before ? sql`AND timestamp < ${timestampParam$1(filter.before)}` : sql``}
+				${filter.after ? sql`AND timestamp > ${timestampParam$1(filter.after)}` : sql``}
+				${filter.beforeCursor ? sql`AND (timestamp, id) < (${timestampParam$1(filter.beforeCursor.timestamp)}, ${filter.beforeCursor.id})` : sql``}
+				${filter.afterCursor ? sql`AND (timestamp, id) > (${timestampParam$1(filter.afterCursor.timestamp)}, ${filter.afterCursor.id})` : sql``}
+			ORDER BY timestamp DESC, id DESC
+			LIMIT ${filter.limit ?? 50}
+		`, signal);
 }
 //#endregion
 //#region src/db/queries/memories.ts
 function vectorLiteral(embedding) {
 	return `[${embedding.map(formatVectorComponent).join(",")}]`;
 }
+function clampedVectorScore(embedding) {
+	const rawScore = sql`1 - (embedding <=> ${embedding}::vector)`;
+	return sql`
+		CASE
+			WHEN ${rawScore} = 'NaN'::double precision
+				OR ${rawScore} = 'Infinity'::double precision
+				OR ${rawScore} = '-Infinity'::double precision
+				THEN 0::double precision
+			ELSE GREATEST(
+				0::double precision,
+				LEAST(1::double precision, ${rawScore})
+			)
+		END
+	`;
+}
 function timestampParam(value) {
 	return sql`${value.toISOString()}::timestamptz`;
 }
@@ -1414,78 +1771,136 @@ async function getGlobalMemoryStatsCounts(db, now) {
 	};
 }
 async function deleteMemory(db, entityId, memoryId) {
-	return (await db.delete(memoriesTable).where(and(eq(memoriesTable.entityId, entityId), eq(memoriesTable.id, memoryId))).returning({ id: memoriesTable.id })).length > 0;
+	return deleteMemoriesWithDependentGuard(db, and(eq(memoriesTable.entityId, entityId), eq(memoriesTable.id, memoryId)));
 }
 async function deleteMemoriesForEntity(db, entityId) {
-	return (await db.delete(memoriesTable).where(eq(memoriesTable.entityId, entityId)).returning({ id: memoriesTable.id })).length;
+	return deleteMemoriesWithDependentGuard(db, eq(memoriesTable.entityId, entityId));
 }
 function pruneConditions(filter) {
 	return and(filter.entityId !== void 0 ? eq(memoriesTable.entityId, filter.entityId) : void 0, filter.expired ? and(isNotNull(memoriesTable.expiresAt), sql`${memoriesTable.expiresAt} <= now()`) : void 0, filter.superseded ? isNotNull(memoriesTable.supersededBy) : void 0, filter.createdBefore ? lt(memoriesTable.createdAt, filter.createdBefore) : void 0, filter.notAccessedSince ? or(isNull(memoriesTable.lastAccessedAt), lt(memoriesTable.lastAccessedAt, filter.notAccessedSince)) : void 0, filter.types && filter.types.length > 0 ? inArray(memoriesTable.type, [...filter.types]) : void 0, tagsContainAll(filter.tags), filter.maxImportanceLevels && filter.maxImportanceLevels.length > 0 ? inArray(memoriesTable.importance, [...filter.maxImportanceLevels]) : void 0);
 }
-async function countPruneMatches(db, filter) {
-	return db.$count(memoriesTable, pruneConditions(filter));
-}
-async function pruneMemories(db, filter) {
-	return (await db.delete(memoriesTable).where(pruneConditions(filter)).returning({ id: memoriesTable.id })).length;
+async function countPruneMatches(db, filter, signal) {
+	const conditions = pruneConditions(filter);
+	const rows = await executeCancelableSql(db, sql`
+			SELECT count(*)::int AS count
+			FROM ${memoriesTable}
+			${conditions ? sql`WHERE ${conditions}` : sql``}
+		`, signal);
+	return Number(rows[0]?.count ?? 0);
+}
+async function pruneMemories(db, filter, signal) {
+	return deleteMemoriesWithDependentGuard(db, pruneConditions(filter), signal);
+}
+async function deleteMemoriesWithDependentGuard(db, conditions, signal) {
+	const rows = await executeCancelableSql(db, sql`
+			WITH candidates AS MATERIALIZED (
+				SELECT id, entity_id
+				FROM ${memoriesTable}
+				${conditions ? sql`WHERE ${conditions}` : sql``}
+			),
+			dependents AS MATERIALIZED (
+				SELECT 1
+				FROM ${memoriesTable} AS dependent
+				INNER JOIN candidates AS target
+					ON dependent.superseded_by = target.id
+				LIMIT 1
+			),
+			deleted AS (
+				DELETE FROM ${memoriesTable}
+				WHERE ${memoriesTable.id} IN (SELECT id FROM candidates)
+					AND NOT EXISTS (SELECT 1 FROM dependents)
+				RETURNING id, entity_id
+			),
+			deleted_counts AS (
+				SELECT entity_id, count(*)::int AS deleted_count
+				FROM deleted
+				GROUP BY entity_id
+			),
+			summary AS (
+				SELECT
+					(SELECT count(*)::int FROM candidates) AS matched_count,
+					(SELECT count(*)::int FROM deleted) AS deleted_count,
+					EXISTS (SELECT 1 FROM dependents) AS has_dependents
+			)
+			SELECT
+				summary.matched_count AS "matchedCount",
+				summary.deleted_count AS "deletedCount",
+				summary.has_dependents AS "hasDependents",
+				deleted_counts.entity_id AS "entityId",
+				deleted_counts.deleted_count AS "entityDeletedCount"
+			FROM summary
+			LEFT JOIN deleted_counts ON true
+			ORDER BY deleted_counts.entity_id
+		`, signal);
+	const row = rows[0];
+	return {
+		matchedCount: Number(row?.matchedCount ?? 0),
+		deletedCount: Number(row?.deletedCount ?? 0),
+		hasDependents: row?.hasDependents === true,
+		deletedByEntity: rows.flatMap((detail) => detail.entityId === null ? [] : [{
+			entityId: detail.entityId,
+			deletedCount: Number(detail.entityDeletedCount ?? 0)
+		}])
+	};
 }
-async function findDuplicatePairs(db, input) {
-	return (await db.execute(sql`
-		SELECT
-			a.id AS "aId",
-			a.entity_id AS "aEntityId",
-			a.content AS "aContent",
-			a.type AS "aType",
-			a.importance AS "aImportance",
-			a.tags AS "aTags",
-			a.source AS "aSource",
-			a.metadata AS "aMetadata",
-			a.confidence AS "aConfidence",
-			a.embedding AS "aEmbedding",
-			a.embedding_model AS "aEmbeddingModel",
-			a.embedding_dimensions AS "aEmbeddingDimensions",
-			a.superseded_by AS "aSupersededBy",
-			a.superseded_at AS "aSupersededAt",
-			a.expires_at AS "aExpiresAt",
-			a.last_accessed_at AS "aLastAccessedAt",
-			a.access_count AS "aAccessCount",
-			a.created_at AS "aCreatedAt",
-			a.updated_at AS "aUpdatedAt",
-			b.id AS "bId",
-			b.entity_id AS "bEntityId",
-			b.content AS "bContent",
-			b.type AS "bType",
-			b.importance AS "bImportance",
-			b.tags AS "bTags",
-			b.source AS "bSource",
-			b.metadata AS "bMetadata",
-			b.confidence AS "bConfidence",
-			b.embedding AS "bEmbedding",
-			b.embedding_model AS "bEmbeddingModel",
-			b.embedding_dimensions AS "bEmbeddingDimensions",
-			b.superseded_by AS "bSupersededBy",
-			b.superseded_at AS "bSupersededAt",
-			b.expires_at AS "bExpiresAt",
-			b.last_accessed_at AS "bLastAccessedAt",
-			b.access_count AS "bAccessCount",
-			b.created_at AS "bCreatedAt",
-			b.updated_at AS "bUpdatedAt",
-			1 - (a.embedding <=> b.embedding) AS "similarity"
-		FROM mnemocyte_memories a
-		JOIN mnemocyte_memories b
-			ON b.entity_id = a.entity_id
-			AND a.id < b.id
-			AND a.embedding IS NOT NULL
-			AND b.embedding IS NOT NULL
-		WHERE
-			a.entity_id = ${input.entityId}
-			${input.includeSuperseded ? sql`` : sql`AND a.superseded_by IS NULL AND b.superseded_by IS NULL`}
-			${input.includeExpired ? sql`` : sql`AND (a.expires_at IS NULL OR a.expires_at > now()) AND (b.expires_at IS NULL OR b.expires_at > now())`}
-			${input.types && input.types.length > 0 ? sql`AND a.type IN (${sql.join(input.types.map((type) => sql`${type}`), sql`, `)}) AND b.type IN (${sql.join(input.types.map((type) => sql`${type}`), sql`, `)})` : sql``}
-			${duplicateTagsFilter(input.tags)}
-			AND 1 - (a.embedding <=> b.embedding) >= ${input.threshold}
-		ORDER BY "similarity" DESC
-		LIMIT ${input.limit}
-	`)).map((row) => {
+async function findDuplicatePairs(db, input, signal) {
+	return (await executeCancelableSql(db, sql`
+			SELECT
+				a.id AS "aId",
+				a.entity_id AS "aEntityId",
+				a.content AS "aContent",
+				a.type AS "aType",
+				a.importance AS "aImportance",
+				a.tags AS "aTags",
+				a.source AS "aSource",
+				a.metadata AS "aMetadata",
+				a.confidence AS "aConfidence",
+				a.embedding AS "aEmbedding",
+				a.embedding_model AS "aEmbeddingModel",
+				a.embedding_dimensions AS "aEmbeddingDimensions",
+				a.superseded_by AS "aSupersededBy",
+				a.superseded_at AS "aSupersededAt",
+				a.expires_at AS "aExpiresAt",
+				a.last_accessed_at AS "aLastAccessedAt",
+				a.access_count AS "aAccessCount",
+				a.created_at AS "aCreatedAt",
+				a.updated_at AS "aUpdatedAt",
+				b.id AS "bId",
+				b.entity_id AS "bEntityId",
+				b.content AS "bContent",
+				b.type AS "bType",
+				b.importance AS "bImportance",
+				b.tags AS "bTags",
+				b.source AS "bSource",
+				b.metadata AS "bMetadata",
+				b.confidence AS "bConfidence",
+				b.embedding AS "bEmbedding",
+				b.embedding_model AS "bEmbeddingModel",
+				b.embedding_dimensions AS "bEmbeddingDimensions",
+				b.superseded_by AS "bSupersededBy",
+				b.superseded_at AS "bSupersededAt",
+				b.expires_at AS "bExpiresAt",
+				b.last_accessed_at AS "bLastAccessedAt",
+				b.access_count AS "bAccessCount",
+				b.created_at AS "bCreatedAt",
+				b.updated_at AS "bUpdatedAt",
+				1 - (a.embedding <=> b.embedding) AS "similarity"
+			FROM mnemocyte_memories a
+			JOIN mnemocyte_memories b
+				ON b.entity_id = a.entity_id
+				AND a.id < b.id
+				AND a.embedding IS NOT NULL
+				AND b.embedding IS NOT NULL
+			WHERE
+				a.entity_id = ${input.entityId}
+				${input.includeSuperseded ? sql`` : sql`AND a.superseded_by IS NULL AND b.superseded_by IS NULL`}
+				${input.includeExpired ? sql`` : sql`AND (a.expires_at IS NULL OR a.expires_at > now()) AND (b.expires_at IS NULL OR b.expires_at > now())`}
+				${input.types && input.types.length > 0 ? sql`AND a.type IN (${sql.join(input.types.map((type) => sql`${type}`), sql`, `)}) AND b.type IN (${sql.join(input.types.map((type) => sql`${type}`), sql`, `)})` : sql``}
+				${duplicateTagsFilter(input.tags)}
+				AND 1 - (a.embedding <=> b.embedding) >= ${input.threshold}
+			ORDER BY "similarity" DESC
+			LIMIT ${input.limit}
+		`, signal)).map((row) => {
 		return {
 			a: {
 				id: row.aId,
@@ -1541,6 +1956,14 @@ async function loadConsolidationTargets(db, entityId, ids) {
 		supersededBy: memoriesTable.supersededBy
 	}).from(memoriesTable).where(and(eq(memoriesTable.entityId, entityId), inArray(memoriesTable.id, [...ids])));
 }
+async function lockConsolidationTargets(db, entityId, ids) {
+	if (ids.length === 0) return [];
+	return db.select({
+		id: memoriesTable.id,
+		tags: memoriesTable.tags,
+		supersededBy: memoriesTable.supersededBy
+	}).from(memoriesTable).where(and(eq(memoriesTable.entityId, entityId), inArray(memoriesTable.id, [...ids]))).orderBy(memoriesTable.id).for("update");
+}
 async function markMemoriesSuperseded(db, params) {
 	if (params.ids.length === 0) return [];
 	return await db.update(memoriesTable).set({
@@ -1560,12 +1983,17 @@ async function setMemoryTags(db, params) {
 }
 async function markMemoriesAccessed(db, memoryIds) {
 	const now = /* @__PURE__ */ new Date();
-	if (memoryIds.length === 0) return;
-	await db.update(memoriesTable).set({
+	if (memoryIds.length === 0) return [];
+	return db.update(memoriesTable).set({
 		lastAccessedAt: now,
 		accessCount: sql`${memoriesTable.accessCount} + 1`,
 		updatedAt: now
-	}).where(inArray(memoriesTable.id, [...memoryIds]));
+	}).where(inArray(memoriesTable.id, [...memoryIds])).returning({
+		id: memoriesTable.id,
+		lastAccessedAt: memoriesTable.lastAccessedAt,
+		accessCount: memoriesTable.accessCount,
+		updatedAt: memoriesTable.updatedAt
+	});
 }
 async function getMemoryEmbeddings(db, memoryIds) {
 	if (memoryIds.length === 0) return /* @__PURE__ */ new Map();
@@ -1577,7 +2005,8 @@ async function getMemoryEmbeddings(db, memoryIds) {
 }
 async function vectorSearch(db, input) {
 	const embedding = vectorLiteral(input.embedding);
-	const minScore = input.minScore ?? 0;
+	const vectorScore = clampedVectorScore(embedding);
+	const minVectorScore = input.minVectorScore ?? 0;
 	return await db.execute(sql`
 		SELECT
 			id,
@@ -1598,7 +2027,7 @@ async function vectorSearch(db, input) {
 			access_count AS "accessCount",
 			created_at AS "createdAt",
 			updated_at AS "updatedAt",
-			1 - (embedding <=> ${embedding}::vector) AS "vectorScore"
+			${vectorScore} AS "vectorScore"
 		FROM mnemocyte_memories
 		WHERE
 			entity_id = ${input.entityId}
@@ -1609,7 +2038,7 @@ async function vectorSearch(db, input) {
 			${rawTagsFilter(input.tags)}
 			${input.before ? sql`AND created_at < ${timestampParam(input.before)}` : sql``}
 			${input.after ? sql`AND created_at > ${timestampParam(input.after)}` : sql``}
-			AND 1 - (embedding <=> ${embedding}::vector) >= ${minScore}
+			AND ${vectorScore} >= ${minVectorScore}
 		ORDER BY embedding <=> ${embedding}::vector
 		LIMIT ${input.limit}
 	`);
@@ -1653,6 +2082,12 @@ async function lexicalSearch(db, input) {
 async function getInstallationMeta(db) {
 	return (await db.select().from(metaTable).where(eq(metaTable.key, "installation")).limit(1))[0] ?? null;
 }
+async function getStoredEmbeddingModels(db) {
+	return (await db.selectDistinct({ embeddingModel: memoriesTable.embeddingModel }).from(memoriesTable).limit(2)).map((row) => row.embeddingModel);
+}
+async function recordInstallationEmbeddingModel(db, embeddingModel) {
+	return (await db.update(metaTable).set({ embeddingModel }).where(and(eq(metaTable.key, "installation"), isNull(metaTable.embeddingModel))).returning())[0] ?? null;
+}
 //#endregion
 //#region src/memory/postgres-records.ts
 function toDate(value) {
@@ -1697,13 +2132,14 @@ const MIGRATION_ERROR_CODES = new Set([
 	"42704",
 	"42883"
 ]);
+const CONSOLIDATION_SURVIVOR_FOREIGN_KEY = "mnemocyte_memories_superseded_by_mnemocyte_memories_id_fk";
 function rowToAuditEvent(row) {
 	return {
 		id: row.id,
 		entityId: row.entityId,
 		description: row.description,
 		metadata: cloneJsonObject(row.metadata),
-		timestamp: row.timestamp
+		timestamp: new Date(row.timestamp)
 	};
 }
 function importanceCeilingLevels(max) {
@@ -1712,6 +2148,9 @@ function importanceCeilingLevels(max) {
 function hasPostgresErrorCode(error, code) {
 	return typeof error === "object" && error !== null && "code" in error && error.code === code;
 }
+function hasPostgresConstraintName(error, name) {
+	return typeof error === "object" && error !== null && "constraint_name" in error && error.constraint_name === name;
+}
 function getPostgresErrorCode(error) {
 	return typeof error === "object" && error !== null && "code" in error && typeof error.code === "string" ? error.code : void 0;
 }
@@ -1728,6 +2167,15 @@ async function runPostgresOperation(operation) {
 		throw normalizePostgresError(error);
 	}
 }
+async function runPostgresDeleteOperation(operation) {
+	try {
+		return await operation();
+	} catch (error) {
+		if (error instanceof MnemocyteError) throw error;
+		if (hasPostgresErrorCode(error, "23503") && hasPostgresConstraintName(error, CONSOLIDATION_SURVIVOR_FOREIGN_KEY)) throw memoryHasDependentsError(error);
+		throw normalizePostgresError(error);
+	}
+}
 function toPruneFilter(input) {
 	const filter = {};
 	if (input.entityId !== void 0) filter.entityId = input.entityId;
@@ -1744,7 +2192,6 @@ function toMemoryRow(memory) {
 	return {
 		...memory,
 		tags: [...memory.tags],
-		metadata: cloneJsonObject(memory.metadata),
 		embedding: [...memory.embedding]
 	};
 }
@@ -1764,11 +2211,26 @@ function createPostgresStore(handle) {
 		try {
 			meta = await getInstallationMeta(handle.db);
 		} catch (error) {
-			if (hasPostgresErrorCode(error, "42P01")) throw new MnemocyteError("mnemocyte_meta is missing. Apply the v0.2.0 migration or render a dimension-specific initial migration before using the Postgres backend.", "MIGRATION", error);
+			if (hasPostgresErrorCode(error, "42P01") || hasPostgresErrorCode(error, "42703")) throw new MnemocyteError("Postgres embedding metadata is missing or outdated. Apply the bundled migrations through 0002_add_embedding_model.sql, or render a fresh dimension-specific initial migration, before using embedding-dependent operations.", "MIGRATION", error);
 			throw normalizePostgresError(error);
 		}
-		if (!meta) throw new MnemocyteError("mnemocyte_meta is missing the \"installation\" row. Apply the v0.2.0 migration or render a dimension-specific initial migration before using the Postgres backend.", "MIGRATION");
+		if (!meta) throw new MnemocyteError("mnemocyte_meta is missing the \"installation\" row. Apply the bundled migrations, or render a fresh dimension-specific initial migration, before using embedding-dependent operations.", "MIGRATION");
 		if (meta.embeddingDimensions !== embedder.dimensions) throw new MnemocyteError(`embedder.dimensions (${embedder.dimensions}) must match mnemocyte_meta.embedding_dimensions (${meta.embeddingDimensions}). Render and apply a migration for the selected embedding dimension, or configure an embedder that matches this installation.`, "CONFIG");
+		let installationModel = meta.embeddingModel;
+		if (installationModel === null) {
+			try {
+				const storedModels = await getStoredEmbeddingModels(handle.db);
+				if (storedModels.length > 1) throw new MnemocyteError("mnemocyte_meta.embedding_model is unset, but stored memories contain multiple embedding_model values. Re-embed or remove the mixed historical rows, then explicitly record the installation model before using embedding-dependent operations.", "MIGRATION");
+				const inferredModel = storedModels[0] ?? embedder.model;
+				const recorded = await recordInstallationEmbeddingModel(handle.db, inferredModel);
+				if (recorded) installationModel = recorded.embeddingModel;
+				else installationModel = (await getInstallationMeta(handle.db))?.embeddingModel ?? null;
+			} catch (error) {
+				throw normalizePostgresError(error);
+			}
+			if (installationModel === null) throw new MnemocyteError("mnemocyte_meta.embedding_model could not be recorded. Verify the installation metadata row and retry.", "MIGRATION");
+		}
+		if (installationModel !== embedder.model) throw new MnemocyteError(`embedder.model ("${embedder.model}") must match mnemocyte_meta.embedding_model ("${installationModel}"). Configure the recorded model, or explicitly re-embed existing memories and update the installation metadata.`, "CONFIG");
 		schemaValidated = true;
 	}
 	return {
@@ -1800,31 +2262,52 @@ function createPostgresStore(handle) {
 			return runPostgresOperation(() => getMemoryEmbeddings(handle.db, memoryIds));
 		},
 		async markMemoriesAccessed(memoryIds) {
-			return runPostgresOperation(() => markMemoriesAccessed(handle.db, memoryIds));
+			return runPostgresOperation(async () => {
+				return (await markMemoriesAccessed(handle.db, memoryIds)).map((row) => {
+					if (row.lastAccessedAt === null) throw new MnemocyteError("Postgres access update returned no timestamp.", "DB");
+					return {
+						...row,
+						lastAccessedAt: row.lastAccessedAt
+					};
+				});
+			});
 		},
 		async deleteMemory(entityId, memoryId) {
-			return runPostgresOperation(() => deleteMemory(handle.db, entityId, memoryId));
+			return runPostgresDeleteOperation(async () => {
+				const result = await deleteMemory(handle.db, entityId, memoryId);
+				if (result.hasDependents) throw memoryHasDependentsError();
+				return result.deletedCount > 0;
+			});
 		},
 		async deleteMemoriesForEntity(entityId) {
-			return runPostgresOperation(() => deleteMemoriesForEntity(handle.db, entityId));
+			return runPostgresDeleteOperation(async () => {
+				const result = await deleteMemoriesForEntity(handle.db, entityId);
+				if (result.hasDependents) throw memoryHasDependentsError();
+				return result.deletedCount;
+			});
 		},
-		async prune(input) {
-			return runPostgresOperation(async () => {
+		async prune(input, options) {
+			return runPostgresDeleteOperation(async () => {
+				throwIfAborted(options?.signal);
+				assertPruneFilterHasSelector(input);
 				const filter = toPruneFilter(input);
 				if (input.dryRun === true) return {
-					matchedCount: await countPruneMatches(handle.db, filter),
+					matchedCount: await countPruneMatches(handle.db, filter, options?.signal),
 					deletedCount: 0,
-					dryRun: true
+					dryRun: true,
+					deletedByEntity: []
 				};
-				const deletedCount = await pruneMemories(handle.db, filter);
+				const result = await pruneMemories(handle.db, filter, options?.signal);
+				if (result.hasDependents) throw memoryHasDependentsError();
 				return {
-					matchedCount: deletedCount,
-					deletedCount,
-					dryRun: false
+					matchedCount: result.matchedCount,
+					deletedCount: result.deletedCount,
+					dryRun: false,
+					deletedByEntity: result.deletedByEntity
 				};
 			});
 		},
-		async findDuplicatePairs(input) {
+		async findDuplicatePairs(input, options) {
 			return runPostgresOperation(async () => {
 				return (await findDuplicatePairs(handle.db, {
 					entityId: input.entityId,
@@ -1834,7 +2317,7 @@ function createPostgresStore(handle) {
 					...input.tags === void 0 ? {} : { tags: input.tags },
 					...input.includeSuperseded === void 0 ? {} : { includeSuperseded: input.includeSuperseded },
 					...input.includeExpired === void 0 ? {} : { includeExpired: input.includeExpired }
-				})).map((row) => ({
+				}, options?.signal)).map((row) => ({
 					a: rowToMemory(row.a),
 					b: rowToMemory(row.b),
 					similarity: Math.max(0, Math.min(1, row.similarity))
@@ -1852,55 +2335,83 @@ function createPostgresStore(handle) {
 				});
 			});
 		},
-		async listAuditLog(input) {
+		async listAuditLog(input, options) {
 			return runPostgresOperation(async () => {
 				return (await listEvents(handle.db, {
 					entityId: input.entityId,
 					limit: input.limit ?? 50,
 					...input.before === void 0 ? {} : { before: input.before },
-					...input.after === void 0 ? {} : { after: input.after }
-				})).map(rowToAuditEvent);
+					...input.after === void 0 ? {} : { after: input.after },
+					...input.beforeCursor === void 0 ? {} : { beforeCursor: input.beforeCursor },
+					...input.afterCursor === void 0 ? {} : { afterCursor: input.afterCursor }
+				}, options?.signal)).map(rowToAuditEvent);
 			});
 		},
-		async getMemory(entityId, memoryId) {
+		async getMemory(entityId, memoryId, options) {
 			return runPostgresOperation(async () => {
+				throwIfAborted(options?.signal);
 				const row = await getMemoryById(handle.db, entityId, memoryId);
+				throwIfAborted(options?.signal);
 				return row ? rowToMemory(row) : null;
 			});
 		},
-		async loadConsolidationTargets(entityId, ids) {
-			return runPostgresOperation(() => loadConsolidationTargets(handle.db, entityId, ids));
+		async loadConsolidationTargets(entityId, ids, options) {
+			return runPostgresOperation(async () => {
+				throwIfAborted(options?.signal);
+				const targets = await loadConsolidationTargets(handle.db, entityId, ids);
+				throwIfAborted(options?.signal);
+				return targets;
+			});
 		},
-		async consolidate(input) {
+		async consolidate(input, options) {
 			return runPostgresOperation(async () => {
+				throwIfAborted(options?.signal);
 				return { supersededIds: await handle.db.transaction(async (tx) => {
+					throwIfAborted(options?.signal);
+					const targets = await lockConsolidationTargets(tx, input.entityId, input.supersededIds);
+					throwIfAborted(options?.signal);
+					if (targets.some((target) => target.supersededBy !== null && target.supersededBy !== input.survivorId)) throw new MnemocyteError("Superseded memory already belongs to a different survivor.", "CONFLICT");
+					const activeIds = targets.filter((target) => target.supersededBy === null).map((target) => target.id);
 					const updated = await markMemoriesSuperseded(tx, {
 						survivorId: input.survivorId,
 						entityId: input.entityId,
-						ids: input.supersededIds,
+						ids: activeIds,
 						now: input.now
 					});
+					throwIfAborted(options?.signal);
 					const ids = updated.map((row) => row.id);
-					if (input.auditEnabled) for (const id of ids) await insertEvent(tx, {
-						id: createEventId(),
-						entityId: input.entityId,
-						description: "memory.superseded",
-						metadata: {
-							memoryId: id,
-							supersededBy: input.survivorId
-						},
-						timestamp: input.now
-					});
-					if (input.mergeTags && updated.length > 0) {
-						const mergedTags = new Set(input.survivorTags);
-						for (const row of updated) for (const tag of row.tags) mergedTags.add(tag);
-						if (mergedTags.size !== input.survivorTags.length) await setMemoryTags(tx, {
+					if (input.auditEnabled) for (const id of ids) {
+						throwIfAborted(options?.signal);
+						await insertEvent(tx, {
+							id: createEventId(),
 							entityId: input.entityId,
-							memoryId: input.survivorId,
-							tags: [...mergedTags],
-							now: input.now
+							description: "memory.superseded",
+							metadata: {
+								memoryId: id,
+								supersededBy: input.survivorId
+							},
+							timestamp: input.now
 						});
+						throwIfAborted(options?.signal);
+					}
+					if (input.mergeTags && updated.length > 0) {
+						const mergedTags = new Set(input.survivorTags);
+						for (const row of updated) {
+							throwIfAborted(options?.signal);
+							for (const tag of row.tags) mergedTags.add(tag);
+						}
+						if (mergedTags.size !== input.survivorTags.length) {
+							throwIfAborted(options?.signal);
+							await setMemoryTags(tx, {
+								entityId: input.entityId,
+								memoryId: input.survivorId,
+								tags: [...mergedTags],
+								now: input.now
+							});
+							throwIfAborted(options?.signal);
+						}
 					}
+					throwIfAborted(options?.signal);
 					return ids;
 				}) };
 			});
@@ -1942,7 +2453,8 @@ function createPostgresClient(config, handle) {
 * @param config - Client configuration. {@link MnemocyteConfig.embedder} is required.
 * @returns A {@link MnemocyteClient} instance.
 * @throws {MnemocyteError} With code `"CONFIG"` if `embedder`, retrieval
-* tuning, or the database URL is malformed, or `"VALIDATION"` if
+* tuning, provider resilience, or the database URL is malformed or does not
+* use the `postgres:` / `postgresql:` protocol, or `"VALIDATION"` if
 * `databaseUrl` is explicitly empty.
 *
 * @example Postgres-backed client
@@ -1956,6 +2468,7 @@ function createPostgresClient(config, handle) {
 function createMnemocyte(config) {
 	assertEmbedder(config.embedder);
 	validateRetrievalConfig(config.retrieval);
+	validateProviderResilienceConfig(config.provider);
 	if (config.databaseUrl !== void 0) {
 		assertNonEmptyString(config.databaseUrl, "databaseUrl");
 		return createPostgresClient(config, createDatabase(config.databaseUrl));