Révisions de la mémoire

Agent Platform Memory Bank conserve automatiquement un historique des versions de vos mémoires via des ressources de révision de mémoire. Chaque fois qu'une information mémorisée est créée ou modifiée, une nouvelle révision immuable est enregistrée, ce qui permet de voir comment les informations évoluent et ce qui a été extrait à chaque étape.

Ce document explique le cycle de vie des souvenirs et de leurs révisions, et décrit des opérations telles que la liste, l'obtention et l'annulation des révisions.

Pour en savoir plus sur la génération de souvenirs, consultez Générer des souvenirs.

Cycle de vie d'une mémoire et de ses révisions

Sources de données et révisions de la mémoire

Les souvenirs peuvent être créés, mis à jour ou supprimés directement (à l'aide de CreateMemory, UpdateMemory ou DeleteMemory, respectivement) ou de manière dynamique (à l'aide de GenerateMemories). Les ressources de révision de souvenirs fournissent un historique complet des versions d'une ressource de souvenir pour toutes les opérations de mutation. Une nouvelle révision immuable est automatiquement enregistrée chaque fois que l'information mémorisée est créée ou modifiée. Cela vous permet de voir comment une mémoire a évolué et (pour la génération de mémoire) quelles informations spécifiques ont été extraites et consolidées à chaque étape.

Chaque ressource de mémoire est associée à une ou plusieurs ressources de révision de mémoire enfants :

  • Les ressources Memory reflètent toujours l'état actuel et consolidé des informations. Une même mémoire peut refléter des données dérivées de plusieurs requêtes et sources de données.

    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(...)
    )
    
  • Les ressources MemoryRevisions représentent les états historiques de la mémoire parente. Chaque révision est un instantané de la mémoire lors d'un événement de mutation. Si une mémoire a été modifiée à l'aide de GenerateMemories, la révision inclut également les informations extraites de la source de données (extracted_memories) avant qu'elles ne soient consolidées avec le contenu existant de la mémoire.

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

    Les révisions de mémoire sont activées par défaut. Pour désactiver les révisions de mémoire, consultez Désactiver les révisions de mémoire.

Création de souvenirs

Les souvenirs peuvent être créés directement à l'aide de CreateMemory ou de manière dynamique à l'aide de GenerateMemories. Avec la génération d'informations mémorisées, une information mémorisée est créée s'il n'existe aucune information mémorisée couvrant des informations similaires pour le même champ d'application :

# 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, ...)

Lorsqu'un souvenir est créé, une seule ressource Memory et un MemoryRevision enfant sont créés :

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

Mise à jour de la mémoire

Les souvenirs peuvent être mis à jour directement à l'aide de UpdateMemory ou de manière dynamique à l'aide de GenerateMemories. Avec la génération de mémoire, les souvenirs sont mis à jour de manière dynamique lorsque le processus de consolidation décide que les nouvelles informations sont redondantes, complémentaires ou contradictoires avec tous les souvenirs existants pour le même champ d'application.

# 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, ...)

Lorsqu'une information mémorisée est mise à jour, la ressource Memory existante est mise à jour et une nouvelle ressource enfant MemoryRevision est créée.

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

Suppression de la mémoire

Les souvenirs peuvent être directement utilisés à l'aide de DeleteMemory ou de manière dynamique à l'aide de GenerateMemories. Avec la génération de mémoire, les souvenirs sont supprimés de manière dynamique lorsque le processus de consolidation décide que les nouvelles informations invalident les informations existantes pour le même champ d'application.

# 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, ...)

Lorsqu'une information mémorisée est supprimée, la ressource Memory existante est supprimée et une nouvelle ressource enfant MemoryRevision est créée. Le champ fact de la dernière révision de la mémoire est vide, car il reflète une mutation de suppression.

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

Les révisions de mémoire enfant ne sont accessibles que pendant 48 heures après la suppression de la mémoire parent. Pendant cette période de récupération, vous pouvez continuer à inspecter vos révisions de mémoire et vous pouvez récupérer votre mémoire en la restaurant à une révision précédente.

Opérations sur les révisions de mémoire

Cette section explique comment inspecter les révisions de mémoire et effectuer un rollback d'une mémoire vers une révision précédente.

Lister les révisions

Vous pouvez inspecter les révisions de mémoire dans la console Google Cloud ou avec le SDK Agent Platform.

Console

