Hunyuan 3 RAM Diagnostic

Hunyuan 3 loves system RAM almost as much as VRAM. On a 24GB card running NF4, something like 20GB of the model's weights live in system RAM, and on 80GB cards they can be up there too. So when your machine starts swapping mid-run, you want to know why RAM is full - and the pack's answer is Hunyuan 3 RAM Diagnostic (class HunyuanRAMDiagnostic), a debug-only node that reports what's actually holding your memory.

It exists because RAM creep is a real, acknowledged problem with this pack. The README's known-limitations section says it plainly: RAM usage accumulates across successive loads, some references persist even after unload, and if you notice RAM creeping up, the definitive fix is restarting ComfyUI. This node is the diagnostic half of that story - it tells you whether you're looking at a leak, and ideally where it's coming from, instead of guessing.

How it works

Two boolean inputs, both about how hard to dig:

• trace_referrers (default False) - uses gc.get_referrers() to trace why the largest live modules are still alive. The tooltip warns it's slow, but it's what reveals the leak source. Turn this on when you've confirmed RAM is climbing and you want to know which objects are pinning weights in memory.
• compact_windows_heap (default True) - after reporting, calls Windows APIs to hand freed memory back to the OS. The tooltip is careful about expectations: this only affects the reported RSS, not actual leaks. On Windows this addresses the known pinned-buffer / heap fragmentation behavior the README mentions with INT8 block swap.

Output is a single report (STRING) with the memory breakdown. It's an output node - drop it in, queue, read the string.

How to install it

Part of the Comfy_HunyuanImage3 pack:

cd ComfyUI/custom_nodes
git clone https://github.com/EricRollei/Comfy_HunyuanImage3
cd Comfy_HunyuanImage3
pip install -r requirements.txt

Restart ComfyUI and hard-refresh the browser. Or search HunyuanImage in ComfyUI Manager.

Common issues & troubleshooting

RSS keeps climbing and the diagnostic shows it. That's the known Instruct-load leak the README flags. The honest fix: restart ComfyUI between long sessions. The diagnostic will show you the pattern, but no node in this pack fully solves the accumulation - it's a documented limitation, not a surprise.

You're on Windows with INT8 block swap and RAM grows slowly over many generations. That's the tradeoff the README documents for skipping pinned buffers on WDDM. compact_windows_heap helps the reported numbers look sane, but the underlying fragmentation is a Windows-specific cost of the INT8 block-swap path - if it bothers you, run INT8 with blocks_to_swap=0 on a 96GB card where the model fits anyway.

Comparing apples to oranges. RAM Diagnostic measures process RSS - it won't show you what other tabs or apps hold. For the VRAM side of the same story, pair it with Hunyuan 3 GPU Info. Between the two you get the full "where did my memory go" picture.