Agentes precisam de memória verificada, não de todo o histórico: como construir o contexto

Quando o Claude Code foi bloqueado de repente, o autor de uma análise no Habr migrou para o Codex e encontrou um problema desagradável: o código continuava no disco, mas meses de conversas sobre arquitetura, bugs e experimentos descartados ficaram presos na ferramenta anterior. Entre 25 projetos e 53 conversas, o importador nativo transferiu cerca de 50 sessões, ainda por cima com associações incorretas aos projetos. Depois surgiu um debate nos comentários que se mostrou mais interessante do que a própria migração.

O debate era sobre tarefas diferentes

Alguns diziam para guardar decisões e planos no Git e que o histórico de conversas era lixo. Outros sugeriam skills, bases de conhecimento e especificações. Outros lembravam que o estado interno de raciocínio de um modelo não pode ser transferido entre provedores. Todos tinham razão: estavam apenas resolvendo tarefas diferentes.

A primeira tarefa é dar ao agente uma compreensão atualizada do projeto. Para isso, bastam AGENTS.md ou CLAUDE.md, documentação atualizada, ADRs, planos de trabalho e testes. Bases de código maiores também precisam de navegação: o Aider Repo Map, por exemplo, cria um mapa compacto do projeto dentro do orçamento de tokens. A segunda tarefa é recuperar a experiência anterior: o que foi tentado, o que foi descartado e por quê. A terceira é retomar um trabalho interrompido quando o limite foi atingido no meio do caminho e ninguém escreveu um HANDOFF.md.

O Git, por si só, não é memória. É controle de versão, e seu valor depende do que você coloca nele e de quanto esse material está atualizado.

Um exemplo: erro de TUN no Windows

O autor desenvolve o NetRuleRouter, um aplicativo de roteamento de tráfego. Ao investigar o erro 5010 do TUN no Windows, o agente descobriu pelo Hansard que o notebook de testes TUF era uma máquina Windows separada com uma cópia local do repositório. Esse tipo de informação não cabe na documentação de arquitetura, mas economiza tempo no diagnóstico. O autor faz uma ressalva honesta: ainda não mediu se o Hansard acelerou a correção.

Entre as ferramentas semelhantes está o deja-vu, que indexa os logs de agentes de programação e permite retomar trabalhos inacabados, buscar sessões por arquivo e marcar soluções descartadas. Já o baton transfere sessões entre agentes de linha de comando quando o anterior não consegue mais responder.

A memória custa dinheiro e comete erros

Em um experimento com o MemShelf, no 38º dia o índice e os resumos de 157 episódios ocupavam cerca de 36,6 mil tokens, ou 18,3% de uma janela de 200 mil. Em outro período de 30 dias, o autor não encontrou nenhuma chamada às ferramentas de memória MCP. Os desenvolvedores do kaeru, depois de analisar mais de 13 mil arquivos de log, observaram algo semelhante: em uma pequena amostra de observação, os agentes não abriram os raciocínios salvos nenhuma vez ao longo de sete sessões. As amostras são pequenas, mas o problema é claro: a memória fica sem uso ou é inserida com frequência demais, poluindo o contexto.

Há também um risco mais grave. Um agente registra uma conclusão errada como experiência; outro a lê e a aceita como fato verificado. Uma conversa antiga pode conter instruções de uma fonte não confiável. Se o agente começar a executá-las, o arquivo se torna um canal para comandos de terceiros.

O que fazer na prática

O fluxo de trabalho proposto é simples: encontrar a informação, determinar seu status, conferir se continua válida, aplicá-la e verificar o resultado, e registrar o que foi obtido.

• Trate uma conversa recuperada como dados do passado, não como uma nova instrução.
• Identifique a fonte e a data, além de determinar se era uma hipótese, um resultado confirmado ou uma opção descartada.
• Confira a informação com o código, os testes e a documentação atuais.
• Registre o que foi verificado em um plano, ADR ou base de conhecimento.

O arquivo guarda evidências do passado; a base de conhecimento contém aquilo em que o projeto pode se apoiar agora. Ela também envelhece, por isso o conhecimento atual precisa ser conferido com uma fonte independente: código, testes ou resultados de execução.

Para um utilitário pequeno, AGENTS.md e testes bastam; grafos complexos de especificações são excessivos. Para um projeto grande com vários agentes, faz sentido considerar um supervisor separado, como faz na prática um dos comentaristas, e rótulos de confiabilidade para os registros. Para entender se a memória ajuda, avalie mais do que se algo foi encontrado: examine as capacidades do LongMemEval (ICLR 2025), como encontrar informações, conectar várias sessões e levar o tempo em conta.

Um último ponto: o autor estudou a maioria das ferramentas por meio de documentação e publicações, sem testes comparativos. Trate a análise como um mapa do cenário, não como um ranking.