ContextQMD
Back to Hermes Agent

Session Heartbeats

website/docs/user-guide/features/heartbeat.md

2026.8.133.3 KB
Original Source

Session Heartbeats (/heartbeat)

/heartbeat gives the current session one recurring instruction. Whenever the session is idle and the interval has elapsed, the prompt fires as a normal user turn — same conversation, same context, same prompt cache.

/heartbeat every 10m Check the deployment and report meaningful changes

Inspired by Prime-Agent's /heartbeat. The Hermes adaptation keeps the strict message-flow invariants: the heartbeat is injected only between turns (never mid-run), as a plain user-role message.

Heartbeat vs cron: which one do I want?

They look similar but serve different jobs:

/heartbeathermes cron
Runs inThis conversation — full context, memory of the discussionA fresh isolated session per tick
Survives process restartState survives (SessionDB); firing resumes next time the session is drivenYes — fully durable scheduler
How manyOne per sessionUnlimited jobs
Best for"Keep an eye on X in this thread while we work"Standing jobs, reports, watchdogs, deliveries

Rule of thumb: if the recurring prompt needs the conversation's context, use /heartbeat. If it's a self-contained job, use cron.

Commands

CommandWhat it does
/heartbeat every <interval> <prompt>Set (or replace) the session's heartbeat. Intervals: 90s, 10m, 2h, 1d (minimum 60s).
/heartbeat or /heartbeat statusShow the heartbeat, its interval, and time to next fire.
/heartbeat pauseStop firing without clearing.
/heartbeat resumeResume (re-anchors the timer — no instant stale fire).
/heartbeat clearRemove the heartbeat.

/hb is an alias. Works on the CLI and gateway platforms (on Slack, use /hermes heartbeat …).

Behavior details

  • Idle-only. A heartbeat never interrupts a running turn. If the agent is busy when the tick comes due, it fires at the next idle poll.
  • Missed ticks coalesce. If the session was busy (or the process wasn't running) through several intervals, you get one heartbeat turn, not a backlog. The timer re-anchors on every fire.
  • User messages win. A queued user message always takes priority; the heartbeat waits for the input queue to drain.
  • Cache-safe. The injected prompt is an ordinary user message. No system-prompt mutation, no toolset change.
  • Persistence. State lives in SessionDB.state_meta keyed by heartbeat:<session_id> — it survives /resume and rides across context-compression session rotations. Firing requires the owning process (CLI session or gateway) to be running; for schedules that must survive anything, use cron.
  • Don't-invent-work guard. The injected prompt tells the agent to reply briefly and stop when nothing meaningful changed, so an idle heartbeat doesn't generate busywork.

Example

You: /heartbeat every 15m Check whether the CI run for PR #1234 finished; summarize the result when it does

  ♥ Heartbeat set (every 15m): Check whether the CI run for PR #1234 finished; ...

[15 minutes of you working on other things in the same session]

Hermes: [Heartbeat — recurring instruction, fires every 15m]
  💻 gh pr checks 1234   (1.2s)
  CI is still running (14/37 checks complete). Nothing to report yet.

When the answer stops changing, /heartbeat clear it — or let it keep watch.