Configurar o Memory Bank

Para usar o Memory Bank da Agent Platform, primeiro crie e configure uma instância do Memory Bank. Essa instância gerencia suas memórias e pode ser integrada aos seus agentes em vários tempos de execução.

Este documento explica como configurar seu projeto do Google Cloud , instalar as bibliotecas necessárias e criar ou atualizar uma instância com configurações personalizadas como tópicos e TTL.

Primeiros passos

Antes de trabalhar com o Memory Bank, você precisa configurar seu ambiente.

Configurar o projeto do Google Cloud

Cada projeto pode ser identificado de duas formas: pelo número ou pelo ID. O PROJECT_NUMBER é criado automaticamente quando você cria o projeto, enquanto o PROJECT_ID é criado por você ou por quem criou o projeto. Para configurar um projeto:

  1. Faça login na sua conta do Google Cloud . Se você começou a usar o Google Cloud, crie uma conta para avaliar o desempenho de nossos produtos em situações reais. Clientes novos também recebem US$ 300 em créditos para executar, testar e implantar cargas de trabalho.

  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. Verify that billing is enabled for your Google Cloud project.

  4. Enable the Agent Platform API.

    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

  5. 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

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

  7. Enable the Agent Platform API.

    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

    8.

Ter os papéis necessários

Para receber as permissões necessárias a fim de usar o Banco de memória, peça que o admin conceda a você os seguintes papéis do IAM no projeto:

Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Também é possível conseguir as permissões necessárias usando papéis personalizados ou outros papéis predefinidos.

Se você estiver fazendo solicitações ao Memory Bank de um agente implantado no Google Kubernetes Engine (GKE) ou no Cloud Run, verifique se a conta de serviço tem as permissões necessárias. O agente de serviço do Reasoning Engine Service já tem as permissões necessárias para ler e gravar memórias. Portanto, as solicitações de saída do Agent Runtime já têm permissão para acessar o Memory Bank.

Instalar bibliotecas

Nesta seção, pressupomos que você configurou um ambiente de desenvolvimento em Python ou está usando um ambiente de execução com um ambiente de desenvolvimento em Python (como o Colaboratory).

Instale o SDK da Agent Platform:

pip install google-cloud-aiplatform>=1.111.0

Autenticação

Siga as instruções em Autenticar na Vertex AI.

Configurar um cliente do SDK da Agent Platform

Execute o código a seguir para configurar um cliente do SDK da Agent Platform:

SDK do Agent Platform 

import vertexai

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

em que

Endpoints globais e multirregionais

O Memory Bank é compatível com endpoints multirregionais e globais:

  • Para instâncias globais, defina o local como global.
  • Para instâncias multirregionais, defina o local como us ou eu.

Criar ou atualizar uma instância do Memory Bank

Para começar a usar o Memory Bank, primeiro você precisa de uma instância dele. Se você ainda não tiver uma instância, crie uma usando a configuração padrão e um nome de exibição de sua escolha.

# create the resource
memory_bank = client.agent_engines.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.api_resource.name)

Se quiser personalizar o comportamento da configuração da sua instância do Memory Bank nova ou atual, consulte Configurar sua instância do Memory Bank. Por exemplo, você pode especificar quais informações o Memory Bank considera significativas para manter.

Depois de ter uma instância do Memory Bank, use o nome dela para ler ou gravar memórias. Por exemplo:

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

Usar com o Agent Runtime

Embora o Memory Bank possa ser usado em qualquer ambiente de execução, também é possível usar o Memory Bank com o Agent Runtime para ler e gravar memórias do agente implantado.

Para implantar um agente no Agent Runtime com o Memory Bank integrado, primeiro configure seu ambiente para o Agent Runtime. Em seguida, prepare seu agente para ser implantado no Agent Runtime com integração de memória. O agente implantado precisa fazer chamadas para ler e gravar memórias conforme necessário.

AdkApp

Se você estiver usando o modelo do Kit de Desenvolvimento de Agente (ADK) da Agent Platform, o agente usará o VertexAiMemoryBankService por padrão quando for implantado no Agent Runtime. Isso significa que as ferramentas de memória do ADK leem memórias do Memory Bank.

