The open-source framework that makes AI agents proactive, self-learning, and autonomous. An agent orchestration system with full memory pipeline, multi-project tracking, and message discipline.
Heartbeat is an agent orchestration pattern that runs a loop every 30 minutes, enabling an AI agent to autonomously decide what to do based on:
- Project priorities -- which task is most urgent right now?
- User state -- what time is it? What is the user probably doing?
- Historical context -- did we make this mistake before?
- Emotional signals -- is the user stressed? Celebrating? Needs space?
The agent works silently in the background, pushing projects forward, learning from mistakes, and only reaching out when it truly matters.
The agent doesn't wait for commands. Every 30 minutes it:
- Reads PROJECTS.md for active tasks
- Picks the highest-priority project
- Makes measurable progress -- even while you sleep
Manage 10+ projects simultaneously. The agent automatically:
- Tracks progress per project with independent task files
- Updates status after each heartbeat
- Asks for decisions only when genuinely blocked
- Archives completed projects with full history
Every heartbeat generates a log. Logs auto-consolidate over time:
- Single heartbeat logs (detailed, 500 chars)
- Daily digests (summarized)
- Monthly summaries (key events only)
- Annual reviews (high-level narrative)
- Old detailed logs are auto-cleaned after integration
30% chance each free heartbeat to randomly review past memories (3-60 days ago):
- "Did we make this mistake before?"
- "Was there something we said we'd do later but forgot?"
- Found a rule gap? Auto-fix it on the spot.
The agent knows when NOT to message you:
- Default behavior: log only, send nothing (reply
HEARTBEAT_OK) - Max 3 non-urgent messages per day
- Only message for: verification needed, decision required, help needed
Define absolute red lines per project:
- "Never write untested code"
- "Never use model X for task Y"
- Violation = immediate stop, no exceptions
When no active project exists, the agent picks from a prioritized task pool:
- P0: Learning, exploration, creative work
- P1: Self-reflection, code optimization
- P2: File organization (can never be the only task)
Every 30 minutes:
Step 0: User state awareness (time, emotion, context)
Step 0.5: Project progress (read PROJECTS.md -> execute task)
Step N: Proactive care evaluation (should I message the user?)
Final: Log -> Reply gateway
Log Pipeline:
heartbeat/logs/tmp/04-11_1430.md (single log, 500 chars)
-> heartbeat/logs/tmp/daily.md (daily buffer)
-> on new day: daily digest -> heartbeat/logs/2026/04/04-11.md
-> on new month: monthly summary
-> on new year: annual review
-> old temp logs auto-deleted
Project Management:
PROJECTS.md (single source of truth)
-> P0 Urgent -> heartbeat/tasks/{id}/current.md
-> P1 Active -> heartbeat/tasks/{id}/current.md
-> P2 When Free -> heartbeat/tasks/{id}/current.md
-> Done -> archive
cp templates/PROJECTS.md.template PROJECTS.md
cp templates/AGENTS.md.template AGENTS.md
cp templates/heartbeat-rules.md.template heartbeat/heartbeat-rules.md
cp templates/free-time-pool.md.template heartbeat/free-time-pool.mdEdit AGENTS.md to add the heartbeat entry point in your agent's startup sequence:
- On receiving a heartbeat poll message, read
heartbeat/heartbeat-rules.md - Follow the heartbeat loop rules strictly
Add your projects with priority levels (P0/P1/P2), status, and task file references.
Configure your agent framework to send a heartbeat poll every 30 minutes. The agent responds with HEARTBEAT_OK (no message) or a proactive message (when justified).
Your agent is now alive and autonomous. It will:
- Push projects forward every 30 minutes
- Log everything automatically
- Only message you when it truly matters
your-workspace/
├── AGENTS.md # Agent core rules (startup sequence, heartbeat entry)
├── PROJECTS.md # Single source of truth for all projects
├── heartbeat/
│ ├── heartbeat-rules.md # Core heartbeat execution rules
│ ├── free-time-pool.md # Task pool for idle heartbeats
│ ├── tasks/
│ │ ├── project-a/
│ │ │ └── current.md # Current task for project A
│ │ └── project-b/
│ │ └── current.md
│ ├── logs/
│ │ ├── tmp/ # Temp logs (auto-cleaned)
│ │ │ ├── 04-11_1430.md
│ │ │ └── daily-buffer.md
│ │ └── 2026/ # Integrated logs
│ │ ├── 04/
│ │ └── 03-month.md
│ └── archive/ # Completed task archives
├── docs/ # Your project documentation
└── memory/ # Long-term memory (optional)
├── core.md # Core memories
└── 2026/ # Daily/monthly logs
"The best proactivity is when the user doesn't notice you exist, but everything is getting done."
Most agent frameworks push messages aggressively. Heartbeat implements three-level restraint:
- Default: log only, no message
- Evaluation: is this truly worth interrupting the user?
- Hard limit: max 3 non-urgent messages per day
Information depreciates. Logs should naturally decay like human memory.
- Today: detailed (single logs)
- Yesterday: summarized (daily digest)
- Last month: key events only (monthly summary)
- Last year: narrative (annual review)
"True learning is not accumulating new knowledge -- it's avoiding repeated mistakes."
The memory review system randomly revisits past records to catch recurring mistakes and forgotten commitments.
"Distributed state = lost state. Single entry point = single source of truth."
PROJECTS.md is the only place to track project status. Heartbeat reads only this file. No parallel tracking systems.
"Agents need to know not just what they SHOULD do, but what they MUST NEVER do."
Every task can define absolute constraints that halt execution immediately on violation.
- Solo developers who want an AI pair programmer that works 24/7
- Indie hackers managing multiple projects simultaneously
- AI agent builders who want proactive, not reactive, agents
- Anyone tired of AI that only responds when asked
This is a framework-agnostic design pattern. It works with any agent runtime that supports:
- Scheduled message polling (cron / timer)
- File system access (read/write markdown)
- Basic message sending capability
Tested with: OpenClaw, and adaptable to Claude Code, Hermes Agent, or custom agent frameworks.
- Architecture Details -- Full system architecture with flow diagrams
- Heartbeat Rules -- Complete heartbeat execution rules
- Project Tracking -- Multi-project management system
- Log Pipeline -- Auto-integrating log system
- Free Time Task Pool -- Idle heartbeat task management
- Memory Review -- Auto-reflection mechanism
MIT
Inspired by real-world agent orchestration patterns. Built to make AI agents feel alive.