@justmpm/memory 0.1.0

package/README.md

@@ -0,0 +1,254 @@
+# @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.
+
+## Licença
+
+MIT © Koda AI Studio

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * 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/
+ */
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG"}