@framers/agentos 0.2.12 → 0.3.1

package/dist/memory/retrieval/store/migrations/v1-to-v2.js

@@ -0,0 +1,491 @@
+/**
+ * @file v1-to-v2.ts
+ * @description Schema migration v1 -> v2: add `brain_id TEXT NOT NULL` column
+ * to all 14 brain-owned tables and recreate composite primary keys / indexes.
+ *
+ * SQLite does not support `ALTER TABLE ADD PRIMARY KEY`, so the migration uses
+ * the standard recreate-table dance: rename old to `<name>_v1`, create new
+ * with target schema, copy rows with the brain_id default, drop the old.
+ *
+ * Postgres uses simple ALTER statements (ADD COLUMN with default, DROP CONSTRAINT,
+ * ADD PRIMARY KEY) since it supports those operations natively.
+ *
+ * Idempotent: detects v2 schema and returns early without touching data.
+ *
+ * @module memory/retrieval/store/migrations/v1-to-v2
+ */
+import { PORTABLE_TABLES } from '../portable-tables.js';
+/**
+ * The 14 tables that gain `brain_id` in v2. Order matters for FK resolution:
+ * documents must exist before document_chunks; conversations before messages.
+ */
+const V2_TABLES = [
+    {
+        name: 'brain_meta',
+        columnsDdl: 'brain_id TEXT NOT NULL, key TEXT NOT NULL, value TEXT NOT NULL',
+        primaryKey: ['brain_id', 'key'],
+        indexes: [],
+    },
+    {
+        name: 'memory_traces',
+        columnsDdl: `
+      brain_id        TEXT    NOT NULL,
+      id              TEXT    NOT NULL,
+      type            TEXT    NOT NULL,
+      scope           TEXT    NOT NULL,
+      content         TEXT    NOT NULL,
+      embedding       BLOB,
+      strength        REAL    NOT NULL DEFAULT 1.0,
+      created_at      INTEGER NOT NULL,
+      last_accessed   INTEGER,
+      retrieval_count INTEGER NOT NULL DEFAULT 0,
+      tags            TEXT    NOT NULL DEFAULT '[]',
+      emotions        TEXT    NOT NULL DEFAULT '{}',
+      metadata        TEXT    NOT NULL DEFAULT '{}',
+      deleted         INTEGER NOT NULL DEFAULT 0
+    `,
+        primaryKey: ['brain_id', 'id'],
+        indexes: [
+            `CREATE INDEX IF NOT EXISTS idx_memory_traces_brain_type
+         ON memory_traces (brain_id, type, created_at DESC)`,
+            `CREATE INDEX IF NOT EXISTS idx_memory_traces_brain_scope
+         ON memory_traces (brain_id, scope)`,
+        ],
+    },
+    {
+        name: 'knowledge_nodes',
+        columnsDdl: `
+      brain_id   TEXT    NOT NULL,
+      id         TEXT    NOT NULL,
+      type       TEXT    NOT NULL,
+      label      TEXT    NOT NULL,
+      properties TEXT    NOT NULL DEFAULT '{}',
+      embedding  BLOB,
+      confidence REAL    NOT NULL DEFAULT 1.0,
+      source     TEXT    NOT NULL DEFAULT '{}',
+      created_at INTEGER NOT NULL
+    `,
+        primaryKey: ['brain_id', 'id'],
+        indexes: [
+            `CREATE INDEX IF NOT EXISTS idx_knowledge_nodes_brain_type
+         ON knowledge_nodes (brain_id, type)`,
+        ],
+    },
+    {
+        name: 'knowledge_edges',
+        columnsDdl: `
+      brain_id      TEXT    NOT NULL,
+      id            TEXT    NOT NULL,
+      source_id     TEXT    NOT NULL,
+      target_id     TEXT    NOT NULL,
+      type          TEXT    NOT NULL,
+      weight        REAL    NOT NULL DEFAULT 1.0,
+      bidirectional INTEGER NOT NULL DEFAULT 0,
+      metadata      TEXT    NOT NULL DEFAULT '{}',
+      created_at    INTEGER NOT NULL
+    `,
+        primaryKey: ['brain_id', 'id'],
+        foreignKeys: [
+            'FOREIGN KEY (brain_id, source_id) REFERENCES knowledge_nodes(brain_id, id)',
+            'FOREIGN KEY (brain_id, target_id) REFERENCES knowledge_nodes(brain_id, id)',
+        ],
+        indexes: [
+            `CREATE INDEX IF NOT EXISTS idx_knowledge_edges_brain_source
+         ON knowledge_edges (brain_id, source_id)`,
+            `CREATE INDEX IF NOT EXISTS idx_knowledge_edges_brain_target
+         ON knowledge_edges (brain_id, target_id)`,
+        ],
+    },
+    {
+        name: 'documents',
+        columnsDdl: `
+      brain_id     TEXT    NOT NULL,
+      id           TEXT    NOT NULL,
+      path         TEXT    NOT NULL,
+      format       TEXT    NOT NULL,
+      title        TEXT,
+      content_hash TEXT    NOT NULL,
+      chunk_count  INTEGER NOT NULL DEFAULT 0,
+      metadata     TEXT    NOT NULL DEFAULT '{}',
+      ingested_at  INTEGER NOT NULL
+    `,
+        primaryKey: ['brain_id', 'id'],
+        indexes: [],
+    },
+    {
+        name: 'document_chunks',
+        columnsDdl: `
+      brain_id     TEXT    NOT NULL,
+      id           TEXT    NOT NULL,
+      document_id  TEXT    NOT NULL,
+      trace_id     TEXT,
+      content      TEXT    NOT NULL,
+      chunk_index  INTEGER NOT NULL,
+      page_number  INTEGER,
+      embedding    BLOB
+    `,
+        primaryKey: ['brain_id', 'id'],
+        foreignKeys: [
+            'FOREIGN KEY (brain_id, document_id) REFERENCES documents(brain_id, id)',
+            'FOREIGN KEY (brain_id, trace_id) REFERENCES memory_traces(brain_id, id)',
+        ],
+        indexes: [
+            `CREATE INDEX IF NOT EXISTS idx_document_chunks_brain_document
+         ON document_chunks (brain_id, document_id, chunk_index)`,
+        ],
+    },
+    {
+        name: 'document_images',
+        columnsDdl: `
+      brain_id    TEXT    NOT NULL,
+      id          TEXT    NOT NULL,
+      document_id TEXT    NOT NULL,
+      chunk_id    TEXT,
+      data        BLOB    NOT NULL,
+      mime_type   TEXT    NOT NULL,
+      caption     TEXT,
+      page_number INTEGER,
+      embedding   BLOB
+    `,
+        primaryKey: ['brain_id', 'id'],
+        foreignKeys: [
+            'FOREIGN KEY (brain_id, document_id) REFERENCES documents(brain_id, id)',
+            'FOREIGN KEY (brain_id, chunk_id) REFERENCES document_chunks(brain_id, id)',
+        ],
+        indexes: [],
+    },
+    {
+        name: 'consolidation_log',
+        columnsDdl: `
+      id          INTEGER PRIMARY KEY AUTOINCREMENT,
+      brain_id    TEXT    NOT NULL,
+      ran_at      INTEGER NOT NULL,
+      pruned      INTEGER NOT NULL DEFAULT 0,
+      merged      INTEGER NOT NULL DEFAULT 0,
+      derived     INTEGER NOT NULL DEFAULT 0,
+      compacted   INTEGER NOT NULL DEFAULT 0,
+      duration_ms INTEGER NOT NULL DEFAULT 0
+    `,
+        primaryKey: [], // AUTOINCREMENT id is global; brain_id scopes via index
+        autoincrementId: true,
+        indexes: [
+            `CREATE INDEX IF NOT EXISTS idx_consolidation_log_brain_time
+         ON consolidation_log (brain_id, ran_at DESC)`,
+        ],
+    },
+    {
+        name: 'retrieval_feedback',
+        columnsDdl: `
+      id         INTEGER PRIMARY KEY AUTOINCREMENT,
+      brain_id   TEXT    NOT NULL,
+      trace_id   TEXT    NOT NULL,
+      signal     TEXT    NOT NULL,
+      query      TEXT,
+      created_at INTEGER NOT NULL
+    `,
+        primaryKey: [],
+        autoincrementId: true,
+        foreignKeys: [
+            'FOREIGN KEY (brain_id, trace_id) REFERENCES memory_traces(brain_id, id)',
+        ],
+        indexes: [
+            `CREATE INDEX IF NOT EXISTS idx_retrieval_feedback_brain_trace
+         ON retrieval_feedback (brain_id, trace_id, created_at DESC)`,
+        ],
+    },
+    {
+        name: 'conversations',
+        columnsDdl: `
+      brain_id   TEXT    NOT NULL,
+      id         TEXT    NOT NULL,
+      title      TEXT,
+      created_at INTEGER NOT NULL,
+      updated_at INTEGER NOT NULL,
+      metadata   TEXT    NOT NULL DEFAULT '{}'
+    `,
+        primaryKey: ['brain_id', 'id'],
+        indexes: [],
+    },
+    {
+        name: 'messages',
+        columnsDdl: `
+      brain_id        TEXT    NOT NULL,
+      id              TEXT    NOT NULL,
+      conversation_id TEXT    NOT NULL,
+      role            TEXT    NOT NULL,
+      content         TEXT    NOT NULL,
+      created_at      INTEGER NOT NULL,
+      metadata        TEXT    NOT NULL DEFAULT '{}'
+    `,
+        primaryKey: ['brain_id', 'id'],
+        foreignKeys: [
+            'FOREIGN KEY (brain_id, conversation_id) REFERENCES conversations(brain_id, id)',
+        ],
+        indexes: [
+            `CREATE INDEX IF NOT EXISTS idx_messages_brain_conversation
+         ON messages (brain_id, conversation_id, created_at)`,
+        ],
+    },
+    {
+        name: 'prospective_items',
+        columnsDdl: `
+      brain_id             TEXT    NOT NULL,
+      id                   TEXT    NOT NULL,
+      content              TEXT    NOT NULL,
+      trigger_type         TEXT    NOT NULL,
+      trigger_at           INTEGER,
+      trigger_event        TEXT,
+      cue_text             TEXT,
+      cue_embedding        BLOB,
+      similarity_threshold REAL    DEFAULT 0.7,
+      importance           REAL    NOT NULL DEFAULT 0.5,
+      triggered            INTEGER NOT NULL DEFAULT 0,
+      recurring            INTEGER NOT NULL DEFAULT 0,
+      source_trace_id      TEXT,
+      created_at           INTEGER NOT NULL
+    `,
+        primaryKey: ['brain_id', 'id'],
+        indexes: [],
+    },
+    {
+        name: 'archived_traces',
+        columnsDdl: `
+      brain_id         TEXT    NOT NULL,
+      trace_id         TEXT    NOT NULL,
+      agent_id         TEXT    NOT NULL,
+      verbatim_content TEXT    NOT NULL,
+      content_hash     TEXT    NOT NULL,
+      trace_type       TEXT    NOT NULL,
+      emotional_context TEXT   NOT NULL DEFAULT '{}',
+      entities         TEXT    NOT NULL DEFAULT '[]',
+      tags             TEXT    NOT NULL DEFAULT '[]',
+      created_at       INTEGER NOT NULL,
+      archived_at      INTEGER NOT NULL,
+      archive_reason   TEXT    NOT NULL,
+      byte_size        INTEGER NOT NULL DEFAULT 0
+    `,
+        primaryKey: ['brain_id', 'trace_id'],
+        // Migration: copy existing agent_id column into brain_id (legacy archive
+        // already discriminated by agent_id, which is semantically the same).
+        //
+        // CAVEAT: if the caller passes an explicit brainId override that differs
+        // from the original agent_id, archived_traces row brain_ids stay at the
+        // original agent_id values (not the override). Live tables receive the
+        // override; only archived_traces inherits agent_id. To rebrand archives,
+        // run a separate UPDATE statement after migration.
+        brainIdSourceColumn: 'agent_id',
+        indexes: [
+            `CREATE INDEX IF NOT EXISTS idx_archived_traces_brain_time
+         ON archived_traces (brain_id, archived_at)`,
+            `CREATE INDEX IF NOT EXISTS idx_archived_traces_brain_reason
+         ON archived_traces (brain_id, archive_reason)`,
+        ],
+    },
+    {
+        name: 'archive_access_log',
+        columnsDdl: `
+      brain_id        TEXT    NOT NULL,
+      trace_id        TEXT    NOT NULL,
+      accessed_at     INTEGER NOT NULL,
+      request_context TEXT
+    `,
+        primaryKey: ['brain_id', 'trace_id', 'accessed_at'],
+        indexes: [
+            `CREATE INDEX IF NOT EXISTS idx_archive_access_recency
+         ON archive_access_log (brain_id, trace_id, accessed_at DESC)`,
+        ],
+    },
+];
+// Sanity check: V2_TABLES names must exactly equal PORTABLE_TABLES order.
+// Failing this assertion means the migration order would not match the
+// portable-artifact order, breaking import/export.
+const v2TableNames = V2_TABLES.map((t) => t.name);
+const portableTableNames = [...PORTABLE_TABLES];
+if (v2TableNames.length !== portableTableNames.length ||
+    v2TableNames.some((n, i) => n !== portableTableNames[i])) {
+    throw new Error(`v1-to-v2.ts: V2_TABLES order (${v2TableNames.join(',')}) does not match ` +
+        `PORTABLE_TABLES (${portableTableNames.join(',')}). Reconcile portable-tables.ts.`);
+}
+/**
+ * Run the v1 -> v2 migration on the given storage adapter.
+ *
+ * Idempotent: returns immediately when schema is already v2.
+ *
+ * @param adapter - The storage adapter to migrate.
+ * @param features - Platform-aware feature bundle (used for dialect-specific paths).
+ * @param brainId - The brain identifier to assign to all existing rows.
+ * @returns `{ migrated: true }` if migration ran, `{ migrated: false }` if no-op.
+ */
+export async function migrateV1ToV2(adapter, features, brainId) {
+    const isPostgres = adapter.kind.includes('postgres');
+    // Detect v2 schema via brain_meta column existence.
+    // If brain_meta does not exist yet, this is a fresh database; no migration needed.
+    const brainMetaExists = isPostgres
+        ? await postgresTableExists(adapter, 'brain_meta')
+        : await sqliteTableExists(adapter, 'brain_meta');
+    if (!brainMetaExists) {
+        // Fresh database; the upcoming _initSchema() call creates v2 directly.
+        return { migrated: false };
+    }
+    const hasBrainId = isPostgres
+        ? await postgresHasColumn(adapter, 'brain_meta', 'brain_id')
+        : await sqliteHasColumn(adapter, 'brain_meta', 'brain_id');
+    if (hasBrainId) {
+        return { migrated: false };
+    }
+    // Run migration. SQLite uses recreate-table dance; Postgres uses ALTER.
+    for (const table of V2_TABLES) {
+        const exists = isPostgres
+            ? await postgresTableExists(adapter, table.name)
+            : await sqliteTableExists(adapter, table.name);
+        if (!exists)
+            continue;
+        if (isPostgres) {
+            await migratePostgresTable(adapter, table, brainId);
+        }
+        else {
+            await migrateSqliteTable(adapter, table, brainId);
+        }
+    }
+    return { migrated: true };
+}
+async function sqliteTableExists(adapter, table) {
+    const row = await adapter.get(`SELECT name FROM sqlite_master WHERE type='table' AND name=?`, [table]);
+    return Boolean(row);
+}
+async function postgresTableExists(adapter, table) {
+    const row = await adapter.get(`SELECT EXISTS (
+       SELECT 1 FROM information_schema.tables
+        WHERE table_schema = current_schema() AND table_name = $1
+     ) AS exists`, [table]);
+    return row?.exists ?? false;
+}
+async function sqliteHasColumn(adapter, table, column) {
+    const rows = await adapter.all(`PRAGMA table_info(${table})`);
+    return rows.some((r) => r.name === column);
+}
+async function postgresHasColumn(adapter, table, column) {
+    const row = await adapter.get(`SELECT EXISTS (
+       SELECT 1 FROM information_schema.columns
+        WHERE table_name = $1 AND column_name = $2
+     ) AS exists`, [table, column]);
+    return row?.exists ?? false;
+}
+/**
+ * SQLite recreate-table dance for a single table.
+ *
+ * 1. Read existing column names.
+ * 2. Rename table to `<name>_v1`.
+ * 3. Create new table with v2 schema.
+ * 4. Copy rows: for tables with `brainIdSourceColumn`, use that column;
+ *    otherwise default to the supplied brainId.
+ * 5. Drop old table.
+ * 6. Apply indexes.
+ */
+async function migrateSqliteTable(adapter, table, brainId) {
+    const oldColumns = (await adapter.all(`PRAGMA table_info(${table.name})`)).map((r) => r.name);
+    await adapter.exec(`ALTER TABLE ${table.name} RENAME TO ${table.name}_v1`);
+    const pkClause = table.primaryKey.length > 0 ? `, PRIMARY KEY (${table.primaryKey.join(', ')})` : '';
+    const fkClause = table.foreignKeys && table.foreignKeys.length > 0
+        ? ',\n  ' + table.foreignKeys.join(',\n  ')
+        : '';
+    await adapter.exec(`CREATE TABLE ${table.name} (
+       ${table.columnsDdl}${pkClause}${fkClause}
+     )`);
+    const oldColList = oldColumns.join(', ');
+    if (table.brainIdSourceColumn && oldColumns.includes(table.brainIdSourceColumn)) {
+        // Copy rows using the existing column as brain_id source.
+        await adapter.exec(`INSERT INTO ${table.name} (brain_id, ${oldColList})
+         SELECT ${table.brainIdSourceColumn}, ${oldColList} FROM ${table.name}_v1`);
+    }
+    else {
+        await adapter.run(`INSERT INTO ${table.name} (brain_id, ${oldColList})
+         SELECT ?, ${oldColList} FROM ${table.name}_v1`, [brainId]);
+    }
+    await adapter.exec(`DROP TABLE ${table.name}_v1`);
+    for (const idx of table.indexes) {
+        await adapter.exec(idx);
+    }
+}
+/**
+ * Postgres ALTER-based migration for a single table.
+ *
+ * 1. Add brain_id column with default = brainId (or copy from agent_id when present).
+ * 2. Drop existing primary key constraint.
+ * 3. Add composite primary key (or skip for AUTOINCREMENT tables).
+ * 4. Drop the default on brain_id (future INSERTs supply it explicitly).
+ * 5. Apply indexes.
+ */
+async function migratePostgresTable(adapter, table, brainId) {
+    const escapedBrainId = brainId.replace(/'/g, "''");
+    if (table.brainIdSourceColumn) {
+        // Defensive: an old archived_traces table might exist without the
+        // expected source column (e.g., schema drift from manual SQL or pre-
+        // archive-feature deployments). Mirror the SQLite path's column-existence
+        // check (see migrateSqliteTable) so a missing source column falls back
+        // to the supplied brainId default rather than crashing the migration.
+        const hasSourceColumn = await postgresHasColumn(adapter, table.name, table.brainIdSourceColumn);
+        if (hasSourceColumn) {
+            await adapter.exec(`ALTER TABLE ${table.name} ADD COLUMN brain_id TEXT`);
+            await adapter.exec(`UPDATE ${table.name} SET brain_id = ${table.brainIdSourceColumn}`);
+            await adapter.exec(`ALTER TABLE ${table.name} ALTER COLUMN brain_id SET NOT NULL`);
+        }
+        else {
+            // Source column missing: fall back to the supplied brainId default,
+            // same as the no-source-column path.
+            await adapter.exec(`ALTER TABLE ${table.name} ADD COLUMN brain_id TEXT NOT NULL DEFAULT '${escapedBrainId}'`);
+            await adapter.exec(`ALTER TABLE ${table.name} ALTER COLUMN brain_id DROP DEFAULT`);
+        }
+    }
+    else {
+        await adapter.exec(`ALTER TABLE ${table.name} ADD COLUMN brain_id TEXT NOT NULL DEFAULT '${escapedBrainId}'`);
+        await adapter.exec(`ALTER TABLE ${table.name} ALTER COLUMN brain_id DROP DEFAULT`);
+    }
+    if (table.primaryKey.length > 0) {
+        // Drop existing PK (Postgres names it <table>_pkey by default).
+        await adapter.exec(`ALTER TABLE ${table.name} DROP CONSTRAINT IF EXISTS ${table.name}_pkey`);
+        await adapter.exec(`ALTER TABLE ${table.name} ADD PRIMARY KEY (${table.primaryKey.join(', ')})`);
+    }
+    for (const idx of table.indexes) {
+        await adapter.exec(idx);
+    }
+}
+/**
+ * The v1 -> v2 schema migration as a Migration object for MigrationRunner.
+ *
+ * The runner handles transaction wrapping, advisory locking, and the
+ * schema_version bump. This Migration's `up` function only runs the schema
+ * diff (the 14-table walk).
+ */
+export const v1ToV2 = {
+    version: 2,
+    up: async (adapter, _features, brainId) => {
+        // The runner already detected that schema_version < 2 (or null=fresh; in
+        // the fresh case the runner would have skipped this migration entirely).
+        // We still defensively check brain_meta column existence so a partial v1
+        // schema doesn't blow up the migration.
+        const isPostgres = adapter.kind.includes('postgres');
+        const hasBrainId = isPostgres
+            ? await postgresHasColumn(adapter, 'brain_meta', 'brain_id')
+            : await sqliteHasColumn(adapter, 'brain_meta', 'brain_id');
+        if (hasBrainId) {
+            // Schema is already at v2 column shape; runner's version filter caught
+            // this case. Defensive no-op.
+            return;
+        }
+        for (const table of V2_TABLES) {
+            const exists = isPostgres
+                ? await postgresTableExists(adapter, table.name)
+                : await sqliteTableExists(adapter, table.name);
+            if (!exists)
+                continue;
+            if (isPostgres) {
+                await migratePostgresTable(adapter, table, brainId);
+            }
+            else {
+                await migrateSqliteTable(adapter, table, brainId);
+            }
+        }
+    },
+};
+//# sourceMappingURL=v1-to-v2.js.map

package/dist/memory/retrieval/store/migrations/v1-to-v2.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"v1-to-v2.js","sourceRoot":"","sources":["../../../../../src/memory/retrieval/store/migrations/v1-to-v2.ts"],"names":[],"mappings":"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"}

