mnemocyte 0.0.7 → 0.1.0

package/dist/index.mjs

@@ -1,6 +1,6 @@
 import { drizzle } from "drizzle-orm/postgres-js";
 import postgres from "postgres";
-import { and, eq, gt, inArray, isNull, lt, sql } from "drizzle-orm";
+import { and, desc, eq, gt, inArray, isNotNull, isNull, lt, or, sql } from "drizzle-orm";
 import { customType, index, integer, jsonb, pgTable, real, text, timestamp } from "drizzle-orm/pg-core";
 //#region \0rolldown/runtime.js
 var __defProp = Object.defineProperty;
@@ -74,6 +74,56 @@ function createDatabase(databaseUrl) {
 	};
 }
 //#endregion
+//#region src/errors.ts
+/**
+* Error type thrown by every public Mnemocyte API.
+*
+* Use the {@link MnemocyteError.code} property — not the message — to branch
+* on failure modes, or call {@link isMnemocyteError} as a type guard when
+* working with `unknown` errors.
+*
+* @example
+* ```ts
+* try {
+*   await client.recall({ entityId: "u1", query: "hi" });
+* } catch (err) {
+*   if (isMnemocyteError(err) && err.code === "DB") {
+*     // handle database failure
+*   }
+*   throw err;
+* }
+* ```
+*/
+var MnemocyteError = class extends Error {
+	/** Stable, machine-readable failure code. See {@link MnemocyteErrorCode}. */
+	code;
+	/** Underlying cause, if any (e.g. an original driver or embedder error). */
+	cause;
+	/**
+	* @param message - Human-readable error message.
+	* @param code - Stable failure code; see {@link MnemocyteErrorCode}.
+	* @param cause - Optional underlying cause (driver error, network error, etc.).
+	*/
+	constructor(message, code, cause) {
+		super(message);
+		this.name = "MnemocyteError";
+		this.code = code;
+		this.cause = cause;
+	}
+};
+/**
+* Type guard for {@link MnemocyteError}.
+*
+* Prefer this over `instanceof` when working across module boundaries or
+* bundlers where multiple copies of the class may exist.
+*
+* @param error - Value to test (typically a caught `unknown`).
+* @returns `true` if `error` is a {@link MnemocyteError}.
+*/
+function isMnemocyteError(error) {
+	return error instanceof MnemocyteError;
+}
+//#endregion
 //#region src/context/formatter.ts
 function escapeXml(value) {
 	return value.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll("\"", "&quot;").replaceAll("'", "&apos;");
@@ -152,21 +202,6 @@ async function buildContext(options) {
 	return trimToTokenBudget(formatContext(await options.recall(options.input), options.input.query, format), maxTokens, tokenCounter);
 }
 //#endregion
-//#region src/errors.ts
-var MnemocyteError = class extends Error {
-	code;
-	cause;
-	constructor(message, code, cause) {
-		super(message);
-		this.name = "MnemocyteError";
-		this.code = code;
-		this.cause = cause;
-	}
-};
-function isMnemocyteError(error) {
-	return error instanceof MnemocyteError;
-}
-//#endregion
 //#region src/observability.ts
 function withMetadata(event, metadata) {
 	return {
@@ -216,6 +251,176 @@ async function observe(config, backend, operation, metadata, action, successMeta
 		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"` / `"ABORTED"`.
+*/
+function defaultShouldRetry(error) {
+	if (error instanceof MnemocyteError) {
+		if (error.code === "VALIDATION" || error.code === "CONFIG" || error.code === "ABORTED") return false;
+		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 });
+		}
+	});
+}
+/**
+* Race `promise` against the configured `timeoutMs` and the caller's
+* `signal`. Rejects with `"TIMEOUT"` or `"ABORTED"` respectively. Resolves
+* with the original promise value if it settles first.
+*/
+function withTimeout(promise, timeoutMs, signal) {
+	if (timeoutMs <= 0 && !signal) return promise;
+	return new Promise((resolve, reject) => {
+		let settled = false;
+		const timer = timeoutMs > 0 ? setTimeout(() => {
+			if (settled) return;
+			settled = true;
+			signal?.removeEventListener("abort", onAbort);
+			reject(new MnemocyteError(`Provider call timed out after ${timeoutMs}ms.`, "TIMEOUT"));
+		}, timeoutMs) : void 0;
+		const onAbort = () => {
+			if (settled) return;
+			settled = true;
+			if (timer) clearTimeout(timer);
+			reject(new MnemocyteError("Operation was aborted.", "ABORTED", signal?.reason));
+		};
+		if (signal) {
+			if (signal.aborted) {
+				if (timer) clearTimeout(timer);
+				settled = true;
+				reject(new MnemocyteError("Operation was aborted.", "ABORTED", signal.reason));
+				return;
+			}
+			signal.addEventListener("abort", onAbort, { once: true });
+		}
+		promise.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"` / `"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 withTimeout(action(externalSignal), 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;
+}
+/**
+* Ordering of {@link ImportanceLevel} from least to most important. Used
+* by `prune({ maxImportance })` to compare a memory's importance against
+* the caller-supplied ceiling.
+*/
+const IMPORTANCE_RANK = {
+	low: 0,
+	normal: 1,
+	high: 2,
+	critical: 3
+};
 function assertNonEmptyString(value, field) {
 	if (value.trim().length === 0) throw new MnemocyteError(`${field} must be a non-empty string.`, "VALIDATION");
 }
@@ -237,6 +442,10 @@ function normalizeTags(tags) {
 function createId() {
 	return `mem_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 10)}`;
 }
+/** Generate a unique audit-event id (`evt_*`). */
+function createEventId() {
+	return `evt_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 10)}`;
+}
 function isExpired(memory, now) {
 	return memory.expiresAt !== null && memory.expiresAt.getTime() <= now.getTime();
 }
@@ -245,6 +454,7 @@ function cloneMemory(memory) {
 		...memory,
 		tags: [...memory.tags],
 		metadata: { ...memory.metadata },
+		supersededAt: memory.supersededAt ? new Date(memory.supersededAt) : null,
 		expiresAt: memory.expiresAt ? new Date(memory.expiresAt) : null,
 		lastAccessedAt: memory.lastAccessedAt ? new Date(memory.lastAccessedAt) : null,
 		createdAt: new Date(memory.createdAt),
@@ -265,6 +475,7 @@ function rowToMemory(row) {
 		embeddingModel: row.embeddingModel,
 		embeddingDimensions: row.embeddingDimensions,
 		supersededBy: row.supersededBy,
+		supersededAt: row.supersededAt,
 		expiresAt: row.expiresAt,
 		lastAccessedAt: row.lastAccessedAt,
 		accessCount: row.accessCount,
@@ -272,11 +483,15 @@ function rowToMemory(row) {
 		updatedAt: row.updatedAt
 	};
 }
-async function embedOne(embedder, text) {
+async function embedOne(embedder, text, options = {}) {
 	let embeddings;
 	try {
-		embeddings = await embedder.embed([text]);
+		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];
@@ -307,6 +522,79 @@ function contextInputToRecallInput(input) {
 		...input.includeExpired === void 0 ? {} : { includeExpired: input.includeExpired }
 	};
 }
+/**
+* Validate a {@link PruneInput} and throw a `"VALIDATION"`
+* {@link MnemocyteError} when no selector is supplied. Mnemocyte
+* deliberately rejects `prune({})` to avoid surprise full-table deletes.
+*/
+function validatePruneInput(input) {
+	if (input.entityId !== void 0) assertNonEmptyString(input.entityId, "entityId");
+	if (!(input.entityId !== void 0 || input.expired === true || input.superseded === true || input.createdBefore !== void 0 || input.notAccessedSince !== void 0 || input.types !== void 0 && input.types.length > 0 || input.tags !== void 0 && input.tags.length > 0 || input.maxImportance !== void 0)) throw new MnemocyteError("prune requires at least one selector (entityId, expired, superseded, createdBefore, notAccessedSince, types, tags, or maxImportance).", "VALIDATION");
+}
+/**
+* Test whether `memory` matches a {@link PruneInput}. All specified
+* selectors are AND-combined; unspecified selectors do not restrict.
+*
+* `now` is supplied by the caller so callers can share a consistent
+* timestamp across a batch.
+*/
+function matchesPruneFilter(memory, input, now) {
+	if (input.entityId !== void 0 && memory.entityId !== input.entityId) return false;
+	if (input.expired === true && !isExpired(memory, now)) return false;
+	if (input.superseded === true && memory.supersededBy === null) return false;
+	if (input.createdBefore !== void 0 && memory.createdAt.getTime() >= input.createdBefore.getTime()) return false;
+	if (input.notAccessedSince !== void 0) {
+		const last = memory.lastAccessedAt;
+		if (last !== null && last.getTime() >= input.notAccessedSince.getTime()) return false;
+	}
+	if (input.types !== void 0 && !input.types.includes(memory.type)) return false;
+	if (input.tags !== void 0 && input.tags.length > 0 && !input.tags.every((tag) => memory.tags.includes(tag))) return false;
+	if (input.maxImportance !== void 0 && IMPORTANCE_RANK[memory.importance] > IMPORTANCE_RANK[input.maxImportance]) return false;
+	return true;
+}
+/**
+* Validate a {@link FindDuplicatesInput} and throw a `"VALIDATION"`
+* {@link MnemocyteError} for malformed `threshold` / `limit` values.
+*/
+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);
+}
+/**
+* Return `true` when a memory should participate in a duplicate scan,
+* given the filters on `input` and a shared `now` timestamp.
+*/
+function matchesDuplicateFilter(memory, input, now) {
+	if (memory.entityId !== input.entityId) return false;
+	if (input.includeSuperseded !== true && memory.supersededBy !== null) return false;
+	if (input.includeExpired !== true && isExpired(memory, now)) return false;
+	if (input.types !== void 0 && !input.types.includes(memory.type)) return false;
+	if (input.tags !== void 0 && input.tags.length > 0 && !input.tags.every((tag) => memory.tags.includes(tag))) return false;
+	return true;
+}
+/**
+* Validate a {@link ConsolidateInput} and throw a `"VALIDATION"`
+* {@link MnemocyteError} for malformed inputs (empty `supersededIds`
+* or a `survivorId` appearing in `supersededIds`).
+*/
+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");
+	for (const id of input.supersededIds) assertNonEmptyString(id, "supersededIds[*]");
+}
+/**
+* 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);
+}
 function matchesRecallFilter(memory, input, now) {
 	if (memory.entityId !== input.entityId) return false;
 	if (!input.includeSuperseded && memory.supersededBy !== null) return false;
@@ -419,15 +707,38 @@ function toScoredMemory(memory, vector, lexical, input, config) {
 //#region src/memory/in-memory.ts
 function createInMemoryClient(config) {
 	const memories = /* @__PURE__ */ new Map();
+	const auditLog = [];
 	let closed = false;
 	function assertOpen() {
 		if (closed) throw new MnemocyteError("Mnemocyte client is closed.", "DB");
 	}
+	function recordAudit(entityId, description, metadata) {
+		if (config.audit?.enabled !== true) return;
+		auditLog.push({
+			id: createEventId(),
+			entityId,
+			description,
+			metadata,
+			timestamp: /* @__PURE__ */ new Date()
+		});
+	}
+	function cloneAuditEvent(event) {
+		return {
+			id: event.id,
+			entityId: event.entityId,
+			description: event.description,
+			metadata: { ...event.metadata },
+			timestamp: new Date(event.timestamp)
+		};
+	}
 	async function remember(input) {
 		return observe(config, "in-memory", "remember", { entityId: input.entityId }, async () => {
 			assertOpen();
 			validateRememberInput(input);
-			const embedding = await embedOne(config.embedder, input.content);
+			const embedding = await embedOne(config.embedder, input.content, {
+				...input.signal === void 0 ? {} : { signal: input.signal },
+				...config.provider === void 0 ? {} : { resilience: config.provider }
+			});
 			const now = /* @__PURE__ */ new Date();
 			const memory = {
 				id: createId(),
@@ -442,6 +753,7 @@ function createInMemoryClient(config) {
 				embeddingModel: config.embedder.model,
 				embeddingDimensions: config.embedder.dimensions,
 				supersededBy: null,
+				supersededAt: null,
 				expiresAt: input.expiresAt ?? null,
 				lastAccessedAt: null,
 				accessCount: 0,
@@ -450,6 +762,11 @@ function createInMemoryClient(config) {
 				embedding
 			};
 			memories.set(memory.id, memory);
+			recordAudit(memory.entityId, "memory.created", {
+				memoryId: memory.id,
+				type: memory.type,
+				importance: memory.importance
+			});
 			return cloneMemory(memory);
 		}, (memory) => ({
 			memoryId: memory.id,
@@ -474,7 +791,10 @@ function createInMemoryClient(config) {
 				const minScore = input.minScore ?? config.defaults?.minScore ?? 0;
 				assertLimit(limit);
 				assertMinScore(minScore);
-				const queryEmbedding = await embedOne(config.embedder, input.query);
+				const queryEmbedding = await embedOne(config.embedder, input.query, {
+					...input.signal === void 0 ? {} : { signal: input.signal },
+					...config.provider === void 0 ? {} : { resilience: config.provider }
+				});
 				const now = /* @__PURE__ */ new Date();
 				const scored = Array.from(memories.values()).filter((memory) => matchesRecallFilter(memory, input, now)).map((memory) => toScoredMemory(memory, Math.max(0, cosineSimilarity(memory.embedding, queryEmbedding)), lexicalScore(memory.content, input.query), input, config.retrieval)).filter((memory) => memory.score >= minScore).sort((a, b) => b.score - a.score).slice(0, limit);
 				for (const memory of scored) {
@@ -493,7 +813,13 @@ function createInMemoryClient(config) {
 				assertOpen();
 				return buildContext({
 					input,
-					recall: (contextInput) => this.recall(contextInputToRecallInput(contextInput))
+					recall: (contextInput) => {
+						const recallInput = contextInputToRecallInput(contextInput);
+						return this.recall(input.signal === void 0 ? recallInput : {
+							...recallInput,
+							signal: input.signal
+						});
+					}
 				});
 			});
 		},
@@ -508,6 +834,7 @@ function createInMemoryClient(config) {
 				const memory = memories.get(input.memoryId);
 				if (!memory || memory.entityId !== input.entityId) throw new MnemocyteError("Memory was not found.", "NOT_FOUND");
 				memories.delete(input.memoryId);
+				recordAudit(memory.entityId, "memory.deleted", { memoryId: memory.id });
 			});
 		},
 		async forgetAll(input) {
@@ -519,9 +846,76 @@ function createInMemoryClient(config) {
 					memories.delete(id);
 					deleted += 1;
 				}
+				recordAudit(input.entityId, "entity.cleared", { count: deleted });
 				return deleted;
 			}, (count) => ({ count })).then(() => void 0);
 		},
+		async prune(input) {
+			return observe(config, "in-memory", "prune", input.entityId === void 0 ? {} : { entityId: input.entityId }, async () => {
+				assertOpen();
+				validatePruneInput(input);
+				const now = /* @__PURE__ */ new Date();
+				const matched = [];
+				for (const memory of memories.values()) if (matchesPruneFilter(memory, input, now)) matched.push(memory.id);
+				const dryRun = input.dryRun === true;
+				if (!dryRun) {
+					for (const id of matched) memories.delete(id);
+					if (matched.length > 0 && input.entityId !== void 0) recordAudit(input.entityId, "memory.pruned", { count: matched.length });
+				}
+				return {
+					matchedCount: matched.length,
+					deletedCount: dryRun ? 0 : matched.length,
+					dryRun
+				};
+			}, (result) => ({ count: result.deletedCount }));
+		},
+		async findDuplicates(input) {
+			return observe(config, "in-memory", "findDuplicates", { entityId: input.entityId }, async () => {
+				assertOpen();
+				validateFindDuplicatesInput(input);
+				const threshold = input.threshold ?? .95;
+				const limit = input.limit ?? 100;
+				const now = /* @__PURE__ */ new Date();
+				const candidates = Array.from(memories.values()).filter((memory) => matchesDuplicateFilter(memory, input, now));
+				const pairs = [];
+				for (let i = 0; i < candidates.length; i += 1) {
+					const a = candidates[i];
+					if (a === void 0) continue;
+					for (let j = i + 1; j < candidates.length; j += 1) {
+						const b = candidates[j];
+						if (b === void 0) continue;
+						const similarity = Math.max(0, Math.min(1, cosineSimilarity(a.embedding, b.embedding)));
+						if (similarity >= threshold) pairs.push({
+							a: cloneMemory(a),
+							b: cloneMemory(b),
+							similarity
+						});
+					}
+				}
+				pairs.sort((x, y) => y.similarity - x.similarity);
+				return pairs.slice(0, limit);
+			}, (result) => ({ count: result.length }));
+		},
+		async listAuditLog(input) {
+			return observe(config, "in-memory", "listAuditLog", { entityId: input.entityId }, async () => {
+				assertOpen();
+				validateListAuditLogInput(input);
+				const limit = input.limit ?? 50;
+				return auditLog.map((event, idx) => ({
+					event,
+					idx
+				})).filter(({ event }) => {
+					if (event.entityId !== input.entityId) return false;
+					if (input.before !== void 0 && event.timestamp.getTime() >= input.before.getTime()) return false;
+					if (input.after !== void 0 && event.timestamp.getTime() <= input.after.getTime()) return false;
+					return true;
+				}).sort((a, b) => {
+					const dt = b.event.timestamp.getTime() - a.event.timestamp.getTime();
+					if (dt !== 0) return dt;
+					return b.idx - a.idx;
+				}).slice(0, limit).map(({ event }) => cloneAuditEvent(event));
+			}, (result) => ({ count: result.length }));
+		},
 		async stats(input) {
 			return observe(config, "in-memory", "stats", input?.entityId ? { entityId: input.entityId } : {}, async () => {
 				assertOpen();
@@ -547,6 +941,7 @@ function createInMemoryClient(config) {
 				};
 			});
 		},
+		experimental: createExperimental(),
 		async close() {
 			return observe(config, "in-memory", "close", {}, async () => {
 				closed = true;
@@ -554,11 +949,62 @@ function createInMemoryClient(config) {
 			});
 		}
 	};
+	function createExperimental() {
+		return { async consolidate(input) {
+			return observe(config, "in-memory", "consolidate", {
+				entityId: input.entityId,
+				memoryId: input.survivorId
+			}, async () => {
+				assertOpen();
+				validateConsolidateInput(input);
+				const survivor = memories.get(input.survivorId);
+				if (!survivor || survivor.entityId !== input.entityId) throw new MnemocyteError("Survivor memory was not found.", "NOT_FOUND");
+				if (survivor.supersededBy !== null) throw new MnemocyteError("Survivor memory is itself superseded.", "VALIDATION");
+				const losers = [];
+				for (const id of input.supersededIds) {
+					const memory = memories.get(id);
+					if (!memory || memory.entityId !== input.entityId) throw new MnemocyteError("Superseded memory was not found.", "NOT_FOUND");
+					if (memory.supersededBy !== null) continue;
+					losers.push(memory);
+				}
+				const now = /* @__PURE__ */ new Date();
+				const newSupersededIds = [];
+				for (const loser of losers) {
+					loser.supersededBy = survivor.id;
+					loser.supersededAt = now;
+					loser.updatedAt = now;
+					newSupersededIds.push(loser.id);
+					recordAudit(input.entityId, "memory.superseded", {
+						memoryId: loser.id,
+						supersededBy: survivor.id
+					});
+				}
+				if (input.mergeTags !== false && losers.length > 0) {
+					const mergedTags = new Set(survivor.tags);
+					for (const loser of losers) for (const tag of loser.tags) mergedTags.add(tag);
+					if (mergedTags.size !== survivor.tags.length) {
+						survivor.tags = [...mergedTags];
+						survivor.updatedAt = now;
+					}
+				}
+				return {
+					survivorId: survivor.id,
+					supersededCount: newSupersededIds.length,
+					supersededIds: newSupersededIds
+				};
+			}, (result) => ({ count: result.supersededCount }));
+		} };
+	}
 }
 //#endregion
 //#region src/db/queries/events.ts
-async function deleteEventsForEntity(db, entityId) {
-	return (await db.delete(eventsTable).where(eq(eventsTable.entityId, entityId)).returning({ id: eventsTable.id })).length;
+async function insertEvent(db, row) {
+	const inserted = (await db.insert(eventsTable).values(row).returning())[0];
+	if (!inserted) throw new Error("Event insert returned no rows.");
+	return inserted;
+}
+async function listEvents(db, filter) {
+	return db.select().from(eventsTable).where(and(eq(eventsTable.entityId, filter.entityId), filter.before ? lt(eventsTable.timestamp, filter.before) : void 0, filter.after ? gt(eventsTable.timestamp, filter.after) : void 0)).orderBy(desc(eventsTable.timestamp)).limit(filter.limit ?? 50);
 }
 //#endregion
 //#region src/db/queries/memories.ts
@@ -573,6 +1019,9 @@ async function insertMemory(db, row) {
 	if (!inserted) throw new Error("Memory insert returned no rows.");
 	return inserted;
 }
+async function getMemoryById(db, entityId, memoryId) {
+	return (await db.select().from(memoriesTable).where(and(eq(memoriesTable.entityId, entityId), eq(memoriesTable.id, memoryId))).limit(1))[0] ?? null;
+}
 async function listMemories(db, filter) {
 	return db.select().from(memoriesTable).where(filterConditions(filter));
 }
@@ -582,6 +1031,145 @@ async function deleteMemory(db, entityId, memoryId) {
 async function deleteMemoriesForEntity(db, entityId) {
 	return (await db.delete(memoriesTable).where(eq(memoriesTable.entityId, entityId)).returning({ id: memoriesTable.id })).length;
 }
+function pruneConditions(filter) {
+	return and(filter.entityId !== void 0 ? eq(memoriesTable.entityId, filter.entityId) : void 0, filter.expired ? and(isNotNull(memoriesTable.expiresAt), sql`${memoriesTable.expiresAt} <= now()`) : void 0, filter.superseded ? isNotNull(memoriesTable.supersededBy) : void 0, filter.createdBefore ? lt(memoriesTable.createdAt, filter.createdBefore) : void 0, filter.notAccessedSince ? or(isNull(memoriesTable.lastAccessedAt), lt(memoriesTable.lastAccessedAt, filter.notAccessedSince)) : void 0, filter.types && filter.types.length > 0 ? inArray(memoriesTable.type, [...filter.types]) : void 0, filter.tags && filter.tags.length > 0 ? sql`${memoriesTable.tags} @> ${filter.tags}` : void 0, filter.maxImportanceLevels && filter.maxImportanceLevels.length > 0 ? inArray(memoriesTable.importance, [...filter.maxImportanceLevels]) : void 0);
+}
+async function countPruneMatches(db, filter) {
+	return (await db.select({ count: sql`count(*)::int` }).from(memoriesTable).where(pruneConditions(filter)))[0]?.count ?? 0;
+}
+async function pruneMemories(db, filter) {
+	return (await db.delete(memoriesTable).where(pruneConditions(filter)).returning({ id: memoriesTable.id })).length;
+}
+async function findDuplicatePairs(db, input) {
+	return (await db.execute(sql`
+		SELECT
+			a.id AS "aId",
+			a.entity_id AS "aEntityId",
+			a.content AS "aContent",
+			a.type AS "aType",
+			a.importance AS "aImportance",
+			a.tags AS "aTags",
+			a.source AS "aSource",
+			a.metadata AS "aMetadata",
+			a.confidence AS "aConfidence",
+			a.embedding AS "aEmbedding",
+			a.embedding_model AS "aEmbeddingModel",
+			a.embedding_dimensions AS "aEmbeddingDimensions",
+			a.superseded_by AS "aSupersededBy",
+			a.superseded_at AS "aSupersededAt",
+			a.expires_at AS "aExpiresAt",
+			a.last_accessed_at AS "aLastAccessedAt",
+			a.access_count AS "aAccessCount",
+			a.created_at AS "aCreatedAt",
+			a.updated_at AS "aUpdatedAt",
+			b.id AS "bId",
+			b.entity_id AS "bEntityId",
+			b.content AS "bContent",
+			b.type AS "bType",
+			b.importance AS "bImportance",
+			b.tags AS "bTags",
+			b.source AS "bSource",
+			b.metadata AS "bMetadata",
+			b.confidence AS "bConfidence",
+			b.embedding AS "bEmbedding",
+			b.embedding_model AS "bEmbeddingModel",
+			b.embedding_dimensions AS "bEmbeddingDimensions",
+			b.superseded_by AS "bSupersededBy",
+			b.superseded_at AS "bSupersededAt",
+			b.expires_at AS "bExpiresAt",
+			b.last_accessed_at AS "bLastAccessedAt",
+			b.access_count AS "bAccessCount",
+			b.created_at AS "bCreatedAt",
+			b.updated_at AS "bUpdatedAt",
+			1 - (a.embedding <=> b.embedding) AS "similarity"
+		FROM mnemocyte_memories a
+		JOIN mnemocyte_memories b
+			ON b.entity_id = a.entity_id
+			AND a.id < b.id
+			AND a.embedding IS NOT NULL
+			AND b.embedding IS NOT NULL
+		WHERE
+			a.entity_id = ${input.entityId}
+			${input.includeSuperseded ? sql`` : sql`AND a.superseded_by IS NULL AND b.superseded_by IS NULL`}
+			${input.includeExpired ? sql`` : sql`AND (a.expires_at IS NULL OR a.expires_at > now()) AND (b.expires_at IS NULL OR b.expires_at > now())`}
+			${input.types && input.types.length > 0 ? sql`AND a.type IN (${sql.join(input.types.map((type) => sql`${type}`), sql`, `)}) AND b.type IN (${sql.join(input.types.map((type) => sql`${type}`), sql`, `)})` : sql``}
+			${input.tags && input.tags.length > 0 ? sql`AND a.tags @> ${input.tags} AND b.tags @> ${input.tags}` : sql``}
+			AND 1 - (a.embedding <=> b.embedding) >= ${input.threshold}
+		ORDER BY "similarity" DESC
+		LIMIT ${input.limit}
+	`)).map((row) => {
+		return {
+			a: {
+				id: row.aId,
+				entityId: row.aEntityId,
+				content: row.aContent,
+				type: row.aType,
+				importance: row.aImportance,
+				tags: row.aTags,
+				source: row.aSource,
+				metadata: row.aMetadata,
+				confidence: row.aConfidence,
+				embedding: row.aEmbedding,
+				embeddingModel: row.aEmbeddingModel,
+				embeddingDimensions: row.aEmbeddingDimensions,
+				supersededBy: row.aSupersededBy,
+				supersededAt: row.aSupersededAt,
+				expiresAt: row.aExpiresAt,
+				lastAccessedAt: row.aLastAccessedAt,
+				accessCount: row.aAccessCount,
+				createdAt: row.aCreatedAt,
+				updatedAt: row.aUpdatedAt
+			},
+			b: {
+				id: row.bId,
+				entityId: row.bEntityId,
+				content: row.bContent,
+				type: row.bType,
+				importance: row.bImportance,
+				tags: row.bTags,
+				source: row.bSource,
+				metadata: row.bMetadata,
+				confidence: row.bConfidence,
+				embedding: row.bEmbedding,
+				embeddingModel: row.bEmbeddingModel,
+				embeddingDimensions: row.bEmbeddingDimensions,
+				supersededBy: row.bSupersededBy,
+				supersededAt: row.bSupersededAt,
+				expiresAt: row.bExpiresAt,
+				lastAccessedAt: row.bLastAccessedAt,
+				accessCount: row.bAccessCount,
+				createdAt: row.bCreatedAt,
+				updatedAt: row.bUpdatedAt
+			},
+			similarity: Number(row.similarity) || 0
+		};
+	});
+}
+async function loadConsolidationTargets(db, entityId, ids) {
+	if (ids.length === 0) return [];
+	return await db.select({
+		id: memoriesTable.id,
+		tags: memoriesTable.tags,
+		supersededBy: memoriesTable.supersededBy
+	}).from(memoriesTable).where(and(eq(memoriesTable.entityId, entityId), inArray(memoriesTable.id, [...ids])));
+}
+async function markMemoriesSuperseded(db, params) {
+	if (params.ids.length === 0) return [];
+	return await db.update(memoriesTable).set({
+		supersededBy: params.survivorId,
+		supersededAt: params.now,
+		updatedAt: params.now
+	}).where(and(eq(memoriesTable.entityId, params.entityId), inArray(memoriesTable.id, [...params.ids]), isNull(memoriesTable.supersededBy))).returning({
+		id: memoriesTable.id,
+		tags: memoriesTable.tags
+	});
+}
+async function setMemoryTags(db, params) {
+	await db.update(memoriesTable).set({
+		tags: [...params.tags],
+		updatedAt: params.now
+	}).where(and(eq(memoriesTable.entityId, params.entityId), eq(memoriesTable.id, params.memoryId)));
+}
 async function markMemoryAccessed(db, memoryIds) {
 	if (memoryIds.length === 0) return;
 	await db.update(memoriesTable).set({
@@ -670,7 +1258,10 @@ async function lexicalSearch(db, input) {
 //#endregion
 //#region src/retrieval/index.ts
 async function hybridRecall(input) {
-	const queryEmbedding = await embedOne(input.embedder, input.input.query);
+	const queryEmbedding = await embedOne(input.embedder, input.input.query, {
+		...input.signal === void 0 ? {} : { signal: input.signal },
+		...input.resilience === void 0 ? {} : { resilience: input.resilience }
+	});
 	const candidateMultiplier = input.retrieval?.candidateMultiplier ?? 3;
 	const candidateLimit = Math.max(input.limit, input.limit * candidateMultiplier);
 	const [vectorRows, lexicalRows] = await Promise.all([vectorSearch(input.db, {
@@ -703,18 +1294,63 @@ async function hybridRecall(input) {
 }
 //#endregion
 //#region src/memory/postgres.ts
+function rowToAuditEvent(row) {
+	return {
+		id: row.id,
+		entityId: row.entityId,
+		description: row.description,
+		metadata: row.metadata,
+		timestamp: row.timestamp
+	};
+}
+const IMPORTANCE_LEVELS = [
+	"low",
+	"normal",
+	"high",
+	"critical"
+];
+function importanceCeilingLevels(max) {
+	return IMPORTANCE_LEVELS.filter((level) => IMPORTANCE_RANK[level] <= IMPORTANCE_RANK[max]);
+}
+function toPruneFilter(input) {
+	const filter = {};
+	if (input.entityId !== void 0) filter.entityId = input.entityId;
+	if (input.expired === true) filter.expired = true;
+	if (input.superseded === true) filter.superseded = true;
+	if (input.createdBefore !== void 0) filter.createdBefore = input.createdBefore;
+	if (input.notAccessedSince !== void 0) filter.notAccessedSince = input.notAccessedSince;
+	if (input.types !== void 0 && input.types.length > 0) filter.types = input.types;
+	if (input.tags !== void 0 && input.tags.length > 0) filter.tags = input.tags;
+	if (input.maxImportance !== void 0) filter.maxImportanceLevels = importanceCeilingLevels(input.maxImportance);
+	return filter;
+}
 function createPostgresClient(config, handle) {
 	let closed = false;
 	function assertOpen() {
 		if (closed) throw new MnemocyteError("Mnemocyte client is closed.", "DB");
 	}
+	async function recordAudit(entityId, description, metadata) {
+		if (config.audit?.enabled !== true) return;
+		try {
+			await insertEvent(handle.db, {
+				id: createEventId(),
+				entityId,
+				description,
+				metadata,
+				timestamp: /* @__PURE__ */ new Date()
+			});
+		} catch {}
+	}
 	async function remember(input) {
 		return observe(config, "postgres", "remember", { entityId: input.entityId }, async () => {
 			assertOpen();
 			validateRememberInput(input);
-			const embedding = await embedOne(config.embedder, input.content);
+			const embedding = await embedOne(config.embedder, input.content, {
+				...input.signal === void 0 ? {} : { signal: input.signal },
+				...config.provider === void 0 ? {} : { resilience: config.provider }
+			});
 			const now = /* @__PURE__ */ new Date();
-			return rowToMemory(await insertMemory(handle.db, {
+			const memory = rowToMemory(await insertMemory(handle.db, {
 				id: createId(),
 				entityId: input.entityId,
 				content: input.content,
@@ -735,6 +1371,12 @@ function createPostgresClient(config, handle) {
 				createdAt: now,
 				updatedAt: now
 			}));
+			await recordAudit(memory.entityId, "memory.created", {
+				memoryId: memory.id,
+				type: memory.type,
+				importance: memory.importance
+			});
+			return memory;
 		}, (memory) => ({
 			memoryId: memory.id,
 			count: 1
@@ -764,7 +1406,9 @@ function createPostgresClient(config, handle) {
 					input,
 					limit,
 					minScore,
-					retrieval: config.retrieval
+					retrieval: config.retrieval,
+					...input.signal === void 0 ? {} : { signal: input.signal },
+					...config.provider === void 0 ? {} : { resilience: config.provider }
 				});
 			}, (result) => ({ count: result.length }));
 		},
@@ -773,7 +1417,13 @@ function createPostgresClient(config, handle) {
 				assertOpen();
 				return buildContext({
 					input,
-					recall: (contextInput) => this.recall(contextInputToRecallInput(contextInput))
+					recall: (contextInput) => {
+						const recallInput = contextInputToRecallInput(contextInput);
+						return this.recall(input.signal === void 0 ? recallInput : {
+							...recallInput,
+							signal: input.signal
+						});
+					}
 				});
 			});
 		},
@@ -786,14 +1436,69 @@ function createPostgresClient(config, handle) {
 				assertNonEmptyString(input.entityId, "entityId");
 				assertNonEmptyString(input.memoryId, "memoryId");
 				if (!await deleteMemory(handle.db, input.entityId, input.memoryId)) throw new MnemocyteError("Memory was not found.", "NOT_FOUND");
+				await recordAudit(input.entityId, "memory.deleted", { memoryId: input.memoryId });
 			});
 		},
 		async forgetAll(input) {
 			return observe(config, "postgres", "forgetAll", { entityId: input.entityId }, async () => {
 				assertOpen();
 				assertNonEmptyString(input.entityId, "entityId");
-				await Promise.all([deleteMemoriesForEntity(handle.db, input.entityId), deleteEventsForEntity(handle.db, input.entityId)]);
-			});
+				const deletedCount = await deleteMemoriesForEntity(handle.db, input.entityId);
+				await recordAudit(input.entityId, "entity.cleared", { count: deletedCount });
+				return deletedCount;
+			}, (count) => ({ count })).then(() => void 0);
+		},
+		async prune(input) {
+			return observe(config, "postgres", "prune", input.entityId === void 0 ? {} : { entityId: input.entityId }, async () => {
+				assertOpen();
+				validatePruneInput(input);
+				const filter = toPruneFilter(input);
+				if (input.dryRun === true) return {
+					matchedCount: await countPruneMatches(handle.db, filter),
+					deletedCount: 0,
+					dryRun: true
+				};
+				const deletedCount = await pruneMemories(handle.db, filter);
+				if (deletedCount > 0 && input.entityId !== void 0) await recordAudit(input.entityId, "memory.pruned", { count: deletedCount });
+				return {
+					matchedCount: deletedCount,
+					deletedCount,
+					dryRun: false
+				};
+			}, (result) => ({ count: result.deletedCount }));
+		},
+		async findDuplicates(input) {
+			return observe(config, "postgres", "findDuplicates", { entityId: input.entityId }, async () => {
+				assertOpen();
+				validateFindDuplicatesInput(input);
+				const threshold = input.threshold ?? .95;
+				const limit = input.limit ?? 100;
+				return (await findDuplicatePairs(handle.db, {
+					entityId: input.entityId,
+					threshold,
+					limit,
+					...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 }
+				})).map((row) => ({
+					a: rowToMemory(row.a),
+					b: rowToMemory(row.b),
+					similarity: Math.max(0, Math.min(1, row.similarity))
+				}));
+			}, (result) => ({ count: result.length }));
+		},
+		async listAuditLog(input) {
+			return observe(config, "postgres", "listAuditLog", { entityId: input.entityId }, async () => {
+				assertOpen();
+				validateListAuditLogInput(input);
+				return (await listEvents(handle.db, {
+					entityId: input.entityId,
+					limit: input.limit ?? 50,
+					...input.before === void 0 ? {} : { before: input.before },
+					...input.after === void 0 ? {} : { after: input.after }
+				})).map(rowToAuditEvent);
+			}, (result) => ({ count: result.length }));
 		},
 		async stats(input) {
 			return observe(config, "postgres", "stats", input?.entityId ? { entityId: input.entityId } : {}, async () => {
@@ -823,6 +1528,7 @@ function createPostgresClient(config, handle) {
 				};
 			});
 		},
+		experimental: createExperimental(),
 		async close() {
 			return observe(config, "postgres", "close", {}, async () => {
 				closed = true;
@@ -830,13 +1536,93 @@ function createPostgresClient(config, handle) {
 			});
 		}
 	};
+	function createExperimental() {
+		return { async consolidate(input) {
+			return observe(config, "postgres", "consolidate", {
+				entityId: input.entityId,
+				memoryId: input.survivorId
+			}, async () => {
+				assertOpen();
+				validateConsolidateInput(input);
+				const survivor = await getMemoryById(handle.db, input.entityId, input.survivorId);
+				if (!survivor) throw new MnemocyteError("Survivor memory was not found.", "NOT_FOUND");
+				if (survivor.supersededBy !== null) throw new MnemocyteError("Survivor memory is itself superseded.", "VALIDATION");
+				const targets = await loadConsolidationTargets(handle.db, input.entityId, input.supersededIds);
+				const foundIds = new Set(targets.map((t) => t.id));
+				for (const id of input.supersededIds) if (!foundIds.has(id)) throw new MnemocyteError("Superseded memory was not found.", "NOT_FOUND");
+				const losers = targets.filter((target) => target.supersededBy === null);
+				if (losers.length === 0) return {
+					survivorId: survivor.id,
+					supersededCount: 0,
+					supersededIds: []
+				};
+				const now = /* @__PURE__ */ new Date();
+				const updated = await markMemoriesSuperseded(handle.db, {
+					survivorId: survivor.id,
+					entityId: input.entityId,
+					ids: losers.map((loser) => loser.id),
+					now
+				});
+				const newSupersededIds = updated.map((row) => row.id);
+				for (const id of newSupersededIds) await recordAudit(input.entityId, "memory.superseded", {
+					memoryId: id,
+					supersededBy: survivor.id
+				});
+				if (input.mergeTags !== false && updated.length > 0) {
+					const mergedTags = new Set(survivor.tags);
+					for (const row of updated) for (const tag of row.tags) mergedTags.add(tag);
+					if (mergedTags.size !== survivor.tags.length) await setMemoryTags(handle.db, {
+						entityId: input.entityId,
+						memoryId: survivor.id,
+						tags: [...mergedTags],
+						now
+					});
+				}
+				return {
+					survivorId: survivor.id,
+					supersededCount: newSupersededIds.length,
+					supersededIds: newSupersededIds
+				};
+			}, (result) => ({ count: result.supersededCount }));
+		} };
+	}
 }
 //#endregion
 //#region src/client.ts
+/** Embedding dimensionality pinned by `migrations/0000_initial.sql`. */
+const POSTGRES_EMBEDDING_DIMENSIONS = 1536;
+/**
+* Create a Mnemocyte client.
+*
+* When {@link MnemocyteConfig.databaseUrl} is provided, a Postgres-backed
+* client is returned (requires the `pgvector` extension and the bundled
+* migration applied). Otherwise an in-memory client is returned, intended
+* for tests, demos, and short-lived processes.
+*
+* The returned client owns any underlying resources (e.g. the Postgres
+* connection pool). Call {@link MnemocyteClient.close} when finished to
+* release them.
+*
+* @param config - Client configuration. {@link MnemocyteConfig.embedder} is required.
+* @returns A {@link MnemocyteClient} instance.
+* @throws {MnemocyteError} With code `"CONFIG"` if `embedder` is missing or
+* invalid (including when `databaseUrl` is set and `embedder.dimensions`
+* is not 1536 — the dimensionality pinned by the bundled migration), or
+* `"VALIDATION"` if `databaseUrl` is provided but empty.
+*
+* @example Postgres-backed client
+* ```ts
+* const client = createMnemocyte({
+*   databaseUrl: process.env.DATABASE_URL,
+*   embedder, // embedder.dimensions MUST be 1536 for the Postgres backend
+* });
+* ```
+*/
 function createMnemocyte(config) {
 	assertEmbedder(config.embedder);
 	if (config.databaseUrl) {
 		assertNonEmptyString(config.databaseUrl, "databaseUrl");
+		if (config.embedder.dimensions !== POSTGRES_EMBEDDING_DIMENSIONS) throw new MnemocyteError(`embedder.dimensions must be ${POSTGRES_EMBEDDING_DIMENSIONS} for the Postgres backend (got ${config.embedder.dimensions}). The bundled migration pins the vector column to vector(${POSTGRES_EMBEDDING_DIMENSIONS}).`, "CONFIG");
 		return createPostgresClient(config, createDatabase(config.databaseUrl));
 	}
 	return createInMemoryClient(config);