Progressive disclosure no claude-mem: como funciona a memória em camadas com custo em tokens à vista

Fala aí, beleza? Sessão longa em projeto grande tem um vício silencioso: o agente carrega meio histórico do repositório pra responder uma pergunta de duas linhas

O claude-mem é um plugin de memória persistente entre sessões para Claude Code, ou seja, ele captura o que o agente fez, comprime com IA e reinjeta o contexto relevante lá na frente

E o progressive disclosure é justamente o padrão que ele usa pra devolver essa memória: em camadas, revelando complexidade aos poucos, com o custo em tokens de cada camada declarado na documentação

Bora entender como isso funciona?

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

O que é o claude-mem e onde a memória em camadas entra

Antes do conceito, o produto

O claude-mem é um plugin de memória persistente para agentes de código, com repositório oficial em thedotmack/claude-mem

O suporte declarado vai além do Claude Code: OpenClaw, Codex, Gemini, Hermes, Copilot e OpenCode também aparecem na lista

Como o ciclo de memória acontece:

A captura é automática, via hooks do ciclo de vida da sessão: SessionStart, UserPromptSubmit, PostToolUse, Stop e SessionEnd

Ou seja, tu não precisa lembrar de "salvar" nada, o plugin observa o que acontece, comprime com IA e guarda

E onde isso mora? Num banco SQLite local, na tua máquina, com busca vetorial via Chroma

Aqui vem o ponto que liga tudo: se a memória cresce a cada sessão, a pergunta interessante deixa de ser "o que guardar" e vira quanto trazer de volta

E é aí que a memória em camadas entra 🙂

As três camadas do progressive disclosure e o custo em tokens de cada uma

A arquitetura é de 3 camadas, cada uma com uma ferramenta e um custo aproximado por resultado

A lógica é de funil: começa barato e amplo, termina caro e específico

Camada 1: search, o índice compacto

A busca é a porta de entrada

Ela não devolve o conteúdo das observações, devolve um índice: ID da observação, título, tipo e data

É o suficiente pra tu (ou o agente) bater o olho e decidir o que interessa, sem pagar pelo texto inteiro

Custo aproximado: 50 a 100 tokens por resultado

Camada 2: timeline, o contexto cronológico

A timeline responde uma pergunta diferente da busca: o que estava acontecendo em volta disso?

Ela mostra o contexto cronológico ao redor de uma observação específica, o que veio antes e o que veio depois

Útil quando o título sozinho não conta a história, tipo uma decisão que só faz sentido junto do problema que apareceu meia hora antes

Custo aproximado: 100 a 200 tokens por resultado

Camada 3: get_observations, o registro completo

Aqui é o detalhe cru, o registro completo da observação

E tem um detalhe de projeto importante: a chamada é por ID e em lote, ou seja, ela existe pra ser usada depois que as camadas anteriores já filtraram

É o passo caro, e é caro de propósito

Custo aproximado: 500 a 1.000 tokens por resultado

Resumo das camadas:

O sistema de 3 camadas é apresentado como uma economia aproximada de 10x em tokens frente à abordagem de despejar tudo no contexto

Por que trazer contexto aos poucos importa em projeto longo

Esquece o número por um minuto e olha a mecânica

Projeto que dura semanas acumula memória, e o contexto do agente é finito

Então a conta é simples: cada token gasto com um registro completo que não servia é token que faltou pro código que tu tá escrevendo AGORA

A lógica do funil:

Filtrar barato primeiro, decidir depois, pagar caro só pelo que sobrou

O índice é barato justamente pra tu poder errar nele

Tu pode pedir dez resultados de busca, descartar oito e só então pagar o preço cheio pelos dois que interessam

Na abordagem de despejar tudo, é o contrário: tu paga o custo integral ANTES de saber se o material serve

Se você já se preocupa em economizar tokens no Claude Code, o raciocínio é o mesmo, só que aplicado à memória em vez do prompt

E não é só economia

Esse é o ponto que costuma passar batido

Contexto entupido de coisa irrelevante não é só caro, ele é ruim

O agente tem que escolher o que olhar no meio do que tu entregou, e material irrelevante compete com material relevante

O ganho do progressive disclosure é de precisão da seleção, a economia vem junto de brinde

Como usar o progressive disclosure na prática (e como instalar o claude-mem)

Bora ver na prática?

1. Instale pelo CLI, com npx

npx claude-mem install

O erro comum deste passo: rodar npm install -g claude-mem achando que é a mesma coisa

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

Tome cuidado, porque a instalação "parece" ter dado certo e nada de memória aparece depois

2. Ou instale pelo marketplace de plugins do Claude Code

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

3. Confira o que o instalador criou

O npx claude-mem install cria o diretório ~/.claude-mem/, gera um settings.json padrão, registra os scripts de hook em ~/.claude/plugins/ e sobe o Worker Service na porta 37777

"Que worker?" É o serviço que fica rodando por trás pra dar conta da captura e do armazenamento, tu não interage com ele no dia a dia

4. Comece sempre pela busca

O fluxo recomendado na documentação é começar pelo search, o índice, nunca pelo detalhe

5. Use limite pequeno e filtre

Limite de 3 a 5 resultados, filtrando por tipo, data e projeto

É o filtro que faz o funil funcionar

6. Só então puxe o detalhe completo

Com os IDs que sobraram na mão, aí sim tu chama o get_observations em lote

O erro comum deste passo: pular direto pro detalhe completo sem filtrar antes

Aí tu tem as três camadas montadas e usa a mais cara como se fosse a primeira, o que joga fora o padrão inteiro

Onde o padrão de camadas aparece além da memória: Smart Explore e leitura de código

O mesmo raciocínio foi aplicado a outro problema clássico: ler código

O Smart Explore traz duas ferramentas, smart_search (busca estrutural com símbolos e assinaturas) e smart_outline (o esqueleto estrutural de um arquivo), seguindo a mesma ideia de revelar aos poucos: estrutura barata primeiro, conteúdo cru só depois

A diferença de custo é o argumento: o smart_outline é apresentado em cerca de 1k a 2k tokens contra cerca de 12k tokens de um Read completo do arquivo

A analogia é a de sempre: tu lê o sumário do livro antes de decidir qual capítulo abrir

Situações onde isso pesa de verdade:

• Retomar projeto antigo sem ter que reexplicar pro agente todas as decisões que já foram tomadas
• Entender um arquivo grande antes de abrir, olhando a estrutura em vez de despejar o conteúdo inteiro
• Trabalhar em base de código que não cabe no contexto, onde escolher o que carregar não é luxo, é a única opção

No fundo é a mesma disciplina de quando tu precisa otimizar n8n em VPS apertada: recurso finito é recurso finito, então tu decide o que entra

Vídeo: por onde os tokens do seu agente vão embora

Se tu quer ver o problema do contexto desperdiçado antes de mexer em ferramenta, dá o play aqui:

Vale adotar memória em camadas no seu fluxo?

Veredito honesto: progressive disclosure não é mágica de compressão

É disciplina de recuperação

O valor todo depende de o agente respeitar o fluxo, buscar o índice, filtrar, e só então pagar pelo registro completo

Se ele pular direto pra Camada 3, a arquitetura de 3 camadas vira só uma forma cara de despejar tudo no contexto, exatamente o problema que ela existe pra resolver 😀

Próximo passo concreto: instala pelo npx ou pelo marketplace, roda uma sessão real de trabalho e presta atenção numa coisa só, o quanto o índice já resolveu antes de alguém precisar do registro completo

Se a resposta for "quase sempre", tu entendeu o porquê do padrão existir…

até o próximo post!