Révisions de la mémoire

La Memory Bank conserve automatiquement un historique des versions de vos souvenirs grâce à des ressources de révision. Chaque fois qu'un souvenir est créé ou modifié, une nouvelle révision immuable est enregistrée. Vous pouvez ainsi 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 la restauration des révisions.

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

Cycle de vie d'un souvenir 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 mémoire fournissent un historique complet des versions d'une ressource de mémoire pour toutes les opérations de mutation. Une nouvelle révision immuable est automatiquement enregistrée chaque fois que la mémoire est créée ou modifiée. Vous pouvez ainsi voir comment un souvenir a évolué et (pour la génération de souvenirs) 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 enfant :

  • 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 la mémoire sont activées par défaut. Pour désactiver les révisions de souvenirs, consultez Désactiver les révisions de souvenirs.

Création de souvenirs

Vous pouvez créer des souvenirs directement à l'aide de CreateMemory ou de manière dynamique à l'aide de GenerateMemories. Avec la génération de mémoire, une mémoire est créée s'il n'existe aucune mémoire couvrant des informations similaires pour la même portée :

# 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 une ressource enfant MemoryRevision sont créées :

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 par rapport à tous les souvenirs existants pour la même portée.

# 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'un souvenir est modifié, la ressource Memory existante est mise à jour et une 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 des informations mémorisées

Les souvenirs peuvent être directement créé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 la même portée.

# 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'un souvenir est supprimé, la ressource Memory existante est supprimée et une nouvelle ressource enfant MemoryRevision est créée. Le 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 la mémoire de l'enfant ne sont accessibles que pendant 48 heures maximum après la suppression de la mémoire du parent. Pendant cette période de récupération, vous pouvez continuer à inspecter vos révisions de mémoire et récupérer votre mémoire en la rétablissant à une révision précédente.

Opérations de révision de la mémoire

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

Lister les révisions

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

Lorsque vous générez des souvenirs, vous pouvez fournir des libellés de révision qui sont appliqués aux révisions associées. Les libellés sont des paires clé/valeur arbitraires. Par exemple, vous pouvez étiqueter les révisions avec un ID de la source de données utilisée pour générer le souvenir, puis filtrer les révisions par cette étiquette :

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 suivant : projects/.../locations/.../reasoningEngines/.../memories/.../revisions/...

Effectuer un rollback sur un souvenir

Utilisez RollbackMemory pour revenir à une révision précédente d'un souvenir.

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 suivant : projects/.../locations/.../reasoningEngines/.../memories/...

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

Si vous souhaitez annuler une modification apportée à un souvenir par GenerateMemories, rétablissez la version du souvenir antérieure à la modification. La réponse de génération de la 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ésactiver les révisions de souvenirs

Les révisions de la mémoire sont activées par défaut. Vous pouvez désactiver les révisions de la mémoire pour toutes les requêtes adressées à votre instance de Memory Bank 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 lorsque vous configurez l'instance :

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

Vous pouvez désactiver les révisions de la mémoire au niveau d'une 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 souvenirs 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 souvenir a expiré, elle n'est plus disponible pour l'inspection ou les rollbacks.

Vous pouvez configurer le TTL pour toutes les requêtes adressées à votre instance Memory Bank lorsque vous la configurez :

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 le TTL de 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
)