メモリツール

メモリツールを使用すると、Claudeはメモリファイルのディレクトリに情報を保存し、会話をまたいでその情報を取得できます。Claudeはセッション間で永続化されるファイルを作成、読み取り、更新、削除できます。これにより、すべてを「context window」（コンテキストウィンドウ）に保持しなくても、時間をかけて知識を蓄積できます。

メモリは「just-in-time context retrieval」（ジャストインタイムのコンテキスト取得）をサポートします。エージェントは関連するすべての情報を最初に読み込むのではなく、学んだことをメモリファイルに記録し、必要に応じて読み返します。これにより、アクティブなコンテキストを現在のタスクに集中させられます。この点は、放置するとコンテキストウィンドウを圧迫してしまう長時間実行セッションで重要です。このパターンの全体像については、Effective context engineeringを参照してください。

メモリツールは「client-side」（クライアントサイド）で動作します。Claudeがファイル操作をリクエストし、アプリケーションがそれを実行します。データをどこにどのように保存するかは、独自のインフラストラクチャを通じて制御できます。

ユースケース

• 複数のエージェントセッションにわたってプロジェクトのコンテキストを維持する
• 過去のやり取り、決定、フィードバックから得た教訓を新しいタスクに適用する
• 時間をかけてナレッジベースを構築する

仕組み

メモリツールが有効になっている場合、Claudeはタスクを開始する前に自動的にメモリディレクトリを確認します。作業中、Claudeは学んだことを/memories配下のファイルに保存し、後の会話でそれらを読み返して以前の作業を継続します。

メモリツールはクライアントサイドで動作するため、Claudeはメモリ操作をリクエストするだけです。アプリケーションは、自身が管理するストレージに対して各リクエストを実行し、その結果をtool_resultブロックで返します（ツール呼び出しの処理を参照）。/memoriesパスはプレフィックスであり、ハンドラーがこれをユーザーごとのディレクトリやデータベースのキーなどの実際のストレージにマッピングします。メモリは完全にアプリケーション内に存在します。後の会話が同じtoolsエントリを送信し、ハンドラーが同じストアを提供すれば、その会話は同じメモリから継続されます。セキュリティのため、すべてのメモリ操作を/memoriesディレクトリに制限してください（パストラバーサル対策を参照）。

例：メモリツール呼び出しの仕組み

典型的なやり取りは次のようになります。

1. ユーザーのリクエスト：

"Help me respond to this customer service ticket."

2. Claudeがメモリディレクトリを確認します：

"I'll help you respond to the customer service ticket. Let me check my memory for any previous context."

Claudeがメモリツールを呼び出します：

{
  "type": "tool_use",
  "id": "toolu_01C4D5E6F7G8H9I0J1K2L3M4",
  "name": "memory",
  "input": {
    "command": "view",
    "path": "/memories"
  }
}

3. アプリケーションがディレクトリの内容を返します：

{
  "type": "tool_result",
  "tool_use_id": "toolu_01C4D5E6F7G8H9I0J1K2L3M4",
  "content": "Here're the files and directories up to 2 levels deep in /memories, excluding hidden items and node_modules:\n4.0K\t/memories\n1.5K\t/memories/customer_service_guidelines.xml\n2.0K\t/memories/refund_policies.xml"
}

4. Claudeが関連するファイルを読み取ります：

{
  "type": "tool_use",
  "id": "toolu_01D5E6F7G8H9I0J1K2L3M4N5",
  "name": "memory",
  "input": {
    "command": "view",
    "path": "/memories/customer_service_guidelines.xml"
  }
}

5. アプリケーションがファイルの内容を返します：

{
  "type": "tool_result",
  "tool_use_id": "toolu_01D5E6F7G8H9I0J1K2L3M4N5",
  "content": "Here's the content of /memories/customer_service_guidelines.xml with line numbers:\n     1\t<guidelines>\n     2\t<addressing_customers>\n     3\t- Always address customers by their first name\n     4\t- Use empathetic language\n..."
}

6. Claudeがメモリを活用して支援します：

"Based on your customer service guidelines, I can help you craft a response. Please share the ticket details..."

メモリツールは、すべてのClaude 4以降のモデルで利用できます。Anthropicが提供するツールの完全な一覧については、ツールリファレンスを参照してください。

はじめに

メモリツールの使用は2つのステップで行います。

1. リクエストにメモリツールを追加します。toolsエントリ{"type": "memory_20250818", "name": "memory"}が設定のすべてです。nameはmemoryである必要があり、Anthropicが提供するツールについては入力スキーマを定義する必要はありません。
2. 各メモリコマンドに対するクライアントサイドのハンドラーを実装します。ハンドラーは/memories外のパスを拒否する必要があるため、実装する前にパストラバーサル対策をお読みください。

