Docs / Autonomy
⭐ Star
🤖 Core Concepts

Autonomy

How OrcBot operates independently via heartbeat, scheduler, and safety guardrails.

💓 Heartbeat Loop

The agent runs a continuous heartbeat loop that:

  • Pulls the next action from the priority queue
  • Simulates potential outcomes via SimulationEngine
  • Executes the action using appropriate skills
  • Stores results in memory
  • Triggers learning consolidation periodically
# Start the heartbeat loop
orcbot run

⏰ Scheduler

The scheduler emits scheduler:tick events on a configurable interval:

# Config
heartbeatInterval: 60  # seconds between ticks

Subscribe to scheduler events via the event bus:

import { eventBus } from './core/EventBus';

eventBus.on('scheduler:tick', async () => {
  // Do periodic work
});

🛡️ Safety Guardrails

Simulation
Pre-plan actions to predict outcomes before execution
Token Tracking
Monitor and limit API token usage per session
Auto-Reply Flags
Control whether channels can trigger autonomous responses
Priority Queue
Ensure high-priority tasks execute first

🧠 Decision Pipeline

Each decision goes through multiple stages:

  1. Context Gathering — Recent memories, journal, learning snippets
  2. Skill Prompts — Inject available skill descriptions
  3. Channel Context — Add channel-specific metadata and instructions
  4. LLM Call — Generate structured JSON response
  5. Parsing — Extract tools, speech, and action items

📋 Action Queue

Tasks are persisted in a file-backed priority queue:

// Push a task programmatically
actionQueue.push({
  taskId: 'abc123',
  description: 'Research topic X',
  priority: 8,
  status: 'pending'
});

// From CLI
orcbot push "Research topic X" -p 8

Queue location: ~/.orcbot/action-queue.json

🔄 Learning & Memory

The agent consolidates short-term memories into episodic summaries:

  • Short-term — Recent events stored individually
  • Episodic — Consolidated summaries after 30 items
  • Journal — Daily reflections and learnings
# View memories
orcbot ui  # → Memory menu