O que é o Claude-Mem e como ele dá memória persistente ao Claude Code?

Fala aí, beleza? O Claude Code é excelente dentro da sessão e completamente amnésico fora dela

Tu passa duas horas explicando a arquitetura do projeto, decide junto com ele por que aquele job ficou daquele jeito, mata um bug chato, aí dá /clear e pronto: sessão nova, contexto zerado, tudo de novo do começo

O Claude-Mem nasceu pra atacar exatamente isso. É um projeto open source criado e mantido por Alex Newman (@thedotmack), licenciado sob Apache License 2.0, com código no repositório oficial no GitHub, e a proposta é bem direta: capturar tudo que o agente faz durante a sessão, comprimir com IA e injetar o contexto relevante de volta nas sessões seguintes

Neste post eu te conto o que o Claude-Mem é, como ele funciona por dentro, onde a memória fica guardada, como instalar, os dois erros de instalação mais comuns e quanto custa cada modo de compressão

Um detalhe que já vale adiantar: ele não é exclusivo do Claude Code. A descrição oficial lista compatibilidade com Claude Code, OpenClaw, Codex, Gemini, Hermes, Copilot, OpenCode e outros

Pré-inscrição Formação Claude Code

Domine o Claude Code do básico ao avançado

Você vai aprender a criar sistemas completos com Claude Code, sem precisar ser programador. Inscreva-se para ter acesso a um desconto de lançamento e bônus especiais!

Quero minha vaga

Como o Claude-Mem funciona por dentro: hooks, compressão e observações

A ligação com o agente acontece por hooks de ciclo de vida

Que hooks? São pontos do fluxo do agente onde uma ferramenta externa consegue se plugar. No caso do Claude-Mem, a lista oficial é: SessionStart, UserPromptSubmit, PostToolUse, Stop e SessionEnd

Ou seja, ele não fica lendo sua tela nem adivinhando nada. Ele escuta os eventos que o próprio agente emite: começou sessão, você mandou um prompt, uma ferramenta rodou e devolveu saída, o agente parou, a sessão acabou

E aí entra a parte mais interessante, que é a compressão

Saída de ferramenta é gorda. Um grep grandão, o retorno de um build, o dump de um arquivo inteiro: isso facilmente ocupa de 1.000 a 10.000 tokens e some do contexto pouco depois

O Claude-Mem pega essa saída e transforma em uma observação semântica de cerca de 500 tokens, categorizada por tipo: decision, bugfix, feature, refactor, discovery e change, com tags de conceitos e referências de arquivos

Sacou a diferença? Não é log, é resumo com significado. Em vez de guardar o texto bruto do que aconteceu, guarda o que aquilo QUER dizer pro projeto: isso aqui foi uma decisão, isso aqui foi correção de bug, isso aqui mexeu em tais arquivos

Pra gerar essas observações, o projeto usa o Claude Agent SDK

Onde a memória fica guardada e como o Claude-Mem busca nela

A memória é local por padrão, e isso é um ponto forte do projeto

O banco fica em ~/.claude-mem/claude-mem.db, e a pasta ~/.claude-mem/ guarda também o version marker, o settings.json e os logs

O banco é SQLite 3 (via módulo nativo bun:sqlite), com FTS5 pra busca full-text e modo WAL pra leitura e escrita concorrentes. Lá dentro moram três coisas: sessions, observations e summaries

Se você já mexeu com SQLite em qualquer projetinho, é exatamente aquilo: um arquivo só, na sua máquina, sem servidor no meio

Busca híbrida: FTS5 mais Chroma

Só full-text não resolve tudo, porque nem sempre você lembra a palavra exata que foi usada três semanas atrás

Por isso o projeto usa também um banco vetorial Chroma pra busca semântica, introduzido na v5.0.0, com a variável CLAUDE_MEM_CHROMA_PATH apontando pra ~/.claude-mem/chroma

Os dois juntos formam a busca híbrida: o literal e o "parecido com isso"

A skill mem-search e o progressive disclosure

A busca na memória é feita pela skill mem-search (que foi renomeada de "search"), e ela trabalha em três camadas:

1. search(query, limit, orderBy) pra achar os candidatos
2. timeline(anchor, depth_before) pra ver o entorno daquele momento
3. get_observations(ids) pra puxar o conteúdo completo só do que interessa

