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

17.9 KB
Raw Blame

Claude Flow V3

Modular AI Agent Coordination System - A complete reimagining of Claude-Flow with 15-agent hierarchical mesh swarm coordination.

Version Node.js TypeScript License

Introduction

Claude Flow V3 is a next-generation AI agent coordination system built on 10 Architecture Decision Records (ADRs). It provides a modular, security-first, high-performance platform for orchestrating multi-agent swarms with hierarchical mesh topology.

V3 represents a complete architectural overhaul:

  • 10x faster testing with Vitest
  • 150x-12,500x faster search with HNSW indexing
  • 2.49x-7.47x Flash Attention speedup
  • 50-75% memory reduction

Features

Core Capabilities

  • 15-Agent Hierarchical Mesh - Queen-led coordination with specialized worker agents
  • Domain-Driven Design - Clean bounded contexts with separation of concerns
  • Plugin Architecture - Microkernel pattern for extensibility
  • MCP-First API - Consistent interfaces across all modules
  • Event Sourcing - Full audit trail for state changes
  • Hybrid Memory Backend - SQLite + AgentDB for optimal performance

Security

  • CVE Remediation - All known vulnerabilities addressed
  • Input Validation - Zod-based schema validation
  • Secure ID Generation - Cryptographic random IDs
  • Path Security - Traversal protection
  • SQL Injection Prevention - Parameterized queries

Performance

Metric Target Achieved
Event Bus (100k events) <50ms ~6ms
Map Lookup (100k gets) <20ms ~16ms
Array.find vs Map O(1) N/A 978x speedup
Flash Attention 2.49x-7.47x Validated
AgentDB Search 150x-12,500x HNSW indexed

Architecture

Architecture Decision Records (ADRs)

ADR Decision
ADR-001 Adopt agentic-flow as core foundation
ADR-002 Domain-Driven Design structure
ADR-003 Single coordination engine (UnifiedSwarmCoordinator)
ADR-004 Plugin-based architecture (microkernel)
ADR-005 MCP-first API design
ADR-006 Unified memory service (AgentDB)
ADR-007 Event sourcing for state changes
ADR-008 Vitest over Jest (10x faster)
ADR-009 Hybrid memory backend default
ADR-010 Remove Deno support (Node.js 20+ only)

Module Architecture

β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚                     @claude-flow/v3-monorepo                    β”‚
β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€
β”‚                                                                 β”‚
β”‚  β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”  β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”  β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”          β”‚
β”‚  β”‚   security   β”‚  β”‚    memory    β”‚  β”‚    swarm     β”‚          β”‚
β”‚  β”‚  CVE fixes   β”‚  β”‚   AgentDB    β”‚  β”‚ 15-agent     β”‚          β”‚
β”‚  β”‚  validation  β”‚  β”‚   HNSW       β”‚  β”‚ coordination β”‚          β”‚
β”‚  β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜  β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜  β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜          β”‚
β”‚                                                                 β”‚
β”‚  β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”  β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”  β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”          β”‚
β”‚  β”‚ integration  β”‚  β”‚  performance β”‚  β”‚    neural    β”‚          β”‚
β”‚  β”‚ agentic-flow β”‚  β”‚ Flash Attn   β”‚  β”‚   SONA       β”‚          β”‚
β”‚  β”‚  bridge      β”‚  β”‚ benchmarks   β”‚  β”‚  learning    β”‚          β”‚
β”‚  β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜  β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜  β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜          β”‚
β”‚                                                                 β”‚
β”‚  β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”  β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”  β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”          β”‚
β”‚  β”‚     cli      β”‚  β”‚   testing    β”‚  β”‚  deployment  β”‚          β”‚
β”‚  β”‚  commands    β”‚  β”‚ TDD London   β”‚  β”‚   release    β”‚          β”‚
β”‚  β”‚  prompts     β”‚  β”‚   School     β”‚  β”‚    CI/CD     β”‚          β”‚
β”‚  β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜  β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜  β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜          β”‚
β”‚                                                                 β”‚
β”‚  β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”   β”‚
β”‚  β”‚                       shared                             β”‚   β”‚
β”‚  β”‚  types β€’ events β€’ core β€’ hooks β€’ resilience β€’ plugins   β”‚   β”‚
β”‚  β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜   β”‚
β”‚                                                                 β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜

Directory Structure

v3/
β”œβ”€β”€ @claude-flow/                    # Modular packages
β”‚   β”œβ”€β”€ security/                    # Security module
β”‚   β”‚   └── src/
β”‚   β”‚       β”œβ”€β”€ index.ts             # Password hashing, validators
β”‚   β”‚       └── ...
β”‚   β”‚
β”‚   β”œβ”€β”€ memory/                      # Memory module
β”‚   β”‚   β”œβ”€β”€ src/
β”‚   β”‚   β”‚   β”œβ”€β”€ agentdb-backend.ts   # AgentDB integration
β”‚   β”‚   β”‚   β”œβ”€β”€ hnsw-index.ts        # HNSW vector indexing
β”‚   β”‚   β”‚   β”œβ”€β”€ hybrid-backend.ts    # SQLite + AgentDB
β”‚   β”‚   β”‚   β”œβ”€β”€ sqlite-backend.ts    # SQLite backend
β”‚   β”‚   β”‚   β”œβ”€β”€ cache-manager.ts     # Caching layer
β”‚   β”‚   β”‚   └── domain/              # DDD entities
β”‚   β”‚   β”œβ”€β”€ benchmarks/              # Performance benchmarks
β”‚   β”‚   └── examples/                # Usage examples
β”‚   β”‚
β”‚   β”œβ”€β”€ swarm/                       # Swarm coordination
β”‚   β”‚   └── src/
β”‚   β”‚       β”œβ”€β”€ unified-coordinator.ts  # Main coordinator
β”‚   β”‚       β”œβ”€β”€ topology-manager.ts     # Topology management
β”‚   β”‚       β”œβ”€β”€ consensus/              # Consensus protocols
β”‚   β”‚       └── domain/                 # DDD entities
β”‚   β”‚
β”‚   β”œβ”€β”€ integration/                 # agentic-flow integration
β”‚   β”‚   └── src/
β”‚   β”‚       β”œβ”€β”€ agentic-flow-bridge.ts  # Core bridge
β”‚   β”‚       β”œβ”€β”€ agent-adapter.ts        # Agent adaptation
β”‚   β”‚       └── sona-adapter.ts         # SONA learning
β”‚   β”‚
β”‚   β”œβ”€β”€ performance/                 # Performance module
β”‚   β”‚   β”œβ”€β”€ src/
β”‚   β”‚   β”‚   └── framework/           # Benchmark framework
β”‚   β”‚   └── benchmarks/
β”‚   β”‚       β”œβ”€β”€ startup/             # Startup benchmarks
β”‚   β”‚       └── attention/           # Flash Attention
β”‚   β”‚
β”‚   β”œβ”€β”€ neural/                      # Neural/SONA module
β”‚   β”‚   └── src/
β”‚   β”‚       β”œβ”€β”€ algorithms/          # Learning algorithms
β”‚   β”‚       └── modes/               # Neural modes
β”‚   β”‚
β”‚   β”œβ”€β”€ cli/                         # CLI module
β”‚   β”‚   β”œβ”€β”€ bin/                     # Executable
β”‚   β”‚   └── src/
β”‚   β”‚       └── commands/            # Command handlers
β”‚   β”‚
β”‚   β”œβ”€β”€ testing/                     # Testing framework
β”‚   β”‚   └── src/
β”‚   β”‚       β”œβ”€β”€ fixtures/            # Test fixtures
β”‚   β”‚       β”œβ”€β”€ mocks/               # Mock services
β”‚   β”‚       β”œβ”€β”€ helpers/             # Test helpers
β”‚   β”‚       └── regression/          # Regression tests
β”‚   β”‚
β”‚   β”œβ”€β”€ shared/                      # Shared utilities
β”‚   β”‚   └── src/
β”‚   β”‚       β”œβ”€β”€ types/               # Shared types
β”‚   β”‚       β”œβ”€β”€ events/              # Event system
β”‚   β”‚       β”œβ”€β”€ core/                # Core interfaces
β”‚   β”‚       β”œβ”€β”€ hooks/               # Hook system
β”‚   β”‚       β”œβ”€β”€ resilience/          # Retry, circuit breaker
β”‚   β”‚       β”œβ”€β”€ plugins/             # Plugin system
β”‚   β”‚       └── security/            # Security utilities
β”‚   β”‚
β”‚   └── deployment/                  # Deployment module
β”‚       └── src/                     # Release management
β”‚
β”œβ”€β”€ mcp/                             # MCP Server
β”‚   β”œβ”€β”€ server.ts                    # Main server
β”‚   β”œβ”€β”€ tools/                       # MCP tools
β”‚   β”‚   β”œβ”€β”€ agent-tools.ts
β”‚   β”‚   β”œβ”€β”€ swarm-tools.ts
β”‚   β”‚   β”œβ”€β”€ memory-tools.ts
β”‚   β”‚   └── hooks-tools.ts
β”‚   └── transport/                   # Transport layers
β”‚       β”œβ”€β”€ stdio.ts
β”‚       β”œβ”€β”€ http.ts
β”‚       └── websocket.ts
β”‚
β”œβ”€β”€ __tests__/                       # Integration tests
β”‚   └── integration/
β”‚       β”œβ”€β”€ memory-integration.test.ts
β”‚       β”œβ”€β”€ swarm-integration.test.ts
β”‚       β”œβ”€β”€ mcp-integration.test.ts
β”‚       └── workflow-integration.test.ts
β”‚
β”œβ”€β”€ docs/                            # Documentation
β”‚   β”œβ”€β”€ README.md                    # Docs overview
β”‚   β”œβ”€β”€ guides/                      # User guides
β”‚   └── implementation/              # Implementation details
β”‚
β”œβ”€β”€ helpers/                         # Cross-platform helpers
β”‚   β”œβ”€β”€ claude-flow-v3.sh            # Master helper (Linux/macOS)
β”‚   β”œβ”€β”€ claude-flow-v3.ps1           # Master helper (Windows)
β”‚   └── templates/                   # Helper templates
β”‚
β”œβ”€β”€ scripts/                         # Utility scripts
β”‚   └── quick-benchmark.mjs          # Quick perf test
β”‚
β”œβ”€β”€ index.ts                         # Main entry point
β”œβ”€β”€ swarm.config.ts                  # Swarm configuration
β”œβ”€β”€ vitest.config.ts                 # Test configuration
└── package.json                     # Monorepo package

