ai-docs

Context editing

Properties1
tagscontext, api, tools, thinking, prompt-caching

5 min read

一行要約

会話履歴から古い tool_result ブロックと古い thinking ブロックを選択的に消すサーバサイド機構。compaction と違って要約せず、該当ブロックだけを落とす。

要点

beta header: context-management-2025-06-27

Server-side: Context editing happens before the prompt reaches Claude; the client maintains the full history. サーバ側: context editing はプロンプトが Claude に届く前に行われる。クライアント側は完全な履歴を保持する。

クライアントは完全な履歴を持ち続ける。 削るのはサーバ側で、送信されたものに対して行われる。

2種類の edit

1. tool result clearing（clear_tool_uses_20250919）

ツールを多用する agentic ワークフロー向け。古い tool result を時系列順に消し、プレースホルダテキストに置き換える。

パラメータ既定内容
triggerinput tokens 100,000発動条件。{type: "input_tokens", value: N} または {type: "tool_uses", value: N}
keeptool use 3件保持する直近の tool use / result のペア数
clear_at_leastなし1回の発動で最低限消すトークン数
exclude_toolsなし決して消さないツール名のリスト
clear_tool_inputsfalse結果と一緒にツール呼び出しのパラメータも消すか

2. thinking block clearing（clear_thinking_20251015）

パラメータ既定内容
keepモデル依存{type: "thinking_turns", value: N} で直近 N ターン、または "all" で全部保持

モデル別の既定: Opus 4.5+ / Sonnet 4.6+ は全ターン保持。それ以前と Haiku は直近1ターンのみ。

組み合わせるときの注意

clear_thinking_20251015 must be listed first when combining strategies. 複数の戦略を組み合わせるときは、clear_thinking_20251015 を最初に並べなければならない。

prompt caching との相互作用（重要）

editキャッシュへの影響
tool result clearingキャッシュを無効化する
thinking block clearingthinking を保持する場合はキャッシュを保つ

→ keep: "all" はキャッシュヒットを最大化する。

レスポンス

context_management.applied_edits に、何がどれだけ消されたかが入る。

token counting

count_tokens エンドポイントも context_management を受け付けるので、送信前に削減量を見積もれる。context_management.original_input_tokens と input_tokens の差が節約分。

memory tool / compaction との関係

  • memory tool と組み合わせられる — 消される情報を永続ストレージに退避する
  • compaction は会話全体をサーバ側で要約する。context editing は特定の tool result をクライアント側の指定で消す

そのまま使える具体例

最小構成:

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

細かく制御する（exclude_tools で検索結果だけは残す）:

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"],
        }
    ]
}

thinking を直近2ターンだけ残す:

context_management={
    "edits": [
        {"type": "clear_thinking_20251015", "keep": {"type": "thinking_turns", "value": 2}}
    ]
}

キャッシュヒットを最大化する:

context_management={
    "edits": [{"type": "clear_thinking_20251015", "keep": "all"}]
}

組み合わせる（thinking を先に書く）:

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}},
    ]
}

削減量を事前に見積もる:

response = client.beta.messages.count_tokens(
    model="claude-opus-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")

レスポンスの形:

{
  "context_management": {
    "applied_edits": [
      {"type": "clear_thinking_20251015", "cleared_thinking_turns": 3, "cleared_input_tokens": 15000},
      {"type": "clear_tool_uses_20250919", "cleared_tool_uses": 8, "cleared_input_tokens": 50000}
    ]
  }
}

原典で言及されている関連文書

グラフビュー

バックリンク