基本的な使い方

client = anthropic.Anthropic()

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

print(message)

メモリハンドラーの実装

前述のようなリクエストに対するClaudeの応答は、view /memoriesなどのメモリ操作をリクエストするtool_useブロックで終わります。アプリケーションはその操作を実行して結果をtool_resultブロックで返し、Claudeが処理を続行できるように会話を送り返します。これが標準的なツール使用ループです。

4つのSDKが、ツールインターフェースとループを処理するメモリツールヘルパーを提供しています。BetaAbstractMemoryToolをサブクラス化する（PythonおよびC#）、betaMemoryToolを使用する（TypeScript）、またはBetaMemoryToolHandlerを実装する（Java）ことで、ディスク上のファイル、データベース、クラウドストレージ、暗号化ファイルなど、独自のストレージでメモリを実装できます。PythonとTypeScriptには、すぐに使えるローカルファイルシステム実装であるBetaLocalFilesystemMemoryToolも同梱されています。メモリツール自体はベータヘッダーを必要としませんが、ヘルパーとツールランナーの機能は各SDKのベータ名前空間に含まれています。GoとRubyのSDKにはメモリヘルパーがないため、これらの例ではツール使用ループを自前で実行します。また、PHPはハンドラーのクロージャを汎用のBetaRunnableToolでラップします。これら3つはいずれもインメモリストアを使用しており、独自のストレージに置き換えて使用します。

import anthropic
from anthropic.tools import BetaLocalFilesystemMemoryTool

client = anthropic.Anthropic()
memory = BetaLocalFilesystemMemoryTool(base_path="./memory")

runner = client.beta.messages.tool_runner(
    model="claude-opus-5-5",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": "Remember that customer Acme Corp prefers email follow-ups.",
        }
    ],
    tools=[memory],
)

final_message = runner.until_done()
print(final_message.content)

Go、PHP、Rubyの例では、インメモリストアを使用することで例を自己完結させています。各ストアはtool_useブロックのinput内のcommandフィールドに基づいて処理を振り分け、ツールコマンドで説明されている文字列を返します。本番環境のハンドラーには、これらのデモ用ストアでは省略されているパス検証も必要です。各SDK独自の完全な例については、以下を参照してください。

• Python：examples/memory/basic.py
• TypeScript：examples/tools-helpers-memory.ts
• C#：MemoryToolExample
• Java：BetaMemoryToolExample.java

ツールコマンド

クライアントサイドの実装では、以下のコマンドを処理する必要があります。これらの仕様は推奨される動作と戻り値の文字列を示しています。Claudeはツール結果に含まれるテキストをそのまま読み取るため、アプリケーションで必要であれば異なる文字列を返すこともできます。

view

ディレクトリの内容、またはファイルの内容（オプションで行範囲を指定可能）を表示します：

{
  "command": "view",
  "path": "/memories/notes.txt",
  "view_range": [1, 10]
}

view_rangeはオプションで、テキストファイルの表示に適用されます。[start_line, end_line]はその範囲の行を返し、[start_line, -1]はstart_lineからファイルの末尾までのすべてを返します。

戻り値

ディレクトリの場合： ファイルとディレクトリをそのサイズとともに示す一覧を返します：

Here're the files and directories up to 2 levels deep in {path}, excluding hidden items and node_modules:
{size}\t{path}
{size}\t{path}/{filename1}
{size}\t{path}/{filename2}

• 最大2階層までのファイルを一覧表示します
• 人間が読みやすい形式でサイズを表示します（例：5.5K、1.2M）
• 隠しアイテム（.で始まるファイル）とnode_modulesを除外します
• サイズとパスの間にタブ文字を使用します

空のストアに対する/memoriesの最初のviewはエラーではありません。SDKのローカルファイルシステム用メモリツール（BetaLocalFilesystemMemoryTool）は、Claudeの最初の呼び出しの前にメモリルートを作成し、一覧のヘッダーに続けて、空のディレクトリ自体を示すサイズとパスの行を1行だけ返します。

ファイルの場合： ヘッダーと行番号付きでファイルの内容を返します：

Here's the content of {path} with line numbers:
{line_numbers}{tab}{content}

行番号の書式：

• 幅： 6文字、スペースで埋めて右揃え
• 区切り文字： 行番号と内容の間にタブ文字
• インデックス： 1始まり（最初の行は1行目）
• 行数の上限： 999,999行を超えるファイルはエラーを返す必要があります："File {path} exceeds maximum line limit of 999,999 lines."