from google.adk.agents import Agent
from vertexai.preview.reasoning_engines 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.agent_engines.create(
      agent_engine=adk_app,
      config={
            "staging_bucket": "STAGING_BUCKET",
            "requirements": ["google-cloud-aiplatform[agent_engines,adk]"],
            # Optional.
            **context_spec
      }
)

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

Substitua:

  • STAGING_BUCKET: o bucket do Cloud Storage que você vai usar para organizar o Agent Runtime.

Para mais informações sobre como usar o Memory Bank com o ADK, consulte o Guia de início rápido com o ADK.

Agente personalizado

Você pode usar o Memory Bank com seu agente personalizado implantado no Agent Runtime. Nesse caso, o agente precisa orquestrar chamadas ao Memory Bank para acionar geração de memória e recuperação de memória chamadas.

O aplicativo implantado no Agent Runtime pode ler as variáveis de ambiente GOOGLE_CLOUD_PROJECT, GOOGLE_CLOUD_LOCATION e GOOGLE_CLOUD_AGENT_ENGINE_ID para inferir o nome do Agent Runtime do ambiente:

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}"

Se você estiver usando o agente de serviço padrão para seu agente no Agent Runtime, ele já terá permissão para ler e gravar memórias. Se você estiver usando uma conta de serviço do cliente, precisará conceder permissões à sua conta de serviço para ler e gravar memórias. As permissões necessárias dependem das operações que o agente precisa realizar. Se você quiser que o agente apenas recupere e gere recordações, aiplatform.memories.generate e aiplatform.memories.retrieve são suficientes.

Uso em todos os outros ambientes de execução

Se você quiser usar o Memory Bank em um ambiente diferente, como Cloud Run ou Colab, crie um Memory Bank. Se você não fornecer uma configuração, o Memory Bank será criado com as configurações padrão para gerenciar a geração de dados de memória e a recuperação.

memory_bank = client.agent_engines.create()

Se você já usou o Memory Bank, criar uma nova instância leva apenas alguns segundos. Se esta for a primeira vez que você usa o Memory Bank, pode levar mais tempo (1 a 2 minutos).

Se você quiser configurar o comportamento, forneça uma configuração do Memory Bank:

Criar

memory_bank = client.agent_engines.create(
  config={
    "context_spec": {
      "memory_bank_config": ...
    }
  }
)

Atualizar

Se quiser mudar a configuração do Memory Bank, atualize a instância dele.

memory_bank = client.agent_engines.update(
  # You can access the name using `memory_bank.api_resource.name` for an AgentEngine object.
  name="MEMORY_BANK_NAME",
  config={
    "context_spec": {
      "memory_bank_config": ...
    }
  }
)

Substitua:

  • MEMORY_BANK_NAME: o nome do Memory Bank. Ele precisa estar no formato projects/.../locations/.../reasoningEngines/.... Consulte as regiões com suporte para o Memory Bank.

É possível usar o Memory Bank em qualquer ambiente com permissão para ler e gravar recordações. Por exemplo, para usar o Memory Bank com o Cloud Run, conceda permissões à identidade do serviço do Cloud Run para ler e gravar memórias. As permissões necessárias dependem das operações que o agente precisa poder realizar. Se você quiser apenas que o agente recupere e gere memórias, aiplatform.memories.generate e aiplatform.memories.retrieve são suficientes.

Configurar a instância do Memory Bank

Você pode configurar o Memory Bank para personalizar como as memórias são geradas e gerenciadas. Se você não fornecer a configuração, o Memory Bank usará as configurações padrão para cada tipo de configuração.

É possível configurar as seguintes opções do Memory Bank para sua instância:

A amostra a seguir mostra o Memory Bank padrão:

Dicionário

