Google 会使用 AI 技术将内容翻译成您偏好的语言。AI 翻译可能包含错误。

内存修订版本

Agent Platform 记忆库通过记忆修订版本资源自动维护记忆的版本记录。每次创建或修改记忆时，系统都会保存一个新的不可变修订版本，以便您清楚了解信息的演变过程以及每个步骤中提取的内容。

本文档介绍了记忆及其修订版本的生命周期，并介绍了列出、获取和回滚修订版本等操作。

如需详细了解如何生成回忆，请参阅生成回忆。

记忆及其修订版本的生命周期

数据源和记忆修订

记忆可以直接创建、更新或删除（分别使用 CreateMemory、UpdateMemory 或 DeleteMemory），也可以动态创建、更新或删除（使用 GenerateMemories）。记忆修订版本资源提供了记忆资源在所有变更操作中的完整版本历史记录。每次创建或修改记忆时，系统都会自动保存一个新的不可变修订版本。这样，您就可以清楚地了解记忆是如何演变的，以及（对于记忆生成）在每个步骤中提取和整合了哪些具体信息。

每个内存资源都有一个或多个关联的子内存修订版本资源：

Memory 资源始终反映信息的当前整合状态。一条记忆可能反映了来自多个请求和数据源的派生数据。

Memory(
    create_time=datetime.datetime(...),
    fact='This is my current memory content after consolidation',
    name='projects/.../locations/.../reasoningEngines/../memories/...',
    scope={
      'my_scope_key': 'my_scope_value'
    },
    topics=[
      MemoryTopicId(
        managed_memory_topic=<ManagedTopicEnum.USER_PERSONAL_INFO: 'USER_PERSONAL_INFO'>
      ),
    ],
    update_time=datetime.datetime(...)
)

MemoryRevisions 资源表示父级内存的历史状态。每个修订版本都是发生变更事件时的记忆快照。如果使用 GenerateMemories 更改了记忆，则修订版本还包含从数据源 (extracted_memories) 提取的信息，这些信息在与记忆的现有内容合并之前会先提取出来。

MemoryRevision(
    create_time=datetime.datetime(...),
    expire_time=datetime.datetime(...),
    extracted_memories=[
      IntermediateExtractedMemory(
        fact='This information was extracted from my data source'
      ),
    ],
    fact='This is my current memory content after consolidation',
    name='projects/.../locations/.../reasoningEngines/.../memories/.../revisions/...'
)

记忆修订功能默认处于启用状态。如需停用记忆修订，请参阅停用记忆修订。

创建回忆

记忆可以直接使用 CreateMemory 创建，也可以使用 GenerateMemories 动态创建。通过记忆生成，如果不存在涵盖同一范围内类似信息的现有记忆，系统会创建记忆：

# Direct creation using CreateMemory
client.memory_banks.memories.create(name=memory_bank_name, ...)

# Dynamic creation using GenerateMemory
client.memory_banks.memories.generate(name=memory_bank_name, ...)

创建记忆时，系统会创建一个 Memory 资源和一个子 MemoryRevision：

client.memory_banks.memories.get(name=memory_name)
"""
Memory(
  name="projects/123/locations/us-central1/reasoningEngines/456/memories/789",
  fact="This is my original fact.",
  ...
)
"""

list(client.memory_banks.memories.revisions.list(name=memory_name))
"""
[
  MemoryRevision(
    name="projects/123/locations/us-central1/reasoningEngines/456/memories/789/revision/123",
    fact="This is my original fact",
    ...
  )
]
"""

记忆更新

您可以使用 UpdateMemory 直接更新记忆，也可以使用 GenerateMemories 动态更新记忆。在记忆生成过程中，当整合过程判定新信息与同一范围内的所有现有记忆存在重复、互补或矛盾时，记忆会动态更新。

# Direct update using UpdateMemory
client.memory_banks.memories.update(name=memory_name, ...)

# Dynamic update using GenerateMemories
client.memory_banks.memories.generate(name=memory_bank_name, ...)

更新记忆时，系统会更新现有 Memory 资源，并创建新的子 MemoryRevision。

client.memory_banks.memories.get(name=memory_name)
"""
Memory(
  name="projects/123/locations/us-central1/reasoningEngines/456/memories/789",
  fact="This is my updated fact.",
  ...
)
"""

