コンテキスト編集

概要

コンテキスト編集により、会話履歴が成長するにつれて、会話履歴から特定のコンテンツを選択的にクリアできます。コストの最適化と制限内での維持を超えて、これはClaudeが見るものを積極的にキュレーションすることです。コンテキストは有限のリソースであり、収益逓減の法則が適用され、無関係なコンテンツはモデルの焦点を低下させます。コンテキスト編集は、そのキュレーションに対する細かい実行時制御を提供します。コンテキスト管理の背後にある広範な原則については、効果的なコンテキストエンジニアリングを参照してください。このページでは以下をカバーしています。

• ツール結果クリア - 古いツール結果がもう不要になった重いツール使用を伴うエージェントワークフローに最適
• 思考ブロッククリア - 拡張思考を使用する際の思考ブロック管理、コンテキスト継続性のための最近の思考を保持するオプション付き
• クライアントサイドSDK圧縮 - サマリーベースのコンテキスト管理のためのSDKベースの代替案（サーバーサイド圧縮が一般的に推奨されます）

サーバーサイド戦略

ツール結果クリア

clear_tool_uses_20250919戦略は、会話コンテキストが設定されたしきい値を超えて成長するときにツール結果をクリアします。これは重いツール使用を伴うエージェントワークフローに特に役立ちます。古いツール結果（ファイルコンテンツや検索結果など）は、Claudeが処理した後は不要になります。

有効化されると、APIは時系列順に最も古いツール結果を自動的にクリアします。APIは各クリアされた結果をプレースホルダーテキストで置き換えるため、Claudeは削除されたことを認識します。デフォルトでは、ツール結果のみがクリアされます。clear_tool_inputsをtrueに設定することで、ツール結果とツール呼び出し（ツール使用パラメータ）の両方をクリアすることができます。

思考ブロッククリア

clear_thinking_20251015戦略は、拡張思考が有効な場合、会話内のthinkingブロックを管理します。この戦略は思考保持に対する制御を提供します。推論の継続性を維持するためにより多くの思考ブロックを保持するか、コンテキストスペースを節約するためにより積極的にクリアするかを選択できます。

アシスタント会話ターンは複数のコンテンツブロック（例：ツール使用時）と複数の思考ブロック（例：インターリーブ思考を使用する場合）を含む場合があります。

コンテキスト編集はサーバーサイドで実行されます

コンテキスト編集はプロンプトがClaudeに到達する前にサーバーサイドで適用されます。クライアントアプリケーションは完全で未修正の会話履歴を保持します。クライアント状態を編集されたバージョンと同期する必要はありません。通常通り、完全な会話履歴をローカルで管理し続けてください。

コンテキスト編集とプロンプトキャッシング

コンテキスト編集とプロンプトキャッシングの相互作用は戦略によって異なります。

• ツール結果クリア：コンテンツがクリアされるとキャッシュされたプロンプトプレフィックスが無効化されます。これを考慮するには、キャッシュ無効化を価値のあるものにするために十分なトークンをクリアしてください。clear_at_leastパラメータを使用して、毎回クリアされるトークンの最小数を確保してください。コンテンツがクリアされるたびにキャッシュ書き込みコストが発生しますが、その後のリクエストは新しくキャッシュされたプレフィックスを再利用できます。

• 思考ブロッククリア：思考ブロックがコンテキストに保持される（クリアされない）場合、プロンプトキャッシュは保持され、キャッシュヒットが有効になり、入力トークンコストが削減されます。思考ブロックがクリアされる場合、キャッシュはクリアが発生する時点で無効化されます。キャッシュパフォーマンスまたはコンテキストウィンドウの可用性を優先するかに基づいて、keepパラメータを設定してください。

サポートされているモデル

コンテキスト編集はサポートされているすべてのClaudeモデルで利用可能です。

ツール結果クリア使用法

ツール結果クリアを有効にする最も簡単な方法は、戦略タイプのみを指定することです。他のすべての設定オプションはデフォルト値を使用します。

高度な設定

ツール結果クリアの動作を追加パラメータでカスタマイズできます。

シンキングブロッククリアリング使用法

拡張シンキングが有効な場合、シンキングブロッククリアリングを有効にしてコンテキストとプロンプトキャッシングを効果的に管理します：

シンキングブロッククリアリングの設定オプション

clear_thinking_20251015戦略は以下の設定をサポートしています：

設定例：

最後の3つのアシスタントターンからシンキングブロックを保持：

{
  "type": "clear_thinking_20251015",
  "keep": {
    "type": "thinking_turns",
    "value": 3
  }
}

すべてのシンキングブロックを保持（キャッシュヒットを最大化）：

{
  "type": "clear_thinking_20251015",
  "keep": "all"
}

戦略の組み合わせ

シンキングブロッククリアリングとツール結果クリアリングを一緒に使用できます：

ツール結果クリアリングの設定オプション

コンテキスト編集レスポンス

