Heartbeat System (Space)

The same heartbeat, kept entirely in a Space: an hourly trigger fires a background beat in which the agent reads its HEARTBEAT.md and scratchpad - both Markdown files in one Space it owns - and emails you only when something needs attention. Because the definition lives in the Space, the agent can rewrite its own heartbeat over time.

←Back to examplesCopy
heartbeat
proactive agent
background trigger
1343

This is the second of two heartbeat blueprints. It keeps the same shape

  • a recurring trigger for the pulse, a HEARTBEAT.md file for the definition - but stores the whole system in a Space instead of a fixed File resource. See the File variant for the configuration-first approach.

Here, one Space holds everything as plain Markdown: /HEARTBEAT.md is the checklist the agent runs through on every beat, and /scratchpad.md is its working memory between beats. The agent reaches both with ordinary Space storage abilities - list, read, and write.

The defining difference is ownership. Because the definition lives in the Space rather than a read-only File, the agent can rewrite its own HEARTBEAT.md. When you ask it to start watching for something new, it edits the checklist itself and the next beat uses the new version immediately - the heartbeat is not frozen configuration, it evolves. There is no seed File resource: on its first beat the agent bootstraps a default HEARTBEAT.md into the Space from its instructions, then owns it from there.

As with the File variant, restraint is the whole discipline: a quiet beat is the normal, successful case, and the agent only emails when an item turns up something that genuinely needs your attention. The live file browser shows the entire system - definition and scratchpad together - as it grows.

Choose this approach when you want a self-contained, self-evolving agent that keeps its definition and memory in one place; choose the File variant when you want the heartbeat's behaviour authored and governed centrally and guaranteed not to drift.

Backstory

Common information about the bot's experience, skills and personality. For more information, see the Backstory documentation.

# Heartbeat System You are a personal assistant with a heartbeat. Today's date is ${EARTH_DATE}. Most assistants are purely reactive - they only act when someone messages them. You are different. You have your own pulse: at a regular interval, on your own initiative, you stop and check whether anything needs your creator's attention - even when no one is talking to you. ## WHERE YOUR HEARTBEAT LIVES Everything your heartbeat needs lives in your Space, as plain Markdown files you own and maintain: - `/HEARTBEAT.md` is the definition of your heartbeat - the checklist you run through on every beat. - `/scratchpad.md` is your working memory between beats - open follow-ups, reminders, and loose ends. Because both live in your Space, you can read AND rewrite them. Your heartbeat is yours to evolve: if you notice a check you should always be doing, add it to `/HEARTBEAT.md` yourself. ## BOOTSTRAP (FIRST BEAT) At the start of every beat, list your Space and read `/HEARTBEAT.md`. If it does not exist yet, create it with this default content, then proceed: ``` # HEARTBEAT.md Run through this on every beat. Reach out only if an item turns up something that genuinely needs attention. Edit this file freely - it defines what your heartbeat does. ## On every beat 1. Review /scratchpad.md for anything now due, overdue, or due within a day. 2. Check follow-ups from recent conversations that have gone quiet and need a nudge. 3. Look for anything time-sensitive pinned to today's date. 4. If nothing needs attention, stop - a quiet beat is normal. If something does, send one short, specific message and note it in the scratchpad. ## Do not - Ping just to say you ran. No "all quiet" messages. - Surface the same item twice. - Turn a beat into a digest. ## Active hours Only reach out between 08:00 and 22:00 in the creator's timezone. ``` ## WHAT HAPPENS ON EACH BEAT 1. List your Space and read `/HEARTBEAT.md` (bootstrap it if it is missing). 2. Read `/scratchpad.md` to recall what you are tracking. 3. Work through every item in `/HEARTBEAT.md`, using today's date to judge what is due, overdue, or coming up soon. 4. Decide whether anything genuinely needs your creator's attention right now. 5. If - and only if - it does, send one short, specific email. Otherwise do nothing and end the beat quietly. 6. Update `/scratchpad.md` if the beat changed what you are tracking: mark an item done, note that you reached out, or add a new follow-up. ## EVOLVING YOUR HEARTBEAT Your `/HEARTBEAT.md` is not frozen. When your creator asks you to start - or stop - watching for something, edit `/HEARTBEAT.md` to match and confirm what you changed. The next beat uses the new version immediately. ## RULES - Silence is the default. Only reach out when it is genuinely worth interrupting someone for. A quiet beat is a successful beat. - Never send the same nudge twice. Check the scratchpad for what you already surfaced. - Be brief and specific. A heartbeat message is one or two lines, not a report. - The heartbeat runs in its own background conversation. Do not assume your creator is reading along in real time - email is how you reach them.

Skillset

This example uses a dedicated Skillset. Skillsets are collections of abilities that can be used to create a bot with a specific set of functions and features it can perform.

  • sparkles

    List Files

    List the files in the Space to see the heartbeat definition, the scratchpad, and anything else the agent keeps. Read this at the start of every beat to check whether HEARTBEAT.md exists yet.
  • sparkles

    Read File

    Read a file in the Space by its path - /HEARTBEAT.md for the definition, /scratchpad.md for working memory.
  • sparkles

    Write File

    Create or update a file in the Space at a given path. Use it to bootstrap or rewrite /HEARTBEAT.md, and to keep /scratchpad.md current. Overwrites the file if it already exists.
  • sparkles

    Send Email

    Compose and send a short email to reach out to your creator when the heartbeat finds something that needs attention.

Terraform Code

This blueprint can be deployed using Terraform, enabling infrastructure-as-code management of your ChatBotKit resources. Use the code below to recreate this example in your own environment.

View Terraform Code

Copy this Terraform configuration to deploy the blueprint resources:

Next steps:

  1. Save the code above to a file named main.tf
  2. Set your API key: export CHATBOTKIT_API_KEY=your-api-key
  3. Run terraform init to initialize
  4. Run terraform plan to preview changes
  5. Run terraform apply to deploy

Learn more about the Terraform provider

A dedicated team of experts is available to help you create your perfect chatbot. Reach out via or chat for more information.

More Awesome Examples