@justmpm/memory 0.2.1 → 0.3.0

package/AGENTS.md

@@ -1,694 +1,99 @@
-# @justmpm/memory - Guia para Subagents (AGENTS.md)
+# @justmpm/memory - Guia para Subagents
 
-## Visão Geral
+## O que é este MCP?
 
-Este documento orienta os diferentes subagents (nexus, sentinel, qa-tester, etc.) sobre como usar o sistema de memória persistente do projeto.
+Este servidor MCP permite que você (subagent) salve e recupere aprendizados entre diferentes sessões de trabalho. Cada agent tem sua própria memória isolada.
 
-**Objetivo:** Permitir que cada subagent mantenha sua própria memória de aprendizados específicos entre sessões de trabalho.
+**Propósito:** Manter persistência de conhecimento específico do projeto entre sessões.
 
 ---
 
-## Quem Deve Usar Memória
+## Tools Disponíveis
 
-TODOS os subagents que participam de tarefas complexas e recorrentes devem usar memória. Isso inclui:
+### memory_read
+Lê todo o conteúdo da sua memória persistente.
 
-- **nexus** - Orquestrador principal
-- **sentinel** - Estrategista de validação
-- **qa-tester** - Tester com automação no Chrome
-- **fix-worker** - Implementações e correções
-- **ui-designer** - Design e refatoração visual
-- **discover-opportunities** - Descoberta de features não exploradas
-- **audit-* (todos os audit agents)** - Auditorias especializadas
+**Use sempre ao iniciar uma sessão** para recuperar contexto anterior.
 
