Seu Agente Esquece Tudo: Comparando Memória por Arquivos, Vetores e MCP

No mês passado, vi o Claude Code redescobrir, pela quarta vez, que meu projeto usa pnpm e não npm. Ele rodou npm test, viu falhar, pediu desculpas e tentou novamente com pnpm. Eu havia explicado isso em três sessões anteriores. Nenhuma sobreviveu. O agente não carrega nada entre execuções, a menos que eu force isso.

Esse é o problema todo. Um agente de codificação é sem estado entre execuções. Cada sessão começa com uma janela de contexto vazia. Tudo que ele descobriu ontem — seus comandos de build, por que um teste é instável, o fato de que o banco de dados de staging reseta à meia-noite — desapareceu. Você re-explica, ele re-deriva, ambos desperdiçam tokens.

Então você dá memória a ele. E no momento em que você começa a procurar, encontra três coisas diferentes todas chamadas "memória", e a maior parte do que se escreve sobre elas é ou um discurso de vendedor ou um tutorial que não te diz quando a abordagem vai falhar.

A versão curta: para um desenvolvedor solo, arquivos simples são o padrão e você deve esgotá-los antes de adicionar qualquer coisa. Armazenamentos vetoriais merecem seu lugar quando você está pesquisando um grande corpus que não cabe no contexto. Servidores de memória MCP são os mais flexíveis e os mais fáceis de envenenar silenciosamente. A maioria das pessoas vai primeiro para o mais sofisticado. Isso é ao contrário.

O que "memória" realmente significa aqui

As três opções não são implementações concorrentes da mesma coisa. Elas resolvem problemas diferentes e falham de maneiras diferentes.

Arquivos simples são markdown ou texto que o agente lê na inicialização — CLAUDE.md, AGENTS.md, um rascunho NOTES.md. Você ou o agente os escreve, e eles são carregados no contexto a cada sessão. Sem pesquisa, sem embeddings — apenas "leia este arquivo primeiro."

Armazenamentos vetoriais transformam texto em embeddings e permitem que o agente recupere por significado em vez de por nome de arquivo. Você escreve algo uma vez, o armazenamento encontra o trecho relevante mais tarde, mesmo que as palavras não correspondam.

Servidores de memória MCP são processos separados com os quais o agente se comunica pelo Model Context Protocol, que expõe ferramentas, recursos e prompts para qualquer host compatível. Um servidor de memória adiciona ferramentas como "armazenar este fato" e "pesquisar minha memória" que o agente chama durante uma tarefa.

Já coloquei em produção os três. Aqui está a leitura honesta de cada um.

Arquivos: chato, barato e o padrão correto

A memória em arquivos é a que você já tem. O Claude Code lê o CLAUDE.md no início de cada sessão, carregado integralmente como uma mensagem de usuário após o prompt do sistema — não como configuração imposta, o que importa, porque o agente ainda pode ignorá-la. Os arquivos são carregados a partir de uma hierarquia: um arquivo gerenciado de toda a organização, seu ~/.claude/CLAUDE.md pessoal, o ./CLAUDE.md do projeto e um CLAUDE.local.md no .gitignore, ordenados do mais amplo ao mais específico para que a instrução mais próxima seja lida por último.

Há também memória automática: o Claude escreve suas próprias notas em ~/.claude/projects/<project>/memory/MEMORY.md, e as primeiras 200 linhas (ou 25KB) desse arquivo são carregadas a cada sessão. Ele salva comandos de build e insights de depuração que descobre, sem que você os digite. Eu deixo ativo; ele capturou alguns fatos do tipo "ah, é verdade, os testes de API precisam de um Redis local" que eu teria re-explicado de outra forma.

Não vou recapitular o que colocar em um CLAUDE.md — escrevi um post inteiro sobre isso. O ponto aqui é arquitetural: arquivos são bons em exatamente uma coisa, e é a coisa que a maioria dos agentes precisa — um conjunto pequeno e curado de fatos que devem ser verdadeiros em cada sessão.

No que arquivos são bons:

• Zero infraestrutura. É um arquivo de texto no seu repositório. Versionado, diferenciável, revisável em um PR.
• Você pode ler sua própria memória. Quando o agente faz algo bobo, você abre o arquivo e vê exatamente o que foi dito a ele. Tente fazer isso com um embedding.
• Sobrevive. O CLAUDE.md na raiz do projeto até é re-injetado após um /compact, então uma sessão longa não o perde.

No que arquivos são ruins:

