エージェントメモリの使用

各 Managed Agents セッションは、デフォルトでは新しいコンテキストから開始されます。セッションが終了すると、エージェントが構築した状態はすべて失われます。「memory store」（メモリストア）を使用すると、エージェントはユーザーの好み、プロジェクトの規約、過去のミス、ドメインのコンテキストといった情報をセッションをまたいで引き継ぐことができます。

概要

メモリストアは、Claude 向けに最適化された、ワークスペーススコープのテキストドキュメントのコレクションです。ストアをセッションにアタッチすると、セッションのサンドボックス内にディレクトリとしてマウントされます。エージェントは、ファイルシステムの他の部分に使用するのと同じファイルツールでこれを読み書きします。また、各マウントを説明するメモがシステムプロンプトに自動的に追加され、エージェントにどこを参照すべきかを伝えます。これらの操作にはエージェントツールセットが必要です。エージェント作成時に必ず有効にしてください。セルフホスト型サンドボックスでは、そのディレクトリはライブマウントではありません。代わりに、SDK の環境ワーカーがエージェントのツールが実行される前にアタッチされた各ストアをサンドボックスにダウンロードし、そのコピーをストアと同期した状態に保ちます。

ストア内の各メモリはパスでアドレス指定され、API または Claude Console を通じて直接読み取りや編集ができるため、チューニング、インポート、エクスポートが可能です。

メモリへのすべての変更は不変のメモリバージョンを作成します。これにより、エージェントが書き込むすべての内容について監査証跡とポイントインタイムリカバリが得られます。

メモリストアを作成する

ストアに name と description を指定します。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/ 配下のディレクトリとしてマウントされます。ディレクトリ名は、ストアの表示名をファイルシステムで安全なスラッグにサニタイズしたもの（小文字化され、英数字以外の連続は単一のハイフンになります）です。そのため、「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)

すべてのパラメータとレスポンススキーマについては、メモリ一覧のリファレンスを参照してください。

メモリを読み取る

個々のメモリを取得すると、完全なコンテンツが返されます。

retrieved = client.beta.memory_stores.memories.retrieve(
    mem.id,
    memory_store_id=store.id,
)
print(retrieved.content)

すべてのパラメータとレスポンススキーマについては、メモリ取得のリファレンスを参照してください。

メモリを作成する

memories.create は指定された path にメモリを作成します。create は上書きしません。既存のメモリを変更するには、memories.update を使用してください。

mem = client.beta.memory_stores.memories.create(
    store.id,
    path="/preferences/formatting.md",
    content="Always use tabs, not spaces.",
)

すべてのパラメータとレスポンススキーマについては、メモリ作成のリファレンスを参照してください。

メモリを更新する

memories.update は既存のメモリを ID で変更します。content、path（リネーム）、またはその両方を変更できます。この例ではメモリをアーカイブパスにリネームしています。

client.beta.memory_stores.memories.update(
    mem.id,
    memory_store_id=store.id,
    path="/archive/2026_q1_formatting.md",
)

すべてのパラメータとレスポンススキーマについては、メモリ更新のリファレンスを参照してください。

安全なコンテンツ編集（楽観的並行性制御）

同時書き込みを上書きしてしまうことを避けるには、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,
)

すべてのパラメータとレスポンススキーマについては、メモリ削除のリファレンスを参照してください。

メモリの変更を監査する

メモリへのすべての変更は、不変のメモリバージョン（memver_...）を作成します。バージョンエンドポイントを使用して、誰がいつ何を変更したかを監査したり、以前のスナップショットを検査または復元したり、redact で履歴から機密コンテンツを消去したりできます。

バージョンは（個々のメモリではなく）ストアに属し、メモリ自体が削除されても削除されないため、監査証跡は削除されたメモリもカバーします（以下で説明する保持期間に従います）。バージョンは書き込まれてから 30 日間保持されます。ただし、ライブメモリの最近のバージョンは経過期間に関係なく常に保持されるため、変更頻度の低いメモリは 30 日を超えて履歴を保持する場合があります。ライブの memories.retrieve 呼び出しは常に最新バージョンを返し、バージョンエンドポイントは保持されている履歴を提供します。

