Sistema de Memória (Memory): Fazendo o Claude Lembrar de Você Entre Sessões

📚 Navegação da Série: O artigo anterior [24 Plugins (Plugins)] ensinou você a empacotar um conjunto de configurações avulsas em um plugin de ativação com um clique. Este artigo abordará um recurso mais fundamental—como fazer o Claude lembrar de você entre sessões. Isso inclui não apenas o arquivo CLAUDE.md escrito manualmente, mas também o "bloco de notas pessoal" que ele constrói autonomamente; basta você corrigi-lo uma vez, e ele registrará a informação silenciosamente para utilizá-la na próxima sessão.

Primeiro, vejamos um erro muito comum cometido por iniciantes.

Ao descobrir a capacidade do Claude de memorizar informações, é comum que os desenvolvedores queiram salvar tudo: um número de porta que acabou de funcionar, uma alteração de variável temporária ou até mesmo instruções de uso único como "desta vez use a porta 8081 em vez da 8080". O raciocínio costuma ser de que "quanto mais ele lembrar, mais inteligente ele será".

O resultado? Duas semanas depois, ao abrir o projeto, ele sugere a porta 8081 que já foi desativada há muito tempo, além de preferências obsoletas que você nem lembra o motivo de ter configurado. Ele acumulou uma série de dados inúteis que acabou soterrando o que realmente importava.

Nesse ponto, você percebe: o sistema de memória não melhora simplesmente por guardar mais informações, o segredo é "memorizar com precisão o que deve ser lembrado e descartar o resto". Uma informação errada memorizada é pior do que nenhuma—pois ele o guiará com convicção baseado em dados obsoletos.

No [18 Guia de Uso do CLAUDE.md] detalhamos como escrever o CLAUDE.md, e no [19 Gerenciamento de Contexto] mencionamos como a memória automática consome tokens na janela de contexto. Contudo, ainda não havíamos explicado como esses dois elementos operam juntos como um "sistema de memória unificado", ou como o bloco de notas autônomo do Claude é processado. Vamos esclarecer isso hoje.

Ao terminar este artigo, você obterá:

• Uma tabela comparativa explicando as duas vertentes do sistema de memória no Claude Code: o arquivo CLAUDE.md escrito por você versus a "memória automática" gerenciada por ele
• Onde o arquivo de "memória automática" é salvo, como ele é injetado na janela de contexto e como usar o comando /memory para auditoria e limpeza
• O fluxo prático passo a passo de como memorizar uma informação, verificar onde ela foi salva e testar sua ativação em uma nova sessão
• Uma diretriz de "o que salvar versus o que descartar" para evitar o erro do acúmulo desnecessário de dados
• Informações sobre a utilidade da antiga tecla de atalho # e as melhores práticas sugeridas na versão atual

---

01 Primeiro passo: O sistema de memória divide-se em duas partes

Conclusão direta: A memória no Claude Code é gerenciada por dois sistemas paralelos—um editado por você e outro escrito autonomamente pelo modelo. Quando as pessoas mencionam "memória", costumam lembrar apenas do CLAUDE.md, mas ele representa apenas metade do ecossistema.

Analogia: Lembretes colados no monitor. Você costuma te dois tipos de papéis na sua mesa. Um deles é impresso de forma organizada e fixado no painel—contendo padrões de nomenclatura e fluxos de commit do projeto; todos que trabalham no projeto seguem essas regras, o que representa o CLAUDE.md. O outro é um pedaço de post-it onde você anota rapidamente "o erro do cache persistia na sessão anterior" e cola no canto da tela para lembrar depois; esses lembretes rápidos criados autonomamente representam a "memória automática (auto-memory)". Ambos os papéis guiam as decisões, mas um define regras rígidas e o outro registra experiências práticas.

A tabela a seguir consolida a distinção oficial entre os dois formatos de memória—esta é a referência mais importante do artigo:

Aspecto	Arquivo CLAUDE.md	Memória Automática (auto-memory)
Autor	Você (edição manual)	Claude (criação automática)
Conteúdo	Instruções e diretrizes de projeto	Experiências e padrões assimilados
Casos comuns	Padrões de código, fluxos de commit, arquitetura	Comandos de build, logs de depuração, preferências
Carga no contexto	Carregamento completo em toda sessão	Carrega apenas as primeiras 200 linhas ou 25KB por padrão
Escopo	Níveis de usuário, projeto ou local	Por repositório git (compartilhado em worktrees)

