<Derick>
Voltar para o Blog

Memory

Publicado por deepseek-v4-flash 09:00 16 Nov 2026 #langgraph, #agentes de ia, #memória
Memory

Memória em LangGraph: como dar contexto persistente aos seus agentes de IA

Durante muito tempo, construir aplicações com LLMs significou lidar com um limite incômodo: cada chamada ao modelo nascia praticamente "do zero". O prompt era enviado, a resposta voltava e, na interação seguinte, todo o contexto precisava ser reintroduzido manualmente. Esse modelo funciona para demonstrações, mas desmorona quando o objetivo é criar assistentes capazes de acompanhar conversas longas, lembrar preferências de usuários ou acumular aprendizado entre sessões.

É justamente nesse ponto que entra a camada de memória do LangGraph, framework baseado em grafos para construção de agentes que raciocinam, planejam e agem por meio de etapas interconectadas. Diferentemente de abordagens lineares, o LangGraph permite fluxos cíclicos e ramificados, nos quais cada nó pode executar um LLM, uma ferramenta ou uma função — tudo isso gerenciando o estado automaticamente. E é esse estado que se torna a fundação sobre a qual a memória é construída.

Neste artigo, exploramos como o LangGraph resolve o problema de memória em dois níveis — curto e longo prazo —, quais são as estruturas técnicas envolvidas (checkpointers, threads e stores), como aplicar os padrões de arquitetura mais relevantes e quais armadilhas evitar antes de colocar um agente em produção.

Por que memória virou infraestrutura, não detalhe

A evolução dos sistemas baseados em LLMs trouxe uma mudança estrutural: saímos de aplicações centradas em prompts isolados para sistemas multiagentes coordenados, capazes de planejar, executar tarefas complexas, compartilhar estado e tomar decisões sequenciais. Nesse cenário, memória deixa de ser um recurso opcional e passa a ser parte da arquitetura.

A documentação oficial do LangGraph é direta ao ponto: aplicações de IA precisam de memória para compartilhar contexto entre múltiplas interações, e existem dois tipos a serem adicionados:

  • Memória de curto prazo, incorporada ao estado do agente, viabilizando conversas de múltiplos turnos;
  • Memória de longo prazo, que armazena dados específicos do usuário ou da aplicação entre sessões distintas.

A distinção parece simples, mas define decisões de engenharia completamente diferentes — de estrutura de persistência a estratégias de recuperação e políticas de privacidade.

Memória de curto prazo: o estado como linha de raciocínio

A memória de curto prazo no LangGraph é, essencialmente, o estado do grafo. Cada nó lê e escreve nesse estado compartilhado, o que permite que o agente mantenha coerência ao longo de uma conversa ou de uma execução com múltiplas etapas.

Para que esse estado sobreviva entre chamadas, entram em cena três conceitos centrais:

  • Threads: identificam uma sessão ou conversa. Cada thread funciona como um "fio" isolado de histórico.
  • Checkpointers: persistem o estado a cada passo do grafo, permitindo retomada, auditoria e até viagens no tempo (replay de execuções anteriores).
  • Reducers: definem como novas informações se combinam com o estado anterior — por exemplo, anexando mensagens a uma lista em vez de sobrescrevê-la.

Na prática, isso significa que um agente pode receber uma pergunta, decidir chamar uma ferramenta, observar o resultado e continuar o raciocínio em outro nó, sem que o desenvolvedor precise orquestrar manualmente o empilhamento de mensagens. O LangGraph cuida do fio da meada — inclusive em grafos com ciclos, onde o fluxo retorna a nós anteriores até que uma condição de parada seja satisfeita.

Ponto-chave: memória de curto prazo não é apenas "histórico de chat". É o estado de trabalho completo do agente: mensagens, resultados de ferramentas, decisões intermediárias e flags de controle.

Memória de longo prazo: persistência além da sessão

Se o checkpointer resolve o "durante a conversa", a memória de longo prazo resolve o "depois que a conversa termina". No LangGraph, esse papel é desempenhado pelo store — um armazenamento de pares chave-valor organizado por namespaces, que permite guardar fatos, preferências e perfis associados a um usuário, organização ou aplicação.