list(client.memory_banks.memories.revisions.list(name=memory_name))
"""
[
  MemoryRevision(
    name="projects/123/locations/us-central1/reasoningEngines/456/memories/789/revision/456",
    fact="This is my updated fact",
    ...
  ),
  MemoryRevision(
    name="projects/123/locations/us-central1/reasoningEngines/456/memories/789/revision/123",
    fact="This is my original fact",
    ...
  )
]
"""

删除记忆

记忆功能既可以直接使用 DeleteMemory，也可以动态使用 GenerateMemories。在记忆生成过程中，如果整合过程判定新信息使同一范围内的现有信息失效，则会动态删除这些记忆。

# Direct deletion using UpdateMemory
client.memory_banks.memories.delete(name=memory_name, ...)

# Dynamic delete using GenerateMemories
client.memory_banks.memories.generate(name=memory_bank_name, ...)

删除记忆时，系统会删除现有 Memory 资源，并创建新的子级 MemoryRevision。最新内存修订版本中的 fact 为空，因为它反映了删除变更。

client.memory_banks.memories.get(name=memory_name)
"""
404 Not Found.
"""

list(client.memory_banks.memories.revisions.list(name=memory_name))
"""
[
  MemoryRevision(
    name="projects/123/locations/us-central1/reasoningEngines/456/memories/789/revision/789",
    fact="",
    ...
  ),
  MemoryRevision(
    name="projects/123/locations/us-central1/reasoningEngines/456/memories/789/revision/456",
    fact="This is my updated fact",
    ...
  ),
  MemoryRevision(
    name="projects/123/locations/us-central1/reasoningEngines/456/memories/789/revision/123",
    fact="This is my original fact",
    ...
  )
]
"""

子级记忆修订版本在父级记忆删除后最多只能访问 48 小时。在此恢复期内，您可以继续检查内存修订版本，并可以通过将内存回滚到之前的修订版本来恢复内存。

记忆修订版本操作

本部分介绍了如何检查记忆修订版本，以及如何将记忆回滚到之前的修订版本。

列出修订版本

您可以在 Google Cloud 控制台中或使用 Agent Platform SDK 检查记忆修订版本。

控制台

如需在 Google Cloud 控制台中查看内存修订版本，需要拥有 aiplatform.memoryRevisions.list 权限（包含在 roles/aiplatform.memoryViewer 和 roles/aiplatform.memoryUser 中），并且该功能在快速模式下不可用。

在 Google Cloud 控制台中打开您的实例：
- 独立记忆库实例：前往 Agent Platform 记忆库页面，然后点击您的实例。
  
  前往记忆库
- 在 Agent Runtime 上部署的智能体：前往 Agent Platform Deployments（部署）页面，然后点击您的智能体。
  
  前往“部署”页面
打开回忆标签页：
- 非结构化记忆：在记忆行中，依次点击更多操作菜单 () > 查看修订版本。
- 结构化个人资料（独立实例）：选择结构化，选择完整范围，点击个人资料行中的查看以打开记忆详情，然后点击记忆事实的查看修订版本。
修订版本面板会列出每个修订版本的创建时间、到期时间、事实和上下文字段。

Agent Platform SDK

使用 ListMemoryRevisions 可返回属于某个记忆的所有记忆修订版本。

list(client.memory_banks.memories.revisions.list(name=MEMORY_NAME))

替换以下内容：

MEMORY_NAME：记忆功能的资源名称，格式为：projects/.../locations/.../reasoningEngines/.../memories/...

生成记忆时，您可以提供应用于关联修订版本的修订版本标签。标签是任意键值对。例如，您可以使用用于生成记忆的数据源的 ID 为修订版本添加标签，然后按此标签过滤修订版本：

response = client.memory_banks.memories.generate(
    ...,
    config={
        "revision_labels": {
            "data_source": "321"
        }
    }
)

list(client.memory_banks.memories.revisions.list(
    name=MEMORY_NAME,
    config={
      "filter": "labels.data_source=\"321\""
    }
))
"""
[
  MemoryRevision(
    name="projects/123/locations/us-central1/reasoningEngines/456/memories/789/revision/123",
    labels={
      "data_source": "123"
    }
    ...
  )
]
"""

申请修订

使用 GetMemoryRevision 提取单个记忆修订版本。

client.memory_banks.memories.revisions.get(name=MEMORY_REVISION_NAME)

