Sessions, Memory & Skills

LLMs são inerentemente stateless: todo o seu raciocínio acontece dentro da context window de uma única chamada de API. Nada do que veio antes existe para o modelo — a menos que alguém coloque lá. Context Engineering é o processo de montar e gerenciar dinamicamente a informação dentro da context window para habilitar agentes stateful e inteligentes.

É a evolução natural do Prompt Engineering: em vez de lapidar uma instrução estática, o engenheiro de contexto orquestra o payload inteiro — selecionando, resumindo e injetando estrategicamente diferentes tipos de informação a cada turno, com máxima relevância e mínimo ruído. Sistemas externos (RAG, session stores, memory managers) gerenciam o contexto; o framework orquestra tudo.

Tudo o que o modelo "vê" em um turno cabe em três categorias. A construção é dinâmica: memórias não são estáticas, few-shot examples devem ser relevantes à tarefa (não hardcoded) e o RAG responde à query imediata.

O histórico de conversa cresce sem parar. Janelas maiores aguentam transcrições longas, mas: custo e latência aumentam a cada token e surge o context rot — a atenção do modelo à informação crítica diminui conforme o contexto cresce. A solução é mutar o histórico dinamicamente: sumarização, poda seletiva, compactação.

Uma session encapsula o histórico de diálogo e a working memory de uma conversa contínua: um registro auto-contido ligado a um usuário específico. Um usuário pode ter múltiplas sessions — logs distintos e desconectados entre si.

O agente anexa events e muta o state conforme a lógica do negócio. A estrutura ecoa a lista de Content objects da Gemini API — cada Content tem role (user/model) e parts (texto, imagens, tool calls): um turno = um Event.

# o histórico é uma lista de Content: role + parts
response = client.models.generate_content(
    model="gemini-2.5-flash",
    contents=[
        {"role": "user",  "parts": [{"text": "Quero ir a Paris em novembro"}]},
        {"role": "model", "parts": [{"text": "Direto ou com escala?"}]},
        {"role": "user",  "parts": [{"text": "Direto, por favor"}]},
    ],
)

O framework é um tradutor universal entre o seu código e o LLM: mantém o histórico e o state, constrói as requests, parseia e armazena as respostas. Para o Gemini, a request é List[Content] — cada Content com role e parts. O framework mapeia seu objeto interno (ex.: um Event do ADK) para role/parts antes da chamada. Essa abstração desacopla a lógica do agente do LLM específico — e previne vendor lock-in.

session = Session(
    id="s_771",
    events=[event_1, event_2, event_3],  # histórico cronológico
    state={"cart_items": [...]},          # working memory separada
)

class AgentState(TypedDict):
    messages: Annotated[list, add_messages]  # histórico
    cart: dict                                 # dados de trabalho
# o grafo pode reescrever o state a cada passo (ex.: compactar)

Há um trade-off crítico: a mesma abstração que desacopla o agente do LLM o isola de agentes de outros frameworks. O isolamento se solidifica na camada de persistência — o schema do banco fica acoplado aos objetos internos do framework, e o registro se torna não-portável. Um agente LangGraph não consegue interpretar nativamente os objetos Session/Event de um agente ADK: handoff seamless, impossível.

Numa arquitetura simples, a session é um log imutável. Conforme ela escala, o uso de tokens explode — e quatro limitações mordem aplicações latency-sensitive:

As três estratégias de compactação

# limita o contexto enviado ao LLM, sem modificar o log persistido
plugin = ContextFilterPlugin(num_invocations_to_keep=10)

# ou: compactação agendada de eventos
config = EventsCompactionConfig(compaction_interval=5, overlap_size=1)

Mecanismos de trigger

Sessions e memory vivem em simbiose: as sessions são a fonte primária para gerar memórias, e as memórias são a estratégia-chave para gerenciar o tamanho das sessions. Uma alimenta a outra, em ciclo contínuo.

Uma memória é um snapshot de informação extraída e significativa de uma conversa ou fonte: uma representação condensada que preserva o contexto importante, persistida entre sessões para uma experiência contínua e personalizada.

Quatro capacidades que um sistema de memória habilita

As cinco camadas que colaboram em cada turno

O retrieval de memória é frequentemente comparado ao RAG, mas os princípios arquiteturais são diferentes: RAG lida com dados externos estáticos; Memory, com contexto dinâmico e específico do usuário. São complementares — e um agente verdadeiramente inteligente precisa dos dois.

Memórias são classificadas por como são armazenadas e capturadas — e trabalham juntas para um entendimento rico e contextual. Regra de ouro: memórias são descritivas, não preditivas.

Anatomia de uma memória

Uma "memória" é uma peça atômica de contexto retornada pelo memory manager e usada pelo agente como contexto. O schema exato pode variar, mas uma memória geralmente consiste em dois componentes: content e metadata.

Declarative × Procedural (ciência cognitiva)

Padrões de organização

Arquiteturas de storage

Mecanismos de criação

Escopo: quem a memória descreve

