As camadas do cérebro

O "cérebro" da Apura é organizado em camadas, cada uma com uma função clara. Entender essas peças é entender o agente inteiro. Uma frase para cada:

O que fica FORA do cérebro

Nem tudo mora no cérebro que sincroniza. A linha que separa é a de sigilo e LGPD: o que viaja entre máquinas é sempre anônimo; o que identifica o cliente fica preso localmente.

Os papéis do agente

A Apura trabalha por papéis especializados — cada um é uma "mente" separada, com seu próprio contexto e manual. Um produtor cria, um revisor tenta derrubar, e nada chega ao cliente sem passar pela sua aprovação. Clique para expandir cada papel.

O que a casa sabe

A biblioteca é o conhecimento do agente — o equivalente ao "RAG" (o material que a IA consulta para trabalhar). Ela é governada por uma lei simples que decide o que pode ser guardado e compartilhado.

A lei da biblioteca

Método é da casa, dado é do cliente. Toda técnica — como fechar um mês, como categorizar uma despesa, como montar um slide — é conhecimento da Apura: fica guardado, é compartilhado e vale para todos. Já número específico, extrato, nome real, CNPJ — isso é do cliente: é confidencial, não sobe para o cérebro, e é lido "fresco" na hora do trabalho.

Nas palavras do Admin: "todo fechamento é o mesmo processo, só muda de onde vem a base de dados." O processo é da casa; o que muda de cliente para cliente é só o "delta", que fica na pasta do cliente.

As 4 estantes

A biblioteca é uma só — as estantes só organizam fisicamente, para achar e carregar mais fácil. Qualquer papel pode ler qualquer estante.

Como conhecimento novo entra

Nada entra direto. Todo conhecimento novo passa por uma quarentena com aprovação — é a defesa contra o cérebro se corromper sozinho.

Regra que acompanha: consolidar não é apagar. Conhecimento nunca é deletado; quando uma nota "vence", ela perde o selo de certificada e volta para a quarentena até ser revalidada — mas não some.

Por que essa arquitetura é a certa

Em julho de 2026, o pesquisador checou esse desenho contra o estado da arte (documentação da Anthropic, pesquisas acadêmicas, padrões de segurança). Veredito: sólido, só pequenos ajustes de calibragem. Os pilares confirmados:

• Biblioteca maior que o agente: carregar um manual curto + consultar o método na hora é o recomendado. Copiar o mesmo texto em vários manuais é o erro clássico que causa contradição.
• Carregar só o necessário: o contexto da IA é finito e piora quando entulhado. Guardar atalhos leves e abrir o conteúdo em tempo real é o certo.
• Compartilhar método não enviesa: o que estraga a independência do revisor é ele ver o raciocínio do produtor — não o método comum. Por isso: método compartilhado, recompute em sessão separada, humano no fim.
• Quarentena + aprovação: é a defesa canônica contra "envenenamento da memória" — o risco real não é um atacante externo, é a auto-corrupção. O gate humano da Apura é até mais forte que o padrão da indústria.

Como a casa aprende

O que separa a Apura de "um chatbot" é o flywheel — a roda que ganha impulso: cada ciclo deixa a casa um pouco melhor, de forma permanente. Não é acumular anotações soltas; é compor melhoria.

Aprendizado × Biblioteca

Dataset e treino do futuro

Toda categorização validada vira um "par" (lançamento → categoria certa) num arquivo de dataset. É uma coleção de gabaritos provados pelo Admin. Hoje orienta o agente; no futuro (V2), é o material com que se treina um modelo próprio e barato — o moat. Treinar modelo próprio é coisa de amanhã; o autoaprimoramento de hoje é por memória (texto e arquivos), sem mexer nos pesos do modelo.

Evals — o freio anti-regressão

Um "eval" é um caso de teste com gabarito conhecido. Antes de mudar uma regra importante, o agente re-testa os casos: se algum regride (passa a errar o que já acertava), a mudança não entra. Há duas suítes: regression (casos que já acerta — tem que ficar perto de 100% para aprovar qualquer mudança) e capability (casos difíceis que medem progresso).

As rotinas de manutenção

• Consolidação: periodicamente, um agente de contexto limpo varre o cérebro atrás de duplicatas e contradições, propõe merges e arquiva o log destilado — sempre com aprovação.
• Validar a quarentena: esvazia o _Inbox — promove o que é verificável, saneia dados pessoais, escala ao Admin só o essencial.
• Debriefing de ciclo: consolida o aprendizado por ciclo — o feedback do Admin, a reunião com o cliente, a telemetria — separando o geral do específico.

O painel de saúde

É a primeira coisa que o agente checa ao abrir trabalho. Existe porque o flywheel já parou em silêncio duas vezes (9 dias, depois ~20 dias) — porque dependia de alguém lembrar. O painel torna todo vencimento visível e obrigatório de reportar: qualquer item vermelho vira aviso ao Admin antes da tarefa. Ele vigia a consolidação, a validação da quarentena, os evals, o dataset, a auditoria de segurança, o radar de números e o backup do cofre.

Mesa × Conselho

As regras e quem aprova

A Apura tem uma hierarquia de regras clara, do inviolável ao pessoal. A regra específica detalha a geral, nunca a contradiz — e em conflito, o nível mais alto sempre vence.

Gates — onde o humano aprova

Um gate é um ponto de parada obrigatório onde o Admin precisa aprovar. Os principais:

