mnemocyte 0.5.0 → 0.5.1

package/dist/index.mjs

@@ -1,6 +1,945 @@
-import { n as isMnemocyteError, t as MnemocyteError } from "./errors-DIPysVWl.mjs";
-import { _ as cloneJsonObject, a as assertEmbedder, c as validateRetrievalConfig, d as IMPORTANCE_RANK, f as cosineSimilarity, g as createEventId, h as cloneMemory, i as createMemoryClient, l as assertPruneFilterHasSelector, m as toVectorScore, n as unwrapMnemocyteStoreConfig, o as assertNonEmptyString, p as createLexicalScorer, r as memoryHasDependentsError, s as validateProviderResilienceConfig, v as throwIfAborted, y as parsePostgresDatabaseUrl } from "./store-config-BFFTm1sj.mjs";
-//#region src/memory/filters.ts
+import { n as isMnemocyteError, t as MnemocyteError } from "./errors-Dgt2nAs1.mjs";
+import { c as IMPORTANCE_RANK, d as createId, f as normalizeTags, g as parsePostgresDatabaseUrl, h as withResilience, i as assertPruneFilterHasSelector, l as cloneMemory, m as throwIfAborted, n as unwrapMnemocyteStoreConfig, p as cloneJsonObject, r as memoryHasDependentsError, u as createEventId } from "./store-config-BZ4J1hrM.mjs";
+// 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);
+	}
+}
+// 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 "";
+}
+// 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);
+}
+// 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;
+		});
+	}
+}
+// 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
+	};
+}
+// 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;
+}
+// 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`);
+}
+// 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;
+		}
+	};
+}
+// src/memory/filters.ts
 function isExpired(memory, now) {
 	return memory.expiresAt !== null && memory.expiresAt.getTime() <= now.getTime();
 }
@@ -47,8 +986,7 @@ function matchesRecallFilter(memory, input, now) {
 	if (input.after && memory.createdAt <= input.after) return false;
 	return true;
 }
-//#endregion
-//#region src/memory/in-memory.ts
+// src/memory/in-memory.ts
 function cloneAuditEvent(event) {
 	return {
 		id: event.id,
@@ -128,7 +1066,7 @@ function createInMemoryStore() {
 		async deleteMemory(entityId, memoryId) {
 			const memory = memories.get(memoryId);
 			if (!memory || memory.entityId !== entityId) return false;
-			assertNoDependentMemories(memories, new Set([memoryId]));
+			assertNoDependentMemories(memories, /* @__PURE__ */ new Set([memoryId]));
 			return memories.delete(memoryId);
 		},
 		async deleteMemoriesForEntity(entityId) {
@@ -308,12 +1246,11 @@ function createInMemoryStore() {
 function createInMemoryClient(config) {
 	return createMemoryClient(config, createInMemoryStore());
 }
-//#endregion
-//#region src/memory/lazy-postgres.ts
+// src/memory/lazy-postgres.ts
 function createLazyPostgresStore(databaseUrl) {
 	let storePromise;
 	function loadStore() {
-		storePromise ??= import("./postgres-runtime-DxJxns07.mjs").then(({ createPostgresStoreFromUrl }) => createPostgresStoreFromUrl(databaseUrl));
+		storePromise ??= import("./postgres-runtime-51fQVwqa.mjs").then(({ createPostgresStoreFromUrl }) => createPostgresStoreFromUrl(databaseUrl));
 		return storePromise;
 	}
 	return {
@@ -374,8 +1311,7 @@ function createLazyPostgresStore(databaseUrl) {
 		}
 	};
 }
-//#endregion
-//#region src/client.ts
+// src/client.ts
 /**
 * Create a Mnemocyte client.
 *
@@ -418,7 +1354,6 @@ function createMnemocyte(config) {
 	if (config.store !== void 0) return createMemoryClient(config, unwrapMnemocyteStoreConfig(config.store));
 	return createInMemoryClient(config);
 }
-//#endregion
 export { MnemocyteError, createMnemocyte, isMnemocyteError };
 
 //# sourceMappingURL=index.mjs.map