Memória multimodal: origem × conteúdo

from google.genai import types

client = vertexai.Client(project=..., location=...)

response = client.agent_engines.memories.generate(
    name=agent_engine_name,
    direct_contents_source={
        "events": [
            {
                "content": types.Content(
                    role="user",
                    parts=[
                        types.Part.from_text("This is context about the multimodal input."),
                        types.Part.from_bytes(data=CONTENT_AS_BYTES, mime_type=MIME_TYPE),
                        types.Part.from_uri(file_uri="file/path/to/content", mime_type=MIME_TYPE)
                    ]
                )
            }
        ]
    },
    scope={"user_id": user_id}
)

A geração transforma autonomamente dados conversacionais raw em insights estruturados e significativos — um pipeline ETL dirigido por LLM (Extract, Transform, Load). É isso que distingue memory managers de RAG engines e databases tradicionais: em vez de o dev especificar operações de banco manualmente, o LLM decide quando adicionar, atualizar ou fundir memórias — abstraindo a complexidade de gerenciar conteúdo, encadear chamadas e rodar serviços em background.

memories.generate(
    scope={"user_id": "u_8123"},
    direct_contents_source=session_events,   # matéria-prima raw
    config={"wait_for_completion": False},   # assíncrono, em background
)

A pergunta fundamental da extraction é: "que informação nesta conversa é significativa o suficiente para virar memória?" Não é sumarização simples — é filtragem inteligente e direcionada: separar o sinal (fatos, preferências, metas) do ruído (cortesias, filler).

"Significativo" não é universal — é definido pelo propósito do agente. Um agente de suporte ao cliente extrai números de pedido e problemas técnicos; um coach de bem-estar extrai metas de longo prazo e estados emocionais. Customizar essa definição é a chave para um agente eficaz.

Como o LLM sabe o que extrair

A maioria dos managers funciona out-of-the-box com tópicos comuns (preferências, fatos-chave, metas) — e muitos permitem tópicos customizados. O exemplo do paper: uma conversa sobre uma cafeteria gera duas memórias de feedback — "o café coado estava morno" e "a música estava alta demais".

config = MemoryGenerationConfig(
    memory_topics=[
        ManagedTopicEnum.USER_PERSONAL_INFO,          # tópico built-in
        CustomMemoryTopic(
            name="business_feedback",
            description="feedback about the coffee shop",
        ),
    ],
    generate_memories_examples=[...],                  # few-shot: conversa → fatos
)

A consolidation integra nova informação numa base de conhecimento coerente, precisa e evolutiva. É o estágio mais sofisticado: sem ela, a memória vira um log ruidoso, contraditório e não-confiável. Essa "self-curation" gerenciada por LLM é o que eleva o memory manager além de um database simples.

Os quatro problemas que ela endereça

O processo em três passos

"Garbage in, garbage out" é ainda mais crítico para LLMs: aqui é "garbage in, confident garbage out". Para decisões confiáveis e consolidação eficaz, o agente deve avaliar criticamente a qualidade das próprias memórias — e a confiabilidade deriva da provenance: o registro detalhado de origem e histórico.

Linhagem durante o gerenciamento

A confiança evolui — e a poda é ativa

A confiança não é estática: aumenta por corroboração (múltiplas fontes confiáveis consistentes) e decai com a idade e o conflito. O memory pruning (esquecimento ativo) identifica e descarta memórias que deixaram de ser úteis — por time-based decay (uma reunião de 2 anos atrás vale menos que a da semana passada), low confidence (inferência fraca nunca corroborada) ou irrelevância (detalhes triviais antigos diante das metas atuais). Consolidação reativa + poda proativa = base de conhecimento curada, não um log crescente de tudo.

Memory managers automatizam extração e consolidação depois que a geração é disparada — mas quem decide quando tentar gerar é o agente. É uma escolha arquitetural crítica: balancear data freshness contra custo computacional e latência.

Estratégias de trigger

Memory-as-a-tool: o agente decide

Na abordagem mais sofisticada, a geração é exposta como uma tool (ex.: create_memory) cuja definição descreve que tipos de informação são significativos. O agente analisa a conversa e chama a tool autonomamente quando identifica algo que vale persistir — transferindo a responsabilidade de identificar o "significativo" do memory manager para o agente/dev.

def generate_memories(tool_context):
    # opção 1: histórico completo da session
    memory_service.add_session_to_memory(tool_context.session)
    # opção 2: só o último turno, assíncrono
    memories.generate(..., config={"wait_for_completion": False})

runner = Runner(agent=agent, memory_service=VertexAiMemoryBankService())

# aqui o AGENTE extrai (extract_memories) e envia ao Memory Bank
# apenas para CONSOLIDAR com as memórias existentes
memories = extract_memories(direct_memories_source={"fact": query})
memory_bank.store(memories)  # consolidação delegada ao serviço

Background, sempre