context_managementレスポンスフィールドを使用して、リクエストに適用されたコンテキスト編集と、クリアされたコンテンツと入力トークンに関する有用な統計を確認できます。

{
  "id": "msg_013Zva2CMHLNnXjNJJKqJ2EF",
  "type": "message",
  "role": "assistant",
  "content": [
    // ...
  ],
  "usage": {
    // ...
  },
  "context_management": {
    "applied_edits": [
      // `clear_thinking_20251015`を使用する場合
      {
        "type": "clear_thinking_20251015",
        "cleared_thinking_turns": 3,
        "cleared_input_tokens": 15000
      },
      // `clear_tool_uses_20250919`を使用する場合
      {
        "type": "clear_tool_uses_20250919",
        "cleared_tool_uses": 8,
        "cleared_input_tokens": 50000
      }
    ]
  }
}

ストリーミングレスポンスの場合、コンテキスト編集は最終的なmessage_deltaイベントに含まれます：

{
  "type": "message_delta",
  "delta": {
    "stop_reason": "end_turn",
    "stop_sequence": null
  },
  "usage": {
    "output_tokens": 1024
  },
  "context_management": {
    "applied_edits": [
      // ...
    ]
  }
}

トークンカウント

トークンカウントエンドポイントはコンテキスト管理をサポートしており、コンテキスト編集が適用された後、プロンプトが使用するトークン数をプレビューできます。

{
  "input_tokens": 25000,
  "context_management": {
    "original_input_tokens": 70000
  }
}

レスポンスは、コンテキスト管理が適用された後の最終的なトークンカウント（input_tokens）と、クリアリングが発生する前の元のトークンカウント（original_input_tokens）の両方を示しています。

メモリツールとの併用

コンテキスト編集は、メモリツールと組み合わせることができます。会話コンテキストが設定されたクリア閾値に近づくと、Claude は重要な情報を保存するための自動警告を受け取ります。これにより、Claude はツール結果またはコンテキストをメモリファイルに保存してから、会話履歴からクリアすることができます。

この組み合わせにより、以下のことが可能になります：

• 重要なコンテキストを保存する: Claude はツール結果から重要な情報をメモリファイルに書き込んでから、それらの結果がクリアされます
• 長時間実行されるワークフローを維持する: 情報を永続的なストレージにオフロードすることで、コンテキスト制限を超えるエージェントワークフローを有効にします
• 必要に応じて情報にアクセスする: Claude は、すべてをアクティブなコンテキストウィンドウに保持するのではなく、必要に応じてメモリファイルから以前クリアされた情報を検索できます

たとえば、Claude が多くの操作を実行するファイル編集ワークフローでは、コンテキストが増加するにつれて、Claude は完了した変更をメモリファイルに要約できます。ツール結果がクリアされると、Claude はメモリシステムを通じてその情報へのアクセスを保持し、効果的に作業を続けることができます。

両方の機能を一緒に使用するには、API リクエストで有効にします：

メモリツールの完全なリファレンス（コマンドと例を含む）については、メモリツールを参照してください。

クライアント側の圧縮（SDK）

圧縮は、トークン使用量が大きくなりすぎた場合に要約を生成することで、会話コンテキストを自動的に管理する SDK 機能です。コンテンツをクリアするサーバー側のコンテキスト編集戦略とは異なり、圧縮は Claude に会話履歴を要約するよう指示し、その後、完全な履歴をその要約に置き換えます。これにより、Claude は、そうでなければコンテキストウィンドウを超える長時間実行されるタスクで作業を続けることができます。

圧縮の仕組み

圧縮が有効になっている場合、SDK は各モデル応答の後にトークン使用量を監視します：

1. 閾値チェック: SDK は合計トークンを input_tokens + cache_creation_input_tokens + cache_read_input_tokens + output_tokens として計算します。
2. 要約生成: 閾値を超えると、要約プロンプトがユーザーターンとして挿入され、Claude は <summary></summary> タグでラップされた構造化要約を生成します。
3. コンテキスト置換: SDK は要約を抽出し、メッセージ履歴全体をそれに置き換えます。
4. 継続: 会話は要約から再開され、Claude は中断したところから再開します。

圧縮の使用

tool_runner 呼び出しに compaction_control を追加して、トークン使用量が閾値を超えたときに自動要約を有効にします。

圧縮中に何が起こるか

会話が成長するにつれて、メッセージ履歴が蓄積されます：

圧縮前（100k トークンに近づいている）:

[
  { "role": "user", "content": "Analyze all files and write a report..." },
  { "role": "assistant", "content": "I'll help. Let me start by reading..." },
  {
    "role": "user",
    "content": [{ "type": "tool_result", "tool_use_id": "...", "content": "..." }]
  },
  { "role": "assistant", "content": "Based on file1.txt, I see..." },
  {
    "role": "user",
    "content": [{ "type": "tool_result", "tool_use_id": "...", "content": "..." }]
  },
  { "role": "assistant", "content": "After analyzing file2.txt..." }
  // ... 50 more exchanges like this ...
]