専用の復元エンドポイントはありません。ロールバックするには、目的のバージョンを取得し、その content を memories.update で書き戻します（親メモリが削除されている場合は、目的のバージョンがまだ保持されていれば 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

すべてのパラメータとレスポンススキーマについては、メモリバージョン一覧のリファレンスを参照してください。

バージョンを取得する

個々のバージョンを取得すると、一覧レスポンスと同じフィールドに加えて完全な content 本文が返されます。

version = client.beta.memory_stores.memory_versions.retrieve(
    version_id,
    memory_store_id=store.id,
)
print(version.content)

すべてのパラメータとレスポンススキーマについては、メモリバージョン取得のリファレンスを参照してください。

バージョンを redact する

redact は、監査証跡（誰がいつ何をしたか）を保持しながら、過去のバージョンからコンテンツを消去します。漏洩したシークレットや PII の削除、ユーザーからの削除リクエストなどのコンプライアンスワークフローに使用してください。

ライブメモリの現在のヘッドであるバージョンは redact できません。まず新しいバージョンを書き込む（またはメモリを削除する）か、その後で古いバージョンを redact してください。

client.beta.memory_stores.memory_versions.redact(
    version_id,
    memory_store_id=store.id,
)

すべてのパラメータとレスポンススキーマについては、メモリバージョン redact のリファレンスを参照してください。

メモリストアを管理する

create に加えて、メモリストアは retrieve、update、list、archive、および delete をサポートしています。

ストアを一覧表示する

ワークスペース内のストアを一覧表示します。アーカイブ済みのストアはデフォルトで除外されます。含めるには 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)

すべてのパラメータとレスポンススキーマについては、メモリストア一覧のリファレンスを参照してください。

ストアをアーカイブする

アーカイブするとストアは読み取り専用になり、新しいセッションにアタッチできなくなります。アーカイブは一方向であり、アーカイブ解除はありません。

client.beta.memory_stores.archive(store.id)

すべてのパラメータとレスポンススキーマについては、メモリストアアーカイブのリファレンスを参照してください。

ストアをそのすべてのメモリおよびバージョンとともに完全に削除するには、memory_stores.delete を使用してください。

メモリ管理のベストプラクティス

ストアが 10,000 件のメモリ上限に達すると、新しいメモリへの書き込みは失敗します。直接の memories.create 呼び出しも、マッピングされていないパスへのエージェントのファイル書き込みも同様です。既存のメモリは引き続き読み取りと編集が可能です。以下のプラクティスは、上限を十分に下回る状態を維持し、上限に達した場合にも適切に回復するのに役立ちます。

• 焦点を絞ったストアを使用する。 1つの大きな汎用ストアではなく、目的別の小さなストアを使用してください。ユーザーごとに1つ、共有ドメイン知識用に1つ、プロジェクト固有のコンテキスト用に1つ、といった形です。各ストアにはそれぞれ 10,000 件のメモリ上限があるため、ストアのスコープを絞っておくことで、いずれか1つが満杯になる可能性を減らせます。

• ストアが満杯になる前に集約または整理する。 古くなったメモリや冗長なメモリは memories.delete で削除してください。また、ドリーミングセッションを実行することもできます。これは元のストアを変更するのではなく、断片化したコンテンツを別の新しい出力ストアに統合します。セッションをその出力ストアに切り替えてから、元のストアをアーカイブまたは削除してください。

• 適切なタイミングで新しいストアをアタッチする。 ストアが有用なスコープを超えて大きくなった場合は、新しいコンテンツ用に新しいストアをアタッチし、元のストアは read_only アクセスでアタッチしてください。エージェントは両方から読み取りつつ、新しいストアにのみ書き込むことができます。

• 適切な場合は書き込みアクセスを制限する。 共有参照資料を読み取るだけのセッションに read_write は必要ありません。書き込みアクセスを実際に新しいメモリを追加するセッションに限定しておくことで、増加がどこから来ているかを追跡しやすくなります。