---
name: hermes-cron-design
description: Design principles for Hermes cron jobs — keep LLM jobs focused on judgment, move deterministic work to scripts.
version: 1.0.0
metadata:
  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.