メモリとコンテキスト編集

上級

長時間動作するエージェントには2つの敵があります。会話が終わった瞬間に学んだことを忘れてしまうこと、そしてコンテキストウィンドウが古いツール出力で埋め尽くされ、あふれてしまうことです。Anthropic はそれぞれに対応するプリミティブを1つずつ提供しています — memory tool（永続化）とコンテキスト編集（整理） — そしてこれらは一緒に使われるように設計されています。

What you'll learn

memory tool とは何か — Anthropic ではなく、あなたが実装する /memories にあるクライアント側のファイルストアであること
ハンドラーが応答しなければならない6つのコマンド: view, create, str_replace, insert, delete, rename
配線する際にパストラバーサルの検証が譲れない理由
コンテキストがトークンのしきい値を超えると、コンテキスト編集がどのように古いツール結果を自動的に削除するか
両方を1つのベータヘッダーの下で組み合わせる方法と、キャッシングおよび順序に関する落とし穴

2つの問題、2つのツール

2つのアイデアを頭の中で分けておきましょう。

memory tool = セッションをまたいだ永続化。Claude がファイルを読み書きし、あなたがそれを保存します。
コンテキスト編集 = セッション内での整理。API は、プロンプトが Claude に届く前に、古いツール結果を削除します。

このページは、コストの面では Prompt Caching とトークンエコノミーと対になり、なぜの面では Context Engineering と長時間動作するエージェントハーネスと対になります。

メモリとコンテキストの用語

Enter キーまたはスペースキーでカードを裏返します。左右の矢印キーでカードを移動できます。用語を表示しました。

1 / 5

memory tool はあなたが実装するツール

ここでつまずく人がいます。memory tool を有効にしても、Anthropic がホストするストレージは得られません。これはクライアント側のツールです。Claude は view や create のようなツール呼び出しを発行し、あなたのアプリケーションが、選択した任意のバックエンド（ローカルファイル、データベース、暗号化されたブロブ、クラウドストレージ）に対してそれらを実行し、結果を返します。バイトがどこに存在するかはあなたが所有します（これが、Zero-Data-Retention の対象となる理由でもあります）。

ツールが有効になると、Anthropic は、他のことをする前にメモリディレクトリを確認するよう Claude に指示し、コンテキストがリセットされても何も失われないよう作業中に進捗を記録するよう指示するシステム命令を注入します。

ステップ 1 — ツールを有効にする

ツールをリクエストに追加します。タイプ文字列は日付付きバージョンの memory_20250818 です。

Python
TypeScript

import anthropic

client = anthropic.Anthropic()

message = client.messages.create(
    model="claude-opus-5",
    max_tokens=2048,
    messages=[{"role": "user", "content": "Help me respond to this support ticket."}],
    tools=[{"type": "memory_20250818", "name": "memory"}],
)

print(message)

import Anthropic from "@anthropic-ai/sdk";

const anthropic = new Anthropic();

const message = await anthropic.messages.create({
  model: "claude-opus-5",
  max_tokens: 2048,
  messages: [{ role: "user", content: "Help me respond to this support ticket." }],
  tools: [{ type: "memory_20250818", name: "memory" }],
});

console.log(message);

公式 SDK にはメモリのヘルパーが付属しているので、ツールインターフェースを自前で組み立てる必要はありません — BetaAbstractMemoryTool（Python、C#）をサブクラス化するか、betaMemoryTool（TypeScript）を使うか、BetaMemoryToolHandler（Java）を実装します。これらは、ストレージを差し込めるクリーンなフックを提供します。

ステップ 2 — 6つのコマンドに応答する

ハンドラーはこれらを実装しなければなりません。Claude が期待して返ってくる文字列は厳密です — モデルが結果を正しく解釈できるよう、それらに一致させてください。

Guided walkthrough1 of 6

ディレクトリの一覧を返す（最大2階層分の深さのファイルを、人間が読めるサイズ付きで）か、ファイルの内容を1始まりの行番号付きで返します。一部を読むためのオプションの view_range が使えます。

ディレクトリの実際の view は、次のようなものを返します — モデルが解析するよう訓練されている、リテラルなヘッダーとタブ区切りのサイズに注目してください。

Here're the files and directories up to 2 levels deep in /memories, excluding hidden items and node_modules:
0K	/memories
5K	/memories/customer_service_guidelines.xml
0K	/memories/refund_policies.xml

ステップ 3 — パスをロックダウンする（これを飛ばさないこと）

memory tool により、モデルは任意のパス文字列を発行できます。汚染された会話やプロンプトインジェクションのペイロードは、/memories から脱出して、あなたのマシン上の他の場所にあるファイルを読んだり上書きしたりしようとする可能性があります。入ってくるすべてのパスを敵対的なものとして扱ってください。

Watch out

/memories の内部に解決されないパスはすべて拒否します。
チェックの前に正規化します — Python では Path(p).resolve() の後に、.relative_to(memories_root) が例外を発生させないことを確認します。
../、..\、および %2e%2e%2f のような URL エンコードされたトラバーサルをブロックします。
暴走したエージェントがディスクを使い果たしたり次のプロンプトを膨張させたりできないよう、ファイルサイズと読み取り長さに上限を設けます。

このバリデーターがすべての決め手です — 他の何をリリースするよりも前に、これを固定してテストしてください。

パストラバーサルガード（Python）

from pathlib import Path

MEMORY_ROOT = Path("/srv/agent/memories").resolve()

