KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#dsh #dsh-plugin #developer-tools #ai-agent #claude-code #codex #typescript #ai-agents #deepseek-harness #mcp #cli #rust

ComfyUI-MemoryCleaner

★ 31 Open GitHub ↗

No description available.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# ComfyUI-MemoryCleaner Usage Guide

**Author**: eddy  
**Project**: ComfyUI-MemoryCleaner

## Quick Start

### For ComfyUI Node

1. Add "Memory Cleaner (Force)" node to your workflow
2. Place it **after** heavy operations (model loading, generation, VAE decode)
3. Connect your data flow through it
4. Run workflow

**Recommended settings for heavy workloads**:
```
aggressive_trim: ✓ True
enable_privileges: ✓ True
external_helper: ✓ True
skip_trim_if_c_low: ✓ True
min_c_free_gb: 60.0
purge_standby: ✗ False (unless running as admin)
```

### For Standalone Scripts

**Check memory**:
```bash
python cleanup_ram.py --check
```

**Clean memory**:
```bash
python cleanup_ram.py
```

**Trim specific process** (e.g., ComfyUI):
```bash
# Auto-detect
python ram_trim_target.py --auto

# Or target PID
python ram_trim_target.py --pid 12345
```

## Understanding the Cleanup Process

### What Happens During Cleanup?

1. **Model Unloading** (0/7):
   - Unloads models from VRAM to system RAM
   - Clears model cache
   - Cleans up model patches
   - Requests aggressive memory free from ComfyUI

2. **Python GC** (1-3/7):
   - Collects unreferenced Python objects
   - Frees Python heap memory
   - Runs 3 passes for thorough cleanup

3. **PyTorch Cache** (4/7):
   - Empties CUDA cache
   - Collects IPC memory
   - Resets memory statistics

4. **OS-Level Trimming** (5/7) - **THE KEY STEP**:
   - Checks C: drive free space
   - Enables Windows privileges if possible
   - Calls `EmptyWorkingSet` - forces pages to disk
   - Calls `SetProcessWorkingSetSize(-1, -1)` - shrinks working set
   - If fails, uses external helper script for cross-process cleanup
   - **This is what frees 30-45GB**

5. **CUDA Sync** (6/7):
   - Synchronizes all GPU operations
   - Ensures cleanup is complete

6. **Final GC** (7/7):
   - One last pass to catch anything missed

7. **Optional Standby Purge**:
   - Clears Windows standby lists
   - Requires administrator privileges

## Common Scenarios

### Scenario 1: Heavy Model Workflow (SDXL, Flux, WanVideo)

**Problem**: Loading large models fills RAM to 50-60GB, subsequent operations OOM.

**Solution**:
```
Load Model A → Generate → Memory Cleaner → Load Model B → Generate
                          [Free 40GB]
```

**Settings**:
- `aggressive_trim=True`
- `external_helper=True`
- `min_c_free_gb=60` (ensure C: has space for pagefile)

**Expected**: 30-45GB freed after each cleanup.

### Scenario 2: Batch Processing Loop

**Problem**: Each batch iteration accumulates memory, crashes after 5-10 iterations.

**Solution**:
```
Loop Start → Process Batch → Memory Cleaner → Loop End
                             [Clean each iteration]
```

**Settings**:
- `aggressive_trim=True`
- `skip_trim_if_c_low=True` (safety)

**Expected**: Stable memory across hundreds of iterations.

### Scenario 3: Low C: Drive Space

**Problem**: C: drive has <30GB free, cleanup causes disk full error.

**Solution 1** (Recommended): Move pagefile to D/E drive
- System Properties → Advanced → Performance → Virtual Memory
- Set C: to small fixed size (2-4GB)
- Set D: to system-managed or large fixed size

**Solution 2**: Disable OS trim
```
aggressive_trim=False
```

**Settings**:
- `skip_trim_if_c_low=True`
- `min_c_free_gb=100` (high threshold)

**Note**: Without OS trim, cleanup effect is limited (1-2GB vs 30-45GB).

### Scenario 4: Running as Non-Admin

