Developer Guide
Data Models
Core data structures in OpenBee
Worker
Represents an AI agent that executes tasks.
| Field | Type | Description |
|---|---|---|
id | string | UUID, auto-generated |
name | string | Display name |
description | string | Purpose and capabilities |
memory | string | Persistent context (written to CLAUDE.md) |
work_dir | string | Filesystem path (~/.openbee/worker/{id}) |
status | string | idle, working, or error |
created_at | int64 | Unix timestamp in milliseconds |
updated_at | int64 | Unix timestamp in milliseconds |
Task
A unit of work assigned to a worker.
| Field | Type | Description |
|---|---|---|
id | string | UUID, auto-generated |
message_id | string | Reference to the originating platform message |
worker_id | string | Assigned worker |
instruction | string | What the worker should do |
type | string | immediate, countdown, or scheduled |
status | string | pending, running, completed, failed, or cancelled |
scheduled_at | int64? | Unix ms — trigger time for countdown tasks |
cron_expr | string | 5-field cron expression for scheduled tasks |
next_run_at | int64? | Unix ms — next trigger time for scheduled tasks |
execution_id | string | Associated execution record |
created_at | int64 | Unix timestamp in milliseconds |
updated_at | int64 | Unix timestamp in milliseconds |
Execution
A record of a worker running a task.
| Field | Type | Description |
|---|---|---|
id | string | UUID, auto-generated |
worker_id | string? | Worker that ran this (null for bee executions) |
session_id | string | Claude Code session ID (for resumption) |
trigger_input | string | The original instruction/prompt |
status | string | pending, running, completed, or failed |
result | string | Execution output |
log_path | string | Filesystem path to execution logs |
ai_process_pid | int | PID of the Claude Code CLI process |
started_at | int64? | Unix timestamp in milliseconds |
completed_at | int64? | Unix timestamp in milliseconds |
PlatformMessage
An inbound message received from a chat platform.
| Field | Type | Description |
|---|---|---|
id | string | UUID, auto-generated |
session_key | string | Session identifier for grouping messages |
platform | string | Platform name (e.g. feishu, dingtalk, wecom, telegram) |
content | string | Message text content |
status | string | received, feeding, bee_processed, merged, or failed |
merged_into | string | ID of the message this was merged into (empty if not merged) |
platform_msg_id | string | Original platform message ID for deduplication |
raw | string | Raw message payload from platform |
received_at | int64 | Unix timestamp in milliseconds |
created_at | int64 | Unix timestamp in milliseconds |
updated_at | int64 | Unix timestamp in milliseconds |
retry_count | int | Number of retry attempts |
Memory
A key-value memory entry scoped globally or per session.
| Field | Type | Description |
|---|---|---|
id | string | UUID, auto-generated |
scope | string | global or a session key |
key | string | Memory identifier |
value | string | Memory content |
created_at | int64 | Unix timestamp in milliseconds |
updated_at | int64 | Unix timestamp in milliseconds |
Unique constraint on (scope, key) — one value per scope+key pair.
Database Schema
All tables use the bee_ prefix and are stored in SQLite:
bee_workers— Worker definitionsbee_tasks— Task recordsbee_executions— Execution historybee_platform_messages— Inbound platform messagesbee_session_contexts— Agent session context trackingbee_memories— Key-value memory storebee_local_sessions— Local chat sessionsbee_local_replies— Local chat repliesbee_migrations— Schema migration tracking
Database path is configurable (default: ~/.openbee/openbee.db or ./data/openbee.db).