Use Memory Bank with ADK

The Agent Development Kit (ADK) connects agents to Agent Platform Memory Bank through VertexAiMemoryBankService, an implementation of the ADK BaseMemoryService interface. This document explains how to choose a memory callback and retrieval tool, and how to connect the memory service in each ADK runtime.

To run a complete example first, see the Memory Bank quickstart with ADK.

Before you begin

  1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.
  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  3. If you're using an existing project for this guide, verify that you have the permissions required to complete this guide. If you created a new project, then you already have the required permissions.

  4. Verify that billing is enabled for your Google Cloud project.

  5. Enable the Agent Platform API, if it is not already enabled.

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

    Enable the API

  6. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  7. If you're using an existing project for this guide, verify that you have the permissions required to complete this guide. If you created a new project, then you already have the required permissions.

  8. Verify that billing is enabled for your Google Cloud project.

  9. Enable the Agent Platform API, if it is not already enabled.

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

    Enable the API

  10. If you're using a local shell, then create local authentication credentials for your user account:

    gcloud auth application-default login

    You don't need to do this if you're using Cloud Shell.

    If an authentication error is returned, and you are using an external identity provider (IdP), confirm that you have signed in to the gcloud CLI with your federated identity.

  11. Install ADK and the Agent Platform SDK:
    pip install --upgrade "google-adk[gcp]" "google-cloud-agentplatform>=2.0.1"
  12. Create a Memory Bank instance in the Google Cloud console or with the Agent Platform SDK. On the Memory Bank page, click Link to an agent > Use with ADK for prefilled setup code. Skip this step if Agent Runtime creates the instance for you.

Required roles

To get the permissions that you need to create a Memory Bank instance and generate and retrieve memories, ask your administrator to grant you the following IAM roles on your project:

  • Create or update a Memory Bank instance: Agent Platform User (`roles/aiplatform.user`)
  • Read, write, or generate memories: Memory Bank User (`roles/aiplatform.memoryUser`)

For more information about granting roles, see Manage access to projects, folders, and organizations.

You might also be able to get the required permissions through custom roles or other predefined roles.

How ADK components work with Memory Bank

An ADK agent uses the following components to read and write memories:

Component Role Required
Memory Bank instance Stores and consolidates memories. Yes
VertexAiMemoryBankService Connects your agent to Memory Bank as the ADK memory service. Yes
Session service Stores conversation history. You can use any ADK session service. Yes
Memory retrieval tool Retrieves memories for the agent. See Retrieve memories with a tool. To read memories
Memory generation callback Sends conversation events to Memory Bank after the agent responds. See Generate memories with a callback. To write memories
ADK Runner or AdkApp Orchestrates the agent, services, tools, and callbacks. Yes

The following diagram shows how these components interact on each turn when an agent uses PreloadMemoryTool and a memory callback:

Memory Bank scopes each memory to the user ID and app name that run your agent, as {"user_id": USER_ID, "app_name": APP_NAME}. Only requests with the same user ID and app name retrieve those memories.

Generate memories with a callback

A memory generation callback sends conversation events to Memory Bank. Memory Bank extracts memories from those events and consolidates them with existing memories. Choose a method based on how often you process events:

Method Events sent When to use
callback_context.add_events_to_memory A subset of events that you select Recommended. Process events incrementally, for example after each turn.
callback_context.add_session_to_memory All events in the session Call once at the end of a session, so that the same events aren't processed more than once.

The following example sends recent events after each agent response:

from google.adk.agents.callback_context import CallbackContext


async def generate_memories_callback(
    callback_context: CallbackContext,
) -> None:
    await callback_context.add_events_to_memory(
        events=callback_context.session.events[-5:]
    )
    return None

To send the full session instead, call await callback_context.add_session_to_memory() in a callback at the end of the session.

By default, VertexAiMemoryBankService sends events by using event ingestion. To wait until memory generation finishes in tests or demos, pass custom_metadata={"wait_for_completion": True} to add_events_to_memory.

Retrieve memories with a tool

A memory retrieval tool controls when the agent retrieves memories and how the memories enter the prompt. Choose one of the following tools:

Tool When memories are retrieved When to use
PreloadMemoryTool At the start of every turn. Memories are injected into the model request context before the current user turn. Establish baseline context about the user on every turn.
LoadMemoryTool When the model decides that memories are necessary to answer the query. Let the model decide when memories are relevant.
Custom FunctionTool When the model calls your tool, guided by the tool's description. Give the agent instructions about when to retrieve memories.

The following example creates an agent that uses PreloadMemoryTool and the callback from the preceding section:

from google import adk
from google.adk.tools.preload_memory_tool import PreloadMemoryTool

