Claude Media
Claude Code cleanupPeriodDaysでデータの保持期間を変える
Claude CodeTips

Claude Code cleanupPeriodDaysでデータの保持期間を変える

settings.jsonのcleanupPeriodDaysはセッション履歴やチェックポイントの自動削除までの日数を決めます。既定30日の中身、managed settingsでの固定、掃除の対象外になるデータをまとめます。

読了目安 約10分

このTipsでできること

Claude Codeはセッション開始後にバックグラウンドで、古くなったセッション履歴やチェックポイントを削除する「保持期間の掃除(retention sweep)」を走らせます。その日数を決めるのがsettings.jsonのcleanupPeriodDaysです。

この記事は、消える物と消えない物の線引き、掃除が止まる条件、日数を変えても効かない場面を扱います。ローカルの--resume用キャッシュの話です。

何が消えて、何が消えないか

既定は30日、最小は1日です。0を書くと検証エラーになります。

~/.claude/settings.json
{
  "cleanupPeriodDays": 7
}

設定ファイルの置き場所と優先順位はClaude Code settings.json完全ガイドにあります。対象はトランスクリプトだけではありません。~/.claude/配下の次のようなパスが、この日数より古くなると削除されます。

対象

日数で消えるデータの例

  • 会話の本体

    projects/<project>/<session>.jsonl(全メッセージ・ツール呼び出し・結果)と、サブエージェントの会話、tool-results/に退避された大きな出力です。サブエージェント分は親セッションのトランスクリプトと一緒に消えます。

  • 作業の痕跡

    file-history/(/rewind用の編集前スナップショット)、plans/、debug/、paste-cache/、tasks/、session-env/です。

  • レポートと下書き

    usage-data/(/insightsのHTMLレポートと集計キャッシュ)は同じ日数で消えます。feedback/drafts/だけは「cleanupPeriodDaysか30日の短い方」です。

同じ日数の基準は、孤立したworktreeの自動削除にも使われます。

貼り付けた画像は少し込み入っています。v2.1.274以前は~/.claude/image-cache/に、それ以降はテンポラリディレクトリ(CLAUDE_CODE_TMPDIRで変更可)のセッション別images/に保存されます。後者もcleanupPeriodDaysより古ければ掃除で消えます。スクラッチパッドはトランスクリプトと同じ寿命で、掃除のとき一緒に消えます。claude project purgeで消したセッションのスクラッチパッドだけは、自分で消すかOSがテンポラリを片付けるまで残ります。

逆に、独自の保持ルールで動くものが3つあります。

  • sessions/: 実行中セッションごとの小さなファイルで、終了時に消え、クラッシュの残りは次回起動で片付きます
  • 自動メモリ(projects/<project>/memory/): 中のファイルは削除されません。ディレクトリが保持期間ずっと空だったときだけディレクトリごと消えます
  • ClaudeデスクトップとCoworkで始めたセッションのトランスクリプト: 既定では何日たっても残ります

デスクトップ由来の例外は見落とされやすいところです。desktopSessionCleanupPeriodDaysに日数を入れると、その日数とcleanupPeriodDaysの両方より古くなった時点で消えます。たとえばcleanupPeriodDaysが既定の30日なら、7を指定しても30日は残ります。managed settingsがcleanupPeriodDaysを持つ場合は、そちらの期間が優先され、desktopSessionCleanupPeriodDaysは無視されます(v2.1.248以降)。

プロンプト履歴のhistory.jsonlとstats-cache.jsonは掃除の対象外で、手で消すまで残ります。セッション履歴が消えても、CLAUDE.mdや自動メモリに書いた知見は残ります。2つの違いはClaude Code memoryの三層構造に、日数で消えないデータの片付け方はClaude Codeの.claudeディレクトリに残るデータの消し方にあります。

掃除が止まるとき、止まらないとき

掃除は、保持日数を安全に決められるときだけ走ります。決められないと一時停止し、次回以降に持ち越します。

判定

掃除が走るかの判定

  1. 1

    managed settingsに値があるか

    あれば、下位の設定ファイルが壊れていても、その値で掃除が走ります。managed settingsのファイル自体が読めない場合は、managedの層が別経路から値を供給しない限り一時停止します。

  2. 2

    設定を読み切れるか

    ユーザー設定が--setting-sourcesで除外されていて他に値の出どころが無い、または設定ファイルが読めない・解析できない場合は停止します。

  3. 3

    検証エラーと明示指定が重なっていないか

    設定に検証エラーがあり、cleanupPeriodDaysが明示されているときも停止します。

停止の原因は、OTelのretention_sweepイベントのskip_reasonで見分けられます。user_source_disabledはユーザー設定の除外、settings_unknowableは設定ファイルが読めない・解析できない、settings_invalid_key_setは検証エラーと明示指定の重なりです。

設定ファイルが読めない場合や、検証エラーと明示指定が重なる場合は、/statusに警告が出続けます。掃除が黙って止まっていないかは、まずここで気づけます。

同じマシンで直近24時間以内に掃除が走っていると、次のセッションの掃除は10分以上遅れます。その場合、10分より早く終わるセッションでは掃除が走りません。

もう一つ、claude -p --bareではそのセッションの掃除が走りません。--bareだけを使うスクリプト運用のマシンでは、他の起動がない限り古いファイルが減りません。

OTelで掃除の結果を見る

claude_code.retention_sweepイベント(v2.1.227以降)は、設定したOpenTelemetryのバックエンドにだけ送られます。見ておきたい属性は次のとおりです。

