O Memory Bank da Plataforma de Agentes mantém automaticamente um histórico de versões das suas memórias com 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.
Neste documento, explicamos o ciclo de vida das memórias e as revisões delas, além de descrever operações como listar, receber e reverter revisões.
Para mais informações sobre como gerar recordações, consulte Gerar recordações.
Ciclo de vida de uma recordação e as 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 fornecem 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 dá transparência sobre como uma memória evoluiu e (para
geração 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 pai. Cada revisão é um snapshot da memória em um evento de mutação. Se uma memória foi modificada 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 recordações
As recordações podem ser criadas diretamente usando CreateMemory ou de forma dinâmica
usando GenerateMemories. Com a geração 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 memória é criada, um único recurso Memory e um MemoryRevision
filho 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 da memória
As memórias podem ser atualizadas diretamente usando UpdateMemory ou dinamicamente
usando GenerateMemories. Com a geração 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
em relação a todas as recordações atuais do 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 atual é 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 memórias
As recordações podem ser usadas diretamente com DeleteMemory ou dinamicamente
com GenerateMemories. Com a geração 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 para o 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 de memória secundária só podem ser acessadas por até 48 horas após a exclusão da memória principal. Durante esse período, você pode continuar inspecionando as revisões da memória e recuperá-la revertendo-a para uma revisão anterior.
Operações de revisão de memória
Nesta seção, descrevemos como inspecionar revisões de memória e reverter uma memória para uma revisão anterior.
Listar revisões
É possível inspecionar as revisões de memória no console do Google Cloud ou com o SDK da Agent Platform.
Console
Para visualizar as revisões de memória no console do Google Cloud , é necessária a permissão aiplatform.memoryRevisions.list (incluída em roles/aiplatform.memoryViewer e roles/aiplatform.memoryUser), que não está disponível no modo expresso.
Abra a instância no console do Google Cloud :
Instância independente do Memory Bank: acesse a página Memory Bank da Plataforma de Agentes e clique na sua instância.
Agente implantado no Agent Runtime: acesse a página Implantações da plataforma de agentes e clique no seu agente.
Abra a guia Recordações:
- Memórias não estruturadas: em uma linha de memória, clique no menu mais ações () > Ver revisões.
- Perfis estruturados (instâncias independentes): selecione Estruturado, escolha um escopo completo, clique em Visualizar em uma linha de perfil para abrir Detalhes da memória e clique em Ver revisões para um fato de memória.
O painel de revisões lista os campos Criado, Expira, Fato e Contexto de cada revisão.
SDK da plataforma de agentes
Use ListMemoryRevisions para retornar todas as revisões de memória que pertencem 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 memórias, é possível fornecer rótulos de revisão que são aplicados às revisões afiliadas. Rótulos são pares de chave-valor arbitrários. Por exemplo, é possível rotular as 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.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"
}
...
)
]
"""
Pedir 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/...
Reverter uma memória
Use RollbackMemory para reverter uma memória 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 que 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 alteração em uma memória feita por GenerateMemories, reverter
a memória para a revisão anterior à alteração. A resposta de geração de memória
inclui uma referência à revisão anterior (previous_revision) para cada
memória atualizada ou excluída:
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
)
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 à instância do banco de memória 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 modificada.
É possível desativar as revisões de memória para todas as solicitações à sua instância do banco de memória no console do Google Cloud (em Configuração > Retenção ou Configuração de serviço > Banco de memória para agentes implantados) ou com o SDK da plataforma de agentes:
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 a solicitação:
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. É necessário definir a validade das revisões ou usar a validade padrão. O time to live (TTL) padrão é de 365 dias. É possível configurar a validade 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 reversões.
É possível configurar o TTL do histórico de revisões para todas as solicitações à sua instância do banco de memória no console do Google Cloud (em Configuração > Retenção ou Configuração de serviço > Banco de memória para agentes implantados) ou com o SDK da Agent Platform:
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 em um nível de 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
)