Background Tasks (The Heartbeat)

Schedule autonomous agent jobs on cron schedules.

Overview

The Heartbeat lets you schedule background agent tasks that run on a cron schedule. Each task fires The Soul with full memory access — the same agentic engine that powers /v1/chat/completions in agentic mode, but without an HTTP request/response cycle.

Use cases:

• Daily summaries — "Summarize all activity from today and store key takeaways"
• Monitoring — "Check our deployment status and flag anomalies"
• Data processing — "Analyze new entries and update the knowledge base"
• Scheduled reports — "Generate a weekly cost optimization report"

How it works

Cron Schedule → Tenant Executor → The Soul
                                     ├─ Full RMM memory access
                                     ├─ Tool use
                                     └─ Result stored in task state

Each task gets its own per-tenant CronService instance with independent scheduling, locking, and backoff. Tasks execute in isolation — a failing task doesn't affect your API traffic or other tasks.

Creating a task

import requests

requests.post(
    "https://api.brainstormrouter.com/v1/tasks",
    headers={"Authorization": "Bearer br_live_..."},
    json={
        "name": "daily-summary",
        "prompt": "Summarize today's key findings and store them in archival memory.",
        "schedule": "0 18 * * *",
        "timezone": "America/New_York",
        "model": "anthropic/claude-sonnet-4-5",
    },
)

The task will run daily at 6 PM Eastern. Each execution has access to the same tenant-wide memory as your interactive API requests.

Stateless by default

Each task execution starts a fresh conversation. Long-term context is preserved through RMM memory (core + archival), not conversation transcripts.

If you need transcript continuity across executions, pass a conversation_id when creating the task. This pins all executions to a single session file.

API endpoints

See the full Tasks API reference for endpoint details.