package/dist/memory/retrieval/store/portable-tables.d.ts

@@ -0,0 +1,27 @@
+/**
+ * @fileoverview Single source of truth for the list of brain-owned tables that
+ * are exported, imported, and migrated as a portable artifact.
+ *
+ * Three call sites import from here:
+ * 1. `Brain.exportToSqlite` / `importFromSqlite` (export/import row copies)
+ * 2. `migrations/v1-to-v2.ts` (migration walk order: parents before children for FKs)
+ * 3. `__tests__/Brain.postgres.test.ts` (cleanup between tests)
+ *
+ * Adding a new portable table requires editing only this file.
+ *
+ * @module memory/retrieval/store/portable-tables
+ */
+/**
+ * Order matters: parents before children to satisfy FK constraints during import.
+ */
+export declare const PORTABLE_TABLES: readonly ["brain_meta", "memory_traces", "knowledge_nodes", "knowledge_edges", "documents", "document_chunks", "document_images", "consolidation_log", "retrieval_feedback", "conversations", "messages", "prospective_items", "archived_traces", "archive_access_log"];
+/**
+ * Composite primary key columns for each portable table, used by
+ * `dialect.insertOrReplace` as the conflict target during merge import.
+ *
+ * Tables with `INTEGER PRIMARY KEY AUTOINCREMENT` (consolidation_log,
+ * retrieval_feedback) use `id` alone since their PK is system-generated.
+ */
+export declare const PORTABLE_TABLE_PRIMARY_KEYS: Record<string, string>;
+export type PortableTable = typeof PORTABLE_TABLES[number];
+//# sourceMappingURL=portable-tables.d.ts.map

