メモリーを取得する

このページでは、生成されたメモリやアップロードされたメモリを Memory Bank から取得する方法について説明します。Memory Bank の構成、生成、使用のワークフロー全体については、REST API のクイックスタートをご覧ください。

始める前に

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

フェッチオペレーション

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

メモリを取得する: Vertex AI SDK を使用して、単一のメモリのコンテンツ全体を取得します。
メモリを一覧表示する: Vertex AI SDK または Google Cloud コンソールを使用してメモリを一覧表示します。
メモリを取得する: Vertex AI SDK を使用して、スコープベースのメモリ取得を使用してメモリを取得します。類似性検索またはスコープ内のすべてのメモリを使用して、メモリを取得します。

メモリを取得する

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

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

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

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

メモリの一覧表示

コンソール

デプロイされたエージェントの場合は、 Google Cloud コンソールを使用して、Agent Engine インスタンスに関連付けられているすべてのメモリを一覧表示できます。

Google Cloud コンソールで、[Vertex AI Agent Engine] ページに移動します。
Agent Engine に移動

選択したプロジェクトの一部である Agent Engine インスタンスがリストに表示されます。[フィルタ] フィールドを使用して、指定した列でリストをフィルタできます。
Agent Engine インスタンスの名前をクリックします。
[思い出] タブをクリックします。思い出のリストが ID 順に表示されます。

Vertex AI SDK

ListMemories を使用して、Memory Bank 内のすべてのメモリを取得します。

pager = client.agent_engines.memories.list(name=agent_engine.api_resource.name)
for page in pager:
  print(page)

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

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

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

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

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

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

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

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

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

"""
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 は、現在の会話との類似性に関係なく、指定されたスコープを持つすべてのメモリを返します。

results = client.agent_engines.memories.retrieve(
    name=agent_engine.api_resource.name,
    scope=SCOPE
)
# RetrieveMemories returns a pager. You can use `list` to retrieve all pages' memories.
list(results)

"""
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"} のようにします。リクエストと同じスコープのメモリのみが返されます。

思い出をフィルタする

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

スコープベースの取得に filter_groups 属性を使用するメタデータ。
filter を使用するシステムフィールド。システムフィールドには、メモリーの topics、create_time、update_time、fact が含まれます。

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

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

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

import datetime

from vertexai 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.agent_engines.memories.create(
  ...,
  config={"metadata": metadata}
)

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

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

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

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

辞書

results = client.agent_engines.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 vertexai import types

results = client.agent_engines.memories.retrieve(
  ...,
  config=types.RetrieveAgentEngineMemoriesConfig(
    # 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.agent_engines.memories.retrieve(
  ...,
  config={"filter": filter_string}
)

client.agent_engines.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.agent_engines.memories.retrieve(
  ...,
  config={"filter": filter_string}
)

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

メモリーを取得する コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

始める前に

フェッチ オペレーション

メモリを取得する

メモリの一覧表示

コンソール

Vertex AI SDK

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

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

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

思い出をフィルタする

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

辞書

クラスベース

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

トピックでフィルタする

メモリーを取得する

フェッチオペレーション

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