Documentação do Claude-Mem: por onde começar e o que ler primeiro?

Fala aí, beleza? O Claude-Mem ataca um problema que todo mundo que usa agente de código conhece: a sessão fecha e o contexto evapora

Aí você abre a documentação pra entender como isso funciona, cai numa página falando de worker service, hooks de ciclo de vida, FTS5 e Chroma opcional… e sai mais confuso do que entrou 😅

O material é bom, o problema é a ORDEM de leitura

Este post é um roteiro: qual página da documentação do Claude-Mem abrir primeiro, qual deixar pro segundo momento e qual só interessa quando algo quebra

A documentação oficial fica em docs.claude-mem.ai e a porta de entrada de conceitos é a Introduction

O que entender antes de abrir a documentação

Antes de sair clicando no menu lateral, vale ter três coisas na cabeça, senão metade das páginas parece grego

Primeira: o que a ferramenta faz. O Claude-Mem captura o que o agente faz durante a sessão, comprime esse material com IA e injeta o contexto relevante em sessões futuras

É isso, em uma frase

Tudo que a documentação descreve depois (banco, hooks, busca) existe pra sustentar esses três movimentos: capturar, comprimir, injetar

Formação Recomendada

Formação Claude Code

Domine Claude Code do absoluto zero até o avançado

• 120 aulas
• 4 projetos
• 9h 45min

Conhecer formação

Segunda: ele não é exclusivo do Claude Code. O projeto se descreve funcionando também com OpenClaw, Codex, Gemini, Hermes, Copilot e OpenCode, entre outros

Isso muda a forma de ler a doc: várias páginas falam de "IDEs e plataformas" no plural, e não de um único fluxo

Terceira: o que é gratuito e o que é pago. O motor claude-mem é gratuito e open source

Em cima dele existe o CMEM como produto pago, com CMEM Cloud a US$ 20/mês e CMEM Pro a US$ 30/mês, após 7 dias grátis

Saber disso evita aquela sensação de "será que essa página é da parte paga?" no meio da leitura

E por que existem dois repositórios?

Essa aqui pega muita gente

O código da documentação vive em um repositório e o código do produto em outro: a doc está em thedotmack/claude-mem-docs e o produto em thedotmack/claude-mem

Os dois ficam sob a mesma conta do GitHub, a @thedotmack, de Alex Newman, que é quem aparece por trás do projeto nesses repositórios

Então, se tu procurar código da ferramenta no repo de docs, não vai achar, e vice-versa

É a mesma lógica de quando você abre a documentação da Claude API pela primeira vez: entender como o material está organizado economiza um monte de tempo antes de qualquer linha de comando

Roteiro de leitura: as páginas da documentação na ordem

A ordem abaixo é do conceito pro detalhe

Cada passo tem o que a página entrega e o erro comum de quem pula ela

1. Introduction: o conceito de memória persistente

Começa em https://docs.claude-mem.ai/introduction

É a página inicial de conceitos, e o que tu quer tirar dela é o modelo mental: o que é capturado durante a sessão, o que acontece com esse material e como ele volta pra você depois

O erro comum deste passo é achar que dá pra pular "a parte teórica" e ir direto instalar

Aí a ferramenta instala, funciona, e você não entende por que o Claude "sabe" de coisas que você não digitou naquela sessão

2. Installation: instalar do jeito certo

A página https://docs.claude-mem.ai/installation cobre o processo de instalação, a configuração inicial e os passos de verificação em diferentes IDEs e plataformas

A instalação recomendada é um comando só no terminal:

npx claude-mem install

Também dá pra instalar de dentro do Claude Code, pelo marketplace de plugins:

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

E, se o teu alvo é outro IDE, existe a instalação direcionada por flag no mesmo comando:

npx claude-mem install --ide opencode

O erro comum deste passo é clássico: instalar via npm global achando que resolveu

npm install -g claude-mem

Esse comando instala apenas a SDK/biblioteca

Ele NÃO configura o plugin: não registra os hooks nem sobe o worker service

Pra ter o plugin funcionando, o caminho é o npx claude-mem install ou os comandos /plugin ali de cima

Ainda nesse passo, presta atenção no que a instalação faz por baixo: ela registra os hooks, cria o diretório ~/.claude-mem/, gera o settings.json com os defaults e inicia o worker

E tem um detalhe que a doc pede e muita gente ignora: reiniciar o Claude Code depois

Sem reiniciar, tu fica olhando pro terminal achando que não instalou 🙂

3. Configuration: o settings.json e os modos

Com a coisa rodando, a próxima parada é https://docs.claude-mem.ai/configuration

Essa página cobre três assuntos: o settings.json, os overrides por variável de ambiente e o sistema de modos

As configurações ficam em ~/.claude-mem/settings.json, aquele mesmo arquivo que a instalação já gerou automaticamente com os defaults

O que dá pra ajustar por lá: modelo de IA, porta do worker, diretório de dados, nível de log e injeção de contexto

E o diretório de dados também pode ser trocado por variável de ambiente:

CLAUDE_MEM_DATA_DIR

O erro comum deste passo é sair editando arquivo antes de saber que ele já nasce com padrões prontos

Na prática, você só mexe no que precisa mudar, não monta o arquivo do zero

4. Progressive Disclosure: por que a busca se comporta assim

Essa página tem URL própria: https://docs.claude-mem.ai/progressive-disclosure

O conceito descrito ali tem quatro camadas de detalhe: o índice (só títulos), os resumos (2 a 3 frases), o detalhe completo e os arquivos-fonte referenciados