----
-
-## Como Identificar Seu Nome de Agent
-
-Seu nome de agent é passado automaticamente pelo sistema. Para saber qual é:
-
-1. **Verifique seu contexto de inicialização** - O nome geralmente é explicitado
-2. **Use o comando `list`** - Para ver todos os agents com memória no projeto
-3. **Pergunte ao nexus/orquestrador** - Se estiver incerto
-
-**Nomes comuns:**
-- `nexus` - Orquestrador principal
-- `sentinel` - Estrategista de validação
-- `qa-tester` - QA com automação no Chrome
-- `fix-worker` - Executor de implementações
-- `ui-designer` - Designer visual
-
-**Normalização automática:**
-- "Sentinel" → `sentinel`
-- "QA-Tester" → `qa-tester`
-- "My Agent" → `my-agent`
-
----
-
-## Quando Usar Memória
-
-### Sempre Use Quando:
-
-✅ **Ao iniciar uma sessão de trabalho**
-- Use `read` para carregar aprendizados anteriores
-- Analise o contexto salvo antes de começar
-- Use as informações para informar suas decisões
-
-✅ **Ao aprender algo sobre o projeto**
-- Descobrir padrões de código
-- Identificar estruturas recorrentes
-- Entender arquitetura específica
-
-✅ **Ao encontrar problemas recorrentes**
-- Bugs que aparecem em múltiplas tarefas
-- Erros de configuração
-- Limitações de ferramentas
-
-✅ **Ao tomar decisões**
-- Escolhas técnicas
-- Trade-offs considerados
-- Razões para não usar X
-
-✅ **Ao entender preferências**
-- Estilo de código preferido
-- Nível de detalhe esperado
-- Comunicação preferida
-
-### NÃO Use Quando:
-
-❌ **Para tarefas triviais de uma linha**
-- "Como escrever um loop for" não precisa ser salvo
-- "Como criar um array" é óbvio demais
-
-❌ **Para coisas específicas da sessão atual**
-- Conversação em andamento
-- Variáveis temporárias
-- Experimentos isolados
-
-❌ **Para duplicar informações**
-- Se algo já está salvo, não salve novamente
-- Use `search` para verificar antes
-
----
-
-## Por Tipo de Agent
-
-### Nexus (Orquestrador)
-
-**Seu foco:** Coordenação, decisões de orquestração, preferências do usuário
-
-**O que salvar:**
-- Padrões de orquestração (ex: "Para tarefas > 5 arquivos, use /relay")
-- Decisões sobre qual agent usar (ex: "Escolhi fix-worker porque...")
-- Preferências do Matheus (ex: "Prefere resposta direta sem enrolação")
-- Sequências de comandos que funcionaram bem
-- Trade-offs que você fez e por quê
-
-**O que NÃO salvar:**
-- Cada mensagem da conversa
-- Coisas óbvias sobre sua função
-- Detalhes técnicos específicos de implementação (deixe isso para fix-worker)
-
-**Exemplo de entrada:**
-```json
-{
-  "command": "append",
-  "agent": "nexus",
-  "entry": "Decisão: Para tarefas longas com > 5 arquivos, use /relay. Para 3-5 arquivos, fix-worker direto funciona melhor. Motivo: /relay mantém contexto entre sessões, fix-worker é mais rápido para tarefas menores"
-}
-```
-
----
-
-### Sentinel (Estrategista de Validação)
-
-**Seu foco:** Validação de planos, identificação de riscos, estratégias de implementação
-
-**O que salvar:**
-- Padrões de risco identificados no projeto
-- Tipos de erros que ocorrem frequentemente
-- Estratégias de validação que funcionaram
-- Limitações de arquitetura descobertas
-- Padrões de boas práticas específicos
-
-**O que NÃO salvar:**
-- Detalhes de validação triviais
-- Erros de uma única ocorrência
-- Coisas que são padrão geral (deixe isso para a documentação oficial)
-
-**Exemplo de entrada:**
-```json
-{
-  "command": "append",
-  "agent": "sentinel",
-  "entry": "Padrão de risco: Este projeto tem dependência circular entre /services/auth.ts e /services/user.ts. Quando validar planos que tocam esses arquivos, sempre verifique impacto em ambos."
-}
-```
-
----
-
-### QA-Tester (Tester com Automação Chrome)
-
-**Seu foco:** Testes automatizados no navegador, bugs encontrados, workflows de teste
-
-**O que salvar:**
-- Bugs recorrentes que encontrou
-- Workflows de teste que funcionam
-- Padrões de comportamento da aplicação
-- Configurações de ambiente necessárias
-- Casos de borda importantes
-
-**O que NÃO salvar:**
-- Cada bug individual de teste
-- Detalhes triviais de navegação
-- Coisas que mudam entre testes
-
-**Exemplo de entrada:**
-```json
-{
-  "command": "append",
-  "agent": "qa-tester",
-  "entry": "Bug recorrente: O botão de submit no formulário de login não funciona quando usuário pressiona Enter rapidamente. Reproduzível em Chrome 120. Workaround: Use click() em vez de submit()"
-}
-```
-
----
-
-### Fix-Worker (Executor de Implementações)
-
-**Seu foco:** Implementações, correções, código escrito
-
-**O que salvar:**
-- Padrões de código descobertos no projeto
-- Convenções específicas de formatação
-- Workarounds para problemas do stack
-- Integrações complexas que funcionaram
-- Limitações técnicas encontradas
-
-**O que NÃO salvar:**
-- Cada implementação individual
-- Coisas que são padrão de linguagem/framework
-- Detalhes que são óbvios do stack
-
-**Exemplo de entrada:**
 ```json
 {
-  "command": "append",
-  "agent": "fix-worker",
-  "entry": "Padrão: Este projeto usa Zod v4.3.5 com strict mode. Quando criar schemas, sempre use .strict() e .parse() ao invés de .safeParse() para lançar erros automaticamente"
+  "agent": "seu-nome"  // OBRIGATÓRIO
 }
 ```
 
----
-
-### UI-Designer (Designer Visual)
+### memory_append
+Adiciona uma entrada no final da sua memória com timestamp automático.
 
-**Seu foco:** Design, estética visual, refatoração UI, MUI v7
+**Use quando aprender algo importante:** padrões de código, bugs, decisões, preferências do usuário.
 
