内存修订版本

记忆库通过记忆修订版资源自动维护记忆的版本记录。每次创建或修改记忆时，系统都会保存一个新的不可变修订版本，从而让您清楚了解信息是如何演变的，以及在每个步骤中提取了哪些信息。

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

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

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

数据源和内存修订版本

您可以直接（分别使用 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 小时。在此恢复期内，您可以继续检查记忆修订版本，还可以通过将记忆回滚到之前的修订版本来恢复记忆。

记忆修订版本操作

本部分介绍如何检查内存修订版本以及如何将内存回滚到之前的修订版本。

列出修订版本

使用 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 = 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 实例的所有请求或每个单独的请求配置过期时间。内存修订版本一旦过期，就无法再进行检查或回滚。

您可以在设置记忆库实例时，为向该实例发出的所有请求配置 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
)