def safe_path(requested: str) -> Path:
  # Map the model's /memories/... onto your real root, then prove containment.
  rel = requested.removeprefix("/memories").lstrip("/")
  candidate = (MEMORY_ROOT / rel).resolve()
  candidate.relative_to(MEMORY_ROOT)  # raises ValueError if it escaped
  return candidate

コンテキスト編集はウィンドウのあふれを防ぐ

メモリは忘却を解決します。その逆の問題 — 40回前のウェブ検索からの古い tool_result ブロックで詰まったコンテキストウィンドウ — を解決するのがコンテキスト編集です。プロンプトがトークンのしきい値を超えると、API は、プロンプトがモデルに送られる前に、最も古いツール結果を削除します（それらが削除されたことを Claude が分かるよう短いプレースホルダーに置き換えます）。あなたのクライアントは完全で未編集の履歴を保持します。トリミングされるのはモデルに届くものだけです。

これはベータヘッダーに乗ります。

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

context_management.edits 配列で設定します。主な戦略は clear_tool_uses_20250919 です。

Python
TypeScript

message = client.beta.messages.create(
    model="claude-opus-5",
    max_tokens=2048,
    betas=["context-management-2025-06-27"],
    messages=[...],
    tools=[{"type": "memory_20250818", "name": "memory"}],
    context_management={
        "edits": [
            {
                "type": "clear_tool_uses_20250919",
                "trigger": {"type": "input_tokens", "value": 30000},  # start clearing past 30k
                "keep": {"type": "tool_uses", "value": 3},            # always keep the last 3
                "clear_at_least": {"type": "input_tokens", "value": 5000},
                "exclude_tools": ["memory"],                          # never clear memory calls
                "clear_tool_inputs": False,                           # keep the call args, drop results
            }
        ]
    },
)

const message = await anthropic.beta.messages.create({
  model: "claude-opus-5",
  max_tokens: 2048,
  betas: ["context-management-2025-06-27"],
  messages: [...],
  tools: [{ type: "memory_20250818", name: "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_tool_inputs: false,
      },
    ],
  },
});

各ノブの意味:

パラメータ	デフォルト	何を制御するか
`trigger`	100,000 入力トークン	削除が始まるタイミング
`keep`	3 tool uses	最近のツール使用／結果のペアをいくつ常に保持するか
`clear_at_least`	なし	1回の発動あたり解放される最小トークン数 — キャッシュの無効化が本当に見合うよう使います
`exclude_tools`	なし	決して削除されないツール（例: `memory`、`web_search`）
`clear_tool_inputs`	`false`	結果だけでなく、ツールの呼び出し引数も削除するかどうか

レスポンスは、context_management.applied_edits の下で何をしたかを伝えます — 例えば cleared_tool_uses や cleared_input_tokens — ので、どれだけ回収されたかをログに記録できます。

兄弟戦略として、古い拡張思考ブロックを整理する clear_thinking_20251015 があります。両方を使う場合は、edits 配列で**clear_thinking_20251015 を先にリストしてください**。

Pro tip

ツール結果の削除は、その削除地点におけるプロンプトキャッシュのプレフィックスを無効化します — clear_at_least と組み合わせて、意味のある量を解放するときだけその無効化のコストを払うようにします。
exclude_tools: ["memory"] が通常の手段です。エージェント自身のノートは永続化させたく、古い検索結果と一緒に流し去られたくはないからです。
コンテキスト編集（クライアント側のトリミング）とコンパクション（サーバー側の要約）は別個の機能です — 非常に長い実行では両方を重ねて使えます。

なぜ両方を組み合わせるのか — 数値

両方を一緒に使うと、エージェントは単一のコンテキストウィンドウをはるかに超えて実行できます。コンテキスト編集がライブのウィンドウを軽量に保ち、重要なものは削除される前にメモリに書き込まれます。Anthropic は、メモリとコンテキスト編集を組み合わせることで、エージェント検索の評価で 39% の改善が得られ、コンテキスト編集だけでも100ターンのウェブ検索テストでトークン使用量を 84% 削減したと報告しています。

うまくいくパターン: マルチセッションのプロジェクトログ

メモリの最もきれいな使い方は、その場限りでファイルを書くのではなく、意図的にブートストラップすることです。

Guided walkthrough1 of 4

実際の作業の前に、進捗ログ、機能チェックリスト、そしてプロジェクトが必要とする起動スクリプトを指すノートを書きます。

理解度を確認する

Check yourself

0/3

memory tool のデータは実際にはどこに保存されますか？
コンテキスト編集の clear_tool_uses_20250919 戦略は何を削除しますか？
memory tool が受け取るすべてのパスを検証しなければならないのはなぜですか？

出典とさらなる参考資料

memory tool — Claude API ドキュメント — ツールタイプ memory_20250818、6つのコマンド、そしてセキュリティガイダンス。
コンテキスト編集 — Claude API ドキュメント — context-management-2025-06-27 ベータ、戦略フィールド、そしてデフォルト値。
Claude Developer Platform でのコンテキスト管理 — 39% / 84% のベンチマーク数値が載ったアナウンスメント。
AI エージェントのための効果的なコンテキストエンジニアリング — メモリがそのために作られたジャストインタイム取得パターン。
長時間動作するエージェントのための効果的なハーネス — マルチセッションのプロジェクトログのケーススタディ。
AILmanac の関連記事: Context Engineering · 長時間動作するエージェントハーネス · Prompt Caching · Tool Use

2つの問題、2つのツール​

memory tool はあなたが実装するツール​

ステップ 1 — ツールを有効にする​

ステップ 2 — 6つのコマンドに応答する​

ステップ 3 — パスをロックダウンする（これを飛ばさないこと）​