Percebeu a distinção? O CLAUDE.md define "como você deseja que ele aja", enquanto a memória automática registra "como ele aprendeu a agir". Se você corrigi-lo avisando que "este repositório exige Redis local para testes", ele lembrará na próxima execução—sem a necessidade de você editar qualquer arquivo de configuração manualmente.

Um aviso de extrema relevância destacado oficialmente:

O Claude trata essas memórias como contexto, não como configurações rígidas. Para bloquear uma ação de forma consistente, use um hook PreToolUse.

O que isso significa? A memória (em qualquer formato) atua apenas como dicas leves que influenciam as decisões do modelo (soft constraints), não como travas rígidas de execução (hard constraints). Isso se alinha com as conclusões do artigo 20 sobre controle de permissões—se precisar impedir uma ação com segurança, use hooks ou regras de acesso; escrever "não envie commits para a main" na memória não impedirá a execução do comando. A memória ajuda a alinhar o comportamento, mas não substitui barreiras de controle.

💡 Resumo em uma frase: A memória divide-se em duas partes—o CLAUDE.md serve para regras inseridas por você e a memória automática registra experiências geradas por ele; ambas funcionam como orientações de contexto, sendo necessário o uso de hooks ou regras para bloquear ações de forma rígida.

Esta imagem representa as duas vias de persistência: à esquerda, o arquivo CLAUDE.md (manual do projeto) editado manualmente e carregado na totalidade; à direita, a memória automática (diário de bordo) gerada no disco e lida nos limites de boot da sessão. Ambas se consolidam no contexto da nova conversa.

---

02 O papel do CLAUDE.md no sistema de memória

As especificações de escrita do CLAUDE.md foram vistas no artigo 18. Aqui destacamos sua função estrutural—ele funciona como as diretrizes oficiais do projeto, visíveis a todos.

Analogia: O manual oficial fixado na mesa. Ele não é um bloco de anotações solto, mas o regulamento oficial do repositório. Portanto, suas propriedades diferem da memória automática: é editado por você, versionado via git com a equipe, carregado na totalidade em toda conversa e focado em regras estruturais em vez de notas rápidas.

A documentação oficial divide o CLAUDE.md em níveis distintos de precedência de carregamento:

Nível	Localização	Escopo de controle
Políticas organizacionais	macOS: /Library/Application Support/ClaudeCode/CLAUDE.md Linux/WSL: /etc/claude-code/CLAUDE.md	Diretrizes corporativas de TI (incomuns para usuários avulsos)
User	~/.claude/CLAUDE.md	Preferências globais do seu usuário em qualquer projeto
Project	./CLAUDE.md ou ./.claude/CLAUDE.md	Compartilhado com o time no repositório (versionado no git)
Local	./CLAUDE.local.md	Configurações específicas suas neste repositório (adicionado ao .gitignore)

Abaixo está uma distinção crítica de processamento em relação à memória automática:

O arquivo CLAUDE.md é carregado na totalidade independentemente do tamanho, enquanto a memória automática possui um limite físico. Como visto no artigo 18, sugerimos manter o CLAUDE.md abaixo de 200 linhas: o modelo é capaz de ler arquivos maiores, mas quanto maior o tamanho, mais espaço útil de tokens é consumido e menor é a aderência às instruções. A memória automática, por outro lado, possui travas físicas de tamanho que evitam o carregamento de dados excedentes.

A divisão de tarefas prática é simples: regras obrigatórias de governança vão no CLAUDE.md, enquanto as experiências aprendidas dinamicamente pelo modelo ficam na memória automática. Por exemplo, fixar o gerenciador de pacotes como pnpm é uma regra de projeto a ser salva no CLAUDE.md; já o fato de que a suíte de testes necessita do Redis iniciado pode ser aprendido pelo Claude a partir do terminal sem edições manuais.

