Claude API のメモリツール（Memory tool）の使い方

メモリツール（memory tool）は、Claude が会話をまたいで情報を保存・参照できるようにする Anthropic 提供のツールです。すべてをコンテキストウィンドウに載せ続けるのではなく、学んだことをファイルとして書き出し、必要になったときだけ読み戻す「必要になったときに取り出す（just-in-time）」方式でコンテキストを管理します。

メモリツールとは

メモリツールを有効にすると、Claude は /memories ディレクトリ配下のファイルを作成・読み取り・更新・削除できるようになります。これらのファイルはセッションをまたいで残るため、複数回のエージェント実行にわたってプロジェクトの文脈を保ったり、過去のやり取りで得た判断や指摘を次のタスクに反映したり、時間をかけて知識ベースを育てたりできます。

公式ドキュメントが挙げる主な用途は次の3つです。

複数のエージェントセッションをまたいでプロジェクトの文脈を維持する
過去のやり取り・決定・フィードバックから得た学びを新しいタスクに適用する
時間をかけて知識ベースを構築する

メモリツールは Claude 4 以降のすべてのモデルで利用でき、Messages API では一般提供（GA）されているためベータヘッダーは不要です。

仕組みと前提

重要な前提として、メモリツールはクライアント側で動作します。Claude はファイル操作を「要求」するだけで、実際にその操作を実行するのはあなたのアプリケーションです。保存先や保存方法は自分のインフラで完全に制御できます。

実際の流れは通常のツール使用ループと同じです。

ユーザーが依頼を送る
Claude がまず view コマンドで /memories の中身を確認する（この指示は API 側が自動でシステムプロンプトに付加します）
あなたのアプリがディレクトリ一覧を tool_result ブロックで返す
Claude が関連するファイルを view で読む
アプリがファイル内容を返す
Claude が読み取った内容を踏まえて回答する

/memories というパスはあくまで接頭辞で、あなたのハンドラがそれを実際のストレージ（ユーザーごとのディレクトリ、データベースのキーなど）に対応づけます。後続の会話で同じ tools エントリを送り、ハンドラが同じストアを参照すれば、前回の続きから作業を再開できます。

リクエストへの追加

リクエストへの追加は 1 行です。Anthropic 提供のツールなので、入力スキーマを自分で定義する必要はありません。

{
  "model": "claude-opus-4-8",
  "max_tokens": 2048,
  "messages": [
    { "role": "user", "content": "この問い合わせへの返信を手伝って" }
  ],
  "tools": [
    { "type": "memory_20250818", "name": "memory" }
  ]
}

もう一方の作業は、各メモリコマンドを実行するクライアント側ハンドラの実装です。Python・TypeScript・Java・C# の各 SDK にはメモリツール用のヘルパーが用意されており、ツールインターフェースとツール使用ループを肩代わりします。Python と TypeScript にはローカルファイルシステム実装（BetaLocalFilesystemMemoryTool）も同梱されています。Go と Ruby にはヘルパーが無いため、自前でツール使用ループを回します。

import anthropic
from anthropic.tools import BetaLocalFilesystemMemoryTool

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

runner = client.beta.messages.tool_runner(
    model="claude-opus-4-8",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Acme社はメール連絡を好むと覚えておいて"}],
    tools=[memory],
)

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

ツールコマンド一覧

ハンドラが処理すべきコマンドは 6 種類です。返す文字列は Claude がそのまま読むため、アプリケーションの都合で変えても構いませんが、公式が示す推奨動作は次のとおりです。

view — ディレクトリ一覧、またはファイル内容を行番号つきで返す。view_range（[開始行, 終了行]、終了行に -1 で末尾まで）を任意で受け取る。行番号は 6 文字幅・右寄せ、区切りはタブ、1 始まり。存在しないパスには「The path {path} does not exist. Please provide a valid path.」を返す。
create — file_text でファイルを作成。成功時は「File created successfully at: {path}」。ツール説明上は「作成または上書き」とされているため、既存パスへの create も来る前提で設計する。
str_replace — old_str を new_str に置換（new_str 省略時は削除）。一致しない場合・複数一致する場合はそれぞれ専用のエラー文字列を返す。
insert — insert_line の直後に insert_text を挿入。0 は先頭への挿入。
delete — ファイルまたはディレクトリを再帰的に削除。/memories 自体の削除は拒否する。
rename — old_path を new_path へ改名・移動。移動先が既存なら上書きせずエラーを返す。/memories 自体の改名は拒否する。

エラーを返すときは tool_result に "is_error": true を付け、content にメッセージを入れます。

セキュリティ上の注意

ファイル操作を実際に実行するのはあなたのアプリケーションなので、安全対策は実装側の責任になります。公式ドキュメントは次の点を挙げています。

パストラバーサル対策: /memories/../../secrets.env のような悪意あるパスは /memories の外に到達しうる。すべてのコマンドのすべてのパスを検証し、/memories 始まりであること、正規化後もメモリディレクトリ内に留まることを確認する。../・..\・URLエンコードされた %2e%2e%2f なども弾く。Python の pathlib.Path.resolve() と relative_to() のような言語標準のパス検証機能を使う。
機微情報: Claude は通常、機微な情報をメモリに書くことを避けるが、確実性を高めたい場合は書き込み前に検証・除去する処理を自分で入れる。
サイズ上限: ファイルサイズを監視して上限を設ける。view が返す文字数を制限し、残りは view_range で分割して読ませる。
有効期限: 長期間アクセスされていないメモリファイルを定期的に削除する。

コンテキスト編集との併用

メモリツールは、長時間動くエージェントのコンテキスト管理と組み合わせると効果的です。

コンテキスト編集（context editing）はクライアント側の特定のツール結果をクリアし、コンパクション（compaction）はコンテキストウィンドウの上限に近づいたときにサーバ側で会話全体を要約します。長時間実行するエージェントでは両方を併用し、コンパクションでアクティブなコンテキストを小さく保ちつつ、要約で失われては困る情報をメモリに残す、という役割分担が推奨されています。

複数セッションにまたがるソフトウェア開発では、作業しながら場当たり的にメモリを書くのではなく、最初のセッションで進捗ログ・機能チェックリスト・起動スクリプトへの参照といったファイルを意図的に用意しておき、以降のセッションはそれを読んで状態を復元し、終了前に進捗ログを更新する、というパターンが紹介されています。ポイントは 1 度に 1 機能ずつ進めること、そしてコードを書き終えた時点ではなくエンドツーエンドの検証が通った時点で完了扱いにすることです。

次に読むもの

メモリツールと関係の深いトピックは次のとおりです。

コンテキスト編集 — 会話が伸びたときにツール結果や思考ブロックを自動整理する
Bash ツール / テキストエディタツール — 同じくクライアント側で実行する Anthropic 提供ツール
ツール使用の基本 — tool_use と tool_result の往復の仕組み

本記事は Anthropic 公式ドキュメントの Memory tool ページ（2026年7月19日時点）に基づく非公式の日本語解説です。仕様は更新される場合があるため、実装前に公式ドキュメントで最新をご確認ください。