@membank/core 0.6.1 → 0.8.0

package/dist/index.cjs

@@ -28,6 +28,7 @@ let better_sqlite3 = require("better-sqlite3");
 better_sqlite3 = __toESM(better_sqlite3, 1);
 let sqlite_vec = require("sqlite-vec");
 sqlite_vec = __toESM(sqlite_vec, 1);
+let zod = require("zod");
 let _huggingface_transformers = require("@huggingface/transformers");
 let node_crypto = require("node:crypto");
 let node_child_process = require("node:child_process");
@@ -48,7 +49,8 @@ var DatabaseError = class extends MembankError {
 //#endregion
 //#region src/db/manager.ts
 const DEFAULT_DB_PATH = (0, node_path.join)((0, node_os.homedir)(), ".membank", "memory.db");
-const MIGRATIONS$1 = [[1, `
+const MIGRATIONS$1 = [
+	[1, `
 CREATE TABLE IF NOT EXISTS memories (
   id           TEXT PRIMARY KEY,
   content      TEXT NOT NULL,
@@ -66,7 +68,8 @@ CREATE TABLE IF NOT EXISTS memories (
 CREATE VIRTUAL TABLE IF NOT EXISTS embeddings USING vec0(
   embedding FLOAT[384]
 );
-`], [2, `
+`],
+	[2, `
 CREATE TABLE IF NOT EXISTS projects (
   id         TEXT PRIMARY KEY,
   name       TEXT NOT NULL,
@@ -99,7 +102,25 @@ JOIN projects p ON p.scope_hash = m.scope
 WHERE m.scope != 'global';
 
 ALTER TABLE memories DROP COLUMN scope;
-`]];
+`],
+	[3, `
+CREATE TABLE IF NOT EXISTS memory_review_events (
+  id                        TEXT PRIMARY KEY,
+  memory_id                 TEXT NOT NULL REFERENCES memories(id) ON DELETE CASCADE,
+  conflicting_memory_id     TEXT REFERENCES memories(id) ON DELETE SET NULL,
+  similarity                REAL NOT NULL,
+  conflict_content_snapshot TEXT NOT NULL,
+  reason                    TEXT NOT NULL,
+  created_at                TEXT NOT NULL,
+  resolved_at               TEXT
+);
+
+CREATE INDEX IF NOT EXISTS idx_review_events_memory_open
+  ON memory_review_events(memory_id) WHERE resolved_at IS NULL;
+
+ALTER TABLE memories DROP COLUMN needs_review;
+`]
+];
 var DatabaseManager = class DatabaseManager {
 	#db;
 	constructor(db) {
@@ -156,22 +177,131 @@ var DatabaseManager = class DatabaseManager {
 	}
 };
 //#endregion
+//#region src/schemas.ts
+const MEMORY_TYPE_VALUES = [
+	"correction",
+	"preference",
+	"decision",
+	"learning",
+	"fact"
+];
+const MemoryTypeSchema = zod.z.enum(MEMORY_TYPE_VALUES);
+const TagsJsonSchema = zod.z.array(zod.z.string());
+const ProjectSchema = zod.z.object({
+	id: zod.z.string(),
+	name: zod.z.string(),
+	scopeHash: zod.z.string(),
+	createdAt: zod.z.string(),
+	updatedAt: zod.z.string()
+});
+const ReviewReasonSchema = zod.z.enum(["similarity_dedup"]);
+const ReviewEventSchema = zod.z.object({
+	id: zod.z.string(),
+	memoryId: zod.z.string(),
+	conflictingMemoryId: zod.z.string().nullable(),
+	similarity: zod.z.number(),
+	conflictContentSnapshot: zod.z.string(),
+	reason: ReviewReasonSchema,
+	createdAt: zod.z.string(),
+	resolvedAt: zod.z.string().nullable()
+});
+const ReviewEventRowSchema = zod.z.object({
+	id: zod.z.string(),
+	memory_id: zod.z.string(),
+	conflicting_memory_id: zod.z.string().nullable(),
+	similarity: zod.z.number(),
+	conflict_content_snapshot: zod.z.string(),
+	reason: ReviewReasonSchema,
+	created_at: zod.z.string(),
+	resolved_at: zod.z.string().nullable()
+});
+const MemorySchema = zod.z.object({
+	id: zod.z.string(),
+	content: zod.z.string(),
+	type: MemoryTypeSchema,
+	tags: zod.z.array(zod.z.string()),
+	projects: zod.z.array(ProjectSchema),
+	sourceHarness: zod.z.string().nullable(),
+	accessCount: zod.z.number().int().nonnegative(),
+	pinned: zod.z.boolean(),
+	reviewEvents: zod.z.array(ReviewEventSchema),
+	createdAt: zod.z.string(),
+	updatedAt: zod.z.string()
+});
+const QueryOptionsSchema = zod.z.object({
+	query: zod.z.string().min(1),
+	type: MemoryTypeSchema.optional(),
+	projectHash: zod.z.string().optional(),
+	limit: zod.z.number().int().positive().optional(),
+	includePinned: zod.z.boolean().optional()
+});
+const SaveOptionsSchema = zod.z.object({
+	content: zod.z.string().min(1),
+	type: MemoryTypeSchema,
+	tags: zod.z.array(zod.z.string()).optional(),
+	projectScope: zod.z.object({
+		hash: zod.z.string(),
+		name: zod.z.string()
+	}).optional(),
+	sourceHarness: zod.z.string().optional()
+});
+const MemoryPatchSchema = zod.z.object({
+	content: zod.z.string().min(1).optional(),
+	tags: zod.z.array(zod.z.string()).optional()
+});
+const SessionContextSchema = zod.z.object({
+	stats: zod.z.record(MemoryTypeSchema, zod.z.number()),
+	pinnedGlobal: zod.z.array(MemorySchema),
+	pinnedProject: zod.z.array(MemorySchema)
+});
+const MemoryRowSchema = zod.z.object({
+	id: zod.z.string(),
+	content: zod.z.string(),
+	type: zod.z.string(),
+	tags: zod.z.string(),
+	source: zod.z.string().nullable(),
+	access_count: zod.z.number(),
+	pinned: zod.z.number(),
+	created_at: zod.z.string(),
+	updated_at: zod.z.string()
+});
+const ProjectRowSchema = zod.z.object({
+	id: zod.z.string(),
+	name: zod.z.string(),
+	scope_hash: zod.z.string(),
+	created_at: zod.z.string(),
+	updated_at: zod.z.string()
+});
+//#endregion
 //#region src/db/row-types.ts
-function rowToMemory(row, projects) {
+function rowToMemory(row, projects, reviewEvents = []) {
 	return {
 		id: row.id,
 		content: row.content,
-		type: row.type,
-		tags: JSON.parse(row.tags),
+		type: MemoryTypeSchema.parse(row.type),
+		tags: TagsJsonSchema.parse(JSON.parse(row.tags)),
 		projects,
 		sourceHarness: row.source,
 		accessCount: row.access_count,
 		pinned: row.pinned !== 0,
-		needsReview: row.needs_review !== 0,
+		reviewEvents,
 		createdAt: row.created_at,
 		updatedAt: row.updated_at
 	};
 }
+function rowToReviewEvent(row) {
+	const parsed = ReviewEventRowSchema.parse(row);
+	return {
+		id: parsed.id,
+		memoryId: parsed.memory_id,
+		conflictingMemoryId: parsed.conflicting_memory_id,
+		similarity: parsed.similarity,
+		conflictContentSnapshot: parsed.conflict_content_snapshot,
+		reason: parsed.reason,
+		createdAt: parsed.created_at,
+		resolvedAt: parsed.resolved_at
+	};
+}
 function rowToProject(row) {
 	return {
 		id: row.id,
@@ -207,15 +337,6 @@ var EmbeddingService = class {
 	}
 };
 //#endregion
-//#region src/types.ts
-const MEMORY_TYPE_VALUES = [
-	"correction",
-	"preference",
-	"decision",
-	"learning",
-	"fact"
-];
-//#endregion
 //#region src/memory/repository.ts
 var MemoryRepository = class {
 	#db;
@@ -227,7 +348,7 @@ var MemoryRepository = class {
 		this.#projects = projects;
 	}
 	async save(options) {
-		const { content, type, tags = [], projectScope, sourceHarness } = options;
+		const { content, type, tags = [], projectScope, sourceHarness } = SaveOptionsSchema.parse(options);
 		const embedding = await this.#embedding.embed(content);
 		const embeddingBlob = Buffer.from(embedding.buffer);
 		let top;
@@ -246,41 +367,50 @@ var MemoryRepository = class {
 		if (top !== void 0 && top.similarity > .92) {
 			this.#db.db.prepare(`UPDATE memories SET content = ?, updated_at = ? WHERE id = ?`).run(content, now, top.id);
 			this.#db.db.prepare(`UPDATE embeddings SET embedding = ? WHERE rowid = ?`).run(embeddingBlob, top.rowid);
-			return rowToMemory(this.#db.db.prepare(`SELECT * FROM memories WHERE id = ?`).get(top.id), this.#projects.getProjectsForMemories([top.id]).get(top.id) ?? []);
+			const updated = MemoryRowSchema.parse(this.#db.db.prepare(`SELECT * FROM memories WHERE id = ?`).get(top.id));
+			const projectMap = this.#projects.getProjectsForMemories([top.id]);
+			const events = this.#getEventsForMemories([top.id]);
+			return rowToMemory(updated, projectMap.get(top.id) ?? [], events.get(top.id) ?? []);
 		}
-		if (top !== void 0 && top.similarity >= .75) this.#db.db.prepare(`UPDATE memories SET needs_review = 1 WHERE id = ?`).run(top.id);
 		const id = (0, node_crypto.randomUUID)();
-		this.#db.db.prepare(`INSERT INTO memories (id, content, type, tags, source, access_count, pinned, needs_review, created_at, updated_at)
-         VALUES (?, ?, ?, ?, ?, 0, 0, 0, ?, ?)`).run(id, content, type, JSON.stringify(tags), sourceHarness ?? null, now, now);
+		this.#db.db.prepare(`INSERT INTO memories (id, content, type, tags, source, access_count, pinned, created_at, updated_at)
+         VALUES (?, ?, ?, ?, ?, 0, 0, ?, ?)`).run(id, content, type, JSON.stringify(tags), sourceHarness ?? null, now, now);
+		if (top !== void 0 && top.similarity >= .75) this.#db.db.prepare(`INSERT INTO memory_review_events
+             (id, memory_id, conflicting_memory_id, similarity, conflict_content_snapshot, reason, created_at)
+           VALUES (?, ?, ?, ?, ?, 'similarity_dedup', ?)`).run((0, node_crypto.randomUUID)(), top.id, id, top.similarity, content, now);
 		this.#db.db.prepare(`INSERT INTO embeddings (rowid, embedding) SELECT m.rowid, ? FROM memories m WHERE m.id = ?`).run(embeddingBlob, id);
 		if (projectScope !== void 0) {
 			const project = this.#projects.upsertByHash(projectScope.hash, projectScope.name);
 			this.#projects.addAssociation(id, project.id);
 		}
-		return rowToMemory(this.#db.db.prepare(`SELECT * FROM memories WHERE id = ?`).get(id), this.#projects.getProjectsForMemories([id]).get(id) ?? []);
+		return rowToMemory(MemoryRowSchema.parse(this.#db.db.prepare(`SELECT * FROM memories WHERE id = ?`).get(id)), this.#projects.getProjectsForMemories([id]).get(id) ?? [], []);
 	}
 	async update(id, patch) {
+		const { content, tags } = MemoryPatchSchema.parse(patch);
 		const existing = this.#db.db.prepare(`SELECT m.rowid, m.* FROM memories m WHERE m.id = ?`).get(id);
 		if (existing === void 0) throw new Error(`Memory not found: ${id}`);
 		const now = (/* @__PURE__ */ new Date()).toISOString();
 		const sets = ["updated_at = ?"];
 		const values = [now];
-		if (patch.content !== void 0) {
+		if (content !== void 0) {
 			sets.push("content = ?");
-			values.push(patch.content);
+			values.push(content);
 		}
-		if (patch.tags !== void 0) {
+		if (tags !== void 0) {
 			sets.push("tags = ?");
-			values.push(JSON.stringify(patch.tags));
+			values.push(JSON.stringify(tags));
 		}
 		values.push(id);
 		this.#db.db.prepare(`UPDATE memories SET ${sets.join(", ")} WHERE id = ?`).run(...values);
-		if (patch.content !== void 0) {
-			const embedding = await this.#embedding.embed(patch.content);
+		if (content !== void 0) {
+			const embedding = await this.#embedding.embed(content);
 			const embeddingBlob = Buffer.from(embedding.buffer);
 			this.#db.db.prepare(`UPDATE embeddings SET embedding = ? WHERE rowid = ?`).run(embeddingBlob, existing.rowid);
 		}
-		return rowToMemory(this.#db.db.prepare(`SELECT * FROM memories WHERE id = ?`).get(id), this.#projects.getProjectsForMemories([id]).get(id) ?? []);
+		const updated = MemoryRowSchema.parse(this.#db.db.prepare(`SELECT * FROM memories WHERE id = ?`).get(id));
+		const projectMap = this.#projects.getProjectsForMemories([id]);
+		const events = this.#getEventsForMemories([id]);
+		return rowToMemory(updated, projectMap.get(id) ?? [], events.get(id) ?? []);
 	}
 	delete(id) {
 		const row = this.#db.db.prepare(`SELECT rowid FROM memories WHERE id = ?`).get(id);
@@ -302,27 +432,69 @@ var MemoryRepository = class {
 		if (rows.length === 0) return [];
 		const ids = rows.map((r) => r.id);
 		const projectMap = this.#projects.getProjectsForMemories(ids);
-		return rows.map((row) => rowToMemory(row, projectMap.get(row.id) ?? []));
+		const eventMap = this.#getEventsForMemories(ids);
+		return rows.map((row) => rowToMemory(row, projectMap.get(row.id) ?? [], eventMap.get(row.id) ?? []));
+	}
+	listFlagged() {
+		const rows = this.#db.db.prepare(`SELECT * FROM memories
+         WHERE EXISTS (
+           SELECT 1 FROM memory_review_events e
+           WHERE e.memory_id = memories.id AND e.resolved_at IS NULL
+         )
+         ORDER BY created_at DESC`).all();
+		if (rows.length === 0) return [];
+		const ids = rows.map((r) => r.id);
+		const projectMap = this.#projects.getProjectsForMemories(ids);
+		const eventMap = this.#getEventsForMemories(ids, { unresolvedOnly: true });
+		return rows.map((row) => rowToMemory(row, projectMap.get(row.id) ?? [], eventMap.get(row.id) ?? []));
+	}
+	listReviewEvents(memoryId, opts) {
+		const where = opts?.unresolvedOnly === true ? "WHERE memory_id = ? AND resolved_at IS NULL" : "WHERE memory_id = ?";
+		return this.#db.db.prepare(`SELECT * FROM memory_review_events ${where} ORDER BY created_at DESC`).all(memoryId).map((r) => rowToReviewEvent(ReviewEventRowSchema.parse(r)));
+	}
+	resolveReviewEvents(memoryId) {
+		const now = (/* @__PURE__ */ new Date()).toISOString();
+		this.#db.db.prepare(`UPDATE memory_review_events SET resolved_at = ? WHERE memory_id = ? AND resolved_at IS NULL`).run(now, memoryId);
+	}
+	#getEventsForMemories(ids, opts) {
+		if (ids.length === 0) return /* @__PURE__ */ new Map();
+		const placeholders = ids.map(() => "?").join(", ");
+		const unresolvedClause = opts?.unresolvedOnly === true ? "AND resolved_at IS NULL" : "";
+		const rows = this.#db.db.prepare(`SELECT * FROM memory_review_events
+         WHERE memory_id IN (${placeholders}) ${unresolvedClause}
+         ORDER BY created_at DESC`).all(...ids);
+		const map = /* @__PURE__ */ new Map();
+		for (const row of rows) {
+			const event = rowToReviewEvent(ReviewEventRowSchema.parse(row));
+			const existing = map.get(event.memoryId) ?? [];
+			existing.push(event);
+			map.set(event.memoryId, existing);
+		}
+		return map;
 	}
 	stats() {
 		const byType = Object.fromEntries(MEMORY_TYPE_VALUES.map((t) => [t, 0]));
 		const typeRows = this.#db.db.prepare(`SELECT type, COUNT(*) as count FROM memories GROUP BY type`).all();
-		for (const row of typeRows) if (row.type in byType) byType[row.type] = row.count;
-		const totals = this.#db.db.prepare(`SELECT COUNT(*) as total, SUM(needs_review) as needsReview FROM memories`).get() ?? {
-			total: 0,
-			needsReview: 0
-		};
+		for (const row of typeRows) {
+			const parsed = MemoryTypeSchema.safeParse(row.type);
+			if (parsed.success) byType[parsed.data] = row.count;
+		}
+		const totals = this.#db.db.prepare(`SELECT COUNT(*) as total FROM memories`).get() ?? { total: 0 };
+		const reviewRow = this.#db.db.prepare(`SELECT COUNT(DISTINCT memory_id) as needsReview FROM memory_review_events WHERE resolved_at IS NULL`).get() ?? { needsReview: 0 };
 		return {
 			byType,
 			total: totals.total,
-			needsReview: totals.needsReview ?? 0
+			needsReview: reviewRow.needsReview
 		};
 	}
 	setPin(id, pinned) {
 		if (this.#db.db.prepare(`SELECT * FROM memories WHERE id = ?`).get(id) === void 0) throw new Error(`Memory not found: ${id}`);
 		const now = (/* @__PURE__ */ new Date()).toISOString();
 		this.#db.db.prepare(`UPDATE memories SET pinned = ?, updated_at = ? WHERE id = ?`).run(pinned ? 1 : 0, now, id);
-		return rowToMemory(this.#db.db.prepare(`SELECT * FROM memories WHERE id = ?`).get(id), this.#projects.getProjectsForMemories([id]).get(id) ?? []);
+		const updated = MemoryRowSchema.parse(this.#db.db.prepare(`SELECT * FROM memories WHERE id = ?`).get(id));
+		const projectMap = this.#projects.getProjectsForMemories([id]);
+		const events = this.#getEventsForMemories([id]);
+		return rowToMemory(updated, projectMap.get(id) ?? [], events.get(id) ?? []);
 	}
 	incrementAccessCount(id) {
 		this.#db.db.prepare(`UPDATE memories SET access_count = access_count + 1 WHERE id = ?`).run(id);
@@ -400,7 +572,7 @@ var ProjectRepository = class {
 		const now = (/* @__PURE__ */ new Date()).toISOString();
 		const id = (0, node_crypto.randomUUID)();
 		this.#db.db.prepare(`INSERT OR IGNORE INTO projects (id, name, scope_hash, created_at, updated_at) VALUES (?, ?, ?, ?, ?)`).run(id, name, hash, now, now);
-		return rowToProject(this.#db.db.prepare(`SELECT * FROM projects WHERE scope_hash = ?`).get(hash));
+		return rowToProject(ProjectRowSchema.parse(this.#db.db.prepare(`SELECT * FROM projects WHERE scope_hash = ?`).get(hash)));
 	}
 	rename(id, name) {
 		const now = (/* @__PURE__ */ new Date()).toISOString();
@@ -459,12 +631,13 @@ var QueryEngine = class {
 		this.#repo = repo;
 	}
 	async query(options) {
-		const { query, type, projectHash, limit = 10 } = options;
+		const { query, type, projectHash, limit = 10, includePinned } = QueryOptionsSchema.parse(options);
 		const queryEmbedding = await this.#embedding.embed(query);
 		const queryBlob = Buffer.from(queryEmbedding.buffer);
 		const whereClauses = [];
 		const params = [queryBlob];
 		let joinClause = "";
+		if (!includePinned) whereClauses.push("m.pinned = 0");
 		if (type !== void 0) {
 			whereClauses.push("m.type = ?");
 			params.push(type);
@@ -524,7 +697,10 @@ var SessionContextBuilder = class {
          WHERE p.scope_hash = ? AND m.pinned = 1`).all(projectHash).map((row) => rowToMemory(row, []));
 		const typeCounts = this.#db.db.prepare("SELECT type, COUNT(*) as count FROM memories GROUP BY type").all();
 		const stats = Object.fromEntries(MEMORY_TYPE_VALUES.map((t) => [t, 0]));
-		for (const row of typeCounts) if (stats[row.type] !== void 0) stats[row.type] = row.count;
+		for (const row of typeCounts) {
+			const parsed = MemoryTypeSchema.safeParse(row.type);
+			if (parsed.success) stats[parsed.data] = row.count;
+		}
 		return {
 			stats,
 			pinnedGlobal,
@@ -539,12 +715,26 @@ exports.EmbeddingService = EmbeddingService;
 exports.MEMORY_TYPE_VALUES = MEMORY_TYPE_VALUES;
 exports.MIGRATIONS = MIGRATIONS;
 exports.MembankError = MembankError;
+exports.MemoryPatchSchema = MemoryPatchSchema;
 exports.MemoryRepository = MemoryRepository;
+exports.MemoryRowSchema = MemoryRowSchema;
+exports.MemorySchema = MemorySchema;
+exports.MemoryTypeSchema = MemoryTypeSchema;
 exports.ProjectRepository = ProjectRepository;
+exports.ProjectRowSchema = ProjectRowSchema;
+exports.ProjectSchema = ProjectSchema;
 exports.QueryEngine = QueryEngine;
+exports.QueryOptionsSchema = QueryOptionsSchema;
+exports.ReviewEventRowSchema = ReviewEventRowSchema;
+exports.ReviewEventSchema = ReviewEventSchema;
+exports.ReviewReasonSchema = ReviewReasonSchema;
+exports.SaveOptionsSchema = SaveOptionsSchema;
 exports.SessionContextBuilder = SessionContextBuilder;
+exports.SessionContextSchema = SessionContextSchema;
+exports.TagsJsonSchema = TagsJsonSchema;
 exports.listMemoryTypes = listMemoryTypes;
 exports.resolveProject = resolveProject;
 exports.resolveScope = resolveScope;
 exports.rowToMemory = rowToMemory;
+exports.rowToProject = rowToProject;
 exports.runScopeToProjectsMigration = runScopeToProjectsMigration;