Architecture

OpenBot is built on a modern, event-driven architecture designed for high extensibility and local-first performance.

The Event Bus

At the heart of OpenBot is a central event bus. Every action, from a user typing a message to an agent performing a tool call, is represented as an event.

Event Flow

1. Source: An event is published to the bus (e.g., via POST /api/publish).
2. Routing: The Melony-powered runtime routes the event to all subscribed agents and plugins.
3. Processing: Subscribed components process the event and may perform side effects (like updating storage).
4. Emission: Components can yield new events back to the bus, triggering further cycles.

Melony Runtime

OpenBot uses Melony, a lightweight event-driven runtime. Melony manages the lifecycle of events and ensures that they are delivered to the correct handlers efficiently.

Key Benefits of Melony:

• Asynchronous Generators: Handlers use async function* to stream events back to the bus.
• Type Safety: Built with TypeScript for robust development.
• Predictable State: Helps maintain a consistent state across the entire harness.

Project Structure

Understanding the layout of the OpenBot repository helps when contributing or debugging:

• src/app: Contains the CLI, server implementation, and core event types.
• src/harness: The core orchestration logic, including the agent harness and MCP runtime.
• src/plugins: Built-in plugin implementations (e.g., storage, UI).
• src/services: Local services like the storage engine.
• src/registry: Manages the discovery and loading of plugins.

Local-First Storage

OpenBot stores all its data in ~/.openbot. This includes:

• agents/: Custom agent definitions (AGENT.md).
• channels/: Per-channel workspace (SPEC.md, state.json) and threads/<threadId>/ folders where conversation events.jsonl lives (threads required for chat). See Your First Channel.
• plugins/: Shared plugins. Each plugin must be in its own subdirectory (e.g., ~/.openbot/plugins/my-plugin/index.js).
• config.json: Global server configuration.
• variables.json: Environment variables and secrets.
• memory/: Long-term memory log for agents using the memory plugin.