COURSE 01 · Harness Engineering
会話履歴の保存・Clear・Resumeの内部構造
ハーネスは会話履歴をローカルに永続保存し、/clearで現在の文脈から切り離し、/resumeで読み直して再構築する。Claude CodeとCodexの保存先と挙動を一次情報で確認し、会話は戻せても実行環境は戻らない、という設計の境界を見る。
これは詳細編のレッスンです。コース全体の流れは、入口のハーネスとは何かから読むとつかめます。この詳細編は、入口で挙げたState(状態)を深掘りします。
核心をひとことで
/clear と /resume は、ハーネスの状態管理の分かりやすい窓です。先に結論を言うと、会話は過去に戻せても、実行環境までは戻らない。この境界が見えると、ハーネスが何をどこに持っているかが整理できます。
注意:ここで扱う挙動は製品のバージョンで変わります。記述は調査時点(2026年11月)に公式ドキュメントで確認した範囲です。
全体の仕組み
ハーネスは、会話の状態をふたつに分けて持っています。
- 実行中のコンテキスト(Active Context):次のモデル推論に渡す情報。いま動いている会話の作業メモリです。
- 永続履歴(Persistent History):ディスクに残す記録。セッションごとにファイルとして保存されます。
/clear は、実行中のコンテキストを切り離して、新しい空のコンテキストに切り替えます。/resume は、保存履歴を読み直して、コンテキストを組み立て直します。
ここで誤解しやすい点があります。/resume は「停止前のメモリ(RAM)をそのまま復元する」仕組みではありません。保存してあるのは会話の記録であって、プロセスのメモリ状態ではない。だから /resume は、記録から会話を読み直す操作です。
どこに保存しているか
会話は、どちらも会話中に逐次ディスクへ書かれ、セッション単位のJSONLファイルとして残ります。
| 項目 | Claude Code | Codex CLI |
|---|---|---|
| 主な保存形式 | JSONL | JSONL(rolloutファイル) |
| 保存場所 | ~/.claude/projects/ |
~/.codex/sessions/ |
| ファイルの単位 | セッション単位 | セッション単位 |
| セッション識別 | Session ID | Session ID |
| 補助の索引・メタデータ | 設定・メモリ等 | history.jsonl(入力のみ)・session_index.jsonl ほか |
| 保存タイミング | 会話中に逐次 | 会話中に逐次 |
Claude Codeの典型的な構造です。
~/.claude/
└── projects/
└── <project>/
├── <session-A>.jsonl
├── <session-B>.jsonl
└── memory/
└── MEMORY.md
保存先は正確には ~/.claude/projects/<プロジェクト>/<セッションID>.jsonl で、<プロジェクト> は作業ディレクトリのパスの英数字以外を - に置き換えた名前です。各行はJSONオブジェクト(メッセージ、ツール利用・結果、メタデータなど)で、この内部フォーマットはバージョンで変わります。古い履歴は既定で30日を過ぎると削除されますが、cleanupPeriodDays(settings.json)で変えられます。メモリ用ファイルは、この削除の対象外です。
Codexの典型的な構造です。
~/.codex/
├── sessions/
│ └── YYYY/MM/DD/
│ └── rollout-<時刻>-<会話ID>.jsonl
├── history.jsonl
└── session_index.jsonl
Codexは会話の記録(rolloutのJSONL)を日付別のフォルダに保存します。ファイル名は rollout-<時刻>-<会話ID>.jsonl の形です(ソースで確認。例:rollout-2025-05-07T17-24-21-<会話ID>.jsonl)。しばらくアクセスのない古いrolloutは .jsonl.zst に圧縮され、アーカイブ専用のフォルダも用意されています。検索・管理に使う索引やメタデータ(入力だけを並べる history.jsonl など)は別に持ち、補助ファイルの名前はバージョンで変わります。いずれにせよ、再開時に読むのは保存された会話であって、停止前のプロセスメモリではありません。
/clear で実際に何が消えるのか
「消える」をいくつかに分けて考える必要があります。
| 対象 | /clear 後 |
|---|---|
| モデルに渡す直前までの会話コンテキスト | リセットされる |
| 画面に表示された過去の会話 | 新しい会話に切り替わる |
| 現在のSession ID | 新しいIDになる |
| 以前のセッションのJSONL | 保持される |
| ツール実行結果の記録 | 保持される |
| 永続メモリ | 保持される |
/tmp やプロジェクトのファイル |
保持される |
| OSのプロセス・実行環境 | 自動で全解放されるとは限らない |
| API側のキャッシュ | 物理削除は保証されない |
Claude Codeは、/clear で以前のセッションを保存したまま、新しい空のコンテキストを始めると説明しています。Codexも同じく、表示履歴と会話コンテキストをリセットして新しいチャットを始めます。大事なのは、「モデルから見えなくなる」と「ストレージから削除される」は別のことだという点です。
/resume で何が戻るのか
| 対象 | /resume の挙動 |
|---|---|
| 過去のユーザー入力・モデル応答 | 復元される |
| ツール呼び出しと結果の履歴 | 復元される |
| 最後の圧縮要約(compact) | 復元される |
| 使用モデル | 原則は引き継ぐ。起動時に --model を指定した場合や非推奨モデルは例外 |
| 実行中だったエージェント(サブエージェント定義) | 復元される |
| アクティブなGoal | 復元される(ターン数・タイマー・集計の起点はリセット) |
| セッションに紐づくスケジュールタスク(未期限) | 復元される。バックグラウンドのBash・監視タスクは対象外 |
| 権限モード | 原則は復元する。ただし安全のため、全許可(bypassPermissions)は引き継がない |
起動時フラグで渡す設定(--mcp-config・--add-dir 等) |
再指定が要る。settings.json は起動時に再読込される |
| 中断していたツール呼び出し | 自動では再実行しない |
/tmp のファイル |
再生成しない。ディスク上に残っていれば使える |
| 変更したソースコード | ディスク上の現在の内容を使う |
| OSのプロセスメモリ | 復元しない |
Claude Codeの公式ドキュメントは、会話履歴・モデル・実行中だったエージェント・アクティブなGoal・未期限のスケジュールタスクを復元し、安全のため全許可モード(bypassPermissions)は引き継がない、と明記しています。中断していたツール呼び出しは、再開時に自動では再実行しません。Codexの公式ドキュメントも、codex resume は「IDで以前の対話セッションを続けるか、直近のチャットを再開する」と説明します。どちらも会話は戻しますが、実行状態そのものを戻すとは述べていません。
compact 済みの場合
長い会話の途中で /compact(会話を要約して文脈を空ける操作)が行われていたとします。
永続履歴
├── 初期の会話
├── compactの要約
└── その後の会話
/resume 後に モデルへ渡すコンテキスト
├── compactの要約
└── その後の会話
保存履歴に以前の会話が残っていても、モデルがその全量を読み直すわけではありません。最後の圧縮要約と、その後の未圧縮部分を使います。だから /resume で過去の全情報が無制限にモデルへ戻る、とは考えないほうが安全です。
開発作業では何が起きるか
たとえば、ひとつのセッションで次の作業をしたとします。
Session A
1. コードを調査する
2. 認証方式をJWTに決める
3. auth.ts を変更する
4. /tmp/test-data.json を作る
5. npm test を走らせる
6. エラーの原因を特定する
ここで /clear すると、過去の判断や実行結果を参照しないSession Bが始まります。Session Bでさらにファイルを編集してから /resume でSession Aに戻ると、こうなります。
- 会話履歴:Session Aの状態を読み直す
auth.ts:Session Bで変更されていれば、その新しい内容のまま/tmp/test-data.json:ディスクに残っていれば使えるnpm test:過去の出力は読めても、テストそのものは再実行されない- JWT採用の判断:会話履歴か要約に残っていれば、また参照できる
会話は過去に戻せても、ワークスペースが過去に巻き戻るわけではありません。
設計の核心:4つのライフサイクル
ここまでをまとめると、ハーネスは少なくとも次の4つを、別々のライフサイクルとして扱っています。
| 管理対象 | /clear | /resume |
|---|---|---|
| 会話コンテキスト(Conversation Context) | リセット | 再構築 |
| セッション履歴(Session History) | 保持 | 読み込み |
| ワークスペース状態(Workspace State) | 変更なし | 現在の状態を使う |
| 実行リソース(Runtime Resources) | 全解放の保証なし | 全復元の保証なし |
コンテキストは復元できるが、実行環境(Runtime)の復元は保証されない。ここに設計上の境界があります。
再開したとき、会話には「サーバーが起動中」と記録されていても、実際のサーバーはもう止まっているかもしれません。逆に、会話から切り離したプロセスが、まだ動き続けていることもあります。会話の記録と、ワークスペースやプロセスの実状態は、ずれるのが当たり前だと考えておく必要があります。
だから、エージェントを長時間動かす基盤では、セッション履歴だけに頼らず、ワークスペースとランタイムの実状態を独立して検査し、管理することになります。/resume は「過去の会話に戻る」機能であって、「過去の実行環境を復元する」機能ではない。この区別が、ハーネスの状態管理を理解する核心です。
次に読む
次はEvals(評価)で、ハーネスが本当に良くなったかをどう測るかを見ます。なお、複数のハーネスを束ねるときに、このセッションの状態を上の層でどう引き継ぐかはMeta-Harnessコースが扱います。