Claude-Mem: plugin de memória persistente para o Claude Code
Claude-Mem é um plugin de terceiros que observa o que seu agente faz, tem um segundo agente que comprime isso em observações e injeta um índice curto delas na sessão seguinte. Aqui está o que ele realmente faz, como instalá-lo e configurá-lo, e onde ele termina e o CLAUDE.md começa.
Claude-Mem em resumo
- É uma camada de memória, não um arquivo de regras: os hooks entregam cada chamada de ferramenta a um worker local, um segundo agente transforma essa atividade em observações curtas e a sessão seguinte começa com um índice compacto delas.
- Duas rotas de instalação suportadas: npx claude-mem install (prepara o runtime e abre uma configuração no navegador), ou o par /plugin marketplace add thedotmack/claude-mem e depois /plugin install claude-mem.
- Apache-2.0, TypeScript, mantido por Alex Newman (thedotmack). A memória fica local, em SQLite, em ~/.claude-mem/claude-mem.db; a sincronização na nuvem é opcional.
- Não substitui o CLAUDE.md nem a memória automática do Claude Code — as três carregam no início da sessão e respondem a perguntas diferentes. A tabela comparativa abaixo é a versão curta.
thedotmack/claude-mem — README
Fontegithub.comchecked 2026-11-13
.claude-plugin/marketplace.json — claude-mem 15.18.3
Fonteraw.githubusercontent.comchecked 2026-11-13
Installation Guide
Fontedocs.claude-mem.aichecked 2026-11-13
Configuration
Fontedocs.claude-mem.aichecked 2026-11-13
Telemetry — what is collected and how to opt out
Fontedocs.claude-mem.aichecked 2026-11-13
How Claude remembers your project — CLAUDE.md vs auto memory
Fontecode.claude.comchecked 2026-11-13
dsh-claude-mem — DeepSeek Harness port (unofficial)
Fontedeepseekharnessplugins.comchecked 2026-11-13
Os comandos, configurações, padrões e caminhos desta página foram lidos do repositório upstream e da documentação oficial em 2026-11-13. Comandos e nomes de configuração ficam sem tradução de propósito, porque um comando traduzido é um comando quebrado.
Dados do repositório obtidos da API do GitHub em 2026-11-13: 116,640 estrelas, 10,120 forks, criado em 2025-08-31, última release v15.18.3 publicada em 2026-11-12. A contagem de estrelas muda todo dia — trate como um retrato do momento, não como uma nota.
O que o Claude-Mem realmente é
Claude-Mem é um plugin de código aberto para o Claude Code (e para uma dúzia de outros agentes de programação) que dá ao agente memória do próprio trabalho. O projeto descreve o problema sem rodeios: toda sessão nova começa do zero, relê os mesmos arquivos, repete as mesmas perguntas e volta aos erros que você já corrigiu junto com ele.
A resposta dele é um segundo agente rodando ao lado do seu. Hooks instalados no agente hospedeiro entregam cada chamada de ferramenta — o que foi lido, editado e executado — a um pequeno worker local. Esse worker roda um modelo observador sobre a atividade, grava observações estruturadas curtas e um resumo de fim de sessão, e guarda tudo num banco SQLite local. Quando uma sessão nova começa, o agente hospedeiro recebe um índice compacto das observações que importam para este projeto e busca os detalhes completos só quando pede por eles.
Ou seja, a unidade de memória aqui é uma observação sobre trabalho que aconteceu, não uma instrução que você escreveu. É a diferença inteira em relação ao CLAUDE.md, e é por isso que os dois coexistem em vez de competir.
- Licença
- Apache-2.0
- Última release
- v15.18.3 · 2026-11-12
- A memória fica em
~/.claude-mem/claude-mem.db- Estrelas (2026-11-13)
- 116,640
Como funciona, em três movimentos
O README enuncia o ciclo em três frases, e todo o resto dos recursos depende dele:
- 1
Seu agente trabalha
Hooks de ciclo de vida no agente hospedeiro entregam cada chamada de ferramenta a um pequeno worker local. No Claude Code os hooks cobrem SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, PostToolUseFailure, Stop, SubagentStop e SessionEnd, além de uma entrada Setup para claude --init e --maintenance. Cada hook é um único comando sem shell, claude-mem hook claude-code <event>.
- 2
O observador toma notas
Um segundo agente transforma essa atividade em observações curtas e escreve um resumo quando a sessão termina. Por padrão o modelo de compressão é o Haiku (CLAUDE_MEM_MODEL=haiku), rodando no seu plano da Anthropic; você também pode apontá-lo para uma chave do OpenRouter ou do Gemini, ou para o observador hospedado do fornecedor.
- 3
A sessão seguinte começa com elas
No SessionStart o agente recebe um índice compacto das observações deste projeto — 50 por padrão, ajustável com CLAUDE_MEM_CONTEXT_OBSERVATIONS — e busca os detalhes completos só quando precisa. A injeção começa na sua segunda sessão em um projeto, porque a primeira ainda não tem nada a injetar.
A busca usa a mesma ideia em camadas. Três ferramentas MCP — search, timeline, get_observations — devolvem primeiro um índice, depois o contexto cronológico e por fim os registros completos, de modo que o agente só paga pelo detalhe nas linhas que escolheu. A skill mem-search opera essas ferramentas para você, e os próprios números do README colocam uma linha de índice em cerca de 50–100 tokens contra 500–1.000 de um registro completo — uma proporção por linha que o README diz explicitamente não ser uma economia medida de ponta a ponta.
O que mais o worker entrega
O worker local serve um visualizador na URL impressa na inicialização — memória, sessões e configurações em /viewer, além de My Work na raiz — e expõe ferramentas além da busca: smart_search, smart_outline e smart_unfold para navegar pelo código, save_memory para gravar uma nota de propósito, e acompanhamento do estado do trabalho. Toda observação tem um ID que você pode citar pela API do worker.
Instalar e verificar
As duas rotas abaixo foram copiadas da documentação upstream. A do instalador é a que o projeto recomenda, porque prepara o runtime e compila o lançador de hooks; a do plugin são dois prompts dentro do Claude Code.
Rota 1 — o instalador
Rode isto em um terminal. O instalador verifica Bun e uv, copia os arquivos do plugin, instala as dependências, coloca o lançador claude-mem no seu PATH e abre uma configuração no navegador onde você escolhe agentes, integrações, skills e o provedor de memória. Mantenha o terminal rodando enquanto usa essa página.
npx claude-mem installNão instale com npm install -g claude-mem. O README é explícito: uma instalação global via npm só deixa o SDK/a biblioteca na sua máquina — não registra nenhum hook de plugin nem inicia nenhum worker, e pode encobrir o lançador real no PATH.
Rota 2 — o marketplace de plugins
Envie estes dois como prompts separados dentro do Claude Code e depois reinicie-o. As duas rotas configuram os hooks e iniciam o worker; a partir daí o contexto das sessões anteriores aparece automaticamente nas novas sessões.
/plugin marketplace add thedotmack/claude-mem/plugin install claude-memUma instalação só pelo marketplace não tem etapa de instalador, então o plugin coloca seu lançador no primeiro início de sessão enquanto compila — essa primeira sessão pode rodar sem contexto de memória, e a seguinte já tem. Rodar npx claude-mem install uma vez elimina essa lacuna.
Confirme que está de fato rodando
Rode npx claude-mem doctor: ele verifica Bun, uv, o lançador de hooks e o worker, e diz o que corrigir. claude-mem --version imprime o número de protocolo do lançador, e a URL do worker impressa na inicialização serve o visualizador. Se os hooks reportarem "Executable not found in $PATH", o doctor mostra qual claude-mem é resolvido no PATH e se ele é o lançador.
npx claude-mem doctorclaude-mem --versionRequisitos antes de começar
- 1Node.js 20.19 ou posterior na linha 20.x, ou 22.12 ou posterior.
- 2Bun 1.2.16 ou mais novo — o lançador de hooks é compilado com ele; o instalador instala o Bun se estiver faltando.
- 3uv, instalado automaticamente se faltar: ele fornece a parte em Python do serviço de embeddings do Chroma para a busca semântica.
- 4Claude Code 2.1.139 ou posterior — a primeira release que executa argumentos de hook em forma exec. Versões anteriores ignoram os args e rodam um claude-mem puro, então nada é capturado. O SQLite vem embutido via bun:sqlite.
As configurações que realmente mudam o comportamento
Tudo fica em ~/.claude-mem/settings.json, criado automaticamente com os padrões na primeira execução, e uma variável de ambiente com o mesmo nome sobrepõe o arquivo. Estas são as linhas que vale conhecer; a página de configuração documenta o resto.
| Configuração | Padrão | O que faz |
|---|---|---|
CLAUDE_MEM_MODEL | haiku | Modelo usado para comprimir as observações quando o provedor é Claude. haiku acompanha o Haiku mais recente; um ID completo fixa uma versão. |
CLAUDE_MEM_PROVIDER | claude | Qual provedor executa o observador: claude, codex, gemini, openrouter ou openai-compatible. |
CLAUDE_MEM_CONTEXT_OBSERVATIONS | 50 | Quantas observações são injetadas no início da sessão. Diminua se o bloco de inicialização parecer pesado. |
CLAUDE_MEM_MODE | code | Perfil de fluxo de trabalho e idioma das observações geradas, por exemplo code, code--chill para menos observações, ou code--zh para chinês. |
CLAUDE_MEM_DATA_DIR | ~/.claude-mem | Raiz dos dados. Todos os outros caminhos — banco de dados, índice do Chroma, logs, configurações, arquivos de pid e de porta do worker — derivam dela. |
CLAUDE_MEM_WORKER_PORT | 37700 + (uid % 100) | Porta do worker. O padrão é por usuário, então dois usuários na mesma máquina não colidem; defina uma porta fixa se você fizer scripts contra a API HTTP. |
CLAUDE_MEM_CONTEXT_PROJECTS | current | Para que projetos o SessionStart lê a memória: current significa este checkout, all significa todos os projetos exceto os que você excluir por padrão glob. |
CLAUDE_MEM_SKIP_TOOLS | ListMcpResourcesTool, SlashCommand, Skill, TodoWrite, AskUserQuestion | Ferramentas excluídas das observações. Útil para ferramentas cuja saída é ruído e não conhecimento. |
CLAUDE_MEM_SESSION_START_INCLUDE_ALL_SOURCES | false | Se o contexto do SessionStart inclui observações de todos os harnesses, não só do que você está usando. Padrão false. |
CLAUDE_MEM_SKILLS_DISABLED | (none) | Oculta skills incluídas da listagem e dos comandos de barra do Claude Code, pelo nome simples da pasta. |
Mais dois que vale conhecer: CLAUDE_MEM_SKIP_BASH_PATTERNS recebe uma expressão regular comparada a cada comando de shell, para que comandos barulhentos nunca virem observações, e CLAUDE_MEM_REDACT_ENABLED (desligado por padrão) ativa a redação automática dos padrões de segredo reconhecidos antes de serem armazenados.
Claude-Mem vs. a memória nativa do Claude Code
O Claude Code já carrega conhecimento entre sessões de duas formas, e a documentação da Anthropic as trata como complementares: os arquivos CLAUDE.md que você escreve e a memória automática que o Claude escreve sozinho. O Claude-Mem é uma terceira camada, independente, por cima.
| Dimensão | Nativo do Claude Code | Plugin Claude-Mem |
|---|---|---|
| Quem escreve | Você escreve o CLAUDE.md; o Claude escreve a memória automática a partir das suas correções. | Um segundo agente observador, a partir da atividade de ferramentas que sua sessão produziu. |
| Onde fica | CLAUDE.md na raiz do projeto ou ~/.claude/CLAUDE.md; a memória automática em ~/.claude/projects/<project>/memory/ com um índice MEMORY.md. | SQLite em ~/.claude-mem/claude-mem.db, mais configurações e logs na mesma pasta. Índice Chroma opcional para busca semântica. |
| O que entra | Instruções e regras; a memória automática guarda aprendizados e padrões, e só as primeiras 200 linhas ou 25 KB são carregadas. | Observações sobre trabalho que aconteceu — decisões, correções de bugs, o que foi lido e alterado — comprimidas por um modelo. |
| Quando carrega | Em toda sessão, automaticamente, como contexto depois do prompt de sistema. | No SessionStart por meio de um hook, da sua segunda sessão em um projeto em diante. |
| Como é lido | O arquivo inteiro ou o índice da memória automática simplesmente está presente no contexto; /memory lista e abre os arquivos. | Um índice compacto é injetado; os detalhes voltam por três ferramentas MCP — search, timeline, get_observations. |
| Dependências e custo | Nada extra — vem com o Claude Code. | Node, Bun e uv, um processo worker local e um modelo que comprime: seu plano da Anthropic por padrão, sua própria chave, ou o observador hospedado pago. |
A divisão prática: regras e convenções no CLAUDE.md, a memória automática recolhe preferências e o Claude-Mem carrega o histórico do que você realmente fez. Se o detalhe de uma sessão importa uma única vez, nenhum dos três precisa dele; se uma regra precisa ser seguida sempre, só o CLAUDE.md é o lugar certo. Eles nem são excludentes no armazenamento — a ingestão de memória do claude-mem importa os arquivos de tópico da memória automática do Claude Code para o próprio banco como observações, sem gastar tokens do modelo.
Tutorial de memória do Claude CodePrivacidade, limites e ressalvas honestas
Este plugin grava suas sessões de trabalho, então vale ler os padrões antes que ele chegue a um repositório de trabalho.
- 1Local por padrão. Sessões, observações e resumos são gravados em SQLite em ~/.claude-mem/claude-mem.db; configurações e logs ficam na mesma pasta. A sincronização na nuvem é opcional, não automática.
- 2Envolva qualquer coisa em tags <private> e ela nunca é armazenada — é o que diz o README. A redação automática de padrões de segredo reconhecidos é outro interruptor opcional, CLAUDE_MEM_REDACT_ENABLED, e vem desligado por padrão.
- 3A telemetria anônima vem ligada por padrão (PostHog, vinculada apenas a um UUID de instalação aleatório). Desligue com npx claude-mem telemetry disable; DO_NOT_TRACK é respeitado e tem precedência sobre tudo.
- 4A compressão é uma chamada de modelo, então a atividade de ferramentas sai da máquina para o provedor que você escolheu — seu plano da Anthropic, sua chave do OpenRouter ou do Gemini, ou o observador hospedado do fornecedor. Escolha com consciência.
- 5É software de terceiros, não um produto da Anthropic, e instala hooks executáveis. Leia plugin/hooks/hooks.json e as configurações antes de levar isso para um time; trate o plugin como código que você está executando, porque é exatamente isso que ele é.
- 6Ele custa contexto além de tokens: um índice injetado, um processo worker e Bun e uv na máquina. Se suas sessões já são curtas e autossuficientes, o ganho é pequeno — meça no seu próprio repositório em vez de confiar num número de manchete.
Nada disso faz dele uma má instalação. Faz dele uma ferramenta para testar primeiro em um projeto real — com os repositórios que você nunca quer registrados excluídos por padrão glob e a telemetria desligada se preferir — antes de torná-lo o padrão em tudo o que você abrir.
A telemetria se desliga com um único comando:
npx claude-mem telemetry disable