出力例：

Here's the content of /memories/notes.txt with line numbers:
     1	Hello World
     2	This is line two
    10	Line ten
   100	Line one hundred

Claudeのツール説明には、viewが画像ファイル（.jpg、.jpeg、.png）を表示すること、および16,000文字を超えるファイルのテキスト表示を切り詰めることも記載されています。画像パスに対するview呼び出しや、長いファイルに対する範囲指定付きの追加の表示が行われることを想定してください。

エラー処理

• ファイルまたはディレクトリが存在しない場合： "The path {path} does not exist. Please provide a valid path."

create

新しいファイルを作成します：

{
  "command": "create",
  "path": "/memories/notes.txt",
  "file_text": "Meeting notes:\n- Discussed project timeline\n- Next steps defined\n"
}

戻り値

• 成功時： "File created successfully at: {path}"

エラー処理

• ファイルがすでに存在する場合： "Error: File {path} already exists"

Claudeのツール説明ではcreateがファイルを「作成または上書きする」とされているため、すでに存在するパスに対するcreate呼び出しが行われることを想定してください。エラーを返すのがリファレンスの動作ですが、代わりに上書きすることも有効な実装上の選択です。

str_replace

ファイル内のテキストを置換します：

{
  "command": "str_replace",
  "path": "/memories/preferences.txt",
  "old_str": "Favorite color: blue",
  "new_str": "Favorite color: green"
}

str_replaceではnew_strはオプションです。省略した場合、old_strは置換されずに削除されます。

戻り値

• 成功時： "The memory file has been edited."に続けて、編集されたファイルの行番号付きスニペット

エラー処理

• ファイルが存在しない場合： "Error: The path {path} does not exist. Please provide a valid path."
• テキストが見つからない場合： "No replacement was performed, old_str `\{old_str}` did not appear verbatim in {path}."
• テキストが重複している場合： old_strが複数回出現する場合は、次を返します："No replacement was performed. Multiple occurrences of old_str `\{old_str}` in lines: {line_numbers}. Please ensure it is unique"

ディレクトリの扱い

パスがディレクトリの場合は、「ファイルが存在しない」エラーを返します。

insert

特定の行にテキストを挿入します：

{
  "command": "insert",
  "path": "/memories/todo.txt",
  "insert_line": 2,
  "insert_text": "- Review memory tool documentation\n"
}

insert_textはinsert_line行目の後に挿入され、0を指定するとファイルの先頭に挿入されます。

戻り値

• 成功時： "The file {path} has been edited."

エラー処理

• ファイルが存在しない場合： "Error: The path {path} does not exist"
• 無効な行番号の場合： "Error: Invalid `insert_line` parameter: {insert_line}. It should be within the range of lines of the file: [0, {n_lines}]"

ディレクトリの扱い

パスがディレクトリの場合は、「ファイルが存在しない」エラーを返します。

delete

ファイルまたはディレクトリを削除します：

{
  "command": "delete",
  "path": "/memories/old_file.txt"
}

戻り値

• 成功時： "Successfully deleted {path}"

エラー処理

• ファイルまたはディレクトリが存在しない場合： "Error: The path {path} does not exist"

ディレクトリの扱い

ディレクトリとそのすべての内容を再帰的に削除します。ツール説明ではClaudeに対して/memoriesディレクトリ自体は削除できないと伝えているため、パスがメモリルートであるdeleteは拒否してください。

rename

ファイルまたはディレクトリの名前を変更、または移動します：

{
  "command": "rename",
  "old_path": "/memories/draft.txt",
  "new_path": "/memories/final.txt"
}

戻り値

• 成功時： "Successfully renamed {old_path} to {new_path}"

エラー処理

• 移動元が存在しない場合： "Error: The path {old_path} does not exist"
• 移動先がすでに存在する場合： エラーを返します（上書きしないでください）："Error: The destination {new_path} already exists"

ディレクトリの扱い

ディレクトリの名前を変更します。ツール説明ではClaudeに対して/memoriesディレクトリ自体の名前は変更できないと伝えているため、old_pathがメモリルートであるrenameは拒否してください。

プロンプトのガイダンス

リクエストのtoolsにメモリツールが含まれている場合、APIは次の指示を自動的にシステムプロンプトに追加します。自分で送信する必要はありません：

IMPORTANT: ALWAYS VIEW YOUR MEMORY DIRECTORY BEFORE DOING ANYTHING ELSE.
MEMORY PROTOCOL:
1. Use the `view` command of your `memory` tool to check for earlier progress.
2. ... (work on the task) ...
   - As you make progress, record status / progress / thoughts etc in your memory.