• Custam tokens em cada requisição. Tudo no CLAUDE.md está na sua janela de contexto durante toda a sessão. A documentação diz que o alvo é menos de 200 linhas, e eles estão certos — além disso, a aderência cai e você está pagando por instruções que o agente folheia.
• Sem recuperação. Você não pode manter mil fatos em um arquivo que o agente lê toda vez. É um conjunto de trabalho, não um banco de dados.
• A desatualização é sua responsabilidade. Se seu comando de build mudar e você esquecer de atualizar o arquivo, o agente executa o antigo com confiança. O arquivo não sabe que está errado.

Para a maioria dos projetos solo, os arquivos são suficientes. Já lancei produtos onde CLAUDE.md mais memória automática era o sistema de memória inteiro e nunca quis mais.

Armazenamentos vetoriais: boa recuperação, sem julgamento

Quando o que você quer lembrar é grande demais para caber em um arquivo que o agente lê toda vez — um ano de decisões de arquitetura, uma grande wiki interna, cada bug passado e sua correção — você passa para a recuperação. Um banco de dados vetorial armazena embeddings de alta dimensionalidade do seu texto e encontra as correspondências mais próximas para uma consulta por significado, tipicamente em dezenas de milissegundos.

Você não precisa de um banco de dados vetorial dedicado para começar. Se você já roda Postgres, o pgvector adiciona armazenamento e pesquisa vetorial ao banco de dados que você já tem, o que geralmente é o primeiro passo certo para um desenvolvedor solo. O padrão de 2026 é pesquisa híbrida — palavra-chave mais vetor — porque a pesquisa semântica pura perde casos de correspondência exata como um nome de função específico ou código de erro.

No que armazenamentos vetoriais são bons:

• Recuperação em escala. Este é o único dos três que lida com "eu tenho dez mil notas, encontre as três relevantes." Arquivos não conseguem e servidores de grafo MCP têm dificuldades.
• Significado acima das palavras. Você escreveu "o fluxo de checkout cobra em dobro no retry", você pergunta mais tarde "por que o pagamento dispara duas vezes", e ele encontra a nota. A pesquisa por palavra-chave não encontraria.

No que armazenamentos vetoriais são ruins:

• A qualidade da recuperação é um pipeline, não uma configuração. Modelo de embedding, estratégia de chunking, tipo de índice e cadência de atualização todos interagem. Errar o chunking e você recupera metade de um pensamento. Este é um trabalho real, e é um trabalho que a maioria dos desenvolvedores solo subestima.
• Sem noção de verdadeiro. Um armazenamento vetorial retorna o que é similar, não o que é correto ou atual. Se você armazenou um fato em março e a verdade mudou em maio, ambas as versões ficam no índice e a de março pode vencer por similaridade.
• É uma superfície de envenenamento. Qualquer coisa que alimenta o armazenamento — uma página web que o agente indexou, um documento que alguém colocou em uma pasta compartilhada — pode plantar texto que é recuperado mais tarde como contexto autoritativo. Mais sobre isso abaixo.

Recorro a um armazenamento vetorial quando o corpus é genuinamente grande demais para o contexto e preciso de recuperação. Para "lembre-se das minhas cinco convenções de projeto", é excessivamente elaborado.

Servidores de memória MCP: flexíveis, estruturados e uma superfície de ataque maior

A terceira opção é um servidor de memória que você conecta via MCP. O de referência é o servidor de memória em grafo de conhecimento da Anthropic. Ele modela a memória como um grafo: entidades (nós nomeados com um tipo), relações (conexões direcionadas em voz ativa entre elas) e observações (fatos atômicos anexados a uma entidade). Persiste em um arquivo memory.jsonl local e expõe ferramentas como create_entities, add_observations, search_nodes e read_graph.

O argumento é que estrutura supera um blob simples. "O usuário prefere pnpm" se torna uma observação em uma entidade Usuário, relacionada a uma entidade Projeto, e o agente percorre isso em vez de fazer grep em prosa. Na prática, fica entre arquivos e vetores: mais consultável que um arquivo de texto, mais interpretável que um embedding.

Vale saber: a própria ferramenta de memória da Anthropic é um mecanismo diferente — uma ferramenta do lado do cliente onde o modelo emite comandos view, create, str_replace, delete contra um diretório /memories e você implementa onde os bytes ficam. Seu prompt de sistema diz ao modelo "ALWAYS VIEW YOUR MEMORY DIRECTORY BEFORE DOING ANYTHING ELSE... your context window might be reset at any moment." Isso diz algo: mesmo a "ferramenta de memória" da Anthropic são arquivos por baixo.

