H3 Reference Registry

MiniMax's H3 prompt grammar doesn't say "the second image you loaded". It says <Picture 2>, <Video 1>, <Audio 1> - labels, in an order the model was trained to read. H3 Reference Registry is the node that turns your canvas wiring into that order and then refuses to guess when your wiring is ambiguous.

It has no required inputs at all, which is the first thing to understand about it. It's a binder, not a loader: you wire media in, it emits one typed object that every downstream node reads.

How the binding actually works

Every socket on it is optional, and each one is a group:

• first_frame - one IMAGE. last_frame - one IMAGE.
• images - ordered IMAGE references, up to nine.
• videos - ordered VIDEO references, up to three.
• paired_audios - soundtracks that belong to a video, up to three.
• audios - standalone AUDIO references, up to three.

The registry assigns deterministic slot ids (first_frame_1, last_frame_1, image_1…, video_1, audio_pair_1, audio_1) and a connection order, in a fixed canonical sequence: frames first, then image references, then each video with its paired audio immediately before it, then standalone audio. Your order is preserved inside each group, which is exactly why connected order is the only thing you can't get wrong here - image three is <Picture 3> because you wired it third, not because it sorted differently somewhere downstream.

For paired audio the rule is arithmetic, not vibes: item N pairs only with video N and must sit before it in canonical order, and you can't have more paired soundtracks than videos. Wire two soundtracks with one video and the node tells you so (paired_audio_without_video) instead of silently dropping one.

Also worth knowing: the registry stores metadata-free slot assets. The actual media values never get serialized into the object that travels the wire - they stay on their own IMAGE/VIDEO/AUDIO connections. If you're coming from the "context bus" pattern where one wire carries everything (the KB's plumbing doc covers both the appeal and the stale-context trap), this is the conservative version of it: identity travels, pixels don't.

Where it plugs in

One output: reference_registry (H3_REFERENCE_REGISTRY). It fans out to the optional reference_registry input on H3 Context Plan, and to H3 Intent Graph Producer, H3 Cross Reference Producer, H3 Feasible AV Timeline and H3 Local Reconstruction. It's also how the bundled H3 Context Assistant - Reference subgraph routes refs.

The minimum reference route looks like this:

Reference Registry ──> Plan ──> Compiler ──> Validator ──> Preview
        (images)        ^
Request ────────────────┘

Note what the registry does not do: it doesn't judge modes. i2va/fl2va want a first and/or last frame, ref2va wants a reference set, and the "audio can't be the only reference" rule lives in the mode's asset validation downstream - in the plan/normalization path. The registry's job ends at roles and order.

Two behaviours that surprise people

First, this node declares INPUT_IS_LIST, so its sockets accept multiple items from a single connection - a batch of nine images wired in from one loader arrives as nine ordered references. That's the intended use, and it's also the source of the most common error you'll see: an empty connection contributes a missing item and the node fails with missing_reference_media, telling you to remove the empty wire rather than quietly renumbering everything after it. ambiguous_nested_reference_input is the sibling error - don't feed it a nested list.

Second, it never caches. The node returns float("NaN") from IS_CHANGED, which is the standard ComfyUI idiom for "always re-run" - a value not equal to itself, explained in the plumbing doc alongside the warning that such a node also drags everything behind it out of the cache. Here it's deliberate: the registry also captures a one-time, process-local receipt of the source media, and a cached registry would let a rerun lose that authority. Expect this branch to execute on every queue. That's not a bug you can tune away.

Install it

Not in the Comfy Registry yet as far as the README goes, so:

cd ComfyUI/custom_nodes
git clone https://github.com/rookiestar28/ComfyUI-MiniMaxH3-Studio.git

Restart ComfyUI and look under Add Node → h3_context → contracts. Zero Python dependencies, no model downloads, and building a registry needs no H3 weights - it's all bookkeeping. Keep the whole repo in place (root __init__.py plus comfyui_h3_context/); a half-copied folder is why people report the nodes missing.