agent = adk.Agent(
    model="gemini-3.5-flash",
    name="stateful_agent",
    instruction="You are a vehicle voice agent. Limit responses to 30 words.",
    tools=[PreloadMemoryTool()],
    after_agent_callback=generate_memories_callback,
)

To let the model decide when to retrieve memories, import LoadMemoryTool from google.adk.tools.load_memory_tool and pass LoadMemoryTool() in tools.

To write a custom retrieval tool, call tool_context.search_memory from a function tool:

from typing import Any

from google import adk
from google.adk.tools import FunctionTool, ToolContext


async def search_memories(query: str, tool_context: ToolContext) -> Any:
    """Query this tool when you need information about user preferences."""
    return await tool_context.search_memory(query)


agent = adk.Agent(
    model="gemini-3.5-flash",
    name="stateful_agent",
    instruction=(
        "You are a vehicle voice agent. Before you change a setting, call "
        "search_memories to look up the user's preferences. Limit responses "
        "to 30 words."
    ),
    tools=[FunctionTool(func=search_memories)],
    after_agent_callback=generate_memories_callback,
)

Connect the memory service to your runtime

How you connect VertexAiMemoryBankService depends on where your agent runs. Select your runtime:

Local runner

When you run your agent with adk.Runner, create the memory service and pass it to the runner:

import asyncio
import os

from google import adk
from google.adk.memory import VertexAiMemoryBankService
from google.adk.sessions import InMemorySessionService
from google.genai import types

os.environ["GOOGLE_GENAI_USE_ENTERPRISE"] = "TRUE"
os.environ["GOOGLE_CLOUD_PROJECT"] = "PROJECT_ID"
os.environ["GOOGLE_CLOUD_LOCATION"] = "LOCATION"

memory_service = VertexAiMemoryBankService(
    project="PROJECT_ID",
    location="LOCATION",
    agent_engine_id="MEMORY_BANK_ID",
)

# You can use any ADK session service. This example keeps sessions in memory.
# To persist conversation history, use VertexAiSessionService with a
# Sessions instance instead.
session_service = InMemorySessionService()

runner = adk.Runner(
    agent=agent,
    app_name="APP_NAME",
    session_service=session_service,
    memory_service=memory_service,
)

async def main() -> None:
    session = await session_service.create_session(
        app_name="APP_NAME",
        user_id="USER_ID",
    )
    message = types.Content(
        role="user", parts=[types.Part(text="Can you fix the temperature?")]
    )
    async for event in runner.run_async(
        user_id="USER_ID",
        session_id=session.id,
        new_message=message,
    ):
        if event.is_final_response() and event.content:
            print(event.content.parts[0].text)

asyncio.run(main())

Replace the following:

  • PROJECT_ID: Your Google Cloud project ID, for example my-project.
  • LOCATION: Your location, for example global. See the supported locations and global and multi-regional endpoints for Memory Bank.
  • MEMORY_BANK_ID: The Memory Bank instance ID, for example 456 in projects/my-project/locations/us-central1/reasoningEngines/456.
  • APP_NAME: The ADK app name, for example my_agent. Memory Bank includes the app name in the memory scope, so memories are isolated across apps.
  • USER_ID: An identifier for your user, for example user-123. Memories generated from this session are scoped to this identifier.

Agent Runtime on Gemini Enterprise Agent Platform

When you deploy an ADK agent to Agent Runtime with the ADK template (AdkApp), the template uses VertexAiMemoryBankService by default. You can create the Memory Bank instance and deploy the agent in one step:

import asyncio

import agentplatform
from agentplatform.frameworks import AdkApp

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

adk_app = AdkApp(agent=agent)

# Create a resource with your agent deployed to Agent Runtime. The
# resource also includes an empty Memory Bank instance.
runtime_instance = client.runtimes.create(
    agent=adk_app,
    config={
        "staging_bucket": "STAGING_BUCKET",
        "requirements": ["google-cloud-agentplatform[runtimes,adk]"],
    },
)

async def main() -> None:
    session = await runtime_instance.async_create_session(
        user_id="USER_ID"
    )
    async for event in runtime_instance.async_stream_query(
        user_id="USER_ID",
        session_id=session.get("id"),
        message="Can you fix the temperature?",
    ):
        print(event)

asyncio.run(main())

To deploy the agent to an existing resource and keep the resource's existing memories, call client.runtimes.update instead:

runtime_instance = client.runtimes.update(
    name="RUNTIME_NAME",
    agent=adk_app,
    config={
        "staging_bucket": "STAGING_BUCKET",
        "requirements": ["google-cloud-agentplatform[runtimes,adk]"],
    },
)

When you run AdkApp locally, it uses InMemoryMemoryService by default. To use Memory Bank locally, override the memory service:

from google.adk.memory import VertexAiMemoryBankService

