Imagine que você contrata um consultor brilhante. Ele tem dois doutorados, fala sete idiomas e resolve problemas que você nem sabia que existiam. Você o senta em uma sala e diz: “preciso que refatore a autenticação do projeto”.

O consultor olha para você, acena com a cabeça e pergunta: “Que projeto?”

Você não lhe deu acesso ao código. Não explicou a arquitetura. Ele não sabe se você usa tokens JWT ou cookies de sessão. Não sabe qual linguagem de programação você usa, quantos microsserviços existem ou por que a última tentativa de migração foi um desastre.

Esse consultor é seu LLM. E você acabou de cometer o erro que 90% das pessoas que trabalham com agentes de IA cometem: se preocupar com o cérebro em vez de se preocupar com o que o cérebro vê.

Prompt engineering está morto. Vida longa ao context engineering.

Faz meses que eu vejo a mesma conversa em fóruns, threads no Twitter e reuniões de equipe: “GPT-5 ou Claude Opus?”, “qual modelo é melhor para código?”, “qual raciocina melhor?”.

E a resposta, sempre que eu faço as contas, é a mesma: tanto faz. Bem, não é exatamente tanto faz. Mas a diferença entre um modelo de ponta e outro também de ponta é marginal, comparada à diferença entre fornecer um bom contexto ou entregar um lixo.

Um modelo medíocre com um contexto perfeito supera um modelo de ponta com um contexto ruim. Sempre. Sem exceção.

Isso tem um nome: context engineering. E não, não é a mesma coisa que prompt engineering.

Prompt engineering é escrever um bom prompt. É escolher as palavras corretas, estruturar o pedido, adicionar exemplos. É importante, mas é só uma parte do processo.

Context engineering é planejar tudo o que o modelo vê: quais informações entram, em que ordem, o que é descartado quando não há espaço, o que é compactado, o que deve ser preservado a qualquer custo. É a arquitetura da informação para LLMs.

Em palavras simples: prompt engineering é formular uma boa pergunta. Context engineering é decidir quais livros o aluno terá na mesa antes que a prova comece.

As quatro fases da memória: um ciclo de vida invisível

A OpenAI recentemente publicou dois artigos em seu Cookbook que desvendam como funciona a gestão de contexto em agentes com memória de longo prazo. Não é RAG. Não é um banco de dados vetorial. É um sistema de estados que funciona como um diário de bordo com regras rígidas.

O padrão é local-first e state-based: um objeto de estado estruturado que viaja com o agente e se atualiza em cada fase.

flowchart TD
    A["1. INJECTION\n(início da sessão)"] --> B["2. DISTILLATION\n(durante a conversa)"]
    B --> C["3. CONSOLIDATION\n(pós-sessão)"]
    C --> D["4. TRIMMING\n(preservação)"]
    D -->|"Nova sessão"| A

    A1["Renderiza estado como YAML\n+ memórias globais (máx. 6)\n+ regras de precedência"] -.-> A
    B1["save_memory_note()\nValida durabilidade\nExige ser acionável\nRejeita PII e especulação"] -.-> B
    C1["Trabalho assíncrono\nFunde sessão → global\nDeduplicação com LLM\nFiltra notas temporárias"] -.-> C
    D1["TrimmingSession: últimos N\nReinjeta notas cortadas\nno system prompt"] -.-> D

    style A fill:#2d3748,stroke:#4a9eed,color:#fff
    style B fill:#2d3748,stroke:#ed9a4a,color:#fff
    style C fill:#2d3748,stroke:#9a4eed,color:#fff
    style D fill:#2d3748,stroke:#4aed5c,color:#fff

Fase 1: Injection — a mesa da prova

Quando uma sessão começa, o agente monta seu contexto inicial. Não é aleatório. É uma estrutura específica:

  • YAML frontmatter com o estado do usuário (preferências, configurações).
  • Lista de memórias globais: no máximo 6, ordenadas por recência. Por que 6? Porque mais de 6 competem entre si pela atenção do modelo e começam a se diluir. Menos é mais.
  • Bloco <memory_policy> com regras explícitas de precedência.

