KB References

A KB (Knowledge Base) do Simplafy Admin centraliza conhecimento operacional, arquitetural e de runbooks consumido por humanos e por coding agents via MCP. Cada entrada é uma reference — um documento curto, versionado, com metadados ricos e busca semântica habilitada por embeddings.

A KB serve como camada compartilhada entre simplafy-hub, simplafy-saude, simplafy-seguros, simplafy-infra e o próprio simplafy-admin. Refs são acessadas pela API REST (/api/references/*) e pelas tools MCP (create_reference, get_reference, search_semantic, etc.).

O que é uma reference

Uma reference é um registro na tabela Reference com slug único, conteúdo Markdown e metadados estruturados. O schema operacional é:

Criar uma reference

curl -X POST https://admin.simplafy.com.br/api/references \
  -H "Content-Type: application/json" \
  -H "x-agent-id: claude-code" \
  --cookie "next-auth.session-token=..." \
  -d '{
    "module": "HUB",
    "title": "Padrao de reconnect AMQP no agent worker",
    "content": "# Reconnect AMQP\n\nUsar aio_pika.connect_robust...",
    "category": "messaging",
    "criticality": "WARNING",
    "tags": ["rabbitmq", "agent-worker"],
    "type": "gotcha"
  }'

O x-agent-id é gravado no campo updatedBy para trilha de auditoria. Se ausente, cai no session.user.id.

Categorias e criticality

Módulos

O enum RefModule define a quem a ref pertence:

Criticality

Criticality afeta ordenação default em list_references e search_references (críticas primeiro):

Listar com filtros

GET /api/references?module=HUB&criticality=CRITICAL&tags=agents,rabbitmq

Parâmetros aceitos:

• module — RefModule
• category — string
• criticality — Criticality
• tags — CSV de tags

Response: { success: true, data: Reference[], meta: { total } }.

Semantic search (pgvector)

A busca semântica usa embeddings text-embedding-3-small da OpenAI armazenados em coluna vector (pgvector) com índice IVFFlat e operador <=> (cosine distance).

Endpoint REST

GET /api/references/search?q=como+lidar+com+reconnect+amqp&module=HUB

Esse endpoint usa busca textual (Prisma contains em title, content, category + tags has). Para busca semântica real, use a tool MCP.

Tool MCP search_semantic

{
  "tool": "search_semantic",
  "args": {
    "query": "como evitar deadlock em worker aio_pika",
    "module": "HUB",
    "top_k": 10
  }
}

Fluxo interno:

Response shape:

{
  "result": {
    "references": [
      {
        "id": "...",
        "slug": "reconnect-amqp-worker-abc12",
        "title": "Padrao de reconnect AMQP no agent worker",
        "module": "HUB",
        "category": "messaging",
        "criticality": "WARNING",
        "tags": ["rabbitmq", "agent-worker"],
        "cosine_similarity": 0.8421,
        "updatedAt": "2026-05-20T12:00:00Z"
      }
    ],
    "total": 1,
    "top_k": 10,
    "fallback": false,
    "duration_ms": 187
  }
}

Geração de embeddings

Ao criar ou atualizar uma reference, o serviço enfileira enqueueEmbedReference(ref.id) (fire-and-forget). O worker chama OpenAI e popula a coluna embedding. Refs sem embedding não aparecem em search_semantic até serem processadas — mas continuam visíveis em list_references e na busca textual.

Verificação periódica

Toda reference tem um campo verifyByDate que define quando ela precisa ser revisada por um humano ou agent. Default ao criar: now + 30 dias.

Endpoint REST

PATCH /api/references/{id}/verify

Atualiza lastVerified = now, verifyByDate = now + 30 dias e updatedBy = x-agent-id ?? session.user.id.

Tool MCP verify_reference

{
  "tool": "verify_reference",
  "args": { "slug": "reconnect-amqp-worker-abc12" }
}

Aceita id ou slug. Requer scope admin:kb:write.

Quando re-verificar

• Após mudança relacionada em produção que afete o conteúdo da ref.
• Quando a ref aparece em search_stale_references (ver abaixo).
• Antes de promover uma ref de INFO para WARNING ou CRITICAL.

Stale references

Refs vencidas ou não verificadas em N dias são consideradas stale e devem ser priorizadas para revisão.

Tool MCP search_stale_references

{
  "tool": "search_stale_references",
  "args": {
    "olderThanDays": 30,
    "module": "HUB",
    "limit": 50
  }
}

Critério de stale (OR):

• verifyByDate < now — vencida.
• verifyByDate == null AND updatedAt < (now - olderThanDays dias) — sem prazo definido e parada há tempos.

Filtros opcionais:

• module — RefModule.
• olderThanDays — 1 a 365, default 30.
• limit — 1 a 100, default 50.

Ordenação: criticality ASC (críticas primeiro), depois verifyByDate ASC (mais vencidas primeiro).

Response inclui campos derivados úteis para triagem:

{
  "result": {
    "staleRefs": [
      {
        "id": "...",
        "slug": "...",
        "title": "...",
        "module": "HUB",
        "criticality": "CRITICAL",
        "lastVerified": "2026-02-10T...",
        "verifyByDate": "2026-03-12T...",
        "accessCount": 47,
        "lastAccessedAt": "2026-05-25T...",
        "updatedAt": "2026-02-10T...",
        "daysSinceUpdate": 108,
        "daysSinceVerify": 108
      }
    ],
    "total": 1
  }
}

Workflow recomendado de triagem