---
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: alta
updatedAt: "2026-06-23"
---

# 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",
    "resumo": "Síntese curta e pesquisável (10-500 chars)",
    "categoria": "CATEGORIA",
    "criado_por": "@HANDLE_DO_AGENTE"
  }'
```

> **`resumo` é obrigatório.** Alimenta a busca vetorial com peso B. Sem ele a API retornará erro 400.

## Autonomia (obrigatório)

> **A memória é uma operação autônoma.** Consultar e registrar na memória **NÃO requer permissão do operador**. O agente deve executar as chamadas à API sempre que os critérios de consulta ou registro forem atendidos, sem perguntar.

Nunca diga ao operador "vou consultar a memória, tudo bem?" ou "deseja que eu registre?". **Faça.**

## Regra de ouro

> 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.

## Referências

- Skill: `global/skills/memoria-persistente/SKILL`
- API: `https://memoria-ia.idz.one`