mnemocyte 0.0.7 → 0.0.8

package/dist/index.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.mts","names":[],"sources":["../src/types.ts","../src/client.ts","../src/errors.ts"],"mappings":"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"}
+{"version":3,"file":"index.d.mts","names":[],"sources":["../src/types.ts","../src/client.ts","../src/errors.ts"],"mappings":"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"}

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,15 @@ 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;
 }
@@ -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");
 }
@@ -272,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];
@@ -307,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;
@@ -427,7 +666,10 @@ function createInMemoryClient(config) {
 		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(),
@@ -474,7 +716,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 +738,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
+						});
+					}
 				});
 			});
 		},
@@ -522,6 +773,22 @@ function createInMemoryClient(config) {
 				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) {
 			return observe(config, "in-memory", "stats", input?.entityId ? { entityId: input.entityId } : {}, async () => {
 				assertOpen();
@@ -582,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({
@@ -670,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, {
@@ -703,6 +982,27 @@ 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() {
@@ -712,7 +1012,10 @@ function createPostgresClient(config, handle) {
 		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, {
 				id: createId(),
@@ -764,7 +1067,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 +1078,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
+						});
+					}
 				});
 			});
 		},
@@ -795,6 +1106,24 @@ function createPostgresClient(config, handle) {
 				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) {
 			return observe(config, "postgres", "stats", input?.entityId ? { entityId: input.entityId } : {}, async () => {
 				assertOpen();
@@ -833,6 +1162,31 @@ function createPostgresClient(config, handle) {
 }
 //#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) {