コンテキスト編集

概要

「context editing」（コンテキスト編集）を使用すると、会話履歴が増大するにつれて、特定のコンテンツを選択的にクリアできます。コストの最適化や制限内に収めることにとどまらず、これはClaudeが目にするものを積極的にキュレーションすることを意味します。コンテキストは収穫逓減のある有限のリソースであり、無関係なコンテンツはモデルの集中力を低下させます。コンテキスト編集は、そのキュレーションに対するきめ細かな実行時制御を提供します。コンテキスト管理の背後にあるより広範な原則については、効果的なコンテキストエンジニアリングを参照してください。このページでは以下を扱います。

• ツール結果のクリア - 古いツール結果が不要になる、ツール使用の多いエージェントワークフローに最適です
• 思考ブロックのクリア - 拡張思考を使用する際の思考ブロックの管理用で、コンテキストの連続性のために最近の思考を保持するオプションがあります
• クライアントサイドSDKコンパクション - 要約ベースのコンテキスト管理のためのSDKベースの代替手段です（一般的にはサーバーサイドコンパクションが推奨されます）

サーバーサイド戦略

ツール結果のクリア

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

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

思考ブロックのクリア

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

アシスタントの会話ターンには、複数のコンテンツブロック（たとえばツールを使用する場合）や複数の思考ブロック（たとえばインターリーブ思考を使用する場合）が含まれることがあります。

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

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

Claude Fable 5.1およびClaude Opus 5.5では、サーバーサイドのコンテキスト管理によって思考ブロックが無効化されることはありません。以前のターンに対するクライアントサイドの編集は、それ以降のすべてのアシスタントターンの思考ブロックを無効化する可能性があります。2026年8月31日以降に作成された新しいアカウントでは、無効化されたブロックを再送するリクエストは、そのブロックの破棄をオプトインしない限り拒否されます。プレフィックスを変更しないようにするを参照してください。

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

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

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

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

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

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

ツール結果のクリアの使用方法

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

response = client.beta.messages.create(
    model="claude-opus-5-5",
    max_tokens=4096,
    messages=[{"role": "user", "content": "Search for recent developments in AI"}],
    tools=[{"type": "web_search_20250305", "name": "web_search"}],
    betas=["context-management-2025-06-27"],
    context_management={"edits": [{"type": "clear_tool_uses_20250919"}]},
)

高度な設定

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

response = client.beta.messages.create(
    model="claude-opus-5-5",
    max_tokens=4096,
    messages=[
        {
            "role": "user",
            "content": "Create a simple command line calculator app using Python",
        }
    ],
    tools=[
        {
            "type": "text_editor_20250728",
            "name": "str_replace_based_edit_tool",
            "max_characters": 10000,
        },
        {"type": "web_search_20250305", "name": "web_search", "max_uses": 3},
    ],
    betas=["context-management-2025-06-27"],
    context_management={
        "edits": [
            {
                "type": "clear_tool_uses_20250919",
                # しきい値を超えたときにクリアを実行します
                "trigger": {"type": "input_tokens", "value": 30000},
                # クリア後に保持するツール使用の数
                "keep": {"type": "tool_uses", "value": 3},
                # オプション: 少なくともこのトークン数をクリアします
                "clear_at_least": {"type": "input_tokens", "value": 5000},
                # これらのツールをクリア対象から除外します
                "exclude_tools": ["web_search"],
            }
        ]
    },
)

思考ブロックのクリアの使用方法

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

response = client.beta.messages.create(
    model="claude-opus-5-5",
    max_tokens=16000,
    messages=[{"role": "user", "content": "Hello"}],
    betas=["context-management-2025-06-27"],
    context_management={
        "edits": [
            {
                "type": "clear_thinking_20251015",
                "keep": {"type": "thinking_turns", "value": 2},
            }
        ]
    },
)

思考ブロックのクリアの設定オプション

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

設定例：

最後の3つのアシスタントターンの思考ブロックを保持する：

response = client.beta.messages.create(
    model="claude-opus-5-5",
    max_tokens=16000,
    messages=[{"role": "user", "content": "Hello"}],
    betas=["context-management-2025-06-27"],
    context_management={
        "edits": [
            {
                "type": "clear_thinking_20251015",
                "keep": {"type": "thinking_turns", "value": 3},
            }
        ]
    },
)

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

response = client.beta.messages.create(
    model="claude-opus-5-5",
    max_tokens=16000,
    messages=[{"role": "user", "content": "Hello"}],
    betas=["context-management-2025-06-27"],
    context_management={
        "edits": [
            {
                "type": "clear_thinking_20251015",
                "keep": "all",
            }
        ]
    },
)

戦略の組み合わせ

思考ブロックのクリアとツール結果のクリアの両方を一緒に使用できます。

response = client.beta.messages.create(
    model="claude-opus-5-5",
    max_tokens=16000,
    messages=[
        {
            "role": "user",
            "content": "Search for the latest developments in quantum error correction and summarize the key breakthroughs.",
        }
    ],
    tools=[
        {
            "type": "web_search_20250305",
            "name": "web_search",
            "max_uses": 5,
        }
    ],
    betas=["context-management-2025-06-27"],
    context_management={
        "edits": [
            {
                "type": "clear_thinking_20251015",
                "keep": {"type": "thinking_turns", "value": 2},
            },
            {
                "type": "clear_tool_uses_20250919",
                "trigger": {"type": "input_tokens", "value": 50000},
                "keep": {"type": "tool_uses", "value": 5},
            },
        ]
    },
)

print(response)

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

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

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

