Save H3 RefMod Bundle

What it's for

A RefMod in this pack is a saved reference: a compressed H3 latent standing in for a face, an outfit, a dance move, or a voice. The point is reuse: extract once, then drop the file into later workflows instead of re-encoding the same photos and audio every run. Character work mostly rerouted to instruction editing in 2026, but the instinct for a reusable character asset is the same one that built the LoRA and adapter stacks.

The catch is the default. The Master extractor saves with save_layout=separate_files, so a character with visuals and audio becomes hero_visual.safetensors plus hero_audio.safetensors. Two files, two loader slots, and the pairing lives in your head.

Save H3 RefMod Bundle collapses that into one version-5 container. Feed it a bundle of references that's in memory, give it a name, queue the workflow. It's a real output node - nothing needs wiring downstream - so it also works as "hand someone a character shoot". Two uses: retrofitting refs you already have as separate files, and repacking a loaded bundle.

How it works

Distinct reference objects are collected once - dedup is by object identity, so a mod echoed three times because a loader copies setting expanded it is written once - and each becomes a tensor member ref_0, ref_1, … The header carries a refmod_meta JSON blob: _format_version: 5, kind: bundle, your display name, and an ordered members array carrying each member's own metadata (kind, latent dims, mode, concept type, saved config). Members stay independent - nothing gets concatenated or fused.

Writes are atomic: staged in a temp file in the destination directory, then moved into place. The node also loads its own output straight back to build the return value, so a bad write surfaces now rather than next week. Zero members, or more than 256, and it refuses to write at all - an empty bundle errors rather than producing a useless file.

Inputs and outputs

Three inputs, and two of them are filenames.

• mods - the H3_REF_MODS bundle, from Load H3 RefMods, Load H3 RefMod Axis, Create H3 RefMod or the Master. If an extractor is upstream, set its own save=False so you don't save twice.
• name - defaults to character. This is the container's display name, not a rename: members keep the names they were extracted with, and two distinct mods that happen to share a name both land in the container. Slashes and backslashes become underscores; empty is an error.
• subfolder - optional, relative to the RefMod storage root. .., absolute paths, drive letters and the reserved graph_presets/.git/__pycache__ dirs are rejected.

Outputs are mods and saved_path - the path written. The mods output is the reloaded container: members now point at the new file, with your runtime strengths and repeated copies re-applied, so a downstream Fix H3 RefMod Config updates the container in place. The sibling Save H3 RefMods writes each member standalone instead; this is the one-file version.

Install

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

Restart ComfyUI, or install it through ComfyUI Manager by searching the pack title. Dependencies are light - torch, safetensors, numpy, Pillow, straight from requirements.txt. opencv-python/imageio are optional, and only the folder loader wants them. You need a current ComfyUI with native MiniMax H3 support; RefMod doesn't import the separate ComfyUI-MiniMaxH3 pack. The pack is at v0.2.6 and openly under construction - schemas shift between versions - and only Windows has actually been exercised.

One upstream caveat: H3's Community License territory excludes the US, EU, UK and South Korea, so users there aren't licensed to run the local weights. Not this node's problem, but it sits under everything here.

Where people get burned

The file stores content, not settings. Strengths, curve shapes and copies are runtime values; load the bundle later and the loader's current controls decide what happens. If you want settings to travel inside the file, route it through Fix H3 RefMod Config first - that writes config into the container's metadata instead of dropping a sidecar.

Selections get baked in when you repack. Load a bundle with components = Audio, save it, and you now have an audio-only container. The format doc says it plainly: repacking a loaded bundle flattens its selected members. Keep different voices in separate files if they need separate strengths.

No "you're about to overwrite the source" guard here. Save H3 RefMods refuses to overwrite a bundle it loaded from; this node doesn't. Point name and subfolder at the file you loaded and you'll replace it in place with whatever you had selected. Usually fine, occasionally how people lose an audio track.

Version-5 files need a bundle-aware reader. Old standalone RefMods and workflows keep working, but readers built against v0.2.5 or earlier aren't guaranteed to open the container. Handing files to someone on an old build? Export standalone with Save H3 RefMods instead.

And don't expect the container to do more than it claims: packing a face and a voice into one file does not bind the voice to the character, and there are no sync timestamps in there - just one file instead of two.