Hermes Agent: Checkpoints
Last updated: 2026-08-31
Checkpoints are Hermes Agent's save system — like game saves, you can save state at any time, reload if something goes wrong, and resume interrupted experiments.
💡 Tip: Checkpoints save not only conversation history but the complete Agent state: memory, skill call chains, tool execution results, and LLM intermediate reasoning steps. After restoration, the Agent continues from the breakpoint without starting over.
📋 Prerequisites: Lesson 6 Memory System, Lesson 7 Skills System
1. What You Will Learn
| # | Content |
|---|---|
| ❶ | Checkpoint mechanism principles |
| ❷ | Automatic and manual checkpoints |
| ❸ | Restore and rollback |
| ❹ | Experiment management |
| ❺ | Checkpoint storage and cleanup |
2. Story
(1) Pain Point: Long Task Interrupted, Everything Lost
Bob asked the Agent to perform a complex code review. After 20 minutes of analysis, the network dropped. Starting over means doing everything again.
(2) Solution: Checkpoint Save, Resume from Breakpoint
Alice's Hermes automatically saves checkpoints, restoring after network loss:
BASH
# Before disconnect
Agent: Reviewed 15/20 files...
# After restore
hermes checkpoint restore latest
Agent: Restored from checkpoint, continuing review 16/20...
3. Checkpoint Mechanism Principles
(1) Checkpoint Content
JSON
{
"checkpoint_id": "cp_20260315_143022",
"timestamp": "2026-03-15T14:30:22Z",
"session_id": "session_abc123",
"agent_state": {
"current_task": "code-review",
"progress": "15/20 files",
"active_skills": ["react-component-review"],
"pending_actions": ["review_file_16", "review_file_17"]
},
"memory_snapshot": {
"working_memory": [...],
"long_term_changes": [...]
},
"tool_results": {
"fs_read_src_main_py": "content_hash_abc",
"code_python_result": "output_hash_def"
},
"llm_context": {
"messages": [...],
"tokens_used": 12500
}
}
(2) Checkpoint Flow
graph LR
A[Agent Execution] --> B{Auto Trigger?}
B -->|Every 5 min| C[Save Checkpoint]
B -->|Skill Complete| C
B -->|Tool Call| C
C --> D[Write to Disk]
D --> A
E[Interrupt/Error] --> F[Restore Checkpoint]
F --> G[Read State]
G --> H[Continue Execution]
4. Automatic and Manual Checkpoints
(1) Auto Checkpoint Configuration
YAML
checkpoint:
enabled: true
# Auto-save policy
auto_save:
interval: 300 # Every 5 minutes
on_skill_complete: true # After skill completion
on_tool_call: true # After tool calls (for large tasks)
on_error: true # On error
max_checkpoints: 50 # Keep max 50
# Storage configuration
storage:
path: "~/.hermes/checkpoints"
compression: true # Compressed storage
max_size_mb: 500 # Total size limit
(2) Manual Save
BASH
# Manual save in conversation
/checkpoint save "review-half-done"
# Command line save
hermes checkpoint save --name "before-deploy"
# View all checkpoints
hermes checkpoint list
# Output example:
# ┌──────────────────────┬──────────┬─────────┬──────────┐
# │ Checkpoint │ Time │ Progress│ Size │
# ├──────────────────────┼──────────┼─────────┼──────────┤
# │ review-half-done │ 14:30 │ 15/20 │ 2.3 MB │
# │ auto-cp-143000 │ 14:30 │ 15/20 │ 2.1 MB │
# │ auto-cp-142500 │ 14:25 │ 12/20 │ 1.8 MB │
# └──────────────────────┴──────────┴─────────┴──────────┘
5. Restore and Rollback
(1) Restore Checkpoint
BASH
# Restore latest checkpoint
hermes checkpoint restore latest
# Restore specific checkpoint
hermes checkpoint restore review-half-done
# Restore in conversation
/checkpoint restore review-half-done
Agent: Restored from checkpoint "review-half-done"
Task: Code review
Progress: 15/20 files
Continuing with file 16...
(2) Rollback
BASH
# Rollback to checkpoint (discard all changes after)
hermes checkpoint rollback review-half-done
# ⚠️ This discards all memory and skill changes after the checkpoint
# Confirm? (y/n)
(3) Selective Restore
YAML
# Restore only partial state
checkpoint:
restore_options:
agent_state: true # Restore task state
memory: true # Restore memory snapshot
tool_results: true # Restore tool result cache
llm_context: false # Don't restore LLM context (regenerate)
6. Experiment Management
(1) Research Mode Checkpoints
In research mode, checkpoints are especially important — batch trajectory generation can run for hours:
YAML
research:
mode: true
checkpoint:
save_every_n_tasks: 10 # Save every 10 tasks completed
save_on_error: true # Save on error (preserve failure samples)
trajectory:
output_format: "sharegpt"
output_dir: "~/.hermes/research/trajectories"
BASH
# Batch trajectory generation
hermes research run \
--tasks experiment_tasks.jsonl \
--model gpt-4o \
--batch-size 50 \
--output sharegpt
# Resume after interruption
hermes research resume \
--from-checkpoint latest \
--output sharegpt
(2) Experiment Comparison
BASH
# Save checkpoints for different experiments
hermes checkpoint save --tag "experiment-a-temp07"
hermes checkpoint save --tag "experiment-b-temp03"
# Compare experiment results
hermes research compare \
--checkpoint experiment-a-temp07 \
--checkpoint experiment-b-temp03
7. Checkpoint Storage and Cleanup
(1) Storage Format
~/.hermes/checkpoints/
├── cp_20260315_143022.tar.gz # Auto checkpoint
├── review-half-done.tar.gz # Manual checkpoint
└── experiment-a.tar.gz # Experiment checkpoint
(2) Cleanup Strategy
YAML
checkpoint:
cleanup:
auto: true
keep_manual: true # Keep manual saves
keep_last_n: 10 # Keep last 10 auto checkpoints
max_age_days: 30 # Auto-cleanup after 30 days
max_total_size: "500MB" # Clean oldest when total size exceeded
BASH
# Manual cleanup
hermes checkpoint clean --keep-last 5
# View storage usage
hermes checkpoint storage-info
❓ FAQ
Q How much space do checkpoints use?
A Single checkpoint is 1-5 MB (compressed). 50 checkpoints ≈ 50-250 MB. Auto-cleanup is configurable.
Q Will restoring a checkpoint lose memory?
A No. Restore only reverts task state and context — it doesn't delete long-term memory. Only rollback discards changes.
Q Can checkpoints be migrated across machines?
A Yes. Export checkpoint files and import on another machine. Path differences may need manual adjustment.
Q How often are auto-saves?
A Default every 5 minutes. Configurable via
checkpoint.auto_save.interval. Frequent saves have minor performance impact.Q Are checkpoints required in research mode?
A Strongly recommended. Batch experiments run for hours — resuming from checkpoint is far more efficient than starting over.
Q Do checkpoints support encryption?
A Yes. Configure
checkpoint.storage.encryption: true for AES-256 encryption.📖 Summary
- Checkpoints save complete Agent state: task progress, memory, tool results, LLM context
- Auto-save (timed + event-triggered) + manual save
- Restore: resume from breakpoint; Rollback: revert to past state
- Research mode: checkpoint-protected batch trajectory experiments
- Auto-cleanup strategy: keep last N, age-based cleanup, total size limits
📝 Exercises
- Basic (⭐): Manually save a checkpoint in conversation, restart Hermes, restore, and verify state consistency.
- Intermediate (⭐⭐): Configure auto-checkpoint policy (every 3 min + on skill completion), run a long task, observe auto-saves.
- Advanced (⭐⭐⭐): Simulate a research scenario, batch-run 10 tasks, force interrupt midway, resume from checkpoint, verify zero data loss.
