@claude-flow/memory 3.0.0-alpha.2 → 3.0.0-alpha.21

package/dist/rvf-migration.js

@@ -0,0 +1,254 @@
+/**
+ * RVF Migration Utility — bidirectional migration between RVF and legacy
+ * formats (JSON files, sql.js / better-sqlite3 databases).
+ * @module @claude-flow/memory/rvf-migration
+ */
+import { readFile, writeFile, rename, mkdir } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { RvfBackend } from './rvf-backend.js';
+import { generateMemoryId } from './types.js';
+// -- Internal helpers -------------------------------------------------------
+function fillDefaults(raw) {
+    const now = Date.now();
+    return {
+        id: raw.id ?? generateMemoryId(),
+        key: raw.key ?? '',
+        content: raw.content ?? '',
+        type: raw.type ?? 'semantic',
+        namespace: raw.namespace ?? 'default',
+        tags: raw.tags ?? [],
+        metadata: raw.metadata ?? {},
+        ownerId: raw.ownerId,
+        accessLevel: raw.accessLevel ?? 'private',
+        createdAt: raw.createdAt ?? now,
+        updatedAt: raw.updatedAt ?? now,
+        expiresAt: raw.expiresAt,
+        version: raw.version ?? 1,
+        references: raw.references ?? [],
+        accessCount: raw.accessCount ?? 0,
+        lastAccessedAt: raw.lastAccessedAt ?? now,
+        embedding: deserializeEmbedding(raw.embedding),
+    };
+}
+function deserializeEmbedding(value) {
+    if (!value)
+        return undefined;
+    if (value instanceof Float32Array)
+        return value;
+    if (value instanceof Buffer || value instanceof Uint8Array) {
+        if (value.byteLength === 0)
+            return undefined;
+        const out = new Float32Array(value.byteLength / 4);
+        const view = new DataView(value.buffer, value.byteOffset, value.byteLength);
+        for (let i = 0; i < out.length; i++)
+            out[i] = view.getFloat32(i * 4, true);
+        return out;
+    }
+    if (Array.isArray(value))
+        return new Float32Array(value);
+    return undefined;
+}
+function serializeForJson(entry) {
+    return { ...entry, embedding: entry.embedding ? Array.from(entry.embedding) : undefined };
+}
+function validateMigrationPath(p) {
+    if (!p || typeof p !== 'string')
+        throw new Error('Path must be a non-empty string');
+    if (p.includes('\0'))
+        throw new Error('Path contains null bytes');
+}
+async function ensureDir(filePath) {
+    validateMigrationPath(filePath);
+    const dir = dirname(resolve(filePath));
+    if (!existsSync(dir))
+        await mkdir(dir, { recursive: true });
+}
+async function atomicWrite(targetPath, data) {
+    validateMigrationPath(targetPath);
+    const abs = resolve(targetPath);
+    const tmp = abs + '.tmp.' + Date.now();
+    await ensureDir(abs);
+    await writeFile(tmp, data, typeof data === 'string' ? 'utf-8' : undefined);
+    await rename(tmp, abs);
+}
+function mkResult(success, entriesMigrated, sourceFormat, targetFormat, startMs, errors) {
+    return { success, entriesMigrated, sourceFormat, targetFormat, durationMs: Date.now() - startMs, errors };
+}
+function normalizeSqliteRow(row) {
+    const out = { ...row };
+    for (const col of ['tags', 'metadata', 'references']) {
+        if (typeof out[col] === 'string') {
+            try {
+                out[col] = JSON.parse(out[col]);
+            }
+            catch {
+                out[col] = col === 'metadata' ? {} : [];
+            }
+        }
+    }
+    return out;
+}
+async function readSqliteRows(dbPath) {
+    // Attempt better-sqlite3
+    try {
+        const mod = await import('better-sqlite3');
+        const Database = mod.default ?? mod;
+        const db = new Database(dbPath, { readonly: true });
+        try {
+            return db.prepare('SELECT * FROM memory_entries').all();
+        }
+        finally {
+            db.close();
+        }
+    }
+    catch { /* unavailable */ }
+    // Attempt sql.js
+    try {
+        const mod = await import('sql.js');
+        const SQL = await (mod.default ?? mod)();
+        const db = new SQL.Database(await readFile(dbPath));
+        try {
+            const stmt = db.prepare('SELECT * FROM memory_entries');
+            const rows = [];
+            while (stmt.step())
+                rows.push(stmt.getAsObject());
+            stmt.free();
+            return rows;
+        }
+        finally {
+            db.close();
+        }
+    }
+    catch { /* unavailable */ }
+    throw new Error('Cannot read SQLite: install better-sqlite3 or sql.js');
+}
+// -- Batch migration helper -------------------------------------------------
+async function migrateBatches(items, rvfPath, options, normalize) {
+    const batchSize = options.batchSize ?? 500;
+    const dimensions = options.dimensions ?? 1536;
+    const backend = new RvfBackend({ databasePath: rvfPath, dimensions, verbose: options.verbose });
+    await backend.initialize();
+    let migrated = 0;
+    const errors = [];
+    try {
+        for (let i = 0; i < items.length; i += batchSize) {
+            const batch = items.slice(i, i + batchSize);
+            const entries = [];
+            for (const item of batch) {
+                try {
+                    entries.push(fillDefaults(normalize ? normalize(item) : item));
+                }
+                catch (e) {
+                    errors.push(`Entry ${item.id ?? i}: ${e.message}`);
+                }
+            }
+            if (entries.length > 0) {
+                await backend.bulkInsert(entries);
+                migrated += entries.length;
+            }
+            options.onProgress?.({ current: Math.min(i + batchSize, items.length), total: items.length, phase: 'migrating' });
+        }
+    }
+    finally {
+        await backend.shutdown();
+    }
+    return { migrated, errors };
+}
+/**
+ * Bidirectional migration utility between RVF and legacy memory formats.
+ *
+ * All methods are static — no instantiation required.
+ */
+export class RvfMigrator {
+    /** Migrate a JSON memory file to RVF format. */
+    static async fromJsonFile(jsonPath, rvfPath, options = {}) {
+        const start = Date.now();
+        const raw = await readFile(jsonPath, 'utf-8');
+        let parsed;
+        try {
+            parsed = JSON.parse(raw);
+        }
+        catch (e) {
+            return mkResult(false, 0, 'json', 'rvf', start, [`Invalid JSON: ${e.message}`]);
+        }
+        const items = Array.isArray(parsed) ? parsed : [parsed];
+        const { migrated, errors } = await migrateBatches(items, rvfPath, options);
+        if (options.verbose)
+            console.log(`[RvfMigrator] Migrated ${migrated} entries from JSON to RVF`);
+        return mkResult(errors.length === 0, migrated, 'json', 'rvf', start, errors);
+    }
+    /** Migrate a SQLite (better-sqlite3 / sql.js) database to RVF. */
+    static async fromSqlite(dbPath, rvfPath, options = {}) {
+        const start = Date.now();
+        let rows;
+        try {
+            rows = await readSqliteRows(dbPath);
+        }
+        catch (e) {
+            return mkResult(false, 0, 'sqlite', 'rvf', start, [e.message]);
+        }
+        options.onProgress?.({ current: 0, total: rows.length, phase: 'reading' });
+        const { migrated, errors } = await migrateBatches(rows, rvfPath, options, normalizeSqliteRow);
+        if (options.verbose)
+            console.log(`[RvfMigrator] Migrated ${migrated} entries from SQLite to RVF`);
+        return mkResult(errors.length === 0, migrated, 'sqlite', 'rvf', start, errors);
+    }
+    /** Export an RVF file back to a JSON array (backward compatibility). */
+    static async toJsonFile(rvfPath, jsonPath) {
+        const start = Date.now();
+        const backend = new RvfBackend({ databasePath: rvfPath });
+        await backend.initialize();
+        let entries;
+        try {
+            entries = await backend.query({ type: 'hybrid', limit: Number.MAX_SAFE_INTEGER });
+        }
+        finally {
+            await backend.shutdown();
+        }
+        const warnings = [];
+        if (entries.length === 0)
+            warnings.push('Source RVF file contained no entries');
+        await atomicWrite(jsonPath, JSON.stringify(entries.map(serializeForJson), null, 2));
+        return mkResult(true, entries.length, 'rvf', 'json', start, warnings);
+    }
+    /**
+     * Detect file format by magic bytes.
+     * - RVF\0 (0x52 0x56 0x46 0x00) -> 'rvf'
+     * - SQLi  (0x53 0x51 0x4C 0x69) -> 'sqlite'
+     * - Leading [ or {              -> 'json'
+     */
+    static async detectFormat(filePath) {
+        if (!existsSync(filePath))
+            return 'unknown';
+        const fd = await import('node:fs').then(m => m.promises.open(filePath, 'r'));
+        try {
+            const buf = Buffer.alloc(16);
+            await fd.read(buf, 0, 16, 0);
+            if (buf[0] === 0x52 && buf[1] === 0x56 && buf[2] === 0x46 && buf[3] === 0x00)
+                return 'rvf';
+            if (buf[0] === 0x53 && buf[1] === 0x51 && buf[2] === 0x4C && buf[3] === 0x69)
+                return 'sqlite';
+            const head = buf.toString('utf-8').trimStart();
+            if (head.startsWith('[') || head.startsWith('{'))
+                return 'json';
+            return 'unknown';
+        }
+        finally {
+            await fd.close();
+        }
+    }
+    /** Auto-detect source format and migrate to RVF. */
+    static async autoMigrate(sourcePath, targetRvfPath, options = {}) {
+        const format = await RvfMigrator.detectFormat(sourcePath);
+        if (options.verbose)
+            console.log(`[RvfMigrator] Detected source format: ${format}`);
+        switch (format) {
+            case 'json': return RvfMigrator.fromJsonFile(sourcePath, targetRvfPath, options);
+            case 'sqlite': return RvfMigrator.fromSqlite(sourcePath, targetRvfPath, options);
+            case 'rvf': return { success: true, entriesMigrated: 0, sourceFormat: 'rvf', targetFormat: 'rvf', durationMs: 0, errors: [] };
+            default: return { success: false, entriesMigrated: 0, sourceFormat: 'unknown', targetFormat: 'rvf', durationMs: 0, errors: [`Unrecognized format: ${sourcePath}`] };
+        }
+    }
+}
+//# sourceMappingURL=rvf-migration.js.map

