@nuzo/memory-core 0.1.0

package/dist/service.js

@@ -0,0 +1,455 @@
+import { NuzoMemoryError } from "./errors.js";
+import { memoryKinds } from "./types.js";
+export function createMemoryService(dependencies) {
+    const { auditLog, clock, ids, policy, searchIndex, store, transactions } = dependencies;
+    const runTransaction = transactions
+        ? (operation) => transactions.run(operation)
+        : (operation) => operation();
+    async function forgetMemory(input) {
+        assertActor(input.actor);
+        const memory = await store.findById(input.id);
+        if (!memory) {
+            throw new NuzoMemoryError("MEMORY_NOT_FOUND", "Memory was not found.", { id: input.id });
+        }
+        const mode = input.mode ?? "archive";
+        const now = clock.now();
+        if (mode === "delete") {
+            if (input.confirm !== true) {
+                throw new NuzoMemoryError("MEMORY_DELETE_CONFIRMATION_REQUIRED", "Hard delete requires explicit confirmation.", { id: input.id });
+            }
+            await runTransaction(async () => {
+                await store.delete(input.id);
+                await searchIndex.remove(input.id);
+                await auditLog.append({
+                    id: ids.eventId(),
+                    memoryId: input.id,
+                    eventType: "memory.deleted",
+                    actor: input.actor,
+                    payload: { reason: input.reason ?? null },
+                    createdAt: now,
+                });
+            });
+            return;
+        }
+        await runTransaction(async () => {
+            await store.archive(input.id, now);
+            await searchIndex.remove(input.id);
+            await auditLog.append({
+                id: ids.eventId(),
+                memoryId: input.id,
+                eventType: "memory.archived",
+                actor: input.actor,
+                payload: { reason: input.reason ?? null },
+                createdAt: now,
+            });
+        });
+    }
+    return {
+        async remember(input) {
+            await policy.assertCanRemember(input);
+            const now = clock.now();
+            const memory = {
+                id: ids.memoryId(),
+                scope: input.scope,
+                kind: input.kind,
+                content: input.content.trim(),
+                tags: [...new Set(input.tags ?? [])],
+                source: input.source,
+                confidence: input.confidence ?? 1,
+                createdAt: now,
+                updatedAt: now,
+                lastUsedAt: null,
+                archivedAt: null,
+            };
+            await runTransaction(async () => {
+                await store.create(memory);
+                await searchIndex.index(memory);
+                await auditLog.append({
+                    id: ids.eventId(),
+                    memoryId: memory.id,
+                    eventType: "memory.created",
+                    actor: input.source,
+                    payload: { kind: memory.kind, scope: memory.scope, tags: memory.tags },
+                    createdAt: now,
+                });
+            });
+            return memory;
+        },
+        async recall(input) {
+            await policy.assertCanRecall(input);
+            const results = await searchIndex.search({
+                ...input,
+                limit: input.limit ?? 8,
+            });
+            if (input.recordUsage === false) {
+                return results;
+            }
+            const now = clock.now();
+            await runTransaction(async () => {
+                for (const result of results) {
+                    await store.update({
+                        ...result.memory,
+                        lastUsedAt: now,
+                    });
+                    await auditLog.append({
+                        id: ids.eventId(),
+                        memoryId: result.memory.id,
+                        eventType: "memory.recalled",
+                        actor: "core",
+                        payload: { query: input.query, score: result.score },
+                        createdAt: now,
+                    });
+                }
+            });
+            return results;
+        },
+        async list(input = {}) {
+            await policy.assertCanList(input);
+            return store.list(input);
+        },
+        async update(input) {
+            const current = await store.findById(input.id);
+            if (!current) {
+                throw new NuzoMemoryError("MEMORY_NOT_FOUND", "Memory was not found.", { id: input.id });
+            }
+            const hasChanges = input.content !== undefined ||
+                input.kind !== undefined ||
+                input.scope !== undefined ||
+                input.tags !== undefined ||
+                input.confidence !== undefined;
+            if (!hasChanges) {
+                throw new NuzoMemoryError("MEMORY_UPDATE_EMPTY", "At least one memory field must be updated.", {
+                    id: input.id,
+                });
+            }
+            await policy.assertCanUpdate(input, current);
+            const updated = {
+                ...current,
+                content: input.content?.trim() ?? current.content,
+                kind: input.kind ?? current.kind,
+                scope: input.scope ?? current.scope,
+                tags: input.tags ? [...new Set(input.tags)] : current.tags,
+                confidence: input.confidence ?? current.confidence,
+                updatedAt: clock.now(),
+            };
+            await runTransaction(async () => {
+                await store.update(updated);
+                await searchIndex.index(updated);
+                await auditLog.append({
+                    id: ids.eventId(),
+                    memoryId: updated.id,
+                    eventType: "memory.updated",
+                    actor: input.actor,
+                    payload: {
+                        changed: {
+                            content: input.content !== undefined,
+                            kind: input.kind !== undefined,
+                            scope: input.scope !== undefined,
+                            tags: input.tags !== undefined,
+                            confidence: input.confidence !== undefined,
+                        },
+                    },
+                    createdAt: updated.updatedAt,
+                });
+            });
+            return updated;
+        },
+        async history(memoryId) {
+            if (memoryId.trim().length === 0) {
+                throw new NuzoMemoryError("MEMORY_ID_EMPTY", "Memory ID cannot be empty.");
+            }
+            return auditLog.list(memoryId);
+        },
+        async exportMemories(input) {
+            assertActor(input.actor);
+            await policy.assertCanList(input);
+            const memories = await store.list(input);
+            const now = clock.now();
+            await auditLog.append({
+                id: ids.eventId(),
+                memoryId: null,
+                eventType: "memory.exported",
+                actor: input.actor,
+                payload: {
+                    scope: input.scope ?? null,
+                    tags: input.tags ?? [],
+                    includeArchived: input.includeArchived === true,
+                    count: memories.length,
+                },
+                createdAt: now,
+            });
+            return {
+                format: "nuzo-memory-export",
+                version: 1,
+                exported_at: now.toISOString(),
+                memories: memories.map(toExportItem),
+            };
+        },
+        async importMemories(input) {
+            assertActor(input.actor);
+            assertExportDocument(input.document);
+            const planned = [];
+            const duplicateKeysByScope = new Map();
+            let skipped = 0;
+            for (const item of input.document.memories) {
+                const scope = input.scope ?? item.scope;
+                await policy.assertCanRemember({
+                    content: item.content,
+                    kind: item.kind,
+                    scope,
+                    tags: item.tags,
+                    source: item.source,
+                    confidence: item.confidence,
+                });
+                const tags = [...new Set(item.tags)];
+                let duplicateKeys = duplicateKeysByScope.get(scope);
+                if (!duplicateKeys) {
+                    const existing = await store.list({ scope, includeArchived: true });
+                    duplicateKeys = new Set(existing.map(toImportDuplicateKey));
+                    duplicateKeysByScope.set(scope, duplicateKeys);
+                }
+                const duplicateKey = toImportDuplicateKey({
+                    scope,
+                    kind: item.kind,
+                    content: item.content,
+                    tags,
+                });
+                if (duplicateKeys.has(duplicateKey)) {
+                    skipped += 1;
+                    continue;
+                }
+                duplicateKeys.add(duplicateKey);
+                planned.push({ item, scope, tags });
+            }
+            if (input.dryRun === true) {
+                return {
+                    imported: planned.length,
+                    skipped,
+                    dryRun: true,
+                };
+            }
+            await runTransaction(async () => {
+                for (const { item, scope, tags } of planned) {
+                    const memory = {
+                        id: ids.memoryId(),
+                        scope,
+                        kind: item.kind,
+                        content: item.content.trim(),
+                        tags,
+                        source: item.source,
+                        confidence: item.confidence,
+                        createdAt: parseExportDate(item.created_at, "created_at"),
+                        updatedAt: parseExportDate(item.updated_at, "updated_at"),
+                        lastUsedAt: item.last_used_at ? parseExportDate(item.last_used_at, "last_used_at") : null,
+                        archivedAt: item.archived_at ? parseExportDate(item.archived_at, "archived_at") : null,
+                    };
+                    await store.create(memory);
+                    await searchIndex.index(memory);
+                    await auditLog.append({
+                        id: ids.eventId(),
+                        memoryId: memory.id,
+                        eventType: "memory.imported",
+                        actor: input.actor,
+                        payload: {
+                            originalScope: item.scope,
+                            scope,
+                            archived: memory.archivedAt !== null,
+                        },
+                        createdAt: clock.now(),
+                    });
+                }
+            });
+            return {
+                imported: planned.length,
+                skipped,
+                dryRun: false,
+            };
+        },
+        forget: forgetMemory,
+        async forgetMany(input) {
+            const hasScope = input.scope !== undefined;
+            const hasTags = (input.tags?.length ?? 0) > 0;
+            const selectsAll = input.all === true;
+            if (!selectsAll && !hasScope && !hasTags) {
+                throw new NuzoMemoryError("MEMORY_BULK_SELECTOR_REQUIRED", "Bulk forget requires a scope, at least one tag, or all.");
+            }
+            if (selectsAll && (hasScope || hasTags)) {
+                throw new NuzoMemoryError("MEMORY_BULK_SELECTOR_CONFLICT", "Bulk forget all cannot be combined with scope or tags.");
+            }
+            assertActor(input.actor);
+            await policy.assertCanList({
+                ...(input.scope === undefined ? {} : { scope: input.scope }),
+                ...(input.tags === undefined ? {} : { tags: input.tags }),
+            });
+            const mode = input.mode ?? "archive";
+            const dryRun = input.dryRun !== false;
+            if (!dryRun && mode === "delete" && input.confirm !== true) {
+                throw new NuzoMemoryError("MEMORY_DELETE_CONFIRMATION_REQUIRED", "Hard delete requires explicit confirmation.");
+            }
+            const filter = {};
+            if (input.scope !== undefined) {
+                filter.scope = input.scope;
+            }
+            if (hasTags) {
+                filter.tags = input.tags;
+            }
+            const memories = await store.list(filter);
+            const memoryIds = memories.map((memory) => memory.id);
+            if (!dryRun) {
+                for (const memory of memories) {
+                    const forgetInput = {
+                        id: memory.id,
+                        mode,
+                        actor: input.actor,
+                    };
+                    if (input.confirm !== undefined) {
+                        forgetInput.confirm = input.confirm;
+                    }
+                    if (input.reason !== undefined) {
+                        forgetInput.reason = input.reason;
+                    }
+                    await forgetMemory(forgetInput);
+                }
+            }
+            return {
+                matched: memories.length,
+                affected: dryRun ? 0 : memories.length,
+                mode,
+                dryRun,
+                ids: memoryIds,
+            };
+        },
+    };
+}
+function assertActor(actor) {
+    if (actor.trim().length === 0) {
+        throw new NuzoMemoryError("MEMORY_ACTOR_EMPTY", "Memory actor cannot be empty.");
+    }
+}
+function toExportItem(memory) {
+    return {
+        scope: memory.scope,
+        kind: memory.kind,
+        content: memory.content,
+        tags: [...memory.tags],
+        source: memory.source,
+        confidence: memory.confidence,
+        created_at: memory.createdAt.toISOString(),
+        updated_at: memory.updatedAt.toISOString(),
+        last_used_at: memory.lastUsedAt?.toISOString() ?? null,
+        archived_at: memory.archivedAt?.toISOString() ?? null,
+    };
+}
+function assertExportDocument(document) {
+    const value = document;
+    if (!isRecord(value)) {
+        throw new NuzoMemoryError("MEMORY_EXPORT_INVALID", "Memory export document is invalid.");
+    }
+    if (value.format !== "nuzo-memory-export" || value.version !== 1) {
+        throw new NuzoMemoryError("MEMORY_EXPORT_UNSUPPORTED", "Memory export format is not supported.", {
+            format: value.format,
+            version: value.version,
+        });
+    }
+    parseExportDate(getStringField(value, "exported_at", "document"), "exported_at");
+    if (!Array.isArray(value.memories)) {
+        throw new NuzoMemoryError("MEMORY_EXPORT_INVALID", "Memory export document is invalid.");
+    }
+    value.memories.forEach(assertExportItem);
+}
+function assertExportItem(item, index) {
+    if (!isRecord(item)) {
+        throwInvalidExportItem(index, "item must be an object");
+    }
+    getStringField(item, "scope", `memories[${index}]`);
+    const kind = getStringField(item, "kind", `memories[${index}]`);
+    if (!memoryKinds.includes(kind)) {
+        throwInvalidExportItem(index, "kind is not supported", { kind });
+    }
+    getStringField(item, "content", `memories[${index}]`);
+    getStringArrayField(item, "tags", `memories[${index}]`);
+    getStringField(item, "source", `memories[${index}]`);
+    const confidence = getNumberField(item, "confidence", `memories[${index}]`);
+    if (confidence < 0 || confidence > 1) {
+        throwInvalidExportItem(index, "confidence must be between 0 and 1", {
+            confidence,
+        });
+    }
+    const createdAt = getStringField(item, "created_at", `memories[${index}]`);
+    const updatedAt = getStringField(item, "updated_at", `memories[${index}]`);
+    const lastUsedAt = getNullableStringField(item, "last_used_at", `memories[${index}]`);
+    const archivedAt = getNullableStringField(item, "archived_at", `memories[${index}]`);
+    parseExportDate(createdAt, `memories[${index}].created_at`);
+    parseExportDate(updatedAt, `memories[${index}].updated_at`);
+    if (lastUsedAt !== null) {
+        parseExportDate(lastUsedAt, `memories[${index}].last_used_at`);
+    }
+    if (archivedAt !== null) {
+        parseExportDate(archivedAt, `memories[${index}].archived_at`);
+    }
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function getStringField(record, field, path) {
+    if (typeof record[field] !== "string") {
+        throwInvalidExportField(path, field, "must be a string", { value: record[field] });
+    }
+    return record[field];
+}
+function getNullableStringField(record, field, path) {
+    if (record[field] !== null && typeof record[field] !== "string") {
+        throwInvalidExportField(path, field, "must be a string or null", { value: record[field] });
+    }
+    return record[field];
+}
+function getStringArrayField(record, field, path) {
+    if (!Array.isArray(record[field]) || !record[field].every((value) => typeof value === "string")) {
+        throwInvalidExportField(path, field, "must be an array of strings", { value: record[field] });
+    }
+    return record[field];
+}
+function getNumberField(record, field, path) {
+    if (typeof record[field] !== "number" || !Number.isFinite(record[field])) {
+        throwInvalidExportField(path, field, "must be a finite number", { value: record[field] });
+    }
+    return record[field];
+}
+function throwInvalidExportField(path, field, reason, details = {}) {
+    throw new NuzoMemoryError("MEMORY_EXPORT_INVALID", "Memory export document is invalid.", {
+        path: `${path}.${field}`,
+        reason,
+        ...details,
+    });
+}
+function throwInvalidExportItem(index, reason, details = {}) {
+    throw new NuzoMemoryError("MEMORY_EXPORT_INVALID", "Memory export document is invalid.", {
+        path: `memories[${index}]`,
+        reason,
+        ...details,
+    });
+}
+function parseExportDate(value, field) {
+    const date = new Date(value);
+    if (Number.isNaN(date.getTime())) {
+        throw new NuzoMemoryError("MEMORY_EXPORT_INVALID", "Memory export contains an invalid date.", {
+            field,
+            value,
+        });
+    }
+    return date;
+}
+function toImportDuplicateKey(memory) {
+    return JSON.stringify([
+        memory.scope,
+        memory.kind,
+        normalizeContent(memory.content),
+        normalizeTags(memory.tags),
+    ]);
+}
+function normalizeContent(content) {
+    return content.trim().replace(/\s+/g, " ");
+}
+function normalizeTags(tags) {
+    return [...new Set(tags)].sort();
+}

package/dist/sqlite/adapter.d.ts

@@ -0,0 +1,26 @@
+import Database from "better-sqlite3";
+import type { AuditLog, MemoryStore, SearchIndex, TransactionManager } from "../ports.js";
+import type { ListMemoriesInput, MemoryEvent, MemoryRecord, RecallMemoriesInput, RecallMemoryResult } from "../types.js";
+export interface SQLiteMemoryDatabaseOptions {
+    path: string;
+}
+export declare class SQLiteMemoryDatabase implements MemoryStore, SearchIndex, AuditLog, TransactionManager {
+    readonly database: Database.Database;
+    private transactionQueue;
+    constructor(options: SQLiteMemoryDatabaseOptions);
+    close(): void;
+    getSchemaVersion(): number;
+    run<T>(operation: () => Promise<T>): Promise<T>;
+    create(memory: MemoryRecord): Promise<void>;
+    update(memory: MemoryRecord): Promise<void>;
+    findById(id: string): Promise<MemoryRecord | null>;
+    archive(id: string, archivedAt: Date): Promise<void>;
+    delete(id: string): Promise<void>;
+    index(memory: MemoryRecord): Promise<void>;
+    remove(memoryId: string): Promise<void>;
+    search(input: RecallMemoriesInput): Promise<RecallMemoryResult[]>;
+    append(event: MemoryEvent): Promise<void>;
+    list(filter: ListMemoriesInput): Promise<MemoryRecord[]>;
+    list(memoryId: string): Promise<MemoryEvent[]>;
+    private listMemories;
+}