Storage

MaestroBot keeps durable operator, runtime, and channel state under one root. Default:

~/.maestrobot

Override the root on any command with --root.

Files

config.yaml

• static operator-authored service configuration

runtime.yaml

• mutable desired runtime configuration
• stable internal users and display names
• edited by the user or by maestrobot user ...

state.json

• mutable control-plane state
• registered channels
• authoritative channel scheduling state, including pending queues, channel state, priority, pause state, wake_at, and timeout_at
• unknown identities
• external account to internal user mappings
• external tool-server state
• retained subagent records

SOUL.md

• exclusive agent identity, voice, persona, and standing preferences

maestrobot.sock

• Unix socket used by the maestrobot control CLI

Directories

workspaces/<channel-id>/

• one persistent host directory per channel
• used as the writable / mount of the channel VFS

users/<user-id>/

• per-user profile files
• profile.md contains concise durable preferences, constraints, communication style, and stable facts
• profile writes are host-validated and bounded by profile.max_bytes and profile.max_bullets

paging/<channel-id>.json

• host-owned paging snapshots
• safe-boundary execution data only
• no opaque Maestro VM serialization
• structured working-memory notebook and current-run metadata
• execution context for a channel run, not the authoritative scheduler queue

transcripts/<channel-id>.jsonl

• normalized inbound and outbound transcript log
• canonical recent same-channel conversation source for prompts

logs/

• daemon service log
• Myria subprocess log
• append-only subagent logs

bin/

• installer-managed maestroc
• installer-managed myria

myria/

• generated myria.json derived from config.yaml
• generated OpenRouter template derived from config.yaml
• persistent SQLite file when SQLite storage is selected

maestro/

• user-editable channel_loop.mstr
• user-editable subagent_loop.mstr
• compiled agent_loop.mstro built from those root-local sources

In the current MaestroBot version, that SQLite file exists mainly to support the convenience bootstrap path. The fuller Myria backend remains PostgreSQL.

The runtime does not execute the repo copy of the Maestro agent program directly. It seeds and compiles the root-local maestro/ directory so operators can customize the Maestro behavior without patching the repo. The runtime also does not depend on repo paths in operator config; it uses the installed binaries under bin/.

Residency And Paging

Paging metadata includes at least:

• channel id
• phase
• current message
• consumed messages
• last action result
• current preset
• valid next states
• retained subagent ids

The daemon pages at safe boundaries and restores host-owned execution state instead of serializing opaque VM internals. On startup, the daemon reconciles state.json against paging snapshots: stale current channels from a previous process are normalized to active when a snapshot has unfinished work, or to idle with a scheduled wake when no work remains.

Workspace VFS

The daemon presents channel workspace access through a host-controlled VFS view:

• / channel workspace
• /.host-path/<n> read-only host PATH mounts

Filesystem side effects are serialized through daemon-owned leases so main-agent and subagent writes do not race each other.