mnemocyte 0.0.8 → 0.1.1

package/dist/index.mjs

@@ -1,6 +1,6 @@
 import { drizzle } from "drizzle-orm/postgres-js";
 import postgres from "postgres";
-import { and, eq, gt, inArray, isNotNull, isNull, lt, or, 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;
@@ -24,12 +24,16 @@ const vector = customType({
 		return `vector(${typeof config === "number" ? config : 1536})`;
 	},
 	toDriver(value) {
-		return `[${value.join(",")}]`;
+		return `[${value.map(formatVectorComponent$1).join(",")}]`;
 	},
 	fromDriver(value) {
 		return value.slice(1, -1).split(",").filter(Boolean).map(Number);
 	}
 });
+function formatVectorComponent$1(value) {
+	if (!Number.isFinite(value)) throw new Error("Vector values must be finite numbers.");
+	return Object.is(value, -0) ? "0" : value.toFixed(17);
+}
 const memoriesTable = pgTable("mnemocyte_memories", {
 	id: text("id").primaryKey(),
 	entityId: text("entity_id").notNull(),
@@ -43,7 +47,7 @@ const memoriesTable = pgTable("mnemocyte_memories", {
 	embedding: vector("embedding", { dimensions: 1536 }),
 	embeddingModel: text("embedding_model").notNull(),
 	embeddingDimensions: integer("embedding_dimensions").notNull(),
-	supersededBy: text("superseded_by"),
+	supersededBy: text("superseded_by").references(() => memoriesTable.id),
 	supersededAt: timestamp("superseded_at", { withTimezone: true }),
 	expiresAt: timestamp("expires_at", { withTimezone: true }),
 	lastAccessedAt: timestamp("last_accessed_at", { withTimezone: true }),
@@ -74,6 +78,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;");
@@ -88,7 +142,11 @@ function formatMetadata(memory) {
 	if (memory.tags.length > 0) parts.push(`tags=${memory.tags.join(",")}`);
 	return parts.join("; ");
 }
-function formatMarkdown(memories, query) {
+function markdownFence(value) {
+	const longestBacktickRun = Math.max(0, ...Array.from(value.matchAll(/`+/g), (match) => match[0].length));
+	return "`".repeat(Math.max(3, longestBacktickRun + 1));
+}
+function formatMarkdown(memories, query, omittedCount) {
 	const lines = [
 		"# Memory Context",
 		"",
@@ -96,10 +154,14 @@ function formatMarkdown(memories, query) {
 		"",
 		"## Relevant Memories"
 	];
-	for (const memory of memories) lines.push("", `- ${memory.content}`, `  - ${formatMetadata(memory)}`);
+	for (const memory of memories) {
+		const fence = markdownFence(memory.content);
+		lines.push("", `- ${formatMetadata(memory)}`, `  ${fence}text`, ...memory.content.split("\n").map((line) => `  ${line}`), `  ${fence}`);
+	}
+	if (omittedCount > 0) lines.push("", `[${omittedCount} memories omitted to fit token budget]`);
 	return lines.join("\n");
 }
-function formatPlain(memories, query) {
+function formatPlain(memories, query, omittedCount) {
 	const lines = [
 		"MEMORY CONTEXT",
 		"",
@@ -107,20 +169,22 @@ function formatPlain(memories, query) {
 		"",
 		"RELEVANT MEMORIES"
 	];
-	for (const memory of memories) lines.push("", memory.content, formatMetadata(memory));
+	for (const [index, memory] of memories.entries()) lines.push("", `--- MEMORY ${index + 1} START ---`, formatMetadata(memory), memory.content, `--- MEMORY ${index + 1} END ---`);
+	if (omittedCount > 0) lines.push("", `[${omittedCount} memories omitted to fit token budget]`);
 	return lines.join("\n");
 }
-function formatXml(memories, query) {
+function formatXml(memories, query, omittedCount) {
 	const lines = [`<memory_context query="${escapeXml(query)}">`];
 	for (const memory of memories) lines.push(`  <memory id="${escapeXml(memory.id)}" type="${escapeXml(memory.type)}" importance="${escapeXml(memory.importance)}" score="${memory.score.toFixed(3)}">`, `    <content>${escapeXml(memory.content)}</content>`, `    <metadata>${escapeXml(formatMetadata(memory))}</metadata>`, "  </memory>");
+	if (omittedCount > 0) lines.push(`  <omitted count="${omittedCount}" reason="token_budget" />`);
 	lines.push("</memory_context>");
 	return lines.join("\n");
 }
-function formatContext(memories, query, format) {
+function formatContext(memories, query, format, omittedCount = 0) {
 	switch (format) {
-		case "markdown": return formatMarkdown(memories, query);
-		case "plain": return formatPlain(memories, query);
-		case "xml": return formatXml(memories, query);
+		case "markdown": return formatMarkdown(memories, query, omittedCount);
+		case "plain": return formatPlain(memories, query, omittedCount);
+		case "xml": return formatXml(memories, query, omittedCount);
 	}
 }
 //#endregion
@@ -149,57 +213,13 @@ async function buildContext(options) {
 	const format = options.input.format ?? "markdown";
 	const maxTokens = options.input.maxTokens ?? 1200;
 	const tokenCounter = options.input.tokenCounter ?? heuristicTokenCounter;
-	return trimToTokenBudget(formatContext(await options.recall(options.input), options.input.query, format), maxTokens, tokenCounter);
-}
-//#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;
+	const memories = await options.recall(options.input);
+	for (let count = memories.length; count >= 0; count -= 1) {
+		const omittedCount = memories.length - count;
+		const context = formatContext(memories.slice(0, count), options.input.query, format, omittedCount);
+		if (tokenCounter.count(context) <= maxTokens) return context;
 	}
-};
-/**
-* 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;
+	return trimToTokenBudget(formatContext([], options.input.query, format, memories.length), maxTokens, tokenCounter);
 }
 //#endregion
 //#region src/observability.ts
@@ -442,6 +462,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();
 }
@@ -450,6 +474,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),
@@ -470,6 +495,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,
@@ -546,6 +572,49 @@ function matchesPruneFilter(memory, input, now) {
 	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;
@@ -658,10 +727,30 @@ 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();
@@ -684,6 +773,7 @@ function createInMemoryClient(config) {
 				embeddingModel: config.embedder.model,
 				embeddingDimensions: config.embedder.dimensions,
 				supersededBy: null,
+				supersededAt: null,
 				expiresAt: input.expiresAt ?? null,
 				lastAccessedAt: null,
 				accessCount: 0,
@@ -692,6 +782,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,
@@ -759,6 +854,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) {
@@ -770,6 +866,7 @@ function createInMemoryClient(config) {
 					memories.delete(id);
 					deleted += 1;
 				}
+				recordAudit(input.entityId, "entity.cleared", { count: deleted });
 				return deleted;
 			}, (count) => ({ count })).then(() => void 0);
 		},
@@ -781,7 +878,10 @@ function createInMemoryClient(config) {
 				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 (!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,
@@ -789,6 +889,53 @@ function createInMemoryClient(config) {
 				};
 			}, (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();
@@ -814,6 +961,7 @@ function createInMemoryClient(config) {
 				};
 			});
 		},
+		experimental: createExperimental(),
 		async close() {
 			return observe(config, "in-memory", "close", {}, async () => {
 				closed = true;
@@ -821,25 +969,83 @@ 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
 function vectorLiteral(embedding) {
-	return `[${embedding.join(",")}]`;
+	return `[${embedding.map(formatVectorComponent).join(",")}]`;
+}
+function formatVectorComponent(value) {
+	if (!Number.isFinite(value)) throw new Error("Vector values must be finite numbers.");
+	return Object.is(value, -0) ? "0" : value.toFixed(17);
 }
 function filterConditions(filter) {
-	return and(eq(memoriesTable.entityId, filter.entityId), filter.includeSuperseded ? void 0 : isNull(memoriesTable.supersededBy), filter.includeExpired ? void 0 : sql`(${memoriesTable.expiresAt} IS NULL OR ${memoriesTable.expiresAt} > now())`, 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.before ? lt(memoriesTable.createdAt, filter.before) : void 0, filter.after ? gt(memoriesTable.createdAt, filter.after) : void 0);
+	return and(eq(memoriesTable.entityId, filter.entityId), filter.includeSuperseded ? void 0 : isNull(memoriesTable.supersededBy), filter.includeExpired ? void 0 : sql`(${memoriesTable.expiresAt} IS NULL OR ${memoriesTable.expiresAt} > now())`, 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.before ? lt(memoriesTable.createdAt, filter.before) : void 0, filter.after ? gt(memoriesTable.createdAt, filter.after) : void 0);
 }
 async function insertMemory(db, row) {
 	const inserted = (await db.insert(memoriesTable).values(row).returning())[0];
 	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));
 }
@@ -858,6 +1064,136 @@ async function countPruneMatches(db, filter) {
 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({
@@ -898,7 +1234,7 @@ async function vectorSearch(db, input) {
 			${input.includeSuperseded ? sql`` : sql`AND superseded_by IS NULL`}
 			${input.includeExpired ? sql`` : sql`AND (expires_at IS NULL OR expires_at > now())`}
 			${input.types && input.types.length > 0 ? sql`AND type IN (${sql.join(input.types.map((type) => sql`${type}`), sql`, `)})` : sql``}
-			${input.tags && input.tags.length > 0 ? sql`AND tags && ${input.tags}` : sql``}
+			${input.tags && input.tags.length > 0 ? sql`AND tags @> ${input.tags}` : sql``}
 			${input.before ? sql`AND created_at < ${input.before}` : sql``}
 			${input.after ? sql`AND created_at > ${input.after}` : sql``}
 			AND 1 - (embedding <=> ${embedding}::vector) >= ${minScore}
@@ -935,7 +1271,7 @@ async function lexicalSearch(db, input) {
 			${input.includeSuperseded ? sql`` : sql`AND superseded_by IS NULL`}
 			${input.includeExpired ? sql`` : sql`AND (expires_at IS NULL OR expires_at > now())`}
 			${input.types && input.types.length > 0 ? sql`AND type IN (${sql.join(input.types.map((type) => sql`${type}`), sql`, `)})` : sql``}
-			${input.tags && input.tags.length > 0 ? sql`AND tags && ${input.tags}` : sql``}
+			${input.tags && input.tags.length > 0 ? sql`AND tags @> ${input.tags}` : sql``}
 			${input.before ? sql`AND created_at < ${input.before}` : sql``}
 			${input.after ? sql`AND created_at > ${input.after}` : sql``}
 			AND to_tsvector('english', content) @@ websearch_to_tsquery('english', ${input.query})
@@ -982,6 +1318,15 @@ 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",
@@ -1008,6 +1353,18 @@ function createPostgresClient(config, handle) {
 	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();
@@ -1017,7 +1374,7 @@ function createPostgresClient(config, handle) {
 				...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,
@@ -1038,6 +1395,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
@@ -1097,14 +1460,17 @@ 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 () => {
@@ -1117,6 +1483,7 @@ function createPostgresClient(config, handle) {
 					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,
@@ -1124,6 +1491,39 @@ function createPostgresClient(config, handle) {
 				};
 			}, (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 () => {
 				assertOpen();
@@ -1152,6 +1552,7 @@ function createPostgresClient(config, handle) {
 				};
 			});
 		},
+		experimental: createExperimental(),
 		async close() {
 			return observe(config, "postgres", "close", {}, async () => {
 				closed = true;
@@ -1159,9 +1560,61 @@ 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.
 *
@@ -1176,14 +1629,16 @@ function createPostgresClient(config, handle) {
 *
 * @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.
+* @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, // embedder.dimensions MUST be 1536 for the Postgres backend
 * });
 * ```
 */
@@ -1191,6 +1646,7 @@ 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);