**Problem**: `EmptyWorkingSet: ✗ FAILED (err 6)`, privileges not available.

**Solution**: External helper automatically activates!

**What happens**:
1. Process-internal WinAPI calls fail
2. Node detects failure (returns None)
3. Spawns `ram_trim_target.py --pid <current>` as external process
4. External process has better privilege context
5. Successfully frees 30-45GB

**No action needed**: Fallback is automatic.

## Parameter Reference

### aggressive_trim (BOOLEAN, default=True)

**Enable**: Full OS-level memory trimming with WinAPI calls  
**Disable**: Only Python GC + CUDA cleanup (1-2GB effect)

**When to disable**:
- C: drive critically low (<20GB free)
- Running on non-Windows OS (Linux/macOS don't support WinAPI)
- Debugging workflows (faster iteration)

### enable_privileges (BOOLEAN, default=True)

**Enable**: Try to enable `SeIncreaseQuotaPrivilege` and `SeDebugPrivilege`  
**Disable**: Skip privilege elevation

**Note**: Even if fails, external helper provides fallback.

### external_helper (BOOLEAN, default=True)

**Enable**: Use `ram_trim_target.py` for cross-process cleanup (recommended)  
**Disable**: Only use process-internal WinAPI calls

**Why enable**:
- Higher success rate (95%+ vs 50%)
- Better privilege context
- Proven 39.51GB cleanup in testing

### skip_trim_if_c_low (BOOLEAN, default=True)

**Enable**: Check C: free space before trimming (safety)  
**Disable**: Always trim regardless of disk space (DANGEROUS)

**Critical**: Keep enabled unless you know pagefile is on another drive.

### min_c_free_gb (FLOAT, default=20.0)

**Default 20GB**: Basic safety margin  
**Recommended 60GB**: Safe for heavy workloads  
**100GB+**: Ultra-safe for production

**Calculation**:
- OS trim moves memory to `pagefile.sys`
- If trimming 40GB, pagefile grows by ~40GB
- Set threshold = expected trim amount + 20GB buffer

### purge_standby (BOOLEAN, default=False)

**Enable**: Purge Windows standby memory lists  
**Disable**: Skip standby purge

**Requirements**:
- Administrator privileges
- Windows only

**Effect**:
- Frees standby/modified page lists
- Minimal impact on pagefile (unlike OS trim)
- FlushModifiedList: 0 (success)
- PurgeStandbyList: -1073741727 (needs admin)

## Monitoring Effectiveness

### Check Logs for These Indicators

**Good cleanup (30-45GB)**:
```
[5/7] C-level aggressive cleanup...
      Working Set Before: 50.350 GB
      Using external helper to trim working set...
      ✓ External helper freed 42.120 GB

💾 CLEANUP RESULTS:
  Process RAM freed: 42.100 GB
```

**Limited cleanup (1-2GB)**:
```
[5/7] Skipping OS trim: C:\ free 15.2 GB < 60.0 GB (avoid pagefile growth)

💾 CLEANUP RESULTS:
  Process RAM freed: 1.234 GB
```

**Failed then recovered**:
```
[5/7] C-level aggressive cleanup...
      EmptyWorkingSet: ✗ FAILED (err 6)
      SetProcessWorkingSetSize: ✗ FAILED (err 6)
      Using external helper to trim working set...
      ✓ External helper freed 39.510 GB
```

### System-Level Verification

**Before cleanup**:
```bash
python cleanup_ram.py --check
# Shows: 50-60GB used, <10GB available
```

**After cleanup**:
```bash
python cleanup_ram.py --check
# Shows: 10-20GB used, 40-50GB available
```

## Troubleshooting

### "C: drive keeps filling up"

**Symptom**: After cleanup, C: drive loses 30-40GB space.

**Root cause**: OS trim moves memory to `pagefile.sys` on C:.

**Solutions**:
1. Increase `min_c_free_gb` to 60-100
2. Move pagefile to D/E drive (recommended)
3. Disable `aggressive_trim` temporarily

### "No memory freed"

**Symptom**: "Process RAM freed: 0.000 GB" or negative values.

**Possible causes**:
1. **C: drive guard active**: Check logs for "Skipping OS trim"
   - Solution: Free up C: drive or move pagefile
2. **Privileges failed**: Check "Privileges: ... = NO"
   - Solution: Should auto-fallback to external helper
3. **Memory actively in use**: Models still loaded
   - Solution: Ensure models are unloaded before cleanup node

### "External helper not available"

**Symptom**: "External helper not available or failed."

**Causes**:
1. `ram_trim_target.py` missing
   - Solution: Reinstall or check file exists
2. Python interpreter not found
   - Solution: Check `sys.executable` path
3. Timeout (>60s)
   - Solution: System too slow, increase timeout in code

### "Privileges always = NO"

**Symptom**: "Privileges: SeIncreaseQuotaPrivilege=NO, SeDebugPrivilege=NO"

**Impact**: Process-internal WinAPI calls may fail (err 6).

**Mitigation**: External helper provides automatic fallback.

**Optional**: Run ComfyUI as administrator for better privileges.

## Best Practices

### ✅ DO

1. **Place at workflow end**: After all operations complete
2. **Monitor C: drive**: Keep 50-100GB free
3. **Enable external helper**: Best success rate
4. **Set high min_c_free_gb**: 60GB+ for heavy workloads
5. **Check logs**: Verify "freed" values are substantial
6. **Use in loops**: Clean each iteration to prevent accumulation

### ❌ DON'T

1. **Don't clean after every node**: Overhead adds up
2. **Don't disable safety guards**: `skip_trim_if_c_low` protects you
3. **Don't ignore C: drive warnings**: Pagefile can fill disk
4. **Don't set min_c_free_gb too low**: <20GB risks disk full
5. **Don't enable purge_standby without admin**: Will fail silently
6. **Don't expect miracles on Linux/macOS**: WinAPI only works on Windows

## Performance Metrics

### Typical Results (Windows, Heavy Workflow)

| Metric | Before | After | Improvement |
|--------|--------|-------|-------------|
| Process RAM | 50.3 GB | 8.2 GB | **-42.1 GB** |
| System RAM | 60.1 GB | 18.3 GB | **-41.8 GB** |
| VRAM | 28.5 GB | 0.08 GB | **-28.4 GB** |
| C: Free | 45 GB | 45 GB | No change (good) |
| Time | - | 2.3s | Fast |

### Lightweight Results (No OS Trim)

| Metric | Before | After | Improvement |
|--------|--------|-------|-------------|
| Process RAM | 10.5 GB | 9.2 GB | -1.3 GB |
| VRAM | 8.5 GB | 0.5 GB | -8.0 GB |
| Time | - | 0.5s | Very fast |

## Advanced: Direct Script Usage

### cleanup_ram.py

```python
# Check only
python cleanup_ram.py --check

# Output:
# Process RAM: 50.35 GB
# System RAM: 60.12 / 63.85 GB (94.2%)
# TOP 10 MEMORY-CONSUMING PROCESSES:
#   1. python.exe    50.35 GB (PID: 12345)
#   ...
```

### ram_trim_target.py

```python
# Auto-detect ComfyUI
python ram_trim_target.py --auto

# Output:
# Target PID: 12345  Name: python.exe
# Steps:
#   open            : ok
#   EmptyWorkingSet : ok
#   SetPWS          : ok
# WorkingSet Before: 50.35 GB
# WorkingSet After : 8.23 GB
# Freed            : 42.12 GB
```

### purge_standby.py (Admin Required)

```python
# Run as administrator
python purge_standby.py

# Output:
# FlushModifiedList           : OK (status 0x00000000)
# PurgeLowPriorityStandbyList : OK (status 0x00000000)
# PurgeStandbyList            : OK (status 0x00000000)
```

## Getting Help

**Issues**: Report on GitHub with logs and system info  
**Questions**: Include ComfyUI version, OS, memory specs  
**Logs**: Copy full cleanup output from console

---

**Author**: eddy  
**Repository**: ComfyUI-MemoryCleaner  
**License**: Apache License 2.0

ComfyUI-MemoryCleaner

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README