# Claude-Flow (Ruflo v3) Research Summary

> Research conducted 2026-02-24 for makima improvement evaluation

## Overview

claude-flow (marketed as Ruflo v3) is an enterprise AI orchestration system built around Claude Code. It provides 175+ MCP tools, manages 60+ specialized agents, and has accumulated 5,923+ commits. Key performance claims: 84.8% SWE-Bench solve rate, 2.8-4.4x faster task completion vs baseline Claude Code.

**Repository**: https://github.com/ruvnet/claude-flow

## Architecture

### Layered Design
```
User Layer:       CLI + Claude Code interfaces
Entry Layer:      MCP Server with AIDefence security validation
Routing Layer:    Q-Learning router + MoE (8 experts) + 42 skills + 17 hooks
Swarm Layer:      Topologies (mesh/hierarchical/ring/star) + consensus
Agent Layer:      60+ specialized agents
Resources:        Memory systems, LLM providers, 12 background workers
Intelligence:     RuVector with 10+ optimization components
```

### MCP Integration
- Runs as stdio process providing 175+ tools
- MCP 2025-11-25 full specification compliance
- Supports tools, resources, prompts, and tasks
- Multiple transports: stdio, HTTP, WebSocket, in-process

## Multi-Agent Coordination (Hive Mind)

### Queen Types (Coordinators)
| Type | Role |
|------|------|
| Strategic | Planning and goal decomposition |
| Tactical | Execution coordination |
| Adaptive | Optimization and learning |

### Worker Types (8 Specialized Roles)
1. **Researcher** - Information gathering and analysis
2. **Coder** - Implementation
3. **Analyst** - Data analysis and insights
4. **Tester** - Quality assurance
5. **Architect** - System design
6. **Reviewer** - Code review and quality gates
7. **Optimizer** - Performance tuning
8. **Documenter** - Documentation generation

### Consensus Algorithms
- **Byzantine** (f < n/3): 2/3 majority for decisions
- **Weighted Voting**: Queen has 3x authority
- **Majority Voting**: Simple democratic decisions

## Task Routing & Scheduling

### Q-Learning Router
- Combined with MoE (8 experts)
- 89% routing accuracy
- 34,798 routes/s throughput
- Learns which agents perform best per task type through execution trajectories

### Three-Tier Routing Strategy
| Tier | Handler | Latency | Cost |
|------|---------|---------|------|
| Simple | Agent Booster WASM | <1ms | $0 |
| Medium | Haiku/Sonnet | ~500ms | Low |
| Complex | Opus + multi-agent swarms | 2-5s | Standard |

### Task Templates (Agent Combinations)
| Task Type | Recommended Agents |
|-----------|--------------------|
| Bug Fix | Coordinator, Researcher, Coder, Tester |
| Feature | Coordinator, Architect, Coder, Tester, Reviewer |
| Refactor | Coordinator, Architect, Coder, Reviewer |
| Performance | Coordinator, Perf-Engineer, Coder |
| Security | Coordinator, Security-Architect, Auditor |

## Self-Learning Mechanisms

### SONA (Self-Optimizing Neural Architecture)
- <0.05ms adaptation time
- Rapid behavior adjustment at runtime
- Two-tier LoRA + EWC++ + ReasoningBank integration

### EWC++ (Elastic Weight Consolidation)
- Preserves 95%+ knowledge across tasks
- Prevents catastrophic forgetting

### ReasoningBank
- Pattern caching with RETRIEVE → JUDGE → DISTILL → CONSOLIDATE → ROUTE cycle
- 32% token savings through pattern retrieval instead of full context
- Stores successful execution trajectories for reuse

### MicroLoRA
- 128x compressed fine-tuning
- No full retraining required
- Lightweight runtime adaptation

## Memory & Context Sharing

### 3-Scope Architecture
| Scope | Purpose |
|-------|---------|
| Project | Task-specific context |
| Local | Machine/user patterns |
| User | Cross-project learnings |

### Storage Stack
- **HNSW Vector Search**: 150x-12,500x faster retrieval, 16,400 QPS
- **AgentDB**: SQLite with WAL for persistence
- **LRU Cache**: Sub-millisecond access for hot data
- **Knowledge Graph**: PageRank + community detection for insight ranking

### 8 Memory Types
Attention, episodic, procedural, semantic, + 4 additional types for comprehensive knowledge representation.

## Drift Control

Critical for multi-agent alignment:
1. **Hierarchical Coordinator** validates all outputs against goals
2. **Small Teams** (6-8 agents) reduce coordination overhead
3. **Frequent Checkpoints** via post-task hooks verify compliance
4. **Raft Consensus** maintains authoritative state
5. **Specialized Roles** enforce clear task boundaries

## Cost Optimization

### Multi-Layer Strategy
| Layer | Mechanism | Savings |
|-------|-----------|---------|
| 1 | Agent Booster WASM | Eliminates tokens entirely |
| 2 | Haiku/Sonnet routing | 75% lower than Opus |
| 3 | ReasoningBank | -32% token savings |
| 4 | Token compression | 30-50% reduction |
| 5 | Caching | 95% hit rate |
| **Combined** | **All layers** | **Extends Claude Max 250%** |

## Hook System

33+ hooks across 7 categories:
- **Session**: start, end
- **Agent**: pre-spawn, post-spawn, pre-terminate
- **Task**: pre-execute, post-complete, error
- **Tool**: pre-call, post-call
- **Memory**: store/retrieve operations
- **Swarm**: coordination events
- **File**: read/write operations

Self-Learning Hooks feed execution insights back into the Q-Learning router.

## Claims System (Human-Agent Coordination)
- **Claim**: Agent requests task ownership
- **Release**: Agent returns uncompleted work
- **Handoff**: Human reassigns to different agent
- Prevents duplicate effort and maintains clear responsibility

## Fault Tolerance
- Byzantine fault-tolerant (f < n/3, 2/3 majority)
- 6 LLM provider failover (Claude, GPT, Gemini, etc.)
- Checkpoint system prevents cascading failures
- Persist/Restore/Export session management

## Swarm Topologies
| Topology | Structure | Best For |
|----------|-----------|----------|
| Hierarchical | Coordinator + workers | Structured coding tasks (0.20s, 256MB/agent) |
| Mesh | Peer-to-peer | Collaborative, high redundancy |
| Ring | Sequential chain | Pipeline processing |
| Star | Hub-and-spoke | Centralized control |