As regras de precedência são fundamentais: Entrada atual > Memória da sessão > Memória global > Recência dentro do mesmo escopo. Se o usuário disser “agora uso Vim”, mas sua memória global indicar “usa VS Code”, vence o que acabou de ser dito. Parece óbvio, mas sem regras explícitas, o modelo às vezes insiste no que “lembra” em vez de considerar o que você acabou de dizer.

Fase 2: Distillation — capturar sem contaminar

Durante a conversa, o agente pode capturar memórias em tempo real com uma ferramenta como save_memory_note(). Mas nem tudo vale. A ferramenta possui guardrails rígidos:

  • Valida durabilidade: “o usuário quer pizza hoje à noite” não é uma memória durável. É rejeitada.
  • Exige ser acionável: a memória precisa ser útil em sessões futuras.
  • Rejeita PII: nomes completos, endereços, números de cartão. Fora.
  • Rejeita especulação: “acho que o usuário prefere Python” não é fato. É suposição.
  • Requer confirmação do usuário: antes de salvar, o agente pergunta.

Esse filtro é rigoroso, e com razão. Uma memória contaminada envenena todas as sessões futuras. É como se seu diário de bordo tivesse uma anotação falsa: cada vez que você o consulta, toma decisões baseadas em informações erradas.

Fase 3: Consolidation — a faxina noturna

Após cada sessão, uma tarefa assíncrona coleta as notas da sessão e as funde com a memória global. Não é um append. É uma consolidação inteligente:

  • Deduplicação assistida pelo LLM: se duas anotações dizem a mesma coisa com palavras diferentes, elas são fundidas.
  • Filtragem de notas temporárias: qualquer coisa com “this time”, “today”, “agora mesmo” é descartada.
  • Resolução de conflitos por recência: se uma anotação nova contradiz uma antiga, prevalece a nova.

Pense nisso como a pessoa que organiza sua mesa no final do dia. Não joga tudo fora — guarda o importante, reúne os post-its redundantes e descarta o que não é mais relevante.

Fase 4: Trimming — cortar sem perder

Quando o histórico cresce demais, é preciso cortá-lo. TrimmingSession preserva apenas os últimos N turnos. Mas — preste atenção nisso — as notas de memória na parte cortada não são perdidas. Elas são reinjecionadas no system prompt do próximo ciclo.

É como arrancar as páginas antigas de um caderno, mas copiar as notas importantes para a primeira página antes de jogá-las fora.

Trimming vs Summarization: duas filosofias, um dilema

Para gerenciar a memória de curto prazo (o histórico de conversa dentro de uma sessão), há duas técnicas fundamentais. Cada uma com vantagens e desvantagens.

flowchart LR
    subgraph Trimming["Trimming (Últimos N turnos)"]
        direction TB
        T1["Histórico completo\n(40 turnos)"]
        T2["Cortar turnos 1-30"]
        T3["Manter turnos 31-40\n(intactos, inalterados)"]
        T1 --> T2 --> T3
    end

    subgraph Summarization["Summarization (Compressão)"]
        direction TB
        S1["Histórico completo\n(40 turnos)"]
        S2["LLM resume turnos 1-30\nem ~400 tokens"]
        S3["Injeta resumo sintético\n+ turnos 31-40"]
        S1 --> S2 --> S3
    end

    style Trimming fill:#1a2332,stroke:#4a9eed,color:#fff
    style Summarization fill:#2a1a32,stroke:#9a4eed,color:#fff

Trimming: a guilhotina determinística

Explora o histórico de trás para frente e mantém completos apenas os últimos N turnos. Tudo o que veio antes desaparece.

Vantagem: fidelidade total ao contexto recente. O que resta não foi alterado, resumido ou interpretado. São mensagens originais, como foram enviadas.

Desvantagem: amnésia repentina. O turno N-1 existe em todo detalhe. O turno N-2 não existe de jeito nenhum.

Summarization: a compressão com risco

Quando o histórico excede um limite, um LLM sintetiza o antigo histórico, que é injetado no contexto da nova conversa, seguindo princípios que maximizem consistência e clareza.

… A diferença em resultados reais: gerentes de contexto - cruciais no fim do pipeline.