Configurer Memory Bank

Pour utiliser Agent Platform Memory Bank, vous devez d'abord créer et configurer une instance Memory Bank. Cette instance gère vos souvenirs et peut être intégrée à vos agents sur différents runtimes.

Ce document explique comment configurer votre projet Google Cloud , installer les bibliothèques requises et créer ou mettre à jour une instance avec des configurations personnalisées telles que des thèmes et un TTL.

Commencer

Avant d'utiliser Memory Bank, vous devez configurer votre environnement.

Configurer votre projet Google Cloud

Chaque projet peut être identifié de deux manières : par son numéro ou par son ID. PROJECT_NUMBER est automatiquement généré lorsque vous créez le projet, tandis que PROJECT_ID est défini par vous ou par le créateur du projet. Pour configurer un projet :

  1. Connectez-vous à votre compte Google Cloud . Si vous débutez sur Google Cloud, créez un compte pour évaluer les performances de nos produits en conditions réelles. Les nouveaux clients bénéficient également de 300 $ de crédits sans frais pour exécuter, tester et déployer des charges de travail.

  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  3. Verify that billing is enabled for your Google Cloud project.

  4. Enable the Agent Platform API.

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

    Enable the API

  5. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  6. Verify that billing is enabled for your Google Cloud project.

  7. Enable the Agent Platform API.

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

    Enable the API

    8.

Obtenir les rôles requis

Pour obtenir les autorisations nécessaires pour utiliser Memory Bank, demandez à votre administrateur de vous accorder les rôles IAM suivants sur votre projet :

Pour en savoir plus sur l'attribution de rôles, consultez Gérer l'accès aux projets, aux dossiers et aux organisations.

Vous pouvez également obtenir les autorisations requises avec des rôles personnalisés ou d'autres rôles prédéfinis.

Si vous envoyez des requêtes à Memory Bank depuis un agent déployé sur Google Kubernetes Engine (GKE) ou Cloud Run, assurez-vous que votre compte de service dispose des autorisations nécessaires. L'agent de service Reasoning Engine dispose déjà des autorisations nécessaires pour lire et écrire des souvenirs. Les requêtes sortantes d'Agent Runtime devraient donc déjà être autorisées à accéder à la Memory Bank.

Installer les bibliothèques

Cette section suppose que vous avez configuré un environnement de développement Python ou que vous utilisez un environnement d'exécution avec un environnement de développement Python (tel que Colaboratory).

Installez le SDK Agent Platform :

pip install google-cloud-aiplatform>=1.111.0

Authentification

Suivez les instructions de la section S'authentifier sur Vertex AI.

Configurer un client SDK Agent Platform

Exécutez le code suivant pour configurer un client Agent Platform SDK :

SDK Agent Platform 

import vertexai

client = vertexai.Client(
  project="PROJECT_ID",
  location="LOCATION",
)

Où :

Points de terminaison multirégionaux et mondiaux

Memory Bank est compatible avec les points de terminaison multirégionaux et mondiaux :

  • Pour les instances mondiales, définissez votre emplacement sur global.
  • Pour les instances multirégionales, définissez votre emplacement sur us ou eu.

Créer ou mettre à jour une instance Memory Bank

Pour commencer à utiliser Memory Bank, vous devez d'abord disposer d'une instance Memory Bank. Si vous n'avez pas encore d'instance, vous pouvez en créer une avec la configuration par défaut et le nom à afficher de votre choix.

# create the resource
memory_bank = client.agent_engines.create(
    config={
        "display_name": "My Memory Bank",
    }
)

# Optionally, print out the Memory Bank resource name. You will need the
# resource name to interact with your Memory Bank instance later on.
print(memory_bank.api_resource.name)

Si vous souhaitez personnaliser le comportement de la configuration de votre instance Memory Bank nouvelle ou existante, consultez Configurer votre instance Memory Bank. Par exemple, vous pouvez spécifier les informations que Memory Bank considère comme importantes à conserver.

Une fois que vous disposez d'une instance Memory Bank, vous pouvez utiliser son nom pour lire ou écrire des souvenirs. Exemple :

# Generate memories using your Memory Bank instance.
client.agent_engines.memories.generate(
  # `name` should have the format `projects/.../locations/.../reasoningEngines/...`.
  name=memory_bank.api_resource.name,
  ...
)

