mnemocyte 0.0.6 → 0.0.8

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, 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;
@@ -153,9 +153,35 @@ async function buildContext(options) {
 }
 //#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";
@@ -163,6 +189,238 @@ var MnemocyteError = class extends Error {
 		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/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 observe(config, backend, operation, metadata, action, successMetadata) {
+	const startedAt = Date.now();
+	await emitObservation(config, withMetadata({
+		operation,
+		phase: "start",
+		backend,
+		timestamp: new Date(startedAt)
+	}, metadata));
+	try {
+		const result = await action();
+		await emitObservation(config, withMetadata({
+			operation,
+			phase: "success",
+			backend,
+			timestamp: /* @__PURE__ */ new Date(),
+			durationMs: Date.now() - startedAt
+		}, {
+			...metadata,
+			...successMetadata?.(result)
+		}));
+		return result;
+	} catch (error) {
+		await emitObservation(config, withMetadata({
+			operation,
+			phase: "error",
+			backend,
+			timestamp: /* @__PURE__ */ new Date(),
+			durationMs: Date.now() - startedAt,
+			error
+		}, metadata));
+		throw error;
+	}
+}
+//#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");
 }
@@ -219,11 +477,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];
@@ -254,6 +516,36 @@ 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;
+}
 function matchesRecallFilter(memory, input, now) {
 	if (memory.entityId !== input.entityId) return false;
 	if (!input.includeSuperseded && memory.supersededBy !== null) return false;
@@ -371,107 +663,162 @@ function createInMemoryClient(config) {
 		if (closed) throw new MnemocyteError("Mnemocyte client is closed.", "DB");
 	}
 	async function remember(input) {
-		assertOpen();
-		validateRememberInput(input);
-		const embedding = await embedOne(config.embedder, input.content);
-		const now = /* @__PURE__ */ new Date();
-		const memory = {
-			id: createId(),
-			entityId: input.entityId,
-			content: input.content,
-			type: input.type ?? "fact",
-			importance: input.importance ?? "normal",
-			tags: normalizeTags(input.tags),
-			source: input.source ?? null,
-			metadata: input.metadata ?? {},
-			confidence: input.confidence ?? 1,
-			embeddingModel: config.embedder.model,
-			embeddingDimensions: config.embedder.dimensions,
-			supersededBy: null,
-			expiresAt: input.expiresAt ?? null,
-			lastAccessedAt: null,
-			accessCount: 0,
-			createdAt: now,
-			updatedAt: now,
-			embedding
-		};
-		memories.set(memory.id, memory);
-		return cloneMemory(memory);
+		return observe(config, "in-memory", "remember", { entityId: input.entityId }, async () => {
+			assertOpen();
+			validateRememberInput(input);
+			const embedding = await embedOne(config.embedder, input.content, {
+				...input.signal === void 0 ? {} : { signal: input.signal },
+				...config.provider === void 0 ? {} : { resilience: config.provider }
+			});
+			const now = /* @__PURE__ */ new Date();
+			const memory = {
+				id: createId(),
+				entityId: input.entityId,
+				content: input.content,
+				type: input.type ?? "fact",
+				importance: input.importance ?? "normal",
+				tags: normalizeTags(input.tags),
+				source: input.source ?? null,
+				metadata: input.metadata ?? {},
+				confidence: input.confidence ?? 1,
+				embeddingModel: config.embedder.model,
+				embeddingDimensions: config.embedder.dimensions,
+				supersededBy: null,
+				expiresAt: input.expiresAt ?? null,
+				lastAccessedAt: null,
+				accessCount: 0,
+				createdAt: now,
+				updatedAt: now,
+				embedding
+			};
+			memories.set(memory.id, memory);
+			return cloneMemory(memory);
+		}, (memory) => ({
+			memoryId: memory.id,
+			count: 1
+		}));
 	}
 	return {
 		remember,
 		async rememberMany(inputs) {
-			assertOpen();
-			const result = [];
-			for (const input of inputs) result.push(await remember(input));
-			return result;
+			return observe(config, "in-memory", "rememberMany", { count: inputs.length }, async () => {
+				assertOpen();
+				const result = [];
+				for (const input of inputs) result.push(await remember(input));
+				return result;
+			}, (result) => ({ count: result.length }));
 		},
 		async recall(input) {
-			assertOpen();
-			validateRecallInput(input);
-			const limit = input.limit ?? config.defaults?.limit ?? 10;
-			const minScore = input.minScore ?? config.defaults?.minScore ?? 0;
-			assertLimit(limit);
-			assertMinScore(minScore);
-			const queryEmbedding = await embedOne(config.embedder, input.query);
-			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)).filter((memory) => memory.score >= minScore).sort((a, b) => b.score - a.score).slice(0, limit);
-			for (const memory of scored) {
-				const stored = memories.get(memory.id);
-				if (stored) {
-					stored.lastAccessedAt = now;
-					stored.accessCount += 1;
-					stored.updatedAt = now;
+			return observe(config, "in-memory", "recall", { entityId: input.entityId }, async () => {
+				assertOpen();
+				validateRecallInput(input);
+				const limit = input.limit ?? config.defaults?.limit ?? 10;
+				const minScore = input.minScore ?? config.defaults?.minScore ?? 0;
+				assertLimit(limit);
+				assertMinScore(minScore);
+				const queryEmbedding = await embedOne(config.embedder, input.query, {
+					...input.signal === void 0 ? {} : { signal: input.signal },
+					...config.provider === void 0 ? {} : { resilience: config.provider }
+				});
+				const now = /* @__PURE__ */ new Date();
+				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) {
+					const stored = memories.get(memory.id);
+					if (stored) {
+						stored.lastAccessedAt = now;
+						stored.accessCount += 1;
+						stored.updatedAt = now;
+					}
 				}
-			}
-			return scored;
+				return scored;
+			}, (result) => ({ count: result.length }));
 		},
 		async buildContext(input) {
-			assertOpen();
-			return buildContext({
-				input,
-				recall: (contextInput) => this.recall(contextInputToRecallInput(contextInput))
+			return observe(config, "in-memory", "buildContext", { entityId: input.entityId }, async () => {
+				assertOpen();
+				return buildContext({
+					input,
+					recall: (contextInput) => {
+						const recallInput = contextInputToRecallInput(contextInput);
+						return this.recall(input.signal === void 0 ? recallInput : {
+							...recallInput,
+							signal: input.signal
+						});
+					}
+				});
 			});
 		},
 		async forget(input) {
-			assertOpen();
-			assertNonEmptyString(input.entityId, "entityId");
-			assertNonEmptyString(input.memoryId, "memoryId");
-			const memory = memories.get(input.memoryId);
-			if (!memory || memory.entityId !== input.entityId) throw new MnemocyteError("Memory was not found.", "NOT_FOUND");
-			memories.delete(input.memoryId);
+			return observe(config, "in-memory", "forget", {
+				entityId: input.entityId,
+				memoryId: input.memoryId
+			}, async () => {
+				assertOpen();
+				assertNonEmptyString(input.entityId, "entityId");
+				assertNonEmptyString(input.memoryId, "memoryId");
+				const memory = memories.get(input.memoryId);
+				if (!memory || memory.entityId !== input.entityId) throw new MnemocyteError("Memory was not found.", "NOT_FOUND");
+				memories.delete(input.memoryId);
+			});
 		},
 		async forgetAll(input) {
-			assertOpen();
-			assertNonEmptyString(input.entityId, "entityId");
-			for (const [id, memory] of memories) if (memory.entityId === input.entityId) memories.delete(id);
+			return observe(config, "in-memory", "forgetAll", { entityId: input.entityId }, async () => {
+				assertOpen();
+				assertNonEmptyString(input.entityId, "entityId");
+				let deleted = 0;
+				for (const [id, memory] of memories) if (memory.entityId === input.entityId) {
+					memories.delete(id);
+					deleted += 1;
+				}
+				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);
+				return {
+					matchedCount: matched.length,
+					deletedCount: dryRun ? 0 : matched.length,
+					dryRun
+				};
+			}, (result) => ({ count: result.deletedCount }));
 		},
 		async stats(input) {
-			assertOpen();
-			const now = /* @__PURE__ */ new Date();
-			const allMemories = Array.from(memories.values());
-			const selected = input?.entityId ? allMemories.filter((memory) => memory.entityId === input.entityId) : allMemories;
-			const activeMemoryCount = selected.filter((memory) => !isExpired(memory, now) && memory.supersededBy === null).length;
-			const expiredMemoryCount = selected.filter((memory) => isExpired(memory, now)).length;
-			const supersededMemoryCount = selected.filter((memory) => memory.supersededBy !== null).length;
-			if (input?.entityId) return {
-				entityId: input.entityId,
-				memoryCount: selected.length,
-				activeMemoryCount,
-				expiredMemoryCount,
-				supersededMemoryCount
-			};
-			return {
-				entityCount: new Set(allMemories.map((memory) => memory.entityId)).size,
-				memoryCount: selected.length,
-				activeMemoryCount,
-				expiredMemoryCount,
-				supersededMemoryCount
-			};
+			return observe(config, "in-memory", "stats", input?.entityId ? { entityId: input.entityId } : {}, async () => {
+				assertOpen();
+				const now = /* @__PURE__ */ new Date();
+				const allMemories = Array.from(memories.values());
+				const selected = input?.entityId ? allMemories.filter((memory) => memory.entityId === input.entityId) : allMemories;
+				const activeMemoryCount = selected.filter((memory) => !isExpired(memory, now) && memory.supersededBy === null).length;
+				const expiredMemoryCount = selected.filter((memory) => isExpired(memory, now)).length;
+				const supersededMemoryCount = selected.filter((memory) => memory.supersededBy !== null).length;
+				if (input?.entityId) return {
+					entityId: input.entityId,
+					memoryCount: selected.length,
+					activeMemoryCount,
+					expiredMemoryCount,
+					supersededMemoryCount
+				};
+				return {
+					entityCount: new Set(allMemories.map((memory) => memory.entityId)).size,
+					memoryCount: selected.length,
+					activeMemoryCount,
+					expiredMemoryCount,
+					supersededMemoryCount
+				};
+			});
 		},
 		async close() {
-			closed = true;
-			memories.clear();
+			return observe(config, "in-memory", "close", {}, async () => {
+				closed = true;
+				memories.clear();
+			});
 		}
 	};
 }
@@ -502,6 +849,15 @@ 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 markMemoryAccessed(db, memoryIds) {
 	if (memoryIds.length === 0) return;
 	await db.update(memoriesTable).set({
@@ -590,7 +946,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, {
@@ -623,114 +982,211 @@ async function hybridRecall(input) {
 }
 //#endregion
 //#region src/memory/postgres.ts
+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 remember(input) {
-		assertOpen();
-		validateRememberInput(input);
-		const embedding = await embedOne(config.embedder, input.content);
-		const now = /* @__PURE__ */ new Date();
-		return rowToMemory(await insertMemory(handle.db, {
-			id: createId(),
-			entityId: input.entityId,
-			content: input.content,
-			type: input.type ?? "fact",
-			importance: input.importance ?? "normal",
-			tags: normalizeTags(input.tags),
-			source: input.source ?? null,
-			metadata: input.metadata ?? {},
-			confidence: input.confidence ?? 1,
-			embedding,
-			embeddingModel: config.embedder.model,
-			embeddingDimensions: config.embedder.dimensions,
-			supersededBy: null,
-			supersededAt: null,
-			expiresAt: input.expiresAt ?? null,
-			lastAccessedAt: null,
-			accessCount: 0,
-			createdAt: now,
-			updatedAt: now
+		return observe(config, "postgres", "remember", { entityId: input.entityId }, async () => {
+			assertOpen();
+			validateRememberInput(input);
+			const embedding = await embedOne(config.embedder, input.content, {
+				...input.signal === void 0 ? {} : { signal: input.signal },
+				...config.provider === void 0 ? {} : { resilience: config.provider }
+			});
+			const now = /* @__PURE__ */ new Date();
+			return rowToMemory(await insertMemory(handle.db, {
+				id: createId(),
+				entityId: input.entityId,
+				content: input.content,
+				type: input.type ?? "fact",
+				importance: input.importance ?? "normal",
+				tags: normalizeTags(input.tags),
+				source: input.source ?? null,
+				metadata: input.metadata ?? {},
+				confidence: input.confidence ?? 1,
+				embedding,
+				embeddingModel: config.embedder.model,
+				embeddingDimensions: config.embedder.dimensions,
+				supersededBy: null,
+				supersededAt: null,
+				expiresAt: input.expiresAt ?? null,
+				lastAccessedAt: null,
+				accessCount: 0,
+				createdAt: now,
+				updatedAt: now
+			}));
+		}, (memory) => ({
+			memoryId: memory.id,
+			count: 1
 		}));
 	}
 	return {
 		remember,
 		async rememberMany(inputs) {
-			assertOpen();
-			const result = [];
-			for (const input of inputs) result.push(await remember(input));
-			return result;
+			return observe(config, "postgres", "rememberMany", { count: inputs.length }, async () => {
+				assertOpen();
+				const result = [];
+				for (const input of inputs) result.push(await remember(input));
+				return result;
+			}, (result) => ({ count: result.length }));
 		},
 		async recall(input) {
-			assertOpen();
-			validateRecallInput(input);
-			const limit = input.limit ?? config.defaults?.limit ?? 10;
-			const minScore = input.minScore ?? config.defaults?.minScore ?? 0;
-			assertLimit(limit);
-			assertMinScore(minScore);
-			return hybridRecall({
-				db: handle.db,
-				embedder: config.embedder,
-				input,
-				limit,
-				minScore,
-				retrieval: config.retrieval
-			});
+			return observe(config, "postgres", "recall", { entityId: input.entityId }, async () => {
+				assertOpen();
+				validateRecallInput(input);
+				const limit = input.limit ?? config.defaults?.limit ?? 10;
+				const minScore = input.minScore ?? config.defaults?.minScore ?? 0;
+				assertLimit(limit);
+				assertMinScore(minScore);
+				return hybridRecall({
+					db: handle.db,
+					embedder: config.embedder,
+					input,
+					limit,
+					minScore,
+					retrieval: config.retrieval,
+					...input.signal === void 0 ? {} : { signal: input.signal },
+					...config.provider === void 0 ? {} : { resilience: config.provider }
+				});
+			}, (result) => ({ count: result.length }));
 		},
 		async buildContext(input) {
-			assertOpen();
-			return buildContext({
-				input,
-				recall: (contextInput) => this.recall(contextInputToRecallInput(contextInput))
+			return observe(config, "postgres", "buildContext", { entityId: input.entityId }, async () => {
+				assertOpen();
+				return buildContext({
+					input,
+					recall: (contextInput) => {
+						const recallInput = contextInputToRecallInput(contextInput);
+						return this.recall(input.signal === void 0 ? recallInput : {
+							...recallInput,
+							signal: input.signal
+						});
+					}
+				});
 			});
 		},
 		async forget(input) {
-			assertOpen();
-			assertNonEmptyString(input.entityId, "entityId");
-			assertNonEmptyString(input.memoryId, "memoryId");
-			if (!await deleteMemory(handle.db, input.entityId, input.memoryId)) throw new MnemocyteError("Memory was not found.", "NOT_FOUND");
+			return observe(config, "postgres", "forget", {
+				entityId: input.entityId,
+				memoryId: input.memoryId
+			}, async () => {
+				assertOpen();
+				assertNonEmptyString(input.entityId, "entityId");
+				assertNonEmptyString(input.memoryId, "memoryId");
+				if (!await deleteMemory(handle.db, input.entityId, input.memoryId)) throw new MnemocyteError("Memory was not found.", "NOT_FOUND");
+			});
 		},
 		async forgetAll(input) {
-			assertOpen();
-			assertNonEmptyString(input.entityId, "entityId");
-			await Promise.all([deleteMemoriesForEntity(handle.db, input.entityId), deleteEventsForEntity(handle.db, input.entityId)]);
+			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)]);
+			});
+		},
+		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);
+				return {
+					matchedCount: deletedCount,
+					deletedCount,
+					dryRun: false
+				};
+			}, (result) => ({ count: result.deletedCount }));
 		},
 		async stats(input) {
-			assertOpen();
-			const now = /* @__PURE__ */ new Date();
-			if (input?.entityId) {
-				const selected = await listMemories(handle.db, {
-					entityId: input.entityId,
-					includeExpired: true,
-					includeSuperseded: true
-				});
+			return observe(config, "postgres", "stats", input?.entityId ? { entityId: input.entityId } : {}, async () => {
+				assertOpen();
+				const now = /* @__PURE__ */ new Date();
+				if (input?.entityId) {
+					const selected = await listMemories(handle.db, {
+						entityId: input.entityId,
+						includeExpired: true,
+						includeSuperseded: true
+					});
+					return {
+						entityId: input.entityId,
+						memoryCount: selected.length,
+						activeMemoryCount: selected.filter((memory) => !isExpired(rowToMemory(memory), now) && memory.supersededBy === null).length,
+						expiredMemoryCount: selected.filter((memory) => isExpired(rowToMemory(memory), now)).length,
+						supersededMemoryCount: selected.filter((memory) => memory.supersededBy !== null).length
+					};
+				}
+				const allMemories = await handle.db.select().from(memoriesTable);
 				return {
-					entityId: input.entityId,
-					memoryCount: selected.length,
-					activeMemoryCount: selected.filter((memory) => !isExpired(rowToMemory(memory), now) && memory.supersededBy === null).length,
-					expiredMemoryCount: selected.filter((memory) => isExpired(rowToMemory(memory), now)).length,
-					supersededMemoryCount: selected.filter((memory) => memory.supersededBy !== null).length
+					entityCount: new Set(allMemories.map((memory) => memory.entityId)).size,
+					memoryCount: allMemories.length,
+					activeMemoryCount: allMemories.filter((memory) => !isExpired(rowToMemory(memory), now) && memory.supersededBy === null).length,
+					expiredMemoryCount: allMemories.filter((memory) => isExpired(rowToMemory(memory), now)).length,
+					supersededMemoryCount: allMemories.filter((memory) => memory.supersededBy !== null).length
 				};
-			}
-			const allMemories = await handle.db.select().from(memoriesTable);
-			return {
-				entityCount: new Set(allMemories.map((memory) => memory.entityId)).size,
-				memoryCount: allMemories.length,
-				activeMemoryCount: allMemories.filter((memory) => !isExpired(rowToMemory(memory), now) && memory.supersededBy === null).length,
-				expiredMemoryCount: allMemories.filter((memory) => isExpired(rowToMemory(memory), now)).length,
-				supersededMemoryCount: allMemories.filter((memory) => memory.supersededBy !== null).length
-			};
+			});
 		},
 		async close() {
-			closed = true;
-			await handle.close();
+			return observe(config, "postgres", "close", {}, async () => {
+				closed = true;
+				await handle.close();
+			});
 		}
 	};
 }
 //#endregion
 //#region src/client.ts
+/**
+* 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,
+* or `"VALIDATION"` if `databaseUrl` is provided but empty.
+*
+* @example Postgres-backed client
+* ```ts
+* const client = createMnemocyte({
+*   databaseUrl: process.env.DATABASE_URL,
+*   embedder,
+* });
+* ```
+*/
 function createMnemocyte(config) {
 	assertEmbedder(config.embedder);
 	if (config.databaseUrl) {
@@ -740,6 +1196,6 @@ function createMnemocyte(config) {
 	return createInMemoryClient(config);
 }
 //#endregion
-export { MnemocyteError, createMnemocyte };
+export { MnemocyteError, createMnemocyte, isMnemocyteError };
 
 //# sourceMappingURL=index.mjs.map