π 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
Claude Flow V3
Modular AI Agent Coordination System - A complete reimagining of Claude-Flow with 15-agent hierarchical mesh swarm coordination.
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
- @claude-flow/security
- @claude-flow/memory
- @claude-flow/swarm
- @claude-flow/integration
- @claude-flow/performance
- @claude-flow/neural
- @claude-flow/cli
- @claude-flow/testing
- @claude-flow/shared
- @claude-flow/deployment
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.