Swarm Performance Optimizations

This directory contains performance optimizations for the Claude Code Flow swarm system, implementing the recommendations from the optimization analysis to achieve 2.5x performance improvement.

🚀 Quick Start

import { createOptimizedSwarmStack } from './swarm/optimizations/index.ts';

// Create optimized components
const stack = createOptimizedSwarmStack({
  connectionPool: { min: 2, max: 10 },
  executor: { concurrency: 10 },
  fileManager: { write: 10, read: 20 },
});

// Use in your swarm coordinator
const executor = stack.executor;
const result = await executor.executeTask(task, agentId);

// Clean shutdown
await stack.shutdown();

📦 Components

1. Connection Pool (connection-pool.ts)

• Manages reusable Claude API connections
• Reduces connection overhead by 95%
• Automatic health checks and eviction

2. Async File Manager (async-file-manager.ts)

• Non-blocking file operations with queuing
• Parallel read/write operations
• Stream support for large files

3. Circular Buffer (circular-buffer.ts)

• Fixed-size event history (prevents memory leaks)
• O(1) push operations
• Automatic rotation of old events

4. TTL Map (ttl-map.ts)

• Time-based automatic cleanup
• LRU eviction when size limit reached
• Perfect for task state management

5. Optimized Executor (optimized-executor.ts)

• Combines all optimizations
• Parallel task execution
• Built-in caching and metrics

📊 Performance Improvements

🔧 Integration Guide

Step 1: Update SwarmCoordinator

// In SwarmCoordinator constructor
private initializeOptimizations() {
  this.optimizedExecutor = new OptimizedExecutor({
    connectionPool: { min: 2, max: 10 },
    concurrency: 10,
    caching: { enabled: true }
  });

  // Replace arrays with optimized structures
  this.events = new CircularBuffer(1000);
  this.tasks = new TTLMap({ defaultTTL: 3600000 });
}

Step 2: Update Task Execution

// Replace synchronous execution
async executeTask(taskId: string) {
  const task = this.tasks.get(taskId);
  const agent = this.agents.get(task.assignedTo?.id);

  // Use optimized executor
  const result = await this.optimizedExecutor.executeTask(task, agent.id);

  task.result = result;
  task.status = 'completed';
}

Step 3: Implement Agent Index

// Build capability index for O(1) selection
private agentCapabilityIndex = new Map<string, Set<string>>();

private indexAgent(agent: AgentState) {
  for (const capability of agent.capabilities) {
    if (!this.agentCapabilityIndex.has(capability)) {
      this.agentCapabilityIndex.set(capability, new Set());
    }
    this.agentCapabilityIndex.get(capability)!.add(agent.id.id);
  }
}

📈 Monitoring

Use the performance monitor to track optimization metrics:

import { PerformanceMonitor } from './optimizations/performance_monitor.ts';

const monitor = new PerformanceMonitor();
monitor.attach_executor(executor);
monitor.attach_connection_pool(connectionPool);

// Start monitoring
await monitor.start_monitoring();

// Get metrics
const metrics = monitor.get_current_metrics();
console.log('Cache hit rate:', metrics.executor.cache_hit_rate);

🧪 Testing

Run the optimization tests:

npm test src/swarm/optimizations/__tests__/optimization.test.ts

Compare performance with benchmarks:

cd benchmark
python compare_optimizations.py

📋 Migration Checklist

• Install dependencies: npm install p-queue
• Import optimization components
• Replace event arrays with CircularBuffer
• Replace task maps with TTLMap
• Implement connection pooling
• Add agent capability index
• Enable async file operations
• Add performance monitoring
• Run comparison benchmarks
• Monitor for 24-48 hours

🎯 Best Practices

1. Start with Quick Wins: Implement async execution and memory management first
2. Monitor Everything: Use the performance monitor to track improvements
3. Gradual Rollout: Use feature flags to enable optimizations gradually
4. Test Thoroughly: Run benchmarks before and after each optimization
5. Document Changes: Keep track of configuration changes and results

🚨 Common Issues

High Memory Usage

• Check CircularBuffer sizes
• Verify TTL settings on maps
• Monitor task cleanup

Connection Pool Exhaustion

• Increase max connections
• Check for connection leaks
• Monitor pool statistics

Cache Misses

• Verify cache key generation
• Check TTL settings
• Monitor cache hit rates

📊 Expected Results

After implementing all optimizations:

• 50% reduction in task execution time
• 70% reduction in memory usage
• 2.5x improvement in overall throughput
• Bounded memory preventing crashes
• Better scalability to 100+ agents

🔗 Related Documentation

• Migration Guide
• Optimization Analysis
• Benchmark Results

🤝 Contributing

When adding new optimizations:

1. Follow the existing pattern of modular components
2. Include comprehensive tests
3. Add performance benchmarks
4. Update documentation
5. Measure impact with comparison scripts