Agentes de IA precisam de documentação estruturada, não de memória vetorial

A crítica aos plugins de memória

Kevin Liao argumenta que todo o ecossistema de plugins de memória para agentes de IA resolve o problema errado. Segundo ele, esses plugins funcionam da mesma forma: analisam transcrições de sessões, geram snippets de "memórias", inserem em um banco vetorial (RAG) e, a cada prompt, recuperam e injetam os cinco snippets mais similares, além de oferecer uma ferramenta de busca no banco.

O autor lista problemas estruturais dessa arquitetura:

• Memórias aparecem por similaridade: a busca mede proximidade no espaço de embeddings, sem indicar o que é correto, atual ou o que falta.
• Armazenamento sem contexto: um snippet perde motivações, lições, ambiente e contexto ao redor.
• O passado é tratado como verdade: o código muda todos os dias, e a precisão de centenas de snippets sobre autenticação, por exemplo, é questionável.
• O agente não busca o que não sabe que existe: mesmo com ferramenta de busca, não sabe quando usá-la.
• O armazenamento é inaudível: com milhares de embeddings, não há visibilidade de quais memórias existem, estão obsoletas, nunca foram recuperadas ou estão incorretas.

Para Liao, a tese comum dos plugins - "agentes esquecem, então precisam lembrar melhor, capturando mais e indexando melhor" - não reflete como pessoas lidam com conhecimento: ninguém reverte uma reunião de três anos atrás para lembrar restrições de uma funcionalidade; escreve-se documentação. Recursos extras (memória de curto e longo prazo, "dreamers" que reescrevem memórias, compressão contínua, rerankers) seriam tentativas de consertar com mais tokens uma arquitetura falha.

Documentação em vez de recall

A proposta é memória baseada em documentos. O autor reconhece que arquivos como AGENTS.md já atendiam à necessidade de contexto, mas aponta que frequentemente esse único arquivo é toda a documentação do projeto. Em vez disso, o agente precisaria de um "cérebro": um workspace estruturado com instruções, especificações, decisões, pesquisas e índices, sem que o usuário precise pedir.

O ciclo agentic mudaria de "prompt → construir → esquecer" para "prompt → consultar → construir → atualizar": antes do trabalho, o agente lê os documentos relevantes; depois, atualiza o que ficou obsoleto e adiciona o que falta, enquanto o quadro completo ainda está no contexto. A memória deixa de ser um banco RAG acoplado e vira um workspace legível, atualizável e compartilhável com o time.

A implementação do autor

Liao relata que identificou o problema há mais de um ano, quando começou a programar com IA, criando uma pasta internal/ para o agente registrar especificações, planos e índices e sempre consultá-los antes e atualizá-los depois do trabalho. Essas instruções evoluíram para um sistema formal e depois para o plugin Operator Memory, que ele usa regularmente em todos os projetos.

O Operator Memory implementa memória documental: um "cérebro" em Markdown onde o agente persiste instruções, specs, pesquisas e índices, consultando-o antes e atualizando-o após cada tarefa. Sem banco vetorial, embeddings, resumidores ou processos em segundo plano - tudo são documentos Markdown simples que podem ser lidos, atualizados, commitados e compartilhados. O autor diz usar o sistema há mais de um ano e disponibiliza o plugin gratuito e open source no GitHub.