package/dist/memory/retrieval/store/portable-tables.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"portable-tables.d.ts","sourceRoot":"","sources":["../../../../src/memory/retrieval/store/portable-tables.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH;;GAEG;AACH,eAAO,MAAM,eAAe,yQAelB,CAAC;AAEX;;;;;;GAMG;AACH,eAAO,MAAM,2BAA2B,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAe9D,CAAC;AAEF,MAAM,MAAM,aAAa,GAAG,OAAO,eAAe,CAAC,MAAM,CAAC,CAAC"}

package/dist/memory/retrieval/store/portable-tables.js

@@ -0,0 +1,56 @@
+/**
+ * @fileoverview Single source of truth for the list of brain-owned tables that
+ * are exported, imported, and migrated as a portable artifact.
+ *
+ * Three call sites import from here:
+ * 1. `Brain.exportToSqlite` / `importFromSqlite` (export/import row copies)
+ * 2. `migrations/v1-to-v2.ts` (migration walk order: parents before children for FKs)
+ * 3. `__tests__/Brain.postgres.test.ts` (cleanup between tests)
+ *
+ * Adding a new portable table requires editing only this file.
+ *
+ * @module memory/retrieval/store/portable-tables
+ */
+/**
+ * Order matters: parents before children to satisfy FK constraints during import.
+ */
+export const PORTABLE_TABLES = [
+    'brain_meta',
+    'memory_traces',
+    'knowledge_nodes',
+    'knowledge_edges',
+    'documents',
+    'document_chunks',
+    'document_images',
+    'consolidation_log',
+    'retrieval_feedback',
+    'conversations',
+    'messages',
+    'prospective_items',
+    'archived_traces',
+    'archive_access_log',
+];
+/**
+ * Composite primary key columns for each portable table, used by
+ * `dialect.insertOrReplace` as the conflict target during merge import.
+ *
+ * Tables with `INTEGER PRIMARY KEY AUTOINCREMENT` (consolidation_log,
+ * retrieval_feedback) use `id` alone since their PK is system-generated.
+ */
+export const PORTABLE_TABLE_PRIMARY_KEYS = {
+    brain_meta: 'brain_id, key',
+    memory_traces: 'brain_id, id',
+    knowledge_nodes: 'brain_id, id',
+    knowledge_edges: 'brain_id, id',
+    documents: 'brain_id, id',
+    document_chunks: 'brain_id, id',
+    document_images: 'brain_id, id',
+    consolidation_log: 'id',
+    retrieval_feedback: 'id',
+    conversations: 'brain_id, id',
+    messages: 'brain_id, id',
+    prospective_items: 'brain_id, id',
+    archived_traces: 'brain_id, trace_id',
+    archive_access_log: 'brain_id, trace_id, accessed_at',
+};
+//# sourceMappingURL=portable-tables.js.map

