@justmpm/memory 0.1.2 → 0.2.2

package/CHANGELOG.md

@@ -0,0 +1,42 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.2.2] - 2026-02-10
+
+### Changed
+- **BREAKING**: Refatorado de 1 tool com múltiplos comandos para 4 tools separadas
+  - `memory_read` - Lê a memória do agent
+  - `memory_append` - Adiciona nova entrada com timestamp
+  - `memory_search` - Busca termo específico na memória
+  - `memory_write` - Reescreve toda a memória
+- Removido comando `list` (cada agent gerencia apenas sua própria memória)
+- Adicionado Zod para validação de schemas
+- Melhoradas descrições das tools para serem mais diretas e claras
+- Simplificadas mensagens de erro com validação automática
+
+### Fixed
+- Validação de parâmetros obrigatórios agora usa Zod schemas
+- Mensagens de erro mais informativas
+
+## [0.2.1] - 2026-02-09
+
+### Added
+- Documentação CLAUDE.md e AGENTS.md
+- Comando `list` para listar todos os agents com memória
+
+### Fixed
+- Pequenas correções na documentação
+
+## [0.2.0] - 2026-02-08
+
+### Added
+- Versão inicial do MCP Server
+- Tools: read, append, search, write, list
+- Suporte a múltiplos agents
+- Limite automático de 200 linhas por memória
+- Timestamp automático para entradas append
+- Backup opcional para operação write

package/CLAUDE.md

@@ -37,9 +37,9 @@
 
 ---
 
-## Tool Memory: Comandos Disponíveis
+## Tools Disponíveis
 
-### 1. READ - Carregar memória anterior
+### 1. memory_read - Carregar memória anterior
 
 **Quando usar:**
 - Ao INICIAR uma nova sessão
@@ -49,8 +49,7 @@
 **Sintaxe:**
 ```json
 {
-  "command": "read",
-  "agent": "nexus"  // ← Seu nome de agent
+  "agent": "nexus"  // ← Seu nome de agent (opcional, padrão: "unknown")
 }
 ```
 
@@ -61,14 +60,14 @@
 
 **Workflow recomendado:**
 ```
-1. Primeira coisa ao iniciar sessão: READ
+1. Primeira coisa ao iniciar sessão: use memory_read
 2. Analise o conteúdo retornado
 3. Use as informações salvas para informar suas decisões
 ```
 
 ---
 
-### 2. APPEND - Salvar aprendizado novo
+### 2. memory_append - Salvar aprendizado novo
 
 **Quando usar:**
 - Ao APRENDER algo importante sobre o projeto
@@ -80,7 +79,6 @@
 **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"
 }
@@ -103,28 +101,24 @@
 ```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"
 }
@@ -132,53 +126,7 @@
 
 ---
 
-### 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
+### 3. memory_search - Buscar informação específica
 
 **Quando usar:**
 - Para encontrar informações rápidas sem ler tudo
@@ -188,7 +136,6 @@
 **Sintaxe:**
 ```json
 {
-  "command": "search",
   "agent": "nexus",
   "query": "Zod"
 }
@@ -196,47 +143,74 @@
 
 **O que retorna:**
 - Até 20 ocorrências com número da linha
-- Case-insensitive (busca "zod" e "Zod" da mesma forma)
+- Case-insensitive (busca "zod" e "Zod")
 - Se não encontrado: mensagem clara
 
 **Exemplos de buscas úteis:**
 
 ```json
 // Buscar padrão específico
-{ "command": "search", "agent": "nexus", "query": "padrão" }
+{ "agent": "nexus", "query": "padrão" }
 
 // Buscar bug específico
-{ "command": "search", "agent": "nexus", "query": "bug" }
+{ "agent": "nexus", "query": "bug" }
 
 // Buscar tecnologia
-{ "command": "search", "agent": "nexus", "query": "TypeScript" }
+{ "agent": "nexus", "query": "TypeScript" }
 
 // Buscar preferência
-{ "command": "search", "agent": "nexus", "query": "Matheus" }
+{ "agent": "nexus", "query": "Matheus" }
 
 // Buscar erro específico
-{ "command": "search", "agent": "nexus", "query": "Firebase" }
+{ "agent": "nexus", "query": "Firebase" }
 ```
 
 ---
 
-### 5. LIST - Descobrir agents existentes
+### 4. memory_write - Reorganizar memória
 
 **Quando usar:**
