@justmpm/memory 0.1.2 → 0.2.2

package/README.md

@@ -1,281 +1,277 @@
-# @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
-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 - Após publicar no npm (futuro):**
-```json
-{
-  "mcpServers": {
-    "memory": {
-      "command": "npx",
-      "args": ["@justmpm/memory"]
-    }
-  }
-}
-```
-
-**Nota:** O nome do servidor MCP é "memory" para facilitar o uso, enquanto o nome do pacote npm é "@justmpm/memory".
-
-### Comandos Disponíveis
-
-#### `read` - Lê a memória do agent
-
-**Quando usar:** Ao iniciar uma sessão para carregar contexto anterior.
-
-```json
-{
-  "command": "read",
-  "agent": "sentinel"
-}
-```
-
-**Retorna:** Conteúdo completo do MEMORY.md com contagem de linhas.
-
-#### `write` - Substitui toda a memória
-
-**Quando usar:** Para reorganizar, limpar ou reconstruir memória do zero.
-
-```json
-{
-  "command": "write",
-  "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.
-
-#### `append` - Adiciona uma entrada no final
-
-**Quando usar:** Ao aprender algo novo e importante.
-
-```json
-{
-  "command": "append",
-  "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]`
-
-#### `search` - Busca texto na memória
-
-**Quando usar:** Para encontrar informações rápidas sem ler tudo.
-
-```json
-{
-  "command": "search",
-  "agent": "sentinel",
-  "query": "Zod"
-}
-```
-
-**Retorna:** Máximo 20 ocorrências com número da linha.
-
-#### `list` - Lista todos os agents com memória
-
-**Quando usar:** Para descobrir quais agents usaram memória no projeto.
-
-```json
-{
-  "command": "list"
-}
-```
-
-**Retorna:** Lista com nome de cada agent + contagem de linhas.
-
-## 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
-   { "command": "read", "agent": "sentinel" }
-   ```
-   → Carrega memória anterior para contexto
-
-2. **Ao aprender algo importante:**
-   ```json
-   { "command": "append", "agent": "sentinel", "entry": "Padrão descoberto: ..." }
-   ```
-   → Salva aprendizado incremental
-
-3. **Quando memória ficar grande (~200 linhas):**
-   ```json
-   { "command": "write", "agent": "sentinel", "content": "# Memória Reorganizada\n\n..." }
-   ```
-   → Consolide e remova entradas obsoletas
-
-4. **Para buscar informação específica:**
-   ```json
-   { "command": "search", "agent": "sentinel", "query": "Zod" }
-   ```
-   → 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 append para entradas cronológicas:** Mantém histórico
-- **Use write para reorganizar:** Limpa e estrutura
-- **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
-```
-
-## Versão
-
-Para alterar a versão do servidor MCP, basta modificar o campo `version` no arquivo `package.json`. O `index.ts` lê automaticamente a versão do package.json em tempo de execução.
-
-## 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 comando
-- 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 específico para cada tipo de subagent sobre como usar a memória de forma alinhada com sua especialização. Inclui:
-
-- O que cada tipo de agent deve salvar
-- Formato de memória recomendado por agent
-- Exemplos práticos por tipo
-- Compartilhamento de informações entre agents
-- Boas práticas específicas
-
-**Para Subagents:** Consulte a seção relevante em AGENTS.md para orientações específicas do seu tipo.
-
-## Licença
-
-MIT © Koda AI Studio
+# @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