Checkpoints and /rollback

Hermes Agent는 destructive operation 전에 project snapshot을 자동으로 만들고, 한 명령으로 복원할 수 있습니다. v2 기준 checkpoints는 opt-in입니다. 대부분의 사용자는 /rollback을 쓰지 않고, shadow store는 시간이 지나면 저장공간을 꽤 사용할 수 있으므로 기본값은 off입니다.

session 단위로 checkpoints를 켜려면 --checkpoints를 붙입니다.

hermes chat --checkpoints

전역으로 켜려면 ~/.hermes/config.yaml에 설정합니다.

checkpoints:
  enabled: true

이 safety net은 내부 Checkpoint Manager가 제공합니다. Checkpoint Manager는 ~/.hermes/checkpoints/store/ 아래에 하나의 공유 shadow git repository를 유지합니다. 실제 project의 .git은 건드리지 않습니다. agent가 작업하는 모든 project가 같은 store를 공유하므로, git의 content-addressable object DB가 project와 turn을 넘나들며 object를 deduplicate합니다.

Checkpoint 생성 조건

다음 작업 전에 checkpoint가 자동 생성됩니다.

• File tools - write_file, patch
• Destructive terminal commands - rm, rmdir, cp, install, mv, sed -i, truncate, dd, shred, output redirect(>), git reset/clean/checkout

agent는 turn마다 directory당 최대 한 개의 checkpoint만 만듭니다. 긴 session에서도 snapshot이 과도하게 늘어나지 않습니다.

빠른 참조

session 안에서 사용하는 slash commands:

Command	Description
/rollback	모든 checkpoints를 change stats와 함께 나열
/rollback <N>	checkpoint N으로 복원. 마지막 chat turn도 함께 undo
/rollback diff <N>	checkpoint N과 현재 상태의 diff 미리보기
/rollback <N> <file>	checkpoint N에서 단일 file만 복원

session 밖에서 store를 점검하고 관리하는 CLI:

Command	Description
hermes checkpoints	전체 size, project count, project별 breakdown 표시
hermes checkpoints status	bare checkpoints와 동일
hermes checkpoints list	status alias
hermes checkpoints prune	강제 sweep: orphan/stale 삭제, GC, size cap 적용
hermes checkpoints clear	checkpoint base 전체 삭제. 먼저 확인을 요청
hermes checkpoints clear-legacy	v1 migration에서 남은 legacy-* archives만 삭제

Checkpoints 동작 방식

개념적으로는 다음 순서입니다.

• Hermes가 tool이 working tree의 file을 수정하려는 순간을 감지합니다.
• conversation turn마다 directory별로 한 번:
  • file에 맞는 project root를 결정합니다.
  • ~/.hermes/checkpoints/store/의 단일 공유 shadow store를 초기화하거나 재사용합니다.
  • project별 index에 stage하고 tree를 만든 뒤, project별 ref(refs/hermes/<project-hash>)에 commit합니다.
• 이 project별 ref들이 checkpoint history를 구성하며, /rollback으로 inspect/restore할 수 있습니다.

Configuration

~/.hermes/config.yaml에서 설정합니다.

checkpoints:
  enabled: false              # master switch (default: false, opt-in)
  max_snapshots: 20           # project별 최대 checkpoints(ref rewrite + gc로 적용)
  max_total_size_mb: 500      # 전체 store hard cap. 오래된 commit부터 제거
  max_file_size_mb: 10        # 이보다 큰 단일 file은 snapshot에서 제외

  # Auto-maintenance(기본 on): startup 때 ~/.hermes/checkpoints/를 sweep하고,
  # working directory가 더 이상 없거나(orphan), last_touch가 retention_days보다
  # 오래된 project entry를 삭제합니다. .last_prune marker를 통해
  # min_interval_hours마다 최대 한 번 실행됩니다.
  auto_prune: true
  retention_days: 7
  delete_orphans: true
  min_interval_hours: 24

전부 끄려면 다음처럼 설정합니다.

checkpoints:
  enabled: false
  auto_prune: false

enabled: false이면 Checkpoint Manager는 no-op이며 git operation을 시도하지 않습니다. auto_prune: false이면 hermes checkpoints prune을 수동으로 실행할 때까지 store가 계속 커집니다.

Checkpoints 목록 보기

CLI session에서:

/rollback

Hermes는 change statistics가 포함된 formatted list를 반환합니다.

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

Shell에서 store 점검

