memoria
This commit is contained in:
parent
69f033e14c
commit
ba38329b87
13 changed files with 594 additions and 1 deletions
307
global/skills/memoria-persistente/SKILL
Normal file
307
global/skills/memoria-persistente/SKILL
Normal file
|
|
@ -0,0 +1,307 @@
|
|||
---
|
||||
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.
|
||||
|
||||
---
|
||||
|
||||
## 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", "limite": 10}'
|
||||
```
|
||||
|
||||
### Listar por módulo
|
||||
|
||||
```bash
|
||||
curl -s -X POST "https://memoria-ia.idz.one/api/memorias/listar" \
|
||||
-H 'Content-Type: application/json' \
|
||||
-H "CHAVE: banana" \
|
||||
-d '{"modulo": "licencas"}'
|
||||
```
|
||||
|
||||
### 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...",
|
||||
"categoria": "modulos",
|
||||
"tipo": "referencia",
|
||||
"tags": ["tag1", "tag2"],
|
||||
"modulo": "nome-do-modulo",
|
||||
"criado_por": "@ag-back"
|
||||
}'
|
||||
```
|
||||
|
||||
### Campos obrigatórios
|
||||
|
||||
| Campo | Descrição |
|
||||
|-------|-----------|
|
||||
| `titulo` | Nome claro e pesquisável da memória |
|
||||
| `conteudo` | Corpo completo do conhecimento |
|
||||
| `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` |
|
||||
| `tags` | Array de strings para facilitar busca |
|
||||
| `modulo` | Nome do módulo/projeto relacionado |
|
||||
|
||||
### 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 |
|
||||
|------|-----------|
|
||||
| `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/categorias/listar` | Listar categorias disponíveis |
|
||||
| `POST /api/tags/listar` | Listar todas as tags |
|
||||
| `POST /api/tags/populares` | Tags mais usadas |
|
||||
|
||||
---
|
||||
|
||||
## 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. **Identificar o autor** — sempre preencher `criado_por` com o handle do agente
|
||||
4. **Tags relevantes** — facilitar buscas futuras por contexto
|
||||
5. **Conteúdo rico** — incluir contexto, decisão, motivo e exemplos quando possível
|
||||
6. **Atualizar, não duplicar** — se a memória já existe, usar editar em vez de criar nova
|
||||
7. **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.",
|
||||
"categoria": "decisoes",
|
||||
"tipo": "adr",
|
||||
"tags": ["licencas", "paginacao", "api"],
|
||||
"modulo": "licencas",
|
||||
"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.",
|
||||
"categoria": "solucao-problemas",
|
||||
"tipo": "solucao-problemas",
|
||||
"tags": ["upload", "nginx", "timeout", "bug"],
|
||||
"modulo": "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 .
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Checklist
|
||||
|
||||
- [ ] Busquei na memória antes de criar? (evitar duplicatas)
|
||||
- [ ] O título é claro e pesquisável?
|
||||
- [ ] A categoria está correta?
|
||||
- [ ] Preenchi `criado_por` com meu handle?
|
||||
- [ ] O conteúdo tem contexto suficiente para ser útil no futuro?
|
||||
- [ ] Adicionei tags relevantes?
|
||||
|
||||
---
|
||||
|
||||
## 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`
|
||||
Loading…
Add table
Add a link
Reference in a new issue