AIエージェント編集部
Claude Managed Agents Memoryで作るエージェント記憶システム完全ガイド
チュートリアル

Claude Managed Agents Memoryで作るエージェント記憶システム完全ガイド

2026-05-01

この記事は、Claude APIでエージェントを作っている開発者に向けた実装ガイドです。「Claude Managed Agents Memory」を使うと、エージェントがセッションをまたいで情報を記憶し続けられるようになります。独自のデータベースやベクトルストアを用意しなくてもいい——この一点が、多くの開発者にとって大きなメリットになるはずです。

公開ベータが始まったばかりのこの機能、まだ日本語の解説記事が少ない。一緒に手を動かしながら理解していきましょう。

Managed Agents Memoryとは何か——3種類の記憶レイヤー解説

まず「記憶」とは何かを整理してみると面白い。人間の記憶には「短期記憶」「長期記憶」「手続き記憶」といった種類があります。Managed Agents Memoryも、役割の異なる3つの層に分かれています。

セッション記憶(Session Memory)

1回の会話セッション内だけ保持される短期記憶です。実はこれはManaged Agents Memoryの前から存在する「コンテキストウィンドウ」そのものです。特別な設定は不要で、会話の流れが自動的に保持されます。

ユーザー記憶(User Memory)

特定のユーザーに紐づいた長期記憶です。「このユーザーはPythonが得意」「前回は料金プランについて質問してきた」といった情報をファイルとして保存し、次回セッションでも参照できます。

タスク記憶(Task Memory)

進行中のプロジェクトや継続タスクに紐づく記憶です。「このコードベースの設計方針」「このユーザーの執筆スタイル」など、タスク単位で積み上がる知識をストアします。

つまり

「誰が」「何を」「どのタスクで」——この3軸で記憶を分けて管理するのがManaged Agents Memoryの核心です。無闇に1つのファイルに詰め込まず、目的別に分割するのがポイント。

セットアップ——managed-agents-2026-04-01ヘッダーの使い方

Managed Agents Memoryを有効にするには、APIリクエストに特定のベータヘッダーを付与します。ここで迷いやすいのが「どのAPIエンドポイントに付けるか」という点ですが、通常のMessages APIに追加するだけなので難しくありません。

Python での実装例

import anthropic

client = anthropic.Anthropic()

# Managed Agents Memory を有効化するベータヘッダー
response = client.beta.messages.create(
    model="claude-opus-4-7-20251101",
    max_tokens=1024,
    betas=["managed-agents-2026-04-01"],
    system=[
        {
            "type": "text",
            "text": "あなたは親切なカスタマーサポートエージェントです。"
        }
    ],
    messages=[
        {"role": "user", "content": "料金プランについて教えてください。"}
    ],
    # ユーザー記憶ファイルを参照・更新
    memory={
        "user_id": "user_12345",
        "read_files": ["user_profile.md", "past_queries.md"],
        "write_files": ["past_queries.md"]
    }
)

print(response.content[0].text)

TypeScript での実装例

import Anthropic from '@anthropic-ai/sdk';

const client = new Anthropic();

const response = await client.beta.messages.create({
  model: 'claude-opus-4-7-20251101',
  max_tokens: 1024,
  betas: ['managed-agents-2026-04-01'],
  system: [
    {
      type: 'text',
      text: 'あなたは親切なカスタマーサポートエージェントです。'
    }
  ],
  messages: [
    { role: 'user', content: '料金プランについて教えてください。' }
  ],
  memory: {
    user_id: 'user_12345',
    read_files: ['user_profile.md', 'past_queries.md'],
    write_files: ['past_queries.md']
  }
});

console.log(response.content[0].text);

💡 TIP

betas: ["managed-agents-2026-04-01"] の文字列は正確に一致させること。タイポがあると機能が有効にならず、エラーも出ないまま通常のAPIとして動作してしまいます。

メモリ設計ベストプラクティス——100KB制限をどう活かすか

Managed Agents Memoryの記憶ファイルは1件あたり100KB(約25,000トークン)が上限です。「少ない」と思うかもしれませんが、実はこれは設計の指針として機能します。

細かく分割する

1つのファイルに全情報を詰め込むのは禁物です。要するに、1ファイル=1テーマにするのが正解。カスタマーサポートなら「ユーザープロフィール」「過去の問い合わせ履歴」「解決済みチケット」を別ファイルに分ける、という考え方です。

# 推奨: テーマ別に分割
memory/
  user_profile.md        # ユーザーの基本情報・好み(更新頻度: 低)
  query_history.md       # 過去の問い合わせ要約(更新頻度: 高)
  resolved_tickets.md    # 解決済みチケット(追記のみ)
  preferences.md         # 返答スタイル・言語設定(更新頻度: 低)

# NG: 全部1ファイルに詰め込む
memory/
  everything.md          # 100KB上限にすぐ達し、古い情報が消える

要約して書き込む

エージェントが記憶ファイルを更新する際は、生の会話ログをそのまま書かず「この会話で分かったこと」に圧縮するよう指示しましょう。