package/dist/memory/retrieval/store/portable-tables.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"portable-tables.js","sourceRoot":"","sources":["../../../../src/memory/retrieval/store/portable-tables.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH;;GAEG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG;IAC7B,YAAY;IACZ,eAAe;IACf,iBAAiB;IACjB,iBAAiB;IACjB,WAAW;IACX,iBAAiB;IACjB,iBAAiB;IACjB,mBAAmB;IACnB,oBAAoB;IACpB,eAAe;IACf,UAAU;IACV,mBAAmB;IACnB,iBAAiB;IACjB,oBAAoB;CACZ,CAAC;AAEX;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,2BAA2B,GAA2B;IACjE,UAAU,EAAE,eAAe;IAC3B,aAAa,EAAE,cAAc;IAC7B,eAAe,EAAE,cAAc;IAC/B,eAAe,EAAE,cAAc;IAC/B,SAAS,EAAE,cAAc;IACzB,eAAe,EAAE,cAAc;IAC/B,eAAe,EAAE,cAAc;IAC/B,iBAAiB,EAAE,IAAI;IACvB,kBAAkB,EAAE,IAAI;IACxB,aAAa,EAAE,cAAc;IAC7B,QAAQ,EAAE,cAAc;IACxB,iBAAiB,EAAE,cAAc;IACjC,eAAe,EAAE,oBAAoB;IACrC,kBAAkB,EAAE,iCAAiC;CACtD,CAAC"}