💡 Resumo em uma frase: O CLAUDE.md funciona como o manual oficial do projeto—editado por você, compartilhado via controle de versão e carregado na totalidade; a memória automática funciona como anotações rápidas e dinâmicas do Claude.

---

03 Memória Automática: O bloco de notas do Claude

Chegamos ao tópico principal do artigo—a memória automática (auto-memory), que funciona como o diário de bordo construído autonomamente pelo Claude.

ℹ️ A memória automática requer o Claude Code v2.1.59 ou superior e vem ativada por padrão. Execute claude --version para checar seu ambiente; atualize se necessário (consulte o artigo 02 sobre instalação).

Analogia: O programador parceiro de longa data. Quando você trabalha com o mesmo colega por meses, não precisa repetir detalhes básicos como "o comando de build deste projeto usa make build em vez de npm run build" ou "o bug intermitente anterior ocorria devido ao fuso horário incorreto do servidor". O colega guarda essas experiências e as aplica nas tarefas seguintes. Os dados são acumulados dinamicamente sem instruções explícitas—a memória automática representa essa capacidade de aprendizado dinâmico do Claude.

O que ele registra especificamente? A lista oficial inclui: comandos de compilação, notas de depuração, observações de arquitetura, preferências de estilo de código e hábitos de fluxo de trabalho. Uma propriedade de design importante: ele não grava informações de toda conversa, apenas dados avaliados como "úteis para interações futuras" (o que evita o acúmulo desnecessário de dados temporários).

Como as informações são registradas? Existem dois modos de acionamento:

Modo 1: Instrução direta. No chat, você pode pedir de forma explícita: "a partir de agora use o pnpm em vez de npm para este repositório" ou "lembre-se de que a API de testes requer Redis local". O Claude salvará o dado na memória automática. Citação oficial:

Quando você pede para o Claude lembrar de algo, como "use sempre pnpm em vez de npm" ou "lembre-se de que os testes de API requerem uma instância local do Redis", o Claude salva essa informação na memória automática.

Modo 2: Aprendizado dinâmico por correções. Você não precisa digitar comandos específicos; basta corrigir o Claude quando ele sugerir uma ferramenta incorreta—por exemplo, se ele sugerir npm test e você corrigir para pnpm test—ele avaliará se a instrução é válida no longo prazo e a salvará de forma silenciosa. Essa é a grande conveniência: suas correções habituais se tornam conhecimento persistente sem custos adicionais de configuração.

Como monitorar o status? Observe as notificações no console. A presença das mensagens "Writing memory" ou "Recalled memory" no console do Claude Code indica que ele está gravando ou carregando dados da memória persistentemente.

💡 Resumo em uma frase: A memória automática é composta por post-its virtuais gerados pelo Claude—seja por instrução direta sua ou a partir de correções no terminal; o status de uso é exibido no console como "Writing/Recalled memory".

---

04 Onde é salva e como é injetada no contexto

Esta seção responde a duas dúvidas práticas de infraestrutura: onde essas anotações são salvas fisicamente no disco e como são integradas na janela de contexto (context window)? A segunda parte se conecta ao tema de gerenciamento de tokens visto no artigo 19.

A localização dos arquivos segue uma árvore de diretórios padrão por repositório:

~/.claude/projects/<project>/memory/
├── MEMORY.md          # 简洁索引，每次会话都加载
├── debugging.md       # 调试相关的详细笔记
├── api-conventions.md # API 设计决策
└── ...                # Claude 自己创建的其他主题文件

Aspectos estruturais importantes:

O arquivo MEMORY.md serve como índice. Ele atua como uma folha de rosto onde o Claude categoriza as informações salvas. Detalhes aprofundados são movidos para arquivos específicos (como debugging.md ou api-conventions.md) para evitar que o índice principal cresça excessivamente.

O diretório <project> é associado ao hash do repositório git. Portanto, múltiplos worktrees ou subpastas de um mesmo projeto compartilham a mesma memória automática (diferente da dinâmica de leitura hierárquica do CLAUDE.md).

Ela reside localmente no disco e não é sincronizada entre máquinas. Os dados criados em uma estação de trabalho não serão vistos em outra e esses arquivos não devem ser adicionados ao git, permanecendo na pasta global do usuário ~/.claude.

