メモリーを取得する

Agent Platform メモリーバンクを使用すると、ニーズに応じて異なるオペレーションを使用して、保存された記憶を取得できます。単一のメモリの取得、メモリのリスト表示とフィルタリング、類似性検索によるスコープベースの取得を行うことができます。

このドキュメントでは、 Google Cloud コンソールまたは Agent Platform SDK を使用してメモリを取得して検査する方法について説明します。

Agent Development Kit（ADK）を使用すると、エージェントはこれらの呼び出しを自動的にオーケストレートできます。ADK を使用したクイックスタートをご覧ください。

始める前に

このページの手順を完了するには、まず Memory Bank の設定の手順を完了する必要があります。

フェッチ オペレーション

生成されたメモリを取得するには、次のオプションがあります。

• メモリを取得する: Agent Platform SDK を使用して、単一のメモリのコンテンツ全体を取得します。

• メモリを取得する: Agent Platform SDK を使用して、スコープベースのメモリ取得を使用してメモリを取得します。類似性検索またはスコープ内のすべてのメモリを使用して、メモリを取得します。

• メモリを一覧表示する:Google Cloud コンソールまたは Agent Platform SDK を使用して、メモリを一覧表示してフィルタします。

メモリを取得する

GetMemories を使用して、単一のメモリのコンテンツ全体を取得します。

memory = client.memory_banks.memories.get(
    name="MEMORY_NAME")

次のように置き換えます。

• MEMORY_NAME: 「projects/.../locations/.../reasoningEngines/.../memories...」形式の完全修飾メモリ名。

スコープベースの取得を使用してメモリを取得する

RetrieveMemories を使用して、特定のスコープのメモリを取得できます。取得リクエストと同じスコープ（順序は関係ありません）を持つメモリのみが返されます。たとえば、{"user_id": "123"} を使用して、特定のユーザーにスコープ設定されたすべてのメモリを取得できます。メモリが返されない場合、Memory Bank には指定されたスコープのメモリがありません。

メモリのスコープは、メモリの生成時または作成時に定義され、変更できません。

RetrieveMemories を使用して、特定のスコープに対して次のオペレーションを実行できます。

• 類似性検索を使用してメモリを取得する
• すべてのメモリを取得する

類似性検索を使用してメモリを取得する

特定のスコープに多くのメモリがある場合は、類似性検索パラメータを指定して類似性検索を使用すると、最も類似したメモリのみを取得できます。Memory Bank は、類似性検索を実行する際に、リクエストとまったく同じスコープを持つメモリのみを考慮します。類似性検索では、メモリの事実とリクエストの検索クエリのエンベディング ベクトルを比較します。

返されたメモリは、最も類似している（ユークリッド距離が最も短い）ものから最も類似していない（ユークリッド距離が最も長い）ものの順に並べ替えられます。

results = client.memory_banks.memories.retrieve(
    name=memory_bank.name,
    scope=SCOPE,
    similarity_search_params={
        "search_query": "QUERY",
        # Optional. Defaults to 3.
        "top_k": 3
    }
)
# RetrieveMemories returns a pager. You can use `page` to retrieve memories.

results.page

"""
Returns:

[
    RetrieveMemoriesResponseRetrievedMemory(
      memory=Memory(
        name="projects/.../locations/.../reasoningEngines/.../memories/...",
        ...
        fact="This is a fact."
      },
      distance=0.5
    ),
    RetrieveMemoriesResponseRetrievedMemory(
      memory=Memory(
        name="projects/.../locations/.../reasoningEngines/.../memories/...",
        ...
        fact="This is another fact."
      },
      distance=0.7
    ),
]
"""

次のように置き換えます。

• QUERY: 類似検索を実行するクエリ。たとえば、会話の最後のユーザーターンをクエリとして使用できます。

• SCOPE: 類似検索のスコープを表す辞書。例: {"user_id": "123"}リクエストと同じスコープのメモリのみが考慮されます。

すべてのメモリを取得する

類似性検索パラメータが指定されていない場合、RetrieveMemories は、現在の会話との類似性に関係なく、指定されたスコープを持つすべてのメモリを返します。

