melhorias

2026-06-23 07:30:59 -03:00 · 2026-06-23 07:30:59 -03:00 · b482fcd6c3
commit b482fcd6c3
parent 56c301ad35
12 changed files with 145 additions and 6 deletions
--- a/agents/ag-agente/persona
+++ b/agents/ag-agente/persona
@ -291,6 +291,10 @@ Você **deve** usar a Memória Azteca (`https://memoria-ia.idz.one`) para consul

 > **`resumo` é obrigatório** ao criar memórias (10-500 chars). O resumo alimenta a busca vetorial com peso B. Sempre incluir `resumo` junto com `titulo`, `conteudo`, `categoria` e `criado_por`.

+> **`contexto`** (opcional) — use para categorizar por projeto, módulo ou cliente (ex: `Módulo Licenças`, `Cliente XPTO`).
+
+> **Vínculos** — relacione memórias usando `{mem:ID}` no campo `relacao` via `/api/vinculos/criar`. Sempre vincular quando descobrir relações entre memórias existentes.
+
 ### Quando consultar

 - Antes de criar ou alterar agentes (verificar decisões anteriores)
--- a/agents/ag-arquiteto/persona
+++ b/agents/ag-arquiteto/persona
@ -73,6 +73,10 @@ Você **deve** usar a Memória Azteca (`https://memoria-ia.idz.one`) para consul

 > **`resumo` é obrigatório** ao criar memórias (10-500 chars). O resumo alimenta a busca vetorial com peso B. Sempre incluir `resumo` junto com `titulo`, `conteudo`, `categoria` e `criado_por`.

+> **`contexto`** (opcional) — use para categorizar por projeto, módulo ou cliente (ex: `Módulo Licenças`, `Cliente XPTO`).
+
+> **Vínculos** — relacione memórias usando `{mem:ID}` no campo `relacao` via `/api/vinculos/criar`. Sempre vincular quando descobrir relações entre memórias existentes.
+
 ### Quando consultar

 - Antes de definir arquitetura de novos módulos (verificar ADRs existentes)
--- a/agents/ag-back/persona
+++ b/agents/ag-back/persona
@ -76,6 +76,10 @@ Você **deve** usar a Memória Azteca (`https://memoria-ia.idz.one`) para consul

 > **`resumo` é obrigatório** ao criar memórias (10-500 chars). O resumo alimenta a busca vetorial com peso B. Sempre incluir `resumo` junto com `titulo`, `conteudo`, `categoria` e `criado_por`.

+> **`contexto`** (opcional) — use para categorizar por projeto, módulo ou cliente (ex: `Módulo Licenças`, `Cliente XPTO`).
+
+> **Vínculos** — relacione memórias usando `{mem:ID}` no campo `relacao` via `/api/vinculos/criar`. Sempre vincular quando descobrir relações entre memórias existentes.
+
 ### Quando consultar

 - Antes de implementar lógica em módulo que não conhece
--- a/agents/ag-comercial/persona
+++ b/agents/ag-comercial/persona
@ -73,6 +73,10 @@ Você **deve** usar a Memória Azteca (`https://memoria-ia.idz.one`) para consul

 > **`resumo` é obrigatório** ao criar memórias (10-500 chars). O resumo alimenta a busca vetorial com peso B. Sempre incluir `resumo` junto com `titulo`, `conteudo`, `categoria` e `criado_por`.

+> **`contexto`** (opcional) — use para categorizar por projeto, módulo ou cliente (ex: `Módulo Licenças`, `Cliente XPTO`).
+
+> **Vínculos** — relacione memórias usando `{mem:ID}` no campo `relacao` via `/api/vinculos/criar`. Sempre vincular quando descobrir relações entre memórias existentes.
+
 ### Quando consultar

 - Antes de criar material sobre funcionalidades (verificar o que realmente existe)
--- a/agents/ag-deploy/persona
+++ b/agents/ag-deploy/persona
@ -72,6 +72,10 @@ Você **deve** usar a Memória Azteca (`https://memoria-ia.idz.one`) para consul

 > **`resumo` é obrigatório** ao criar memórias (10-500 chars). O resumo alimenta a busca vetorial com peso B. Sempre incluir `resumo` junto com `titulo`, `conteudo`, `categoria` e `criado_por`.

+> **`contexto`** (opcional) — use para categorizar por projeto, módulo ou cliente (ex: `Módulo Licenças`, `Cliente XPTO`).
+
+> **Vínculos** — relacione memórias usando `{mem:ID}` no campo `relacao` via `/api/vinculos/criar`. Sempre vincular quando descobrir relações entre memórias existentes.
+
 ### Quando consultar

 - Antes de configurar ambientes (verificar configurações anteriores)
