Générer des souvenirs

Ce document explique comment fonctionne la génération de souvenirs, comment personnaliser l'extraction de souvenirs avec des thèmes et comment déclencher des demandes de génération de souvenirs.

Pour savoir comment configurer votre environnement, consultez Configurer Memory Bank.

Comprendre la génération de la mémoire

Memory Bank extrait des souvenirs à partir de données sources et les organise automatiquement pour une collection spécifique (définie par un scope) en ajoutant, en modifiant et en supprimant des souvenirs au fil du temps.

Lorsque vous déclenchez la génération de souvenirs, Memory Bank effectue les opérations suivantes :

• Extraction : extrait des informations sur l'utilisateur à partir de ses conversations avec l'agent. Seules les informations correspondant à au moins un des thèmes de mémoire de votre instance seront conservées.

• Consolidation : indique si les souvenirs existants de même portée doivent être supprimés ou mis à jour en fonction des informations extraites. Memory Bank vérifie que les nouveaux souvenirs ne sont pas des doublons ni des contradictions avant de les fusionner avec les souvenirs existants. Si les infos mémorisées existantes ne chevauchent pas les nouvelles informations, une nouvelle info mémorisée sera créée.

  • Par défaut, Memory Bank prend en compte tous les souvenirs existants pour la même portée lors de la consolidation. Si vous souhaitez limiter plus précisément les souvenirs éligibles à la consolidation à l'aide de métadonnées, utilisez la stratégie de fusion des métadonnées REQUIRE_EXACT_MATCH.

  • Par défaut, seule la révision la plus récente d'un souvenir est utilisée pour la comparaison. Pour mieux identifier les tendances à long terme et corroborer les données, vous pouvez augmenter revisions_per_candidate_count lorsque vous créez votre instance Agent Platform afin d'inclure davantage de révisions historiques dans la logique de consolidation.

Vous pouvez inspecter les étapes intermédiaires de la génération de la mémoire et voir comment une Mémoire change au fil de plusieurs requêtes à l'aide des révisions de mémoire. Chaque révision inclut la sortie intermédiaire de l'étape d'extraction (extracted_memories) et l'étape de consolidation finale (fact) pour chaque demande de génération de mémoire.

list(client.agent_engines.memories.revisions.list(
  name="projects/.../locations/.../reasoningEngines/.../memories/.../revisions/..."))

"""
[
  MemoryRevision(
    name="projects/123/locations/us-central1/reasoningEngines/456/memories/789/revision/456",
    fact="This is my updated fact",
    extracted_memories=[
      IntermediateExtractedMemory(
        fact='This is the output of extraction for a single request.'
      ),
    ],
    ...
  ),
  MemoryRevision(
    name="projects/123/locations/us-central1/reasoningEngines/456/memories/789/revision/123",
    fact="This is my original fact",
    extracted_memories=[
      IntermediateExtractedMemory(
        fact='This is my original fact.'
      ),
    ],
    ...
  )
]
"""

Thèmes de souvenirs

Les "thèmes de mémoire" identifient les informations que Memory Bank considère comme importantes et qui doivent donc être conservées en tant que souvenirs générés. Memory Bank accepte deux types de thèmes de mémoire :

• Sujets gérés : le libellé et les instructions sont définis par Memory Bank. Vous n'avez qu'à indiquer le nom du thème géré. Exemple :

  Dictionnaire

  memory_topic = {
      "managed_memory_topic": {
          "managed_topic_enum": "USER_PERSONAL_INFO"
      }
  }
  

  Basée sur les classes

  from vertexai.types import ManagedTopicEnum
  from vertexai.types import MemoryBankCustomizationConfigMemoryTopic as MemoryTopic
  from vertexai.types import MemoryBankCustomizationConfigMemoryTopicManagedMemoryTopic as ManagedMemoryTopic
  
  memory_topic = MemoryTopic(
      managed_memory_topic=ManagedMemoryTopic(
          managed_topic_enum=ManagedTopicEnum.USER_PERSONAL_INFO
      )
  )
  

