O Memory Bank mantém automaticamente um histórico de versões das suas memórias usando recursos de revisão de memória. Sempre que uma memória é criada ou modificada, uma nova revisão imutável é salva, oferecendo transparência sobre como as informações evoluem e o que foi extraído em cada etapa.
Este documento explica o ciclo de vida das memórias e das revisões delas, além de descrever operações como listar, receber e reverter revisões.
Para mais informações sobre como gerar memórias, consulte Gerar memórias.
Ciclo de vida de uma memória e das revisões dela
As memórias podem ser criadas, atualizadas ou excluídas diretamente (usando CreateMemory, UpdateMemory ou DeleteMemory, respectivamente) ou dinamicamente (usando GenerateMemories). Os recursos de revisão de memória oferecem um histórico de versões completo de um recurso de memória em todas as operações de mutação. Uma nova revisão imutável é salva automaticamente sempre que a memória é criada ou modificada. Isso oferece transparência sobre como uma Memória evoluiu e (para a geração de dados de memória) quais informações específicas foram extraídas e consolidadas em cada etapa.
Cada recurso de memória tem um ou mais recursos de revisão de memória filhos associados:
Os recursos
Memorysempre refletem o estado atual e consolidado das informações. Uma única memória pode refletir dados derivados de várias solicitações e fontes de dados.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(...) )Os recursos
MemoryRevisionsrepresentam os estados históricos da memória mãe. Cada revisão é um snapshot da memória em um evento de mutação. Se uma memória foi mutada usandoGenerateMemories, a revisão também inclui as informações extraídas da fonte de dados (extracted_memories) antes de serem consolidadas com o conteúdo atual da memória.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/...' )As revisões de memória são ativadas por padrão. Para desativar as revisões de memória, consulte Como desativar as revisões de memória.
Criação de memória
As memórias podem ser criadas diretamente usando CreateMemory ou dinamicamente usando GenerateMemories. Com a geração de dados de memória, uma memória é criada se não houver memórias que cubram informações semelhantes para o mesmo escopo:
# 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, ...)
Quando uma memória é criada, um único Memory recurso e um filho
MemoryRevision são criados:
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",
...
)
]
"""
Atualização de memória
As memórias podem ser atualizadas diretamente usando UpdateMemory ou dinamicamente usando GenerateMemories. Com a geração de dados de memória, as memórias são dinamicamente
atualizadas quando o processo de consolidação
decide que as novas informações são duplicadas, complementares ou contraditórias
a todas as memórias atuais do mesmo escopo.
# 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, ...)
Quando uma memória é atualizada, o recurso Memory atual é atualizado e um novo
filho MemoryRevision é criado.
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",
...
)
]
"""
Exclusão de memória
As memórias podem ser excluídas diretamente usando DeleteMemory ou dinamicamente usando GenerateMemories. Com a geração de dados de memória, as memórias são excluídas dinamicamente quando o processo de consolidação decide que as novas informações invalidam as informações atuais do mesmo escopo.
# 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, ...)
Quando uma memória é excluída, o recurso Memory atual é excluído e um novo
filho MemoryRevision é criado. O fact na revisão de memória mais recente está vazio porque reflete uma mutação de exclusão.
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",
...
)
]
"""
As revisões de memória filhas só ficam acessíveis por até 48 horas após a exclusão da memória mãe. Durante essa janela de recuperação, você pode continuar inspecionando as revisões de memória e recuperar a memória revertendo-a para uma revisão anterior.
Operações de revisão de memória
Esta seção descreve como inspecionar revisões de memória e reverter uma memória para uma revisão anterior.
Listar revisões
Use ListMemoryRevisions para retornar todas as revisões de memória pertencentes a uma memória.
list(client.agent_engines.memories.revisions.list(name=MEMORY_NAME))
Substitua:
MEMORY_NAME: nome do recurso da memória no formato:projects/.../locations/.../reasoningEngines/.../memories/...
Ao gerar memórias, é possível fornecer rótulos de revisão que são aplicados às revisões afiliadas. Os rótulos são pares de chave-valor arbitrários. Por exemplo, é possível rotular revisões com um ID da fonte de dados usada para gerar a memória e, em seguida, filtrar as revisões por esse rótulo:
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"
}
...
)
]
"""
Receber uma revisão
Use GetMemoryRevision para buscar uma revisão de memória individual.
client.agent_engines.memories.revisions.get(name=MEMORY_REVISION_NAME)
Substitua:
MEMORY_REVISION_NAME: nome do recurso da revisão de memória a ser buscado no formato:projects/.../locations/.../reasoningEngines/.../memories/.../revisions/...
Reverter uma memória
Use RollbackMemory para reverter uma memória para uma revisão anterior.
client.agent_engines.memories.rollback(
name=name=MEMORY_NAME,
target_revision_id=REVISION_ID
)
Substitua:
MEMORY_NAME: nome do recurso da memória a ser atualizado no formato:projects/.../locations/.../reasoningEngines/.../memories/...REVISION_ID: ID da revisão para a qual a memória precisa ser revertida. Esse é o último segmento do nome do recurso de revisão de memória, como789emprojects/MyProject/locations/us-central1/reasoningEngines/123/memories/456/revisions/789.
Se você quiser desfazer uma mudança em uma memória feita por GenerateMemories, reverter a memória para a revisão anterior à mudança. A resposta de geração de dados de memória inclui uma referência à revisão anterior (previous_revision) para cada memória atualizada ou excluída:
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
)
Como desativar as revisões de memória
As revisões de memória são ativadas por padrão. É possível desativar as revisões de memória para todas as solicitações da instância do Memory Bank ou para cada solicitação individual. Se as revisões de memória estiverem desativadas, uma revisão de memória não será criada quando a memória for mutada.
É possível desativar as revisões de memória para todas as solicitações da instância do Memory Bank ao configurar a instância:
memory_bank = client.agent_engines.create(
config={
"context_spec": {
"memory_bank_config": {
"disable_memory_revisions": True
}
}
}
)
É possível desativar as revisões de memória no nível da solicitação ao enviar a solicitação:
Gerar
client.agent_engines.memories.generate(
...,
"config": {
"disable_memory_revisions": True
}
)
Criar
client.agent_engines.memories.create(
...,
"config": {
"disable_memory_revisions": True
}
)
Atualizar
client.agent_engines.memories.update(
...,
"config": {
"disable_memory_revisions": True
}
)
Validade da revisão
As revisões de memória não são mantidas para sempre. É necessário definir a validade das revisões ou usar a validade padrão. O tempo de vida útil (TTL) padrão é de 365 dias. É possível configurar a validade para todas as solicitações da instância do Memory Bank ou para cada solicitação individual. Depois que uma revisão de memória expira, ela não fica disponível para inspeção ou reversões.
É possível configurar o TTL para todas as solicitações da instância do Memory Bank ao configurar a instância:
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"
}
}
}
}
)
Para configurar o TTL de cada revisão de memória no nível da solicitação, inclua revision_expire_time ou revision_ttl na solicitação:
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
)
Expiração
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
)