Skip to main content
ArgentOS Business — This feature is part of ArgentOS Business. The architecture is documented here for all users, but full functionality requires a Business license. Learn more about Business

​
Overview

Heartbeat Contracts are the structured interface between the operator and the heartbeat runner. The agent maintains a HEARTBEAT.md file in its workspace that defines what it should check during each heartbeat cycle. The contract parser converts this markdown into machine-readable tasks that the heartbeat runner processes, the verification sidecar validates, and the accountability system scores.

​
HEARTBEAT.md Format

The HEARTBEAT.md file has two sections:

​
Freeform Context

Everything outside the ## Tasks section is passed as prompt context to the heartbeat runner. Use this for priorities, reminders, situational notes, or any information the agent should consider during the heartbeat cycle.

​
Structured Tasks

​
Task Line Format

Each task in the ## Tasks section follows this pipe-delimited format:

​
Parsing Rules

  • Task lines must start with a list marker (-, *, or +) followed by a checkbox
  • Checkbox state: [ ] = unchecked, [x] or [X] = checked
  • Fields are split by pipe (|) characters
  • The task_id is auto-generated by lowercasing and replacing spaces with underscores
  • If required or optional is not specified, the task defaults to required
  • The verify: prefix is optional on the verification hint field

​
Progress Tracking

Per-task progress is tracked across heartbeat cycles:

​
Cycle Initialization

When a new heartbeat cycle starts, initCycleProgress() carries state from the previous cycle:

​
Progress Persistence

Progress is persisted to ~/argent/memory/heartbeat-progress.json. The file is created automatically if it does not exist.

​
Verification Process

After the agent processes each task, the verification sidecar (heartbeat-verifier.ts) evaluates the outcome:
A special groundTruthContradiction flag is set when the agent explicitly claimed a result that verification proves false — the harshest penalty in the accountability system.

​
Integration with Accountability Scoring

Verification verdicts feed directly into the Accountability System: The contract system is the primary driver of the daily accountability score. Well-written contracts with clear verification hints produce reliable scores.

​
Best Practices

​
Writing Good Tasks

  1. Use clear verification hints: verify: email_count > 0 is better than verify: done
  2. Separate required from optional: Only mark tasks required if they must complete every cycle
  3. Set appropriate max_attempts: Complex tasks may need 5+ attempts; simple checks need only 2
  4. Use descriptive task IDs: check_email is better than task_1

​
Freeform Context

  • Include priorities: “Focus on email monitoring during business hours”
  • Note temporal context: “Richard has a client demo on Thursday”
  • Set expectations: “Skip weather brief on weekends”

​
Task Granularity

  • Too coarse: “Do everything” — impossible to verify
  • Too fine: 20 tasks per cycle — overwhelming
  • Right size: 3-7 tasks covering key responsibilities with specific verification criteria