• Thèmes personnalisés : le libellé et les instructions sont définis par vous lorsque vous configurez votre instance Memory Bank. Elles seront utilisées dans la requête pour l'étape d'extraction de Memory Bank. Exemple :

  Dictionnaire

  memory_topic = {
      "custom_memory_topic": {
          "label": "business_feedback",
          "description": """Specific user feedback about their experience
          at the coffee shop. This includes opinions on drinks, food,
          pastries, ambiance, staff friendliness, service speed,
          cleanliness, and any suggestions for improvement."""
      }
  }
  

  Basée sur les classes

  from vertexai.types import MemoryBankCustomizationConfigMemoryTopic as MemoryTopic
  from vertexai.types import MemoryBankCustomizationConfigMemoryTopicCustomMemoryTopic as CustomMemoryTopic
  
  memory_topic = MemoryTopic(
      custom_memory_topic=CustomMemoryTopic(
          label="business_feedback",
          description="""Specific user feedback about their experience at
          the coffee shop. This includes opinions on drinks, food,
          pastries, ambiance, staff friendliness, service speed,
          cleanliness, and any suggestions for improvement."""
      )
  )
  

  Lorsque vous utilisez des thèmes personnalisés, nous vous recommandons de fournir également des exemples few-shot pour montrer comment les souvenirs doivent être extraits de votre conversation.

Par défaut, Memory Bank conserve tous les thèmes gérés suivants :

• Informations sur l'utilisateur (USER_PERSONAL_INFO) : informations importantes sur l'utilisateur, comme son nom, ses relations, ses loisirs et ses dates importantes. Par exemple, "Je travaille chez Google" ou "Mon anniversaire de mariage est le 31 décembre".

• Préférences de l'utilisateur (USER_PREFERENCES) : préférences explicites ou implicites, styles ou motifs préférés. Par exemple, "Je préfère le siège du milieu".

• Événements clés de la conversation et résultats des tâches (KEY_CONVERSATION_DETAILS) : étapes ou conclusions importantes du dialogue. Par exemple : "J'ai réservé des billets d'avion aller-retour entre JFK et SFO. Je pars le 1er juin 2025 et reviens le 7 juin 2025."

• Instructions explicites pour se souvenir ou oublier (EXPLICIT_INSTRUCTIONS) : informations que l'utilisateur demande explicitement à l'agent de mémoriser ou d'oublier. Par exemple, si l'utilisateur dit "Mémorise que j'utilise principalement Python", la Memory Bank génère un souvenir tel que "J'utilise principalement Python".

Cela équivaut à utiliser l'ensemble de rubriques sur la mémoire gérée suivant :

  memory_topics = [
      {"managed_memory_topic": {"managed_topic_enum": "USER_PERSONAL_INFO"}},
      {"managed_memory_topic": {"managed_topic_enum": "USER_PREFERENCES"}},
      {"managed_memory_topic": {"managed_topic_enum": "KEY_CONVERSATION_DETAILS"}},
      {"managed_memory_topic": {"managed_topic_enum": "EXPLICIT_INSTRUCTIONS"}},
  ]

from vertexai.types import ManagedTopicEnum
from vertexai.types import MemoryBankCustomizationConfigMemoryTopic as MemoryTopic
from vertexai.types import MemoryBankCustomizationConfigMemoryTopicManagedMemoryTopic as ManagedMemoryTopic

memory_topics = [
  MemoryTopic(
      managed_memory_topic=ManagedMemoryTopic(
          managed_topic_enum=ManagedTopicEnum.USER_PERSONAL_INFO)),
  MemoryTopic(
      managed_memory_topic=ManagedMemoryTopic(
          managed_topic_enum=ManagedTopicEnum.USER_PREFERENCES)),
  MemoryTopic(
      managed_memory_topic=ManagedMemoryTopic(
          managed_topic_enum=ManagedTopicEnum.KEY_CONVERSATION_DETAILS)),
  MemoryTopic(
      managed_memory_topic=ManagedMemoryTopic(
          managed_topic_enum=ManagedTopicEnum.EXPLICIT_INSTRUCTIONS)),
]

