Memory em agentes: como fazer o Claude lembrar entre sessões

TL;DR: O Claude Code começa cada sessão com contexto zero. Para resolver isso, uso um sistema de memória baseado em arquivos markdown: uma pasta memory/ com um MEMORY.md como índice e arquivos individuais por memória, cada um tipado como user, feedback, project ou reference. O Claude lê o índice em todo turno e busca os arquivos relevantes sob demanda. Simples, auditável e funciona na prática.

---

Toda vez que você abre uma nova sessão no Claude Code, ele esqueceu tudo.

Não tem histórico. Não tem preferências salvas. Não sabe que você passou os últimos três meses construindo um sistema de agentes, que prefere TypeScript com tipos estritos, que detesta comentários óbvios no código ou que tem uma convenção de nomes específica para os seus endpoints.

Você explica de novo. Ele faz errado. Você corrige. Amanhã, repete.

Esse é o problema que qualquer pessoa que usa agentes no trabalho real enfrenta. E resolver isso direito faz uma diferença grande no quanto o agente realmente te ajuda. Junto com a memória, tem outro problema que aparece cedo: o contexto que explode quando você empilha agentes. São dois lados do mesmo problema de estado.

O que é memória de longo prazo em agentes de IA?

Memória de longo prazo em agentes é qualquer mecanismo que persiste informação entre sessões, além do que cabe na janela de contexto atual. Sem isso, o agente opera com amnésia total a cada nova conversa.

Na prática, existem três tipos principais de informação que um agente precisa lembrar: episódica (o que aconteceu em sessões anteriores), semântica (fatos e preferências sobre você e o projeto) e procedimental (como fazer certas coisas, padrões e regras). O sistema que descrevo aqui cobre os três.

Pesquisadores da Machine Learning Mastery descrevem bem essa divisão: memória episódica para experiências passadas, semântica para conhecimento factual e procedimental para rotinas aprendidas. A diferença na prática é que você precisa de mecanismos diferentes para armazenar e recuperar cada tipo.

Como o Claude Code trata memória nativamente?

O Claude Code tem dois mecanismos nativos de memória: arquivos CLAUDE.md, que você escreve com instruções permanentes, e auto memory, que o Claude escreve para ele mesmo durante as sessões. Os dois são carregados no início de cada conversa e se complementam: um para regras estáticas, outro para aprendizados acumulados.

Os dois são complementares, mas têm propósitos distintos.

Os arquivos CLAUDE.md são instruções que você escreve. O Claude os lê no início de cada sessão. Você usa para regras do projeto, convenções de código, comandos de build, arquitetura. São boas para o que não muda com frequência.

O auto memory é diferente: o Claude escreve para ele mesmo, sem você precisar fazer nada. Ele guarda o que aprendeu durante as sessões: atalhos que você prefere, padrões que descobriu, contexto sobre debugging. O arquivo fica em ~/.claude/projects/<projeto>/memory/MEMORY.md, com até 200 linhas ou 25KB carregados por sessão. Detalhes mais extensos ficam em arquivos separados, lidos sob demanda.

Essa arquitetura de duas camadas, índice compacto mais arquivos de detalhe, é exatamente o que inspirou o sistema que construí em cima disso. Aliás, quando o codebase do Claude Code vazou, uma das coisas que ficou evidente foi como o sistema de memória foi projetado com esse princípio desde o início.

Por que não usar banco vetorial ou RAG?

Para memória de agente de desenvolvimento pessoal, banco vetorial adiciona infraestrutura sem retorno claro. Arquivos markdown são auditáveis, editáveis direto no editor e não exigem nenhum serviço externo. A vantagem do banco vetorial aparece quando você tem milhares de entradas e precisa de busca semântica em tempo real. Com dezenas de memórias bem estruturadas, arquivo ganha.

Essa é a pergunta que aparece quando o assunto é memória para agentes. Banco vetorial não seria mais escalável? Para o caso de uso de um agente de desenvolvimento pessoal, não. Os motivos são dois:

Banco vetorial adiciona infraestrutura. Você precisa de uma instância rodando, embeddings atualizados, queries de similaridade configuradas. Para um agente que roda na sua máquina local, isso é overhead sem retorno claro.

Arquivos markdown são auditáveis. Você abre no editor, lê, edita, deleta. Sabe exatamente o que o agente vai encontrar. Com banco vetorial, você confia que a busca por similaridade vai retornar o que é relevante, sem garantia.

A comparação entre file systems e databases para memória de agentes da Oracle mostra que a escolha depende do caso de uso. Para memória estruturada e controlada, sistemas de arquivo funcionam bem. Para escala com milhões de entradas e busca semântica em tempo real, banco vetorial faz mais sentido.

