メモリツール

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

これは「just-in-time context retrieval」（ジャストインタイムコンテキスト取得）のための重要な基本要素です。関連するすべての情報を事前に読み込むのではなく、エージェントは学習した内容をメモリに保存し、必要に応じて取り出します。これにより、アクティブなコンテキストを現在関連する内容に集中させることができます。これは、すべてを一度に読み込むとコンテキストウィンドウが圧迫されてしまうような長時間実行されるワークフローにとって極めて重要です。より広範なパターンについては、Effective context engineeringを参照してください。

メモリツールはクライアント側で動作します。データの保存場所と保存方法は、独自のインフラストラクチャを通じて制御できます。



ユースケース

• 複数のエージェント実行にわたってプロジェクトのコンテキストを維持する
• 過去のやり取り、決定、フィードバックから学習する
• 時間をかけてナレッジベースを構築する
• Claudeが繰り返し発生するワークフローで改善していく、会話をまたいだ学習を可能にする



仕組み

有効にすると、Claudeはタスクを開始する前に自動的にメモリディレクトリを確認します。Claudeは/memoriesディレクトリ内のファイルを作成、読み取り、更新、削除して、作業中に学習した内容を保存し、将来の会話でそれらのメモリを参照して、類似のタスクをより効果的に処理したり、前回中断した場所から再開したりできます。

これはクライアント側のツールであるため、Claudeはメモリ操作を実行するためにツール呼び出しを行い、アプリケーションがそれらの操作をローカルで実行します。これにより、メモリの保存場所と保存方法を完全に制御できます。セキュリティのため、すべてのメモリ操作を/memoriesディレクトリに制限する必要があります。



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

Claudeにタスクの支援を依頼すると、Claudeは最初に自動的にメモリディレクトリを確認します。典型的なやり取りは次のようになります。

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..."

モデルのサポートについては、ツールリファレンスを参照してください。



はじめに

メモリツールを使用するには：

1. リクエストにメモリツールを追加する
2. メモリ操作用のクライアント側ハンドラーを実装する



基本的な使用方法

client = anthropic.Anthropic()

message = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=2048,
    messages=[
        {
            "role": "user",
            "content": "I'm working on a Python web scraper that keeps crashing with a timeout error. Here's the problematic function:\n\n```python\ndef fetch_page(url, retries=3):\n    for i in range(retries):\n        try:\n            response = requests.get(url, timeout=5)\n            return response.text\n        except requests.exceptions.Timeout:\n            if i == retries - 1:\n                raise\n            time.sleep(1)\n```\n\nPlease help me debug this.",
        }
    ],
    tools=[{"type": "memory_20250818", "name": "memory"}],
)

print(message)



ツールコマンド

クライアント側の実装では、これらのメモリツールコマンドを処理する必要があります。これらの仕様はClaudeが最も慣れている推奨動作を説明していますが、ユースケースに応じて実装を変更し、必要な文字列を返すことができます。



view

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

{
  "command": "view",
  "path": "/memories",
  "view_range": [1, 10] // Optional: view specific lines
}



戻り値

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

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

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

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

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



エラー処理

• ファイル/ディレクトリが存在しない："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"



str_replace

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

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



戻り値

• 成功："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"
}



戻り値

• 成功："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"



ディレクトリの処理

ディレクトリとそのすべての内容を再帰的に削除します。



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"



ディレクトリの処理

ディレクトリの名前を変更します。



プロンプトのガイダンス

メモリツールが有効になっている場合、この指示がシステムプロンプトに自動的に含まれます：

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が雑然としたメモリファイルを作成していることに気づいた場合は、次の指示を含めることができます：

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がコンテンツをページネーションできるようにすることを検討してください。



メモリの有効期限

長期間アクセスされていないメモリファイルを定期的にクリアすることを検討してください。



パストラバーサル保護

次の保護策を検討してください：

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



エラー処理

メモリツールは、テキストエディタツールと同様のエラー処理パターンを使用します。詳細なエラーメッセージと動作については、上記の各ツールコマンドのセクションを参照してください。一般的なエラーには、ファイルが見つからない、権限エラー、無効なパス、重複テキストの一致などがあります。



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

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



コンパクションとの併用

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

長時間実行されるエージェントワークフローでは、両方の使用を検討してください。コンパクションはクライアント側の管理作業なしでアクティブなコンテキストを管理可能な状態に保ち、メモリはコンパクションの境界を越えて重要な情報を永続化するため、要約で重要な内容が失われることはありません。



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

複数のエージェントセッションにまたがる長期的なソフトウェアプロジェクトでは、メモリファイルは作業の進行に応じてその場しのぎで書き込むのではなく、意図的にブートストラップする必要があります。以下のパターンは、メモリを構造化された復旧メカニズムに変え、各新しいセッションが前回のセッションが終了した場所から正確に再開できるようにします。



仕組み

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

2. 後続のセッション： 各新しいセッションは、それらのメモリアーティファクトを読み取ることから始まります。これにより、コードベースを再探索したり、以前の決定をたどり直したりすることなく、数秒でプロジェクトの完全な状態を復元できます。

3. セッション終了時の更新： セッションが終了する前に、完了した内容と残っている内容で進捗ログを更新します。これにより、次のセッションが正確な開始点を持つことが保証されます。



重要な原則

一度に1つの機能に取り組みます。コードが書かれた直後ではなく、エンドツーエンドの検証で動作が確認された後にのみ、機能を完了としてマークします。これにより、進捗ログの信頼性が保たれ、セッションをまたいでスコープクリープが累積するのを防ぎます。



次のステップ