Context editingとmemory toolを併用する長時間エージェント設計

クリアされる前にClaudeへ警告が届く

context editingとmemory toolを併用すると、会話コンテキストがクリアの閾値に近づいた時点で、Claudeに重要な情報を保存するよう促す自動的な警告が届きます。Claudeはツール結果が会話履歴から消される前に、その内容をmemoryファイルへ書き出せます。

併用の動機は、サーバー側で古いツール結果を間引く仕組みと、消えると困る情報を残したい要求との衝突にあります。tool result clearingは古いツール結果を機械的に間引くだけで、後で必要かどうかは判断しません。memory toolを足すと、消える前に重要な部分だけを自分のストレージへ逃がせます。

公式ドキュメントが挙げる併用の効果は3つあります。

• ツール結果の本質的な情報を、クリアされる前にmemoryファイルへ書き込める
• コンテキスト上限を超えてしまう長時間作業を、永続ストレージへの退避で続けられる
• 過去にクリアされた情報を、必要になった時点でmemoryファイルから読み戻せる

1回のクリアで何が起きるか

既定の設定で、ツール結果が積み上がる作業を流したときの順序は次のとおりです。数値はclear_tool_uses_20250919の既定値です。

警告がどのタイミングで出るかについて、公式ページは「設定したクリア閾値に近づいたとき」と書いていて、残りトークン数のような具体値は示していません。警告の発火位置に依存した設計は避けるのが無難です。

2つの機能は動く場所が違う

併用が成り立つのは、2つの機能が別のレイヤーで動くからです。

クリアだけなら、間引かれた情報はClaudeから見て失われます。memory toolだけなら、Claudeが自発的に書き出さない限り履歴は膨らみ続けます。両方を有効にすると「肥大化したら間引く」と「間引く前に大事な部分を残す」が噛み合います。

memory toolは、関連情報を最初から全部読み込まず、必要なときに読み戻す方式を前提にしています。アクティブなコンテキストが今のタスクに集中するので、そのままではウィンドウを圧迫する長時間セッションでも破綻しにくくなります。

実装

toolsにmemory_20250818タイプのmemory toolを加え、context_management.editsにclear_tool_uses_20250919を指定します。公式ドキュメントの併用例と同じ形で、anthropic-betaヘッダーにcontext-management-2025-06-27が必要です。

curl https://api.anthropic.com/v1/messages \
    --header "x-api-key: $ANTHROPIC_API_KEY" \
    --header "anthropic-version: 2023-06-01" \
    --header "anthropic-beta: context-management-2025-06-27" \
    --data '{
        "model": "claude-opus-5-5",
        "max_tokens": 4096,
        "messages": [{"role": "user", "content": "設定ファイルを全部調べてレポートにまとめて"}],
        "tools": [{"type": "memory_20250818", "name": "memory"}],
        "context_management": {
            "edits": [{"type": "clear_tool_uses_20250919"}]
        }
    }'

memoryツールは、名前をmemoryにする以外に入力スキーマを書く必要がありません。この1行をtoolsに足せば有効になります。ただしmemory toolの実体はクライアント側にあります。view・create・str_replace・insert・delete・renameの6コマンドは、アプリケーション側で実装します。コマンドごとの返り値はMemoryツールの6コマンド実装にまとめています。

既定値を調整するときの設定項目

何も指定しなくても動きますが、併用では次の5項目が効きます。

公式の設定例はtriggerを30,000、keepを3、clear_at_leastを5,000、exclude_toolsを["web_search"]にしています。memory toolと併用するなら、読み戻した内容を残したいのでexclude_toolsにmemoryを入れる形が考えられます。

"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": ["memory"]
    }]
}

clear_at_leastは、プロンプトキャッシュとの兼ね合いで決めます。ツール結果をクリアするとキャッシュ済みのプロンプト接頭辞が無効になり、クリアのたびにキャッシュ書き込みのコストが発生します。そのため、消す量が少なすぎるクリアは割に合いません。clear_at_leastを指定すると、API側が指定量を消せないときにクリア自体が実行されなくなります。

クリアが実際に起きたかを見る

クリアが発動した回は、レスポンスのcontext_management.applied_editsにcleared_tool_usesとcleared_input_tokensが入ります。ストリーミングでは最後のmessage_deltaイベントに載ります。この値が出たターンを目印にすると、直前のターンでClaudeがmemoryへ書き出したかをログから突き合わせられます。

組み込む前に効果を見積もりたいときは、トークンカウントのエンドポイントがcontext managementに対応しているので、クリア適用後のトークン数を事前に確認できます。

ファイル編集ワークフローでの動き方

