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 dans différents environnements d'exécution.

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 une valeur 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, if it is not already enabled.

    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, if it is not already enabled.

    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 autorisations requises

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 à partir d'un agent déployé sur Google Kubernetes Engine (GKE) ou Cloud Run, assurez-vous que votre compte de service dispose des autorisations nécessaires pour lire, écrire ou générer des souvenirs. L'agent de service Reasoning Engine dispose déjà des autorisations nécessaires pour lire, écrire et générer des souvenirs. Les requêtes sortantes d'Agent Runtime devraient donc déjà être autorisées à accéder à la banque de mémoire.

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-agentplatform>=2.0.1

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 SDK Agent Platform :

SDK Agent Platform 

import agentplatform

client = agentplatform.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 globales, définissez l'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 à l'aide de la configuration par défaut et d'un nom à afficher de votre choix.

# create the resource
memory_bank = client.memory_banks.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.name)

Si vous souhaitez personnaliser le comportement de votre instance Memory Bank, qu'elle soit 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 infos mémorisées. Exemple :

# Generate memories using your Memory Bank instance.
client.memory_banks.memories.generate(
  # `name` should have the format `projects/.../locations/.../reasoningEngines/...`.
  name=memory_bank.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 informations mémorisées à partir de votre agent déployé.

Pour déployer un agent sur Agent Runtime avec Memory Bank intégré, 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 si nécessaire.

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 de l'ADK lisent les informations mémorisées dans Memory Bank.

from google.adk.agents import Agent
from agentplatform.frameworks 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.runtimes.create(
      agent=adk_app,
      config={
            "staging_bucket": "STAGING_BUCKET",
            "requirements": ["google-cloud-agentplatform[runtimes,adk]"],
            # Optional.
            **context_spec
      }
)

# Update an existing Agent Runtime to add or modify the Runtime.
runtime = client.runtimes.update(
      name=runtime.api_resource.name,
      agent=adk_app,
      config={
            "staging_bucket": "STAGING_BUCKET",
            "requirements": ["google-cloud-agentplatform[runtimes,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 Agent Runtime 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 nécessaires pour lire et écrire 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.

Utilisation dans tous les autres environnements d'exécution

Si vous souhaitez utiliser Memory Bank dans un autre environnement, comme Cloud Run ou Colab, créez une instance Memory Bank. 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.memory_banks.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 Memory Bank 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.memory_banks.create(
  managed_semantic_memory_config={
    "generation_config": ...,
    "unstructured_memory_configs": [...],
    "structured_memory_configs": [...],
    "similarity_search_config": ...,
    "ttl_config": ...,
    "disable_memory_revisions": False,
  }
)

Mettre à jour

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

memory_bank = client.runtimes.update(
  # You can access the name using `memory_bank.name` for a MemoryBank object.
  name="MEMORY_BANK_NAME",
  config={
    "context_spec": {
      "memory_bank_config": {
        "generation_config": ...,
        "customization_configs": [...],
        "structured_memory_configs": [...],
        "similarity_search_config": ...,
        "ttl_config": ...,
        "disable_memory_revisions": False,
      }
    }
  }
)

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 disponibles 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 Memory Bank suivants pour votre instance :

L'exemple suivant montre le Memory Bank par défaut :

Dictionnaire

managed_semantic_memory_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"
  },
  "unstructured_memory_configs": [
    {
      # Extract user information, preferences, key conversation details,
      # and information that the user explicitly asked to be remembered.
      "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"}}
      ],
      "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 agentplatform.types import ManagedSemanticMemoryConfig
from agentplatform.types import ManagedSemanticMemoryConfigGenerationConfig as GenerationConfig
from agentplatform.types import ManagedSemanticMemoryConfigSimilaritySearchConfig as SimilaritySearchConfig
from agentplatform.types import ManagedSemanticMemoryConfigTtlConfig as TtlConfig
from agentplatform.types import ManagedTopicEnum
from agentplatform.types import MemoryBankCustomizationConfig as CustomizationConfig
from agentplatform.types import MemoryBankCustomizationConfigConsolidationConfig as ConsolidationConfig
from agentplatform.types import MemoryBankCustomizationConfigMemoryTopic as MemoryTopic
from agentplatform.types import MemoryBankCustomizationConfigMemoryTopicManagedMemoryTopic as ManagedMemoryTopic

managed_semantic_memory_config = ManagedSemanticMemoryConfig(
  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"
  ),
  unstructured_memory_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 Memory Bank lorsque vous créez ou mettez à jour votre instance. L'exemple suivant montre comment créer une instance avec une configuration de banque de mémoire spécifique.

memory_bank = client.memory_banks.create(
    managed_semantic_memory_config=managed_semantic_memory_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 :

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 à Memory Bank les informations à conserver. Les exemples de type "few-shot" montrent à la Memory Bank le type d'informations qui doivent entraîner une mémoire spécifique, ce qui l'aide à apprendre les schémas, les nuances et les expressions que vous attendez qu'elle comprenne.

Vous pouvez éventuellement configurer un comportement différent pour différents niveaux de champ d'application. Par exemple, les thèmes pertinents pour les souvenirs au niveau de la session peuvent ne pas l'être 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 champ d'application de la configuration de personnalisation. Seules les requêtes GenerateMemories incluant ces clés de champ d'application 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, le user_level_config ne s'applique qu'aux requêtes GenerateMemories qui utilisent exactement la clé de champ d'application user_id (c'est-à-dire scope={"user_id": "123"} sans clés supplémentaires). 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": [...]
}

managed_semantic_memory_config = {
  "unstructured_memory_configs": [
    user_level_config,
    default_config
  ]
}

Basée sur les classes 

from agentplatform.types import ManagedSemanticMemoryConfig
from agentplatform.types import MemoryBankCustomizationConfig as CustomizationConfig

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

default_config = CustomizationConfig(
  memory_topics=[...],
  generate_memories_examples=[...]
)

managed_semantic_memory_config = ManagedSemanticMemoryConfig(
  unstructured_memory_configs=[
    user_level_config,
    default_config,
  ]
)

Configurer les thèmes des informations mémorisées

Les "thèmes 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 Memory Bank. Il vous suffit de fournir le nom du sujet géré. Par 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
    )
)

    Les thèmes gérés suivants sont compatibles avec Memory Bank :

    • 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 préférés, 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".

  • Sujets personnalisés : vous définissez l'étiquette et les instructions lors de la configuration de 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 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 montrant comment les souvenirs doivent être extraits de votre conversation.