警告: 類似性検索を使用せずにすべてのメモリを取得すると、複数のページが返されることがあります。RetrieveMemories レスポンスで list() を呼び出すと、すべてのページで自動ページネーションがトリガーされます。大規模なコレクションの場合は、response.page を直接使用してアイテムを 1 ページずつ取得し、予期しない呼び出しを防ぎます。

results = client.memory_banks.memories.retrieve(
    name=memory_bank.name,
    scope=SCOPE
)
# RetrieveMemories returns a pager. You can use `page` to retrieve up to 100 memories per page.

results.page

"""
Returns:

[
    RetrieveMemoriesResponseRetrievedMemory(
      memory=Memory(
        name="projects/.../locations/.../reasoningEngines/.../memories/...",
        ...
        fact="This is a fact."
      }
    ),
    RetrieveMemoriesResponseRetrievedMemory(
      memory=Memory(
        name="projects/.../locations/.../reasoningEngines/.../memories/...",
        ...
        fact="This is another fact."
      }
    ),
]
"""

次のように置き換えます。

• SCOPE: 取得のスコープを表す辞書。例: {"user_id": "123"}リクエストと同じスコープのメモリのみが返されます。

メモリの一覧表示

メモリの一覧表示と検査は、 Google Cloud コンソールまたは Agent Platform SDK で行うことができます。

コンソール

Google Cloud コンソールでメモリを表示してフィルタするには（aiplatform.memories.list が必要。roles/aiplatform.memoryViewer と roles/aiplatform.memoryUser に含まれています）:

1. Google Cloud コンソールでインスタンスを開きます。

   • スタンドアロンの Memory Bank インスタンス: Agent Platform の [Memory Bank] ページに移動し、インスタンスをクリックします。

     Memory Bank に移動

   • Agent Runtime にデプロイされたエージェント: Agent Platform の [デプロイ] ページに移動し、エージェントをクリックします。

     [デプロイメント] に移動

2. [思い出] タブを開きます。デフォルトでは、[非構造化] ビューにメモリのテーブル（[スコープ]、[リソース名]、[ファクト]、[作成日時]、[更新日時]）が表示されます。

3. 省略可: 思い出をフィルタまたは管理します。

   • スコープでフィルタする: フィルタバーに key:value ペア（user_id:123 など）を入力するか、任意の行のスコープチップをクリックします。
   • 構造化プロファイルを表示する: [構造化] に切り替えて完全なスコープを選択するか、[非構造化] でスコープ フィルタを適用して [構造化メモリを検索] をクリックします。詳細については、メモリ プロファイルをご覧ください。
   • 編集、リビジョンの検査、削除: メモリ行のその他の操作メニュー（）をクリックし、[編集]、[リビジョンを表示]、[削除] のいずれかを選択します。

Agent Platform SDK

警告: ListMemories レスポンスで list() を呼び出すと、すべてのページで自動ページネーションがトリガーされます。大規模なコレクションの場合は、response.page を直接使用してアイテムを 1 ページずつ取得し、予期しない呼び出しを防止します。

ListMemories を使用して、スコープベースのフィルタリングなしで Memory Bank からメモリを一覧表示します。スコープベースの取得には、代わりに RetrieveMemories を使用します。ListMemories は、低レイテンシの取得にはおすすめしません。

pager = client.memory_banks.memories.list(name=memory_bank.name)
for page in pager:
  print(page)

思い出をフィルタする

このセクションでは、フィルタを使用して、取得するメモリを制限する方法について説明します。以下に基づいてフィルタできます。

• スコープベースの取得に filter_groups 属性を使用するメタデータ。

• filter を使用するシステム フィールド。システム フィールドには、メモリの topics、create_time、update_time、fact が含まれます。

メタデータとシステム フィールドのフィルタリングは、同じリクエストで使用できます。

メタデータでフィルタする

注: メタデータによるフィルタリングは、スコープベースの取得とメモリのパージでのみサポートされています。

メモリの作成、更新、生成時に、保存されたメモリに構造化メタデータを適用できます。

import datetime

from agentplatform import types

metadata = {
    "my_string_key": types.MemoryMetadataValue(string_value="my_string_value"),
    "my_double_key": types.MemoryMetadataValue(double_value=123.456),
    "my_boolean_key": types.MemoryMetadataValue(bool_value=True),
    "my_timestamp_key": types.MemoryMetadataValue(
        timestamp_value=datetime.datetime(
            2027, 1, 1, 12, 30, 00, tzinfo=datetime.timezone.utc
        )
    ),
}

