Fetch memories

This page describes how to fetch generated and uploaded memories from Memory Bank. For the entire workflow of configuring, generating, and using Memory Bank, see the Quickstart with REST API.

You have the following options to fetch generated memories:

  • Get memory: Get the full content of a single memory.

  • List memories: List memories

  • Retrieve memories: Retrieve memories using scope-based memory retrieval. Retrieve memories using similarity search or all memories within the scope.

Before you begin

To complete the steps demonstrated in this page, you must first follow the steps in Set up for Memory Bank.

Get memory

Use GetMemories to get the full content of a single memory:

memory = client.agent_engines.get_memory(name="MEMORY_NAME")

Replace the following:

  • MEMORY_NAME: A fully-qualified memory name in the format "projects/.../locations/.../reasoningEngines/.../memories...".

List memories

Use ListMemories to fetch all memories in your Memory Bank.

pager = client.agent_engines.list_memories(name=agent_engine.api_resource.name)
for page in pager:
  print(page)

Fetch memories using scope-based retrieval

You can use RetrieveMemories to retrieve memories for a particular scope. Only memories that have the exact same scope (independent of order) as the retrieval request are returned. For example, you can retrieve all memories that are scoped to a particular user by using {"user_id": "123"}. If no memories are returned, Memory Bank doesn't have any memories for the provided scope.

A memory's scope is defined when the memory is generated or created and is immutable.

You can use RetrieveMemories to perform the following operations for a particular scope:

For cases where you have many memories for a particular scope, you can use similarity search to retrieve only the most similar memories by providing similarity search parameters. Memory Bank only considers memories that have exactly the same scope as the request when performing similarity search. Similarity search compares the embedding vectors between memories' facts and the request's search query.

Returned memories are sorted from most similar (shortest Euclidean distance) to least similar (greatest Euclidean distance):

results = client.agent_engines.retrieve_memories(
    name=agent_engine.api_resource.name,
    scope=SCOPE,
    similarity_search_params={
        "search_query": "QUERY",
        # Optional. Defaults to 3.
        "top_k": 3
    }
)
# RetrieveMemories returns a pager. You can use `list` to retrieve all memories.
list(results)

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

Replace the following:

  • QUERY: The query for which to perform similarity search. For example, you can use the last user turn of the conversation as the query.

  • SCOPE: A dictionary, representing the scope for the similarity search. For example, {"user_id": "123"}. Only memories with the same scope as the request are considered.

Retrieve all memories

If no similarity search parameters are provided, RetrieveMemories returns all memories that have the provided scope, regardless of their similarity with the current conversation.

results = client.agent_engines.retrieve_memories(
    name=agent_engine.api_resource.name,
    scope=SCOPE
)
# RetrieveMemories returns a pager. You can use `list` to retrieve all pages' memories.
list(results)

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

Replace the following:

  • SCOPE: A dictionary representing the scope for retrieval. For example, {"user_id": "123"}. Only memories with the same scope as the request are returned.