Utiliser avec Agent Runtime

Bien que Memory Bank puisse être utilisé dans n'importe quel environnement d'exécution, vous pouvez également l'utiliser avec Agent Runtime pour lire et écrire des souvenirs à partir de votre agent déployé.

Pour déployer un agent sur Agent Runtime avec une Memory Bank intégrée, commencez par configurer votre environnement pour Agent Runtime. Ensuite, préparez votre agent à être déployé sur Agent Runtime avec l'intégration de la mémoire. Votre agent déployé doit effectuer des appels pour lire et écrire des souvenirs selon les besoins.

AdkApp

Si vous utilisez le modèle Agent Platform Agent Development Kit (ADK), l'agent utilise VertexAiMemoryBankService par défaut lorsqu'il est déployé sur Agent Runtime. Cela signifie que les outils de mémoire ADK lisent les souvenirs de Memory Bank.

from google.adk.agents import Agent
from vertexai.preview.reasoning_engines import AdkApp

# Develop an agent using the ADK template.
agent = Agent(...)

adk_app = AdkApp(
      agent=adk_agent,
      ...
)

# Deploy the agent to Agent Runtime.
runtime = client.agent_engines.create(
      agent_engine=adk_app,
      config={
            "staging_bucket": "STAGING_BUCKET",
            "requirements": ["google-cloud-aiplatform[agent_engines,adk]"],
            # Optional.
            **context_spec
      }
)

# Update an existing Agent Runtime to add or modify the Runtime.
runtime = client.agent_engines.update(
      name=runtime.api_resource.name,
      agent=adk_app,
      config={
            "staging_bucket": "STAGING_BUCKET",
            "requirements": ["google-cloud-aiplatform[agent_engines,adk]"],
            # Optional.
            **context_spec
      }
)

Remplacez les éléments suivants :

  • STAGING_BUCKET : bucket Cloud Storage à utiliser pour préparer votre Agent Runtime.

Pour en savoir plus sur l'utilisation de Memory Bank avec ADK, consultez le guide de démarrage rapide avec ADK.

Agent personnalisé

Vous pouvez utiliser Memory Bank avec votre agent personnalisé déployé sur Agent Runtime. Dans ce cas, votre agent doit orchestrer les appels à Memory Bank pour déclencher les appels de génération de mémoire et de récupération de mémoire.

Votre application déployée dans Agent Runtime peut lire les variables d'environnement GOOGLE_CLOUD_PROJECT, GOOGLE_CLOUD_LOCATION et GOOGLE_CLOUD_AGENT_ENGINE_ID pour déduire le nom d'Agent Runtime à partir de l'environnement :

project = os.environ.get("GOOGLE_CLOUD_PROJECT")
location = os.environ.get("GOOGLE_CLOUD_LOCATION")
agent_engine_id = os.environ.get("GOOGLE_CLOUD_AGENT_ENGINE_ID")

agent_engine_name = f"projects/{project}/locations/{location}/reasoningEngines/{agent_engine_id}"

Si vous utilisez l'agent de service par défaut pour votre agent sur Agent Runtime, votre agent est déjà autorisé à lire et à écrire des souvenirs. Si vous utilisez un compte de service client, vous devez accorder à votre compte de service les autorisations de lecture et d'écriture des souvenirs. Les autorisations requises dépendent des opérations que votre agent doit pouvoir effectuer. Si vous souhaitez uniquement que votre agent récupère et génère des souvenirs, aiplatform.memories.generate et aiplatform.memories.retrieve suffisent.

Utiliser dans tous les autres environnements d'exécution

Si vous souhaitez utiliser la banque de mémoire dans un autre environnement, comme Cloud Run ou Colab, créez une banque de mémoire. Si vous ne fournissez pas de configuration, Memory Bank est créé avec les paramètres par défaut pour la gestion de la génération et de la récupération de la mémoire.

memory_bank = client.agent_engines.create()

Si vous avez déjà utilisé Memory Bank, la création d'une instance Memory Bank ne devrait prendre que quelques secondes. Si vous utilisez la Banque de données pour la première fois, cela peut prendre plus de temps (une à deux minutes).

Si vous souhaitez configurer le comportement, fournissez une configuration Memory Bank :

Créer

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

Mettre à jour

