RefMod Loader Stack ( MiniMax H3 RefMods )

MiniMax H3 shipped open weights in August 2026 with native audio and day-zero ComfyUI support. What it didn't ship with is a sane way to feed it references - a face, a costume, a voice clip - and keep several alive at once. That's RefMods, and that's this node.

What a RefMod actually is

A RefMod is an H3 reference saved as a reusable .safetensors. You push an image, video or audio clip through H3's VAE once, the pack stores the latent plus metadata, and later workflows load the reference without re-encoding the source. Stack a few and the sampler is conditioned on several references at once.

One thing to get straight early: there is no training here. The extraction mode named training pools a latent to a smaller grid and refines it against the original - no DiT, no text instruction, no identity recognizer. It's compression, and compression loses detail. File RefMods under encode-and-inject character consistency rather than 2026's "edit a good frame" default. The win is that H3 makes multi-reference injection cheap, and juggling several references used to be the awkward part.

What this node does, mechanically

It's a skin, and knowing that saves you an hour. At run time H3_refmod_loader looks up MiniMaxH3RefModsLoader - the "Load H3 RefMods" node from Luisacaotica/ComfyUI-MiniMaxH3Mod - through ComfyUI's global NODE_CLASS_MAPPINGS registry, then calls its public .load(). Your canvas rows become that node's mod_1..mod_8, strength_1..8, copies_1..8 keyword arguments. Folder scanning, safetensors loading, the file cache, token budgeting and the H3_REF_MODS bundle format all stay upstream. Even IS_CHANGED is delegated.

That's why it never drifts from upstream behavior - and why the failure mode is quiet. With the upstream pack missing, this node doesn't error. It logs MiniMaxH3RefModsLoader not found - install ComfyUI-MiniMaxH3Mod and returns an empty bundle. Your graph runs, you get zero reference influence, and the canvas tells you nothing.

Inputs and outputs

• show_info (boolean, default off) - prints each loaded mod's tokens, layout, source and pool to the console. Useful while tuning, spam otherwise.
• stack_data - your rows actually live here. The node draws a DOM UI over the widget and hides it, but it's a plain JSON array in the node's properties, which is why the stack survives a save and why duplicating the node duplicates the stack.
• max_total_tokens (int, default 0) - 0 disables the budget. A positive value rejects bundles exceeding it after copies are counted, and fails the queue rather than quietly trimming.

Each row gets an enable toggle, a searchable mod picker, a strength and a copies count. Strength runs 0–1, where 1.0 is a full reference; the upstream tooltip is worth repeating because it's unusual - lowering it blurs the reference toward a softened copy of itself, so identity fades plausibly instead of turning into noise. A row at strength 0 is skipped, as are disabled and empty rows, and anything past the eighth logs extra enabled row(s) ignored. Copies repeats the block 1–10 times; two or three is the useful range, since each copy pays its full token cost in every DiT block.

Two outputs. mods (H3_REF_MODS) goes into Apply H3 RefMod, into H3 RefMod Text Encode for numbered <Picture 1> / <Video 1> labels in the prompt, or into Inspect H3 RefMod to see what you actually loaded. prompt_hint (STRING) is a prompt-ready string built from each loaded mod's concept type and description, e.g. identity: ginger woman, tattooed neck; pose_motion: slow twirl into camera - concat it ahead of your text encode instead of retyping descriptions. Mods saved without a description contribute nothing, so a blank hint means your mods are undocumented, not broken.

Install

cd ComfyUI/custom_nodes
git clone https://github.com/PlagueKind/ComfyUI-PlagueKind-Nodes.git
git clone https://github.com/Luisacaotica/ComfyUI-MiniMaxH3Mod.git

Restart ComfyUI. The second clone isn't optional - skip it and every run silently produces empty bundles. The PlagueKind pack needs nothing beyond what ComfyUI ships (torch, comfy.utils, comfy.lora) and is on ComfyUI Manager; upstream pulls its own safetensors / numpy / Pillow requirements. You also need current ComfyUI with native H3 support and an H3 video VAE.

Mods live in the first registered refmods folder (falling back to ComfyUI/models/refmods/), and extra_model_paths.yaml mappings are honored. Upstream ships mods/vanellope_example.safetensors as a smoke test: if that name appears in the dropdown, your wiring is right.

Where people get burned

You saved a mod and the dropdown doesn't show it. The list is cached until a file's stat changes. Click the node's refresh button - it calls the pack's /plaguekind/h3_refmod_loader/refresh route - or use "Refresh node definitions". A server restart also works, just slower.

You want different strengths for a bundled visual+audio mod. Not possible here. The rows forward one strength and a copies count, while upstream's loader also exposes All / Visual / Audio plus per-modality strength per slot. If one .safetensors holds both modalities and you want the voice quieter than the face, use the upstream node.

The token bill creeps up on you. Visual cost is roughly T × (H/2) × (W/2) - a 1024×1024 image encoding to a 64×64 latent grid is about 1024 tokens per frame; audio is 2 × T. Four references at strength 1.0 is thousands of tokens added to every attention call. Set max_total_tokens to something you'll actually pay and let it error.

Upstream is a moving target. Its README calls the pack under construction, with schemas that shift between versions. Because this wrapper calls .load() by fixed keyword names, a renamed upstream input raises, gets caught, and returns an empty bundle with a load() failed line. Read the console, not the canvas.

RefMods mix attributes, and voice transfer doesn't work. Identity, clothing, background and composition bleed into each other, and upstream's own testing reports speaker-identity transfer failing. This gets several references into H3 - it isn't a character-training replacement or a voice cloner.