package/dist/rvf-migration.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rvf-migration.js","sourceRoot":"","sources":["../src/rvf-migration.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC;AACtE,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAC7C,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAE9C,OAAO,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAsB9C,8EAA8E;AAE9E,SAAS,YAAY,CAAC,GAA4B;IAChD,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IACvB,OAAO;QACL,EAAE,EAAG,GAAG,CAAC,EAAa,IAAI,gBAAgB,EAAE;QAC5C,GAAG,EAAG,GAAG,CAAC,GAAc,IAAI,EAAE;QAC9B,OAAO,EAAG,GAAG,CAAC,OAAkB,IAAI,EAAE;QACtC,IAAI,EAAG,GAAG,CAAC,IAAmB,IAAI,UAAU;QAC5C,SAAS,EAAG,GAAG,CAAC,SAAoB,IAAI,SAAS;QACjD,IAAI,EAAG,GAAG,CAAC,IAAiB,IAAI,EAAE;QAClC,QAAQ,EAAG,GAAG,CAAC,QAAoC,IAAI,EAAE;QACzD,OAAO,EAAE,GAAG,CAAC,OAA6B;QAC1C,WAAW,EAAG,GAAG,CAAC,WAA2B,IAAI,SAAS;QAC1D,SAAS,EAAG,GAAG,CAAC,SAAoB,IAAI,GAAG;QAC3C,SAAS,EAAG,GAAG,CAAC,SAAoB,IAAI,GAAG;QAC3C,SAAS,EAAE,GAAG,CAAC,SAA+B;QAC9C,OAAO,EAAG,GAAG,CAAC,OAAkB,IAAI,CAAC;QACrC,UAAU,EAAG,GAAG,CAAC,UAAuB,IAAI,EAAE;QAC9C,WAAW,EAAG,GAAG,CAAC,WAAsB,IAAI,CAAC;QAC7C,cAAc,EAAG,GAAG,CAAC,cAAyB,IAAI,GAAG;QACrD,SAAS,EAAE,oBAAoB,CAAC,GAAG,CAAC,SAAS,CAAC;KAC/C,CAAC;AACJ,CAAC;AAED,SAAS,oBAAoB,CAAC,KAAc;IAC1C,IAAI,CAAC,KAAK;QAAE,OAAO,SAAS,CAAC;IAC7B,IAAI,KAAK,YAAY,YAAY;QAAE,OAAO,KAAK,CAAC;IAChD,IAAI,KAAK,YAAY,MAAM,IAAI,KAAK,YAAY,UAAU,EAAE,CAAC;QAC3D,IAAI,KAAK,CAAC,UAAU,KAAK,CAAC;YAAE,OAAO,SAAS,CAAC;QAC7C,MAAM,GAAG,GAAG,IAAI,YAAY,CAAC,KAAK,CAAC,UAAU,GAAG,CAAC,CAAC,CAAC;QACnD,MAAM,IAAI,GAAG,IAAI,QAAQ,CAAC,KAAK,CAAC,MAAM,EAAE,KAAK,CAAC,UAAU,EAAE,KAAK,CAAC,UAAU,CAAC,CAAC;QAC5E,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,GAAG,CAAC,MAAM,EAAE,CAAC,EAAE;YAAE,GAAG,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,UAAU,CAAC,CAAC,GAAG,CAAC,EAAE,IAAI,CAAC,CAAC;QAC3E,OAAO,GAAG,CAAC;IACb,CAAC;IACD,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QAAE,OAAO,IAAI,YAAY,CAAC,KAAiB,CAAC,CAAC;IACrE,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,SAAS,gBAAgB,CAAC,KAAkB;IAC1C,OAAO,EAAE,GAAG,KAAK,EAAE,SAAS,EAAE,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,SAAS,EAAE,CAAC;AAC5F,CAAC;AAED,SAAS,qBAAqB,CAAC,CAAS;IACtC,IAAI,CAAC,CAAC,IAAI,OAAO,CAAC,KAAK,QAAQ;QAAE,MAAM,IAAI,KAAK,CAAC,iCAAiC,CAAC,CAAC;IACpF,IAAI,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,0BAA0B,CAAC,CAAC;AACpE,CAAC;AAED,KAAK,UAAU,SAAS,CAAC,QAAgB;IACvC,qBAAqB,CAAC,QAAQ,CAAC,CAAC;IAChC,MAAM,GAAG,GAAG,OAAO,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC;IACvC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC;QAAE,MAAM,KAAK,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;AAC9D,CAAC;AAED,KAAK,UAAU,WAAW,CAAC,UAAkB,EAAE,IAAqB;IAClE,qBAAqB,CAAC,UAAU,CAAC,CAAC;IAClC,MAAM,GAAG,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;IAChC,MAAM,GAAG,GAAG,GAAG,GAAG,OAAO,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IACvC,MAAM,SAAS,CAAC,GAAG,CAAC,CAAC;IACrB,MAAM,SAAS,CAAC,GAAG,EAAE,IAAI,EAAE,OAAO,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;IAC3E,MAAM,MAAM,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;AACzB,CAAC;AAED,SAAS,QAAQ,CACf,OAAgB,EAAE,eAAuB,EAAE,YAAoB,EAC/D,YAAoB,EAAE,OAAe,EAAE,MAAgB;IAEvD,OAAO,EAAE,OAAO,EAAE,eAAe,EAAE,YAAY,EAAE,YAAY,EAAE,UAAU,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,OAAO,EAAE,MAAM,EAAE,CAAC;AAC5G,CAAC;AAED,SAAS,kBAAkB,CAAC,GAA4B;IACtD,MAAM,GAAG,GAA4B,EAAE,GAAG,GAAG,EAAE,CAAC;IAChD,KAAK,MAAM,GAAG,IAAI,CAAC,MAAM,EAAE,UAAU,EAAE,YAAY,CAAU,EAAE,CAAC;QAC9D,IAAI,OAAO,GAAG,CAAC,GAAG,CAAC,KAAK,QAAQ,EAAE,CAAC;YACjC,IAAI,CAAC;gBAAC,GAAG,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAW,CAAC,CAAC;YAAC,CAAC;YAAC,MAAM,CAAC;gBAAC,GAAG,CAAC,GAAG,CAAC,GAAG,GAAG,KAAK,UAAU,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAAC,CAAC;QACvG,CAAC;IACH,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAMD,KAAK,UAAU,cAAc,CAAC,MAAc;IAC1C,yBAAyB;IACzB,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,MAAM,MAAM,CAAC,gBAA0B,CAAC,CAAC;QACrD,MAAM,QAAQ,GAAG,GAAG,CAAC,OAAO,IAAI,GAAG,CAAC;QACpC,MAAM,EAAE,GAAG,IAAI,QAAQ,CAAC,MAAM,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC;QACpD,IAAI,CAAC;YAAC,OAAO,EAAE,CAAC,OAAO,CAAC,8BAA8B,CAAC,CAAC,GAAG,EAAiB,CAAC;QAAC,CAAC;gBACvE,CAAC;YAAC,EAAE,CAAC,KAAK,EAAE,CAAC;QAAC,CAAC;IACzB,CAAC;IAAC,MAAM,CAAC,CAAC,iBAAiB,CAAC,CAAC;IAC7B,iBAAiB;IACjB,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,MAAM,MAAM,CAAC,QAAkB,CAAC,CAAC;QAC7C,MAAM,GAAG,GAAG,MAAM,CAAC,GAAG,CAAC,OAAO,IAAI,GAAG,CAAC,EAAE,CAAC;QACzC,MAAM,EAAE,GAAG,IAAI,GAAG,CAAC,QAAQ,CAAC,MAAM,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC;QACpD,IAAI,CAAC;YACH,MAAM,IAAI,GAAG,EAAE,CAAC,OAAO,CAAC,8BAA8B,CAAC,CAAC;YACxD,MAAM,IAAI,GAAgB,EAAE,CAAC;YAC7B,OAAO,IAAI,CAAC,IAAI,EAAE;gBAAE,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,WAAW,EAAe,CAAC,CAAC;YAC/D,IAAI,CAAC,IAAI,EAAE,CAAC;YACZ,OAAO,IAAI,CAAC;QACd,CAAC;gBAAS,CAAC;YAAC,EAAE,CAAC,KAAK,EAAE,CAAC;QAAC,CAAC;IAC3B,CAAC;IAAC,MAAM,CAAC,CAAC,iBAAiB,CAAC,CAAC;IAC7B,MAAM,IAAI,KAAK,CAAC,sDAAsD,CAAC,CAAC;AAC1E,CAAC;AAED,8EAA8E;AAE9E,KAAK,UAAU,cAAc,CAC3B,KAAgC,EAChC,OAAe,EACf,OAA4B,EAC5B,SAAmE;IAEnE,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,IAAI,GAAG,CAAC;IAC3C,MAAM,UAAU,GAAG,OAAO,CAAC,UAAU,IAAI,IAAI,CAAC;IAC9C,MAAM,OAAO,GAAG,IAAI,UAAU,CAAC,EAAE,YAAY,EAAE,OAAO,EAAE,UAAU,EAAE,OAAO,EAAE,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC;IAChG,MAAM,OAAO,CAAC,UAAU,EAAE,CAAC;IAC3B,IAAI,QAAQ,GAAG,CAAC,CAAC;IACjB,MAAM,MAAM,GAAa,EAAE,CAAC;IAC5B,IAAI,CAAC;QACH,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,IAAI,SAAS,EAAE,CAAC;YACjD,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,GAAG,SAAS,CAAC,CAAC;YAC5C,MAAM,OAAO,GAAkB,EAAE,CAAC;YAClC,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;gBACzB,IAAI,CAAC;oBACH,OAAO,CAAC,IAAI,CAAC,YAAY,CAAC,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;gBACjE,CAAC;gBAAC,OAAO,CAAC,EAAE,CAAC;oBAAC,MAAM,CAAC,IAAI,CAAC,SAAS,IAAI,CAAC,EAAE,IAAI,CAAC,KAAM,CAAW,CAAC,OAAO,EAAE,CAAC,CAAC;gBAAC,CAAC;YAChF,CAAC;YACD,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBAAC,MAAM,OAAO,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC;gBAAC,QAAQ,IAAI,OAAO,CAAC,MAAM,CAAC;YAAC,CAAC;YAC1F,OAAO,CAAC,UAAU,EAAE,CAAC,EAAE,OAAO,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,SAAS,EAAE,KAAK,CAAC,MAAM,CAAC,EAAE,KAAK,EAAE,KAAK,CAAC,MAAM,EAAE,KAAK,EAAE,WAAW,EAAE,CAAC,CAAC;QACpH,CAAC;IACH,CAAC;YAAS,CAAC;QAAC,MAAM,OAAO,CAAC,QAAQ,EAAE,CAAC;IAAC,CAAC;IACvC,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,CAAC;AAC9B,CAAC;AAED;;;;GAIG;AACH,MAAM,OAAO,WAAW;IACtB,gDAAgD;IAChD,MAAM,CAAC,KAAK,CAAC,YAAY,CACvB,QAAgB,EAAE,OAAe,EAAE,UAA+B,EAAE;QAEpE,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QACzB,MAAM,GAAG,GAAG,MAAM,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;QAC9C,IAAI,MAAe,CAAC;QACpB,IAAI,CAAC;YAAC,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QAAC,CAAC;QACjC,OAAO,CAAC,EAAE,CAAC;YAAC,OAAO,QAAQ,CAAC,KAAK,EAAE,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,iBAAkB,CAAW,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC;QAAC,CAAC;QACzG,MAAM,KAAK,GAAG,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAiC,CAAC,CAAC;QACnF,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,MAAM,cAAc,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;QAC3E,IAAI,OAAO,CAAC,OAAO;YAAE,OAAO,CAAC,GAAG,CAAC,0BAA0B,QAAQ,2BAA2B,CAAC,CAAC;QAChG,OAAO,QAAQ,CAAC,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,CAAC,CAAC;IAC/E,CAAC;IAED,kEAAkE;IAClE,MAAM,CAAC,KAAK,CAAC,UAAU,CACrB,MAAc,EAAE,OAAe,EAAE,UAA+B,EAAE;QAElE,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QACzB,IAAI,IAAiB,CAAC;QACtB,IAAI,CAAC;YAAC,IAAI,GAAG,MAAM,cAAc,CAAC,MAAM,CAAC,CAAC;QAAC,CAAC;QAC5C,OAAO,CAAC,EAAE,CAAC;YAAC,OAAO,QAAQ,CAAC,KAAK,EAAE,CAAC,EAAE,QAAQ,EAAE,KAAK,EAAE,KAAK,EAAE,CAAE,CAAW,CAAC,OAAO,CAAC,CAAC,CAAC;QAAC,CAAC;QACxF,OAAO,CAAC,UAAU,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,KAAK,EAAE,IAAI,CAAC,MAAM,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC,CAAC;QAC3E,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,MAAM,cAAc,CAAC,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,kBAAkB,CAAC,CAAC;QAC9F,IAAI,OAAO,CAAC,OAAO;YAAE,OAAO,CAAC,GAAG,CAAC,0BAA0B,QAAQ,6BAA6B,CAAC,CAAC;QAClG,OAAO,QAAQ,CAAC,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,QAAQ,EAAE,QAAQ,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,CAAC,CAAC;IACjF,CAAC;IAED,wEAAwE;IACxE,MAAM,CAAC,KAAK,CAAC,UAAU,CAAC,OAAe,EAAE,QAAgB;QACvD,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QACzB,MAAM,OAAO,GAAG,IAAI,UAAU,CAAC,EAAE,YAAY,EAAE,OAAO,EAAE,CAAC,CAAC;QAC1D,MAAM,OAAO,CAAC,UAAU,EAAE,CAAC;QAC3B,IAAI,OAAsB,CAAC;QAC3B,IAAI,CAAC;YAAC,OAAO,GAAG,MAAM,OAAO,CAAC,KAAK,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,CAAC,gBAAgB,EAAE,CAAC,CAAC;QAAC,CAAC;gBAClF,CAAC;YAAC,MAAM,OAAO,CAAC,QAAQ,EAAE,CAAC;QAAC,CAAC;QACrC,MAAM,QAAQ,GAAa,EAAE,CAAC;QAC9B,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;YAAE,QAAQ,CAAC,IAAI,CAAC,sCAAsC,CAAC,CAAC;QAChF,MAAM,WAAW,CAAC,QAAQ,EAAE,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,GAAG,CAAC,gBAAgB,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;QACpF,OAAO,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,QAAQ,CAAC,CAAC;IACxE,CAAC;IAED;;;;;OAKG;IACH,MAAM,CAAC,KAAK,CAAC,YAAY,CAAC,QAAgB;QACxC,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC;YAAE,OAAO,SAAS,CAAC;QAC5C,MAAM,EAAE,GAAG,MAAM,MAAM,CAAC,SAAS,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC,CAAC;QAC7E,IAAI,CAAC;YACH,MAAM,GAAG,GAAG,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;YAC7B,MAAM,EAAE,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC;YAC7B,IAAI,GAAG,CAAC,CAAC,CAAC,KAAK,IAAI,IAAI,GAAG,CAAC,CAAC,CAAC,KAAK,IAAI,IAAI,GAAG,CAAC,CAAC,CAAC,KAAK,IAAI,IAAI,GAAG,CAAC,CAAC,CAAC,KAAK,IAAI;gBAAE,OAAO,KAAK,CAAC;YAC3F,IAAI,GAAG,CAAC,CAAC,CAAC,KAAK,IAAI,IAAI,GAAG,CAAC,CAAC,CAAC,KAAK,IAAI,IAAI,GAAG,CAAC,CAAC,CAAC,KAAK,IAAI,IAAI,GAAG,CAAC,CAAC,CAAC,KAAK,IAAI;gBAAE,OAAO,QAAQ,CAAC;YAC9F,MAAM,IAAI,GAAG,GAAG,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,SAAS,EAAE,CAAC;YAC/C,IAAI,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC;gBAAE,OAAO,MAAM,CAAC;YAChE,OAAO,SAAS,CAAC;QACnB,CAAC;gBAAS,CAAC;YAAC,MAAM,EAAE,CAAC,KAAK,EAAE,CAAC;QAAC,CAAC;IACjC,CAAC;IAED,oDAAoD;IACpD,MAAM,CAAC,KAAK,CAAC,WAAW,CACtB,UAAkB,EAAE,aAAqB,EAAE,UAA+B,EAAE;QAE5E,MAAM,MAAM,GAAG,MAAM,WAAW,CAAC,YAAY,CAAC,UAAU,CAAC,CAAC;QAC1D,IAAI,OAAO,CAAC,OAAO;YAAE,OAAO,CAAC,GAAG,CAAC,yCAAyC,MAAM,EAAE,CAAC,CAAC;QACpF,QAAQ,MAAM,EAAE,CAAC;YACf,KAAK,MAAM,CAAC,CAAG,OAAO,WAAW,CAAC,YAAY,CAAC,UAAU,EAAE,aAAa,EAAE,OAAO,CAAC,CAAC;YACnF,KAAK,QAAQ,CAAC,CAAC,OAAO,WAAW,CAAC,UAAU,CAAC,UAAU,EAAE,aAAa,EAAE,OAAO,CAAC,CAAC;YACjF,KAAK,KAAK,CAAC,CAAI,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,eAAe,EAAE,CAAC,EAAE,YAAY,EAAE,KAAK,EAAE,YAAY,EAAE,KAAK,EAAE,UAAU,EAAE,CAAC,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC;YACjI,OAAO,CAAC,CAAO,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,eAAe,EAAE,CAAC,EAAE,YAAY,EAAE,SAAS,EAAE,YAAY,EAAE,KAAK,EAAE,UAAU,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,wBAAwB,UAAU,EAAE,CAAC,EAAE,CAAC;QAC5K,CAAC;IACH,CAAC;CACF"}

