O loop fechado auto-evolutivo

A Lição 3 nomeou o ciclo de aprendizado como a pedra angular da fusão. Aqui está como ele realmente é entregue: três subsistemas — memory, learning, curator — que juntos deixam uma run finalizada tornar a próxima mais esperta, sem nunca auto-escrever uma lição não validada na memória durável.

01 · Três partes, um loop

Antes do código, o modelo mental. "Auto-evolutivo" soa mágico, mas é um circuito de três peças concretas. Pense numa oficina que melhora entre turnos: ela trabalha com o caderno de notas do jeito que estava ao abrir de manhã (memory), no fim do dia um revisor propõe anotações novas e um inspetor decide quais entram (learning), e periodicamente alguém arruma a estante de ferramentas — sem jogar nada fora (curator). A oficina de amanhã abre com o caderno mais rico.

02 · Memory — o snapshot congelado

Dois stores limitados, em arquivo, persistem entre sessões: MEMORY.md (as próprias notas do agente) e USER.md (o que ele sabe sobre o usuário). Ambos são injetados no system prompt como um snapshot congelado no início da sessão. A analogia: é uma fotografia do caderno tirada quando a sessão abre. Você pode escrever no caderno durante o dia (e a tinta seca de verdade, no disco), mas a fotografia colada na parede não muda até você tirar uma nova — amanhã.

Por que congelar? O cache de prompt

Parece estranho não atualizar o snapshot na hora. A razão é puramente de engenharia, e vale entender:

Modelos cacheiam o prefixo do prompt: se o começo não muda, a parte cara já está computada. Se cada escrita reescrevesse o snapshot, o prefixo mudaria e o cache esquentaria do zero a cada nota. Por isso a disciplina:

• Escritas no meio da sessão vão para o disco imediatamente (duráveis) mas não mudam o snapshot — então o cache de prefixo de prompt fica quente a sessão inteira.
• O snapshot só se atualiza no próximo início de sessão (um load novo). É isso que torna "a próxima run é mais esperta" literal.
• Trazido da fonte do Hermes exatamente: uma op memory com ação ∈ {add, replace, remove}; replace/remove localizam o alvo por uma substring curta e única (sem IDs); entradas são delimitadas por § em sua própria linha; limites em caracteres, não tokens (independente do modelo).

// packages/hermes/src/memory/memory-store.ts:50-57
export const ENTRY_DELIMITER = '\n§\n';
/** Limite de caracteres padrão para o store MEMORY.md (padrão do Hermes). */
export const DEFAULT_MEMORY_CHAR_LIMIT = 2200;
/** Limite de caracteres padrão para o store USER.md (padrão do Hermes). */
export const DEFAULT_USER_CHAR_LIMIT = 1375;

Este subsistema é um CLONE fiel de tools/memory_tool.py (1089 LOC). Os desvios são deliberados: IO é injetado via FsPort, e toda op falível retorna Result<T,Error> em vez de um dict Python. O mergulho completo no MemoryStore é a Lição 07.

Dois stores, dois limites

São dois arquivos distintos, com tetos de caracteres distintos — porque servem a propósitos distintos. As notas do agente cabem mais (2200); o que ele sabe do usuário é mais enxuto (1375):

A anatomia de uma op de memória

A op memory tem três ações, e o detalhe que importa: replace/remove acham o alvo por uma substring curta e única — sem IDs. As entradas ficam separadas por § numa linha própria:

03 · A escolha de design mais importante (ADR-0018)

Em uma frase: propor ≠ dispor. Quem sugere uma lição (o revisor) não é quem decide se ela entra (o Validador). Em quase todo o resto a fusão clona o Hermes "quase literalmente"; aqui ela diverge de propósito. Por que a mudança? Duas razões do ADR, ambas fundamentadas:

• Não há AIAgent em Python no Alembic para forkar como thread daemon — um passo síncrono pós-unidade sobre portas injetadas é a unidade certa, e compõe com o harness.
• Mais importante, auto-escrever burlaria o Validator Gate e deixaria lições não validadas endurecerem na memória durável — exatamente o modo de falha que a ADR-0006 existe para prevenir ("nada sedimenta sem passar um piso de qualidade").

Então o ciclo são três portas injetadas e um kernel. As portas são as "tomadas" onde produção e teste plugam implementações diferentes — exatamente o padrão de injeção da Lição 05:

04 · O kernel reviewAndLearn