Si vous souhaitez modifier la configuration de votre Memory Bank, vous pouvez mettre à jour votre instance Memory Bank.

memory_bank = client.agent_engines.update(
  # You can access the name using `memory_bank.api_resource.name` for an AgentEngine object.
  name="MEMORY_BANK_NAME",
  config={
    "context_spec": {
      "memory_bank_config": ...
    }
  }
)

Remplacez les éléments suivants :

  • MEMORY_BANK_NAME : nom de la banque de données. Il doit être au format projects/.../locations/.../reasoningEngines/.... Consultez les régions compatibles pour Memory Bank.

Vous pouvez utiliser la banque de mémoire dans n'importe quel environnement autorisé à lire et à écrire des souvenirs. Par exemple, pour utiliser Memory Bank avec Cloud Run, accordez à l'identité du service Cloud Run les autorisations de lecture et d'écriture des souvenirs. Les autorisations requises dépendent des opérations que votre agent doit pouvoir effectuer. Si vous souhaitez uniquement que votre agent récupère et génère des souvenirs, aiplatform.memories.generate et aiplatform.memories.retrieve suffisent.

Configurer votre instance Memory Bank

Vous pouvez configurer votre Memory Bank pour personnaliser la façon dont les souvenirs sont générés et gérés. Si vous ne fournissez pas la configuration, Memory Bank utilise les paramètres par défaut pour chaque type de configuration.

Vous pouvez configurer les paramètres de Memory Bank suivants pour votre instance :

  • Configuration de la personnalisation : configure la façon dont les souvenirs sont extraits des données sources et consolidés avec les souvenirs existants.
  • Configuration de la recherche de similarité : spécifie le modèle d'embedding que la Memory Bank utilise pour la recherche de similarité. La valeur par défaut est text-embedding-005.
  • Configuration de la génération : configure le LLM que la banque de mémoire utilise pour la génération de mémoire. La valeur par défaut est gemini-3.5-flash.
  • Configuration de la valeur TTL : configure la façon dont la valeur TTL est automatiquement définie pour les entrées de mémoire créées ou mises à jour. Par défaut, aucune valeur TTL n'est définie.

L'exemple suivant montre la banque de données Memory par défaut :

Dictionnaire

memory_bank_config = {
  "generation_config": {
    # `gemini-3.5-flash` will be used to extract and consolidate memories.
    "model": "projects/{PROJECT}/locations/{LOCATION}/publishers/google/models/gemini-3.5-flash"
  },
  "similarity_search_config": {
    # `text-embedding-005` will be used for similarity search, including
    # during consolidation. Consolidation uses similarity search to find
    # candidate memories that may be updated with new information.
    "embedding_model": "projects/{PROJECT}/locations/{LOCATION}/publishers/google/models/text-embedding-005"
  },
  "ttl_config": {
    # Default TTL for memory revisions is 365 days.
    "memory_revision_default_ttl": f"{365 * 24 * 60 * 60}s"
  },
  "customization_configs": [
    {
      # Extract user information, preferences, key conversation details,
      # and information that the user explicitly asked to be remembered.
      "memory_topics": [
        {"managed_memory_topic": "USER_PERSONAL_INFO"},
        {"managed_memory_topic": "USER_PREFERENCES"},
        {"managed_memory_topic": "KEY_CONVERSATION_DETAILS"},
        {"managed_memory_topic": "EXPLICIT_INSTRUCTIONS"}
      ],
      "consolidation_config": {
        # Only use the latest memory revision of each candidate memory during
        # consolidation.
        "revisions_per_candidate_count": 1
      },
      # Only use the pre-defined set of examples.
      "generate_memories_examples": [],
      # Generate memories in the first person.
      "enable_third_person_memories": False
    }
  ],
  # Memory revisions will be persisted. This can be overridden on a request-level.
  "disable_memory_revisions": False
}

Basée sur les classes

