ai-docs

Context editing

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

原典: Context editing ／ 日本語版

一行要約

会話履歴から古い tool_result ブロックと古い thinking ブロックを選択的に消すサーバサイド機構。compaction と違って要約せず、該当ブロックだけを落とす。長い会話の context 管理の主役は server-side compaction（compaction）で、こちらは何を消すかを細かく制御したい場面向けと原典自身が位置づけている。

要点

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

Context editing is applied server-side before the prompt reaches Claude. Your client application maintains the full, unmodified conversation history. You do not need to sync your client state with the edited version.

context editing はサーバ側で、プロンプトが Claude に届く前に適用される。クライアントのアプリケーションは、完全で手を加えていない会話履歴を保持する。クライアントの状態を編集後の版と同期させる必要はない。

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

On Claude Fable 5.1, Claude Opus 5.5, and Claude Sonnet 5.5, server-side context management never invalidates thinking blocks. Client-side edits to earlier turns can invalidate the thinking blocks in every later assistant turn.

Claude Fable 5.1・Claude Opus 5.5・Claude Sonnet 5.5 では、サーバ側の context 管理が thinking ブロックを無効にすることはない。クライアント側で過去のターンを編集すると、それ以降のすべての assistant ターンの thinking ブロックが無効になりうる。

削るならサーバ側に任せる理由がここにある。 一定の日以降に作られたアカウントでは、無効になったブロックを送り返すリクエストは、捨てる設定をしない限り拒否される（prefix 検査。thinking に要点、詳細は未取得の preserved-thinking）。

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+ / Fable と Mythos の全モデルは全ターン保持。それ以前の Opus / Sonnet と Haiku（4.5 まで全部）は直近1ターンのみ。 複数のモデル階層にまたがって走るコードなら、既定に頼らず keep を明示する。

組み合わせるときの注意

When using multiple strategies, the clear_thinking_20251015 strategy must be listed first in the edits array.

複数の戦略を使うときは、clear_thinking_20251015 を edits 配列の最初に並べなければならない。

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

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

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

レスポンス

context_management.applied_edits に、何がどれだけ消されたかが入る。ストリーミングでは最後の message_delta イベントに入る。

token counting

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

memory tool / compaction との関係

  • memory tool と組み合わせられる — 消去の閾値に近づくと Claude に自動で警告が届き、消される前に tool result や context を memory ファイルへ退避できる。消えた情報は後で memory から引ける
  • compaction は会話全体を要約して置き換える。context editing は要約せず、古い tool result と thinking ブロックを規則どおりにサーバ側で消す（何を消すかの規則はクライアントが context_management で指定する）

SDK の client-side compaction（非推奨）

原典は server-side compaction（compaction-threshold）を勧め、SDK の compaction_control はクライアント側で要約を制御する必要があるときだけにせよと言う。

  • TypeScript / Ruby SDK では非推奨で、有効にすると警告が出て、将来削除される。Python SDK は v1.0 で削除した。C# / Go / Java / PHP の tool runner は client-side の compaction_control をサポートしていない
  • tool runner と server-side compaction を併用するなら、context_management に compact_20260112 の edit を渡す
  • server-side tool（web search / web fetch など）と使うと、SDK がトークン数を誤って数え、compaction が間違ったタイミングで起きることがある（原典の例は早すぎるほう。cache_read_input_tokens に server tool 内部の複数の呼び出し分が積まれる）。回避策は、token counting エンドポイントで正確な長さを取るか、server tool を多用するなら compaction を避けるか
  • 向かない用途: 会話の初期の細部を正確に思い出す必要があるタスク、server-side tool を多用するワークフロー

そのまま使える具体例

最小構成:

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

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

バックリンク