提取记忆内容

本页面介绍了如何从记忆库中提取生成的记忆和上传的记忆。如需了解配置、生成和使用记忆库的完整工作流程，请参阅 REST API 快速入门。

准备工作

如需完成本页面中的步骤，您必须先完成设置记忆库中的步骤。

提取操作

您可以通过以下方式获取生成的记忆：

获取记忆：使用 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 可提取记忆库中的所有记忆。

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

使用基于范围的检索功能提取记忆

您可以使用 RetrieveMemories 检索特定范围内的记忆。系统只会返回与检索请求具有完全相同范围（不考虑顺序）的记忆。例如，您可以使用 {"user_id": "123"} 检索特定用户范围内的所有记忆。如果未返回任何记忆，则表示记忆库中没有与所提供范围相关的记忆。

记忆的范围在生成或创建记忆时定义，且不可变。

您可以使用 RetrieveMemories 对特定范围执行以下操作：

使用相似度搜索功能检索记忆
检索所有记忆

使用相似度搜索功能检索记忆

如果您在特定范围内有很多记忆内容，可以使用相似度搜索参数，仅检索最相似的记忆内容。在执行相似度搜索时，记忆库只会考虑范围与请求完全相同的记忆。相似度搜索会比较记忆的事实与请求的搜索查询之间的嵌入向量。

返回的回忆按相似度从高（欧几里得距离最短）到低（欧几里得距离最长）排序：

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 连接的子句的 OR 逻辑表达式。

例如，以下请求将检索包含元数据（{"my_string_key": {"string_value": "my_value"}} 和 {"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

使用基于范围的检索功能提取记忆

使用相似度搜索功能检索记忆

检索所有记忆

过滤回忆

按元数据过滤

字典

基于类

按系统字段过滤

按主题过滤

提取记忆内容