O meu sistema não chega perto de milhões de entradas. São dezenas de memórias, bem estruturadas, fáceis de manter.

O sistema que uso: pasta memory/ com MEMORY.md como índice

O sistema vive em ~/.claude/projects/{projeto}/memory/. Essa é a mesma pasta que o auto memory nativo do Claude Code usa, o que significa que o Claude já sabe onde procurar.

A estrutura é esta:

memory/
├── MEMORY.md              # índice, máximo 200 linhas
├── user_idioma.md         # PT-BR em todo conteúdo
├── feedback_sem-traves.md # nunca usar travessão
├── project_blog-stack.md  # Next.js, posts em _posts/
└── reference_posts-2026.md # links para posts existentes

O MEMORY.md é o índice. O Claude lê ele em todo turno e decide quais arquivos de detalhe buscar com base no que é relevante para a tarefa. Uma linha por memória, no formato:

- [Nome da memória](arquivo.md): descrição de uma linha

Cada arquivo individual tem um frontmatter simples:

---
name: "Nome da memória"
description: "O que essa memória contém"
type: user | feedback | project | reference
---

E então o conteúdo. Direto ao ponto, sem enrolação.

Os quatro tipos de memória

O sistema usa quatro tipos que cobrem casos de uso distintos:

user é o perfil do Thiago. Idioma (PT-BR), tom de voz, preferências de formatação, como ele trabalha. Esse tipo de memória muda pouco e precisa estar disponível em toda sessão.

feedback são correções e validações. Quando o agente faz algo errado e eu corrijo, essa correção vira uma memória de feedback. O formato inclui três campos: a regra em si, o porquê (why) e como aplicar (how to apply). Por exemplo: "nunca use travessão em conteúdo. Por quê: é parte da identidade de escrita do Thiago. Como aplicar: substitua por vírgula, ponto ou parênteses."

project é contexto do projeto atual. Stack técnica, estrutura de diretórios, convenções de nomes, onde ficam os arquivos, como funciona o build. O que um desenvolvedor novo precisaria saber para começar a contribuir.

reference são ponteiros externos. Links para posts existentes no blog, documentação relevante, repositórios de referência. Evita que o agente invente URLs ou ignore conteúdo que já existe.

Como o Claude usa as memórias durante a sessão

O fluxo é simples. No início de cada sessão, o Claude lê o MEMORY.md completo. Com esse índice em mãos, ele sabe o que está disponível.

Quando aparece uma tarefa, ele avalia quais memórias são relevantes. Se estou escrevendo um post do blog, ele busca as memórias de feedback sobre estilo de escrita, as de referência com posts existentes e as de projeto com a estrutura do blog. Se estou ajustando código, ele busca as de projeto com a stack e as de feedback sobre convenções.

Ele só carrega o que é necessário. Isso mantém a janela de contexto limpa. Para isso funcionar, as descrições no índice precisam ser boas o suficiente para o Claude decidir o que buscar sem ler tudo de uma vez.

Esse padrão é o mesmo que o Claude Code usa internamente para o auto memory: índice compacto sempre presente, detalhes sob demanda.

Memórias de feedback: a parte mais valiosa

Das quatro categorias, as memórias de feedback são as que mais mudam o comportamento do agente ao longo do tempo.

A ideia é simples: cada vez que o agente faz algo errado e você corrige, essa correção vai para o sistema de memória. Com o tempo, o agente para de repetir os mesmos erros.

O formato que uso para essas memórias tem três partes obrigatórias:

Regra: o que fazer ou não fazer. Específica, verificável. "Nunca comece parágrafo com 'Eu' como primeira palavra" é melhor do que "escreva bem".

Why: por que essa regra existe. Sem contexto, o agente aplica a regra mecanicamente e quebra quando o caso é ligeiramente diferente. Com o porquê, ele consegue inferir a intenção.

How to apply: exemplos concretos de como aplicar. Mostra o padrão correto, não só o errado.

É o mesmo princípio que descrevi quando o Claude Code construiu este blog: o agente executa bem quando o contrato está claro. Memórias de feedback são parte desse contrato.

O que esse sistema resolve que o CLAUDE.md puro não resolve

O CLAUDE.md tem três limitações práticas: tamanho máximo recomendado de 200 linhas, carregamento total em todo turno independente de relevância, e dificuldade de organizar contexto acumulado ao longo do tempo. A pasta memory/ resolve os três: cresce sem limite, carrega só o necessário e organiza por tipo.

