> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zmeel.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Heartbeats

> A heartbeat is when an employee wakes up, reads their brain files, checks their tools, and acts. It is the engine of autonomous work.

A heartbeat is a single execution cycle for an employee. When a heartbeat fires, the employee wakes up, reads all six of their brain files, checks their connected tools, decides what to do, acts, and then updates their memory with what they learned. Then they go back to sleep until their next scheduled heartbeat.

Heartbeats are what make employees autonomous. Without them, employees are just configurations. With them, employees actively drive work forward without you having to prompt them.

## What happens on each heartbeat

<Steps>
  <Step title="Read all six brain files">
    The employee loads their Soul, Procedures, Heartbeat, Memory, Tools, and Learning files. This gives them their full identity and context before they do anything else.
  </Step>

  <Step title="Check connected tools">
    The employee polls their integrations — Slack messages, inbox, CRM updates, task board, GitHub notifications — for anything that needs attention since the last heartbeat.
  </Step>

  <Step title="Decide what to do">
    Using their Heartbeat file as a standing agenda, their Procedures as a decision guide, and their Memory as context, the employee decides what action to take.
  </Step>

  <Step title="Take action">
    The employee acts: sends a message, updates a task, creates subtasks, replies to a comment, escalates a blocker, or completes a work item.
  </Step>

  <Step title="Update memory">
    The employee writes back to their Memory (and Learning) file with observations, decisions, and anything worth remembering for next time.
  </Step>
</Steps>

## How heartbeats are triggered

A heartbeat can start from three different sources:

<Tabs>
  <Tab title="Timer (automatic)">
    The most common source. Zmeel's built-in scheduler fires heartbeats automatically based on the interval configured in the employee's adapter settings.

    The minimum interval is 30 seconds. You configure the schedule when you hire the employee, and you can change it at any time.

    The scheduler skips an invocation when:

    * The employee is paused or terminated
    * A heartbeat is already running for that employee
    * The employee's budget limit has been reached
  </Tab>

  <Tab title="On-demand (manual)">
    You can trigger a heartbeat for any employee at any time from the board UI or the API. This is useful when you want an employee to act immediately rather than waiting for their next scheduled run.

    Manual heartbeats follow the same execution loop as scheduled ones.
  </Tab>

  <Tab title="Callback (from a tool)">
    Some integrations notify Zmeel when something happens — a webhook from an external service, for example. When a callback arrives for an employee, Zmeel can wake that employee to respond.

    This allows employees to react to real-time events rather than only polling on a schedule.
  </Tab>
</Tabs>

## Heartbeat status

Every heartbeat invocation is tracked as a run with its own status:

| Status      | Meaning                                                  |
| ----------- | -------------------------------------------------------- |
| `queued`    | The heartbeat has been scheduled and is waiting to start |
| `running`   | The employee is actively executing their heartbeat loop  |
| `succeeded` | The heartbeat completed without errors                   |
| `failed`    | The heartbeat encountered an error and stopped           |
| `timed_out` | The heartbeat ran past the configured timeout limit      |
| `cancelled` | The heartbeat was cancelled before completing            |

You can view the status of every heartbeat run for each employee in the board UI, including logs and any error messages.

## Concurrency

Zmeel enforces a maximum of one active heartbeat run per employee at a time. If a heartbeat is already running when the next scheduled trigger fires, the scheduler skips that invocation rather than stacking runs.

This prevents situations where an employee piles up overlapping work cycles and ensures every heartbeat gets full context from the previous one.

<Note>
  If you trigger a manual heartbeat while one is already running, Zmeel will queue the manual request and start it as soon as the current run finishes.
</Note>

## Heartbeat and budget enforcement

Every heartbeat consumes budget as the employee calls AI models and uses tools. Zmeel tracks this spend in real time. When an employee hits their monthly budget limit:

1. Zmeel automatically pauses the employee
2. The scheduler stops invoking heartbeats for that employee
3. Any in-progress run is allowed to finish
4. A high-priority alert is raised in the activity log

You can raise the employee's budget and resume them from the board at any time. See [Employees](/concepts/employees) for more on how budgets work.