Claude Code cleanupPeriodDaysでデータの保持期間を変える
settings.jsonのcleanupPeriodDaysはセッション履歴やチェックポイントの自動削除までの日数を決めます。既定30日の中身、managed settingsでの固定、掃除の対象外になるデータをまとめます。
このTipsでできること
Claude Codeは起動のたびに、古くなったセッション履歴やチェックポイントを自動で削除する「保持期間の掃除」を実行します。この日数を決めているのがsettings.jsonのcleanupPeriodDaysです。この記事では、実際に何が削除対象になるか、既定値30日の根拠、managed settingsでの固定運用、そして自動削除の対象から外れるデータまでを扱います。
cleanupPeriodDaysが削除するもの
cleanupPeriodDaysは、~/.claude/projects/配下に溜まるセッショントランスクリプト(会話ログの.jsonlファイル)を中心に、関連する複数のデータを対象にした保持期間です。対象は1種類ではありません。
| 対象 | 内容 |
|---|---|
| セッショントランスクリプト | 内容~/.claude/projects/*/*.jsonl。会話の再開に使う本体データ |
| セッション付随ファイル | 内容サイドカーファイル・録画・ツール実行結果など、トランスクリプトに紐づく補助データ |
| チェックポイント | 内容/rewind用のファイルスナップショット。セッションと一緒に削除される |
/insightsレポート | 内容~/.claude/usage-data/に溜まる使用状況レポート。同じスケジュールで古いものが削除される |
これらは起動時に一括で走る「保持期間の掃除(retention sweep)」の対象で、cleanupPeriodDaysの日数を過ぎたファイルから削除されます。
デフォルト30日とmanaged settingsでの固定
既定値は30日、設定できる最小値は1日です。値を短くすればディスク使用量やログの残存期間を絞れますし、長くすれば過去のセッションを--resumeで長く遡れます。
{
"cleanupPeriodDays": 7
}組織として保持期間を統一したい場合は、個々のメンバーのsettings.jsonではなくmanaged settingsで配布します。managed settingsがcleanupPeriodDaysを設定していると、下位スコープの設定ファイルが壊れていたり無効な値を含んでいたりしても、managedの値で掃除が実行されます。逆に、managed settingsのファイル自体が読み込めない場合は掃除そのものが一時停止されます。
コンプライアンス要件でログの保持期間に上限を設けたい場合は、個人の設定に委ねずmanaged settingsで固定するのが確実です。組織全体への配布手順はClaude Code組織管理ガイド — managed settingsで統制するにまとめています。
掃除が止まるケースと安全側の設計
掃除は「保持期間を安全に判定できる場合に限って」実行される設計です。次のようなケースでは削除が一時停止され、次回以降に持ち越されます。
- ユーザー設定が
--setting-sourcesなどで除外されていて、cleanupPeriodDaysを提供するソースが他に無い - いずれかの設定ファイルが壊れていて読み込めず、
cleanupPeriodDaysが本来どんな値なのか判定できない - 設定に検証エラーがあり、かつ
cleanupPeriodDays自体は明示的に指定されている(既定値へフォールバックすると、本来消してはいけないファイルまで消しかねないため)
この設計により、設定ファイルの一時的な不備で意図しない大量削除が起きることは避けられています。
また、同一マシンで直近24時間以内にすでに掃除を実行済みの場合、そのセッションでの掃除実行は起動から10分以上遅らせて負荷を分散する仕組みになっています。そのため、10分より早く終了するセッションでは掃除自体が走らないことがあります。claude -p --bareのような軽量実行も同様に対象外です。
ローカルの保持期間とAnthropic側のデータ保持ポリシーは別物
cleanupPeriodDaysが制御するのは、あなたのマシン上の~/.claude/projects/に置かれたプレーンテキストのローカルキャッシュだけです。
これとは別に、Anthropicのサーバー側にもデータ保持ポリシーがあり、モデル改善のためのデータ利用を許可しているかどうかで期間が変わります。データ利用を許可している場合は5年、許可していない場合は標準30日という保持期間がサーバー側に適用されます。Claude Code for Enterpriseの一部アカウントでは、サーバー側に一切データを残さないZero Data Retentionも選べます。
つまり「ローカルの保持期間を1日に縮めれば、Anthropic側にも会話が残らなくなる」わけではありません。cleanupPeriodDaysはあくまでローカルの--resume用キャッシュの寿命であり、サーバー側の保持・利用ポリシーを変える設定ではない点を分けて理解しておく必要があります。
除外されるデータ — memoryとMEMORY.md
cleanupPeriodDaysの対象はセッション単位のデータに限られます。自動メモリ(MEMORY.mdとトピックファイル)はこの掃除の対象から明示的に除外されており、自分や過去のセッションが編集・削除しない限り残り続けます。セッション履歴は日数で消えても、CLAUDE.mdやメモリに書いた恒久的な知見は保持期間の影響を受けません。この2つの違いはClaude Code memoryの三層構造で詳しく扱っています。
チェックポイントは日数だけでなく件数の上限もある
チェックポイントの削除はcleanupPeriodDaysの日数だけで決まるわけではありません。Claude Codeは1セッションにつき直近100件のチェックポイントだけを保持し、それより古いチェックポイントはセッション自体がまだ保持期間内でも破棄されます。
破棄の際、他のどのチェックポイントからも参照されなくなったスナップショットファイルが削除されますが、各ファイルの最初のスナップショットだけはVS Code拡張のセッション差分表示の基準点として残ります。頻繁に/rewindを使い長時間の1セッションでチェックポイントを積み重ねている場合は、cleanupPeriodDaysを伸ばしても100件の上限には別途引っかかる点に注意してください。
OTelでretention sweepを監視する
チーム規模で保持ポリシーの遵守を確認したい場合、claude_code.retention_sweepイベントの主な属性は次のとおりです。
| 属性 | 内容 |
|---|---|
result | 内容complete(掃除を実行)/ skipped(一時停止) |
period_days | 内容実際に使われたcleanupPeriodDaysの値 |
used_default | 内容設定ソースが無く既定30日を使ったかどうか |
transcripts_deleted / session_files_deleted | 内容削除したトランスクリプト数 / セッション付随ファイルを含めた総数 |
files_past_cutoff | 内容期限を過ぎているのに削除できなかったファイル数 |
error_count | 内容掃除中に発生したエラー件数 |
このイベントはv2.1.227以降で利用でき、設定したOpenTelemetryのバックエンドにのみ送られます(Anthropicには送られません)。監視基盤を組んでいるチームであれば、used_defaultが意図せずtrueになっていないか、files_past_cutoffが増え続けていないかを定期的にチェックすると、保持ポリシーが設定どおりに機能しているかを継続的に確認できます。
設定が反映されているか確認する
cleanupPeriodDaysを変更したあと、実際にどの値が有効になっているか確認したい場合は、Claude Code内で/statusを実行します。Setting sourcesの行で、User settings・Project settings・Managed settingsのうちどれが読み込まれているかを確認できます。ただし/statusは読み込まれたファイルの一覧を示すだけで、cleanupPeriodDaysの実効値そのものは表示しません。
実際に何日分残っているかを確かめたい場合は、OpenTelemetryを構成していれば前節のretention_sweepイベントのperiod_days属性が最も直接的です。構成していない場合は、~/.claude/projects/配下のファイルの更新日時を見て、想定より古いファイルが残っていないかを確認する方法もあります。
保持期間を完全に無効化したい場合
cleanupPeriodDaysはあくまで「削除までの日数」を変える設定で、トランスクリプトの書き込み自体を止めるものではありません。ローカルにプレーンテキストで会話ログを残したくない場合は、書き込みそのものを抑止する別の経路を使います。
| やりたいこと | 使う設定 |
|---|---|
| 保持日数を変える(30日から変更) | 使う設定cleanupPeriodDays |
| 全モードでトランスクリプト書き込みを止める | 使う設定環境変数CLAUDE_CODE_SKIP_PROMPT_HISTORY |
-p実行1回だけ永続化を止める | 使う設定CLIフラグ--no-session-persistence |
保存先自体を~/.claude以外に移す | 使う設定環境変数CLAUDE_CONFIG_DIR |
保持日数を短くするだけで十分か、書き込みそのものを止める必要があるかは、セッション再開機能をどこまで使うかで判断します。書き込みを止めると--resumeによる会話の再開ができなくなる点に注意してください。
場面別にどう設定するか
保持期間をどう決めるかは、--resumeをどれだけ活用するかとディスク容量の余裕次第です。使い方ごとの目安は次のとおりです。
| 使い方 | 推奨する日数 | 理由 |
|---|---|---|
日常的に数日前のセッションへ--resumeで戻る | 推奨する日数既定の30日のまま、またはさらに延ばす | 理由過去のセッションを長く遡れる方が実用的 |
| 機密性の高いリポジトリを一時的にクローンして短時間だけ作業する | 推奨する日数1〜3日程度 | 理由ディスクに残る痕跡を最小限にできる |
| CI環境で毎回使い捨てのコンテナを立てる | 推奨する日数意識する必要はほぼ無い | 理由コンテナごと破棄されるため |
| チームで統一の判断基準を持ちたい | 推奨する日数個人設定に委ねずmanaged settingsで固定 | 理由運用の揺れが最も少ない |
どの使い方でも共通しているのは、cleanupPeriodDaysが「消えて困る過去のセッションが無いか」と「ディスクや監査上の理由でどこまで痕跡を残したいか」のトレードオフだという点です。用途が変わるたびに都度設定を見直すのではなく、上の表のどの行に自分の使い方が近いかを確認して、最初にひとつだけ決めてしまう方が長い目で見て運用は安定します。
よくある質問
cleanupPeriodDaysを0にできますか
できません。最小値は1日です。0や負の値は設定できないため、最短でも1日分のセッションデータはディスクに残ります。
/insightsのレポートも対象ですか
対象です。~/.claude/usage-data/に保存される/insightsのHTMLレポートも、同じcleanupPeriodDaysのスケジュールで古いものから削除されます。過去のレポートを長期保存したい場合は、掃除の対象外の場所に自分でコピーしておく必要があります。
掃除が実行されたかどうかを確認する方法はありますか
前述のOTelのclaude_code.retention_sweepイベントで、実行結果(完了 / 一時停止とその理由)や削除件数を確認できます。
保持日数を変えたのに古いファイルが消えないことがありますか
あります。ファイルが開かれたままだったり権限エラーが起きたりすると、期限を過ぎても削除に失敗することがあります。OTelのretention_sweepイベントでは、こうした削除失敗ファイルの件数やエラー件数も別カウンタで記録されるため、大量に失敗が続く場合は権限設定やファイルロックの状況を見直す価値があります。
まとめ
cleanupPeriodDaysは、セッショントランスクリプト・チェックポイント・/insightsレポートをまとめて対象にする保持期間の設定で、既定は30日・最小1日です。設定ファイルが読み込めない状況では安全側に倒して掃除自体を一時停止する設計になっており、組織単位で保持期間を固定したい場合はmanaged settingsでの配布が確実です。自動メモリは掃除の対象から除外されるため、セッション履歴と恒久的な知見は別々の寿命で管理されています。settings.json全体のキー一覧はClaude Code settings.json完全ガイド、環境変数やトラブルシューティングを含む実戦的な設定例はClaude Code設定ガイドを参照してください。