@justmpm/memory 0.2.1 → 0.2.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/AGENTS.md +45 -640
- package/CHANGELOG.md +42 -0
- package/CLAUDE.md +74 -180
- package/README.md +31 -46
- package/dist/index.js +164 -286
- package/dist/index.js.map +1 -1
- package/package.json +3 -2
- package/src/index.ts +185 -292
- package/TEST_REPORT.md +0 -226
package/CHANGELOG.md
ADDED
|
@@ -0,0 +1,42 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
All notable changes to this project will be documented in this file.
|
|
4
|
+
|
|
5
|
+
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
|
|
6
|
+
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
|
|
7
|
+
|
|
8
|
+
## [0.2.2] - 2026-02-10
|
|
9
|
+
|
|
10
|
+
### Changed
|
|
11
|
+
- **BREAKING**: Refatorado de 1 tool com múltiplos comandos para 4 tools separadas
|
|
12
|
+
- `memory_read` - Lê a memória do agent
|
|
13
|
+
- `memory_append` - Adiciona nova entrada com timestamp
|
|
14
|
+
- `memory_search` - Busca termo específico na memória
|
|
15
|
+
- `memory_write` - Reescreve toda a memória
|
|
16
|
+
- Removido comando `list` (cada agent gerencia apenas sua própria memória)
|
|
17
|
+
- Adicionado Zod para validação de schemas
|
|
18
|
+
- Melhoradas descrições das tools para serem mais diretas e claras
|
|
19
|
+
- Simplificadas mensagens de erro com validação automática
|
|
20
|
+
|
|
21
|
+
### Fixed
|
|
22
|
+
- Validação de parâmetros obrigatórios agora usa Zod schemas
|
|
23
|
+
- Mensagens de erro mais informativas
|
|
24
|
+
|
|
25
|
+
## [0.2.1] - 2026-02-09
|
|
26
|
+
|
|
27
|
+
### Added
|
|
28
|
+
- Documentação CLAUDE.md e AGENTS.md
|
|
29
|
+
- Comando `list` para listar todos os agents com memória
|
|
30
|
+
|
|
31
|
+
### Fixed
|
|
32
|
+
- Pequenas correções na documentação
|
|
33
|
+
|
|
34
|
+
## [0.2.0] - 2026-02-08
|
|
35
|
+
|
|
36
|
+
### Added
|
|
37
|
+
- Versão inicial do MCP Server
|
|
38
|
+
- Tools: read, append, search, write, list
|
|
39
|
+
- Suporte a múltiplos agents
|
|
40
|
+
- Limite automático de 200 linhas por memória
|
|
41
|
+
- Timestamp automático para entradas append
|
|
42
|
+
- Backup opcional para operação write
|
package/CLAUDE.md
CHANGED
|
@@ -37,9 +37,9 @@
|
|
|
37
37
|
|
|
38
38
|
---
|
|
39
39
|
|
|
40
|
-
##
|
|
40
|
+
## Tools Disponíveis
|
|
41
41
|
|
|
42
|
-
### 1.
|
|
42
|
+
### 1. memory_read - Carregar memória anterior
|
|
43
43
|
|
|
44
44
|
**Quando usar:**
|
|
45
45
|
- Ao INICIAR uma nova sessão
|
|
@@ -49,8 +49,7 @@
|
|
|
49
49
|
**Sintaxe:**
|
|
50
50
|
```json
|
|
51
51
|
{
|
|
52
|
-
"
|
|
53
|
-
"agent": "nexus" // ← Seu nome de agent
|
|
52
|
+
"agent": "nexus" // ← Seu nome de agent (opcional, padrão: "unknown")
|
|
54
53
|
}
|
|
55
54
|
```
|
|
56
55
|
|
|
@@ -61,14 +60,14 @@
|
|
|
61
60
|
|
|
62
61
|
**Workflow recomendado:**
|
|
63
62
|
```
|
|
64
|
-
1. Primeira coisa ao iniciar sessão:
|
|
63
|
+
1. Primeira coisa ao iniciar sessão: use memory_read
|
|
65
64
|
2. Analise o conteúdo retornado
|
|
66
65
|
3. Use as informações salvas para informar suas decisões
|
|
67
66
|
```
|
|
68
67
|
|
|
69
68
|
---
|
|
70
69
|
|
|
71
|
-
### 2.
|
|
70
|
+
### 2. memory_append - Salvar aprendizado novo
|
|
72
71
|
|
|
73
72
|
**Quando usar:**
|
|
74
73
|
- Ao APRENDER algo importante sobre o projeto
|
|
@@ -80,7 +79,6 @@
|
|
|
80
79
|
**Sintaxe:**
|
|
81
80
|
```json
|
|
82
81
|
{
|
|
83
|
-
"command": "append",
|
|
84
82
|
"agent": "nexus",
|
|
85
83
|
"entry": "Padrão descoberto: Sempre use Zod para validar inputs do usuário em todos os componentes de formulário"
|
|
86
84
|
}
|
|
@@ -103,28 +101,24 @@
|
|
|
103
101
|
```json
|
|
104
102
|
// Padrão de código
|
|
105
103
|
{
|
|
106
|
-
"command": "append",
|
|
107
104
|
"agent": "nexus",
|
|
108
105
|
"entry": "Padrão: Este projeto usa App Router com estrutura /features/[domain]/. Sempre que criar um novo domínio, coloque em /features/[domain]/components, /features/[domain]/hooks, etc."
|
|
109
106
|
}
|
|
110
107
|
|
|
111
108
|
// Decisão arquitetural
|
|
112
109
|
{
|
|
113
|
-
"command": "append",
|
|
114
110
|
"agent": "nexus",
|
|
115
111
|
"entry": "Decisão: Escolhemos Zustand em vez de Redux para estado global. Motivo: mais leve, TypeScript-friendly, e este projeto tem até 5 stores independentes"
|
|
116
112
|
}
|
|
117
113
|
|
|
118
114
|
// Bug recorrente
|
|
119
115
|
{
|
|
120
|
-
"command": "append",
|
|
121
116
|
"agent": "nexus",
|
|
122
117
|
"entry": "Bug: Firestore update com array de strings falha silenciosamente quando array está vazio. Workaround: sempre verificar if (array.length > 0) antes de update"
|
|
123
118
|
}
|
|
124
119
|
|
|
125
120
|
// Preferência do usuário
|
|
126
121
|
{
|
|
127
|
-
"command": "append",
|
|
128
122
|
"agent": "nexus",
|
|
129
123
|
"entry": "Preferência: Matheus prefere componentes funcionais simples com styled-components em vez de criar arquivos separados CSS"
|
|
130
124
|
}
|
|
@@ -132,53 +126,7 @@
|
|
|
132
126
|
|
|
133
127
|
---
|
|
134
128
|
|
|
135
|
-
### 3.
|
|
136
|
-
|
|
137
|
-
**Quando usar:**
|
|
138
|
-
- Quando memória estiver MUITO GRANDE (perto de 200 linhas)
|
|
139
|
-
- Para REORGANIZAR estruturas e seções
|
|
140
|
-
- Para REMOVER entradas obsoletas
|
|
141
|
-
- Para RECONSTRUIR memória do zero
|
|
142
|
-
|
|
143
|
-
**Sintaxe:**
|
|
144
|
-
```json
|
|
145
|
-
{
|
|
146
|
-
"command": "write",
|
|
147
|
-
"agent": "nexus",
|
|
148
|
-
"content": "# Memória do Nexus\n\n## Padrões\n- Sempre use TypeScript estrito\n\n## Decisões\n- Zustand em vez de Redux\n\n## Bugs\n- Bug XYZ ocorre quando..."
|
|
149
|
-
}
|
|
150
|
-
```
|
|
151
|
-
|
|
152
|
-
**O que acontece:**
|
|
153
|
-
- SUBSTITUI TODO o conteúdo existente
|
|
154
|
-
- Aplica limite de 200 linhas
|
|
155
|
-
- Cria estrutura nova do zero
|
|
156
|
-
|
|
157
|
-
**CUIDADO:** `write` APAGA tudo o que estava antes! Use com cautela.
|
|
158
|
-
|
|
159
|
-
**Quando usar write vs append:**
|
|
160
|
-
|
|
161
|
-
| Situação | Use |
|
|
162
|
-
|----------|-----|
|
|
163
|
-
| Aprender algo novo | `append` |
|
|
164
|
-
| Salvar decisão incremental | `append` |
|
|
165
|
-
| Memória grande demais | `write` |
|
|
166
|
-
| Remover entradas obsoletas | `write` |
|
|
167
|
-
| Reorganizar seções | `write` |
|
|
168
|
-
|
|
169
|
-
**Exemplo de reorganização:**
|
|
170
|
-
|
|
171
|
-
```json
|
|
172
|
-
{
|
|
173
|
-
"command": "write",
|
|
174
|
-
"agent": "nexus",
|
|
175
|
-
"content": "# Memória do Nexus\n\n## Padrões de Código\n- Sempre use TypeScript estrito (noImplicitAny: true)\n- Use 2 espaços de indentação em TSX\n- Nomeie componentes com PascalCase\n\n## Arquitetura\n- App Router com estrutura /features/[domain]/\n- Cada domínio tem components/, hooks/, services/\n\n## Decisões\n- Zustand para estado global (mais leve que Redux)\n- Firestore para banco de dados (escalabilidade)\n- MUI v7 para componentes UI\n\n## Bugs Conhecidos\n- Bug XYZ: ocorre quando... (workaround: ...)\n- Bug ABC: acontece se... (solução: ...)\n\n## Preferências do Matheus\n- Prefere componentes funcionais\n- Gosta de código conciso (1-3 linhas quando possível)\n- Valoriza explicações simples"
|
|
176
|
-
}
|
|
177
|
-
```
|
|
178
|
-
|
|
179
|
-
---
|
|
180
|
-
|
|
181
|
-
### 4. SEARCH - Buscar informação específica
|
|
129
|
+
### 3. memory_search - Buscar informação específica
|
|
182
130
|
|
|
183
131
|
**Quando usar:**
|
|
184
132
|
- Para encontrar informações rápidas sem ler tudo
|
|
@@ -188,7 +136,6 @@
|
|
|
188
136
|
**Sintaxe:**
|
|
189
137
|
```json
|
|
190
138
|
{
|
|
191
|
-
"command": "search",
|
|
192
139
|
"agent": "nexus",
|
|
193
140
|
"query": "Zod"
|
|
194
141
|
}
|
|
@@ -196,47 +143,74 @@
|
|
|
196
143
|
|
|
197
144
|
**O que retorna:**
|
|
198
145
|
- Até 20 ocorrências com número da linha
|
|
199
|
-
- Case-insensitive (busca "zod" e "Zod"
|
|
146
|
+
- Case-insensitive (busca "zod" e "Zod")
|
|
200
147
|
- Se não encontrado: mensagem clara
|
|
201
148
|
|
|
202
149
|
**Exemplos de buscas úteis:**
|
|
203
150
|
|
|
204
151
|
```json
|
|
205
152
|
// Buscar padrão específico
|
|
206
|
-
{ "
|
|
153
|
+
{ "agent": "nexus", "query": "padrão" }
|
|
207
154
|
|
|
208
155
|
// Buscar bug específico
|
|
209
|
-
{ "
|
|
156
|
+
{ "agent": "nexus", "query": "bug" }
|
|
210
157
|
|
|
211
158
|
// Buscar tecnologia
|
|
212
|
-
{ "
|
|
159
|
+
{ "agent": "nexus", "query": "TypeScript" }
|
|
213
160
|
|
|
214
161
|
// Buscar preferência
|
|
215
|
-
{ "
|
|
162
|
+
{ "agent": "nexus", "query": "Matheus" }
|
|
216
163
|
|
|
217
164
|
// Buscar erro específico
|
|
218
|
-
{ "
|
|
165
|
+
{ "agent": "nexus", "query": "Firebase" }
|
|
219
166
|
```
|
|
220
167
|
|
|
221
168
|
---
|
|
222
169
|
|
|
223
|
-
###
|
|
170
|
+
### 4. memory_write - Reorganizar memória
|
|
224
171
|
|
|
225
172
|
**Quando usar:**
|
|
226
|
-
-
|
|
227
|
-
-
|
|
173
|
+
- Quando memória estiver MUITO GRANDE (perto de 200 linhas)
|
|
174
|
+
- Para REORGANIZAR estruturas e seções
|
|
175
|
+
- Para REMOVER entradas obsoletas
|
|
176
|
+
- Para RECONSTRUIR memória do zero
|
|
228
177
|
|
|
229
178
|
**Sintaxe:**
|
|
230
179
|
```json
|
|
231
180
|
{
|
|
232
|
-
"
|
|
181
|
+
"agent": "nexus",
|
|
182
|
+
"content": "# Memória do Nexus\n\n## Padrões\n- Sempre use TypeScript estrito\n\n## Decisões\n- Zustand em vez de Redux\n\n## Bugs\n- Bug XYZ ocorre quando...",
|
|
183
|
+
"backup": true
|
|
233
184
|
}
|
|
234
185
|
```
|
|
235
186
|
|
|
236
|
-
**O que
|
|
237
|
-
-
|
|
238
|
-
-
|
|
239
|
-
- Se
|
|
187
|
+
**O que acontece:**
|
|
188
|
+
- SUBSTITUI TODO o conteúdo existente
|
|
189
|
+
- Aplica limite de 200 linhas
|
|
190
|
+
- Se `backup: true`, cria MEMORY.md.backup antes
|
|
191
|
+
- Cria estrutura nova do zero
|
|
192
|
+
|
|
193
|
+
**CUIDADO:** `memory_write` APAGA tudo o que estava antes! Use com cautela.
|
|
194
|
+
|
|
195
|
+
**Quando usar write vs append:**
|
|
196
|
+
|
|
197
|
+
| Situação | Use |
|
|
198
|
+
|----------|-----|
|
|
199
|
+
| Aprender algo novo | `memory_append` |
|
|
200
|
+
| Salvar decisão incremental | `memory_append` |
|
|
201
|
+
| Memória grande demais | `memory_write` |
|
|
202
|
+
| Remover entradas obsoletas | `memory_write` |
|
|
203
|
+
| Reorganizar seções | `memory_write` |
|
|
204
|
+
|
|
205
|
+
**Exemplo de reorganização:**
|
|
206
|
+
|
|
207
|
+
```json
|
|
208
|
+
{
|
|
209
|
+
"agent": "nexus",
|
|
210
|
+
"content": "# Memória do Nexus\n\n## Padrões de Código\n- Sempre use TypeScript estrito (noImplicitAny: true)\n- Use 2 espaços de indentação em TSX\n- Nomeie componentes com PascalCase\n\n## Arquitetura\n- App Router com estrutura /features/[domain]/\n- Cada domínio tem components/, hooks/, services/\n\n## Decisões\n- Zustand para estado global (mais leve que Redux)\n- Firestore para banco de dados (escalabilidade)\n- MUI v7 para componentes UI\n\n## Bugs Conhecidos\n- Bug XYZ: ocorre quando... (workaround: ...)\n\n## Preferências do Matheus\n- Prefere componentes funcionais\n- Gosta de código conciso (1-3 linhas quando possível)",
|
|
211
|
+
"backup": true
|
|
212
|
+
}
|
|
213
|
+
```
|
|
240
214
|
|
|
241
215
|
---
|
|
242
216
|
|
|
@@ -245,22 +219,22 @@
|
|
|
245
219
|
### Ao Iniciar uma Sessão
|
|
246
220
|
|
|
247
221
|
```
|
|
248
|
-
1.
|
|
222
|
+
1. Use memory_read
|
|
249
223
|
↓
|
|
250
224
|
2. Analise as entradas retornadas
|
|
251
225
|
↓
|
|
252
226
|
3. Use o conhecimento salvo para informar suas respostas
|
|
253
227
|
↓
|
|
254
|
-
4. Se a memória estiver muito grande, considere reorganizar com
|
|
228
|
+
4. Se a memória estiver muito grande, considere reorganizar com memory_write
|
|
255
229
|
```
|
|
256
230
|
|
|
257
231
|
### Durante a Sessão
|
|
258
232
|
|
|
259
233
|
```
|
|
260
|
-
Ao aprender algo importante →
|
|
261
|
-
Ao tomar uma decisão →
|
|
262
|
-
Ao descobrir um bug →
|
|
263
|
-
Ao identificar um padrão →
|
|
234
|
+
Ao aprender algo importante → memory_append
|
|
235
|
+
Ao tomar uma decisão → memory_append
|
|
236
|
+
Ao descobrir um bug → memory_append
|
|
237
|
+
Ao identificar um padrão → memory_append
|
|
264
238
|
```
|
|
265
239
|
|
|
266
240
|
### Ao Final da Sessão
|
|
@@ -268,7 +242,7 @@ Ao identificar um padrão → APPEND
|
|
|
268
242
|
```
|
|
269
243
|
1. Revise as entradas adicionadas
|
|
270
244
|
↓
|
|
271
|
-
2. Se memória estiver grande (~150+ linhas), considere
|
|
245
|
+
2. Se memória estiver grande (~150+ linhas), considere memory_write para limpar
|
|
272
246
|
↓
|
|
273
247
|
3. Organize as entradas em seções (Padrões, Decisões, Bugs, etc.)
|
|
274
248
|
```
|
|
@@ -326,7 +300,7 @@ Ao identificar um padrão → APPEND
|
|
|
326
300
|
|
|
327
301
|
**Informações duplicadas:**
|
|
328
302
|
- Se um padrão já está salvo, não salve novamente
|
|
329
|
-
- Use
|
|
303
|
+
- Use memory_search antes de salvar para verificar
|
|
330
304
|
|
|
331
305
|
**Logs de conversação:**
|
|
332
306
|
- Não salve cada mensagem da conversa
|
|
@@ -383,11 +357,11 @@ Use seções markdown bem organizadas:
|
|
|
383
357
|
### 1. Verifique antes de salvar
|
|
384
358
|
|
|
385
359
|
```
|
|
386
|
-
1.
|
|
360
|
+
1. Use memory_search com o termo
|
|
387
361
|
↓
|
|
388
362
|
2. Se já existe, não salve duplicata
|
|
389
363
|
↓
|
|
390
|
-
3. Se não existe, faça
|
|
364
|
+
3. Se não existe, faça memory_append
|
|
391
365
|
```
|
|
392
366
|
|
|
393
367
|
### 2. Seja específico e contextual
|
|
@@ -414,100 +388,20 @@ Use seções markdown bem organizadas:
|
|
|
414
388
|
{ "entry": "Decisão: Usamos Zustand em vez de Redux porque é mais leve (1KB vs 10KB), tem melhor suporte TypeScript, e o projeto tem apenas 5 stores independentes" }
|
|
415
389
|
```
|
|
416
390
|
|
|
417
|
-
### 4. Use
|
|
391
|
+
### 4. Use memory_append para cronologia
|
|
418
392
|
|
|
419
|
-
`
|
|
393
|
+
`memory_append` mantém o histórico cronológico, o que ajuda a entender:
|
|
420
394
|
- Quando aprendizados foram feitos
|
|
421
395
|
- A evolução das decisões
|
|
422
396
|
- Progresso do projeto
|
|
423
397
|
|
|
424
|
-
### 5. Use
|
|
398
|
+
### 5. Use memory_write para limpeza
|
|
425
399
|
|
|
426
400
|
Quando a memória estiver grande (~150+ linhas):
|
|
427
|
-
1.
|
|
401
|
+
1. Use memory_read primeiro
|
|
428
402
|
2. Reorganize em seções bem definidas
|
|
429
403
|
3. Remova entradas obsoletas
|
|
430
|
-
4. Use
|
|
431
|
-
|
|
432
|
-
---
|
|
433
|
-
|
|
434
|
-
## Exemplos Práticos de Uso
|
|
435
|
-
|
|
436
|
-
### Exemplo 1: Iniciar sessão e carregar memória
|
|
437
|
-
|
|
438
|
-
```
|
|
439
|
-
IA: { "command": "read", "agent": "nexus" }
|
|
440
|
-
|
|
441
|
-
Resultado: 📝 Memória de "nexus" (45 linhas):
|
|
442
|
-
─────────────────────────────────────────────────────────────────
|
|
443
|
-
|
|
444
|
-
# Memória do Nexus
|
|
445
|
-
|
|
446
|
-
## Padrões
|
|
447
|
-
- Sempre use TypeScript estrito
|
|
448
|
-
- Nomeie componentes com PascalCase
|
|
449
|
-
|
|
450
|
-
## Decisões
|
|
451
|
-
- Usamos Zustand para estado global
|
|
452
|
-
...
|
|
453
|
-
```
|
|
454
|
-
|
|
455
|
-
### Exemplo 2: Aprender novo padrão
|
|
456
|
-
|
|
457
|
-
```
|
|
458
|
-
Usuário: "Adicione um novo componente de botão"
|
|
459
|
-
IA: [Implementa o botão]
|
|
460
|
-
|
|
461
|
-
IA: { "command": "append", "agent": "nexus",
|
|
462
|
-
"entry": "Padrão descoberto: Este projeto usa MUI Button com variantes customizadas. Para consistência, use: <Button variant='contained' color='primary' size='small'> para botões de ação" }
|
|
463
|
-
```
|
|
464
|
-
|
|
465
|
-
### Exemplo 3: Salvar decisão arquitetural
|
|
466
|
-
|
|
467
|
-
```
|
|
468
|
-
Usuário: "Vamos usar PostgreSQL ou Firestore?"
|
|
469
|
-
IA: [Analisa e recomenda Firestore]
|
|
470
|
-
|
|
471
|
-
IA: { "command": "append", "agent": "nexus",
|
|
472
|
-
"entry": "Decisão: Escolhemos Firestore em vez de PostgreSQL. Motivos: (1) Real-time nativo, (2) Escalabilidade automática, (3) Integração com Firebase Auth, (4) Menor overhead de ops" }
|
|
473
|
-
```
|
|
474
|
-
|
|
475
|
-
### Exemplo 4: Documentar bug
|
|
476
|
-
|
|
477
|
-
```
|
|
478
|
-
Usuário: "O formulário não está salvando"
|
|
479
|
-
IA: [Investiga e descobre o bug]
|
|
480
|
-
|
|
481
|
-
IA: { "command": "append", "agent": "nexus",
|
|
482
|
-
"entry": "Bug: Formulário não salva quando usuário não seleciona foto. Causa: validação em FormData falha quando file input está vazio. Workaround: sempre inicializar FormData com file mesmo que vazio" }
|
|
483
|
-
```
|
|
484
|
-
|
|
485
|
-
### Exemplo 5: Reorganizar memória grande
|
|
486
|
-
|
|
487
|
-
```
|
|
488
|
-
IA: { "command": "read", "agent": "nexus" }
|
|
489
|
-
Resultado: Memória com 195 linhas
|
|
490
|
-
|
|
491
|
-
IA: { "command": "write", "agent": "nexus",
|
|
492
|
-
"content": "# Memória do Nexus\n\n## Padrões (reorganizado e limpo)\n\n..." }
|
|
493
|
-
```
|
|
494
|
-
|
|
495
|
-
---
|
|
496
|
-
|
|
497
|
-
## Verificação Final
|
|
498
|
-
|
|
499
|
-
Antes de fazer `WRITE`, SEMPRE:
|
|
500
|
-
1. ✅ Leia tudo com `READ` primeiro
|
|
501
|
-
2. ✅ Entenda o que está lá
|
|
502
|
-
3. ✅ Reorganize em seções lógicas
|
|
503
|
-
4. ✅ Remova duplicatas e obsoleto
|
|
504
|
-
5. ✅ Preserve o conhecimento importante
|
|
505
|
-
|
|
506
|
-
Antes de fazer `APPEND`, SEMPRE:
|
|
507
|
-
1. ✅ Use `SEARCH` para verificar se já existe
|
|
508
|
-
2. ✅ Seja específico e contextual
|
|
509
|
-
3. ✅ Explique o PORQUÊ quando relevante
|
|
510
|
-
4. ✅ Use formato markdown apropriado
|
|
404
|
+
4. Use memory_write com o conteúdo reorganizado
|
|
511
405
|
|
|
512
406
|
---
|
|
513
407
|
|
|
@@ -529,7 +423,8 @@ Antes de fazer `APPEND`, SEMPRE:
|
|
|
529
423
|
|
|
530
424
|
**Antes de salvar:**
|
|
531
425
|
```json
|
|
532
|
-
|
|
426
|
+
// Use memory_search primeiro
|
|
427
|
+
{ "query": "Zustand" }
|
|
533
428
|
```
|
|
534
429
|
|
|
535
430
|
### Erro 3: Não explicar contexto
|
|
@@ -544,31 +439,30 @@ Antes de fazer `APPEND`, SEMPRE:
|
|
|
544
439
|
{ "entry": "Neste projeto, use 2 espaços de indentação em arquivos TSX (não 4, não tabs). Isso é consistente com o linter configurado" }
|
|
545
440
|
```
|
|
546
441
|
|
|
547
|
-
### Erro 4:
|
|
442
|
+
### Erro 4: memory_write sem ler antes
|
|
548
443
|
|
|
549
444
|
**Errado:**
|
|
550
445
|
```
|
|
551
|
-
IA: { "
|
|
446
|
+
IA: { "tool": "memory_write", "content": "..." }
|
|
552
447
|
```
|
|
553
448
|
|
|
554
449
|
**Certo:**
|
|
555
450
|
```
|
|
556
|
-
IA: { "
|
|
451
|
+
IA: { "tool": "memory_read" }
|
|
557
452
|
[Analisa o conteúdo]
|
|
558
|
-
IA: { "
|
|
453
|
+
IA: { "tool": "memory_write", "content": "..." }
|
|
559
454
|
```
|
|
560
455
|
|
|
561
456
|
---
|
|
562
457
|
|
|
563
458
|
## Resumo
|
|
564
459
|
|
|
565
|
-
|
|
|
566
|
-
|
|
567
|
-
| `
|
|
568
|
-
| `
|
|
569
|
-
| `
|
|
570
|
-
| `
|
|
571
|
-
| `list` | Descobrir agents | Nenhum |
|
|
460
|
+
| Tool | Quando usar | Cuidado |
|
|
461
|
+
|------|------------|---------|
|
|
462
|
+
| `memory_read` | Iniciar sessão | Nenhum |
|
|
463
|
+
| `memory_append` | Aprender algo novo | Use memory_search antes |
|
|
464
|
+
| `memory_write` | Reorganizar memória | Leia ANTES |
|
|
465
|
+
| `memory_search` | Encontrar info rápida | Nenhum |
|
|
572
466
|
|
|
573
467
|
---
|
|
574
468
|
|
package/README.md
CHANGED
|
@@ -16,6 +16,12 @@ Este servidor permite que subagents salvem e recuperem aprendizados específicos
|
|
|
16
16
|
|
|
17
17
|
## Instalação
|
|
18
18
|
|
|
19
|
+
```bash
|
|
20
|
+
npm install -g @justmpm/memory
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
Ou localmente:
|
|
24
|
+
|
|
19
25
|
```bash
|
|
20
26
|
npm install
|
|
21
27
|
npm run build
|
|
@@ -39,7 +45,7 @@ Para usar este servidor como MCP, adicione ao seu arquivo de configuração do c
|
|
|
39
45
|
}
|
|
40
46
|
```
|
|
41
47
|
|
|
42
|
-
**Opção 2 -
|
|
48
|
+
**Opção 2 - Via npx (após publicar no npm):**
|
|
43
49
|
```json
|
|
44
50
|
{
|
|
45
51
|
"mcpServers": {
|
|
@@ -51,30 +57,26 @@ Para usar este servidor como MCP, adicione ao seu arquivo de configuração do c
|
|
|
51
57
|
}
|
|
52
58
|
```
|
|
53
59
|
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
### Comandos Disponíveis
|
|
60
|
+
### Tools Disponíveis
|
|
57
61
|
|
|
58
|
-
#### `
|
|
62
|
+
#### `memory_read` - Lê a memória do agent
|
|
59
63
|
|
|
60
64
|
**Quando usar:** Ao iniciar uma sessão para carregar contexto anterior.
|
|
61
65
|
|
|
62
66
|
```json
|
|
63
67
|
{
|
|
64
|
-
"
|
|
65
|
-
"agent": "sentinel"
|
|
68
|
+
"agent": "sentinel" // opcional, padrão: "unknown"
|
|
66
69
|
}
|
|
67
70
|
```
|
|
68
71
|
|
|
69
72
|
**Retorna:** Conteúdo completo do MEMORY.md com contagem de linhas.
|
|
70
73
|
|
|
71
|
-
#### `
|
|
74
|
+
#### `memory_write` - Substitui toda a memória
|
|
72
75
|
|
|
73
76
|
**Quando usar:** Para reorganizar, limpar ou reconstruir memória do zero.
|
|
74
77
|
|
|
75
78
|
```json
|
|
76
79
|
{
|
|
77
|
-
"command": "write",
|
|
78
80
|
"agent": "sentinel",
|
|
79
81
|
"content": "# Memória do Sentinel\n\n## Padrões\n- Sempre use TypeScript estrito\n\n## Bugs\n- Bug XYZ ocorre quando..."
|
|
80
82
|
}
|
|
@@ -85,7 +87,6 @@ Para usar este servidor como MCP, adicione ao seu arquivo de configuração do c
|
|
|
85
87
|
**Backup de segurança:**
|
|
86
88
|
```json
|
|
87
89
|
{
|
|
88
|
-
"command": "write",
|
|
89
90
|
"agent": "sentinel",
|
|
90
91
|
"content": "# Nova memória...",
|
|
91
92
|
"backup": true
|
|
@@ -93,13 +94,12 @@ Para usar este servidor como MCP, adicione ao seu arquivo de configuração do c
|
|
|
93
94
|
```
|
|
94
95
|
Quando `backup: true`, o conteúdo atual é salvo em `MEMORY.md.backup` antes de sobrescrever.
|
|
95
96
|
|
|
96
|
-
#### `
|
|
97
|
+
#### `memory_append` - Adiciona uma entrada no final
|
|
97
98
|
|
|
98
99
|
**Quando usar:** Ao aprender algo novo e importante.
|
|
99
100
|
|
|
100
101
|
```json
|
|
101
102
|
{
|
|
102
|
-
"command": "append",
|
|
103
103
|
"agent": "sentinel",
|
|
104
104
|
"entry": "Padrão descoberto: sempre use Zod para validar inputs do usuário"
|
|
105
105
|
}
|
|
@@ -109,31 +109,18 @@ Quando `backup: true`, o conteúdo atual é salvo em `MEMORY.md.backup` antes de
|
|
|
109
109
|
|
|
110
110
|
**Nota:** O timestamp é adicionado automaticamente: `## [2026-02-09 12:34:56]`
|
|
111
111
|
|
|
112
|
-
#### `
|
|
112
|
+
#### `memory_search` - Busca texto na memória
|
|
113
113
|
|
|
114
114
|
**Quando usar:** Para encontrar informações rápidas sem ler tudo.
|
|
115
115
|
|
|
116
116
|
```json
|
|
117
117
|
{
|
|
118
|
-
"command": "search",
|
|
119
118
|
"agent": "sentinel",
|
|
120
119
|
"query": "Zod"
|
|
121
120
|
}
|
|
122
121
|
```
|
|
123
122
|
|
|
124
|
-
**Retorna:** Máximo 20 ocorrências com número da linha.
|
|
125
|
-
|
|
126
|
-
#### `list` - Lista todos os agents com memória
|
|
127
|
-
|
|
128
|
-
**Quando usar:** Para descobrir quais agents usaram memória no projeto.
|
|
129
|
-
|
|
130
|
-
```json
|
|
131
|
-
{
|
|
132
|
-
"command": "list"
|
|
133
|
-
}
|
|
134
|
-
```
|
|
135
|
-
|
|
136
|
-
**Retorna:** Lista com nome de cada agent + contagem de linhas.
|
|
123
|
+
**Retorna:** Máximo 20 ocorrências com número da linha (case-insensitive).
|
|
137
124
|
|
|
138
125
|
## Estrutura de Arquivos
|
|
139
126
|
|
|
@@ -157,25 +144,25 @@ Quando `backup: true`, o conteúdo atual é salvo em `MEMORY.md.backup` antes de
|
|
|
157
144
|
|
|
158
145
|
1. **Ao iniciar sessão:**
|
|
159
146
|
```json
|
|
160
|
-
{ "
|
|
147
|
+
{ "agent": "sentinel" } // via memory_read
|
|
161
148
|
```
|
|
162
149
|
→ Carrega memória anterior para contexto
|
|
163
150
|
|
|
164
151
|
2. **Ao aprender algo importante:**
|
|
165
152
|
```json
|
|
166
|
-
{ "
|
|
153
|
+
{ "agent": "sentinel", "entry": "Padrão descoberto: ..." } // via memory_append
|
|
167
154
|
```
|
|
168
155
|
→ Salva aprendizado incremental
|
|
169
156
|
|
|
170
157
|
3. **Quando memória ficar grande (~200 linhas):**
|
|
171
158
|
```json
|
|
172
|
-
{ "
|
|
159
|
+
{ "agent": "sentinel", "content": "# Memória Reorganizada\n\n..." } // via memory_write
|
|
173
160
|
```
|
|
174
161
|
→ Consolide e remova entradas obsoletas
|
|
175
162
|
|
|
176
163
|
4. **Para buscar informação específica:**
|
|
177
164
|
```json
|
|
178
|
-
{ "
|
|
165
|
+
{ "agent": "sentinel", "query": "Zod" } // via memory_search
|
|
179
166
|
```
|
|
180
167
|
→ Encontre rapidamente sem ler tudo
|
|
181
168
|
|
|
@@ -232,9 +219,9 @@ Use seções markdown organizadas:
|
|
|
232
219
|
|
|
233
220
|
- **Seja específico:** "Use 2 espaços" > "Formate bem"
|
|
234
221
|
- **Adicione contexto:** "No projeto X, use Y..."
|
|
235
|
-
- **Use
|
|
236
|
-
- **Use
|
|
237
|
-
- **
|
|
222
|
+
- **Use memory_append para entradas cronológicas:** Mantém histórico
|
|
223
|
+
- **Use memory_write para reorganizar:** Limpa e estrutura
|
|
224
|
+
- **memory_search antes de salvar:** Evita duplicatas
|
|
238
225
|
- **Limpe periodicamente:** Remova entradas obsoletas
|
|
239
226
|
|
|
240
227
|
## Limitações
|
|
@@ -256,10 +243,6 @@ npm run build
|
|
|
256
243
|
npm start
|
|
257
244
|
```
|
|
258
245
|
|
|
259
|
-
## Versão
|
|
260
|
-
|
|
261
|
-
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.
|
|
262
|
-
|
|
263
246
|
## Documentação Adicional
|
|
264
247
|
|
|
265
248
|
### CLAUDE.md
|
|
@@ -267,7 +250,7 @@ Para alterar a versão do servidor MCP, basta modificar o campo `version` no arq
|
|
|
267
250
|
Documentação completa para IAs sobre como usar corretamente o sistema de memória. Inclui:
|
|
268
251
|
|
|
269
252
|
- Workflow recomendado por sessão
|
|
270
|
-
- Guia de quando usar cada
|
|
253
|
+
- Guia de quando usar cada tool
|
|
271
254
|
- O que salvar vs não salvar
|
|
272
255
|
- Formato recomendado
|
|
273
256
|
- Dicas práticas e exemplos
|
|
@@ -277,15 +260,17 @@ Documentação completa para IAs sobre como usar corretamente o sistema de memó
|
|
|
277
260
|
|
|
278
261
|
### AGENTS.md
|
|
279
262
|
|
|
280
|
-
Guia
|
|
263
|
+
Guia simplificado para subagents sobre como usar a memória. Inclui:
|
|
264
|
+
|
|
265
|
+
- Descrição rápida de cada tool
|
|
266
|
+
- Workflow básico
|
|
267
|
+
- Dicas rápidas
|
|
268
|
+
|
|
269
|
+
**Para Subagents:** Consulte AGENTS.md para orientações rápidas.
|
|
281
270
|
|
|
282
|
-
|
|
283
|
-
- Formato de memória recomendado por agent
|
|
284
|
-
- Exemplos práticos por tipo
|
|
285
|
-
- Compartilhamento de informações entre agents
|
|
286
|
-
- Boas práticas específicas
|
|
271
|
+
## Changelog
|
|
287
272
|
|
|
288
|
-
|
|
273
|
+
Veja [CHANGELOG.md](CHANGELOG.md) para histórico de versões.
|
|
289
274
|
|
|
290
275
|
## Licença
|
|
291
276
|
|