package/dist/memory-router/backends/EntityRetrievalRanker.d.ts

@@ -0,0 +1,54 @@
+/**
+ * @file EntityRetrievalRanker.ts
+ * @description Mem0-v3-style recall-stage re-ranker. Adds an
+ * entity-overlap signal to the existing semantic-similarity score:
+ *
+ *   combinedScore = (1 - entityWeight) * semanticScore
+ *                 + entityWeight * (overlap / queryEntityCount)
+ *
+ * Returns candidates sorted descending by combinedScore. The original
+ * fields (id, text, semanticScore, entities) are preserved alongside
+ * the new combinedScore + entityOverlap.
+ *
+ * The query's entities are extracted via {@link EntityExtractor} so
+ * this ranker is end-to-end self-contained: pass a query string and
+ * candidate list, get a re-ranked list back.
+ *
+ * Reference: docs.mem0.ai/migration/oss-v2-to-v3.
+ *
+ * @module @framers/agentos/memory-router/backends/EntityRetrievalRanker
+ */
+/**
+ * One candidate to be ranked. The bench (or any consumer) passes a
+ * list of these from its hybrid retrieval pool.
+ */
+export interface RankedCandidate {
+    id: string;
+    text: string;
+    /** Pre-computed semantic similarity (cosine, BM25, or a blend). */
+    semanticScore: number;
+    /** Entities extracted at ingest, indexed alongside the chunk. */
+    entities: string[];
+}
+/**
+ * Re-ranked candidate with the combined score + per-candidate
+ * entity-overlap count for diagnostics.
+ */
+export interface RankedCandidateWithBoost extends RankedCandidate {
+    combinedScore: number;
+    entityOverlap: number;
+}
+export interface EntityRetrievalRankerOptions {
+    /**
+     * Weight on the entity-overlap signal in the combined score.
+     * 0 = pure semantic. 1 = pure entity overlap. Mem0-v3 default ~0.5.
+     */
+    entityWeight: number;
+}
+export declare class EntityRetrievalRanker {
+    private readonly entityWeight;
+    private readonly extractor;
+    constructor(opts: EntityRetrievalRankerOptions);
+    rank(query: string, candidates: RankedCandidate[]): RankedCandidateWithBoost[];
+}
+//# sourceMappingURL=EntityRetrievalRanker.d.ts.map

package/dist/memory-router/backends/EntityRetrievalRanker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"EntityRetrievalRanker.d.ts","sourceRoot":"","sources":["../../../src/memory-router/backends/EntityRetrievalRanker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAIH;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,mEAAmE;IACnE,aAAa,EAAE,MAAM,CAAC;IACtB,iEAAiE;IACjE,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED;;;GAGG;AACH,MAAM,WAAW,wBAAyB,SAAQ,eAAe;IAC/D,aAAa,EAAE,MAAM,CAAC;IACtB,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,4BAA4B;IAC3C;;;OAGG;IACH,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,qBAAa,qBAAqB;IAChC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IACtC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAyB;gBAEvC,IAAI,EAAE,4BAA4B;IAI9C,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,eAAe,EAAE,GAAG,wBAAwB,EAAE;CAc/E"}