トークンが閾値を超えると、SDK は要約リクエストを挿入し、Claude は要約を生成します。その後、メッセージ履歴全体が置き換えられます：

圧縮後（約 2～3k トークンに戻る）:

[
  {
    "role": "assistant",
    "content": "# Task Overview\nThe user requested analysis of directory files to produce a summary report...\n\n# Current State\nAnalyzed 52 files across 3 subdirectories. Key findings documented in report.md...\n\n# Important Discoveries\n- Configuration files use YAML format\n- Found 3 deprecated dependencies\n- Test coverage at 67%\n\n# Next Steps\n1. Analyze remaining files in /src/legacy\n2. Complete final report sections...\n\n# Context to Preserve\nUser prefers markdown format with executive summary first..."
  }
]

Claude はこの要約から、元の会話履歴であるかのように作業を続けます。

設定オプション

トークン閾値の選択

閾値は圧縮が発生するタイミングを決定します。低い閾値は、より小さなコンテキストウィンドウでより頻繁な圧縮を意味します。高い閾値はより多くのコンテキストを許可しますが、制限に達するリスクがあります。

# More frequent compaction for memory-constrained scenarios
compaction_control = {"enabled": True, "context_token_threshold": 50000}

# Less frequent compaction when you need more context
compaction_control = {"enabled": True, "context_token_threshold": 150000}

要約に別のモデルを使用する

要約生成に、より高速または安価なモデルを使用できます：

compaction_control = {
    "enabled": True,
    "context_token_threshold": 100000,
    "model": "claude-haiku-4-5",
}

カスタム要約プロンプト

ドメイン固有のニーズのためにカスタムプロンプトを提供できます。プロンプトは Claude に要約を <summary></summary> タグでラップするよう指示する必要があります。

compaction_control = {
    "enabled": True,
    "context_token_threshold": 100000,
    "summary_prompt": """Summarize the research conducted so far, including:
- Sources consulted and key findings
- Questions answered and remaining unknowns
- Recommended next steps

Wrap your summary in <summary></summary> tags.""",
}

デフォルト要約プロンプト

組み込みの要約プロンプトは、Claude に以下を含む構造化された継続要約を作成するよう指示します：

1. タスク概要: ユーザーのコア要求、成功基準、および制約。
2. 現在の状態: 完了したもの、変更されたファイル、および生成されたアーティファクト。
3. 重要な発見: 技術的な制約、下された決定、解決されたエラー、および失敗したアプローチ。
4. 次のステップ: 必要な特定のアクション、ブロッカー、および優先順位。
5. 保存するコンテキスト: ユーザーの好み、ドメイン固有の詳細、および下された約束。

この構造により、Claude は重要なコンテキストを失ったり、間違いを繰り返したりすることなく、効率的に作業を再開できます。

制限事項

サーバー側ツール

サーバー側ツールを使用する場合、SDK はトークン使用量を誤って計算し、圧縮が間違ったタイミングでトリガーされる可能性があります。

たとえば、ウェブ検索操作の後、API レスポンスは以下を示す可能性があります：

{
  "usage": {
    "input_tokens": 63000,
    "cache_read_input_tokens": 270000,
    "output_tokens": 1400
  }
}

SDK は合計使用量を 63,000 + 270,000 = 333,000 トークンとして計算します。ただし、cache_read_input_tokens 値には、サーバー側ツールによって行われた複数の内部 API 呼び出しからの累積読み取りが含まれており、実際の会話コンテキストではありません。実際のコンテキスト長は 63,000 の input_tokens のみかもしれませんが、SDK は 333k を見て圧縮を早期にトリガーします。

回避策：

• トークンカウントエンドポイントを使用して、正確なコンテキスト長を取得します
• サーバー側ツールを広範に使用する場合は圧縮を避けます

ツール使用のエッジケース

SDK が圧縮をトリガーしている間にツール使用レスポンスが保留中の場合、メッセージ履歴から要約を生成する前にツール使用ブロックを削除します。要約から再開した後、必要に応じて Claude はツール呼び出しを再発行します。

圧縮の監視

圧縮がいつトリガーされるかを理解することは、閾値をチューニングし、予期された動作を検証するのに役立ちます。

圧縮を使用する場合

適切なユースケース：

• 多くのファイルまたはデータソースを処理する長時間実行されるエージェントタスク
• 大量の情報を蓄積する研究ワークフロー
• 明確で測定可能な進捗を持つ複数ステップのタスク
• 会話の外で永続化するアーティファクト（ファイル、レポート）を生成するタスク

あまり理想的ではないユースケース：

• 初期の会話の詳細を正確に思い出す必要があるタスク
• サーバー側ツールを広範に使用するワークフロー
• 多くの変数全体で正確な状態を維持する必要があるタスク