체크포인트에 대해 알아야 하는 이유

Hermes에게 코드의 큰 덩어리를 리팩터링해 달라고 요청했는데, 작업 중간에 새 방식이 완전히 엉망이라는 걸 깨달았다고 상상해 보세요. 체크포인트가 없다면 변경 사항을 수동으로 되돌리거나 git 히스토리를 뒤져야 하는 상황에 처하게 됩니다. 하지만 체크포인트가 있으면 그냥 /rollback을 입력하고 복원 지점을 선택하면 됩니다. 프로젝트를 위한 타임머신과도 같은 기능이죠.

가장 좋은 점은? 체크포인트는 완전히 선택적이라는 겁니다. v2에서는 기본적으로 꺼져 있어서, 사용하지 않는다면 존재 자체를 모르고 지나칠 수 있습니다. 하지만 필요할 때는 생명의 은인이 되어줍니다.

체크포인트 켜기

이 안전망을 활성화하는 방법은 두 가지가 있습니다:

세션별(이 채팅에서만):

hermes chat --checkpoints

전역 설정(모든 세션) — ~/.hermes/config.yaml을 편집하세요:

checkpoints:
  enabled: true

체크포인트는 언제 생성되나?

Hermes는 파괴적인 작업을 수행하기 전에 프로젝트의 스냅샷을 자동으로 생성합니다. 여기에는 다음이 포함됩니다:

파일 도구 — write_file 및 patch
위험한 터미널 명령어 — rm, rmdir, cp, mv, sed -i, truncate, dd, shred, 출력 리다이렉션(>), 그리고 git reset/clean/checkout

스팸을 방지하기 위해 Hermes는 턴당 디렉토리별로 최대 1개의 체크포인트만 생성합니다. 따라서 긴 세션에서도 수백 개의 스냅샷으로 디스크가 가득 차는 일은 없습니다.

숨겨진 마법

여기서 놀라운 부분이 나옵니다: Hermes는 ~/.hermes/checkpoints/store/에 저장된 단일 공유 섀도우 git 저장소를 사용합니다. 실제 프로젝트의 .git 폴더는 절대 건드리지 않습니다. 모든 프로젝트가 이 하나의 저장소를 공유하며, git의 콘텐츠 주소 지정 시스템이 프로젝트 간 파일 중복을 자동으로 제거합니다. 즉, 두 프로젝트에 비슷한 파일이 있어도 한 번만 저장됩니다.

세션 내에서 `/rollback` 사용하기

체크포인트가 켜져 있으면 채팅 중에 다음 슬래시 명령어를 사용할 수 있습니다:

명령어	기능
`/rollback`	변경 통계와 함께 모든 체크포인트 목록 표시
`/rollback <N>`	체크포인트 N으로 복원, 수동 편집 내용은 유지 (마지막 채팅 턴도 되돌림)
`/rollback <N> --all`	전체 복원 — 수동 편집 내용도 덮어씀
`/rollback diff <N>`	체크포인트 N과 현재 상태의 차이점 미리보기
`/rollback <N> <file>`	체크포인트 N에서 단일 파일만 복원

/rollback을 입력하면 다음과 같은 화면이 표시됩니다:

📸 /path/to/project 프로젝트의 체크포인트:

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

셸에서 저장소 관리하기

세션 밖에서도 체크포인트 저장소를 확인하고 정리할 수 있습니다:

hermes checkpoints              # 총 크기, 프로젝트 수, 세부 내역 표시
hermes checkpoints status       # 위와 동일
hermes checkpoints list         # status의 별칭
hermes checkpoints prune        # 강제 정리: 고아 항목 삭제, GC, 크기 제한 적용
hermes checkpoints clear        # 체크포인트 전체 삭제 (확인 메시지 표시)
hermes checkpoints clear-legacy # v1 마이그레이션 아카이브만 삭제

설정 조정하기

~/.hermes/config.yaml에서 모든 것을 제어할 수 있습니다:

checkpoints:
  enabled: false              # 마스터 스위치 (기본값: false)
  max_snapshots: 20           # 프로젝트당 최대 체크포인트 수
  max_total_size_mb: 500      # 전체 저장소 크기 상한
  max_file_size_mb: 10        # 이 크기보다 큰 파일은 건너뜀
  auto_prune: true            # 시작 시 오래된 항목 자동 정리
  retention_days: 7           # 이 기간 내에 접근된 항목만 유지
  min_interval_hours: 24      # 이 간격으로 최대 1회 정리

세심한 디테일 하나: 자동 정리는 고아 항목을 절대 삭제하지 않습니다 (작업 디렉토리가 더 이상 존재하지 않는 프로젝트). 디렉토리가 없다는 것은 외장 드라이브가 마운트 해제되었거나 VPN이 아직 연결되지 않았을 수도 있기 때문입니다. 고아 항목 정리는 확인 메시지를 표시하는 명시적인 hermes checkpoints prune 명령어로만 수행됩니다.

언제 활성화해야 할까?

실험적인 작업, 대규모 리팩터링, 또는 Hermes를 배우는 중이라면 체크포인트를 켜두세요. 저장 공간 오버헤드는 중복 제거 덕분에 크지 않고, 마음의 평화는 엄청납니다. 단순하고 안전한 작업만 한다면 꺼두고 디스크 공간을 아끼세요.

체크포인트는 평소에는 잊고 지내다가 — 절실히 필요해지는 순간이 오는 기능입니다. 그리고 그 순간이 왔을 때, 체크포인트가 있다는 사실에 감사하게 될 겁니다.