HRM README

The project's README from github.com/sapientinc/HRM. As one markdown file: README.md.

Hierarchical Reasoning Model

Reasoning, the process of devising and executing complex goal-oriented action sequences, remains a critical challenge in AI. Current large language models (LLMs) primarily employ Chain-of-Thought (CoT) techniques, which suffer from brittle task decomposition, extensive data requirements, and high latency. Inspired by the hierarchical and multi-timescale processing in the human brain, we propose the Hierarchical Reasoning Model (HRM), a novel recurrent architecture that attains significant computational depth while maintaining both training stability and efficiency. HRM executes sequential reasoning tasks in a single forward pass without explicit supervision of the intermediate process, through two interdependent recurrent modules: a high-level module responsible for slow, abstract planning, and a low-level module handling rapid, detailed computations. With only 27 million parameters, HRM achieves exceptional performance on complex reasoning tasks using only 1000 training samples. The model operates without pre-training or CoT data, yet achieves nearly perfect performance on challenging tasks including complex Sudoku puzzles and optimal path finding in large mazes. Furthermore, HRM outperforms much larger models with significantly longer context windows on the Abstraction and Reasoning Corpus (ARC), a key benchmark for measuring artificial general intelligence capabilities. These results underscore HRM’s potential as a transformative advancement toward universal computation and general-purpose reasoning systems.

Read Our Paper: https://arxiv.org/abs/2506.21734

Join Our Discord Community: https://discord.gg/sapient

Quick Start Guide 🚀

Prerequisites ⚙️

Ensure PyTorch and CUDA are installed. The repo needs CUDA extensions to be built. If not present, run the following commands:

# Install CUDA 12.6
CUDA_URL=https://developer.download.nvidia.com/compute/cuda/12.6.3/local_installers/cuda_12.6.3_560.35.05_linux.run

wget -q --show-progress --progress=bar:force:noscroll -O cuda_installer.run $CUDA_URL
sudo sh cuda_installer.run --silent --toolkit --override

export CUDA_HOME=/usr/local/cuda-12.6

# Install PyTorch with CUDA 12.6
PYTORCH_INDEX_URL=https://download.pytorch.org/whl/cu126

pip3 install torch torchvision torchaudio --index-url $PYTORCH_INDEX_URL

# Additional packages for building extensions
pip3 install packaging ninja wheel setuptools setuptools-scm

Then install FlashAttention. For Hopper GPUs, install FlashAttention 3

git clone [email protected]:Dao-AILab/flash-attention.git
cd flash-attention/hopper
python setup.py install

For Ampere or earlier GPUs, install FlashAttention 2

pip3 install flash-attn

Install Python Dependencies 🐍

pip install -r requirements.txt

W&B Integration 📈

This project uses Weights & Biases for experiment tracking and metric visualization. Ensure you're logged in:

wandb login

Run Experiments

Quick Demo: Sudoku Solver 💻🗲

Train a master-level Sudoku AI capable of solving extremely difficult puzzles on a modern laptop GPU. 🧩

# Download and build Sudoku dataset
python dataset/build_sudoku_dataset.py --output-dir data/sudoku-extreme-1k-aug-1000  --subsample-size 1000 --num-aug 1000

# Start training (single GPU, smaller batch size)
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

Runtime: ~10 hours on a RTX 4070 laptop GPU

Trained Checkpoints 🚧

To use the checkpoints, see Evaluation section below.

Full-scale Experiments 🔵

Experiments below assume an 8-GPU setup.

Dataset Preparation

# Initialize submodules
git submodule update --init --recursive

# ARC-1
python dataset/build_arc_dataset.py  # ARC offical + ConceptARC, 960 examples
# ARC-2
python dataset/build_arc_dataset.py --dataset-dirs dataset/raw-data/ARC-AGI-2/data --output-dir data/arc-2-aug-1000  # ARC-2 official, 1120 examples

# Sudoku-Extreme
python dataset/build_sudoku_dataset.py  # Full version
python dataset/build_sudoku_dataset.py --output-dir data/sudoku-extreme-1k-aug-1000  --subsample-size 1000 --num-aug 1000  # 1000 examples

# Maze
python dataset/build_maze_dataset.py  # 1000 examples

Dataset Visualization

Explore the puzzles visually:

Launch experiments

Small-sample (1K)

ARC-1:

OMP_NUM_THREADS=8 torchrun --nproc-per-node 8 pretrain.py 

Runtime: ~24 hours

ARC-2:

OMP_NUM_THREADS=8 torchrun --nproc-per-node 8 pretrain.py data_path=data/arc-2-aug-1000

Runtime: ~24 hours (checkpoint after 8 hours is often sufficient)

Sudoku Extreme (1k):

OMP_NUM_THREADS=8 torchrun --nproc-per-node 8 pretrain.py data_path=data/sudoku-extreme-1k-aug-1000 epochs=20000 eval_interval=2000 lr=1e-4 puzzle_emb_lr=1e-4 weight_decay=1.0 puzzle_emb_weight_decay=1.0

