Skip to content

armgit / ruflo

Public Imported from GitHub
0

🌊 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

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.md
index 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 reachable
ping host1
diff --git a/.agents/skills/github-multi-repo/SKILL.md b/.agents/skills/github-multi-repo/SKILL.md
index 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 initialization
npx 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 synchronization
npx 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 dependencies
const 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 repositories
Bash(`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; do
gh repo clone org/$repo /tmp/$repo -- --depth=1
cd /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 state
mcp__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 status
mcp__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 packages
mcp__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 practices
Bash(`gh search repos "language:javascript template architecture" \
@@ -268,7 +268,7 @@ mcp__claude-flow__swarm_init({
// Store analysis results
mcp__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 Tests
on: [push, pull_request]
jobs:
test:
runs-on: ubuntu-latest
steps:
- - uses: actions$checkout@v3
- - uses: actions$setup-node@v3
+ - uses: actions/checkout@v3
+ - uses: actions/setup-node@v3
with: { 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 repositories
TS_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"'; then
echo "$repo"
fi
@@ -432,17 +432,17 @@ Part of #$TRACKING_ISSUE"
while read -r repo; do
gh repo clone org/$repo /tmp/$repo -- --depth=1
cd /tmp/$repo
- npm audit --json > $tmp$audit-$repo.json
+ npm audit --json > /tmp/audit-$repo.json
done`)
// Apply patches
- Bash(`for repo in $tmp$audit-*.json; do
+ Bash(`for repo in /tmp/audit-*.json; do
if [ $(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 fix
if npm test; then
- git checkout -b security$patch-$(date +%Y%m%d)
+ git checkout -b security/patch-$(date +%Y%m%d)
git add -A
git 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.yml
version: 1
organization: my-org
repositories:
- name: frontend
- url: github.com$my-org$frontend
+ url: github.com/my-org/frontend
role: ui
agents: [coder, designer, tester]
- name: backend
- url: github.com$my-org$backend
+ url: github.com/my-org/backend
role: api
agents: [architect, coder, tester]
- name: shared
- url: github.com$my-org$shared
+ url: github.com/my-org/shared
role: library
agents: [analyst, coder]
coordination:
topology: hierarchical
communication: webhook
- memory: redis:/$shared-memory
+ memory: redis://shared-memory
dependencies:
- 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
```bash
npx 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
```bash
npx 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.md
index 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 commands
Examples:
- 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.json
index 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.json
index 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.json
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
new file mode 100644
index 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.json
index 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.ts
index 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 size
const 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.ts
index 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_backgr
function 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 tools
diff --git a/v3/@claude-flow/cli/src/mcp-tools/agent-tools.ts b/v3/@claude-flow/cli/src/mcp-tools/agent-tools.ts
index 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 applicable
const 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.ts
index 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.ts
index 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 trajectories
if (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.ts
index 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 search
if (text) {
+ if (embeddingServiceName === 'none') {
+ embeddingServiceName = 'hash-fallback';
+ }
const hash = text.split('').reduce((acc, char, i) => {
return acc + char.charCodeAt(0) * (i + 1);
}, 0);
@@ -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.ts
index 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.ts
index 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 available
loadPersistedStats();
+ // 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.ts
index 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 day
const 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 matching
const 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 available
if (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 heuristic
const 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 fallback
return {
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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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.ts
index 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-flow
diff --git a/v3/@claude-flow/memory/src/hnsw-index.ts b/v3/@claude-flow/memory/src/hnsw-index.ts
index 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.md
new file mode 100644
index 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.md
new file mode 100644
index 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 passing
diff --git a/v3/package-lock.json b/v3/package-lock.json
index 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.json
index 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.json
index 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.json
index 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.json
index 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.json
index 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.json
index 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.json
index 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.json
index 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.json
index 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.json
index 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.json
index 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.json
index 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",