Récupérer des souvenirs

Memory Bank vous permet de récupérer des infos mémorisées à l'aide de différentes opérations en fonction de vos besoins. Vous pouvez récupérer une seule info mémorisée, répertorier toutes les infos mémorisées ou effectuer une récupération basée sur le champ d'application avec la recherche de similarité.

Ce document explique comment utiliser ces opérations de récupération à l'aide du SDK Agent Platform.

Si vous utilisez Agent Development Kit (ADK), votre agent peut orchestrer automatiquement ces appels pour vous. Consultez le guide de démarrage rapide avec ADK.

Avant de commencer

Pour suivre les étapes de cette page, vous devez d'abord suivre les étapes de la section Configurer Memory Bank.

Opérations de récupération

Vous disposez des options suivantes pour récupérer les infos mémorisées générées :

  • Obtenir une info mémorisée : obtenez le contenu complet d'une seule info mémorisée à l'aide du SDK Agent Platform.

  • Récupérer des infos mémorisées : à l’aide du SDK Agent Platform, récupérez des infos mémorisées à l’aide de la récupération basée sur le champ d’application. Récupérez des infos mémorisées à l'aide de la recherche de similarité ou toutes les infos mémorisées dans le champ d'application.

  • Répertorier les infos mémorisées : répertoriez les infos mémorisées à l'aide du SDK Agent Platform.

Obtenir une info mémorisée

Utilisez GetMemories pour obtenir le contenu complet d'une seule info mémorisée :

memory = client.memory_banks.memories.get(
    name="MEMORY_NAME")

Remplacez les éléments suivants :

  • MEMORY_NAME: nom d'info mémorisée complet au format "projects/.../locations/.../reasoningEngines/.../memories...".

Récupérer des infos mémorisées à l'aide de la récupération basée sur le champ d'application

Vous pouvez utiliser RetrieveMemories pour récupérer des infos mémorisées pour un champ d'application particulier. Seules les infos mémorisées qui ont exactement le même champ d'application (indépendamment de l'ordre) que la requête de récupération sont renvoyées. Par exemple, vous pouvez récupérer toutes les infos mémorisées qui sont limitées à un utilisateur particulier à l'aide de {"user_id": "123"}. Si aucune info mémorisée n'est renvoyée, Memory Bank n'en possède aucune pour le champ d'application fourni.

Le champ d'application d'une info mémorisée est défini lorsque l'info mémorisée est générée ou créée, et il est immuable.

Vous pouvez utiliser RetrieveMemories pour effectuer les opérations suivantes pour un champ d'application particulier :

Si vous disposez de nombreuses infos mémorisées pour un champ d'application particulier, vous pouvez utiliser la recherche de similarité pour ne récupérer que les infos mémorisées les plus similaires en fournissant des paramètres de recherche de similarité. Memory Bank ne prend en compte que les infos mémorisées qui ont exactement le même champ d'application que la requête lors de l'exécution de la recherche de similarité. La recherche de similarité compare les vecteurs d'embedding entre les faits des infos mémorisées et la requête de recherche.

Les infos mémorisées renvoyées sont triées de la plus similaire (distance euclidienne la plus courte) à la moins similaire (distance euclidienne la plus grande) :

results = client.memory_banks.memories.retrieve(
    name=memory_bank.name,
    scope=SCOPE,
    similarity_search_params={
        "search_query": "QUERY",
        # Optional. Defaults to 3.
        "top_k": 3
    }
)
# RetrieveMemories returns a pager. You can use `page` to retrieve memories.

results.page

"""
Returns:

[
    RetrieveMemoriesResponseRetrievedMemory(
      memory=Memory(
        name="projects/.../locations/.../reasoningEngines/.../memories/...",
        ...
        fact="This is a fact."
      },
      distance=0.5
    ),
    RetrieveMemoriesResponseRetrievedMemory(
      memory=Memory(
        name="projects/.../locations/.../reasoningEngines/.../memories/...",
        ...
        fact="This is another fact."
      },
      distance=0.7
    ),
]
"""

Remplacez les éléments suivants :

  • QUERY : requête pour laquelle effectuer la recherche de similarité. Par exemple, vous pouvez utiliser le dernier tour de l'utilisateur dans la conversation comme requête.

  • SCOPE : dictionnaire représentant le champ d'application de la recherche de similarité. Par exemple, {"user_id": "123"}. Seules les infos mémorisées ayant le même champ d'application que la requête sont prises en compte.

Récupérer toutes les infos mémorisées

Si aucun paramètre de recherche de similarité n'est fourni, RetrieveMemories renvoie toutes les infos mémorisées qui ont le champ d'application fourni, quelle que soit leur similarité avec la conversation en cours.

results = client.memory_banks.memories.retrieve(
    name=memory_bank.name,
    scope=SCOPE
)
# RetrieveMemories returns a pager. You can use `page` to retrieve up to 100 memories per page.

results.page

"""
Returns:

[
    RetrieveMemoriesResponseRetrievedMemory(
      memory=Memory(
        name="projects/.../locations/.../reasoningEngines/.../memories/...",
        ...
        fact="This is a fact."
      }
    ),
    RetrieveMemoriesResponseRetrievedMemory(
      memory=Memory(
        name="projects/.../locations/.../reasoningEngines/.../memories/...",
        ...
        fact="This is another fact."
      }
    ),
]
"""

Remplacez les éléments suivants :

  • SCOPE : dictionnaire représentant le champ d'application de la récupération. Par exemple, {"user_id": "123"}. Seules les infos mémorisées ayant le même champ d'application que la requête sont renvoyées.

Répertorier les infos mémorisées

Utilisez ListMemories pour récupérer des infos mémorisées à partir de votre Memory Bank sans filtrage basé sur le champ d'application. Pour la récupération basée sur le champ d'application, utilisez RetrieveMemories plutôt. ListMemories n'est pas recommandé pour la récupération à faible latence.

pager = client.memory_banks.memories.list(name=memory_bank.name)
for page in pager:
  print(page)

Filtrer les infos mémorisées

Cette section explique comment utiliser des filtres pour limiter les infos mémorisées récupérées. Vous pouvez appliquer les filtres suivants :

Le filtrage des métadonnées et des champs système peut être utilisé dans la même requête.

Filtrer par métadonnées

Lorsque vous créez, mettez à jour ou générez des infos mémorisées, vous pouvez appliquer des métadonnées structurées aux infos mémorisées stockées :

import datetime

from agentplatform import types

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
        )
    ),
}

