HRM (Hierarchical Reasoning Model): A 27M-Parameter Recurrent Solver for Sudoku, Mazes and ARC

The problem HRM targets: reasoning without chain-of-thought supervision

The README frames its target directly: current large language models rely on Chain-of-Thought techniques, which the authors describe as suffering from brittle task decomposition, extensive data requirements, and high latency. HRM is the proposed alternative. It is a recurrent architecture that, in the authors' description, attains computational depth in a single forward pass without explicit supervision of the intermediate process, using only 1000 training samples and no pre-training or CoT data. The audience is therefore narrow and specific: researchers working on reasoning architectures who want a small, self-contained model they can train from scratch on a defined task family. The repository reflects that audience. It is a training harness with dataset builders for Sudoku, mazes and ARC, not a product with an inference API. If you came looking for a drop-in reasoner to put behind a chat interface, the shape of the codebase will tell you quickly that this is not it.

Two recurrent modules, one forward pass, and a halt condition

The architecture is described as two interdependent recurrent modules. A high-level module handles slow, abstract planning. A low-level module handles rapid, detailed computation. The two operate at different timescales and feed each other, which is where the brain-inspired framing in the repository topics comes from. Depth comes from recurrence rather than from stacking layers, which is why a 27 million parameter model can be compared against much larger models on ARC in the paper's results. The training configuration exposes the recurrence controls directly. In the full Sudoku-Hard command the README gives arch.L_cycles=8 and arch.halt_max_steps=8, so the number of reasoning cycles and the maximum halting steps are both configurable, along with arch.pos_encodings=learned and the loss choice arch.loss.loss_type=softmax_cross_entropy. That is the clearest evidence in the material of how the recurrence is bounded: a fixed cycle count with a halting cap, set through the config tree rather than hardcoded. The README does not walk through the module internals, the state update equations, or how the halting signal is trained. For those you have to go to the linked paper at arxiv.org/abs/2506.21734. Treat the repository as the implementation and the paper as the specification.

Installing HRM: CUDA 12.6, FlashAttention, and a hard GPU-generation split

The prerequisites section is explicit that the repo needs CUDA extensions to be built. The README supplies a CUDA 12.6 installer URL, a silent toolkit install, and an export CUDA_HOME=/usr/local/cuda-12.6, followed by a PyTorch install pinned to the cu126 index. It then installs packaging, ninja, wheel, setuptools and setuptools-scm as build dependencies. FlashAttention comes next, and here the instructions branch in a way worth reading carefully. For Hopper GPUs the README has you clone Dao-AILab/flash-attention, change into the hopper directory and run python setup.py install. For Ampere or earlier GPUs it is pip3 install flash-attn. Getting this wrong is the most likely first failure, because the two paths are not interchangeable. After that, pip install -r requirements.txt covers the Python dependencies, and wandb login is required because the project uses Weights & Biases for experiment tracking and metric visualization. There is no mention of a CPU path, a container image, or a pinned requirements lock. Budget time for the extension build; the README treats it as a prerequisite rather than a step the project handles for you.

Training and evaluation commands, from a laptop demo to an 8-GPU run

The quickest entry point is the Sudoku demo. You build the dataset with python dataset/build_sudoku_dataset.py --output-dir data/sudoku-extreme-1k-aug-1000 --subsample-size 1000 --num-aug 1000, then train with OMP_NUM_THREADS=8 python pretrain.py data_path=data/sudoku-extreme-1k-aug-1000 epochs=20000 eval_interval=2000 global_batch_size=384 lr=7e-5 puzzle_emb_lr=7e-5 weight_decay=1.0 puzzle_emb_weight_decay=1.0. The README states a runtime of roughly 10 hours on an RTX 4070 laptop GPU for that configuration. Note the two separate learning rates and weight decays, one for the model and one for the puzzle embedding. Full-scale runs switch to torchrun --nproc-per-node 8. ARC-1 is the bare command with no data_path override, because the default points at the ARC-1 build. ARC-2 adds data_path=data/arc-2-aug-1000. Sudoku Extreme and Maze 30x30 Hard use epochs=20000, eval_interval=2000, lr=1e-4 and puzzle_emb_lr=1e-4. Full Sudoku-Hard is different again: epochs=100, eval_interval=10, lr_min_ratio=0.1, global_batch_size=2304, lr=3e-4, weight_decay=0.1, plus the arch.* overrides already mentioned. Dataset preparation requires git submodule update --init --recursive first, and the ARC-2 builder takes --dataset-dirs dataset/raw-data/ARC-AGI-2/data with --output-dir data/arc-2-aug-1000. Evaluation for ARC-AGI runs through torchrun --nproc-per-node 8 evaluate.py checkpoint=<CHECKPOINT_PATH>, after which the README points you at arc_eval.ipynb to finalize and inspect results. For general runs it points at eval/exact_accuracy in W&B. There is also puzzle_visualizer.html, which you open in a browser and feed a generated dataset folder to inspect puzzles visually.

