npm package: @justmpm/memory
Description: MCP Server para gerenciar memória persistente de subagents
Author: Koda AI Studio
Latest version: 0.3.0

# @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

```bash
npm install -g @justmpm/memory
```

Ou localmente:

```bash
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):**
```json
{
  "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):**
```json
{
  "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.

```json
{
  "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.

```json
{
  "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:**
```json
{
  "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.

```json
{
  "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.

```json
{
  "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:**
   ```json
   { "agent": "sentinel" }  // via memory_read
   ```
   → Carrega memória anterior para contexto

2. **Ao aprender algo importante:**
   ```json
   { "agent": "sentinel", "entry": "Padrão descoberto: ..." }  // via memory_append
   ```
   → Salva aprendizado incremental

3. **Quando memória ficar grande (~200 linhas):**
   ```json
   { "agent": "sentinel", "content": "# Memória Reorganizada\n\n..." }  // via memory_write
   ```
   → Consolide e remova entradas obsoletas

4. **Para buscar informação específica:**
   ```json
   { "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:

```markdown
# 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

```bash
# 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](CHANGELOG.md) para histórico de versões.

## Licença

MIT © Koda AI Studio