O Memory Bank mantém automaticamente um histórico de versões das suas memórias com recursos de revisão de memória. Cada vez 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 recordações 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 suas revisões
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 fornecem um histórico completo de versões 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 filhos de revisão de memória 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 principal. Cada revisão é um snapshot da memória em um evento de mutação. Se uma memória foi alterada 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 Desativar revisões de memória.
Criação de recordações
As recordações podem ser criadas diretamente usando CreateMemory ou de forma dinâmica 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.memory_banks.memories.create(name=memory_bank_name, ...)
# Dynamic creation using GenerateMemory
client.memory_banks.memories.generate(name=memory_bank_name, ...)
Quando uma recordação é criada, um único recurso Memory e um filho MemoryRevision são criados:
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",
...
)
]
"""
Atualização de recordação
As recordações podem ser atualizadas diretamente usando UpdateMemory ou dinamicamente
usando GenerateMemories. Com a geração de dados de memória, as recordações são atualizadas dinamicamente quando o processo de consolidação decide que as novas informações são duplicadas, complementares ou contraditórias a todas as recordações existentes para o mesmo escopo.
# 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, ...)
Quando uma memória é atualizada, o recurso Memory existente é atualizado, e um novo
MemoryRevision filho é criado.
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",
...
)
]
"""
Exclusão de recordações
As recordações podem ser criadas diretamente usando DeleteMemory ou dinamicamente usando GenerateMemories. Com a geração de dados de memória, as recordações 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.memory_banks.memories.delete(name=memory_name, ...)
# Dynamic delete using GenerateMemories
client.memory_banks.memories.generate(name=memory_bank_name, ...)
Quando uma memória é excluída, o recurso Memory atual é excluído, e um novo
MemoryRevision filho é criado. O fact na revisão de memória mais recente está
vazio porque reflete uma mutação de exclusão.
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",
...
)
]
"""
As revisões da memória da criança só ficam acessíveis por até 48 horas após a exclusão da memória do familiar responsável. Durante esse período de recuperação, você pode continuar inspecionando as revisões de memória e recuperá-la revertendo 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.memory_banks.memories.revisions.list(name=MEMORY_NAME))
Substitua:
MEMORY_NAME: nome do recurso da memória no formato:projects/.../locations/.../reasoningEngines/.../memories/...
Ao gerar recordações, você pode 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, você pode rotular revisões com um ID da fonte de dados usada para gerar a memória e depois filtrar as revisões por esse rótulo:
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"
}
...
)
]
"""
Receber uma revisão
Use GetMemoryRevision para buscar uma revisão de memória individual.
client.memory_banks.memories.revisions.get(name=MEMORY_REVISION_NAME)
Substitua:
MEMORY_REVISION_NAME: nome do recurso da revisão de memória a ser buscada no formato:projects/.../locations/.../reasoningEngines/.../memories/.../revisions/...
Relembrar um momento
Use RollbackMemory para reverter uma recordação para uma revisão anterior.
client.memory_banks.memories.rollback(
name="MEMORY_NAME",
target_revision_id="REVISION_ID"
)
Substitua:
MEMORY_NAME: nome do recurso da memória a ser atualizada no formato:projects/.../locations/.../reasoningEngines/.../memories/...REVISION_ID: ID da revisão para a qual a reversão deve ser feita. Este é 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 quiser desfazer uma mudança feita por GenerateMemories em uma recordação, reverter
a recordação 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 dado de memória atualizado ou excluído:
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
)
Desativar 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 todos os pedidos à sua instância do Memory Bank ou para cada pedido individual. Se as revisões de memória estiverem desativadas, uma revisão não será criada quando a memória for alterada.
É possível desativar as revisões de memória para todas as solicitações à sua instância do Memory Bank ao configurar a instância:
memory_bank = client.memory_banks.create(
managed_semantic_memory_config={
"disable_memory_revisions": True
}
)
É possível desativar as revisões de memória no nível da solicitação ao enviar:
Gerar
client.memory_banks.memories.generate(
...,
"config": {
"disable_memory_revisions": True
}
)
Criar
client.memory_banks.memories.create(
...,
"config": {
"disable_memory_revisions": True
}
)
Atualizar
client.memory_banks.memories.update(
...,
"config": {
"disable_memory_revisions": True
}
)
Validade da revisão
As revisões de memória não são mantidas para sempre. Defina a expiração das revisões ou use a expiração padrão. O tempo de vida útil (TTL) padrão é de 365 dias. É possível configurar a expiração para todas as solicitações à sua 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 rollbacks.
É possível configurar o TTL para todas as solicitações à sua instância do Memory Bank ao configurar a instância:
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"
}
}
)
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.memory_banks.memories.create(
...,
config=config
)
client.memory_banks.memories.update(
...,
config=config
)
client.memory_banks.memories.generate(
...,
config=config
)
Expiração
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
)