from vertexai.types import MemoryBankCustomizationConfig as CustomizationConfig
from vertexai.types import MemoryBankCustomizationConfigConsolidationConfig as ConsolidationConfig
from vertexai.types import MemoryBankCustomizationConfigMemoryTopic as MemoryTopic
from vertexai.types import MemoryBankCustomizationConfigMemoryTopicManagedMemoryTopic as ManagedMemoryTopic
from vertexai.types import ManagedTopicEnum
from vertexai.types import ReasoningEngineContextSpecMemoryBankConfig as MemoryBankConfig
from vertexai.types import ReasoningEngineContextSpecMemoryBankConfigGenerationConfig as GenerationConfig
from vertexai.types import ReasoningEngineContextSpecMemoryBankConfigSimilaritySearchConfig as SimilaritySearchConfig
from vertexai.types import ReasoningEngineContextSpecMemoryBankConfigTtlConfig as TtlConfig

memory_bank_config = MemoryBankConfig(
  generation_config=GenerationConfig(
    # `gemini-3.5-flash` will be used to extract and consolidate memories.
    # Note: The global endpoint will be used for regions that don't have a
    # regional endpoint available.
    model="projects/{PROJECT}/locations/{LOCATION}/publishers/google/models/gemini-3.5-flash"
  ),
  similarity_search_config=SimilaritySearchConfig(
    # `text-embedding-005` will be used for similarity search, including
    # during consolidation. Consolidation uses similarity search to find
    # candidate memories that may be updated with new information.
    embedding_model="projects/{PROJECT}/locations/{LOCATION}/publishers/google/models/text-embedding-005"
  ),
  ttl_config=TtlConfig(
    # Default TTL for memory revisions is 365 days.
    memory_revision_default_ttl=f"{365 * 24 * 60 * 60}s"
  ),
  customization_configs=[
    CustomizationConfig(
      # Extract personal information, preferences, key conversation details,
      # and information that the user explicitly asked to be remembered.
      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))
      ],
      # Only use the pre-defined set of examples.
      generate_memories_examples=[],
      consolidation_config=ConsolidationConfig(
        # Only use the latest memory revision of each candidate memory during
        # consolidation.
        revisions_per_candidate_count=1
      ),
      # Generate memories in the first person.
      enable_third_person_memories=False,
    )
  ],
  # Memory revisions will be persisted. This can be overridden on a request-level.
  disable_memory_revisions=False
)

Vous pouvez ajuster la configuration de la banque de mémoire lorsque vous créez ou mettez à jour votre instance. L'exemple suivant montre comment créer ou mettre à jour une instance avec une configuration de Memory Bank spécifique.

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

# Alternatively, update an existing Memory Bank instance's config.
memory_bank = client.agent_engines.update(
      name=memory_bank.api_resource.name,
      config={
          "context_spec": {
                "memory_bank_config": memory_bank_config
          }
      }
)

Configuration de la personnalisation de la mémoire en langage naturel

Pour personnaliser la façon dont Memory Bank extrait les souvenirs en langage naturel, configurez le comportement d'extraction lorsque vous configurez votre instance. Utilisez les options suivantes pour personnaliser le comportement :

  • Configurer les thèmes de mémoire : définissez le type d'informations que Memory Bank doit considérer comme significatives pour les conserver. Seules les informations qui correspondent à l'un de ces thèmes de mémoire seront conservées par Memory Bank.
  • Fournir des exemples few-shot : montrez le comportement attendu pour l'extraction de la mémoire vers la banque de mémoire.
  • Configurer la perspective des souvenirs : configurez si les souvenirs doivent être générés à la première personne (par défaut) ou à la troisième personne.
  • Configurer la consolidation : configurez le nombre de révisions de mémoire que Memory Bank prend en compte lors de la consolidation de chaque candidat de mémoire.

Vous pouvez personnaliser le comportement d'extraction de votre banque de mémoire en deux étapes : dire et montrer. Les thèmes de mémoire indiquent à la banque de mémoire quelles informations conserver. Les exemples de type "few-shot" indiquent à la Memory Bank le type d'informations qui doit entraîner une mémoire spécifique. Ils l'aident ainsi à apprendre les schémas, les nuances et les expressions que vous attendez qu'elle comprenne.

