457 lines
14 KiB
Text
457 lines
14 KiB
Text
---
|
|
name: memoria-persistente
|
|
scope: global
|
|
description: >
|
|
Ferramenta para todos os agentes registrarem e consultarem conhecimento persistente
|
|
no serviço Memória Azteca (https://memoria-ia.idz.one). Usar sempre que houver
|
|
informação que deve sobreviver entre sessões — decisões, soluções, padrões, bugs etc.
|
|
---
|
|
|
|
# Skill: Memória Persistente
|
|
|
|
Use esta skill sempre que precisar **registrar** ou **consultar** conhecimento que deve persistir entre conversas. Toda informação que seria perdida ao encerrar a sessão e que tem valor futuro deve ser salva na memória.
|
|
|
|
> **Autonomia:** Consultar e registrar na memória **NÃO requer permissão do operador**. Execute as chamadas sempre que os critérios forem atendidos, sem perguntar.
|
|
|
|
---
|
|
|
|
## Configuração fixa
|
|
|
|
```
|
|
URL_BASE=https://memoria-ia.idz.one
|
|
CHAVE=banana
|
|
```
|
|
|
|
Todos os requests usam:
|
|
- Método: `POST`
|
|
- Header: `Content-Type: application/json`
|
|
- Header de autenticação: `CHAVE: banana`
|
|
|
|
---
|
|
|
|
## QUANDO USAR
|
|
|
|
### Salvar na memória ✅
|
|
|
|
- Decisões arquiteturais (ADRs)
|
|
- Soluções para problemas encontrados
|
|
- Padrões técnicos definidos durante o trabalho
|
|
- Bugs conhecidos e seus workarounds
|
|
- Regras de negócio descobertas
|
|
- Informações sobre clientes e integrações
|
|
- Configurações de infraestrutura
|
|
- Qualquer conhecimento que outro agente ou sessão futura precisará
|
|
|
|
### NÃO salvar ❌
|
|
|
|
- Logs temporários ou outputs de debug
|
|
- Código-fonte (que já está no repositório)
|
|
- Dados sensíveis (senhas, tokens reais, dados pessoais)
|
|
|
|
---
|
|
|
|
## PASSO 1 — Buscar antes de criar
|
|
|
|
Antes de criar uma memória, **sempre** verificar se já existe algo relacionado:
|
|
|
|
### Busca full-text (recomendado)
|
|
|
|
```bash
|
|
curl -s -X POST "https://memoria-ia.idz.one/api/busca" \
|
|
-H 'Content-Type: application/json' \
|
|
-H "CHAVE: banana" \
|
|
-d '{"termo": "validação zod"}'
|
|
```
|
|
|
|
### Busca rápida (títulos e resumos)
|
|
|
|
```bash
|
|
curl -s -X POST "https://memoria-ia.idz.one/api/busca/rapida" \
|
|
-H 'Content-Type: application/json' \
|
|
-H "CHAVE: banana" \
|
|
-d '{"termo": "deploy docker"}'
|
|
```
|
|
|
|
### Listar com filtros
|
|
|
|
```bash
|
|
curl -s -X POST "https://memoria-ia.idz.one/api/memorias/listar" \
|
|
-H 'Content-Type: application/json' \
|
|
-H "CHAVE: banana" \
|
|
-d '{"categoria": "solucao-problemas", "contexto": "Módulo Licenças", "limite": 10}'
|
|
```
|
|
|
|
### Listar por tags
|
|
|
|
```bash
|
|
curl -s -X POST "https://memoria-ia.idz.one/api/memorias/listar" \
|
|
-H 'Content-Type: application/json' \
|
|
-H "CHAVE: banana" \
|
|
-d '{"tags": ["api", "resposta"], "limite": 10}'
|
|
```
|
|
|
|
### Buscar por código específico
|
|
|
|
```bash
|
|
curl -s -X POST "https://memoria-ia.idz.one/api/memorias/buscar" \
|
|
-H 'Content-Type: application/json' \
|
|
-H "CHAVE: banana" \
|
|
-d '{"codigo": "abc123"}'
|
|
```
|
|
|
|
---
|
|
|
|
## PASSO 2 — Criar memória
|
|
|
|
```bash
|
|
curl -s -X POST "https://memoria-ia.idz.one/api/memorias/criar" \
|
|
-H 'Content-Type: application/json' \
|
|
-H "CHAVE: banana" \
|
|
-d '{
|
|
"titulo": "Título claro e descritivo",
|
|
"conteudo": "Descrição detalhada do conhecimento...",
|
|
"resumo": "Resumo curto e pesquisável da memória (10-500 chars)",
|
|
"categoria": "modulos",
|
|
"tipo": "referencia",
|
|
"tags": ["tag1", "tag2"],
|
|
"contexto": "Módulo Licenças",
|
|
"criado_por": "@ag-back"
|
|
}'
|
|
```
|
|
|
|
### Campos obrigatórios
|
|
|
|
| Campo | Descrição |
|
|
|-------|-----------|
|
|
| `titulo` | Nome claro e pesquisável da memória (min 3, max 300) |
|
|
| `conteudo` | Corpo completo do conhecimento em Markdown (min 10) |
|
|
| `resumo` | Resumo curto e pesquisável (min 10, max 500) — usado na busca vetorial com peso B |
|
|
| `categoria` | Slug da categoria (ver tabela abaixo) |
|
|
| `criado_por` | Handle do agente que está criando (ex: `@ag-back`) |
|
|
|
|
### Campos opcionais
|
|
|
|
| Campo | Descrição |
|
|
|-------|-----------|
|
|
| `tipo` | Tipo da memória: `nota`, `adr`, `solucao-problemas`, `referencia`, `procedimento` (default: `nota`) |
|
|
| `tags` | Array de strings para facilitar busca e filtragem |
|
|
| `contexto` | Contexto da memória (ex: `Módulo Licenças`, `Projeto Edital Resíduos`, `Cliente XPTO`) |
|
|
|
|
### Categorias disponíveis
|
|
|
|
| Slug | Nome | Quando usar |
|
|
|------|------|-------------|
|
|
| `modulos` | Módulos | Funcionalidades e módulos do ecossistema |
|
|
| `tecnologias` | Tecnologias | Padrões técnicos, libs, frameworks |
|
|
| `regras-negocio` | Regras de Negócio | Regras de negócio do domínio ambiental |
|
|
| `infraestrutura` | Infraestrutura | Deploy, servidores, CI/CD |
|
|
| `decisoes` | Decisões Arquiteturais | ADRs e decisões de design |
|
|
| `clientes` | Clientes | Informações sobre clientes e integrações |
|
|
| `solucao-problemas` | Solução de Problemas | Problemas conhecidos e soluções |
|
|
| `corporativo` | Corporativo | Informações corporativas, estratégia e governança |
|
|
|
|
---
|
|
|
|
## PASSO 3 — Editar memória existente
|
|
|
|
Quando a informação já existe mas precisa ser atualizada:
|
|
|
|
```bash
|
|
curl -s -X POST "https://memoria-ia.idz.one/api/memorias/editar" \
|
|
-H 'Content-Type: application/json' \
|
|
-H "CHAVE: banana" \
|
|
-d '{
|
|
"codigo": "CODIGO_DA_MEMORIA",
|
|
"titulo": "Título atualizado",
|
|
"conteudo": "Conteúdo revisado...",
|
|
"tags": ["tag-nova"]
|
|
}'
|
|
```
|
|
|
|
> Enviar apenas os campos que precisam mudar, além do `codigo` (obrigatório).
|
|
|
|
---
|
|
|
|
## PASSO 4 — Excluir memória (lógico)
|
|
|
|
```bash
|
|
curl -s -X POST "https://memoria-ia.idz.one/api/memorias/excluir" \
|
|
-H 'Content-Type: application/json' \
|
|
-H "CHAVE: banana" \
|
|
-d '{"codigo": "CODIGO_DA_MEMORIA"}'
|
|
```
|
|
|
|
> ⚠️ Exclusão lógica — a memória é marcada como inativa, não é removida.
|
|
|
|
---
|
|
|
|
## PASSO 5 — Consultar metadados
|
|
|
|
### Listar categorias
|
|
|
|
```bash
|
|
curl -s -X POST "https://memoria-ia.idz.one/api/categorias/listar" \
|
|
-H 'Content-Type: application/json' \
|
|
-H "CHAVE: banana" \
|
|
-d '{}'
|
|
```
|
|
|
|
### Listar tags
|
|
|
|
```bash
|
|
curl -s -X POST "https://memoria-ia.idz.one/api/tags/listar" \
|
|
-H 'Content-Type: application/json' \
|
|
-H "CHAVE: banana" \
|
|
-d '{}'
|
|
```
|
|
|
|
### Tags mais usadas
|
|
|
|
```bash
|
|
curl -s -X POST "https://memoria-ia.idz.one/api/tags/populares" \
|
|
-H 'Content-Type: application/json' \
|
|
-H "CHAVE: banana" \
|
|
-d '{}'
|
|
```
|
|
|
|
---
|
|
|
|
## Referência rápida de rotas
|
|
|
|
| Rota | Finalidade |
|
|
|------|-----------|
|
|
| `GET /api/status` | Checar healthcheck da API da memória |
|
|
| `POST /api/busca` | Busca full-text em todas as memórias |
|
|
| `POST /api/busca/rapida` | Busca simplificada (títulos e resumos) |
|
|
| `POST /api/memorias/criar` | Criar nova memória |
|
|
| `POST /api/memorias/editar` | Editar memória existente |
|
|
| `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/memorias/mesclar` | Fundir duas memórias e inativar a origem |
|
|
| `POST /api/memorias/sinalizar` | Marcar memória como obsoleta ou que precisa de revisão |
|
|
| `POST /api/memorias/batch` | Operações em lote (criar e editar múltiplos registros) |
|
|
| `POST /api/memorias/historico` | Ver histórico de alterações de uma memória |
|
|
| `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 |
|
|
| `POST /api/contextos/listar` | Listar todos os contextos existentes |
|
|
|
|
---
|
|
|
|
## 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
|
|
|
|
---
|
|
|
|
## PASSO 7 — Operações de Manutenção e Qualidade
|
|
|
|
Para garantir a qualidade da rede de conhecimento a longo prazo:
|
|
|
|
### Sinalizar como obsoleta ou em revisão
|
|
|
|
Se uma memória não faz mais sentido ou o código mudou, sinalize-a (não exclua, a menos que seja lixo):
|
|
|
|
```bash
|
|
curl -s -X POST "https://memoria-ia.idz.one/api/memorias/sinalizar" \
|
|
-H 'Content-Type: application/json' \
|
|
-H "CHAVE: banana" \
|
|
-d '{
|
|
"codigo": 42,
|
|
"obsoleto": true,
|
|
"motivo": "Este padrão foi refatorado e substituído pelo novo helper",
|
|
"sinalizado_por": "@ag-back"
|
|
}'
|
|
```
|
|
|
|
### Mesclar memórias duplicadas
|
|
|
|
Se houver duas memórias sobre o mesmo assunto:
|
|
|
|
```bash
|
|
curl -s -X POST "https://memoria-ia.idz.one/api/memorias/mesclar" \
|
|
-H 'Content-Type: application/json' \
|
|
-H "CHAVE: banana" \
|
|
-d '{
|
|
"codigo_origem": 10,
|
|
"codigo_destino": 5,
|
|
"acao_origem": "sinalizar",
|
|
"realizado_por": "@ag-memoria"
|
|
}'
|
|
```
|
|
*(As tags e vínculos da origem irão para o destino. A origem será sinalizada ou excluída de acordo com `acao_origem`)*
|
|
|
|
### Operações em Lote (Batch)
|
|
|
|
Se precisar importar ou registrar múltiplas memórias rapidamente:
|
|
|
|
```bash
|
|
curl -s -X POST "https://memoria-ia.idz.one/api/memorias/batch" \
|
|
-H 'Content-Type: application/json' \
|
|
-H "CHAVE: banana" \
|
|
-d '{
|
|
"criar": [
|
|
{ "titulo": "Regra 1", "conteudo": "...", "resumo": "...", "categoria": "regras-negocio", "criado_por": "@ag-memoria" }
|
|
],
|
|
"editar": [
|
|
{ "codigo": 8, "tags": ["nova-tag"], "atualizado_por": "@ag-memoria" }
|
|
]
|
|
}'
|
|
```
|
|
|
|
---
|
|
|
|
## Boas práticas
|
|
|
|
1. **Buscar antes de criar** — evitar duplicatas na base
|
|
2. **Títulos pesquisáveis** — usar palavras-chave que outro agente buscaria
|
|
3. **Resumo obrigatório** — sempre preencher `resumo` com uma síntese curta e pesquisável (10-500 chars); o resumo alimenta a busca vetorial com peso B
|
|
4. **Identificar o autor** — sempre preencher `criado_por` com o handle do agente
|
|
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. **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
|
|
|
|
---
|
|
|
|
## Exemplos por agente
|
|
|
|
### @ag-back registrando uma decisão
|
|
|
|
```bash
|
|
curl -s -X POST "https://memoria-ia.idz.one/api/memorias/criar" \
|
|
-H 'Content-Type: application/json' \
|
|
-H "CHAVE: banana" \
|
|
-d '{
|
|
"titulo": "API de licenças usa paginação offset com limite 50",
|
|
"conteudo": "Endpoint POST /licencas/listar retorna no máximo 50 itens por página. Paginação via campos pagina e limite no body. Resposta inclui total para calcular páginas no front.",
|
|
"resumo": "Paginação offset com limite 50 no endpoint de licenças",
|
|
"categoria": "decisoes",
|
|
"tipo": "adr",
|
|
"tags": ["licencas", "paginacao", "api"],
|
|
"contexto": "Módulo Licenças",
|
|
"criado_por": "@ag-back"
|
|
}'
|
|
```
|
|
|
|
### @ag-testes registrando um bug conhecido
|
|
|
|
```bash
|
|
curl -s -X POST "https://memoria-ia.idz.one/api/memorias/criar" \
|
|
-H 'Content-Type: application/json' \
|
|
-H "CHAVE: banana" \
|
|
-d '{
|
|
"titulo": "Bug: timeout no upload de arquivos maiores que 10MB",
|
|
"conteudo": "O proxy nginx corta a conexão após 60s. Uploads grandes falham silenciosamente. Workaround: aumentar proxy_read_timeout para 300s no nginx.conf do servidor de produção.",
|
|
"resumo": "Timeout no upload acima de 10MB por limite do nginx. Solução: proxy_read_timeout 300s",
|
|
"categoria": "solucao-problemas",
|
|
"tipo": "solucao-problemas",
|
|
"tags": ["upload", "nginx", "timeout", "bug"],
|
|
"contexto": "Módulo Arquivos",
|
|
"criado_por": "@ag-testes"
|
|
}'
|
|
```
|
|
|
|
### @ag-front consultando padrões
|
|
|
|
```bash
|
|
curl -s -X POST "https://memoria-ia.idz.one/api/busca" \
|
|
-H 'Content-Type: application/json' \
|
|
-H "CHAVE: banana" \
|
|
-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
|
|
|
|
- [ ] Busquei na memória antes de criar? (evitar duplicatas)
|
|
- [ ] O título é claro e pesquisável?
|
|
- [ ] O resumo está preenchido e é descritivo? (obrigatório, 10-500 chars)
|
|
- [ ] A categoria está correta?
|
|
- [ ] 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?
|
|
|
|
---
|
|
|
|
## Referências
|
|
|
|
- API: `https://memoria-ia.idz.one`
|
|
- Painel Web: `https://memoria-ia.idz.one/painel`
|
|
- Rule: `global/rules/autonomia-agente`
|
|
- Skill: `global/skills/orquestrar-agentes/SKILL`
|