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

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

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

この仕組みが解決するのは「サーバーサイドでコンテキストを間引く仕組み」と「消えると困る情報を残しておきたい要求」の衝突です。tool result clearingは古いツール結果を機械的に間引くだけで、その情報が後で必要かどうかは判断しません。memory toolと組み合わせることで、消える前に重要な情報だけをクライアント側の永続ストレージへ退避する、という役割分担が成立します。

公式ドキュメントは併用のメリットを3つに整理しています。1つ目は重要なコンテキストの保全で、ツール結果からの本質的な情報をクリアされる前にmemoryファイルへ書き込めること。2つ目は長時間ワークフローの維持で、そのままではコンテキスト上限を超えてしまうエージェント作業を、情報を永続ストレージへ逃がすことで継続できること。3つ目はオンデマンドでの情報アクセスで、アクティブなコンテキストウィンドウにすべてを保持し続けるのではなく、必要になった時点でmemoryファイルから過去にクリアされた情報を読み出せることです。

2つの機能はレイヤーが違う

tool result clearingはサーバーサイドで動き、APIリクエストがClaudeに届く前にコンテンツを間引きます。memory toolはクライアントサイドで動き、Claudeがtool_useでファイル操作をリクエストし、呼び出し元のアプリケーションが実際の読み書きを実行します。データがどこに保存されるかは完全に自分のインフラ次第です。

この層の違いが併用の意味を作ります。tool result clearingだけでは、間引かれた情報は本当に失われます。memory toolだけでは、Claudeが自発的に書き出さない限り、会話履歴はいつまでも膨張し続けます。両方を有効にすることで、「肥大化したら間引く」仕組みと「間引かれる前に大事な情報だけ残す」仕組みが噛み合います。

memory toolはさらに「just-in-time context retrieval」という考え方に基づいています。関連する情報をあらかじめ全部コンテキストへ読み込んでおくのではなく、エージェントが学んだことをmemoryファイルに記録し、必要になった時点で読み戻す方式です。これによってアクティブなコンテキストは今のタスクに集中したまま保たれ、そうでなければコンテキストウィンドウを圧迫してしまう長時間セッションでも破綻しにくくなります。memoryツールが有効な状態では、Claudeはタスクを始める前に自動で/memories配下を確認する挙動も持っており、tool result clearingで過去のやり取りが消えていても、memory経由で以前の学習内容を引き継げます。

実装

tools配列にmemory_20250818タイプのmemory toolを追加し、context_management.editsにclear_tool_uses_20250919を指定します。

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",
        "max_tokens": 4096,
        "messages": [{"role": "user", "content": "設定ファイルを全部調べてレポートにまとめて"}],
        "tools": [{"type": "memory_20250818", "name": "memory"}],
        "context_management": {
            "edits": [{"type": "clear_tool_uses_20250919"}]
        }
    }'

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

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

公式ドキュメントが挙げる典型例は、Claudeが多数のファイル操作を行うワークフローです。会話が進むにつれてツール結果が積み上がりますが、Claudeは完了した変更内容をmemoryファイルへ要約として書き残せます。tool result clearingが古いツール結果を実際に消したあとも、Claudeはmemoryシステム経由でその情報にアクセスし続けられるため、作業を中断せずに続行できます。

これは「情報を全部アクティブなコンテキストウィンドウに置き続ける」設計から、「必要になったときだけmemoryファイルを読み返す」設計への転換です。エージェントが数十回、数百回とツールを呼び出すような長時間タスクほど、この転換の効果が大きくなります。複数セッションにまたがる開発タスクで進捗ログをmemoryに残す設計はClaude Memoryツールで複数セッション開発を再開するパターンで扱っており、本記事のcontext editing併用はその進捗ログを書き込むタイミングを「クリアされる前」に前倒しする実装と言えます。

compactionとの違いと使い分け

長時間エージェントのコンテキスト管理には、本記事のcontext editing×memory toolのほかに、サーバーサイドcompactionという選択肢もあります。この2つは仕組みが異なります。

