Set up Memory Bank

To use Agent Platform Memory Bank, you must first create and configure a Memory Bank instance. This instance manages your memories and can be integrated with your agents across various runtimes.

This document explains how to set up your Google Cloud project, install the required libraries, and create or update an instance with custom configurations like topics and TTL.

Get started

Before you work with Memory Bank, you must set up your environment.

Set up your Google Cloud project

Every project can be identified in two ways: the project number or the project ID. The PROJECT_NUMBER is automatically created when you create the project, whereas the PROJECT_ID is created by you, or whoever created the project. To set up a project:

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.

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

Verify that billing is enabled for your Google Cloud project.

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

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

Verify that billing is enabled for your Google Cloud project.

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

Get the required permissions

To get the permissions that you need to use Memory Bank, 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.

If you're making requests to Memory Bank from an agent deployed on Google Kubernetes Engine (GKE) or Cloud Run, make sure that your service account has the necessary permissions to read, write or generate memories. The Reasoning Engine Service Agent already has the necessary permissions to read, write, and generate memories, so outbound requests from Agent Runtime should already have permission to access Memory Bank.

Install libraries

This section assumes that you have set up a Python development environment, or are using a runtime with a Python development environment (such as Colaboratory).

Install the Agent Platform SDK:

pip install google-cloud-agentplatform>=2.0.1

Authentication

Follow the instructions at Authenticate to Gemini Enterprise Agent Platform.

Set up a Agent Platform SDK client

Run the following code to set up a Agent Platform SDK client:

import agentplatform

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

Multi-regional and global endpoints

Memory Bank supports multi-regional and global endpoints:

• For global instances, set your location to global.
• For multi-regional instances, set your location to us or eu.

Create or update a Memory Bank instance

To get started with Memory Bank, you first need a Memory Bank instance. If you don't already have an instance, you can create one using the default configuration, and a display name of your choosing.

# create the resource
memory_bank = client.memory_banks.create(
    config={
        "display_name": "My Memory Bank",
    }
)

# Optionally, print out the Memory Bank resource name. You will need the
# resource name to interact with your Memory Bank instance later on.
print(memory_bank.name)

If you want to customize the configuration of your new or existing Memory Bank instance's behavior, refer to Configure your Memory Bank instance. For example, you can specify what information Memory Bank considers meaningful to persist.

Once you have a Memory Bank instance, you can use the name of the instance to read or write memories. For example:

# Generate memories using your Memory Bank instance.
client.memory_banks.memories.generate(
  # `name` should have the format `projects/.../locations/.../reasoningEngines/...`.
  name=memory_bank.name,
  ...
)

Use with Agent Runtime

Although Memory Bank can be used in any runtime, you can also use Memory Bank with Agent Runtime to read and write memories from your deployed agent.

To deploy an agent on Agent Runtime with built-in Memory Bank, first set up your environment for Agent Runtime. Then, prepare your agent to be deployed on Agent Runtime with memory integration. Your deployed agent should make calls to read and write memories as needed.

from google.adk.agents import Agent
from agentplatform.frameworks import AdkApp

# Develop an agent using the ADK template.
agent = Agent(...)

adk_app = AdkApp(
      agent=adk_agent,
      ...
)

# Deploy the agent to Agent Runtime.
runtime = client.runtimes.create(
      agent=adk_app,
      config={
            "staging_bucket": "STAGING_BUCKET",
            "requirements": ["google-cloud-agentplatform[runtimes,adk]"],
            # Optional.
            **context_spec
      }
)

# Update an existing Agent Runtime to add or modify the Runtime.
runtime = client.runtimes.update(
      name=runtime.api_resource.name,
      agent=adk_app,
      config={
            "staging_bucket": "STAGING_BUCKET",
            "requirements": ["google-cloud-agentplatform[runtimes,adk]"],
            # Optional.
            **context_spec
      }
)

Your application deployed to Agent Runtime can read the environment variables GOOGLE_CLOUD_PROJECT, GOOGLE_CLOUD_LOCATION,GOOGLE_CLOUD_AGENT_ENGINE_ID to infer the Agent Runtime name from the environment:

project = os.environ.get("GOOGLE_CLOUD_PROJECT")
location = os.environ.get("GOOGLE_CLOUD_LOCATION")
agent_engine_id = os.environ.get("GOOGLE_CLOUD_AGENT_ENGINE_ID")

agent_engine_name = f"projects/{project}/locations/{location}/reasoningEngines/{agent_engine_id}"

If you're using the default service agent for your agent on Agent Runtime, your agent already has permission to read and write memories. If you're using a customer service account, you need to grant permissions to your service account to read and write memories. The required permissions depend on what operations your agent should be able to perform. If you only want your agent to retrieve and generate memories, aiplatform.memories.generate and aiplatform.memories.retrieve are sufficient.