Si vous souhaitez personnaliser les thèmes que Memory Bank conserve, définissez les thèmes de mémoire dans votre configuration de personnalisation lorsque vous configurez Memory Bank.

Utiliser des métadonnées lors de la consolidation

Vous pouvez associer des métadonnées aux souvenirs générés. Les métadonnées vous permettent de stocker des informations structurées (chaînes, doubles, booléens ou codes temporels) à côté d'un fait de mémoire. Cela est utile pour filtrer ou gérer le cycle de vie des mémoires.

import datetime

client.agent_engines.memories.generate(
    ...,
    config={
        "metadata": {
            "my_string_key": {"string_value": "my_string_value"},
            "my_double_key": {"double_value": 123.456},
            "my_boolean_key": {"bool_value": True},
            "my_timestamp_key": {
                "timestamp_value": datetime.datetime(
                    2027, 1, 1, 12, 30, 00, tzinfo=datetime.timezone.utc
                )
            }
        },
        "metadata_merge_strategy": "MERGE"
    },
)

import datetime

from vertexai import types

client.agent_engines.memories.generate(
    ...,
    config=types.GenerateAgentEngineMemoriesConfig(
        metadata={
            "my_string_key": types.MemoryMetadataValue(string_value="my_string_value"),
            "my_double_key": types.MemoryMetadataValue(double_value=123.456),
            "my_boolean_key": types.MemoryMetadataValue(bool_value=True),
            "my_timestamp_key": types.MemoryMetadataValue(
                timestamp_value=datetime.datetime(
                    2027, 1, 1, 12, 30, 00, tzinfo=datetime.timezone.utc
                )
            ),
        },
        metadata_merge_strategy=types.MemoryMetadataMergeStrategy.MERGE,
    )
)

En utilisant un metadata_merge_strategy, vous pouvez contrôler la façon dont les nouvelles métadonnées interagissent avec les souvenirs existants lors de la consolidation :

• MERGE : (par défaut) combine les nouvelles métadonnées avec celles existantes. Si une clé existe déjà, la nouvelle valeur écrase l'ancienne.

• OVERWRITE : remplacez les métadonnées des souvenirs modifiés par les nouvelles métadonnées.

• REQUIRE_EXACT_MATCH : limite la consolidation aux souvenirs dont les métadonnées sont exactement les mêmes que celles de la requête. Si les métadonnées d'un souvenir ne sont pas identiques, il ne peut pas être consolidé ni mis à jour.

Générer des souvenirs pour un sous-ensemble de thèmes

Par défaut, la génération de la mémoire extrait les données de tous les thèmes de mémoire que vous avez configurés lorsque vous avez configuré votre instance Memory Bank. Pour une requête GenerateMemories spécifique, vous pouvez limiter l'extraction à un sous-ensemble de thèmes configurés. Pour configurer les thèmes autorisés, utilisez le champ allowed_topics.

client.agent_engines.memories.generate(
    ...,
    config={
        "allowed_topics": [
            {"managed_memory_topic": "USER_PERSONAL_INFO"},
            {"custom_memory_topic_label": "business_feedback"}
        ]
    },
)

from vertexai import types

client.agent_engines.memories.generate(
    ...,
    config=types.GenerateAgentEngineMemoriesConfig(
        allowed_topics=[
            types.MemoryTopicId(
                managed_memory_topic=types.ManagedTopicEnum.USER_PERSONAL_INFO
            ),
            types.MemoryTopicId(
                custom_memory_topic_label="business_feedback"
            )
        ]
    )
)

Déclencher la génération de la mémoire

Vous pouvez déclencher la génération de souvenirs à l'aide de l'une des méthodes suivantes :