memory_bank_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"
  },
  "customization_configs": [
    {
      # Extract user information, preferences, key conversation details,
      # and information that the user explicitly asked to be remembered.
      "memory_topics": [
        {"managed_memory_topic": "USER_PERSONAL_INFO"},
        {"managed_memory_topic": "USER_PREFERENCES"},
        {"managed_memory_topic": "KEY_CONVERSATION_DETAILS"},
        {"managed_memory_topic": "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
}

Com base em classes

from vertexai.types import MemoryBankCustomizationConfig as CustomizationConfig
from vertexai.types import MemoryBankCustomizationConfigConsolidationConfig as ConsolidationConfig
from vertexai.types import MemoryBankCustomizationConfigMemoryTopic as MemoryTopic
from vertexai.types import MemoryBankCustomizationConfigMemoryTopicManagedMemoryTopic as ManagedMemoryTopic
from vertexai.types import ManagedTopicEnum
from vertexai.types import ReasoningEngineContextSpecMemoryBankConfig as MemoryBankConfig
from vertexai.types import ReasoningEngineContextSpecMemoryBankConfigGenerationConfig as GenerationConfig
from vertexai.types import ReasoningEngineContextSpecMemoryBankConfigSimilaritySearchConfig as SimilaritySearchConfig
from vertexai.types import ReasoningEngineContextSpecMemoryBankConfigTtlConfig as TtlConfig

memory_bank_config = MemoryBankConfig(
  generation_config=GenerationConfig(
    # `gemini-3.5-flash` will be used to extract and consolidate memories.
    # Note: The global endpoint will be used for regions that don't have a
    # regional endpoint available.
    model="projects/{PROJECT}/locations/{LOCATION}/publishers/google/models/gemini-3.5-flash"
  ),
  similarity_search_config=SimilaritySearchConfig(
    # `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=TtlConfig(
    # Default TTL for memory revisions is 365 days.
    memory_revision_default_ttl=f"{365 * 24 * 60 * 60}s"
  ),
  customization_configs=[
    CustomizationConfig(
      # Extract personal information, preferences, key conversation details,
      # and information that the user explicitly asked to be remembered.
      memory_topics=[
        MemoryTopic(
          managed_memory_topic=ManagedMemoryTopic(
            managed_topic_enum=ManagedTopicEnum.USER_PERSONAL_INFO)),
        MemoryTopic(
          managed_memory_topic=ManagedMemoryTopic(
            managed_topic_enum=ManagedTopicEnum.USER_PREFERENCES)),
        MemoryTopic(
          managed_memory_topic=ManagedMemoryTopic(
            managed_topic_enum=ManagedTopicEnum.KEY_CONVERSATION_DETAILS)),
        MemoryTopic(
          managed_memory_topic=ManagedMemoryTopic(
            managed_topic_enum=ManagedTopicEnum.EXPLICIT_INSTRUCTIONS))
      ],
      # Only use the pre-defined set of examples.
      generate_memories_examples=[],
      consolidation_config=ConsolidationConfig(
        # Only use the latest memory revision of each candidate memory during
        # consolidation.
        revisions_per_candidate_count=1
      ),
      # 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
)

É possível ajustar a configuração do Memory Bank ao criar ou atualizar a instância. O exemplo a seguir demonstra como criar ou atualizar uma instância com uma configuração específica do Memory Bank.

client.agent_engines.create(
      ...,
      config={
            "context_spec": {
                  "memory_bank_config": memory_bank_config
            }
      }
)

# Alternatively, update an existing Memory Bank instance's config.
memory_bank = client.agent_engines.update(
      name=memory_bank.api_resource.name,
      config={
          "context_spec": {
                "memory_bank_config": memory_bank_config
          }
      }
)

Configuração de personalização de memória em linguagem natural

Para personalizar como o Memory Bank extrai memórias de linguagem natural, configure o comportamento de extração ao configurar sua instância. Use as opções a seguir para personalizar o comportamento:

Você pode pensar em personalizar o comportamento de extração do seu Banco de Memórias em duas etapas: dizer e mostrar. Os temas da Memória informam ao Memory Bank quais informações devem ser mantidas. Os poucos exemplos mostram ao Memory Bank que tipo de informação deve resultar em uma memória específica, ajudando a aprender os padrões, as nuances e as frases que você espera que ele entenda.

Você também pode configurar comportamentos diferentes para níveis de escopo diferentes. Por exemplo, os tópicos relevantes para recordações no nível da sessão podem não ser relevantes para recordações no nível do usuário (em várias sessões). Para configurar o comportamento de um determinado subconjunto de memórias, defina as chaves de escopo da configuração de personalização. Somente as solicitações GenerateMemories que incluem essas chaves de escopo usam essa configuração. Também é possível configurar o comportamento padrão (aplicado a todos os conjuntos de chaves de escopo) omitindo o campo scope_key. Essa configuração será aplicada a todas as solicitações que não tiverem uma configuração que corresponda exatamente às chaves de escopo de outra configuração de personalização.

Por exemplo, o user_level_config só se aplicaria a solicitações GenerateMemories que usam exatamente a chave de escopo user_id (ou seja, scope={"user_id": "123"} sem chaves adicionais). default_config se aplicaria a outras solicitações:

Dicionário 


user_level_config = {
  "scope_keys": ["user_id"],
  "memory_topics": [...],
  "generate_memories_examples": [...]
}

default_config = {
  "memory_topics": [...],
  "generate_memories_examples": [...]
}

memory_bank_config = {
  "customization_configs": [
    user_level_config,
    default_config
  ]
}

Com base em classes 

from vertexai.types import MemoryBankCustomizationConfig as CustomizationConfig

user_level_config = CustomizationConfig(
  scope_keys=["user_id"],
  memory_topics=[...],
  generate_memories_examples=[...]
)

Como configurar tópicos de memória

Os "Temas da memória" identificam quais informações o Memory Bank considera significativas e, portanto, devem ser mantidas como recordações geradas. O Memory Bank é compatível com dois tipos de temas de memória:

  • Tópicos gerenciados: o rótulo e as instruções são definidos pelo Memory Bank. Você só precisa informar o nome do tópico gerenciado. Por exemplo,

    Dicionário

    memory_topic = {
  "managed_memory_topic": {
    "managed_topic_enum": "USER_PERSONAL_INFO"
  }
}

    Com base em classes

    from vertexai.types import ManagedTopicEnum
from vertexai.types import MemoryBankCustomizationConfigMemoryTopic as MemoryTopic
from vertexai.types import MemoryBankCustomizationConfigMemoryTopicManagedMemoryTopic as ManagedMemoryTopic

memory_topic = MemoryTopic(
    managed_memory_topic=ManagedMemoryTopic(
        managed_topic_enum=ManagedTopicEnum.USER_PERSONAL_INFO
    )
)

    O Memory Bank oferece suporte aos seguintes tópicos gerenciados:

    • Informações do usuário (USER_PERSONAL_INFO): informações significativas sobre o usuário, como nomes, relacionamentos, hobbies e datas importantes. Por exemplo, "Trabalho no Google" ou "Meu aniversário de casamento é em 31 de dezembro".
    • Preferências do usuário (USER_PREFERENCES): gostos, não gostos, estilos ou padrões preferidos declarados ou implícitos. Por exemplo, "Prefiro o assento do meio".
    • Principais eventos de conversa e resultados de tarefas (KEY_CONVERSATION_DETAILS): marcos ou conclusões importantes no diálogo. Por exemplo, "Comprei passagens aéreas de ida e volta entre JFK e SFO. Vou sair em 1º de junho de 2025 e voltar em 7 de junho de 2025".
    • Instruções explícitas para lembrar / esquecer (EXPLICIT_INSTRUCTIONS): informações que o usuário pede explicitamente ao agente para lembrar ou esquecer. Por exemplo, se o usuário disser "Lembre-se de que eu uso principalmente Python", o Memory Bank vai gerar uma memória como "Eu uso principalmente Python".

  • Tópicos personalizados: o rótulo e as instruções são definidos por você ao configurar sua instância do Memory Bank. Eles serão usados na solicitação para a etapa de extração do Memory Bank. Por exemplo,

    Dicionário

    memory_topic = {
  "custom_memory_topic": {
    "label": "business_feedback",
    "description": """Specific user feedback about their experience at
    the coffee shop. This includes opinions on drinks, food, pastries, ambiance,
    staff friendliness, service speed, cleanliness, and any suggestions for
    improvement."""
    }
}

    Com base em classes

    from vertexai.types import MemoryBankCustomizationConfigMemoryTopic as MemoryTopic
from vertexai.types import MemoryBankCustomizationConfigMemoryTopicCustomMemoryTopic as CustomMemoryTopic

memory_topic = MemoryTopic(
  custom_memory_topic=CustomMemoryTopic(
    label="business_feedback",
    description="""Specific user feedback about their experience at
    the coffee shop. This includes opinions on drinks, food, pastries, ambiance,
    staff friendliness, service speed, cleanliness, and any suggestions for
    improvement."""
  )
)

    Ao usar tópicos personalizados, também é recomendável fornecer exemplos few-shot que mostrem como as memórias devem ser extraídas da conversa.

Com a personalização, você pode usar qualquer combinação de temas de memória. Por exemplo, é possível usar um subconjunto dos tópicos de memória gerenciada disponíveis:

Dicionário

customization_config = {
  "memory_topics": [
    { "managed_memory_topic": { "managed_topic_enum": "USER_PERSONAL_INFO" } },
    { "managed_memory_topic": { "managed_topic_enum": "USER_PREFERENCES" } }
  ]
}

Com base em classes

from vertexai.types import MemoryBankCustomizationConfig as CustomizationConfig
from vertexai.types import MemoryBankCustomizationConfigMemoryTopic as MemoryTopic
from vertexai.types import MemoryBankCustomizationConfigMemoryTopicManagedMemoryTopic as ManagedMemoryTopic
from vertexai.types import ManagedTopicEnum

customization_config = CustomizationConfig(
  memory_topics=[
      MemoryTopic(
          managed_memory_topic=ManagedMemoryTopic(
              managed_topic_enum=ManagedTopicEnum.USER_PERSONAL_INFO)
      ),
      MemoryTopic(
          managed_memory_topic=ManagedMemoryTopic(
              managed_topic_enum=ManagedTopicEnum.USER_PREFERENCES)
      ),
  ]
)

Você também pode usar uma combinação de temas gerenciados e personalizados (ou apenas temas personalizados):

Dicionário

customization_config = {
  "memory_topics": [
    { "managed_memory_topic": { "managed_topic_enum": "USER_PERSONAL_INFO" } },
    {
      "custom_memory_topic": {
        "label": "business_feedback",
        "description": """Specific user feedback about their experience at
the coffee shop. This includes opinions on drinks, food, pastries, ambiance,
staff friendliness, service speed, cleanliness, and any suggestions for
improvement."""
        }
    }
  ]
}

Com base em classes

from vertexai.types import MemoryBankCustomizationConfig as CustomizationConfig
from vertexai.types import MemoryBankCustomizationConfigMemoryTopic as MemoryTopic
from vertexai.types import MemoryBankCustomizationConfigMemoryTopicCustomMemoryTopic as CustomMemoryTopic
from vertexai.types import MemoryBankCustomizationConfigMemoryTopicManagedMemoryTopic as ManagedMemoryTopic
from vertexai.types import ManagedTopicEnum

customization_config = CustomizationConfig(
  memory_topics=[
      MemoryTopic(
          managed_memory_topic=ManagedMemoryTopic(
              managed_topic_enum=ManagedTopicEnum.USER_PERSONAL_INFO)
      ),
      MemoryTopic(
          custom_memory_topic=CustomMemoryTopic(
              label="business_feedback",
              description="""Specific user feedback about their experience at
the coffee shop. This includes opinions on drinks, food, pastries, ambiance,
staff friendliness, service speed, cleanliness, and any suggestions for
improvement."""
          )
    )
  ]
)

Exemplos few-shot

Com exemplos de poucos disparos (few-shot), você demonstra o comportamento esperado de extração de memória para o Memory Bank. Por exemplo, você pode fornecer uma conversa de entrada de amostra e as memórias que devem ser extraídas dela.

Recomendamos sempre usar poucos exemplos com temas personalizados para que o Memory Bank possa aprender o comportamento pretendido. Os poucos exemplos são opcionais ao usar tópicos gerenciados, já que o Memory Bank define exemplos para cada tópico. Demonstre conversas que não devem resultar em recordações fornecendo uma lista generated_memories vazia.

Por exemplo, você pode fornecer exemplos few-shot que demonstram como extrair feedback sobre sua empresa das mensagens dos clientes:

Dicionário

example = {
    "conversationSource": {
      "events": [
        {
          "content": {
            "role": "model",
            "parts": [{ "text": "Welcome back to The Daily Grind! We'd love to hear your feedback on your visit." }] }
        },
        {
          "content": {
            "role": "user",
            "parts": [{ "text": "Hey. The drip coffee was a bit lukewarm today, which was a bummer. Also, the music was way too loud, I could barely hear my friend." }] }
        }
      ]
    },
    "generatedMemories": [
      {
        "fact": "The user reported that the drip coffee was lukewarm."
      },
      {
        "fact": "The user felt the music in the shop was too loud."
      }
    ]
}

Com base em classes

from google.genai.types import Content, Part
from vertexai.types import MemoryBankCustomizationConfigGenerateMemoriesExample as GenerateMemoriesExample
from vertexai.types import MemoryBankCustomizationConfigGenerateMemoriesExampleConversationSource as ConversationSource
from vertexai.types import MemoryBankCustomizationConfigGenerateMemoriesExampleConversationSourceEvent as ConversationSourceEvent
from vertexai.types import MemoryBankCustomizationConfigGenerateMemoriesExampleGeneratedMemory as ExampleGeneratedMemory

example = GenerateMemoriesExample(
    conversation_source=ConversationSource(
        events=[
            ConversationSourceEvent(
                content=Content(
                    role="model",
                    parts=[Part(text="Welcome back to The Daily Grind! We'd love to hear your feedback on your visit.")]
                )
            ),
            ConversationSourceEvent(
                content=Content(
                    role="user",
                    parts=[Part(text= "Hey. The drip coffee was a bit lukewarm today, which was a bummer. Also, the music was way too loud, I could barely hear my friend.")]
                )
            )
        ]
    ),
    generated_memories=[
        ExampleGeneratedMemory(
            fact="The user reported that the drip coffee was lukewarm."
        ),
        ExampleGeneratedMemory(
            fact="The user felt the music in the shop was too loud."
        )
    ]
)

Você também pode fornecer exemplos de conversas que não devem resultar em memórias geradas, fornecendo uma lista vazia para a saída esperada (generated_memories):

Dicionário

example = {
    "conversationSource": {
        "events": [
          {
              "content": {
                  "role": "model",
                  "parts": [{ "text": "Good morning! What can I get for you at The Daily Grind?" }] }
          },
          {
              "content": {
                  "role": "user",
                  "parts": [{ "text": "Thanks for the coffee." }] }
          }
        ]
    },
    "generatedMemories": []
}

Com base em classes

from google.genai.types import Content, Part
from vertexai.types import MemoryBankCustomizationConfigGenerateMemoriesExample as GenerateMemoriesExample
from vertexai.types import MemoryBankCustomizationConfigGenerateMemoriesExampleConversationSource as ConversationSource
from vertexai.types import MemoryBankCustomizationConfigGenerateMemoriesExampleConversationSourceEvent as ConversationSourceEvent

example = GenerateMemoriesExample(
    conversation_source=ConversationSource(
        events=[
            ConversationSourceEvent(
                content=Content(
                    role="model",
                    parts=[Part(text="Welcome back to The Daily Grind! We'd love to hear your feedback on your visit.")]
                )
            ),
            ConversationSourceEvent(
                content=Content(
                    role="user",
                    parts=[Part(text= "Thanks for the coffee!")]
                )
            )
        ]
    ),
    generated_memories=[]
)

Perspectiva de memória

Por padrão, as recordações são geradas na primeira pessoa (por exemplo, "Eu uso o Memory Bank para gerenciamento de memória"). É possível configurar o Memory Bank para gerar na terceira pessoa (por exemplo, "O usuário usa o Memory Bank para gerenciamento de memória") usando o parâmetro enable_third_person_memories.

Dicionário

customization_config = {
  "enable_third_person_memories": True
}

Com base em classes

from vertexai.types import MemoryBankCustomizationConfig as CustomizationConfig

customization_config = CustomizationConfig(
    enable_third_person_memories=True
)

Personalização da consolidação

Durante a consolidação, o Memory Bank determina como integrar as informações recém-adquiridas ao seu conjunto de memórias atual. O Memory Bank avalia se é necessário ADICIONAR novas recordações, ATUALIZAR as recordações atuais com mais contexto ou EXCLUIR as recordações obsoletas.

Para garantir recordações corroboradas e de alta qualidade, o Memory Bank pode analisar o histórico de uma recordação para distinguir tendências de longo prazo de outliers únicos.

Por padrão, o Banco de Memória só compara novas informações com o snapshot mais recente de uma memória candidata (uma revisão de memória). Para aumentar a profundidade dessa análise, configure o parâmetro revisions_per_candidate_count. Esse parâmetro define quantas revisões anteriores de cada "memória candidata" (o registro específico que está sendo avaliado para uma atualização) o Memory Bank considera durante a consolidação.

Dicionário

customization_config = {
  "consolidation_customization": {
    "revisions_per_candidate_count": 10
  }
}

Com base em classes

from vertexai.types import MemoryBankCustomizationConfig as CustomizationConfig
from vertexai.types import MemoryBankCustomizationConfigConsolidationConfig as ConsolidationConfig

customization_config = CustomizationConfig(
    consolidation_customization=ConsolidationConfig(
      revisions_per_candidate_count=10
    )
)

Aumentar revisions_per_candidate_count resulta em memórias mais consistentes e corroboradas, considerando a repetição das informações ingeridas. No entanto, uma contagem maior aumenta o consumo de tokens durante o processo de consolidação.

Configuração da pesquisa por similaridade

A configuração de pesquisa de similaridade controla qual modelo de embedding é usado pela sua instância para essa pesquisa. A pesquisa de similaridade é usada para identificar quais memórias devem ser candidatas à consolidação e à recuperação de memória com base na pesquisa de similaridade. Se essa configuração não for fornecida, o Memory Bank vai usar text-embedding-005 como o modelo padrão.

Se você espera que as conversas dos usuários sejam em idiomas diferentes do inglês, use um modelo que ofereça suporte a vários idiomas, como gemini-embedding-2, gemini-embedding-001 ou text-multilingual-embedding-002, para melhorar a qualidade da recuperação.

Dicionário

memory_bank_config = {
    "similarity_search_config": {
        "embedding_model": "EMBEDDING_MODEL",
    }
}

Com base em classes 

from vertexai.types import ReasoningEngineContextSpecMemoryBankConfig as MemoryBankConfig
from vertexai.types import ReasoningEngineContextSpecMemoryBankConfigSimilaritySearchConfig as SimilaritySearchConfig

memory_bank_config = MemoryBankConfig(
    similarity_search_config=SimilaritySearchConfig(
        embedding_model="EMBEDDING_MODEL"
    )
)

Substitua:

  • EMBEDDING_MODEL: o modelo de embedding de texto do Google a ser usado para pesquisa de similaridade, no formato projects/{project}/locations/{location}/publishers/google/models/{model}.

Configuração de geração

A configuração de geração controla qual LLM é usado para gerar memórias, incluindo extrair memórias e consolidar novas memórias com as atuais.

A partir de 29 de junho de 2026, o Memory Bank vai usar gemini-3.5-flash para o modelo padrão. As instâncias criadas antes dessa data usam gemini-2.5-flash.

Para novas instâncias do Memory Bank usando o modelo padrão:

  • As instâncias do Memory Bank na multirregião us ou nas regiões únicas us-* (por exemplo, us-central1) usam o endpoint multirregional us do Gemini 3.5.
  • As instâncias do Memory Bank na multirregião eu ou nas regiões únicas eu-* (por exemplo, europe-west2) usam o endpoint multirregional eu do Gemini 3.5.
  • Todas as outras regiões do Memory Bank usam o endpoint global do Gemini 3.5.

Para instâncias do Memory Bank criadas antes de 29 de junho de 2026 usando o modelo padrão, o Memory Bank usa o endpoint global do Gemini em regiões que não têm um endpoint regional do Gemini 2.5 disponível.

Dicionário

memory_bank_config = {
  "generation_config": {
    "model": "LLM_MODEL",
  }
}

Com base em classes 

from vertexai.types import ReasoningEngineContextSpecMemoryBankConfig as MemoryBankConfig
from vertexai.types import ReasoningEngineContextSpecMemoryBankConfigGenerationConfig as GenerationConfig

memory_bank_config = MemoryBankConfig(
  generation_config=GenerationConfig(
    model="LLM_MODEL"
  )
)

Substitua:

  • LLM_MODEL: o modelo de LLM do Google a ser usado para extrair e consolidar memórias, no formato projects/{project}/locations/{location}/publishers/google/models/{model}.

Configuração de time to live (TTL)

A configuração de TTL controla como o Memory Bank define dinamicamente o tempo de expiração das memórias. Depois que o tempo de expiração expirar, as recordações não estarão mais disponíveis para recuperação e serão excluídas.

Se a configuração não for fornecida, o prazo de validade não será definido dinamicamente para as recordações criadas ou atualizadas. Portanto, elas não vão expirar, a menos que o prazo de validade seja definido manualmente.

Há duas opções para a configuração de TTL:

  • TTL padrão: o TTL será aplicado a todas as operações que criam ou atualizam uma memória, incluindo UpdateMemory, CreateMemory e GenerateMemories.

    Dicionário

    memory_bank_config = {
  "ttl_config": {
      "default_ttl": f"TTLs"
  }
}

    Com base em classes 

    from vertexai.types import ReasoningEngineContextSpecMemoryBankConfig as MemoryBankConfig
from vertexai.types import ReasoningEngineContextSpecMemoryBankConfigTtlConfig as TtlConfig

memory_bank_config = MemoryBankConfig(
  ttl_config=TtlConfig(
      default_ttl=f"TTLs"
  )
)

    Substitua:

    • TTL: a duração em segundos do TTL. Para memórias atualizadas, o prazo de validade recém-calculado (agora + TTL) vai substituir o prazo anterior.

  • TTL granular (por operação): o TTL é calculado com base na operação que criou ou atualizou a memória. Se não for definido para uma determinada operação, a operação não vai atualizar o prazo de validade da memória.

    Dicionário

    memory_bank_config = {
  "ttl_config": {
      "granular_ttl": {
          "create_ttl": f"CREATE_TTLs",
          "generate_created_ttl": f"GENERATE_CREATED_TTLs",
          "generate_updated_ttl": f"GENERATE_UPDATED_TTLs"
      }
  }
}

    Com base em classes 

    from vertexai.types import ReasoningEngineContextSpecMemoryBankConfig as MemoryBankConfig
from vertexai.types import ReasoningEngineContextSpecMemoryBankConfigTtlConfig as TtlConfig
from vertexai.types import ReasoningEngineContextSpecMemoryBankConfigTtlConfigGranularTtlConfig as GranularTtlConfig

memory_bank_config = MemoryBankConfig(
  ttl_config=TtlConfig(
      granular_ttl_config=GranularTtlConfig(
          create_ttl=f"CREATE_TTLs",
          generate_created_ttl=f"GENERATE_CREATED_TTLs",
          generate_updated_ttl=f"GENERATE_UPDATED_TTLs",
      )
  )
)

    Substitua:

    • CREATE_TTL: a duração em segundos do TTL para memórias criadas usando CreateMemory.
    • GENERATE_CREATED_TTL: a duração em segundos do TTL para memórias criadas usando GenerateMemories.
    • GENERATE_UPDATED_TTL: a duração em segundos do TTL para memórias atualizadas usando GenerateMemories. O prazo de validade recém-calculado (agora + TTL) vai substituir o prazo de validade anterior da memória.

A seguir

Guia de início rápido

Comece a usar a API Memory Bank para gerenciar memórias de longo prazo.

Guia de início rápido

Comece a usar o Kit de Desenvolvimento de Agente (ADK).