memoria

2026-06-22 22:51:41 -03:00 · 2026-06-22 22:51:41 -03:00 · ba38329b87
commit ba38329b87
parent 69f033e14c
13 changed files with 594 additions and 1 deletions
--- a/global/rules/usar-memoria-persistente
+++ b/global/rules/usar-memoria-persistente
@ -0,0 +1,73 @@
+---
+type: rule
+name: usar-memoria-persistente
+description: Todo agente deve consultar e registrar conhecimento persistente na Memória Azteca sempre que relevante
+scope: global
+trigger: always_on
+priority: media
+updatedAt: "2026-06-22"
+---
+
+# Regra: Usar Memória Persistente
+
+## Contexto
+
+O ecossistema Azteca possui uma memória centralizada em `https://memoria-ia.idz.one` acessível por todos os agentes via API REST. Informações descobertas durante o trabalho se perdem entre sessões se não forem registradas.
+
+## Quando consultar a memória
+
+O agente **deve** buscar na memória antes de:
+
+- Tomar decisões arquiteturais (verificar se já existe ADR sobre o tema)
+- Resolver um bug (verificar se já existe solução documentada)
+- Implementar um padrão novo (verificar se já existe padrão definido)
+- Trabalhar em módulo que não conhece (buscar contexto do módulo)
+
+```bash
+curl -s -X POST "https://memoria-ia.idz.one/api/busca" \
+  -H 'Content-Type: application/json' \
+  -H "CHAVE: banana" \
+  -d '{"termo": "PALAVRA_CHAVE"}' | jq .
+```
+
+## Quando registrar na memória
+
+O agente **deve** salvar na memória quando:
+
+- Toma uma decisão arquitetural significativa
+- Descobre e resolve um bug não trivial
+- Define ou altera um padrão técnico
+- Descobre uma regra de negócio nova
+- Encontra um workaround para problema de infraestrutura
+- Qualquer conhecimento que beneficiaria sessões futuras
+
+## Como registrar
+
+Usar a skill `global/skills/memoria-persistente/SKILL` para o protocolo completo.
+
+**Mínimo obrigatório:**
+
+```bash
+curl -s -X POST "https://memoria-ia.idz.one/api/memorias/criar" \
+  -H 'Content-Type: application/json' \
+  -H "CHAVE: banana" \
+  -d '{
+    "titulo": "Descrição clara e pesquisável",
+    "conteudo": "Detalhes completos com contexto",
+    "categoria": "CATEGORIA",
+    "criado_por": "@HANDLE_DO_AGENTE"
+  }'
+```
+
+## Regra de ouro
+
+> Se a informação seria útil para outro agente ou para a mesma tarefa daqui 1 semana — **salve na memória**.
+
+## 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.
+
+## Referências
+
+- Skill: `global/skills/memoria-persistente/SKILL`
+- API: `https://memoria-ia.idz.one`
--- a/global/skills/memoria-persistente/SKILL
+++ b/global/skills/memoria-persistente/SKILL
@ -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`