A consulta aceita a sintaxe FTS5 do SQLite, então dá pra usar AND, OR, NOT e busca por campo com title:, content: e concepts:

Esse desenho em camadas tem nome: progressive disclosure. A ideia é não jogar a memória inteira na cara do modelo logo no início. Segundo o projeto, isso representa cerca de 2.250 tokens economizados por início de sessão em comparação com a abordagem via MCP

O viewer

Tem também uma interface web, feita em React + TypeScript, servida pelo próprio worker na porta definida em CLAUDE_MEM_WORKER_PORT

É por ali que você olha o que está sendo guardado. E o Context Settings Modal do viewer é a forma recomendada de configurar o comportamento

Como instalar o Claude-Mem no Claude Code

São dois caminhos oficiais, os dois de um passo só. Bora ver na prática?

1. Instalação por npx, direto no terminal:

npx claude-mem install

2. Ou, se você prefere resolver de dentro do próprio agente, pelo marketplace de plugins do Claude Code:

/plugin marketplace add thedotmack/claude-mem
/plugin install claude-mem

3. Depois de instalar, é só usar o Claude Code normalmente. Nos dois métodos a configuração dos hooks e o start do worker são automáticos, e o contexto de sessões anteriores passa a aparecer sozinho nas sessões novas

O erro comum deste passo: achar que npm install -g claude-mem resolve. Não resolve! Esse comando instala apenas o SDK/biblioteca, sem registrar os hooks do plugin e sem iniciar o serviço worker

4. Passo opcional, se você quer rodar a partir do código-fonte:

git clone https://github.com/thedotmack/claude-mem.git
npm install
npm run build

5. E, pra controlar o worker na mão, existem scripts próprios:

npm run worker:start
npm run worker:stop
npm run worker:restart
npm run worker:logs
npm run worker:status

O worker:status e o worker:logs são teus amigos quando parecer que nada está sendo capturado. Antes de sair mexendo em configuração, olhe se o worker está de pé

Dois problemas comuns de instalação do Claude-Mem (e como resolver)

Caso 1: instalei e não acontece nada

Sintoma: você rodou a instalação, abriu o Claude Code, e nenhum contexto aparece, nenhuma observação é criada

Causa: provavelmente você usou npm install -g claude-mem. Esse caminho traz só o SDK/biblioteca: ele não registra os hooks do plugin nem sobe o worker, e sem hook não tem captura

Solução: instale por um dos dois métodos oficiais, npx claude-mem install ou o marketplace de plugins dentro do Claude Code. Os dois configuram os hooks e iniciam o worker automaticamente

Caso 2: o hook de setup acusa divergência de versão

Sintoma: você atualizou o Claude-Mem por fora e, na sessão seguinte, o hook de setup reclama que o version marker não bate

Causa: o upgrade feito por fora deixa o estado local fora de sincronia, com dependências de runtime faltando e o marker desatualizado

Solução: rode o comando de reparo

npx claude-mem repair

Ele instala as dependências de runtime que estiverem faltando e atualiza o marker

Prevenção: mantenha a instalação e a atualização pelos caminhos oficiais. Atalho por fora sempre cobra o pedágio depois 🙂

E o /clear, apaga minha memória?

Essa dúvida aparece sempre, então vale o parágrafo

Não apaga. O /clear limpa a conversa visível e reinjeta contexto recente das sessões anteriores, enquanto a sessão subjacente continua registrando observações

Ou seja, aquele reflexo de limpar o contexto pra o agente parar de se perder deixa de custar tão caro

Quanto custa rodar o Claude-Mem: comparativo dos provedores de compressão

O projeto é open source (Apache License 2.0), mas gerar observação é chamada de IA, e chamada de IA tem conta pra alguém pagar

Por isso o Claude-Mem oferece escolha de provedor pra compressão, e o README compara as quatro opções pelo custo por 1.000 observações:

Repare no detalhe da última linha, porque ele muda a decisão pra muita gente: rodando pelo plano Anthropic, o Claude-Mem usa a autenticação existente do Claude Code pra fazer a compressão

É o caminho de menor atrito pra começar (zero configuração de chave), e também o de maior custo por 1.000 observações na comparação do README

