Générer des souvenirs

Ce document explique comment fonctionne la génération de la mémoire, comment personnaliser l'extraction de la mémoire avec des thèmes et comment déclencher des requêtes de génération de la mémoire.

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

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

Memory Bank extrait les informations mémorisées des données sources et les organise automatiquement pour une collection spécifique d'informations mémorisées (définie par un scope) en ajoutant, mettant à jour et supprimant des informations mémorisées au fil du temps.

Lorsque vous déclenchez la génération de mémoire, 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 l'un des sujets de mémoire de votre instance seront conservées.

• Consolidation : identifie si les souvenirs existants de même portée doivent être supprimés ou mis à jour en fonction des informations extraites. La banque de mémoire vérifie que les nouvelles informations mémorisées ne sont pas des doublons ni des contradictions avant de les fusionner avec les informations existantes. 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 toutes les informations mémorisées existantes pour le même champ d'application 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'une mémoire 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 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 requête de génération de mémoire.

list(client.memory_banks.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 des informations mémorisées

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

• Sujets gérés : le libellé et les instructions sont définis par la Banque de souvenirs. Vous n'avez qu'à indiquer le nom de la rubrique gérée. Exemple :

  Dictionnaire

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

  Basée sur les classes

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

• Rubriques personnalisées : 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 agentplatform.types import MemoryBankCustomizationConfigMemoryTopic as MemoryTopic
  from agentplatform.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, telles que les noms, les relations, les loisirs et les 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) : goûts, aversions, styles ou habitudes, qu'ils soient explicites ou implicites. 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 pour un aller-retour entre JFK et SFO. Je pars le 1er juin 2025 et je rentre le 7 juin 2025."

• Instructions explicites de mémorisation / d'oubli (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", Memory Bank génère une mémoire telle 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 agentplatform.types import ManagedTopicEnum
from agentplatform.types import MemoryBankCustomizationConfigMemoryTopic as MemoryTopic
from agentplatform.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 les 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) avec un fait mémorisé. Cela est utile pour filtrer ou gérer le cycle de vie des mémoires.

import datetime

client.memory_banks.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 agentplatform import types

client.memory_banks.memories.generate(
    ...,
    config=types.GenerateMemoriesConfig(
        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 les métadonnées existantes. Si une clé existe déjà, la nouvelle valeur remplace 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 qui ont exactement les mêmes métadonnées que la requête. Si les métadonnées d'un souvenir ne sont pas identiques, il ne peut pas être consolidé et ne sera pas mis à jour.

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

Par défaut, la génération de 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.memory_banks.memories.generate(
    ...,
    config={
        "allowed_topics": [
            {"managed_memory_topic": "USER_PERSONAL_INFO"},
            {"custom_memory_topic_label": "business_feedback"}
        ]
    },
)

from agentplatform import types

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

Déclenchement de la génération de la mémoire…

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

• GenerateMemories : ingérer des données dans la banque de mémoire et déclencher immédiatement la génération de 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 mémoire en fonction du volume ou du temps. Pour en savoir plus, consultez Ingérer des événements.

La génération de mémoire extrait le contexte clé des conversations sources et le combine avec les informations mémorisées 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 informations mémorisées ayant la même portée peuvent être consolidées et récupérées ensemble.

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

GenerateMemoriesOperation(
  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'un nouveau souvenir a été ajouté, représentant un nouveau concept qui n'a pas été capturé par les souvenirs existants.

• UPDATED : indique qu'une mémoire existante a été mise à jour, ce qui se produit si la mémoire couvrait des concepts similaires aux informations nouvellement extraites. Les faits de la mémoire peuvent être mis à jour avec de nouvelles informations ou rester les mêmes.

• 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.memory_banks.memories.generate 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 souvenirs en tant qu'opération de blocage est utile lorsque vous souhaitez inspecter manuellement les souvenirs générés ou informer les utilisateurs finaux des souvenirs qui ont été générés.

Toutefois, pour les agents de production, vous souhaitez généralement exécuter la génération de 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 est donc inutile 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.memory_banks.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 mémoire et traite les événements en arrière-plan par défaut.

Sources de données

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

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

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

• Fournissez des faits pré-extraits pour les consolider avec les informations mémorisées existantes pour la même portée.

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

client.memory_banks.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.memory_banks.memories.generate(
    name=memory_bank.name,
    direct_contents_source={
      "events": EVENTS
    },
    # For example, `scope={"user_id": "123"}`.
    scope=SCOPE,
    config={
        "wait_for_completion": True
    }
)

from google import genai
from agentplatform import types

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

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

Utiliser les sessions Agent Platform 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 informations mémorisées générées, Memory Bank extrait et utilise par défaut l'ID utilisateur de la session. 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.memory_banks.memories.generate(
  name=memory_bank.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
  }
)

from agentplatform import types

client.memory_banks.memories.generate(
  name=memory_bank.name,
  vertex_session_source=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 éventuellement indiquer une période pour spécifier les événements de la session à inclure. Si ce paramètre n'est pas fourni, tous les événements de la session sont inclus.

import datetime

client.memory_banks.memories.generate(
  name=memory_bank.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

from agentplatform import types

client.memory_banks.memories.generate(
  name=memory_bank.name,
  vertex_session_source=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
)

Consolidation des 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 le même champ d'application. Cela peut être utile lorsque vous souhaitez que votre agent ou un human-in-the-loop (avec intervention humaine) 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.memory_banks.memories.generate(
    name=memory_bank.name,
    direct_memories_source={"direct_memories": [{"fact": "FACT"}]},
    scope=SCOPE
)

Remplacez les éléments suivants :

• FACT : fait pré-extrait à consolider 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"}. Seules les informations mémorisées ayant le même champ d'application sont prises en compte pour la consolidation.

Utiliser une entrée multimodale

Vous pouvez extraire des souvenirs d'une entrée multimodale. Toutefois, les souvenirs ne sont extraits que du texte, des fichiers intégrés et des données de fichier du contenu source. Tout autre contenu, y compris les appels de fonction et les réponses, est ignoré 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 la banque de mémoire 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", la Banque de souvenirs 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
from agentplatform import types

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

events = [
  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",
        )
      ]
    )
  )
]

Étapes suivantes