client.memory_banks.memories.create(
  ...,
  config={"metadata": metadata}
)

client.memory_banks.memories.update(
  ...,
  config={"metadata": metadata}
)

client.memory_banks.memories.generate(
  ...,
  config={"metadata": metadata}
)

Vous pouvez filtrer ces métadonnées lorsque vous récupérez des infos mémorisées à l'aide de l'attribut filter_groups. Les filtres de métadonnées sont définis sous forme normale disjonctive (DNF), qui est une expression logique de OR de AND.

Par exemple, la requête suivante récupère les infos mémorisées qui incluent les métadonnées ({"my_string_key": {"string_value": "my_value"}} AND {"my_double_key": {"double": 1.23}}) OR {"my_string_key": {"string_value": "other"}}.

Dictionnaire

results = client.memory_banks.memories.retrieve(
  ...,
  config={
    # Each element of `filter_groups` is combined using OR logic.
    "filter_groups": [
      {
        # Each element of `filters` is combined using AND logic.
        "filters": [
          {
            "key": "my_string_key",
            "value": {"string_value": "my_value"}
          },
          {
            "key": "my_double_key",
            "value": {"double_value": 1.23}
          }
        ]
      },
      {
        "filters": [
          {
            "key": "my_string_key",
            "value": {"string_value": "other"}
          }
        ]
      }
    ]
  }
)

Basé sur une classe

from agentplatform import types

results = client.memory_banks.memories.retrieve(
  ...,
  config=types.RetrieveMemoriesConfig(
    # Each element of `filter_groups` is combined using OR logic.
    filter_groups=[
      types.MemoryConjunctionFilter(
        # Each element of `filters` is combined using AND logic.
        filters=[
          types.MemoryFilter(
            key="my_string_key",
            value=types.MemoryMetadataValue(string_value="my_value")
          ),
          types.MemoryFilter(
            key="my_double_key",
            value=types.MemoryMetadataValue(double_value=1.23)
          )
        ]
      ),
      types.MemoryConjunctionFilter(
        filters=[
          types.MemoryFilter(
            key="my_string_key",
            value=types.MemoryMetadataValue(string_value="other")
          )
        ]
      )
    ]
  )
)

Filtrer par champs système

Vous pouvez filtrer les champs système à l'aide de l'attribut filter, qui attend une valeur de chaîne utilisant la syntaxe EBNF. Les champs système incluent create_time, update_time, fact, et topics.

La syntaxe EBNF présente les exigences suivantes lors de la construction d'une chaîne de filtre :

  • Pour combiner des filtres, utilisez AND et OR.
  • La chaîne doit utiliser des guillemets doubles ".
  • Les champs de date et d'heure (comme create_time) utilisent une chaîne entre guillemets doubles représentant la date et l'heure au format ISO 8601 ou un champ numérique représentant les microsecondes depuis l'époque Unix.

Par exemple, le filtre suivant peut être utilisé pour récupérer les infos mémorisées dans lesquelles le fact inclut la sous-chaîne "allergies" et update_time est postérieur au 1er janvier 2026.

filter_string = 'fact=~".*allergies.*" AND update_time>="2026-01-01T00:00:00Z"'

client.memory_banks.memories.retrieve(
  ...,
  config={"filter": filter_string}
)

client.memory_banks.memories.list(
  ...,
  config={"filter": filter_string}
)

Filtrer par thème

Les infos mémorisées générées sont automatiquement libellées avec le thème d'info mémorisée approprié.

Pour filtrer les thèmes gérés, utilisez topics.managed_memory_topic comme nom de champ et le ManagedTopicEnum attendu comme valeur, comme topics.managed_memory_topic: USER_PREFERENCES.

Pour filtrer les thèmes personnalisés, utilisez topics.custom_memory_topic_label comme nom de champ et le libellé du thème attendu comme valeur, comme topics.custom_memory_topic_label: custom-label.

filter_string = "topics.managed_memory_topic: USER_PREFERENCES " + \
"OR topics.custom_memory_topic_label: custom-label"

client.memory_banks.memories.retrieve(
  ...,
  config={"filter": filter_string}
)

client.memory_banks.memories.list(
  ...,
  config={"filter": filter_string}
)