E olha o detalhe do CMEM Pro: o custo por 1k é zero, mas o que está em jogo ali é a assinatura de US$ 30/mês, que já vem com o cloud sync incluído. Guarde essa peça, porque ela volta logo abaixo no aviso de privacidade

Para quem o Claude-Mem faz sentido

Nem toda ferramenta serve pra todo mundo, então vamos aos cenários que os recursos verificados sustentam:

• Projeto longo, onde decisão se perde entre sessões. As observações do tipo decision e bugfix existem justamente pra isso: guardar o porquê, não só o que aconteceu
• Quem vive dando /clear. Se limpar contexto faz parte do teu fluxo, ter reinjeção automática do contexto recente muda o jogo
• Quem quer tudo local. O padrão é SQLite na tua própria máquina, dentro de ~/.claude-mem/
• Quem usa mais de um agente. Como a compatibilidade listada vai além do Claude Code (OpenClaw, Codex, Gemini, Hermes, Copilot, OpenCode e outros), a memória não fica presa a uma ferramenta só
• Quem trabalha em mais de um computador. Aí entra o cloud sync do Pro, que replica o banco entre dispositivos pelo hub da conta cmem.ai
• Times. Pra esse público, o caminho a olhar é o Server Beta, que eu explico na próxima seção

Vale dizer que o Claude-Mem faz parte de uma safra crescente de projetos que estendem o agente por fora, junto com coisas como o Ponytail para o Claude Code

E se o teu caso é o de trabalhar em máquinas diferentes, cuidado pra não confundir as peças: o Claude Code é a ferramenta de terminal, e a conversa sobre o aplicativo de desktop do Claude é outra história

Um aviso de privacidade antes de ligar o cloud sync

Esse aqui merece atenção de verdade

O cloud sync (cmem.ai Pro) funciona por push/pull HTTP contra um hub por usuário, com log ordenado e WebSocket opcional como camada de velocidade, e roda dentro do próprio worker, sem daemon separado

Só que o conteúdo enviado pro hub, na tua conta cmem.ai, inclui as narrativas das observações e o texto integral dos prompts

Se você trabalha com código ou informação sensível, essa é a linha do post pra ler duas vezes antes de ativar. Local por padrão é uma coisa, sincronizado é outra

O que a linha v13 do Claude-Mem trouxe

A linha v13 é a versão principal atual do projeto, e ela trouxe um runtime opcional chamado Server Beta

O pacote do Server Beta inclui:

• pipeline de eventos para observações em Postgres + BullMQ
• auth por API key
• escopo de time/projeto
• audit log
• três provedores de IA (Anthropic, OpenAI e Google)
• servidor MCP dedicado
• stack Docker/Compose
• superfície REST /v1

Junto com essa linha veio também o relicenciamento pro Apache License 2.0, a licença sob a qual o projeto está hoje

Agora a parte tranquilizadora, porque "nova arquitetura" costuma dar calafrio em quem já tem coisa rodando: o Server Beta é opt-in, e a instalação padrão continua funcionando sem breaking changes

Na prática, o que isso significa pra você?

Se você é dev individual, não muda nada: segue com npx claude-mem install, banco local, worker, viewer, vida que segue

Se você é de time, é justamente esse o caminho a olhar. Escopo de time/projeto, auth por API key e audit log são exatamente os itens que faltam quando a memória deixa de ser de uma pessoa e passa a ser de um grupo

Conclusão

O Claude-Mem resolve um problema concreto e chato de quem trabalha com agente de código: o contexto que morre no fim da sessão

A receita é honesta e fácil de entender: hooks capturam, a IA comprime em observações curtas e categorizadas, o SQLite guarda na tua máquina e a busca híbrida devolve só o pedaço que importa

Se você quiser experimentar, o caminho mais curto é esse:

1. instalar com npx claude-mem install ou pelo marketplace de plugins
2. abrir o viewer pra ver as observações sendo criadas de verdade enquanto você trabalha
3. decidir o provedor de compressão pelo comparativo de custo ANTES de deixar rodando no dia a dia

Esse terceiro passo é o que mais gente pula, e é o que aparece na fatura depois 😀

Até o próximo post!