Abaixo está o mecanismo de limitação de carregamento definido nas especificações oficiais:

As primeiras 200 linhas ou 25KB (o que ocorrer primeiro) do arquivo MEMORY.md são carregadas no início de cada conversa. Dados que excedem esse limite não são carregadas na inicialização.

Isso implica três regras práticas:

1. Cada nova sessão carrega automaticamente apenas as primeiras 200 linhas (ou 25KB) do MEMORY.md. Esse é o mecanismo que possibilita a persistência entre sessões—as notas salvas anteriormente retornam como contexto inicial na nova conversa.
2. O conteúdo que excede as 200 linhas (ou 25KB) é ignorado no boot. Por esse motivo, o Claude reorganiza os dados, dividindo detalhes em arquivos secundários para manter o índice limpo.
3. Arquivos secundários (como debugging.md) não são carregados de início; eles são lidos sob demanda pelo Claude usando ferramentas de leitura de arquivo quando necessário, similar ao fluxo de leitura hierárquica visto no artigo 18.

Abaixo está o comparativo dos limites de carga de contexto:

Limites	CLAUDE.md	Memória Automática MEMORY.md
Volume carregado	Completo (independente do tamanho)	Apenas as 200 linhas iniciais / 25KB
Excedentes	Carregado integralmente (requer moderação manual)	Ignorado na inicialização e lido apenas sob demanda
Gerenciamento de tamanho	Manutenção manual feita por você	Divisão e compactação automatizada pelo Claude

Esse limite estrutural impede que o sistema de memória "esgote" sua janela de contexto de tokens—a memória automática conta com uma barreira nativa de 200 linhas, enquanto o CLAUDE.md depende exclusivamente do seu bom senso no tamanho do arquivo.

💡 Resumo em uma frase: A memória automática reside em ~/.claude/projects/<project>/memory/MEMORY.md por repositório git local; ela carrega apenas 200 linhas ou 25KB por sessão, dividindo o excesso em subarquivos para proteger a janela de contexto.

---

05 /memory: Auditoria, edição e controle em um único comando

O receio comum com o uso de automações é: o que fazer se o Claude memorizar dados incorretos ou obsoletos? (O erro do redirecionamento de porta 8081 citado no início representa isso). A solução fornecida nativamente é o comando /memory.

Analogia: Inspecionar e descartar lembretes antigos. As notas geradas no disco não são uma caixa-preta; você tem total acesso para ler e remover o que quiser. O comando /memory funciona como essa inspeção manual.

Ao digitar /memory na sessão, o console gerencia três frentes:

1. Listar todos os arquivos de memória carregados na sessão atual—incluindo o CLAUDE.md, CLAUDE.local.md, regras globais e a pasta de memória automática. Excelente para rastrear de onde vem uma instrução incorreta.
2. Fornecer o caminho físico da pasta de memórias automáticas—permitindo acessar o diretório memory/ com um clique. Os arquivos são salvos em Markdown legível, permitindo editar ou deletar dados obsoletos diretamente.
3. Habilitar ou desabilitar a memória automática—permitindo interromper gravações automáticas.

Para desativar a função permanentemente por arquivos de configuração, existem duas abordagens oficiais:

Desativar no arquivo settings.json (escopo de projeto persistente):

{
  "autoMemoryEnabled": false
}

Ou configurar uma variável de ambiente temporária (definindo CLAUDE_CODE_DISABLE_AUTO_MEMORY=1).

Recomendamos criar uma rotina simples: digitar /memory periodicamente para dar uma olhada nas notas salvas. É comum encontrar dados obsoletos—como portas de rede de testes antigos, regras de rotas descontinuadas ou preferências que não se aplicam mais. Uma rotina rápida de manutenção que evita guias incorretas do modelo no futuro. Essa é a melhor prevenção contra erros de informações obsoletas.

💡 Resumo em uma frase: O comando /memory expõe todos os componentes do sistema—listando caminhos de leitura, facilitando a edição manual de arquivos Markdown e fornecendo chaves de ativação; auditar as notas regularmente é o caminho sugerido para limpar dados obsoletos.

---

06 O que memorizar versus o que descartar: Evitando o acúmulo descontrolado