--- a/agents/ag-documentacao/persona
+++ b/agents/ag-documentacao/persona
@ -71,6 +71,10 @@ Você **deve** usar a Memória Azteca (`https://memoria-ia.idz.one`) para consul

 > **`resumo` é obrigatório** ao criar memórias (10-500 chars). O resumo alimenta a busca vetorial com peso B. Sempre incluir `resumo` junto com `titulo`, `conteudo`, `categoria` e `criado_por`.

+> **`contexto`** (opcional) — use para categorizar por projeto, módulo ou cliente (ex: `Módulo Licenças`, `Cliente XPTO`).
+
+> **Vínculos** — relacione memórias usando `{mem:ID}` no campo `relacao` via `/api/vinculos/criar`. Sempre vincular quando descobrir relações entre memórias existentes.
+
 ### Quando consultar

 - Antes de documentar módulos (verificar contexto e decisões existentes)
--- a/agents/ag-front/persona
+++ b/agents/ag-front/persona
@ -76,6 +76,10 @@ Você **deve** usar a Memória Azteca (`https://memoria-ia.idz.one`) para consul

 > **`resumo` é obrigatório** ao criar memórias (10-500 chars). O resumo alimenta a busca vetorial com peso B. Sempre incluir `resumo` junto com `titulo`, `conteudo`, `categoria` e `criado_por`.

+> **`contexto`** (opcional) — use para categorizar por projeto, módulo ou cliente (ex: `Módulo Licenças`, `Cliente XPTO`).
+
+> **Vínculos** — relacione memórias usando `{mem:ID}` no campo `relacao` via `/api/vinculos/criar`. Sempre vincular quando descobrir relações entre memórias existentes.
+
 ### Quando consultar

 - Antes de implementar telas em módulo que não conhece
--- a/agents/ag-refatorar/persona
+++ b/agents/ag-refatorar/persona
@ -220,6 +220,10 @@ Você **deve** usar a Memória Azteca (`https://memoria-ia.idz.one`) para consul

 > **`resumo` é obrigatório** ao criar memórias (10-500 chars). O resumo alimenta a busca vetorial com peso B. Sempre incluir `resumo` junto com `titulo`, `conteudo`, `categoria` e `criado_por`.

+> **`contexto`** (opcional) — use para categorizar por projeto, módulo ou cliente (ex: `Módulo Licenças`, `Cliente XPTO`).
+
+> **Vínculos** — relacione memórias usando `{mem:ID}` no campo `relacao` via `/api/vinculos/criar`. Sempre vincular quando descobrir relações entre memórias existentes.
+
 ### Quando consultar

 - Antes de refatorar módulo desconhecido (buscar contexto e decisões anteriores)
--- a/agents/ag-testes/persona
+++ b/agents/ag-testes/persona
@ -106,6 +106,10 @@ Você **deve** usar a Memória Azteca (`https://memoria-ia.idz.one`) para consul

 > **`resumo` é obrigatório** ao criar memórias (10-500 chars). O resumo alimenta a busca vetorial com peso B. Sempre incluir `resumo` junto com `titulo`, `conteudo`, `categoria` e `criado_por`.

+> **`contexto`** (opcional) — use para categorizar por projeto, módulo ou cliente (ex: `Módulo Licenças`, `Cliente XPTO`).
+
+> **Vínculos** — relacione memórias usando `{mem:ID}` no campo `relacao` via `/api/vinculos/criar`. Sempre vincular quando descobrir relações entre memórias existentes.
+
 ### Quando consultar

 - Antes de testar módulo que não conhece (buscar contexto e bugs anteriores)
--- a/agents/ag-ux/persona
+++ b/agents/ag-ux/persona
@ -72,6 +72,10 @@ Você **deve** usar a Memória Azteca (`https://memoria-ia.idz.one`) para consul

 > **`resumo` é obrigatório** ao criar memórias (10-500 chars). O resumo alimenta a busca vetorial com peso B. Sempre incluir `resumo` junto com `titulo`, `conteudo`, `categoria` e `criado_por`.

+> **`contexto`** (opcional) — use para categorizar por projeto, módulo ou cliente (ex: `Módulo Licenças`, `Cliente XPTO`).
+
+> **Vínculos** — relacione memórias usando `{mem:ID}` no campo `relacao` via `/api/vinculos/criar`. Sempre vincular quando descobrir relações entre memórias existentes.
+
 ### Quando consultar

 - Antes de revisar UX de módulo que não conhece (buscar decisões anteriores)
