@justmpm/memory 0.2.1 → 0.3.0

package/dist/index.js

@@ -10,9 +10,41 @@
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
-import { readFileSync, writeFileSync, existsSync, mkdirSync, readdirSync, } from "fs";
+import { readFileSync, writeFileSync, existsSync, mkdirSync, } from "fs";
 import { join, dirname } from "path";
 import { fileURLToPath } from "url";
+import { z } from "zod";
+// ═══════════════════════════════════════════════════════════════════════════
+// SCHEMAS DE VALIDAÇÃO (Zod)
+// ═══════════════════════════════════════════════════════════════════════════
+/**
+ * Schema para tool memory_read
+ */
+const MemoryReadSchema = z.object({
+    agent: z.string().min(1).describe('Seu nome de agent (ex: "sentinel", "fix-worker", "nexus"). OBRIGATÓRIO.'),
+});
+/**
+ * Schema para tool memory_append
+ */
+const MemoryAppendSchema = z.object({
+    agent: z.string().min(1).describe('Seu nome de agent (ex: "sentinel", "fix-worker", "nexus"). OBRIGATÓRIO.'),
+    entry: z.string().min(1).describe('Texto da informação a salvar. Ex: "Padrão: sempre use try/catch em funções async" ou "Bug: erro quando usuário clica 2x". Será adicionado com timestamp automaticamente.'),
+});
+/**
+ * Schema para tool memory_search
+ */
+const MemorySearchSchema = z.object({
+    agent: z.string().min(1).describe('Seu nome de agent (ex: "sentinel", "fix-worker", "nexus"). OBRIGATÓRIO.'),
+    query: z.string().min(1).describe('Palavra-chave para buscar na sua memória. Ex: "Zod", "bug", "Firebase". Retorna até 20 resultados com número da linha.'),
+});
+/**
+ * Schema para tool memory_write
+ */
+const MemoryWriteSchema = z.object({
+    agent: z.string().min(1).describe('Seu nome de agent (ex: "sentinel", "fix-worker", "nexus"). OBRIGATÓRIO.'),
+    content: z.string().min(1).describe('Conteúdo completo em markdown para substituir a memória existente. Use para reorganizar, limpar ou reconstruir memória do zero.'),
+    backup: z.boolean().optional().default(false).describe('Se true, cria um backup do conteúdo atual antes de sobrescrever. O backup é salvo como MEMORY.md.backup no mesmo diretório.'),
+});
 // ═══════════════════════════════════════════════════════════════════════════
 // VERSÃO DO PROJETO
 // ═══════════════════════════════════════════════════════════════════════════
@@ -89,23 +121,6 @@ function limitMemoryLines(content, maxLines = 200) {
 
 ${lines.slice(-keepCount).join("\n")}`;
 }
-/**
- * Lista todos os agents que têm memória
- */
-function listAgentsWithMemory() {
-    const memoryRoot = join(process.cwd(), ".claude", "agent-memory");
-    if (!existsSync(memoryRoot))
-        return [];
-    try {
-        return readdirSync(memoryRoot).filter((name) => {
-            const memoryPath = join(memoryRoot, name, "MEMORY.md");
-            return existsSync(memoryPath);
-        });
-    }
-    catch {
-        return [];
-    }
-}
 // ═══════════════════════════════════════════════════════════════════════════
 // HANDLERS DAS OPERAÇÕES
 // ═══════════════════════════════════════════════════════════════════════════
@@ -217,33 +232,6 @@ ${results}${more}`;
         return `❌ Erro ao buscar: ${error.message}`;
     }
 }
-/**
- * Handler: list - Lista todos os agents com memória
- */
-async function handleList() {
-    const agents = listAgentsWithMemory();
-    if (agents.length === 0) {
-        return `📝 Nenhum agent com memória neste projeto.
-
-Diretório: .claude/agent-memory/`;
-    }
-    const agentList = agents
-        .map((name) => {
-        const path = join(".claude", "agent-memory", name, "MEMORY.md");
-        let lines = 0;
-        try {
-            lines = readFileSync(join(process.cwd(), path), "utf-8").split("\n").length;
-        }
-        catch { }
-        return `  • ${name} (${lines} linhas)`;
-    })
-        .join("\n");
-    return `📝 Agents com memória neste projeto (${agents.length}):
-
-${agentList}
-
-Use o comando "read" de cada agent para ver o conteúdo.`;
-}
 // ═══════════════════════════════════════════════════════════════════════════
 // SERVIDOR MCP
 // ═══════════════════════════════════════════════════════════════════════════