• GenerateMemories : ingérer des données dans la Memory Bank et déclencher immédiatement la génération de la mémoire. Cette méthode est utile lorsque vous souhaitez générer des souvenirs à un moment précis, par exemple à la fin d'une session ou à intervalles réguliers au cours d'une session.
• IngestEvents : ingérez des données dans Memory Bank en continu et laissez Memory Bank les traiter lorsque vos critères de déclenchement sont remplis. Cette méthode est utile lorsque vous disposez d'un flux continu d'événements et que vous souhaitez que Memory Bank gère automatiquement la mise en mémoire tampon et déclenche la génération de la mémoire en fonction du volume ou du temps. Pour en savoir plus, consultez Ingérer des événements.

La génération de la mémoire extrait le contexte clé des conversations sources et le combine avec les mémoires existantes pour la même portée. Par exemple, vous pouvez créer des souvenirs au niveau de la session en utilisant un champ d'application tel que {"user_id": "123", "session_id": "456"}. Les souvenirs ayant la même portée peuvent être consolidés et récupérés ensemble.

GenerateMemories est une opération de longue durée. Une fois l'opération terminée, AgentEngineGenerateMemoriesOperation contient une liste des souvenirs générés, le cas échéant :

AgentEngineGenerateMemoriesOperation(
  name="projects/.../locations/.../reasoningEngines/.../operations/...",
  done=True,
  response=GenerateMemoriesResponse(
    generatedMemories=[
      GenerateMemoriesResponseGeneratedMemory(
        memory=Memory(
          "name": "projects/.../locations/.../reasoningEngines/.../memories/..."
        ),
        action="CREATED",
      ),
      GenerateMemoriesResponseGeneratedMemory(
        memory=Memory(
          "name": "projects/.../locations/.../reasoningEngines/.../memories/..."
        ),
        action="UPDATED",
      ),
      GenerateMemoriesResponseGeneratedMemory(
        memory=Memory(
          "name": "projects/.../locations/.../reasoningEngines/.../memories/..."
        ),
        action="DELETED",
      ),
    ]
  )
)

Chaque souvenir généré inclut l'action qui a été effectué sur ce souvenir :

• CREATED : indique qu'une nouvelle mémoire a été ajoutée, représentant un nouveau concept qui n'a pas été capturé par les mémoires existantes.

• UPDATED : indique qu'une mémoire existante a été mise à jour, ce qui se produit si la mémoire couvrait des concepts similaires à ceux des nouvelles informations extraites. Le fait de la mémoire peut être mis à jour avec de nouvelles informations ou rester le même.

• DELETED : indique que la mémoire existante a été supprimée, car ses informations étaient contradictoires avec les nouvelles informations extraites de la conversation.

Pour les souvenirs CREATED ou UPDATED, vous pouvez utiliser GetMemories pour récupérer l'intégralité du contenu du souvenir. La récupération des souvenirs DELETED génère une erreur 404.

Génération de souvenirs en arrière-plan

GenerateMemories est une opération de longue durée. Par défaut, client.agent_engines.generate_memories est une fonction de blocage qui interroge l'opération jusqu'à ce qu'elle soit terminée. L'exécution de la génération de mémoire en tant qu'opération de blocage est utile lorsque vous souhaitez inspecter manuellement les mémoires générées ou informer les utilisateurs finaux des mémoires qui ont été générées.

Toutefois, pour les agents de production, vous souhaitez généralement exécuter la génération de la mémoire en arrière-plan en tant que processus asynchrone. Dans la plupart des cas, le client n'a pas besoin d'utiliser la sortie pour l'exécution en cours. Il n'est donc pas nécessaire d'entraîner une latence supplémentaire en attendant une réponse. Si vous souhaitez que la génération de mémoire s'exécute en arrière-plan, définissez wait_for_completion sur False :

client.agent_engines.memories.generate(
    ...,
    config={
        "wait_for_completion": False
    }
)

Au lieu d'appeler GenerateMemories de manière asynchrone, vous pouvez utiliser IngestEvents, qui dissocie l'ingestion d'événements de la génération de la mémoire et traite les événements en arrière-plan par défaut.

Sources de données