-**O que salvar:**
-- Tokens de design usados no projeto
-- Padrões visuais recorrentes
-- Preferências estéticas do usuário
-- Componentes MUI customizados
-- Limitações visuais descobertas
-
-**O que NÃO salvar:**
-- Cada ajuste visual individual
-- Coisas que são padrão MUI
-- Detalhes triviais de CSS
-
-**Exemplo de entrada:**
 ```json
 {
-  "command": "append",
-  "agent": "ui-designer",
-  "entry": "Padrão visual: Este projeto usa MUI v7 com tema customizado. Cores primárias são indigo (#6366f1) e secundárias são emerald (#10b981). Use sempre variantes outlined para inputs e contained para botões de ação"
+  "agent": "seu-nome",      // OBRIGATÓRIO
+  "entry": "texto aqui"     // OBRIGATÓRIO
 }
 ```
 
----
-
-### Audit Agents (todos os audit-*)
+### memory_search
+Busca um termo na sua memória sem precisar ler tudo.
 
-**Seu foco:** Auditorias especializadas, bugs encontrados, boas práticas
+**Use para encontrar informações rapidamente.**
 
-**O que salvar:**
-- Padrões de bugs encontrados no projeto
-- Boas práticas que foram violadas frequentemente
-- Configurações específicas que causam problemas
-- Workflows de auditoria que funcionaram
-- Integrações problemáticas
-
-**O que NÃO salvar:**
-- Cada bug de auditoria individual
-- Coisas que são padrão de qualidade geral
-- Erros de uma única ocorrência
-
-**Exemplo de entrada (audit-technical):**
 ```json
 {
-  "command": "append",
-  "agent": "audit-technical",
-  "entry": "Padrão de bug: Este projeto frequentemente esquece de tratar erros async/await. Use try/catch em todas as funções async ou .catch() em Promises"
+  "agent": "seu-nome",      // OBRIGATÓRIO
+  "query": "termo"          // OBRIGATÓRIO
 }
 ```
 
----
-
-### Discover-Opportunities (Descoberta de Features)
-
-**Seu foco:** Features não exploradas, diferenciais competitivos, verticais ausentes
+### memory_write
+SUBSTITUI TODO o conteúdo da sua memória. **APAGA tudo o que estava antes.**
 
-**O que salvar:**
-- Padrões de features que fazem sentido para o projeto
-- Verticais identificadas como ausentes
-- Diferenciais competitivos sugeridos
-- Restrições de negócio entendidas
-- Padrões de domínio do projeto
+**Use apenas quando:** memória está grande (~150+ linhas) e precisa reorganizar.
 
-**O que NÃO salvar:**
-- Cada sugestão individual
-- Coisas que não fazem sentido para o domínio
-- Ideias vagas sem contexto
-
-**Exemplo de entrada:**
 ```json
 {
-  "command": "append",
-  "agent": "discover-opportunities",
-  "entry": "Padrão: Este projeto é um CRM de pets. Vertical ausente: não há funcionalidade de telemedicina veterinária, que seria um diferencial competitivo forte"
+  "agent": "seu-nome",           // OBRIGATÓRIO
+  "content": "# Memória\\n\\n- item",  // OBRIGATÓRIO
+  "backup": true                 // opcional, cria backup antes
 }
 ```
 
 ---
 
-## Comandos Essenciais por Agent
-
-### Para TODOS os agents
+## Workflow Básico
 
-**Ao iniciar trabalho:**
-```json
-{
-  "command": "read",
-  "agent": "seu-nome-aqui"
-}
+### Iniciando uma sessão:
 ```
-
-**Para salvar algo importante:**
-```json
-{
-  "command": "append",
-  "agent": "seu-nome-aqui",
-  "entry": "O que você aprendeu"
-}
+1. Use memory_read
+2. Analise o conteúdo retornado
+3. Use as informações salvas para informar suas decisões
 ```
 
-**Para verificar algo antes de salvar:**
-```json
-{
-  "command": "search",
-  "agent": "seu-nome-aqui",
-  "query": "termo-busca"
-}
+### Durante o trabalho:
 ```
-
-**Para limpar memória grande:**
-```json
-{
-  "command": "write",
-  "agent": "seu-nome-aqui",
-  "content": "# Memória do Seu-Nome\n\n## Seções\n..."
-}
+Ao aprender algo importante → memory_append
+Ao tomar uma decisão → memory_append
+Ao descobrir um bug → memory_append
 ```
 
