Curator Daemon: Managing the Birth, Aging, and Death of Hermes Agent Skills

Problem Root: Why the Skill Library Decays

The skill library inevitably accumulates entropy for three reasons: (1) creation scope is local, so similar experiences are repeatedly turned into slightly different skills; (2) there is no natural decay mechanism for automatically generated skills; (3) skills become outdated as the runtime environment evolves (e.g., Node.js 18 vs Node.js 22 or OpenAI API v1 vs v2). These factors turn the library into a "trash bin" that slows agent startup and raises token costs.

Curator Identity: An Agent Inside an Agent

Curator is not a separate process or cron job; it is a lightweight AI agent forked from the main Agent, inheriting the provider, model, and system‑prompt cache while restricting tool permissions.

DEFAULT_INTERVAL_HOURS   = 24 * 7  # run every 7 days
DEFAULT_MIN_IDLE_HOURS   = 2      # trigger only after 2 idle hours
DEFAULT_STALE_AFTER_DAYS = 30     # 30 days unused → stale
DEFAULT_ARCHIVE_AFTER_DAYS = 90   # 90 days unused → archived

Its tool whitelist includes only three categories: skills_list, skill_view – browse existing skills skill_manage (patch/edit/delete) – modify or delete skills skill_usage – read usage statistics

Curator cannot create new skills, run terminals, or access the network; it is deliberately designed as a "librarian" rather than a builder.

Skill Lifecycle State Machine: Three‑State Conversion

Each skill has a sidecar file skill_usage.json that records usage metadata. The state machine progresses from active → stale → archived based on time thresholds, with the ability to revert to active if the skill is used again or manually unarchived.

active ──(30 days unused)──▶ stale ──(90 days unused)──▶ archived
  ▲                                 │
  └───(re‑used)─────────────────────┘
  ▲
  └───(user unarchive)───────────────────────────────────────┘

Example sidecar JSON:

{
    "use_count": 12,
    "last_used": "2026-01-15",
    "created_at": "2025-11-01",
    "patch_count": 3,
    "agent_created": true,
    "pinned": false,
    "lifecycle_state": "active"
}

Archive Mechanism: archive ≠ delete

When Curator archives a skill, it moves the directory to .archive instead of permanently deleting it. The archive_skill function creates the archive folder, avoids overwriting by timestamping duplicates, moves the skill, and records the reason.

def archive_skill(skill_dir: Path, reason: str) -> Path:
    archive_root = SKILLS_DIR / ".archive"
    archive_root.mkdir(exist_ok=True)
    target = archive_root / skill_dir.name
    if target.exists():
        ts = datetime.now().strftime("%Y%m%d_%H%M%S")
        target = archive_root / f"{skill_dir.name}.{ts}"
    shutil.move(str(skill_dir), str(target))
    _write_archive_record(target, reason=reason, archived_at=datetime.now())
    return target

Archived skills are ignored by skills_list, do not appear in the system prompt, but remain on disk for possible recovery via hermes curator unarchive or pinning with hermes curator pin.

Ownership Distinction: agent‑created vs user‑created

When a skill is created, Hermes tags its provenance. If the creation occurs inside a Background Review fork, the flag agent_created = True is set; otherwise the skill is considered user‑created.

if action == "create":
    if is_background_review():
        mark_agent_created(name)   # agent‑created
    # else: user‑created (default)

Curator only automatically archives agent‑created skills, never touching user‑created ones, preventing accidental loss of manually crafted assets. The pinned flag provides an explicit manual safeguard.

Common Pitfalls

Curator runs but has no effect : usually because min_idle_hours (<2 h) or the 7‑day interval has not been satisfied. Use hermes curator status to inspect and hermes curator run --force to bypass checks.

Incorrect merge : LLM‑driven merge can mis‑classify skills. Recover by locating the skill in ~/.hermes/skills/.archive/, then hermes curator unarchive <skill> and optionally hermes curator pin <skill>.

Valuable auto‑generated skill gets archived : pin the skill with hermes curator pin <skill>, which sets pinned: true and blocks deletion.

Configuration changes not taking effect immediately : Curator reads ~/.hermes/config.yaml only at the next scheduled run. Use --force to apply changes instantly.

Conclusion

Curator acts as an entropy‑reduction engine for Hermes' skill library, running as a forked lightweight agent with strict tool limits. Its three‑state lifecycle, provenance‑aware archiving, LLM‑guided merge logic, and reversible operations keep the skill base lean, searchable, and safe, while preserving user‑crafted assets through ownership tags and pinning.