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.

Set up your environment

Before you get started, you need to setup your environment and Agent Engine instance. This section presumes that you have set up a Python development environment, or are using a runtime with a Python development environment (such as Colab).

Import libraries

Install the Vertex AI SDK:

  pip install google-cloud-aiplatform>=1.100.0

Set up a Vertex AI SDK client

  import vertexai

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

Replace the following:

• PROJECT_ID: Your project ID.
• LOCATION: Your region. Only us-central1 is supported for Vertex AI Agent Engine Memory Bank.

Configure your Agent Engine instance

To fetch memories from Memory Bank, you first need an instance of an Agent Engine. You can either create a new instance or get an existing instance. New Agent Engine instances are empty unless you first create or generate memories.

agent_engine = client.agent_engines.create()

agent_engine = client.agent_engines.get(name="AGENT_ENGINE_NAME")

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:

• Retrieve memories using similarity search
• Retrieve all memories

Retrieve memories using similarity search

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.