チェックポイントを気にかけるべき理由

Hermesにコードの大きな塊をリファクタリングしてもらう場面を想像してみてください。そして作業の途中で、新しいアプローチが大失敗だと気づいたとします。チェックポイントがなければ、手動で変更を元に戻したり、gitの履歴を掘り返したりするはめになります。チェックポイントがあれば、/rollbackと入力して復元ポイントを選ぶだけです。まるでプロジェクト専用のタイムマシンです。

さらに嬉しいことに、チェックポイントは完全にオプションです。v2ではデフォルトでオフになっているので、使わなければ存在すら気づかないでしょう。しかし、必要なときには命綱になってくれます。

チェックポイントを有効にする

このセーフティネットを有効にする方法は2つあります。

セッション単位（このチャットだけ）:

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ターンにつきディレクトリごとに最大1つのチェックポイントしか作成しません。つまり、長いセッションでもディスクが何百ものスナップショットで埋まることはありません。

舞台裏の仕組み

ここが賢いところです。Hermesは~/.hermes/checkpoints/store/に保存された単一の共有シャドウgitリポジトリを使用します。実際のプロジェクトの.gitフォルダには一切触れません。すべてのプロジェクトがこの1つのストアを共有し、gitのコンテンツアドレス方式によってプロジェクト間のファイル重複が自動的に排除されます。つまり、2つのプロジェクトに似たファイルがあっても、保存されるのは1回だけです。

セッション中の`/rollback`の使い方

チェックポイントが有効になると、チャット中に以下のスラッシュコマンドが使えます:

コマンド	機能
`/rollback`	変更統計付きの全チェックポイントを一覧表示
`/rollback <N>`	チェックポイントNに復元。手動編集は保持（直前のチャットターンも取り消し）
`/rollback <N> --all`	完全復元 — 手動編集も上書き
`/rollback diff <N>`	チェックポイントNと現在の状態の差分をプレビュー
`/rollback <N> <file>`	チェックポイントNから1つのファイルだけを復元

/rollbackと入力すると、次のような表示がされます:

📸 /path/to/project のチェックポイント:

  1. 4270a8c  2026-03-16 04:36  patch前  (1 file, +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 file, +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の学習中であれば、チェックポイントをオンにしましょう。ストレージのオーバーヘッドは（重複排除のおかげで）控えめで、精神的な安心感は絶大です。単純で安全なタスクだけを行っているなら、オフのままにしてディスク容量を節約しましょう。

チェックポイントは、普段は忘れてしまう機能のひとつです — しかし、切実に必要になる瞬間が来ます。そして、その瞬間が来たら、あってよかったと思うはずです。