ASSUME INTERRUPTION: Your context window might be reset at any moment, so you risk losing any progress that is not recorded in your memory directory.

Claudeのツール説明ではすでにメモリディレクトリを整理された状態に保つよう指示しているため、その指示を繰り返す必要はありません。それでもClaudeが雑然としたメモリファイルを作成する場合は、プロンプトで指示を補強できます：

Note: when editing your memory folder, always try to keep its content up-to-date, coherent and organized. You can rename or delete files that are no longer relevant. Do not create new files unless necessary.

Claudeがメモリに書き込む内容を誘導することもできます。例：「メモリシステムには <topic> に関連する情報のみを書き留めてください。」

セキュリティに関する考慮事項

Claudeがリクエストするすべてのファイル操作はアプリケーションが実行するため、以下の安全対策はアプリケーション側の責任となります。

機密情報

Claudeは通常、機密情報をメモリファイルに書き込むことを拒否します。より強力な保証が必要な場合は、ハンドラーがファイルを書き込む前に機密データを除去する検証処理を追加してください。

ファイルストレージのサイズ

メモリファイルのサイズを追跡し、ファイルが大きくなりすぎないよう上限を設けてください。viewコマンドが返す文字数に上限を設け、残りの部分はClaudeがview_rangeでページングして読めるようにすることも検討してください。

メモリの有効期限

長期間アクセスされていないメモリファイルは定期的に削除してください。

パストラバーサル対策

以下の安全対策を検討してください：

• すべてのパスが/memoriesで始まることを検証する
• パスを正規形に解決し、メモリディレクトリ内に収まっていることを確認する
• ../、..\\などのシーケンスやその他のトラバーサルパターンを含むパスを拒否する
• URLエンコードされたトラバーサルシーケンス（%2e%2e%2f）に注意する
• 使用する言語に組み込まれたパスセキュリティユーティリティを使用する（例：Pythonのpathlib.Path.resolve()とrelative_to()）

エラー処理

メモリツールは、テキストエディタツールと同様のエラー処理パターンを使用します。各コマンドのエラーメッセージはツールコマンドに記載されています。Claudeにエラーを返すには、ツール結果のis_errorをtrueに設定し、メッセージをcontentに入れます：

{
  "type": "tool_result",
  "tool_use_id": "toolu_01C4D5E6F7G8H9I0J1K2L3M4",
  "content": "Error: The path /memories/notes.txt does not exist",
  "is_error": true
}

コンテキスト編集との統合

メモリツールは「context editing」（コンテキスト編集）と組み合わせて、長時間実行される会話を管理できます。詳細については、コンテキスト編集を参照してください。

コンパクションとの併用

メモリツールは、古い会話コンテキストをサーバーサイドで要約する「compaction」（コンパクション）と組み合わせることもできます。コンテキスト編集は、クライアント上で特定のツール結果をクリアします。コンパクションは、会話がコンテキストウィンドウの上限に近づくと、サーバー上で会話全体を自動的に要約します。

長時間実行されるエージェントでは、両方の使用を検討してください。コンパクションはクライアントサイドでの管理作業なしにアクティブなコンテキストを小さく保ち、メモリは要約後も残す必要がある情報を保持します。

マルチセッションのソフトウェア開発パターン

複数のエージェントセッションにまたがるソフトウェアプロジェクトでは、作業の進行に合わせて場当たり的にメモリファイルを書き込むのではなく、意図的にメモリファイルを設計してください。次のパターンでは、メモリを復旧メカニズムとして活用します。新しいセッションはそれぞれ、前回のセッションが記録した状態から再開します。

パターンの仕組み

1. 初期化セッション： 最初のセッションでは、実質的な作業を始める前にメモリファイルをセットアップします。これには、進捗ログ（完了した作業と次に行う作業を追跡）、機能チェックリスト（作業範囲を定義）、およびプロジェクトに必要な起動スクリプトや初期化スクリプトへの参照が含まれます。

2. 後続のセッション： 新しいセッションはそれぞれ、まずこれらのメモリファイルを読み込みます。これにより、コードベースを再調査したり以前の決定をたどり直したりすることなく、プロジェクトの状態を復元できます。

3. セッション終了時の更新： セッションを終了する前に、完了した作業と残っている作業で進捗ログを更新します。これにより、次のセッションが正確な出発点を持てるようになります。

重要な原則

一度に1つの機能に取り組んでください。機能を完了としてマークするのは、コードを書いた時点ではなく、エンドツーエンドの検証で動作が確認された後にしてください。これにより、セッションをまたいで進捗ログの正確さが保たれます。

次のステップ