-### Específicos por tipo de agent
-
-**Orquestradores (nexus):**
-```json
-// Salvar decisão de orquestração
-{
-  "command": "append",
-  "agent": "nexus",
-  "entry": "Decisão: Escolhi /relay para esta tarefa porque envolve > 10 arquivos e precisa manter contexto entre sessões"
-}
+### Onde a memória fica:
 ```
-
-**Executores (fix-worker, ui-designer):**
-```json
-// Salvar padrão de código
-{
-  "command": "append",
-  "agent": "fix-worker",
-  "entry": "Padrão: Sempre use try/catch em funções async que acessam Firestore"
-}
+.claude/agent-memory/<seu-nome>/MEMORY.md
 ```
 
-**Auditores (audit-*, sentinel, qa-tester):**
-```json
-// Salvar bug recorrente
-{
-  "command": "append",
-  "agent": "audit-technical",
-  "entry": "Bug recorrente: Formulários sem validação de Zod causam erros runtime em produção. Sempre adicione .strict() aos schemas"
-}
-```
-
-**Analisadores (discover-opportunities):**
-```json
-// Salvar padrão de domínio
-{
-  "command": "append",
-  "agent": "discover-opportunities",
-  "entry": "Padrão de domínio: Este projeto é focado em B2B, então features B2C (como reviews públicos) não são prioridade"
-}
-```
-
----
-
-## Formato de Memória por Tipo de Agent
-
-### Nexus (Orquestrador)
-
-```markdown
-# Memória do Nexus
-
-## Padrões de Orquestração
-- Para tarefas > 5 arquivos, use /relay
-- Para 3-5 arquivos, fix-worker direto funciona melhor
-- Use analyze antes de delegar para agents
-
-## Decisões
-- Escolhi /relay para tarefas longas
-- Prefiro fix-worker para implementações diretas
-
-## Preferências do Matheus
-- Prefere resposta direta sem enrolação
-- Gosta de explicações simples
-- Valida decisões com contexto
-
-## Anti-padrões
-- Não chame agents sem investigar antes
-- Não assuma, pergunte se não tiver certeza
-```
-
-### Fix-Worker (Executor)
-
-```markdown
-# Memória do Fix-Worker
-
-## Padrões de Código
-- Use Zod com .strict() para validação
-- Trate erros async com try/catch
-- Use TypeScript strict mode
-
-## Integrações
-- Firestore: sempre verifique se array tem length > 0
-- Firebase Auth: use onAuthStateChanged para estado
-
-## Bugs Conhecidos
-- Bug XYZ: ocorre quando array vazio
-- Workaround: verificar antes de update
-
-## Limitações
-- Não consegue acessar recursos externos sem permissão
-```
-
-### QA-Tester (Tester)
-
-```markdown
-# Memória do QA-Tester
-
-## Padrões de Teste
-- Use Chrome 120+ para testes
-- Sempre limpe localStorage antes de testar
-- Use wait() para carregamento assíncrono
-
-## Bugs Recorrentes
-- Login falha quando Enter é pressionado
-- Workaround: usar click() em vez de submit
-
-## Configurações de Ambiente
-- URL base: http://localhost:3000
-- Timeout padrão: 10 segundos
-
-## Workflows de Teste
-- Teste de login: 1) Navegue para /login 2) ...
-```
-
-### UI-Designer (Designer)
-
-```markdown
-# Memória do UI-Designer
-
-## Tokens de Design
-- Primária: indigo (#6366f1)
-- Secundária: emerald (#10b981)
-- Fonte: Inter, 400/500/600
-
-## Padrões Visuais
-- Botões: variant outlined para inputs, contained para ações
-- Cards: elevation={2}, padding={3}
-- Spacing: múltiplos de 8px
-
-## Componentes MUI Customizados
-- CustomButton: com icon support
-- CustomCard: com hover effect
-
-## Preferências do Matheus
-- Prefere design minimalista
-- Gosta de consistência visual
-- Evita animações excessivas
-```
-
----
-
-## Compartilhamento de Informações Entre Agents
-
-### Como Nexus pode ajudar outros agents
-
-**Ao delegar para fix-worker:**
-```json
-{
-  "command": "read",
-  "agent": "nexus"
-}
-
-// Nexus analisa se há informações relevantes para fix-worker
-// Se houver, passa no contexto da delegação
-```
-
-**Ao delegar para ui-designer:**
-```json
-{
-  "command": "read",
-  "agent": "nexus"
-}
-
-// Nexus busca preferências visuais do Matheus
-// Passa essas informações para ui-designer
-```
-
-### Como outros agents podem compartilhar com Nexus
-
-**Ao completar tarefa:**
-- Fix-worker: reporta padrões de código descobertos
-- QA-Tester: reporta bugs recorrentes encontrados
-- UI-Designer: reporta limitações visuais descobertas
-
-Nexus pode então usar `append` para salvar essas informações se forem importantes.
-
-### Quando usar `list` para descobrir outros agents
-
-```json
-{
-  "command": "list"
-}
-```
-
-**Útil para:**
-- Saber quais agents já trabalharam no projeto
-- Verificar se há memória relevante em outros agents
-- Entender a história do projeto
-
----
-
-## Boas Práticas Específicas por Agent
-
-### Para Orquestradores (Nexus)
-
-✅ **DO:**
-- Salve decisões de por que escolheu X ao invés de Y
-- Salve padrões de orquestração que funcionaram
-- Salve preferências do usuário para passar a outros agents
-- Use `list` para descobrir agents existentes antes de delegar
-- Leia memória de outros agents se for relevante
-
-❌ **DON'T:**
-- Salve cada decisão trivial
-- Salve detalhes técnicos de implementação
-- Assuma que sabe tudo o que outros agents descobriram
-
-### Para Executores (Fix-Worker, UI-Designer)
-
-✅ **DO:**
-- Salve padrões de código/design específicos do projeto
-- Salve workarounds para problemas recorrentes
-- Salve limitações técnicas encontradas
-- Salve integrações que funcionaram bem
-- Use `search` para verificar se algo já foi salvo
-
-❌ **DON'T:**
-- Salve cada implementação individual
-- Salve coisas que são padrão de linguagem/framework
-- Salve detalhes triviais que não se repetem
-
-### Para Auditores (Audit-*, Sentinel, QA-Tester)
-
-✅ **DO:**
-- Salve padrões de bugs encontrados no projeto
-- Salve workflows de auditoria/teste que funcionaram
-- Salve configurações que causam problemas
-- Salve boas práticas violadas frequentemente
-- Salve restrições de ambiente/teste
-
-❌ **DON'T:**
-- Salve cada bug individual de uma única ocorrência
-- Salve coisas que são padrão geral de qualidade
-- Salve detalhes triviais de navegação/teste
-
-### Para Analisadores (Discover-Opportunities)
-
-✅ **DO:**
-- Salve padrões de domínio do projeto
-- Salve verticais identificadas como ausentes
-- Salve restrições de negócio entendidas
-- Salver diferenciais competitivos que fazem sentido
-- Salvar estratégias de análise que funcionaram
-
-❌ **DON'T:**
-- Salvar cada sugestão individual sem contexto
-- Salvar ideias vagas sem relação com o domínio
-- Salvar coisas que não fazem sentido para o projeto
-
----
-
-## Exemplos Completos de Uso
-
-### Exemplo 1: Nexus iniciando sessão e delegando
-
-```
-// Nexus: Lê sua própria memória
-IA: { "command": "read", "agent": "nexus" }
-
-Resultado: 📝 Memória de "nexus" (30 linhas):
-─────────────────────────────────────────────────────────────────
-
-# Memória do Nexus
-
-## Padrões de Orquestração
-- Para tarefas > 5 arquivos, use /relay
-- Use analyze antes de delegar
-
-## Preferências do Matheus
-- Prefere resposta direta sem enrolação
-...
-
-// Nexus: Lista todos os agents com memória
-IA: { "command": "list" }
-
-Resultado: 📝 Agents com memória neste projeto (3):
-
-  • nexus (30 linhas)
-  • fix-worker (45 linhas)
-  • ui-designer (20 linhas)
-
-// Nexus: Lê memória do fix-worker para entender contexto
-IA: { "command": "read", "agent": "fix-worker" }
-
-Resultado: 📝 Memória de "fix-worker" (45 linhas):
-─────────────────────────────────────────────────────────────────
-
-# Memória do Fix-Worker
-
-## Padrões de Código
-- Use Zod com .strict() para validação
-...
-
-// Nexus: Delega para fix-worker com contexto completo
-IA: [Usa task para chamar fix-worker com contexto sobre o projeto]
-```
-
-### Exemplo 2: Fix-worker descobrindo padrão e salvando
-
-```
-// Fix-worker: Implementa um formulário
-IA: [Escreve código do formulário]
-
-// Fix-worker: Nota que todos os formulários usam Zod
-IA: { "command": "search", "agent": "fix-worker", "query": "Zod" }
-
-Resultado: 📝 Nenhuma ocorrência de "Zod" encontrada
-
-// Fix-worker: Salva o padrão descoberto
-IA: { "command": "append", "agent": "fix-worker",
-     "entry": "Padrão descoberto: Este projeto usa Zod v4.3.5 com strict mode para validação de formulários. Sempre use .strict() e .parse() ao criar schemas de formulário" }
-```
-
-### Exemplo 3: QA-tester encontrando bug recorrente
-
-```
-// QA-tester: Testa formulário de login
-IA: [Executa teste automatizado no Chrome]
-
-// QA-tester: Encontra bug ao pressionar Enter
-IA: { "command": "search", "agent": "qa-tester", "query": "Enter" }
-
-Resultado: 📝 Nenhuma ocorrência de "Enter" encontrada
-
-// QA-tester: Verifica se ocorre em outros formulários
-IA: [Testa mais formulários]
-
-// QA-tester: Confirma que é um padrão recorrente
-IA: { "command": "append", "agent": "qa-tester",
-     "entry": "Bug recorrente: Botões de submit em formulários não funcionam quando usuário pressiona Enter. Ocorre em formulários de login, cadastro e contato. Workaround: usar event de click() em vez de submit()" }
-```
-
----
-
-## Checklist por Sessão
-
-### Ao INICIAR sessão de trabalho
-
-- [ ] Use `read` para carregar sua memória
-- [ ] Analise o conteúdo retornado
-- [ ] Use `list` para descobrir outros agents (se relevante)
-- [ ] Leia memórias de outros agents se for relevante para sua tarefa
-
-### DURANTE a sessão
-
-- [ ] Use `search` antes de salvar algo novo
-- [ ] Salve apenas coisas que são específicas e importantes
-- [ ] Seja específico e contextual em suas entradas
-- [ ] Explique o PORQUÊ quando relevante
-
-### Ao FINAL da sessão
-
-- [ ] Revise as entradas adicionadas
-- [ ] Se memória estiver grande (~150+ linhas), considere `WRITE`
-- [ ] Organize as entradas em seções (se usar WRITE)
-- [ ] Compartilhe informações relevantes com nexus/outros agents
+### Limite de tamanho:
+- Máximo 200 linhas
+- Ao atingir, mantém apenas as últimas 160
 
 ---
 
-## Resumo Rápido
+## Dicas Rápidas
 
-| Comando | Nexus | Fix-Worker | QA-Tester | UI-Designer |
-|---------|-------|------------|-----------|--------------|
-| `read` | ✅ Sempre | ✅ Sempre | ✅ Sempre | ✅ Sempre |
-| `append` | Decisões, preferências | Padrões de código | Bugs recorrentes | Padrões visuais |
-| `write` | Reorganizar | Reorganizar | Reorganizar | Reorganizar |
-| `search` | Verificar antes | Verificar antes | Verificar antes | Verificar antes |
-| `list` | Descobrir agents | Raramente | Raramente | Raramente |
+- **Antes de salvar:** Use `memory_search` para verificar se já existe
+- **Seja específico:** "Use 2 espaços" > "Formate bem"
+- **Explique o PORQUÊ:** Não só o que, mas também por que
+- **Não salve:** Coisas triviais, informações temporárias, logs de conversa
 
 ---
 
-**Lembre-se:** Cada agent tem sua própria especialização e foco. Salve o que é relevante para SUA função, não tudo o que você faz!
+**Lembre-se:** A memória é para preservar conhecimento importante entre sessões, não registrar toda a conversa. Seja seletivo!