公式ドキュメントの典型例は、Claudeが多数のファイル操作を行うワークフローです。会話が進むとツール結果が積み上がりますが、Claudeは完了した変更を要約としてmemoryファイルに書き残せます。古い結果がクリアされたあとも、memory経由でその情報へ届くので作業を止めずに続けられます。

これは「全部をアクティブなコンテキストに置く」設計から「必要なときだけ読み返す」設計への転換です。ツールを呼ぶ回数が多いタスクほど、この設計の差が出ます。

複数セッションにまたがる開発では、進捗ログをmemoryに残す設計が使えます。詳細はClaude Memoryツールで複数セッション開発を再開するパターンにあります。公式のパターンでは、最初のセッションで進捗ログ・機能チェックリスト・起動スクリプトへの参照をmemoryに用意します。context editingとの併用は、その進捗ログを書くタイミングをクリア前へ前倒しする形です。

公式ページ同士の言い方の違い

併用の前提になる記述が、2つの公式ページで少し食い違っています。

context editingのページは、クリアはAPIがプロンプトをClaudeへ渡す前にサーバー側で行うとし、クライアントは完全な履歴を持ち続けると書いています。一方memory toolのページは、compactionとの対比で「context editingは特定のツール結果をクライアント側でクリアする」と書いています。実装を決めるときは、ツール結果の削除をAPIに任せる前者の説明に沿います。

もう1つは対応モデルです。context editingは「サポートされるすべてのClaudeモデルで利用可能」とされ、memory toolは「Claude 4以降のすべてのモデル」で使えるとされています。併用は後者の範囲で成り立つので、対象モデルがClaude 4以降かを先に見てください。

compactionとの違いと使い分け

長時間エージェントのコンテキスト管理には、サーバーサイドcompactionもあります。context editingのページ自体が、長い会話の主な戦略はサーバーサイドcompactionだとしています。tool result clearingは、何を消すかを細かく制御したい場面向けです。

compactionはクライアントの作り込みなしにアクティブなコンテキストを小さく保ち、memoryは要約をまたいで残したい情報を守ります。長時間エージェントで両方を併用する構成も選べます。特定のツール結果だけを間引きたいならtool result clearing、会話全体を圧縮したいならcompactionが目安です。memoryファイルの構造(進捗ログ・参照情報・チェックリスト)を先に決めておくと、読み戻しの手戻りが減ります。

セキュリティ上の注意

memory toolはクライアント側で動くため、パスの検証は自分のハンドラーの責任です。/memoriesの外へのアクセスを許すと、パストラバーサルの脆弱性になります。公式は/memories/../../secrets.envのようなパスを例に、全コマンドで検証するよう求めています。対策の実装はMemory toolのパストラバーサル対策で扱っています。

6コマンドのどれでも、Claudeから渡されたパスをそのままストレージAPIへ渡さず、/memories以下の相対パスが親ディレクトリの外へ抜けていないかを確かめます。

パス以外にも、公式は次の運用上の安全策を挙げています。

• 機密情報: Claudeは通常、機密情報をmemoryに書くのを断ります。より強い保証がほしければ、ハンドラーが書き込む前に機密データを取り除く検証を足します
• ファイルサイズ: ファイルの最大サイズに上限を設け、viewが返す文字数も絞ります。残りはview_rangeで読み進めさせます
• 有効期限: 長く参照されていないmemoryファイルを定期的に削除します

併用でつまずいたときの切り分け

症状から原因を探す順に並べます。

1行目の対処は、組み込みの指示とも関係します。memory toolをtoolsに入れると、APIがシステム指示を自動で加えます。趣旨は「作業前にmemoryをviewする」「進捗や考えを記録する」「コンテキストはいつリセットされるか分からない」の3点です。この指示は進捗の記録を促しますが、クリア直前の退避に直接触れた文面ではありません。書き込むかどうかはClaudeの判断なので、確実に残したい情報は自分のプロンプトで書き出しを指示します。

memoryファイルの実体は自分のアプリケーションが管理するストレージにあります。/memoriesは実際のストレージへ対応付けるための接頭辞です。ユーザー別のディレクトリにも、データベースのキーにもできるので、ユーザーやタスクを分けたい場合は、このパス変換のところで保存先を切り替えます。

thinking blockのクリアは別のstrategy(clear_thinking_20251015)で、併用するときはedits配列の先頭に置く決まりがあります。順序の詳細はContext editingでthinking blockとtool resultを併用する順序にあります。

併用するときの判断は1つに絞れます。長く参照するのが特定のツール結果ならexclude_toolsで残し、後から要約として必要になる情報ならmemoryへ書き出す、という使い分けです。