Avec la personnalisation, vous pouvez utiliser n'importe quelle combinaison de thèmes de souvenirs. Par exemple, vous pouvez utiliser un sous-ensemble des sujets 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 agentplatform.types import ManagedTopicEnum
from agentplatform.types import MemoryBankCustomizationConfig as CustomizationConfig
from agentplatform.types import MemoryBankCustomizationConfigMemoryTopic as MemoryTopic
from agentplatform.types import MemoryBankCustomizationConfigMemoryTopicManagedMemoryTopic as ManagedMemoryTopic

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 agentplatform.types import ManagedTopicEnum
from agentplatform.types import MemoryBankCustomizationConfig as CustomizationConfig
from agentplatform.types import MemoryBankCustomizationConfigMemoryTopic as MemoryTopic
from agentplatform.types import MemoryBankCustomizationConfigMemoryTopicCustomMemoryTopic as CustomMemoryTopic
from agentplatform.types import MemoryBankCustomizationConfigMemoryTopicManagedMemoryTopic as ManagedMemoryTopic

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 à Memory Bank le comportement d'extraction de mémoire attendu. Par exemple, vous pouvez fournir un exemple de conversation d'entrée et les informations mémorisées qui doivent être extraites de cette conversation.

Nous vous recommandons de toujours utiliser des exemples few-shot avec des thèmes personnalisés afin que Memory Bank puisse apprendre le comportement attendu. Les exemples few-shot sont facultatifs lorsque vous utilisez des thèmes gérés, car Memory Bank définit des exemples pour chaque thème. Illustrez 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 agentplatform.types import MemoryBankCustomizationConfigGenerateMemoriesExample as GenerateMemoriesExample
from agentplatform.types import MemoryBankCustomizationConfigGenerateMemoriesExampleConversationSource as ConversationSource
from agentplatform.types import MemoryBankCustomizationConfigGenerateMemoriesExampleConversationSourceEvent as ConversationSourceEvent
from agentplatform.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 pas générer de souvenirs 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 agentplatform.types import MemoryBankCustomizationConfigGenerateMemoriesExample as GenerateMemoriesExample
from agentplatform.types import MemoryBankCustomizationConfigGenerateMemoriesExampleConversationSource as ConversationSource
from agentplatform.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 "Souvenirs"

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'elle génère des réponses à 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 agentplatform.types import MemoryBankCustomizationConfig as CustomizationConfig