属性内容
result内容complete(掃除を実行)/ skipped(一時停止)
period_days内容使われた日数。どの設定にも無いときは30
used_default内容読めた設定ソースのどれにもcleanupPeriodDaysが無かったか
transcripts_deleted内容削除したトランスクリプト数
files_past_cutoff内容期限を過ぎたのに削除できなかったファイル数(権限エラー、開きっぱなしなど)
error_count内容掃除中のエラー数

files_past_cutoffが0でも、ディレクトリごとの削除失敗はerror_countに数えられるため、期限切れが残っていない証明にはなりません。used_defaultが意図せずtrueのままなら、設定が読めていないか、そもそも書かれていません。

OTelを組んでいない場合は、~/.claude/projects/の更新日時を見て古いファイルが残っていないか確かめられます。

Anthropic側の保持とは別の話

cleanupPeriodDaysが動かすのは、手元の~/.claude/のファイルです。Anthropic側の保持は、アカウントの種類で決まります。

くらべる

ローカルとサーバー側で寿命が違う

cleanupPeriodDays

手元のマシン

セッションのトランスクリプトを平文で~/.claude/projects/に置き、既定30日で消します。日数は自分(またはmanaged settings)で変えられます。

アカウント別

Anthropicのサーバー

データ利用を許可している個人アカウントは5年、許可していない場合は30日です。商用アカウントは標準30日で、Claude Code for Enterpriseの適格アカウントにはZero Data Retentionもあります。この設定では変わりません。

逆にZDRを有効にしても、手元のファイルはcleanupPeriodDaysの間残ります。

チェックポイントは日数の前に件数で切られる

/rewind用のスナップショットには、日数とは別に件数の上限があります。1セッションで保持するのは直近100件のチェックポイントで、古いものは、セッションが保持期間内でも破棄されます。

破棄のとき、どのチェックポイントからも参照されなくなったスナップショットは削除されますが、各ファイルの最初のスナップショットだけは残ります。VS Code拡張がセッション差分の基準点に使うためです。

日数の側は、セッションが最後にスナップショットを保存してから、既定で約30日です。期限後に古いチェックポイントへ戻ろうとすると、No files were restoredで失敗することがあります。

実機で確認できること

v2.1.285で、作業ディレクトリ内に空の設定ディレクトリを作り、CLAUDE_CONFIG_DIRで指定して試しました。中身は{"cleanupPeriodDays": 7}だけのsettings.json1枚です。ログインもモデル呼び出しもしていません。

実行前のls -Aはsettings.jsonだけで、claude --version、claude --help、claude project --helpを順に実行したあともsettings.jsonだけのままでした。少なくともこの3つのコマンドでは、指定したディレクトリにprojects/やsessions/は作られませんでした。この確認では、セッションを始めた場合の掃除の挙動までは見ていません。

出力の該当部分は次のとおりです。

claude --version
2.1.285 (Claude Code)
claude --help
  --no-session-persistence   Disable session persistence - sessions
                             will not be saved to disk and cannot be
                             resumed (only works with --print)
  --setting-sources <sources>  Comma-separated list of setting sources
                             to load (user, project, local).

--no-session-persistenceは--print(-p)専用で、対話セッションには効きません。ヘルプにcleanupPeriodDays専用のフラグはありません。また--setting-sourcesのヘルプの選択肢はuser・project・localの3つで、managedは載っていません。「掃除が止まるとき」のuser_source_disabledは、この--setting-sourcesでuserを外したときに起きる停止です。

保持日数を変えるか、書き込みを止めるか

cleanupPeriodDaysは削除までの日数を動かす設定で、書き込み自体は止めません。0が使えないため、実質的に消さない運用にしたいときは3650のような大きな値を入れる手があります。掃除は通知なしで削除し、保持期間より古いセッションは/resumeの一覧からも消えます。目的別に道具が分かれます。

やりたいこと使う設定
保持日数を変える使う設定cleanupPeriodDays
対話でも-pでも書き込みを止める使う設定環境変数CLAUDE_CODE_SKIP_PROMPT_HISTORY=1
-p実行1回だけ永続化を止める使う設定--no-session-persistence
保存先を~/.claude以外にする使う設定環境変数CLAUDE_CONFIG_DIR

CLAUDE_CODE_SKIP_PROMPT_HISTORYを付けたセッションは、プロンプト履歴とトランスクリプトの両方がディスクに書かれず、--resume・--continue・上矢印の履歴にも出ません。再開が要る作業では使えません。

自分の使い方ではどうするか

判断の軸は、「消えて困る過去のセッションがあるか」と「ディスクや監査の面で痕跡をどこまで許せるか」の2つです。

  • 数日前のセッションへ--resumeで戻る使い方なら、既定の30日を維持するか延ばします
  • 短期の案件や機密リポジトリで痕跡を減らしたいなら、cleanupPeriodDaysを短くします
  • 再開が不要で、そもそも書きたくないなら、日数ではなくCLAUDE_CODE_SKIP_PROMPT_HISTORYを選びます
  • チームで期間をそろえたいなら、個人のsettings.jsonに任せず、managed settingsで固定します。固定すると壊れた下位設定の影響を受けず、デスクトップ側の例外も同じ期間に揃います。配布手順はClaude Code組織管理ガイドにあります

まとめ

消したくない過去のセッションがあるかで日数を決めます。そもそも残したくないなら、日数ではなく書き込みを止める設定を選びます。

この記事を共有:XはてブLinkedIn

関連する記事

Claude Code をもっと見る →