@justmpm/memory 0.1.1 → 0.2.1

package/src/index.ts

@@ -1,690 +1,645 @@
-/**
- * Memory MCP Server - Sistema de memória persistente para subagents
- *
- * Permite que subagents salvem e recuperem aprendizados entre sessões.
- * Cada agent tem sua própria memória, armazenada em .claude/agent-memory/<agent-name>/MEMORY.md
- *
- * @see https://modelcontextprotocol.io/
- */
-
-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 { join, dirname } from "path";
-import { fileURLToPath } from "url";
-
-// ═══════════════════════════════════════════════════════════════════════════
-// VERSÃO DO PROJETO
-// ═══════════════════════════════════════════════════════════════════════════
-
-/**
- * Lê a versão do package.json dinamicamente
- */
-function getPackageVersion(): string {
-  try {
-    const __filename = fileURLToPath(import.meta.url);
-    const __dirname = dirname(__filename);
-    const packagePath = join(__dirname, "..", "package.json");
-    const packageJson = JSON.parse(readFileSync(packagePath, "utf-8"));
-    return packageJson.version || "0.1.0";
-  } catch {
-    return "0.1.0";
-  }
-}
-
-const PACKAGE_VERSION = getPackageVersion();
-
-// ═══════════════════════════════════════════════════════════════════════════
-// FUNÇÕES UTILITÁRIAS
-// ═══════════════════════════════════════════════════════════════════════════
-
-/**
- * Normaliza nome do agent para usar como nome de pasta
- * Ex: "Sentinel" → "sentinel", "QA-Tester" → "qa-tester"
- */
-function normalizeAgentName(agentName: string): string {
-  return agentName
-    .toLowerCase()
-    .replace(/[^a-z0-9]+/g, "-")
-    .replace(/^-|-$/g, "");
-}
-
-/**
- * Retorna o caminho do diretório de memória para um agent
- */
-function getAgentMemoryDir(agentName: string): string {
-  const normalizedName = normalizeAgentName(agentName);
-  return join(process.cwd(), ".claude", "agent-memory", normalizedName);
-}
-
-/**
- * Retorna o caminho do arquivo MEMORY.md de um agent
- */
-function getAgentMemoryPath(agentName: string): string {
-  return join(getAgentMemoryDir(agentName), "MEMORY.md");
-}
-
-/**
- * Garante que o diretório existe
- */
-function ensureAgentMemoryDir(agentName: string): void {
-  const dir = getAgentMemoryDir(agentName);
-  if (!existsSync(dir)) {
-    mkdirSync(dir, { recursive: true });
-  }
-}
-
-/**
- * Formata timestamp para uso em entradas de memória
- */
-function formatTimestamp(): string {
-  const now = new Date();
-  return now.toISOString().replace("T", " ").slice(0, 19);
-}
-
-/**
- * Limita memória a ~200 linhas (últimas entradas)
- */
-function limitMemoryLines(content: string, maxLines = 200): string {
-  const lines = content.split("\n");
-  if (lines.length <= maxLines) return content;
-  const keepCount = Math.floor(maxLines * 0.8); // 160 linhas
-  const removed = lines.length - keepCount;
-  return `# Memória (últimas ${keepCount} de ${lines.length} linhas)
-
-[... ${removed} linhas anteriores removidas ...]
-
-${lines.slice(-keepCount).join("\n")}`;
-}
-
-/**
- * Lista todos os agents que têm memória
- */
-function listAgentsWithMemory(): string[] {
-  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
-// ═══════════════════════════════════════════════════════════════════════════
-
-/**
- * Handler: read - Lê a memória do agent atual
- */
-async function handleRead(agentName: string): Promise<string> {
-  const memoryPath = getAgentMemoryPath(agentName);
-
-  if (!existsSync(memoryPath)) {
-    return `📝 Memória vazia para agent "${agentName}".
-
-Use \`command="append", entry="..."\` para criar a primeira entrada.`;
-  }
-
-  try {
-    const content = readFileSync(memoryPath, "utf-8");
-    const lines = content.split("\n").length;
-    return `📝 Memória de "${agentName}" (${lines} linhas):
-
-─────────────────────────────────────────────────────────────────
-
-${content}`;
-  } catch (error) {
-    return `❌ Erro ao ler memória: ${(error as Error).message}`;
-  }
-}
-
-/**
- * Handler: write - Substitui toda a memória
- */
-async function handleWrite(
-  agentName: string,
-  content: string
-): Promise<string> {
-  try {
-    ensureAgentMemoryDir(agentName);
-    const limited = limitMemoryLines(content);
-    writeFileSync(getAgentMemoryPath(agentName), limited, "utf-8");
-
-    const lines = limited.split("\n").length;
-    return `✅ Memória de "${agentName}" atualizada (${lines} linhas).
-
-${lines >= 200 ? "⚠️ Memória atingiu o limite de 200 linhas." : ""}`;
-  } catch (error) {
-    return `❌ Erro ao escrever memória: ${(error as Error).message}`;
-  }
-}
-
-/**
- * Handler: append - Adiciona uma entrada no final
- */
-async function handleAppend(
-  agentName: string,
-  entry: string
-): Promise<string> {
-  try {
-    ensureAgentMemoryDir(agentName);
-    const memoryPath = getAgentMemoryPath(agentName);
-
-    // Lê conteúdo existente
-    let existingContent = "";
-    if (existsSync(memoryPath)) {
-      existingContent = readFileSync(memoryPath, "utf-8");
-    }
-
-    // Adiciona nova entrada com timestamp
-    const timestamp = formatTimestamp();
-    const newEntry = `\n## [${timestamp}]\n${entry}\n`;
-    const newContent = existingContent + newEntry;
-
-    // Salva com limite
-    const limited = limitMemoryLines(newContent);
-    writeFileSync(memoryPath, limited, "utf-8");
-
-    return `✅ Entrada adicionada à memória de "${agentName}".
-
-**Timestamp:** ${timestamp}
-**Entry:** ${entry.slice(0, 100)}${entry.length > 100 ? "..." : ""}`;
-  } catch (error) {
-    return `❌ Erro ao adicionar entrada: ${(error as Error).message}`;
-  }
-}
-
-/**
- * Handler: search - Busca texto na memória
- */
-async function handleSearch(
-  agentName: string,
-  query: string
-): Promise<string> {
-  const memoryPath = getAgentMemoryPath(agentName);
-
-  if (!existsSync(memoryPath)) {
-    return `📝 Memória vazia para agent "${agentName}".`;
-  }
-
-  try {
-    const content = readFileSync(memoryPath, "utf-8");
-    const lines = content.split("\n");
-    const queryLower = query.toLowerCase();
-
-    const matches = lines
-      .map((line, idx) => ({ line, idx }))
-      .filter(({ line }) => line.toLowerCase().includes(queryLower));
-
-    if (matches.length === 0) {
-      return `📝 Nenhuma ocorrência de "${query}" encontrada na memória de "${agentName}".`;
-    }
-
-    const results = matches
-      .slice(0, 20) // Máximo 20 resultados
-      .map(({ line, idx }) => `  L${idx + 1}: ${line}`)
-      .join("\n");
-
-    const more = matches.length > 20 ? `\n... e mais ${matches.length - 20} ocorrências` : "";
-
-    return `📝 Busca por "${query}" em "${agentName}" (${matches.length} ocorrências):
-
-${results}${more}`;
-  } catch (error) {
-    return `❌ Erro ao buscar: ${(error as Error).message}`;
-  }
-}
-
-/**
- * Handler: list - Lista todos os agents com memória
- */
-async function handleList(): Promise<string> {
-  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
-// ═══════════════════════════════════════════════════════════════════════════
-
-// Cria o servidor MCP
-const server = new Server(
-  {
-    name: "@justmpm/memory",
-    version: PACKAGE_VERSION,
-  },
-  {
-    capabilities: {
-      tools: {},
-    },
-  }
-);
-
-/**
- * Handler: ListTools - Lista todas as tools disponíveis
- */
-server.setRequestHandler(ListToolsRequestSchema, async () => {
-  return {
-    tools: [
-      {
-        name: "memory",
-        description: `
-Gerencia memória persistente para subagents entre sessões.
-
-**PROPÓSITO:** Permitir que agents salvem e recuperem aprendizados específicos do projeto entre diferentes sessões de trabalho. Cada agent mantém sua própria memória isolada.
-
-**LOCALIZAÇÃO:** .claude/agent-memory/<agent-name>/MEMORY.md (nome do agent é normalizado: lowercase, hífens para espaços)
-
-**LIMITE:** Máximo 200 linhas (quando excedido, mantém as últimas 160 entradas + cabeçalho de alerta)
-
-═══════════════════════════════════════════════════════════════
-COMANDOS DISPONÍVEIS:
-═══════════════════════════════════════════════════════════════
-
-1. **read** - Lê a memória de um agent
-   Uso: Carregar contexto anterior ao iniciar uma sessão
-   - agent: (opcional) Nome do agent. Se não fornecido, usa "unknown"
-   - Retorna: Conteúdo completo do MEMORY.md com contagem de linhas
-   - Se não existir: Retorna mensagem de memória vazia com sugestão
-
-2. **write** - Substitui TODO o conteúdo da memória
-   Uso: Reorganizar, limpar ou reconstruir memória do zero
-   - agent: (opcional) Nome do agent
-   - content: (OBRIGATÓRIO) Novo conteúdo completo em markdown
-   - Aplica: Limite de 200 linhas automaticamente
-   - Retorna: Confirmação + contagem de linhas
-
-3. **append** - Adiciona entrada ao final (COM TIMESTAMP)
-   Uso: Salvar aprendizados incrementais sem perder histórico
-   - agent: (opcional) Nome do agent
-   - entry: (OBRIGATÓRIO) Texto a adicionar
-   - Formato automático: "## [YYYY-MM-DD HH:MM:SS]\\n<entry>"
-   - Aplica: Limite de 200 linhas automaticamente
-   - Retorna: Timestamp + preview da entrada
-
-4. **search** - Busca termo específico na memória
-   Uso: Encontrar informações rápidas sem ler tudo
-   - agent: (opcional) Nome do agent
-   - query: (OBRIGATÓRIO) Termo de busca (case-insensitive)
-   - Retorna: Máximo 20 ocorrências com número da linha
-   - Se não encontrado: Mensagem clara de "nenhuma ocorrência"
-
-5. **list** - Lista todos os agents com memória no projeto
-   Uso: Descobrir quais agents já usaram memória neste projeto
-   - Sem parâmetros adicionais
-   - Retorna: Lista com nome de cada agent + contagem de linhas
-
-═══════════════════════════════════════════════════════════════
-QUANDO USAR CADA COMANDO:
-═══════════════════════════════════════════════════════════════
-
-✅ **USE READ:**
-   - Ao INICIAR uma sessão de trabalho
-   - Quando precisar entender o contexto anterior
-   - Antes de fazer decisões baseadas em memória passada
-
-✅ **USE APPEND:**
-   - Ao APRENDER algo novo e importante
-   - Ao descobrir padrões no código
-   - Ao encontrar bugs recorrentes
-   - Ao tomar decisões arquiteturais
-   - Para manter cronologia de descobertas
-
-✅ **USE WRITE:**
-   - Quando memória estiver muito grande (perto de 200 linhas)
-   - Para reorganizar e consolidar informações
-   - Para remover entradas obsoletas
-   - Para reestruturar seções (Padrões, Decisões, Bugs)
-
-✅ **USE SEARCH:**
-   - Para buscar informações específicas rapidamente
-   - Para verificar se algo já foi documentado
-   - Para encontrar padrões específicos (ex: "Zod", "TypeScript")
-
-✅ **USE LIST:**
-   - Para descobrir agents existentes no projeto
-   - Para ver quantos agents usaram memória
-   - Ao iniciar trabalho em projeto desconhecido
-
-═══════════════════════════════════════════════════════════════
-EXEMPLOS DE USO:
-═══════════════════════════════════════════════════════════════
-
-Exemplo 1 - Iniciar sessão e carregar memória:
-  { "command": "read", "agent": "sentinel" }
-
-Exemplo 2 - Salvar padrão descoberto:
-  { "command": "append", "agent": "sentinel", "entry": "Padrão: Sempre use Zod para validar inputs do usuário em todos os componentes de formulário" }
-
-Exemplo 3 - Salvar decisão arquitetural:
-  { "command": "append", "agent": "nexus", "entry": "Decisão: Usar Zustand para estado global (mais leve que Redux) - Projeto tem até 5 stores independentes" }
-
-Exemplo 4 - Buscar informações sobre Zod:
-  { "command": "search", "agent": "sentinel", "query": "Zod" }
-
-Exemplo 5 - Reorganizar memória grande:
-  { "command": "write", "agent": "sentinel", "content": "# Memória do Sentinel\\n\\n## Padrões\\n- Use Zod para validação\\n\\n## Bugs\\n- Bug XYZ: ocorre quando..." }
-
-Exemplo 6 - Listar todos os agents:
-  { "command": "list" }
-
-═══════════════════════════════════════════════════════════════
-BOAS PRÁTICAS (O QUE SALVAR):
-═══════════════════════════════════════════════════════════════
-
-✅ **SEMPRE salve:**
-   - Padrões de código descobertos (ex: "Sempre use 2 espaços de indentação em TSX")
-   - Decisões arquiteturais (ex: "Escolhemos Firestore em vez de PostgreSQL porque...")
-   - Bugs recorrentes (ex: "Erro X acontece quando...")
-   - Soluções para problemas específicos (ex: "Para resolver problema Y, use...")
-   - Configurações importantes (ex: "Firebase Auth usa Google Sign-In")
-   - Preferências do usuário (ex: "Matheus prefere estilos inline para componentes simples")
-
-✅ **Use markdown organizado:**
-   ## Padrões       - Padrões de código e convenções
-   ## Decisões      - Escolhas arquiteturais e trade-offs
-   ## Bugs          - Problemas conhecidos e workarounds
-   ## Configurações - Configs e setup específicos
-   ## Preferências  - Preferências pessoais do usuário
-
-✅ **Adicione contexto:**
-   - "No projeto X, use Y..." (especifica o projeto)
-   - "Ao trabalhar com componente Z..." (especifica o contexto)
-   - "Quando acontecer erro Y..." (especifica a condição)
-
-═══════════════════════════════════════════════════════════════
-BOAS PRÁTICAS (O QUE NÃO SALVAR):
-═══════════════════════════════════════════════════════════════
-
-❌ **NÃO salve:**
-   - Coisas triviais (ex: "Hoje está chovendo")
-   - Informações que mudam frequentemente (ex: "Tem 3 arquivos na pasta")
-   - Coisas que são óbvias (ex: "O código precisa compilar")
-   - Informações duplicadas
-   - Logs de conversação
-   - Erros temporários que já foram resolvidos
-
-❌ **NÃO repita:**
-   - Se um padrão já está salvo, não salve novamente
-   - Use search para verificar antes de salvar
-
-═══════════════════════════════════════════════════════════════
-IMPORTANTE:
-═══════════════════════════════════════════════════════════════
-
-• O nome do agent é NORMALIZADO automaticamente:
-  - "Sentinel" → "sentinel"
-  - "QA-Tester" → "qa-tester"
-  - "My Agent" → "my-agent"
-
-• O parâmetro 'agent' é OPCIONAL:
-   - Se não fornecido, usa "unknown" como nome padrão
-   - É recomendável SEMPRE fornecer o nome do agent atual
-
-• Memória é específica por projeto:
-  - Cada projeto tem sua própria pasta .claude/agent-memory/
-  - Memórias de diferentes projetos não se misturam
-
-• Quando a memória atinge 200 linhas:
-  - As primeiras entradas mais antigas são removidas automaticamente
-  - Mantém as últimas 160 linhas mais recentes
-  - Adiciona cabeçalho informando sobre a limpeza
-  - Use write para reorganizar se isso acontecer com frequência
-        `.trim(),
-        inputSchema: {
-          type: "object",
-          properties: {
-            command: {
-              type: "string",
-              enum: ["read", "write", "append", "search", "list"],
-              description: "Comando a executar. 'read' carrega memória, 'write' substitui tudo, 'append' adiciona entrada, 'search' busca termo, 'list' mostra agents.",
-            },
-            agent: {
-              type: "string",
-              description: 'Nome do agent (opcional, usa "unknown" se não fornecido). O nome será normalizado (lowercase, hífens). Ex: "Sentinel", "QA-Tester", "My Agent"',
-            },
-            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.',
-            },
-            entry: {
-              type: "string",
-              description: 'Texto da entrada a adicionar no final da memória (OBRIGATÓRIO para "append"). Será prefixado automaticamente com timestamp "## [YYYY-MM-DD HH:MM:SS]". Use para salvar aprendizados incrementais.',
-            },
-            query: {
-              type: "string",
-              description: 'Termo ou padrão de busca case-insensitive (OBRIGATÓRIO para "search"). Retorna até 20 ocorrências com número da linha. Ex: "Zod", "bug", "Firebase"',
-            },
-          },
-          required: ["command"],
-        },
-      },
-    ],
-  };
-});
-
-/**
- * Handler: CallTool - Executa uma tool
- */
-server.setRequestHandler(CallToolRequestSchema, async (request) => {
-  const { name, arguments: args } = request.params;
-
-  if (name !== "memory") {
-    throw new Error(`Tool desconhecida: ${name}`);
-  }
-
-  const command = args?.command as string;
-  const agentName = (args?.agent as string) || "unknown";
-
-  // Valida comando
-  const validCommands = ["read", "write", "append", "search", "list"];
-  if (!validCommands.includes(command)) {
-    return {
-      content: [
-        {
-          type: "text",
-          text: `❌ ERRO: Comando desconhecido "${command}"
-
-COMANDOS DISPONÍVEIS:
-
-  1. read    - Lê a memória de um agent
-  2. write   - Substitui todo o conteúdo da memória
-  3. append  - Adiciona uma entrada ao final (com timestamp)
-  4. search  - Busca um termo na memória
-  5. list    - Lista todos os agents com memória no projeto
-
-PARA MAIS DETALHES, CONSULTE A DESCRIÇÃO DA TOOL "memory"
-`,
-        },
-      ],
-    };
-  }
-
-  // Executa comando específico
-  let result: string;
-
-  switch (command) {
-    case "read": {
-      result = await handleRead(agentName);
-      break;
-    }
-
-    case "write": {
-      const content = args?.content as string;
-      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 "write" para reorganizar memória grande ou reconstruir do zero.
-Para adicionar uma entrada preservando o histórico, use "append".
-`;
-        break;
-      }
-      result = await handleWrite(agentName, content);
-      break;
-    }
-
-    case "append": {
-      const entry = args?.entry as string;
-      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;
-      }
-      result = await handleAppend(agentName, entry);
-      break;
-    }
-
-    case "search": {
-      const query = args?.query as string;
-      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;
-      }
-      result = await handleSearch(agentName, query);
-      break;
-    }
-
-    case "list": {
-      result = await handleList();
-      break;
-    }
-
-    default:
-      result = `❌ Comando desconhecido: ${command}`;
-  }
-
-  return {
-    content: [
-      {
-        type: "text",
-        text: result,
-      },
-    ],
-  };
-});
-
-// ═══════════════════════════════════════════════════════════════════════════
-// 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
-}
-
-main().catch((error) => {
-  console.error("Erro fatal ao iniciar servidor:", error);
-  process.exit(1);
-});
+#!/usr/bin/env node
+
+/**
+ * Memory MCP Server - Sistema de memória persistente para subagents
+ *
+ * Permite que subagents salvem e recuperem aprendizados entre sessões.
+ * Cada agent tem sua própria memória, armazenada em .claude/agent-memory/<agent-name>/MEMORY.md
+ *
+ * @see https://modelcontextprotocol.io/
+ */
+
+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 { join, dirname } from "path";
+import { fileURLToPath } from "url";
+
+// ═══════════════════════════════════════════════════════════════════════════
+// VERSÃO DO PROJETO
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Lê a versão do package.json dinamicamente
+ */
+function getPackageVersion(): string {
+  try {
+    const __filename = fileURLToPath(import.meta.url);
+    const __dirname = dirname(__filename);
+    const packagePath = join(__dirname, "..", "package.json");
+    const packageJson = JSON.parse(readFileSync(packagePath, "utf-8"));
+    return packageJson.version || "0.1.0";
+  } catch {
+    return "0.1.0";
+  }
+}
+
+const PACKAGE_VERSION = getPackageVersion();
+
+// ═══════════════════════════════════════════════════════════════════════════
+// FUNÇÕES UTILITÁRIAS
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Normaliza nome do agent para usar como nome de pasta
+ * Ex: "Sentinel" → "sentinel", "QA-Tester" → "qa-tester"
+ */
+function normalizeAgentName(agentName: string): string {
+  return agentName
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-|-$/g, "");
+}
+
+/**
+ * Retorna o caminho do diretório de memória para um agent
+ */
+function getAgentMemoryDir(agentName: string): string {
+  const normalizedName = normalizeAgentName(agentName);
+  return join(process.cwd(), ".claude", "agent-memory", normalizedName);
+}
+
+/**
+ * Retorna o caminho do arquivo MEMORY.md de um agent
+ */
+function getAgentMemoryPath(agentName: string): string {
+  return join(getAgentMemoryDir(agentName), "MEMORY.md");
+}
+
+/**
+ * Garante que o diretório existe
+ */
+function ensureAgentMemoryDir(agentName: string): void {
+  const dir = getAgentMemoryDir(agentName);
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true });
+  }
+}
+
+/**
+ * Formata timestamp para uso em entradas de memória
+ */
+function formatTimestamp(): string {
+  const now = new Date();
+  return now.toISOString().replace("T", " ").slice(0, 19);
+}
+
+/**
+ * Limita memória a ~200 linhas (últimas entradas)
+ */
+function limitMemoryLines(content: string, maxLines = 200): string {
+  const lines = content.split("\n");
+  if (lines.length <= maxLines) return content;
+  const keepCount = Math.floor(maxLines * 0.8); // 160 linhas
+  const removed = lines.length - keepCount;
+  return `# Memória (últimas ${keepCount} de ${lines.length} linhas)
+
+[... ${removed} linhas anteriores removidas ...]
+
+${lines.slice(-keepCount).join("\n")}`;
+}
+
+/**
+ * Lista todos os agents que têm memória
+ */
+function listAgentsWithMemory(): string[] {
+  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
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Handler: read - Lê a memória do agent atual
+ */
+async function handleRead(agentName: string): Promise<string> {
+  const memoryPath = getAgentMemoryPath(agentName);
+
+  if (!existsSync(memoryPath)) {
+    return `📝 Memória vazia para agent "${agentName}".
+
+Use \`command="append", entry="..."\` para criar a primeira entrada.`;
+  }
+
+  try {
+    const content = readFileSync(memoryPath, "utf-8");
+    const lines = content.split("\n").length;
+    return `📝 Memória de "${agentName}" (${lines} linhas):
+
+─────────────────────────────────────────────────────────────────
+
+${content}`;
+  } catch (error) {
+    return `❌ Erro ao ler memória: ${(error as Error).message}`;
+  }
+}
+
+/**
+ * Handler: write - Substitui toda a memória
+ */
+async function handleWrite(
+  agentName: string,
+  content: string,
+  backup: boolean = false
+): Promise<string> {
+  try {
+    ensureAgentMemoryDir(agentName);
+    const memoryPath = getAgentMemoryPath(agentName);
+
+    // Cria backup se solicitado e arquivo existir
+    let backupMessage = "";
+    if (backup && existsSync(memoryPath)) {
+      const backupPath = memoryPath + ".backup";
+      const existingContent = readFileSync(memoryPath, "utf-8");
+      writeFileSync(backupPath, existingContent, "utf-8");
+      backupMessage = `\n💾 Backup criado: MEMORY.md.backup`;
+    }
+
+    const limited = limitMemoryLines(content);
+    writeFileSync(memoryPath, limited, "utf-8");
+
+    const lines = limited.split("\n").length;
+    return `✅ Memória de "${agentName}" atualizada (${lines} linhas).${backupMessage}
+
+${lines >= 200 ? "⚠️ Memória atingiu o limite de 200 linhas." : ""}`;
+  } catch (error) {
+    return `❌ Erro ao escrever memória: ${(error as Error).message}`;
+  }
+}
+
+/**
+ * Handler: append - Adiciona uma entrada no final
+ */
+async function handleAppend(
+  agentName: string,
+  entry: string
+): Promise<string> {
+  try {
+    ensureAgentMemoryDir(agentName);
+    const memoryPath = getAgentMemoryPath(agentName);
+
+    // Lê conteúdo existente
+    let existingContent = "";
+    if (existsSync(memoryPath)) {
+      existingContent = readFileSync(memoryPath, "utf-8");
+    }
+
+    // Adiciona nova entrada com timestamp
+    const timestamp = formatTimestamp();
+    const newEntry = `\n## [${timestamp}]\n${entry}\n`;
+    const newContent = existingContent + newEntry;
+
+    // Salva com limite
+    const limited = limitMemoryLines(newContent);
+    writeFileSync(memoryPath, limited, "utf-8");
+
+    return `✅ Entrada adicionada à memória de "${agentName}".
+
+**Timestamp:** ${timestamp}
+**Entry:** ${entry.slice(0, 100)}${entry.length > 100 ? "..." : ""}`;
+  } catch (error) {
+    return `❌ Erro ao adicionar entrada: ${(error as Error).message}`;
+  }
+}
+
+/**
+ * Handler: search - Busca texto na memória
+ */
+async function handleSearch(
+  agentName: string,
+  query: string
+): Promise<string> {
+  const memoryPath = getAgentMemoryPath(agentName);
+
+  if (!existsSync(memoryPath)) {
+    return `📝 Memória vazia para agent "${agentName}".`;
+  }
+
+  try {
+    const content = readFileSync(memoryPath, "utf-8");
+    const lines = content.split("\n");
+    const queryLower = query.toLowerCase();
+
+    const matches = lines
+      .map((line, idx) => ({ line, idx }))
+      .filter(({ line }) => line.toLowerCase().includes(queryLower));
+
+    if (matches.length === 0) {
+      return `📝 Nenhuma ocorrência de "${query}" encontrada na memória de "${agentName}".`;
+    }
+
+    const results = matches
+      .slice(0, 20) // Máximo 20 resultados
+      .map(({ line, idx }) => `  L${idx + 1}: ${line}`)
+      .join("\n");
+
+    const more = matches.length > 20 ? `\n... e mais ${matches.length - 20} ocorrências` : "";
+
+    return `📝 Busca por "${query}" em "${agentName}" (${matches.length} ocorrências):
+
+${results}${more}`;
+  } catch (error) {
+    return `❌ Erro ao buscar: ${(error as Error).message}`;
+  }
+}
+
+/**
+ * Handler: list - Lista todos os agents com memória
+ */
+async function handleList(): Promise<string> {
+  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
+// ═══════════════════════════════════════════════════════════════════════════
+
+// Cria o servidor MCP
+const server = new Server(
+  {
+    name: "@justmpm/memory",
+    version: PACKAGE_VERSION,
+  },
+  {
+    capabilities: {
+      tools: {},
+    },
+  }
+);
+
+/**
+ * Handler: ListTools - Lista todas as tools disponíveis
+ */
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+  return {
+    tools: [
+      {
+        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"],
+        },
+      },
+    ],
+  };
+});
+
+/**
+ * Handler: CallTool - Executa uma tool
+ */
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const { name, arguments: args } = request.params;
+
+  if (name !== "memory") {
+    throw new Error(`Tool desconhecida: ${name}`);
+  }
+
+  const command = args?.command as string;
+  const agentName = (args?.agent as string) || "unknown";
+
+  // Valida comando
+  const validCommands = ["read", "append", "search", "write"];
+  if (!validCommands.includes(command)) {
+    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"
+`,
+        },
+      ],
+    };
+  }
+
+  // Executa comando específico
+  let result: string;
+
+  switch (command) {
+    case "read": {
+      result = await handleRead(agentName);
+      break;
+    }
+
+    case "write": {
+      const content = args?.content as string;
+      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;
+      }
+      const backup = (args?.backup as boolean) || false;
+      result = await handleWrite(agentName, content, backup);
+      break;
+    }
+
+    case "append": {
+      const entry = args?.entry as string;
+      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;
+      }
+      result = await handleAppend(agentName, entry);
+      break;
+    }
+
+    case "search": {
+      const query = args?.query as string;
+      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;
+      }
+      result = await handleSearch(agentName, query);
+      break;
+    }
+
+    default:
+      result = `❌ Comando desconhecido: ${command}`;
+  }
+
+  return {
+    content: [
+      {
+        type: "text",
+        text: result,
+      },
+    ],
+  };
+});
+
+// ═══════════════════════════════════════════════════════════════════════════
+// 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
+}
+
+main().catch((error) => {
+  console.error("Erro fatal ao iniciar servidor:", error);
+  process.exit(1);
+});