def memory_bank_service_builder() -> VertexAiMemoryBankService:
    return VertexAiMemoryBankService(
        project="PROJECT_ID",
        location="LOCATION",
        agent_engine_id="MEMORY_BANK_ID",
    )

adk_app = AdkApp(
    agent=agent,
    memory_service_builder=memory_bank_service_builder,
)

Replace the following:

  • PROJECT_ID: Your Google Cloud project ID, for example my-project.
  • LOCATION: Your Agent Runtime region or multi-region, for example us-central1. Only standalone VertexAiMemoryBankService instances support global, not client.runtimes.create. See supported locations.
  • STAGING_BUCKET: The Cloud Storage bucket URI for staging your Agent Runtime, for example gs://my-staging-bucket.
  • USER_ID: An identifier for your user, for example user-123.
  • RUNTIME_NAME: The resource name of the existing Agent Runtime, in the format projects/.../locations/.../reasoningEngines/....
  • MEMORY_BANK_ID: The Memory Bank instance ID, for example 456 in projects/my-project/locations/us-central1/reasoningEngines/456.

Cloud Run

To deploy your agent to Cloud Run, follow the ADK documentation and pass your Memory Bank instance as the memory service:

adk deploy cloud_run \
    ...
    --memory_service_uri=agentengine://MEMORY_BANK_ID

Replace MEMORY_BANK_ID with your Memory Bank instance ID, for example 456. To test the deployed agent, see the ADK Cloud Run deployment documentation.

Google Kubernetes Engine (GKE)

To deploy your agent to GKE, follow the ADK documentation and pass your Memory Bank instance as the memory service:

adk deploy gke \
    ...
    --memory_service_uri=agentengine://MEMORY_BANK_ID

Replace MEMORY_BANK_ID with your Memory Bank instance ID, for example 456. To test the deployed agent, see the Testing your agent section of the ADK GKE deployment documentation.

ADK Web

ADK Web is a local browser interface for testing and inspecting your agent during development.

ADK Web reads your project and location from environment variables. Run the following commands in your terminal, from the directory that contains your agent folder:

export GOOGLE_GENAI_USE_ENTERPRISE=TRUE
export GOOGLE_CLOUD_PROJECT=PROJECT_ID
export GOOGLE_CLOUD_LOCATION=LOCATION
adk web --memory_service_uri=agentengine://MEMORY_BANK_ID

Replace the following:

Then open http://localhost:8000 in your browser. By default, ADK Web sets the user ID to user. To use a different user ID, add the userId query parameter, for example http://localhost:8000?userId=USER_ID.

Use a multi-regional Memory Bank with a regional runtime

By default, when you use Runtime with built-in Memory Bank, your agent and Memory Bank are deployed in the same region. To maintain one central Memory Bank across regional deployments, you can pair a multi-regional Memory Bank (such as us) with a regional runtime (such as us-central1).

To use a multi-regional Memory Bank, override the default ADK memory service builder so that it points to the multi-region location and instance ID:

import agentplatform
from agentplatform.frameworks import AdkApp
from google.adk.memory import VertexAiMemoryBankService

# Create the Memory Bank instance in a multi-region location.
client_mb = agentplatform.Client(
    project="PROJECT_ID",
    location="us",
)
memory_bank = client_mb.memory_banks.create()
memory_bank_id = memory_bank.name.split("/")[-1]


# Point the memory service to the multi-regional instance.
def memory_bank_service_builder() -> VertexAiMemoryBankService:
    return VertexAiMemoryBankService(
        project="PROJECT_ID",
        location="us",
        agent_engine_id=memory_bank_id,
    )


adk_app = AdkApp(
    agent=agent,
    memory_service_builder=memory_bank_service_builder,
)

# Deploy the runtime to a specific region.
client_runtime = agentplatform.Client(
    project="PROJECT_ID",
    location="us-central1",
)
runtime_instance = client_runtime.runtimes.create(
    agent=adk_app,
    config={
        "staging_bucket": "STAGING_BUCKET",
        "requirements": ["google-cloud-agentplatform[runtimes,adk]"],
    },
)

Replace the following:

  • PROJECT_ID: Your Google Cloud project ID, for example my-project.
  • STAGING_BUCKET: The Cloud Storage bucket URI for staging your Agent Runtime, for example gs://my-staging-bucket.

To delete these resources, delete the runtime and the multi-regional instance. If you delete an instance right after a conversation, the request can fail with a FAILED_PRECONDITION error while memory generation finishes. If that happens, wait a minute and run the deletion again.

client_runtime.runtimes.delete(
    name=runtime_instance.api_resource.name,
    force=True,
)
client_mb.memory_banks.delete(name=memory_bank.name, force=True)

What's next

Quickstart

Build an ADK agent that recalls user preferences.

Guide

Learn how to generate memories in Memory Bank.

Guide

Learn how to set up Memory Bank.