メモリツール

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

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

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

ユースケース

• 複数のエージェント実行間でプロジェクトコンテキストを維持する
• 過去のインタラクション、決定、フィードバックから学ぶ
• 時間をかけてナレッジベースを構築する
• 会話間学習を有効にして、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 がメモリを使用して支援：

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

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

はじめに

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

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

基本的な使用方法

ツールコマンド

クライアント側の実装は、これらのメモリツールコマンドを処理する必要があります。これらの仕様は 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 で始まることを検証する
• パスを正規形に解決し、メモリディレクトリ内に留まることを確認する
• ../、..\、またはその他のトラバーサルパターンを含むパスを拒否する
• URL エンコードされたトラバーサルシーケンス（%2e%2e%2f）を監視する
• 言語の組み込みパスセキュリティユーティリティを使用する（例：Python の pathlib.Path.resolve() と relative_to()）

エラー処理

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

コンテキスト編集統合

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

圧縮での使用

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

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

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

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

仕組み

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

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

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

重要な原則

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

次のステップ