Skip to content

06 troubleshooting performance issues

Jump to bottom
Doug Beard edited this page Aug 21, 2025 · 3 revisions

Coherence APM v4.2.0 Performance Issues and Optimization

This guide addresses performance-related problems in the Coherence APM Framework v4.2.0 and provides optimization strategies.

⚡ Performance Overview

Expected Performance Baselines

Coherence APM v4.2.0 Performance Baselines:

  • Command Execution: < 2 seconds for simple commands (67 total slash commands)
  • Persona Activation: < 3 seconds with TTS notifications (11 personas)
  • Coherence Orchestrator: < 5 seconds for initialization with unified context engineering
  • Session Management: < 1 second for context transfer and archiving
  • Memory Usage: < 100MB for typical operations
  • TTS Response: < 1 second for voice notifications (5 providers available)

Performance Indicators:

  • ✅ Good: Commands respond within expected baselines
  • ⚠️ Degraded: 2-5x slower than baseline performance
  • 🚨 Poor: >5x slower or system becomes unresponsive

🐌 Common Performance Issues

1. Slow Command Execution

Symptoms:

Commands take >10 seconds to respond
Long delays before persona activation
Timeout errors during command processing

Root Causes:

  • Large session note files
  • Excessive log accumulation
  • System resource constraints
  • Network latency (for remote operations)

Solutions:

Immediate Actions:

# Check system resources
top -p $(pgrep -f claude)
df -h /mnt/c/Code/agentic-persona-mapping/.apm/

# Archive large session files (automatic archiving to pre_compact_archive)
find /mnt/c/Code/agentic-persona-mapping/.apm/session_notes/ -name "*.md" -size +5M -ls

# Check session archive structure
ls -la /mnt/c/Code/agentic-persona-mapping/.apm/session_notes/pre_compact_archive/

# Restart with clean Coherence session
cd /mnt/c/Code/agentic-persona-mapping
/coherence

Long-term Optimization:

# Configure automatic session archiving
echo "MAX_SESSION_SIZE=1000000" >> {{APM_ROOT}}/config/performance.conf
echo "AUTO_ARCHIVE=true" >> {{APM_ROOT}}/config/performance.conf

# Set up log rotation
echo "LOG_ROTATE_SIZE=10M" >> {{APM_ROOT}}/config/logging.conf
echo "LOG_KEEP_DAYS=7" >> {{APM_ROOT}}/config/logging.conf

2. Memory Usage Issues

Symptoms:

Gradually increasing memory usage
System swap usage increasing
"Out of memory" errors
System becomes unresponsive during APM operations

Root Causes:

  • Memory leaks in long-running sessions
  • Large context preservation between handoffs
  • Excessive session history retention

Solutions:

Memory Analysis:

# Monitor APM memory usage
ps aux | grep -E "(claude|apm)" | awk '{sum+=$6} END {print "Total APM Memory: " sum/1024 " MB"}'

# Check for memory leaks
top -p $(pgrep -f claude) -b -n 1 | tail -n +8

# Analyze session file sizes
find {{APM_ROOT}}/session_notes/ -name "*.md" -exec ls -lh {} \; | sort -k5 -hr | head -10

Memory Optimization:

# Enable memory-efficient mode
export APM_MEMORY_MODE=efficient

# Limit session context size
echo "MAX_CONTEXT_SIZE=50000" >> {{APM_ROOT}}/config/session.conf

# Configure automatic cleanup
echo "SESSION_CLEANUP_INTERVAL=3600" >> {{APM_ROOT}}/config/performance.conf

# Restart with memory constraints
/wrap --compact-memory
/coherence --memory-limit 100M

Advanced Memory Management:

# Use session compaction
/switch --compact-session

