hermes-skills/hermes-cron-design/SKILL.md

name, description, version, metadata

name	description	version	metadata
hermes-cron-design	Design principles for Hermes cron jobs — keep LLM jobs focused on judgment, move deterministic work to scripts.	1.0.0	hermes tags cron design patterns simplicity

Hermes Cron Job Design

Core Principle

One cron job = one responsibility. An LLM cron job should do exactly one judgment task. If the prompt grows beyond ~500 words for a data-processing job, you're almost certainly doing deterministic work that belongs in a script.

The Split

LLM Cron Job (judgment)	Script (deterministic)
Classify type/tags/entities	Quality scoring math
Detect contradictions	Cosine dedup
Synthesize observation text	Deletion with caps
Decide supersession	Checkpoint management
Extract named entities	Live count queries
	Vector fetch + write-back
	Log updates, ETA calculation

Anti-Pattern: The Monolithic Prompt

Do NOT write a 4,000-word prompt that asks an LLM to execute a full ETL pipeline via curl. This produces:

• JSON parsing bugs (string indices must be integers)
• Off-by-one errors (scroll offset inclusive vs exclusive)
• Counter drift (self-incremented vs ground truth)
• Half-organized points (organized_at stamped before write completes)
• Unbounded prompt growth as each bug fix adds more rules

The LLM is the judgment engine, not the execution engine.

Pattern: Classification-Only Cron

The simplest and most reliable pattern. The LLM does ONE thing:

1. Scroll unorganized points
2. Classify each (type, mem_class, tags, entities, confidence)
3. Write back via set_payload
4. Report

~500 words. No scoring, no dedup, no deletion, no pass-2, no self-healing. A separate script or cron handles everything else deterministically.

Pattern: Multi-Job Pipeline

For complex workflows, chain focused jobs:

Job A (LLM): Classify 100 points → write type/tags/entities
Job B (script): Score classified points → write quality_score
Job C (script): Dedup via vector search → merge + delete
Job D (LLM): Consolidate episodics → synthesize observations
Job E (script): Garbage collect → delete noise/expired

Each job is simple, testable, and can't break the others.

Pitfalls

• Don't ask an LLM to do math. Quality scoring, cosine comparison, deletion caps, ETA calculation — these are arithmetic. A script can't get them wrong.
• Don't ask an LLM to manage state. Checkpoints, counters, daily ceilings, pass numbers — these are state machines. A script can't drift them.
• Don't ask an LLM to guarantee atomicity. Log-then-delete, organized_at-with-payload — these are transaction patterns. A script can't half-write them.
• Don't iterate prompts to fix deterministic bugs. If Claude finds a bug in your scoring formula or your Qdrant filter syntax, that's a signal the logic belongs in code, not prose.