@@ -262,136 +250,94 @@ const server = new Server({
 server.setRequestHandler(ListToolsRequestSchema, async () => {
     return {
         tools: [
+            // ────────────────────────────────────────────────────────────────────────
+            // TOOL: memory_read
+            // ────────────────────────────────────────────────────────────────────────
             {
-                name: "memory",
-                description: `
-Sua memória pessoal - salve e recupere seus aprendizados entre sessões.
-
-**PARA QUE:** Guarde padrões de código, bugs encontrados, decisões tomadas e preferências do usuário. Tudo persiste entre sessões.
-
-**ONDE:** Seu arquivo fica em .claude/agent-memory/<seu-nome>/MEMORY.md
-
-**IMPORTANTE:** Máximo 200 linhas. Quando passar, as mais antigas são removidas (mantém últimas 160).
-
-═══════════════════════════════════════════════════════════════
-COMANDOS DISPONÍVEIS:
-═══════════════════════════════════════════════════════════════
-
-1. **read** - Carrega sua memória
-   Uso: Ao iniciar uma sessão para recuperar seu contexto anterior
-   - agent: (opcional) Seu nome de agent. Se não fornecido, usa "unknown"
-   - Retorna: Conteúdo completo do seu MEMORY.md com contagem de linhas
-   - Se não existir: Mensagem de memória vazia com sugestão de usar 'append'
-
-2. **append** - Adiciona nova informação à sua memória
-   Uso: Quando aprender algo novo importante (padrão, bug, decisão)
-   - entry: (OBRIGATÓRIO) Texto da informação a salvar
-   - Formato automático: Adiciona timestamp "## [YYYY-MM-DD HH:MM:SS]"
-   - Retorna: Confirmação com timestamp e preview da entrada
-
-3. **search** - Procura informação específica na sua memória
-   Uso: Quando precisar encontrar algo sem ler tudo
-   - query: (OBRIGATÓRIO) Termo ou palavra-chave a buscar
-   - Busca: Case-insensitive, máximo 20 resultados
-   - Retorna: Ocorrências encontradas com número da linha
-
-4. **write** - Reescreve sua memória reorganizando tudo
-   Uso: Quando a memória ficar grande (perto de 200 linhas) ou precisar reestruturar
-   - content: (OBRIGATÓRIO) Novo conteúdo completo em markdown
-   - backup: (opcional) Se true, cria backup antes de sobrescrever
-   - Retorna: Confirmação com contagem de linhas e alerta se atingir limite
-
-═══════════════════════════════════════════════════════════════
-WORKFLOW RECOMENDADO:
-═══════════════════════════════════════════════════════════════
-
-1. **INICIAR SESSÃO:** { "command": "read" }
-   → Carrega sua memória anterior para ter contexto
-
-2. **DURANTE O TRABALHO:** { "command": "append", "entry": "Padrão: ..." }
-   → Sempre que aprender algo importante, salve imediatamente
-
-3. **PRECISAR DE ALGO:** { "command": "search", "query": "Zod" }
-   → Procure na sua memória sem precisar ler tudo
-
-4. **MEMÓRIA GRANDE:** { "command": "write", "content": "...", "backup": true }
-   → Reestruture e use backup para segurança
-
-═══════════════════════════════════════════════════════════════
-EXEMPLOS PRÁTICOS:
-═══════════════════════════════════════════════════════════════
-
-Iniciar sessão (sempre comece assim):
-  { "command": "read" }
-
-Salvar um padrão de código:
-  { "command": "append", "entry": "Padrão: Sempre use Zod para validar inputs do usuário" }
-
-Salvar uma decisão importante:
-  { "command": "append", "entry": "Decisão: Usar Zustand em vez de Redux (mais leve)" }
-
-Salvar um bug recorrente:
-  { "command": "append", "entry": "Bug: Erro acontece quando array está vazio no submit" }
-
-Buscar informação sobre Zod:
-  { "command": "search", "query": "Zod" }
-
-Reorganizar memória grande com backup:
-  { "command": "write", "content": "# Memória Reorganizada\\n\\n## Padrões\\n- Padrão 1\\n- Padrão 2", "backup": true }
-
-═══════════════════════════════════════════════════════════════
-O QUE SALVAR (exemplos):
-═══════════════════════════════════════════════════════════════
-
-✅ **Salve:** Padrões de código, bugs recorrentes, decisões arquiteturais, preferências do usuário, configurações importantes.
-
-✅ **Organize com markdown:**
-   ## Padrões  - Convenções de código
-   ## Bugs     - Problemas e workarounds  
-   ## Decisões - Escolhas arquiteturais
-
-❌ **Não salve:** Coisas triviais, informações temporárias, logs de conversa, coisas óbvias.
-
-═══════════════════════════════════════════════════════════════
-DICAS IMPORTANTES:
-═══════════════════════════════════════════════════════════════
-
-• Seu nome é normalizado: "Meu Agent" → "meu-agent"
-• Use search antes de salvar para evitar duplicatas
-• Memória é por projeto (pasta .claude/agent-memory/)
-• Ao atingir 200 linhas, as mais antigas são removidas automaticamente
-        `.trim(),
-                inputSchema: {
-                    type: "object",
-                    properties: {
-                        command: {
-                            type: "string",
-                            enum: ["read", "append", "search", "write"],
-                            description: "Comando a executar: 'read' carrega sua memória, 'append' adiciona nova informação, 'search' procura algo específico, 'write' reescreve reorganizando tudo.",
-                        },
-                        agent: {
-                            type: "string",
-                            description: 'Seu nome de agent (ex: "sentinel", "fix-worker"). Opcional - usa "unknown" se não informado. Será normalizado para minúsculas.',
-                        },
-                        content: {
-                            type: "string",
-                            description: 'Conteúdo completo em markdown para substituir a memória existente (OBRIGATÓRIO para "write"). Use para reorganizar, limpar ou reconstruir memória do zero.',
-                        },
-                        backup: {
-                            type: "boolean",
-                            description: 'Se true, cria um backup do conteúdo atual antes de sobrescrever. O backup é salvo como MEMORY.md.backup no mesmo diretório. Padrão: false.',
-                        },
-                        entry: {
-                            type: "string",
-                            description: 'Texto da informação a salvar (OBRIGATÓRIO para append). Ex: "Padrão: sempre use try/catch em funções async" ou "Bug: erro quando usuário clica 2x". Será adicionado com timestamp automaticamente.',
-                        },
-                        query: {
-                            type: "string",
-                            description: 'Palavra-chave para buscar na sua memória (OBRIGATÓRIO para search). Ex: "Zod", "bug", "Firebase". Retorna até 20 resultados com número da linha.',
-                        },
-                    },
-                    required: ["command"],
-                },
+                name: "memory_read",
+                description: `Lê todo o conteúdo da sua memória persistente. Use sempre ao iniciar uma sessão para recuperar contexto anterior.
+
+RETORNA: Conteúdo completo do MEMORY.md localizado em .claude/agent-memory/<agent-name>/MEMORY.md.
+
+Se a memória não existir, retorna mensagem de memória vazia com sugestão para usar memory_append.
+
+Limite: Máximo 200 linhas. Ao atingir, mantém apenas as últimas 160 entradas.
+
+Parâmetro "agent": Seu nome de agent (OBRIGATÓRIO).`,
+                inputSchema: MemoryReadSchema,
+            },
+            // ────────────────────────────────────────────────────────────────────────
+            // TOOL: memory_append
+            // ────────────────────────────────────────────────────────────────────────
+            {
+                name: "memory_append",
+                description: `Adiciona uma entrada no final da sua memória com timestamp automático "## [YYYY-MM-DD HH:MM:SS]".
+
+USE QUANDO APRENDER algo importante: padrões de código, bugs recorrentes, decisões arquiteturais, preferências do usuário, configurações importantes.
+
+EXEMPLOS DE ENTRADAS VÁLIDAS:
+- "Padrão: Este projeto usa App Router com estrutura /features/[domain]/"
+- "Decisão: Escolhemos Zustand em vez de Redux porque é mais leve"
+- "Bug: Firestore update falha silenciosamente quando array está vazio"
+
+NÃO salve: Coisas triviais, informações temporárias, logs de conversa.
+
+Parâmetro "agent": Seu nome de agent (OBRIGATÓRIO).
+Parâmetro "entry": OBRIGATÓRIO - Texto da informação a salvar.`,
+                inputSchema: MemoryAppendSchema,
+            },
+            // ────────────────────────────────────────────────────────────────────────
+            // TOOL: memory_search
+            // ────────────────────────────────────────────────────────────────────────
+            {
+                name: "memory_search",
+                description: `Busca um termo na sua memória sem precisar ler todo o conteúdo.
+
+RETORNA: Até 20 ocorrências encontradas com número da linha. Busca case-insensitive.
+
+EXEMPLOS DE BUSCA ÚTEIS:
+- "Zod" → encontrar tudo sobre validação
+- "bug" → encontrar bugs documentados
+- "Firebase" → encontrar configurações
+- "TypeScript" → encontrar padrões de tipagem
+
+Se não encontrar, retorna mensagem de que nenhuma ocorrência foi encontrada.
+
+Parâmetro "agent": Seu nome de agent (OBRIGATÓRIO).
+Parâmetro "query": OBRIGATÓRIO - Termo ou palavra-chave a buscar.`,
+                inputSchema: MemorySearchSchema,
+            },
+            // ────────────────────────────────────────────────────────────────────────
+            // TOOL: memory_write
+            // ────────────────────────────────────────────────────────────────────────
+            {
+                name: "memory_write",
+                description: `SUBSTITUI TODO o conteúdo da sua memória. APAGA tudo que estava antes - use com cautela.
+
+USE QUANDO: Memória está grande (~150+ linhas) e precisa reorganizar, ou quer remover entradas obsoletas.
+
+DICAS:
+- Use "backup: true" para criar MEMORY.md.backup antes de sobrescrever
+- Leia primeiro com memory_read para não perder conteúdo importante
+- Organize em seções: ## Padrões, ## Bugs, ## Decisões, ## Configurações
+
+EXEMPLO DE ESTRUTURA:
+# Memória do Agent
+
+## Padrões de Código
+- Sempre use TypeScript estrito
+
+## Bugs Conhecidos
+- Bug XYZ: ocorre quando array vazio
+  Workaround: verificar length antes de usar
+
+## Decisões
+- Zustand em vez de Redux (mais leve)
+
+Parâmetro "agent": Seu nome de agent (OBRIGATÓRIO).
+Parâmetro "content": OBRIGATÓRIO - Novo conteúdo completo em markdown.
+Parâmetro "backup": Opcional (padrão: false) - Se true, cria backup antes de sobrescrever.`,
+                inputSchema: MemoryWriteSchema,
             },
         ],
     };
@@ -401,123 +347,67 @@ DICAS IMPORTANTES:
  */
 server.setRequestHandler(CallToolRequestSchema, async (request) => {
     const { name, arguments: args } = request.params;
-    if (name !== "memory") {
-        throw new Error(`Tool desconhecida: ${name}`);
-    }
-    const command = args?.command;
-    const agentName = args?.agent || "unknown";
-    // Valida comando
-    const validCommands = ["read", "append", "search", "write"];
-    if (!validCommands.includes(command)) {
+    const agentName = args?.agent;
+    // Valida parâmetro agent obrigatório
+    if (!agentName || typeof agentName !== "string" || agentName.trim().length === 0) {
         return {
             content: [
                 {
                     type: "text",
-                    text: `❌ ERRO: Comando desconhecido "${command}"
-
-COMANDOS DISPONÍVEIS:
-
-  1. read    - Carrega sua memória (use ao iniciar)
-  2. append  - Adiciona nova informação (mais usado)
-  3. search  - Procura algo na sua memória
-  4. write   - Reescreve reorganizando tudo (cuidado!)
-
-PARA MAIS DETALHES, CONSULTE A DESCRIÇÃO DA TOOL "memory"
-`,
+                    text: `❌ Erro: Parâmetro "agent" é obrigatório em todas as operações de memória. Informe o nome do agent (ex: "sentinel", "nexus", "fix-worker").`,
                 },
             ],
         };
     }
-    // Executa comando específico
-    let result;
-    switch (command) {
-        case "read": {
-            result = await handleRead(agentName);
-            break;
-        }
-        case "write": {
-            const content = args?.content;
-            if (!content) {
-                result = `❌ ERRO: O parâmetro "content" é OBRIGATÓRIO para o comando "write".
-
-EXEMPLO DE USO CORRETO:
-  {
-    "command": "write",
-    "agent": "sentinel",
-    "content": "# Memória do Sentinel\\n\\n## Padrões\\n- Sempre use Zod para validação\\n\\n## Bugs\\n- Bug XYZ ocorre quando..."
-  }
-
-DICA: Use "backup": true para criar uma cópia de segurança antes de sobrescrever:
-  {
-    "command": "write",
-    "agent": "sentinel",
-    "content": "# Nova memória...",
-    "backup": true
-  }
-
-Use "write" para reorganizar memória grande ou reconstruir do zero.
-Para adicionar uma entrada preservando o histórico, use "append".
-`;
-                break;
+    try {
+        switch (name) {
+            case "memory_read": {
+                const parsed = MemoryReadSchema.safeParse(args);
+                if (!parsed.success) {
+                    throw new Error(`Parâmetros inválidos: ${parsed.error.issues.map((e) => e.message).join(", ")}`);
+                }
+                const result = await handleRead(agentName);
+                return { content: [{ type: "text", text: result }] };
             }
-            const backup = args?.backup || false;
-            result = await handleWrite(agentName, content, backup);
-            break;
-        }
-        case "append": {
-            const entry = args?.entry;
-            if (!entry) {
-                result = `❌ ERRO: O parâmetro "entry" é OBRIGATÓRIO para o comando "append".
-
-EXEMPLO DE USO CORRETO:
-  {
-    "command": "append",
-    "agent": "sentinel",
-    "entry": "Padrão descoberto: Sempre use Zod para validar inputs do usuário em todos os componentes de formulário"
-  }
-
-DICA: Use "append" para salvar aprendizados incrementais. O timestamp é adicionado automaticamente no formato:
-  ## [2026-02-09 12:34:56]
-  Sua entrada aqui
-
-Para salvar informações mais longas ou estruturadas, considere usar "write".
-`;
-                break;
+            case "memory_append": {
+                const parsed = MemoryAppendSchema.safeParse(args);
+                if (!parsed.success) {
+                    throw new Error(`Parâmetros inválidos: ${parsed.error.issues.map((e) => e.message).join(", ")}`);
+                }
+                const result = await handleAppend(agentName, parsed.data.entry);
+                return { content: [{ type: "text", text: result }] };
             }
-            result = await handleAppend(agentName, entry);
-            break;
-        }
-        case "search": {
-            const query = args?.query;
-            if (!query) {
-                result = `❌ ERRO: O parâmetro "query" é OBRIGATÓRIO para o comando "search".
-
-EXEMPLO DE USO CORRETO:
-  {
-    "command": "search",
-    "agent": "sentinel",
-    "query": "Zod"
-  }
-
-DICA: A busca é case-insensitive e retorna até 20 ocorrências com o número da linha.
-Exemplos de busca úteis: "padrão", "bug", "TypeScript", "Firebase", "erro"
-`;
-                break;
+            case "memory_search": {
+                const parsed = MemorySearchSchema.safeParse(args);
+                if (!parsed.success) {
+                    throw new Error(`Parâmetros inválidos: ${parsed.error.issues.map((e) => e.message).join(", ")}`);
+                }
+                const result = await handleSearch(agentName, parsed.data.query);
+                return { content: [{ type: "text", text: result }] };
+            }
+            case "memory_write": {
+                const parsed = MemoryWriteSchema.safeParse(args);
+                if (!parsed.success) {
+                    throw new Error(`Parâmetros inválidos: ${parsed.error.issues.map((e) => e.message).join(", ")}`);
+                }
+                const result = await handleWrite(agentName, parsed.data.content, parsed.data.backup);
+                return { content: [{ type: "text", text: result }] };
             }
-            result = await handleSearch(agentName, query);
-            break;
+            default:
+                throw new Error(`Tool desconhecida: ${name}`);
         }
-        default:
-            result = `❌ Comando desconhecido: ${command}`;
     }
-    return {
-        content: [
-            {
-                type: "text",
-                text: result,
-            },
-        ],
-    };
+    catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `❌ Erro ao executar tool "${name}": ${errorMessage}`,
+                },
+            ],
+        };
+    }
 });
 // ═══════════════════════════════════════════════════════════════════════════
 // INICIALIZAÇÃO
@@ -542,12 +432,11 @@ USO:
   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
+TOOLS MCP:
+  - memory_read    Lê a memória de um agent
+  - memory_write   Substitui toda a memória
+  - memory_append  Adiciona uma entrada ao final
+  - memory_search  Busca texto na memória
 
 DOCUMENTAÇÃO:
   Para mais detalhes, consulte:

package/package.json

@@ -1,7 +1,7 @@
-{
-  "name": "@justmpm/memory",
-  "version": "0.2.1",
-  "description": "MCP Server para gerenciar memória persistente de subagents",
+{
+  "name": "@justmpm/memory",
+  "version": "0.3.0",
+  "description": "MCP Server para gerenciar memória persistente de subagents",
   "type": "module",
   "main": "dist/index.js",
   "bin": {
@@ -30,7 +30,8 @@
     "access": "public"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.0.4"
+    "@modelcontextprotocol/sdk": "^1.0.4",
+    "zod": "^4.3.5"
   },
   "devDependencies": {
     "@types/node": "^22.10.2",