mnemocyte 0.1.5 → 0.3.0

package/dist/index.mjs

@@ -1,4 +1,4 @@
-import { n as isMnemocyteError, t as MnemocyteError } from "./errors-BG3-mNur.mjs";
+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";
@@ -15,26 +15,29 @@ var __exportAll = (all, no_symbols) => {
 	return target;
 };
 //#endregion
+//#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);
+}
+//#endregion
 //#region src/db/schema.ts
 var schema_exports = /* @__PURE__ */ __exportAll({
 	eventsTable: () => eventsTable,
-	memoriesTable: () => memoriesTable
+	memoriesTable: () => memoriesTable,
+	metaTable: () => metaTable
 });
 const vector = customType({
 	dataType(config) {
-		return `vector(${typeof config === "number" ? config : 1536})`;
+		return `vector(${config?.dimensions ?? 1536})`;
 	},
 	toDriver(value) {
-		return `[${value.map(formatVectorComponent$1).join(",")}]`;
+		return `[${value.map(formatVectorComponent).join(",")}]`;
 	},
 	fromDriver(value) {
 		return value.slice(1, -1).split(",").filter(Boolean).map(Number);
 	}
 });
-function formatVectorComponent$1(value) {
-	if (!Number.isFinite(value)) throw new Error("Vector values must be finite numbers.");
-	return Object.is(value, -0) ? "0" : value.toFixed(17);
-}
 const memoriesTable = pgTable("mnemocyte_memories", {
 	id: text("id").primaryKey(),
 	entityId: text("entity_id").notNull(),
@@ -43,7 +46,7 @@ const memoriesTable = pgTable("mnemocyte_memories", {
 	importance: text("importance").notNull().default("normal"),
 	tags: text("tags").array().notNull().default(sql`'{}'::text[]`),
 	source: text("source"),
-	metadata: jsonb("metadata").notNull().default({}),
+	metadata: jsonb("metadata").$type().notNull().default({}),
 	confidence: real("confidence").notNull().default(1),
 	embedding: vector("embedding", { dimensions: 1536 }),
 	embeddingModel: text("embedding_model").notNull(),
@@ -64,9 +67,13 @@ const eventsTable = pgTable("mnemocyte_events", {
 	id: text("id").primaryKey(),
 	entityId: text("entity_id").notNull(),
 	description: text("description").notNull(),
-	metadata: jsonb("metadata").notNull().default({}),
+	metadata: jsonb("metadata").$type().notNull().default({}),
 	timestamp: timestamp("timestamp", { withTimezone: true }).notNull().defaultNow()
 }, (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()
+});
 //#endregion
 //#region src/db/index.ts
 function parseSslFromUrl(url) {
@@ -76,7 +83,12 @@ function parseSslFromUrl(url) {
 	if (mode === "verify-full") return "verify-full";
 }
 function createDatabase(databaseUrl) {
-	const url = new URL(databaseUrl);
+	let url;
+	try {
+		url = new URL(databaseUrl);
+	} catch (error) {
+		throw new MnemocyteError("databaseUrl must be a valid Postgres connection URL.", "CONFIG", error);
+	}
 	const ssl = parseSslFromUrl(url);
 	const isPooler = url.port === "6543" || url.searchParams.get("pgbouncer") === "true";
 	const client = postgres(databaseUrl, {
@@ -94,6 +106,203 @@ function createDatabase(databaseUrl) {
 	};
 }
 //#endregion
+//#region src/memory/json.ts
+function invalidJsonValue(path, cause) {
+	return new MnemocyteError(`${path} must contain only JSON-compatible value data.`, "VALIDATION", cause);
+}
+function cloneJsonValue(value, path, ancestors) {
+	if (value === null || typeof value === "string" || typeof value === "boolean") return value;
+	if (typeof value === "number") {
+		if (!Number.isFinite(value)) throw invalidJsonValue(path);
+		return Object.is(value, -0) ? 0 : value;
+	}
+	if (typeof value !== "object") throw invalidJsonValue(path);
+	if (ancestors.has(value)) throw invalidJsonValue(path);
+	ancestors.add(value);
+	try {
+		if (Array.isArray(value)) {
+			if (Object.getOwnPropertySymbols(value).length > 0 || Object.keys(value).some((key) => !/^(0|[1-9]\d*)$/.test(key))) throw invalidJsonValue(path);
+			return Array.from({ length: value.length }, (_, index) => {
+				if (!Object.hasOwn(value, index)) throw invalidJsonValue(`${path}[${index}]`);
+				return cloneJsonValue(value[index], `${path}[${index}]`, ancestors);
+			});
+		}
+		const prototype = Object.getPrototypeOf(value);
+		if (prototype !== Object.prototype && prototype !== null) throw invalidJsonValue(path);
+		const descriptors = Object.getOwnPropertyDescriptors(value);
+		const entries = [];
+		for (const key of Reflect.ownKeys(descriptors)) {
+			if (typeof key !== "string") throw invalidJsonValue(path);
+			const descriptor = descriptors[key];
+			if (descriptor === void 0 || descriptor.enumerable !== true || !("value" in descriptor)) throw invalidJsonValue(`${path}.${key}`);
+			entries.push([key, cloneJsonValue(descriptor.value, `${path}.${key}`, ancestors)]);
+		}
+		return Object.fromEntries(entries);
+	} finally {
+		ancestors.delete(value);
+	}
+}
+/** Validate and deep-clone a JSON-compatible object. */
+function cloneJsonObject(value, path = "metadata") {
+	try {
+		if (value === null || typeof value !== "object" || Array.isArray(value)) throw invalidJsonValue(path);
+		return cloneJsonValue(value, path, /* @__PURE__ */ new Set());
+	} catch (error) {
+		if (error instanceof MnemocyteError) throw error;
+		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) {
+	if (!tags) return [];
+	return [...new Set(tags.map((tag) => tag.trim()).filter(Boolean))];
+}
+function createId() {
+	return `mem_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 10)}`;
+}
+/** Generate a unique audit-event id (`evt_*`). */
+function createEventId() {
+	return `evt_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 10)}`;
+}
+function cloneMemory(memory) {
+	return {
+		id: memory.id,
+		entityId: memory.entityId,
+		content: memory.content,
+		type: memory.type,
+		importance: memory.importance,
+		tags: [...memory.tags],
+		source: memory.source,
+		metadata: cloneJsonObject(memory.metadata),
+		confidence: memory.confidence,
+		embeddingModel: memory.embeddingModel,
+		embeddingDimensions: memory.embeddingDimensions,
+		supersededBy: memory.supersededBy,
+		supersededAt: memory.supersededAt ? new Date(memory.supersededAt) : null,
+		expiresAt: memory.expiresAt ? new Date(memory.expiresAt) : null,
+		lastAccessedAt: memory.lastAccessedAt ? new Date(memory.lastAccessedAt) : null,
+		accessCount: memory.accessCount,
+		createdAt: new Date(memory.createdAt),
+		updatedAt: new Date(memory.updatedAt)
+	};
+}
+//#endregion
+//#region src/retrieval/scorer.ts
+const IMPORTANCE_SCORES = {
+	low: 0,
+	normal: .5,
+	high: .8,
+	critical: 1
+};
+const DEFAULT_RETRIEVAL_WEIGHTS = {
+	vector: .55,
+	lexical: .2,
+	recency: .1,
+	confidence: .05,
+	access: .05,
+	importance: .05
+};
+const DEFAULT_RECENCY_HALF_LIFE_DAYS = 90;
+const DEFAULT_ACCESS_SATURATION = 10;
+function cosineSimilarity(a, b) {
+	let dot = 0;
+	let aMagnitude = 0;
+	let bMagnitude = 0;
+	for (let i = 0; i < a.length; i += 1) {
+		const av = a[i] ?? 0;
+		const bv = b[i] ?? 0;
+		dot += av * bv;
+		aMagnitude += av * av;
+		bMagnitude += bv * bv;
+	}
+	if (aMagnitude === 0 || bMagnitude === 0) return 0;
+	return dot / (Math.sqrt(aMagnitude) * Math.sqrt(bMagnitude));
+}
+function tokenizeQuery(query) {
+	return query.toLowerCase().split(/\s+/).filter(Boolean);
+}
+function lexicalScoreWithTerms(content, terms) {
+	if (terms.length === 0) return 0;
+	const lowerContent = content.toLowerCase();
+	return terms.filter((term) => lowerContent.includes(term)).length / terms.length;
+}
+function createLexicalScorer(query) {
+	const terms = tokenizeQuery(query);
+	return (content) => lexicalScoreWithTerms(content, terms);
+}
+function clampScore(value) {
+	if (!Number.isFinite(value)) return 0;
+	return Math.max(0, Math.min(1, value));
+}
+function normalizeWeights(weights) {
+	const merged = {
+		...DEFAULT_RETRIEVAL_WEIGHTS,
+		...weights
+	};
+	const total = merged.vector + merged.lexical + merged.recency + merged.confidence + merged.access + merged.importance;
+	if (total <= 0) return { ...DEFAULT_RETRIEVAL_WEIGHTS };
+	return {
+		vector: merged.vector / total,
+		lexical: merged.lexical / total,
+		recency: merged.recency / total,
+		confidence: merged.confidence / total,
+		access: merged.access / total,
+		importance: merged.importance / total
+	};
+}
+function createScoringConfig(config) {
+	return {
+		weights: normalizeWeights(config?.weights),
+		recencyHalfLifeDays: config?.recencyHalfLifeDays ?? DEFAULT_RECENCY_HALF_LIFE_DAYS,
+		accessSaturation: config?.accessSaturation ?? DEFAULT_ACCESS_SATURATION
+	};
+}
+function recencyScore(createdAt, halfLifeDays) {
+	const ageMs = Date.now() - createdAt.getTime();
+	const ageDays = Math.max(0, ageMs / 864e5);
+	return Math.exp(-Math.LN2 * ageDays / halfLifeDays);
+}
+function accessScore(accessCount, saturation) {
+	if (accessCount <= 0) return 0;
+	return Math.min(1, Math.log1p(accessCount) / Math.log1p(saturation));
+}
+function toScoredMemoryWithConfig(memory, vector, lexical, input, config) {
+	const { weights } = config;
+	const recency = recencyScore(memory.createdAt, config.recencyHalfLifeDays);
+	const confidence = clampScore(memory.confidence);
+	const access = accessScore(memory.accessCount, config.accessSaturation);
+	const importance = IMPORTANCE_SCORES[memory.importance];
+	const score = Math.max(0, Math.min(1, clampScore(vector) * weights.vector + clampScore(lexical) * weights.lexical + recency * weights.recency + confidence * weights.confidence + access * weights.access + importance * weights.importance));
+	return {
+		...cloneMemory(memory),
+		score,
+		scores: {
+			vector: clampScore(vector),
+			lexical: clampScore(lexical),
+			recency,
+			confidence,
+			access,
+			importance
+		},
+		explanation: input.explain ? {
+			vectorScore: clampScore(vector),
+			lexicalScore: clampScore(lexical),
+			recencyScore: recency,
+			confidenceScore: confidence,
+			accessScore: access,
+			importanceScore: importance,
+			importanceBoost: importance * weights.importance,
+			weights,
+			finalScore: score
+		} : null
+	};
+}
+//#endregion
 //#region src/context/formatter.ts
 function escapeXml(value) {
 	return value.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll("\"", "&quot;").replaceAll("'", "&apos;");
@@ -245,6 +454,17 @@ async function observe(config, backend, operation, metadata, action, successMeta
 		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
 /**
@@ -331,37 +551,44 @@ function delay(ms, signal) {
 		}
 	});
 }
+function timeoutError(timeoutMs) {
+	return new MnemocyteError(`Provider call timed out after ${timeoutMs}ms.`, "TIMEOUT");
+}
 /**
-* Race `promise` against the configured `timeoutMs` and the caller's
-* `signal`. Rejects with `"TIMEOUT"` or `"ABORTED"` respectively. Resolves
-* with the original promise value if it settles first.
+* 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 withTimeout(promise, timeoutMs, signal) {
-	if (timeoutMs <= 0 && !signal) return promise;
+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);
-			reject(new MnemocyteError(`Provider call timed out after ${timeoutMs}ms.`, "TIMEOUT"));
+			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 });
 		}
-		promise.then((value) => {
+		action(controller.signal).then((value) => {
 			if (settled) return;
 			settled = true;
 			if (timer) clearTimeout(timer);
@@ -400,7 +627,7 @@ async function withResilience(action, options = {}) {
 	for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
 		throwIfAborted(externalSignal);
 		try {
-			return await withTimeout(action(externalSignal), timeoutMs, externalSignal);
+			return await runAttempt(action, timeoutMs, externalSignal);
 		} catch (error) {
 			lastError = error;
 			if (error instanceof MnemocyteError && error.code === "ABORTED") throw error;
@@ -411,84 +638,11 @@ async function withResilience(action, options = {}) {
 	}
 	throw lastError;
 }
-/**
-* 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
-};
-function assertNonEmptyString(value, field) {
-	if (value.trim().length === 0) throw new MnemocyteError(`${field} must be a non-empty string.`, "VALIDATION");
-}
-function assertLimit(value) {
-	if (!Number.isInteger(value) || value < 1) throw new MnemocyteError("limit must be a positive integer.", "VALIDATION");
-}
-function assertMinScore(value) {
-	if (!Number.isFinite(value) || value < 0 || value > 1) throw new MnemocyteError("minScore must be a number between 0 and 1.", "VALIDATION");
-}
-function assertEmbedder(embedder) {
-	if (!embedder || typeof embedder.embed !== "function") throw new MnemocyteError("embedder with an embed function is required.", "CONFIG");
-	assertNonEmptyString(embedder.model, "embedder.model");
-	if (!Number.isInteger(embedder.dimensions) || embedder.dimensions < 1) throw new MnemocyteError("embedder.dimensions must be a positive integer.", "CONFIG");
-}
-function normalizeTags(tags) {
-	if (!tags) return [];
-	return [...new Set(tags.map((tag) => tag.trim()).filter(Boolean))];
-}
-function createId() {
-	return `mem_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 10)}`;
-}
-/** Generate a unique audit-event id (`evt_*`). */
-function createEventId() {
-	return `evt_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 10)}`;
-}
-function isExpired(memory, now) {
-	return memory.expiresAt !== null && memory.expiresAt.getTime() <= now.getTime();
-}
-function cloneMemory(memory) {
-	return {
-		...memory,
-		tags: [...memory.tags],
-		metadata: { ...memory.metadata },
-		supersededAt: memory.supersededAt ? new Date(memory.supersededAt) : null,
-		expiresAt: memory.expiresAt ? new Date(memory.expiresAt) : null,
-		lastAccessedAt: memory.lastAccessedAt ? new Date(memory.lastAccessedAt) : null,
-		createdAt: new Date(memory.createdAt),
-		updatedAt: new Date(memory.updatedAt)
-	};
-}
-function toDate(value) {
-	return value instanceof Date ? value : new Date(value);
-}
-function toNullableDate(value) {
-	return value === null ? null : toDate(value);
-}
-function rowToMemory(row) {
-	return {
-		id: row.id,
-		entityId: row.entityId,
-		content: row.content,
-		type: row.type,
-		importance: row.importance,
-		tags: row.tags,
-		source: row.source,
-		metadata: row.metadata,
-		confidence: row.confidence,
-		embeddingModel: row.embeddingModel,
-		embeddingDimensions: row.embeddingDimensions,
-		supersededBy: row.supersededBy,
-		supersededAt: toNullableDate(row.supersededAt),
-		expiresAt: toNullableDate(row.expiresAt),
-		lastAccessedAt: toNullableDate(row.lastAccessedAt),
-		accessCount: row.accessCount,
-		createdAt: toDate(row.createdAt),
-		updatedAt: toDate(row.updatedAt)
-	};
+//#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");
 }
 async function embedOne(embedder, text, options = {}) {
 	let embeddings;
@@ -503,7 +657,7 @@ async function embedOne(embedder, text, options = {}) {
 	}
 	const embedding = embeddings[0];
 	if (!embedding) throw new MnemocyteError("Embedder returned no embedding.", "EMBEDDING");
-	if (embedding.length !== embedder.dimensions) throw new MnemocyteError("Embedder returned an embedding with unexpected dimensions.", "EMBEDDING");
+	validateEmbedding(embedding, embedder.dimensions);
 	return embedding;
 }
 async function embedMany(embedder, texts, options = {}) {
@@ -519,23 +673,67 @@ async function embedMany(embedder, texts, options = {}) {
 		throw new MnemocyteError("Failed to embed texts.", "EMBEDDING", error);
 	}
 	if (embeddings.length !== texts.length) throw new MnemocyteError(`Embedder returned ${embeddings.length} embeddings for ${texts.length} texts.`, "EMBEDDING");
-	for (const embedding of embeddings) if (embedding.length !== embedder.dimensions) throw new MnemocyteError("Embedder returned an embedding with unexpected dimensions.", "EMBEDDING");
+	for (const embedding of embeddings) validateEmbedding(embedding, embedder.dimensions);
 	return embeddings;
 }
-function validateRememberInput(input) {
-	assertNonEmptyString(input.entityId, "entityId");
-	assertNonEmptyString(input.content, "content");
-	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");
+//#endregion
+//#region src/memory/validation.ts
+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);
 }
-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);
+function assertLimit(value) {
+	if (!Number.isInteger(value) || value < 1) throw new MnemocyteError("limit must be a positive integer.", "VALIDATION");
 }
-function contextInputToRecallInput(input) {
-	return {
-		entityId: input.entityId,
+function assertMinScore(value) {
+	if (!Number.isFinite(value) || value < 0 || value > 1) throw new MnemocyteError("minScore must be a number between 0 and 1.", "VALIDATION");
+}
+function assertEmbedder(embedder) {
+	if (!embedder || typeof embedder.embed !== "function") throw new MnemocyteError("embedder with an embed function is required.", "CONFIG");
+	assertNonEmptyString(embedder.model, "embedder.model", "CONFIG");
+	if (!Number.isInteger(embedder.dimensions) || embedder.dimensions < 1) throw new MnemocyteError("embedder.dimensions must be a positive integer.", "CONFIG");
+}
+const RETRIEVAL_WEIGHT_KEYS = [
+	"vector",
+	"lexical",
+	"recency",
+	"confidence",
+	"access",
+	"importance"
+];
+function assertPositiveFiniteConfigValue(value, field) {
+	if (!Number.isFinite(value) || value <= 0) throw new MnemocyteError(`${field} must be a positive finite number.`, "CONFIG");
+}
+function validateRetrievalConfig(config) {
+	if (config === void 0) return;
+	let weightTotal = 0;
+	for (const key of RETRIEVAL_WEIGHT_KEYS) {
+		const weight = config.weights?.[key] ?? DEFAULT_RETRIEVAL_WEIGHTS[key];
+		if (!Number.isFinite(weight) || weight < 0) throw new MnemocyteError(`retrieval.weights.${key} must be a non-negative finite number.`, "CONFIG");
+		weightTotal += weight;
+	}
+	if (weightTotal === 0) throw new MnemocyteError("retrieval.weights must have an effective total greater than zero.", "CONFIG");
+	if (config.recencyHalfLifeDays !== void 0) assertPositiveFiniteConfigValue(config.recencyHalfLifeDays, "retrieval.recencyHalfLifeDays");
+	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 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.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");
+}
+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);
+}
+function contextInputToRecallInput(input) {
+	return {
+		entityId: input.entityId,
 		query: input.query,
 		...input.limit === void 0 ? {} : { limit: input.limit },
 		...input.minScore === void 0 ? {} : { minScore: input.minScore },
@@ -555,27 +753,6 @@ function validatePruneInput(input) {
 	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");
 }
 /**
-* Test whether `memory` matches a {@link PruneInput}. All specified
-* selectors are AND-combined; unspecified selectors do not restrict.
-*
-* `now` is supplied by the caller so callers can share a consistent
-* timestamp across a batch.
-*/
-function matchesPruneFilter(memory, input, now) {
-	if (input.entityId !== void 0 && memory.entityId !== input.entityId) return false;
-	if (input.expired === true && !isExpired(memory, now)) return false;
-	if (input.superseded === true && memory.supersededBy === null) return false;
-	if (input.createdBefore !== void 0 && memory.createdAt.getTime() >= input.createdBefore.getTime()) return false;
-	if (input.notAccessedSince !== void 0) {
-		const last = memory.lastAccessedAt;
-		if (last !== null && last.getTime() >= input.notAccessedSince.getTime()) return false;
-	}
-	if (input.types !== void 0 && !input.types.includes(memory.type)) return false;
-	if (input.tags !== void 0 && input.tags.length > 0 && !input.tags.every((tag) => memory.tags.includes(tag))) return false;
-	if (input.maxImportance !== void 0 && IMPORTANCE_RANK[memory.importance] > IMPORTANCE_RANK[input.maxImportance]) return false;
-	return true;
-}
-/**
 * Validate a {@link FindDuplicatesInput} and throw a `"VALIDATION"`
 * {@link MnemocyteError} for malformed `threshold` / `limit` values.
 */
@@ -587,18 +764,6 @@ function validateFindDuplicatesInput(input) {
 	if (input.limit !== void 0) assertLimit(input.limit);
 }
 /**
-* Return `true` when a memory should participate in a duplicate scan,
-* given the filters on `input` and a shared `now` timestamp.
-*/
-function matchesDuplicateFilter(memory, input, now) {
-	if (memory.entityId !== input.entityId) return false;
-	if (input.includeSuperseded !== true && memory.supersededBy !== null) return false;
-	if (input.includeExpired !== true && isExpired(memory, now)) return false;
-	if (input.types !== void 0 && !input.types.includes(memory.type)) return false;
-	if (input.tags !== void 0 && input.tags.length > 0 && !input.tags.every((tag) => memory.tags.includes(tag))) return false;
-	return true;
-}
-/**
 * Validate a {@link ConsolidateInput} and throw a `"VALIDATION"`
 * {@link MnemocyteError} for malformed inputs (empty `supersededIds`
 * or a `survivorId` appearing in `supersededIds`).
@@ -618,274 +783,178 @@ function validateListAuditLogInput(input) {
 	assertNonEmptyString(input.entityId, "entityId");
 	if (input.limit !== void 0) assertLimit(input.limit);
 }
-function matchesRecallFilter(memory, input, now) {
-	if (memory.entityId !== input.entityId) return false;
-	if (!input.includeSuperseded && memory.supersededBy !== null) return false;
-	if (!input.includeExpired && isExpired(memory, now)) return false;
-	if (input.types && !input.types.includes(memory.type)) return false;
-	if (input.tags && !input.tags.every((tag) => memory.tags.includes(tag))) return false;
-	if (input.before && memory.createdAt >= input.before) return false;
-	if (input.after && memory.createdAt <= input.after) return false;
-	return true;
-}
 //#endregion
-//#region src/retrieval/scorer.ts
-const IMPORTANCE_SCORES = {
-	low: 0,
-	normal: .5,
-	high: .8,
-	critical: 1
-};
-const DEFAULT_WEIGHTS = {
-	vector: .55,
-	lexical: .2,
-	recency: .1,
-	confidence: .05,
-	access: .05,
-	importance: .05
-};
-const DEFAULT_RECENCY_HALF_LIFE_DAYS = 90;
-const DEFAULT_ACCESS_SATURATION = 10;
-function cosineSimilarity(a, b) {
-	let dot = 0;
-	let aMagnitude = 0;
-	let bMagnitude = 0;
-	for (let i = 0; i < a.length; i += 1) {
-		const av = a[i] ?? 0;
-		const bv = b[i] ?? 0;
-		dot += av * bv;
-		aMagnitude += av * av;
-		bMagnitude += bv * bv;
-	}
-	if (aMagnitude === 0 || bMagnitude === 0) return 0;
-	return dot / (Math.sqrt(aMagnitude) * Math.sqrt(bMagnitude));
-}
-function tokenizeQuery(query) {
-	return query.toLowerCase().split(/\s+/).filter(Boolean);
+//#region src/memory/client-core.ts
+function isPositionalRememberManyInput(input) {
+	return Array.isArray(input);
 }
-function lexicalScoreWithTerms(content, terms) {
-	if (terms.length === 0) return 0;
-	const lowerContent = content.toLowerCase();
-	return terms.filter((term) => lowerContent.includes(term)).length / terms.length;
-}
-function createLexicalScorer(query) {
-	const terms = tokenizeQuery(query);
-	return (content) => lexicalScoreWithTerms(content, terms);
-}
-function clampScore(value) {
-	if (!Number.isFinite(value)) return 0;
-	return Math.max(0, Math.min(1, value));
-}
-function normalizeWeights(weights) {
-	const merged = {
-		...DEFAULT_WEIGHTS,
-		...weights
-	};
-	const total = merged.vector + merged.lexical + merged.recency + merged.confidence + merged.access + merged.importance;
-	if (total <= 0) return DEFAULT_WEIGHTS;
+function providerOptions(config, signal) {
 	return {
-		vector: merged.vector / total,
-		lexical: merged.lexical / total,
-		recency: merged.recency / total,
-		confidence: merged.confidence / total,
-		access: merged.access / total,
-		importance: merged.importance / total
+		...signal === void 0 ? {} : { signal },
+		...config.provider === void 0 ? {} : { resilience: config.provider }
 	};
 }
-function createScoringConfig(config) {
+function createStoredMemory(config, input, embedding, now) {
 	return {
-		weights: normalizeWeights(config?.weights),
-		recencyHalfLifeDays: config?.recencyHalfLifeDays ?? DEFAULT_RECENCY_HALF_LIFE_DAYS,
-		accessSaturation: config?.accessSaturation ?? DEFAULT_ACCESS_SATURATION
+		id: createId(),
+		entityId: input.entityId,
+		content: input.content,
+		type: input.type ?? "fact",
+		importance: input.importance ?? "normal",
+		tags: normalizeTags(input.tags),
+		source: input.source ?? null,
+		metadata: cloneJsonObject(input.metadata ?? {}),
+		confidence: input.confidence ?? 1,
+		embeddingModel: config.embedder.model,
+		embeddingDimensions: config.embedder.dimensions,
+		supersededBy: null,
+		supersededAt: null,
+		expiresAt: input.expiresAt ?? null,
+		lastAccessedAt: null,
+		accessCount: 0,
+		createdAt: now,
+		updatedAt: now,
+		embedding
 	};
 }
-function recencyScore(createdAt, halfLifeDays) {
-	const ageMs = Date.now() - createdAt.getTime();
-	const ageDays = Math.max(0, ageMs / 864e5);
-	return Math.exp(-Math.LN2 * ageDays / halfLifeDays);
-}
-function accessScore(accessCount, saturation) {
-	if (accessCount <= 0) return 0;
-	return Math.min(1, Math.log1p(accessCount) / Math.log1p(saturation));
+function auditEvent(entityId, description, metadata, timestamp = /* @__PURE__ */ new Date()) {
+	return {
+		id: createEventId(),
+		entityId,
+		description,
+		metadata: cloneJsonObject(metadata),
+		timestamp
+	};
 }
-function toScoredMemoryWithConfig(memory, vector, lexical, input, config) {
-	const { weights } = config;
-	const recency = recencyScore(memory.createdAt, config.recencyHalfLifeDays);
-	const confidence = clampScore(memory.confidence);
-	const access = accessScore(memory.accessCount, config.accessSaturation);
-	const importance = IMPORTANCE_SCORES[memory.importance];
-	const score = Math.max(0, Math.min(1, clampScore(vector) * weights.vector + clampScore(lexical) * weights.lexical + recency * weights.recency + confidence * weights.confidence + access * weights.access + importance * weights.importance));
+function toDuplicatePair(pair) {
 	return {
-		...cloneMemory(memory),
-		score,
-		scores: {
-			vector: clampScore(vector),
-			lexical: clampScore(lexical),
-			recency,
-			confidence,
-			access,
-			importance
-		},
-		explanation: input.explain ? {
-			vectorScore: clampScore(vector),
-			lexicalScore: clampScore(lexical),
-			recencyScore: recency,
-			confidenceScore: confidence,
-			accessScore: access,
-			importanceScore: importance,
-			importanceBoost: importance * weights.importance,
-			weights,
-			finalScore: score
-		} : null
+		a: cloneMemory(pair.a),
+		b: cloneMemory(pair.b),
+		similarity: Math.max(0, Math.min(1, pair.similarity))
 	};
 }
-//#endregion
-//#region src/memory/in-memory.ts
-function createInMemoryClient(config) {
-	const memories = /* @__PURE__ */ new Map();
-	const auditLog = [];
+function createMemoryClient(config, store) {
 	let closed = false;
 	function assertOpen() {
 		if (closed) throw new MnemocyteError("Mnemocyte client is closed.", "DB");
 	}
-	function recordAudit(entityId, description, metadata) {
-		if (config.audit?.enabled !== true) return;
-		auditLog.push({
-			id: createEventId(),
-			entityId,
-			description,
-			metadata,
-			timestamp: /* @__PURE__ */ new Date()
-		});
+	async function ensureSchema() {
+		await store.ensureSchema();
 	}
-	function cloneAuditEvent(event) {
-		return {
-			id: event.id,
-			entityId: event.entityId,
-			description: event.description,
-			metadata: { ...event.metadata },
-			timestamp: new Date(event.timestamp)
-		};
+	async function ensureEmbeddingCompatibility() {
+		await store.ensureEmbeddingCompatibility(config.embedder);
+	}
+	async function recordAudit(events) {
+		if (events.length === 0 || config.audit?.enabled !== true) return;
+		try {
+			await store.addAuditEvents(events);
+		} catch {}
 	}
 	async function remember(input) {
-		return observe(config, "in-memory", "remember", { entityId: input.entityId }, async () => {
+		const preparedInput = {
+			...input,
+			metadata: cloneJsonObject(input.metadata ?? {})
+		};
+		return observe(config, store.backend, "remember", { entityId: preparedInput.entityId }, async () => {
 			assertOpen();
-			validateRememberInput(input);
-			const embedding = await embedOne(config.embedder, input.content, {
-				...input.signal === void 0 ? {} : { signal: input.signal },
-				...config.provider === void 0 ? {} : { resilience: config.provider }
-			});
-			const now = /* @__PURE__ */ new Date();
-			const memory = {
-				id: createId(),
-				entityId: input.entityId,
-				content: input.content,
-				type: input.type ?? "fact",
-				importance: input.importance ?? "normal",
-				tags: normalizeTags(input.tags),
-				source: input.source ?? null,
-				metadata: input.metadata ?? {},
-				confidence: input.confidence ?? 1,
-				embeddingModel: config.embedder.model,
-				embeddingDimensions: config.embedder.dimensions,
-				supersededBy: null,
-				supersededAt: null,
-				expiresAt: input.expiresAt ?? null,
-				lastAccessedAt: null,
-				accessCount: 0,
-				createdAt: now,
-				updatedAt: now,
-				embedding
-			};
-			memories.set(memory.id, memory);
-			recordAudit(memory.entityId, "memory.created", {
+			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");
+			await recordAudit([auditEvent(memory.entityId, "memory.created", {
 				memoryId: memory.id,
 				type: memory.type,
 				importance: memory.importance
-			});
+			})]);
 			return cloneMemory(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 () => {
+			assertOpen();
+			if (preparedInputs.length === 0) return [];
+			for (const item of preparedInputs) validateRememberInput(item);
+			await ensureEmbeddingCompatibility();
+			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);
+			await recordAudit(memories.map((memory) => auditEvent(memory.entityId, "memory.created", {
+				memoryId: memory.id,
+				type: memory.type,
+				importance: memory.importance
+			})));
+			return memories.map(cloneMemory);
+		}, (result) => ({ count: result.length }));
+	}
 	const client = {
 		remember,
-		async rememberMany(inputs) {
-			return observe(config, "in-memory", "rememberMany", { count: inputs.length }, async () => {
-				assertOpen();
-				if (inputs.length === 0) return [];
-				for (const input of inputs) validateRememberInput(input);
-				const embeddings = await embedMany(config.embedder, inputs.map((i) => i.content), {
-					...inputs[0]?.signal === void 0 ? {} : { signal: inputs[0].signal },
-					...config.provider === void 0 ? {} : { resilience: config.provider }
-				});
-				const now = /* @__PURE__ */ new Date();
-				const result = [];
-				for (let i = 0; i < inputs.length; i++) {
-					const input = inputs[i];
-					const memory = {
-						id: createId(),
-						entityId: input.entityId,
-						content: input.content,
-						type: input.type ?? "fact",
-						importance: input.importance ?? "normal",
-						tags: normalizeTags(input.tags),
-						source: input.source ?? null,
-						metadata: input.metadata ?? {},
-						confidence: input.confidence ?? 1,
-						embeddingModel: config.embedder.model,
-						embeddingDimensions: config.embedder.dimensions,
-						supersededBy: null,
-						supersededAt: null,
-						expiresAt: input.expiresAt ?? null,
-						lastAccessedAt: null,
-						accessCount: 0,
-						createdAt: now,
-						updatedAt: now,
-						embedding: embeddings[i]
-					};
-					memories.set(memory.id, memory);
-					recordAudit(memory.entityId, "memory.created", {
-						memoryId: memory.id,
-						type: memory.type,
-						importance: memory.importance
-					});
-					result.push(cloneMemory(memory));
-				}
-				return result;
-			}, (result) => ({ count: result.length }));
-		},
+		rememberMany,
 		async recall(input) {
-			return observe(config, "in-memory", "recall", { entityId: input.entityId }, async () => {
+			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);
-				const queryEmbedding = await embedOne(config.embedder, input.query, {
-					...input.signal === void 0 ? {} : { signal: input.signal },
-					...config.provider === void 0 ? {} : { resilience: config.provider }
-				});
-				const now = /* @__PURE__ */ new Date();
+				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 scored = Array.from(memories.values()).filter((memory) => matchesRecallFilter(memory, input, now)).map((memory) => toScoredMemoryWithConfig(memory, Math.max(0, cosineSimilarity(memory.embedding, queryEmbedding)), scoreLexical(memory.content), input, scoringConfig)).filter((memory) => memory.score >= minScore).sort((a, b) => b.score - a.score).slice(0, limit);
-				for (const memory of scored) {
-					const stored = memories.get(memory.id);
-					if (stored) {
-						stored.lastAccessedAt = now;
-						stored.accessCount += 1;
-						stored.updatedAt = now;
+				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 }));
 		},
 		async buildContext(input) {
-			return observe(config, "in-memory", "buildContext", { entityId: input.entityId }, async () => {
+			return observe(config, store.backend, "buildContext", { entityId: input.entityId }, async () => {
 				assertOpen();
+				validateBuildContextInput(input);
 				return buildContext({
 					input,
 					recall: (contextInput) => {
@@ -899,178 +968,375 @@ function createInMemoryClient(config) {
 			});
 		},
 		async forget(input) {
-			return observe(config, "in-memory", "forget", {
+			return observe(config, store.backend, "forget", {
 				entityId: input.entityId,
 				memoryId: input.memoryId
 			}, async () => {
 				assertOpen();
 				assertNonEmptyString(input.entityId, "entityId");
 				assertNonEmptyString(input.memoryId, "memoryId");
-				const memory = memories.get(input.memoryId);
-				if (!memory || memory.entityId !== input.entityId) throw new MnemocyteError("Memory was not found.", "NOT_FOUND");
-				memories.delete(input.memoryId);
-				recordAudit(memory.entityId, "memory.deleted", { memoryId: memory.id });
+				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, "in-memory", "forgetAll", { entityId: input.entityId }, async () => {
+			return observe(config, store.backend, "forgetAll", { entityId: input.entityId }, async () => {
 				assertOpen();
 				assertNonEmptyString(input.entityId, "entityId");
-				let deleted = 0;
-				for (const [id, memory] of memories) if (memory.entityId === input.entityId) {
-					memories.delete(id);
-					deleted += 1;
-				}
-				recordAudit(input.entityId, "entity.cleared", { count: deleted });
-				return deleted;
+				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);
 		},
 		async prune(input) {
-			return observe(config, "in-memory", "prune", input.entityId === void 0 ? {} : { entityId: input.entityId }, async () => {
+			return observe(config, store.backend, "prune", input.entityId === void 0 ? {} : { entityId: input.entityId }, async () => {
 				assertOpen();
 				validatePruneInput(input);
-				const now = /* @__PURE__ */ new Date();
-				const matched = [];
-				for (const memory of memories.values()) if (matchesPruneFilter(memory, input, now)) matched.push(memory.id);
-				const dryRun = input.dryRun === true;
-				if (!dryRun) {
-					for (const id of matched) memories.delete(id);
-					if (matched.length > 0 && input.entityId !== void 0) recordAudit(input.entityId, "memory.pruned", { count: matched.length });
-				}
+				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 }));
+		},
+		async findDuplicates(input) {
+			return observe(config, store.backend, "findDuplicates", { entityId: input.entityId }, async () => {
+				assertOpen();
+				validateFindDuplicatesInput(input);
+				await ensureEmbeddingCompatibility();
+				return (await store.findDuplicatePairs(input)).map(toDuplicatePair);
+			}, (result) => ({ count: result.length }));
+		},
+		async listAuditLog(input) {
+			return observe(config, store.backend, "listAuditLog", { entityId: input.entityId }, async () => {
+				assertOpen();
+				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 }));
+		},
+		async stats(input) {
+			return 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", {
+				entityId: input.entityId,
+				memoryId: input.survivorId
+			}, async () => {
+				assertOpen();
+				validateConsolidateInput(input);
+				await ensureSchema();
+				const survivor = await store.getMemory(input.entityId, input.survivorId);
+				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 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 {
+					survivorId: survivor.id,
+					supersededCount: 0,
+					supersededIds: []
+				};
+				const result = await store.consolidate({
+					entityId: input.entityId,
+					survivorId: survivor.id,
+					survivorTags: survivor.tags,
+					supersededIds: losers.map((loser) => loser.id),
+					mergeTags: input.mergeTags !== false,
+					now: /* @__PURE__ */ new Date(),
+					auditEnabled: config.audit?.enabled === true
+				});
 				return {
-					matchedCount: matched.length,
-					deletedCount: dryRun ? 0 : matched.length,
-					dryRun
+					survivorId: survivor.id,
+					supersededCount: result.supersededIds.length,
+					supersededIds: result.supersededIds
 				};
-			}, (result) => ({ count: result.deletedCount }));
+			}, (result) => ({ count: result.supersededCount }));
+		} },
+		async close() {
+			return observe(config, store.backend, "close", {}, async () => {
+				if (!closed) {
+					closed = true;
+					await store.close();
+				}
+			});
+		}
+	};
+	return client;
+}
+//#endregion
+//#region src/memory/filters.ts
+function isExpired(memory, now) {
+	return memory.expiresAt !== null && memory.expiresAt.getTime() <= now.getTime();
+}
+/**
+* Test whether `memory` matches a {@link PruneInput}. All specified
+* selectors are AND-combined; unspecified selectors do not restrict.
+*
+* `now` is supplied by the caller so callers can share a consistent
+* timestamp across a batch.
+*/
+function matchesPruneFilter(memory, input, now) {
+	if (input.entityId !== void 0 && memory.entityId !== input.entityId) return false;
+	if (input.expired === true && !isExpired(memory, now)) return false;
+	if (input.superseded === true && memory.supersededBy === null) return false;
+	if (input.createdBefore !== void 0 && memory.createdAt.getTime() >= input.createdBefore.getTime()) return false;
+	if (input.notAccessedSince !== void 0) {
+		const last = memory.lastAccessedAt;
+		if (last !== null && last.getTime() >= input.notAccessedSince.getTime()) return false;
+	}
+	if (input.types !== void 0 && !input.types.includes(memory.type)) return false;
+	if (input.tags !== void 0 && input.tags.length > 0 && !input.tags.every((tag) => memory.tags.includes(tag))) return false;
+	if (input.maxImportance !== void 0 && IMPORTANCE_RANK[memory.importance] > IMPORTANCE_RANK[input.maxImportance]) return false;
+	return true;
+}
+/**
+* Return `true` when a memory should participate in a duplicate scan,
+* given the filters on `input` and a shared `now` timestamp.
+*/
+function matchesDuplicateFilter(memory, input, now) {
+	if (memory.entityId !== input.entityId) return false;
+	if (input.includeSuperseded !== true && memory.supersededBy !== null) return false;
+	if (input.includeExpired !== true && isExpired(memory, now)) return false;
+	if (input.types !== void 0 && !input.types.includes(memory.type)) return false;
+	if (input.tags !== void 0 && input.tags.length > 0 && !input.tags.every((tag) => memory.tags.includes(tag))) return false;
+	return true;
+}
+function matchesRecallFilter(memory, input, now) {
+	if (memory.entityId !== input.entityId) return false;
+	if (!input.includeSuperseded && memory.supersededBy !== null) return false;
+	if (!input.includeExpired && isExpired(memory, now)) return false;
+	if (input.types && !input.types.includes(memory.type)) return false;
+	if (input.tags && !input.tags.every((tag) => memory.tags.includes(tag))) return false;
+	if (input.before && memory.createdAt >= input.before) return false;
+	if (input.after && memory.createdAt <= input.after) return false;
+	return true;
+}
+//#endregion
+//#region src/memory/in-memory.ts
+function cloneStoredMemory(memory) {
+	return {
+		...cloneMemory(memory),
+		embedding: [...memory.embedding]
+	};
+}
+function cloneAuditEvent(event) {
+	return {
+		id: event.id,
+		entityId: event.entityId,
+		description: event.description,
+		metadata: cloneJsonObject(event.metadata),
+		timestamp: new Date(event.timestamp)
+	};
+}
+function createInMemoryStore() {
+	const memories = /* @__PURE__ */ new Map();
+	const auditLog = [];
+	return {
+		backend: "in-memory",
+		async ensureSchema() {},
+		async ensureEmbeddingCompatibility() {},
+		async insertMemories(rows) {
+			const inserted = [];
+			for (const row of rows) {
+				const stored = cloneStoredMemory(row);
+				memories.set(stored.id, stored);
+				inserted.push(cloneMemory(stored));
+			}
+			return inserted;
+		},
+		async vectorSearch(input) {
+			const now = /* @__PURE__ */ new Date();
+			const minScore = input.minScore ?? 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);
+		},
+		async lexicalSearch(input) {
+			const now = /* @__PURE__ */ new Date();
+			const scoreLexical = createLexicalScorer(input.query);
+			return Array.from(memories.values()).filter((memory) => matchesRecallFilter(memory, input, now)).map((memory) => ({
+				memory: cloneMemory(memory),
+				lexicalScore: scoreLexical(memory.content)
+			})).filter((candidate) => candidate.lexicalScore > 0).sort((a, b) => b.lexicalScore - a.lexicalScore).slice(0, input.limit);
+		},
+		async getMemoryEmbeddings(memoryIds) {
+			const result = /* @__PURE__ */ new Map();
+			for (const id of memoryIds) {
+				const memory = memories.get(id);
+				if (memory) result.set(id, [...memory.embedding]);
+			}
+			return result;
+		},
+		async markMemoriesAccessed(memoryIds) {
+			const now = /* @__PURE__ */ new Date();
+			for (const id of memoryIds) {
+				const memory = memories.get(id);
+				if (memory) {
+					memory.lastAccessedAt = now;
+					memory.accessCount += 1;
+					memory.updatedAt = now;
+				}
+			}
+		},
+		async deleteMemory(entityId, memoryId) {
+			const memory = memories.get(memoryId);
+			if (!memory || memory.entityId !== entityId) return false;
+			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;
 		},
-		async findDuplicates(input) {
-			return observe(config, "in-memory", "findDuplicates", { entityId: input.entityId }, async () => {
-				assertOpen();
-				validateFindDuplicatesInput(input);
-				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 pairs = [];
-				for (let i = 0; i < candidates.length; i += 1) {
-					const a = candidates[i];
-					if (a === void 0) continue;
-					for (let j = i + 1; j < candidates.length; j += 1) {
-						const b = candidates[j];
-						if (b === void 0) continue;
-						const similarity = Math.max(0, Math.min(1, cosineSimilarity(a.embedding, b.embedding)));
-						if (similarity >= threshold) pairs.push({
-							a: cloneMemory(a),
-							b: cloneMemory(b),
-							similarity
-						});
-					}
+		async prune(input) {
+			const now = /* @__PURE__ */ new Date();
+			const matched = [];
+			for (const memory of memories.values()) if (matchesPruneFilter(memory, input, now)) matched.push(memory.id);
+			const dryRun = input.dryRun === true;
+			if (!dryRun) for (const id of matched) memories.delete(id);
+			return {
+				matchedCount: matched.length,
+				deletedCount: dryRun ? 0 : matched.length,
+				dryRun
+			};
+		},
+		async findDuplicatePairs(input) {
+			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 pairs = [];
+			for (let i = 0; i < candidates.length; i += 1) {
+				const a = candidates[i];
+				if (a === void 0) continue;
+				for (let j = i + 1; j < candidates.length; j += 1) {
+					const b = candidates[j];
+					if (b === void 0) continue;
+					const similarity = Math.max(0, Math.min(1, cosineSimilarity(a.embedding, b.embedding)));
+					if (similarity >= threshold) pairs.push({
+						a: cloneMemory(a),
+						b: cloneMemory(b),
+						similarity
+					});
 				}
-				pairs.sort((x, y) => y.similarity - x.similarity);
-				return pairs.slice(0, limit);
-			}, (result) => ({ count: result.length }));
+			}
+			pairs.sort((x, y) => y.similarity - x.similarity);
+			return pairs.slice(0, limit);
+		},
+		async addAuditEvents(events) {
+			auditLog.push(...events.map(cloneAuditEvent));
 		},
 		async listAuditLog(input) {
-			return observe(config, "in-memory", "listAuditLog", { entityId: input.entityId }, async () => {
-				assertOpen();
-				validateListAuditLogInput(input);
-				const limit = input.limit ?? 50;
-				return auditLog.map((event, idx) => ({
-					event,
-					idx
-				})).filter(({ event }) => {
-					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;
-					return true;
-				}).sort((a, b) => {
-					const dt = b.event.timestamp.getTime() - a.event.timestamp.getTime();
-					if (dt !== 0) return dt;
-					return b.idx - a.idx;
-				}).slice(0, limit).map(({ event }) => cloneAuditEvent(event));
-			}, (result) => ({ count: result.length }));
+			const limit = input.limit ?? 50;
+			return auditLog.map((event, idx) => ({
+				event,
+				idx
+			})).filter(({ event }) => {
+				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;
+				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));
 		},
-		async stats(input) {
-			return observe(config, "in-memory", "stats", input?.entityId ? { entityId: input.entityId } : {}, async () => {
-				assertOpen();
-				const now = /* @__PURE__ */ new Date();
-				const allMemories = Array.from(memories.values());
-				const selected = input?.entityId ? allMemories.filter((memory) => memory.entityId === input.entityId) : allMemories;
-				const activeMemoryCount = selected.filter((memory) => !isExpired(memory, now) && memory.supersededBy === null).length;
-				const expiredMemoryCount = selected.filter((memory) => isExpired(memory, now)).length;
-				const supersededMemoryCount = selected.filter((memory) => memory.supersededBy !== null).length;
-				if (input?.entityId) return {
-					entityId: input.entityId,
-					memoryCount: selected.length,
-					activeMemoryCount,
-					expiredMemoryCount,
-					supersededMemoryCount
-				};
-				return {
-					entityCount: new Set(allMemories.map((memory) => memory.entityId)).size,
-					memoryCount: selected.length,
-					activeMemoryCount,
-					expiredMemoryCount,
-					supersededMemoryCount
-				};
-			});
+		async getMemory(entityId, memoryId) {
+			const memory = memories.get(memoryId);
+			return memory && memory.entityId === entityId ? cloneMemory(memory) : null;
 		},
-		experimental: createExperimental(),
-		async close() {
-			return observe(config, "in-memory", "close", {}, async () => {
-				closed = true;
-				memories.clear();
+		async loadConsolidationTargets(entityId, ids) {
+			return ids.flatMap((id) => {
+				const memory = memories.get(id);
+				if (!memory || memory.entityId !== entityId) return [];
+				return [{
+					id: memory.id,
+					tags: [...memory.tags],
+					supersededBy: memory.supersededBy
+				}];
 			});
-		}
-	};
-	return client;
-	function createExperimental() {
-		return { async consolidate(input) {
-			return observe(config, "in-memory", "consolidate", {
-				entityId: input.entityId,
-				memoryId: input.survivorId
-			}, async () => {
-				assertOpen();
-				validateConsolidateInput(input);
-				const survivor = memories.get(input.survivorId);
-				if (!survivor || survivor.entityId !== input.entityId) throw new MnemocyteError("Survivor memory was not found.", "NOT_FOUND");
-				if (survivor.supersededBy !== null) throw new MnemocyteError("Survivor memory is itself superseded.", "VALIDATION");
-				const losers = [];
-				for (const id of input.supersededIds) {
+		},
+		async consolidate(input) {
+			const survivor = memories.get(input.survivorId);
+			const newlySuperseded = [];
+			for (const id of input.supersededIds) {
+				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);
+			}
+			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 || memory.entityId !== input.entityId) throw new MnemocyteError("Superseded memory was not found.", "NOT_FOUND");
-					if (memory.supersededBy !== null) continue;
-					losers.push(memory);
+					if (memory) for (const tag of memory.tags) mergedTags.add(tag);
 				}
-				const now = /* @__PURE__ */ new Date();
-				const newSupersededIds = [];
-				for (const loser of losers) {
-					loser.supersededBy = survivor.id;
-					loser.supersededAt = now;
-					loser.updatedAt = now;
-					newSupersededIds.push(loser.id);
-					recordAudit(input.entityId, "memory.superseded", {
-						memoryId: loser.id,
-						supersededBy: survivor.id
-					});
-				}
-				if (input.mergeTags !== false && losers.length > 0) {
-					const mergedTags = new Set(survivor.tags);
-					for (const loser of losers) for (const tag of loser.tags) mergedTags.add(tag);
-					if (mergedTags.size !== survivor.tags.length) {
-						survivor.tags = [...mergedTags];
-						survivor.updatedAt = now;
-					}
+				if (mergedTags.size !== survivor.tags.length) {
+					survivor.tags = [...mergedTags];
+					survivor.updatedAt = input.now;
 				}
-				return {
-					survivorId: survivor.id,
-					supersededCount: newSupersededIds.length,
-					supersededIds: newSupersededIds
-				};
-			}, (result) => ({ count: result.supersededCount }));
-		} };
-	}
+			}
+			if (input.auditEnabled) for (const id of newlySuperseded) auditLog.push({
+				id: createEventId(),
+				entityId: input.entityId,
+				description: "memory.superseded",
+				metadata: {
+					memoryId: id,
+					supersededBy: input.survivorId
+				},
+				timestamp: input.now
+			});
+			return { supersededIds: newlySuperseded };
+		},
+		async stats(input, now) {
+			const allMemories = Array.from(memories.values());
+			const selected = input?.entityId ? allMemories.filter((memory) => memory.entityId === input.entityId) : allMemories;
+			const activeMemoryCount = selected.filter((memory) => !isExpired(memory, now) && memory.supersededBy === null).length;
+			const expiredMemoryCount = selected.filter((memory) => isExpired(memory, now)).length;
+			const supersededMemoryCount = selected.filter((memory) => memory.supersededBy !== null).length;
+			if (input?.entityId) return {
+				entityId: input.entityId,
+				memoryCount: selected.length,
+				activeMemoryCount,
+				expiredMemoryCount,
+				supersededMemoryCount
+			};
+			return {
+				entityCount: new Set(allMemories.map((memory) => memory.entityId)).size,
+				memoryCount: selected.length,
+				activeMemoryCount,
+				expiredMemoryCount,
+				supersededMemoryCount
+			};
+		},
+		async close() {
+			memories.clear();
+			auditLog.length = 0;
+		}
+	};
+}
+function createInMemoryClient(config) {
+	return createMemoryClient(config, createInMemoryStore());
 }
 //#endregion
 //#region src/db/queries/events.ts
@@ -1087,10 +1353,6 @@ async function listEvents(db, filter) {
 function vectorLiteral(embedding) {
 	return `[${embedding.map(formatVectorComponent).join(",")}]`;
 }
-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);
-}
 function timestampParam(value) {
 	return sql`${value.toISOString()}::timestamptz`;
 }
@@ -1132,11 +1394,6 @@ function emptyMemoryStatsCounts() {
 		supersededMemoryCount: 0
 	};
 }
-async function insertMemory(db, row) {
-	const inserted = (await db.insert(memoriesTable).values(row).returning())[0];
-	if (!inserted) throw new MnemocyteError("Memory insert returned no rows.", "DB");
-	return inserted;
-}
 async function insertMemories(db, rows) {
 	if (rows.length === 0) return [];
 	return db.insert(memoriesTable).values(rows).returning();
@@ -1301,7 +1558,7 @@ async function setMemoryTags(db, params) {
 		updatedAt: params.now
 	}).where(and(eq(memoriesTable.entityId, params.entityId), eq(memoriesTable.id, params.memoryId)));
 }
-async function markMemoryAccessed(db, memoryIds) {
+async function markMemoriesAccessed(db, memoryIds) {
 	const now = /* @__PURE__ */ new Date();
 	if (memoryIds.length === 0) return;
 	await db.update(memoriesTable).set({
@@ -1393,71 +1650,84 @@ async function lexicalSearch(db, input) {
 		LIMIT ${input.limit}
 	`);
 }
-//#endregion
-//#region src/retrieval/index.ts
-async function hybridRecall(input) {
-	const queryEmbedding = await embedOne(input.embedder, input.input.query, {
-		...input.signal === void 0 ? {} : { signal: input.signal },
-		...input.resilience === void 0 ? {} : { resilience: input.resilience }
-	});
-	const candidateMultiplier = input.retrieval?.candidateMultiplier ?? 3;
-	const candidateLimit = Math.max(input.limit, input.limit * candidateMultiplier);
-	const scoreLexical = createLexicalScorer(input.input.query);
-	const scoringConfig = createScoringConfig(input.retrieval);
-	const [vectorRows, lexicalRows] = await Promise.all([vectorSearch(input.db, {
-		...input.input,
-		embedding: queryEmbedding,
-		limit: candidateLimit,
-		minScore: 0
-	}), lexicalSearch(input.db, {
-		...input.input,
-		limit: candidateLimit
-	})]);
-	const merged = /* @__PURE__ */ new Map();
-	for (const row of vectorRows) merged.set(row.id, {
-		row,
-		vectorScore: row.vectorScore,
-		lexicalScore: scoreLexical(row.content)
-	});
-	const lexicalOnlyRows = lexicalRows.filter((row) => !merged.has(row.id));
-	const lexicalOnlyEmbeddings = await getMemoryEmbeddings(input.db, lexicalOnlyRows.map((row) => row.id));
-	for (const row of lexicalRows) {
-		const existing = merged.get(row.id);
-		if (existing) existing.lexicalScore = row.lexicalScore;
-		else {
-			const embedding = lexicalOnlyEmbeddings.get(row.id);
-			const sim = embedding ? cosineSimilarity(embedding, queryEmbedding) : 0;
-			merged.set(row.id, {
-				row,
-				vectorScore: Math.max(0, sim),
-				lexicalScore: row.lexicalScore
-			});
-		}
-	}
-	const scored = Array.from(merged.values()).map((entry) => toScoredMemoryWithConfig(rowToMemory(entry.row), Math.max(0, entry.vectorScore), Math.max(0, entry.lexicalScore), input.input, scoringConfig)).filter((memory) => memory.score >= input.minScore).sort((a, b) => b.score - a.score).slice(0, input.limit);
-	await markMemoryAccessed(input.db, scored.map((memory) => memory.id));
-	return scored;
+async function getInstallationMeta(db) {
+	return (await db.select().from(metaTable).where(eq(metaTable.key, "installation")).limit(1))[0] ?? null;
 }
 //#endregion
-//#region src/memory/postgres.ts
-function rowToAuditEvent(row) {
+//#region src/memory/postgres-records.ts
+function toDate(value) {
+	return value instanceof Date ? value : new Date(value);
+}
+function toNullableDate(value) {
+	return value === null ? null : toDate(value);
+}
+function rowToMemory(row) {
 	return {
 		id: row.id,
 		entityId: row.entityId,
-		description: row.description,
-		metadata: row.metadata,
-		timestamp: row.timestamp
+		content: row.content,
+		type: row.type,
+		importance: row.importance,
+		tags: row.tags,
+		source: row.source,
+		metadata: cloneJsonObject(row.metadata),
+		confidence: row.confidence,
+		embeddingModel: row.embeddingModel,
+		embeddingDimensions: row.embeddingDimensions,
+		supersededBy: row.supersededBy,
+		supersededAt: toNullableDate(row.supersededAt),
+		expiresAt: toNullableDate(row.expiresAt),
+		lastAccessedAt: toNullableDate(row.lastAccessedAt),
+		accessCount: row.accessCount,
+		createdAt: toDate(row.createdAt),
+		updatedAt: toDate(row.updatedAt)
 	};
 }
+//#endregion
+//#region src/memory/postgres.ts
 const IMPORTANCE_LEVELS = [
 	"low",
 	"normal",
 	"high",
 	"critical"
 ];
+const MIGRATION_ERROR_CODES = new Set([
+	"42P01",
+	"42703",
+	"42704",
+	"42883"
+]);
+function rowToAuditEvent(row) {
+	return {
+		id: row.id,
+		entityId: row.entityId,
+		description: row.description,
+		metadata: cloneJsonObject(row.metadata),
+		timestamp: row.timestamp
+	};
+}
 function importanceCeilingLevels(max) {
 	return IMPORTANCE_LEVELS.filter((level) => IMPORTANCE_RANK[level] <= IMPORTANCE_RANK[max]);
 }
+function hasPostgresErrorCode(error, code) {
+	return typeof error === "object" && error !== null && "code" in error && error.code === code;
+}
+function getPostgresErrorCode(error) {
+	return typeof error === "object" && error !== null && "code" in error && typeof error.code === "string" ? error.code : void 0;
+}
+function normalizePostgresError(error) {
+	if (error instanceof MnemocyteError) return error;
+	const code = getPostgresErrorCode(error);
+	if (code && MIGRATION_ERROR_CODES.has(code)) return new MnemocyteError("Postgres schema is missing or incompatible. Apply the bundled Mnemocyte migrations before using the Postgres backend.", "MIGRATION", error);
+	return new MnemocyteError("Postgres operation failed.", "DB", error);
+}
+async function runPostgresOperation(operation) {
+	try {
+		return await operation();
+	} catch (error) {
+		throw normalizePostgresError(error);
+	}
+}
 function toPruneFilter(input) {
 	const filter = {};
 	if (input.entityId !== void 0) filter.entityId = input.entityId;
@@ -1470,166 +1740,76 @@ function toPruneFilter(input) {
 	if (input.maxImportance !== void 0) filter.maxImportanceLevels = importanceCeilingLevels(input.maxImportance);
 	return filter;
 }
-function createPostgresClient(config, handle) {
-	let closed = false;
-	function assertOpen() {
-		if (closed) throw new MnemocyteError("Mnemocyte client is closed.", "DB");
+function toMemoryRow(memory) {
+	return {
+		...memory,
+		tags: [...memory.tags],
+		metadata: cloneJsonObject(memory.metadata),
+		embedding: [...memory.embedding]
+	};
+}
+function createPostgresStore(handle) {
+	let schemaValidated = false;
+	let schemaValidationPromise;
+	async function ensureEmbeddingCompatibility(embedder) {
+		if (schemaValidated) return;
+		if (!schemaValidationPromise) schemaValidationPromise = validateEmbeddingCompatibility(embedder).catch((error) => {
+			schemaValidationPromise = void 0;
+			throw error;
+		});
+		await schemaValidationPromise;
 	}
-	async function recordAudit(entityId, description, metadata) {
-		if (config.audit?.enabled !== true) return;
+	async function validateEmbeddingCompatibility(embedder) {
+		let meta;
 		try {
-			await insertEvent(handle.db, {
-				id: createEventId(),
-				entityId,
-				description,
-				metadata,
-				timestamp: /* @__PURE__ */ new Date()
-			});
-		} catch {}
+			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);
+			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.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");
+		schemaValidated = true;
 	}
-	async function remember(input) {
-		return observe(config, "postgres", "remember", { entityId: input.entityId }, async () => {
-			assertOpen();
-			validateRememberInput(input);
-			const embedding = await embedOne(config.embedder, input.content, {
-				...input.signal === void 0 ? {} : { signal: input.signal },
-				...config.provider === void 0 ? {} : { resilience: config.provider }
+	return {
+		backend: "postgres",
+		async ensureSchema() {},
+		ensureEmbeddingCompatibility,
+		async insertMemories(memories) {
+			return runPostgresOperation(async () => {
+				return (await insertMemories(handle.db, memories.map(toMemoryRow))).map(rowToMemory);
 			});
-			const now = /* @__PURE__ */ new Date();
-			const memory = rowToMemory(await insertMemory(handle.db, {
-				id: createId(),
-				entityId: input.entityId,
-				content: input.content,
-				type: input.type ?? "fact",
-				importance: input.importance ?? "normal",
-				tags: normalizeTags(input.tags),
-				source: input.source ?? null,
-				metadata: input.metadata ?? {},
-				confidence: input.confidence ?? 1,
-				embedding,
-				embeddingModel: config.embedder.model,
-				embeddingDimensions: config.embedder.dimensions,
-				supersededBy: null,
-				supersededAt: null,
-				expiresAt: input.expiresAt ?? null,
-				lastAccessedAt: null,
-				accessCount: 0,
-				createdAt: now,
-				updatedAt: now
-			}));
-			await recordAudit(memory.entityId, "memory.created", {
-				memoryId: memory.id,
-				type: memory.type,
-				importance: memory.importance
+		},
+		async vectorSearch(input) {
+			return runPostgresOperation(async () => {
+				return (await vectorSearch(handle.db, input)).map((row) => ({
+					memory: rowToMemory(row),
+					vectorScore: row.vectorScore
+				}));
 			});
-			return memory;
-		}, (memory) => ({
-			memoryId: memory.id,
-			count: 1
-		}));
-	}
-	const client = {
-		remember,
-		async rememberMany(inputs) {
-			return observe(config, "postgres", "rememberMany", { count: inputs.length }, async () => {
-				assertOpen();
-				if (inputs.length === 0) return [];
-				for (const input of inputs) validateRememberInput(input);
-				const embeddings = await embedMany(config.embedder, inputs.map((i) => i.content), {
-					...inputs[0]?.signal === void 0 ? {} : { signal: inputs[0].signal },
-					...config.provider === void 0 ? {} : { resilience: config.provider }
-				});
-				const now = /* @__PURE__ */ new Date();
-				const rows = inputs.map((input, idx) => ({
-					id: createId(),
-					entityId: input.entityId,
-					content: input.content,
-					type: input.type ?? "fact",
-					importance: input.importance ?? "normal",
-					tags: normalizeTags(input.tags),
-					source: input.source ?? null,
-					metadata: input.metadata ?? {},
-					confidence: input.confidence ?? 1,
-					embedding: embeddings[idx],
-					embeddingModel: config.embedder.model,
-					embeddingDimensions: config.embedder.dimensions,
-					supersededBy: null,
-					supersededAt: null,
-					expiresAt: input.expiresAt ?? null,
-					lastAccessedAt: null,
-					accessCount: 0,
-					createdAt: now,
-					updatedAt: now
+		},
+		async lexicalSearch(input) {
+			return runPostgresOperation(async () => {
+				return (await lexicalSearch(handle.db, input)).map((row) => ({
+					memory: rowToMemory(row),
+					lexicalScore: row.lexicalScore
 				}));
-				const memories = (await insertMemories(handle.db, rows)).map(rowToMemory);
-				for (const memory of memories) recordAudit(memory.entityId, "memory.created", {
-					memoryId: memory.id,
-					type: memory.type,
-					importance: memory.importance
-				});
-				return memories;
-			}, (result) => ({ count: result.length }));
+			});
 		},
-		async recall(input) {
-			return observe(config, "postgres", "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);
-				return hybridRecall({
-					db: handle.db,
-					embedder: config.embedder,
-					input,
-					limit,
-					minScore,
-					retrieval: config.retrieval,
-					...input.signal === void 0 ? {} : { signal: input.signal },
-					...config.provider === void 0 ? {} : { resilience: config.provider }
-				});
-			}, (result) => ({ count: result.length }));
+		async getMemoryEmbeddings(memoryIds) {
+			return runPostgresOperation(() => getMemoryEmbeddings(handle.db, memoryIds));
 		},
-		async buildContext(input) {
-			return observe(config, "postgres", "buildContext", { entityId: input.entityId }, async () => {
-				assertOpen();
-				return buildContext({
-					input,
-					recall: (contextInput) => {
-						const recallInput = contextInputToRecallInput(contextInput);
-						return client.recall(input.signal === void 0 ? recallInput : {
-							...recallInput,
-							signal: input.signal
-						});
-					}
-				});
-			});
+		async markMemoriesAccessed(memoryIds) {
+			return runPostgresOperation(() => markMemoriesAccessed(handle.db, memoryIds));
 		},
-		async forget(input) {
-			return observe(config, "postgres", "forget", {
-				entityId: input.entityId,
-				memoryId: input.memoryId
-			}, async () => {
-				assertOpen();
-				assertNonEmptyString(input.entityId, "entityId");
-				assertNonEmptyString(input.memoryId, "memoryId");
-				if (!await deleteMemory(handle.db, input.entityId, input.memoryId)) throw new MnemocyteError("Memory was not found.", "NOT_FOUND");
-				await recordAudit(input.entityId, "memory.deleted", { memoryId: input.memoryId });
-			});
+		async deleteMemory(entityId, memoryId) {
+			return runPostgresOperation(() => deleteMemory(handle.db, entityId, memoryId));
 		},
-		async forgetAll(input) {
-			return observe(config, "postgres", "forgetAll", { entityId: input.entityId }, async () => {
-				assertOpen();
-				assertNonEmptyString(input.entityId, "entityId");
-				const deletedCount = await deleteMemoriesForEntity(handle.db, input.entityId);
-				await recordAudit(input.entityId, "entity.cleared", { count: deletedCount });
-				return deletedCount;
-			}, (count) => ({ count })).then(() => void 0);
+		async deleteMemoriesForEntity(entityId) {
+			return runPostgresOperation(() => deleteMemoriesForEntity(handle.db, entityId));
 		},
 		async prune(input) {
-			return observe(config, "postgres", "prune", input.entityId === void 0 ? {} : { entityId: input.entityId }, async () => {
-				assertOpen();
-				validatePruneInput(input);
+			return runPostgresOperation(async () => {
 				const filter = toPruneFilter(input);
 				if (input.dryRun === true) return {
 					matchedCount: await countPruneMatches(handle.db, filter),
@@ -1637,24 +1817,19 @@ function createPostgresClient(config, handle) {
 					dryRun: true
 				};
 				const deletedCount = await pruneMemories(handle.db, filter);
-				if (deletedCount > 0 && input.entityId !== void 0) await recordAudit(input.entityId, "memory.pruned", { count: deletedCount });
 				return {
 					matchedCount: deletedCount,
 					deletedCount,
 					dryRun: false
 				};
-			}, (result) => ({ count: result.deletedCount }));
+			});
 		},
-		async findDuplicates(input) {
-			return observe(config, "postgres", "findDuplicates", { entityId: input.entityId }, async () => {
-				assertOpen();
-				validateFindDuplicatesInput(input);
-				const threshold = input.threshold ?? .95;
-				const limit = input.limit ?? 100;
+		async findDuplicatePairs(input) {
+			return runPostgresOperation(async () => {
 				return (await findDuplicatePairs(handle.db, {
 					entityId: input.entityId,
-					threshold,
-					limit,
+					threshold: input.threshold ?? .95,
+					limit: input.limit ?? 100,
 					...input.types === void 0 ? {} : { types: input.types },
 					...input.tags === void 0 ? {} : { tags: input.tags },
 					...input.includeSuperseded === void 0 ? {} : { includeSuperseded: input.includeSuperseded },
@@ -1664,110 +1839,94 @@ function createPostgresClient(config, handle) {
 					b: rowToMemory(row.b),
 					similarity: Math.max(0, Math.min(1, row.similarity))
 				}));
-			}, (result) => ({ count: result.length }));
+			});
+		},
+		async addAuditEvents(events) {
+			return runPostgresOperation(async () => {
+				for (const event of events) await insertEvent(handle.db, {
+					id: event.id,
+					entityId: event.entityId,
+					description: event.description,
+					metadata: cloneJsonObject(event.metadata),
+					timestamp: event.timestamp
+				});
+			});
 		},
 		async listAuditLog(input) {
-			return observe(config, "postgres", "listAuditLog", { entityId: input.entityId }, async () => {
-				assertOpen();
-				validateListAuditLogInput(input);
+			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);
-			}, (result) => ({ count: result.length }));
-		},
-		async stats(input) {
-			return observe(config, "postgres", "stats", input?.entityId ? { entityId: input.entityId } : {}, async () => {
-				assertOpen();
-				const now = /* @__PURE__ */ new Date();
-				if (input?.entityId) {
-					const counts = await getEntityMemoryStatsCounts(handle.db, input.entityId, now);
-					return {
-						entityId: input.entityId,
-						...counts
-					};
-				}
-				return await getGlobalMemoryStatsCounts(handle.db, now);
 			});
 		},
-		experimental: createExperimental(),
-		async close() {
-			return observe(config, "postgres", "close", {}, async () => {
-				closed = true;
-				await handle.close();
+		async getMemory(entityId, memoryId) {
+			return runPostgresOperation(async () => {
+				const row = await getMemoryById(handle.db, entityId, memoryId);
+				return row ? rowToMemory(row) : null;
 			});
-		}
-	};
-	return client;
-	function createExperimental() {
-		return { async consolidate(input) {
-			return observe(config, "postgres", "consolidate", {
-				entityId: input.entityId,
-				memoryId: input.survivorId
-			}, async () => {
-				assertOpen();
-				validateConsolidateInput(input);
-				const survivor = await getMemoryById(handle.db, input.entityId, input.survivorId);
-				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 loadConsolidationTargets(handle.db, input.entityId, input.supersededIds);
-				const foundIds = new Set(targets.map((t) => t.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 {
-					survivorId: survivor.id,
-					supersededCount: 0,
-					supersededIds: []
-				};
-				const now = /* @__PURE__ */ new Date();
-				const { newSupersededIds } = await handle.db.transaction(async (tx) => {
+		},
+		async loadConsolidationTargets(entityId, ids) {
+			return runPostgresOperation(() => loadConsolidationTargets(handle.db, entityId, ids));
+		},
+		async consolidate(input) {
+			return runPostgresOperation(async () => {
+				return { supersededIds: await handle.db.transaction(async (tx) => {
 					const updated = await markMemoriesSuperseded(tx, {
-						survivorId: survivor.id,
+						survivorId: input.survivorId,
 						entityId: input.entityId,
-						ids: losers.map((loser) => loser.id),
-						now
+						ids: input.supersededIds,
+						now: input.now
 					});
-					const newSupersededIds = updated.map((row) => row.id);
-					if (config.audit?.enabled === true) for (const id of newSupersededIds) await insertEvent(tx, {
+					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: survivor.id
+							supersededBy: input.survivorId
 						},
-						timestamp: now
+						timestamp: input.now
 					});
-					if (input.mergeTags !== false && updated.length > 0) {
-						const mergedTags = new Set(survivor.tags);
+					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 !== survivor.tags.length) await setMemoryTags(tx, {
+						if (mergedTags.size !== input.survivorTags.length) await setMemoryTags(tx, {
 							entityId: input.entityId,
-							memoryId: survivor.id,
+							memoryId: input.survivorId,
 							tags: [...mergedTags],
-							now
+							now: input.now
 						});
 					}
+					return ids;
+				}) };
+			});
+		},
+		async stats(input, now) {
+			return runPostgresOperation(async () => {
+				if (input?.entityId) {
+					const counts = await getEntityMemoryStatsCounts(handle.db, input.entityId, now);
 					return {
-						updated,
-						newSupersededIds
+						entityId: input.entityId,
+						...counts
 					};
-				});
-				return {
-					survivorId: survivor.id,
-					supersededCount: newSupersededIds.length,
-					supersededIds: newSupersededIds
-				};
-			}, (result) => ({ count: result.supersededCount }));
-		} };
-	}
+				}
+				return await getGlobalMemoryStatsCounts(handle.db, now);
+			});
+		},
+		async close() {
+			return runPostgresOperation(() => handle.close());
+		}
+	};
+}
+function createPostgresClient(config, handle) {
+	return createMemoryClient(config, createPostgresStore(handle));
 }
 //#endregion
 //#region src/client.ts
-/** Embedding dimensionality pinned by `migrations/0000_initial.sql`. */
-const POSTGRES_EMBEDDING_DIMENSIONS = 1536;
 /**
 * Create a Mnemocyte client.
 *
@@ -1782,24 +1941,23 @@ const POSTGRES_EMBEDDING_DIMENSIONS = 1536;
 *
 * @param config - Client configuration. {@link MnemocyteConfig.embedder} is required.
 * @returns A {@link MnemocyteClient} instance.
-* @throws {MnemocyteError} With code `"CONFIG"` if `embedder` is missing or
-* invalid (including when `databaseUrl` is set and `embedder.dimensions`
-* is not 1536 — the dimensionality pinned by the bundled migration), or
-* `"VALIDATION"` if `databaseUrl` is provided but empty.
+* @throws {MnemocyteError} With code `"CONFIG"` if `embedder`, retrieval
+* tuning, or the database URL is malformed, or `"VALIDATION"` if
+* `databaseUrl` is explicitly empty.
 *
 * @example Postgres-backed client
 * ```ts
 * const client = createMnemocyte({
 *   databaseUrl: process.env.DATABASE_URL,
-*   embedder, // embedder.dimensions MUST be 1536 for the Postgres backend
+*   embedder, // embedder.dimensions must match mnemocyte_meta
 * });
 * ```
 */
 function createMnemocyte(config) {
 	assertEmbedder(config.embedder);
-	if (config.databaseUrl) {
+	validateRetrievalConfig(config.retrieval);
+	if (config.databaseUrl !== void 0) {
 		assertNonEmptyString(config.databaseUrl, "databaseUrl");
-		if (config.embedder.dimensions !== POSTGRES_EMBEDDING_DIMENSIONS) throw new MnemocyteError(`embedder.dimensions must be ${POSTGRES_EMBEDDING_DIMENSIONS} for the Postgres backend (got ${config.embedder.dimensions}). The bundled migration pins the vector column to vector(${POSTGRES_EMBEDDING_DIMENSIONS}).`, "CONFIG");
 		return createPostgresClient(config, createDatabase(config.databaseUrl));
 	}
 	return createInMemoryClient(config);