client.memory_banks.memories.create(
  ...,
  config={"metadata": metadata}
)

client.memory_banks.memories.update(
  ...,
  config={"metadata": metadata}
)

client.memory_banks.memories.generate(
  ...,
  config={"metadata": metadata}
)

filter_groups 属性を使用してメモリを取得するときに、このメタデータでフィルタできます。メタデータ フィルタは、選言標準形（DNF）で定義されます。これは、AND の OR の論理式です。

たとえば、次のリクエストは、メタデータ（{"my_string_key": {"string_value": "my_value"}} AND {"my_double_key": {"double": 1.23}}）OR {"my_string_key": {"string_value": "other"}} を含むメモリを取得します。

辞書

results = client.memory_banks.memories.retrieve(
  ...,
  config={
    # Each element of `filter_groups` is combined using OR logic.
    "filter_groups": [
      {
        # Each element of `filters` is combined using AND logic.
        "filters": [
          {
            "key": "my_string_key",
            "value": {"string_value": "my_value"}
          },
          {
            "key": "my_double_key",
            "value": {"double_value": 1.23}
          }
        ]
      },
      {
        "filters": [
          {
            "key": "my_string_key",
            "value": {"string_value": "other"}
          }
        ]
      }
    ]
  }
)

クラスベース

from agentplatform import types

results = client.memory_banks.memories.retrieve(
  ...,
  config=types.RetrieveMemoriesConfig(
    # Each element of `filter_groups` is combined using OR logic.
    filter_groups=[
      types.MemoryConjunctionFilter(
        # Each element of `filters` is combined using AND logic.
        filters=[
          types.MemoryFilter(
            key="my_string_key",
            value=types.MemoryMetadataValue(string_value="my_value")
          ),
          types.MemoryFilter(
            key="my_double_key",
            value=types.MemoryMetadataValue(double_value=1.23)
          )
        ]
      ),
      types.MemoryConjunctionFilter(
        filters=[
          types.MemoryFilter(
            key="my_string_key",
            value=types.MemoryMetadataValue(string_value="other")
          )
        ]
      )
    ]
  )
)

システム フィールドでフィルタする

システム フィールドをフィルタするには、filter 属性を使用します。この属性には、EBNF 構文を使用した文字列値が必要です。システム フィールドには、create_time、update_time、fact、topics があります。

EBNF 構文では、フィルタ文字列を作成する際に次の要件があります。

• フィルタを組み合わせるには、AND と OR を使用します。
• 文字列には二重引用符 " を使用する必要があります。
• 日時フィールド（create_time など）では、ISO 8601 の日時を表す二重引用符で囲まれた文字列か、Unix エポックからのマイクロ秒を表す数値フィールドを使用します。

たとえば、次のフィルタを使用すると、fact に部分文字列「allergies」が含まれ、update_time が 2026 年 1 月 1 日以降のメモリを取得できます。

filter_string = 'fact=~".*allergies.*" AND update_time>="2026-01-01T00:00:00Z"'

client.memory_banks.memories.retrieve(
  ...,
  config={"filter": filter_string}
)

client.memory_banks.memories.list(
  ...,
  config={"filter": filter_string}
)

トピックでフィルタ

生成されたメモリには、関連するメモリトピックが自動的にラベル付けされます。

管理対象トピックでフィルタするには、フィールド名として topics.managed_memory_topic を使用し、値として想定される ManagedTopicEnum を使用します（例: topics.managed_memory_topic: USER_PREFERENCES）。

カスタム トピックでフィルタするには、フィールド名として topics.custom_memory_topic_label を使用し、想定されるトピックのラベルを値として使用します（例: topics.custom_memory_topic_label: custom-label）。

filter_string = "topics.managed_memory_topic: USER_PREFERENCES " + \
"OR topics.custom_memory_topic_label: custom-label"

client.memory_banks.memories.retrieve(
  ...,
  config={"filter": filter_string}
)

client.memory_banks.memories.list(
  ...,
  config={"filter": filter_string}
)