CM - Sistema de Memória CASS
Memória procedural para agentes de IA de codificação. Transforma sessões dispersas em memória persistente entre agentes. Utiliza uma arquitetura cognitiva de três camadas que espelha o desenvolvimento da expertise humana.
Por Que Isso Existe
Agentes de IA de codificação acumulam conhecimento valioso, mas ele:
- Fica preso em sessões - Contexto perdido quando a sessão termina
- É específico do agente - Claude não sabe o que o Cursor aprendeu
- Não é estruturado - Logs brutos não são orientação acionável
- Sujeito a colapso - Sumarização ingênua perde detalhes críticos
Você resolveu bugs de autenticação três vezes este mês em diferentes agentes. Cada vez começou do zero.
O CM resolve isso com aprendizado entre agentes: um padrão descoberto no Cursor fica imediatamente disponível para o Claude Code.
Arquitetura Cognitiva de Três Camadas
┌─────────────────────────────────────────────────────────────────────┐
│ MEMÓRIA EPISÓDICA (cass) │
│ Logs brutos de sessões de todos os agentes — a "verdade fundamental"│
│ Claude Code │ Codex │ Cursor │ Aider │ PI │ Gemini │ ChatGPT │ ...│
└───────────────────────────┬─────────────────────────────────────────┘
│ busca cass
▼
┌─────────────────────────────────────────────────────────────────────┐
│ MEMÓRIA DE TRABALHO (Diário) │
│ Resumos estruturados de sessões: realizações, decisões, etc. │
└───────────────────────────┬─────────────────────────────────────────┘
│ refletir + curar (automatizado)
▼
┌─────────────────────────────────────────────────────────────────────┐
│ MEMÓRIA PROCEDIMENTAL (Playbook) │
│ Regras destiladas com rastreamento de confiança e decaimento │
└─────────────────────────────────────────────────────────────────────┘
As sessões de cada agente alimentam a memória compartilhada. Um padrão descoberto no Cursor automaticamente ajuda o Claude Code na próxima sessão.
O Único Comando Que Você Precisa
cm context "<sua tarefa>" --json
Execute isso antes de iniciar qualquer tarefa não trivial. Retorna:
- relevantBullets - Regras do playbook pontuadas pela relevância da tarefa
- antiPatterns - Coisas que causaram problemas
- historySnippets - Sessões passadas (suas e de outros agentes)
- suggestedCassQueries - Pesquisas de investigação mais aprofundadas
Filtrando Histórico por Origem
historySnippets[].origin.kind é "local" ou "remote". Acessos remotos incluem origin.host:
{
"historySnippets": [
{
"source_path": "~/.claude/sessions/session-001.jsonl",
"origin": { "kind": "local" }
},
{
"source_path": "/home/user/.codex/sessions/session.jsonl",
"origin": { "kind": "remote", "host": "workstation" }
}
]
}
Sistema de Decaimento de Confiança
Regras não são imortais. A confiança decai sem revalidação:
| Mecanismo | Efeito |
|---|---|
| Meia-vida de 90 dias | Confiança cai pela metade a cada 90 dias sem feedback |
| Multiplicador 4x prejudicial | Um erro conta 4× mais do que um sucesso |
| Progressão de maturidade | candidato → estabelecido → comprovado |
Visualização da Pontuação de Decaimento
Pontuação inicial: 10,0 (10 marcas úteis hoje)
Após 90 dias (meia-vida): 5,0
Após 180 dias: 2,5
Após 270 dias: 1,25
Após 365 dias: 0,78
Fórmula da Pontuação Efetiva
pontuacaoEfetiva = utilDecaido - (4 × prejudicialDecaido)
// Onde fatorDecaimento = 0,5 ^ (diasDesdeFeedback / 90)
Máquina de Estados de Maturidade
┌──────────┐ ┌─────────────┐ ┌────────┐
│ candidato│──────▶│ estabelecido│───▶│comprovado│
└──────────┘ └─────────────┘ └────────┘
│ │ │
│ │ (prejudicial >25%)│
│ ▼ │
│ ┌─────────────┐ │
└────────────▶│ obsoleto │◀─────────┘
└─────────────┘
Regras de Transição:
| Transição | Critério |
|---|---|
candidato → estabelecido | 3+ úteis, razão prejudicial <25% |
estabelecido → comprovado | 10+ úteis, razão prejudicial <10% |
qualquer → obsoleto | Razão prejudicial >25% OU depreciação explícita |
Aprendizado de Antipadrões
Regras ruins não são apenas excluídas. Elas se tornam avisos:
"Cache tokens de autenticação para desempenho"
↓ (3 marcas prejudiciais)
"ARMADILHA: Não armazene tokens de autenticação em cache sem validação de expiração"
Quando uma regra é marcada como prejudicial várias vezes (razão prejudicial >50% com 3+ marcas), ela é automaticamente invertida em um antipadrão.
Pipeline ACE (Como as Regras São Criadas)
Gerador → Refletor → Validador → Curador
| Estágio | Função | LLM? |
|---|---|---|
| Gerador | Hidratação de contexto pré-tarefa (cm context) | Não |
| Refletor | Extrair padrões de sessões (cm reflect) | Sim |
| Validador | Portão de evidências contra o histórico cass | Sim |
| Curador | Mesclagem delta determinística | Não |
Crítico: O Curador NÃO tem LLM para evitar colapso de contexto por desvio iterativo. LLMs propõem padrões; a lógica determinística os gerencia.
Validação Científica
Antes que uma regra entre no seu playbook, ela é validada contra o histórico cass:
Regra proposta: "Sempre verifique a expiração do token antes de depurar autenticação"
↓
Portão de evidências: Pesquisar cass por sessões onde isso se aplicou
↓
Resultado: 5 sessões encontradas, 4 resultados bem-sucedidos → ACEITAR
Regras sem evidências históricas são sinalizadas como candidatas até serem comprovadas.
Referência de Comandos
Recuperação de Contexto (Fluxo de Trabalho Principal)
# O COMANDO PRINCIPAL - execute antes de tarefas não triviais
cm context "implementar autenticação de usuário" --json
# Limitar resultados para orçamento de tokens
cm context "corrigir bug" --json --limit 5 --no-history
# Com filtro de workspace
cm context "refatorar" --json --workspace /caminho/para/projeto
# Explicação autodocumentada
cm quickstart --json
# Saúde do sistema
cm doctor --json
cm doctor --fix # Corrigir problemas automaticamente
# Encontrar regras semelhantes
cm similar "melhores práticas de tratamento de erros"
Gerenciamento de Playbook
cm playbook list # Todas as regras
cm playbook get b-8f3a2c # Detalhes da regra
cm playbook add "Sempre execute testes primeiro" # Adicionar regra
cm playbook add --file regras.json # Adicionar em lote de arquivo
cm playbook add --file regras.json --session /caminho/sessao.jsonl # Rastrear origem
cm playbook remove b-xyz --reason "Desatualizado" # Remover
cm playbook export > backup.yaml # Exportar
cm playbook import compartilhado.yaml # Importar
cm playbook bootstrap react # Aplicar iniciador ao existente
cm top 10 # Regras mais eficazes
cm stale --days 60 # Regras sem feedback recente
cm why b-8f3a2c # Proveniência da regra
cm stats --json # Métricas de saúde do playbook
Aprendizado e Feedback
# Feedback manual
cm mark b-8f3a2c --helpful
cm mark b-xyz789 --harmful --reason "Causou regressão"
cm undo b-xyz789 # Reverter feedback
# Resultados de sessão (posicional: status, regras)
cm outcome success b-8f3a2c,b-def456
cm outcome failure b-x7k9p1 --summary "Abordagem de autenticação falhou"
cm outcome-apply # Aplicar ao playbook
# Reflexão (geralmente automatizada)
cm reflect --days 7 --json
cm reflect --session /caminho/para/sessao.jsonl # Sessão única
cm reflect --workspace /caminho/para/projeto # Específico do projeto
# Validação
cm validate "Sempre verifique nulo antes de desreferenciar"
# Auditar sessões contra regras
cm audit --days 30
# Obsoleter permanentemente
cm forget b-xyz789 --reason "Substituído por padrão melhor"
Integração (Nativo do Agente)
Construção de playbook com custo zero usando seu agente existente:
cm onboard status # Verificar progresso
cm onboard gaps # Lacunas de categoria
cm onboard sample --fill-gaps # Sessões priorizadas
cm onboard sample --agent claude --days 14 # Filtrar por agente/tempo
cm onboard sample --workspace /caminho/projeto # Filtrar por workspace
cm onboard sample --include-processed # Reanalisar sessões
cm onboard read /caminho/sessao.jsonl --template # Contexto rico
cm onboard mark-done /caminho/sessao.jsonl # Marcar como processado
cm onboard reset # Começar do zero
Trauma Guard (Sistema de Segurança)
cm trauma list # Padrões ativos
cm trauma add "DROP TABLE" --description "Exclusão em massa" --severity critico
cm trauma heal t-abc --reason "Migração intencional"
cm trauma remove t-abc
cm trauma scan --days 30 # Escanear por traumas
cm trauma import compartilhado-traumas.yaml
cm guard --install # Hook do Claude Code
cm guard --git # Hook pre-commit do Git
cm guard --install --git # Ambos
cm guard --status # Verificar instalação
Comandos do Sistema
cm init # Inicializar
cm init --starter typescript # Com modelo
cm init --force # Reinicializar (cria backup)
cm starters # Listar modelos
cm serve --port 3001 # Servidor MCP
cm usage # Estatísticas de custo LLM
cm privacy status # Configurações de privacidade
cm privacy enable # Habilitar enriquecimento entre agentes
cm privacy disable # Desabilitar enriquecimento
cm project --format agents.md # Exportar para AGENTS.md
Playbooks Iniciadores
Começar com um playbook vazio é desafiador. Os iniciadores fornecem melhores práticas selecionadas:
cm starters # Listar disponíveis
cm init --starter typescript # Inicializar com iniciador
cm playbook bootstrap react # Aplicar ao playbook existente
Iniciadores Embutidos
| Iniciador | Foco | Regras |
|---|---|---|
| general | Melhores práticas universais | 5 |
| typescript | Padrões TypeScript/Node.js | 4 |
| react | Desenvolvimento React/Next.js | 4 |
| python | Python/FastAPI/Django | 4 |
| node | Serviços Node.js/Express | 4 |
| rust | Padrões de serviço Rust | 4 |
Iniciadores Personalizados
Crie arquivos YAML em ~/.cass-memory/starters/:
# ~/.cass-memory/starters/django.yaml
name: django
description: Melhores práticas do framework web Django
bullets:
- content: "Sempre use o ORM do Django para operações de banco de dados"
category: banco de dados
maturity: estabelecido
tags: [django, orm]
Feedback Inline (Durante o Trabalho)
Deixe feedback em comentários de código. Analisado durante a reflexão:
// [cass: helpful b-8f3a2c] - esta regra me salvou de uma toca de coelho
// [cass: harmful b-x7k9p1] - este conselho estava errado para nosso caso de uso
Protocolo do Agente
1. INÍCIO: cm context "<tarefa>" --json
2. TRABALHO: Referencie IDs de regras ao segui-las (ex.: "Seguindo b-8f3a2c...")
3. FEEDBACK: Deixe comentários inline quando as regras ajudarem/prejudicarem
4. FIM: Apenas termine. O aprendizado acontece automaticamente.
Você NÃO precisa:
- Executar
cm reflect(a automação cuida disso) - Executar
cm markmanualmente (use comentários inline) - Adicionar regras manualmente ao playbook
Categorias de Análise de Lacunas
| Categoria | Palavras-chave |
|---|---|
debugging | erro, corrigir, bug, trace, stack |
testing | teste, mock, assert, expect, jest |
architecture | design, padrão, módulo, abstração |
workflow | tarefa, CI/CD, deploy |
documentation | comentário, README, doc API |
integration | API, HTTP, JSON, endpoint |
collaboration | revisão, PR, equipe |
git | branch, merge, commit |
security | auth, token, criptografar, permissão |
performance | otimizar, cache, perfil |
Limiares de Status da Categoria:
| Status | Contagem de Regras | Prioridade |
|---|---|---|
critico | 0 regras | Alta |
sub-representado | 1-2 regras | Média |
adequado | 3-10 regras | Baixa |
bem-coberto | 11+ regras | Nenhuma |
Trauma Guard: Sistema de Segurança
O princípio do "fogão quente" — aprender com incidentes passados e prevenir recorrências.
Como Funciona
Histórico de Sessão Registro de Trauma Guarda de Tempo de Execução
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ rm -rf /* (ops) │ ──────▶ │ Padrão: rm -rf │ ──────▶ │ BLOQUEADO: Este │
│ "desculpe, eu │ scan │ Severidade: FATAL│ hook │ comando │
│ errei..." │ │ Sessão: abc123 │ │ corresponde a um│
└─────────────────┘ └─────────────────┘ └─────────────────┘
Padrões de Perigo Embutidos (20+)
| Categoria | Exemplos |
|---|---|
| Sistema de Arquivos | rm -rf /, rm -rf ~, exclusões recursivas |
| Banco de Dados | DROP DATABASE, TRUNCATE, DELETE FROM sem WHERE |
| Git | git push --force para main/master, git reset --hard |
| Infraestrutura | terraform destroy -auto-approve, kubectl delete namespace |
| Nuvem | aws s3 rm --recursive, CloudFormation destrutivo |
Armazenamento de Padrões
| Escopo | Localização | Propósito |
|---|---|---|
| Global | ~/.cass-memory/traumas.jsonl | Padrões pessoais |
| Projeto | .cass/traumas.jsonl | Commit ao repositório para a equipe |
Ciclo de Vida do Padrão
- Ativo: Bloqueia comandos correspondentes
- Curado: Bypass temporário (com motivo e timestamp)
- Excluído: Removido (pode ser readicionado)
Servidor MCP
Execute como servidor MCP para integração com agentes:
# Apenas local (recomendado)
cm serve --port 3001
# Com token de autenticação (para não-loopback)
MCP_HTTP_TOKEN="<aleatório>" cm serve --host 0.0.0.0 --port 3001
Ferramentas Expostas
| Ferramenta | ... |
|---|