hermes checkpoints

예시 출력:

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

24시간 idempotency marker를 무시하고 full sweep을 강제하려면:

hermes checkpoints prune --retention-days 3 --max-size-mb 200

/rollback diff로 변경 미리보기

복원하기 전에 checkpoint 이후 무엇이 바뀌었는지 먼저 확인합니다.

/rollback diff 1

git diff stat summary와 실제 diff가 표시됩니다.

/rollback으로 복원

/rollback 1

내부적으로 Hermes는 다음을 수행합니다.

1. 대상 commit이 shadow store에 존재하는지 확인합니다.
2. 현재 상태의 pre-rollback snapshot을 만들어 나중에 "undo the undo"가 가능하게 합니다.
3. working directory의 tracked files를 복원합니다.
4. 마지막 conversation turn을 undo해서 agent context와 filesystem state가 맞도록 합니다.

단일 file 복원

directory 전체에 영향을 주지 않고 checkpoint에서 file 하나만 복원합니다.

/rollback 1 src/broken_file.py

Safety and performance guards

• Git availability - git이 PATH에 없으면 checkpoints는 조용히 disabled됩니다.
• Directory scope - Hermes는 너무 넓은 directory(root /, home $HOME)를 건너뜁니다.
• Repository size - file이 50,000개를 넘는 directory는 건너뜁니다.
• Per-file size cap - max_file_size_mb보다 큰 file(기본 10 MB)은 snapshot에서 제외됩니다. dataset, model weights, generated media를 실수로 넣는 일을 막습니다.
• Total store size cap - store가 max_total_size_mb(기본 500 MB)를 넘으면 project별 oldest commit을 round-robin으로 제거해 cap 아래로 내립니다.
• Real pruning - max_snapshots는 project별 ref를 rewrite하고 git gc --prune=now를 실행해 적용합니다. loose objects가 쌓이지 않게 합니다.
• No-change snapshots - 마지막 snapshot 이후 변경이 없으면 checkpoint를 건너뜁니다.
• Non-fatal errors - Checkpoint Manager 내부 오류는 debug level로 log되고, tools는 계속 실행됩니다.

Checkpoints 저장 위치

~/.hermes/checkpoints/
  store/                    # single shared bare git repo
    HEAD, objects/          # git internals (projects 간 공유)
    refs/hermes/<hash>      # project별 branch tip
    indexes/<hash>          # project별 git index
    projects/<hash>.json    # workdir + created_at + last_touch
    info/exclude
  .last_prune               # auto-prune idempotency marker
  legacy-<ts>/              # archived pre-v2 per-project shadow repos

각 <hash>는 working directory의 absolute path에서 파생됩니다. 일반적으로 이 파일들을 직접 만질 필요는 없습니다. hermes checkpoints status / prune / clear를 사용하세요.

v1에서 migration

v2 rewrite 전에는 각 working directory가 ~/.hermes/checkpoints/<hash>/ 아래에 자기 전용 shadow git repo를 가졌습니다. 이 layout은 project 간 object deduplication을 할 수 없었고, documented no-op pruner 때문에 store가 계속 커질 수 있었습니다.

v2가 처음 실행되면 pre-v2 shadow repos는 ~/.hermes/checkpoints/legacy-<timestamp>/로 이동되고, 새 single-store layout이 깨끗하게 시작됩니다. 예전 /rollback history는 legacy archive를 git으로 직접 inspect하면 여전히 접근할 수 있습니다. 더 필요 없다는 확신이 들면 다음으로 공간을 회수하세요.

hermes checkpoints clear-legacy

legacy archives도 retention_days 이후 auto_prune 대상이 됩니다.

Best practices

• 필요할 때만 checkpoints를 켜세요 - hermes chat --checkpoints 또는 profile별 enabled: true.
• 복원 전 /rollback diff를 사용하세요 - 어떤 checkpoint가 맞는지 먼저 확인합니다.
• agent-driven changes만 undo하고 싶다면 git reset 대신 /rollback을 사용하세요.
• checkpoints를 자주 쓴다면 hermes checkpoints status를 가끔 확인하세요 - active project와 store 비용을 보여줍니다.
• 최대 안전성을 위해 Git worktrees와 함께 쓰세요 - Hermes session마다 별도 worktree/branch를 두고 checkpoints를 추가 layer로 사용합니다.

같은 repo에서 여러 agent를 병렬 실행하려면 Git worktrees guide를 참고하세요.