Where HRM breaks: overfitting, variance, and the tasks it does not cover

The Notes section is unusually candid and is the most useful part of the README for anyone deciding whether to adopt. Small-sample learning typically shows accuracy variance of around plus or minus 2 points, so a single run is not a reliable measurement and you should not read a two-point delta as a result. For Sudoku-Extreme on the 1000-example dataset, late-stage overfitting may cause numerical instability during training and in Q-learning, and the README advises early stopping once training accuracy approaches 100 percent. That is a real failure mode, not a footnote: a configuration that looks like it is converging can degrade. The broader limitation is scope. Every dataset builder in the repository produces grid puzzles: Sudoku, mazes, ARC. There is no text corpus loader, no tokenizer configuration, no instruction data path, and no serving or inference server described. The model is trained from scratch per task with no pre-training. If your reasoning problem is not expressible as a grid or an ARC-style transformation, the repository gives you nothing to start from, and the paper's claims about general-purpose reasoning do not translate into code you can point at your own data. The absence of any retrieved release also means there is no versioned artifact history to pin against; you are tracking main.

HRM versus a transformer trained with chain-of-thought

The obvious alternative is the thing HRM defines itself against: a transformer language model trained with CoT traces. The difference in approach is structural, not a matter of scale. A CoT model externalizes intermediate steps as tokens, so reasoning depth costs context length and latency, and the decomposition has to be learned from supervised traces. HRM keeps the intermediate computation inside the recurrent state, which is why the README can claim a single forward pass without supervision of the intermediate process and why the parameter count stays at 27 million. The trade is that you lose inspectability. With a CoT model you can read the reasoning trace; with HRM the cycles are internal and the only visible signal is the final answer, plus whatever the arch.L_cycles and halt settings imply about how much computation ran. A second alternative worth naming is a plain supervised model trained on the same puzzles without recurrence. HRM's own framing is that it reaches computational depth that a feed-forward stack of the same size would not, which is a claim you would want to reproduce on your own task before assuming it holds. Neither comparison is settled by the README, and the repository does not ship a baseline script for either.

Licence, checkpoints and the cost of keeping this running

HRM is released under Apache-2.0, which permits commercial use and modification subject to the licence terms, including its patent grant and notice requirements. This is a statement about the licence text, not legal advice; if you plan to ship something derived from it, read the licence and the notices in the repository yourself. The repository bundles no weights. Three checkpoints are listed on Hugging Face under sapientinc: HRM-checkpoint-ARC-2, HRM-checkpoint-sudoku-extreme and HRM-checkpoint-maze-30x30-hard. Using them means following the evaluation path, and for ARC that means the evaluate.py command plus arc_eval.ipynb. Maintenance cost is dominated by the environment. The build depends on a specific CUDA toolkit version, a matching PyTorch index, and a FlashAttention variant chosen by GPU generation, any of which can break on a driver or toolkit upgrade. Training cost is stated in wall-clock terms in the README: about 10 hours on an RTX 4070 laptop for the Sudoku demo, roughly 10 minutes for Sudoku Extreme on 8 GPUs, about 1 hour for Maze 30x30 Hard, about 2 hours for full Sudoku-Hard, and about 24 hours for ARC-1 and ARC-2, with the note that an ARC-2 checkpoint after 8 hours is often sufficient. There is no released version to upgrade between, so the practical maintenance question is whether you can rebuild the CUDA extensions when your stack moves.

Editorial conclusion

Adopt HRM if you are researching recurrent reasoning architectures on grid-structured tasks and can supply a CUDA 12.6 environment with FlashAttention plus, for full-scale runs, eight GPUs. Do not adopt it as a general text or agent reasoning model: the repository ships puzzle dataset builders, a pretrain.py loop and an evaluate.py path, with no serving stack and no language task support. Before committing, verify that your GPU generation matches the FlashAttention branch you install (hopper versus pip flash-attn), and confirm the checkpoint you intend to use exists on Hugging Face under sapientinc, since the README lists three and none are bundled in the repo.

Official sources

1. Issues
2. License: Apache-2.0
3. Project website
4. README
5. sapientinc/HRM on GitHub