O CLAUDE.md é ótimo para regras estáticas que se aplicam sempre. Mas na prática ele tem limites claros:

Tamanho. A documentação oficial do Claude Code recomenda manter o CLAUDE.md abaixo de 200 linhas. Acima disso, mais contexto é consumido e a aderência cai.

Granularidade. Colocar tudo no CLAUDE.md significa que o Claude carrega todo o contexto em todo turno, mesmo quando não é relevante. Uma sessão focada em código não precisa das memórias de estilo de escrita.

Organização. Com o sistema de tipos (user, feedback, project, reference), fica fácil saber o que está em cada arquivo. O CLAUDE.md vira uma bagunça quando cresce demais.

O sistema de memória complementa o CLAUDE.md: regras universais ficam no CLAUDE.md, contexto específico e acumulado fica na pasta memory/.

Isso é exatamente como uso no sistema de agentes que entrega features enquanto durmo: o CLAUDE.md tem as regras do projeto, a pasta memory/ tem o que foi aprendido ao longo do tempo.

Como começar com o seu sistema de memória

Se você usa o Claude Code e quer implementar algo parecido, o caminho mais direto é:

1. Crie a pasta ~/.claude/projects/{nome-do-projeto}/memory/
2. Crie um MEMORY.md vazio com um cabeçalho simples
3. Comece adicionando memórias de perfil (tipo user) com suas preferências básicas
4. Cada vez que você corrigir o agente, adicione uma memória de feedback com a regra, o porquê e como aplicar
5. Com o tempo, adicione contexto de projeto e referências

A parte mais importante é manter o índice (MEMORY.md) conciso. Uma linha por memória, com descrição boa o suficiente para o Claude decidir o que buscar. Arquivos grandes no índice fazem o oposto do que você quer: consomem contexto sem ajudar.

O sistema não precisa de setup complexo. Começa pequeno e cresce conforme você usa.

Se você quer ver como memória, contexto e custo de tokens se encaixam no workflow completo de produto com IA, tenho um post que cobre exatamente isso: o stack completo que uso como PM.

Se quiser acompanhar como esse sistema evolui, com casos reais e ajustes ao longo do tempo, me segue no LinkedIn e no GitHub onde o sistema de memória está open source.

---

Perguntas Frequentes

O que é o sistema de memory do Claude Code e como ele funciona?

O Claude Code tem dois mecanismos nativos de memória: arquivos CLAUDE.md, que você escreve com regras e contexto permanente, e auto memory, onde o próprio Claude salva aprendizados durante as sessões. Os dois são carregados no início de cada sessão. O auto memory usa uma pasta memory/ com um MEMORY.md como índice e arquivos de detalhe por tópico, carregados sob demanda conforme a necessidade.

Qual a diferença entre CLAUDE.md e o sistema de memory com arquivos markdown?

O CLAUDE.md é para regras estáticas que sempre se aplicam: convenções de código, estrutura do projeto, comandos de build. O sistema de memory/ é para contexto acumulado e dinâmico: correções de comportamento, referências externas, contexto específico de projeto. O CLAUDE.md deve ficar abaixo de 200 linhas. O sistema de memory cresce sem limite, porque só o que é relevante é carregado em cada sessão.

Por que usar arquivos markdown em vez de um banco vetorial para memória de agentes?

Para sistemas de desenvolvimento pessoal, arquivos markdown são mais simples, auditáveis e não precisam de infraestrutura extra. Você lê, edita e deleta memórias diretamente no editor. A busca por similaridade de um banco vetorial é vantajosa quando você tem milhares de memórias e precisa de recuperação semântica sofisticada. Com dezenas de memórias bem estruturadas, a abordagem por arquivo funciona melhor.

O que são memórias de feedback e por que são as mais importantes?

Memórias de feedback registram correções que você fez ao agente: o que estava errado, por que estava errado e como fazer certo. Com o tempo, elas ensinam o agente a parar de repetir os mesmos erros. Cada memória de feedback tem três campos obrigatórios: a regra específica, o porquê (contexto que permite inferir a intenção) e como aplicar (exemplos concretos). São a principal forma de treinar comportamento persistente sem fine-tuning.

Como os quatro tipos de memória (user, feedback, project, reference) se relacionam na prática?

Cada tipo cobre um caso de uso distinto. user armazena perfil e preferências permanentes. feedback acumula correções de comportamento ao longo do tempo. project contém contexto técnico do projeto atual: stack, estrutura, convenções. reference guarda ponteiros externos como links de posts existentes ou documentação relevante. Na prática, uma sessão de escrita de post usa principalmente user, feedback e reference. Uma sessão de código usa principalmente project e feedback.