Checkpoints: файловые снапшоты и rollback

· 4 мин чтения · admin

Что такое checkpoints

Checkpoints — это автоматические снапшоты файловой системы, которые Hermes создаёт перед каждым инструментом, изменяющим файлы. Если что-то пошло не так, вы можете откатиться к любому предыдущему состоянию файлов с помощью команды /rollback.

Checkpoints превращают агента в безопасную среду для экспериментов: рефакторинг, генерация кода,批量 изменения — всё можно отменить одной командой.

Конфигурация

Checkpoints настраиваются в секции checkpoints файла config.yaml:

checkpoints:
  enabled: true          # включить/выключить (по умолчанию: false)
  max_snapshots: 50      # максимальное количество снапшотов (по умолчанию: 50)

Установить через CLI:

hermes config set checkpoints.enabled true
hermes config set checkpoints.max_snapshots 50

Включение checkpoints

Через конфиг

Глобальное включение для всех сессий:

hermes config set checkpoints.enabled true

Через флаг CLI

Включение только для конкретной сессии:

hermes chat --checkpoints

В текущей сессии

Checkpoints активируются при запуске сессии. Если не были включены заранее, нужно перезапустить сессию с флагом --checkpoints.

Slash-команды

/rollback [N]

Восстановить файлы из снапшота. Без аргумента — откат к последнему снапшоту. С числом — откат к снапшоту N сессий назад:

/rollback      # откат к последнему снапшоту
/rollback 1    # то же самое
/rollback 3    # откат на 3 снапшота назад

После восстановления агент покажет, какие файлы были изменены и какие вернулись к предыдущему состоянию.

Как работают checkpoints

  1. Автоматический снапшот — перед каждым tool call, который изменяет файлы (write_file, patch, terminal с записью), Hermes автоматически создаёт снапшот затронутых файлов.
  2. Дифф-снапшот — сохраняются только изменённые файлы, не вся файловая система. Это экономит место и ускоряет операции.
  3. Цепочка снапшотов — каждый снапшот ссылается на предыдущий, формируя цепочку состояний. Можно откатиться на несколько шагов назад.
  4. Лимит хранения — когда количество снапшотов превышает max_snapshots, самые старые автоматически удаляются.

Практические сценарии

Безопасный рефакторинг

hermes chat --checkpoints

# Просим агента провести рефакторинг
> Рефакторинг модуля auth: вынести middleware в отдельный файл

# Если результат не устраивает:
/rollback

# Пробуем другой подход:
> Рефакторинг модуля auth: использовать декораторы вместо middleware

Эксперименты с кодом

# Пробуем разные варианты реализации
> Попробуй использовать asyncio вместо threading в модуле worker

# Результат хуже? Откатываемся:
/rollback

> Попробуй multiprocessing вместо threading

Откат неудачных изменений

# Агент внёс изменения, которые сломали тесты
> Запусти тесты

# Тесты упали? Откатываемся:
/rollback

# Или на несколько шагов назад:
/rollback 2

Цепочка экспериментов

# Шаг 1: пробуем вариант A
> Перепиши парсер на regex
# Шаг 2: пробуем вариант B поверх A
> Добавь кэширование результатов парсинга
# Результат не нравится — откатываем оба шага:
/rollback 2
# Теперь мы вернулись к состоянию до шага 1

Где хранятся снапшоты

Снапшоты хранятся в директории профиля:

~/.hermes/profiles/<name>/checkpoints/
# или для глобального агента:
~/.hermes/checkpoints/

Каждый снапшот — это директория с копиями изменённых файлов и метаданными (timestamp, tool call info). Структура:

checkpoints/
├── 20260722_143052_a1b2c3/     # снапшот 1
│   ├── metadata.json           # timestamp, tool, описание
│   └── files/
│       ├── src/auth.py
│       └── config.yaml
├── 20260722_143105_d4e5f6/     # снапшот 2
│   ├── metadata.json
│   └── files/
│       └── src/auth.py
└── ...

Ограничения

  • Только файлы — checkpoints отслеживают изменения файлов. Операции с БД, сетевыми ресурсами, внешними API не захватываются.
  • Не покрывает terminal побочные эффекты — если terminal запускает команды с побочными эффектами (установка пакетов, миграции БД), откат файлов не отменит эти эффекты.
  • Размер хранилища — при max_snapshots: 50 и крупных проектах директория checkpoints может занимать значительное место. Регулируйте лимит под свои задачи.
  • Производительность — создание снапшотов adds небольшую задержку перед tool calls. Для проектов с тысячами файлов это может быть заметно.
  • Нет инкрементальных снапшотов — каждый снапшот хранит полную копию затронутых файлов (не дельты). Это упрощает восстановление, но требует больше места.
  • Откат только файлов — история чата, состояние агента и переменные окружения не откатываются. /rollback работает только с файловой системой.

Советы

  • Включайте --checkpoints при любых задачах, связанных с изменениями кода
  • Для одноразовых задач используйте флаг CLI; для постоянной работы — конфиг
  • Проверяйте размер директории checkpoints периодически: du -sh ~/.hermes/checkpoints/
  • При нехватке места уменьшите max_snapshots или очистите старые снапшоты