Generative AI Google Brain

agents-agent-engine-memory-bank-get-started-with-memory-bank-on-adk

4 min read

Get started with Memory Bank on ADK

Source notebook

Repo path: agents/agent_engine/memory_bank/get_started_with_memory_bank_on_adk.ipynb · Open on GitHub · advanced

Build ADK agents that generate, retrieve, preload, and customize Agent Engine Memory Bank memories.

Summary

This notebook teaches how ADK memory services work with a simple Gemini-backed LlmAgent. It compares InMemoryMemoryService with VertexAiMemoryBankService, generates memories from sessions and event slices, retrieves them through ADK and the Agent Engine SDK, and wires memory into agents with PreloadMemoryTool, LoadMemoryTool, and callbacks. It also shows Memory Bank customization with managed topics, custom topics, and TTL settings, then deletes the Agent Engine resource.

Key code patterns

Initialize Vertex AI and ADK env

PROJECT = os.environ.get("GOOGLE_CLOUD_PROJECT")
LOCATION = os.environ.get("GOOGLE_CLOUD_REGION", "us-central1")
client = vertexai.Client(project=PROJECT, location=LOCATION)
os.environ["GOOGLE_GENAI_USE_VERTEXAI"] = "TRUE"
os.environ["GOOGLE_CLOUD_PROJECT"] = PROJECT
os.environ["GOOGLE_CLOUD_LOCATION"] = LOCATION

ADK is configured to use Vertex AI for Gemini calls in the selected project and region.

Create ADK runner

agent = LlmAgent(
    model="gemini-2.5-flash",
    name="Generic_QA_Agent",
    instruction="Answer the user's questions",
)
session_service = InMemorySessionService()
runner = Runner(agent=agent, app_name=APP_NAME, session_service=session_service)

The Runner binds the agent to an app name and session service that stores conversation history.

Create Memory Bank service

agent_engine = client.agent_engines.create(config={
    "context_spec": {"memory_bank_config": {"generation_config": {
        "model": f"projects/{PROJECT}/locations/{LOCATION}/publishers/google/models/gemini-2.5-flash"
    }}}
})
memory_bank_service = VertexAiMemoryBankService(
    agent_engine_id=agent_engine.api_resource.name.split("/")[-1],
    project=PROJECT,
    location=LOCATION,
)

VertexAiMemoryBankService connects ADK memory APIs to an Agent Engine Memory Bank instance.

Incremental memory generation

await memory_bank_service.add_events_to_memory(
    app_name=APP_NAME,
    user_id=USER_ID,
    events=recommendations_session.events,
)
await memory_bank_service.search_memory(
    app_name=APP_NAME,
    user_id=USER_ID,
    query="What should I get my mom for mother's day",
)

add_events_to_memory streams selected events and avoids repeatedly processing the full session.

Retrieve with Agent Engine SDK

response = client.agent_engines.memories.retrieve(
    name=agent_engine.api_resource.name,
    scope={"app_name": APP_NAME, "user_id": USER_ID},
    similarity_search_params={
        "search_query": "what should I get my niece for her birthday?"
    },
)
list(response)

Direct SDK retrieval can list scoped memories or use similarity search.

Preload memories into prompts

agent = LlmAgent(
    model=MODEL,
    name="Generic_QA_Agent",
    instruction="Answer the user's questions",
    tools=[PreloadMemoryTool()],
)
runner = Runner(
    agent=agent,
    app_name=APP_NAME,
    session_service=session_service,
    memory_service=memory_bank_service,
)

PreloadMemoryTool fetches memories before the model call and appends them to system instructions.

Customize managed topics

user_preferences_config = {
    "scope_keys": ["user_id"],
    "memory_topics": [{"managed_memory_topic": {
        "managed_topic_enum": "USER_PREFERENCES"
    }}],
}
client.agent_engines.update(
    name=agent_engine.api_resource.name,
    config={"context_spec": {"memory_bank_config": {
        "customization_configs": [user_preferences_config]
    }}},
)

Memory Bank extraction can be limited to selected managed memory topics.

Set Memory Bank TTL

client.agent_engines.update(
    name=agent_engine.api_resource.name,
    config={"context_spec": {"memory_bank_config": {
        "ttl_config": {"default_ttl": f"{60 * 60 * 24 * 30}s"}
    }}},
)

TTL configuration controls expiration for generated, created, or updated memories.

Models & APIs used

  • Models: gemini-2.5-flash
  • APIs / services: Vertex AI, Agent Platform API, Agent Engine Memory Bank
  • SDKs / libraries: google-adk, google-cloud-aiplatform, vertexai, google-genai

When to use this

Use this pattern when building ADK agents that need long-term, scoped user memory across sessions on Vertex AI Agent Engine.

Gotchas & caveats

  • Agent Platform API must be enabled for the Google Cloud project.
  • Colab requires auth.authenticate_user(); local development needs Application Default Credentials.
  • ADK uses async APIs; standard Python scripts need async functions and asyncio.run().
  • VertexAiMemoryBankService add_events_to_memory is non-blocking, so memories may not be available immediately.
  • InMemoryMemoryService persists raw dialogue in memory, while VertexAiMemoryBankService only persists meaningful extracted memories.
  • Memory Bank scope dictionaries isolate memories; changing scope keys hides prior memories.
  • Processing entire sessions repeatedly can be costly as session history grows.
  • The notebook uses us-central1 as the default region when GOOGLE_CLOUD_REGION is unset.

Best practices

  • Use add_events_to_memory for production agents to stream recent events incrementally.
  • Use add_session_to_memory at the end of a session when processing the whole session is acceptable.
  • Provide both a memory tool on the Agent and a memory service on the Runner when using built-in ADK memory tools.
  • Use callbacks to automate memory generation after turns.
  • Use Agent Engine SDK generate with wait_for_completion when blocking memory generation is required.
  • Customize memory topics so Memory Bank persists only meaningful information for the application.
  • Configure TTL to avoid retaining memories longer than needed.
  • Delete Agent Engine resources when finished to avoid unexpected costs.

Graph View

Backlinks