エージェントメモリの使用
メモリストアを使用して、セッションをまたいで保持される永続的なメモリをエージェントに与えます。
各 Managed Agents セッションは、デフォルトでは新しいコンテキストから開始されます。セッションが終了すると、エージェントが構築した状態はすべて失われます。「memory store」(メモリストア)を使用すると、エージェントはユーザーの好み、プロジェクトの規約、過去のミス、ドメインのコンテキストといった情報をセッションをまたいで引き継ぐことができます。
概要
メモリストアは、Claude向けに最適化されたテキストドキュメントの、ワークスペース単位のコレクションです。ストアをセッションにアタッチすると、セッションのサンドボックス内にディレクトリとしてマウントされます。エージェントは、ファイルシステムの他の部分で使用するのと同じファイルツールでストアの読み書きを行い、各マウントを説明するメモがシステムプロンプトに自動的に追加され、エージェントにどこを参照すべきかを伝えます。これらのやり取りにはエージェントツールセットが必要です。エージェントの作成時に必ず有効にしてください。セルフホスト型サンドボックスでは、そのディレクトリはライブマウントではありません。代わりに、環境ワーカーがエージェントのツールが実行される前に、アタッチされた各ストアをサンドボックスにダウンロードし、そのコピーをストアと同期させ続けます。
ストア内の各メモリはパスでアドレス指定され、API または Claude Console を通じて直接読み取りや編集ができるため、チューニング、インポート、エクスポートが可能です。
メモリへのすべての変更は不変のメモリバージョンを作成します。これにより、エージェントが書き込むすべての内容について監査証跡とポイントインタイムリカバリが得られます。
メモリストアを作成する
ストアに name と description を指定します。説明はエージェントに渡され、ストアに何が含まれているかを伝えます。
ant apply memory_store.yaml# yaml-language-server: $schema=https://platform.claude.com/schemas/ant/beta/memory_store.json
name: User Preferences
description: Per-user preferences and project context.メモリストアの id(memstore_...)は、ストアをセッションにアタッチする際に渡す値です。
コンテンツをシードする(オプション)
エージェントが実行される前に、ストアに参照資料を事前にロードします。
client.beta.memory_stores.memories.create(
store.id,
path="/formatting_standards.md",
content="All reports use GAAP formatting. Dates are ISO-8601...",
)メモリストアをセッションにアタッチする
メモリストアは、セッションの作成時にセッションの resources 配列でアタッチします。ファイルリソースとは異なり、メモリストアはセッション作成時にのみアタッチでき、実行中のセッションへの追加や削除はサポートされていません。クラウド環境とセルフホスト型環境のどちらのセッションでも、メモリストアは同じ方法でアタッチします。セルフホスト型環境では memory_store リソースのみが受け付けられます。
オプションで instructions を含めて、エージェントがこのストアをどのように使用すべきかについてセッション固有のガイダンスを提供できます。これはストアの name および description とともにエージェントに表示され、上限は4,096文字です。
access も設定できます。デフォルトは read_write(次の例では明示的に指定しています)ですが、read_only もサポートされています。
session = client.beta.sessions.create(
agent=agent.id,
environment_id=environment.id,
resources=[
{
"type": "memory_store",
"memory_store_id": store.id,
"access": "read_write",
"instructions": "User preferences and project context. Check before starting any task.",
}
],
)各セッションでは最大8個のメモリストアがサポートされます。メモリの異なる部分でオーナーやアクセスルールが異なる場合は、複数のストアをアタッチします。一般的な理由は次のとおりです:
- 共有の参考資料: 多数のセッションにアタッチされる1つの読み取り専用ストア(標準、規約、ドメイン知識)を、各セッション独自の読み書き可能なストアとは分けて保持する
- 製品の構造へのマッピング: 単一のエージェント設定を共有しながら、エンドユーザー、チーム、またはプロジェクトごとに1つのストアを使用する
- 異なるライフサイクル: 単一のセッションよりも長く存続するストアや、独自のスケジュールでアーカイブしたいストア
エージェントがメモリにアクセスする方法
アタッチされた各ストアは、セッションのサンドボックス内の /mnt/memory/ 配下にディレクトリとしてマウントされます。ディレクトリ名は、ストアの表示名をファイルシステムで安全に使えるスラッグに変換したもの(小文字化し、英数字以外の連続する文字をそれぞれ1つのハイフンに置き換えたもの)であるため、「Demo Memory」という名前のストアは /mnt/memory/demo-memory/ にマウントされます。正確なパスはセッションのメモリストアリソースの mount_path フィールドで返されます。パスは自分で組み立てるのではなく、そこから読み取ってください。エージェントは標準のエージェントツールセットを使ってストアの読み書きを行います。マウントパス配下への書き込みはストアに永続化され、そのストアを共有するセッション間で同期された状態に保たれます。/mnt/memory/ 配下のその他のパスへの書き込みは、サンドボックスがその親ディレクトリを読み取り専用でマウントしているため失敗します。各マウントの簡単な説明(表示名、マウントパス、アクセスモード、ストアの description、および instructions(ある場合))がシステムプロンプトに自動的に追加されます。
access はファイルシステムレベルで強制されます。read_only マウントは書き込みを拒否し、read_write マウントへの書き込みはセッションに帰属するメモリバージョンを生成します。
エージェントの読み取りと書き込みは、マウントに触れたツールに応じた通常の agent.tool_use および agent.tool_result イベントとしてイベントストリームに表示されます。
メモリの表示と編集
メモリストアは API を通じて直接管理できます。レビューワークフローの構築、誤ったメモリの修正、またはセッション実行前のストアのシードに使用してください。
メモリを一覧表示する
ストア内のメモリを一覧表示します。結果はサーバー定義の安定した順序で返されます。
path_prefixは一覧を1つのディレクトリに限定します。/で終わる必要があり、パスセグメント全体に一致するため、path_prefix=/notes/は/notes/todo.mdを返しますが/notes-archive/todo.mdは返しません。depthはpath_prefixの下をどの深さまで一覧表示するかを制御します。サブツリー全体を一覧表示するには省略する(または0を渡す)か、直下の子のみを一覧表示するには1を渡します。その他の値を指定すると400エラーが返されます。
page = client.beta.memory_stores.memories.list(
store.id,
path_prefix="/",
)
for item in page.data:
print(item.type, item.path)パラメータとレスポンススキーマの詳細については、メモリの一覧表示API リファレンスへのリンクを含むプレビューを表示できます — カードにフォーカスが移るまで Tab キーを押します。戻るには Escape キーを押します。のリファレンスを参照してください。
メモリを読み取る
個々のメモリを取得すると、完全なコンテンツが返されます。
retrieved = client.beta.memory_stores.memories.retrieve(
mem.id,
memory_store_id=store.id,
)
print(retrieved.content)パラメータとレスポンススキーマの詳細については、メモリの取得API リファレンスへのリンクを含むプレビューを表示できます — カードにフォーカスが移るまで Tab キーを押します。戻るには Escape キーを押します。のリファレンスを参照してください。
メモリを作成する
client.beta.memory_stores.memories.create() は、指定された path にメモリを作成します。作成操作は上書きを行いません。既存のメモリを更新するには、client.beta.memory_stores.memories.update() を使用してください。
mem = client.beta.memory_stores.memories.create(
store.id,
path="/preferences/formatting.md",
content="Always use tabs, not spaces.",
)パラメータとレスポンススキーマの詳細については、メモリの作成API リファレンスへのリンクを含むプレビューを表示できます — カードにフォーカスが移るまで Tab キーを押します。戻るには Escape キーを押します。のリファレンスを参照してください。
メモリを更新する
client.beta.memory_stores.memories.update() は、IDを指定して既存のメモリを変更します。content、path(名前の変更)、またはその両方を変更できます。次の例では、メモリの名前をアーカイブパスに変更します。
client.beta.memory_stores.memories.update(
mem.id,
memory_store_id=store.id,
path="/archive/2026_q1_formatting.md",
)パラメータとレスポンススキーマの詳細については、メモリの更新API リファレンスへのリンクを含むプレビューを表示できます — カードにフォーカスが移るまで Tab キーを押します。戻るには Escape キーを押します。のリファレンスを参照してください。
安全なコンテンツ編集(楽観的並行性制御)
同時に行われた書き込みを上書きしないように、content_sha256 の前提条件を渡します。更新は、保存されているコンテンツのハッシュが読み取り時のハッシュと一致する場合にのみ適用されます。一致しない場合は、メモリを再度読み取り、最新の状態に対して再試行してください。
client.beta.memory_stores.memories.update(
memory_id=mem.id,
memory_store_id=store.id,
content="CORRECTED: Always use 2-space indentation.",
precondition={"type": "content_sha256", "content_sha256": mem.content_sha256},
)メモリを削除する
client.beta.memory_stores.memories.delete(
mem.id,
memory_store_id=store.id,
)パラメータとレスポンススキーマの詳細については、メモリの削除API リファレンスへのリンクを含むプレビューを表示できます — カードにフォーカスが移るまで Tab キーを押します。戻るには Escape キーを押します。のリファレンスを参照してください。
メモリの変更を監査する
メモリへのすべての変更は、不変のメモリバージョン(memver_...)を作成します。バージョンエンドポイントを使用して、誰がいつ何を変更したかを監査したり、以前のスナップショットを検査または復元したり、redact で履歴から機密コンテンツを消去したりできます。
バージョンは(個々のメモリではなく)ストアに属し、メモリ自体が削除されても削除されないため、監査証跡は削除されたメモリも対象とします(後述の保持期間に従います)。バージョンは書き込まれてから30日間保持されます。ただし、存続しているメモリの最近のバージョンは経過期間にかかわらず常に保持されるため、変更頻度の低いメモリでは30日を超えて履歴が保持される場合があります。存続しているメモリに対する client.beta.memory_stores.memories.retrieve() 呼び出しは常に最新バージョンを返します。保持されている履歴はバージョンエンドポイントで取得できます。
専用の復元エンドポイントはありません。ロールバックするには、目的のバージョンを取得し、その content を client.beta.memory_stores.memories.update() で書き戻します(親メモリが削除されている場合は、目的のバージョンがまだ保持されていれば client.beta.memory_stores.memories.create() を使用します)。
過去のメモリバージョンは 30 日後に削除される可能性があります。メモリ履歴をより長く保存するには、API を通じてバージョンをエクスポートしてください。
バージョンを一覧表示する
ストアのバージョン履歴を新しい順に一覧表示します。この例では単一のメモリの履歴に絞り込んでいます。
versions = client.beta.memory_stores.memory_versions.list(
store.id,
memory_id=mem.id,
)
for version in versions:
print(f"{version.id}: {version.operation}")
version_id = versions.data[1].idパラメータとレスポンススキーマの詳細については、メモリバージョンの一覧表示API リファレンスへのリンクを含むプレビューを表示できます — カードにフォーカスが移るまで Tab キーを押します。戻るには Escape キーを押します。のリファレンスを参照してください。
バージョンを取得する
個々のバージョンを取得すると、一覧レスポンスと同じフィールドに加えて、完全な content 本文が返されます。
version = client.beta.memory_stores.memory_versions.retrieve(
version_id,
memory_store_id=store.id,
)
print(version.content)パラメータとレスポンススキーマの詳細については、メモリバージョンの取得API リファレンスへのリンクを含むプレビューを表示できます — カードにフォーカスが移るまで Tab キーを押します。戻るには Escape キーを押します。のリファレンスを参照してください。
バージョンを redact する
redactは、監査証跡(誰が、いつ、何をしたか)を保持しながら、過去のバージョンからコンテンツを消去します。漏洩したシークレットや個人を特定できる情報(PII)の削除、ユーザーの削除リクエストへの対応など、コンプライアンスのワークフローに使用してください。
ライブメモリの現在のヘッドであるバージョンは redact できません。まず新しいバージョンを書き込み(またはメモリを削除し)、その後で古いバージョンを redact してください。
client.beta.memory_stores.memory_versions.redact(
version_id,
memory_store_id=store.id,
)パラメータとレスポンススキーマの詳細については、メモリバージョンの編集除去API リファレンスへのリンクを含むプレビューを表示できます — カードにフォーカスが移るまで Tab キーを押します。戻るには Escape キーを押します。のリファレンスを参照してください。
メモリストアを管理する
createAPI リファレンスへのリンクを含むプレビューを表示できます — カードにフォーカスが移るまで Tab キーを押します。戻るには Escape キーを押します。 に加えて、メモリストアは retrieveAPI リファレンスへのリンクを含むプレビューを表示できます — カードにフォーカスが移るまで Tab キーを押します。戻るには Escape キーを押します。、updateAPI リファレンスへのリンクを含むプレビューを表示できます — カードにフォーカスが移るまで Tab キーを押します。戻るには Escape キーを押します。、listAPI リファレンスへのリンクを含むプレビューを表示できます — カードにフォーカスが移るまで Tab キーを押します。戻るには Escape キーを押します。、archiveAPI リファレンスへのリンクを含むプレビューを表示できます — カードにフォーカスが移るまで Tab キーを押します。戻るには Escape キーを押します。、および deleteAPI リファレンスへのリンクを含むプレビューを表示できます — カードにフォーカスが移るまで Tab キーを押します。戻るには Escape キーを押します。 をサポートしています。
ストアを一覧表示する
ワークスペース内のストアを一覧表示します。アーカイブされたストアはデフォルトで除外されます。含めるには include_archived を true に設定してください。
for memory_store in client.beta.memory_stores.list(include_archived=True):
print(memory_store.id, memory_store.name, memory_store.archived_at)パラメータとレスポンススキーマの詳細については、メモリストアの一覧表示API リファレンスへのリンクを含むプレビューを表示できます — カードにフォーカスが移るまで Tab キーを押します。戻るには Escape キーを押します。のリファレンスを参照してください。
ストアをアーカイブする
アーカイブするとストアは読み取り専用になり、新しいセッションにアタッチできなくなります。アーカイブは一方向であり、アーカイブ解除はありません。
client.beta.memory_stores.archive(store.id)パラメータとレスポンススキーマの詳細については、メモリストアのアーカイブAPI リファレンスへのリンクを含むプレビューを表示できます — カードにフォーカスが移るまで Tab キーを押します。戻るには Escape キーを押します。のリファレンスを参照してください。
すべてのメモリとバージョンとともにストアを完全に削除するAPI リファレンスへのリンクを含むプレビューを表示できます — カードにフォーカスが移るまで Tab キーを押します。戻るには Escape キーを押します。には、client.beta.memory_stores.delete()を呼び出します。
メモリ管理のベストプラクティス
ストアが10,000メモリの上限に達すると、新しいメモリへの書き込みは失敗します。これには、直接の client.beta.memory_stores.memories.create() 呼び出しと、マッピングされていないパスへのエージェントのファイル書き込みの両方が含まれます。既存のメモリは引き続き読み取りと編集が可能です。以下のプラクティスは、上限を十分に下回る状態を保ち、上限に達した場合にも適切に回復するのに役立ちます。
-
焦点を絞ったストアを使用する。 1つの大きな汎用ストアではなく、目的別の小さなストアを使用してください。たとえば、ユーザーごとに1つ、共有のドメイン知識用に1つ、プロジェクト固有のコンテキスト用に1つといった形です。各ストアにはそれぞれ10,000個のメモリ上限があるため、ストアの範囲を限定しておくことで、いずれか1つのストアが満杯になる可能性を低減できます。
-
ストアが満杯になる前に集約または整理する。 古くなったメモリや冗長なメモリは
client.beta.memory_stores.memories.delete()で削除してください。ドリーミングセッションを実行することもできます。これは元のストアを変更するのではなく、断片化したコンテンツを別の新しい出力ストアに統合します。セッションをその出力ストアに切り替えてから、元のストアをアーカイブまたは削除してください。 -
適切なタイミングで新しいストアをアタッチする。 ストアが有用なスコープを超えて大きくなった場合は、新しいコンテンツ用に新しいストアをアタッチし、元のストアは
read_onlyアクセスでアタッチしてください。エージェントは両方から読み取りつつ、新しいストアにのみ書き込むことができます。 -
適切な場合は書き込みアクセスを制限する。 共有参照資料を読み取るだけのセッションに
read_writeは必要ありません。書き込みアクセスを実際に新しいメモリを追加するセッションに限定しておくことで、増加がどこから来ているかを追跡しやすくなります。
利用可能状況
Claude API
- ステータス
- ベータ
- API
- Managed Agents
- ベータヘッダー
- が必要
- モデル
- すべてのモデル
- 注記
メモリストアの呼び出しで
managed-agents-2026-04-01とagent-memory-2026-07-22を一緒に送信すると、400エラーが返されます。
Claude Platform on AWS
- ステータス
- ベータ
- API
- Managed Agents
- ベータヘッダー
- が必要
- モデル
- すべてのモデル
- 注記
Claude Platform on AWSでは、セルフホスト型環境のセッションにメモリストアをアタッチできません。メモリストアの呼び出しで
managed-agents-2026-04-01とagent-memory-2026-07-22を一緒に送信すると、400エラーが返されます。
Claude Models on Google Cloud (Anthropic managed)
- ステータス
- ベータ
- API
- Managed Agents
- ベータヘッダー
- が必要
- モデル
- すべてのモデル
- 注記
Claude Models on Google Cloud (Anthropic managed)では、セルフホスト型環境のセッションでメモリストアはサポートされていません。メモリストアの呼び出しで
managed-agents-2026-04-01とagent-memory-2026-07-22を一緒に送信すると、400エラーが返されます。
データの取り扱い
データの取り扱いの概要対象エンドポイント
/v1/agents/v1/sessions/v1/environments
セルフホスト型Managed Agentsを除き、ZDRの適格対象ではありません。セッションはステートフルなリソースであり、トランスクリプトは削除するまで保持されます。 詳細はこちら
HIPAAの適格対象ではありません。すべてのManaged Agentsのサブ機能に適用されます。
このページは役に立ちましたか?