@nuzo/memory-core 0.1.0

package/dist/sqlite/adapter.js

@@ -0,0 +1,241 @@
+import Database from "better-sqlite3";
+import { NuzoMemoryError } from "../errors.js";
+import { migrate } from "./schema.js";
+export class SQLiteMemoryDatabase {
+    database;
+    transactionQueue = Promise.resolve();
+    constructor(options) {
+        this.database = new Database(options.path);
+        try {
+            migrate(this.database);
+        }
+        catch (error) {
+            this.database.close();
+            throw error;
+        }
+    }
+    close() {
+        this.database.close();
+    }
+    getSchemaVersion() {
+        return this.database.pragma("user_version", { simple: true });
+    }
+    async run(operation) {
+        const previous = this.transactionQueue;
+        let release;
+        this.transactionQueue = new Promise((resolve) => {
+            release = resolve;
+        });
+        await previous;
+        let started = false;
+        try {
+            this.database.exec("BEGIN IMMEDIATE");
+            started = true;
+            const result = await operation();
+            this.database.exec("COMMIT");
+            return result;
+        }
+        catch (error) {
+            if (started && this.database.inTransaction) {
+                this.database.exec("ROLLBACK");
+            }
+            throw error;
+        }
+        finally {
+            release();
+        }
+    }
+    async create(memory) {
+        this.database
+            .prepare(`
+          INSERT INTO memories (
+            id, scope, kind, content, tags, source, confidence,
+            created_at, updated_at, last_used_at, archived_at
+          )
+          VALUES (
+            @id, @scope, @kind, @content, @tags, @source, @confidence,
+            @created_at, @updated_at, @last_used_at, @archived_at
+          )
+        `)
+            .run(toMemoryRow(memory));
+    }
+    async update(memory) {
+        this.database
+            .prepare(`
+          UPDATE memories
+          SET scope = @scope,
+              kind = @kind,
+              content = @content,
+              tags = @tags,
+              source = @source,
+              confidence = @confidence,
+              created_at = @created_at,
+              updated_at = @updated_at,
+              last_used_at = @last_used_at,
+              archived_at = @archived_at
+          WHERE id = @id
+        `)
+            .run(toMemoryRow(memory));
+    }
+    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 delete(id) {
+        this.database.prepare("DELETE FROM memories WHERE id = ?").run(id);
+    }
+    async index(memory) {
+        this.database.prepare("DELETE FROM memories_fts WHERE id = ?").run(memory.id);
+        if (memory.archivedAt) {
+            return;
+        }
+        this.database
+            .prepare("INSERT INTO memories_fts (id, scope, content, tags) VALUES (?, ?, ?, ?)")
+            .run(memory.id, memory.scope, memory.content, memory.tags.join(" "));
+    }
+    async remove(memoryId) {
+        this.database.prepare("DELETE FROM memories_fts WHERE id = ?").run(memoryId);
+    }
+    async search(input) {
+        const limit = input.limit ?? 8;
+        const query = toFtsQuery(input.query);
+        if (!query) {
+            return [];
+        }
+        const scopeClause = input.includeGlobal === true
+            ? "AND (m.scope = @scope OR m.scope = 'user:default')"
+            : "AND m.scope = @scope";
+        const rows = this.database
+            .prepare(`
+          SELECT m.*, bm25(memories_fts) * -1 AS score
+          FROM memories_fts
+          JOIN memories m ON m.id = memories_fts.id
+          WHERE memories_fts MATCH @query
+            AND m.archived_at IS NULL
+            ${scopeClause}
+          ORDER BY bm25(memories_fts)
+          LIMIT @limit
+        `)
+            .all({ query, scope: input.scope, limit });
+        return rows.map((row) => ({
+            memory: fromMemoryRow(row),
+            score: row.score,
+            reason: `Matched FTS query: ${query}`,
+        }));
+    }
+    async append(event) {
+        this.database
+            .prepare(`
+          INSERT INTO memory_events (id, memory_id, event_type, actor, payload, created_at)
+          VALUES (@id, @memory_id, @event_type, @actor, @payload, @created_at)
+        `)
+            .run(toEventRow(event));
+    }
+    async list(memoryIdOrFilter) {
+        if (typeof memoryIdOrFilter !== "string") {
+            return this.listMemories(memoryIdOrFilter);
+        }
+        const rows = this.database
+            .prepare("SELECT * FROM memory_events WHERE memory_id = ? ORDER BY created_at ASC")
+            .all(memoryIdOrFilter);
+        return rows.map(fromEventRow);
+    }
+    async listMemories(filter) {
+        const where = [];
+        const params = {};
+        if (filter.scope) {
+            where.push("scope = @scope");
+            params.scope = filter.scope;
+        }
+        if (filter.includeArchived !== true) {
+            where.push("archived_at IS NULL");
+        }
+        const sql = `
+      SELECT *
+      FROM memories
+      ${where.length > 0 ? `WHERE ${where.join(" AND ")}` : ""}
+      ORDER BY updated_at DESC, created_at DESC
+    `;
+        const rows = this.database.prepare(sql).all(params);
+        return rows
+            .map(fromMemoryRow)
+            .filter((memory) => !filter.tags || filter.tags.every((tag) => memory.tags.includes(tag)));
+    }
+}
+function toMemoryRow(memory) {
+    return {
+        id: memory.id,
+        scope: memory.scope,
+        kind: memory.kind,
+        content: memory.content,
+        tags: JSON.stringify(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 fromMemoryRow(row) {
+    return {
+        id: row.id,
+        scope: row.scope,
+        kind: row.kind,
+        content: row.content,
+        tags: parseTags(row.tags),
+        source: row.source,
+        confidence: row.confidence,
+        createdAt: new Date(row.created_at),
+        updatedAt: new Date(row.updated_at),
+        lastUsedAt: row.last_used_at ? new Date(row.last_used_at) : null,
+        archivedAt: row.archived_at ? new Date(row.archived_at) : null,
+    };
+}
+function toEventRow(event) {
+    return {
+        id: event.id,
+        memory_id: event.memoryId,
+        event_type: event.eventType,
+        actor: event.actor,
+        payload: JSON.stringify(event.payload),
+        created_at: event.createdAt.toISOString(),
+    };
+}
+function fromEventRow(row) {
+    return {
+        id: row.id,
+        memoryId: row.memory_id,
+        eventType: row.event_type,
+        actor: row.actor,
+        payload: parsePayload(row.payload),
+        createdAt: new Date(row.created_at),
+    };
+}
+function parseTags(value) {
+    const parsed = JSON.parse(value);
+    if (!Array.isArray(parsed) || !parsed.every((tag) => typeof tag === "string")) {
+        throw new NuzoMemoryError("MEMORY_TAGS_INVALID", "Stored memory tags are invalid.");
+    }
+    return parsed;
+}
+function parsePayload(value) {
+    const parsed = JSON.parse(value);
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new NuzoMemoryError("MEMORY_EVENT_PAYLOAD_INVALID", "Stored memory event payload is invalid.");
+    }
+    return parsed;
+}
+function toFtsQuery(query) {
+    return query
+        .trim()
+        .split(/\W+/)
+        .filter(Boolean)
+        .map((term) => `"${term.replaceAll('"', '""')}"`)
+        .join(" OR ");
+}

package/dist/sqlite/schema.d.ts

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

package/dist/sqlite/schema.js

@@ -0,0 +1,54 @@
+import { NuzoMemoryError } from "../errors.js";
+export const schemaVersion = 1;
+export function migrate(database) {
+    database.pragma("journal_mode = WAL");
+    database.pragma("foreign_keys = ON");
+    const currentVersion = database.pragma("user_version", { simple: true });
+    if (currentVersion > schemaVersion) {
+        throw new NuzoMemoryError("MEMORY_SCHEMA_UNSUPPORTED", "SQLite memory schema is newer than this Nuzo version supports.", {
+            currentVersion,
+            supportedVersion: schemaVersion,
+        });
+    }
+    if (currentVersion < 1) {
+        migrateToV1(database);
+        database.pragma(`user_version = ${schemaVersion}`);
+    }
+}
+function migrateToV1(database) {
+    database.exec(`
+    CREATE TABLE IF NOT EXISTS memories (
+      id TEXT PRIMARY KEY,
+      scope TEXT NOT NULL,
+      kind TEXT NOT NULL,
+      content TEXT NOT NULL,
+      tags TEXT NOT NULL DEFAULT '[]',
+      source TEXT NOT NULL,
+      confidence REAL NOT NULL DEFAULT 1.0,
+      created_at TEXT NOT NULL,
+      updated_at TEXT NOT NULL,
+      last_used_at TEXT,
+      archived_at TEXT
+    );
+
+    CREATE TABLE IF NOT EXISTS memory_events (
+      id TEXT PRIMARY KEY,
+      memory_id TEXT,
+      event_type TEXT NOT NULL,
+      actor TEXT NOT NULL,
+      payload TEXT NOT NULL,
+      created_at TEXT NOT NULL
+    );
+
+    CREATE VIRTUAL TABLE IF NOT EXISTS memories_fts USING fts5(
+      id UNINDEXED,
+      scope UNINDEXED,
+      content,
+      tags
+    );
+
+    CREATE INDEX IF NOT EXISTS idx_memories_scope ON memories(scope);
+    CREATE INDEX IF NOT EXISTS idx_memories_archived_at ON memories(archived_at);
+    CREATE INDEX IF NOT EXISTS idx_memory_events_memory_id ON memory_events(memory_id);
+  `);
+}

package/dist/types.d.ts

@@ -0,0 +1,114 @@
+export type MemoryKind = "preference" | "project_decision" | "fact" | "instruction" | "note";
+export declare const memoryKinds: readonly ["preference", "project_decision", "fact", "instruction", "note"];
+export type MemoryScope = `user:${string}` | `project:${string}` | `agent:${string}` | `team:${string}`;
+export interface MemoryRecord {
+    id: string;
+    scope: MemoryScope;
+    kind: MemoryKind;
+    content: string;
+    tags: string[];
+    source: string;
+    confidence: number;
+    createdAt: Date;
+    updatedAt: Date;
+    lastUsedAt: Date | null;
+    archivedAt: Date | null;
+}
+export interface MemoryEvent {
+    id: string;
+    memoryId: string | null;
+    eventType: "memory.created" | "memory.updated" | "memory.archived" | "memory.deleted" | "memory.imported" | "memory.exported" | "memory.recalled";
+    actor: string;
+    payload: Record<string, unknown>;
+    createdAt: Date;
+}
+export interface RememberMemoryInput {
+    content: string;
+    kind: MemoryKind;
+    scope: MemoryScope;
+    tags?: string[];
+    source: string;
+    confidence?: number;
+}
+export interface RecallMemoriesInput {
+    query: string;
+    scope: MemoryScope;
+    limit?: number;
+    includeGlobal?: boolean;
+    recordUsage?: boolean;
+}
+export interface ListMemoriesInput {
+    scope?: MemoryScope;
+    tags?: string[];
+    includeArchived?: boolean;
+}
+export interface ForgetMemoryInput {
+    id: string;
+    mode?: "archive" | "delete";
+    confirm?: boolean;
+    actor: string;
+    reason?: string;
+}
+export interface ForgetMemoriesInput {
+    scope?: MemoryScope;
+    tags?: string[];
+    all?: boolean;
+    mode?: "archive" | "delete";
+    confirm?: boolean;
+    dryRun?: boolean;
+    actor: string;
+    reason?: string;
+}
+export interface ForgetMemoriesResult {
+    matched: number;
+    affected: number;
+    mode: "archive" | "delete";
+    dryRun: boolean;
+    ids: string[];
+}
+export interface UpdateMemoryInput {
+    id: string;
+    content?: string;
+    kind?: MemoryKind;
+    scope?: MemoryScope;
+    tags?: string[];
+    confidence?: number;
+    actor: string;
+}
+export interface ExportMemoriesInput extends ListMemoriesInput {
+    actor: string;
+}
+export interface ImportMemoriesInput {
+    document: MemoryExportDocument;
+    actor: string;
+    scope?: MemoryScope;
+    dryRun?: boolean;
+}
+export interface ImportMemoriesResult {
+    imported: number;
+    skipped: number;
+    dryRun: boolean;
+}
+export interface MemoryExportDocument {
+    format: "nuzo-memory-export";
+    version: 1;
+    exported_at: string;
+    memories: MemoryExportItem[];
+}
+export interface MemoryExportItem {
+    scope: MemoryScope;
+    kind: MemoryKind;
+    content: string;
+    tags: string[];
+    source: string;
+    confidence: number;
+    created_at: string;
+    updated_at: string;
+    last_used_at: string | null;
+    archived_at: string | null;
+}
+export interface RecallMemoryResult {
+    memory: MemoryRecord;
+    score: number;
+    reason: string;
+}

package/dist/types.js

@@ -0,0 +1,7 @@
+export const memoryKinds = [
+    "preference",
+    "project_decision",
+    "fact",
+    "instruction",
+    "note",
+];

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@nuzo/memory-core",
+  "version": "0.1.0",
+  "description": "Core memory lifecycle, ports, and domain contracts for Nuzo.",
+  "keywords": [
+    "ai-agents",
+    "memory",
+    "local-first",
+    "sqlite"
+  ],
+  "license": "Apache-2.0",
+  "type": "module",
+  "engines": {
+    "node": ">=22",
+    "npm": ">=10"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "better-sqlite3": "^12.10.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/fabionfsc/nuzo-memory.git",
+    "directory": "packages/core"
+  },
+  "homepage": "https://nuzo.com.br/",
+  "bugs": {
+    "url": "https://github.com/fabionfsc/nuzo-memory/issues"
+  }
+}