# システムプロンプトへの追記例
"""
会話が終わったら、学んだことを以下の形式で past_queries.md に追記してください:
- 日付: YYYY-MM-DD
- 質問カテゴリ: [料金/技術/返品/その他]
- 要点: 1〜2文で要約
- 解決済み: yes/no

生の会話ログは書かないでください。
"""

読み込みファイルと書き込みファイルを分ける

read_files と write_files を明示的に分けることで、誤った上書きを防げます。参照専用の「設計ポリシーファイル」などは write_files に含めないようにしましょう。

Opus 4.7 + Memory の組み合わせ

現在のところ、メモリファイルの読み書き精度が最も高いのは Claude Opus 4.7 です。「何を覚えておくべきか」「どう要約するか」の判断力がOpus 4.7で大幅に改善されています。コスト面が気になる場合は、記憶ファイルを更新するターンだけOpus 4.7を使い、通常の応答はSonnetを使う、という使い分けも有効です。

ユースケース別活用例

カスタマーサポートエージェント

最もわかりやすいユースケースです。ユーザーが「先月も同じ質問したんですが」と言ったとき、エージェントが「そうですね、前回はXXの方法で解決しましたね」と返せるようになります。

memory={
    "user_id": f"customer_{user_id}",
    "read_files": [
        "user_profile.md",    # ユーザーの契約プラン・技術レベル
        "query_history.md",   # 過去問い合わせの要約
    ],
    "write_files": [
        "query_history.md"    # 今回の問い合わせを追記
    ]
}

記憶があることで「前にも同じ問題が起きているな」「このユーザーは技術的に詳しいから省略してよい説明がある」という判断が自動でできるようになります。

コードレビューエージェント

「このプロジェクトはTypeScript strict modeを使っている」「チームのコーディング規約はXXX」といったコンテキストをタスク記憶として保持させます。毎回説明する手間がなくなるだけでなく、レビューの一貫性も上がります。

memory={
    "task_id": f"project_{repo_name}",
    "read_files": [
        "coding_standards.md",  # チームのコーディング規約
        "architecture.md",      # プロジェクト設計方針
        "review_history.md",    # 過去のレビューコメント傾向
    ],
    "write_files": [
        "review_history.md"     # 今回のレビューで気づいたパターンを追記
    ]
}

編集・ライティングエージェント

ライターの文体・好み・避けたい表現などを記憶させると、毎回「ですます調で、専門用語は平易に言い換えて」と指示しなくてよくなります。

memory={
    "user_id": f"writer_{user_id}",
    "read_files": [
        "writing_style.md",   # 文体・トーン・禁止ワード
        "past_articles.md",   # 過去記事のトピックと評価
    ],
    "write_files": [
        "past_articles.md"    # 今回の記事情報を追記
    ]
}

よくある落とし穴と回避策

落とし穴1: ファイル名の管理が雑になる

user_id や task_id をそのままファイルパスに使うと、特殊文字が含まれた場合にAPIエラーが起きます。ファイル名には英数字とアンダースコアのみを使うよう正規化しましょう。

import re

def sanitize_filename(name: str) -> str:
    # 英数字・アンダースコア・ハイフン以外を除去
    return re.sub(r'[^a-zA-Z0-9_\-]', '_', name)

user_file = f"user_{sanitize_filename(user_id)}_profile.md"

落とし穴2: 記憶ファイルが肥大化する

write_files に含めたファイルは毎回更新されます。エージェントへの指示が曖昧だと、会話ログをそのまま追記し続けて100KBに達してしまいます。システムプロンプトで「要約して書く」「古い情報は削除する」を明示するのが重要です。

落とし穴3: 記憶を信頼しすぎる

記憶ファイルの内容はエージェント自身が書いたものです。「確実な事実」として扱わず「前回の会話から推測した情報」として扱うよう、システムプロンプトで注釈を入れましょう。

# システムプロンプトへの追記
"""
past_queries.md の内容は過去の会話から推測した情報です。
ユーザーが明示的に訂正した場合は記憶を更新してください。
確認が必要な場合はユーザーに質問してから回答してください。
"""

落とし穴4: read_files を増やしすぎてコンテキストが膨らむ

read_files に含めたファイルはすべてコンテキストウィンドウに読み込まれます。ファイルが多いほどトークンを消費し、コストが上がります。「今のリクエストに本当に必要か」を判断してread_filesを絞ることが大切です。

まとめ——記憶を持つエージェントが変えるUX

Managed Agents Memoryの本質は「エージェントが成長する」という体験をユーザーに届けることです。初回から完璧でなくても、使うたびに賢くなっていく——そのUXが、ユーザーのエンゲージメントを根本から変えます。

今回の内容をまとめると:

まずは一番シンプルなカスタマーサポートエージェントで試してみてください。「前回の会話を覚えていてくれる」という体験は、使い始めると手放せなくなります。

この記事で使ったツール

本記事はAIエージェントが収集・執筆した情報を含みます。内容の正確性・最新性については公式ドキュメントや一次情報源をご確認ください。