CFN Memory Management Skill

Purpose: Prevent and detect memory leaks in Claude CLI operations through proactive monitoring, limits, and profiling.

Overview

This skill implements memory leak prevention strategies based on real-world memory spike analysis. It provides automated memory monitoring, profiling, and safe defaults to prevent Claude CLI from exhausting system memory.

Features

• Automatic Memory Limits: Configurable memory caps with safe defaults
• Heap Profiling: Built-in profiling for memory allocation analysis
• Real-time Monitoring: Live memory usage tracking with alerts
• Crash Detection: Automatic detection of memory exhaustion events
• Profile Analysis: Tools to analyze heap profiles and identify leaks

Configuration

Default Memory Limits

# Safe default (reduced from 16GB)
export NODE_OPTIONS="--max-old-space-size=8192"

# For production environments
export CLAUDE_MEMORY_LIMIT="8GB"
export CLAUDE_MEMORY_PROFILE_DIR="/tmp/claude-memory-profiles"

Environment Variables

• CLAUDE_MEMORY_LIMIT: Memory limit in MB (default: 8192)
• CLAUDE_MEMORY_PROFILE_DIR: Directory for heap profiles (default: /tmp/claude-memory-profiles)
• CLAUDE_MEMORY_MONITORING: Enable/disable monitoring (default: true)
• CLAUDE_MEMORY_ALERT_THRESHOLD: Alert threshold in MB (default: 6144)

Usage

Start Claude with Memory Profiling

# Use the memory leak prevention script
./scripts/memory-leak-prevention.sh profile --limit 6144

# Or set environment manually
export NODE_OPTIONS="--max-old-space-size=6144 --inspect=0.0.0.0:9229 --heap-prof"
npx claude-flow-novice

Monitor Existing Process

./scripts/memory-leak-prevention.sh monitor --pid 12345 --duration 600

Install Debug Tools

./scripts/memory-leak-prevention.sh install-tools

Analyze Memory Profiles

./scripts/memory-leak-prevention.sh analyze --output ./profiles

Memory Leak Detection Patterns

High-Risk Indicators

• RSS memory > 8GB within 5 minutes of launch
• Multiple simultaneous TLS connections (>50)
• High number of open files (>1000)
• Large heap arenas (>1GB allocations)
• Bun Pool worker count > 20

Automatic Detection

The skill monitors for these patterns and triggers alerts:

# Check for memory spikes
if [[ $rss_mb -gt 8192 ]]; then
    log "⚠️  High memory usage detected: ${rss_mb}MB RSS"
    # Trigger profiling dump
    kill -USR2 $target_pid 2>/dev/null || true
fi

Integration with CFN Loop

Memory-Safe CFN Loop Execution

# Before starting CFN Loop
export NODE_OPTIONS="--max-old-space-size=4096"
export CLAUDE_MEMORY_MONITORING=true

# Execute with memory bounds
/cfn-loop-cli "task description" --mode=standard

Agent Memory Management

Agents spawned via CLI automatically inherit memory limits:

# Agent inherits parent process memory limits
npx claude-flow-novice agent-spawn \
  --agent-type backend-developer \
  --memory-limit 2048 \
  --enable-profiling

Debugging Tools

Heap Profile Analysis

// Analyze heap profile data
const fs = require('fs');
const profile = JSON.parse(fs.readFileSync('profile.heapprofile', 'utf8'));

// Find largest allocations
const allocations = profile.heapProfile.samples
  .sort((a, b) => b.size - a.size)
  .slice(0, 10);

allocations.forEach((alloc, i) => {
  console.log(`${i+1}. ${alloc.functionName}: ${(alloc.size/1024/1024).toFixed(2)}MB`);
});

Memory Usage Monitoring

# Real-time memory monitoring
watch -n 5 'ps aux | grep claude | grep -v grep'

# Network connection monitoring
netstat -an | grep ESTABLISHED | grep -c

# File descriptor monitoring
lsof -p <PID> | wc -l

Recovery Procedures

When Memory Leak Detected

1. Immediate Action: Kill the process to prevent system exhaustion

   bashCopy

   kill -9 <PID>
   

2. Save Diagnostic Data:

   bashCopy

   # Save memory map
   cat /proc/<PID>/smaps > memory-smaps.log
   
   # Save process info
   ps auxf > process-tree.log
   

3. Restart with Limits:

   bashCopy

   export NODE_OPTIONS="--max-old-space-size=4096"
   ./scripts/memory-leak-prevention.sh profile
   

Automatic Recovery

The skill includes automatic recovery mechanisms:

• Memory threshold monitoring
• Process termination on memory exhaustion
• Automatic profile generation on crashes
• Safe restart procedures

Performance Impact

Monitoring Overhead

• CPU: < 1% overhead for monitoring
• Memory: ~10MB additional for monitoring data
• I/O: Minimal logging impact

Profiling Overhead

• CPU: 10-15% overhead when profiling enabled
• Memory: ~50MB additional for profile data
• Startup: 2-3 second delay for profiler initialization

Best Practices

Development Environment

# Use profiling for development
export NODE_OPTIONS="--max-old-space-size=4096 --inspect --heap-prof"

Production Environment

# Use conservative limits
export NODE_OPTIONS="--max-old-space-size=6144"
export CLAUDE_MEMORY_MONITORING=false

WSL Specific

# WSL memory optimization
export NODE_OPTIONS="--max-old-space-size=4096"
echo 1 | sudo tee /proc/sys/vm/overcommit_memory  # Enable memory overcommit

Troubleshooting

Common Issues

1. High memory usage: Reduce memory limit, restart with profiling
2. Slow performance: Disable profiling in production
3. Connection issues: Check WSL memory limits
4. Profile corruption: Use larger memory limits for profiling

Debug Mode

# Enable verbose debugging
export CLAUDE_MEMORY_DEBUG=true
export CLAUDE_MEMORY_LOG_LEVEL=trace

./scripts/memory-leak-prevention.sh profile --debug

Integration Hooks

Pre-Execution Hook

#!/bin/bash
# .claude/hooks/cfn-pre-execution/memory-check.sh

./.claude/skills/cfn-memory-management/check-memory.sh
if [[ $? -ne 0 ]]; then
    echo "❌ Memory check failed. Please free memory before proceeding."
    exit 1
fi

Post-Execution Hook

#!/bin/bash
# .claude/hooks/cfn-post-execution/memory-cleanup.sh

./.claude/skills/cfn-memory-management/cleanup-memory.sh

Metrics and Monitoring

Key Metrics

• RSS memory usage
• Heap size and allocation patterns
• Number of open file descriptors
• Network connection count
• Process/thread count

Alert Thresholds

• Critical: RSS > 8GB or connections > 100
• Warning: RSS > 6GB or connections > 50
• Info: RSS > 4GB or connections > 25

Dependencies

• node >= 18.0.0
• strace (for system call tracing)
• perf (for performance profiling)
• lsof (for file descriptor monitoring)
• ps (for process monitoring)

Security Considerations

• Profiles may contain sensitive data - stored in /tmp with restricted permissions
• Debugging ports should not be exposed publicly
• Memory limits prevent DoS attacks
• All temporary files are automatically cleaned up

Version History

• v1.0.0: Initial implementation based on memory leak analysis
• v1.1.0: Added automatic recovery mechanisms
• v1.2.0: Integrated with CFN Loop orchestration
• v1.3.0: Added WSL-specific optimizations