Esta página foi traduzida pela API Cloud Translation.

Revisões de memória

Nesta página, descrevemos como os recursos de revisão de memória são criados e gerenciados para o banco de memória do Vertex AI Agent Engine.

Ciclo de vida de uma memória e suas revisões

Fontes de dados e revisões de memória

As recordações podem ser criadas, atualizadas ou excluídas diretamente (usando CreateMemory, UpdateMemory ou DeleteMemory, respectivamente) ou dinamicamente (usando GenerateMemories). Os recursos de revisão de recordação fornecem um histórico completo de versões de um recurso de recordação em todas as operações de mutação. Uma revisão nova e 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 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 do Memory sempre 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 MemoryRevisions representam 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 usando GenerateMemories, a revisão também inclui as informações extraídas da fonte de dados (extracted_memories) antes da consolidação 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 memórias, 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=agent_engine_name, ...)

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

Quando uma recordação é criada, um único recurso Memory 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 recordação

As recordações podem ser atualizadas diretamente usando UpdateMemory ou dinamicamente usando GenerateMemories. Com a geração de recordações, elas 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.agent_engines.memories.update(name=memory_name, ...)

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

Quando uma recordação é 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 recordações podem ser acessadas diretamente usando DeleteMemory ou dinamicamente usando GenerateMemories. Com a geração de memórias, elas 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.agent_engines.memories.delete(name=memory_name, ...)

# Dynamic delete using GenerateMemories
client.agent_engines.memories.generate_memories(name=agent_engine_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.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 da memória da criança só ficam acessíveis por até 48 horas após a exclusão da memória do responsável. Durante esse período, você pode continuar inspecionando as revisões de memória e reverter 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 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, é possível 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.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"
    }
    ...
  )
]
"""

Acessar 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 buscada no formato: projects/.../locations/.../reasoningEngines/.../memories/.../revisions/...

Reverter uma recordação

Use RollbackMemory para reverter uma recordação 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 atualizada no formato: projects/.../locations/.../reasoningEngines/.../memories/...
REVISION_ID: ID da revisão para a qual o rollback deve ser feito. Esse é o último segmento do nome do recurso de revisão de memória, como 789 em projects/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 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 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 à sua instância do Memory Bank ou para cada solicitação 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:

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:

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
  }
)

Expiração 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.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
)

Revisões de memória Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Ciclo de vida de uma memória e suas revisões

Criação de recordações

Atualização de recordação

Exclusão de memória

Operações de revisão de memória

Listar revisões

Acessar uma revisão

Reverter uma recordação

Como desativar revisões de memória

Gerar

Criar

Atualizar

Expiração da revisão

TTL

Expiração

Revisões de memória