claude-flow 3.5.73 → 3.5.75

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-flow",
-  "version": "3.5.73",
+  "version": "3.5.75",
   "description": "Ruflo - Enterprise AI agent orchestration for Claude Code. Deploy 60+ specialized agents in coordinated swarms with self-learning, fault-tolerant consensus, vector memory, and MCP integration",
   "main": "dist/index.js",
   "type": "module",

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

@@ -260,6 +260,17 @@ const trainCommand = {
             // Flush patterns to disk
             flushPatterns();
             const persistence = getPersistenceStatus();
+            // Save LoRA checkpoint via ruvllm TrainingPipeline if available
+            try {
+                const { LoRAAdapter } = await import('../ruvector/lora-adapter.js');
+                const path = await import('path');
+                const cpDir = path.join(process.cwd(), '.claude-flow', 'neural');
+                const cpPath = path.join(cpDir, `lora-checkpoint-${Date.now()}.json`);
+                const adapter = new LoRAAdapter({ inputDim: dim, outputDim: dim, rank: 4 });
+                await adapter.initBackend();
+                await adapter.saveCheckpoint(cpPath);
+            }
+            catch { /* checkpoint save is best-effort */ }
             output.writeln();
             // Display results
             const tableData = [
@@ -421,6 +432,43 @@ const statusCommand = {
                         status: output.success('Available'),
                         details: '~4x memory reduction',
                     },
+                    {
+                        component: 'ruvllm Coordinator',
+                        status: stats._ruvllmBackend === 'active' ? output.success('Active') : output.dim('Unavailable'),
+                        details: stats._ruvllmBackend === 'active'
+                            ? `SonaCoordinator | ${stats._ruvllmTrajectories} trajectories`
+                            : 'Install @ruvector/ruvllm',
+                    },
+                    {
+                        component: 'Contrastive Trainer',
+                        status: stats._contrastiveTrainer && stats._contrastiveTrainer !== 'unavailable' ? output.success('Active') : output.dim('Unavailable'),
+                        details: stats._contrastiveTrainer && stats._contrastiveTrainer !== 'unavailable'
+                            ? `${stats._contrastiveTrainer.triplets ?? 0} triplets, ${stats._contrastiveTrainer.agents ?? 0} agents`
+                            : 'Install @ruvector/ruvllm',
+                    },
+                    {
+                        component: 'Training Pipeline',
+                        status: stats._trainingBackend === 'ruvllm' ? output.success('Active') : output.dim(stats._trainingBackend || 'Unavailable'),
+                        details: stats._trainingBackend === 'ruvllm'
+                            ? 'ruvllm checkpoints enabled'
+                            : 'JS fallback (no checkpoints)',
+                    },
+                    await (async () => {
+                        try {
+                            const { getGraphStats } = await import('../ruvector/graph-backend.js');
+                            const gs = await getGraphStats();
+                            return {
+                                component: 'Graph Database',
+                                status: gs.backend === 'graph-node' ? output.success('Active') : output.dim('Unavailable'),
+                                details: gs.backend === 'graph-node'
+                                    ? `${gs.totalNodes} nodes, ${gs.totalEdges} edges`
+                                    : 'Install @ruvector/graph-node',
+                            };
+                        }
+                        catch {
+                            return { component: 'Graph Database', status: output.dim('Unavailable'), details: 'Not loaded' };
+                        }
+                    })(),
                 ],
             });
             if (verbose) {
@@ -678,6 +726,12 @@ const optimizeCommand = {
             await initializeIntelligence();
             const patterns = await getAllPatterns();
             const stats = getIntelligenceStats();
+            // Trigger ruvllm background learning if available
+            try {
+                const { runBackgroundLearning } = await import('../memory/intelligence.js');
+                await runBackgroundLearning();
+            }
+            catch { /* background learning is best-effort */ }
             // Get actual pattern storage size
             const patternDir = path.join(process.cwd(), '.claude-flow', 'neural');
             let beforeSize = 0;

package/v3/@claude-flow/cli/dist/src/mcp-tools/agent-tools.js

@@ -184,6 +184,12 @@ export const agentTools = [
             };
             store.agents[agentId] = agent;
             saveAgentStore(store);
+            // Record agent in graph database (ADR-087, best-effort)
+            try {
+                const { addNode } = await import('../ruvector/graph-backend.js');
+                await addNode({ id: agentId, type: 'agent', name: agentType });
+            }
+            catch { /* graph-node not available */ }
             // Include Agent Booster routing info if applicable
             const response = {
                 success: true,

package/v3/@claude-flow/cli/dist/src/mcp-tools/agentdb-tools.js

@@ -243,6 +243,20 @@ export const agentdbCausalEdge = {
                 return { success: false, error: 'targetId is required (non-empty string)' };
             if (!relation)
                 return { success: false, error: 'relation is required (non-empty string)' };
+            // Try native graph-node backend first (ADR-087)
+            try {
+                const graphBackend = await import('../ruvector/graph-backend.js');
+                if (await graphBackend.isGraphBackendAvailable()) {
+                    const graphResult = await graphBackend.recordCausalEdge(sourceId, targetId, relation, typeof params.weight === 'number' ? validateScore(params.weight, 0.5) : undefined);
+                    if (graphResult.success) {
+                        // Also record in AgentDB bridge for compatibility
+                        const bridge = await getBridge();
+                        await bridge.bridgeRecordCausalEdge({ sourceId, targetId, relation, weight: typeof params.weight === 'number' ? validateScore(params.weight, 0.5) : undefined }).catch(() => { });
+                        return { ...graphResult, _graphNodeBackend: true };
+                    }
+                }
+            }
+            catch { /* graph-node not available, fall through */ }
             const bridge = await getBridge();
             const result = await bridge.bridgeRecordCausalEdge({
                 sourceId,

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

@@ -2033,6 +2033,46 @@ export const hooksIntelligence = {
                     implemented: true,
                     note: 'Real ONNX embeddings via Xenova/all-MiniLM-L6-v2',
                 },
+                ruvllmCoordinator: await (async () => {
+                    try {
+                        const { getIntelligenceStats } = await import('../memory/intelligence.js');
+                        const s = getIntelligenceStats();
+                        return { status: s._ruvllmBackend || 'unavailable', trajectories: s._ruvllmTrajectories || 0, note: s._ruvllmBackend === 'active' ? 'SonaCoordinator forwarding trajectories' : '@ruvector/ruvllm not loaded' };
+                    }
+                    catch {
+                        return { status: 'unavailable', trajectories: 0, note: 'Not initialized' };
+                    }
+                })(),
+                contrastiveTrainer: await (async () => {
+                    try {
+                        const { getSONAStats } = await import('../memory/sona-optimizer.js');
+                        const s = await getSONAStats();
+                        return { status: s._contrastiveTrainer !== 'unavailable' ? 'active' : 'unavailable', details: s._contrastiveTrainer, note: s._contrastiveTrainer !== 'unavailable' ? 'Agent embedding learning active' : '@ruvector/ruvllm not loaded' };
+                    }
+                    catch {
+                        return { status: 'unavailable', details: null, note: 'Not initialized' };
+                    }
+                })(),
+                trainingPipeline: await (async () => {
+                    try {
+                        const loraInst = await getLoRAAdapter();
+                        const s = loraInst?.getStats();
+                        return { status: s?._trainingBackend || 'unavailable', note: s?._trainingBackend === 'ruvllm' ? 'Checkpoint save/load via ruvllm' : 'JS fallback' };
+                    }
+                    catch {
+                        return { status: 'unavailable', note: 'Not initialized' };
+                    }
+                })(),
+                graphDatabase: await (async () => {
+                    try {
+                        const { getGraphStats } = await import('../ruvector/graph-backend.js');
+                        const gs = await getGraphStats();
+                        return { status: gs.backend, totalNodes: gs.totalNodes, totalEdges: gs.totalEdges, avgDegree: gs.avgDegree, note: gs.backend === 'graph-node' ? 'Native Rust graph with hyperedges and k-hop queries' : '@ruvector/graph-node not loaded' };
+                    }
+                    catch {
+                        return { status: 'unavailable', totalNodes: 0, totalEdges: 0, avgDegree: 0, note: 'Not initialized' };
+                    }
+                })(),
             },
             realMetrics: {
                 trajectories: realStats.trajectories,
@@ -2044,7 +2084,7 @@ export const hooksIntelligence = {
                 working: [
                     'memory-store', 'embeddings', 'trajectory-recording', 'claims', 'swarm-coordination',
                     'hnsw-index', 'pattern-storage', 'sona-optimizer', 'ewc-consolidation', 'moe-routing',
-                    'flash-attention', 'lora-adapter'
+                    'flash-attention', 'lora-adapter', 'ruvllm-coordinator', 'contrastive-trainer', 'training-pipeline', 'graph-database'
                 ],
                 partial: [],
                 notImplemented: [],
@@ -2307,6 +2347,12 @@ export const hooksTrajectoryEnd = {
                     // SONA learning failed, continue without it
                 }
             }
+            // Trigger ruvllm background learning after trajectory end
+            try {
+                const { runBackgroundLearning } = await import('../memory/intelligence.js');
+                await runBackgroundLearning();
+            }
+            catch { /* best-effort */ }
             // Try EWC++ consolidation on successful trajectories
             if (success) {
                 const ewc = await getEWCConsolidator();
@@ -2671,12 +2717,38 @@ export const hooksIntelligenceStats = {
                 implementation: 'real-lora',
             };
         }
+        // ruvllm native backend stats
+        let ruvllmStats = { coordinator: 'unavailable', trajectories: 0, contrastiveTrainer: 'unavailable', trainingBackend: 'unavailable', graphDatabase: { backend: 'unavailable', totalNodes: 0, totalEdges: 0 } };
+        try {
+            const { getIntelligenceStats } = await import('../memory/intelligence.js');
+            const iStats = getIntelligenceStats();
+            ruvllmStats.coordinator = iStats._ruvllmBackend || 'unavailable';
+            ruvllmStats.trajectories = iStats._ruvllmTrajectories || 0;
+        }
+        catch { /* not initialized */ }
+        try {
+            const { getSONAStats: getSONA } = await import('../memory/sona-optimizer.js');
+            const sStats = await getSONA();
+            ruvllmStats.contrastiveTrainer = sStats._contrastiveTrainer || 'unavailable';
+        }
+        catch { /* not initialized */ }
+        if (lora) {
+            const ls = lora.getStats();
+            ruvllmStats.trainingBackend = ls._trainingBackend || 'unavailable';
+        }
+        try {
+            const { getGraphStats } = await import('../ruvector/graph-backend.js');
+            const gs = await getGraphStats();
+            ruvllmStats.graphDatabase = { backend: gs.backend, totalNodes: gs.totalNodes, totalEdges: gs.totalEdges, avgDegree: gs.avgDegree };
+        }
+        catch { /* not available */ }
         const stats = {
             sona: sonaStats,
             moe: moeStats,
             ewc: ewcStats,
             flash: flashStats,
             lora: loraStats,
+            ruvllm: ruvllmStats,
             hnsw: {
                 indexSize: memoryStats.memory.indexSize,
                 avgSearchTimeMs: 0.12,

package/v3/@claude-flow/cli/dist/src/mcp-tools/ruvllm-tools.js

@@ -16,8 +16,32 @@ export const ruvllmWasmTools = [
         handler: async () => {
             try {
                 const mod = await loadRuvllmWasm();
-                const status = await mod.getRuvllmStatus();
-                return { content: [{ type: 'text', text: JSON.stringify(status, null, 2) }] };
+                const wasmStatus = await mod.getRuvllmStatus();
+                // Also include native ruvllm CJS backend status (ADR-086)
+                let nativeBackend = { available: false };
+                try {
+                    const { getIntelligenceStats } = await import('../memory/intelligence.js');
+                    const iStats = getIntelligenceStats();
+                    const { getSONAStats } = await import('../memory/sona-optimizer.js');
+                    const sStats = await getSONAStats();
+                    nativeBackend = {
+                        available: iStats._ruvllmBackend === 'active',
+                        coordinator: iStats._ruvllmBackend || 'unavailable',
+                        trajectories: iStats._ruvllmTrajectories || 0,
+                        contrastiveTrainer: sStats._contrastiveTrainer !== 'unavailable' ? 'active' : 'unavailable',
+                        trainingBackend: iStats._trainingBackend || 'unknown',
+                    };
+                }
+                catch { /* not initialized yet */ }
+                // Graph database status (ADR-087)
+                let graphStatus = { available: false };
+                try {
+                    const { getGraphStats } = await import('../ruvector/graph-backend.js');
+                    const gs = await getGraphStats();
+                    graphStatus = { available: gs.backend === 'graph-node', ...gs };
+                }
+                catch { /* not loaded */ }
+                return { content: [{ type: 'text', text: JSON.stringify({ wasm: wasmStatus, native: nativeBackend, graph: graphStatus }, null, 2) }] };
             }
             catch (err) {
                 return { content: [{ type: 'text', text: JSON.stringify({ error: String(err) }) }], isError: true };

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

@@ -250,7 +250,15 @@ export declare function findSimilarPatterns(query: string, options?: {
 /**
  * Get intelligence system statistics
  */
-export declare function getIntelligenceStats(): IntelligenceStats;
+export declare function getIntelligenceStats(): IntelligenceStats & {
+    _ruvllmBackend: string;
+    _ruvllmTrajectories: number;
+    _contrastiveTrainer?: {
+        triplets: number;
+        agents: number;
+    } | string;
+    _trainingBackend?: string;
+};
 /**
  * Get SONA coordinator for advanced operations
  */
@@ -329,6 +337,11 @@ export declare function clearAllPatterns(): Promise<void>;
  * Get the neural data directory path
  */
 export declare function getNeuralDataDir(): string;
+/**
+ * Trigger background learning on the @ruvector/ruvllm SonaCoordinator.
+ * No-op if ruvllm is not installed.
+ */
+export declare function runBackgroundLearning(): Promise<void>;
 /**
  * Get persistence status
  */

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

@@ -559,6 +559,26 @@ class LocalReasoningBank {
     }
 }
 // ============================================================================
+// @ruvector/ruvllm SonaCoordinator Integration
+// ============================================================================
+let ruvllmCoordinator = null;
+let ruvllmLoaded = false;
+async function loadRuvllmCoordinator() {
+    if (ruvllmLoaded)
+        return ruvllmCoordinator;
+    ruvllmLoaded = true;
+    try {
+        const { createRequire } = await import('module');
+        const requireCjs = createRequire(import.meta.url);
+        const ruvllm = requireCjs('@ruvector/ruvllm');
+        ruvllmCoordinator = new ruvllm.SonaCoordinator(ruvllm.DEFAULT_SONA_CONFIG);
+        return ruvllmCoordinator;
+    }
+    catch {
+        return null;
+    }
+}
+// ============================================================================
 // Module State
 // ============================================================================
 let sonaCoordinator = null;
@@ -634,6 +654,8 @@ export async function initializeIntelligence(config) {
         });
         // Load persisted stats if available
         loadPersistedStats();
+        // Eagerly load ruvllm coordinator so stats reflect backend status
+        await loadRuvllmCoordinator();
         intelligenceInitialized = true;
         return {
             success: true,
@@ -773,6 +795,26 @@ export async function recordTrajectory(steps, verdict) {
                 }
             }
         }
+        // Forward trajectory to @ruvector/ruvllm SonaCoordinator if available
+        const ruvllmCoord = await loadRuvllmCoordinator();
+        if (ruvllmCoord) {
+            try {
+                const avgQuality = verdict === 'success' ? 1.0 : verdict === 'partial' ? 0.5 : 0.0;
+                ruvllmCoord.recordTrajectory({
+                    steps: enrichedSteps.map(s => ({
+                        state: s.content,
+                        action: s.type,
+                        reward: avgQuality,
+                        embedding: s.embedding || []
+                    })),
+                    totalReward: avgQuality,
+                    success: verdict === 'success'
+                });
+            }
+            catch {
+                // ruvllm recording failed silently
+            }
+        }
         globalStats.trajectoriesRecorded++;
         globalStats.lastAdaptation = Date.now();
         savePersistedStats();
@@ -837,6 +879,19 @@ export async function findSimilarPatterns(query, options) {
 export function getIntelligenceStats() {
     const sonaStats = sonaCoordinator?.stats();
     const bankStats = reasoningBank?.stats();
+    const ruvllmStats = ruvllmCoordinator?.stats?.() || null;
+    // Fetch cross-module stats for unified reporting
+    let contrastiveTrainer = 'unavailable';
+    let trainingBackend = 'unavailable';
+    try {
+        // Synchronous check — contrastiveTrainer is module-level in sona-optimizer
+        // We read it via the SONAOptimizer singleton if available
+        const sonaModule = globalThis.__claudeFlowSonaStats;
+        if (sonaModule) {
+            contrastiveTrainer = sonaModule._contrastiveTrainer || 'unavailable';
+        }
+    }
+    catch { /* not available */ }
     return {
         sonaEnabled: !!sonaCoordinator,
         reasoningBankSize: bankStats?.size ?? 0,
@@ -844,7 +899,11 @@ export function getIntelligenceStats() {
         signalsProcessed: globalStats.signalsProcessed,
         trajectoriesRecorded: globalStats.trajectoriesRecorded,
         lastAdaptation: globalStats.lastAdaptation,
-        avgAdaptationTime: sonaStats?.avgAdaptationMs ?? 0
+        avgAdaptationTime: sonaStats?.avgAdaptationMs ?? 0,
+        _ruvllmBackend: ruvllmStats ? 'active' : 'unavailable',
+        _ruvllmTrajectories: ruvllmStats?.trajectoriesBuffered || 0,
+        _contrastiveTrainer: contrastiveTrainer,
+        _trainingBackend: trainingBackend,
     };
 }
 /**
@@ -1088,6 +1147,15 @@ export async function clearAllPatterns() {
 export function getNeuralDataDir() {
     return getDataDir();
 }
+/**
+ * Trigger background learning on the @ruvector/ruvllm SonaCoordinator.
+ * No-op if ruvllm is not installed.
+ */
+export async function runBackgroundLearning() {
+    const coord = await loadRuvllmCoordinator();
+    if (coord)
+        coord.runBackgroundLoop();
+}
 /**
  * Get persistence status
  */

package/v3/@claude-flow/cli/dist/src/memory/sona-optimizer.d.ts

@@ -87,6 +87,11 @@ export interface SONAStats {
     qLearningEnabled: boolean;
     /** Time of last learning update */
     lastUpdate: number | null;
+    /** Contrastive trainer status (from @ruvector/ruvllm) */
+    _contrastiveTrainer?: {
+        triplets: number;
+        agents: number;
+    } | 'unavailable';
 }
 /**
  * SONA Optimizer for adaptive routing based on trajectory outcomes
@@ -149,6 +154,17 @@ export declare class SONAOptimizer {
      * Get optimizer statistics
      */
     getStats(): SONAStats;
+    /**
+     * Trigger contrastive training on accumulated agent embeddings.
+     * Returns training metrics or { trained: false } if insufficient data.
+     *
+     * @param _epochs - reserved for future use (epochs are set at ContrastiveTrainer construction)
+     */
+    trainAgentEmbeddings(_epochs?: number): Promise<{
+        trained: boolean;
+        loss?: number;
+        triplets?: number;
+    }>;
     /**
      * Apply temporal decay to pattern confidence
      * Reduces confidence of unused patterns
@@ -166,6 +182,12 @@ export declare class SONAOptimizer {
      * Import patterns (for migration or testing)
      */
     importPatterns(patterns: Record<string, LearnedPattern>): number;
+    /**
+     * Convert extracted keywords into a lightweight 384-dim embedding proxy.
+     * Uses a deterministic hash-scatter so each keyword set maps to a
+     * consistent unit-length vector compatible with ContrastiveTrainer.
+     */
+    private keywordsToEmbedding;
     /**
      * Extract meaningful keywords from task description
      */

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

@@ -26,6 +26,26 @@ const CONFIDENCE_INCREMENT = 0.1;
 const CONFIDENCE_DECREMENT = 0.15;
 const DECAY_RATE = 0.01; // Per day
 const MAX_PATTERNS = 1000;
+// ============================================================================
+// Contrastive Trainer (lazy-loaded from @ruvector/ruvllm)
+// ============================================================================
+let contrastiveTrainer = null;
+let trainerLoaded = false;
+async function loadContrastiveTrainer() {
+    if (trainerLoaded)
+        return contrastiveTrainer;
+    trainerLoaded = true;
+    try {
+        const { createRequire } = await import('module');
+        const requireCjs = createRequire(import.meta.url);
+        const ruvllm = requireCjs('@ruvector/ruvllm');
+        contrastiveTrainer = new ruvllm.ContrastiveTrainer({ batchSize: 32, margin: 0.5 });
+        return contrastiveTrainer;
+    }
+    catch {
+        return null;
+    }
+}
 /**
  * Common agent types for routing
  */
@@ -159,6 +179,8 @@ export class SONAOptimizer {
             // Q-learning not available, continue without it
             this.qLearningEnabled = false;
         }
+        // Eagerly load ContrastiveTrainer so stats reflect backend status
+        await loadContrastiveTrainer();
         return {
             success: true,
             patternsLoaded: loaded ? this.patterns.size : 0,
@@ -218,6 +240,16 @@ export class SONAOptimizer {
             const reward = success ? 1.0 : -0.5;
             this.qLearningRouter.update(task, agent, reward);
         }
+        // Feed outcome into contrastive trainer for agent embedding learning (fire-and-forget)
+        if (success) {
+            loadContrastiveTrainer().then(trainer => {
+                if (!trainer)
+                    return;
+                // Use keyword vector as a lightweight embedding proxy
+                const embedding = this.keywordsToEmbedding(keywords);
+                trainer.addAgentEmbedding(agent, embedding);
+            }).catch(() => { });
+        }
         // Persist to disk (debounced)
         this.saveToDisk();
         return {
@@ -334,8 +366,25 @@ export class SONAOptimizer {
             avgConfidence: this.patterns.size > 0 ? totalConfidence / this.patterns.size : 0,
             qLearningEnabled: this.qLearningEnabled,
             lastUpdate: this.lastUpdate,
+            _contrastiveTrainer: contrastiveTrainer
+                ? { triplets: contrastiveTrainer.getTripletCount?.() ?? 0, agents: contrastiveTrainer.getAgentEmbeddings?.()?.size ?? 0 }
+                : 'unavailable',
         };
     }
+    /**
+     * Trigger contrastive training on accumulated agent embeddings.
+     * Returns training metrics or { trained: false } if insufficient data.
+     *
+     * @param _epochs - reserved for future use (epochs are set at ContrastiveTrainer construction)
+     */
+    async trainAgentEmbeddings(_epochs = 5) {
+        const trainer = await loadContrastiveTrainer();
+        if (!trainer || (trainer.getTripletCount?.() ?? 0) < 3) {
+            return { trained: false };
+        }
+        const result = trainer.train();
+        return { trained: true, loss: result.finalLoss, triplets: result.tripletCount };
+    }
     /**
      * Apply temporal decay to pattern confidence
      * Reduces confidence of unused patterns
@@ -404,6 +453,33 @@ export class SONAOptimizer {
     // ============================================================================
     // Private Methods
     // ============================================================================
+    /**
+     * Convert extracted keywords into a lightweight 384-dim embedding proxy.
+     * Uses a deterministic hash-scatter so each keyword set maps to a
+     * consistent unit-length vector compatible with ContrastiveTrainer.
+     */
+    keywordsToEmbedding(keywords) {
+        const dim = 384;
+        const vec = new Float32Array(dim);
+        for (const kw of keywords) {
+            // Simple FNV-1a-like hash per character to scatter energy across dims
+            let h = 0x811c9dc5;
+            for (let i = 0; i < kw.length; i++) {
+                h ^= kw.charCodeAt(i);
+                h = Math.imul(h, 0x01000193);
+            }
+            const idx = Math.abs(h) % dim;
+            vec[idx] += (h & 1) ? 1 : -1;
+        }
+        // L2-normalize
+        let norm = 0;
+        for (let i = 0; i < dim; i++)
+            norm += vec[i] * vec[i];
+        norm = Math.sqrt(norm) || 1;
+        for (let i = 0; i < dim; i++)
+            vec[i] /= norm;
+        return vec;
+    }
     /**
      * Extract meaningful keywords from task description
      */

package/v3/@claude-flow/cli/dist/src/ruvector/graph-backend.d.ts

@@ -0,0 +1,79 @@
+/**
+ * @ruvector/graph-node native graph database backend (ADR-087)
+ *
+ * Provides persistent graph storage for agent relationships, causal edges,
+ * task dependencies, and swarm topology using native Rust bindings.
+ *
+ * API requirements discovered via testing:
+ * - createNode: requires { id, type, embedding }
+ * - createEdge: requires { from, to, label, description, embedding, properties }
+ * - createHyperedge: requires { nodes[], label, description, embedding, properties }
+ * - kHopNeighbors(nodeId, k): returns string[] of node IDs
+ * - stats(): returns { totalNodes, totalEdges, avgDegree }
+ */
+export interface GraphNodeData {
+    id: string;
+    type: string;
+    name?: string;
+    properties?: Record<string, unknown>;
+}
+export interface GraphEdgeData {
+    from: string;
+    to: string;
+    label: string;
+    description?: string;
+    weight?: number;
+    properties?: Record<string, unknown>;
+}
+export interface GraphStats {
+    totalNodes: number;
+    totalEdges: number;
+    avgDegree: number;
+    backend: 'graph-node' | 'unavailable';
+}
+/**
+ * Check if graph-node backend is available
+ */
+export declare function isGraphBackendAvailable(): Promise<boolean>;
+/**
+ * Add a node to the graph (agent, task, pattern, etc.)
+ */
+export declare function addNode(data: GraphNodeData): Promise<string | null>;
+/**
+ * Add an edge between two nodes
+ */
+export declare function addEdge(data: GraphEdgeData): Promise<string | null>;
+/**
+ * Create a hyperedge connecting multiple nodes (e.g., swarm teams)
+ */
+export declare function addHyperedge(nodeIds: string[], label: string, description?: string, properties?: Record<string, unknown>): Promise<string | null>;
+/**
+ * Get k-hop neighbors of a node
+ */
+export declare function getNeighbors(nodeId: string, hops?: number): Promise<string[]>;
+/**
+ * Get graph statistics
+ */
+export declare function getGraphStats(): Promise<GraphStats>;
+/**
+ * Record a causal edge (used by agentdb_causal-edge MCP tool)
+ */
+export declare function recordCausalEdge(sourceId: string, targetId: string, relation: string, weight?: number): Promise<{
+    success: boolean;
+    edgeId?: string;
+    backend: string;
+}>;
+/**
+ * Record agent collaboration (used by swarm coordination)
+ */
+export declare function recordCollaboration(agentId: string, agentType: string, taskId: string, taskName: string): Promise<{
+    success: boolean;
+}>;
+/**
+ * Record swarm team as a hyperedge
+ */
+export declare function recordSwarmTeam(agentIds: string[], topology: string, taskDescription?: string): Promise<{
+    success: boolean;
+    hyperedgeId?: string;
+}>;
+//# sourceMappingURL=graph-backend.d.ts.map

package/v3/@claude-flow/cli/dist/src/ruvector/graph-backend.js

@@ -0,0 +1,220 @@
+/**
+ * @ruvector/graph-node native graph database backend (ADR-087)
+ *
+ * Provides persistent graph storage for agent relationships, causal edges,
+ * task dependencies, and swarm topology using native Rust bindings.
+ *
+ * API requirements discovered via testing:
+ * - createNode: requires { id, type, embedding }
+ * - createEdge: requires { from, to, label, description, embedding, properties }
+ * - createHyperedge: requires { nodes[], label, description, embedding, properties }
+ * - kHopNeighbors(nodeId, k): returns string[] of node IDs
+ * - stats(): returns { totalNodes, totalEdges, avgDegree }
+ */
+import { join } from 'path';
+// Lazy-loaded graph-node module
+let graphNodeModule = null;
+let graphDb = null;
+let graphBackendLoaded = false;
+let graphBackendAvailable = false;
+const DEFAULT_EMBEDDING_DIM = 8; // Minimal embedding for graph structure
+/**
+ * Load @ruvector/graph-node via createRequire (CJS package)
+ */
+async function loadGraphNode() {
+    if (graphBackendLoaded)
+        return graphNodeModule;
+    graphBackendLoaded = true;
+    try {
+        const { createRequire } = await import('module');
+        const requireCjs = createRequire(import.meta.url);
+        graphNodeModule = requireCjs('@ruvector/graph-node');
+        graphBackendAvailable = true;
+        return graphNodeModule;
+    }
+    catch {
+        graphBackendAvailable = false;
+        return null;
+    }
+}
+/**
+ * Get or create the singleton graph database instance
+ */
+async function getGraphDb() {
+    if (graphDb)
+        return graphDb;
+    const mod = await loadGraphNode();
+    if (!mod)
+        return null;
+    // Use persistent path if available, otherwise in-memory
+    const dataDir = join(process.cwd(), '.claude-flow', 'graph');
+    try {
+        const fs = await import('fs');
+        fs.mkdirSync(dataDir, { recursive: true });
+        graphDb = new mod.GraphDatabase(join(dataDir, 'agents.db'));
+    }
+    catch {
+        // Fallback to in-memory
+        graphDb = new mod.GraphDatabase();
+    }
+    return graphDb;
+}
+/**
+ * Create a minimal embedding for non-vector graph operations.
+ * Uses a deterministic hash of the string content.
+ */
+function textToMiniEmbedding(text) {
+    const emb = new Float32Array(DEFAULT_EMBEDDING_DIM);
+    for (let i = 0; i < text.length; i++) {
+        emb[i % DEFAULT_EMBEDDING_DIM] += text.charCodeAt(i) / 256;
+    }
+    // Normalize
+    let norm = 0;
+    for (let i = 0; i < emb.length; i++)
+        norm += emb[i] * emb[i];
+    norm = Math.sqrt(norm) || 1;
+    for (let i = 0; i < emb.length; i++)
+        emb[i] /= norm;
+    return emb;
+}
+/**
+ * Check if graph-node backend is available
+ */
+export async function isGraphBackendAvailable() {
+    await loadGraphNode();
+    return graphBackendAvailable;
+}
+/**
+ * Add a node to the graph (agent, task, pattern, etc.)
+ */
+export async function addNode(data) {
+    const db = await getGraphDb();
+    if (!db)
+        return null;
+    try {
+        const embedding = textToMiniEmbedding(`${data.type}:${data.name || data.id}`);
+        return await db.createNode({
+            id: data.id,
+            type: data.type,
+            ...data.properties,
+            embedding,
+        });
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Add an edge between two nodes
+ */
+export async function addEdge(data) {
+    const db = await getGraphDb();
+    if (!db)
+        return null;
+    try {
+        const embedding = textToMiniEmbedding(`${data.label}:${data.from}->${data.to}`);
+        return await db.createEdge({
+            from: data.from,
+            to: data.to,
+            label: data.label,
+            description: data.description || data.label,
+            embedding,
+            properties: { weight: data.weight ?? 1.0, ...data.properties },
+        });
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Create a hyperedge connecting multiple nodes (e.g., swarm teams)
+ */
+export async function addHyperedge(nodeIds, label, description, properties) {
+    const db = await getGraphDb();
+    if (!db)
+        return null;
+    try {
+        const embedding = textToMiniEmbedding(`${label}:${nodeIds.join(',')}`);
+        return await db.createHyperedge({
+            nodes: nodeIds,
+            label,
+            description: description || label,
+            embedding,
+            properties: properties || {},
+        });
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Get k-hop neighbors of a node
+ */
+export async function getNeighbors(nodeId, hops = 2) {
+    const db = await getGraphDb();
+    if (!db)
+        return [];
+    try {
+        return await db.kHopNeighbors(nodeId, hops);
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Get graph statistics
+ */
+export async function getGraphStats() {
+    const db = await getGraphDb();
+    if (!db)
+        return { totalNodes: 0, totalEdges: 0, avgDegree: 0, backend: 'unavailable' };
+    try {
+        const stats = await db.stats();
+        return { ...stats, backend: 'graph-node' };
+    }
+    catch {
+        return { totalNodes: 0, totalEdges: 0, avgDegree: 0, backend: 'unavailable' };
+    }
+}
+/**
+ * Record a causal edge (used by agentdb_causal-edge MCP tool)
+ */
+export async function recordCausalEdge(sourceId, targetId, relation, weight) {
+    // Ensure both nodes exist
+    await addNode({ id: sourceId, type: 'memory-entry' });
+    await addNode({ id: targetId, type: 'memory-entry' });
+    const edgeId = await addEdge({
+        from: sourceId,
+        to: targetId,
+        label: relation,
+        description: `${relation}: ${sourceId} -> ${targetId}`,
+        weight,
+    });
+    return {
+        success: edgeId !== null,
+        edgeId: edgeId ?? undefined,
+        backend: graphBackendAvailable ? 'graph-node' : 'unavailable',
+    };
+}
+/**
+ * Record agent collaboration (used by swarm coordination)
+ */
+export async function recordCollaboration(agentId, agentType, taskId, taskName) {
+    await addNode({ id: agentId, type: 'agent', name: agentType });
+    await addNode({ id: taskId, type: 'task', name: taskName });
+    const edgeId = await addEdge({
+        from: agentId,
+        to: taskId,
+        label: 'assigned_to',
+        description: `${agentType} works on ${taskName}`,
+    });
+    return { success: edgeId !== null };
+}
+/**
+ * Record swarm team as a hyperedge
+ */
+export async function recordSwarmTeam(agentIds, topology, taskDescription) {
+    const heId = await addHyperedge(agentIds, 'swarm-team', taskDescription || `${topology} swarm with ${agentIds.length} agents`, { topology, agentCount: agentIds.length });
+    return { success: heId !== null, hyperedgeId: heId ?? undefined };
+}
+//# sourceMappingURL=graph-backend.js.map

package/v3/@claude-flow/cli/dist/src/ruvector/lora-adapter.d.ts

@@ -94,6 +94,8 @@ export interface LoRAStats {
     avgAdaptationNorm: number;
     /** Last update timestamp */
     lastUpdate: number | null;
+    /** Training backend in use ('ruvllm' | 'js-fallback') */
+    _trainingBackend?: string;
 }
 /**
  * Low-Rank Adaptation module for efficient embedding fine-tuning
@@ -107,6 +109,16 @@ export declare class LoRAAdapter {
     private lastUpdate;
     private updatesSinceLastSave;
     constructor(config?: Partial<LoRAConfig>);
+    /**
+     * Eagerly load the ruvllm TrainingPipeline backend.
+     * Called automatically during first checkpoint operation,
+     * or call explicitly to make getStats() report backend status.
+     */
+    initBackend(): Promise<void>;
+    /**
+     * Get a readonly copy of the adapter configuration
+     */
+    getConfig(): Readonly<LoRAConfig>;
     /**
      * Initialize weights with Kaiming/He initialization
      */
@@ -156,6 +168,16 @@ export declare class LoRAAdapter {
      * Load weights from disk
      */
     loadWeights(): boolean;
+    /**
+     * Save a training checkpoint via ruvllm TrainingPipeline.
+     * Falls back to writing our own weight JSON if ruvllm is unavailable.
+     */
+    saveCheckpoint(path: string): Promise<boolean>;
+    /**
+     * Load a training checkpoint via ruvllm TrainingPipeline.
+     * Falls back to reading our own weight JSON if ruvllm is unavailable.
+     */
+    loadCheckpoint(path: string): Promise<boolean>;
     /**
      * Export weights as JSON
      */

package/v3/@claude-flow/cli/dist/src/ruvector/lora-adapter.js

@@ -53,6 +53,33 @@ const DEFAULT_CONFIG = {
     autoSaveInterval: 50,
 };
 // ============================================================================
+// @ruvector/ruvllm TrainingPipeline (lazy-loaded)
+// ============================================================================
+let ruvllmPipeline = null;
+let pipelineLoaded = false;
+async function loadTrainingPipeline(adapter) {
+    if (pipelineLoaded)
+        return ruvllmPipeline;
+    pipelineLoaded = true;
+    try {
+        const { createRequire } = await import('module');
+        const requireCjs = createRequire(import.meta.url);
+        const ruvllm = requireCjs('@ruvector/ruvllm');
+        const config = adapter.getConfig();
+        // Create a ruvllm LoraAdapter that mirrors our JS adapter's config
+        const nativeAdapter = new ruvllm.LoraAdapter(config.inputDim, config.outputDim, config.rank);
+        ruvllmPipeline = new ruvllm.TrainingPipeline({
+            adapter: nativeAdapter,
+            learningRate: 0.001,
+            batchSize: 8,
+        });
+        return ruvllmPipeline;
+    }
+    catch {
+        return null;
+    }
+}
+// ============================================================================
 // LoRA Adapter Class
 // ============================================================================
 /**
@@ -70,6 +97,20 @@ export class LoRAAdapter {
         this.config = { ...DEFAULT_CONFIG, ...config };
         this.weights = this.initializeWeights();
     }
+    /**
+     * Eagerly load the ruvllm TrainingPipeline backend.
+     * Called automatically during first checkpoint operation,
+     * or call explicitly to make getStats() report backend status.
+     */
+    async initBackend() {
+        await loadTrainingPipeline(this);
+    }
+    /**
+     * Get a readonly copy of the adapter configuration
+     */
+    getConfig() {
+        return this.config;
+    }
     /**
      * Initialize weights with Kaiming/He initialization
      */
@@ -254,6 +295,9 @@ export class LoRAAdapter {
                 ? this.adaptationNormSum / this.totalAdaptations
                 : 0,
             lastUpdate: this.lastUpdate,
+            _trainingBackend: pipelineLoaded
+                ? (ruvllmPipeline ? 'ruvllm' : 'js-fallback')
+                : 'js-fallback',
         };
     }
     /**
@@ -341,6 +385,57 @@ export class LoRAAdapter {
             return false;
         }
     }
+    /**
+     * Save a training checkpoint via ruvllm TrainingPipeline.
+     * Falls back to writing our own weight JSON if ruvllm is unavailable.
+     */
+    async saveCheckpoint(path) {
+        const pipeline = await loadTrainingPipeline(this);
+        if (pipeline) {
+            try {
+                pipeline.saveCheckpoint(path);
+                // Verify ruvllm actually wrote the file (some versions are no-op)
+                const fs = await import('fs');
+                if (fs.existsSync(path))
+                    return true;
+            }
+            catch { /* fall through to JS fallback */ }
+        }
+        // Fallback: save our own weights as JSON
+        try {
+            const fs = await import('fs');
+            const data = JSON.stringify(this.exportWeights());
+            fs.writeFileSync(path, data);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Load a training checkpoint via ruvllm TrainingPipeline.
+     * Falls back to reading our own weight JSON if ruvllm is unavailable.
+     */
+    async loadCheckpoint(path) {
+        const pipeline = await loadTrainingPipeline(this);
+        if (pipeline) {
+            try {
+                pipeline.loadCheckpoint(path);
+                return true;
+            }
+            catch { /* fall through to JS fallback */ }
+        }
+        // Fallback: load from our JSON format
+        try {
+            const fs = await import('fs');
+            if (fs.existsSync(path)) {
+                const data = JSON.parse(fs.readFileSync(path, 'utf-8'));
+                return this.importWeights(data);
+            }
+        }
+        catch { /* return false below */ }
+        return false;
+    }
     /**
      * Export weights as JSON
      */

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

@@ -1,6 +1,6 @@
 {
   "name": "@claude-flow/cli",
-  "version": "3.5.73",
+  "version": "3.5.75",
   "type": "module",
   "description": "Ruflo CLI - Enterprise AI agent orchestration with 60+ specialized agents, swarm coordination, MCP server, self-learning hooks, and vector memory for Claude Code",
   "main": "dist/src/index.js",