公式ドキュメントは、compactionがアクティブなコンテキストをクライアント側の作り込みなしに小さく保つのに対し、memoryはその要約でも失われては困る情報を保持する役割だと位置付けています。長時間エージェントでは、compactionで会話全体を軽くしつつ、memoryで要約をまたいで残したい情報を守る、という両方の併用も選択肢になります。tool result clearingとcompactionのどちらを選ぶかは、間引きたいのが特定のツール結果だけか、会話全体を要約で圧縮したいかで決まります。

言い換えると、memory toolは「何と組み合わせるか」よりも「クリアや要約の前にどう情報を退避するか」を担う共通のレイヤーです。tool result clearingの粒度で細かく間引く構成でも、compactionで会話全体をまとめて圧縮する構成でも、memoryへ書き出す判断自体はClaude側のプロンプト設計に依存します。どちらの経路を選んでも、memoryファイルの構造(進捗ログ・参照情報・チェックリストなど)を最初に決めておくと、後から読み戻すときの手戻りが減ります。

セキュリティ上の注意

memory toolはクライアントサイドで動くため、パスの検証は自分のハンドラーの責任です。/memoriesディレクトリの外へのアクセスを許すと、パストラバーサルの脆弱性になります。実装の注意点はMemory toolのパストラバーサル対策で扱っています。context editingと併用する場合も、クリア前にmemoryへ書き出す先のパス検証を省略しない設計が必要です。

併用構成では、書き出し先が増える分だけ検証すべき経路も増えます。view・create・str_replace・insert・delete・renameの6コマンドすべてで、Claudeから渡されたパスをそのまま自分のストレージAPIに渡さず、/memoriesプレフィックスを剥がした後の相対パスが親ディレクトリの外へ抜けていないかをハンドラー側で検証します。tool result clearingが頻繁に発火する構成ほどClaudeがmemoryへ書き込む頻度も増えるため、検証漏れが実際に叩かれる機会も比例して増える点は運用上見落としやすいところです。

併用でハマりやすい点

• 書き出しをClaude任せにしすぎる: memory toolは自動で発動する保証がある機能ではなく、Claudeが判断して書き込むかどうかが決まります。本当に失ってはいけない情報については、プロンプトの指示で明示的に「クリアされる前にmemoryへ保存すること」と促す設計が安全です
• 保存先の永続性を勘違いする: memoryファイルの実体はあくまで自分のアプリケーションが管理するストレージです。セッションをまたいで同じmemoryを参照するには、次回以降のリクエストでも同じtoolsエントリを送り、同じハンドラーが同じストアを参照する構成にしておく必要があります
• クリア対象の重複: exclude_toolsでmemoryツール自体をクリア対象から除外し忘れると、memory toolの呼び出し結果そのものが間引かれ、直近のファイル操作の文脈が失われることがあります

よくある質問

memory toolだけでcontext editingを使わないとどうなるか

memory toolはClaudeが自発的にファイルへ書き出す機能で、会話履歴そのものを間引く機能ではありません。Claudeがmemoryへの退避を怠ったツール結果は会話履歴に残り続け、tool result clearingが無いとコンテキストウィンドウの上限に近づいたときに古い情報が意図せず失われるリスクが残ります。

警告はどのタイミングで届くか

公式ドキュメントは「クリアの閾値に近づいたとき」と説明していますが、具体的な残りトークン数や発火の仕組みまでは公開されていません。tool result clearingのtriggerで設定した閾値に近づく挙動と連動していると読めますが、正確な発火条件は公式ページに記載が無いため断定を避けます。

memory toolはClaude 4より前のモデルでも使えるか

公式ドキュメントはmemory toolを「すべてのClaude 4以降のモデルで利用可能」としています。それより前の世代のモデルでは、toolsにmemory toolを含めても機能しません。context editingと併用する場合も、両方が使えるモデルかどうかを先に確認します。