Explicada a infraestrutura, vamos para a tomada de decisão prática—quais dados devem ser retidos e quais devem ser descartados. Essas recomendações evitam perda de tempo e erros em produção.

Por design, a memória automática filtra a gravação de dados temporários de uso único. Contudo, quando você solicita gravações diretas ("lembre-se de X"), o Claude cumprirá a instrução. A filtragem inicial depende de você.

Abaixo está o comparativo prático de tomada de decisão:

❌ Não memorizar (dados voláteis, temporários ou sensíveis)	✅ Memorizar (recursos estáveis, reutilizáveis ou regras específicas)
"Desta vez use a porta 8081" (Uso único)	"O comando de build do projeto é make build em vez de npm run build"
"Altere a variável de teste para tmp temporariamente" (Volátil)	"A suíte de testes do projeto requer Redis local iniciado"
"Vamos rodar assim só por enquanto" (Suscetível a alterações rápidas)	"A causa raiz do erro de testes anterior era o fuso horário incorreto" (Logs de depuração)
Credenciais de banco de dados, chaves de API ou tokens (Sensível!)	"A API de datas do projeto deve seguir o padrão ISO 8601" (Boas práticas de estilo)
"Estou depurando a tela de login agora" (Estado temporário da sessão)	"O fluxo de autenticação local está modularizado em src/auth/" (Arquitetura)

Siga estes três critérios básicos de seleção:

1. Volatilidade. Dados temporários, remendos rápidos ou estados instantâneos não devem ser persistidos. O tempo de validade dessas informações é menor do que a duração da conversa. Guardar esses dados gera retrabalho e inconsistências em sessões posteriores.

2. Reutilização. Informações de uso único (como o foco do seu sprint atual) devem permanecer apenas no histórico temporário. Dados com utilidade de longo prazo (como comandos de compilação ou dores de cabeça resolvidas em depuração) devem ser registrados.

3. Sensibilidade de dados. Esta é uma linha vermelha (restrição de segurança)—credenciais de acesso, chaves privadas ou senhas de banco nunca devem ser adicionadas ao sistema de memória. Os arquivos Markdown no disco são salvos em texto puro; memorizar esses dados causaria vazamento local. Mantenha chaves e segredos em variáveis de ambiente, nunca em arquivos de contexto persistente.

Antes de pedir para o Claude memorizar algo, avalie: as informações são voláteis? Serão úteis no futuro? Contêm chaves privadas? Apenas prossiga se as respostas forem adequadas. Esse filtro inicial garante um bloco de notas organizado e reduz riscos de segurança.

💡 Resumo em uma frase: Filtre a retenção de dados—evite armazenar parâmetros temporários ou dados voláteis, e nunca salve credenciais de segurança em texto puro; priorize anotações estáveis e arquitetura do projeto.

---

07 O atalho antigo # ainda funciona?

ℹ️ O atalho # pertencia a versões antigas da plataforma e foi descontinuado. Tutoriais antigos de terceiros costumavam sugerir o prefixo # no terminal para adicionar notas rápidas. Esqueça esse padrão. Atualmente, o fluxo oficial indica: use termos como "lembre-se de X" para salvar na memória automática local, solicite "adicione ao CLAUDE.md" para salvar no manual do repositório, e execute /memory para gerenciar os arquivos.

Um erro frequente de iniciantes: solicitar "lembre-se de X" salva o dado na memória automática local, e não insere no arquivo CLAUDE.md do repositório. Para definir regras de projeto visíveis para todo o time, diga explicitamente: "adicione esta regra no CLAUDE.md". A escolha das palavras define o escopo do compartilhamento.

💡 Resumo em uma frase: O prefixo # está obsoleto; "lembre-se de X" alimenta a memória automática local e "adicione ao CLAUDE.md" atualiza o repositório git compartilhado.

---

08 Prática: Memorizando um comando, verificando o arquivo e testando em nova sessão

Vamos testar o fluxo prático básico: memorizar uma instrução → inspecionar o arquivo gerado no disco → verificar o recall automático em nova sessão. Sem dependências complexas de sistema.

ℹ️ Requisito: Claude Code v2.1.59 ou superior e o recurso de memória automática ativado.