Il existe plusieurs façons de fournir des données sources pour la génération de mémoire :

• Fournissez les événements directement dans la charge utile.

• Fournissez des événements à l'aide des sessions Agent Platform d'Agent Runtime.

• Fournissez des faits préextraits pour les consolider avec les souvenirs existants pour la même portée.

Lorsque vous fournissez des événements directement dans la charge utile ou que vous utilisez des sessions Agent Runtime, les informations sont extraites de la conversation et consolidées avec les souvenirs existants. Si vous souhaitez uniquement extraire des informations de ces sources de données, vous pouvez désactiver la consolidation :

client.agent_engines.memories.generate(
    ...
    config={
        "disable_consolidation": True
    }
)

Utiliser les événements de la charge utile comme source de données

Utilisez direct_contents_source lorsque vous souhaitez générer des souvenirs à l'aide d'événements fournis directement dans la charge utile. Des informations pertinentes sont extraites de ces événements et consolidées avec les informations existantes pour la même portée. Cette approche peut être utilisée si vous utilisez un stockage de session différent de celui des sessions de la plate-forme d'agent.

events =  [
  {
    "content": {
      "role": "user",
      "parts": [
        {"text": "I work with LLM agents!"}
      ]
    }
  }
]

client.agent_engines.memories.generate(
    name=agent_engine.api_resource.name,
    direct_contents_source={
      "events": EVENTS
    },
    # For example, `scope={"user_id": "123"}`.
    scope=SCOPE,
    config={
        "wait_for_completion": True
    }
)

from google import genai
import vertexai

events = [
  vertexai.types.GenerateMemoriesRequestDirectContentsSourceEvent(
    content=genai.types.Content(
      role="user",
      parts=[
        genai.types.Part.from_text(text="I work with LLM agents!")
      ]
    )
  )
]

client.agent_engines.memories.generate(
    name=agent_engine.api_resource.name,
    direct_contents_source={
      "events": events
    },
    # For example, `scope={"user_id": "123"}`.
    scope=SCOPE,
    config={
        "wait_for_completion": True
    }
)

Utiliser des sessions Agent Runtime comme source de données

Avec les sessions, Memory Bank utilise les événements de session comme source de conversation pour la génération de la mémoire.

Pour définir le champ d'application des souvenirs générés, Memory Bank extrait et utilise l'ID utilisateur de la session par défaut. Par exemple, le champ d'application des souvenirs est stocké sous la forme {"user_id": "123"} si le user_id de la session est "123". Vous pouvez également fournir un scope directement, ce qui remplace l'utilisation du user_id de la session comme champ d'application.

client.agent_engines.memories.generate(
  name=agent_engine.api_resource.name,
  vertex_session_source={
      # For example, projects/.../locations/.../reasoningEngines/.../sessions/...
      "session": "SESSION_NAME"
  },
  # Optional when using Sessions. Defaults to {"user_id": session.user_id}.
  scope=SCOPE,
  config={
      "wait_for_completion": True
  }
)

client.agent_engines.memories.generate(
  name=agent_engine.api_resource.name,
  vertex_session_source=vertexai.types.GenerateMemoriesRequestVertexSessionSource(
      # For example, projects/.../locations/.../reasoningEngines/.../sessions/...
      session="SESSION_NAME"
  ),
  # Optional when using Sessions. Defaults to {"user_id": session.user_id}.
  scope=SCOPE,
  config={
      "wait_for_completion": True
  }
)

Vous pouvez également fournir une plage de temps indiquant les événements de la session à inclure. Si aucune valeur n'est fournie, tous les événements de la session sont inclus.

import datetime

client.agent_engines.memories.generate(
  name=agent_engine.api_resource.name,
  vertex_session_source={
      "session": "SESSION_NAME",
      # Extract memories from the last hour of events.
      "start_time": datetime.datetime.now(tz=datetime.timezone.utc) - datetime.timedelta(seconds=24 * 60),
      "end_time": datetime.datetime.now(tz=datetime.timezone.utc)
  },
  scope=SCOPE
)