Vous pouvez éventuellement configurer différents comportements pour différents niveaux de portée. Par exemple, les thèmes qui ont du sens pour les souvenirs au niveau de la session peuvent ne pas en avoir pour les souvenirs au niveau de l'utilisateur (sur plusieurs sessions). Pour configurer le comportement d'un certain sous-ensemble de souvenirs, définissez les clés de portée de la configuration de personnalisation. Seules les requêtes GenerateMemories qui incluent ces clés de portée utiliseront cette configuration. Vous pouvez également configurer le comportement par défaut (qui s'applique à tous les ensembles de clés de portée) en omettant le champ scope_key. Cette configuration s'appliquera à toutes les requêtes qui ne disposent pas d'une configuration correspondant exactement aux clés de portée d'une autre configuration de personnalisation.

Par exemple, user_level_config ne s'appliquerait qu'aux requêtes GenerateMemories qui utilisent exactement la clé de portée user_id (c'est-à-dire scope={"user_id": "123"} sans clé supplémentaire). default_config s'appliquerait aux autres demandes :

Dictionnaire 


user_level_config = {
  "scope_keys": ["user_id"],
  "memory_topics": [...],
  "generate_memories_examples": [...]
}

default_config = {
  "memory_topics": [...],
  "generate_memories_examples": [...]
}

memory_bank_config = {
  "customization_configs": [
    user_level_config,
    default_config
  ]
}

Basée sur les classes 

from vertexai.types import MemoryBankCustomizationConfig as CustomizationConfig

user_level_config = CustomizationConfig(
  scope_keys=["user_id"],
  memory_topics=[...],
  generate_memories_examples=[...]
)

Configurer les thèmes de la mémoire

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 est compatible avec deux types de thèmes de mémoire :

  • Sujets gérés : le libellé et les instructions sont définis par Memory Bank. Il vous suffit d'indiquer le nom du thème géré. Par 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
    )
)

    Memory Bank accepte 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 importantes ou conclusions 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 d'une information ou l'oublier (EXPLICIT_INSTRUCTIONS) : informations que l'utilisateur demande explicitement à l'agent de mémoriser ou d'oublier. Par exemple, si l'utilisateur dit "Souviens-toi que j'utilise principalement Python", Memory Bank génère un souvenir tel que "J'utilise principalement Python".

  • 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. Par 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 également de fournir des exemples few-shot montrant comment les souvenirs doivent être extraits de votre conversation.

La personnalisation vous permet d'utiliser n'importe quelle combinaison de thèmes de souvenirs. Par exemple, vous pouvez utiliser un sous-ensemble des thèmes de mémoire gérée disponibles :

Dictionnaire

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

Basée sur les classes

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

customization_config = CustomizationConfig(
  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)
      ),
  ]
)

Vous pouvez également utiliser une combinaison de thèmes gérés et personnalisés (ou uniquement des thèmes personnalisés) :

Dictionnaire