# Archive old sessions
mv {{APM_ROOT}}/session_notes/*.md {{APM_ROOT}}/session_notes/archive/

# Clear caches
rm -rf {{APM_ROOT}}/cache/*

3. Slow Parallel Operations

Symptoms:

Parallel commands not showing expected speedup
Individual sub-agents executing slowly
Native sub-agent coordination delays

Root Causes:

  • System CPU constraints
  • I/O bottlenecks
  • Sub-agent resource contention
  • Network latency in distributed operations

Solutions:

Resource Optimization:

# Check CPU availability
nproc
top -b -n 1 | grep "Cpu(s)"

# Monitor parallel execution
/parallel-test --benchmark --verbose

# Tune parallel execution
echo "MAX_PARALLEL_AGENTS=4" >> {{APM_ROOT}}/config/parallel.conf
echo "PARALLEL_TIMEOUT=30" >> {{APM_ROOT}}/config/parallel.conf

I/O Optimization:

# Check disk I/O
iostat -x 1 3

# Use faster storage for session notes (if available)
export APM_FAST_STORAGE="/tmp/apm-session"
mkdir -p $APM_FAST_STORAGE
ln -sf $APM_FAST_STORAGE {{APM_ROOT}}/session_notes/active

# Enable asynchronous I/O
echo "ASYNC_IO=true" >> {{APM_ROOT}}/config/performance.conf

Parallel Agent Tuning:

# Optimize for your system
export APM_PARALLEL_WORKERS=$(nproc)
export APM_WORKER_MEMORY="50M"

# Use conservative settings for resource-constrained systems
export APM_PARALLEL_WORKERS=2
export APM_WORKER_TIMEOUT=60

4. Session Management Performance

Symptoms:

Slow session creation and switching
Long delays during /handoff operations
Context preservation taking excessive time

Root Causes:

  • Large session context
  • Inefficient session serialization
  • Excessive session history

Solutions:

Session Optimization:

# Enable session streaming
echo "SESSION_STREAM_MODE=true" >> {{APM_ROOT}}/config/session.conf

# Limit context preservation
echo "CONTEXT_PRESERVE_LIMIT=1000" >> {{APM_ROOT}}/config/session.conf

# Use incremental session updates
echo "SESSION_INCREMENTAL=true" >> {{APM_ROOT}}/config/session.conf

# Test session performance
/session-benchmark --verbose

Context Management:

# Compress large contexts
echo "CONTEXT_COMPRESSION=gzip" >> {{APM_ROOT}}/config/session.conf

# Use smart context filtering
echo "CONTEXT_SMART_FILTER=true" >> {{APM_ROOT}}/config/session.conf

# Enable context caching
echo "CONTEXT_CACHE=true" >> {{APM_ROOT}}/config/session.conf

5. TTS Voice Notification Delays

Symptoms:

Long delays before voice notifications play
Audio stuttering or distortion during persona activation
TTS blocking other operations
Voice notifications failing to play

Root Causes:

  • TTS provider misconfiguration (5 providers available)
  • Audio system latency
  • TTS processing overhead
  • Wrong TTS provider selected

Solutions:

TTS Provider Optimization (5 providers available):

# Test all TTS providers for performance
time bash /mnt/c/Code/agentic-persona-mapping/.apm/agents/scripts/tts-providers/system.sh "Performance test"
time bash /mnt/c/Code/agentic-persona-mapping/.apm/agents/scripts/tts-providers/piper.sh "Performance test"
time bash /mnt/c/Code/agentic-persona-mapping/.apm/agents/scripts/tts-providers/elevenlabs.sh "Performance test"

# Use fastest TTS provider
# System TTS (fastest, basic)
bash /mnt/c/Code/agentic-persona-mapping/.apm/agents/scripts/tts-providers/system.sh

# Piper TTS (good balance of speed and quality)
bash /mnt/c/Code/agentic-persona-mapping/.apm/agents/scripts/tts-providers/piper.sh

# Disable TTS for maximum performance
bash /mnt/c/Code/agentic-persona-mapping/.apm/agents/scripts/tts-providers/none.sh

Voice System Configuration:

# Test voice script performance
time bash /mnt/c/Code/agentic-persona-mapping/.apm/agents/voice/speakOrchestrator.sh "Test"
time bash /mnt/c/Code/agentic-persona-mapping/.apm/agents/voice/speakDeveloper.sh "Test"

# If TTS causes delays, configure for performance
# Check TTS configuration scripts
ls -la /mnt/c/Code/agentic-persona-mapping/.apm/agents/scripts/configure-tts.sh
ls -la /mnt/c/Code/agentic-persona-mapping/.apm/agents/scripts/tts-manager.sh

🔧 Performance Monitoring

Built-in Performance Tools

APM Performance Monitor:

# Real-time performance monitoring
{{APM_ROOT}}/scripts/performance-monitor.sh

# Performance benchmarking
{{APM_ROOT}}/scripts/benchmark-apm.sh --full

# Resource usage tracking
{{APM_ROOT}}/scripts/resource-tracker.sh --start

Command-specific Benchmarks:

# Test persona activation speed
time /dev --benchmark

# Test parallel operation performance
time /parallel-test --benchmark

# Test session management performance
time /switch dev --benchmark

System Performance Monitoring

Resource Monitoring:

# CPU and Memory usage
htop -p $(pgrep -f claude)

# Disk I/O monitoring
iotop -p $(pgrep -f claude)

# Network usage (if applicable)
nethogs -p $(pgrep -f claude)

Performance Logging:

# Enable performance logging
echo "PERF_LOGGING=true" >> {{APM_ROOT}}/config/logging.conf

# Monitor performance logs
tail -f {{APM_ROOT}}/logs/performance.log

# Analyze performance trends
{{APM_ROOT}}/scripts/analyze-performance.sh --last-week

⚡ Performance Optimization Strategies

1. System-Level Optimizations

CPU Optimization:

# Set CPU governor for performance
echo performance | sudo tee /sys/devices/system/cpu/cpu*/cpufreq/scaling_governor

# Disable CPU throttling during APM operations
echo 0 | sudo tee /sys/devices/system/cpu/intel_pstate/no_turbo

# Use all available cores
export OMP_NUM_THREADS=$(nproc)

Memory Optimization:

# Increase swappiness for better memory management
echo 10 | sudo tee /proc/sys/vm/swappiness

# Clear system caches before intensive operations
sync && echo 3 | sudo tee /proc/sys/vm/drop_caches

I/O Optimization:

# Use SSD-optimized settings
echo deadline | sudo tee /sys/block/*/queue/scheduler

# Increase I/O queue depth
echo 128 | sudo tee /sys/block/*/queue/nr_requests

2. APM-Specific Optimizations

Configuration Tuning:

# Create performance-optimized config
cat > {{APM_ROOT}}/config/performance.conf << 'EOF'
# APM Performance Configuration
MAX_SESSION_SIZE=500000
SESSION_CLEANUP_INTERVAL=1800
CONTEXT_PRESERVE_LIMIT=2000
PARALLEL_WORKERS=4
MEMORY_LIMIT=200M
CACHE_SIZE=100M
TTS_ASYNC=true
LOG_LEVEL=WARN
EOF

# Apply configuration
source {{APM_ROOT}}/config/performance.conf

Resource Allocation:

# Allocate dedicated resources for APM
nice -n -10 /coherence  # Higher priority
ionice -c 1 -n 4  # Real-time I/O scheduling

# Use memory mapping for large files
echo "MEMORY_MAP_SESSIONS=true" >> {{APM_ROOT}}/config/performance.conf

3. Workflow Optimizations

Session Management:

# Use efficient session patterns
/coherence --quick-start  # Skip verbose initialization
/dev --fast-mode   # Reduce context loading
/handoff architect --minimal-context  # Faster handoffs

Parallel Operations:

# Optimize parallel command usage
/planning-architecture --workers=2  # Match CPU cores
/parallel-test --batch-size=10      # Optimal batch size
/parallel-development --memory-aware # Respect memory limits

📊 Performance Benchmarking

Baseline Performance Tests

Command Execution Benchmarks:

# Basic command performance
echo "=== Basic Command Performance ===" > performance-report.txt
(time /coherence --test-mode) 2>> performance-report.txt
(time /dev --test-mode) 2>> performance-report.txt
(time /architect --test-mode) 2>> performance-report.txt

# Parallel operation benchmarks
echo "=== Parallel Operation Performance ===" >> performance-report.txt
(time /parallel-test --benchmark) 2>> performance-report.txt
(time /planning-architecture --benchmark) 2>> performance-report.txt

Session Management Benchmarks:

# Session operation performance
echo "=== Session Management Performance ===" >> performance-report.txt
(time /handoff dev) 2>> performance-report.txt
(time /switch architect) 2>> performance-report.txt
(time /wrap) 2>> performance-report.txt

Performance Regression Testing

Automated Performance Tests:

# Run comprehensive performance test suite
{{APM_ROOT}}/scripts/performance-test-suite.sh

# Compare with baseline
{{APM_ROOT}}/scripts/compare-performance.sh baseline.json current.json

# Generate performance report
{{APM_ROOT}}/scripts/generate-perf-report.sh > performance-analysis.html

🚨 Performance Troubleshooting Flowchart

Step 1: Identify Performance Issue Type

Is the issue:
├── Command execution slowness? → Go to "Slow Command Execution"
├── Memory usage problems? → Go to "Memory Usage Issues"  
├── Parallel operation slowness? → Go to "Slow Parallel Operations"
├── Session management delays? → Go to "Session Management Performance"
└── Voice notification delays? → Go to "Voice Notification Delays"

Step 2: Apply Immediate Solutions

For each issue type:
1. Apply immediate solutions
2. Monitor for improvement
3. If improved, apply long-term optimizations
4. If not improved, proceed to advanced troubleshooting

Step 3: Advanced Performance Analysis

# Generate detailed performance profile
{{APM_ROOT}}/scripts/profile-apm.sh --detailed

# Analyze system bottlenecks
{{APM_ROOT}}/scripts/bottleneck-analysis.sh

# Create {{APM_ROOT}}/scripts/optimization-planner.sh

🛠️ Performance Recovery Procedures

Emergency Performance Recovery

# Stop all APM processes
pkill -f apm
pkill -f claude

# Clear all caches and temporary files
rm -rf {{APM_ROOT}}/cache/*
rm -rf {{APM_ROOT}}/temp/*
rm -f {{APM_ROOT}}/logs/*.tmp

# Archive large session files
find {{APM_ROOT}}/session_notes/ -size +1M -exec mv {} {{APM_ROOT}}/session_notes/archive/ \;

# Restart with minimal configuration
export APM_MINIMAL_MODE=true
/coherence --recovery-mode

Performance Reset

# Reset all performance configurations to defaults
cp {{APM_ROOT}}/config/default/* {{APM_ROOT}}/config/

# Clear performance logs
truncate -s 0 {{APM_ROOT}}/logs/performance.log

# Restart APM with fresh session
/wrap --force
/coherence --clean-start

📚 Related Resources

Last Updated: 2025-08-19 Coherence APM Framework v4.2.0 - Enhanced TTS Audio Experience

Clone this wiki locally