Construindo um Sistema de Memória para Agentes de IA

Como a maioria dos usuários de agentes de IA como Claude Code, fiquei frustrado com o problema da memória do agente. Os modelos melhoraram muito e não perdem mais o foco em uma conversa longa como costumavam fazer, mas entre as sessões a memória é bastante irregular, seja em uma conversa com um LLM onde ele recorda dados imperfeitos ou irrelevantes de chats anteriores, ou em uma nova sessão do Claude Code onde sinto que é o Dia da Marmota, integrando um novo funcionário que é inteligente e talentoso, mas não sabe nada sobre o meu mundo. Então, comecei a investigar os vários sistemas de memória. Tentei uma pasta de arquivos markdown, cofres do Obsidian, etc., mas todo sistema de memória de IA que experimentei tinha o mesmo problema: despejar texto em um armazenamento vetorial, recuperar por similaridade cosseno, esperar pelo melhor.

Funciona bem para "sobre o que conversamos na semana passada?" mas desmorona no momento em que você precisa de um raciocínio real, como quando os fatos se contradizem, quando a resposta requer conectar informações de três conversas diferentes, ou quando o usuário pergunta "o que mudou desde janeiro?"

Então, eu construí Memento, um sistema de memória de gráfico de conhecimento bitemporal para agentes de IA. Depois, eu o coloquei através do melhor benchmark de memória de longo prazo que consegui encontrar, LongMemEval. Esta é a história do que funcionou, do que não funcionou e do que aprendi ao longo do caminho.

O Problema com a Memória de Armazenamento Vetorial

A maioria das memórias de IA se parece com: o usuário diz algo, você o incorpora em um vetor, armazena e depois incorpora uma consulta para encontrar os vizinhos mais próximos e coloca os resultados em um prompt. Isso é basicamente uma busca de documentos e não tem conceito de entidades, por exemplo, quando "John" e "John Smith" são dois pedaços diferentes. Não tem consciência do tempo, então um fato de janeiro parece o mesmo que um de ontem. E não tem capacidade de detectar quando novas informações contradizem informações antigas.

Eu queria uma memória que pudesse rastrear entidades, tempo e contradições.

O que Memento Faz de Diferente

Memento constrói um gráfico de conhecimento a partir de conversas. Quando você ingere texto, ele extrai entidades e suas propriedades (pessoas, organizações, projetos), e depois as resolve em relação a entidades existentes — "John", "John Smith" e "o VP de vendas" se tornam um único nó usando correspondência em camadas: exata, difusa, fonética, depois similaridade de incorporação, e então um desempate de LLM. Ele detecta contradições — se o título de John era "VP de Vendas" e agora é "SVP de Vendas", isso é sinalizado. Ele rastreia o tempo bitemporalmente, registrando tanto quando um fato era verdadeiro no mundo quanto quando o sistema o aprendeu. Também armazena texto literal como fallback — a conversa bruta está sempre lá via FTS5 e busca vetorial, então erros de extração não significam perda de informação.

Quando você recorda informações, ele não apenas busca vetores. Ele percorre o gráfico: "O que eu deveria saber antes da minha reunião com John?" encontra o nó de John, percorre suas relações com a Alpha Corp, encontra a aquisição pendente da Alpha Corp e compõe um briefing — tudo dentro de um orçamento de tokens que você especifica.

   Agente / LLM
         │ (Consulta/Ingestão)
         ▼
  Motor de Recuperação  <───>  Pipeline de Ingestão
         │                     │
         ▼                     ▼
    Gráfico de Conhecimento Temporal (SQLite)
         │
         ├── Motor de Consolidação (decair, deduplicar, podar)
         ├── Fallback Verbatim (FTS5 + busca vetorial)
         └── Camada de Privacidade (exportar, auditar, exclusão permanente)

Encontrando um Benchmark