Aqui está o coração do learning — pequeno de propósito. Leia primeiro o fluxo de cada proposta, depois o código exato. A regra de ouro: tudo que pode falhar de verdade falha fechado (para o passo inteiro), mas uma rejeição normal não é falha — é um resultado esperado que vai para um balde.

// packages/hermes/src/learning/review.ts:54-69 — o kernel
export const reviewAndLearn = async (summary, deps) => {
  if (summary.trim().length === 0) return ok(emptyOutcome());   // "Nada a salvar."
  const proposed = await deps.proposer(summary);
  if (!proposed.ok) return proposed;                          // erro do proposer → falha fechada
  if (proposed.value.length === 0) return ok(emptyOutcome());
  const acc = { applied: [], rejected: [], failed: [] };
  for (const raw of proposed.value) {
    const stepErr = await processOne(raw, deps, acc);   // validar → portão → aplicar
    if (stepErr) return stepErr;                            // erro do portão → falha fechada
  }
  return ok({ applied: acc.applied, rejected: acc.rejected, failed: acc.failed });
};

Três baldes de resultado — applied / rejected / failed — então nada é descartado em silêncio. A saída do proposer é validada por Zod na fronteira (é saída de modelo não confiável em produção). Um erro de proposer ou portão falha o passo inteiro fechado; uma rejeição do store a uma escrita aprovada é registrada em failed, nunca lançada.

Rejeição (dado) ≠ erro (falha)

A distinção que confunde mais gente: uma proposta reprovada não é uma falha. Reprovar é resultado esperado e vem como ok(...); só uma quebra real (proposer ou portão estourando) vira err(...) e fecha o passo. Veja os dois mundos lado a lado:

05 · O portão e o piso de 0.7

O portão padrão é deliberadamente simples — um check puro de score. "Com portão" não quer dizer "humano no loop"; quer dizer "tem que passar um piso de qualidade". O piso padrão é 0.7:

// packages/hermes/src/learning/gate.ts:24-36 — o portão conservador padrão
export const scoreThresholdGate = (min = DEFAULT_REVIEW_SCORE_THRESHOLD) => {
  return async (proposal) => {
    const approved = proposal.score >= min;          // limite inclusivo: score === min aprova
    const reason = approved
      ? `score ${proposal.score} ≥ threshold ${min}`
      : `score ${proposal.score} < threshold ${min} (learn only from validated wins)`;
    return ok({ approved, reason });                  // puro + total: ok(verdict) para toda entrada
  };
};

O limite padrão é 0.7 — a codificação mecânica da regra do hermes-mini-loop "aprender só com vitórias validadas". Note que a decisão vive em verdict.approved, não no Result: uma rejeição é um ok(...) normal, não um erro.

A escala de score, lado a lado com o piso

Veja onde o piso corta. Tudo de 0.7 pra cima aprova (verde); abaixo, rejeita (clay) — e rejeitar é normal, não erro:

06 · Siga uma proposta de ponta a ponta (passo a passo → agora você)

Você viu o fluxograma e o código. Agora rode-os na mão com um exemplo concreto, devagar — depois um caso é seu. Recuperar o procedimento (não só ver o veredito pronto) é o que fixa.

07 · Com portão vs auto-aplicar — a opção rejeitada de propósito

A ADR-0018 não escolheu "com portão" por inércia: ela considerou e rejeitou a alternativa óbvia — auto-aplicar (o comportamento literal do Hermes). Veja os dois caminhos lado a lado. Repare onde o caminho de cima contorna o gate, e por que isso é justamente o que a ADR-0006 proíbe:

08 · Curator — a metade do descarte

Memory e learning são a metade que acumula. O curador é a metade que mantém limpo. O agente cria skills; telemetria de uso se acumula; o curador é o passo determinístico que arruma a biblioteca. É um CLONE fiel de agent/curator.py:apply_automatic_transitions, com quatro regras clonadas exatamente:

• Portão de proveniência: apenas skills createdBy === 'agent' são tocadas; o resto é pulado.
• Isenção de pin: uma skill pinned nunca é transicionada, em nenhum caminho.
• Nunca deletar: o estado terminal é archived — "ação máxima = arquivar". Não há remoção.
• As quatro transições: active/stale além do corte de arquivamento → archived; active além do corte de stale → stale; uma skill stale usada de novo → reativada para active.

