Todo desenvolvedor que usa agentes de codificação de IA já passou por isso: você passa uma hora explicando a arquitetura, preferências e convenções do seu projeto para o Claude Code. A sessão termina. Você começa uma nova. É uma folha em branco. Claude-Mem é o plugin de código aberto que resolve esse problema — e ele se tornou uma das ferramentas mais populares no ecossistema de codificação por IA. Nós o pesquisamos no GitHub, Reddit, Twitter/X e no próprio código-fonte — aqui está o guia definitivo.
Get the latest on AI, LLMs & developer tools
New MCP servers, model updates, and guides like this one — delivered weekly.
1. Por Que Isso Importa
O Claude-Mem é um dos plugins com mais estrelas (stars) no ecossistema Claude Code, com dezenas de milhares de estrelas no GitHub, centenas de releases e milhares de forks. Para um plugin que essencialmente adiciona memória a um agente de codificação de IA, essa é uma adoção extraordinária. Não é um framework nem uma biblioteca — é uma ampliação comportamental para o Claude Code.
Por que isso é importante
Agentes de IA são stateless por design — cada sessão começa do zero. Mas projetos de desenvolvimento reais abrangem semanas e meses. Cada re-explicação custa tokens, tempo e introduz o risco de o agente entender errado algo que você já esclareceu. O Claude-Mem preenche essa lacuna automaticamente.
O projeto é construído principalmente com TypeScript, com JavaScript, Shell scripts, e HTML para seu visualizador web. Ele é licenciado sob a AGPL-3.0, o que significa que você pode usá-lo e modificá-lo livremente, mas trabalhos derivados implantados em uma rede também devem ter o código aberto.
2. A História de Origem
O Claude-Mem foi criado por Alex Newman, conhecido online como @thedotmack. A trajetória de Newman abrange AI Product Management, Solutions Architecture e Forward Deployed Engineering — uma combinação que explica por que o claude-mem parece menos um projeto de hobby e mais uma infraestrutura de produção.
O projeto surgiu de uma observação simples: o Claude Code é incrivelmente poderoso, mas trata cada sessão como se estivesse te conhecendo pela primeira vez. Newman criou o claude-mem para resolver sua própria dor — e a comunidade de desenvolvedores o validou massivamente.
O Insight Principal
Newman percebeu que o problema não era armazenar memórias — era comprimir e recuperar elas de forma eficiente. Logs de conversa brutos são muito grandes e sem foco. O Claude-Mem usa a própria AI para gerar resumos semânticos do que aconteceu em cada sessão e, em seguida, recupera apenas o contexto relevante para a próxima.
O projeto tem uma conta oficial no X/Twitter (@Claude_Memory), uma comunidade no Discord, e até um site oficial em claude-mem.ai com documentação abrangente.
3. O Problema que Ele Resolve
Se você já usou o Claude Code, Cursor ou qualquer agente de codificação de AI por mais de um dia, conhece a dor:
Problema 1: Amnésia de Contexto
Você explica a arquitetura do seu projeto, o esquema do banco de dados e as convenções de código. A sessão termina. Próxima sessão: “Que tipo de projeto é este?” Toda. Santa. Vez.
Problema 2: Decisões Repetidas
Você decide usar um padrão específico (ex: “sempre use server actions, nunca API routes”). Na próxima sessão, o agente gera API routes porque não se lembra da sua preferência.
Problema 3: Perda de Contexto de Bugs
Você passou 30 minutos depurando uma race condition complexa. A correção exigiu entender três serviços interagindo entre si. Na próxima sessão, o agente sugere exatamente a abordagem que você já tentou e rejeitou.
Problema 4: Desperdício de Tokens
Cada re-explicação consome tokens. Se você estiver em um plano baseado em uso, o custo do reestabelecimento de contexto aumenta rapidamente ao longo de dezenas de sessões diárias.
O Claude-Mem resolve todos os quatro problemas. Ele roda silenciosamente em segundo plano, capturando o que o Claude faz (não apenas o que você diz), comprimindo essas observações em resumos semânticos e injetando as informações relevantes no início de cada nova sessão.
4. Como Funciona
O Claude-Mem opera através de 6 componentes principais, todos trabalhando juntos para criar uma camada de memória contínua:
| Componente | O Que Faz |
|---|---|
| 5 Lifecycle Hooks | SessionStart, UserPromptSubmit, PostToolUse, Stop, SessionEnd — capturam eventos em cada etapa |
| Instalação Inteligente | Verificador de dependências em cache que executa antes dos hooks (garante que o Bun, uv e as dependências estejam prontos) |
| Serviço de Worker | API HTTP na porta 37777 com interface de visualização web e 10 endpoints de busca, gerenciada pelo Bun |
| Banco de Dados SQLite | Armazena sessões, observações e resumos localmente com busca full-text FTS5 |
| Skill mem-search | Consultas em linguagem natural com divulgação progressiva para pesquisar o histórico do projeto |
| Chroma Vector DB | Busca híbrida (semântica + palavras-chave) para recuperação inteligente de contexto |
O Fluxo do Ciclo de Vida
Veja o que acontece durante uma sessão típica:
1. Hook SessionStart
→ O serviço de Worker inicia (se não estiver em execução)
→ Recupera observações passadas relevantes
→ Injeta contexto comprimido na sessão
2. Hook UserPromptSubmit
→ Registra o que o usuário perguntou
3. Hook PostToolUse (executa após CADA chamada de ferramenta)
→ Captura o nome da ferramenta + entrada + saída
→ Comprime a observação com IA
→ Armazena em SQLite + DB vetorial
4. Stop Hook
→ Captura eventos de pausa da sessão
5. SessionEnd Hook
→ Gera o resumo da sessão
→ Armazena o snapshot final do contexto
O insight fundamental aqui é PostToolUse. O Claude-Mem não apenas grava suas mensagens — ele grava o que o agente faz: arquivos lidos, código escrito, testes executados, erros encontrados. Isso proporciona uma compreensão muito mais rica do estado do projeto do que apenas logs de conversa.
5. Revelação Progressiva
Este é o padrão de design mais inovador do claude-mem. Em vez de despejar toda a memória na janela de contexto (o que explodiria os custos de tokens), ele utiliza um sistema de recuperação de 3 camadas:
Camada 1: Session Priming (<500 tokens)
→ Resumo simplificado do projeto
→ Decisões principais de sessões recentes
→ Injetado automaticamente no SessionStart
Camada 2: Índice de busca (~50-100 tokens/resultado)
→ IDs de observação compactos + títulos
→ O Agente realiza buscas quando precisa de mais contexto
→ O suficiente apenas para decidir “isso é relevante?”
Camada 3: Detalhes completos (~500-1000 tokens/resultado)
→ Conteúdo completo da observação
→ Recuperado APENAS para IDs relevantes
→ O Agente solicita explicitamente o que precisa
Resultado: ~10x de economia de tokens em comparação à abordagem de enviar tudo de uma vez
Esta é a arquitetura que torna o claude-mem prático em escala. Sem a exposição progressiva, os sistemas de memória ou consomem tokens demais (caro, dilui o foco) ou recuperam muito pouco (perdem contextos críticos). O sistema de 3 camadas do claude-mem permite que o agente seja seu próprio juiz de relevância.
6. Ferramentas de busca MCP
O Claude-Mem expõe 4 ferramentas MCP que o Claude pode usar para consultar sua própria memória:
| Ferramenta | Objetivo | Custo de Tokens |
|---|---|---|
search | Busca full-text com filtros (tipo, data, projeto) | ~50-100/resultado |
timeline | Contexto cronológico em torno de observações específicas | ~100-200/resultado |
get_observations | Buscar detalhes completos por IDs de observação (em lote) | ~500-1000/resultado |
Exemplo: Pesquisando sua Memória
search(query="bug de autenticação",
type="bugfix", limit=10)
// Step 2: Review index, identify relevant IDs
// e.g., observations #123, #456 look relevant
// Step 3: Fetch full details ONLY for those
get_observations(ids=[123, 456])
Este fluxo de trabalho significa que o Claude paga apenas o custo de tokens pelas observações de que realmente precisa, não por tudo no banco de dados. A camada de busca atua como um filtro, e a camada de recuperação fornece profundidade.
7. Como Instalar
O Claude-Mem oferece três métodos de instalação:
Opção A: npx (Recomendado)
A maneira mais rápida — um comando:
npx claude-mem install
# Instalar para o Gemini CLI
npx claude-mem install --ide gemini-cli
Opção B: Marketplace de Plugins (Dentro do Claude Code)
/plugin marketplace add thedotmack/claude-mem
# Instalar o plugin
/plugin install claude-mem
Opção C: OpenClaw Gateway
⚠️ Nota Importante
npm install -g claude-mem instala a SDK/biblioteca apenas — ele não registra os hooks de plugin ou configura o serviço de worker. Sempre use npx claude-mem install ou os /plugin comandos.
Requisitos do Sistema
| Requisito | Detalhes |
|---|---|
| Node.js | 18.0.0 ou superior |
| Claude Code | Versão mais recente com suporte a plugins |
| Bun | Runtime JavaScript (instalado automaticamente se estiver ausente) |
| uv | Gerenciador de pacotes Python para busca vetorial (instalado automaticamente) |
| SQLite 3 | Para armazenamento persistente (incluído) |
Após a instalação, reinicie o Claude Code ou a Gemini CLI. O contexto de sessões anteriores aparecerá automaticamente em novas sessões — sem necessidade de intervenção manual.
8. Mergulho Profundo nos Principais Recursos
🧠 Memória Persistente
O recurso principal: o contexto sobrevive entre as sessões. Ao iniciar uma nova sessão, o Claude já sabe em quais arquivos você trabalhou, quais bugs corrigiu, quais decisões de arquitetura tomou e quais padrões você prefere.
🖥️ UI do Web Viewer
Navegue até http://localhost:37777 no seu navegador para ver um fluxo de memória em tempo real. Você pode navegar pelas observações, pesquisar no histórico e monitorar o que o claude-mem está capturando. O visualizador também oferece acesso a recursos beta e troca de versão.
🔒 Controle de Privacidade
Envolva qualquer conteúdo em <private> tags para excluí-lo do armazenamento. Chaves de API, credenciais, informações pessoais — qualquer coisa dentro dessas tags nunca é persistida. Os dados permanecem inteiramente na sua máquina no SQLite.
🔗 Citações
Cada observação recebe um ID exclusivo. Você pode referenciar observações passadas com seus IDs e acessá-las via http://localhost:37777/api/observation/{id}. exatamente por que o Claude tomou uma decisão específica.
🧪 Canal Beta: Endless Mode
O “Endless Mode” experimental implementa uma arquitetura de memória biomimética projetada para sessões estendidas que duram horas. Ele utiliza uma estratégia de compressão diferente que evita a saturação da janela de contexto durante sessões de codificação maratonais. Alterne entre stable e beta a partir da UI do web viewer.
⚙️ Configuração de Contexto
As configurações são gerenciadas em ~/.claude-mem/settings.json. Você pode configurar o modelo de IA usado para compressão, a porta do worker, o diretório de dados, o nível de log e ter um controle granular sobre qual contexto é injetado e quando.
9. Visão Geral da Arquitetura
A arquitetura do Claude-Mem evoluiu significativamente através de múltiplas versões principais. Veja como as peças se encaixam:
┌─────────────────────────────────────┐
│ Sessão do Claude Code │
│ │
│ SessionStart → PostToolUse → End │
└────────────────┬────────────────────┘
│ Hooks
▼
┌─────────────────────────────────────┐
│ Serviço Worker (Bun, porta 37777) │
│ │
│ ┌──────────┐ ┌──────────────────┐ │
│ │ Web UI │ │ 10 Endpoints de API │ │
│ └──────────┘ └──────────────────┘ │
└────────────────┬────────────────────┘
│
▼
┌─────────────────────────────────────┐
│ Camada de Armazenamento │
│ │
│ ┌──────────────┐ ┌──────────────┐│
│ │ SQLite + FTS5 │ │ Chroma VecDB ││
│ │ (estruturado) │ │ (semântico) ││
│ └──────────────┘ └──────────────┘│
└─────────────────────────────────────┘
A Estratégia de Banco de Dados Duplo
O Claude-Mem utiliza dois bancos de dados em conjunto:
- SQLite com FTS5 — Para consultas estruturadas, buscas de correspondência exata e filtragem baseada em tempo. Rápido, local e zero-config.
- Banco de Dados Vetorial Chroma — Para busca por similaridade semântica. Quando o Claude pergunta “o que fizemos sobre o sistema de autenticação?”, o Chroma encontra observações conceitualmente relacionadas, mesmo que as palavras exatas não coincidam.
Juntos, eles fornecem busca híbrida: correspondências exatas do SQLite e correspondências difusas/semânticas do Chroma. Este é o mesmo padrão de arquitetura de busca usado por sistemas RAG em produção, miniaturizado para uso local.
10. Reações da Comunidade
Pesquisamos discussões no Reddit (r/ClaudeAI, r/ClaudeCode), Twitter/X e artigos técnicos. Aqui está o consenso da comunidade:
O fim da “Folha em Branco”
O sentimento predominante no Reddit: o claude-mem é a melhor solução para o problema da “folha em branco”. Os usuários relatam que ele reduz significativamente a fricção de reexplicar arquiteturas de projeto, economizando tempo, tokens e frustração. Diversas threads no r/ClaudeCode o descrevem como um plugin “indispensável”.
O Debate sobre a Economia de Tokens
Alguns usuários inicialmente se preocuparam com os custos de tokens — um sistema de memória ativa que comprime observações usando chamadas de IA poderia, por si só, consumir tokens. O consenso da comunidade: a arquitetura de divulgação progressiva torna o saldo positivo. Os tokens economizados ao não reexplicar o contexto superam em muito os tokens gastos na compressão de memória.
A Divisão “Heavy vs. Lite”
Como o claude-mem é um sistema completo (exigindo Bun, Python para busca vetorial, um serviço de worker em segundo plano), alguns desenvolvedores criaram alternativas mais leves como claude-mem-lite e memsearch. Estes utilizam armazenamento baseado em texto mais simples e minimizam as chamadas de LLM. A comunidade os vê como complementares: claude-mem para projetos sérios de várias semanas, e ferramentas mais leves para experimentos rápidos.
A Camada de Integração de Workflow
Power users no Reddit descrevem o claude-mem como uma camada fundamental para workflows personalizados. Eles constroem “skills” especializadas sobre ela — combinando memória persistente com regras personalizadas e conhecimento específico de domínio para criar agentes de IA que entendem profundamente seus projetos específicos.
Veredito da Comunidade
O Claude-Mem é amplamente considerado a melhor solução da categoria para memória persistente de agentes de IA. A principal crítica é que ele é “pesado” — um sistema complexo com múltiplas dependências. O contra-argumento: memória é um problema difícil, e soluções simples produzem resultados simples.
11. O Veredito: Vale a pena usar o Claude-Mem?
Nossa Opinião
Sim, se você usa o Claude Code para projetos de múltiplas sessões. O Claude-Mem é a melhor solução de memória persistente da categoria para agentes de codificação de IA. A arquitetura de divulgação progressiva o torna eficiente em termos de tokens, a busca dual SQLite + Chroma oferece recuperação exata e semântica, e a operação totalmente automática significa zero overhead manual.
Use-o se:
- Você trabalha em projetos que abrangem múltiplas sessões (dias, semanas, meses)
- Você está cansado de reexplicar a arquitetura do seu projeto a cada sessão
- Você quer que o Claude se lembre de decisões passadas, correções de bugs e abordagens rejeitadas
- Você se sente confortável com a pegada de dependências (Node.js, Bun, Python para busca vetorial)
Pule se:
- Você só usa o Claude Code para tarefas rápidas e pontuais
- Você prefere ferramentas mínimas e quer zero serviços em segundo plano
- Você usa Cursor ou Windsurf (o claude-mem só funciona com Claude Code, Gemini CLI e OpenClaw)
- Um arquivo
CLAUDE.mdbem mantido é suficiente para o seu fluxo de trabalho
12. Alternativas & Comparação
Como o claude-mem se compara a outras abordagens para dar memória a agentes de IA?
| Abordagem | Prós | Contras |
|---|---|---|
| CLAUDE.md (Manual) | Simples, sem dependências, totalmente controlado | Manutenção manual, sem captura automática, estático |
| Claude-Mem | Automático, busca semântica, exposição progressiva, rico | Configuração complexa, requer Bun + Python, serviço em segundo plano |
| claude-mem-lite | Leve, baseado em texto, menos dependências | Sem busca semântica, compressão mais simples |
| Scripts Personalizados | Totalmente personalizável, sem dependências externas | DIY para tudo, sem suporte do ecossistema |
| Claude Memory integrada | Configuração zero, integração nativa | Escopo limitado, sem persistência específica do projeto |
Para a maioria dos desenvolvedores que trabalham em projetos sérios de múltiplas sessões, o claude-mem oferece o conjunto de recursos mais rico. Para experimentos rápidos ou desenvolvedores que preferem ferramentas mínimas, um arquivo CLAUDE.md bem mantido combinado com um arquivo de skills (como as skills do Karpathy) pode ser suficiente.
13. O Panorama Geral
De Agentes Stateless para Stateful
O Claude-Mem representa uma mudança na forma como pensamos sobre agentes de codificação de IA. A primeira geração de assistentes de IA era stateless — cada interação começava do zero. A geração atual, com ferramentas como o claude-mem, está se tornando stateful — agentes que acumulam conhecimento sobre seu projeto ao longo do tempo.
Isso tem implicações profundas. Um agente com estado não apenas escreve código — ele entende sua base de código. Ele sabe quais padrões funcionaram, quais foram rejeitados e o porquê. Ele lembra que o sistema de auth usa um formato de token específico devido a uma restrição de migração passada. Ele recorda que a consulta ao banco de dados precisa de um índice específico porque você depurou um problema de performance duas semanas atrás.
O Ecossistema de Engenharia de Contexto
O Claude-Mem faz parte de um “engenharia de contexto” ecossistema mais amplo que está amadurecendo rapidamente:
- CLAUDE.md / Arquivos de regras — Contexto estático (convenções do projeto, padrões de codificação)
- Skills/Plugins — Diretrizes comportamentais (como o arquivo de skills do Karpathy)
- Plugins de memória — Contexto dinâmico (claude-mem, histórico de sessão)
- Servidores MCP — Conhecimento externo (bancos de dados, APIs, documentação)
Juntas, essas camadas criam agentes que são profundamente personalizados para projetos e desenvolvedores específicos. A era do “vibe coding” de interação com IA solta e não estruturada está evoluindo para a “engenharia agêntica” — uma prática disciplinada onde o gerenciamento de contexto é tão importante quanto os próprios prompts.
O que vem a seguir
Com a v12, o claude-mem já suporta Claude Code, Gemini CLI e gateways OpenClaw. A trajetória aponta para memória universal de agentes — uma camada de conhecimento persistente que funciona em qualquer ferramenta de codificação por IA, editor ou plataforma. O token $CMEM (um token Solana impulsionado pela comunidade que o criador adotou oficialmente) sugere planos ainda mais ambiciosos para compartilhamento de dados de agentes em tempo real e colaboração entre desenvolvedores.
14. Perguntas Frequentes
P: O claude-mem funciona com o Gemini CLI ou apenas com o Claude Code?
O Claude-Mem suporta tanto o Claude Code quanto o Gemini CLI. Instale para o Gemini CLI com 'npx claude-mem install --ide gemini-cli'. Ele também funciona com gateways OpenClaw.
P: O claude-mem envia meu código ou dados para a nuvem?
Não. Todos os dados são armazenados localmente em um banco de dados SQLite em ~/.claude-mem/claude-mem.db. Nada sai da sua máquina. A API HTTP na porta 37777 também roda localmente, sem necessidade de autenticação.
P: O claude-mem custa tokens extras?
Ele utiliza tokens para comprimir observações, mas a arquitetura de progressive disclosure resulta em economia líquida. Os tokens economizados ao não precisar reexplicar o contexto entre as sessões superam em muito o custo da compressão.
P: Por que o worker não está iniciando ou a porta 37777 está em uso?
Verifique o que está usando a porta com 'lsof -i :37777' e encerre o processo com 'kill -9 $(lsof -t -i:37777)'. Você também pode alterar a porta em ~/.claude-mem/settings.json.
P: Qual é a diferença entre o claude-mem e o CLAUDE.md?
O CLAUDE.md é um arquivo estático que você mantém manualmente com as convenções do projeto. O Claude-Mem é automático — ele captura, comprime e recupera o contexto dinamicamente. Eles se complementam: use o CLAUDE.md para regras e o claude-mem para memória.
P: Posso usar o claude-mem com o Cursor ou Windsurf?
Não. O Claude-Mem foi construído especificamente para o sistema de plugins/hooks do Claude Code. Ele também suporta o Gemini CLI e gateways OpenClaw, mas não o Cursor, Windsurf ou outras IDEs.
P: O que é o Endless Mode no claude-mem?
O Endless Mode é um recurso beta que implementa uma arquitetura de memória biomimética para maratonas de codificação que duram horas. Ele utiliza uma estratégia de compressão diferente para evitar a saturação da context window. Ative-o através da UI do Web Viewer.
15. Todas as Fontes & Links
Este artigo foi pesquisado utilizando pesquisa de múltiplas fontes no GitHub, Reddit, Twitter/X, artigos da web e no próprio código-fonte. Aqui estão todas as fontes primárias:
Fontes Primárias
- GitHub: thedotmack/claude-mem — O repositório
- claude-mem.ai — Site oficial & documentação
- Visão Geral da Arquitetura — Componentes do sistema & fluxo de dados
- Documentação de Divulgação Progressiva — Filosofia de priming de contexto
- Guia de Engenharia de Contexto — Princípios de otimização de agentes de IA
Comunidade & Social
- @Claude_Memory — Conta oficial no X/Twitter
- Comunidade no Discord — Servidor oficial no Discord
- Reddit r/ClaudeAI — Discussões da comunidade sobre soluções de memória de IA
- Reddit r/ClaudeCode — Tópicos técnicos sobre arquitetura de plugins e gerenciamento de tokens
Referências Técnicas
- Evolução da Arquitetura — A jornada da v3 para a v5+
- Arquitetura de Hooks — Como o claude-mem utiliza hooks de ciclo de vida
- Arquitetura de Busca — Busca híbrida com Chroma
- Guia de Ferramentas de Busca — Exemplos de uso da ferramenta MCP
Autor
- Alex Newman (@thedotmack) — Criador do claude-mem
Artigos Relacionados neste Site
- Arquivo de Skills CLAUDE.md do Karpathy: O Guia Completo
- LLM Wiki do Karpathy: O Guia Completo para seu Arquivo de Ideias
- Como Configurar Skills em sua AI IDE
- O Guia Completo de System Prompts para Agentes de IA
- Dominando Agent Skills
Get the Ultimate Antigravity Cheat Sheet
Join 5,000+ developers and get our exclusive PDF guide to mastering Gemini 3 shortcuts and agent workflows.