🎯 KPIs do sistema de memoria
Quatro metricas capturam o essencial. Meca semanal.
📊 Os 4 KPIs
Cada um responde uma pergunta:
- •Consistencia (%): mesma pergunta, mesma resposta? Alvo: >95%
- •Hit rate das buscas (%): top-3 contem a resposta certa? Alvo: >80%
- •Tokens economizados (M/mes): vs bulk-load. Alvo: tendencia positiva
- •Regras promovidas (n): observacoes virando sabedoria. Alvo: 2-5 por mes
⚠️ Consistencia <80% = falha grave
Se nao atinge, hooks nao estao disparando ou memoria nao e deterministica. Debug prioritario.
📈 Dashboard simples
30 linhas de Python. Sem SaaS, sem dependencias externas.
📐 dashboard.py
#!/usr/bin/env python3
import os, json, glob
from pathlib import Path
from collections import Counter
MEMORY = Path('~/.memory').expanduser()
def hook_fires_per_event():
log = (MEMORY / 'hook.log').read_text()
return Counter(line.split('[')[1].split(']')[0] for line in log.splitlines() if '[' in line)
def knowledge_stats():
types = Counter(md.parent.name for md in (MEMORY/'knowledge').rglob('*.md'))
return dict(types)
def promotion_count():
promoted = (MEMORY/'archive/promoted').rglob('*.md')
return sum(1 for _ in promoted)
def access_distribution():
accesses = []
for md in (MEMORY/'knowledge').rglob('*.md'):
for line in md.read_text().splitlines()[:10]:
if line.startswith('access_count:'):
accesses.append(int(line.split(':')[1].strip()))
return {'zero': accesses.count(0),
'low (1-3)': sum(1 for a in accesses if 1 <= a <= 3),
'high (4+)': sum(1 for a in accesses if a >= 4)}
if __name__ == '__main__':
print('=== Memory System Dashboard ===\n')
print('Hook fires (last run):', dict(hook_fires_per_event()))
print('Knowledge by type: ', knowledge_stats())
print('Total promoted rules: ', promotion_count())
print('Access distribution: ', access_distribution())💡 Rode toda segunda-feira
Cinco minutos. Tendencias aparecem em 4 semanas.
📅 Revisao mensal
Ritual de 30 minutos, uma vez por mes. Como manutencao em carro.
Minuto 0-5: rode dashboard
Numero de consistencia, hit rate. Compare com mes anterior.
Minuto 5-15: revise archive
Veja o que foi decaido. Algo importante que nao deveria sumir? Salience errada?
Minuto 15-25: promotions pending
Revise proposals. Aprove as boas, edite as ambiguas, rejeite as ruins.
Minuto 25-30: ajustes
Identity inflou? Context.md bagunçou? Decay muito agressivo? Uma correcao por mes e suficiente.
💡 Calendar recurring
Segunda-feira do primeiro dia util do mes, 10h. Block no calendario. Sem esse ritmo, sistema apodrece.
🚪 Quando mudar de backend
Criterios claros evitam migrar por modinha.
📐 Triggers de migracao
MARKDOWN → SQLite + FTS5 Trigger: busca grep > 500ms consistente Sinal: 500+ memorias, grep fica lento SQLite → sqlite-vec (adicionar semantica) Trigger: hit rate < 75% por 2 meses Sinal: keyword nao captura variacoes de vocabulario LOCAL → CLOUD (Supabase/Turso) Trigger: trabalho serio em multi-device Sinal: sincronizacao git fica pesada e conflitante Regra inversa: NAO migre se os criterios nao bateram. Complexidade adicional sem ganho real.
💡 Meca antes de migrar
Antes de 'vou pra SQLite porque ta lento', meça. Rode dashboard 3 meses antes de decidir. Dado > hype.
🎓 Post-mortem: quando da errado
Sistemas falham. Checklist evita que voce perca confianca e desista.
✓ Sintomas → causas
- ✓Claude ignora regra: ver se CLAUDE.md nao ficou no CLAUDE.md vs hook
- ✓Contexto sumiu pos-compactacao: checar PreCompact disparou
- ✓Hit rate baixa: revisar pesos do multi-sinal
- ✓Memoria obsoleta: executar decay.py
✗ Nao fazer
- ✗Reescrever tudo ao primeiro bug
- ✗Adicionar mais hooks sem entender o existente
- ✗Migrar backend antes de medir
- ✗Copiar sistema de outra pessoa sem adaptar
🎉 Curso concluido — proximos 30 dias
Curso acabou. Aplicacao comeca. Plano de 30 dias para transformar conhecimento em habito.
Semana 1: usar
Instalar hooks, popular prime + context, usar Claude Code normalmente. Nao otimizar. Sentir o comportamento novo.
Semana 2: medir
Rodar dashboard. Anotar KPIs. Identificar onde hit rate e baixa. Escrever golden questions para testar consistencia.
Semana 3: ajustar
Uma mudanca por vez: ajustar prime.md inflado, add layer faltante, tune decay. Medir depois de cada ajuste.
Semana 4: compartilhar
Documentar seu setup em README interno. Apresentar para time se aplicavel. Ensinar e a forma mais rapida de dominar.
Dia 30: review
Rode dashboard final. Compare com baseline da semana 1. Voce tem dado concreto do ganho.
💡 Voce terminou o curso
Mas memoria e jogo infinito. Volte em /memory-architect com advisor mode quando necessidade mudar. Esse sistema evolui com voce.
📝 Resumo do Modulo
Proximo:
🎉 Curso concluido — aplique nos proximos 30 dias