Memory Engine
Camada de aprimoramento para o sistema de memória manual. Este skill não substitui o comportamento automático de memória existente — ele adiciona estrutura, consciência de orçamento e um ponto de verificação no final da sessão sobre ele.
Filosofia central: sugerir, nunca salvar automaticamente. O ser humano decide o que vale a pena manter.
Diretório de Memória
Todos os arquivos de memória residem em ~/.claude/projects/-Users-coni/memory/.
Arquivo de índice: MEMORY.md (sempre carregado, ponteiros puros, sem conteúdo).
Fase 1: Captura de Memória
Ao salvar qualquer memória (seja acionada por você ou pelo ponto de verificação da sessão), siga este fluxo sempre:
Passo 1 — Classificar
Cinco tipos. Escolha o que se encaixa:
| Tipo | O que captura | Sinais |
|---|---|---|
user | Identidade, preferências, valores, conhecimento | "Eu sou...", "Eu prefiro...", mudanças de personalidade |
feedback | Como trabalhar com o usuário — correções E confirmações | "Não faça isso", "Isso mesmo", abordagem validada |
project | Contexto de trabalho ativo, prazos, metas | "Estamos fazendo X até quinta-feira", marco atingido |
reference | Conhecimento externo, configurações de ferramentas, ponteiros | Nova ferramenta descoberta, API configurada |
decision | Por que X foi escolhido em vez de Y | "Escolheu X em vez de Y", comparação de trade-offs, decisões arquiteturais |
Para o tipo decision: leia references/decision-type-spec.md para o esquema de frontmatter
e estrutura do corpo (Contexto → Opções → Decisão → Revisitar Quando).
Passo 2 — Deduplicar
Antes de escrever, escaneie o índice MEMORY.md em busca de entradas sobrepostas:
- Mesmo tópico já coberto? → Atualize o arquivo existente, não crie um novo
- Sobreposição com uma regra do CLAUDE.md? → Não salve (a regra é autoritativa)
- Detalhe de tarefa efêmera? → Não salve (git log / código é a fonte da verdade)
Aplique todas as regras de feedback-memory-hygiene.md — elas permanecem autoritativas.
Passo 3 — Estimar Custo de Tokens
Calcule: tamanho_do_arquivo / 3.2 (inteiro, arredondado para baixo). Isso fornece uma aproximação razoável
para conteúdo misto CJK/Inglês sem dependências externas.
Passo 4 — Escrever
- Crie o arquivo de memória com frontmatter YAML (nome, descrição, tipo)
- Atualize o índice MEMORY.md — adicione entrada sob o título de seção correto
- Acrescente a estimativa de tokens:
`~NNNNtk`no final da linha do índice
Exemplo de linha de índice:
- [decision-deploy-cloudflare.md](decision-deploy-cloudflare.md) — Deploy doméstico escolheu CF Pages não Vercel `~280tk`
O que NÃO Salvar
Estas regras são inegociáveis (de memória-higiene + sistema de memória automática):
- Padrões de código, arquitetura, caminhos de arquivo — deriváveis do código
- Histórico Git, mudanças recentes —
git logé autoritativo - Soluções de debug — a correção está no código
- Qualquer coisa já em CLAUDE.md ou
~/cc-personal/rules/ - Estado de tarefa efêmera — útil apenas na sessão atual
- Instantâneos de status do projeto — leia do código e do git
Fase 2: Manutenção de Memória
/memory-check
Execute o script de auditoria e apresente os resultados:
bash ~/.claude/skills/memory-engine/scripts/memory-health-check.sh
O script gera um relatório estruturado cobrindo:
- Orçamento: total de tokens vs limite de 40.000tk (20% do contexto de 200K)
- Distribuição por tipo: contagem e tokens por tipo
- Top 5 por tamanho: maiores arquivos consumindo mais orçamento
- Problemas: arquivos obsoletos (>30 dias), órfãos, links quebrados, tipos vazios, avisos de orçamento
Após apresentar o relatório, sugira ações específicas para cada problema encontrado:
| Problema | Ação |
|---|---|
| OBSOLETO | "Revisar ou arquivar: {arquivo} — ainda relevante?" |
| ÓRFÃO | "Adicionar ao índice MEMORY.md, ou excluir se obsoleto" |
| LINK QUEBRADO | "Remover de MEMORY.md, ou recriar o arquivo" |
| SEM ENTRADAS | Informativo — nem todos os tipos precisam de entradas em todos os momentos |
| AVISO DE ORÇAMENTO | "Maiores arquivos: ... — considere compactar ou dividir" |
Após resolver os problemas, atualize o comentário de orçamento no MEMORY.md:
<!-- budget: ~NNNNtk / 40000tk (NN%) | updated: YYYY-MM-DD -->
Formato de Anotação de Token
Cada entrada do índice MEMORY.md carrega um sufixo de estimativa de token:
- [arquivo.md](arquivo.md) — descrição `~NNNNtk`
O comentário de orçamento fica no topo de MEMORY.md (antes do título). É um comentário HTML — invisível no Markdown renderizado, analisável por scripts.
Fase 3: Ponto de Verificação de Consolidação em Sete Dimensões
Gatilho (Dupla Proteção)
Gatilho principal — Baseado em prompt (regra CLAUDE.md): Ao perceber os seguintes sinais na conversa, execute ativamente a varredura de sete dimensões:
- Chamadas de ferramenta densas (>15 chamadas de ferramenta)
- Conclusão de uma saída substancial (código, análise, solução)
- Mudança grande de tópico
- Usuário diz explicitamente "sedimentar", "revisar", "resumir"
Gatilho de fallback — Stop hook (settings.json):
consolidation-trigger.sh é executado sempre que o agente para, rastreando o número de paradas e o intervalo de tempo.
Quando o número de paradas ≥ 20 e o tempo desde o último gatilho ≥ 30 minutos, gera um prompt de varredura de sete dimensões.
Arquivo de estado: ~/.claude/projects/-Users-coni/memory/.consolidate-state
Varredura em Sete Dimensões
Varra a conversa atual linha por linha, determinando se cada dimensão foi acertada:
| # | Dimensão | Sinal de Acerto | Tipo de Memória Correspondente |
|---|---|---|---|
| 1 | Fechamento de Tarefa | Uma tarefa completa desde a solicitação até a entrega | project (marco) |
| 2 | Atualização do CLAUDE.md | Descobriu novas regras de comportamento gerais | Escrever diretamente em CLAUDE.md |
| 3 | Sedimentação de Regras | Descobriu regras relacionadas a domínio/ferramenta/tipo de arquivo | Escrever em ~/cc-personal/rules/ |
| 4 | Decisão Arquitetural | Fez escolha não óbvia de ferramenta, solução técnica, estratégia de deploy | decision |
| 5 | Marco do Projeto | Status do projeto avançou substancialmente (lançamento, publicação, funcionalidade chave concluída) | project |
| 6 | Calibração de Colaboração | Usuário corrigiu uma prática ou confirmou uma prática não óbvia | feedback |
| 7 | Análise de Alto Valor | Produziu estrutura de análise, insight ou modelo reutilizável entre sessões | reference ou user |
Fluxo de Execução
Varrer 7 dimensões → Contar acertos
Acertos 0-1 → Pular silenciosamente
Acertos 2+ → Gerar sugestão de checkpoint
Regras
- Aplique estritamente a lista "O que NÃO Salvar" — sem exceções no momento do checkpoint
- Verifique as entradas existentes em MEMORY.md antes de sugerir — sem duplicatas
- Máximo de 3 candidatos por checkpoint — qualidade sobre quantidade
- Se nada se qualificar, não produza saída (pulo silencioso, sem sugestões forçadas)
- Nunca escreva arquivos durante o checkpoint — apenas apresente candidatos para aprovação do usuário
- Cada candidato deve anotar o número da dimensão acertada
Formato de Saída
[Checkpoint de Sedimentação] Esta conversa acertou 3/7 dimensões (④⑥⑦), sugestão de sedimentação:
1. [decision] ④ Escolha do esquema de gatilho duplo Stop hook + prompt, em vez de apenas hook — hook não percebe semântica da conversa
2. [feedback] ⑥ Usuário confirmou: o núcleo do volante é o gatilho automático, não a classificação de memória
3. [reference] ⑦ Estrutura de vitalidade do sujeito: modelo de alocação de tempo/esforço para três sujeitos (pessoa/empresa/AI)
Salvar quais? Responda com os números (ex.: 1,2), ou "pular" para pular.
Quando o usuário confirmar os números, execute o fluxo de salvamento da Fase 1 para cada item selecionado. Quando o usuário disser "pular" ou equivalente, não faça nada.
Armadilhas
- Não atualize o comentário de orçamento do MEMORY.md a cada salvamento — apenas durante /memory-check. Atualizações frequentes quebram o cache e adicionam ruído aos diffs do git.
- Estimativas de token são aproximações — não as trate como exatas. O método /3.2 tem ~90% de precisão para conteúdo misto CJK/EN, o que é bom o suficiente para consciência de orçamento.
- Tipo decision é para escolhas não triviais — "usei vim em vez de nano" não é uma decisão que vale a pena salvar. Reserve para escolhas que afetam sessões futuras.
- Stop hook é um fallback, não o principal — se o usuário sair com Ctrl+C, o hook não dispara. A varredura ativa é o motor do volante.
- A varredura ativa não deve interromper o fluxo do usuário — dispare nos intervalos entre tarefas (conclusão de fase, mudança de tópico), não insira no meio da execução.