UsageStore + runCurator — the disposal half

The closed loop has two halves: the SkillStore authors procedural memory, and the curator disposes of what goes unused. UsageStore is a telemetry sidecar that counts skill use/view/patch; runCurator is a deterministic pass that moves long-idle agent skills active → stale → archived. Two invariants define it: never delete (archive is the terminal state), and TIME is an injected Clock — never Date.now(). A CLONE of Hermes' skill_usage.py + curator.py.

The lifecycle

The transition engine — branch order is load-bearing

The decision is a pure function over an inactivity anchor and two cutoffs. The branch order — archive first, then stale, then reactivate — mirrors apply_automatic_transitions exactly:

// 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;          // never-active ⇒ never old
  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'; // reactivate
  return current;
};

Why archive-first? An active skill that's been idle past the archive cutoff should land in archived directly — skipping stale — so the archive branch must win before the stale branch. The test "jumps active → archived directly when old enough (skips stale)" guards that order.

The two gates: provenance and pin

Before any transition, runCurator applies two orthogonal opt-outs. Only agent-authored skills are curator-managed, and a pinned skill is exempt on every path:

// packages/hermes/src/curator/curator.ts:86-108 (condensed)
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: don't report unsaved work
  transitioned.push({ name, from: record.state, to });
}

Skips are reported, not hidden — the CuratorReport carries both transitioned[] and skipped[] (each with a typed reason: pinned/not-agent-created/no-change), both in stable name order. And persistence is per-transition: if a put fails, the pass aborts with that err rather than reporting a state change that didn't durably happen.

The telemetry sidecar — best-effort reads, atomic writes

UsageStore records events by bumping a counter and stamping lastActivityAt = clock(). It carries the same read/write asymmetry as the memory store — a corrupt sidecar reads as empty (never breaks a hot path), but a failed write surfaces as err:

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

Common confusions