Runtime: ~10 minutes

Maze 30x30 Hard (1k):

OMP_NUM_THREADS=8 torchrun --nproc-per-node 8 pretrain.py data_path=data/maze-30x30-hard-1k epochs=20000 eval_interval=2000 lr=1e-4 puzzle_emb_lr=1e-4 weight_decay=1.0 puzzle_emb_weight_decay=1.0

Runtime: ~1 hour

Full Sudoku-Hard

OMP_NUM_THREADS=8 torchrun --nproc-per-node 8 pretrain.py data_path=data/sudoku-hard-full epochs=100 eval_interval=10 lr_min_ratio=0.1 global_batch_size=2304 lr=3e-4 puzzle_emb_lr=3e-4 weight_decay=0.1 puzzle_emb_weight_decay=0.1 arch.loss.loss_type=softmax_cross_entropy arch.L_cycles=8 arch.halt_max_steps=8 arch.pos_encodings=learned

Runtime: ~2 hours

Evaluation

Evaluate your trained models:

OMP_NUM_THREADS=8 torchrun --nproc-per-node 8 evaluate.py checkpoint=<CHECKPOINT_PATH>

Notes

Citation 📜

@misc{wang2025hierarchicalreasoningmodel,
      title={Hierarchical Reasoning Model}, 
      author={Guan Wang and Jin Li and Yuhao Sun and Xing Chen and Changling Liu and Yue Wu and Meng Lu and Sen Song and Yasin Abbasi Yadkori},
      year={2025},
      eprint={2506.21734},
      archivePrefix={arXiv},
      primaryClass={cs.AI},
      url={https://arxiv.org/abs/2506.21734}, 
}

HRM (sapientinc/HRM)

Searching Database…

12.7K ·GitHub
Что это такое?Официальный релиз иерархической модели рассуждений (Hierarchical Reasoning Model, HRM): рекуррентной архитектуры, вдохновлённой устройством мозга, которая достигает значительной вычислительной глубины всего при 27 миллионах параметров и обучается примерно на 1000 примерах без предобучения и без данных в стиле chain-of-thought.
Это готовая обученная модель или код, который нужно обучать самому?И то, и другое. В репозитории лежит сама архитектура вместе с полным пайплайном обучения, а авторы также выкладывают обученные чекпоинты для ARC-AGI-2, судоку 9x9 Extreme и лабиринтов 30x30 Hard Maze — их можно оценить без какого-либо обучения.
Как его запустить?Сначала установите PyTorch с поддержкой CUDA, потому что репозиторий собирает CUDA-расширения; затем добавьте FlashAttention (версия 3 для GPU Hopper, версия 2 для Ampere и старше), установите Python-зависимости и войдите в Weights & Biases для отслеживания обучения.
Сколько длится обучение и какие есть подводные камни?На датасетах из 1 тысячи примеров судоку Extreme обучается примерно за 10 минут на референсной конфигурации из 8 GPU, лабиринт 30x30 — примерно за час, а ARC — примерно за 24 часа. Учтите разброс точности около ±2 пунктов на маленьких выборках, а на Sudoku-Extreme используйте раннюю остановку: на поздних этапах переобучение может дестабилизировать и само обучение, и Q-learning.
Какое железо нужно для обучения?Нужна GPU от NVIDIA — весь стек построен на PyTorch, CUDA-расширениях и FlashAttention. Демо с судоку обучается примерно за 10 часов на ноутбучной GPU RTX 4070, а полноразмерные эксперименты предполагают конфигурацию из 8 GPU.
Чем это отличается от того, как рассуждают большие языковые модели?Здесь вообще нет текстовых цепочек рассуждений (chain-of-thought): HRM выполняет последовательные рассуждения за один прямой проход через два взаимозависимых рекуррентных модуля — медленный высокоуровневый для абстрактного планирования и быстрый низкоуровневый для детальных вычислений — без какого-либо явного контроля промежуточных шагов.
Какие задачи он реально решает и насколько хорошо?Из коробки — три головоломных задачи: судоку 9x9 Extreme, лабиринты 30x30 Hard и Abstraction and Reasoning Corpus (ARC), где он превосходит куда более крупные модели с гораздо более длинными контекстными окнами; на судоку и лабиринтах результат почти идеальный.
Как проверить, насколько хороша обученная модель?Запустите скрипт оценки и смотрите метрику eval/exactaccuracy в Weights & Biases; для ARC есть дополнительные шаги, а финализировать и просмотреть результаты можно в прилагаемом ноутбуке arceval.ipynb.
Можно ли самому посмотреть на обучающие головоломки?Да — сгенерируйте датасет, откройте в браузере файл puzzlevisualizer.html и загрузите папку из data/, чтобы разглядывать головоломки наглядно.
Creator
sapientinc
Size
0.1 MB
Stars
12.7K
Updated
CommitMar 31
Age
1y
Commits · 90 Days