UsageStore + runCurator — a metade da disposição

O ciclo fechado tem duas metades: o SkillStore autora memória procedural, e o curador dispõe do que fica sem uso. UsageStore é um sidecar de telemetria que conta use/view/patch de skills; runCurator é um passo determinístico que move skills de agente há muito ociosas active → stale → archived. Dois invariantes o definem: nunca deletar (archive é o estado terminal), e TEMPO é um Clock injetado — nunca Date.now(). Um CLONE do skill_usage.py + curator.py do Hermes.

O ciclo de vida

O motor de transições — a ordem dos ramos é estrutural

A decisão é uma função pura sobre uma âncora de inatividade e dois cortes. A ordem dos ramos — archive primeiro, depois stale, depois reativar — espelha o apply_automatic_transitions exatamente:

// packages/hermes/src/curator/curator.ts:123-136 — nextState
const nextState = (record, staleCutoff, archiveCutoff): SkillState => {
  const anchor = record.lastActivityAt > 0
    ? record.lastActivityAt
    : Number.POSITIVE_INFINITY;          // nunca-ativo ⇒ nunca velho
  const current = record.state;
  if (anchor <= archiveCutoff && current !== 'archived') return 'archived';
  if (anchor <= staleCutoff   && current === 'active')   return 'stale';
  if (anchor >  staleCutoff   && current === 'stale')    return 'active'; // reativa
  return current;
};

Por que archive-primeiro? Uma skill active ociosa além do corte de archive deve cair em archived diretamente — pulando stale — então o ramo de archive precisa vencer antes do ramo de stale. O teste "jumps active → archived directly when old enough (skips stale)" protege essa ordem.

Os dois portões: proveniência e pin

Antes de qualquer transição, runCurator aplica dois opt-outs ortogonais. Só skills autoradas pelo agente são geridas pelo curador, e uma skill pinned é isenta em todo caminho:

// packages/hermes/src/curator/curator.ts:86-108 (condensado)
for (const name of names) {
  const record = sidecar[name];
  if (record.createdBy !== 'agent') { skipped.push({ name, reason: 'not-agent-created' }); continue; }
  if (record.pinned)             { skipped.push({ name, reason: 'pinned' });           continue; }
  const to = nextState(record, staleCutoff, archiveCutoff);
  if (to === record.state)       { skipped.push({ name, reason: 'no-change' });        continue; }
  const persisted = await deps.usage.put(name, { ...record, state: to });
  if (!persisted.ok) return persisted;     // fail-closed: não reporta trabalho não salvo
  transitioned.push({ name, from: record.state, to });
}

Skips são reportados, não escondidos — o CuratorReport carrega tanto transitioned[] quanto skipped[] (cada um com razão tipada: pinned/not-agent-created/no-change), ambos em ordem estável de nome. E a persistência é por-transição: se um put falha, o passo aborta com aquele err em vez de reportar uma mudança de estado que não aconteceu duravelmente.

O sidecar de telemetria — leituras best-effort, escritas atômicas

UsageStore registra eventos incrementando um contador e carimbando lastActivityAt = clock(). Carrega a mesma assimetria leitura/escrita do memory store — um sidecar corrompido lê como vazio (nunca quebra um caminho quente), mas uma escrita que falha emerge como err:

// packages/hermes/src/curator/usage-store.ts:153-166 — load best-effort
private async load(): Promise<UsageSidecar> {
  const stat = await tryCatchAsync(() => this.fs.stat(this.sidecarPath));
  if (!stat.ok || !stat.value) return {};        // ausente ⇒ vazio
  const read = await tryCatchAsync(() => this.fs.readText(this.sidecarPath));
  if (!read.ok) return {};                         // erro de IO ⇒ vazio
  const parsed = tryParseJson(read.value);
  if (!parsed.ok) return {};                       // JSON ruim ⇒ vazio
  const valid = usageSidecarSchema.safeParse(parsed.value);
  if (!valid.success) return {};                   // forma errada ⇒ vazio
  return valid.data;
}

Confusões comuns