package/dist/smart-retrieval.d.ts

@@ -0,0 +1,118 @@
+/**
+ * SmartRetrieval — LongMemEval-derived retrieval pipeline (ADR-090)
+ *
+ * Wraps a raw HNSW `SearchFn` with the optimizations identified by the
+ * ADR-088 LongMemEval benchmark:
+ *
+ *   1. Query expansion (template-based, no LLM)
+ *   2. Multi-query fan-out + Reciprocal Rank Fusion
+ *   3. Recency boost from metadata timestamps
+ *   4. MMR diversity re-ranking (token-Jaccard proxy)
+ *   5. Session round-robin for multi-session coverage
+ *
+ * The module is pluggable: callers provide a `SearchFn` that hits whatever
+ * raw store they use (AgentDB HNSW, sql.js, a test fake, etc.). That keeps
+ * `@claude-flow/memory` free of a hard dependency on the CLI's memory-initializer
+ * and makes the pipeline easy to benchmark in isolation.
+ */
+export interface SearchCandidate {
+    id: string;
+    key: string;
+    content: string;
+    score: number;
+    namespace: string;
+    /** Optional metadata pulled through from the underlying store. */
+    metadata?: Record<string, unknown>;
+    /** Optional unix-ms timestamp used by the recency booster. */
+    createdAt?: number;
+    /** Optional unix-ms timestamp; preferred over createdAt when present. */
+    updatedAt?: number;
+}
+export interface RawSearchRequest {
+    query: string;
+    namespace?: string;
+    limit?: number;
+    threshold?: number;
+}
+export interface RawSearchResponse {
+    results: SearchCandidate[];
+}
+/** Pluggable raw search function — typically wraps HNSW or a test fake. */
+export type SearchFn = (req: RawSearchRequest) => Promise<RawSearchResponse>;
+export interface SmartSearchOptions {
+    query: string;
+    namespace?: string;
+    /** Final number of results to return (default 10). */
+    limit?: number;
+    /** Similarity floor applied to the raw store (default 0.3). */
+    threshold?: number;
+    /** Fan out 2-3 expanded query variants and fuse with RRF. Default: true. */
+    multiQuery?: boolean;
+    /** Re-score with recency boost using entry timestamps. Default: true. */
+    recencyBoost?: boolean;
+    /** Apply MMR diversity re-ranking. Default: true. */
+    diversityMMR?: boolean;
+    /** Round-robin across distinct session_ids. Default: true. */
+    sessionDiversity?: boolean;
+    /** How many candidates to pull from the raw store per variant (default limit × 3). */
+    fanOutK?: number;
+    /** RRF constant; 60 is the standard default. */
+    rrfK?: number;
+    /** Recency half-life in days; older entries decay past this. Default 30. */
+    recencyHalfLifeDays?: number;
+    /** Max recency multiplier applied to top of the curve. Default 0.2. */
+    recencyWeight?: number;
+    /** MMR tradeoff λ — 1.0 = pure relevance, 0.0 = pure diversity. Default 0.7. */
+    mmrLambda?: number;
+    /** Metadata key that identifies a session for round-robin. Default 'session_id'. */
+    sessionKey?: string;
+    /** "Now" for recency decay — pass a fixed value in tests for determinism. */
+    now?: number;
+    /** Override the default template-based expansions with your own set. */
+    queryExpansions?: (query: string) => string[];
+}
+export interface SmartSearchStats {
+    variantCount: number;
+    variants: string[];
+    rawCandidateCount: number;
+    afterRrfCount: number;
+    afterRecencyCount: number;
+    afterMmrCount: number;
+    afterSessionCount: number;
+    durationMs: number;
+}
+export interface SmartSearchResult {
+    results: SearchCandidate[];
+    stats: SmartSearchStats;
+}
+/**
+ * Default query expansion set. Keeps variants cheap (≤3) so we only pay
+ * ~3× the HNSW cost on the hot path.
+ */
+export declare function defaultQueryExpansions(query: string): string[];
+/**
+ * Public-facing Reciprocal Rank Fusion. Takes any number of pre-sorted
+ * candidate lists (best-first) and fuses them with the RRF score
+ * `sum(1 / (k + rank_i))`. Used by the ADR-125 Phase 5 hybridSearch
+ * controller to fuse dense + sparse arms.
+ */
+export declare function applyRRF<T extends SearchCandidate>(rankedLists: T[][], k?: number): Array<{
+    candidate: T;
+    score: number;
+}>;
+/**
+ * Public-facing MMR rerank.
+ *
+ * Re-exported as `applyMMR` for ADR-125 Phase 5 callers (the hybridSearch
+ * controller). Takes already-scored candidates plus an MMR lambda
+ * (1.0 = pure relevance, 0.0 = pure diversity).
+ */
+export declare function applyMMR<T extends SearchCandidate>(scored: Array<{
+    candidate: T;
+    score: number;
+}>, lambda?: number, limit?: number): Array<{
+    candidate: T;
+    score: number;
+}>;
+export declare function smartSearch(search: SearchFn, opts: SmartSearchOptions): Promise<SmartSearchResult>;
+//# sourceMappingURL=smart-retrieval.d.ts.map

package/dist/smart-retrieval.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"smart-retrieval.d.ts","sourceRoot":"","sources":["../src/smart-retrieval.ts"],"names":[],"mappings":"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"}