customization_config = CustomizationConfig(
    enable_third_person_memories=True
)

Personnalisation de la consolidation

Lors de la consolidation, Memory Bank détermine comment intégrer les informations nouvellement acquises dans votre ensemble de mémoire existant. Memory Bank évalue s'il faut AJOUTER de nouvelles informations mémorisées, METTRE À JOUR les informations mémorisées existantes avec du contexte supplémentaire ou SUPPRIMER les informations mémorisées obsolètes.

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

Par défaut, Memory Bank ne compare les nouvelles informations qu'à l'instantané le plus récent d'une mémoire candidate (une "révision de mémoire"). Pour augmenter la profondeur de 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 en cours d'évaluation pour une mise à jour) que Memory Bank prend en compte lors de la consolidation.

Dictionnaire

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

Basée sur les classes

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

customization_config = CustomizationConfig(
    consolidation_config=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 pendant le processus de consolidation.

Application des configurations de personnalisation…

Pour appliquer des configurations de personnalisation à votre instance Memory Bank, fournissez-les dans la liste unstructured_memory_configs de votre managed_semantic_memory_config :

Dictionnaire

managed_semantic_memory_config = {
  "unstructured_memory_configs": [customization_config],
  # Include other configurations (similarity search, generation, TTL)...
}

Basée sur les classes

from agentplatform.types import ManagedSemanticMemoryConfig

managed_semantic_memory_config = ManagedSemanticMemoryConfig(
  unstructured_memory_configs=[customization_config],
  # Include other configurations (similarity search, generation, TTL)...
)

Configuration de la recherche de similarités

La configuration de la recherche de similarités contrôle le modèle d'embedding utilisé par votre instance pour la recherche de similarités. La recherche de similarité permet d'identifier les mémoires candidates à la consolidation et à la récupération de mémoire 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 vous attendez à ce que les conversations des utilisateurs se déroulent dans des langues autres que l'anglais, utilisez un modèle compatible avec plusieurs langues, tel que gemini-embedding-2, gemini-embedding-001 ou text-multilingual-embedding-002, pour améliorer la qualité de la récupération.

Dictionnaire

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

Basée sur les classes 

from agentplatform.types import ManagedSemanticMemoryConfigSimilaritySearchConfig as SimilaritySearchConfig

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 de similarité, au format projects/{project}/locations/{location}/publishers/google/models/{model}.

Configuration de génération

La configuration de génération contrôle le LLM utilisé pour générer des entrées de mémoire, y compris pour extraire des entrées de mémoire et consolider les nouvelles entrées de mémoire avec les entrées de mémoire existantes.

À 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 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 l'emplacement multirégional eu ou les emplacements régionaux eu-* (par exemple, europe-west2) utilisent le point de terminaison Gemini 3.5 multirégional eu.
  • Toutes les autres régions de Memory Bank utilisent le point de terminaison Gemini 3.5 mondial.

Pour les instances de 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

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

Basée sur les classes 

from agentplatform.types import ManagedSemanticMemoryConfigGenerationConfig as GenerationConfig

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 manière dont Memory Bank doit définir dynamiquement le délai d'expiration des informations mémorisées. Une fois leur date d'expiration passée, les souvenirs ne seront plus disponibles 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 informations mémorisées créées ou modifiées. Par conséquent, les informations mémorisées n'expireront pas, sauf si leur délai d'expiration est défini manuellement.

Deux options sont disponibles pour la configuration du 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

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

    Basée sur les classes 

    from agentplatform.types import ManagedSemanticMemoryConfigTtlConfig as TtlConfig

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, la nouvelle date d'expiration calculée (maintenant + TTL) remplacera la date d'expiration précédente de l'entrée de mémoire.

  • 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 du souvenir.

    Dictionnaire

    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 agentplatform.types import ManagedSemanticMemoryConfigTtlConfig as TtlConfig
from agentplatform.types import ManagedSemanticMemoryConfigTtlConfigGranularTtlConfig as GranularTtlConfig

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 entrées de mémoire mises à jour à l'aide de GenerateMemories. La nouvelle date d'expiration calculée (maintenant + TTL) remplacera la date d'expiration précédente de la 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

Premiers pas avec Agent Development Kit (ADK)