内存修订版本

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

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

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

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

数据源和内存修订版本

您可以直接（分别使用 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.agent_engines.memories.create(name=memory_bank_name, ...)

# Dynamic creation using GenerateMemory
client.agent_engines.memories.generate_memories(name=memory_bank_name, ...)

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

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

list(client.agent_engines.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.agent_engines.memories.update(name=memory_name, ...)

# Dynamic update using GenerateMemories
client.agent_engines.memories.generate_memories(name=memory_bank_name, ...)

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

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

list(client.agent_engines.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.agent_engines.memories.delete(name=memory_name, ...)

# Dynamic delete using GenerateMemories
client.agent_engines.memories.generate_memories(name=memory_bank_name, ...)

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

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

list(client.agent_engines.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.agent_engines.memories.revisions.list(name=MEMORY_NAME))

替换以下内容：

  • MEMORY_NAME：内存的资源名称，格式为：projects/.../locations/.../reasoningEngines/.../memories/...

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

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

list(client.agent_engines.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.agent_engines.memories.revisions.get(name=MEMORY_REVISION_NAME)

替换以下内容：

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

回滚回忆

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

client.agent_engines.memories.rollback(
    name=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.agent_engines.memories.generate(
  ...
)

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

停用内存修订版本

记忆修订版本默认处于启用状态。您可以为记忆库实例的所有请求或每个单独的请求停用记忆修订版本。如果停用记忆修订版本，则在记忆发生变异时不会创建记忆修订版本。

您可以在设置记忆库实例时，针对向该实例发出的所有请求停用记忆修订：

memory_bank = client.agent_engines.create(
  config={
    "context_spec": {
      "memory_bank_config": {
        "disable_memory_revisions": True
      }
    }
  }
)

您可以在发送请求时在请求级停用内存修订：

生成

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

创建

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

更新

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

修订版本过期

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

您可以在设置记忆库实例时，为向该实例发出的所有请求配置 TTL：

client.agent_engines.create(
  config={
    "context_spec": {
      "memory_bank_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.agent_engines.memories.create(
  ...,
  config=config
)

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

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

到期日期

import datetime

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

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

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

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