체크포인트 및 /rollback

Hermes Agent는 이전에 프로젝트를 자동으로 스냅할 수 있습니다.destructive operation 은 단일 명령으로 복원합니다. Checkpoints는opt-in as of v2 — most users never use /rollback, 그리고 shadow-store storage are non-trivial over time, 그래서 기본값은 꺼집니다.

--checkpoints에 대한 제한적 인 체크 포인트:

hermes chat --checkpoints

또는 ~/.hermes/config.yaml에서 글로벌 활성화:

checkpoints:
  enabled: true

이 안전망은 ~/.hermes/checkpoints/store/의 단일 공유 그림자 저장소를 유지하는 내부 ** 체크인 관리자**에 의해 구동됩니다. 실제 프로젝트 .git는 결코 만지지 않습니다. 모든 프로젝트 에이전트는 동일한 저장소를 공유, 그래서 git's content-addressable object DB deduplicates 프로젝트 전반에 걸쳐 및 회전.

어떤 트리거 검사점

체크포인트는 자동적으로 촬영됩니다:

• 파일 도구 - write_file 및 patch
• 파괴적인 터미널 명령 - rm, rmdir, cp, install, mv, sed -i, truncate, dd, ..., ..., ...

이 에이전트는 턴당 디렉토리당 가장 하나의 체크포인트를 만듭니다**, 그래서 긴 실행 세션은 스팸 스냅샷을 하지 않습니다.

빠른 참고

소유 슬래시 명령:

설명	설명
/rollback	모든 체크포인트를 변경할 수 있습니다
/rollback <N>	체크포인트 N 복원 (또한 마지막 채팅 차례)
/rollback diff <N>	체크포인트 사이의 미리보기 디퓨프 N와 현재 국가
/rollback <N> <file>	checkpoint N의 단일 파일 복원

세션 밖에서 매장을 검사하고 관리하기 위한 CLI:

설명	설명
hermes checkpoints	총 크기, 프로젝트 수, per-project 고장 표시
hermes checkpoints status	베어와 동일 checkpoints
hermes checkpoints list	status에 대한 별명
hermes checkpoints prune	스포트: 삭제 orphans/stale, GC, 강제 크기 캡
hermes checkpoints clear	전체 체크 포인트베이스를 Nuke (첫 번째로 작업)
hermes checkpoints clear-legacy	legacy-* 아카이브만 v1 마이그레이션

자주 묻는 질문

높은 수준에서:

• Hermes는 도구가에 대해 파일 생성 작업 트리에.
• 대화 턴 당 한 번 ( 디렉토리당), 그것은:
  • 파일에 대한 합리적인 프로젝트 루트를 해결합니다.
  • ~/.hermes/checkpoints/store/에서 ** 단일 공유 그림자 저장소를 초기 또는 재사용합니다.
  • 프로젝트 인덱스로 단계, 나무를 짓고, per-project ref (refs/hermes/<project-hash>)에 커밋합니다.
• 이 per-project refs는 ...입니다.

제품 설명

~/.hermes/config.yaml의 구성:

checkpoints:
  enabled: false              # master switch (default: false — opt-in)
  max_snapshots: 20           # max checkpoints per project (enforced via ref rewrite + gc)
  max_total_size_mb: 500      # hard cap on total store size; oldest commits dropped
  max_file_size_mb: 10        # skip any single file larger than this

  # Auto-maintenance (on by default): sweep ~/.hermes/checkpoints/ at startup
  # and delete project entries whose working directory no longer exists
  # (orphans) or whose last_touch is older than retention_days. Runs at most
  # once per min_interval_hours, tracked via a.last_prune marker.
  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 작업을 시도하지 않습니다. `auto_prune: false`일 때, 상점은 `hermes checkpoints prune`를 수동으로 실행할 때까지 성장합니다.

## 목록 체크포인트 \{#listing-checkpoints}

CLI 세션에서:

/rollback

Hermes는 변화 통계를 보여주는 형식화된 목록과 응답합니다:

```text
📸 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에서 상점 검사

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

가득 차있는 청소를 강제하십시오 (24h idempotency 감적을 특색짓습니다):

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

/rollback diff로 미리보기 변경

복원하기 전에, 체크 포인트 이후 변경 된 것을 미리보기:

/rollback diff 1

이 git diff stat 요약은 실제 diff에 의해 따랐습니다.

/rollback로 복원

/rollback 1

무대 뒤에서, Hermes:

1. 대상 커밋이 그림자 저장소에 존재합니다.
2. 현재 상태의pre-rollback snapshot를 가져와 나중에 "undo the undo"를 할 수 있습니다.
3. 작업 디렉토리에 트랙 된 파일을 복원합니다.
4. **마지막 대화 턴 ** 그래서 에이전트의 컨텍스트는 복원 된 파일 시스템 상태를 일치.

단일 파일 복원

디렉토리의 나머지에 영향을 미치지 않고 체크포인트에서 하나의 파일 복원:

/rollback 1 src/broken_file.py

안전 및 성능 감시

• **Git 가용성 ** - git이 PATH에 발견되지 않은 경우, 체크포인트는 투명하게 비활성화됩니다.
• ** 디렉터리 범위 ** - 헤르메스는 지나치게 넓은 감독을 건너 (root /, home $HOME).
• Repository size - 50,000 개 이상의 파일이 건너뛰는 디렉토리.
• Per-file size cap - max_file_size_mb (기본 ) 이상의 파일이 스냅샷에서 제외됩니다. 실수로 삼키는 datasets, 모델 무게, 또는 생성 된 미디어를 방지합니다.
• ** 총 상점 크기 캡 ** - 상점이 max_total_size_mb (기본 500 MB)를 초과 할 때 프로젝트 당 가장 오래된 커밋은 캡 아래까지 라운드 로빈을 떨어뜨립니다.
• Real pruning — max_snapshots는 프로젝트 ref를 재작성하여 git gc --prune=now를 다시 실행하여 시행됩니다.
• No-change snapshots - 마지막 스냅샷 이후 변경이 없는 경우, 체크포인트가 건너집니다.
• Non-fatal errors - Checkpoint Manager 내부의 모든 오류는 디버그 수준에 기록됩니다. 도구가 계속 실행됩니다.

자주 묻는 질문

~/.hermes/checkpoints/
  ├── store/                 # single shared bare git repo
  │   ├── HEAD, objects/     # git internals (shared across projects)
  │   ├── refs/hermes/<hash> # per-project branch tip
  │   ├── indexes/<hash>     # per-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>는 작업 디렉토리의 절대 경로에서 파생됩니다. 당신은 일반적으로이 수동으로 만질 필요가 없습니다 — 사용 hermes checkpoints status / prune / clear 대신.

v1에서 마이그레이션

v2를 다시 작성하기 전에 각 작업 디렉토리는 ~/.hermes/checkpoints/<hash>/에서 직접 자신의 완전한 그림자 git repo를 얻었다. 그 레이아웃은 프로젝트 전반에 걸쳐 개체를 dedup 할 수 없으며 문서화 된 no-op pruner가있었습니다. 상점은 경계없이 성장합니다.

첫 번째 v2 실행에, 모든 사전 v2 그림자 저장소가 ~/.hermes/checkpoints/legacy-<timestamp>/로 이동하므로 새로운 단일 상점 레이아웃이 깨끗하게 시작합니다. 오래된 /rollback 역사는 git와 레거시 아카이브를 수동으로 검사하여 여전히 도달 할 수 있습니다. 필요한 경우 실행하십시오

hermes checkpoints clear-legacy

공간의 재구성 레거시 아카이브는 auto_prune 으로 retention_days 니다.

최고의 연습

• **이 필요할 때만 체크 포인트를 활성화 ** — hermes chat --checkpoints 또는 per-profile enabled: true.
• **완구하기 전에 /rollback diff 사용 ** - 올바른 체크포인트를 선택하기 위해 어떤 변경 사항을 미리 볼 수 있습니다.
• ** /rollback 대신 git reset**를 사용하여 에이전트 구동 변경만 할 수 있습니다.
• Check hermes checkpoints status 가끔 당신이 체크포인트를 정기적으로 사용하는 경우 — 프로젝트가 활성화되고 저장 비용이 무엇인지 보여줍니다.
• Git worktrees for max safety — checkpoints as a extra layer.

동일한 repo에 평행한 다수 대리인을 달리기를 위해, Git worktrees에 가이드를 보십시오.