Recuperare i ricordi

Memory Bank ti consente di recuperare le informazioni salvate utilizzando diverse operazioni a seconda delle tue esigenze. Puoi recuperare una singola informazione salvata, elencare tutte le informazioni salvate o eseguire il recupero basato sull'ambito con la ricerca di similarità.

Questo documento spiega come utilizzare queste operazioni di recupero utilizzando l'SDK Agent Platform.

Se utilizzi Agent Development Kit (ADK), il tuo agente può orchestrare automaticamente queste chiamate per te. Consulta la guida rapida con ADK.

Prima di iniziare

Per completare i passaggi descritti in questa pagina, devi prima completare i passaggi descritti in Configurare Memory Bank.

Operazioni di recupero

Hai le seguenti opzioni per recuperare le informazioni salvate generate:

  • Recupera informazione salvata: recupera l'intero contenuto di una singola informazione salvata utilizzando l' SDK Agent Platform.

  • Recupera informazioni salvate: utilizzando l'SDK Agent Platform, recupera le informazioni salvate utilizzando il recupero delle informazioni salvate basato sull'ambito. Recupera le informazioni salvate utilizzando la ricerca di similarità o tutte le informazioni salvate nell'ambito.

  • Elenca informazioni salvate: elenca le informazioni salvate utilizzando l'SDK Agent Platform.

Recupera informazione salvata

Utilizza GetMemories per recuperare l'intero contenuto di una singola informazione salvata:

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

Sostituisci quanto segue:

  • MEMORY_NAME: il nome completo di un'informazione salvata nel formato "projects/.../locations/.../reasoningEngines/.../memories...".

Recupera informazioni salvate utilizzando il recupero basato sull'ambito

Puoi utilizzare RetrieveMemories per recuperare le informazioni salvate per un ambito specifico. Vengono restituite solo le informazioni salvate che hanno esattamente lo stesso ambito (indipendentemente dall'ordine) della richiesta di recupero. Ad esempio, puoi recuperare tutte le informazioni salvate con ambito a un utente specifico utilizzando {"user_id": "123"}. Se non vengono restituite informazioni salvate, Memory Bank non ne ha per l'ambito fornito.

L'ambito di un'informazione salvata viene definito quando l'informazione salvata viene generata o creata ed è immutabile.

Puoi utilizzare RetrieveMemories per eseguire le seguenti operazioni per un ambito specifico:

Nei casi in cui hai molte informazioni salvate per un ambito specifico, puoi utilizzare la ricerca di similarità per recuperare solo le informazioni salvate più simili fornendo i parametri di ricerca di similarità. Quando esegue la ricerca di similarità, Memory Bank prende in considerazione solo le informazioni salvate che hanno esattamente lo stesso ambito della richiesta. La ricerca di similarità confronta i vector embedding tra i fatti delle informazioni salvate e la query di ricerca della richiesta.

Le informazioni salvate restituite sono ordinate dalla più simile (distanza euclidea più breve) alla meno simile (distanza euclidea più lunga):

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

Sostituisci quanto segue:

  • QUERY: la query per cui eseguire la ricerca di similarità. Ad esempio, puoi utilizzare l'ultimo turno utente della conversazione come query.

  • SCOPE: un dizionario che rappresenta l'ambito della ricerca di similarità. Ad esempio, {"user_id": "123"}. Vengono prese in considerazione solo le informazioni salvate con lo stesso ambito della richiesta.

Recupera tutte le informazioni salvate

Se non vengono forniti parametri di ricerca di similarità, RetrieveMemories restituisce tutte le informazioni salvate con l'ambito fornito, indipendentemente dalla loro similarità con la conversazione corrente.

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."
      }
    ),
]
"""

Sostituisci quanto segue:

  • SCOPE: un dizionario che rappresenta l'ambito del recupero. Ad esempio, {"user_id": "123"}. Vengono restituite solo le informazioni salvate con lo stesso ambito della richiesta.

Elenca informazioni salvate

Utilizza ListMemories per recuperare le informazioni salvate da Memory Bank senza filtri basati sull'ambito. Per il recupero basato sull'ambito, utilizza invece RetrieveMemories. ListMemories non è consigliato per il recupero a bassa latenza.

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

Filtra informazioni salvate

Questa sezione descrive come utilizzare i filtri per limitare le informazioni salvate recuperate. Puoi filtrare in base a:

  • Metadati utilizzando l'attributo filter_groups per il recupero basato sull'ambito.

  • Campi di sistema utilizzando filter. I campi di sistema includono topics, create_time, update_time e fact delle informazioni salvate.

Il filtro dei metadati e dei campi di sistema può essere utilizzato nella stessa richiesta.

Filtra per metadati

Quando crei, aggiorni o generi informazioni salvate, puoi applicare metadati strutturati alle informazioni salvate memorizzate:

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

Puoi filtrare questi metadati quando recuperi le informazioni salvate utilizzando l'attributo filter_groups. I filtri dei metadati sono definiti in forma normale disgiuntiva (DNF), ovvero un' espressione logica di OR di AND.

Ad esempio, la seguente richiesta recupererà le informazioni salvate che includono i metadati ({"my_string_key": {"string_value": "my_value"}} AND {"my_double_key": {"double": 1.23}}) OR {"my_string_key": {"string_value": "other"}}.

Dizionario

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"}
          }
        ]
      }
    ]
  }
)

Basato sulla 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")
          )
        ]
      )
    ]
  )
)

Filtra per campi di sistema

Puoi filtrare i campi di sistema utilizzando l'attributo filter, che prevede un valore stringa che utilizza la sintassi EBNF. I campi di sistema includono create_time, update_time, fact, e topics.

La sintassi EBNF prevede i seguenti requisiti per la creazione di una stringa di filtro:

  • Per combinare i filtri, utilizza AND e OR.
  • La stringa deve utilizzare le virgolette doppie ".
  • I campi data/ora (come create_time) utilizzano una stringa tra virgolette doppie che rappresenta la data/ora ISO 8601 o un campo numerico che rappresenta i microsecondi dall'epoca Unix.

Ad esempio, il seguente filtro può essere utilizzato per recuperare le informazioni salvate in cui fact include la sottostringa "allergies" e update_time è successiva al 1° gennaio 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}
)

Filtra per argomenti

Le informazioni salvate generate vengono etichettate automaticamente con l'argomento pertinente della memoria topic.

Per filtrare gli argomenti gestiti, utilizza topics.managed_memory_topic come nome del campo e il valore ManagedTopicEnum previsto, ad esempio topics.managed_memory_topic: USER_PREFERENCES.

Per filtrare gli argomenti personalizzati, utilizza topics.custom_memory_topic_label come nome del campo e l'etichetta dell'argomento previsto come valore, ad esempio 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}
)