moflo 4.0.3 → 4.0.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "moflo",
-  "version": "4.0.3",
+  "version": "4.0.4",
   "description": "MoFlo — AI agent orchestration for Claude Code. Forked from ruflo/claude-flow with patches applied to source, plus feature-level orchestration.",
   "main": "dist/index.js",
   "type": "module",

package/v3/@claude-flow/cli/dist/src/commands/hooks.js

@@ -59,7 +59,8 @@ const preEditCommand = {
         output.printInfo(`Analyzing context for: ${output.highlight(filePath)}`);
         try {
             // Call MCP tool for pre-edit hook
-            const result = await callMCPTool('hooks_pre-edit', {
+            // Wrap MCP call in timeout to prevent indefinite hang (#13)
+            const mcpPromise = callMCPTool('hooks_pre-edit', {
                 filePath,
                 operation,
                 context: ctx.flags.context,
@@ -183,6 +184,8 @@ const postEditCommand = {
                 metrics,
                 timestamp: Date.now(),
             });
+            const timeoutPromise = new Promise((_, reject) => setTimeout(() => reject(new Error('session-end timed out after 3s')), 3000));
+            const result = await Promise.race([mcpPromise, timeoutPromise]);
             if (ctx.flags.format === 'json') {
                 output.printJson(result);
                 return { success: true, data: result };

package/v3/@claude-flow/cli/dist/src/memory/memory-bridge.js

@@ -17,11 +17,10 @@
  * @module v3/cli/memory-bridge
  */
 import * as path from 'path';
-import * as fs from 'fs';
 import * as crypto from 'crypto';
-import { createRequire } from 'module';
-import { pathToFileURL } from 'url';
-// Project root resolution — handles npx running from node_modules/moflo
+// ===== Project root resolution =====
+// When run via npx, CWD may be node_modules/moflo — walk up to find actual project
+import * as fs from 'fs';
 let _projectRoot;
 function getProjectRoot() {
     if (_projectRoot)
@@ -41,11 +40,41 @@ function getProjectRoot() {
             _projectRoot = dir;
             return _projectRoot;
         }
+        // Skip node_modules directories
+        if (path.basename(dir) === 'node_modules') {
+            dir = path.dirname(dir);
+            continue;
+        }
         dir = path.dirname(dir);
     }
     _projectRoot = process.cwd();
     return _projectRoot;
 }
+// ===== Transformers.js fallback embedder =====
+let _tfEmbedder = null;
+let _tfFailed = false;
+async function getFallbackEmbedder() {
+    if (_tfFailed)
+        return null;
+    if (_tfEmbedder)
+        return _tfEmbedder;
+    try {
+        const { pipeline } = await import('@xenova/transformers');
+        _tfEmbedder = await pipeline('feature-extraction', 'Xenova/all-MiniLM-L6-v2');
+        return _tfEmbedder;
+    }
+    catch {
+        _tfFailed = true;
+        return null;
+    }
+}
+async function fallbackEmbed(text) {
+    const embedder = await getFallbackEmbedder();
+    if (!embedder)
+        return null;
+    const result = await embedder(text, { pooling: 'mean', normalize: true });
+    return Array.from(result.data);
+}
 // ===== Lazy singleton =====
 let registryPromise = null;
 let registryInstance = null;
@@ -56,15 +85,15 @@ let bridgeAvailable = null;
  * or the special ':memory:' path.
  */
 function getDbPath(customPath) {
-    const projectRoot = getProjectRoot();
-    const swarmDir = path.resolve(projectRoot, '.swarm');
+    const swarmDir = path.resolve(getProjectRoot(), '.swarm');
     if (!customPath)
         return path.join(swarmDir, 'memory.db');
     if (customPath === ':memory:')
         return ':memory:';
     const resolved = path.resolve(customPath);
-    // Ensure the path doesn't escape the project directory
-    if (!resolved.startsWith(projectRoot)) {
+    // Ensure the path doesn't escape the working directory
+    const cwd = getProjectRoot();
+    if (!resolved.startsWith(cwd)) {
         return path.join(swarmDir, 'memory.db'); // fallback to safe default
     }
     return resolved;
@@ -76,10 +105,8 @@ function generateId(prefix) {
     return `${prefix}_${Date.now()}_${crypto.randomBytes(8).toString('hex')}`;
 }
 /**
- * Lazily initialize the ControllerRegistry singleton via @claude-flow/memory.
- * Falls back to direct agentdb import if @claude-flow/memory is unavailable.
- * The registry exposes .get(name), .getAgentDB(), .listControllers(), and .initialize()
- * to maintain compatibility with all bridge consumers.
+ * Lazily initialize the ControllerRegistry singleton.
+ * Returns null if @claude-flow/memory is not available.
  */
 async function getRegistry(dbPath) {
     if (bridgeAvailable === false)
@@ -89,81 +116,13 @@ async function getRegistry(dbPath) {
     if (!registryPromise) {
         registryPromise = (async () => {
             try {
-                // Try @claude-flow/memory ControllerRegistry first (bundled in moflo)
-                let memoryModule = null;
-                const memoryRelPath = '../../../../memory/dist/index.js';
-                try {
-                    memoryModule = await import(memoryRelPath);
-                }
-                catch {
-                    try {
-                        const req = createRequire(path.join(getProjectRoot(), 'package.json'));
-                        const resolved = req.resolve('@claude-flow/memory');
-                        memoryModule = await import(pathToFileURL(resolved).href);
-                    }
-                    catch {
-                        // @claude-flow/memory not available
-                    }
-                }
-                // If @claude-flow/memory has ControllerRegistry, use it directly
-                if (memoryModule?.ControllerRegistry) {
-                    const { ControllerRegistry } = memoryModule;
-                    const registry = new ControllerRegistry();
-                    // Suppress noisy console.log during init
-                    const origLog = console.log;
-                    console.log = (...args) => {
-                        const msg = String(args[0] ?? '');
-                        if (msg.includes('Transformers.js') ||
-                            msg.includes('better-sqlite3') ||
-                            msg.includes('[AgentDB]') ||
-                            msg.includes('[HNSWLibBackend]') ||
-                            msg.includes('RuVector graph'))
-                            return;
-                        origLog.apply(console, args);
-                    };
-                    try {
-                        await registry.initialize({
-                            dbPath: dbPath || getDbPath(),
-                            dimension: 384,
-                        });
-                    }
-                    finally {
-                        console.log = origLog;
-                    }
-                    registryInstance = registry;
-                    return registry;
-                }
-                // Fallback: direct agentdb import with manual adapter
-                let agentdbModule = null;
-                try {
-                    agentdbModule = await import('agentdb');
-                }
-                catch {
-                    try {
-                        const req = createRequire(path.join(getProjectRoot(), 'package.json'));
-                        const resolved = req.resolve('agentdb');
-                        agentdbModule = await import(pathToFileURL(resolved).href);
-                    }
-                    catch {
-                        // Not available
-                    }
-                }
-                if (!agentdbModule) {
-                    bridgeAvailable = false;
-                    registryPromise = null;
-                    return null;
-                }
-                const { AgentDB } = agentdbModule;
-                const agentdb = new AgentDB({
-                    dbPath: dbPath || getDbPath(),
-                    dimension: 384,
-                });
+                const { ControllerRegistry } = await import('@claude-flow/memory');
+                const registry = new ControllerRegistry();
                 // Suppress noisy console.log during init
                 const origLog = console.log;
                 console.log = (...args) => {
                     const msg = String(args[0] ?? '');
                     if (msg.includes('Transformers.js') ||
-                        msg.includes('better-sqlite3') ||
                         msg.includes('[AgentDB]') ||
                         msg.includes('[HNSWLibBackend]') ||
                         msg.includes('RuVector graph'))
@@ -171,38 +130,22 @@ async function getRegistry(dbPath) {
                     origLog.apply(console, args);
                 };
                 try {
-                    await agentdb.initialize();
+                    await registry.initialize({
+                        dbPath: dbPath || getDbPath(),
+                        dimension: 384,
+                        controllers: {
+                            reasoningBank: true,
+                            learningBridge: false,
+                            tieredCache: true,
+                            hierarchicalMemory: true,
+                            memoryConsolidation: true,
+                            memoryGraph: true, // issue #1214: enable MemoryGraph for graph-aware ranking
+                        },
+                    });
                 }
                 finally {
                     console.log = origLog;
                 }
-                // Build a registry-compatible adapter over AgentDB
-                const registry = {
-                    _agentdb: agentdb,
-                    get(name) {
-                        try {
-                            return agentdb.getController(name);
-                        }
-                        catch {
-                            return null;
-                        }
-                    },
-                    getAgentDB() {
-                        return agentdb;
-                    },
-                    listControllers() {
-                        return [
-                            'reflexion', 'skills', 'reasoningBank',
-                            'causalGraph', 'causalRecall', 'learningSystem',
-                            'explainableRecall', 'nightlyLearner',
-                            'graphTransformer', 'mutationGuard',
-                            'attestationLog', 'vectorBackend'
-                        ].filter(name => {
-                            try { return agentdb.getController(name) != null; }
-                            catch { return false; }
-                        });
-                    },
-                };
                 registryInstance = registry;
                 bridgeAvailable = true;
                 return registry;
@@ -352,25 +295,25 @@ function getDb(registry) {
     const db = agentdb.database;
     // Ensure memory_entries table exists (idempotent)
     try {
-        db.exec(`CREATE TABLE IF NOT EXISTS memory_entries (
-      id TEXT PRIMARY KEY,
-      key TEXT NOT NULL,
-      namespace TEXT DEFAULT 'default',
-      content TEXT NOT NULL,
-      type TEXT DEFAULT 'semantic',
-      embedding TEXT,
-      embedding_model TEXT DEFAULT 'local',
-      embedding_dimensions INTEGER,
-      tags TEXT,
-      metadata TEXT,
-      owner_id TEXT,
-      created_at INTEGER NOT NULL DEFAULT (strftime('%s', 'now') * 1000),
-      updated_at INTEGER NOT NULL DEFAULT (strftime('%s', 'now') * 1000),
-      expires_at INTEGER,
-      last_accessed_at INTEGER,
-      access_count INTEGER DEFAULT 0,
-      status TEXT DEFAULT 'active',
-      UNIQUE(namespace, key)
+        db.exec(`CREATE TABLE IF NOT EXISTS memory_entries (
+      id TEXT PRIMARY KEY,
+      key TEXT NOT NULL,
+      namespace TEXT DEFAULT 'default',
+      content TEXT NOT NULL,
+      type TEXT DEFAULT 'semantic',
+      embedding TEXT,
+      embedding_model TEXT DEFAULT 'local',
+      embedding_dimensions INTEGER,
+      tags TEXT,
+      metadata TEXT,
+      owner_id TEXT,
+      created_at INTEGER NOT NULL DEFAULT (strftime('%s', 'now') * 1000),
+      updated_at INTEGER NOT NULL DEFAULT (strftime('%s', 'now') * 1000),
+      expires_at INTEGER,
+      last_accessed_at INTEGER,
+      access_count INTEGER DEFAULT 0,
+      status TEXT DEFAULT 'active',
+      UNIQUE(namespace, key)
     )`);
         // Ensure indexes
         db.exec(`CREATE INDEX IF NOT EXISTS idx_bridge_ns ON memory_entries(namespace)`);
@@ -424,17 +367,17 @@ export async function bridgeStoreEntry(options) {
                 // Embedding failed — store without
             }
         }
-        // better-sqlite3 uses synchronous .run() with positional params
+        // sql.js uses synchronous .run() with positional params
         const insertSql = options.upsert
-            ? `INSERT OR REPLACE INTO memory_entries (
-          id, key, namespace, content, type,
-          embedding, embedding_dimensions, embedding_model,
-          tags, metadata, created_at, updated_at, expires_at, status
+            ? `INSERT OR REPLACE INTO memory_entries (
+          id, key, namespace, content, type,
+          embedding, embedding_dimensions, embedding_model,
+          tags, metadata, created_at, updated_at, expires_at, status
         ) VALUES (?, ?, ?, ?, 'semantic', ?, ?, ?, ?, ?, ?, ?, ?, 'active')`
-            : `INSERT INTO memory_entries (
-          id, key, namespace, content, type,
-          embedding, embedding_dimensions, embedding_model,
-          tags, metadata, created_at, updated_at, expires_at, status
+            : `INSERT INTO memory_entries (
+          id, key, namespace, content, type,
+          embedding, embedding_dimensions, embedding_model,
+          tags, metadata, created_at, updated_at, expires_at, status
         ) VALUES (?, ?, ?, ?, 'semantic', ?, ?, ?, ?, ?, ?, ?, ?, 'active')`;
         const stmt = ctx.db.prepare(insertSql);
         stmt.run(id, key, namespace, value, embeddingJson, dimensions || null, model, tags.length > 0 ? JSON.stringify(tags) : null, '{}', now, now, ttl ? now + (ttl * 1000) : null);
@@ -485,17 +428,17 @@ export async function bridgeSearchEntries(options) {
         catch {
             // Fall back to keyword search
         }
-        // better-sqlite3: .prepare().all() returns array of objects
+        // Prepare/all returns array of objects
         const nsFilter = namespace !== 'all'
             ? `AND namespace = ?`
             : '';
         let rows;
         try {
-            const stmt = ctx.db.prepare(`
-        SELECT id, key, namespace, content, embedding
-        FROM memory_entries
-        WHERE status = 'active' ${nsFilter}
-        LIMIT 1000
+            const stmt = ctx.db.prepare(`
+        SELECT id, key, namespace, content, embedding
+        FROM memory_entries
+        WHERE status = 'active' ${nsFilter}
+        LIMIT 1000
       `);
             rows = namespace !== 'all' ? stmt.all(namespace) : stmt.all();
         }
@@ -585,12 +528,12 @@ export async function bridgeListEntries(options) {
         // List
         const entries = [];
         try {
-            const stmt = ctx.db.prepare(`
-        SELECT id, key, namespace, content, embedding, access_count, created_at, updated_at
-        FROM memory_entries
-        WHERE status = 'active' ${nsFilter}
-        ORDER BY updated_at DESC
-        LIMIT ? OFFSET ?
+            const stmt = ctx.db.prepare(`
+        SELECT id, key, namespace, content, embedding, access_count, created_at, updated_at
+        FROM memory_entries
+        WHERE status = 'active' ${nsFilter}
+        ORDER BY updated_at DESC
+        LIMIT ? OFFSET ?
       `);
             const rows = stmt.all(...nsParams, limit, offset);
             for (const row of rows) {
@@ -653,11 +596,11 @@ export async function bridgeGetEntry(options) {
         }
         let row;
         try {
-            const stmt = ctx.db.prepare(`
-        SELECT id, key, namespace, content, embedding, access_count, created_at, updated_at, tags
-        FROM memory_entries
-        WHERE status = 'active' AND key = ? AND namespace = ?
-        LIMIT 1
+            const stmt = ctx.db.prepare(`
+        SELECT id, key, namespace, content, embedding, access_count, created_at, updated_at, tags
+        FROM memory_entries
+        WHERE status = 'active' AND key = ? AND namespace = ?
+        LIMIT 1
       `);
             row = stmt.get(key, namespace);
         }
@@ -721,10 +664,10 @@ export async function bridgeDeleteEntry(options) {
         // Soft delete using parameterized query
         let changes = 0;
         try {
-            const result = ctx.db.prepare(`
-        UPDATE memory_entries
-        SET status = 'deleted', updated_at = ?
-        WHERE key = ? AND namespace = ? AND status = 'active'
+            const result = ctx.db.prepare(`
+        UPDATE memory_entries
+        SET status = 'deleted', updated_at = ?
+        WHERE key = ? AND namespace = ? AND status = 'active'
       `).run(Date.now(), key, namespace);
             changes = result?.changes ?? 0;
         }
@@ -869,11 +812,11 @@ export async function bridgeSearchHNSW(queryEmbedding, options, dbPath) {
             : '';
         let rows;
         try {
-            const stmt = ctx.db.prepare(`
-        SELECT id, key, namespace, content, embedding
-        FROM memory_entries
-        WHERE status = 'active' AND embedding IS NOT NULL ${nsFilter}
-        LIMIT 10000
+            const stmt = ctx.db.prepare(`
+        SELECT id, key, namespace, content, embedding
+        FROM memory_entries
+        WHERE status = 'active' AND embedding IS NOT NULL ${nsFilter}
+        LIMIT 10000
       `);
             rows = nsFilter
                 ? stmt.all(options.namespace)
@@ -925,12 +868,12 @@ export async function bridgeAddToHNSW(id, embedding, entry, dbPath) {
     try {
         const now = Date.now();
         const embeddingJson = JSON.stringify(embedding);
-        ctx.db.prepare(`
-      INSERT OR REPLACE INTO memory_entries (
-        id, key, namespace, content, type,
-        embedding, embedding_dimensions, embedding_model,
-        created_at, updated_at, status
-      ) VALUES (?, ?, ?, ?, 'semantic', ?, ?, 'Xenova/all-MiniLM-L6-v2', ?, ?, 'active')
+        ctx.db.prepare(`
+      INSERT OR REPLACE INTO memory_entries (
+        id, key, namespace, content, type,
+        embedding, embedding_dimensions, embedding_model,
+        created_at, updated_at, status
+      ) VALUES (?, ?, ?, ?, 'semantic', ?, ?, 'Xenova/all-MiniLM-L6-v2', ?, ?, 'active')
     `).run(id, entry.key, entry.namespace, entry.content, embeddingJson, embedding.length, now, now);
         return true;
     }
@@ -1198,9 +1141,9 @@ export async function bridgeRecordCausalEdge(options) {
         const ctx = getDb(registry);
         if (ctx) {
             try {
-                ctx.db.prepare(`
-          INSERT OR REPLACE INTO memory_entries (id, key, namespace, content, type, created_at, updated_at, status)
-          VALUES (?, ?, 'causal-edges', ?, 'procedural', ?, ?, 'active')
+                ctx.db.prepare(`
+          INSERT OR REPLACE INTO memory_entries (id, key, namespace, content, type, created_at, updated_at, status)
+          VALUES (?, ?, 'causal-edges', ?, 'procedural', ?, ?, 'active')
         `).run(generateId('edge'), `${options.sourceId}→${options.targetId}`, JSON.stringify(options), Date.now(), Date.now());
                 return { success: true, controller: 'bridge-fallback' };
             }

package/v3/@claude-flow/memory/dist/controller-registry.js

@@ -10,6 +10,7 @@
  * @module @claude-flow/memory/controller-registry
  */
 import { EventEmitter } from 'node:events';
+import * as path from 'node:path';
 import { LearningBridge } from './learning-bridge.js';
 import { MemoryGraph } from './memory-graph.js';
 import { TieredCacheManager } from './cache-manager.js';
@@ -290,7 +291,7 @@ export class ControllerRegistry extends EventEmitter {
             // Validate dbPath to prevent path traversal
             const dbPath = config.dbPath || ':memory:';
             if (dbPath !== ':memory:') {
-                const resolved = require('path').resolve(dbPath);
+                const resolved = path.resolve(dbPath);
                 if (resolved.includes('..')) {
                     this.emit('agentdb:unavailable', { reason: 'Invalid dbPath' });
                     return;
@@ -309,7 +310,6 @@ export class ControllerRegistry extends EventEmitter {
             const suppressFilter = (args) => {
                 const msg = String(args[0] ?? '');
                 return msg.includes('Transformers.js') ||
-                    msg.includes('better-sqlite3') ||
                     msg.includes('[AgentDB]');
             };
             console.log = (...args) => {

package/v3/@claude-flow/memory/dist/database-provider.d.ts

@@ -12,7 +12,7 @@ import { IMemoryBackend } from './types.js';
 /**
  * Available database provider types
  */
-export type DatabaseProvider = 'better-sqlite3' | 'sql.js' | 'json' | 'rvf' | 'auto';
+export type DatabaseProvider = 'sql.js' | 'json' | 'rvf' | 'auto';
 /**
  * Database creation options
  */

package/v3/@claude-flow/memory/dist/database-provider.js

@@ -10,7 +10,6 @@
  */
 import { platform } from 'node:os';
 import { existsSync } from 'node:fs';
-import { SQLiteBackend } from './sqlite-backend.js';
 import { SqlJsBackend } from './sqljs-backend.js';
 /**
  * Detect platform and recommend provider
@@ -21,7 +20,7 @@ function detectPlatform() {
     const isMacOS = os === 'darwin';
     const isLinux = os === 'linux';
     // Recommend better-sqlite3 for Unix-like systems, sql.js for Windows
-    const recommendedProvider = isWindows ? 'sql.js' : 'better-sqlite3';
+    const recommendedProvider = 'sql.js';
     return {
         os,
         isWindows,
@@ -36,19 +35,9 @@ function detectPlatform() {
 async function testRvf() {
     return true;
 }
-/**
- * Test if better-sqlite3 is available and working
- */
+/** better-sqlite3 removed — always returns false */
 async function testBetterSqlite3() {
-    try {
-        const Database = (await import('better-sqlite3')).default;
-        const testDb = new Database(':memory:');
-        testDb.close();
-        return true;
-    }
-    catch (error) {
-        return false;
-    }
+    return false;
 }
 /**
  * Test if sql.js is available and working
@@ -87,19 +76,7 @@ async function selectProvider(preferred, verbose = false) {
         }
         return 'rvf';
     }
-    // Try recommended provider
-    if (platformInfo.recommendedProvider === 'better-sqlite3') {
-        if (await testBetterSqlite3()) {
-            if (verbose) {
-                console.log('[DatabaseProvider] better-sqlite3 available and working');
-            }
-            return 'better-sqlite3';
-        }
-        else if (verbose) {
-            console.log('[DatabaseProvider] better-sqlite3 not available, trying sql.js');
-        }
-    }
-    // Try sql.js as fallback
+    // Try sql.js (moflo: sql.js is the only SQLite backend)
     if (await testSqlJs()) {
         if (verbose) {
             console.log('[DatabaseProvider] sql.js available and working');
@@ -147,18 +124,6 @@ export async function createDatabase(path, options = {}) {
     }
     let backend;
     switch (selectedProvider) {
-        case 'better-sqlite3': {
-            const config = {
-                databasePath: path,
-                walMode,
-                optimize,
-                defaultNamespace,
-                maxEntries,
-                verbose,
-            };
-            backend = new SQLiteBackend(config);
-            break;
-        }
         case 'sql.js': {
             const config = {
                 databasePath: path,

package/v3/@claude-flow/memory/dist/database-provider.test.js

@@ -33,7 +33,7 @@ describe('DatabaseProvider', () => {
                 expect(info.recommendedProvider).toBe('sql.js');
             }
             else {
-                expect(info.recommendedProvider).toBe('better-sqlite3');
+                expect(info.recommendedProvider).toBe('sql.js');
             }
         });
     });
@@ -100,7 +100,7 @@ describe('DatabaseProvider', () => {
                 return;
             }
             const db = await createDatabase(':memory:', {
-                provider: 'better-sqlite3',
+                provider: 'sql.js',
                 verbose: false,
             });
             expect(db).toBeDefined();
@@ -142,7 +142,7 @@ describe('DatabaseProvider', () => {
             const available = await getAvailableProviders();
             const providers = [];
             if (available.betterSqlite3)
-                providers.push('better-sqlite3');
+                providers.push('sql.js');
             if (available.sqlJs)
                 providers.push('sql.js');
             providers.push('json'); // Always available

package/v3/@claude-flow/memory/dist/index.d.ts

@@ -63,7 +63,6 @@ export { AgentDBAdapter } from './agentdb-adapter.js';
 export type { AgentDBAdapterConfig } from './agentdb-adapter.js';
 export { AgentDBBackend } from './agentdb-backend.js';
 export type { AgentDBBackendConfig } from './agentdb-backend.js';
-export { SQLiteBackend } from './sqlite-backend.js';
 export type { SQLiteBackendConfig } from './sqlite-backend.js';
 export { SqlJsBackend } from './sqljs-backend.js';
 export type { SqlJsBackendConfig } from './sqljs-backend.js';

package/v3/@claude-flow/memory/dist/index.js

@@ -61,7 +61,6 @@ export { ControllerRegistry, INIT_LEVELS } from './controller-registry.js';
 // ===== Core Components =====
 export { AgentDBAdapter } from './agentdb-adapter.js';
 export { AgentDBBackend } from './agentdb-backend.js';
-export { SQLiteBackend } from './sqlite-backend.js';
 export { SqlJsBackend } from './sqljs-backend.js';
 export { HybridBackend } from './hybrid-backend.js';
 export { RvfBackend } from './rvf-backend.js';

package/v3/@claude-flow/memory/dist/rvf-migration.js

@@ -90,38 +90,18 @@ function normalizeSqliteRow(row) {
     return out;
 }
 async function readSqliteRows(dbPath) {
-    // Attempt better-sqlite3
+    // Use sql.js (WASM) for SQLite reading
     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();
-        }
+        const initSqlJs = (await import('sql.js')).default;
+        const SQL = await initSqlJs();
+        const fs = await import('node:fs');
+        const buf = fs.readFileSync(dbPath);
+        const db = new SQL.Database(buf);
+        return { exec: (sql) => db.exec(sql), close: () => 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 {
+        throw new Error('Cannot read SQLite: install sql.js');
     }
-    catch { /* unavailable */ }
-    throw new Error('Cannot read SQLite: install better-sqlite3 or sql.js');
 }
 // -- Batch migration helper -------------------------------------------------
 async function migrateBatches(items, rvfPath, options, normalize) {

package/v3/@claude-flow/memory/dist/sqlite-backend.js

@@ -8,7 +8,15 @@
  * @module v3/memory/sqlite-backend
  */
 import { EventEmitter } from 'node:events';
-import Database from 'better-sqlite3';
+// Lazy import — better-sqlite3 is optional (requires native build tools)
+let Database = null;
+async function loadBetterSqlite3() {
+    if (!Database) {
+        const mod = await import('better-sqlite3');
+        Database = mod.default;
+    }
+    return Database;
+}
 /**
  * Default configuration values
  */
@@ -91,19 +99,19 @@ export class SQLiteBackend extends EventEmitter {
     async store(entry) {
         this.ensureInitialized();
         const startTime = performance.now();
-        const stmt = this.db.prepare(`
-      INSERT OR REPLACE INTO memory_entries (
-        id, key, content, type, namespace, tags, metadata,
-        owner_id, access_level, created_at, updated_at, expires_at,
-        version, "references", access_count, last_accessed_at
-      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+        const stmt = this.db.prepare(`
+      INSERT OR REPLACE INTO memory_entries (
+        id, key, content, type, namespace, tags, metadata,
+        owner_id, access_level, created_at, updated_at, expires_at,
+        version, "references", access_count, last_accessed_at
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
     `);
         stmt.run(entry.id, entry.key, entry.content, entry.type, entry.namespace, JSON.stringify(entry.tags), JSON.stringify(entry.metadata), entry.ownerId || null, entry.accessLevel, entry.createdAt, entry.updatedAt, entry.expiresAt || null, entry.version, JSON.stringify(entry.references), entry.accessCount, entry.lastAccessedAt);
         // Store embedding separately (as BLOB)
         if (entry.embedding) {
-            const embeddingStmt = this.db.prepare(`
-        INSERT OR REPLACE INTO memory_embeddings (entry_id, embedding)
-        VALUES (?, ?)
+            const embeddingStmt = this.db.prepare(`
+        INSERT OR REPLACE INTO memory_embeddings (entry_id, embedding)
+        VALUES (?, ?)
       `);
             embeddingStmt.run(entry.id, Buffer.from(entry.embedding.buffer));
         }
@@ -128,9 +136,9 @@ export class SQLiteBackend extends EventEmitter {
      */
     async getByKey(namespace, key) {
         this.ensureInitialized();
-        const stmt = this.db.prepare(`
-      SELECT * FROM memory_entries
-      WHERE namespace = ? AND key = ?
+        const stmt = this.db.prepare(`
+      SELECT * FROM memory_entries
+      WHERE namespace = ? AND key = ?
     `);
         const row = stmt.get(namespace, key);
         if (!row)
@@ -244,9 +252,9 @@ export class SQLiteBackend extends EventEmitter {
             }
             // Use parameterized query with JSON functions
             const tagPlaceholders = query.tags.map(() => '?').join(', ');
-            sql += ` AND EXISTS (
-        SELECT 1 FROM json_each(tags) AS t
-        WHERE t.value IN (${tagPlaceholders})
+            sql += ` AND EXISTS (
+        SELECT 1 FROM json_each(tags) AS t
+        WHERE t.value IN (${tagPlaceholders})
       )`;
             params.push(...query.tags);
         }
@@ -342,9 +350,9 @@ export class SQLiteBackend extends EventEmitter {
         const deleteEntries = this.db.prepare('DELETE FROM memory_entries WHERE namespace = ?');
         const result = deleteEntries.run(namespace);
         // Clean up orphaned embeddings
-        this.db.prepare(`
-      DELETE FROM memory_embeddings
-      WHERE entry_id NOT IN (SELECT id FROM memory_entries)
+        this.db.prepare(`
+      DELETE FROM memory_embeddings
+      WHERE entry_id NOT IN (SELECT id FROM memory_entries)
     `).run();
         return result.changes;
     }
@@ -354,10 +362,10 @@ export class SQLiteBackend extends EventEmitter {
     async getStats() {
         this.ensureInitialized();
         // Count by namespace
-        const namespaceStmt = this.db.prepare(`
-      SELECT namespace, COUNT(*) as count
-      FROM memory_entries
-      GROUP BY namespace
+        const namespaceStmt = this.db.prepare(`
+      SELECT namespace, COUNT(*) as count
+      FROM memory_entries
+      GROUP BY namespace
     `);
         const namespaceRows = namespaceStmt.all();
         const entriesByNamespace = {};
@@ -365,10 +373,10 @@ export class SQLiteBackend extends EventEmitter {
             entriesByNamespace[row.namespace] = row.count;
         }
         // Count by type
-        const typeStmt = this.db.prepare(`
-      SELECT type, COUNT(*) as count
-      FROM memory_entries
-      GROUP BY type
+        const typeStmt = this.db.prepare(`
+      SELECT type, COUNT(*) as count
+      FROM memory_entries
+      GROUP BY type
     `);
         const typeRows = typeStmt.all();
         const entriesByType = {
@@ -475,40 +483,40 @@ export class SQLiteBackend extends EventEmitter {
         if (!this.db)
             return;
         // Main entries table
-        this.db.exec(`
-      CREATE TABLE IF NOT EXISTS memory_entries (
-        id TEXT PRIMARY KEY,
-        key TEXT NOT NULL,
-        content TEXT NOT NULL,
-        type TEXT NOT NULL,
-        namespace TEXT NOT NULL,
-        tags TEXT NOT NULL,
-        metadata TEXT NOT NULL,
-        owner_id TEXT,
-        access_level TEXT NOT NULL,
-        created_at INTEGER NOT NULL,
-        updated_at INTEGER NOT NULL,
-        expires_at INTEGER,
-        version INTEGER NOT NULL,
-        "references" TEXT NOT NULL,
-        access_count INTEGER NOT NULL,
-        last_accessed_at INTEGER NOT NULL
-      );
-
-      CREATE INDEX IF NOT EXISTS idx_namespace ON memory_entries(namespace);
-      CREATE INDEX IF NOT EXISTS idx_key ON memory_entries(key);
-      CREATE INDEX IF NOT EXISTS idx_namespace_key ON memory_entries(namespace, key);
-      CREATE INDEX IF NOT EXISTS idx_type ON memory_entries(type);
-      CREATE INDEX IF NOT EXISTS idx_owner_id ON memory_entries(owner_id);
-      CREATE INDEX IF NOT EXISTS idx_created_at ON memory_entries(created_at);
-      CREATE INDEX IF NOT EXISTS idx_updated_at ON memory_entries(updated_at);
-      CREATE INDEX IF NOT EXISTS idx_expires_at ON memory_entries(expires_at);
-
-      CREATE TABLE IF NOT EXISTS memory_embeddings (
-        entry_id TEXT PRIMARY KEY,
-        embedding BLOB,
-        FOREIGN KEY (entry_id) REFERENCES memory_entries(id) ON DELETE CASCADE
-      );
+        this.db.exec(`
+      CREATE TABLE IF NOT EXISTS memory_entries (
+        id TEXT PRIMARY KEY,
+        key TEXT NOT NULL,
+        content TEXT NOT NULL,
+        type TEXT NOT NULL,
+        namespace TEXT NOT NULL,
+        tags TEXT NOT NULL,
+        metadata TEXT NOT NULL,
+        owner_id TEXT,
+        access_level TEXT NOT NULL,
+        created_at INTEGER NOT NULL,
+        updated_at INTEGER NOT NULL,
+        expires_at INTEGER,
+        version INTEGER NOT NULL,
+        "references" TEXT NOT NULL,
+        access_count INTEGER NOT NULL,
+        last_accessed_at INTEGER NOT NULL
+      );
+
+      CREATE INDEX IF NOT EXISTS idx_namespace ON memory_entries(namespace);
+      CREATE INDEX IF NOT EXISTS idx_key ON memory_entries(key);
+      CREATE INDEX IF NOT EXISTS idx_namespace_key ON memory_entries(namespace, key);
+      CREATE INDEX IF NOT EXISTS idx_type ON memory_entries(type);
+      CREATE INDEX IF NOT EXISTS idx_owner_id ON memory_entries(owner_id);
+      CREATE INDEX IF NOT EXISTS idx_created_at ON memory_entries(created_at);
+      CREATE INDEX IF NOT EXISTS idx_updated_at ON memory_entries(updated_at);
+      CREATE INDEX IF NOT EXISTS idx_expires_at ON memory_entries(expires_at);
+
+      CREATE TABLE IF NOT EXISTS memory_embeddings (
+        entry_id TEXT PRIMARY KEY,
+        embedding BLOB,
+        FOREIGN KEY (entry_id) REFERENCES memory_entries(id) ON DELETE CASCADE
+      );
     `);
     }
     rowToEntry(row) {
@@ -543,18 +551,18 @@ export class SQLiteBackend extends EventEmitter {
      * Synchronous store for use in transactions
      */
     storeSync(entry) {
-        const stmt = this.db.prepare(`
-      INSERT OR REPLACE INTO memory_entries (
-        id, key, content, type, namespace, tags, metadata,
-        owner_id, access_level, created_at, updated_at, expires_at,
-        version, "references", access_count, last_accessed_at
-      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+        const stmt = this.db.prepare(`
+      INSERT OR REPLACE INTO memory_entries (
+        id, key, content, type, namespace, tags, metadata,
+        owner_id, access_level, created_at, updated_at, expires_at,
+        version, "references", access_count, last_accessed_at
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
     `);
         stmt.run(entry.id, entry.key, entry.content, entry.type, entry.namespace, JSON.stringify(entry.tags), JSON.stringify(entry.metadata), entry.ownerId || null, entry.accessLevel, entry.createdAt, entry.updatedAt, entry.expiresAt || null, entry.version, JSON.stringify(entry.references), entry.accessCount, entry.lastAccessedAt);
         if (entry.embedding) {
-            const embeddingStmt = this.db.prepare(`
-        INSERT OR REPLACE INTO memory_embeddings (entry_id, embedding)
-        VALUES (?, ?)
+            const embeddingStmt = this.db.prepare(`
+        INSERT OR REPLACE INTO memory_embeddings (entry_id, embedding)
+        VALUES (?, ?)
       `);
             embeddingStmt.run(entry.id, Buffer.from(entry.embedding.buffer));
         }

package/v3/@claude-flow/memory/package.json

@@ -1,46 +1,42 @@
-{
-  "name": "@claude-flow/memory",
-  "version": "3.0.0-alpha.11",
-  "type": "module",
-  "description": "Memory module - AgentDB unification, HNSW indexing, vector search, hybrid SQLite+AgentDB backend (ADR-009)",
-  "main": "dist/index.js",
-  "types": "dist/index.d.ts",
-  "exports": {
-    ".": "./dist/index.js",
-    "./*": "./dist/*.js"
-  },
-  "scripts": {
-    "test": "vitest run",
-    "bench": "vitest bench",
-    "build": "tsc"
-  },
-  "dependencies": {
-    "agentdb": "^3.0.0-alpha.10",
-    "sql.js": "^1.10.3"
-  },
-  "optionalDependencies": {
-    "better-sqlite3": "^11.0.0"
-  },
-  "devDependencies": {
-    "@types/better-sqlite3": "^7.6.11",
-    "@types/sql.js": "^1.4.9",
-    "vitest": "^4.0.16"
-  },
-  "files": [
-    "dist",
-    "README.md"
-  ],
-  "publishConfig": {
-    "access": "public",
-    "tag": "v3alpha"
-  },
-  "os": [
-    "darwin",
-    "linux",
-    "win32"
-  ],
-  "cpu": [
-    "x64",
-    "arm64"
-  ]
-}
+{
+  "name": "@claude-flow/memory",
+  "version": "3.0.0-alpha.11",
+  "type": "module",
+  "description": "Memory module - AgentDB unification, HNSW indexing, vector search, hybrid SQLite+AgentDB backend (ADR-009)",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": "./dist/index.js",
+    "./*": "./dist/*.js"
+  },
+  "scripts": {
+    "test": "vitest run",
+    "bench": "vitest bench",
+    "build": "tsc"
+  },
+  "dependencies": {
+    "agentdb": "^3.0.0-alpha.10",
+    "sql.js": "^1.10.3"
+  },
+  "devDependencies": {
+    "@types/sql.js": "^1.4.9",
+    "vitest": "^4.0.16"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "tag": "v3alpha"
+  },
+  "os": [
+    "darwin",
+    "linux",
+    "win32"
+  ],
+  "cpu": [
+    "x64",
+    "arm64"
+  ]
+}