Repara numa coisa: essas quatro camadas são o CONCEITO de quanto detalhe é entregue por vez, e não a lista de ferramentas de busca (essas moram em outra página, e a gente chega nelas mais pra frente)

Parece papo de arquitetura, mas o princípio é simples: primeiro vem pouca coisa, e o detalhe só é buscado quando alguém pede

Se você conhece aquele padrão de listar resultados resumidos e só abrir o item escolhido, é exatamente essa ideia aplicada à memória

O erro comum deste passo é pular ela e depois achar que a busca "veio incompleta"

Não veio incompleta, veio na camada certa

O que consultar depois, conforme o seu caso

Aqui começa a leitura de segundo momento

Ninguém precisa ler tudo isso de cara: abre a página quando a necessidade aparecer

Quero entender como a busca funciona:

Vai em https://docs.claude-mem.ai/usage/search-tools

A busca é exposta como ferramentas MCP, em um fluxo de três camadas: search, timeline e get_observations

O papel de cada uma:

• search retorna um índice compacto com IDs
• timeline dá o contexto cronológico em torno de um resultado
• get_observations busca o detalhe completo só dos IDs que sobraram do filtro

É o princípio do passo 4 virando ferramenta: as quatro camadas de detalhe são a régua conceitual da página de progressive disclosure, e o fluxo de chamadas aqui tem três passos

São 4 ferramentas MCP no total, e a quarta é engraçadinha: chama __IMPORTANT e existe só pra lembrar o agente de seguir o padrão de três passos, hahaha

Quero saber onde os meus dados ficam:

O banco é local, em SQLite, em ~/.claude-mem/claude-mem.db

A camada de banco usa SQLite com FTS5 e, opcionalmente, Chroma pra busca semântica

O diretório de dados guarda o claude-mem.db, o .install-version, o settings.json e a pasta logs/, com worker-out.log e worker-error.log

Esses dois arquivos de log são teu primeiro lugar pra olhar quando algo parece parado

Quero entender a arquitetura por baixo:

A página https://docs.claude-mem.ai/architecture/overview descreve quatro peças: Plugin Hooks, Worker Service (uma API HTTP em Express), Database Layer e Search Tools (API HTTP e servidor MCP)

Os hooks de ciclo de vida usados pelo plugin são um Setup de version-check mais 5 hooks: SessionStart, UserPromptSubmit, PreToolUse (Read), PostToolUse e Stop

Olhando essa lista dá pra sacar o fluxo inteiro: começou a sessão, você mandou um prompt, o agente leu algo, o agente executou algo, a sessão parou

Massa, né? Cada momento desses é um gancho de captura

Quero trabalhar em português (ou outro idioma):

O Claude-Mem tem sistema de modos, definidos na pasta plugin/modes/ e selecionados por configuração, no setting CLAUDE_MEM_MODE

Os modos por idioma seguem o padrão code-- seguido do código ISO 639-1, tipo code--pt, code--es ou code--ja

A documentação lista suporte multilíngue com 28 idiomas suportados e também geração automática de arquivos de contexto por pasta, com linha do tempo de atividade

Quero proteger conteúdo sensível:

Esse ponto merece atenção antes de sair usando em projeto de cliente

Conteúdo envolvido em tags <private> é removido na camada de hook, ou seja, antes de chegar ao worker ou ao banco

E os dados ficam locais, em ~/.claude-mem/

Quando ir direto para a página de troubleshooting

Tem hora que roteiro nenhum importa: a coisa não está funcionando e você quer resposta

Nesses casos, abre https://docs.claude-mem.ai/troubleshooting

Sintoma: mensagens que parecem paradas. A doc trata a fila do worker e a detecção de mensagens travadas

A régua descrita é essa: mensagens em processing por mais de 5 minutos são tratadas como travadas

Sintoma: instalou e nada parece ativo. Antes de reinstalar tudo no braço, olha o comando de reparo, citado na documentação junto do comando de instalação:

npx claude-mem repair

E vale lembrar do básico do passo 2: reiniciar o Claude Code depois de instalar

Esse tipo de investigação segue sempre o mesmo caminho de quando o Claude Code não reconhece um plugin: confirmar o que foi instalado, onde ficou registrado e se o processo subiu

Sintoma: confusão de versão. O projeto trabalha com três branches de desenvolvimento: main, core-dev e community-edge

A main é a estável e a única publicada no npm

No momento da pesquisa deste post, a versão do pacote claude-mem publicada no npm era a 13.15.2

Se você está lendo comportamento de uma branch e rodando outra coisa, é normal a documentação não bater com o que aparece na tela

Como prevenir os três? Instalar pelo caminho recomendado (npx claude-mem install ou os comandos /plugin) e reiniciar o Claude Code em seguida

Parece bobo, mas é o que resolve boa parte dos sustos

Vídeo do canal pra quem está começando do zero:

Se você ainda está construindo a base de programação antes de mergulhar em ferramenta de agente, este vídeo do canal mostra onde praticar TypeScript:

Conclusão

A documentação do Claude-Mem não é difícil, ela é grande

A ordem que funciona é essa: Introduction pro conceito, Installation pra colocar pra rodar, Configuration pra ajustar e Progressive Disclosure pra entender o comportamento da busca

Arquitetura, ferramentas MCP, modos por idioma e troubleshooting entram depois, cada um quando a necessidade aparecer

Próximo passo prático, bem direto: abre a Introduction, roda npx claude-mem install, reinicia o Claude Code e volta na página de configuração pra dar uma olhada no teu settings.json

Com esses quatro movimentos você já sai do lugar de "me perdi no menu" pra "sei o que estou configurando" 😀

até o próximo post!