diff options
Diffstat (limited to 'docs/research/claude-flow-research.md')
| -rw-r--r-- | docs/research/claude-flow-research.md | 169 |
1 files changed, 169 insertions, 0 deletions
diff --git a/docs/research/claude-flow-research.md b/docs/research/claude-flow-research.md new file mode 100644 index 0000000..479691a --- /dev/null +++ b/docs/research/claude-flow-research.md @@ -0,0 +1,169 @@ +# 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 | |