-- Para descobrir quais agents já usaram memória no projeto
-- Ao iniciar trabalho em projeto desconhecido
+- 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": "list"
+  "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...",
+  "backup": true
 }
 ```
 
-**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"
+**O que acontece:**
+- SUBSTITUI TODO o conteúdo existente
+- Aplica limite de 200 linhas
+- Se `backup: true`, cria MEMORY.md.backup antes
+- Cria estrutura nova do zero
+
+**CUIDADO:** `memory_write` APAGA tudo o que estava antes! Use com cautela.
+
+**Quando usar write vs append:**
+
+| Situação | Use |
+|----------|-----|
+| Aprender algo novo | `memory_append` |
+| Salvar decisão incremental | `memory_append` |
+| Memória grande demais | `memory_write` |
+| Remover entradas obsoletas | `memory_write` |
+| Reorganizar seções | `memory_write` |
+
+**Exemplo de reorganização:**
+
+```json
+{
+  "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\n## Preferências do Matheus\n- Prefere componentes funcionais\n- Gosta de código conciso (1-3 linhas quando possível)",
+  "backup": true
+}
+```
 
 ---
 
@@ -245,22 +219,22 @@
 ### Ao Iniciar uma Sessão
 
 ```
-1. { "command": "read", "agent": "nexus" }
+1. Use memory_read
    ↓
 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
+4. Se a memória estiver muito grande, considere reorganizar com memory_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 aprender algo importante → memory_append
+Ao tomar uma decisão → memory_append
+Ao descobrir um bug → memory_append
+Ao identificar um padrão → memory_append
 ```
 
 ### Ao Final da Sessão
@@ -268,7 +242,7 @@ Ao identificar um padrão → APPEND
 ```
 1. Revise as entradas adicionadas
    ↓
-2. Se memória estiver grande (~150+ linhas), considere WRITE para limpar
+2. Se memória estiver grande (~150+ linhas), considere memory_write para limpar
    ↓
 3. Organize as entradas em seções (Padrões, Decisões, Bugs, etc.)
 ```
@@ -326,7 +300,7 @@ Ao identificar um padrão → APPEND
 
 **Informações duplicadas:**
 - Se um padrão já está salvo, não salve novamente
-- Use SEARCH antes de salvar para verificar
+- Use memory_search antes de salvar para verificar
 
 **Logs de conversação:**
 - Não salve cada mensagem da conversa
@@ -383,11 +357,11 @@ Use seções markdown bem organizadas:
 ### 1. Verifique antes de salvar
 
 ```
-1. { "command": "search", "agent": "nexus", "query": "termo" }
+1. Use memory_search com o termo
    ↓
 2. Se já existe, não salve duplicata
    ↓
-3. Se não existe, faça APPEND
+3. Se não existe, faça memory_append
 ```
 
 ### 2. Seja específico e contextual
@@ -414,100 +388,20 @@ Use seções markdown bem organizadas:
 { "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
+### 4. Use memory_append para cronologia
 
-`APPEND` mantém o histórico cronológico, o que ajuda a entender:
+`memory_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
+### 5. Use memory_write para limpeza
 
 Quando a memória estiver grande (~150+ linhas):
-1. Leia tudo com `READ`
+1. Use memory_read primeiro
 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
+4. Use memory_write com o conteúdo reorganizado
 
 ---
 
@@ -529,7 +423,8 @@ Antes de fazer `APPEND`, SEMPRE:
 
 **Antes de salvar:**
 ```json
-{ "command": "search", "agent": "nexus", "query": "Zustand" }
+// Use memory_search primeiro
+{ "query": "Zustand" }
 ```
 
 ### Erro 3: Não explicar contexto
@@ -544,31 +439,30 @@ Antes de fazer `APPEND`, SEMPRE:
 { "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
+### Erro 4: memory_write sem ler antes
 
 **Errado:**
 ```
-IA: { "command": "write", "agent": "nexus", "content": "..." }
+IA: { "tool": "memory_write", "content": "..." }
 ```
 
 **Certo:**
 ```
-IA: { "command": "read", "agent": "nexus" }
+IA: { "tool": "memory_read" }
 [Analisa o conteúdo]
-IA: { "command": "write", "agent": "nexus", "content": "..." }
+IA: { "tool": "memory_write", "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 |
+| Tool | Quando usar | Cuidado |
+|------|------------|---------|
+| `memory_read` | Iniciar sessão | Nenhum |
+| `memory_append` | Aprender algo novo | Use memory_search antes |
+| `memory_write` | Reorganizar memória | Leia ANTES |
+| `memory_search` | Encontrar info rápida | Nenhum |
 
 ---