customization_config = {
  "memory_topics": [
    { "managed_memory_topic": { "managed_topic_enum": "USER_PERSONAL_INFO" } },
    {
      "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 MemoryBankCustomizationConfig as CustomizationConfig
from vertexai.types import MemoryBankCustomizationConfigMemoryTopic as MemoryTopic
from vertexai.types import MemoryBankCustomizationConfigMemoryTopicCustomMemoryTopic as CustomMemoryTopic
from vertexai.types import MemoryBankCustomizationConfigMemoryTopicManagedMemoryTopic as ManagedMemoryTopic
from vertexai.types import ManagedTopicEnum

customization_config = CustomizationConfig(
  memory_topics=[
      MemoryTopic(
          managed_memory_topic=ManagedMemoryTopic(
              managed_topic_enum=ManagedTopicEnum.USER_PERSONAL_INFO)
      ),
      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."""
          )
    )
  ]
)

Exemples few-shot

Les exemples few-shot vous permettent de montrer à la Memory Bank le comportement attendu pour l'extraction de la mémoire. Par exemple, vous pouvez fournir un exemple de conversation et les souvenirs qui doivent en être extraits.

Nous vous recommandons de toujours utiliser des few-shots avec des thèmes personnalisés pour que la Memory Bank puisse apprendre le comportement souhaité. Les few-shots sont facultatifs lorsque vous utilisez des thèmes gérés, car la banque de mémoire définit des exemples pour chaque thème. Montrez les conversations qui ne devraient pas générer de souvenirs en fournissant une liste generated_memories vide.

Par exemple, vous pouvez fournir des exemples few-shot qui montrent comment extraire les commentaires sur votre entreprise à partir des messages des clients :

Dictionnaire

example = {
    "conversationSource": {
      "events": [
        {
          "content": {
            "role": "model",
            "parts": [{ "text": "Welcome back to The Daily Grind! We'd love to hear your feedback on your visit." }] }
        },
        {
          "content": {
            "role": "user",
            "parts": [{ "text": "Hey. The drip coffee was a bit lukewarm today, which was a bummer. Also, the music was way too loud, I could barely hear my friend." }] }
        }
      ]
    },
    "generatedMemories": [
      {
        "fact": "The user reported that the drip coffee was lukewarm."
      },
      {
        "fact": "The user felt the music in the shop was too loud."
      }
    ]
}

Basée sur les classes

from google.genai.types import Content, Part
from vertexai.types import MemoryBankCustomizationConfigGenerateMemoriesExample as GenerateMemoriesExample
from vertexai.types import MemoryBankCustomizationConfigGenerateMemoriesExampleConversationSource as ConversationSource
from vertexai.types import MemoryBankCustomizationConfigGenerateMemoriesExampleConversationSourceEvent as ConversationSourceEvent
from vertexai.types import MemoryBankCustomizationConfigGenerateMemoriesExampleGeneratedMemory as ExampleGeneratedMemory

example = GenerateMemoriesExample(
    conversation_source=ConversationSource(
        events=[
            ConversationSourceEvent(
                content=Content(
                    role="model",
                    parts=[Part(text="Welcome back to The Daily Grind! We'd love to hear your feedback on your visit.")]
                )
            ),
            ConversationSourceEvent(
                content=Content(
                    role="user",
                    parts=[Part(text= "Hey. The drip coffee was a bit lukewarm today, which was a bummer. Also, the music was way too loud, I could barely hear my friend.")]
                )
            )
        ]
    ),
    generated_memories=[
        ExampleGeneratedMemory(
            fact="The user reported that the drip coffee was lukewarm."
        ),
        ExampleGeneratedMemory(
            fact="The user felt the music in the shop was too loud."
        )
    ]
)

Vous pouvez également fournir des exemples de conversations qui ne doivent générer aucun souvenir en fournissant une liste vide pour le résultat attendu (generated_memories) :

Dictionnaire

example = {
    "conversationSource": {
        "events": [
          {
              "content": {
                  "role": "model",
                  "parts": [{ "text": "Good morning! What can I get for you at The Daily Grind?" }] }
          },
          {
              "content": {
                  "role": "user",
                  "parts": [{ "text": "Thanks for the coffee." }] }
          }
        ]
    },
    "generatedMemories": []
}

Basée sur les classes

from google.genai.types import Content, Part
from vertexai.types import MemoryBankCustomizationConfigGenerateMemoriesExample as GenerateMemoriesExample
from vertexai.types import MemoryBankCustomizationConfigGenerateMemoriesExampleConversationSource as ConversationSource
from vertexai.types import MemoryBankCustomizationConfigGenerateMemoriesExampleConversationSourceEvent as ConversationSourceEvent

example = GenerateMemoriesExample(
    conversation_source=ConversationSource(
        events=[
            ConversationSourceEvent(
                content=Content(
                    role="model",
                    parts=[Part(text="Welcome back to The Daily Grind! We'd love to hear your feedback on your visit.")]
                )
            ),
            ConversationSourceEvent(
                content=Content(
                    role="user",
                    parts=[Part(text= "Thanks for the coffee!")]
                )
            )
        ]
    ),
    generated_memories=[]
)

Perspective de la mémoire

Par défaut, les souvenirs sont générés à la première personne (par exemple, "J'utilise Memory Bank pour gérer ma mémoire."). Vous pouvez configurer Memory Bank pour qu'il génère du contenu à la troisième personne (par exemple, "L'utilisateur utilise Memory Bank pour la gestion de la mémoire") à l'aide du paramètre enable_third_person_memories.

Dictionnaire

customization_config = {
  "enable_third_person_memories": True
}

Basée sur les classes

from vertexai.types import MemoryBankCustomizationConfig as CustomizationConfig

customization_config = CustomizationConfig(
    enable_third_person_memories=True
)

Personnalisation de la consolidation

Lors de la consolidation, la Banque de mémoire détermine comment intégrer les nouvelles informations à votre ensemble de mémoire existant. Memory Bank évalue s'il faut AJOUTER de nouveaux souvenirs, METTRE À JOUR les souvenirs existants avec du contexte supplémentaire ou SUPPRIMER les souvenirs obsolètes.

Pour garantir des souvenirs corroborés et de haute qualité, Memory Bank peut éventuellement analyser l'historique d'un souvenir afin de distinguer les tendances à long terme des valeurs aberrantes ponctuelles.

Par défaut, la banque de données compare uniquement les nouvelles informations à l'instantané le plus récent d'une mémoire candidate (une révision de mémoire). Pour approfondir cette analyse, configurez le paramètre revisions_per_candidate_count. Ce paramètre définit le nombre de révisions précédentes de chaque "mémoire candidate" (l'enregistrement spécifique évalué pour une mise à jour) que la banque de mémoire prend en compte lors de la consolidation.

Dictionnaire

customization_config = {
  "consolidation_customization": {
    "revisions_per_candidate_count": 10
  }
}

Basée sur les classes

from vertexai.types import MemoryBankCustomizationConfig as CustomizationConfig
from vertexai.types import MemoryBankCustomizationConfigConsolidationConfig as ConsolidationConfig

customization_config = CustomizationConfig(
    consolidation_customization=ConsolidationConfig(
      revisions_per_candidate_count=10
    )
)

L'augmentation de revisions_per_candidate_count permet d'obtenir des souvenirs plus cohérents et corroborés en tenant compte de la répétition des informations ingérées. Toutefois, un nombre plus élevé augmente la consommation de jetons lors du processus de consolidation.

Configuration de la recherche de similarités

La configuration de la recherche de similarité contrôle le modèle d'embedding utilisé par votre instance pour la recherche de similarité. La recherche de similarité est utilisée pour identifier les souvenirs qui peuvent être consolidés et pour la récupération de souvenirs basée sur la recherche de similarité. Si cette configuration n'est pas fournie, Memory Bank utilise text-embedding-005 comme modèle par défaut.

Si vous pensez que les conversations des utilisateurs seront dans des langues autres que l'anglais, utilisez un modèle compatible avec plusieurs langues, comme gemini-embedding-2, gemini-embedding-001 ou text-multilingual-embedding-002, pour améliorer la qualité de la récupération.

Dictionnaire

memory_bank_config = {
    "similarity_search_config": {
        "embedding_model": "EMBEDDING_MODEL",
    }
}

Basée sur les classes 

from vertexai.types import ReasoningEngineContextSpecMemoryBankConfig as MemoryBankConfig
from vertexai.types import ReasoningEngineContextSpecMemoryBankConfigSimilaritySearchConfig as SimilaritySearchConfig

memory_bank_config = MemoryBankConfig(
    similarity_search_config=SimilaritySearchConfig(
        embedding_model="EMBEDDING_MODEL"
    )
)

Remplacez les éléments suivants :

  • EMBEDDING_MODEL : modèle d'embedding textuel Google à utiliser pour la recherche par similarité, au format projects/{project}/locations/{location}/publishers/google/models/{model}.

Configuration de génération

La configuration de la génération contrôle le LLM utilisé pour générer des souvenirs, y compris pour extraire des souvenirs et consolider de nouveaux souvenirs avec des souvenirs existants.

À compter du 29 juin 2026, Memory Bank utilisera gemini-3.5-flash pour le modèle par défaut. Les instances créées avant cette date utilisent gemini-2.5-flash.

Pour les nouvelles instances de Memory Bank utilisant le modèle par défaut :

  • Les instances Memory Bank dans les régions uniques us-* (par exemple, us-central1) ou multirégionales us utilisent le point de terminaison Gemini 3.5 multirégional us.
  • Les instances Memory Bank dans les régions multirégionales eu ou les régions uniques eu-* (par exemple, europe-west2) utilisent le point de terminaison multirégional eu de Gemini 3.5.
  • Toutes les autres régions de la mémoire bancaire utilisent le point de terminaison mondial Gemini 3.5.

Pour les instances Memory Bank créées avant le 29 juin 2026 à l'aide du modèle par défaut, Memory Bank utilise le point de terminaison Gemini global pour les régions qui ne disposent pas d'un point de terminaison Gemini 2.5 régional.

Dictionnaire

memory_bank_config = {
  "generation_config": {
    "model": "LLM_MODEL",
  }
}

Basée sur les classes 

from vertexai.types import ReasoningEngineContextSpecMemoryBankConfig as MemoryBankConfig
from vertexai.types import ReasoningEngineContextSpecMemoryBankConfigGenerationConfig as GenerationConfig

memory_bank_config = MemoryBankConfig(
  generation_config=GenerationConfig(
    model="LLM_MODEL"
  )
)

Remplacez les éléments suivants :

  • LLM_MODEL : modèle LLM Google à utiliser pour extraire et consolider les souvenirs, au format projects/{project}/locations/{location}/publishers/google/models/{model}.

Configuration de la valeur TTL (Time to Live)

La configuration TTL contrôle la façon dont Memory Bank doit définir dynamiquement le délai d'expiration des souvenirs. Une fois leur durée de vie expirée, les souvenirs ne pourront plus être récupérés et seront supprimés.

Si la configuration n'est pas fournie, le délai d'expiration ne sera pas défini de manière dynamique pour les souvenirs créés ou modifiés. Par conséquent, les souvenirs n'expireront pas, sauf si leur délai d'expiration est défini manuellement.

Deux options s'offrent à vous pour configurer le TTL :

  • Valeur TTL par défaut : la valeur TTL sera appliquée à toutes les opérations qui créent ou mettent à jour une entrée de mémoire, y compris UpdateMemory, CreateMemory et GenerateMemories.

    Dictionnaire

    memory_bank_config = {
  "ttl_config": {
      "default_ttl": f"TTLs"
  }
}

    Basée sur les classes 

    from vertexai.types import ReasoningEngineContextSpecMemoryBankConfig as MemoryBankConfig
from vertexai.types import ReasoningEngineContextSpecMemoryBankConfigTtlConfig as TtlConfig

memory_bank_config = MemoryBankConfig(
  ttl_config=TtlConfig(
      default_ttl=f"TTLs"
  )
)

    Remplacez les éléments suivants :

    • TTL : durée en secondes de la valeur TTL. Pour les entrées de mémoire mises à jour, le nouveau délai d'expiration calculé (maintenant + TTL) remplacera le délai d'expiration précédent.

  • Valeur TTL précise (par opération) : la valeur TTL est calculée en fonction de l'opération qui a créé ou mis à jour la mémoire. Si elle n'est pas définie pour une opération donnée, l'opération ne mettra pas à jour le délai d'expiration de la mémoire.

    Dictionnaire

    memory_bank_config = {
  "ttl_config": {
      "granular_ttl": {
          "create_ttl": f"CREATE_TTLs",
          "generate_created_ttl": f"GENERATE_CREATED_TTLs",
          "generate_updated_ttl": f"GENERATE_UPDATED_TTLs"
      }
  }
}

    Basée sur les classes 

    from vertexai.types import ReasoningEngineContextSpecMemoryBankConfig as MemoryBankConfig
from vertexai.types import ReasoningEngineContextSpecMemoryBankConfigTtlConfig as TtlConfig
from vertexai.types import ReasoningEngineContextSpecMemoryBankConfigTtlConfigGranularTtlConfig as GranularTtlConfig

memory_bank_config = MemoryBankConfig(
  ttl_config=TtlConfig(
      granular_ttl_config=GranularTtlConfig(
          create_ttl=f"CREATE_TTLs",
          generate_created_ttl=f"GENERATE_CREATED_TTLs",
          generate_updated_ttl=f"GENERATE_UPDATED_TTLs",
      )
  )
)

    Remplacez les éléments suivants :

    • CREATE_TTL : durée en secondes de la valeur TTL pour les entrées de mémoire créées à l'aide de CreateMemory.
    • GENERATE_CREATED_TTL : durée en secondes de la valeur TTL pour les entrées de mémoire créées à l'aide de GenerateMemories.
    • GENERATE_UPDATED_TTL : durée en secondes de la valeur TTL pour les souvenirs mis à jour à l'aide de GenerateMemories. La nouvelle date d'expiration calculée (maintenant + TTL) remplacera la date d'expiration précédente de l'entrée de mémoire.

Étapes suivantes

Guide de démarrage rapide

Faites vos premiers pas avec l'API Memory Bank pour gérer les souvenirs à long terme.

Guide de démarrage rapide

Commencez à utiliser l'Agent Development Kit (ADK).