O que é a skill mem-search do Claude-Mem e como ela consulta o histórico do projeto em linguagem natural?

Fala aí, beleza? Sessão nova do agente, e lá vem o ritual de sempre: explicar de novo o que é o projeto, o que já foi corrigido semana passada, por que aquele arquivo ficou daquele jeito esquisito

Contexto é a coisa mais cara do fluxo com IA, e mesmo assim a gente joga fora um monte dele toda vez que fecha uma sessão

A skill mem-search ataca exatamente esse ponto: em vez de reexplicar o projeto do zero, você PERGUNTA pro histórico dele, em linguagem natural, e o agente vai buscar a resposta no que já foi feito

Bora entender como ela funciona por dentro? 🙂

Formação Recomendada

Formação Vibe Coding

Do Prompt ao Produto: Crie Software Real com IA

• 474 aulas
• 20 projetos
• 39h 27min

Conhecer formação

De onde vem a mem-search e por que ela mudou de nome

Ela não é uma skill solta que alguém jogou num gist: faz parte do plugin Claude-Mem, cujo repositório oficial é thedotmack/claude-mem

O perfil que mantém o repositório no GitHub é o thedotmack, identificado no próprio perfil como Alex Newman

Dentro do repositório, a skill vive em plugin/skills/mem-search, ou seja, ela é distribuída junto com o plugin, não como um pacote à parte

E tem um detalhe que confunde quem leu material antigo: a skill se chamava só search

A renomeação de search para mem-search está registrada na versão 5.5.0 do Claude-Mem, e a ideia foi deixar o escopo mais claro

Faz sentido, né? "search" sozinho é genérico demais num ambiente onde o agente já busca em arquivo, na web e em tudo quanto é lugar

O prefixo mem- avisa de cara: essa busca é na MEMÓRIA do projeto

Se você já brincou de escrever regras de skill em projeto legado, a lógica de nomear bem o escopo é a mesma coisa

Como funciona a busca em três camadas do Claude-Mem

Aqui mora a parte interessante da engenharia

A busca na memória do Claude-Mem não despeja tudo que encontrou na sua janela de contexto

Ela trabalha em três camadas, cada uma abrindo um pouco mais de detalhe só quando precisa:

Repara na sacada: a camada 1 é de propósito leve em tokens

Ela te dá o mapa, não o território

Se você conhece o resultado de um grep, é bem parecido: primeiro a lista do que bateu, depois você abre só o arquivo que importa

A documentação chama esse padrão de divulgação progressiva (progressive disclosure) e atribui a ele uma economia de aproximadamente 10x em tokens frente à abordagem RAG tradicional, que costuma empurrar blocões de texto recuperado direto pro contexto

A camada timeline é a que salva em investigação de bug

Porque raramente o que você quer é só a observação isolada: você quer o que aconteceu em volta dela, e é por isso que existe profundidade configurável pra trás e pra frente

Que perguntas a mem-search responde no dia a dia

O gatilho não é comando

É pergunta mesmo, escrita como você falaria com um colega que estava na sessão anterior

A documentação e o repositório citam exemplos como estes:

• What bugs did we fix last session?
• How did we implement authentication?
• What changes were made to worker-service.ts?
• Show me recent work on this project

Traduzindo pro seu dia:

Retomar de onde parou. Segunda-feira de manhã, aquele branco total. Em vez de abrir um monte de arquivo pra reconstruir a história, você pergunta o que foi corrigido na última sessão

Relembrar COMO algo foi feito. Não é "onde está o código de auth", isso o próprio agente acha lendo o projeto. É o porquê da decisão, o caminho que foi seguido, o que já tinha sido tentado e descartado

Rastrear um arquivo específico. Aquele arquivo que ninguém mais entende e todo mundo tem medo de mexer: dá pra perguntar o que mudou nele ao longo do tempo

Recuperar o trabalho recente do projeto. Útil quando você trabalha em três frentes ao mesmo tempo e volta pra uma delas depois de duas semanas

Perceba que nenhuma dessas respostas vive no código-fonte

Elas vivem no PROCESSO, e processo é justamente o que evapora quando a sessão fecha

Como instalar o Claude-Mem para usar a skill mem-search

A skill vem dentro do plugin, então o que você instala é o Claude-Mem

Dois caminhos, ambos verificados na documentação oficial:

1. Comando único, pelo terminal. É o caminho recomendado se você quer resolver rápido:

npx claude-mem install

2. Pelo marketplace de plugins, dentro do Claude Code. Adiciona o marketplace apontando pro repositório e depois instala o plugin:

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

Cuidado com o atalho errado:

Esse é o erro comum de verdade, e é fácil cair nele por reflexo de dev: rodar npm install -g claude-mem achando que resolveu

Não resolve

Esse comando instala apenas a SDK/biblioteca: ele não registra os hooks do plugin nem sobe o serviço worker

Ou seja, você fica com o pacote na máquina e sem nada capturando o histórico, que é justamente o combustível da busca

Se a memória parecer "vazia" logo depois de instalar, vale conferir por qual caminho você passou

Onde ficam os dados que a skill consulta e onde ela funciona

A pergunta que todo mundo faz (e faz certo): esse histórico todo vai pra onde?

A busca roda sobre um banco SQLite local, em ~/.claude-mem/claude-mem.db, com busca full-text via FTS5 sobre sessões, observações e resumos

É arquivo na sua máquina, no seu home

Existe também um índice vetorial Chroma, mas ele é OPCIONAL

Dá pra ligar e desligar pela configuração CLAUDE_MEM_CHROMA_ENABLED, e sem Chroma o sistema opera em modo somente SQLite

Isso é bom por dois motivos: menos peça pra quebrar, e menos dependência de infra pra rodar a busca básica

E tem outra coisa que costuma surpreender: o Claude-Mem não é exclusivo do Claude Code

A descrição oficial do projeto cita compatibilidade com Claude Code, OpenClaw, Codex, Gemini, Hermes, Copilot e OpenCode, entre outros

A documentação ainda tem uma página dedicada de "Claude Desktop MCP", pra quem quer consultar a memória a partir do Desktop

Memória local também muda a conversa sobre continuidade do trabalho: em conta de time, quando alguém sai, fica sempre a dúvida sobre o que acontece com chats e skills daquela pessoa

Vale colocar a mem-search no seu fluxo?

Veredito honesto: a skill resolve um problema real e chato, que é reexplicar contexto toda santa sessão

Mas ela não é mágica, e depende de duas coisas fora dela

Primeira: o plugin instalado do jeito certo, com os hooks registrados e o worker rodando (por isso o npm install -g engana tanta gente)

Segunda: histórico acumulado

No dia 1 o banco está vazio, e nenhuma busca inventa passado que não existe

Então o caminho é: instala pelo comando único ou pelo marketplace, trabalha normal por alguns dias deixando o histórico se formar, e aí testa com uma pergunta simples sobre a sessão anterior

Se a resposta vier com o contexto certo, você acabou de parar de pagar o pedágio do "deixa eu te explicar o projeto de novo"

E se não vier, pelo menos você sabe onde olhar: o banco local em ~/.claude-mem/

Bora testar? Até o próximo post! 😀