import datetime

client.agent_engines.memories.generate(
  name=agent_engine.api_resource.name,
  vertex_session_source=vertexai.types.GenerateMemoriesRequestVertexSessionSource(
      session="SESSION_NAME",
      # Extract memories from the last hour of events.
      start_time=datetime.datetime.now(tz=datetime.timezone.utc) - datetime.timedelta(seconds=24 * 60),
      end_time=datetime.datetime.now(tz=datetime.timezone.utc)
  ),
  scope=SCOPE
)

Consolider les souvenirs pré-extraits

Au lieu d'utiliser le processus d'extraction automatique de la banque de souvenirs, vous pouvez fournir directement des souvenirs pré-extraits. Les souvenirs de source directe seront consolidés avec les souvenirs existants pour la même portée. Cela peut être utile lorsque vous souhaitez que votre agent ou un humain dans la boucle soit responsable de l'extraction des souvenirs, mais que vous souhaitez toujours profiter de la consolidation de la Memory Bank pour vous assurer qu'il n'y a pas de souvenirs en double ou contradictoires.

client.agent_engines.memories.generate(
    name=agent_engine.api_resource.name,
    direct_memories_source={"direct_memories": [{"fact": "FACT"}]},
    scope=SCOPE
)

Remplacez les éléments suivants :

• FACT : fait préextrait qui doit être consolidé avec les souvenirs existants. Vous pouvez fournir jusqu'à cinq faits préextraits dans une liste comme celle-ci :

  {"direct_memories": [{"fact": "fact 1"}, {"fact": "fact 2"}]}
  

• SCOPE : dictionnaire représentant le champ d'application des souvenirs générés. Exemple : {"session_id": "MY_SESSION"}. Seuls les souvenirs ayant la même portée sont pris en compte pour la consolidation.

Utiliser des entrées multimodales

Vous pouvez extraire des souvenirs à partir d'entrées multimodales. Toutefois, les souvenirs ne sont extraits que du texte, des fichiers intégrés et des données de fichier du contenu source. Tous les autres contenus, y compris les appels de fonction et les réponses, sont ignorés lors de la génération de souvenirs.

Les souvenirs peuvent être extraits des images, des vidéos et des éléments audio fournis par l'utilisateur. Si Memory Bank juge que le contexte fourni par l'entrée multimodale est pertinent pour les futures interactions, une mémoire textuelle peut être créée, incluant les informations extraites de l'entrée. Par exemple, si l'utilisateur fournit une image d'un golden retriever avec le texte "C'est mon chien", Memory Bank génère un souvenir tel que "Mon chien est un golden retriever".

Par exemple, vous pouvez fournir une image et le contexte de l'image dans la charge utile :

with open(file_name, "rb") as f:
    inline_data = f.read()

events =  [
  {
    "content": {
      "role": "user",
      "parts": [
        {"text": "This is my dog"},
        {
          "inline_data": {
            "mime_type": "image/jpeg",
            "data": inline_data
          }
        },
        {
          "file_data": {
            "file_uri": "gs://cloud-samples-data/generative-ai/image/dog.jpg",
            "mime_type": "image/jpeg"
          }
        },
      ]
    }
  }
]

from google import genai
import vertexai

with open(file_name, "rb") as f:
    inline_data = f.read()

events = [
  vertexai.types.GenerateMemoriesRequestDirectContentsSourceEvent(
    content=genai.types.Content(
      role="user",
      parts=[
        genai.types.Part.from_text(text="This is my dog"),
        genai.types.Part.from_bytes(
          data=inline_data,
          mime_type="image/jpeg",
        ),
        genai.types.Part.from_uri(
          file_uri="gs://cloud-samples-data/generative-ai/image/dog.jpg",
          mime_type="image/jpeg",
        )
      ]
    )
  )
]

Lorsque vous utilisez des sessions Agent Runtime comme source de données, le contenu multimodal est fourni directement dans les événements de la session.

Étapes suivantes