メモリツール

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

これはジャストインタイムコンテキスト取得の重要なプリミティブです。すべての関連情報を事前にロードするのではなく、エージェントは学習内容をメモリに保存し、必要に応じてそれを取り戻します。これにより、アクティブなコンテキストを現在関連性のあるものに焦点を当てたままにし、すべてを一度にロードするとコンテキストウィンドウを圧倒してしまう長時間実行ワークフローに重要です。より広いパターンについては、効果的なコンテキストエンジニアリングを参照してください。

メモリツールはクライアント側で動作します。データがどこにどのように保存されるかは、独自のインフラストラクチャを通じて制御します。

このフィーチャーに関するフィードバックを共有するには、フィードバックフォームを通じてお問い合わせください。

This feature is eligible for Zero Data Retention (ZDR). When your organization has a ZDR arrangement, data sent through this feature is not stored after the API response is returned.

ユースケース

複数のエージェント実行間でプロジェクトコンテキストを維持する
過去のインタラクション、決定、フィードバックから学習する
時間をかけて知識ベースを構築する
会話間学習を有効にし、Claudeが繰り返されるワークフローで改善できるようにする

仕組み

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

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

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

Claudeにタスクを支援するよう依頼すると、Claudeは最初に自動的にメモリディレクトリをチェックします。典型的なインタラクションは次のようになります：

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

"このカスタマーサービスチケットに対応するのを手伝ってください。"

2. Claudeがメモリディレクトリをチェック：

"カスタマーサービスチケットに対応するのを手伝います。以前のコンテキストについてメモリをチェックさせてください。"

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がメモリを使用して支援：

"カスタマーサービスガイドラインに基づいて、対応を作成するのを手伝うことができます。チケットの詳細を共有してください..."

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

はじめに

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

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

アプリケーションでメモリツール操作を処理するには、各メモリコマンドのハンドラーを実装する必要があります。SDKはメモリツールヘルパーを提供し、ツールインターフェースを処理します。BetaAbstractMemoryTool（Python）をサブクラス化するか、betaMemoryTool（TypeScript）を使用して、独自のメモリバックエンド（ファイルベース、データベース、クラウドストレージ、暗号化ファイルなど）を実装できます。

実装例については、以下を参照してください：

Python: examples/memory/basic.py
TypeScript: examples/tools-helpers-memory.ts

基本的な使用方法

ツールコマンド

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

view

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

{
  "command": "view",
  "path": "/memories",
  "view_range": [1, 10] // オプション：特定の行を表示
}

戻り値

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

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がメモリファイルを散らかしているのを観察する場合、この指示を含めることができます：

注：メモリフォルダを編集するときは、常にその内容を最新の状態に保ち、一貫性があり、整理されていることを確認してください。関連性がなくなったファイルの名前を変更または削除できます。必要な場合を除き、新しいファイルを作成しないでください。

また、Claudeがメモリに何を書き込むかをガイドすることもできます。例えば：「<topic>に関連する情報のみをメモリシステムに書き込んでください。」

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

メモリストアを実装する際の重要なセキュリティ上の懸念事項は以下の通りです：

機密情報

Claudeは通常、機密情報をメモリファイルに書き込むことを拒否します。ただし、潜在的に機密情報を削除する厳密な検証を実装することをお勧めします。

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

メモリファイルサイズを追跡し、ファイルが大きくなりすぎるのを防ぐことを検討してください。メモリ読み取りコマンドが返すことができる最大文字数を追加し、Claudeがコンテンツをページネーションできるようにすることを検討してください。

メモリの有効期限

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

パストラバーサル保護

悪意のあるパス入力は、/memoriesディレクトリの外のファイルにアクセスしようとする可能性があります。実装は、ディレクトリトラバーサル攻撃を防ぐために、すべてのパスを検証する必要があります。

これらのセーフガードを検討してください：

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

エラーハンドリング

メモリツールはテキストエディタツールと同様のエラーハンドリングパターンを使用します。詳細なエラーメッセージと動作については、上記の個別のツールコマンドセクションを参照してください。一般的なエラーには、ファイルが見つからない、パーミッションエラー、無効なパス、重複するテキストマッチが含まれます。

コンテキスト編集統合

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

圧縮との使用

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

長時間実行されるエージェンティックワークフローの場合、両方の使用を検討してください：圧縮はクライアント側のブックキーピングなしでアクティブなコンテキストを管理可能に保ち、メモリは圧縮境界間で重要な情報を永続化し、要約で重要な情報が失われないようにします。

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

複数のエージェントセッションにまたがる長時間実行ソフトウェアプロジェクトの場合、メモリファイルは作業が進むにつれてアドホックに書き込まれるのではなく、意図的にブートストラップする必要があります。以下のパターンはメモリを構造化された復旧メカニズムに変え、各新しいセッションが最後に中断したところから正確に再開できるようにします。

仕組み

初期化セッション： 最初のセッションは、実質的な作業が始まる前にメモリアーティファクトを設定します。これには、進捗ログ（何が完了し、次に何が来るかを追跡）、機能チェックリスト（作業の範囲を定義）、プロジェクトが必要とするスタートアップまたは初期化スクリプトへの参照が含まれます。
後続セッション： 各新しいセッションはそれらのメモリアーティファクトを読み取ることで開始します。これにより、コードベースを再度探索したり、以前の決定をたどり直したりすることなく、数秒でプロジェクトの完全な状態を復旧できます。
セッション終了時の更新： セッションが終了する前に、完了した内容と残っている内容で進捗ログを更新します。これにより、次のセッションが正確な開始点を持つようになります。

重要な原則

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

初期化スクリプト、進捗ファイル構造、gitベースの復旧を含む、このパターンの実践的な詳細なケーススタディについては、長時間実行エージェント用の効果的なハーネスを参照してください。

次のステップ

すべてのツールを参照

Anthropic提供ツールとそのプロパティのディレクトリ。

コンテキスト編集

メモリとともに会話の長さを管理します。

client = anthropic.Anthropic()

message = client.messages.create(
    model="claude-opus-4-7",
    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)