Modules

@claude-flow/security

Security-first implementation with CVE fixes, input validation, and credential management.

import { PasswordHasher, validateInput, sanitizePath } from '@claude-flow/security';

const hasher = new PasswordHasher();
const hash = await hasher.hash('password');
const valid = await hasher.verify('password', hash);

@claude-flow/memory

Unified memory service with AgentDB, HNSW indexing, and 150x-12,500x faster search.

import { HybridMemoryRepository, HNSWIndex } from '@claude-flow/memory';

const memory = new HybridMemoryRepository({
  backend: 'agentdb',
  vectorSearch: true
});

await memory.store({ key: 'knowledge', value: 'context', embedding: [...] });
const results = await memory.search({ query: 'knowledge', limit: 10 });

@claude-flow/swarm

15-agent hierarchical mesh coordination with consensus protocols.

import { UnifiedSwarmCoordinator } from '@claude-flow/swarm';

const coordinator = new UnifiedSwarmCoordinator({
  topology: 'hierarchical-mesh',
  maxAgents: 15
});

await coordinator.initialize();
await coordinator.spawnAgent({ type: 'queen-coordinator' });

@claude-flow/integration

Deep integration with agentic-flow@alpha per ADR-001.

import { AgenticFlowBridge } from '@claude-flow/integration';

const bridge = new AgenticFlowBridge();
await bridge.initialize();
const agent = await bridge.createAgent({ type: 'coder' });

@claude-flow/performance

Benchmarking framework with Flash Attention validation.

import { BenchmarkRunner, formatTime } from '@claude-flow/performance';