--- a/global/rules/usar-memoria-persistente
+++ b/global/rules/usar-memoria-persistente
@ -66,6 +66,26 @@ curl -s -X POST "https://memoria-ia.idz.one/api/memorias/criar" \

 > Se a informação seria útil para outro agente ou para a mesma tarefa daqui 1 semana — **salve na memória**.

+## Vínculos entre memórias
+
+Ao criar ou editar memórias, verificar se existem memórias relacionadas na base. Se sim, criar vínculos usando a rota `/api/vinculos/criar` com a sintaxe `{mem:ID}` no campo `relacao`.
+
+```bash
+curl -s -X POST "https://memoria-ia.idz.one/api/vinculos/criar" \
+  -H 'Content-Type: application/json' \
+  -H "CHAVE: banana" \
+  -d '{
+    "codigo_memoria_a": 1,
+    "codigo_memoria_b": 5,
+    "relacao": "{mem:1} define o padrão usado por {mem:5}",
+    "criado_por": "@HANDLE_DO_AGENTE"
+  }'
+```
+
+## Campo contexto
+
+Use o campo opcional `contexto` para categorizar memórias por projeto, módulo ou cliente (ex: `Módulo Licenças`, `Projeto Edital Resíduos`, `Cliente XPTO`). Facilita filtros e buscas por escopo.
+
 ## Impacto

 Sem esta regra, cada sessão começa do zero. Com ela, o ecossistema acumula conhecimento e fica mais inteligente a cada interação.
--- a/global/skills/memoria-persistente/SKILL
+++ b/global/skills/memoria-persistente/SKILL
@ -76,7 +76,7 @@ curl -s -X POST "https://memoria-ia.idz.one/api/busca/rapida" \
 curl -s -X POST "https://memoria-ia.idz.one/api/memorias/listar" \
  -H 'Content-Type: application/json' \
  -H "CHAVE: banana" \
-  -d '{"categoria": "solucao-problemas", "modulo": "licencas", "limite": 10}'
+  -d '{"categoria": "solucao-problemas", "contexto": "Módulo Licenças", "limite": 10}'
 ```

 ### Listar por tags
@ -112,7 +112,7 @@ curl -s -X POST "https://memoria-ia.idz.one/api/memorias/criar" \
    "categoria": "modulos",
    "tipo": "referencia",
    "tags": ["tag1", "tag2"],
-    "modulo": "nome-do-modulo",
+    "contexto": "Módulo Licenças",
    "criado_por": "@ag-back"
  }'
 ```
@ -133,7 +133,7 @@ curl -s -X POST "https://memoria-ia.idz.one/api/memorias/criar" \
 |-------|-----------|
 | `tipo` | Tipo da memória: `nota`, `adr`, `solucao-problemas`, `referencia`, `procedimento` (default: `nota`) |
 | `tags` | Array de strings para facilitar busca e filtragem |
-| `modulo` | Nome do módulo/projeto relacionado |
+| `contexto` | Contexto da memória (ex: `Módulo Licenças`, `Projeto Edital Resíduos`, `Cliente XPTO`) |

 ### Categorias disponíveis

@ -225,12 +225,74 @@ curl -s -X POST "https://memoria-ia.idz.one/api/tags/populares" \
 | `POST /api/memorias/buscar` | Buscar por código |
 | `POST /api/memorias/listar` | Listar com filtros e paginação |
 | `POST /api/memorias/excluir` | Exclusão lógica |
+| `POST /api/vinculos/criar` | Criar vínculo entre memórias |
+| `POST /api/vinculos/listar` | Listar vínculos de uma memória |
+| `POST /api/vinculos/excluir` | Excluir vínculo |
 | `POST /api/categorias/listar` | Listar categorias disponíveis |
 | `POST /api/tags/listar` | Listar todas as tags |
 | `POST /api/tags/populares` | Tags mais usadas |

 ---

