Контрольные точки

На этой странице Hermes Agent может автоматически создавать снимки вашего проекта перед деструктивными операциями и восстанавливать их одной командой. Контрольные точки являются опциональными начиная с v2 — большинство пользователей никогда не используют /rollback, а хранилище теневых копий со временем занимает немалый объём, поэтому по умолчанию функция отключена. Включите контрольные точки для сессии с помощью --checkpoints: [code] hermes chat --checkpoints

[/code] Или включите глобально в ~/.hermes/config.yaml: [code] checkpoints:
enabled: true

[/code] Эта страховка работает на основе внутреннего Менеджера контрольных точек, который хранит единый общий теневой git-репозиторий в ~/.hermes/checkpoints/store/ — ваш реальный .git проекта никогда не затрагивается. Все проекты, с которыми работает агент, используют одно и то же хранилище, поэтому объектная БД git с адресацией по содержимому дедуплицирует данные между проектами и между шагами.

Что вызывает создание контрольной точки​

Контрольные точки создаются автоматически перед: * Файловыми инструментами — write_file и patch * Деструктивными командами в терминале — rm, rmdir, cp, install, mv, sed -i, truncate, dd, shred, перенаправлением вывода (>) и git reset/clean/checkout

Агент создаёт не более одной контрольной точки на директорию за шаг, так что в длительных сессиях снимки не засоряют хранилище.

Краткая справка​

Команды внутри сессии (slash-команды): Команда| Описание
---|---
/rollback| Вывести список всех контрольных точек со статистикой изменений
/rollback <N>| Восстановить контрольную точку N (также отменяет последний шаг чата)
/rollback diff <N>| Показать различия между контрольной точкой N и текущим состоянием
/rollback <N> <file>| Восстановить один файл из контрольной точки N
CLI для просмотра и управления хранилищем вне сессии: Команда| Описание
---|---
hermes checkpoints| Показать общий размер, количество проектов, разбивку по проектам
hermes checkpoints status| То же, что и checkpoints без аргументов
hermes checkpoints list| Псевдоним для status
hermes checkpoints prune| Принудительная очистка: удаление осиротевших/устаревших данных, сборка мусора, соблюдение лимита размера
hermes checkpoints clear| Полная очистка базы контрольных точек (с запросом подтверждения)
hermes checkpoints clear-legacy| Удаление только архивов legacy-* от миграции с v1

Как работают контрольные точки​

На высоком уровне: * Hermes обнаруживает, когда инструменты собираются изменить файлы в вашем рабочем дереве. * Один раз за шаг беседы (на директорию) он: * Определяет разумный корень проекта для файла. * Инициализирует или переиспользует единое общее теневое хранилище в ~/.hermes/checkpoints/store/. * Индексирует в индекс проекта, строит дерево и создаёт коммит в ссылку проекта (refs/hermes/<project-hash>). * Эти ссылки проектов образуют историю контрольных точек, которую вы можете просматривать и восстанавливать через /rollback.

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

Настройка в ~/.hermes/config.yaml: [code] checkpoints:
enabled: false # главный выключатель (по умолчанию: false — опционально)
max_snapshots: 20 # максимум контрольных точек на проект (обеспечивается через перезапись ref + gc)
max_total_size_mb: 500 # жёсткий лимит общего размера хранилища; старейшие коммиты удаляются
max_file_size_mb: 10 # пропускать файлы больше этого размера

  # Автоматическое обслуживание (включено по умолчанию): очистка ~/.hermes/checkpoints/ при запуске  
  # и удаление записей проектов, чья рабочая директория больше не существует  
  # (осиротевшие) или чей last_touch старше retention_days. Выполняется не чаще  
  # одного раза за min_interval_hours, отслеживается через маркер .last_prune.  
  auto_prune: true  
  retention_days: 7  
  delete_orphans: true  
  min_interval_hours: 24

[/code] Чтобы отключить всё: [code] checkpoints:
enabled: false
auto_prune: false

[/code] Когда enabled: false, Менеджер контрольных точек ничего не делает и никогда не пытается выполнять git-операции. Когда auto_prune: false, хранилище растёт, пока вы вручную не выполните hermes checkpoints prune.

Просмотр контрольных точек​

Из CLI-сессии: [code] /rollback

[/code] Hermes отвечает отформатированным списком со статистикой изменений: [code] 📸 Checkpoints for /path/to/project:

  1. 4270a8c  2026-03-16 04:36  before patch  (1 file, +1/-0)  
  2. eaf4c1f  2026-03-16 04:35  before write_file  
  3. b3f9d2e  2026-03-16 04:34  before terminal: sed -i s/old/new/ config.py  (1 file, +1/-1)

  /rollback <N>             restore to checkpoint N  
  /rollback diff <N>        preview changes since checkpoint N  
  /rollback <N> <file>      restore a single file from checkpoint N

[/code]

Просмотр хранилища из командной строки​

[code] hermes checkpoints

[/code] Пример вывода: [code] Checkpoint base: /home/you/.hermes/checkpoints
Total size: 142.3 MB
store/ 138.1 MB
legacy-* 4.2 MB
Projects: 12

  WORKDIR                                                       COMMITS    LAST TOUCH  STATE  
  /home/you/code/hermes-agent                                        20       2h ago  live  
  /home/you/code/experiments/rl-runner                                8       1d ago  live  
  /home/you/code/old-prototype                                        3       9d ago  orphan  
  ...

