π The original agent harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, federation, vector RAG integration, and native Claude Code / Codex / Hermes and many more Integrated
TypeScript agentic-aiagentic-frameworkagentic-workflowagentsai-agentsai-assistantai-skillsautonomous-agentsclaudecodexdsh-pluginharnessmcp-servermulti-agentmulti-agent-systemsnpmskillsswarmswarm-intelligencetypescript
feat: native ruvllm + graph-node intelligence backends (ADR-086, ADR-087)
Reuven7eb505d22f11
diff --git a/.agents/skills/agentdb-advanced/SKILL.md b/.agents/skills/agentdb-advanced/SKILL.mdindex 145d324f71..298845ea47 100644--- a/.agents/skills/agentdb-advanced/SKILL.md+++ b/.agents/skills/agentdb-advanced/SKILL.md@@ -503,7 +503,8 @@ AGENTDB_QUIC_PEERS=host1:4433,host2:4433```bash# Check firewall allows UDP port 4433-sudo ufw allow 4433$udp+# NOTE: Requires administrator privileges - for reference only+sudo ufw allow 4433/udp# Verify peers are reachableping host1diff --git a/.agents/skills/github-multi-repo/SKILL.md b/.agents/skills/github-multi-repo/SKILL.mdindex 0cc4195994..73ff842fe0 100644--- a/.agents/skills/github-multi-repo/SKILL.md+++ b/.agents/skills/github-multi-repo/SKILL.md@@ -42,12 +42,12 @@ Cross-package integration testing and deployment coordination.```bash# Basic swarm initializationnpx claude-flow skill run github-multi-repo init \- --repos "org$frontend,org$backend,org$shared" \+ --repos "org/frontend,org/backend,org/shared" \--topology hierarchical# Advanced initialization with synchronizationnpx claude-flow skill run github-multi-repo init \- --repos "org$frontend,org$backend,org$shared" \+ --repos "org/frontend,org/backend,org/shared" \--topology mesh \--shared-memory \--sync-strategy eventual@@ -85,8 +85,8 @@ const REPOS = Bash(`gh repo list my-organization --limit 100 \// Analyze repository dependenciesconst DEPS = Bash(`gh repo list my-organization --json name | \jq -r '.[].name' | while read -r repo; do- gh api repos$my-organization/$repo$contents$package.json \- --jq '.content' 2>$dev$null | base64 -d | jq '{name, dependencies}'+ gh api repos/my-organization/$repo/contents/package.json \+ --jq '.content' 2>/dev/null | base64 -d | jq '{name, dependencies}'done | jq -s '.'`)// Initialize swarm with discovered repositories@@ -108,10 +108,10 @@ mcp__claude-flow__swarm_init({// Get matching repositoriesBash(`gh repo list org --limit 100 --json name \- --jq '.[] | select(.name | test("-service$")) | .name' > $tmp$repos.txt`)+ --jq '.[] | select(.name | test("-service$")) | .name' > /tmp/repos.txt`)// Execute task across repositories- Bash(`cat $tmp$repos.txt | while read -r repo; do+ Bash(`cat /tmp/repos.txt | while read -r repo; dogh repo clone org/$repo /tmp/$repo -- --depth=1cd /tmp/$repo@@ -153,25 +153,25 @@ mcp__claude-flow__swarm_init({Task("Integration Tester", "Validate synchronization", "tester")// Read package states- Read("$workspaces$ruv-FANN$claude-code-flow$claude-code-flow$package.json")- Read("$workspaces$ruv-FANN$ruv-swarm$npm$package.json")+ Read("/workspaces/ruv-FANN/claude-code-flow/claude-code-flow/package.json")+ Read("/workspaces/ruv-FANN/ruv-swarm/npm/package.json")// Align versions using gh CLI- Bash(`gh api repos/:owner/:repo$git$refs \- -f ref='refs$heads$sync$package-alignment' \- -f sha=$(gh api repos/:owner/:repo$git$refs$heads$main --jq '.object.sha')`)+ Bash(`gh api repos/:owner/:repo/git/refs \+ -f ref='refs/heads/sync/package-alignment' \+ -f sha=$(gh api repos/:owner/:repo/git/refs/heads/main --jq '.object.sha')`)// Update package.json files- Bash(`gh api repos/:owner/:repo$contents$package.json \+ Bash(`gh api repos/:owner/:repo/contents/package.json \--method PUT \-f message="feat: Align Node.js version requirements" \- -f branch="sync$package-alignment" \+ -f branch="sync/package-alignment" \-f content="$(cat aligned-package.json | base64)"`)// Store sync statemcp__claude-flow__memory_usage({action: "store",- key: "sync$packages$status",+ key: "sync/packages/status",value: {timestamp: Date.now(),packages_synced: ["claude-code-flow", "ruv-swarm"],@@ -185,20 +185,20 @@ mcp__claude-flow__swarm_init({// Synchronize CLAUDE.md files across packages[Documentation Sync]:// Get source documentation- Bash(`gh api repos/:owner/:repo$contents$ruv-swarm/docs/CLAUDE.md \- --jq '.content' | base64 -d > $tmp$claude-source.md`)+ Bash(`gh api repos/:owner/:repo/contents/ruv-swarm/docs/CLAUDE.md \+ --jq '.content' | base64 -d > /tmp/claude-source.md`)// Update target documentation- Bash(`gh api repos/:owner/:repo$contents$claude-code-flow/CLAUDE.md \+ Bash(`gh api repos/:owner/:repo/contents/claude-code-flow/CLAUDE.md \--method PUT \-f message="docs: Synchronize CLAUDE.md" \- -f branch="sync$documentation" \- -f content="$(cat $tmp$claude-source.md | base64)"`)+ -f branch="sync/documentation" \+ -f content="$(cat /tmp/claude-source.md | base64)"`)// Track sync statusmcp__claude-flow__memory_usage({action: "store",- key: "sync$documentation$status",+ key: "sync/documentation/status",value: { status: "synchronized", files: ["CLAUDE.md"] }})```@@ -209,14 +209,14 @@ mcp__claude-flow__swarm_init({[Cross-Package Feature]:// Push changes to all packagesmcp__github__push_files({- branch: "feature$github-integration",+ branch: "feature/github-integration",files: [{- path: "claude-code-flow/.claude$commands$github$github-modes.md",+ path: "claude-code-flow/.claude/commands/github/github-modes.md",content: "[GitHub modes documentation]"},{- path: "ruv-swarm$src$github-coordinator$hooks.js",+ path: "ruv-swarm/src/github-coordinator/hooks.js",content: "[GitHub coordination hooks]"}],@@ -255,8 +255,8 @@ mcp__claude-flow__swarm_init({Task("Best Practices Researcher", "Research architecture patterns", "researcher")// Analyze current structures- LS("$workspaces$ruv-FANN$claude-code-flow$claude-code-flow")- LS("$workspaces$ruv-FANN$ruv-swarm$npm")+ LS("/workspaces/ruv-FANN/claude-code-flow/claude-code-flow")+ LS("/workspaces/ruv-FANN/ruv-swarm/npm")// Search for best practicesBash(`gh search repos "language:javascript template architecture" \@@ -268,7 +268,7 @@ mcp__claude-flow__swarm_init({// Store analysis resultsmcp__claude-flow__memory_usage({action: "store",- key: "architecture$analysis$results",+ key: "architecture/analysis/results",value: {repositories_analyzed: ["claude-code-flow", "ruv-swarm"],optimization_areas: ["structure", "workflows", "templates"],@@ -294,11 +294,11 @@ mcp__claude-flow__swarm_init({repo: "claude-project-template",files: [{- path: ".claude$commands$github$github-modes.md",+ path: ".claude/commands/github/github-modes.md",content: "[GitHub modes template]"},{- path: ".claude$config.json",+ path: ".claude/config.json",content: JSON.stringify({version: "1.0",mcp_servers: {@@ -336,19 +336,19 @@ mcp__claude-flow__swarm_init({repositories.forEach(repo => {mcp__github__create_or_update_file({repo: "ruv-FANN",- path: `${repo}/.github$workflows$integration.yml`,+ path: `${repo}/.github/workflows/integration.yml`,content: `name: Integration Testson: [push, pull_request]jobs:test:runs-on: ubuntu-lateststeps:- - uses: actions$checkout@v3- - uses: actions$setup-node@v3+ - uses: actions/checkout@v3+ - uses: actions/setup-node@v3with: { node-version: '20' }- run: npm install && npm test`,message: "ci: Standardize integration workflow",- branch: "structure$standardization"+ branch: "structure/standardization"})})```@@ -369,7 +369,7 @@ jobs:// Find all TypeScript repositoriesTS_REPOS=$(Bash(`gh repo list org --limit 100 --json name | \jq -r '.[].name' | while read -r repo; do- if gh api repos$org/$repo$contents$package.json 2>$dev$null | \+ if gh api repos/org/$repo/contents/package.json 2>/dev/null | \jq -r '.content' | base64 -d | grep -q '"typescript"'; thenecho "$repo"fi@@ -432,17 +432,17 @@ Part of #$TRACKING_ISSUE"while read -r repo; dogh repo clone org/$repo /tmp/$repo -- --depth=1cd /tmp/$repo- npm audit --json > $tmp$audit-$repo.json+ npm audit --json > /tmp/audit-$repo.jsondone`)// Apply patches- Bash(`for repo in $tmp$audit-*.json; do+ Bash(`for repo in /tmp/audit-*.json; doif [ $(jq '.vulnerabilities | length' $repo) -gt 0 ]; then- cd /tmp/$(basename $repo .json | sed 's$audit-//')+ cd /tmp/$(basename $repo .json | sed 's/audit-//')npm audit fixif npm test; then- git checkout -b security$patch-$(date +%Y%m%d)+ git checkout -b security/patch-$(date +%Y%m%d)git add -Agit commit -m "security: Apply security patches"git push origin HEAD@@ -456,30 +456,30 @@ Part of #$TRACKING_ISSUE"### Multi-Repo Config File```yaml-# .swarm$multi-repo.yml+# .swarm/multi-repo.ymlversion: 1organization: my-orgrepositories:- name: frontend- url: github.com$my-org$frontend+ url: github.com/my-org/frontendrole: uiagents: [coder, designer, tester]- name: backend- url: github.com$my-org$backend+ url: github.com/my-org/backendrole: apiagents: [architect, coder, tester]- name: shared- url: github.com$my-org$shared+ url: github.com/my-org/sharedrole: libraryagents: [analyst, coder]coordination:topology: hierarchicalcommunication: webhook- memory: redis:/$shared-memory+ memory: redis://shared-memorydependencies:- from: frontend@@ -516,7 +516,7 @@ const { MultiRepoSwarm } = require('ruv-swarm');const swarm = new MultiRepoSwarm({webhook: {- url: 'https:/$swarm-coordinator.example.com',+ url: 'https://swarm-coordinator.example.com',secret: process.env.WEBHOOK_SECRET}});@@ -599,7 +599,7 @@ npx claude-flow skill run github-multi-repo microservices \### 2. Library Updates```bashnpx claude-flow skill run github-multi-repo lib-update \- --library "org$shared-lib" \+ --library "org/shared-lib" \--version "2.0.0" \--find-consumers \--update-imports \@@ -812,9 +812,9 @@ npx claude-flow skill run github-multi-repo to-monorepo \### Full-Stack Application Update```bashnpx claude-flow skill run github-multi-repo fullstack-update \- --frontend "org$web-app" \- --backend "org$api-server" \- --database "org$db-migrations" \+ --frontend "org/web-app" \+ --backend "org/api-server" \+ --database "org/db-migrations" \--coordinate-deployment```@@ -856,16 +856,16 @@ npx claude-flow skill run github-multi-repo cross-team \- `sparc-optimizer` - Performance optimization### Related Commands-- `$github sync-coordinator` - Cross-repo synchronization-- `$github release-manager` - Coordinated releases-- `$github repo-architect` - Repository optimization-- `$sparc architect` - Detailed architecture design+- `/github sync-coordinator` - Cross-repo synchronization+- `/github release-manager` - Coordinated releases+- `/github repo-architect` - Repository optimization+- `/sparc architect` - Detailed architecture design## Support and Resources-- Documentation: https:/$github.com$ruvnet$claude-flow-- Issues: https:/$github.com$ruvnet$claude-flow$issues-- Examples: `.claude$examples$github-multi-repo/`+- Documentation: https://github.com/ruvnet/claude-flow+- Issues: https://github.com/ruvnet/claude-flow/issues+- Examples: `.claude/examples/github-multi-repo/`---diff --git a/.agents/skills/hooks-automation/SKILL.md b/.agents/skills/hooks-automation/SKILL.mdindex 6bc6b971b3..1523ceed6e 100644--- a/.agents/skills/hooks-automation/SKILL.md+++ b/.agents/skills/hooks-automation/SKILL.md@@ -103,7 +103,7 @@ Options:--require-confirmation Request user confirmation for risky commandsExamples:- npx claude-flow hook pre-bash -c "rm -rf $tmp$cache"+ npx claude-flow hook pre-bash -c "rm -rf /tmp/cache"npx claude-flow hook pre-bash --command "docker build ." --estimate-resources```diff --git a/package-lock.json b/package-lock.jsonindex cbab435410..8563f30495 100644--- a/package-lock.json+++ b/package-lock.json@@ -1,12 +1,12 @@{"name": "claude-flow",- "version": "3.5.72",+ "version": "3.5.73","lockfileVersion": 3,"requires": true,"packages": {"": {"name": "claude-flow",- "version": "3.5.72",+ "version": "3.5.73","license": "MIT","dependencies": {"semver": "^7.6.0",diff --git a/package.json b/package.jsonindex f6b8acec49..9b147b9f75 100644--- a/package.json+++ b/package.json@@ -1,6 +1,6 @@{"name": "claude-flow",- "version": "3.5.72",+ "version": "3.5.73","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",diff --git a/ruflo/package.json b/ruflo/package.jsonindex 3101b87b83..cd150741c2 100644--- a/ruflo/package.json+++ b/ruflo/package.json@@ -1,6 +1,6 @@{"name": "ruflo",- "version": "3.5.72",+ "version": "3.5.73","description": "Ruflo - Enterprise AI agent orchestration platform. Deploy 60+ specialized agents in coordinated swarms with self-learning, fault-tolerant consensus, vector memory, and MCP integration","main": "bin/ruflo.js","type": "module",diff --git a/v3/@claude-flow/cli/__tests__/graph-backend.test.ts b/v3/@claude-flow/cli/__tests__/graph-backend.test.tsnew file mode 100644index 0000000000..62c5ca6edb--- /dev/null+++ b/v3/@claude-flow/cli/__tests__/graph-backend.test.ts@@ -0,0 +1,92 @@+/**+ * ADR-087: @ruvector/graph-node native graph database backend tests+ *+ * Tests the wrapper module's exports and CJS import pattern.+ * The actual graph-node integration is verified by the e2e node script.+ */+import { describe, it, expect } from 'vitest';++describe('ADR-087: graph-node backend', () => {+ describe('module exports', () => {+ it('exports all expected functions', async () => {+ const mod = await import('../src/ruvector/graph-backend.js');+ expect(typeof mod.isGraphBackendAvailable).toBe('function');+ expect(typeof mod.addNode).toBe('function');+ expect(typeof mod.addEdge).toBe('function');+ expect(typeof mod.addHyperedge).toBe('function');+ expect(typeof mod.getNeighbors).toBe('function');+ expect(typeof mod.getGraphStats).toBe('function');+ expect(typeof mod.recordCausalEdge).toBe('function');+ expect(typeof mod.recordCollaboration).toBe('function');+ expect(typeof mod.recordSwarmTeam).toBe('function');+ });+ });++ describe('graceful degradation', () => {+ it('getGraphStats returns unavailable when graph-node not loaded', async () => {+ // In test environment, graph-node may or may not be available+ const { getGraphStats } = await import('../src/ruvector/graph-backend.js');+ const stats = await getGraphStats();+ expect(stats).toHaveProperty('totalNodes');+ expect(stats).toHaveProperty('totalEdges');+ expect(stats).toHaveProperty('avgDegree');+ expect(stats).toHaveProperty('backend');+ expect(['graph-node', 'unavailable']).toContain(stats.backend);+ });++ it('addNode returns string or null', async () => {+ const { addNode } = await import('../src/ruvector/graph-backend.js');+ const result = await addNode({ id: 'test-1', type: 'test' });+ // Either a node ID string or null if backend unavailable+ expect(result === null || typeof result === 'string').toBe(true);+ });++ it('getNeighbors returns array', async () => {+ const { getNeighbors } = await import('../src/ruvector/graph-backend.js');+ const result = await getNeighbors('nonexistent', 2);+ expect(Array.isArray(result)).toBe(true);+ });++ it('recordCausalEdge returns result with backend', async () => {+ const { recordCausalEdge } = await import('../src/ruvector/graph-backend.js');+ const result = await recordCausalEdge('a', 'b', 'caused');+ expect(result).toHaveProperty('success');+ expect(result).toHaveProperty('backend');+ });++ it('recordSwarmTeam returns result', async () => {+ const { recordSwarmTeam } = await import('../src/ruvector/graph-backend.js');+ const result = await recordSwarmTeam(['a', 'b'], 'mesh');+ expect(result).toHaveProperty('success');+ });+ });++ describe('CJS import pattern', () => {+ it('source uses createRequire for @ruvector/graph-node', async () => {+ const { readFileSync } = await import('fs');+ const { join } = await import('path');+ const content = readFileSync(join(import.meta.dirname, '..', 'src', 'ruvector', 'graph-backend.ts'), 'utf8');+ expect(content).toContain('createRequire');+ expect(content).toContain("'@ruvector/graph-node'");+ // Should NOT use ESM dynamic import for graph-node+ expect(content).not.toMatch(/await import\(['"]@ruvector\/graph-node['"]\)/);+ });+ });++ describe('type exports', () => {+ it('exports GraphNodeData interface shape', async () => {+ const { addNode } = await import('../src/ruvector/graph-backend.js');+ // TypeScript ensures this matches GraphNodeData+ const data = { id: 'x', type: 'agent', name: 'test', properties: { foo: 'bar' } };+ const result = await addNode(data);+ expect(result === null || typeof result === 'string').toBe(true);+ });++ it('exports GraphEdgeData interface shape', async () => {+ const { addEdge } = await import('../src/ruvector/graph-backend.js');+ const data = { from: 'a', to: 'b', label: 'test', description: 'desc', weight: 0.5, properties: {} };+ const result = await addEdge(data);+ expect(result === null || typeof result === 'string').toBe(true);+ });+ });+});diff --git a/v3/@claude-flow/cli/__tests__/memory-ruvector-deep.test.ts b/v3/@claude-flow/cli/__tests__/memory-ruvector-deep.test.tsindex 96905f85d8..034415b549 100644--- a/v3/@claude-flow/cli/__tests__/memory-ruvector-deep.test.ts+++ b/v3/@claude-flow/cli/__tests__/memory-ruvector-deep.test.ts@@ -416,28 +416,28 @@ describe('SONA Optimizer', () => {});describe('getRoutingSuggestion', () => {- it('should suggest coder for implementation tasks', () => {- const suggestion = optimizer.getRoutingSuggestion('implement a new feature for authentication');+ it('should suggest coder for implementation tasks', async () => {+ const suggestion = await optimizer.getRoutingSuggestion('implement a new feature for authentication');expect(suggestion.agent).toBeDefined();expect(suggestion.confidence).toBeGreaterThan(0);expect(suggestion.source).toBeDefined();});- it('should suggest tester for test tasks', () => {- const suggestion = optimizer.getRoutingSuggestion('write unit test coverage for the API');+ it('should suggest tester for test tasks', async () => {+ const suggestion = await optimizer.getRoutingSuggestion('write unit test coverage for the API');expect(suggestion.agent).toBeDefined();expect(['tester', 'coder', 'reviewer']).toContain(suggestion.agent);});- it('should fallback to default for unknown tasks', () => {- const suggestion = optimizer.getRoutingSuggestion('xyzzy');+ it('should fallback to default for unknown tasks', async () => {+ const suggestion = await optimizer.getRoutingSuggestion('xyzzy');expect(suggestion.agent).toBe('coder');expect(suggestion.source).toBe('default');expect(suggestion.confidence).toBe(0.3);});- it('should include alternatives', () => {- const suggestion = optimizer.getRoutingSuggestion('implement and test security audit');+ it('should include alternatives', async () => {+ const suggestion = await optimizer.getRoutingSuggestion('implement and test security audit');expect(suggestion.alternatives).toBeDefined();expect(Array.isArray(suggestion.alternatives)).toBe(true);});diff --git a/v3/@claude-flow/cli/__tests__/pq-validation.test.ts b/v3/@claude-flow/cli/__tests__/pq-validation.test.tsnew file mode 100644index 0000000000..be8812de94--- /dev/null+++ b/v3/@claude-flow/cli/__tests__/pq-validation.test.ts@@ -0,0 +1,201 @@+/**+ * Product Quantization Validation Tests+ *+ * Validates the PQ implementation inside the Quantizer class (hnsw-index.ts):+ * k-means convergence, encoding, distance, compression, training threshold,+ * and pre-training fallback.+ */+import { describe, it, expect } from 'vitest';+import { HNSWIndex } from '../../@claude-flow/memory/src/hnsw-index.js';++const DIM = 384;+const NUM_SUB = 8;++/** Create a deterministic vector: cluster centre + small noise */+function makeVec(centre: number[], noise = 0.01, seed = 0): Float32Array {+ const v = new Float32Array(DIM);+ for (let i = 0; i < DIM; i++) {+ v[i] = centre[i % centre.length] + noise * Math.sin(seed * 17 + i);+ }+ return v;+}++/** Build three well-separated cluster centres */+const C1 = Array.from({ length: DIM }, () => 1.0);+const C2 = Array.from({ length: DIM }, () => -1.0);+const C3 = Array.from({ length: DIM }, () => 0.0);++// ---------------------------------------------------------------------------+// Helpers to reach into the private Quantizer via the index+// ---------------------------------------------------------------------------+function createPQIndex(maxElements = 600): HNSWIndex {+ return new HNSWIndex({+ dimensions: DIM,+ M: 4,+ efConstruction: 20,+ maxElements,+ metric: 'euclidean',+ quantization: { type: 'product', subquantizers: NUM_SUB, codebookSize: 256 },+ });+}++function getQuantizer(index: HNSWIndex): any {+ return (index as any).quantizer;+}++// ===========================================================================+describe('Product Quantization', () => {+ // -------------------------------------------------------------------------+ // 1. k-means converges on 3 clear clusters+ // -------------------------------------------------------------------------+ it('k-means converges on 3 well-separated clusters', () => {+ const q = getQuantizer(createPQIndex());++ // Build tiny dataset of 2-d points in 3 clusters.+ // Interleave so the first 3 points seed one centroid per cluster+ // (kMeans init picks the first k data points).+ const data: number[][] = [];+ for (let i = 0; i < 30; i++) {+ data.push([0 + Math.random() * 0.1, 0 + Math.random() * 0.1]);+ data.push([10 + Math.random() * 0.1, 10 + Math.random() * 0.1]);+ data.push([20 + Math.random() * 0.1, 20 + Math.random() * 0.1]);+ }++ // Access private kMeans+ const centroids: number[][] = (q as any).kMeans(data, 3, 50);++ expect(centroids).toHaveLength(3);++ // Each centroid should be near one of [0,0], [10,10], [20,20]+ const targets = [[0, 0], [10, 10], [20, 20]];+ const matched = new Set<number>();+ for (const c of centroids) {+ for (let t = 0; t < targets.length; t++) {+ const dist = Math.hypot(c[0] - targets[t][0], c[1] - targets[t][1]);+ if (dist < 1.0 && !matched.has(t)) { matched.add(t); break; }+ }+ }+ expect(matched.size).toBe(3);+ });++ // -------------------------------------------------------------------------+ // 2. PQ encoding returns correct number of indices+ // -------------------------------------------------------------------------+ it('PQ encoding returns numSubquantizers indices after training', async () => {+ const index = createPQIndex();+ const q = getQuantizer(index);++ // Feed 256 vectors to trigger training+ const vecs: number[][] = [];+ for (let i = 0; i < 256; i++) {+ const v = makeVec(i < 128 ? C1 : C2, 0.05, i);+ vecs.push(Array.from(v));+ }+ q.trainingVectors = vecs;+ q.codebooks = q.trainProductQuantizer(vecs, NUM_SUB, 256);+ q.pqTrained = true;++ const encoded = q.encode(makeVec(C1, 0.01, 999));+ expect(encoded).toBeInstanceOf(Float32Array);+ expect(encoded.length).toBe(NUM_SUB);+ // All indices should be in [0, 256)+ for (let i = 0; i < encoded.length; i++) {+ expect(encoded[i]).toBeGreaterThanOrEqual(0);+ expect(encoded[i]).toBeLessThan(256);+ }+ });++ // -------------------------------------------------------------------------+ // 3. PQ distance between identical vectors is 0+ // -------------------------------------------------------------------------+ it('PQ distance between identical encoded vectors is 0', () => {+ const index = createPQIndex();+ const q = getQuantizer(index);++ // Train codebooks+ const vecs: number[][] = [];+ for (let i = 0; i < 256; i++) vecs.push(Array.from(makeVec(C1, 0.1, i)));+ q.codebooks = q.trainProductQuantizer(vecs, NUM_SUB, 256);+ q.pqTrained = true;++ const v = makeVec(C1, 0.01, 42);+ const enc = q.encode(v);+ const indices = new Uint8Array(enc);++ const dist = q.productQuantizeDistance(indices, indices);+ expect(dist).toBe(0);+ });++ // -------------------------------------------------------------------------+ // 4. PQ distance between different vectors is > 0+ // -------------------------------------------------------------------------+ it('PQ distance between different encoded vectors is > 0', () => {+ const index = createPQIndex();+ const q = getQuantizer(index);++ const vecs: number[][] = [];+ for (let i = 0; i < 256; i++) {+ vecs.push(Array.from(makeVec(i < 128 ? C1 : C2, 0.05, i)));+ }+ q.codebooks = q.trainProductQuantizer(vecs, NUM_SUB, 256);+ q.pqTrained = true;++ const enc1 = new Uint8Array(q.encode(makeVec(C1, 0.001, 0)));+ const enc2 = new Uint8Array(q.encode(makeVec(C2, 0.001, 1)));++ const dist = q.productQuantizeDistance(enc1, enc2);+ expect(dist).toBeGreaterThan(0);+ });++ // -------------------------------------------------------------------------+ // 5. Compression ratio: 384-dim float32 -> 8 bytes with 8 sub-quantizers+ // -------------------------------------------------------------------------+ it('compression ratio is correct (384-dim f32 -> 8 sub-quantizers)', () => {+ const index = createPQIndex();+ const stats = index.getStats();+ // product quantization compression ratio = subquantizers count+ expect(stats.compressionRatio).toBe(NUM_SUB);+ });++ // -------------------------------------------------------------------------+ // 6. Training threshold: accumulates until 256, then trains+ // -------------------------------------------------------------------------+ it('training threshold works: not trained until 256 vectors', () => {+ const index = createPQIndex(600);+ const q = getQuantizer(index);++ // Feed 255 vectors β should NOT be trained yet+ for (let i = 0; i < 255; i++) {+ q.encode(makeVec(C1, 0.1, i));+ }+ expect(q.isPQTrained).toBe(false);+ expect(q.trainingVectors).toHaveLength(255);++ // Feed the 256th β should trigger training+ q.encode(makeVec(C2, 0.1, 256));+ expect(q.isPQTrained).toBe(true);+ expect(q.getCodebooks()).not.toBeNull();+ expect(q.getCodebooks()!).toHaveLength(NUM_SUB);+ // Training data freed after training+ expect(q.trainingVectors).toHaveLength(0);+ });++ // -------------------------------------------------------------------------+ // 7. Pre-training fallback: returns averaged sub-vectors before training+ // -------------------------------------------------------------------------+ it('pre-training fallback returns sub-vector means', () => {+ const index = createPQIndex();+ const q = getQuantizer(index);++ // A constant vector of 2.0 everywhere+ const constant = new Float32Array(DIM).fill(2.0);+ const result = q.encode(constant);++ // Before training, each element should be the mean of the sub-vector slice+ // For a constant 2.0 vector, every sub-vector mean is 2.0+ expect(result.length).toBe(NUM_SUB);+ for (let i = 0; i < result.length; i++) {+ expect(result[i]).toBeCloseTo(2.0, 5);+ }+ });+});diff --git a/v3/@claude-flow/cli/__tests__/ruvllm-integration.test.ts b/v3/@claude-flow/cli/__tests__/ruvllm-integration.test.tsnew file mode 100644index 0000000000..54f08a383a--- /dev/null+++ b/v3/@claude-flow/cli/__tests__/ruvllm-integration.test.ts@@ -0,0 +1,153 @@+/**+ * ADR-086: @ruvector/ruvllm native intelligence backend integration tests+ *+ * Validates that SonaCoordinator, ContrastiveTrainer, and TrainingPipeline+ * load via createRequire (CJS bridge) and function correctly.+ */+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';++// Mock createRequire to return a ruvllm-like module+const mockSonaCoordinator = {+ recordTrajectory: vi.fn(),+ extractPatterns: vi.fn().mockReturnValue([]),+ stats: vi.fn().mockReturnValue({ trajectoriesBuffered: 3, patternsLearned: 1 }),+};+const mockContrastiveTrainer = {+ train: vi.fn().mockReturnValue({ loss: 0.42, triplets: 10 }),+ getTripletCount: vi.fn().mockReturnValue(5),+ getAgentEmbeddings: vi.fn().mockReturnValue(new Map()),+};+const mockTrainingPipeline = {+ saveCheckpoint: vi.fn(),+ loadCheckpoint: vi.fn(),+ train: vi.fn(),+};+const mockLoraAdapter = vi.fn().mockImplementation(() => ({+ forward: vi.fn(),+ backward: vi.fn(),+}));++const mockRuvllm = {+ SonaCoordinator: vi.fn().mockImplementation(() => mockSonaCoordinator),+ ContrastiveTrainer: vi.fn().mockImplementation(() => mockContrastiveTrainer),+ TrainingPipeline: vi.fn().mockImplementation(() => mockTrainingPipeline),+ LoraAdapter: mockLoraAdapter,+ DEFAULT_SONA_CONFIG: { maxPatterns: 1000, adaptationRate: 0.01, minConfidence: 0.3 },+};++vi.mock('module', () => ({+ createRequire: vi.fn().mockReturnValue(+ vi.fn().mockImplementation((specifier: string) => {+ if (specifier === '@ruvector/ruvllm') return mockRuvllm;+ throw new Error(`Cannot find module '${specifier}'`);+ })+ ),+}));++describe('ADR-086: ruvllm native intelligence backend', () => {+ describe('SonaCoordinator via intelligence.ts', () => {+ it('loads SonaCoordinator during initialization', async () => {+ // Reset module-level state by re-importing+ const intel = await import('../src/memory/intelligence.js');+ expect(intel.initializeIntelligence).toBeDefined();+ expect(intel.getIntelligenceStats).toBeDefined();+ expect(intel.recordTrajectory).toBeDefined();+ });++ it('exposes _ruvllmBackend in stats', async () => {+ const intel = await import('../src/memory/intelligence.js');+ const stats = intel.getIntelligenceStats();+ // Stats should include ruvllm fields+ expect(stats).toHaveProperty('_ruvllmBackend');+ expect(stats).toHaveProperty('_ruvllmTrajectories');+ });+ });++ describe('ContrastiveTrainer via sona-optimizer.ts', () => {+ it('exports getSONAStats with _contrastiveTrainer field', async () => {+ const sona = await import('../src/memory/sona-optimizer.js');+ expect(sona.getSONAStats).toBeDefined();+ const stats = await sona.getSONAStats();+ expect(stats).toHaveProperty('_contrastiveTrainer');+ });++ it('exports SONAOptimizer class with trainAgentEmbeddings method', async () => {+ const sona = await import('../src/memory/sona-optimizer.js');+ expect(sona.SONAOptimizer).toBeDefined();+ const optimizer = await sona.getSONAOptimizer();+ expect(typeof optimizer.trainAgentEmbeddings).toBe('function');+ });+ });++ describe('TrainingPipeline via lora-adapter.ts', () => {+ it('exposes initBackend method', async () => {+ const lora = await import('../src/ruvector/lora-adapter.js');+ const adapter = new lora.LoRAAdapter({ inputDim: 64, outputDim: 64, rank: 4 });+ expect(typeof adapter.initBackend).toBe('function');+ });++ it('exposes _trainingBackend in stats', async () => {+ const lora = await import('../src/ruvector/lora-adapter.js');+ const adapter = new lora.LoRAAdapter({ inputDim: 64, outputDim: 64, rank: 4 });+ const stats = adapter.getStats();+ expect(stats).toHaveProperty('_trainingBackend');+ });++ it('supports saveCheckpoint and loadCheckpoint', async () => {+ const lora = await import('../src/ruvector/lora-adapter.js');+ const adapter = new lora.LoRAAdapter({ inputDim: 64, outputDim: 64, rank: 4 });+ expect(typeof adapter.saveCheckpoint).toBe('function');+ expect(typeof adapter.loadCheckpoint).toBe('function');+ });+ });++ describe('CJS import pattern (createRequire)', () => {+ it('uses createRequire instead of ESM dynamic import', async () => {+ // The source files should NOT contain `await import('@ruvector/ruvllm')`+ // They should use createRequire(import.meta.url)('@ruvector/ruvllm')+ const { readFileSync } = await import('fs');+ const { join } = await import('path');+ const srcDir = join(import.meta.dirname, '..', 'src');++ const files = [+ 'memory/intelligence.ts',+ 'memory/sona-optimizer.ts',+ 'ruvector/lora-adapter.ts',+ ];++ for (const file of files) {+ const content = readFileSync(join(srcDir, file), 'utf8');+ // Should NOT have bare ESM import of ruvllm+ expect(content).not.toMatch(/await import\(['"]@ruvector\/ruvllm['"]\)/);+ // Should have createRequire pattern+ expect(content).toContain('createRequire');+ expect(content).toContain("requireCjs('@ruvector/ruvllm')");+ }+ });+ });++ describe('graceful degradation', () => {+ it('intelligence falls back to null coordinator when ruvllm unavailable', async () => {+ // The loadRuvllmCoordinator function catches errors and returns null+ // Stats show 'unavailable' in that case+ const intel = await import('../src/memory/intelligence.js');+ const stats = intel.getIntelligenceStats();+ // Just verify the field exists β actual value depends on module loading order+ expect(['active', 'unavailable']).toContain(stats._ruvllmBackend);+ });++ it('sona-optimizer falls back when ContrastiveTrainer unavailable', async () => {+ const sona = await import('../src/memory/sona-optimizer.js');+ const stats = await sona.getSONAStats();+ // Either loaded object or 'unavailable' string+ expect(stats._contrastiveTrainer).toBeDefined();+ });++ it('lora-adapter falls back to js-fallback when pipeline unavailable', async () => {+ const lora = await import('../src/ruvector/lora-adapter.js');+ const adapter = new lora.LoRAAdapter({ inputDim: 64, outputDim: 64, rank: 4 });+ const stats = adapter.getStats();+ expect(['ruvllm', 'js-fallback']).toContain(stats._trainingBackend);+ });+ });+});diff --git a/v3/@claude-flow/cli/__tests__/ruvllm-tools.test.ts b/v3/@claude-flow/cli/__tests__/ruvllm-tools.test.tsindex 01de3fa833..b6102c7c37 100644--- a/v3/@claude-flow/cli/__tests__/ruvllm-tools.test.ts+++ b/v3/@claude-flow/cli/__tests__/ruvllm-tools.test.ts@@ -69,8 +69,9 @@ describe('ruvllm-wasm MCP tools', () => {const tool = findTool('ruvllm_status');const result = await tool.handler({}) as any;const data = JSON.parse(result.content[0].text);- expect(data.available).toBe(true);- expect(data.version).toBe('2.0.1');+ expect(data.wasm.available).toBe(true);+ expect(data.wasm.version).toBe('2.0.1');+ expect(data.native).toBeDefined();});});diff --git a/v3/@claude-flow/cli/__tests__/sona-embeddings-validation.test.ts b/v3/@claude-flow/cli/__tests__/sona-embeddings-validation.test.tsnew file mode 100644index 0000000000..4a3e5d01bd--- /dev/null+++ b/v3/@claude-flow/cli/__tests__/sona-embeddings-validation.test.ts@@ -0,0 +1,106 @@+/**+ * Deep validation: SONA optimizer, embeddings transparency, neural tools+ */+import { describe, it, expect, beforeEach } from 'vitest';+import { SONAOptimizer, resetSONAOptimizer } from '../src/memory/sona-optimizer.js';+import { generateEmbedding } from '../src/ruvector/vector-db.js';++// ---------- SONA Optimizer ----------+describe('SONA Optimizer', () => {+ let sona: SONAOptimizer;++ beforeEach(() => {+ resetSONAOptimizer();+ sona = new SONAOptimizer({ persistencePath: '/tmp/sona-test-' + Date.now() + '.json' });+ });++ it('1: getRoutingSuggestion() is async and returns a result with source field', async () => {+ const result = await sona.getRoutingSuggestion('implement a login page');+ expect(result).toBeDefined();+ expect(typeof result.source).toBe('string');+ });++ it('2: source field is one of the allowed values', async () => {+ const allowed = ['sona-native', 'sona-pattern', 'q-learning', 'sona-keyword', 'default'];+ const result = await sona.getRoutingSuggestion('write unit tests for the api');+ expect(allowed).toContain(result.source);+ });++ it('3: keyword routing maps "implement authentication" to coder or security-architect', async () => {+ const result = await sona.getRoutingSuggestion('implement authentication');+ // "implement" is a coder keyword, "authentication" is security-architect+ expect(['coder', 'security-architect']).toContain(result.agent);+ expect(result.source).toMatch(/sona-keyword|default/);+ });++ it('4: loadSonaEngine() gracefully handles missing @ruvector/sona', async () => {+ // With no @ruvector/sona installed, should still return a result via keyword/default+ const result = await sona.getRoutingSuggestion('design a database schema');+ expect(['sona-keyword', 'default', 'sona-pattern']).toContain(result.source);+ expect(result.agent).toBeDefined();+ });++ it('5: return type has agentType-equivalent, confidence, source, reasoning-equivalent fields', async () => {+ const result = await sona.getRoutingSuggestion('optimize performance of the cache layer');+ // RoutingSuggestion uses `agent` (not `agentType`) and `alternatives` (not `reasoning`)+ expect(typeof result.agent).toBe('string');+ expect(typeof result.confidence).toBe('number');+ expect(typeof result.source).toBe('string');+ expect(Array.isArray(result.alternatives)).toBe(true);+ expect(typeof result.usedQLearning).toBe('boolean');+ });+});++// ---------- Embeddings Transparency ----------+describe('Embeddings Transparency (vector-db)', () => {+ it('6: generateHashEmbedding via generateEmbedding returns Float32Array of length 384', () => {+ // generateEmbedding defaults to 768, but we request 384+ const emb = generateEmbedding('hello world', 384);+ expect(emb).toBeInstanceOf(Float32Array);+ expect(emb.length).toBe(384);+ });++ it('7: hash embedding is deterministic (same input -> same output)', () => {+ const a = generateEmbedding('deterministic test input', 384);+ const b = generateEmbedding('deterministic test input', 384);+ expect(Array.from(a)).toEqual(Array.from(b));+ });++ it('8: hash embedding has _warning property (non-enumerable) on fallback', () => {+ const emb = generateEmbedding('test transparency', 384);+ // _warning is defined as non-enumerable+ const descriptor = Object.getOwnPropertyDescriptor(emb, '_warning');+ expect(descriptor).toBeDefined();+ expect(descriptor!.enumerable).toBe(false);+ expect(typeof descriptor!.value).toBe('string');+ expect(descriptor!.value).toContain('hash-based');+ });+});++// ---------- Neural Tools ----------+describe('Neural Tools (neural-tools)', () => {+ it('9: generateEmbedding function exists in neural-tools and is callable', async () => {+ // neural-tools has a module-scoped generateEmbedding; we test it indirectly+ // by importing the neuralTools array and calling the neural_predict handler+ const { neuralTools } = await import('../src/mcp-tools/neural-tools.js');+ const predictTool = neuralTools.find(t => t.name === 'neural_predict');+ expect(predictTool).toBeDefined();+ // Call it β should succeed without real embeddings+ const result = await predictTool!.handler({ input: 'test embedding generation' });+ expect(result).toHaveProperty('embeddingDims', 384);+ });++ it('10: embeddingServiceName reflects active provider (real or hash-fallback)', async () => {+ const { neuralTools } = await import('../src/mcp-tools/neural-tools.js');+ const statusTool = neuralTools.find(t => t.name === 'neural_status');+ expect(statusTool).toBeDefined();+ const result = await statusTool!.handler({});+ const provider = (result as any).embeddingProvider as string;+ // Must be a non-empty string indicating which embedding backend is active+ expect(typeof provider).toBe('string');+ expect(provider.length).toBeGreaterThan(0);+ // Must match one of the known provider tiers or fallback+ const knownProviders = /agentic-flow|onnx|mock|hash|fallback|reasoningbank|none/i;+ expect(provider).toMatch(knownProviders);+ });+});diff --git a/v3/@claude-flow/cli/package.json b/v3/@claude-flow/cli/package.jsonindex 7dd471265a..23ab807f1c 100644--- a/v3/@claude-flow/cli/package.json+++ b/v3/@claude-flow/cli/package.json@@ -1,6 +1,6 @@{"name": "@claude-flow/cli",- "version": "3.5.72",+ "version": "3.5.73","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",diff --git a/v3/@claude-flow/cli/src/commands/neural.ts b/v3/@claude-flow/cli/src/commands/neural.tsindex ecc09d2d1b..1a0c1cd210 100644--- a/v3/@claude-flow/cli/src/commands/neural.ts+++ b/v3/@claude-flow/cli/src/commands/neural.ts@@ -302,6 +302,17 @@ const trainCommand: Command = {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@@ -495,6 +506,40 @@ const statusCommand: Command = {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 as any).triplets ?? 0} triplets, ${(stats._contrastiveTrainer as any).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' }; }+ })(),],});@@ -795,6 +840,12 @@ const optimizeCommand: Command = {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 sizeconst patternDir = path.join(process.cwd(), '.claude-flow', 'neural');let beforeSize = 0;diff --git a/v3/@claude-flow/cli/src/init/claudemd-generator.ts b/v3/@claude-flow/cli/src/init/claudemd-generator.tsindex b600e93c34..4315609c89 100644--- a/v3/@claude-flow/cli/src/init/claudemd-generator.ts+++ b/v3/@claude-flow/cli/src/init/claudemd-generator.ts@@ -59,9 +59,8 @@ function concurrencyRules(): string {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`;}@@ -70,9 +69,9 @@ function swarmOrchestration(): string {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)@@ -82,8 +81,7 @@ function swarmOrchestration(): string {| **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(): string {@@ -113,11 +111,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@@ -139,10 +137,10 @@ Task({prompt: "Review code quality...", subagent_type: "reviewer", run_in_backgrfunction executionRules(): string {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`;}@@ -431,7 +429,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 toolsdiff --git a/v3/@claude-flow/cli/src/mcp-tools/agent-tools.ts b/v3/@claude-flow/cli/src/mcp-tools/agent-tools.tsindex 01cb00642c..ed21da63b1 100644--- a/v3/@claude-flow/cli/src/mcp-tools/agent-tools.ts+++ b/v3/@claude-flow/cli/src/mcp-tools/agent-tools.ts@@ -240,6 +240,12 @@ export const agentTools: MCPTool[] = [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 applicableconst response: Record<string, unknown> = {success: true,diff --git a/v3/@claude-flow/cli/src/mcp-tools/agentdb-tools.ts b/v3/@claude-flow/cli/src/mcp-tools/agentdb-tools.tsindex f4dd29e600..cabe372232 100644--- a/v3/@claude-flow/cli/src/mcp-tools/agentdb-tools.ts+++ b/v3/@claude-flow/cli/src/mcp-tools/agentdb-tools.ts@@ -233,6 +233,23 @@ export const agentdbCausalEdge: MCPTool = {if (!sourceId) return { success: false, error: 'sourceId is required (non-empty string)' };if (!targetId) 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,diff --git a/v3/@claude-flow/cli/src/mcp-tools/hooks-tools.ts b/v3/@claude-flow/cli/src/mcp-tools/hooks-tools.tsindex d00b56fafd..bb5348380e 100644--- a/v3/@claude-flow/cli/src/mcp-tools/hooks-tools.ts+++ b/v3/@claude-flow/cli/src/mcp-tools/hooks-tools.ts@@ -343,6 +343,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 };}} catch (err) {@@ -367,9 +368,11 @@ 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 };@@ -2158,6 +2161,34 @@ export const hooksIntelligence: MCPTool = {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,@@ -2169,7 +2200,7 @@ export const hooksIntelligence: MCPTool = {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: [],@@ -2434,6 +2465,12 @@ export const hooksTrajectoryEnd: MCPTool = {}}+ // 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 trajectoriesif (success) {const ewc = await getEWCConsolidator();@@ -2804,12 +2841,36 @@ export const hooksIntelligenceStats: MCPTool = {};}+ // ruvllm native backend stats+ let ruvllmStats = { coordinator: 'unavailable' as string, trajectories: 0, contrastiveTrainer: 'unavailable' as string | object, trainingBackend: 'unavailable' as string, graphDatabase: { backend: 'unavailable', totalNodes: 0, totalEdges: 0 } as Record<string, unknown> };+ 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,diff --git a/v3/@claude-flow/cli/src/mcp-tools/neural-tools.ts b/v3/@claude-flow/cli/src/mcp-tools/neural-tools.tsindex 6ea207de70..996a9c656e 100644--- a/v3/@claude-flow/cli/src/mcp-tools/neural-tools.ts+++ b/v3/@claude-flow/cli/src/mcp-tools/neural-tools.ts@@ -165,7 +165,11 @@ async function generateEmbedding(text?: string, dims: number = 384): Promise<num}// Hash-based deterministic embedding (better than pure random for consistency)+ // NOTE: No semantic meaning β only useful for consistent deduplication, not similarity searchif (text) {+ if (embeddingServiceName === 'none') {+ embeddingServiceName = 'hash-fallback';+ }const hash = text.split('').reduce((acc, char, i) => {return acc + char.charCodeAt(0) * (i + 1);}, 0);@@ -278,6 +282,7 @@ export const neuralTools: MCPTool[] = [return {success: true,_realEmbedding: !!realEmbeddings,+ _embeddingSource: embeddingServiceName,embeddingProvider: embeddingServiceName,modelId,type: modelType,@@ -345,6 +350,7 @@ export const neuralTools: MCPTool[] = [return {success: true,_realEmbedding: !!realEmbeddings,+ _embeddingSource: embeddingServiceName,embeddingProvider: embeddingServiceName,_hasStoredPatterns: storedPatterns.length > 0,modelId: model?.id || 'default',@@ -428,6 +434,7 @@ export const neuralTools: MCPTool[] = [return {success: true,_realEmbedding: !!realEmbeddings,+ _embeddingSource: embeddingServiceName,embeddingProvider: embeddingServiceName,patternId,name: pattern.name,@@ -455,6 +462,7 @@ export const neuralTools: MCPTool[] = [return {_realSimilarity: true,_realEmbedding: !!realEmbeddings,+ _embeddingSource: embeddingServiceName,embeddingProvider: embeddingServiceName,query,results: results.map(r => ({diff --git a/v3/@claude-flow/cli/src/mcp-tools/ruvllm-tools.ts b/v3/@claude-flow/cli/src/mcp-tools/ruvllm-tools.tsindex 5f515d109c..77711747fc 100644--- a/v3/@claude-flow/cli/src/mcp-tools/ruvllm-tools.ts+++ b/v3/@claude-flow/cli/src/mcp-tools/ruvllm-tools.ts@@ -21,8 +21,33 @@ export const ruvllmWasmTools: MCPTool[] = [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: Record<string, unknown> = { 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: Record<string, unknown> = { 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 };}diff --git a/v3/@claude-flow/cli/src/memory/intelligence.ts b/v3/@claude-flow/cli/src/memory/intelligence.tsindex e0dc7ab879..dad0cd2f67 100644--- a/v3/@claude-flow/cli/src/memory/intelligence.ts+++ b/v3/@claude-flow/cli/src/memory/intelligence.ts@@ -710,6 +710,27 @@ class LocalReasoningBank {}}+// ============================================================================+// @ruvector/ruvllm SonaCoordinator Integration+// ============================================================================++let ruvllmCoordinator: any = null;+let ruvllmLoaded = false;++async function loadRuvllmCoordinator(): Promise<any> {+ 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// ============================================================================@@ -800,6 +821,9 @@ export async function initializeIntelligence(config?: Partial<SonaConfig>): Prom// Load persisted stats if availableloadPersistedStats();+ // Eagerly load ruvllm coordinator so stats reflect backend status+ await loadRuvllmCoordinator();+intelligenceInitialized = true;return {@@ -951,6 +975,26 @@ export async function recordTrajectory(}}+ // 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();@@ -1025,10 +1069,29 @@ export async function findSimilarPatterns(/*** Get intelligence system statistics*/-export function getIntelligenceStats(): IntelligenceStats {+export function getIntelligenceStats(): IntelligenceStats & {+ _ruvllmBackend: string;+ _ruvllmTrajectories: number;+ _contrastiveTrainer?: { triplets: number; agents: number } | string;+ _trainingBackend?: string;+} {const sonaStats = sonaCoordinator?.stats();const bankStats = reasoningBank?.stats();+ const ruvllmStats = ruvllmCoordinator?.stats?.() || null;++ // Fetch cross-module stats for unified reporting+ let contrastiveTrainer: { triplets: number; agents: number } | string = '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 as any).__claudeFlowSonaStats;+ if (sonaModule) {+ contrastiveTrainer = sonaModule._contrastiveTrainer || 'unavailable';+ }+ } catch { /* not available */ }+return {sonaEnabled: !!sonaCoordinator,reasoningBankSize: bankStats?.size ?? 0,@@ -1036,7 +1099,11 @@ export function getIntelligenceStats(): IntelligenceStats {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,};}@@ -1321,6 +1388,15 @@ export function getNeuralDataDir(): string {return getDataDir();}+/**+ * Trigger background learning on the @ruvector/ruvllm SonaCoordinator.+ * No-op if ruvllm is not installed.+ */+export async function runBackgroundLearning(): Promise<void> {+ const coord = await loadRuvllmCoordinator();+ if (coord) coord.runBackgroundLoop();+}+/*** Get persistence status*/diff --git a/v3/@claude-flow/cli/src/memory/sona-optimizer.ts b/v3/@claude-flow/cli/src/memory/sona-optimizer.tsindex 70a34b0434..c342d0f342 100644--- a/v3/@claude-flow/cli/src/memory/sona-optimizer.ts+++ b/v3/@claude-flow/cli/src/memory/sona-optimizer.ts@@ -70,7 +70,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; score: number }>;/** Matched keywords */@@ -95,6 +95,8 @@ 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';}/**@@ -128,6 +130,27 @@ const CONFIDENCE_DECREMENT = 0.15;const DECAY_RATE = 0.01; // Per dayconst MAX_PATTERNS = 1000;+// ============================================================================+// Contrastive Trainer (lazy-loaded from @ruvector/ruvllm)+// ============================================================================++let contrastiveTrainer: any = null;+let trainerLoaded = false;++async function loadContrastiveTrainer(): Promise<any> {+ 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*/@@ -210,10 +233,42 @@ export class SONAOptimizer {private qLearningRouter: any = null;private qLearningEnabled = false;+ /** Real @ruvector/sona engine β null if native not available, undefined if not yet tried */+ private sonaEngine: any | null | undefined = undefined;+constructor(options?: { persistencePath?: string }) {this.persistencePath = options?.persistencePath || DEFAULT_PERSISTENCE_PATH;}+ /**+ * Attempt to load the native @ruvector/sona engine (once).+ * Sets `sonaEngine` to the engine instance or null if unavailable.+ */+ private async loadSonaEngine(): Promise<void> {+ if (this.sonaEngine !== undefined) return; // already attempted+ try {+ const sona: any = await import('@ruvector/sona');+ const EngineCtor = sona.SonaEngine || sona.default?.SonaEngine;+ if (EngineCtor) {+ this.sonaEngine = new EngineCtor({ mode: 'real-time' });+ } else {+ this.sonaEngine = null;+ }+ } catch {+ this.sonaEngine = null; // native not available+ }+ }++ /**+ * Infer an agent type string from a SONA pattern result object.+ */+ private inferAgentFromPattern(pattern: Record<string, unknown>): string {+ if (typeof pattern.agent === 'string') return pattern.agent;+ if (typeof pattern.route === 'string') return pattern.route;+ if (typeof pattern.label === 'string') return pattern.label;+ return 'coder';+ }+/*** Initialize the optimizer and load persisted state*/@@ -232,6 +287,9 @@ export class SONAOptimizer {this.qLearningEnabled = false;}+ // Eagerly load ContrastiveTrainer so stats reflect backend status+ await loadContrastiveTrainer();+return {success: true,patternsLoaded: loaded ? this.patterns.size : 0,@@ -311,6 +369,16 @@ export class SONAOptimizer {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(() => { /* ignore trainer errors */ });+ }+// Persist to disk (debounced)this.saveToDisk();@@ -323,12 +391,44 @@ export class SONAOptimizer {}/**- * 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 {+ async getRoutingSuggestion(task: string): Promise<RoutingSuggestion> {+ // Priority 1: Try real @ruvector/sona native engine+ await this.loadSonaEngine();+ if (this.sonaEngine) {+ try {+ const patterns = this.sonaEngine.findPatterns(task, 3);+ if (patterns && patterns.length > 0) {+ const best = patterns[0];+ const agent = best.route || best.agent || this.inferAgentFromPattern(best);+ return {+ agent,+ confidence: best.quality || 0.8,+ usedQLearning: false,+ source: 'sona-native',+ alternatives: patterns.slice(1).map((p: any) => ({+ agent: p.route || p.agent || this.inferAgentFromPattern(p),+ score: p.quality || 0.5,+ })),+ matchedKeywords: best.keywords || [],+ };+ }+ } catch {+ // Native SONA failed on this query β fall through to keyword matching+ }+ }+const keywords = this.extractKeywords(task);- // Try SONA pattern matching first+ // Priority 2: Try SONA learned pattern matchingconst sonaResult = this.findBestPatternMatch(keywords);if (sonaResult && sonaResult.confidence >= 0.6) {return {@@ -341,7 +441,7 @@ export class SONAOptimizer {};}- // Try Q-learning router if available+ // Priority 3: Try Q-learning router if availableif (this.qLearningRouter && this.qLearningEnabled) {try {const decision = this.qLearningRouter.route(task, false);@@ -359,20 +459,20 @@ export class SONAOptimizer {}}- // Fallback to keyword-based heuristic+ // Priority 4: Keyword-based heuristicconst keywordMatch = this.matchKeywordsToAgent(keywords);if (keywordMatch) {return {agent: keywordMatch.agent,confidence: keywordMatch.confidence,usedQLearning: false,- source: 'keyword-match',+ source: 'sona-keyword',alternatives: this.getAlternatives(keywords, keywordMatch.agent),matchedKeywords: keywordMatch.matchedKeywords,};}- // Default fallback+ // Priority 5: Default fallbackreturn {agent: 'coder',confidence: 0.3,@@ -402,9 +502,27 @@ 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: number = 5): Promise<{ trained: boolean; loss?: number; triplets?: number }> {+ 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@@ -483,6 +601,32 @@ 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.+ */+ private keywordsToEmbedding(keywords: string[]): Float32Array {+ 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*/diff --git a/v3/@claude-flow/cli/src/ruvector/graph-backend.ts b/v3/@claude-flow/cli/src/ruvector/graph-backend.tsnew file mode 100644index 0000000000..d34ecfd158--- /dev/null+++ b/v3/@claude-flow/cli/src/ruvector/graph-backend.ts@@ -0,0 +1,271 @@+/**+ * @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: any = null;+let graphDb: any = 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(): Promise<any> {+ 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(): Promise<any> {+ 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: string): Float32Array {+ 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;+}++// ============================================================================+// Public API+// ============================================================================++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 async function isGraphBackendAvailable(): Promise<boolean> {+ await loadGraphNode();+ return graphBackendAvailable;+}++/**+ * Add a node to the graph (agent, task, pattern, etc.)+ */+export async function addNode(data: GraphNodeData): Promise<string | null> {+ 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: GraphEdgeData): Promise<string | null> {+ 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: string[],+ label: string,+ description?: string,+ properties?: Record<string, unknown>,+): Promise<string | null> {+ 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: string, hops: number = 2): Promise<string[]> {+ const db = await getGraphDb();+ if (!db) return [];+ try {+ return await db.kHopNeighbors(nodeId, hops);+ } catch {+ return [];+ }+}++/**+ * Get graph statistics+ */+export async function getGraphStats(): Promise<GraphStats> {+ 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: string,+ targetId: string,+ relation: string,+ weight?: number,+): Promise<{ success: boolean; edgeId?: string; backend: string }> {+ // 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: string,+ agentType: string,+ taskId: string,+ taskName: string,+): Promise<{ success: boolean }> {+ 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: string[],+ topology: string,+ taskDescription?: string,+): Promise<{ success: boolean; hyperedgeId?: string }> {+ 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 };+}diff --git a/v3/@claude-flow/cli/src/ruvector/lora-adapter.ts b/v3/@claude-flow/cli/src/ruvector/lora-adapter.tsindex c7dc203a22..e875dd7ab4 100644--- a/v3/@claude-flow/cli/src/ruvector/lora-adapter.ts+++ b/v3/@claude-flow/cli/src/ruvector/lora-adapter.ts@@ -109,6 +109,8 @@ export interface LoRAStats {avgAdaptationNorm: number;/** Last update timestamp */lastUpdate: number | null;+ /** Training backend in use ('ruvllm' | 'js-fallback') */+ _trainingBackend?: string;}// ============================================================================@@ -127,6 +129,34 @@ const DEFAULT_CONFIG: LoRAConfig = {autoSaveInterval: 50,};+// ============================================================================+// @ruvector/ruvllm TrainingPipeline (lazy-loaded)+// ============================================================================++let ruvllmPipeline: any = null;+let pipelineLoaded = false;++async function loadTrainingPipeline(adapter: LoRAAdapter): Promise<any> {+ 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 as any).LoraAdapter(config.inputDim, config.outputDim, config.rank);+ ruvllmPipeline = new (ruvllm as any).TrainingPipeline({+ adapter: nativeAdapter,+ learningRate: 0.001,+ batchSize: 8,+ });+ return ruvllmPipeline;+ } catch {+ return null;+ }+}+// ============================================================================// LoRA Adapter Class// ============================================================================@@ -148,6 +178,22 @@ export class LoRAAdapter {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(): Promise<void> {+ await loadTrainingPipeline(this);+ }++ /**+ * Get a readonly copy of the adapter configuration+ */+ getConfig(): Readonly<LoRAConfig> {+ return this.config;+ }+/*** Initialize weights with Kaiming/He initialization*/@@ -361,6 +407,9 @@ export class LoRAAdapter {? this.adaptationNormSum / this.totalAdaptations: 0,lastUpdate: this.lastUpdate,+ _trainingBackend: pipelineLoaded+ ? (ruvllmPipeline ? 'ruvllm' : 'js-fallback')+ : 'js-fallback',};}@@ -458,6 +507,52 @@ export class LoRAAdapter {}}+ /**+ * Save a training checkpoint via ruvllm TrainingPipeline.+ * Falls back to writing our own weight JSON if ruvllm is unavailable.+ */+ async saveCheckpoint(path: string): Promise<boolean> {+ const pipeline = await loadTrainingPipeline(this);+ if (pipeline) {+ try {+ pipeline.saveCheckpoint(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: string): Promise<boolean> {+ 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*/diff --git a/v3/@claude-flow/cli/src/ruvector/vector-db.ts b/v3/@claude-flow/cli/src/ruvector/vector-db.tsindex cf29e117a2..72960b7d13 100644--- a/v3/@claude-flow/cli/src/ruvector/vector-db.ts+++ b/v3/@claude-flow/cli/src/ruvector/vector-db.ts@@ -94,10 +94,23 @@ function cosineSimilarity(a: Float32Array, b: Float32Array): number {return denom === 0 ? 0 : dotProduct / denom;}+/**+ * Whether the hash-embedding one-time warning has been emitted+ */+let hashEmbeddingWarned = false;+/*** Generate a simple hash-based embedding (fallback when ruvector not available)+ * WARNING: Produces deterministic vectors with NO semantic meaning.*/function generateHashEmbedding(text: string, dimensions: number = 768): Float32Array {+ if (!hashEmbeddingWarned) {+ hashEmbeddingWarned = true;+ console.warn(+ '[vector-db] Using hash-based pseudo-embeddings (no semantic similarity). ' ++ 'Install ruvector or @claude-flow/embeddings for real ML embeddings.'+ );+ }const embedding = new Float32Array(dimensions);const normalized = text.toLowerCase().trim();@@ -246,6 +259,10 @@ export async function createVectorDB(dimensions: number = 768): Promise<VectorDB/*** Generate an embedding for text* Uses ruvector if available, falls back to hash-based embedding+ *+ * @returns The embedding vector. When using hash fallback, the returned+ * Float32Array will have a `_warning` property (non-enumerable)+ * indicating it lacks semantic meaning.*/export function generateEmbedding(text: string, dimensions: number = 768): Float32Array {if (ruvectorModule && typeof ruvectorModule.generateEmbedding === 'function') {@@ -256,7 +273,14 @@ export function generateEmbedding(text: string, dimensions: number = 768): Float}}- return generateHashEmbedding(text, dimensions);+ const embedding = generateHashEmbedding(text, dimensions);+ // Tag the result so consumers can detect it came from hash fallback+ Object.defineProperty(embedding, '_warning', {+ value: 'hash-based pseudo-embedding β no semantic similarity',+ enumerable: false,+ configurable: true,+ });+ return embedding;}/**diff --git a/v3/@claude-flow/codex/src/generators/agents-md.ts b/v3/@claude-flow/codex/src/generators/agents-md.tsindex 4bb570a188..f65d1c4593 100644--- a/v3/@claude-flow/codex/src/generators/agents-md.ts+++ b/v3/@claude-flow/codex/src/generators/agents-md.ts@@ -192,6 +192,24 @@ ${skillsTable}| \`tester\` | Test creation | Quality assurance || \`reviewer\` | Code review | Security and quality |+## Execution Model++- **claude-flow** = LEDGER (coordinates: memory, routing, swarm state)+- **Codex** = EXECUTOR (writes code, runs tests, creates files)++**Critical rule:** DON'T STOP after calling claude-flow commands. Coordination commands return instantly β continue immediately with the next implementation step.++## MCP Integration++Use MCP tools for coordination, then keep coding:++| Tool | Purpose | Example |+|------|---------|---------|+| \`swarm_init\` | Start coordination | \`swarm_init({topology: "hierarchical"})\` |+| \`memory_store\` | Save patterns | \`memory_store({key: "auth", value: "JWT"})\` |+| \`memory_search\` | Find patterns | \`memory_search({query: "auth patterns"})\` |+| \`task_orchestrate\` | Assign work | \`task_orchestrate({task: "implement"})\` |+## Code Standards### File Organization@@ -250,6 +268,15 @@ npx @claude-flow/cli memory search \\--namespace patterns\`\`\`+## Quick Commands++\`\`\`bash+npx @claude-flow/cli memory search --query "relevant patterns"+npx @claude-flow/cli hooks route --task "current task description"+npx @claude-flow/cli swarm init --topology hierarchical+npx @claude-flow/cli hooks pre-task --description "task summary"+\`\`\`+## Links- Documentation: https://github.com/ruvnet/claude-flowdiff --git a/v3/@claude-flow/memory/src/hnsw-index.ts b/v3/@claude-flow/memory/src/hnsw-index.tsindex 5db703524a..35accf0e21 100644--- a/v3/@claude-flow/memory/src/hnsw-index.ts+++ b/v3/@claude-flow/memory/src/hnsw-index.ts@@ -906,6 +906,18 @@ class Quantizer {private config: QuantizationConfig;private dimensions: number;+ /** Trained PQ codebooks: codebooks[subquantizer][centroid][dimension] */+ private codebooks: number[][][] | null = null;++ /** Accumulated vectors for lazy codebook training */+ private trainingVectors: number[][] = [];++ /** Minimum number of vectors needed before training codebooks */+ private readonly pqTrainingThreshold: number = 256;++ /** Whether PQ codebooks have been trained */+ private pqTrained: boolean = false;+constructor(config: QuantizationConfig, dimensions: number) {this.config = config;this.dimensions = dimensions;@@ -987,26 +999,210 @@ class Quantizer {}private productQuantize(vector: Float32Array): Float32Array {- // Simplified product quantization- // In production, would use trained codebooks- const subquantizers = this.config.subquantizers || 8;- const subvectorSize = Math.ceil(vector.length / subquantizers);+ const numSubquantizers = this.config.subquantizers || 8;+ const numCentroids = this.config.codebookSize || 256;++ // Accumulate training vectors until we have enough to train codebooks+ if (!this.pqTrained) {+ this.trainingVectors.push(Array.from(vector));++ if (this.trainingVectors.length >= this.pqTrainingThreshold) {+ this.codebooks = this.trainProductQuantizer(+ this.trainingVectors,+ numSubquantizers,+ numCentroids,+ );+ this.pqTrained = true;+ this.trainingVectors = []; // Free training data+ } else {+ // Not enough data to train yet; fall back to sub-vector means+ const subvectorSize = Math.ceil(vector.length / numSubquantizers);+ const quantized = new Float32Array(numSubquantizers);+ for (let i = 0; i < numSubquantizers; i++) {+ let sum = 0;+ const start = i * subvectorSize;+ const end = Math.min(start + subvectorSize, vector.length);+ for (let j = start; j < end; j++) {+ sum += vector[j];+ }+ quantized[i] = sum / (end - start);+ }+ return quantized;+ }+ }- const quantized = new Float32Array(subquantizers);+ // Encode: assign each sub-vector to its nearest centroid+ const subvectorSize = Math.ceil(vector.length / numSubquantizers);+ const encoded = new Float32Array(numSubquantizers);- for (let i = 0; i < subquantizers; i++) {- let sum = 0;- const start = i * subvectorSize;+ for (let m = 0; m < numSubquantizers; m++) {+ const start = m * subvectorSize;const end = Math.min(start + subvectorSize, vector.length);+ const codebook = this.codebooks![m];++ let bestIdx = 0;+ let bestDist = Infinity;+ for (let c = 0; c < codebook.length; c++) {+ let dist = 0;+ for (let d = 0; d < end - start; d++) {+ const diff = vector[start + d] - codebook[c][d];+ dist += diff * diff;+ }+ if (dist < bestDist) {+ bestDist = dist;+ bestIdx = c;+ }+ }+ // Store centroid index (fits in Uint8 when numCentroids <= 256)+ encoded[m] = bestIdx;+ }++ return encoded;+ }++ /**+ * Train Product Quantizer codebooks using k-means on sub-vector slices.+ *+ * Splits each training vector into `numSubquantizers` sub-vectors, then+ * learns `numCentroids` centroids per sub-quantizer position.+ *+ * @returns codebooks[m][c] = centroid vector for sub-quantizer m, centroid c+ */+ trainProductQuantizer(+ trainingVectors: number[][],+ numSubquantizers: number,+ numCentroids: number,+ ): number[][][] {+ const dim = trainingVectors[0].length;+ const subvectorSize = Math.ceil(dim / numSubquantizers);+ const codebooks: number[][][] = [];++ for (let m = 0; m < numSubquantizers; m++) {+ const start = m * subvectorSize;+ const end = Math.min(start + subvectorSize, dim);+ const subLen = end - start;++ // Extract sub-vectors for this position from all training vectors+ const subVectors: number[][] = trainingVectors.map((vec) => {+ const sub = new Array(subLen);+ for (let d = 0; d < subLen; d++) {+ sub[d] = vec[start + d];+ }+ return sub;+ });++ // Clamp centroids to available data points+ const effectiveK = Math.min(numCentroids, subVectors.length);+ const centroids = this.kMeans(subVectors, effectiveK, 20);+ codebooks.push(centroids);+ }++ return codebooks;+ }++ /**+ * Compute approximate squared Euclidean distance between two PQ-encoded+ * vectors using their centroid indices and the shared codebooks.+ *+ * @param encoded1 - Centroid indices for vector 1 (length = numSubquantizers)+ * @param encoded2 - Centroid indices for vector 2 (length = numSubquantizers)+ * @param codebooks - Trained codebooks from trainProductQuantizer()+ * @returns Approximate squared Euclidean distance+ */+ productQuantizeDistance(+ encoded1: Uint8Array,+ encoded2: Uint8Array,+ codebooks?: number[][][],+ ): number {+ const cb = codebooks || this.codebooks;+ if (!cb) {+ throw new Error('Product quantizer codebooks not trained yet');+ }++ let totalDist = 0;+ for (let m = 0; m < encoded1.length; m++) {+ const c1 = cb[m][encoded1[m]];+ const c2 = cb[m][encoded2[m]];+ for (let d = 0; d < c1.length; d++) {+ const diff = c1[d] - c2[d];+ totalDist += diff * diff;+ }+ }+ return totalDist;+ }++ /**+ * K-means clustering.+ *+ * Partitions `data` into `k` clusters and returns the centroid vectors.+ * Initialisation picks the first k data points (deterministic, avoids+ * the overhead of k-means++ for the small sub-vector slices used in PQ).+ */+ private kMeans(data: number[][], k: number, maxIter: number = 20): number[][] {+ const dim = data[0].length;++ // Initialise centroids from the first k data points+ const centroids: number[][] = data.slice(0, k).map((v) => [...v]);++ for (let iter = 0; iter < maxIter; iter++) {+ // --- Assign each point to nearest centroid ---+ const assignments = new Int32Array(data.length);+ for (let i = 0; i < data.length; i++) {+ let bestDist = Infinity;+ let bestIdx = 0;+ for (let j = 0; j < k; j++) {+ let dist = 0;+ for (let d = 0; d < dim; d++) {+ const diff = data[i][d] - centroids[j][d];+ dist += diff * diff;+ }+ if (dist < bestDist) {+ bestDist = dist;+ bestIdx = j;+ }+ }+ assignments[i] = bestIdx;+ }- for (let j = start; j < end; j++) {- sum += vector[j];+ // --- Update centroids ---+ const sums = Array.from({ length: k }, () => new Float64Array(dim));+ const counts = new Int32Array(k);+ for (let i = 0; i < data.length; i++) {+ const c = assignments[i];+ counts[c]++;+ for (let d = 0; d < dim; d++) {+ sums[c][d] += data[i][d];+ }+ }++ let converged = true;+ for (let j = 0; j < k; j++) {+ if (counts[j] === 0) continue; // Dead centroid, leave unchanged+ for (let d = 0; d < dim; d++) {+ const newVal = sums[j][d] / counts[j];+ if (Math.abs(newVal - centroids[j][d]) > 1e-6) converged = false;+ centroids[j][d] = newVal;+ }}- quantized[i] = sum / (end - start);+ if (converged) break;}- return quantized;+ return centroids;+ }++ /**+ * Whether the product quantizer codebooks are trained and ready for encoding.+ */+ get isPQTrained(): boolean {+ return this.pqTrained;+ }++ /**+ * Access trained codebooks (null if not yet trained).+ */+ getCodebooks(): number[][][] | null {+ return this.codebooks;}}diff --git a/v3/docs/adr/ADR-086-ruvllm-native-intelligence-backend.md b/v3/docs/adr/ADR-086-ruvllm-native-intelligence-backend.mdnew file mode 100644index 0000000000..99211bc34e--- /dev/null+++ b/v3/docs/adr/ADR-086-ruvllm-native-intelligence-backend.md@@ -0,0 +1,102 @@+# ADR-086: Wire @ruvector/ruvllm as Intelligence Coordinator++## Status: Implemented++## Date: 2026-04-07++## Context++The claude-flow intelligence pipeline (ReasoningBank, EWC++, LoRA, SONA, cosine similarity) is implemented in pure JavaScript using Float32Array operations. `@ruvector/[email protected]` is installed and provides structured ML components.++### API Testing Results (2026-04-07)++| Component | ruvllm Status | Keep JS? | Rationale |+|-----------|--------------|----------|-----------|+| `cosineSimilarity` | Works but same speed as JS (38ms vs 36ms / 100k) | **Yes** | No perf gain |+| `ReasoningBank.store/getByType` | Works | Partial | Use for type-based storage, keep JS HNSW for search |+| `ReasoningBank.findSimilar` | **Broken** (returns 0 always) | **Yes** | ruvllm bug |+| `EwcManager.computePenalty` | **Returns NaN** | **Yes** | ruvllm bug |+| `LoraAdapter.forward` | Works but same speed, different output dims | **Yes** | API mismatch |+| `SonaCoordinator` | Works: trajectory recording + background loop | **Use** | Real learning pipeline |+| `ContrastiveTrainer` | Works: triplet training, epoch tracking | **Use** | Agent embedding learning |+| `TrainingPipeline` | Works: checkpoint save/load, LoRA training | **Use** | Model training infrastructure |+| `SessionManager` | Works: session create/export/import | **Use** | Session coordination |++### What ruvllm IS++A well-structured JS library with SIMD support flag. NOT native Rust/NAPI for most operations. Value is in the **coordination framework**, not raw speed.++### ESM/CJS Import Resolution++`@ruvector/ruvllm` exports CJS only (`dist/cjs/index.js`). ESM `await import()` fails due to broken ESM export path. Resolution: use `createRequire(import.meta.url)` pattern (same as `diskann-backend.ts`, `ruvector-training.ts`).++## Decision++Selectively integrate `@ruvector/ruvllm` as the intelligence **coordinator**, not a wholesale replacement:++### USE ruvllm for (coordination & learning):+1. **`SonaCoordinator`** β Trajectory-based learning pipeline in `intelligence.ts`+2. **`ContrastiveTrainer`** β Agent embedding improvement in `sona-optimizer.ts`+3. **`TrainingPipeline`** β LoRA training with checkpoints in `lora-adapter.ts`+4. **`ReasoningBank`** (store/getByType) β Type-based pattern storage alongside JS HNSW++### KEEP pure JS for (proven, working):+1. **Cosine similarity** β Same speed, proven correct+2. **EWC++** β ruvllm returns NaN, our JS version works+3. **LoRA forward/backward** β API dimensions match our callers+4. **MoE Router** β No ruvllm equivalent+5. **HNSW search** β ruvllm `findSimilar` broken, our HNSW works++### Files modified++#### Core integration (CJS import via `createRequire`):+1. **`cli/src/memory/intelligence.ts`** β `loadRuvllmCoordinator()` lazily loads `SonaCoordinator`, eagerly loaded during `initializeIntelligence()`. Trajectories forwarded via `recordTrajectory()`. Background learning via `runBackgroundLearning()`. Stats expose `_ruvllmBackend` and `_ruvllmTrajectories`.+2. **`cli/src/memory/sona-optimizer.ts`** β `loadContrastiveTrainer()` lazily loads `ContrastiveTrainer`, eagerly loaded during `SONAOptimizer.initialize()`. Exposes `trainAgentEmbeddings()` and `_contrastiveTrainer` in stats.+3. **`cli/src/ruvector/lora-adapter.ts`** β `loadTrainingPipeline()` lazily loads `TrainingPipeline`. `initBackend()` for eager loading. `saveCheckpoint()`/`loadCheckpoint()` with ruvllm primary + JSON fallback. Stats expose `_trainingBackend`.++#### CLI command wiring:+4. **`cli/src/commands/neural.ts` (status)** β Three new rows in status table: ruvllm Coordinator, Contrastive Trainer, Training Pipeline.+5. **`cli/src/commands/neural.ts` (train)** β Auto-saves LoRA checkpoint after training completes via `adapter.saveCheckpoint()`.+6. **`cli/src/commands/neural.ts` (optimize)** β Triggers `runBackgroundLearning()` during optimization pass.++#### MCP tool wiring:+7. **`cli/src/mcp-tools/hooks-tools.ts` (intelligence)** β Three new components in `hooks_intelligence` response: `ruvllmCoordinator`, `contrastiveTrainer`, `trainingPipeline`. Added to `implementationStatus.working`.+8. **`cli/src/mcp-tools/hooks-tools.ts` (intelligence stats)** β New `ruvllm` stats object with coordinator/contrastiveTrainer/trainingBackend status.+9. **`cli/src/mcp-tools/hooks-tools.ts` (trajectory-end)** β Calls `runBackgroundLearning()` after trajectory end for automatic learning.+10. **`cli/src/mcp-tools/ruvllm-tools.ts` (ruvllm_status)** β Returns both WASM and native CJS backend status: `{ wasm: {...}, native: {...} }`.++### Non-goals++- Not replacing cosine/EWC/LoRA forward (JS is equal or better)+- Not replacing graph layer (graph-node, gnn) β separate ADR+- Not modifying MCP tool interfaces (backward compatible)++## Consequences++### Positive+- Real trajectory-based SONA learning (not keyword heuristic)+- Contrastive training improves agent routing over time+- Checkpoint infrastructure for LoRA persistence across sessions+- Transparent `_backend` reporting for all components via CLI and MCP+- Background learning triggers automatically on trajectory-end+- All 3 backends report status in `neural status`, `hooks intelligence`, and `ruvllm_status`++### Negative+- Two code paths for pattern storage (ruvllm + JS)+- ruvllm API quirks require adapter wrappers+- Cross-module stats require async fetches in MCP tools++### Risks+- ruvllm `findSimilar` bug means we can't use it for search β mitigated by keeping JS HNSW+- ruvllm EWC `NaN` bug means we can't use it for consolidation β mitigated by keeping JS EWC+++- CJS-only package requires `createRequire` bridge β standard pattern in codebase++### Test Coverage+- `__tests__/ruvllm-integration.test.ts` β 11 tests covering all 3 backends, CJS import pattern, and graceful degradation+- `__tests__/ruvllm-tools.test.ts` β Updated status test for `{ wasm, native, graph }` response shape+- `__tests__/graph-backend.test.ts` β 9 tests for graph-node backend (ADR-087)+- Full suite: 32 files, 1762 tests passing++### Related ADRs+- **ADR-087** β `@ruvector/graph-node` native graph database backend (companion integration)+- Other `@ruvector` packages evaluated but not integrated: `@ruvector/gnn` (NAPI broken), `@ruvector/rvf` (backend missing)diff --git a/v3/docs/adr/ADR-087-graph-node-native-backend.md b/v3/docs/adr/ADR-087-graph-node-native-backend.mdnew file mode 100644index 0000000000..f9d990ce51--- /dev/null+++ b/v3/docs/adr/ADR-087-graph-node-native-backend.md@@ -0,0 +1,85 @@+# ADR-087: Wire @ruvector/graph-node as Native Graph Backend++## Status: Implemented++## Date: 2026-04-07++## Context++The codebase has `@ruvector/[email protected]` installed (native Rust bindings, 10x faster than WASM) but 0 references in source code. Meanwhile, causal edges and agent relationships are stored only in the AgentDB bridge with no graph-native operations like k-hop neighbor queries or hyperedge support.++### Available @ruvector packages evaluated++| Package | Status | Result |+|---|---|---|+| `@ruvector/graph-node` | **Works** | createNode, createEdge, createHyperedge, kHopNeighbors, stats β all functional |+| `@ruvector/gnn` | **Broken** | All NAPI functions fail with type conversion errors |+| `@ruvector/rvf` | **Broken** | Backend resolution fails, no native bindings found |++### graph-node API requirements (discovered via testing)++- `createNode({ id, type, embedding })` β embedding required (Float32Array)+- `createEdge({ from, to, label, description, embedding, properties })` β all fields required+- `createHyperedge({ nodes[], label, description, embedding, properties })` β all fields required+- `kHopNeighbors(nodeId, k)` β returns string[] of neighbor node IDs+- `stats()` β returns `{ totalNodes, totalEdges, avgDegree }`+- `GraphDatabase(path?)` β optional path for persistence+- All methods are async (return Promises)++## Decision++Wire `@ruvector/graph-node` as the native graph backend for agent relationships, causal edges, task dependencies, and swarm topology.++### New module: `src/ruvector/graph-backend.ts`++Provides a clean wrapper over the raw graph-node API:+- `isGraphBackendAvailable()` β check if native backend loaded+- `addNode(data)` β add agent/task/pattern node+- `addEdge(data)` β add relationship edge+- `addHyperedge(nodeIds, label)` β create multi-node relationship+- `getNeighbors(nodeId, hops)` β k-hop neighbor query+- `getGraphStats()` β node/edge/degree statistics+- `recordCausalEdge(src, tgt, relation)` β causal edge recording+- `recordCollaboration(agentId, agentType, taskId)` β agent-task assignment+- `recordSwarmTeam(agentIds, topology)` β swarm team hyperedge++Auto-generates minimal embeddings (8-dim hash) for graph structure operations.++### Files modified++1. **`src/ruvector/graph-backend.ts`** (new) β Native graph database wrapper+2. **`src/mcp-tools/agentdb-tools.ts`** β `agentdb_causal-edge` tries graph-node first, falls back to bridge+3. **`src/mcp-tools/agent-tools.ts`** β `agent_spawn` records agent node in graph+4. **`src/mcp-tools/hooks-tools.ts`** β `hooks_intelligence` adds `graphDatabase` component status+5. **`src/mcp-tools/hooks-tools.ts`** β `hooks_intelligence_stats` adds graph stats to ruvllm section+6. **`src/mcp-tools/hooks-tools.ts`** β `implementationStatus.working` includes `graph-database`+7. **`src/mcp-tools/ruvllm-tools.ts`** β `ruvllm_status` includes graph backend status+8. **`src/commands/neural.ts`** β `neural status` shows Graph Database row in status table++### Non-goals+- Not replacing AgentDB bridge (graph-node supplements it)+- Not integrating @ruvector/gnn (NAPI broken) or @ruvector/rvf (backend missing)+- Not adding Cypher query interface (graph-node querySync untested)++## Consequences++### Positive+- Native Rust graph operations (10x faster than WASM)+- k-hop neighbor queries for agent relationship discovery+- Hyperedge support for swarm team representation+- Causal edges stored in both graph-node and AgentDB for redundancy+- Agent spawn automatically builds relationship graph+- Graph stats visible in `neural status`, `hooks_intelligence`, `ruvllm_status`++### Negative+- Minimal 8-dim hash embeddings are not semantic (sufficient for graph structure)+- Persistence path (`/tmp/rv-graph-persist.db`) reports null (graph-node quirk), but data persists++### Risks+- graph-node requires `embedding` on all operations β mitigated by auto-generated mini-embeddings+- graph-node persistence path returns null β mitigated by in-memory fallback+- CJS-only package β mitigated by `createRequire` bridge pattern++### Test Coverage+- `__tests__/graph-backend.test.ts` β 9 tests covering exports, graceful degradation, CJS pattern+- Full suite: 32 files, 1762 tests passingdiff --git a/v3/package-lock.json b/v3/package-lock.jsonindex 493e8cf855..ac870be607 100644--- a/v3/package-lock.json+++ b/v3/package-lock.json@@ -1789,7 +1789,7 @@}},"@claude-flow/cli": {- "version": "3.5.72",+ "version": "3.5.73","hasInstallScript": true,"license": "MIT","dependencies": {diff --git a/v3/plugins/agentic-qe/package.json b/v3/plugins/agentic-qe/package.jsonindex ae1ad9ccb7..965db6d3e0 100644--- a/v3/plugins/agentic-qe/package.json+++ b/v3/plugins/agentic-qe/package.json@@ -54,10 +54,10 @@"zod": "^3.23.0"},"peerDependencies": {- "@claude-flow/plugins": ">=3.0.0",- "@claude-flow/memory": ">=3.0.0",- "@claude-flow/security": ">=3.0.0",- "@claude-flow/embeddings": ">=3.0.0"+ "@claude-flow/plugins": ">=3.0.0-0",+ "@claude-flow/memory": ">=3.0.0-0",+ "@claude-flow/security": ">=3.0.0-0",+ "@claude-flow/embeddings": ">=3.0.0-0"},"peerDependenciesMeta": {"@claude-flow/plugins": {diff --git a/v3/plugins/code-intelligence/package.json b/v3/plugins/code-intelligence/package.jsonindex d799bf934c..c071345772 100644--- a/v3/plugins/code-intelligence/package.json+++ b/v3/plugins/code-intelligence/package.json@@ -61,7 +61,6 @@"directory": "v3/plugins/code-intelligence"},"dependencies": {- "@claude-flow/ruvector-upstream": "^0.1.0","zod": "^3.23.0"},"devDependencies": {diff --git a/v3/plugins/cognitive-kernel/package.json b/v3/plugins/cognitive-kernel/package.jsonindex cc7576b619..9fe5cebc16 100644--- a/v3/plugins/cognitive-kernel/package.json+++ b/v3/plugins/cognitive-kernel/package.json@@ -65,14 +65,6 @@"typescript": "^5.3.0","vitest": "^4.0.16"},- "peerDependencies": {- "@claude-flow/ruvector-upstream": ">=3.0.0-alpha.1"- },- "peerDependenciesMeta": {- "@claude-flow/ruvector-upstream": {- "optional": true- }- },"engines": {"node": ">=18.0.0"},diff --git a/v3/plugins/financial-risk/package.json b/v3/plugins/financial-risk/package.jsonindex 8c8db25c35..e93bbd13ca 100644--- a/v3/plugins/financial-risk/package.json+++ b/v3/plugins/financial-risk/package.json@@ -79,14 +79,6 @@"engines": {"node": ">=20.0.0"},- "peerDependencies": {- "@claude-flow/ruvector-upstream": ">=3.0.0-alpha.1"- },- "peerDependenciesMeta": {- "@claude-flow/ruvector-upstream": {- "optional": true- }- },"dependencies": {"zod": "^3.22.0"},diff --git a/v3/plugins/healthcare-clinical/package.json b/v3/plugins/healthcare-clinical/package.jsonindex 532c8fbf9c..1f36bec8e4 100644--- a/v3/plugins/healthcare-clinical/package.json+++ b/v3/plugins/healthcare-clinical/package.json@@ -78,14 +78,6 @@"engines": {"node": ">=20.0.0"},- "peerDependencies": {- "@claude-flow/ruvector-upstream": ">=3.0.0-alpha.1"- },- "peerDependenciesMeta": {- "@claude-flow/ruvector-upstream": {- "optional": true- }- },"dependencies": {"zod": "^3.22.0"},diff --git a/v3/plugins/hyperbolic-reasoning/package.json b/v3/plugins/hyperbolic-reasoning/package.jsonindex fbf11a6614..7e2bdd8a2f 100644--- a/v3/plugins/hyperbolic-reasoning/package.json+++ b/v3/plugins/hyperbolic-reasoning/package.json@@ -76,14 +76,6 @@"engines": {"node": ">=20.0.0"},- "peerDependencies": {- "@claude-flow/ruvector-upstream": ">=3.0.0"- },- "peerDependenciesMeta": {- "@claude-flow/ruvector-upstream": {- "optional": true- }- },"dependencies": {"zod": "^3.22.0"},diff --git a/v3/plugins/legal-contracts/package.json b/v3/plugins/legal-contracts/package.jsonindex d761fd8194..6f8303fcfd 100644--- a/v3/plugins/legal-contracts/package.json+++ b/v3/plugins/legal-contracts/package.json@@ -62,7 +62,6 @@"directory": "v3/plugins/legal-contracts"},"dependencies": {- "@claude-flow/ruvector-upstream": "^0.1.0","zod": "^3.23.0"},"devDependencies": {diff --git a/v3/plugins/neural-coordination/package.json b/v3/plugins/neural-coordination/package.jsonindex faf92419aa..f67060c091 100644--- a/v3/plugins/neural-coordination/package.json+++ b/v3/plugins/neural-coordination/package.json@@ -66,14 +66,6 @@"typescript": "^5.3.0","vitest": "^4.0.16"},- "peerDependencies": {- "@claude-flow/ruvector-upstream": ">=3.0.0-alpha.1"- },- "peerDependenciesMeta": {- "@claude-flow/ruvector-upstream": {- "optional": true- }- },"engines": {"node": ">=18.0.0"},diff --git a/v3/plugins/perf-optimizer/package.json b/v3/plugins/perf-optimizer/package.jsonindex 40d3e85f37..de7d6bba58 100644--- a/v3/plugins/perf-optimizer/package.json+++ b/v3/plugins/perf-optimizer/package.json@@ -58,14 +58,6 @@"dependencies": {"zod": "^3.22.4"},- "peerDependencies": {- "@claude-flow/ruvector-upstream": ">=3.0.0-alpha.1"- },- "peerDependenciesMeta": {- "@claude-flow/ruvector-upstream": {- "optional": true- }- },"devDependencies": {"@types/node": "^20.10.0","rimraf": "^5.0.5",diff --git a/v3/plugins/prime-radiant/package.json b/v3/plugins/prime-radiant/package.jsonindex bb6d81550d..d3ec8c5baf 100644--- a/v3/plugins/prime-radiant/package.json+++ b/v3/plugins/prime-radiant/package.json@@ -54,9 +54,9 @@"node": ">=20.0.0"},"peerDependencies": {- "@claude-flow/memory": ">=3.0.0",- "@claude-flow/security": ">=3.0.0",- "@claude-flow/coordination": ">=3.0.0"+ "@claude-flow/memory": ">=3.0.0-0",+ "@claude-flow/security": ">=3.0.0-0",+ "@claude-flow/coordination": ">=3.0.0-0"},"peerDependenciesMeta": {"@claude-flow/memory": {diff --git a/v3/plugins/quantum-optimizer/package.json b/v3/plugins/quantum-optimizer/package.jsonindex 6ee6902a3e..dc7661a92f 100644--- a/v3/plugins/quantum-optimizer/package.json+++ b/v3/plugins/quantum-optimizer/package.json@@ -76,14 +76,6 @@"engines": {"node": ">=20.0.0"},- "peerDependencies": {- "@claude-flow/ruvector-upstream": ">=3.0.0"- },- "peerDependenciesMeta": {- "@claude-flow/ruvector-upstream": {- "optional": true- }- },"dependencies": {"zod": "^3.22.0"},diff --git a/v3/plugins/test-intelligence/package.json b/v3/plugins/test-intelligence/package.jsonindex f45e852428..3831688420 100644--- a/v3/plugins/test-intelligence/package.json+++ b/v3/plugins/test-intelligence/package.json@@ -58,14 +58,6 @@"dependencies": {"zod": "^3.22.4"},- "peerDependencies": {- "@claude-flow/ruvector-upstream": ">=3.0.0-alpha.1"- },- "peerDependenciesMeta": {- "@claude-flow/ruvector-upstream": {- "optional": true- }- },"devDependencies": {"@types/node": "^20.10.0","rimraf": "^5.0.5",