A estratégia de retrieval depende da organização: um structured user profile é um lookup simples (o perfil inteiro ou um atributo); uma collection é um problema de busca complexo — descobrir a informação mais pertinente num pool grande e pouco estruturado.

Retrieval eficaz é crucial: memórias irrelevantes confundem o modelo e degradam a resposta; o contexto perfeito gera uma interação notavelmente inteligente. O desafio central é balancear utilidade com um budget de latência estrito.

As três dimensões do scoring

Técnicas de precisão (e seu custo)

Timing: quando buscar

# Option 1: PreloadMemoryTool embutida — busca por similaridade em todo turno
agent = LlmAgent(
    ...,
    tools=[adk.tools.preload_memory_tool.PreloadMemoryTool()]
)

# Option 2: callback customizado — mais controle sobre como as memórias são buscadas
def retrieve_memories_callback(callback_context, llm_request):
    user_id = callback_context._invocation_context.user_id
    app_name = callback_context._invocation_context.app_name
    response = client.agent_engines.memories.retrieve(
        name="projects/.../locations/.../reasoningEngines/...",
        scope={"user_id": user_id, "app_name": app_name}
    )
    memories = [f"* {memory.memory.fact}" for memory in list(response)]
    if not memories:
        return  # nenhuma memória para acrescentar às System Instructions
    # anexa as memórias formatadas às System Instructions
    llm_request.config.system_instruction += "\nHere is information that you have about the user:\n"
    llm_request.config.system_instruction += "\n".join(memories)

agent = LlmAgent(
    ...,
    before_model_callback=retrieve_memories_callback,
)

# Option 1: LoadMemoryTool embutida — o agente decide quando buscar
agent = LlmAgent(
    ...,
    tools=[adk.tools.load_memory_tool.LoadMemoryTool()],
)

# Option 2: tool customizada — descreva que tipos de informação podem estar disponíveis
def load_memory(query: str, tool_context: ToolContext):
    """Retrieves memories for the user. The following types of
    information may be stored for the user:
    * User preferences, like the user's favorite foods. ..."""
    # busca memórias por similaridade
    response = tool_context.search_memory(query)
    return response.memories

agent = LlmAgent(
    ...,
    tools=[load_memory],
)

O posicionamento influencia o raciocínio do LLM, os custos operacionais e a qualidade da resposta. Na prática, a estratégia híbrida é a mais eficaz: system prompt para memórias estáveis/globais (perfil do usuário, sempre presentes); dialogue injection ou memory-as-a-tool para memórias transitórias/episódicas (relevantes só ao contexto imediato).

Memórias nas System Instructions

Anexar memórias ao system prompt com um preamble dá alta autoridade e separa o contexto do diálogo — ideal para informação estável e global. Tipicamente via template (ex.: Jinja) com um bloco <MEMORIES> iterando sobre retrieved_memory.memory.fact.

from jinja2 import Template

template = Template("""
{{ system_instructions }}
<MEMORIES>
Here is some information about the user:
{% for retrieved_memory in data %}* {{ retrieved_memory.memory.fact }}
{% endfor %}</MEMORIES>
""")

prompt = template.render(
    system_instructions=system_instructions,
    data=retrieved_memories
)

Memórias no Conversation History

Injetar diretamente no diálogo — antes do histórico completo ou logo antes da última query. Riscos: ruído (mais tokens, confusão se irrelevantes) e dialogue injection (o modelo trata a memória como algo realmente dito na conversa). Cuidado com a perspectiva: se usar role "user" com memórias user-level, escreva em primeira pessoa. Caso especial: retrieval via tool calls — as memórias chegam como tool output.

def load_memory(query: str, tool_context):
    """Search the user's long-term memories."""
    response = tool_context.search_memory(query)
    return response.memories  # entra no contexto como tool output

E as procedural memories?

O paper focou em declarative — reflexo do mercado comercial atual, cujas plataformas são arquitetadas para extrair/armazenar/recuperar o "what". Mas armazenar o "how" não é um problema de information retrieval — é um problema de reasoning augmentation, com lifecycle próprio:

Evaluation de memória é um processo em múltiplas camadas: verificar se o agente lembra as coisas certas (qualidade), encontra as memórias quando precisa (retrieval) e se usá-las realmente ajuda a cumprir objetivos (task success). Na academia, benchmarks reproduzíveis; na indústria, impacto direto no agente de produção.

Do protótipo à produção, o foco muda para concerns enterprise-grade: escalabilidade, resiliência e segurança. A regra número um: desacoplar o processamento de memória da lógica principal — a UX nunca pode ser bloqueada por geração cara.

Concorrência, falhas e escala global

Privacidade & riscos de segurança

Memórias derivam de — e incluem — dados do usuário. Pense num arquivo corporativo seguro gerenciado por um arquivista profissional: ele preserva o conhecimento valioso protegendo a empresa.

A jornada de um turno conversacional até inteligência persistente é governada pela Context Engineering — montar dinamicamente histórico, memórias e conhecimento externo na context window. Ela depende da interação de dois sistemas distintos e interconectados: