Communitygithub.com

jau123/claude-memory-manager

Uma habilidade para Claude Code que mantém a biblioteca de memória do seu projeto auditável, nomeada de forma consistente e livre de desvios — por meses, não dias.

O que é claude-memory-manager?

Esta habilidade para Claude Code gerencia a biblioteca de memória automática do projeto, garantindo que ela permaneça auditável, nomeada de forma consistente e livre de desvios ao longo do tempo. Ela fornece um sistema completo de regras e fluxos de trabalho para decidir o que memorizar, como escrever memórias (feedback, referência, projeto), onde armazenar as informações (comentários inline, regras do Claude, memória ou CLAUDE.md) e como organizar o índice `MEMORY.md` para máxima eficiência de recuperação. A habilidade suporta todas as plataformas onde o Claude Code é utilizado e inclui modos para avaliar múltiplos candidatos a memória, criar novas memórias, atualizar as existentes, realizar alterações estruturais no schema e inicializar a memória do zero em novos projetos. Ela também aborda armadilhas comuns, como descrições vagas, fragmentação de tópicos, violações de limite de tamanho do índice e confusão entre regras da habilidade e fatos do projeto.

Funciona com✓Claude Code~Codex CLI~Cursor
npx skills add jau123/claude-memory-manager

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

Gerenciamento de Memória

Como escrever na memória automática do Claude Code e no CLAUDE.md para que a biblioteca permaneça pesquisável à medida que o projeto cresce.

Referência Rápida

Usuário diz...Faça isso
"registra isso" (vago, múltiplos candidatos)/"revisão"/"depois do desenvolvimento, veja o que vale registrar"→ Modo 1: Avaliação de Candidatos (filtragem de múltiplos candidatos)
"registra aquele X bug de hoje" (item específico único)/após consertar um bug grave/fim de incidente de segurança/decisão única com conclusão não óbvia→ Modo 2: Nova memória (vai direto)
"atualiza esta memória / corrige a conclusão de X"→ Modo 3: Atualizar memória existente (prioritário sobre criar nova)
O trecho a adicionar tem mais de 100 linhas ou o arquivo já tem > 4 tópicos H2→ Regra 6: Dividir em vez de atualizar
"mudar schema / adicionar novo tipo / alterar estrutura de memória"→ Modo 4: Mudança estrutural (leia a lista de armadilhas)
"novo projeto, memória do zero" / "como começar"→ Modo 5: Bootstrap sem memória
"o sistema de memória parece bagunçado / auditoria"→ Se existir scripts/audit-memory.sh na raiz do projeto, execute-o; caso contrário, consulte templates/audit-memory.template.sh para criar o seu próprio

Regras Importantes

Regra 1: Fatos na memória, métodos na habilidade

O arquivo de memória armazena "caiu no buraco X", "dados da indústria Y", "estado do projeto Z"; esta habilidade armazena "como decidir o que registrar / como escrever / como organizar". Não coloque especificações de schema nos arquivos de memória (erro de categoria).

Regra 2: Primeiro julgue "vale a pena registrar?", depois decida "onde registrar"

Nem toda descoberta merece ser registrada. Árvore de decisão:

SinalDeve registrar?
Mesmo buraco, 2ª vez✅ Obrigatório
Julgamento não óbvio descoberto em revisão✅ Registre o "Porquê" da decisão
Comparação com a indústria / números medidos (linha de base reutilizável)✅ Registre
Debug único já corrigido sem valor de aprendizado❌ Não registre (mensagem de commit é suficiente)
Estado temporário que mudará⚠️ Veja a persistência; só registre se for duradouro
Baixa frequência, mas fatal (não lido em 6 meses, mas ainda é a única verdade)✅ Mantenha — 30 dias sem toque ≠ obsoleto; o critério para excluir é "tópico desapareceu/foi substituído", não "há quanto tempo não é lido"

Julgue "onde registrar" — Roteamento de quatro níveis por localidade de gatilho:

Primeiro faça uma pergunta ortogonal: "Quando esta informação for necessária no futuro, a pessoa estará olhando para uma localização específica do código, ou estará tomando uma decisão entre arquivos / depurando um tipo específico de erro?"

Condição de gatilhoDestinoMecanismo
Olhando para uma linha/bloco específico, o PORQUÊ cabe em uma fraseComentário inline no código (logo acima da linha)100% de chance de ser visto ao modificar o arquivo, custo de indexação zero
Contrato de múltiplos pontos envolvendo um conjunto específico de arquivos / checklist.claude/rules/<x>.md + frontmatter paths:Contexto injetado automaticamente ao acessar caminhos correspondentes
Gatilho é um cenário/erro/tipo de problema, ou envolve vários arquivos, ou não pertence a um único arquivo do repositório (SDK/buraco de plataforma)memory (este sistema)Acionado pela description
Regra que deve ser seguida em toda sessão (comandos, pilha tecnológica, preferências de colaboração)CLAUDE.mdPermanente

Feedback vinculado a um arquivo: por padrão, DIVIDIR: O cerne local do arquivo vai para comentários inline; a memória só mantém o princípio reutilizável entre arquivos + um ponteiro para o arquivo.

Três barreiras contra migração excessiva (por padrão, fique na memória, evite migrar):

  1. Se após remover o arquivo específico ainda restar uma lição genérica → mantenha na memória (ex.: "não use campos opcionais para decisões críticas" — o arquivo específico é só um exemplo, o princípio é transferível)
  2. Comportamento de plataforma/SDK que se repete em vários arquivos → mantenha na memória, mesmo que tenha implicações de código
  3. Lápide (X foi aposentado → veja Y) / SOP de investigação / raciocínio econômico do negócio → mantenha na memória (gatilho está no nível de arquitetura/cenário)

Evidência (auditoria completa de uma base de produção com 175 arquivos): apenas ~15% das entradas estão vinculadas a um único arquivo, e na maioria desses casos o cerne do arquivo já estava em comentários de código — "migrar" geralmente significa remover cópias redundantes da memória, não uma verdadeira realocação.

Como escrever .claude/rules/*.md (coloque em .claude/rules/ do projeto, no git → compartilhado entre máquinas/worktrees):

---
description: Uma frase sobre o que esta regra trata
paths:
  - src/components/SomeDialog.tsx
  - src/lib/providers/*.ts          # suporta glob
---
Corpo do contrato / checklist de vários pontos (gotchas de múltiplos pontos) que é injetado automaticamente ao acessar os caminhos acima.

⚠️ Limitações conhecidas da injeção nativa de regras (verificado em 2026-07, anthropics/claude-code issues): Regras com paths: só são injetadas durante Leitura de arquivos correspondentes, não durante Escrita / criação de novos arquivos (#23478); paths: nas regras do usuário ~/.claude/rules/ são ignoradas, apenas as do projeto funcionam (#21858). Contratos que "devem ser aplicados mesmo ao criar novos arquivos" devem ficar no CLAUDE.md, não apenas nas regras.

Regra 3: Priorize atualizar existente, não criar novo

Se já existe um arquivo relacionado ao tópico → atualize esse arquivo (adicione seção ou seção de changelog). Crie novo apenas se o tópico for completamente ortogonal. Criar novos leva à fragmentação do tópico → dificuldade em encontrar → perda de memória.

Regra 4: Memória não é carregada automaticamente, a description determina o acerto

Arquivos de tópico (memory/*.md) não são carregados no início da sessão. O Claude usa a description no índice MEMORY.md para decidir se deve lê-los. A description deve ser uma mistura de palavras-chave de cenário + conclusão central, caso contrário, o Claude decidirá qual ler por impulso.

Verificação do mecanismo nativo (2026-07, docs oficiais/en/memory): Não há recuperação semântica automática por vetores — a descoberta depende inteiramente da "linha de índice MEMORY.md + nome do arquivo"; o Claude lê sob demanda usando Read; ao ler, o harness injeta um aviso de atualidade "Esta memória tem N dias de idade". A qualidade do gancho da linha de índice = 100% da taxa de acerto — este é o comportamento nativo, não uma convenção desta habilidade.

Regra 5: A habilidade deve obedecer às regras que ensina

Se esta habilidade instrui o usuário a escrever uma seção ## Why, ela também deve explicar o Porquê de cada uma de suas regras (todas estão inline neste arquivo).

Aviso de Escopo: A Regra 5 se aplica a "método/forma de escrever/formato da Referência Rápida, etc.", não se aplica recursivamente às regras de schema. Schema (nomeação/ frontmatter/ seção Why) é para arquivos de memória, não se aplica à habilidade em si. A habilidade não é um arquivo de memória.

Regra 6: Quando dividir em vez de atualizar (evitar sobrecarga de arquivo único / grupo único)

A Regra 3 prioriza atualizar, mas há limites. Sinais de que deve dividir (nível de arquivo único):

SinalAção
Arquivo existente > 100 linhas, e o novo conteúdo é ortogonal ao tópico originalDivida em novo arquivo, não insira
Arquivo existente já tem ≥ 4 seções de nível H2, e o novo conteúdo pertence a um 5º tópico independenteDivida em novo arquivo
Após adicionar, o comprimento total ultrapassa 150 linhasAvalie se deve dividir (depende da independência do tópico)
O novo conteúdo não corresponde ao título/description do arquivo existenteDivida em novo arquivo (o arquivo original deve focar no tópico declarado)

Sobrecarga de grupo único (nível de índice):

SinalAção
Número de entradas em um grande grupo do MEMORY.md ≥ 15Considere criar uma memória hub (índice de seção) para substituir a lista plana; novas entradas são anexadas ao hub
A soma das descriptions de um grupo, quando lida, > 25 linhasMesmo que acima
MEMORY.md > 23.000 caracteres (wc -m) ou > 190 linhas🔴 Limite nativo = primeiras 200 linhas ou 25K caracteres, o que vier primeiro (redação oficial "25KB", mas na prática é medido como comprimento de string em caracteres: um índice de 27.972 caracteres/37,9KB foi truncado exatamente no caractere 25.000, ~35% antes do que seria por bytes). A parte excedente não é carregada silenciosamente. ⚠️ Não use wc -c (bytes) para estimar: chinês UTF-8 tem 3 bytes por caractere, superestimando a margem em ~35%. Próximo ao limite, o harness injeta um aviso; se vir Only part of it was loaded, o índice já está sendo perdido
Linha de índice individual > ~160 caracteresDescription com muitos detalhes → mova para o arquivo de tópico ou para comentários de código, deixando apenas "palavras-chave de cenário + conclusão central"

Por que a sobrecarga de grupo único também importa: O Claude escaneia as descriptions do MEMORY.md para acertar; com 20+ descriptions em um grupo, há risco de omissão em uma única varredura. Depois de criar um hub, o índice do grupo aponta para uma única linha para o hub, e o hub contém um mapa de tópicos.

Por que a sobrecarga do índice como um todo é a mais perigosa: Sobrecarga de arquivo único/grupo único é apenas "queda na taxa de acerto"; mas o truncamento do índice = a entrada inteira no final não é carregada = taxa de acerto zero, e silenciosamente, sem erro. Portanto, ⭐⭐⭐ as entradas coroa devem ser colocadas no topo do MEMORY.md (seguro contra truncamento).

Prioridades de redução quando o índice está acima do limite / muito grande (comprimir descriptions é a pior primeira medida, pois prejudica a taxa de acerto):

  1. Primeiro migre: Entradas locais de arquivo → comentários inline / .claude/rules (índice fica menor e taxa de acerto aumenta, veja Regra 2 roteamento de quatro níveis)
  2. Depois exclua: Lápides reais (tópico desapareceu/foi substituído e sem valor de prevenção de renascimento)
  3. Depois reordene: Mova ⭐⭐⭐ para o topo do MEMORY.md
  4. Depois classifique: Aloque orçamento de caracteres por importância — entradas coroa ≤160 caracteres, entradas comuns ≤110, entradas de cauda longa/baixa frequência agregadas em uma única linha com vários links (subtópico → [a](f1.md) · [b](f2.md), uma linha comporta 5-10 arquivos). Além disso: use nomes curtos sem prefixo de tipo para rótulos de links ([foo-bar](feedback_foo_bar.md)), não repita o nome completo do arquivo, economize 12-45 caracteres por linha
  5. Por último comprima a quantidade de informação de uma descrição individual

Casos históricos de buracos (referência, não parte das regras)

  • Sobrecarga de arquivo único: Um arquivo de referência cresceu para 130+ linhas, com 7-8 subtópicos independentes (infraestrutura, lista de crons, manual de falhas, etc.), e a descrição no índice MEMORY.md não resumia bem, então o Claude não conseguia acertar o subtópico específico. Dividido em 5 memórias independentes, cada tópico foi acertado com precisão.
  • Sobrecarga de grupo único: Um determinado grupo acumulou 20+ entradas; em uma nova sessão, o Claude omitiu algumas ao escanear o índice e, ao processar uma tarefa, reinventou a roda. Criar uma memória hub para agregar as entradas relacionadas → resolvido.
  • Sobrecarga geral do índice: MEMORY.md cresceu para 43KB (≈31K caracteres, excedendo o limite de 25K caracteres), com 93 descriptions cada uma com 400-900 caracteres; ao iniciar, foi truncado silenciosamente, e entradas ⭐⭐⭐ no final foram perdidas → em uma investigação, um mecanismo que funcionava conforme o design foi erroneamente classificado como um bug. Lição: description não é quanto mais detalhada melhor; detalhes excessivos estouram o índice e prejudicam o acerto.
  • Calibração errada entre bytes e caracteres: Ao gerenciar a sobrecarga, o limite de aviso foi definido em bytes (wc -c) como 32KB, enquanto o harness executa em caracteres (chinês tem 3 bytes por caractere) → o limite em bytes fez parecer que ainda havia margem, e o índice foi truncado novamente. Lição: alinhe-se com o harness usando a mesma unidade; monitore com wc -m.

Modos de Fluxo de Trabalho

Modo 1: Avaliação de Candidatos (múltiplos candidatos, precisa filtrar)

Cenários de gatilho (múltiplos candidatos → precisa do Modo 1 para filtrar):

  • Após concluir uma funcionalidade / após um longo debug / após uma revisão
  • Após concluir uma ação antiexploração (possivelmente múltiplos pontos de julgamento + lições)
  • Após concluir um incidente de segurança / localizar uma falha
  • Usuário diz "registra isso" (vago, sem especificar qual buraco)

Conteúdo específico único vai direto para o Modo 2: Usuário diz "registra aquele bug wildcard de hoje" / "registra o manual de falhas de vazamento de conexão" → já está claro que é um item único → Modo 2, não Modo 1.

Passos:

  1. Revise os nós-chave desta sessão (correções do usuário, descobertas de revisão, bugs inesperados, consultas de comparação da indústria, conclusões não óbvias de decisões únicas)
  2. Aplique a árvore de decisão da Regra 2 a cada um, filtrando os que valem a pena registrar
  3. Para cada candidato, julgue:
    • Já existe um arquivo de memória cobrindo isso? (grep no índice MEMORY.md) → Se sim, vá para o Modo 3 (atualizar); se não, vá para o Modo 2 (criar novo)
    • O conteúdo a ser adicionado ultrapassa a linha de gatilho de divisão da Regra 6? → Divida em novo arquivo
    • Deve ir para o CLAUDE.md em vez de memória? (veja tabela abaixo)
  4. Confirme a lista com o usuário: Liste os candidatos "sugerido criar novo / sugerido atualizar / sugerido dividir" e aguarde confirmação antes de escrever

Limite memória vs CLAUDE.md:

Natureza do conteúdoOnde colocar
Buracos específicos aprendidos (bug de SDK, limitação de plataforma, dados da indústria)memória feedback_*
Referência aprofundada sobre tópico / método padrão / documentação de processomemória reference_*
Fatos de estado (trabalho em andamento, configuração temporária, snapshot da arquitetura atual)memória project_*
Regras que devem ser seguidas em toda sessão (comandos, pilha tecnológica, preferências de colaboração)CLAUDE.md
Regras necessárias apenas ao operar em arquivos específicos.claude/rules/*.md com frontmatter paths

Modo 2: Nova memória (fluxo padrão)

Passo 0: Primeiro verifique a localidade do gatilho (Regra 2, roteamento de quatro níveis)

Antes de escrever, confirme se realmente deve ir para a memória: arquivo único → comentário inline; contrato de múltiplos arquivos → .claude/rules+paths; cenário/entre arquivos/buraco de plataforma → só então vai para a memória. Feedback vinculado a arquivo: por padrão DIVIDIR (cerne vai para comentário, memória só mantém princípio entre arquivos + ponteiro). Veja Regra 2.

Passo 1: Determine o tipo

TipoQuando usarInformação obrigatória
feedbackBuraco aprendido (bug de SDK / limitação de plataforma / preferência do usuário)Razão (por que esta conclusão) + Quando reutilizar (cenário de gatilho)
referenceReferência aprofundada sobre tópico / método padrão / comparação da indústria / pipeline reutilizávelSeção de razão não obrigatória (descritiva)
projectFatos de estado (snapshot de arquitetura, trabalho em andamento, análise econômica)Seção de razão não obrigatória (estado)

Forma de apresentação da informação obrigatória para feedback (qualquer uma serve):

  • Seção separada: ## Why ou sinônimos em chinês ## 根因 / ## 原因 / ## 教训 / ## 为什么 (auditoria aceita)
  • Negrito inline: **Why**: / **根因**: (também para conclusões curtas)
  • Inline na description ou no título ## (se a conclusão em si já implica a razão + quando reutilizar, como tabela ❌/✅)

Informação de quando reutilizar: Pode ser uma seção separada ## How to apply, ou a description contém palavras-chave de cenário (ex.: troca de tab / mutation já sugere o cenário de gatilho).

Passo 2: Nomeação do arquivo

<type>_<topic>[_<modifier>].md tudo minúsculo com underscore:

  • ✅ feedback_supabase_from_deadlock.md
  • ✅ reference_supabase_egress_favorites_refactor.md
  • ❌ feedback-supabase-deadlock.md (usou hífen)
  • ❌ FeedbackSupabaseDeadlock.md (CamelCase)
  • ❌ _schema.md (começa com underscore, será tratado como arquivo oculto e Claude não o lerá ativamente)

Passo 3: Escreva o frontmatter

---
name: slug-em-kebab-case
description: Palavras-chave de cenário + conclusão central
type: feedback | reference | project       # plano (recomendado)
# ou:
# metadata:
#   type: feedback | reference | project   # aninhado (compatível)
---

Posição do campo type: type: plano (recomendado) ou metadata.type: aninhado (ambos aceitos). O script de auditoria reconhece ambos. Para novos arquivos, prefira o formato plano, alinhado com a maioria existente.

Critério de estilo da description:

✅ Boa description❌ Má description
Mutation supabase.from() no lado do navegador causa deadlock após troca de tab; deve usar fetch() para chamar a API RESTProblemas relacionados ao Supabase
Falha de Transformações de Imagem CF com cache de 7 dias / cf-resized err= / Padrão de repetição FavoriteCardÀs vezes a imagem não aparece
Políticas RLS devem ser encapsuladas com (SELECT auth.uid()), caso contrário, serão reavaliadas por linhaOtimização de desempenho RLS

Critério: Ao ler a description, Claude consegue saber imediatamente "esta é a conclusão Y a ser consultada no cenário X"?

Passo 4: Escreva o corpo

Classe feedback (deve conter razão + quando reutilizar):

# Título (O quê — uma frase)

[Conclusão central + 1-2 parágrafos de contexto]

## Why (ou sinônimos: ## 根因 / ## 原因 / ## 教训 / ## 为什么)

[Por que esta conclusão — o buraco específico que caiu, descoberta de revisão, preferência do usuário]
**Por que é obrigatório**: Sem a seção de razão, na próxima vez que a mesma decisão for discutida, muitas vezes a mesma conclusão errada será alcançada.

## How to apply (pode ser omitido, se a description já contiver palavras-chave de cenário)

[Quando reutilizar esta — cenário de gatilho, checklist, passos para evitar o buraco]

Classes reference / project: Estrutura de seção não obrigatória; organize naturalmente por tópico.

Passo 5: Adicione ao índice MEMORY.md

  • Escolha um grupo grande existente, não crie um novo grupo
  • Adicione a description na posição correspondente dentro do grupo (alta importância use negrito ⭐⭐ / ⭐⭐⭐)
  • Entre tópicos: adicione (veja também [[outro-arquivo]]) no final da description

Modo 3: Atualizar memória existente (prioritário sobre criar nova)

Passo 1: Confirme a afiliação do tópico existente com grep

grep -l "<palavra-chave>" memory/*.md

Passo 2: Decida como atualizar

SituaçãoComo atualizar
Novo dado / novo caso complementa conclusão existenteAdicione seção no corpo ou seção de changelog
Conclusão existente é refutadaAdicione no topo do arquivo antigo ⚠️ Substituído por [[novo-arquivo-slug]]; no novo arquivo, escreva "substitui a parte X de [[antigo]]"
Apenas a description não está clara o suficienteAltere a description no índice MEMORY.md, não altere o arquivo em si (a menos que também adicione conteúdo)

Passo 3: Sincronize o MEMORY.md

Se a description foi alterada, a linha correspondente no MEMORY.md também deve ser alterada.


Modo 4: Mudança estrutural (alterar schema / adicionar novo tipo / alterar agrupamento)

Lista de buracos já conhecidos (leitura obrigatória):

  • Não tente usar a sintaxe de glob if: "Write(memory/*.md)" — if: é uma regra de permissão, não um glob de arquivo, já verificado como ineficaz
  • Não use exit 2 para bloquear hooks — já verificado que quebra o fluxo de lote de pré-implantação (Claude não tem mecanismo de repetição automática)
  • Não coloque a fonte oficial do schema em arquivos que começam com underscore, como _schema.md — Claude não lê arquivos de tópico ativamente
  • Não configure hooks em .claude/settings.json do projeto — este diretório geralmente está em .gitignore, não entra no git e não é compartilhado entre worktrees
  • Ao adicionar um novo campo obrigatório, sincronize 3 lugares: (a) seção desta habilidade "Modo 2 → Passo 3" (b) seção de resumo rápido no topo do MEMORY.md (c) lista de campos no script audit-memory.sh
  • Antes de modificar um hook / adicionar restrição, execute bash scripts/audit-memory.sh para ver a taxa de conformidade atual — só tome medidas rigorosas se <95%; se ≥95%, mantenha avisos leves
  • O monitoramento do tamanho do MEMORY.md deve ser em caracteres (wc -m), não em bytes (wc -c) — o limite nativo de 200 linhas/25K caracteres é contado em caracteres; chinês tem 3 bytes por caractere, calibrar por bytes causará truncamento silencioso (veja casos históricos na Regra 6)

Fluxo para alteração de schema:

  1. Execute a auditoria para obter a linha de base atual
  2. Projete a alteração (modifique esta habilidade + hub do projeto)
  3. Verifique se as memórias existentes violam massivamente a nova regra (>10% → adie, primeiro migre conforme a nova regra)
  4. Atualize a seção de resumo do MEMORY.md
  5. Altere a lista de campos do script de auditoria
  6. Execute a auditoria novamente para ver a nova taxa de conformidade

Modo 5: Bootstrap sem memória (novo projeto)

Quando o usuário, em um projeto sem sistema de memória, disser "comece a construir a memória":

Passo 1: Confirme o caminho do diretório de memória automática

O Claude Code cria automaticamente ~/.claude/projects/<project-slug>/memory/, onde <project-slug> = caminho absoluto do projeto com / substituído por -. Ex.:

  • Projeto /Users/alice/Project/myapp → slug -Users-alice-Project-myapp

Se o Claude Code já tiver criado memória automática para este projeto, o diretório existirá. Verifique: ls ~/.claude/projects/ | grep <nome do projeto>.

Passo 2: Crie o índice MEMORY.md

Modelo do topo (pode ser comprimido para ~25 linhas):

# Memória do projeto <Nome do Projeto>

## ⭐⭐⭐ Regras rápidas para escrever memória (regras rígidas)
- Nome do arquivo:`<type>_<topic>.md` tudo minúsculo com underscore; type ∈ {feedback, reference, project}
- Frontmatter obrigatório: name / description / type
- feedback deve conter seção ## Why (ou sinônimos em chinês ## 根因 / ## 教训 / ## 原因)
- Estilo da description: palavras-chave de cenário + conclusão central (uma linha ≤160 caracteres)
- Se já existe arquivo para o mesmo tópico → atualize, não crie novo (se ultrapassar o limite da Regra 6, divida)
- Limite rígido deste índice: primeiras 200 linhas ou 25K caracteres (o que vier primeiro); o que exceder não é carregado silenciosamente
- Método detalhado: habilidade memory-management

## ⭐ Lista de tópicos do projeto
(Nenhum ainda — posteriormente, adicione grupos por tópico)

Passo 3: Limiares de evolução de agrupamento (estrutura determinada pelo número de arquivos)

Número de arquivos de memóriaEstrutura recomendada
< 15Lista plana, sem agrupamento (uma única lista é suficiente; agrupar fragmenta)
15-25Introduza 3-5 grupos grandes (agregue por tópico)
> 25Agrupamento maduro, congele grupos proibindo novos; novas entradas anexadas a grupos existentes (entre tópicos, use (veja também X))

Passo 4: Adicione um protocolo de Memória no topo do CLAUDE.md (3-5 linhas)

## Gerenciamento de Memória
Ao escrever / atualizar memória / ajustar schema → use a habilidade `memory-management`.
- Regras rápidas: seção ⭐⭐⭐ no topo do MEMORY.md
- Taxa de conformidade da auditoria:`bash scripts/audit-memory.sh` (opcional, veja skill templates/)

Passo 5: Reutilize os métodos gerais desta habilidade

Não copie o conteúdo da habilidade para o projeto. A habilidade fica no nível do usuário, todos os projetos compartilham um único conjunto de métodos. No projeto, coloque apenas o estado específico do projeto (lista de grupos / tarefas pendentes / buracos específicos do projeto).


Especificação do Schema (fonte oficial)

Nomeação de arquivos

<type>_<topic>[_<modifier>].md tudo minúsculo com underscore, type ∈ {feedback, reference, project}

Frontmatter obrigatório

---
name: slug-em-kebab-case
description: Palavras-chave de cenário + conclusão central
type: feedback | reference | project       # plano (recomendado)
# ou:
# metadata:
#   type: feedback | reference | project   # aninhado (compatível)
---

O script de auditoria reconhece ambos. Para novos arquivos, prefira o formato plano.

Informação obrigatória para feedback

Seção de razão (qualquer uma):

  • ## Why ou título sinônimo em chinês ## 根因 / ## 教训 / ## 原因 / ## 为什么 / ## Root cause (pode ter : em inglês ou chinês)
  • Negrito inline **Why**: / **Why**: / **根因**: etc.

Quando reutilizar (qualquer um):

  • Seção separada ## How to apply
  • Description contém palavras-chave de cenário (implícito o cenário de gatilho)

Estilo da description

Mistura (palavras-chave de cenário + conclusão central) para que Claude, pela description, acerte "consulta Y no cenário X". Uma linha ≤ ~160 caracteres — detalhes vão para o arquivo de tópico ou comentários de código (limite rígido do índice = 200 linhas/25.000 caracteres, o que vier primeiro; o que exceder não é carregado silenciosamente)

Formato da linha de índice

- [rótulo curto](nome completo do arquivo.md) — gancho. Rótulo curto = nome com hífen sem prefixo de tipo (ex.: [supabase-from-deadlock](feedback_supabase_from_deadlock.md)); entradas de cauda longa/baixa frequência usam linha agregada (subtópico → [a](f1.md) · [b](f2.md))

Congelamento de grupos

Escolha entre grupos grandes existentes, proibido criar novos grupos. Afiliação ambígua use (veja também hub-X) para referência cruzada.


Erros Comuns

ErroCerto
Escrever description genérica "Problema Supabase" de memóriaEscreva palavras-chave de cenário + conclusão "supabase.from() deadlock ao trocar tab, use fetch"
feedback só descreve "o quê"feedback deve ter ## Why, protegendo contra re-questionamento futuro
Criar segundo arquivo para o mesmo tópicoPriorize atualizar o existente; criar novo fragmenta
Criar novo grupo "Problemas de Rede" para colocar 1 entradaUse grupo existente; entre tópicos, use (veja também X)
Colocar especificação de schema em arquivo de memóriaSchema está nesta habilidade; memória armazena fatos
Usar hook com exit 2 para bloqueio forçadoUse aviso leve (stderr + exit 0) ou auditoria posterior

Auto-Verificação (após escrever)

  • O tipo está correto (feedback/reference/project)?
  • O nome do arquivo segue <type>_<topic>.md tudo minúsculo com underscore?
  • Frontmatter completo (name / description / type)?
  • Classe feedback tem seção de razão (## Why ou sinônimo em chinês / negrito inline)?
  • Description contém palavras-chave de cenário + conclusão central?
  • Já foi adicionado ao grupo correto no índice MEMORY.md?
  • Não foi criado um novo grupo? (se sim, desfaça e coloque em grupo existente)
  • Entre tópicos, foi adicionado (veja também X)?
  • Verificação da Regra 6: Novo arquivo < 100 linhas + < 5 seções H2? (se atualizar um arquivo existente o fez ultrapassar o limite, converta em divisão em novo arquivo)
  • Verificação de localidade de gatilho (Regra 2): Esta entrada está vinculada a um arquivo específico? Se sim, o PORQUÊ local do arquivo já deve / deve estar em comentários de código, e a memória deve conter apenas o princípio entre arquivos?
  • Verificação do nível do índice: Após adicionar/alterar a description, o MEMORY.md ainda tem < 23.000 caracteres (wc -m, não bytes!) e < 190 linhas + cada linha ≤ ~160 caracteres?
  • Auditoria de força de gatilho: Liste 3 palavras-chave de cenário que podem ser perguntadas no futuro e simule: "Claude leria esta memória com base na description?" (se não conseguir imaginar um cenário, a description está inadequada)

Integração com Ferramentas

O script de auditoria é uma ferramenta opcional do projeto.

Se existir scripts/audit-memory.sh na raiz do projeto → execute:

bash scripts/audit-memory.sh  # veja taxa de conformidade / liste violações / liste não tocados há 30 dias

Saída: total de arquivos / sem frontmatter / sem Why / links quebrados no MEMORY.md / não tocados há 30 dias / tamanho do MEMORY.md (caracteres + linhas, comparado ao limite nativo de 200 linhas/25K caracteres) / taxa de conformidade em %. Taxa de conformidade alvo ≥ 95%.

Se não houver script de auditoria → crie a partir do modelo:

# A habilidade no nível do usuário tem um modelo genérico
cp ~/.claude/skills/memory-management/templates/audit-memory.template.sh \
   <seu-projeto>/scripts/audit-memory.sh
# Modifique MEMORY_DIR para apontar para o diretório de memória automática do seu projeto
chmod +x <seu-projeto>/scripts/audit-memory.sh
bash <seu-projeto>/scripts/audit-memory.sh

Caminho de memória automática padrão de referência: ~/.claude/projects/<project-slug>/memory/, veja Modo 5, Passo 1.

Habilidades Relacionadas