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.
Create
agent_engine = client.agent_engines.create()
Use existing
agent_engine = client.agent_engines.get(name="AGENT_ENGINE_NAME")
Replace the following:
- AGENT_ENGINE_NAME: The name of the Agent Engine. It should be in the format
projects/.../locations/.../reasoningEngines/...
. You can only use Agent Engine instances inus-central1
for Vertex AI Agent Engine 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:
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.