Use in all other runtimes

If you want to use Memory Bank in a different environment, like Cloud Run or Colab, create a Memory Bank. If you don't provide a configuration, Memory Bank is created with the default settings for managing memory generation and retrieval.

memory_bank = client.memory_banks.create()

If you've used Memory Bank before, creating a new Memory Bank instance should only take a few seconds. If this is the first time you're using Memory Bank, it may take longer (1-2 minutes).

If you want to configure behavior, provide a Memory Bank configuration:

memory_bank = client.memory_banks.create(
  managed_semantic_memory_config={
    "generation_config": ...,
    "unstructured_memory_configs": [...],
    "structured_memory_configs": [...],
    "similarity_search_config": ...,
    "ttl_config": ...,
    "disable_memory_revisions": False,
  }
)

memory_bank = client.runtimes.update(
  # You can access the name using `memory_bank.name` for a MemoryBank object.
  name="MEMORY_BANK_NAME",
  config={
    "context_spec": {
      "memory_bank_config": {
        "generation_config": ...,
        "customization_configs": [...],
        "structured_memory_configs": [...],
        "similarity_search_config": ...,
        "ttl_config": ...,
        "disable_memory_revisions": False,
      }
    }
  }
)

You can use Memory Bank in any environment that has permission to read and write memories. For example, to use Memory Bank with Cloud Run, grant permissions to the Cloud Run service identity to read and write memories. The required permissions depend on what operations your agent should be able to perform. If you only want your agent to retrieve and generate memories, aiplatform.memories.generate and aiplatform.memories.retrieve are sufficient.

Configure your Memory Bank instance

You can configure your Memory Bank to customize how memories are generated and managed. If you don't provide the configuration, then Memory Bank uses the default settings for each type of configuration.

You can configure the following Memory Bank settings for your instance:

• Customization configuration (unstructured_memory_configs): Configures how memories are extracted from source data and consolidated with existing memories.
• Similarity search configuration: Specifies which embedding model Memory Bank uses for similarity search. Defaults to text-embedding-005.
• Generation configuration: Configures which LLM Memory Bank uses for memory generation. Defaults to gemini-3.5-flash.
• TTL configuration: Configures how TTL is automatically set for created or updated memories. Defaults to no TTL.

The following sample shows the default Memory Bank:

managed_semantic_memory_config = {
  "generation_config": {
    # `gemini-3.5-flash` will be used to extract and consolidate memories.
    "model": "projects/{PROJECT}/locations/{LOCATION}/publishers/google/models/gemini-3.5-flash"
  },
  "similarity_search_config": {
    # `text-embedding-005` will be used for similarity search, including
    # during consolidation. Consolidation uses similarity search to find
    # candidate memories that may be updated with new information.
    "embedding_model": "projects/{PROJECT}/locations/{LOCATION}/publishers/google/models/text-embedding-005"
  },
  "ttl_config": {
    # Default TTL for memory revisions is 365 days.
    "memory_revision_default_ttl": f"{365 * 24 * 60 * 60}s"
  },
  "unstructured_memory_configs": [
    {
      # Extract user information, preferences, key conversation details,
      # and information that the user explicitly asked to be remembered.
      "memory_topics": [
        {"managed_memory_topic": {"managed_topic_enum": "USER_PERSONAL_INFO"}},
        {"managed_memory_topic": {"managed_topic_enum": "USER_PREFERENCES"}},
        {"managed_memory_topic": {"managed_topic_enum": "KEY_CONVERSATION_DETAILS"}},
        {"managed_memory_topic": {"managed_topic_enum": "EXPLICIT_INSTRUCTIONS"}}
      ],
      "consolidation_config": {
        # Only use the latest memory revision of each candidate memory during
        # consolidation.
        "revisions_per_candidate_count": 1
      },
      # Only use the pre-defined set of examples.
      "generate_memories_examples": [],
      # Generate memories in the first person.
      "enable_third_person_memories": False
    }
  ],
  # Memory revisions will be persisted. This can be overridden on a request-level.
  "disable_memory_revisions": False
}

from agentplatform.types import ManagedSemanticMemoryConfig
from agentplatform.types import ManagedSemanticMemoryConfigGenerationConfig as GenerationConfig
from agentplatform.types import ManagedSemanticMemoryConfigSimilaritySearchConfig as SimilaritySearchConfig
from agentplatform.types import ManagedSemanticMemoryConfigTtlConfig as TtlConfig
from agentplatform.types import ManagedTopicEnum
from agentplatform.types import MemoryBankCustomizationConfig as CustomizationConfig
from agentplatform.types import MemoryBankCustomizationConfigConsolidationConfig as ConsolidationConfig
from agentplatform.types import MemoryBankCustomizationConfigMemoryTopic as