O tempo é um Clock injetado — nunca Date.now() (a regra de determinismo do motor, e o que torna os testes de transição reprodutíveis). O curador é o mesmo Clock com que o usage store foi construído, então um evento registrado "agora" e uma transição decidida "agora" concordam.

As guardas, antes das transições

Antes de decidir qualquer transição, o curador filtra. Duas guardas eliminam a maioria das skills sem nem olhar para datas — é o que impede o curador de mexer no que não é dele:

A máquina de estados

Passadas as guardas, restam quatro transições entre três estados. Repare: não há nenhuma seta saindo para "deletado" — o estado terminal é archived, e uma skill stale pode voltar para active se for usada de novo:

O mergulho completo no UsageStore + curador (a telemetria que alimenta as datas) é a Lição 09.

09 · O ciclo de vida, acumular vs descartar (lado a lado)

As duas metades do loop fechado seguem a mesma filosofia conservadora, mas em direções opostas. Veja-as na mesma tabela — uma sedimenta conhecimento sob portão; a outra poda skills sem nunca apagar:

10 · Como isso se encaixa

Você dissecou o loop por dentro. Agora dê um passo atrás: onde ele liga no resto da máquina? O loop fechado não é um apêndice — é o que acontece depois que uma run termina e antes que a próxima comece. Ele se pluga na ponta de saída do pipeline (uma run finalizada, já passada pelos gates) e alimenta a ponta de entrada da run seguinte (o snapshot de memória mais rico).

Onde você está na metodologia: as Lições 01–03 montaram o motor, a engenharia reversa do Hermes e a matriz de fusão; as Lições 14–19 detalham a cintura estreita, o funil, os gates, o Council e o swarm que executam uma run. Esta Lição 04 é a peça que fecha o circuito por cima de tudo isso — ela transforma o resultado de uma run executada (sob os gates) no combustível da próxima. Para ver as 30 peças no mesmo mapa e como cada uma liga na seguinte, abra o mapa interativo da metodologia (ou volte ao hub do curso).

11 · Na prática

Chega de diagrama — eis o loop como comandos reais. O passe de aprendizado é opt-in: uma run normal não aprende. Você liga a peça desta lição com a flag --learn numa run com escopo (ADR-0018). O passe roda depois que os gates passam, e é não-fatal — se ele falhar, a run verde continua verde.

# Liga o passe de aprendizado pós-run (opt-in, ADR-0018).
# --offline mantém tudo hermético e $0 (adapter offline determinístico).
alembic run --goal GOAL.md --plan alembic.plan.ts --learn --offline --yes

# … a run executa as units e passa os gates como sempre …
# então, no fim, o passe de aprendizado roda e imprime UMA linha:
#   learning gate: 1 applied, 1 rejected
# (evento de log: run:learning-pass-done { applied:1, rejected:1, failed:0 })
# as escritas APROVADAS sedimentam no MEMORY.md / USER.md do dir da run.

Fonte da forma exata: apps/cli/src/index.ts:117 (a flag) e apps/cli/src/commands.ts:1364-1390 — o passe só roda sob --learn, dispõe pelo gate do Validador (gate:{kind:'validator'}) e escreve learning gate: N applied, M rejected. Sem --learn, nada disso acontece: o comportamento da run é idêntico ao de antes.

E para inspecionar a memória multi-store que o agente acumula (episódica, semântica, procedural, de decisão, de transcrição), o comando é alembic memory. Liste um substore para ver o que já sedimentou:

# Lista os registros de um substore (newest-first), com filtros opcionais.
alembic memory decision list --limit 3

# saída (uma linha de cabeçalho + uma por registro):
#   memory decision: 2 record(s) under .alembic/memory/decision.jsonl
#     dec-01J… [agent cli] at 2026-06-27T16:00:00.000Z
#     dec-01J… [agent cli] at 2026-06-27T15:58:00.000Z

Fonte: apps/cli/src/commands.ts (runMemory) — list imprime memory <substore>: N record(s) under <path> e uma linha <id> [agent <agente>] at <timestamp> por registro; os substores são episodic | semantic | procedural | decision | transcript (CLAUDE.md). Atenção à camada: este alembic memory é o store multi-substore append-only em JSONL; é parente — não idêntico — ao MEMORY.md/USER.md de snapshot da seção 02, que é o store que o --learn sedimenta. Os dois são memória, em granularidades diferentes.

Fixe os conceitos (flashcards)

Clique pra virar. Tente lembrar a resposta antes de virar — recuperação ativa fixa mais que reler.