Revisioni della memoria

Questa pagina descrive come vengono create e gestite le risorse di revisione della memoria per Memory Bank di Vertex AI Agent Engine.

Ciclo di vita di un ricordo e delle relative revisioni

Origini dati e revisioni della memoria

I ricordi possono essere creati, aggiornati o eliminati direttamente (utilizzando rispettivamente CreateMemory, UpdateMemory o DeleteMemory) o dinamicamente (utilizzando GenerateMemories). Le risorse di revisione dei ricordi forniscono una cronologia completa delle versioni di una risorsa di ricordi in tutte le operazioni di mutazione. Ogni volta che la memoria viene creata o modificata, viene salvata automaticamente una nuova revisione immutabile. In questo modo, puoi vedere l'evoluzione di un ricordo e (per la generazione di ricordi) quali informazioni specifiche sono state estratte e consolidate in ogni passaggio.

Ogni risorsa di memoria ha una o più risorse di revisione della memoria figlio associate:

  • Le risorse Memory riflettono sempre lo stato attuale e consolidato delle informazioni. Una singola memoria può riflettere i dati derivati da più richieste e origini dati.

    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(...)
)

  • Le risorse MemoryRevisions rappresentano gli stati storici della memoria padre. Ogni revisione è uno snapshot della memoria in corrispondenza di un evento di mutazione. Se una memoria è stata modificata utilizzando GenerateMemories, la revisione include anche le informazioni estratte dall'origine dati (extracted_memories) prima che venissero consolidate con i contenuti esistenti della memoria.

    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/...'
)

Le revisioni della memoria sono attive per impostazione predefinita. Per disattivare le revisioni della memoria, vedi Disattivare le revisioni della memoria.

Creazione di ricordi

I ricordi possono essere creati direttamente utilizzando CreateMemory o dinamicamente utilizzando GenerateMemories. Con la generazione di ricordi, viene creato un ricordo se non ne esistono di simili che coprono informazioni simili per lo stesso ambito:

# 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 viene creato un ricordo, vengono create una risorsa Memory e una risorsa secondaria 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",
    ...
  )
]
"""

Aggiornamento della memoria

I ricordi possono essere aggiornati direttamente utilizzando UpdateMemory o dinamicamente utilizzando GenerateMemories. Con la generazione di ricordi, questi vengono aggiornati dinamicamente quando il processo di consolidamento stabilisce che le nuove informazioni sono duplicate, complementari o contraddittorie rispetto a tutti i ricordi esistenti per lo stesso ambito.

# 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 un ricordo viene aggiornato, la risorsa Memory esistente viene aggiornata e viene creato un nuovo elemento secondario 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",
    ...
  )
]
"""

Eliminazione della memoria

I ricordi possono essere creati direttamente utilizzando DeleteMemory o in modo dinamico utilizzando GenerateMemories. Con la generazione della memoria, i ricordi vengono eliminati dinamicamente quando il processo di consolidamento stabilisce che le nuove informazioni invalidano quelle esistenti per lo stesso ambito.

# 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 una memoria viene eliminata, la risorsa Memory esistente viene eliminata e viene creato un nuovo elemento secondario MemoryRevision. Il fact nell'ultima revisione della memoria è vuoto perché riflette una mutazione di eliminazione.

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",
    ...
  )
]
"""

Le revisioni dei ricordi del bambino sono accessibili solo fino a 48 ore dopo l'eliminazione del ricordo del genitore. Durante questo periodo di recupero, puoi continuare a esaminare le revisioni del ricordo e recuperarlo ripristinando una revisione precedente.

Operazioni di revisione della memoria

Questa sezione descrive come ispezionare le revisioni della memoria e rollback una revisione precedente.

Elenca revisioni

Utilizza ListMemoryRevisions per restituire tutte le revisioni della memoria appartenenti a una memoria.

list(client.agent_engines.memories.revisions.list(name=MEMORY_NAME))

Sostituisci quanto segue:

  • MEMORY_NAME: il nome della risorsa della memoria nel formato: projects/.../locations/.../reasoningEngines/.../memories/...

Quando generi i ricordi, puoi fornire etichette di revisione che vengono applicate alle revisioni affiliate. Le etichette sono coppie chiave-valore arbitrarie. Ad esempio, puoi etichettare le revisioni con un ID dell'origine dati utilizzata per generare il ricordo e poi filtrare le revisioni in base a questa etichetta:

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"
    }
    ...
  )
]
"""

Ottenere una revisione

Utilizza GetMemoryRevision per recuperare una singola revisione della memoria.

client.agent_engines.memories.revisions.get(name=MEMORY_REVISION_NAME)

Sostituisci quanto segue:

  • MEMORY_REVISION_NAME: il nome della risorsa della revisione della memoria da recuperare nel formato: projects/.../locations/.../reasoningEngines/.../memories/.../revisions/...

Eseguire il rollback di un ricordo

Utilizza RollbackMemory per ripristinare una revisione precedente di un ricordo.

client.agent_engines.memories.rollback(
    name=name=MEMORY_NAME,
    target_revision_id=REVISION_ID
)

Sostituisci quanto segue:

  • MEMORY_NAME: il nome della risorsa della memoria da aggiornare nel formato: projects/.../locations/.../reasoningEngines/.../memories/...
  • REVISION_ID: l'ID della revisione a cui deve essere eseguito il rollback. Questo è l'ultimo segmento del nome della risorsa di revisione della memoria, ad esempio 789 in projects/MyProject/locations/us-central1/reasoningEngines/123/memories/456/revisions/789.

Se vuoi annullare una modifica apportata a un ricordo da GenerateMemories, rollback la revisione precedente alla modifica. La risposta alla generazione del ricordo include un riferimento alla revisione precedente (previous_revision) per ogni ricordo aggiornato o eliminato:

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
)

Disattivazione delle revisioni della memoria

Le revisioni della memoria sono attive per impostazione predefinita. Puoi disattivare le revisioni della memoria per tutte le richieste alla tua istanza di Memory Bank o per ogni singola richiesta. Se le revisioni della memoria sono disattivate, non viene creata una revisione della memoria quando questa viene modificata.

Puoi disattivare le revisioni della memoria per tutte le richieste alla tua istanza di Memory Bank quando la configuri:

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

Puoi disattivare le revisioni della memoria a livello di richiesta quando invii la richiesta:

Genera

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

Crea

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

Aggiorna

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

Scadenza della revisione

Le revisioni della memoria non vengono conservate per sempre. Devi impostare la scadenza delle revisioni o utilizzare la scadenza predefinita. La durata predefinita (TTL) è di 365 giorni. Puoi configurare la scadenza per tutte le richieste alla tua istanza di Memory Bank o per ogni singola richiesta. Una volta scaduta, una revisione della memoria non è disponibile per l'ispezione o i rollback.

Puoi configurare il TTL per tutte le richieste alla tua istanza Memory Bank quando la configuri:

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

Per configurare il TTL per ogni revisione della memoria a livello di richiesta, includi revision_expire_time o revision_ttl nella richiesta:

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
)

Scadenza

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
)