{
  "id": "msg_013Zva2CMHLNnXjNJJKqJ2EF",
  "type": "message",
  "role": "assistant",
  "content": [
    // ...
  ],
  "usage": {
    // ...
  },
  "context_management": {
    "applied_edits": [
      // When using `clear_thinking_20251015`
      {
        "type": "clear_thinking_20251015",
        "cleared_thinking_turns": 3,
        "cleared_input_tokens": 15000
      },
      // When using `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": [
      // ...
    ]
  }
}

トークンカウント

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

response = client.beta.messages.count_tokens(
    model="claude-opus-5-5",
    messages=[{"role": "user", "content": "Continue our conversation..."}],
    betas=["context-management-2025-06-27"],
    context_management={
        "edits": [
            {
                "type": "clear_tool_uses_20250919",
                "trigger": {"type": "input_tokens", "value": 30000},
                "keep": {"type": "tool_uses", "value": 5},
            }
        ]
    },
)

print(f"Original tokens: {response.context_management.original_input_tokens}")
print(f"After clearing: {response.input_tokens}")
print(
    f"Savings: {response.context_management.original_input_tokens - response.input_tokens} tokens"
)

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

レスポンスには、コンテキスト管理が適用された後の最終的なトークン数（input_tokens）と、クリアが行われる前の元のトークン数（original_input_tokens）の両方が表示されます。

メモリツールとの併用

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

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

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

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

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

response = client.beta.messages.create(
    model="claude-opus-5-5",
    max_tokens=4096,
    messages=[{"role": "user", "content": "Hello"}],
    tools=[{"type": "memory_20250818", "name": "memory"}],
    betas=["context-management-2025-06-27"],
    context_management={"edits": [{"type": "clear_tool_uses_20250919"}]},
)

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

クライアントサイドコンパクション（SDK）

「compaction」（コンパクション）は、トークン使用量が大きくなりすぎたときに要約を生成することで会話コンテキストを自動的に管理する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は、この要約が元の会話履歴であるかのように、そこから作業を続けます。

設定オプション

トークンしきい値の選択

しきい値はコンパクションがいつ発生するかを決定します。しきい値が低いほど、より小さなコンテキストウィンドウでより頻繁にコンパクションが行われます。しきい値が高いほど、より多くのコンテキストが許容されますが、制限に達するリスクがあります。

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

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

カスタム要約プロンプト

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

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

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

1. タスクの概要： ユーザーの中核となるリクエスト、成功基準、および制約。
2. 現在の状態： 完了した内容、変更されたファイル、および生成された成果物。
3. 重要な発見： 技術的な制約、下された決定、解決されたエラー、および失敗したアプローチ。
4. 次のステップ： 必要な具体的なアクション、ブロッカー、および優先順位。
5. 保持すべきコンテキスト： ユーザーの好み、ドメイン固有の詳細、および行われたコミットメント。

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

You have been working on the task described above but have not yet completed it. Write a continuation summary that will allow you (or another instance of yourself) to resume work efficiently in a future context window where the conversation history will be replaced with this summary. Your summary should be structured, concise, and actionable. Include:

1. Task Overview
The user's core request and success criteria
Any clarifications or constraints they specified

2. Current State
What has been completed so far
Files created, modified, or analyzed (with paths if relevant)
Key outputs or artifacts produced

3. Important Discoveries
Technical constraints or requirements uncovered
Decisions made and their rationale
Errors encountered and how they were resolved
What approaches were tried that didn't work (and why)

4. Next Steps
Specific actions needed to complete the task
Any blockers or open questions to resolve
Priority order if multiple steps remain

5. Context to Preserve
User preferences or style requirements
Domain-specific details that aren't obvious
Any promises made to the user

Be concise but complete—err on the side of including information that would prevent duplicate work or repeated mistakes. Write in a way that enables immediate resumption of the task.

Wrap your summary in <summary></summary> tags.

制限事項

サーバーサイドツール

サーバーサイドツールを使用する場合、SDKがトークン使用量を誤って計算し、コンパクションが誤ったタイミングでトリガーされる可能性があります。

たとえば、ウェブ検索操作の後、APIレスポンスは次のように表示される場合があります。

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

SDKは合計使用量を63,000 + 0 + 270,000 + 1,400 = 334,400トークンと計算します。しかし、cache_read_input_tokens の値には、実際の会話コンテキストではなく、サーバーサイドツールによって行われた複数の内部API呼び出しからの累積読み取りが含まれています。実際のコンテキスト長は63,000の input_tokens のみかもしれませんが、SDKは334kと認識し、コンパクションを早期にトリガーしてしまいます。

回避策：

• 正確なコンテキスト長を取得するにはトークンカウントエンドポイントを使用する
• サーバーサイドツールを多用する場合はコンパクションを避ける

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

ツール使用レスポンスが保留中にSDKがコンパクションをトリガーした場合、SDKは要約を生成する前にメッセージ履歴からツール使用ブロックを削除します。Claudeは、要約から再開した後、まだ必要であればツール呼び出しを再発行します。

コンパクションの監視

コンパクションがいつトリガーされるかを理解することは、しきい値の調整や期待される動作の検証に役立ちます。

コンパクションを使用すべき場合

適したユースケース：

• 多くのファイルやデータソースを処理する長時間にわたるエージェントタスク
• 大量の情報を蓄積するリサーチワークフロー
• 明確で測定可能な進捗がある複数ステップのタスク
• 会話の外部に永続する成果物（ファイル、レポート）を生成するタスク

あまり適さないユースケース：

• 会話初期の詳細を正確に思い出す必要があるタスク
• サーバーサイドツールを多用するワークフロー
• 多くの変数にわたって正確な状態を維持する必要があるタスク

次のステップ