チュートリアル10: チェックポイント — AIの「元に戻す」ボタン

大事なものをうっかり消しちゃったときの、あの絶望感を覚えていますか？何時間もかけて作ったファイルだったり、すべてを壊してしまった設定変更だったり。現実の世界では、ファイルシステムにCtrl+Zは存在しません。でもHermes Agentにはあるんです — それがチェックポイントです。

チェックポイントは、ビデオゲームのセーブポイントみたいなものだと思ってください。AIエージェントがファイルの上書きや破壊的なコマンドの実行といったリスクのある行動をする前に、プロジェクトのスナップショットを素早く撮ってくれます。もし何か問題が起きたら、たった1つのコマンドでそのスナップショットに戻れます。プロジェクト全体に「元に戻す」ボタンがあるようなものです。

セーフティネットをオンにする

正直なところ、チェックポイントはHermes v2ではオプトインです。ほとんどのユーザーは必要としませんし、ストレージは時間とともに増えていきます。でも、何か重要な作業をしているなら、これは命綱になります。

有効にする方法は2つあります：

セッション単位（1回のチャットだけ）：

hermes chat --checkpoints

グローバル（~/.hermes/config.yaml内）：

checkpoints:
  enabled: true

これだけです。有効にすると、Hermesは破壊的なことが起こる前に自動的にプロジェクトのスナップショットを撮ります。

チェックポイントのトリガー条件

Hermesはスナップショットを撮るタイミングを賢く判断します。以下のような操作を監視しています：

ファイル操作 — write_fileやpatchなど
破壊的なターミナルコマンド — rm、mv、sed -i、truncate、さらにはgit resetやgit cleanなど

一番いいところは、1ターンにつきディレクトリごとに最大1つのチェックポイントしか作成しないので、長いセッションでも何百ものスナップショットで溢れることはありません。

ロールバック：スラッシュコマンド

チャットセッション中は、/rollbackがあなたの最高の味方です：

コマンド	機能
`/rollback`	変更統計付きで全チェックポイントを表示
`/rollback <N>`	チェックポイントNに復元（手動での編集は保持）
`/rollback <N> --all`	完全復元 — 手動での編集も上書き
`/rollback diff <N>`	チェックポイントNと現在の差分をプレビュー
`/rollback <N> <file>`	チェックポイントNから特定のファイルだけ復元

デフォルトの/rollback <N>は賢いです — エージェントがやったことだけを取り消し、あなたが手動で行った変更は保持します。完全に消去したい場合は、--allを使いましょう。

ターミナルからストアを管理する

チャットの外では、CLIコマンドでチェックポイントを確認・管理できます：

hermes checkpoints              # サイズ、プロジェクト、内訳を表示
hermes checkpoints status       # 上と同じ
hermes checkpoints list         # statusのエイリアス
hermes checkpoints prune        # 孤立データや古いデータをクリーンアップ
hermes checkpoints clear        # すべて削除（確認あり）
hermes checkpoints clear-legacy # 古いv1移行アーカイブを削除

内部での仕組み

「これって自分の実際のgitリポジトリに影響するの？」と思っているかもしれませんね。いいえ。 Hermesは~/.hermes/checkpoints/store/に別の「シャドウストア」を保持します。実際のプロジェクトの.gitには一切触れません。

すべてのプロジェクトがこの1つのストアを共有します。gitはコンテンツアドレス方式なので、複数のプロジェクトに存在するファイルは1回だけ保存されます。驚くほど効率的なんです。

設定のチューニング

チェックポイントが使用するストレージ量を制御できます：

checkpoints:
  enabled: true
  max_snapshots: 20           # プロジェクトごとの最大チェックポイント数
  max_total_size_mb: 500      # ストア全体のサイズ上限
  max_file_size_mb: 10        # これより大きいファイルはスキップ
  auto_prune: true            # 古いエントリを自動クリーンアップ
  retention_days: 7           # エントリを7日間保持
  min_interval_hours: 24      # プルーニングは1日最大1回

自動プルーニング機能は賢いです — 起動時に古いエントリをクリーンアップしますが、「孤立」エントリ（フォルダが見つからないプロジェクト）は決して削除しません。フォルダが見つからないのは、外付けドライブがまだマウントされていないだけかもしれないからです。孤立データのクリーンアップには、hermes checkpoints pruneを手動で実行する必要があります。

プロジェクトの「元に戻す」ボタン

チェックポイントがあれば、いつでも過去に戻れると分かっているので、AIエージェントに自由に作業させることができます。コードのリファクタリング、設定の実験、あるいは単に安心感が欲しいだけでも、有効にする価値はあります。

次のセッションでhermes chat --checkpointsを試してみてください。ロールバックが必要になることはないかもしれません — でも、もし必要になったら、それがあったことをきっと喜ぶはずです。