@justmpm/memory 0.1.0 → 0.1.2

package/CLAUDE.md

@@ -0,0 +1,575 @@
+# @justmpm/memory - Documentação para IA (CLAUDE.md)
+
+## O que é o @justmpm/memory?
+
+**@justmpm/memory** é um servidor MCP (Model Context Protocol) que permite que você, como agent, salve e recupere aprendizados entre diferentes sessões de trabalho.
+
+**Propósito principal:** Manter persistência de conhecimento específico do projeto entre sessões, para que você não precise reaprender as mesmas coisas sempre que iniciar uma nova conversa.
+
+---
+
+## Como Funciona
+
+### Estrutura de Arquivos
+
+```
+.claude/
+└── agent-memory/
+    ├── nexus/
+    │   └── MEMORY.md         ← Seu arquivo de memória
+    ├── sentinel/
+    │   └── MEMORY.md         ← Memória do Sentinel
+    ├── qa-tester/
+    │   └── MEMORY.md         ← Memória do QA-Tester
+    └── ...
+```
+
+**Importante:**
+- Cada agent tem sua própria memória isolada
+- O nome do arquivo é sempre `MEMORY.md`
+- O nome da pasta é o nome do agent normalizado (lowercase, hífens)
+
+### Limite de Tamanho
+
+- **Máximo:** 200 linhas
+- **Quando excedido:** Mantém as últimas 160 linhas + cabeçalho de alerta
+- **Auto-limpeza:** Removerá as entradas mais antigas automaticamente
+
+---
+
+## Tool Memory: Comandos Disponíveis
+
+### 1. READ - Carregar memória anterior
+
+**Quando usar:**
+- Ao INICIAR uma nova sessão
+- Antes de tomar decisões baseadas em aprendizados anteriores
+- Quando precisar entender o contexto do projeto
+
+**Sintaxe:**
+```json
+{
+  "command": "read",
+  "agent": "nexus"  // ← Seu nome de agent
+}
+```
+
+**O que retorna:**
+- Conteúdo completo do MEMORY.md
+- Contagem de linhas
+- Se não existir: mensagem de memória vazia com sugestão
+
+**Workflow recomendado:**
+```
+1. Primeira coisa ao iniciar sessão: READ
+2. Analise o conteúdo retornado
+3. Use as informações salvas para informar suas decisões
+```
+
+---
+
+### 2. APPEND - Salvar aprendizado novo
+
+**Quando usar:**
+- Ao APRENDER algo importante sobre o projeto
+- Ao descobrir PADRÕES de código
+- Ao encontrar BUGS recorrentes
+- Ao tomar DECISÕES arquiteturais
+- Ao aprender PREFERÊNCIAS do usuário
+
+**Sintaxe:**
+```json
+{
+  "command": "append",
+  "agent": "nexus",
+  "entry": "Padrão descoberto: Sempre use Zod para validar inputs do usuário em todos os componentes de formulário"
+}
+```
+
+**O que acontece:**
+- Adiciona automaticamente um timestamp: `## [2026-02-09 12:34:56]`
+- Insere sua entrada abaixo do timestamp
+- Mantém todas as entradas anteriores
+- Aplica limite de 200 linhas automaticamente
+
+**Dicas para bons entries:**
+- Seja ESPECÍFICO: "Use 2 espaços" > "Formate bem"
+- Adicione CONTEXTO: "No projeto X, use Y..."
+- Use markdown estruturado quando apropriado
+- Explique O PORQUÊ, não só o que
+
+**Exemplos de bons entries:**
+
+```json
+// Padrão de código
+{
+  "command": "append",
+  "agent": "nexus",
+  "entry": "Padrão: Este projeto usa App Router com estrutura /features/[domain]/. Sempre que criar um novo domínio, coloque em /features/[domain]/components, /features/[domain]/hooks, etc."
+}
+
+// Decisão arquitetural
+{
+  "command": "append",
+  "agent": "nexus",
+  "entry": "Decisão: Escolhemos Zustand em vez de Redux para estado global. Motivo: mais leve, TypeScript-friendly, e este projeto tem até 5 stores independentes"
+}
+
+// Bug recorrente
+{
+  "command": "append",
+  "agent": "nexus",
+  "entry": "Bug: Firestore update com array de strings falha silenciosamente quando array está vazio. Workaround: sempre verificar if (array.length > 0) antes de update"
+}
+
+// Preferência do usuário
+{
+  "command": "append",
+  "agent": "nexus",
+  "entry": "Preferência: Matheus prefere componentes funcionais simples com styled-components em vez de criar arquivos separados CSS"
+}
+```
+
+---
+
+### 3. WRITE - Reorganizar memória
+
+**Quando usar:**
+- Quando memória estiver MUITO GRANDE (perto de 200 linhas)
+- Para REORGANIZAR estruturas e seções
+- Para REMOVER entradas obsoletas
+- Para RECONSTRUIR memória do zero
+
+**Sintaxe:**
+```json
+{
+  "command": "write",
+  "agent": "nexus",
+  "content": "# Memória do Nexus\n\n## Padrões\n- Sempre use TypeScript estrito\n\n## Decisões\n- Zustand em vez de Redux\n\n## Bugs\n- Bug XYZ ocorre quando..."
+}
+```
+
+**O que acontece:**
+- SUBSTITUI TODO o conteúdo existente
+- Aplica limite de 200 linhas
+- Cria estrutura nova do zero
+
+**CUIDADO:** `write` APAGA tudo o que estava antes! Use com cautela.
+
+**Quando usar write vs append:**
+
+| Situação | Use |
+|----------|-----|
+| Aprender algo novo | `append` |
+| Salvar decisão incremental | `append` |
+| Memória grande demais | `write` |
+| Remover entradas obsoletas | `write` |
+| Reorganizar seções | `write` |
+
+**Exemplo de reorganização:**
+
+```json
+{
+  "command": "write",
+  "agent": "nexus",
+  "content": "# Memória do Nexus\n\n## Padrões de Código\n- Sempre use TypeScript estrito (noImplicitAny: true)\n- Use 2 espaços de indentação em TSX\n- Nomeie componentes com PascalCase\n\n## Arquitetura\n- App Router com estrutura /features/[domain]/\n- Cada domínio tem components/, hooks/, services/\n\n## Decisões\n- Zustand para estado global (mais leve que Redux)\n- Firestore para banco de dados (escalabilidade)\n- MUI v7 para componentes UI\n\n## Bugs Conhecidos\n- Bug XYZ: ocorre quando... (workaround: ...)\n- Bug ABC: acontece se... (solução: ...)\n\n## Preferências do Matheus\n- Prefere componentes funcionais\n- Gosta de código conciso (1-3 linhas quando possível)\n- Valoriza explicações simples"
+}
+```
+
+---
+
+### 4. SEARCH - Buscar informação específica
+
+**Quando usar:**
+- Para encontrar informações rápidas sem ler tudo
+- Para verificar se algo já foi documentado
+- Para buscar padrões específicos
+
+**Sintaxe:**
+```json
+{
+  "command": "search",
+  "agent": "nexus",
+  "query": "Zod"
+}
+```
+
+**O que retorna:**
+- Até 20 ocorrências com número da linha
+- Case-insensitive (busca "zod" e "Zod" da mesma forma)
+- Se não encontrado: mensagem clara
+
+**Exemplos de buscas úteis:**
+
+```json
+// Buscar padrão específico
+{ "command": "search", "agent": "nexus", "query": "padrão" }
+
+// Buscar bug específico
+{ "command": "search", "agent": "nexus", "query": "bug" }
+
+// Buscar tecnologia
+{ "command": "search", "agent": "nexus", "query": "TypeScript" }
+
+// Buscar preferência
+{ "command": "search", "agent": "nexus", "query": "Matheus" }
+
+// Buscar erro específico
+{ "command": "search", "agent": "nexus", "query": "Firebase" }
+```
+
+---
+
+### 5. LIST - Descobrir agents existentes
+
+**Quando usar:**
+- Para descobrir quais agents já usaram memória no projeto
+- Ao iniciar trabalho em projeto desconhecido
+
+**Sintaxe:**
+```json
+{
+  "command": "list"
+}
+```
+
+**O que retorna:**
+- Lista de todos os agents com memória
+- Contagem de linhas de cada um
+- Se nenhum: mensagem de "nenhum agent com memória"
+
+---
+
+## Workflow Recomendado para Você (IA)
+
+### Ao Iniciar uma Sessão
+
+```
+1. { "command": "read", "agent": "nexus" }
+   ↓
+2. Analise as entradas retornadas
+   ↓
+3. Use o conhecimento salvo para informar suas respostas
+   ↓
+4. Se a memória estiver muito grande, considere reorganizar com WRITE
+```
+
+### Durante a Sessão
+
+```
+Ao aprender algo importante → APPEND
+Ao tomar uma decisão → APPEND
+Ao descobrir um bug → APPEND
+Ao identificar um padrão → APPEND
+```
+
+### Ao Final da Sessão
+
+```
+1. Revise as entradas adicionadas
+   ↓
+2. Se memória estiver grande (~150+ linhas), considere WRITE para limpar
+   ↓
+3. Organize as entradas em seções (Padrões, Decisões, Bugs, etc.)
+```
+
+---
+
+## O Que Salvar vs Não Salvar
+
+### ✅ SEMPRE salve
+
+**Padrões de código:**
+- Convenções de nomenclatura
+- Estrutura de arquivos do projeto
+- Padrões de importação
+- Formatação específica
+
+**Decisões arquiteturais:**
+- Escolha de tecnologias e PORQUÊ
+- Trade-offs considerados
+- Razões para não usar X
+
+**Bugs recorrentes:**
+- Bugs que aparecem com frequência
+- Workarounds conhecidos
+- Soluções temporárias
+
+**Soluções específicas:**
+- Como resolver problemas específicos do projeto
+- Configurações que funcionaram
+- Comandos úteis
+
+**Configurações importantes:**
+- Setup de Firebase, Stripe, etc.
+- Variáveis de ambiente importantes
+- Chaves de configuração
+
+**Preferências do usuário:**
+- Estilo de código preferido
+- Nível de detalhe esperado em explicações
+- Comunicação preferida
+
+### ❌ NÃO salve
+
+**Coisas triviais:**
+- "Hoje está chovendo"
+- "Tudo funcionou bem"
+
+**Informações que mudam frequentemente:**
+- "Tem 3 arquivos na pasta"
+- "O build levou 5 segundos"
+
+**Coisas óbvias:**
+- "O código precisa compilar"
+- "Use TypeScript para tipagem"
+
+**Informações duplicadas:**
+- Se um padrão já está salvo, não salve novamente
+- Use SEARCH antes de salvar para verificar
+
+**Logs de conversação:**
+- Não salve cada mensagem da conversa
+- Salve apenas o APRENDIZADO, não a conversa inteira
+
+---
+
+## Formato Recomendado
+
+Use seções markdown bem organizadas:
+
+```markdown
+# Memória do Nexus
+
+## Padrões de Código
+- Sempre use TypeScript estrito
+- Use 2 espaços de indentação em TSX
+- Nomeie componentes com PascalCase
+- Coloque componentes em /components/, hooks em /hooks/
+
+## Arquitetura
+- App Router com estrutura /features/[domain]/
+- Cada domínio tem components/, hooks/, services/
+- Firebase para backend (Firestore, Auth, Functions)
+- Zustand para estado global
+
+## Decisões
+- Zustand em vez de Redux: mais leve, TypeScript-friendly
+- Firestore em vez de PostgreSQL: melhor escalabilidade e real-time
+- MUI v7: componentes prontos e consistência visual
+
+## Bugs Conhecidos
+- Bug XYZ: ocorre quando array vazio é passado para Firestore update
+  Workaround: verificar if (array.length > 0) antes
+- Bug ABC: acontece se não usar loader ao navegar
+  Solução: adicionar Suspense ou loading state
+
+## Configurações
+- Firebase Auth: Google Sign-In habilitado
+- Stripe: Webhook endpoint configurado em /api/stripe/webhook
+- App Router: usa i18n com next-intl
+
+## Preferências do Matheus
+- Prefere componentes funcionais simples
+- Gosta de código conciso (1-3 linhas quando possível)
+- Valoriza explicações simples sem jargões
+- Prefere resposta direta sem enrolação
+```
+
+---
+
+## Dicas Importantes
+
+### 1. Verifique antes de salvar
+
+```
+1. { "command": "search", "agent": "nexus", "query": "termo" }
+   ↓
+2. Se já existe, não salve duplicata
+   ↓
+3. Se não existe, faça APPEND
+```
+
+### 2. Seja específico e contextual
+
+**Ruim:**
+```json
+{ "entry": "Use TypeScript" }
+```
+
+**Bom:**
+```json
+{ "entry": "Neste projeto, sempre use TypeScript strict mode (noImplicitAny: true) em todos os arquivos .ts e .tsx" }
+```
+
+### 3. Explique o PORQUÊ
+
+**Ruim:**
+```json
+{ "entry": "Use Zustand" }
+```
+
+**Bom:**
+```json
+{ "entry": "Decisão: Usamos Zustand em vez de Redux porque é mais leve (1KB vs 10KB), tem melhor suporte TypeScript, e o projeto tem apenas 5 stores independentes" }
+```
+
+### 4. Use APPEND para cronologia
+
+`APPEND` mantém o histórico cronológico, o que ajuda a entender:
+- Quando aprendizados foram feitos
+- A evolução das decisões
+- Progresso do projeto
+
+### 5. Use WRITE para limpeza
+
+Quando a memória estiver grande (~150+ linhas):
+1. Leia tudo com `READ`
+2. Reorganize em seções bem definidas
+3. Remova entradas obsoletas
+4. Use `WRITE` com o conteúdo reorganizado
+
+---
+
+## Exemplos Práticos de Uso
+
+### Exemplo 1: Iniciar sessão e carregar memória
+
+```
+IA: { "command": "read", "agent": "nexus" }
+
+Resultado: 📝 Memória de "nexus" (45 linhas):
+─────────────────────────────────────────────────────────────────
+
+# Memória do Nexus
+
+## Padrões
+- Sempre use TypeScript estrito
+- Nomeie componentes com PascalCase
+
+## Decisões
+- Usamos Zustand para estado global
+...
+```
+
+### Exemplo 2: Aprender novo padrão
+
+```
+Usuário: "Adicione um novo componente de botão"
+IA: [Implementa o botão]
+
+IA: { "command": "append", "agent": "nexus",
+     "entry": "Padrão descoberto: Este projeto usa MUI Button com variantes customizadas. Para consistência, use: <Button variant='contained' color='primary' size='small'> para botões de ação" }
+```
+
+### Exemplo 3: Salvar decisão arquitetural
+
+```
+Usuário: "Vamos usar PostgreSQL ou Firestore?"
+IA: [Analisa e recomenda Firestore]
+
+IA: { "command": "append", "agent": "nexus",
+     "entry": "Decisão: Escolhemos Firestore em vez de PostgreSQL. Motivos: (1) Real-time nativo, (2) Escalabilidade automática, (3) Integração com Firebase Auth, (4) Menor overhead de ops" }
+```
+
+### Exemplo 4: Documentar bug
+
+```
+Usuário: "O formulário não está salvando"
+IA: [Investiga e descobre o bug]
+
+IA: { "command": "append", "agent": "nexus",
+     "entry": "Bug: Formulário não salva quando usuário não seleciona foto. Causa: validação em FormData falha quando file input está vazio. Workaround: sempre inicializar FormData com file mesmo que vazio" }
+```
+
+### Exemplo 5: Reorganizar memória grande
+
+```
+IA: { "command": "read", "agent": "nexus" }
+Resultado: Memória com 195 linhas
+
+IA: { "command": "write", "agent": "nexus",
+     "content": "# Memória do Nexus\n\n## Padrões (reorganizado e limpo)\n\n..." }
+```
+
+---
+
+## Verificação Final
+
+Antes de fazer `WRITE`, SEMPRE:
+1. ✅ Leia tudo com `READ` primeiro
+2. ✅ Entenda o que está lá
+3. ✅ Reorganize em seções lógicas
+4. ✅ Remova duplicatas e obsoleto
+5. ✅ Preserve o conhecimento importante
+
+Antes de fazer `APPEND`, SEMPRE:
+1. ✅ Use `SEARCH` para verificar se já existe
+2. ✅ Seja específico e contextual
+3. ✅ Explique o PORQUÊ quando relevante
+4. ✅ Use formato markdown apropriado
+
+---
+
+## Erros Comuns e Como Evitar
+
+### Erro 1: Salvar coisas óbvias
+
+**Ruim:**
+```json
+{ "entry": "Use TypeScript para tipos" }
+```
+
+**Bom:**
+```json
+{ "entry": "Neste projeto, use TypeScript strict mode e defina tipos explicitamente. Evite any: sempre use interfaces ou tipos específicos" }
+```
+
+### Erro 2: Duplicar informações
+
+**Antes de salvar:**
+```json
+{ "command": "search", "agent": "nexus", "query": "Zustand" }
+```
+
+### Erro 3: Não explicar contexto
+
+**Ruim:**
+```json
+{ "entry": "Use 2 espaços" }
+```
+
+**Bom:**
+```json
+{ "entry": "Neste projeto, use 2 espaços de indentação em arquivos TSX (não 4, não tabs). Isso é consistente com o linter configurado" }
+```
+
+### Erro 4: WRITE sem ler antes
+
+**Errado:**
+```
+IA: { "command": "write", "agent": "nexus", "content": "..." }
+```
+
+**Certo:**
+```
+IA: { "command": "read", "agent": "nexus" }
+[Analisa o conteúdo]
+IA: { "command": "write", "agent": "nexus", "content": "..." }
+```
+
+---
+
+## Resumo
+
+| Comando | Quando usar | Cuidado |
+|---------|------------|---------|
+| `read` | Iniciar sessão | Nenhum |
+| `append` | Aprender algo novo | Use SEARCH antes |
+| `write` | Reorganizar memória | Leia ANTES |
+| `search` | Encontrar info rápida | Nenhum |
+| `list` | Descobrir agents | Nenhum |
+
+---
+
+**Lembre-se:** O objetivo da memória é preservar conhecimento importante entre sessões, não registrar toda a conversa. Seja seletivo, específico e organizado!

package/README.md

@@ -249,6 +249,33 @@ npm start
 
 Para alterar a versão do servidor MCP, basta modificar o campo `version` no arquivo `package.json`. O `index.ts` lê automaticamente a versão do package.json em tempo de execução.
 
+## Documentação Adicional
+
+### CLAUDE.md
+
+Documentação completa para IAs sobre como usar corretamente o sistema de memória. Inclui:
+
+- Workflow recomendado por sessão
+- Guia de quando usar cada comando
+- O que salvar vs não salvar
+- Formato recomendado
+- Dicas práticas e exemplos
+- Erros comuns e como evitar
+
+**Para IAs:** Leia CLAUDE.md para entender como usar este sistema eficientemente.
+
+### AGENTS.md
+
+Guia específico para cada tipo de subagent sobre como usar a memória de forma alinhada com sua especialização. Inclui:
+
+- O que cada tipo de agent deve salvar
+- Formato de memória recomendado por agent
+- Exemplos práticos por tipo
+- Compartilhamento de informações entre agents
+- Boas práticas específicas
+
+**Para Subagents:** Consulte a seção relevante em AGENTS.md para orientações específicas do seu tipo.
+
 ## Licença
 
 MIT © Koda AI Studio

package/dist/index.d.ts

@@ -1,3 +1,4 @@
+#!/usr/bin/env node
 /**
  * Memory MCP Server - Sistema de memória persistente para subagents
  *

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAEA;;;;;;;GAOG"}

package/dist/index.js

@@ -1,3 +1,4 @@
+#!/usr/bin/env node
 /**
  * Memory MCP Server - Sistema de memória persistente para subagents
  *
@@ -571,6 +572,46 @@ Exemplos de busca úteis: "padrão", "bug", "TypeScript", "Firebase", "erro"
 // INICIALIZAÇÃO
 // ═══════════════════════════════════════════════════════════════════════════
 async function main() {
+    // Verifica argumentos de linha de comando
+    const args = process.argv.slice(2);
+    // --version
+    if (args.includes("--version") || args.includes("-v")) {
+        console.log(`@justmpm/memory v${PACKAGE_VERSION}`);
+        process.exit(0);
+    }
+    // --help
+    if (args.includes("--help") || args.includes("-h")) {
+        console.log(`
+@justmpm/memory - MCP Server para gerenciar memória persistente de subagents
+
+Versão: ${PACKAGE_VERSION}
+
+USO:
+  memory                    Inicia o servidor MCP (comunicação via stdio)
+  memory --version          Mostra a versão do pacote
+  memory --help             Mostra esta mensagem de ajuda
+
+COMANDOS MCP:
+  - read     Lê a memória de um agent
+  - write    Substitui toda a memória
+  - append   Adiciona uma entrada ao final
+  - search   Busca texto na memória
+  - list     Lista todos os agents com memória
+
+DOCUMENTAÇÃO:
+  Para mais detalhes, consulte:
+  - CLAUDE.md  (Documentação para IAs)
+  - AGENTS.md  (Guia para subagents)
+  - README.md  (Documentação principal)
+
+REPOSITÓRIO:
+  https://github.com/justmpm/memory-mcp
+
+LICENÇA:
+  MIT © Koda AI Studio
+`);
+        process.exit(0);
+    }
     const transport = new StdioServerTransport();
     await server.connect(transport);
     // Não faz log aqui pois o servidor se comunica via stdio