Architecture | OrcBot Docs

⭐ Star

📦 System Overview

┌─────────────────────────────────────────────────────────┐
│                      Channels                            │
│   (Telegram, WhatsApp, Discord, CLI, Web Gateway)       │
└─────────────────────────┬───────────────────────────────┘
                          ▼
┌─────────────────────────────────────────────────────────┐
│                    Agent Core                            │
│  ┌─────────────┐  ┌──────────────┐  ┌───────────────┐  │
│  │  Decision   │  │   Memory     │  │   Scheduler   │  │
│  │   Engine    │  │   Manager    │  │   (Heartbeat) │  │
│  └─────────────┘  └──────────────┘  └───────────────┘  │
└─────────────────────────┬───────────────────────────────┘
                          ▼
┌─────────────────────────────────────────────────────────┐
│                 Skills & Tools                           │
│   (Browser, File System, Search, Messaging, Plugins)    │
└─────────────────────────┬───────────────────────────────┘
                          ▼
┌─────────────────────────────────────────────────────────┐
│                    Providers                             │
│     (OpenAI, Google, Bedrock, NVIDIA, OpenRouter)       │
└─────────────────────────────────────────────────────────┘

📁 Data Paths

OrcBot stores all data in ~/.orcbot/ by default:

Path	Purpose
`orcbot.config.yaml`	Main configuration file
`memory.json`	Short-term and episodic memories
`action-queue.json`	Pending tasks queue
`profiles/`	Contact profiles (per-JID)
`plugins/`	Custom skill plugins
`browser-profiles/`	Persistent browser sessions
`downloads/`	Downloaded media files

🧠 Decision Engine

The decision engine builds context from memories, skills, and channel metadata, then calls the LLM to determine the next action. It supports multi-tool responses.

💾 Memory Manager

Manages short-term memories with automatic consolidation into episodic summaries after 30 entries. Retrieval is capped for context window efficiency.

⏰ Scheduler

Emits scheduler:tick events for background jobs. Heartbeat tasks, polling jobs, and autonomy checks all run through the scheduler.

🔌 Event Bus

Central pub/sub system for decoupled communication. Components subscribe to events like config:changed, action:push, etc.

🔄 Request Flow

Inbound: Message arrives via channel (Telegram, WhatsApp, etc.)
Memory: Message stored in short-term memory with context
Decision: Decision engine builds prompt with memories, skills, channel context
LLM Call: MultiLLM routes to appropriate provider based on model name
Parse: Parser layer extracts tools array from JSON response
Execute: Skills manager executes each tool in sequence
Respond: Results sent back through the originating channel