.agent/global/skills/memoria-persistente/SKILL

---
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", "modulo": "licencas", "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"],
    "modulo": "nome-do-modulo",
    "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 |
| `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. **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. **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"],
    "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.",
    "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"],
    "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?
- [ ] 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?

---

## 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`