Pour afficher les révisions de mémoire dans la console Google Cloud , vous devez disposer de l'autorisation aiplatform.memoryRevisions.list (incluse dans roles/aiplatform.memoryViewer et roles/aiplatform.memoryUser). Cette fonctionnalité n'est pas disponible en mode express.

  1. Ouvrez votre instance dans la console Google Cloud  :

    • Instance Memory Bank autonome : accédez à la page Memory Bank d'Agent Platform, puis cliquez sur votre instance.

      Accéder à Memory Bank

    • Agent déployé sur Agent Runtime : accédez à la page Déploiements d'Agent Platform, puis cliquez sur votre agent.

      Accéder à la page "Déploiements"

  2. Ouvrez l'onglet Souvenirs :

    • Mémoires non structurées : sur une ligne de mémoire, cliquez sur le menu Autres actions () > Afficher les révisions.
    • Profils structurés (instances autonomes) : sélectionnez Structuré, choisissez un champ d'application complet, cliquez sur Afficher sur une ligne de profil pour ouvrir Détails de la mémoire, puis cliquez sur Afficher les révisions pour un fait de mémoire.

    Le panneau des révisions liste les champs Création, Expiration, Fait et Contexte de chaque révision.

SDK Agent Platform

Utilisez ListMemoryRevisions pour renvoyer toutes les révisions de mémoire appartenant à une mémoire.

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

Remplacez les éléments suivants :

  • MEMORY_NAME : nom de ressource de la mémoire au format projects/.../locations/.../reasoningEngines/.../memories/....

Lors de la génération de mémoires, vous pouvez fournir des libellés de révision qui sont appliqués aux révisions associées. Les étiquettes sont des paires clé-valeur arbitraires. Par exemple, vous pouvez ajouter un libellé aux révisions avec l'ID de la source de données utilisée pour générer la mémoire, puis filtrer les révisions en fonction de ce libellé :

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

Obtenir une révision

Utilisez GetMemoryRevision pour récupérer une révision de mémoire individuelle.

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

Remplacez les éléments suivants :

  • MEMORY_REVISION_NAME : nom de ressource de la révision de mémoire à récupérer, au format projects/.../locations/.../reasoningEngines/.../memories/.../revisions/....

Revenir à une version précédente d'une information mémorisée

Utilisez RollbackMemory pour effectuer un rollback d'une mémoire vers une révision précédente.

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

Remplacez les éléments suivants :

  • MEMORY_NAME : nom de ressource de la mémoire à mettre à jour, au format : projects/.../locations/.../reasoningEngines/.../memories/...

  • REVISION_ID : ID de la révision vers laquelle effectuer le rollback. Il s'agit du dernier segment du nom de la ressource de révision de mémoire, par exemple 789 dans projects/MyProject/locations/us-central1/reasoningEngines/123/memories/456/revisions/789.

Si vous souhaitez annuler une modification apportée à une mémoire par GenerateMemories, effectuez un rollback de la mémoire vers sa révision avant la modification. La réponse de génération de mémoire inclut une référence à la révision précédente (previous_revision) pour chaque mémoire mise à jour ou supprimée :

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
)

Désactivation des révisions de mémoire

Les révisions de mémoire sont activées par défaut. Vous pouvez désactiver les révisions de mémoire pour toutes les requêtes adressées à votre instance de banque de mémoire ou pour chaque requête individuelle. Si les révisions de mémoire sont désactivées, aucune révision de mémoire n'est créée lorsque la mémoire est modifiée.

Vous pouvez désactiver les révisions de mémoire pour toutes les requêtes adressées à votre instance Memory Bank dans la console Google Cloud (sous Configuration > Conservation ou Configuration du service > Memory Bank pour les agents déployés) ou avec le SDK Agent Platform :

memory_bank = client.memory_banks.create(
  managed_semantic_memory_config={
    "disable_memory_revisions": True
  }
)

Vous pouvez désactiver les révisions de mémoire au niveau de la requête lorsque vous l'envoyez :

Générer

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

Créer

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

Mettre à jour

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

Expiration des révisions

Les révisions de mémoire ne sont pas conservées indéfiniment. Vous devez définir l'expiration des révisions ou utiliser l'expiration par défaut. La valeur TTL (Time To Live) par défaut est de 365 jours. Vous pouvez configurer l'expiration pour toutes les requêtes adressées à votre instance Memory Bank ou pour chaque requête individuelle. Une fois qu'une révision de mémoire a expiré, elle n'est plus disponible pour inspection ou rollback.

Vous pouvez configurer la valeur TTL de l'historique des révisions pour toutes les requêtes adressées à votre instance Memory Bank dans la console Google Cloud (sous Configuration > Conservation ou Configuration du service > Memory Bank pour les agents déployés) ou avec le SDK 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"
    }
  }
)

Pour configurer la valeur TTL pour chaque révision de mémoire au niveau de la requête, incluez revision_expire_time ou revision_ttl dans votre requête :

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

Expiration

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
)