mnemocyte 0.3.0 → 0.5.0

package/dist/store-config-BFFTm1sj.mjs

@@ -0,0 +1,1255 @@
+import { t as MnemocyteError } from "./errors-DIPysVWl.mjs";
+//#region src/database-url.ts
+function parsePostgresDatabaseUrl(databaseUrl) {
+	let url;
+	try {
+		url = new URL(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");
+	return url;
+}
+//#endregion
+//#region src/context/formatter.ts
+function escapeXml(value) {
+	return value.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll("\"", "&quot;").replaceAll("'", "&apos;");
+}
+function formatMetadata(memory) {
+	const parts = [
+		`type=${memory.type}`,
+		`importance=${memory.importance}`,
+		`score=${memory.score.toFixed(3)}`
+	];
+	if (memory.source) parts.push(`source=${memory.source}`);
+	if (memory.tags.length > 0) parts.push(`tags=${memory.tags.join(",")}`);
+	return parts.join("; ");
+}
+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",
+		"",
+		`Query: ${query}`,
+		"",
+		"## Relevant Memories"
+	];
+	for (const memory of memories) {
+		const fence = markdownFence(memory.content);
+		lines.push("", `- ${formatMetadata(memory)}`, `  ${fence}text`, ...memory.content.split("\n").map((line) => `  ${line}`), `  ${fence}`);
+	}
+	if (omittedCount > 0) lines.push("", `[${omittedCount} memories omitted to fit token budget]`);
+	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",
+		"",
+		`QUERY: ${query}`,
+		"",
+		"RELEVANT MEMORIES"
+	];
+	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");
+}
+function formatXml(memories, query, omittedCount) {
+	const lines = [`<memory_context query="${escapeXml(query)}">`];
+	for (const memory of memories) lines.push(`  <memory id="${escapeXml(memory.id)}" type="${escapeXml(memory.type)}" importance="${escapeXml(memory.importance)}" score="${memory.score.toFixed(3)}">`, `    <content>${escapeXml(memory.content)}</content>`, `    <metadata>${escapeXml(formatMetadata(memory))}</metadata>`, "  </memory>");
+	if (omittedCount > 0) lines.push(`  <omitted count="${omittedCount}" reason="token_budget" />`);
+	lines.push("</memory_context>");
+	return lines.join("\n");
+}
+function formatContext(memories, query, format, omittedCount = 0) {
+	switch (format) {
+		case "markdown": return formatMarkdown(memories, query, omittedCount);
+		case "plain": return formatPlain(memories, query, omittedCount);
+		case "xml": return formatXml(memories, query, omittedCount);
+	}
+}
+//#endregion
+//#region src/context/tokens.ts
+const TRUNCATION_MARKER = "[truncated to fit token budget]";
+const heuristicTokenCounter = { count(text) {
+	return Math.ceil(text.length / 4);
+} };
+function trimToTokenBudget(text, maxTokens, tokenCounter) {
+	if (maxTokens < 1 || tokenCounter.count(text) <= maxTokens) return text;
+	let low = 0;
+	let high = text.length;
+	let best = "";
+	while (low <= high) {
+		const mid = Math.floor((low + high) / 2);
+		const output = `${text.slice(0, mid).trimEnd()}\n${TRUNCATION_MARKER}`;
+		if (tokenCounter.count(output) <= maxTokens) {
+			best = output;
+			low = mid + 1;
+		} else high = mid - 1;
+	}
+	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
+async function buildContext(options) {
+	const format = options.input.format ?? "markdown";
+	const maxTokens = options.input.maxTokens ?? 1200;
+	const tokenCounter = options.input.tokenCounter ?? heuristicTokenCounter;
+	const memories = await options.recall(options.input);
+	let low = 0;
+	let high = memories.length;
+	let bestContext = "";
+	while (low <= high) {
+		const mid = Math.floor((low + high) / 2);
+		const omittedCount = memories.length - mid;
+		const context = formatContext(memories.slice(0, mid), options.input.query, format, omittedCount);
+		if (tokenCounter.count(context) <= maxTokens) {
+			bestContext = context;
+			low = mid + 1;
+		} else high = mid - 1;
+	}
+	if (bestContext || memories.length === 0) return bestContext;
+	return trimToTokenBudget(formatContext([], options.input.query, format, memories.length), maxTokens, tokenCounter);
+}
+//#endregion
+//#region src/observability.ts
+function withMetadata(event, metadata) {
+	return {
+		...event,
+		...metadata.entityId === void 0 ? {} : { entityId: metadata.entityId },
+		...metadata.memoryId === void 0 ? {} : { memoryId: metadata.memoryId },
+		...metadata.count === void 0 ? {} : { count: metadata.count }
+	};
+}
+async function emitObservation(config, event) {
+	try {
+		await config.observability?.onEvent?.(event);
+	} catch {
+		return;
+	}
+}
+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;
+		});
+	}
+}
+//#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);
+}
+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);
+	}
+}
+//#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 toVectorScore(cosineSimilarity) {
+	return clampScore(cosineSimilarity);
+}
+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
+	};
+}
+/**
+* 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
+};
+/** Default cosine-similarity threshold for {@link FindDuplicatesInput}. */
+const DEFAULT_DUPLICATE_THRESHOLD = .95;
+//#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;
+	try {
+		embeddings = await withResilience((signal) => signal === void 0 ? embedder.embed([text]) : embedder.embed([text], { signal }), {
+			...options.signal === void 0 ? {} : { signal: options.signal },
+			...options.resilience === void 0 ? {} : { resilience: options.resilience }
+		});
+	} catch (error) {
+		if (error instanceof MnemocyteError && (error.code === "TIMEOUT" || error.code === "ABORTED")) throw error;
+		throw new MnemocyteError("Failed to embed text.", "EMBEDDING", error);
+	}
+	const embedding = embeddings[0];
+	if (!embedding) throw new MnemocyteError("Embedder returned no embedding.", "EMBEDDING");
+	validateEmbedding(embedding, embedder.dimensions);
+	return embedding;
+}
+async function embedMany(embedder, texts, options = {}) {
+	if (texts.length === 0) return [];
+	let embeddings;
+	try {
+		embeddings = await withResilience((signal) => signal === void 0 ? embedder.embed(texts) : embedder.embed(texts, { signal }), {
+			...options.signal === void 0 ? {} : { signal: options.signal },
+			...options.resilience === void 0 ? {} : { resilience: options.resilience }
+		});
+	} catch (error) {
+		if (error instanceof MnemocyteError && (error.code === "TIMEOUT" || error.code === "ABORTED")) throw error;
+		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) validateEmbedding(embedding, embedder.dimensions);
+	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 = [
+	"low",
+	"normal",
+	"high",
+	"critical"
+];
+function isMemoryType(value) {
+	return typeof value === "string" && MEMORY_TYPES.includes(value);
+}
+function isImportanceLevel(value) {
+	return typeof value === "string" && IMPORTANCE_LEVELS.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);
+}
+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", "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 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.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 {
+		entityId: input.entityId,
+		query: input.query,
+		...input.limit === void 0 ? {} : { limit: input.limit },
+		...input.minScore === void 0 ? {} : { minScore: input.minScore },
+		...input.types === void 0 ? {} : { types: input.types },
+		...input.tags === void 0 ? {} : { tags: input.tags },
+		...input.includeSuperseded === void 0 ? {} : { includeSuperseded: input.includeSuperseded },
+		...input.includeExpired === void 0 ? {} : { includeExpired: input.includeExpired }
+	};
+}
+/**
+* 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");
+	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"`
+* {@link MnemocyteError} for malformed `threshold` / `limit` values.
+*/
+function validateFindDuplicatesInput(input) {
+	assertNonEmptyString(input.entityId, "entityId");
+	if (input.threshold !== void 0) {
+		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"`
+* {@link MnemocyteError} for malformed inputs (empty `supersededIds`
+* a `survivorId` appearing in `supersededIds`, or duplicate loser IDs).
+*/
+function validateConsolidateInput(input) {
+	assertNonEmptyString(input.entityId, "entityId");
+	assertNonEmptyString(input.survivorId, "survivorId");
+	if (input.supersededIds.length === 0) throw new MnemocyteError("supersededIds must contain at least one memory id.", "VALIDATION");
+	if (input.supersededIds.includes(input.survivorId)) throw new MnemocyteError("survivorId must not appear in supersededIds.", "VALIDATION");
+	const seenIds = /* @__PURE__ */ new Set();
+	for (const id of input.supersededIds) {
+		assertNonEmptyString(id, "supersededIds[*]");
+		if (seenIds.has(id)) throw new MnemocyteError("supersededIds must not contain duplicate memory ids.", "VALIDATION");
+		seenIds.add(id);
+	}
+}
+/**
+* Validate a {@link ListAuditLogInput} and throw a `"VALIDATION"`
+* {@link MnemocyteError} when malformed.
+*/
+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
+function isPositionalRememberManyInput(input) {
+	return Array.isArray(input);
+}
+function providerOptions(config, signal) {
+	return {
+		...signal === void 0 ? {} : { 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(),
+		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
+	};
+}
+function auditEvent(entityId, description, metadata, timestamp = /* @__PURE__ */ new Date()) {
+	return {
+		id: createEventId(),
+		entityId,
+		description,
+		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),
+		b: cloneMemory(pair.b),
+		similarity: Math.max(0, Math.min(1, pair.similarity))
+	};
+}
+function createMemoryClient(config, store) {
+	let state = "open";
+	let activeOperations = 0;
+	let operationsDrainedPromise;
+	let resolveOperationsDrained;
+	let closePromise;
+	function assertOpen() {
+		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();
+	}
+	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 {}
+	}
+	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 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 memory;
+		}, (memory) => ({
+			memoryId: memory.id,
+			count: 1
+		})));
+	}
+	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);
+			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 = 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;
+		}, (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 }));
+	}
+	return {
+		remember,
+		rememberMany,
+		recall(input) {
+			return runOperation("recall", { entityId: input.entityId }, () => recall(input));
+		},
+		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 recall(input.signal === void 0 ? recallInput : {
+							...recallInput,
+							signal: input.signal
+						});
+					}
+				});
+			}));
+		},
+		forget(input) {
+			return runOperation("forget", {
+				entityId: input.entityId,
+				memoryId: input.memoryId
+			}, () => observe(config, store.backend, "forget", {
+				entityId: input.entityId,
+				memoryId: input.memoryId
+			}, async () => {
+				assertOpen();
+				assertNonEmptyString(input.entityId, "entityId");
+				assertNonEmptyString(input.memoryId, "memoryId");
+				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 })]);
+			}));
+		},
+		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));
+		},
+		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();
+				throwIfAborted(input.signal);
+				const filter = validatePruneInput(input);
+				await ensureSchema();
+				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 })));
+		},
+		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, storeOptions(input.signal))).map(toDuplicatePair);
+			}, (result) => ({ count: result.length })));
+		},
+		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, storeOptions(input.signal));
+			}, (result) => ({ count: result.length })));
+		},
+		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: { 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, 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, 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");
+				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: []
+				};
+				const result = await store.consolidate({
+					entityId: input.entityId,
+					survivorId: survivor.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 })));
+		} },
+		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;
+		}
+	};
+}
+//#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/store-config.ts
+const MEMORY_STORE_CONFIG = Symbol.for("mnemocyte.memory-store-config");
+function createMnemocyteStoreConfig(store) {
+	return Object.freeze({ [MEMORY_STORE_CONFIG]: store });
+}
+function unwrapMnemocyteStoreConfig(config) {
+	const candidate = config;
+	if (typeof candidate !== "object" || candidate === null || !(MEMORY_STORE_CONFIG in candidate)) throw new MnemocyteError("store must be created by a supported Mnemocyte store adapter.", "CONFIG");
+	return candidate[MEMORY_STORE_CONFIG];
+}
+//#endregion
+export { cloneJsonObject as _, assertEmbedder as a, validateRetrievalConfig as c, IMPORTANCE_RANK as d, cosineSimilarity as f, createEventId as g, cloneMemory as h, createMemoryClient as i, assertPruneFilterHasSelector as l, toVectorScore as m, unwrapMnemocyteStoreConfig as n, assertNonEmptyString as o, createLexicalScorer as p, memoryHasDependentsError as r, validateProviderResilienceConfig as s, createMnemocyteStoreConfig as t, DEFAULT_DUPLICATE_THRESHOLD as u, throwIfAborted as v, parsePostgresDatabaseUrl as y };
+
+//# sourceMappingURL=store-config-BFFTm1sj.mjs.map