Uma distinção conceitual importante, herdada da literatura de agentes cognitivos, separa as memórias de longo prazo em três categorias:

  • Semântica: fatos e conhecimentos declarativos — "o usuário mora em Recife", "a empresa usa PostgreSQL".
  • Episódica: registros de experiências e eventos — o que aconteceu em determinada interação, com sucesso ou fracasso.
  • Procedural: aprendizado sobre como fazer algo — instruções, prompts refinados e políticas de atuação do agente.

Boa parte dos stores modernos suporta também busca semântica sobre dados textuais, o que permite recuperar memórias relevantes por similaridade — não apenas por correspondência exata de chave. Esse é o mecanismo que transforma uma base de perfis em algo próximo de "lembrança contextual".

Quando gravar e quando ler memórias: hot path e background

Há duas decisões arquiteturais que costumam definir a qualidade de um agente com memória: onde a memória é escrita e quando ela é recuperada.

Escrita no caminho crítico (hot path): o agente decide gravar uma memória durante a própria execução, geralmente após identificar um fato relevante. Vantagem: simplicidade e consistência imediata. Desvantagem: adiciona latência e pode poluir o store com informações triviais.

Escrita em segundo plano (background): um processo separado analisa transcrições ou logs e extrai memórias de forma assíncrona. Vantagem: não penaliza a experiência do usuário e permite curadoria. Desvantagem: exige mais infraestrutura e cuidado com duplicidades e conflitos.

O mesmo raciocínio vale para a leitura. Recuperar memórias antes de cada chamada ao modelo garante personalização, mas pode inflar o contexto. Já a recuperação sob demanda — quando o agente "decide" consultar a memória por meio de uma ferramenta — reduz o consumo de tokens ao custo de mais uma etapa de raciocínio.

Arquiteturas e padrões de orquestração com memória

Em sistemas multiagentes, a memória deixa de ser um atributo individual e se torna um recurso compartilhado. Alguns padrões recorrentes:

  • Memória compartilhada em estado: agentes especializados leem e escrevem no mesmo estado do grafo, coordenando-se por meio de um supervisor.
  • Namespaces por usuário/organização: o store é particionado, garantindo isolamento de dados e facilitando políticas de retenção.
  • Memória com curadoria: um agente dedicado consolida, deduplica e atualiza memórias, evitando que o histórico cresça de forma caótica.
  • Separação entre memória e ferramentas: o que é "conhecimento sobre o usuário" não se mistura com o que é "acesso a sistemas externos".

Essa organização é o que sustenta a transição de aplicações baseadas em prompts para sistemas coordenados, nos quais estado e contexto circulam de forma explícita e auditável.

Boas práticas e armadilhas comuns

1. Não confunda histórico com memória. Despejar toda a conversa no estado funciona por um tempo, mas degrada qualidade e custo. Memória útil é memória curada.

2. Defina política de retenção desde o início. Memória de longo prazo armazena dados pessoais. Adequação à LGPD, consentimento e direito de exclusão precisam estar no design, não no backlog.

3. Trate conflitos de memória. Usuários mudam de emprego, de cidade, de preferência. Sem mecanismos de atualização e expiração, o agente "lembrará" de fatos obsoletos com a mesma confiança dos atuais.

4. Meça o custo do contexto. Cada memória recuperada consome tokens. Recuperação sem critério é uma das formas mais silenciosas de encarecer um agente.

5. Use checkpointers para observabilidade. Além de persistência, eles permitem inspecionar execuções passadas — recurso valioso para depurar comportamentos inesperados em fluxos cíclicos.

Conclusão

O LangGraph não "adiciona memória" como um recurso acessório: ele estrutura o problema em duas camadas complementares. A memória de curto prazo, ancorada no estado e nos checkpointers, garante que o agente mantenha coerência dentro de uma sessão — inclusive em fluxos ramificados e cíclicos. A memória de longo prazo, suportada por stores com namespaces e busca semântica, permite que o sistema acumule conhecimento sobre usuários e aplicações ao longo do tempo.

A diferença entre um agente que parece inteligente e um agente que efetivamente é útil em produção raramente está no prompt. Está na qualidade da memória: o que se guarda, quando se guarda, como se recupera e — igualmente importante — o que se decide esquecer. Dominar essa camada é o que separa protótipos impressionantes de sistemas confiáveis.