@justmpm/memory

MCP Server (Model Context Protocol) para gerenciar memória persistente de subagents entre sessões.

Descrição

Este servidor permite que subagents salvem e recuperem aprendizados específicos do projeto entre diferentes sessões de trabalho. Cada agent mantém sua própria memória isolada, armazenada em .claude/agent-memory/<agent-name>/MEMORY.md.

Por que usar?

• Persistência entre sessões: Aprendizados salvos não se perdem quando a sessão termina
• Memória por agent: Cada subagent tem sua própria memória isolada
• Específico por projeto: Cada projeto tem sua própria pasta de memórias
• Auto-limpeza: Limite automático de 200 linhas para manter memória gerenciável
• Busca eficiente: Encontre informações rapidamente sem ler tudo

Instalação

npm install -g @justmpm/memory

Ou localmente:

npm install
npm run build

Uso

Como Servidor MCP

Para usar este servidor como MCP, adicione ao seu arquivo de configuração do cliente MCP:

Opção 1 - Caminho absoluto (desenvolvimento local):

{
  "mcpServers": {
    "memory": {
      "command": "node",
      "args": ["D:\\Users\\Matheus Pimenta\\Pictures\\Pacotes-Pessoais\\mcps-ai\\memory\\dist\\index.js"]
    }
  }
}

Opção 2 - Via npx (após publicar no npm):

{
  "mcpServers": {
    "memory": {
      "command": "npx",
      "args": ["@justmpm/memory"]
    }
  }
}

Tools Disponíveis

memory_read - Lê a memória do agent

Quando usar: Ao iniciar uma sessão para carregar contexto anterior.

{
  "agent": "sentinel"  // opcional, padrão: "unknown"
}

Retorna: Conteúdo completo do MEMORY.md com contagem de linhas.

memory_write - Substitui toda a memória

Quando usar: Para reorganizar, limpar ou reconstruir memória do zero.

{
  "agent": "sentinel",
  "content": "# Memória do Sentinel\n\n## Padrões\n- Sempre use TypeScript estrito\n\n## Bugs\n- Bug XYZ ocorre quando..."
}

Retorna: Confirmação + contagem de linhas.

Backup de segurança:

{
  "agent": "sentinel",
  "content": "# Nova memória...",
  "backup": true
}

Quando backup: true, o conteúdo atual é salvo em MEMORY.md.backup antes de sobrescrever.

memory_append - Adiciona uma entrada no final

Quando usar: Ao aprender algo novo e importante.

{
  "agent": "sentinel",
  "entry": "Padrão descoberto: sempre use Zod para validar inputs do usuário"
}

Retorna: Timestamp + preview da entrada.

Nota: O timestamp é adicionado automaticamente: ## [2026-02-09 12:34:56]

memory_search - Busca texto na memória

Quando usar: Para encontrar informações rápidas sem ler tudo.

{
  "agent": "sentinel",
  "query": "Zod"
}

Retorna: Máximo 20 ocorrências com número da linha (case-insensitive).

Estrutura de Arquivos

.claude/
└── agent-memory/
    ├── sentinel/
    │   └── MEMORY.md
    ├── qa-tester/
    │   └── MEMORY.md
    └── nexus/
        └── MEMORY.md

Nota: O nome do agent é normalizado automaticamente:

• "Sentinel" → "sentinel"
• "QA-Tester" → "qa-tester"
• "My Agent" → "my-agent"

Workflow Recomendado

1. Ao iniciar sessão:

   { "agent": "sentinel" }  // via memory_read

   → Carrega memória anterior para contexto

2. Ao aprender algo importante:

   { "agent": "sentinel", "entry": "Padrão descoberto: ..." }  // via memory_append

   → Salva aprendizado incremental

3. Quando memória ficar grande (~200 linhas):

   { "agent": "sentinel", "content": "# Memória Reorganizada\n\n..." }  // via memory_write

   → Consolide e remova entradas obsoletas

4. Para buscar informação específica:

   { "agent": "sentinel", "query": "Zod" }  // via memory_search

   → Encontre rapidamente sem ler tudo

O Que Salvar

✅ SEMPRE salve

• Padrões de código: 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 específicas: 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"

❌ NÃO salve

• Coisas triviais: "Hoje está chovendo"
• Informações que mudam frequentemente: "Tem 3 arquivos na pasta"
• Coisas óbvias: "O código precisa compilar"
• Informações duplicadas
• Logs de conversação

Boas Práticas

Formatação recomendada

Use seções markdown organizadas:

# Memória do [Nome do Agent]

## Padrões
- Sempre use TypeScript estrito
- Use Zod para validação de inputs

## Decisões
- Escolhemos Zustand em vez de Redux (mais leve)
- Firestore para banco de dados (escalabilidade)

## Bugs
- Bug XYZ: ocorre quando...
- Solução temporária: use workaround...

## Configurações
- Firebase Auth com Google Sign-In
- MUI v7 para componentes

## Preferências
- Matheus prefere componentes funcionais
- Use 2 espaços de indentação

Dicas

• Seja específico: "Use 2 espaços" > "Formate bem"
• Adicione contexto: "No projeto X, use Y..."
• Use memory_append para entradas cronológicas: Mantém histórico
• Use memory_write para reorganizar: Limpa e estrutura
• memory_search antes de salvar: Evita duplicatas
• Limpe periodicamente: Remova entradas obsoletas

Limitações

• Máximo 200 linhas: Quando excedido, mantém as últimas 160 linhas
• Memória é específica por projeto: Cada projeto tem sua própria pasta
• Parâmetro agent é opcional: Usa "unknown" se não fornecido (mas é recomendável sempre fornecer)

Desenvolvimento

# Desenvolvimento com hot reload
npm run dev

# Build
npm run build

# Executar
npm start

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 tool
• 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 simplificado para subagents sobre como usar a memória. Inclui:

• Descrição rápida de cada tool
• Workflow básico
• Dicas rápidas

Para Subagents: Consulte AGENTS.md para orientações rápidas.

Changelog

Veja CHANGELOG.md para histórico de versões.

Licença

MIT © Koda AI Studio