CLAUDE.md vs. um MCP de memória: o que vai onde

Se você usa Claude Code ou Cursor para trabalho real, você já tem um CLAUDE.md (ou um AGENTS.md, ou um .cursorrules). Você anotou o comando de construção, o "nós usamos pnpm, não npm", o layout da pasta, a única coisa estranha sobre o fluxo de autenticação. E funciona. O agente lê isso no início de cada sessão e para de cometer os mesmos três erros.

Então, quando alguém aparece dizendo "adicione um servidor de memória MCP ao seu agente", a reação honesta inicial é: por quê? Eu já tenho um arquivo que o agente lê. Essa é uma pergunta justa. Este post responde isso adequadamente — incluindo os casos em que a resposta honesta é "você ainda não precisa de um."

Divulgação desde o início: eu construo um desses (Kireo — mais no final). Então leia isso como um construtor tentando não exagerar, não como uma pesquisa neutra. Mas a estrutura abaixo é a que eu realmente uso para decidir o que vai em um arquivo markdown e o que vai em um armazenamento de memória, e ela se aplica não importa qual armazenamento você use.

A única distinção que importa: quem escreve e com que frequência muda

Aqui está a divisão que sobreviveu ao contato com projetos reais:

CLAUDE.md é para fatos estáveis que um humano curadoria. "Execute pnpm --filter api test. A API se comunica com Postgres e Redis. Não toque em generated/." Você digitou isso. Você os relê quando eles desviam. Eles mudam talvez uma vez por mês.

Um armazenamento de memória é para fatos dinâmicos que um agente acumula. "Tentei agrupar o upload da incorporação em 500 símbolos por solicitação — o serviço de incorporação trava em lotes tão grandes, então limitei a 100." Ninguém edita isso manualmente em CLAUDE.md. O agente encontrou isso na terça-feira, e até quinta-feira, em uma nova sessão, simplesmente desapareceu — a menos que algo o anotasse.

O teste que uso: eu abriria o arquivo e digitava isso manualmente? Se sim, é um fato de CLAUDE.md. Se é um subproduto do trabalho — uma decisão, um beco sem saída, um "nós tentamos X e isso quebrou Y" — precisa de um armazenamento de memória, porque você nunca voltará para curá-lo em markdown.

Você não precisa de um MCP de memória ainda se…

Eu preferiria que você não adicionasse um servidor que não precisa, então aqui está a lista de verificação honesta. Se todos esses forem verdadeiros, um CLAUDE.md bem mantido é suficiente, e adicionar infraestrutura é apenas sobrecarga:

• Um projeto. Seu contexto ainda se encaixa, e um arquivo o descreve.
• Uma ferramenta. Você vive no Claude Code, ou apenas no Cursor — não em ambos.
• Uma máquina. Mesmo laptop, mesma configuração, todos os dias.
• Pequeno volume curável. Os fatos estáveis são poucos o suficiente que você está feliz em mantê-los manualmente, e você raramente encontra "o agente resolveu exatamente isso na semana passada e eu não consigo recuperá-lo."

Se esse é você, feche esta aba e mantenha um bom CLAUDE.md. A maioria dos projetos solo e de repositório único se encaixa aqui, e não há nada a corrigir. Um armazenamento de memória é uma ferramenta para um problema que você pode não ter ainda.

Quando o arquivo deixa de ser suficiente

Quatro gatilhos movem a agulha. Quando você os atinge, um arquivo estático começa a perder:

1. Múltiplas ferramentas. Você começa uma funcionalidade no Claude Code, depois pula para o Cursor para a interface. Duas ferramentas, dois arquivos separados no estilo CLAUDE.md, e o contexto que você construiu em um é invisível para o outro. Como o MCP é um protocolo aberto, um servidor de memória que ambas as ferramentas falam significa um único armazenamento: escrito pela ferramenta em que você estava, legível pela outra.

2. Múltiplas máquinas. Laptop mais desktop mais uma caixa de desenvolvimento na nuvem. Um arquivo por máquina rapidamente desvia. Um armazenamento é um lugar, acessível de todas elas.

3. Contexto compartilhado pela equipe. Um CLAUDE.md no git é compartilhado — mas compartilha fatos estáveis que você concordou em se comprometer. O acumulado "nós tentamos X, quebrou Y" é exatamente o que o agente de um novo colega de equipe se beneficiaria, e exatamente o que ninguém escreve no markdown comprometido. Um namespace compartilhado em um armazenamento carrega o longo rabo que nunca chega ao arquivo.

4. Volume além da curadoria manual. Além de um certo tamanho, CLAUDE.md se torna uma parede de texto que consome contexto em cada sessão, independentemente de qualquer linha ser relevante hoje. Um armazenamento inverte isso: nada é carregado até que o agente execute uma busca e traga de volta os poucos resultados que realmente precisa. Se nunca pesquisar, isso não custa zero contexto.

Esse último ponto é a verdadeira diferença mecânica. Um arquivo é carregado. Um armazenamento é consultado. Um está sempre no seu orçamento de contexto; o outro está lá apenas quando o agente pede.

"Mas o Claude Code já tem memória automática"

Tem, e é genuinamente útil — eu uso. Mas tem uma forma que vale a pena entender antes de você assumir que cobre o mesmo terreno.

• É seletivo por design. O agente decide o que vale a pena persistir. Esse é o padrão certo — você não quer cada pensamento aleatório lá — mas isso significa que a memória é sempre apenas um subconjunto do que aconteceu. E você não pode pesquisar o que ele decidiu não anotar. Se ele nunca registrou o teto de OOM, não há nada para recordar mais tarde; você redescobre isso da maneira difícil.
• É por ferramenta. A memória do Claude Code pertence ao Claude Code. O Cursor não a lê.
• É um arquivo que carrega no contexto, não uma consulta. Mecanicamente, é mais próximo de CLAUDE.md do que de um armazenamento pesquisável: presente, relevante ou não, em vez de puxado sob demanda.

Nada disso o torna ruim. Isso o torna a camada fatos estáveis mais um pouco, não a camada de acumulação pesquisável entre ferramentas. As duas coexistem felizmente: deixe o Claude Code continuar gerenciando seu arquivo, e deixe um armazenamento de memória manter o longo rabo pesquisável que abrange suas ferramentas e máquinas.

Se você decidir que quer a camada pesquisável

Aqui está como isso se parece na prática, mantido curto e factual em vez de vendido.

O agente recebe um memory_save e um memory_search, além de memory_recall, memory_get, memory_update, memory_delete, memory_list_namespaces, e memory_health — oito ferramentas no total. Ele salva uma decisão ou uma armadilha quando julga que vale a pena manter; mais tarde, em qualquer cliente MCP, ele pesquisa e obtém os poucos resultados principais de volta. Como é um servidor MCP, "qualquer cliente" inclui tanto o Claude Code quanto o Cursor lendo e escrevendo o mesmo armazenamento.

Duas coisas que insisti, porque são as partes que me deixam nervoso como usuário de ferramentas de memória de outras pessoas:

• Tudo é visível. Há um painel da web onde você pode ler, editar e excluir cada memória. Não é uma caixa-preta acumulando silenciosamente quem-sabe-o-quê.
• Tudo exporta. Dump completo em JSON a qualquer momento — sem bloqueio. Se a ferramenta decepciona você, você sai com todos os seus dados.

Sobre privacidade, já que geralmente é a próxima pergunta: o armazenamento mantém o texto da memória que suas ferramentas enviam explicitamente, além de seus metadados (namespace, tags, timestamps); o índice de código mantém embeddings derivadas e caminhos de arquivos, nunca seus dados.