Legacy archives (1):  
  legacy-20260506-050616                           4.2 MB

Clear with: hermes checkpoints clear-legacy

[/code] Принудительная полная очистка (игнорирует 24-часовой маркер идемпотентности): [code] hermes checkpoints prune --retention-days 3 --max-size-mb 200

[/code]

Просмотр изменений через /rollback diff​

Перед тем как решиться на восстановление, просмотрите, что изменилось с момента контрольной точки: [code] /rollback diff 1

[/code] Отображается сводка diff stat от git, а затем сам diff.

Восстановление через /rollback​

[code] /rollback 1

[/code] За кулисами Hermes: 1. Проверяет, существует ли целевой коммит в теневом хранилище. 2. Создаёт снимок перед восстановлением текущего состояния, чтобы вы могли позже «отменить отмену». 3. Восстанавливает отслеживаемые файлы в вашей рабочей директории. 4. Отменяет последний шаг беседы, чтобы контекст агента соответствовал восстановленному состоянию файловой системы.

Восстановление одного файла​

Восстановите только один файл из контрольной точки, не затрагивая остальную директорию: [code] /rollback 1 src/broken_file.py

[/code]

Защитные и производительные ограничения​

• Наличие git — если git не найден в PATH, контрольные точки прозрачно отключаются.
• Область директорий — Hermes пропускает слишком широкие директории (корень /, домашняя $HOME).
• Размер репозитория — директории с более чем 50 000 файлов пропускаются.
• Лимит на файл — файлы больше max_file_size_mb (по умолчанию 10 МБ) исключаются из снимка. Предотвращает случайное сохранение датасетов, весов моделей или сгенерированного медиа.
• Лимит общего размера хранилища — когда хранилище превышает max_total_size_mb (по умолчанию 500 МБ), старейший коммит каждого проекта удаляется по кругу, пока размер не вернётся под лимит.
• Настоящая чистка — max_snapshots обеспечивается перезаписью ссылки проекта и последующим запуском git gc --prune=now, чтобы свободные объекты не накапливались.
• Снимки без изменений — если с последнего снимка нет изменений, контрольная точка не создаётся.
• Нефатальные ошибки — все ошибки внутри Менеджера контрольных точек логируются на уровне debug; ваши инструменты продолжают работу.

Где хранятся контрольные точки​

[code] ~/.hermes/checkpoints/
├── store/ # единый общий bare git-репозиторий
│ ├── HEAD, objects/ # внутренности git (общие для всех проектов)
│ ├── refs/hermes/ # указатель ветки проекта
│ ├── indexes/ # git-индекс проекта
│ ├── projects/.json # workdir + created_at + last_touch
│ └── info/exclude
├── .last_prune # маркер идемпотентности автоочистки
└── legacy-/ # архивированные теневые репозитории до-v2 для каждого проекта

[/code] Каждый <hash> получен из абсолютного пути рабочей директории. Обычно вам никогда не нужно трогать их вручную — используйте hermes checkpoints status / prune / clear.

Миграция с v1​

До переработки в v2 каждая рабочая директория получала собственный полный теневой git-репозиторий прямо в ~/.hermes/checkpoints/<hash>/. Такая структура не могла дедуплицировать объекты между проектами и имела документированно неработающий очиститель — хранилище росло бесконечно. При первом запуске v2 все теневые репозитории до-v2 перемещаются в ~/.hermes/checkpoints/legacy-<timestamp>/, чтобы новая структура с единым хранилищем начинала с чистого листа. Старая история /rollback всё ещё доступна через ручной просмотр legacy-архива с помощью git; когда вы убедитесь, что она вам не нужна, выполните: [code] hermes checkpoints clear-legacy

[/code] чтобы освободить место. Legacy-архивы также удаляются автоматической очисткой (auto_prune) после retention_days.

Рекомендации​

• Включайте контрольные точки только когда они нужны — hermes chat --checkpoints или enabled: true в профиле.
• Используйте /rollback diff перед восстановлением — просмотрите, что изменится, чтобы выбрать правильную контрольную точку.
• Используйте /rollback вместо git reset, когда хотите отменить только изменения, сделанные агентом.
• Периодически проверяйте hermes checkpoints status, если регулярно пользуетесь контрольными точками — показывает, какие проекты активны и сколько места занимает хранилище.
• Комбинируйте с Git worktree для максимальной безопасности — держите каждую сессию Hermes в отдельном worktree/ветке, используя контрольные точки как дополнительный уровень защиты.

Информацию о запуске нескольких агентов параллельно в одном репозитории см. в руководстве по Git worktrees. * Что вызывает создание контрольной точки * Краткая справка * Как работают контрольные точки * Конфигурация * Просмотр контрольных точек * Просмотр хранилища из командной строки * Просмотр изменений через /rollback diff * Восстановление через /rollback * Восстановление одного файла * Защитные и производительные ограничения * Где хранятся контрольные точки * Миграция с v1 * Рекомендации