• Entregável ao cliente: todo material passa pelo revisor e para no gate do Admin. Nada é enviado sem isso — é a linha que protege a marca.
• Gate de entrada: num pedido ambíguo, o agente devolve um brief curto e espera OK antes de executar. Tarefa trivial e reversível é feita direto.
• Promover aprendizado: conhecimento auto-gerado só vira verdade com aval humano.
• Subir uma versão: PR → aprovação → merge → tag. Em versão MAJOR, gate reforçado.

Versionamento

A Apura é um sistema que evolui — as versões se sucedem, não convivem. O número diz o quão evoluído o sistema está, e independe de qual modelo Claude roda por baixo. Cada versão é uma tag no git (recuperável em minutos). MAJOR muda arquitetura ou comportamento profundo (ritual completo: backup + testes + gate). MINOR é capacidade ou regra nova. Patch é correção pequena.

Produção × desenvolvimento

O agente opera em dois modos, e a fronteira é o branch do git. Produção (main) é onde se atende o cliente — aqui não se mexe no sistema. Desenvolvimento (dev/*) é a oficina onde se mexe no próprio sistema — aqui não se atende cliente. A regra de ouro: "quem está em dev não atende; quem atende não desenvolve." Entrar em dev exige a chave de administrador.

A régua de decisão: o treinador propõe a mudança (no debrief ou na mesa); o gate — o Admin — aprova. Quem produz nunca é quem aprova.

Como a casa se protege

Segurança na Apura não é um aviso no manual — é estrutura: proibições duras, anonimização por desenho, uma chave à prova de forja, e verificações automáticas que rodam sozinhas em toda sessão.

Os NUNCA

• Nome real ou dado pessoal no cérebro, nunca. Nada de pessoa, CNPJ, banco/conta real. Um "guarda-PII" avisa quando algo do tipo aparece.
• Entregável ao cliente sem revisor + gate, nunca.
• Número sem origem não se escreve.
• Segredo em chat, documento ou repositório, nunca. O segredo nasce direto no destino (arquivo local ou 1Password). Colar no chat "queima" o segredo.
• Escrever no OneDrive da Base, nunca (é zona só de leitura).
• Trabalhar sem o carimbo de papel+modelo, ou um papel agir sem ter lido o próprio manual = erro.

Codinome — a regra de ouro da LGPD

O codinome (Cliente-A, Cliente-B…) é a chave em todos os documentos e tabelas. Zero nome real, zero CNPJ, zero conta real — até as contas são genéricas (corrente-1). O cérebro sincroniza entre máquinas, então só pode conter codinome. O cofre — a tabela que liga codinome ao nome real — nunca sobe: fica só local. O que viaja é anônimo; o que revela quem é o cliente fica preso na máquina.

A chave de administrador (anti-forja)

Como o sistema sabe que quem manda mexer é autorizado? Não pela identidade declarada (dizer "sou o Admin" no git é só uma assinatura, e assinatura se forja). A autoridade vem da credencial provada: o sistema testa se a máquina realmente acessa o repositório privado.

As verificações automáticas (hooks)

Um roteiro dispara sozinho no começo de toda sessão e injeta as regras + checagens no contexto, mesmo que ninguém leia manual. Ele:

• Reforça o carimbo obrigatório e o Princípio Zero.
• Lê o painel de saúde e avisa o que está vencido, antes da tarefa.
• Confere se o motor está sincronizado (senão manda dar git pull antes de qualquer fechamento).
• Valida o modo dev e a chave (a checagem anti-forja).
• Verifica a idade do backup do cofre (local e no Drive) e manda renovar se envelheceu.
• Avisa quando um arquivo de aprendizado passou do teto e precisa ser arquivado.
• Repete os NUNCA no fim, como lembrete fixo.

Backups — onde mora a recuperação

Onde os números e o código vivem

A Apura separa fisicamente o que sincroniza (sempre anônimo) do que identifica o cliente (preso local). São quatro "caixas", cada uma com um papel.

O radar (Supabase)

É um banco de dados na nuvem — projeto próprio da Apura, região Brasil, isolado do projeto do cliente — onde os números ficam consultáveis. Em vez de abrir uma planilha de 26 MB, confere-se um número com uma consulta rápida. Quem manda continua sendo a planilha e o motor; o Supabase espelha o resultado para consulta.

• Entrada: cada transação vira uma linha, sem duplicar (por hash). (em construção)
• Saída: os números já fechados — é o que se consulta. (já funciona)
• Ele se defende sozinho: trava de acesso ligada, só aceita codinome no padrão Cliente-…, um gatilho barra CPF/CNPJ em descrição, e mês fechado vira imutável.
• Benchmark entre clientes é proibido por consulta solta — só sai de uma camada dedicada, com amostra mínima. Nenhum dado real de pessoa entra ali.

As quatro caixas

Como pedir — e o que roda por baixo

Você fala com a Apura em linguagem natural. Não há comando decorado a aprender: o orquestrador entende o pedido e chama o papel certo. Para as tarefas recorrentes, existem "comandos salvos" — receitas fixas que rodam sempre igual, nunca de memória.

Comandos salvos (os rituais)

Quando você diz uma destas frases, o agente roda um roteiro versionado — a garantia de que o passo a passo é sempre o mesmo, não improvisado.

A caixa de ferramentas

Para não errar conta e não reinventar a roda, a Apura tem um toolbox — ferramentas testadas que os papéis usam em vez de escrever um script novo toda vez. A regra: antes de escrever qualquer script, consulta o índice — a ferramenta provavelmente já existe. As principais:

Cada ferramenta nasce de um caso real e passa pelo revisor de engenharia antes de virar oficial.

Os termos, em uma linha

Um dicionário rápido dos termos que aparecem neste manual, para leigos.

Apura · Manual do agente · versão 2.3 · documento interno da Base · pt-BR.