@nuzo/memory-core 0.1.0 → 0.1.1

package/dist/policy.d.ts

@@ -1,12 +1,33 @@
 import type { PolicyEngine, SecretScanner } from "./ports.js";
+import { type MemoryScope } from "./types.js";
 import type { ListMemoriesInput, MemoryRecord, RecallMemoriesInput, RememberMemoryInput, UpdateMemoryInput } from "./types.js";
 export declare const memoryScopePattern: RegExp;
 export declare const memoryTagPattern: RegExp;
+export declare const memoryLimits: {
+    readonly actorLength: 256;
+    readonly contentLength: 8000;
+    readonly dateLength: 64;
+    readonly identifierLength: 256;
+    readonly importItems: 1000;
+    readonly queryLength: 2000;
+    readonly reasonLength: 1000;
+    readonly scopeLength: 256;
+    readonly sourceLength: 256;
+    readonly tags: 32;
+};
+export interface DefaultPolicyEngineOptions {
+    allowedScopes?: readonly MemoryScope[];
+}
 export declare class DefaultPolicyEngine implements PolicyEngine {
     private readonly secretScanner;
-    constructor(secretScanner: SecretScanner);
+    private readonly allowedScopes;
+    constructor(secretScanner: SecretScanner, options?: DefaultPolicyEngineOptions);
     assertCanRemember(input: RememberMemoryInput): Promise<void>;
     assertCanUpdate(input: UpdateMemoryInput, current: MemoryRecord): Promise<void>;
+    assertCanForget(_input: {
+        id: string;
+    }, current: MemoryRecord): Promise<void>;
     assertCanRecall(input: RecallMemoriesInput): Promise<void>;
     assertCanList(input: ListMemoriesInput): Promise<void>;
+    private assertScopeAllowed;
 }

package/dist/policy.js

@@ -1,21 +1,41 @@
-import { invariant } from "./errors.js";
+import { invariant, NuzoMemoryError } from "./errors.js";
 import { memoryKinds } from "./types.js";
 export const memoryScopePattern = /^(user|project|agent|team):[A-Za-z0-9._~:/-]+$/;
 export const memoryTagPattern = /^[a-z0-9][a-z0-9._-]{0,63}$/;
