claude-flow 3.5.72 → 3.5.74

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-flow",
-  "version": "3.5.72",
+  "version": "3.5.74",
   "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/init/claudemd-generator.js

@@ -52,9 +52,8 @@ function concurrencyRules() {
     return `## Concurrency: 1 MESSAGE = ALL RELATED OPERATIONS
 
 - All operations MUST be concurrent/parallel in a single message
-- Use Claude Code's Task tool for spawning agents, not just MCP
-- ALWAYS batch ALL todos in ONE TodoWrite call (5-10+ minimum)
-- ALWAYS spawn ALL agents in ONE message with full instructions via Task tool
+- Use Claude Code's Agent tool for spawning agents, not just MCP
+- ALWAYS spawn ALL agents in ONE message with full instructions via Agent tool
 - ALWAYS batch ALL file reads/writes/edits in ONE message
 - ALWAYS batch ALL Bash commands in ONE message`;
 }
@@ -62,9 +61,9 @@ function swarmOrchestration() {
     return `## Swarm Orchestration
 
 - MUST initialize the swarm using CLI tools when starting complex tasks
-- MUST spawn concurrent agents using Claude Code's Task tool
-- Never use CLI tools alone for execution — Task tool agents do the actual work
-- MUST call CLI tools AND Task tool in ONE message for complex work
+- MUST spawn concurrent agents using Claude Code's Agent tool
+- Never use CLI tools alone for execution — Agent tool agents do the actual work
+- MUST call CLI tools AND Agent tool in ONE message for complex work
 
 ### 3-Tier Model Routing (ADR-026)
 
@@ -74,8 +73,7 @@ function swarmOrchestration() {
 | **2** | Haiku | ~500ms | $0.0002 | Simple tasks, low complexity (<30%) |
 | **3** | Sonnet/Opus | 2-5s | $0.003-0.015 | Complex reasoning, architecture, security (>30%) |
 
-- Always check for \`[AGENT_BOOSTER_AVAILABLE]\` or \`[TASK_MODEL_RECOMMENDATION]\` before spawning agents
-- Use Edit tool directly when \`[AGENT_BOOSTER_AVAILABLE]\``;
+- For Tier 1 simple transforms, use Edit tool directly — no LLM agent needed`;
 }
 function antiDriftConfig() {
     return `## Swarm Configuration & Anti-Drift
@@ -103,11 +101,11 @@ When the user requests a complex task, spawn agents in background and WAIT:
 Bash("npx @claude-flow/cli@latest swarm init --topology hierarchical --max-agents 8 --strategy specialized")
 
 // STEP 2: Spawn ALL agents IN BACKGROUND in a SINGLE message
-Task({prompt: "Research requirements...", subagent_type: "researcher", run_in_background: true})
-Task({prompt: "Design architecture...", subagent_type: "system-architect", run_in_background: true})
-Task({prompt: "Implement solution...", subagent_type: "coder", run_in_background: true})
-Task({prompt: "Write tests...", subagent_type: "tester", run_in_background: true})
-Task({prompt: "Review code quality...", subagent_type: "reviewer", run_in_background: true})
+Agent("Research requirements", "Analyze codebase patterns and store findings in memory", {subagent_type: "researcher", run_in_background: true})
+Agent("Design architecture", "Design architecture based on research", {subagent_type: "system-architect", run_in_background: true})
+Agent("Implement solution", "Implement the solution following the design", {subagent_type: "coder", run_in_background: true})
+Agent("Write tests", "Write comprehensive tests for the implementation", {subagent_type: "tester", run_in_background: true})
+Agent("Review code quality", "Review code quality, security, and best practices", {subagent_type: "reviewer", run_in_background: true})
 \`\`\`
 
 ### Agent Routing
@@ -128,10 +126,10 @@ Task({prompt: "Review code quality...", subagent_type: "reviewer", run_in_backgr
 function executionRules() {
     return `## Swarm Execution Rules
 
-- ALWAYS use \`run_in_background: true\` for all agent Task calls
-- ALWAYS put ALL agent Task calls in ONE message for parallel execution
+- ALWAYS use \`run_in_background: true\` for all Agent tool calls
+- ALWAYS put ALL Agent calls in ONE message for parallel execution
 - After spawning, STOP — do NOT add more tool calls or check status
-- Never poll TaskOutput or check swarm status — trust agents to return
+- Never poll agent status repeatedly — trust agents to return
 - When agent results arrive, review ALL results before proceeding`;
 }
 function cliCommandsTable() {
@@ -407,7 +405,7 @@ npx @claude-flow/cli@latest doctor --fix
 
 ## Claude Code vs MCP Tools
 
-- **Claude Code Task tool** handles execution: agents, file ops, code generation, git
+- **Claude Code Agent tool** handles execution: agents, file ops, code generation, git
 - **MCP tools** (via ToolSearch) handle coordination: swarm, memory, hooks, routing, hive-mind
 - **CLI commands** (via Bash) are the same tools with terminal output
 - Use \`ToolSearch("keyword")\` to discover available MCP tools

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

@@ -291,6 +291,7 @@ async function getSemanticRouter() {
             }
             nativeVectorDb = db;
             routerBackend = 'native';
+            console.log('[hooks] Semantic router initialized: native VectorDb (HNSW, 16k+ routes/s)');
             return { router: null, backend: routerBackend, native: nativeVectorDb };
         }
     }
@@ -312,10 +313,12 @@ async function getSemanticRouter() {
             });
         }
         routerBackend = 'pure-js';
+        console.log('[hooks] Semantic router initialized: pure JS (cosine, 47k routes/s)');
     }
     catch {
         semanticRouter = null;
         routerBackend = 'none';
+        console.log('[hooks] Semantic router initialized: none (no backend available)');
     }
     return { router: semanticRouter, backend: routerBackend, native: nativeVectorDb };
 }
@@ -2030,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,
@@ -2041,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: [],
@@ -2304,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();
@@ -2668,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/neural-tools.js

@@ -131,7 +131,11 @@ async function generateEmbedding(text, dims = 384) {
         }
     }
     // Hash-based deterministic embedding (better than pure random for consistency)
+    // NOTE: No semantic meaning — only useful for consistent deduplication, not similarity search
     if (text) {
+        if (embeddingServiceName === 'none') {
+            embeddingServiceName = 'hash-fallback';
+        }
         const hash = text.split('').reduce((acc, char, i) => {
             return acc + char.charCodeAt(0) * (i + 1);
         }, 0);
@@ -238,6 +242,7 @@ export const neuralTools = [
             return {
                 success: true,
                 _realEmbedding: !!realEmbeddings,
+                _embeddingSource: embeddingServiceName,
                 embeddingProvider: embeddingServiceName,
                 modelId,
                 type: modelType,
@@ -307,6 +312,7 @@ export const neuralTools = [
             return {
                 success: true,
                 _realEmbedding: !!realEmbeddings,
+                _embeddingSource: embeddingServiceName,
                 embeddingProvider: embeddingServiceName,
                 _hasStoredPatterns: storedPatterns.length > 0,
                 modelId: model?.id || 'default',
@@ -397,6 +403,7 @@ export const neuralTools = [
                 return {
                     success: true,
                     _realEmbedding: !!realEmbeddings,
+                    _embeddingSource: embeddingServiceName,
                     embeddingProvider: embeddingServiceName,
                     patternId,
                     name: pattern.name,
@@ -420,6 +427,7 @@ export const neuralTools = [
                 return {
                     _realSimilarity: true,
                     _realEmbedding: !!realEmbeddings,
+                    _embeddingSource: embeddingServiceName,
                     embeddingProvider: embeddingServiceName,
                     query,
                     results: results.map(r => ({

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

@@ -60,7 +60,7 @@ export interface RoutingSuggestion {
     /** Whether Q-learning was used */
     usedQLearning: boolean;
     /** Source of recommendation */
-    source: 'sona-pattern' | 'q-learning' | 'keyword-match' | 'default';
+    source: 'sona-native' | 'sona-pattern' | 'q-learning' | 'sona-keyword' | 'default';
     /** Alternative agents with scores */
     alternatives: Array<{
         agent: string;
@@ -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
@@ -103,9 +108,20 @@ export declare class SONAOptimizer {
     private persistencePath;
     private qLearningRouter;
     private qLearningEnabled;
+    /** Real @ruvector/sona engine — null if native not available, undefined if not yet tried */
+    private sonaEngine;
     constructor(options?: {
         persistencePath?: string;
     });
+    /**
+     * Attempt to load the native @ruvector/sona engine (once).
+     * Sets `sonaEngine` to the engine instance or null if unavailable.
+     */
+    private loadSonaEngine;
+    /**
+     * Infer an agent type string from a SONA pattern result object.
+     */
+    private inferAgentFromPattern;
     /**
      * Initialize the optimizer and load persisted state
      */
@@ -124,13 +140,31 @@ export declare class SONAOptimizer {
         keywordsExtracted: string[];
     };
     /**
-     * Get routing suggestion based on learned patterns
+     * Get routing suggestion based on learned patterns.
+     *
+     * Priority order:
+     * 1. Real @ruvector/sona native engine (if available and has matches)
+     * 2. SONA learned pattern matching (keyword overlap + confidence)
+     * 3. Q-learning router (if enabled)
+     * 4. Keyword heuristic
+     * 5. Default fallback
      */
-    getRoutingSuggestion(task: string): RoutingSuggestion;
+    getRoutingSuggestion(task: string): Promise<RoutingSuggestion>;
     /**
      * 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
@@ -148,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
      */