Passo 1: Criar pasta de teste e inicializar o Claude (PowerShell)

New-Item -ItemType Directory -Path "memory-demo" -Force
cd memory-demo
claude

Passo 2: Enviar a instrução de memorização

No input do chat, digite uma regra comum de compilação do projeto:

Lembre-se de que o comando de build deste projeto é make build, e não npm build

Saída esperada: O Claude confirmará o salvamento e o terminal exibirá a marcação "Writing memory" no log de execução, indicando a escrita física no disco.

Passo 3: Auditar o arquivo salvo via /memory

Execute o comando:

/memory

Saída esperada: O painel de gerenciamento será exibido. Você verá a indicação do arquivo de memórias do repositório. Abra o diretório ou acesse o arquivo MEMORY.md; a anotação contendo make build estará estruturada na lista.

Para inspecionar de forma alternativa via PowerShell externo, digite:

Get-Content "$env:USERPROFILE\.claude\projects\*\memory\MEMORY.md"

Passo 4: Confirmar a persistência do recall em nova conversa

Essa etapa valida a utilidade real da função de persistência. Encerre o chat atual:

/exit

Reinicie o Claude Code e faça uma pergunta relacionada:

claude

Pergunte:

Como eu compilo este projeto?

Saída esperada: O Claude responderá que o comando correto é make build. Você observará a notificação "Recalled memory" nos logs de boot, provando o sucesso na recuperação dos dados salvos no início do chat.

Passo 5: Limpeza e exclusão de notas (opcional)

Execute /memory, acesse o arquivo de notas Markdown e delete o registro de compilação. Ao perguntar novamente "Como eu compilo o projeto?", ele deixará de sugerir make build como resposta padrão—confirmando o controle total que você tem sobre o conteúdo retido.

Concluir este roteiro prático valida todo o fluxo operacional da ferramenta: "gravação → inspeção local → recall automatizado → auditoria de limpeza". Este é o alicerce de todas as dinâmicas de memória da plataforma.

---

09 Resumo

Neste artigo, desmistificamos os detalhes operacionais de persistência no Claude Code—compreendendo a distinção entre os dois caminhos paralelos e a importância da qualidade sobre a quantidade de dados.

Revisão dos pontos principais:

Conceito	Resposta / Conclusão
Vertentes de persistência	Duas frentes: regras estruturais no CLAUDE.md e experiências na memória automática
Diferenças de formato	Avalie autoria, finalidade e escopo de carregamento de tokens
Caminho físico	Armazenado na pasta global local do usuário ~/.claude indexado por projeto git
Limites de inicialização	Lê apenas as 200 linhas iniciais (25KB) no boot, separando detalhes sob demanda
Auditoria e controle	O comando /memory gerencia arquivos Markdown e atalhos de gravação no terminal
Critérios de filtragem	Avalie volatilidade, utilidade futura e segurança de chaves de API
Atalho antigo #	Descontinuado; use "lembre-se de X" ou especifique "adicione ao CLAUDE.md" para projetos

Agora você deve ser capaz de: Diferenciar os casos de uso de memórias de projeto e memórias de experiência local, auditar arquivos gerados no disco usando o comando /memory e aplicar filtros iniciais para proteger o contexto útil del modelo. Com isso, seu parceiro de desenvolvimento reterá apenas o que for produtivo, eliminando o ruído de dados obsoletos.

---

No próximo artigo, 26 "Skills dos Agentes (Agent Skills)"—a persistência gerencia a retenção de contexto, enquanto as Skills lidam com a capacitação funcional: empacotar fluxos de execução complexos em rotinas reutilizáveis. Se a memória permite ao Claude entender suas necessidades, as Skills estendem o alcance das tarefas que ele consegue realizar autonomamente. Fica uma reflexão: no alinhamento do assistente, quando vale mais a pena gravar uma instrução de regra versão empacotar uma Skill funcional?

---

Leitura Recomendada

• Modo de Voz (Voice Mode): Falando os seus prompts em vez de digitá-los
• Equipes de agentes (Agent Teams): Colaboração multissessão
• Gerenciamento de contexto: Evitando o consumo excessivo de tokens