+export const memoryLimits = {
+    actorLength: 256,
+    contentLength: 8000,
+    dateLength: 64,
+    identifierLength: 256,
+    importItems: 1000,
+    queryLength: 2000,
+    reasonLength: 1000,
+    scopeLength: 256,
+    sourceLength: 256,
+    tags: 32,
+};
 export class DefaultPolicyEngine {
     secretScanner;
-    constructor(secretScanner) {
+    allowedScopes;
+    constructor(secretScanner, options = {}) {
         this.secretScanner = secretScanner;
+        this.allowedScopes = options.allowedScopes === undefined
+            ? null
+            : new Set(options.allowedScopes);
     }
     async assertCanRemember(input) {
         invariant(input.content.trim().length > 0, "MEMORY_CONTENT_EMPTY", "Memory content cannot be empty.");
-        invariant(input.content.length <= 8000, "MEMORY_CONTENT_TOO_LONG", "Memory content is too long.", { maxLength: 8000 });
+        invariant(input.content.length <= memoryLimits.contentLength, "MEMORY_CONTENT_TOO_LONG", "Memory content is too long.", { maxLength: memoryLimits.contentLength });
         invariant(memoryKinds.includes(input.kind), "MEMORY_KIND_UNSUPPORTED", "Memory kind is not supported.", { kind: input.kind });
         assertScope(input.scope);
+        this.assertScopeAllowed(input.scope);
         invariant(input.source.trim().length > 0, "MEMORY_SOURCE_EMPTY", "Memory source cannot be empty.");
+        invariant(input.source.length <= memoryLimits.sourceLength, "MEMORY_SOURCE_TOO_LONG", "Memory source is too long.", { maxLength: memoryLimits.sourceLength });
         const confidence = input.confidence ?? 1;
         invariant(confidence >= 0 && confidence <= 1, "MEMORY_CONFIDENCE_INVALID", "Memory confidence must be between 0 and 1.", { confidence });
-        for (const tag of input.tags ?? []) {
+        const tags = input.tags ?? [];
+        invariant(tags.length <= memoryLimits.tags, "MEMORY_TAG_LIMIT_EXCEEDED", "Memory has too many tags.", { maxTags: memoryLimits.tags });
+        for (const tag of tags) {
             assertTag(tag);
         }
         const secretScan = await this.secretScanner.scan(input.content);
@@ -24,6 +44,7 @@ export class DefaultPolicyEngine {
         });
     }
     async assertCanUpdate(input, current) {
+        this.assertScopeAllowed(current.scope);
         await this.assertCanRemember({
             content: input.content ?? current.content,
             kind: input.kind ?? current.kind,
@@ -34,9 +55,17 @@ export class DefaultPolicyEngine {
         });
         invariant(input.actor.trim().length > 0, "MEMORY_ACTOR_EMPTY", "Memory actor cannot be empty.");
     }
+    async assertCanForget(_input, current) {
+        this.assertScopeAllowed(current.scope);
+    }
     async assertCanRecall(input) {
         invariant(input.query.trim().length > 0, "RECALL_QUERY_EMPTY", "Recall query cannot be empty.");
+        invariant(input.query.length <= memoryLimits.queryLength, "RECALL_QUERY_TOO_LONG", "Recall query is too long.", { maxLength: memoryLimits.queryLength });
         assertScope(input.scope);
+        this.assertScopeAllowed(input.scope);
+        if (input.includeGlobal === true) {
+            this.assertScopeAllowed("user:default");
+        }
         const limit = input.limit ?? 8;
         invariant(limit > 0 && limit <= 50, "RECALL_LIMIT_INVALID", "Recall limit must be 1-50.", {
             limit,
@@ -45,16 +74,30 @@ export class DefaultPolicyEngine {
     async assertCanList(input) {
         if (input.scope !== undefined) {
             assertScope(input.scope);
+            this.assertScopeAllowed(input.scope);
         }
-        for (const tag of input.tags ?? []) {
+        else if (this.allowedScopes !== null) {
+            throw new NuzoMemoryError("MEMORY_SCOPE_REQUIRED", "A scope is required for this restricted memory session.");
+        }
+        const tags = input.tags ?? [];
+        invariant(tags.length <= memoryLimits.tags, "MEMORY_TAG_LIMIT_EXCEEDED", "Memory filter has too many tags.", { maxTags: memoryLimits.tags });
+        for (const tag of tags) {
             assertTag(tag);
         }
     }
+    assertScopeAllowed(scope) {
+        if (this.allowedScopes === null) {
+            return;
+        }
+        if (!this.allowedScopes.has(scope)) {
+            throw new NuzoMemoryError("MEMORY_SCOPE_FORBIDDEN", "Memory scope is not authorized.", {
+                scope,
+            });
+        }
+    }
 }
 function assertScope(scope) {
-    invariant(memoryScopePattern.test(scope), "MEMORY_SCOPE_INVALID", "Memory scope is invalid.", {
-        scope,
-    });
+    invariant(scope.length <= memoryLimits.scopeLength && memoryScopePattern.test(scope), "MEMORY_SCOPE_INVALID", "Memory scope is invalid.", { scope, maxLength: memoryLimits.scopeLength });
 }
 function assertTag(tag) {
     invariant(memoryTagPattern.test(tag), "MEMORY_TAG_INVALID", "Memory tag is invalid.", {

package/dist/ports.d.ts

@@ -1,11 +1,11 @@
 import type { ListMemoriesInput, MemoryEvent, MemoryRecord, RecallMemoriesInput, RecallMemoryResult, RememberMemoryInput, UpdateMemoryInput } from "./types.js";
 export interface MemoryStore {
     create(memory: MemoryRecord): Promise<void>;
-    update(memory: MemoryRecord): Promise<void>;
+    update(memory: MemoryRecord, expectedRevision?: number): Promise<boolean>;
     findById(id: string): Promise<MemoryRecord | null>;
     list(filter: ListMemoriesInput): Promise<MemoryRecord[]>;
-    archive(id: string, archivedAt: Date): Promise<void>;
-    delete(id: string): Promise<void>;
+    archive(id: string, archivedAt: Date, expectedRevision?: number): Promise<boolean>;
+    delete(id: string, expectedRevision?: number): Promise<boolean>;
 }
 export interface SearchIndex {
     index(memory: MemoryRecord): Promise<void>;
@@ -40,6 +40,9 @@ export interface SecretFinding {
 export interface PolicyEngine {
     assertCanRemember(input: RememberMemoryInput): Promise<void>;
     assertCanUpdate(input: UpdateMemoryInput, current: MemoryRecord): Promise<void>;
+    assertCanForget(input: {
+        id: string;
+    }, current: MemoryRecord): Promise<void>;
     assertCanRecall(input: RecallMemoriesInput): Promise<void>;
     assertCanList(input: ListMemoriesInput): Promise<void>;
 }

package/dist/secrets.js

@@ -9,6 +9,11 @@ const patterns = [
         regex: /\b(?:ghp|gho|ghu|ghs|ghr)_[A-Za-z0-9_]{20,}\b/,
         message: "GitHub tokens should not be stored as memory.",
     },
+    {
+        kind: "npm_token",
+        regex: /\bnpm_[A-Za-z0-9]{20,}\b/,
+        message: "npm access tokens should not be stored as memory.",
+    },
     {
         kind: "provider_api_key",
         regex: /\b(?:sk-(?:proj-|ant-[A-Za-z0-9-]+-)?[A-Za-z0-9_-]{20,}|sk_live_[A-Za-z0-9]{20,}|AIza[A-Za-z0-9_-]{30,})\b/,

package/dist/service.d.ts

@@ -1,5 +1,5 @@
 import type { AuditLog, Clock, IdGenerator, MemoryStore, PolicyEngine, SearchIndex, TransactionManager } from "./ports.js";
-import type { ExportMemoriesInput, ForgetMemoryInput, ForgetMemoriesInput, ForgetMemoriesResult, ImportMemoriesInput, ImportMemoriesResult, ListMemoriesInput, MemoryExportDocument, MemoryEvent, MemoryRecord, RecallMemoriesInput, RecallMemoryResult, RememberMemoryInput, UpdateMemoryInput } from "./types.js";
+import type { CaptureSuggestionResult, ExportMemoriesInput, ForgetMemoryInput, ForgetMemoriesInput, ForgetMemoriesResult, ImportMemoriesInput, ImportMemoriesResult, ListMemoriesInput, MemoryExportDocument, MemoryEvent, MemoryRecord, RecallMemoriesInput, RecallMemoryResult, RememberMemoryInput, SuggestCaptureInput, UpdateMemoryInput } from "./types.js";
 export interface MemoryServiceDependencies {
     store: MemoryStore;
     searchIndex: SearchIndex;
@@ -10,6 +10,7 @@ export interface MemoryServiceDependencies {
     transactions?: TransactionManager;
 }
 export interface MemoryService {
+    suggestCapture(input: SuggestCaptureInput): Promise<CaptureSuggestionResult>;
     remember(input: RememberMemoryInput): Promise<MemoryRecord>;
     recall(input: RecallMemoriesInput): Promise<RecallMemoryResult[]>;
     list(input?: ListMemoriesInput): Promise<MemoryRecord[]>;

package/dist/service.js

@@ -1,4 +1,5 @@
 import { NuzoMemoryError } from "./errors.js";
+import { memoryLimits } from "./policy.js";
 import { memoryKinds } from "./types.js";
 export function createMemoryService(dependencies) {
     const { auditLog, clock, ids, policy, searchIndex, store, transactions } = dependencies;
@@ -6,11 +7,15 @@ export function createMemoryService(dependencies) {
         ? (operation) => transactions.run(operation)
         : (operation) => operation();
     async function forgetMemory(input) {
+        assertMemoryId(input.id);
         assertActor(input.actor);
+        assertReason(input.reason);
         const memory = await store.findById(input.id);
         if (!memory) {
             throw new NuzoMemoryError("MEMORY_NOT_FOUND", "Memory was not found.", { id: input.id });
         }
+        assertExpectedRevision(input.expectedRevision, memory);
+        await policy.assertCanForget(input, memory);
         const mode = input.mode ?? "archive";
         const now = clock.now();
         if (mode === "delete") {
@@ -18,7 +23,8 @@ export function createMemoryService(dependencies) {
                 throw new NuzoMemoryError("MEMORY_DELETE_CONFIRMATION_REQUIRED", "Hard delete requires explicit confirmation.", { id: input.id });
             }
             await runTransaction(async () => {
-                await store.delete(input.id);
+                const deleted = await store.delete(input.id, memory.revision);
+                assertRevisionCommitted(deleted, input.id, memory.revision);
                 await searchIndex.remove(input.id);
                 await auditLog.append({
                     id: ids.eventId(),
@@ -32,7 +38,8 @@ export function createMemoryService(dependencies) {
             return;
         }
         await runTransaction(async () => {
-            await store.archive(input.id, now);
+            const archived = await store.archive(input.id, now, memory.revision);
+            assertRevisionCommitted(archived, input.id, memory.revision);
             await searchIndex.remove(input.id);
             await auditLog.append({
                 id: ids.eventId(),
@@ -45,11 +52,36 @@ export function createMemoryService(dependencies) {
         });
     }
     return {
+        async suggestCapture(input) {
+            assertCaptureReason(input.reason);
+            await policy.assertCanRemember(input);
+            const draft = {
+                content: input.content.trim(),
+                kind: input.kind,
+                scope: input.scope,
+                tags: [...new Set(input.tags ?? [])],
+                source: input.source,
+                confidence: input.confidence ?? 1,
+                reason: input.reason.trim(),
+            };
+            const duplicateKey = toCaptureDuplicateKey(draft.content);
+            const memories = await store.list({ scope: draft.scope });
+            const duplicate = memories.find((memory) => (memory.archivedAt === null &&
+                toCaptureDuplicateKey(memory.content) === duplicateKey)) ?? null;
+            return {
+                status: duplicate ? "duplicate" : "ready",
+                memoryWrites: false,
+                requiresConfirmation: true,
+                draft,
+                duplicate,
+            };
+        },
         async remember(input) {
             await policy.assertCanRemember(input);
             const now = clock.now();
             const memory = {
                 id: ids.memoryId(),
+                revision: 1,
                 scope: input.scope,
                 kind: input.kind,
                 content: input.content.trim(),
@@ -81,19 +113,26 @@ export function createMemoryService(dependencies) {
                 ...input,
                 limit: input.limit ?? 8,
             });
-            if (input.recordUsage === false) {
+            if (input.recordUsage !== true) {
                 return results;
             }
             const now = clock.now();
             await runTransaction(async () => {
                 for (const result of results) {
-                    await store.update({
-                        ...result.memory,
+                    const current = await store.findById(result.memory.id);
+                    if (!current || current.archivedAt !== null) {
+                        continue;
+                    }
+                    const updated = {
+                        ...current,
+                        revision: current.revision + 1,
                         lastUsedAt: now,
-                    });
+                    };
+                    const committed = await store.update(updated, current.revision);
+                    assertRevisionCommitted(committed, current.id, current.revision);
                     await auditLog.append({
                         id: ids.eventId(),
-                        memoryId: result.memory.id,
+                        memoryId: current.id,
                         eventType: "memory.recalled",
                         actor: "core",
                         payload: { query: input.query, score: result.score },
@@ -108,10 +147,12 @@ export function createMemoryService(dependencies) {
             return store.list(input);
         },
         async update(input) {
+            assertMemoryId(input.id);
             const current = await store.findById(input.id);
             if (!current) {
                 throw new NuzoMemoryError("MEMORY_NOT_FOUND", "Memory was not found.", { id: input.id });
             }
+            assertExpectedRevision(input.expectedRevision, current);
             const hasChanges = input.content !== undefined ||
                 input.kind !== undefined ||
                 input.scope !== undefined ||
@@ -125,6 +166,7 @@ export function createMemoryService(dependencies) {
             await policy.assertCanUpdate(input, current);
             const updated = {
                 ...current,
+                revision: current.revision + 1,
                 content: input.content?.trim() ?? current.content,
                 kind: input.kind ?? current.kind,
                 scope: input.scope ?? current.scope,
@@ -133,7 +175,8 @@ export function createMemoryService(dependencies) {
                 updatedAt: clock.now(),
             };
             await runTransaction(async () => {
-                await store.update(updated);
+                const committed = await store.update(updated, current.revision);
+                assertRevisionCommitted(committed, input.id, current.revision);
                 await searchIndex.index(updated);
                 await auditLog.append({
                     id: ids.eventId(),
@@ -155,9 +198,7 @@ export function createMemoryService(dependencies) {
             return updated;
         },
         async history(memoryId) {
-            if (memoryId.trim().length === 0) {
-                throw new NuzoMemoryError("MEMORY_ID_EMPTY", "Memory ID cannot be empty.");
-            }
+            assertMemoryId(memoryId);
             return auditLog.list(memoryId);
         },
         async exportMemories(input) {
@@ -188,9 +229,6 @@ export function createMemoryService(dependencies) {
         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({
@@ -201,37 +239,53 @@ export function createMemoryService(dependencies) {
                     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 });
             }
+            const planImport = async () => {
+                const planned = [];
+                const duplicateKeysByScope = new Map();
+                let skipped = 0;
+                for (const item of input.document.memories) {
+                    const scope = input.scope ?? item.scope;
+                    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 });
+                }
+                return { planned, skipped };
+            };
             if (input.dryRun === true) {
+                const { planned, skipped } = await planImport();
                 return {
                     imported: planned.length,
                     skipped,
                     dryRun: true,
                 };
             }
+            let imported = 0;
+            let skipped = 0;
             await runTransaction(async () => {
-                for (const { item, scope, tags } of planned) {
+                const plan = await planImport();
+                imported = plan.planned.length;
+                skipped = plan.skipped;
+                for (const { item, scope, tags } of plan.planned) {
                     const memory = {
                         id: ids.memoryId(),
+                        revision: 1,
                         scope,
                         kind: item.kind,
                         content: item.content.trim(),
@@ -260,7 +314,7 @@ export function createMemoryService(dependencies) {
                 }
             });
             return {
-                imported: planned.length,
+                imported,
                 skipped,
                 dryRun: false,
             };
@@ -277,6 +331,7 @@ export function createMemoryService(dependencies) {
                 throw new NuzoMemoryError("MEMORY_BULK_SELECTOR_CONFLICT", "Bulk forget all cannot be combined with scope or tags.");
             }
             assertActor(input.actor);
+            assertReason(input.reason);
             await policy.assertCanList({
                 ...(input.scope === undefined ? {} : { scope: input.scope }),
                 ...(input.tags === undefined ? {} : { tags: input.tags }),
@@ -299,6 +354,7 @@ export function createMemoryService(dependencies) {
                 for (const memory of memories) {
                     const forgetInput = {
                         id: memory.id,
+                        expectedRevision: memory.revision,
                         mode,
                         actor: input.actor,
                     };
@@ -321,10 +377,63 @@ export function createMemoryService(dependencies) {
         },
     };
 }
+function assertExpectedRevision(expectedRevision, memory) {
+    if (expectedRevision === undefined) {
+        return;
+    }
+    if (!Number.isInteger(expectedRevision) || expectedRevision < 1) {
+        throw new NuzoMemoryError("MEMORY_REVISION_INVALID", "Memory revision is invalid.", {
+            expectedRevision,
+        });
+    }
+    if (memory.revision !== expectedRevision) {
+        throw new NuzoMemoryError("MEMORY_REVISION_CONFLICT", "Memory changed before this operation could commit.", {
+            id: memory.id,
+            expectedRevision,
+            currentRevision: memory.revision,
+        });
+    }
+}
+function assertRevisionCommitted(committed, id, expectedRevision) {
+    if (!committed) {
+        throw new NuzoMemoryError("MEMORY_REVISION_CONFLICT", "Memory changed before this operation could commit.", {
+            id,
+            expectedRevision,
+        });
+    }
+}
 function assertActor(actor) {
     if (actor.trim().length === 0) {
         throw new NuzoMemoryError("MEMORY_ACTOR_EMPTY", "Memory actor cannot be empty.");
     }
+    if (actor.length > memoryLimits.actorLength) {
+        throw new NuzoMemoryError("MEMORY_ACTOR_INVALID", "Memory actor is too long.", {
+            maxLength: memoryLimits.actorLength,
+        });
+    }
+}
+function assertMemoryId(memoryId) {
+    if (memoryId.trim().length === 0) {
+        throw new NuzoMemoryError("MEMORY_ID_EMPTY", "Memory ID cannot be empty.");
+    }
+    if (memoryId.length > memoryLimits.identifierLength) {
+        throw new NuzoMemoryError("MEMORY_ID_INVALID", "Memory ID is too long.", {
+            maxLength: memoryLimits.identifierLength,
+        });
+    }
+}
+function assertReason(reason) {
+    if (reason !== undefined && reason.length > memoryLimits.reasonLength) {
+        throw new NuzoMemoryError("MEMORY_REASON_TOO_LONG", "Memory reason is too long.", {
+            maxLength: memoryLimits.reasonLength,
+        });
+    }
+}
+function assertCaptureReason(reason) {
+    if (reason.trim().length === 0) {
+        throw new NuzoMemoryError("MEMORY_REASON_EMPTY", "Memory reason cannot be empty.");
+    }
+    assertReason(reason);
 }
 function toExportItem(memory) {
     return {
@@ -355,6 +464,9 @@ function assertExportDocument(document) {
     if (!Array.isArray(value.memories)) {
         throw new NuzoMemoryError("MEMORY_EXPORT_INVALID", "Memory export document is invalid.");
     }
+    if (value.memories.length > memoryLimits.importItems) {
+        throw new NuzoMemoryError("MEMORY_IMPORT_LIMIT_EXCEEDED", "Memory import contains too many items.", { maxItems: memoryLimits.importItems });
+    }
     value.memories.forEach(assertExportItem);
 }
 function assertExportItem(item, index) {
@@ -430,6 +542,12 @@ function throwInvalidExportItem(index, reason, details = {}) {
     });
 }
 function parseExportDate(value, field) {
+    if (value.length > memoryLimits.dateLength) {
+        throw new NuzoMemoryError("MEMORY_EXPORT_INVALID", "Memory export contains an invalid date.", {
+            field,
+            maxLength: memoryLimits.dateLength,
+        });
+    }
     const date = new Date(value);
     if (Number.isNaN(date.getTime())) {
         throw new NuzoMemoryError("MEMORY_EXPORT_INVALID", "Memory export contains an invalid date.", {
@@ -450,6 +568,9 @@ function toImportDuplicateKey(memory) {
 function normalizeContent(content) {
     return content.trim().replace(/\s+/g, " ");
 }
+function toCaptureDuplicateKey(content) {
+    return normalizeContent(content).toLowerCase();
+}
 function normalizeTags(tags) {
     return [...new Set(tags)].sort();
 }

package/dist/sqlite/adapter.d.ts

@@ -12,10 +12,10 @@ export declare class SQLiteMemoryDatabase implements MemoryStore, SearchIndex, A
     getSchemaVersion(): number;
     run<T>(operation: () => Promise<T>): Promise<T>;
     create(memory: MemoryRecord): Promise<void>;
-    update(memory: MemoryRecord): Promise<void>;
+    update(memory: MemoryRecord, expectedRevision?: number): Promise<boolean>;
     findById(id: string): Promise<MemoryRecord | null>;
-    archive(id: string, archivedAt: Date): Promise<void>;
-    delete(id: string): Promise<void>;
+    archive(id: string, archivedAt: Date, expectedRevision?: number): Promise<boolean>;
+    delete(id: string, expectedRevision?: number): Promise<boolean>;
     index(memory: MemoryRecord): Promise<void>;
     remove(memoryId: string): Promise<void>;
     search(input: RecallMemoriesInput): Promise<RecallMemoryResult[]>;

package/dist/sqlite/adapter.js

@@ -1,21 +1,26 @@
 import Database from "better-sqlite3";
+import { chmodSync, closeSync, existsSync, openSync } from "node:fs";
 import { NuzoMemoryError } from "../errors.js";
 import { migrate } from "./schema.js";
 export class SQLiteMemoryDatabase {
     database;
     transactionQueue = Promise.resolve();
     constructor(options) {
+        createPrivateDatabaseFile(options.path);
         this.database = new Database(options.path);
         try {
             migrate(this.database);
+            protectDatabaseFiles(options.path);
         }
         catch (error) {
             this.database.close();
+            protectDatabaseFiles(options.path);
             throw error;
         }
     }
     close() {
         this.database.close();
+        protectDatabaseFiles(this.database.name);
     }
     getSchemaVersion() {
         return this.database.pragma("user_version", { simple: true });
@@ -31,6 +36,7 @@ export class SQLiteMemoryDatabase {
         try {
             this.database.exec("BEGIN IMMEDIATE");
             started = true;
+            protectDatabaseFiles(this.database.name);
             const result = await operation();
             this.database.exec("COMMIT");
             return result;
@@ -42,6 +48,7 @@ export class SQLiteMemoryDatabase {
             throw error;
         }
         finally {
+            protectDatabaseFiles(this.database.name);
             release();
         }
     }
@@ -59,11 +66,13 @@ export class SQLiteMemoryDatabase {
         `)
             .run(toMemoryRow(memory));
     }
-    async update(memory) {
-        this.database
+    async update(memory, expectedRevision) {
+        const where = expectedRevision === undefined ? "id = @id" : "id = @id AND revision = @expected_revision";
+        const result = this.database
             .prepare(`
           UPDATE memories
-          SET scope = @scope,
+          SET revision = @revision,
+              scope = @scope,
               kind = @kind,
               content = @content,
               tags = @tags,
@@ -73,21 +82,37 @@ export class SQLiteMemoryDatabase {
               updated_at = @updated_at,
               last_used_at = @last_used_at,
               archived_at = @archived_at
-          WHERE id = @id
+          WHERE ${where}
         `)
-            .run(toMemoryRow(memory));
+            .run({
+            ...toMemoryRow(memory),
+            expected_revision: expectedRevision,
+        });
+        return result.changes === 1;
     }
     async findById(id) {
         const row = this.database.prepare("SELECT * FROM memories WHERE id = ?").get(id);
         return row ? fromMemoryRow(row) : null;
     }
-    async archive(id, archivedAt) {
-        this.database
-            .prepare("UPDATE memories SET archived_at = @archived_at, updated_at = @archived_at WHERE id = @id")
-            .run({ id, archived_at: archivedAt.toISOString() });
+    async archive(id, archivedAt, expectedRevision) {
+        const where = expectedRevision === undefined ? "id = @id" : "id = @id AND revision = @expected_revision";
+        const result = this.database
+            .prepare(`
+          UPDATE memories
+          SET revision = revision + 1,
+              archived_at = @archived_at,
+              updated_at = @archived_at
+          WHERE ${where}
+        `)
+            .run({ id, archived_at: archivedAt.toISOString(), expected_revision: expectedRevision });
+        return result.changes === 1;
     }
-    async delete(id) {
-        this.database.prepare("DELETE FROM memories WHERE id = ?").run(id);
+    async delete(id, expectedRevision) {
+        const where = expectedRevision === undefined ? "id = ?" : "id = ? AND revision = ?";
+        const result = expectedRevision === undefined
+            ? this.database.prepare(`DELETE FROM memories WHERE ${where}`).run(id)
+            : this.database.prepare(`DELETE FROM memories WHERE ${where}`).run(id, expectedRevision);
+        return result.changes === 1;
     }
     async index(memory) {
         this.database.prepare("DELETE FROM memories_fts WHERE id = ?").run(memory.id);
@@ -170,6 +195,7 @@ export class SQLiteMemoryDatabase {
 function toMemoryRow(memory) {
     return {
         id: memory.id,
+        revision: memory.revision,
         scope: memory.scope,
         kind: memory.kind,
         content: memory.content,
@@ -185,6 +211,7 @@ function toMemoryRow(memory) {
 function fromMemoryRow(row) {
     return {
         id: row.id,
+        revision: row.revision,
         scope: row.scope,
         kind: row.kind,
         content: row.content,
@@ -234,8 +261,23 @@ function parsePayload(value) {
 function toFtsQuery(query) {
     return query
         .trim()
-        .split(/\W+/)
+        .split(/[^\p{L}\p{N}_]+/u)
         .filter(Boolean)
         .map((term) => `"${term.replaceAll('"', '""')}"`)
         .join(" OR ");
 }
+function protectDatabaseFiles(path) {
+    for (const candidate of [path, `${path}-wal`, `${path}-shm`]) {
+        if (existsSync(candidate)) {
+            chmodSync(candidate, 0o600);
+        }
+    }
+}
+function createPrivateDatabaseFile(path) {
+    if (path === ":memory:") {
+        return;
+    }
+    const descriptor = openSync(path, "a", 0o600);
+    closeSync(descriptor);
+    chmodSync(path, 0o600);
+}

package/dist/sqlite/schema.d.ts

@@ -1,3 +1,3 @@
 import type Database from "better-sqlite3";
-export declare const schemaVersion = 1;
+export declare const schemaVersion = 2;
 export declare function migrate(database: Database.Database): void;

package/dist/sqlite/schema.js

@@ -1,7 +1,8 @@
 import { NuzoMemoryError } from "../errors.js";
-export const schemaVersion = 1;
+export const schemaVersion = 2;
 export function migrate(database) {
     database.pragma("journal_mode = WAL");
+    database.pragma("busy_timeout = 5000");
     database.pragma("foreign_keys = ON");
     const currentVersion = database.pragma("user_version", { simple: true });
     if (currentVersion > schemaVersion) {
@@ -12,6 +13,10 @@ export function migrate(database) {
     }
     if (currentVersion < 1) {
         migrateToV1(database);
+        database.pragma("user_version = 1");
+    }
+    if (currentVersion < 2) {
+        migrateToV2(database);
         database.pragma(`user_version = ${schemaVersion}`);
     }
 }
@@ -19,6 +24,7 @@ function migrateToV1(database) {
     database.exec(`
     CREATE TABLE IF NOT EXISTS memories (
       id TEXT PRIMARY KEY,
+      revision INTEGER NOT NULL DEFAULT 1,
       scope TEXT NOT NULL,
       kind TEXT NOT NULL,
       content TEXT NOT NULL,
@@ -52,3 +58,9 @@ function migrateToV1(database) {
     CREATE INDEX IF NOT EXISTS idx_memory_events_memory_id ON memory_events(memory_id);
   `);
 }
+function migrateToV2(database) {
+    const columns = database.pragma("table_info(memories)");
+    if (!columns.some((column) => column.name === "revision")) {
+        database.exec("ALTER TABLE memories ADD COLUMN revision INTEGER NOT NULL DEFAULT 1;");
+    }
+}

package/dist/types.d.ts

@@ -3,6 +3,7 @@ export declare const memoryKinds: readonly ["preference", "project_decision", "f
 export type MemoryScope = `user:${string}` | `project:${string}` | `agent:${string}` | `team:${string}`;
 export interface MemoryRecord {
     id: string;
+    revision: number;
     scope: MemoryScope;
     kind: MemoryKind;
     content: string;
@@ -30,6 +31,25 @@ export interface RememberMemoryInput {
     source: string;
     confidence?: number;
 }
+export interface SuggestCaptureInput extends RememberMemoryInput {
+    reason: string;
+}
+export interface CaptureSuggestionDraft {
+    content: string;
+    kind: MemoryKind;
+    scope: MemoryScope;
+    tags: string[];
+    source: string;
+    confidence: number;
+    reason: string;
+}
+export interface CaptureSuggestionResult {
+    status: "ready" | "duplicate";
+    memoryWrites: false;
+    requiresConfirmation: true;
+    draft: CaptureSuggestionDraft;
+    duplicate: MemoryRecord | null;
+}
 export interface RecallMemoriesInput {
     query: string;
     scope: MemoryScope;
@@ -44,6 +64,7 @@ export interface ListMemoriesInput {
 }
 export interface ForgetMemoryInput {
     id: string;
+    expectedRevision?: number;
     mode?: "archive" | "delete";
     confirm?: boolean;
     actor: string;
@@ -68,6 +89,7 @@ export interface ForgetMemoriesResult {
 }
 export interface UpdateMemoryInput {
     id: string;
+    expectedRevision?: number;
     content?: string;
     kind?: MemoryKind;
     scope?: MemoryScope;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nuzo/memory-core",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Core memory lifecycle, ports, and domain contracts for Nuzo.",
   "keywords": [
     "ai-agents",
@@ -28,7 +28,7 @@
     "LICENSE"
   ],
   "dependencies": {
-    "better-sqlite3": "^12.10.0"
+    "better-sqlite3": "^12.11.1"
   },
   "publishConfig": {
     "access": "public"