No que servidores de memória MCP são bons:

• Recuperação estruturada sobre a qual o agente pode raciocinar. A travessia de grafo responde "o que eu sei sobre este projeto" com mais precisão do que uma pesquisa por similaridade.
• Portabilidade. O MCP é um padrão, então o mesmo servidor funciona no Claude Code, Cursor e qualquer host compatível. Uma memória, muitas ferramentas.
• Escritas explícitas. O agente decide o que vale armazenar como uma observação discreta, o que mantém a memória mais limpa do que despejar transcrições inteiras em um índice vetorial.

No que servidores de memória MCP são ruins:

• Configuração e um processo em execução. É mais uma peça móvel para instalar, configurar e manter ativa. Para um projeto, é muita cerimônia.
• O grafo deriva. Sem disciplina, você obtém entidades duplicadas ("Projeto", "o projeto", "meu app") e observações contraditórias. A estrutura que deveria ajudar agora precisa de manutenção.
• É o mais fácil de envenenar. Persistente, gravável, recuperado como autoritativo — esse é o perfil exato que os atacantes visam.

Os dois modos de falha que ninguém coloca na página de destino

Todo post de "dê memória ao seu agente" vende o lado positivo. Aqui estão os dois que me morderam.

Envenenamento de memória. Este é o que você deve levar a sério. Ao contrário de uma injeção de prompt, que morre quando a sessão fecha, o envenenamento de memória é um ataque de persistência — uma instrução maliciosa plantada em seu armazenamento hoje executa semanas depois, acionada por uma tarefa não relacionada. O ataque e seu efeito são temporalmente desacoplados. Qualquer pipeline que escreve na memória é um ponto de entrada: uma página web que o agente indexou, o README de uma dependência que ele resumiu, um documento compartilhado. Armazenamentos vetoriais e servidores MCP estão ambos expostos porque ambos ingerem conteúdo automaticamente e o servem de volta como contexto confiável. Arquivos são o seguro, precisamente porque um humano os escreve e pode lê-los em um diff.

Fatos obsoletos substituindo a realidade. Menos dramático, mais comum. Sua memória diz que o nível de preço é $20. Foi para $25 na semana passada. O agente puxa o fato em cache sem verificação de prazo de validade e serve o número antigo como autoritativo. O agente não tem como saber que a página mudou uma hora atrás. Todo sistema de memória tem esse problema, e quanto mais "automático" o sistema, pior fica, porque ninguém está observando o que foi escrito. Já lancei um valor de configuração errado exatamente dessa forma. A memória estava confiante. A memória estava errada.

A verdade desconfortável: quanto mais você automatiza a memória, menos você percebe quando ela está mentindo para você. Arquivos são chatos de manter manualmente, e esse aborrecimento também é a auditoria.

O que eu realmente rodaria como desenvolvedor solo

Comece com arquivos. CLAUDE.md para os fatos que você fica re-explicando, memória automática ativa para que o agente capture o resto. Isso cobre a maior parte do que um projeto solo precisa, não custa nada para configurar e você pode ler cada byte. Não adicione um segundo sistema até que os arquivos visivelmente falhem — e "falhar" significa um sintoma específico: o agente não consegue encontrar uma decisão que você sabe que escreveu, ou seu CLAUDE.md ultrapassou 200 linhas de coisas que só importam às vezes.

Quando isso acontecer, faça uma pergunta: o problema é recuperação ou estrutura? Se você tem um grande corpus e o agente não consegue encontrar a parte certa, é recuperação — adicione um armazenamento vetorial, comece com pgvector se você já está no Postgres e use pesquisa híbrida. Se você quer que o agente raciocine sobre relacionamentos entre sessões e está trabalhando em múltiplas ferramentas, é estrutura — um servidor de memória MCP justifica seu custo de configuração.

Seja qual for a adição, trate a memória como algo que pode estar errado. Coloque uma data nos fatos que expiram. Leia periodicamente o que foi escrito — o comando /memory do Claude Code mostra exatamente isso para arquivos, e é markdown simples que você pode editar ou excluir. Nunca deixe um pipeline automatizado escrever na memória a partir de uma fonte que você não colaria no seu próprio terminal.

O agente esquecer tudo é irritante. O agente lembrar com confiança algo falso é pior. Escolha a memória mais simples que resolve seu problema real e mantenha-a pequena o suficiente para que você ainda possa dizer quando está errada.