Eu queria avaliar em exemplos sólidos. Encontrei LongMemEval, um benchmark especificamente projetado para memória conversacional de longo prazo. Ele tem 500 perguntas em cinco categorias de dificuldade crescente:

Recordação de sessão única — fatos declarados pelo usuário ou assistente em uma conversa. Rastreamento de preferências — aplicando preferências do usuário reveladas em conversas passadas. Raciocínio de múltiplas sessões — sintetizando informações espalhadas por várias conversas. Atualizações de conhecimento — retornando o valor mais recente quando os fatos mudam ao longo do tempo. Raciocínio temporal — entendendo quando os eventos aconteceram e sua ordem cronológica.

Cada pergunta vem com sessões de feno (as conversas contendo a resposta) e uma resposta de referência. Um juiz GPT-4o compara a saída do sistema com a referência. Todas as execuções usaram Claude Sonnet como a base de extração e raciocínio, com GPT-4o como o juiz de avaliação (seguindo a metodologia do artigo LongMemEval). Cada pergunta também tem uma variante de abstenção onde a resposta correta é "não sei" que testa se o sistema não alucina.

Eu executei contra a variante oracle: sessões apenas com evidências sem distrações, de 1 a 6 sessões por pergunta. Um teste limpo de se o sistema pode extrair e raciocinar sobre informações que definitivamente tem acesso.

Primeiro Contato — 91.0%

Eu acabei de tornar o Memento de código aberto e ainda não tinha um suporte de benchmark. Eu escrevi um, executei um teste rápido de 5 perguntas (5/5, apenas checando a parte técnica), e então iniciei uma execução completa de 500 perguntas.

Mas antes daquela execução, já havia identificado duas lacunas.

A lacuna do timestamp. O Memento não tinha como saber quando uma conversa aconteceu. Para perguntas de raciocínio temporal como "qual aconteceu primeiro, X ou Y?" o sistema estava adivinhando. Correção: canalizar datas de sessão na ingestão como timestamps e adicionar cabeçalhos [Data da conversa: ...] ao texto.

A lacuna de busca literal. O Memento estava ingerindo cada sessão como um grande bloco de texto. Se um usuário perguntasse sobre uma frase específica, o FTS5 estava buscando em sessões concatenadas inteiras em vez de turnos individuais. Correção: armazenar cada turno individualmente no armazenamento literal para busca de palavras-chave detalhada, enquanto ainda ingere sessões completas para extração de entidades.

A primeira execução completa retornou 455/500 — 91.0% no total, 92.4% em média por tarefa.

Perguntas de sessão única estavam quase perfeitas. Múltiplas sessões com 85.0% foram o elo mais fraco.

A Armadilha da Recuperação — 89.6%

A intuição natural: múltiplas sessões estão fracas, então dê mais contexto. Eu ampliei a janela de recuperação — top_k de 10 para 20, limite de conversação de 5 para 10, orçamento de tokens de 4K para 8K. Também adicionei algumas melhorias no prompt: não pergunte questões de esclarecimento para consultas de preferência, enumere antes de contar.

A execução completa de 500 perguntas retornou: 89.6% no total, 91.0% em média por tarefa. Uma regressão. A recuperação mais ampla prejudicou a precisão da sessão única em 4 a 6 pontos percentuais devido à diluição do contexto, enquanto apenas ajudou a múltiplas sessões em +0.7%. Quando você despeja 8K tokens de contexto vagamente relacionado em um prompt, o LLM fica confuso e começa a duvidar de si mesmo.

Lição: mais recuperação não é melhor recuperação.

Eu revertei a ampliação da recuperação, mas mantive as melhorias no prompt e executei novamente. 91.2% no total, 92.4% em média por tarefa — o melhor resultado até agora. As mudanças no prompt sozinhas estavam fazendo a diferença.

Retornos Decrescentes — 86.0% → 90.8%

Em seguida, corrigi cinco bugs (referências de conflito, idempotência...