const runner = new BenchmarkRunner();
const result = await runner.run('map-lookup', () => map.get(key), {
  iterations: 100000,
  targetTime: 20
});

@claude-flow/neural

SONA learning integration for self-optimizing agents.

import { SONAAdapter } from '@claude-flow/neural';

const sona = new SONAAdapter();
await sona.train({ patterns: learningData });
const prediction = await sona.predict(context);

@claude-flow/cli

Modern CLI with interactive prompts and formatted output.

npx @claude-flow/cli swarm init --topology hierarchical-mesh
npx @claude-flow/cli agent spawn --type queen-coordinator
npx @claude-flow/cli memory search "knowledge"

@claude-flow/testing

TDD London School framework with mocks, fixtures, and regression testing.

import { createMockAgent, createTestFixture } from '@claude-flow/testing';

const mockAgent = createMockAgent({ type: 'coder' });
const fixture = createTestFixture('swarm-coordination');

@claude-flow/shared

Common types, events, utilities, and core interfaces.

import { EventBus, Result, success, failure } from '@claude-flow/shared';
import type { AgentId, TaskStatus } from '@claude-flow/shared/types';

@claude-flow/deployment

Release management and CI/CD automation.

import { ReleaseManager } from '@claude-flow/deployment';

const release = new ReleaseManager();
await release.prepare({ version: '3.0.0', changelog: '...' });

Usage

Quick Start

import { initializeV3Swarm } from '@claude-flow/v3';

// Initialize the swarm
const swarm = await initializeV3Swarm();

// Spawn agents
await swarm.spawnAllAgents();

// Submit a task
const task = swarm.submitTask({
  type: 'implementation',
  title: 'Implement feature X',
  description: 'Detailed description...',
  domain: 'core',
  phase: 'phase-2-core',
  priority: 'high'
});

// Wait for completion
const result = await swarm.waitForTask(task.id);

Import Specific Modules

// Import everything
import * as claudeFlow from '@claude-flow/v3';

// Or import specific modules for tree-shaking
import { UnifiedSwarmCoordinator } from '@claude-flow/swarm';
import { PasswordHasher } from '@claude-flow/security';
import { HNSWIndex } from '@claude-flow/memory';

MCP Server

import { createMCPServer } from '@claude-flow/v3/mcp';

const server = createMCPServer({
  transport: 'stdio',
  tools: ['agent', 'swarm', 'memory', 'hooks']
});

await server.start();

Helper System

Cross-platform automation for V3 development:

# Linux/macOS
./helpers/claude-flow-v3.sh init
./helpers/claude-flow-v3.sh status
./helpers/claude-flow-v3.sh update domain 3

# Windows (PowerShell)
.\helpers\claude-flow-v3.ps1 init
.\helpers\claude-flow-v3.ps1 status
.\helpers\claude-flow-v3.ps1 update domain 3

Features:

  • Progress Tracking: Real-time domain/agent/performance metrics
  • Checkpointing: Auto-commit with development milestones
  • Validation: Environment and configuration verification
  • GitHub Integration: PR management and issue tracking

Installation

# Clone the repository
git clone https://github.com/ruvnet/claude-flow.git
cd claude-flow/v3

# Install dependencies
pnpm install

# Build all modules
pnpm build

Testing

# Run all tests
pnpm test

# Run integration tests
pnpm test:integration

# Run specific module tests
pnpm test:memory
pnpm test:swarm
pnpm test:security

# Run benchmarks
pnpm bench

# Quick benchmark (no dependencies)
node scripts/quick-benchmark.mjs

# Coverage report
pnpm test:coverage

Performance Targets

Category Metric Target
Search AgentDB HNSW 150x-12,500x faster
Attention Flash Attention 2.49x-7.47x speedup
Memory Reduction 50-75%
Code Total lines <5,000
Startup Cold start <500ms
Learning SONA adaptation <0.05ms

Links

Documentation

Modules

Examples

MCP Tools

External

Requirements

  • Node.js: >=20.0.0
  • pnpm: >=8.0.0
  • TypeScript: >=5.3.0

License

MIT License - See LICENSE for details.


Built with the SPARC methodology and 15-agent hierarchical mesh coordination.