替换以下内容：

MEMORY_REVISION_NAME：要提取的记忆修订版本的资源名称，格式为：projects/.../locations/.../reasoningEngines/.../memories/.../revisions/...

回滚记忆

使用 RollbackMemory 可将记忆回滚到之前的修订版本。

client.memory_banks.memories.rollback(
    name="MEMORY_NAME",
    target_revision_id="REVISION_ID"
)

替换以下内容：

MEMORY_NAME：要更新的记忆的资源名称，格式如下： projects/.../locations/.../reasoningEngines/.../memories/...
REVISION_ID：应回滚到的修订版本的 ID。这是记忆修订版本资源名称的最后一部分，例如 projects/MyProject/locations/us-central1/reasoningEngines/123/memories/456/revisions/789 中的 789。

如果您想撤消 GenerateMemories 对记忆所做的更改，请将记忆回滚到更改前的修订版本。记忆生成响应包含对每个更新或删除的记忆的先前修订版本 (previous_revision) 的引用：

operation = client.memory_banks.memories.generate(
  ...
)

# Rollback the first generated memory to the previous revision.
client.memory_banks.memories.rollback(
    name=operation.response.generated_memories[0].memory.name,
    target_revision_id=operation.response.generated_memories[0].previous_revision
)

停用记忆修订版本

记忆修订功能默认处于启用状态。您可以针对向 Memory Bank 实例发出的所有请求或针对每个单独的请求停用记忆修订功能。如果记忆修订版本功能已停用，则在记忆发生变化时，系统不会创建记忆修订版本。

您可以在 Google Cloud 控制台中（在配置 > 保留下，或在已部署智能体的服务配置 > 记忆库下）或使用 Agent Platform SDK，为对记忆库实例的所有请求关闭记忆修订功能：

memory_bank = client.memory_banks.create(
  managed_semantic_memory_config={
    "disable_memory_revisions": True
  }
)

您可以在发送请求时在请求级别停用记忆功能修订：

生成

client.memory_banks.memories.generate(
  ...,
  "config": {
    "disable_memory_revisions": True
  }
)

创建

client.memory_banks.memories.create(
  ...,
  "config": {
    "disable_memory_revisions": True
  }
)

更新

client.memory_banks.memories.update(
  ...,
  "config": {
    "disable_memory_revisions": True
  }
)

修订版本到期时间

记忆修订版本不会永久保留。您必须设置修订版本的到期时间，或使用默认到期时间。默认存留时间 (TTL) 为 365 天。您可以为向 Memory Bank 实例发出的所有请求配置失效时间，也可以为每个单独的请求配置失效时间。记忆修订版本过期后，将无法进行检查或回滚。

您可以在 Google Cloud 控制台中（在配置 > 保留下，或在服务配置 > 记忆库下，适用于已部署的智能体），或使用 Agent Platform SDK，为向记忆库实例发出的所有请求配置修订历史记录 TTL：

client.memory_banks.create(
  managed_semantic_memory_config={
    "ttl_config": {
      # Persist memory revisions for 30 days after they're created.
      "revision_ttl": f"{30 * 60 * 60 * 24}s"
    }
  }
)

如需在请求级别为每个记忆修订版本配置 TTL，请在请求中添加 revision_expire_time 或 revision_ttl：

TTL

config = {
    # Persist memory revisions for 30 days after they're created.
    "revision_ttl": f"{30 * 60 * 60 * 24}s"
}

client.memory_banks.memories.create(
  ...,
  config=config
)

client.memory_banks.memories.update(
  ...,
  config=config
)

client.memory_banks.memories.generate(
  ...,
  config=config
)

失效时间

import datetime

config = {
    "revision_expire_time": datetime.datetime.now(tz=datetime.timezone.utc) + datetime.timedelta(weeks=3)
}

client.memory_banks.memories.create(
  ...,
  config=config
)

client.memory_banks.memories.update(
  ...,
  config=config
)

client.memory_banks.memories.generate(
  ...,
  config=config
)

内存修订版本 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

记忆及其修订版本的生命周期

创建回忆

记忆更新

删除记忆

记忆修订版本操作

列出修订版本

控制台

Agent Platform SDK

申请修订

回滚记忆

停用记忆修订版本

生成

创建

更新

修订版本到期时间

TTL

失效时间

内存修订版本