+## PASSO 6 — Vínculos entre memórias
+
+Vínculos permitem relacionar memórias entre si usando a sintaxe `{mem:ID}` no campo `relacao`.
+
+### Regras de vínculo
+
+- `codigo_memoria_a` e `codigo_memoria_b` **não podem ser iguais**
+- O campo `relacao` **deve** conter `{mem:codigo_memoria_a}` e `{mem:codigo_memoria_b}`
+- A relação é bidirecional — aparece ao consultar qualquer uma das memórias vinculadas
+
+### Criar vínculo
+
+```bash
+curl -s -X POST "https://memoria-ia.idz.one/api/vinculos/criar" \
+  -H 'Content-Type: application/json' \
+  -H "CHAVE: banana" \
+  -d '{
+    "codigo_memoria_a": 1,
+    "codigo_memoria_b": 5,
+    "relacao": "{mem:1} é sócio de {mem:5}",
+    "criado_por": "@ag-arquiteto"
+  }'
+```
+
+### Exemplos de relação
+
+```
+{mem:1} é sócio de {mem:5}
+{mem:3} e {mem:7} são concorrentes
+{mem:2} depende de {mem:4}
+{mem:10} substituiu {mem:6}
+```
+
+### Listar vínculos de uma memória
+
+```bash
+curl -s -X POST "https://memoria-ia.idz.one/api/vinculos/listar" \
+  -H 'Content-Type: application/json' \
+  -H "CHAVE: banana" \
+  -d '{"codigo_memoria": 1}'
+```
+
+### Excluir vínculo
+
+```bash
+curl -s -X POST "https://memoria-ia.idz.one/api/vinculos/excluir" \
+  -H 'Content-Type: application/json' \
+  -H "CHAVE: banana" \
+  -d '{"codigo": 42}'
+```
+
+### Quando criar vínculos
+
+- Ao registrar decisões que impactam outras memórias existentes
+- Ao descobrir relações entre pessoas, módulos ou conceitos já documentados
+- Ao resolver um problema cuja causa está documentada em outra memória
+
+---
+
 ## Boas práticas

 1. **Buscar antes de criar** — evitar duplicatas na base
@ -240,7 +302,9 @@ curl -s -X POST "https://memoria-ia.idz.one/api/tags/populares" \
 5. **Tags relevantes** — facilitar buscas futuras por contexto e filtragem por tags
 6. **Conteúdo rico** — incluir contexto, decisão, motivo e exemplos quando possível
 7. **Atualizar, não duplicar** — se a memória já existe, usar editar em vez de criar nova
-8. **Pipe com jq** — para leitura limpa, adicionar `| jq .` ao final do curl
+8. **Vincular memórias relacionadas** — ao criar ou editar, verificar se existem memórias que devem ser vinculadas com `{mem:ID}`
+9. **Contexto descritivo** — usar o campo `contexto` para categorizar por projeto, módulo ou cliente (ex: `Módulo Licenças`, `Cliente XPTO`)
+10. **Pipe com jq** — para leitura limpa, adicionar `| jq .` ao final do curl

 ---

@ -259,7 +323,7 @@ curl -s -X POST "https://memoria-ia.idz.one/api/memorias/criar" \
    "categoria": "decisoes",
    "tipo": "adr",
    "tags": ["licencas", "paginacao", "api"],
-    "modulo": "licencas",
+    "contexto": "Módulo Licenças",
    "criado_por": "@ag-back"
  }'
 ```
@ -277,7 +341,7 @@ curl -s -X POST "https://memoria-ia.idz.one/api/memorias/criar" \
    "categoria": "solucao-problemas",
    "tipo": "solucao-problemas",
    "tags": ["upload", "nginx", "timeout", "bug"],
-    "modulo": "arquivos",
+    "contexto": "Módulo Arquivos",
    "criado_por": "@ag-testes"
  }'
 ```
@ -291,6 +355,20 @@ curl -s -X POST "https://memoria-ia.idz.one/api/busca" \
  -d '{"termo": "composable padrão vue"}' | jq .
 ```

+### @ag-arquiteto criando vínculo entre memórias
+
+```bash
+curl -s -X POST "https://memoria-ia.idz.one/api/vinculos/criar" \
+  -H 'Content-Type: application/json' \
+  -H "CHAVE: banana" \
+  -d '{
+    "codigo_memoria_a": 3,
+    "codigo_memoria_b": 7,
+    "relacao": "{mem:3} define o padrão de resposta usado por {mem:7}",
+    "criado_por": "@ag-arquiteto"
+  }'
+```
+
 ---

 ## Checklist
@ -302,6 +380,7 @@ curl -s -X POST "https://memoria-ia.idz.one/api/busca" \
 - [ ] Preenchi `criado_por` com meu handle?
 - [ ] O conteúdo tem contexto suficiente para ser útil no futuro?
 - [ ] Adicionei tags relevantes?
+- [ ] Existem memórias relacionadas que devem ser vinculadas?

 ---