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

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



概要

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

ストア内の各メモリはパスによってアドレス指定され、APIまたはConsoleを通じて直接読み取りおよび編集できるため、調整、インポート、エクスポートが可能です。

メモリへの変更はすべて、不変のメモリバージョンを作成します。これにより、エージェントが書き込むすべての内容について、監査証跡と特定時点へのリカバリが可能になります。



メモリストアを作成する

ストアにnameとdescriptionを指定します。descriptionはエージェントに渡され、ストアに何が含まれているかを伝えます。

store_id=$(ant beta:memory-stores create \
  --name "User Preferences" \
  --description "Per-user preferences and project context." \
  --transform id --raw-output)

メモリストアのid（memstore_...）は、ストアをセッションにアタッチする際に渡す値です。



コンテンツをシードする（オプション）

エージェントを実行する前に、参照資料をストアに事前ロードします。

ant beta:memory-stores:memories create \
  --memory-store-id "$store_id" \
  --path "/formatting_standards.md" \
  --content "All reports use GAAP formatting. Dates are ISO-8601..." \
  > /dev/null



メモリストアをセッションにアタッチする

メモリストアは、セッション作成時にセッションのresources[]配列でアタッチします。ファイルリソースやリポジトリリソースとは異なり、メモリストアはセッション作成時にのみアタッチできます。実行中のセッションへの追加や削除はサポートされていません。

オプションでinstructionsを含めることで、エージェントがこのストアをどのように使用すべきかについて、セッション固有のガイダンスを提供できます。これはストアのnameおよびdescriptionとともにエージェントに表示され、4,096文字に制限されています。

accessも設定できます。デフォルトはread_write（次の例で明示的に示されています）ですが、read_onlyもサポートされています。

ant beta:sessions create <<YAML
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.
YAML

1つのセッションにつき最大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でフィルタリングして、パスをディレクトリのように閲覧できます。

ant beta:memory-stores:memories list \
  --memory-store-id "$store_id" \
  --path-prefix "/" --order-by path --depth 2

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



メモリを読み取る

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

ant beta:memory-stores:memories retrieve \
  --memory-store-id "$store_id" \
  --memory-id "$mem_id"

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



メモリを作成する

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

mem=$(ant beta:memory-stores:memories create \
  --memory-store-id "$store_id" \
  --path "/preferences/formatting.md" \
  --content "Always use tabs, not spaces." \
  --format json)
mem_id=$(jq -r '.id' <<< "$mem")
mem_sha=$(jq -r '.content_sha256' <<< "$mem")

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



メモリを更新する

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

ant beta:memory-stores:memories update \
  --memory-store-id "$store_id" \
  --memory-id "$mem_id" \
  --path "/archive/2026_q1_formatting.md" \
  > /dev/null

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



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

同時書き込みを上書きしてしまうことを避けるには、content_sha256前提条件を渡します。保存されているコンテンツハッシュが読み取ったものとまだ一致する場合にのみ更新が適用されます。不一致の場合は、メモリを再読み取りし、最新の状態に対して再試行してください。

ant beta:memory-stores:memories update \
  --memory-store-id "$store_id" \
  --memory-id "$mem_id" \
  --content "CORRECTED: Always use 2-space indentation." \
  --precondition "{type: content_sha256, content_sha256: $mem_sha}" \
  > /dev/null



メモリを削除する

ant beta:memory-stores:memories delete \
  --memory-store-id "$store_id" \
  --memory-id "$mem_id" \
  > /dev/null

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



メモリの変更を監査する

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

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

専用の復元エンドポイントはありません。ロールバックするには、目的のバージョンを取得し、そのcontentをmemories.updateで書き戻します（バージョンは親メモリよりも長く存続するため、親メモリが削除されている場合はmemories.createを使用します）。

過去のメモリバージョンは30日後に削除される場合があります。メモリ履歴をより長く保持するには、APIを通じてバージョンをエクスポートしてください。



バージョンを一覧表示する

ストアのバージョン履歴を新しい順に一覧表示します。次の例では、単一のメモリの履歴にフィルタリングしています。

versions=$(ant beta:memory-stores:memory-versions list \
  --memory-store-id "$store_id" \
  --memory-id "$mem_id" \
  --format json)
jq -r '.data[] | "\(.id): \(.operation)"' <<< "$versions"
version_id=$(jq -r '.data[1].id' <<< "$versions")

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



バージョンを取得する

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

ant beta:memory-stores:memory-versions retrieve \
  --memory-store-id "$store_id" \
  --memory-version-id "$version_id"

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



バージョンをredactする

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

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

ant beta:memory-stores:memory-versions redact \
  --memory-store-id "$store_id" \
  --memory-version-id "$version_id"

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



メモリストアを管理する

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



ストアを一覧表示する

ワークスペース内のストアを一覧表示します。アーカイブされたストアはデフォルトで除外されます。含めるにはinclude_archived: trueを渡してください。

ant beta:memory-stores list --include-archived

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



ストアをアーカイブする

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

ant beta:memory-stores archive --memory-store-id "$store_id"

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

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



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

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

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

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

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

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