@aigentic/claude-flow 3.7.0-alpha.69

package/v3/@claude-flow/cli/dist/src/memory/neural-package-bridge.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Bridge to @claude-flow/neural — Phase 1 convergence (#1773).
+ *
+ * The cli has historically reimplemented SONA / ReasoningBank / PatternLearner
+ * locally in `intelligence.ts`. The dedicated `@claude-flow/neural` package
+ * (3.0.0-alpha.7+) ships the canonical implementations plus 7 RL algorithms
+ * (PPO/DQN/A2C/Decision Transformer/Q-Learning/SARSA/Curiosity), 5 SONA
+ * modes (RealTime/Balanced/Research/Edge/Batch), and an event listener
+ * system that the cli's local impl doesn't have.
+ *
+ * This bridge lazy-loads `NeuralLearningSystem` from the package and exposes
+ * a stable accessor for cli code that wants to use the richer surface. The
+ * existing local LocalSonaCoordinator + LocalReasoningBank in intelligence.ts
+ * stay intact for now — Phase 1 just proves the wiring works without
+ * breaking the 769 cli tests. Phase 2+ migrates functions one at a time.
+ *
+ * Why lazy: instantiating NeuralLearningSystem pulls in @ruvector/sona and
+ * a few transitive WASM modules — not free at process startup. The bridge
+ * defers until something actually asks for it.
+ */
+import type { NeuralLearningSystem, SONAMode } from '@claude-flow/neural';
+/**
+ * Lazy-load + initialize the @claude-flow/neural NeuralLearningSystem. Returns
+ * null if the package isn't resolvable (defensive — the package is in cli's
+ * regular dependencies, but environments with --ignore-scripts or pnpm prune
+ * can leave it unavailable). Idempotent across calls.
+ */
+export declare function getNeuralPackage(mode?: SONAMode): Promise<NeuralLearningSystem | null>;
+/**
+ * Quick "is the package available?" probe without forcing initialization.
+ * Returns true if a previous getNeuralPackage() call succeeded; null if
+ * never tried or failed. Useful for dashboards that want to surface package
+ * status without triggering load.
+ */
+export declare function isNeuralPackageLoaded(): boolean;
+/**
+ * Get aggregated stats from the neural package alongside cli's local stats.
+ * Returns null if the package isn't loaded — caller should fall back to
+ * local-only stats. The return shape mirrors the package's NeuralLearningSystem
+ * .getStats() output: { sona, reasoningBank, patternLearner }.
+ */
+export declare function getNeuralPackageStats(): Promise<ReturnType<NeuralLearningSystem['getStats']> | null>;
+/**
+ * Reset the bridge (mainly for tests). Drops the cached instance and
+ * forgets any prior init failure so the next getNeuralPackage() retries.
+ */
+export declare function resetNeuralPackageBridge(): void;
+//# sourceMappingURL=neural-package-bridge.d.ts.map

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

@@ -0,0 +1,87 @@
+/**
+ * Bridge to @claude-flow/neural — Phase 1 convergence (#1773).
+ *
+ * The cli has historically reimplemented SONA / ReasoningBank / PatternLearner
+ * locally in `intelligence.ts`. The dedicated `@claude-flow/neural` package
+ * (3.0.0-alpha.7+) ships the canonical implementations plus 7 RL algorithms
+ * (PPO/DQN/A2C/Decision Transformer/Q-Learning/SARSA/Curiosity), 5 SONA
+ * modes (RealTime/Balanced/Research/Edge/Batch), and an event listener
+ * system that the cli's local impl doesn't have.
+ *
+ * This bridge lazy-loads `NeuralLearningSystem` from the package and exposes
+ * a stable accessor for cli code that wants to use the richer surface. The
+ * existing local LocalSonaCoordinator + LocalReasoningBank in intelligence.ts
+ * stay intact for now — Phase 1 just proves the wiring works without
+ * breaking the 769 cli tests. Phase 2+ migrates functions one at a time.
+ *
+ * Why lazy: instantiating NeuralLearningSystem pulls in @ruvector/sona and
+ * a few transitive WASM modules — not free at process startup. The bridge
+ * defers until something actually asks for it.
+ */
+let pkgInstance = null;
+let pkgInitPromise = null;
+let pkgInitFailed = false;
+/**
+ * Lazy-load + initialize the @claude-flow/neural NeuralLearningSystem. Returns
+ * null if the package isn't resolvable (defensive — the package is in cli's
+ * regular dependencies, but environments with --ignore-scripts or pnpm prune
+ * can leave it unavailable). Idempotent across calls.
+ */
+export async function getNeuralPackage(mode = 'balanced') {
+    if (pkgInstance)
+        return pkgInstance;
+    if (pkgInitFailed)
+        return null;
+    if (pkgInitPromise)
+        return pkgInitPromise;
+    pkgInitPromise = (async () => {
+        try {
+            const m = await import('@claude-flow/neural');
+            const sys = m.createNeuralLearningSystem(mode);
+            await sys.initialize();
+            pkgInstance = sys;
+            return sys;
+        }
+        catch (err) {
+            // CLAUDE_FLOW_DEBUG-gated log so future regressions of this shape
+            // don't disappear silently — same convention as the ruvllm coordinator
+            // bridge (#1770).
+            if (process.env.CLAUDE_FLOW_DEBUG) {
+                // eslint-disable-next-line no-console
+                console.error('[neural-package] @claude-flow/neural load failed:', err.message);
+            }
+            pkgInitFailed = true;
+            return null;
+        }
+    })();
+    return pkgInitPromise;
+}
+/**
+ * Quick "is the package available?" probe without forcing initialization.
+ * Returns true if a previous getNeuralPackage() call succeeded; null if
+ * never tried or failed. Useful for dashboards that want to surface package
+ * status without triggering load.
+ */
+export function isNeuralPackageLoaded() {
+    return pkgInstance !== null;
+}
+/**
+ * Get aggregated stats from the neural package alongside cli's local stats.
+ * Returns null if the package isn't loaded — caller should fall back to
+ * local-only stats. The return shape mirrors the package's NeuralLearningSystem
+ * .getStats() output: { sona, reasoningBank, patternLearner }.
+ */
+export async function getNeuralPackageStats() {
+    const sys = await getNeuralPackage();
+    return sys ? sys.getStats() : null;
+}
+/**
+ * Reset the bridge (mainly for tests). Drops the cached instance and
+ * forgets any prior init failure so the next getNeuralPackage() retries.
+ */
+export function resetNeuralPackageBridge() {
+    pkgInstance = null;
+    pkgInitPromise = null;
+    pkgInitFailed = false;
+}
+//# sourceMappingURL=neural-package-bridge.js.map

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

@@ -0,0 +1,60 @@
+/**
+ * RaBitQ Index — 1-bit quantized vector pre-filter (32× compression)
+ *
+ * Wraps @ruvector/rabitq-wasm to provide Hamming-scan pre-filtering
+ * over quantized embeddings. Candidates are reranked with exact cosine
+ * similarity from the full-precision source (HNSW or SQLite).
+ *
+ * Lifecycle:
+ *  1. build() — bulk-load all embeddings from SQLite into the WASM index
+ *  2. search() — fast Hamming scan → candidate ids → caller reranks
+ *  3. rebuild() — called when entry count drifts >20% from last build
+ */
+/**
+ * Build or rebuild the RaBitQ index from SQLite embeddings.
+ * Returns entry count or 0 if RaBitQ is unavailable.
+ */
+export declare function buildRabitqIndex(options?: {
+    dbPath?: string;
+    dimensions?: number;
+    force?: boolean;
+}): Promise<{
+    success: boolean;
+    vectorCount: number;
+    dimensions: number;
+    compressionRatio: number;
+    buildTimeMs: number;
+    wasmVersion?: string;
+    error?: string;
+}>;
+/**
+ * Search the RaBitQ index for candidate IDs.
+ * Returns null if index not built or unavailable.
+ * Caller is responsible for reranking with exact similarity.
+ */
+export declare function searchRabitq(queryEmbedding: number[], options?: {
+    k?: number;
+    namespace?: string;
+}): Promise<Array<{
+    id: string;
+    key: string;
+    namespace: string;
+    distance: number;
+    position: number;
+}> | null>;
+/**
+ * Check if the RaBitQ index needs rebuilding.
+ */
+export declare function shouldRebuildRabitq(currentEntryCount: number): Promise<boolean>;
+/**
+ * Get RaBitQ index status.
+ */
+export declare function getRabitqStatus(): {
+    available: boolean;
+    initialized: boolean;
+    vectorCount: number;
+    dimensions: number;
+    builtAt: number | null;
+    compressionRatio: number;
+};
+//# sourceMappingURL=rabitq-index.d.ts.map

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

@@ -0,0 +1,242 @@
+/**
+ * RaBitQ Index — 1-bit quantized vector pre-filter (32× compression)
+ *
+ * Wraps @ruvector/rabitq-wasm to provide Hamming-scan pre-filtering
+ * over quantized embeddings. Candidates are reranked with exact cosine
+ * similarity from the full-precision source (HNSW or SQLite).
+ *
+ * Lifecycle:
+ *  1. build() — bulk-load all embeddings from SQLite into the WASM index
+ *  2. search() — fast Hamming scan → candidate ids → caller reranks
+ *  3. rebuild() — called when entry count drifts >20% from last build
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+const RABITQ_SEED = 42n;
+const RABITQ_RERANK_FACTOR = 20;
+const REBUILD_DRIFT_THRESHOLD = 0.2; // rebuild when count drifts >20%
+let rabitqState = null;
+let rabitqInitializing = false;
+async function loadRabitqModule() {
+    try {
+        const mod = await import('@ruvector/rabitq-wasm');
+        // Node.js: use initSync with the WASM bytes
+        const { createRequire } = await import('module');
+        const require = createRequire(import.meta.url);
+        const wasmPath = require.resolve('@ruvector/rabitq-wasm/ruvector_rabitq_wasm_bg.wasm');
+        const wasmBytes = fs.readFileSync(wasmPath);
+        mod.initSync({ module: wasmBytes });
+        return {
+            RabitqIndex: mod.RabitqIndex,
+            initSync: mod.initSync,
+            version: mod.version,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Build or rebuild the RaBitQ index from SQLite embeddings.
+ * Returns entry count or 0 if RaBitQ is unavailable.
+ */
+export async function buildRabitqIndex(options) {
+    if (rabitqInitializing) {
+        return { success: false, vectorCount: 0, dimensions: 0, compressionRatio: 0, buildTimeMs: 0, error: 'Build already in progress' };
+    }
+    rabitqInitializing = true;
+    const startTime = Date.now();
+    try {
+        const mod = await loadRabitqModule();
+        if (!mod) {
+            rabitqInitializing = false;
+            return { success: false, vectorCount: 0, dimensions: 0, compressionRatio: 0, buildTimeMs: 0, error: '@ruvector/rabitq-wasm not available' };
+        }
+        const dimensions = options?.dimensions ?? 384;
+        const swarmDir = path.resolve(process.cwd(), '.swarm');
+        const dbPath = options?.dbPath ? path.resolve(options.dbPath) : path.join(swarmDir, 'memory.db');
+        const entries = [];
+        const vectors = [];
+        // Try bridge first (reads via better-sqlite3, sees WAL data)
+        let usedBridge = false;
+        try {
+            const { bridgeGetAllEmbeddings } = await import('./memory-bridge.js');
+            const bridgeRows = await bridgeGetAllEmbeddings({ dimensions, dbPath: options?.dbPath });
+            if (bridgeRows && bridgeRows.length > 0) {
+                for (const row of bridgeRows) {
+                    entries.push({ id: row.id, key: row.key, namespace: row.namespace });
+                    vectors.push(...row.embedding);
+                }
+                usedBridge = true;
+            }
+        }
+        catch { /* bridge unavailable, fall through */ }
+        // Fallback: read .swarm/memory.db via sql.js
+        if (!usedBridge) {
+            if (!fs.existsSync(dbPath)) {
+                rabitqInitializing = false;
+                return { success: false, vectorCount: 0, dimensions, compressionRatio: 0, buildTimeMs: 0, error: 'Database not found' };
+            }
+            const initSqlJs = (await import('sql.js')).default;
+            const SQL = await initSqlJs();
+            const fileBuffer = fs.readFileSync(dbPath);
+            const db = new SQL.Database(fileBuffer);
+            const result = db.exec(`
+        SELECT id, key, namespace, embedding
+        FROM memory_entries
+        WHERE status = 'active' AND embedding IS NOT NULL
+        LIMIT 50000
+      `);
+            if (result[0]?.values) {
+                for (const row of result[0].values) {
+                    const [id, key, ns, embeddingJson] = row;
+                    if (!embeddingJson)
+                        continue;
+                    try {
+                        const embedding = JSON.parse(embeddingJson);
+                        if (embedding.length !== dimensions)
+                            continue;
+                        entries.push({ id: String(id), key: key || String(id), namespace: ns || 'default' });
+                        vectors.push(...embedding);
+                    }
+                    catch {
+                        // skip invalid
+                    }
+                }
+            }
+            db.close();
+        }
+        if (entries.length < 2) {
+            rabitqInitializing = false;
+            return { success: false, vectorCount: entries.length, dimensions, compressionRatio: 0, buildTimeMs: Date.now() - startTime, error: 'Need at least 2 vectors to build RaBitQ index' };
+        }
+        // Build the RaBitQ index
+        const flatVectors = new Float32Array(vectors);
+        const index = mod.RabitqIndex.build(flatVectors, dimensions, RABITQ_SEED, RABITQ_RERANK_FACTOR);
+        // Free old index if exists
+        if (rabitqState?.index) {
+            try {
+                rabitqState.index.free();
+            }
+            catch { /* already freed */ }
+        }
+        rabitqState = {
+            index,
+            entries,
+            dimensions,
+            builtAt: Date.now(),
+            vectorCount: entries.length,
+        };
+        // Persist metadata for fast reload hint
+        try {
+            const metaPath = path.join(swarmDir, 'rabitq.meta.json');
+            fs.writeFileSync(metaPath, JSON.stringify({
+                vectorCount: entries.length,
+                dimensions,
+                builtAt: rabitqState.builtAt,
+                wasmVersion: mod.version(),
+            }));
+        }
+        catch { /* best-effort */ }
+        const rawBytes = entries.length * dimensions * 4; // f32 = 4 bytes
+        const quantizedBytes = entries.length * Math.ceil(dimensions / 8); // 1 bit per dim
+        const compressionRatio = rawBytes / Math.max(quantizedBytes, 1);
+        rabitqInitializing = false;
+        return {
+            success: true,
+            vectorCount: entries.length,
+            dimensions,
+            compressionRatio: Math.round(compressionRatio * 10) / 10,
+            buildTimeMs: Date.now() - startTime,
+            wasmVersion: mod.version(),
+        };
+    }
+    catch (error) {
+        rabitqInitializing = false;
+        return {
+            success: false,
+            vectorCount: 0,
+            dimensions: 0,
+            compressionRatio: 0,
+            buildTimeMs: Date.now() - startTime,
+            error: error instanceof Error ? error.message : String(error),
+        };
+    }
+}
+/**
+ * Search the RaBitQ index for candidate IDs.
+ * Returns null if index not built or unavailable.
+ * Caller is responsible for reranking with exact similarity.
+ */
+export async function searchRabitq(queryEmbedding, options) {
+    if (!rabitqState?.index)
+        return null;
+    try {
+        const query = new Float32Array(queryEmbedding);
+        if (query.length !== rabitqState.dimensions)
+            return null;
+        const k = options?.k ?? 10;
+        // Get more candidates than needed for namespace filtering + rerank
+        const expandedK = Math.min(k * 3, rabitqState.vectorCount);
+        const rawResults = rabitqState.index.search(query, expandedK);
+        const results = [];
+        for (const hit of rawResults) {
+            const pos = hit.id; // row index from build()
+            const entry = rabitqState.entries[pos];
+            if (!entry)
+                continue;
+            // Namespace filter
+            if (options?.namespace && options.namespace !== 'all' && entry.namespace !== options.namespace) {
+                continue;
+            }
+            results.push({
+                id: entry.id,
+                key: entry.key,
+                namespace: entry.namespace,
+                distance: hit.distance,
+                position: pos,
+            });
+            // Free WASM SearchResult to prevent leak
+            try {
+                hit.free();
+            }
+            catch { /* already freed */ }
+            if (results.length >= k)
+                break;
+        }
+        // Free remaining SearchResults
+        for (const hit of rawResults) {
+            try {
+                hit.free();
+            }
+            catch { /* already freed or used */ }
+        }
+        return results;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Check if the RaBitQ index needs rebuilding.
+ */
+export async function shouldRebuildRabitq(currentEntryCount) {
+    if (!rabitqState)
+        return currentEntryCount >= 10; // Build if we have enough vectors
+    const drift = Math.abs(currentEntryCount - rabitqState.vectorCount) / Math.max(rabitqState.vectorCount, 1);
+    return drift > REBUILD_DRIFT_THRESHOLD;
+}
+/**
+ * Get RaBitQ index status.
+ */
+export function getRabitqStatus() {
+    return {
+        available: rabitqState !== null,
+        initialized: rabitqState !== null,
+        vectorCount: rabitqState?.vectorCount ?? 0,
+        dimensions: rabitqState?.dimensions ?? 384,
+        builtAt: rabitqState?.builtAt ?? null,
+        compressionRatio: rabitqState ? Math.round((rabitqState.dimensions * 4) / Math.ceil(rabitqState.dimensions / 8) * 10) / 10 : 0,
+    };
+}
+//# sourceMappingURL=rabitq-index.js.map