【AI】Claude APIのMemory Toolで記憶を永続化する方法

当ページのリンクには広告が含まれています。
いずみ

こんな悩みを解決できる記事を書きました!

僕は現役フリーランスエンジニア(歴年)で、資格は個保有しています。

Claude APIで会話をまたいで情報を覚えさせたい」とお考えではありませんか?

長時間動くエージェントを作ると、文脈ウィンドウに必要な情報を全部は載せきれなくなります。

Memory Toolを使うと、Claudeが学んだ内容をファイルとして保存し、次の会話で読み戻せます

いずみ

Memory Toolはツール定義を1つ足すだけで有効になります。

保存処理はクライアントサイドで動くので、保存先はアプリ側で自由に選べます。

ということで、本記事ではClaude APIのMemory Toolで記憶を永続化する方法を解説します。

いずみ

すぐ読み終わるので、ぜひ最後まで読んでくださいませ。

スクロールできます
【当サイト】おすすめフリーランスエージェント3選
エージェント評価ポイント公式サイト
レバテックフリーランス

5.0
業界最大級のエージェント。
高単価案件が豊富。
公式
Midworks

4.8
満足度調査で
3年連続3冠を達成。
公式
ITプロパートナーズ

4.6
週2〜3向けの案件が豊富。公式
執筆者/監修者
  • フリーランスエンジニア(保有資格個、企業と直接契約
  • ブログ・アフィリエイト歴7年(2018年〜)
  • ブランドせどりで月利50万円⇨脱サラ
  • 投資(仮想通貨・FX)歴7年(2018年〜)
  • X(旧Twitter)フォロワー約1,900人
  • 運営者情報はこちら
いずみです
目次

【AI】Claude APIのMemory Toolで記憶を永続化する方法

早速、Claude APIのMemory Toolで記憶を永続化する方法を見ていきます。

Memory Toolの仕組み

Memory Toolは、会話をまたいで情報をファイルとして保存・参照するためのツールです。

Claude 4以降のモデルで利用できます。

大きな特徴は、保存処理がクライアントサイドで動く点です。

Claudeはファイル操作を要求するだけで、実際の読み書きはアプリ側のハンドラが実行します。

保存先のパスは/memoriesから始まるプレフィックスで、実体はアプリ側が用意するストレージ(ディスク・データベース・クラウドストレージなど)に対応づけます。

Claudeが扱うコマンドはviewcreatestr_replaceinsertdeleterenameの6種類です。

ツール定義は{"type": "memory_20250818", "name": "memory"}だけで、入力スキーマを自分で定義する必要はありません。

いずみ

Anthropic側にメモリが保存されるわけではありません。

永続化の責任はアプリ側にあると考えると分かりやすいです。

事前準備

Memory Toolを試す前に、SDKとAPIキーを用意します。

STEP
Anthropic Python SDKをインストールする

pipでインストールします。

pip install anthropic
STEP
APIキーを環境変数に設定する

Anthropic ConsoleでAPIキーを発行し、環境変数に設定します。

export ANTHROPIC_API_KEY="your_api_key"

SDKのヘルパーで最短で動かす

Python SDKには、ローカルファイルシステムをそのまま使うBetaLocalFilesystemMemoryToolと、ツール実行ループを回すtool_runnerが用意されています。

ヘルパーを使うと、ハンドラを書かずに動作を確認できます。

import anthropic
from anthropic.tools import BetaLocalFilesystemMemoryTool

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

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

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

base_pathで指定したディレクトリに、Claudeが作成したメモリファイルが書き込まれます。

runner.until_done()が、Claudeのメモリ操作要求とハンドラ実行の往復を最後まで進めます。

いずみ

まずBetaLocalFilesystemMemoryToolで挙動を掴んでから、本番のストレージに差し替える流れがおすすめです。

ハンドラを自前で実装する

本番では、保存先をデータベースやユーザーごとのディレクトリに分けたくなります。

BetaAbstractMemoryToolをサブクラス化するか、tool_useループを自分で回してコマンドを処理します。

import anthropic

client = anthropic.Anthropic()

TOOLS = [{"type": "memory_20250818", "name": "memory"}]
messages = [{"role": "user", "content": "前回の続きから作業を進めて"}]

while True:
    message = client.messages.create(
        model="claude-sonnet-5",
        max_tokens=2048,
        messages=messages,
        tools=TOOLS,
    )

    if message.stop_reason != "tool_use":
        print(message.content)
        break

    tool_results = []
    for block in message.content:
        if block.type == "tool_use" and block.name == "memory":
            output = run_memory_command(block.input)
            tool_results.append({
                "type": "tool_result",
                "tool_use_id": block.id,
                "content": output,
            })

    messages.append({"role": "assistant", "content": message.content})
    messages.append({"role": "user", "content": tool_results})

run_memory_commandは、tool_useブロックのinputに含まれるcommandフィールドで分岐し、Anthropicのドキュメントが定める文字列を返します。

6種類のコマンドは、返す文字列の形式まで仕様で決まっているため、ドキュメントの記載に合わせます。

パストラバーサル対策を入れる

ハンドラを自作するときに一番注意すべき点は、パスの検証です。

/memories/../../secrets.envのようなパスを渡されると、メモリディレクトリの外へアクセスできてしまいます。

すべてのコマンドで、パスが/memories配下に収まっているかを毎回チェックします。

Pythonならpathlib.Path.resolve()で正規化し、is_relative_to()でルート配下かどうかを確認できます。

from pathlib import Path

MEMORY_ROOT = Path("./memory_store").resolve()


def resolve_safe(path: str) -> Path:
    relative = path.removeprefix("/memories").lstrip("/")
    resolved = (MEMORY_ROOT / relative).resolve()
    if not resolved.is_relative_to(MEMORY_ROOT):
        raise ValueError(f"不正なパスが指定されました: {path}")
    return resolved


def run_memory_command(command: dict) -> str:
    action = command["command"]

    if action == "view":
        target = resolve_safe(command["path"])
        if target.is_dir():
            return "\n".join(sorted(str(p) for p in target.iterdir()))
        return target.read_text(encoding="utf-8")

    if action == "create":
        target = resolve_safe(command["path"])
        target.parent.mkdir(parents=True, exist_ok=True)
        target.write_text(command["file_text"], encoding="utf-8")
        return f"File created successfully at: {command['path']}"

    # str_replace / insert / delete / rename も同じ要領で実装する
    raise ValueError(f"未対応のコマンドです: {action}")
いずみ

パス検証を省いたハンドラは、事故のもとです。

デモ用のコードには検証が入っていないことが多いので、そのまま本番に持ち込まないよう注意してください。

context editingと組み合わせる

Memory Toolは、長時間の会話で文脈があふれる問題を単体では解決しません。

ツール結果が積み重なって入力トークンが増えるため、context editingを併用します。

context editingは、context_managementパラメータで古いツール結果を自動的に削除する機能です。

clear_tool_uses_20250919を指定し、triggerで発動する入力トークン数、keepで残すツール往復の数を決めます。

exclude_toolsmemoryを入れておくと、メモリ操作の履歴だけは削除対象から外せます。

併用にはcontext-management-2025-06-27のベータヘッダーが必要です。

response = client.beta.messages.create(
    model="claude-sonnet-5",
    max_tokens=4096,
    messages=messages,
    tools=[{"type": "memory_20250818", "name": "memory"}],
    betas=["context-management-2025-06-27"],
    context_management={
        "edits": [
            {
                "type": "clear_tool_uses_20250919",
                "trigger": {"type": "input_tokens", "value": 30000},
                "keep": {"type": "tool_uses", "value": 3},
                "exclude_tools": ["memory"],
            }
        ]
    },
)

print(response.context_management)

レスポンスのcontext_managementフィールドに、削除されたツール往復数と削減トークン数が入ります。

いずみ

Anthropicの社内評価では、メモリとcontext editingの併用で検索タスクのスコアが改善したと報告されています。

長く動くエージェントほど効果が出やすい組み合わせです。

使うときの注意点

createはファイルを上書きする可能性があるため、既存ファイルの扱いを決めておきます。

str_replaceold_strがファイル内に一字一句一致し、かつ一意である必要があります。

メモリファイルのサイズに上限を設け、肥大化を防ぎます。

機微情報が書き込まれないよう、ハンドラ側でバリデーションを入れます。

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

スクロールできます
【当サイト】おすすめフリーランスエージェント3選
エージェント評価ポイント公式サイト
レバテックフリーランス

5.0
業界最大級のエージェント。
高単価案件が豊富。
公式
Midworks

4.8
満足度調査で
3年連続3冠を達成。
公式
ITプロパートナーズ

4.6
週2〜3向けの案件が豊富。公式

【厳選】フリーランスエンジニアにおすすめなエージェント3選

フリーランスエンジニアになるにはエージェントから案件をもらう必要があります。

僕が実際に利用しているおすすめエージェントを紹介しますね。

いずみ

エージェントは必ず複数登録してください。

担当者によっては「全然案件紹介してくれない…」みたいなこともあるので…

僕は実際に5つのエージェントを使い回していますよ。

フリーランスを始めるなら「

案件数マージン率単価
約88,000件非公開
初心者福利厚生申し込み
無料
Good Point
  • 業界最大級の案件数。
  • 業界トップクラスの高単価報酬、低マージン(平均年収862万円)。
  • 案件参画中のフォローの充実。

※詳細は「【業界最大手】レバテックフリーランスとは?メリットや利用手順を解説!」を参照。

は業界最大手のフリーランスエージェントです。

とにかく案件数が多いので、とりあえず登録しておけば間違いないエージェントです!

いずみ

僕もはじめてフリーランスの案件を貰ったのはです。

保有している案件数が多いので、業務経験がなくても何かしらの案件は紹介してもらえますよ(僕はJavaの経験3年でも案件を貰えました)。

手厚い保障を重視したいなら「

案件数マージン率単価
約10,000件非公開
初心者福利厚生申し込み
無料
Good Point
  • 手厚い保障で正社員並みの安心感。
  • 還元率60%超え&単価公開でクリアな契約。
  • 給与保障制度(審査あり)。

は手厚い保障が特徴のフリーランスエージェントです。

フリーランスを目指しているけど不安な方や保障を重視したい方におすすめです。

いずみ

僕も何度か案件を紹介してもらいました。

自分のスキルに合った案件を紹介してもらえましたし、電話のやり取りも非常に丁寧でした。

週2〜3日の案件探しなら「

案件数マージン率単価
約5,000件非公開
初心者福利厚生申し込み
経験者向け無料
Good Point
  • IT案件に特化したフリーランスエージェント。
  • 週2〜3日の案件が豊富。
  • リモート案件が多く、直エンドなので単価も高い。

※詳細は「【週2・3案件】ITプロパートナーズとは?メリットや利用手順を解説!」を参照。

はIT案件に特化したフリーランスエージェントです。

週2〜3日から参画できる案件が豊富なので、起業したい人にもおすすめです。

いずみ

週2〜3日の案件はある程度スキルがないと紹介してもらえない印象です。

とはいえ、週5の案件ももちろんありますし、僕が利用した時は迅速・丁寧に対応していただきました!

よくある質問

Memory Toolの利用にベータヘッダーは必要ですか?

memory_20250818のツール定義自体は、ベータヘッダーなしで利用できます。

ただしSDKのヘルパーやツールランナーはbeta名前空間にあり、context editingを併用する場合はcontext-management-2025-06-27を指定します。

メモリはどこに保存されますか?

/memoriesはプレフィックスで、実体はアプリ側が用意したストレージです。

ディスク・データベース・クラウドストレージなどを自由に選べ、Anthropic側には保存されません。

str_replaceが失敗します

old_strがファイル内の文字列と完全一致していないか、複数箇所に出現しているのが主な原因です。

前後の行を含めてold_strが一意になるように指定すると解決します。

どのモデルで使えますか?

Memory ToolはClaude 4以降のモデルで利用できます。

まとめ

今回は、Claude APIのMemory Toolで記憶を永続化する方法について解説しました。

以下が本記事のまとめになります。

まとめ
  • Memory Toolは {"type": "memory_20250818", "name": "memory"} をtoolsに足すだけで有効になる。
  • 保存処理はクライアントサイドなので、アプリ側でハンドラとパス検証を用意する。
  • Python SDKの BetaLocalFilesystemMemoryTooltool_runner を使うと最短で動かせる。
  • context editingと併用すると、長時間エージェントの文脈あふれを抑えられる。
まとめ
いずみ

最後までお読みいただき、ありがとうございました!

スクロールできます
【当サイト】おすすめフリーランスエージェント3選
エージェント評価ポイント公式サイト
レバテックフリーランス

5.0
業界最大級のエージェント。
高単価案件が豊富。
公式
Midworks

4.8
満足度調査で
3年連続3冠を達成。
公式
ITプロパートナーズ

4.6
週2〜3向けの案件が豊富。公式
  • クソおすすめ本
¥4,480 (2024/06/01 23:28時点 | Amazon調べ)
\楽天ポイント4倍セール!/
楽天市場
いずみ

海外のエンジニアがどういった思考で働いているかが理解できます。

海外に行く気はないけど海外エンジニアの動向が気になる雑魚エンジニアにおすすめです(本当におすすめな本しか紹介しないのでご安心を)。

この記事が気に入ったら
フォローしてね!

シェアしてね!
  • URLをコピーしました!
目次