clawboo.db: 63 tables, plus a full-text search table for memory. Every column and index below comes from the schema definition in packages/db/src/schemaBootstrap.ts.
To copy the database while Clawboo runs, use clawboo backup (see the CLI reference). Where the file lives and how to reset it are in Data and state.
Tables at a glance
Conventions
- Times are
INTEGERepoch milliseconds (columns ending in_at, plustsandtimestamp_ms). - Flags are
INTEGER0or1. JSON is stored asTEXT. tenant_idcolumns are unused and always null.- Most ids are
TEXT: UUIDs, or ids from an agent source.chat_messages,cost_records,graph_layoutsandapproval_historyuse an autoincrementINTEGERid, andorchestration_eventsis keyed byseq. - Foreign keys are switched on, but only the columns below are declared as foreign keys. Every other id column (for example
tasks.team_idortasks.assignee_agent_id) is a plain reference that SQLite does not check. - Nothing deletes rows from
orchestration_events,tool_call_auditorgovernance_audit, so they grow until you reset or trim the database.
Foreign keys
In the column tables below,
FK marks these columns and cascade marks the ones deleted with their parent.
Teams and agents
teams
One row per team.
Indexes:
idx_teams_name (name), idx_teams_task_prefix (task_prefix, unique).
agents
The agent registry. Every agent source (OpenClaw, Clawboo Native, Claude Code, Codex and Hermes) records its agents here, so the fleet still renders when the OpenClaw Gateway is offline. For OpenClaw agents,name, status, identity_json and source_agent_id are overwritten on every sync; the other columns are Clawboo’s own.
Indexes:
idx_agents_gateway_id (gateway_id), idx_agents_status (status), idx_agents_team_id (team_id), idx_agents_source (source_id, source_agent_id).
sessions
Clawboo Native’s sessions, and the chain of sessions a task-runner run moves through when it rotates. OpenClaw sessions live in the Gateway and are not stored here.
Indexes:
uniq_sessions_source (unique: source_id, source_session_id), idx_sessions_agent (agent_id), idx_sessions_parent (parent_session_id).
boo_zero_team_briefs
Boo Zero’s brief for one team (Markdown), added to Boo Zero’s context when it works on that team.
No indexes beyond the primary key.
team_profiles
Stored team templates. The server neither reads nor writes this table.
No indexes beyond the primary key.
Chat
The team chats you use in the dashboard (General and its rooms) and one-to-one agent chats. The agents’ peer room is a different table,team_chat.
chat_messages
Chat transcripts, so history survives a page refresh. A team chat’s rows use the session keyagent:<agentId>:team:<teamId> in General and agent:<agentId>:team:<teamId>:room:<roomId> in a room. Clear chat keeps the rows and appends #cleared:<ts> to session_key and entry_id, so no reader matches them again.
Indexes:
uniq_chat_messages_entry_id (unique: entry_id), idx_chat_messages_session_ts (session_key, timestamp_ms), idx_chat_messages_session_id (session_key, id).
rooms
A team’s chat rooms: extra conversations inside its team chat, each with a subset of its members. General has no row; a room id of null means General. A room is archived, never deleted, and goes only with its team.
Indexes:
idx_rooms_team (team_id).
room_members
Which agents belong to which room. A room’s live roster is its members that are still active agents of the room’s team.
Primary key:
room_id, agent_id. Indexes: idx_room_members_agent (agent_id).
Board
The board is where team work is coordinated. Statuses and legal moves are described in The board.tasks
The task cards.
Indexes:
idx_tasks_team_status (team_id, status), idx_tasks_status (status), idx_tasks_team_room (team_id, room_id), idx_tasks_assignee (assignee_agent_id), idx_tasks_assignee_person (assignee_person_id), idx_tasks_parent (parent_task_id), idx_tasks_parent_dropped_created (parent_task_id, dropped, created_at), idx_tasks_identifier (identifier, unique), idx_tasks_chat_session (chat_session_key, updated_at), idx_tasks_goal (goal_id).
The (parent_task_id, dropped, created_at) index serves the Tasks MCP creation caps, which count live children per parent and new root tasks per 5 minutes.
task_create_keys
What makes a create safe to repeat: one row per idempotency key, pointing at the task it made or found.delegation_failures
The team engine’s loop breaker: how many times in a row one agent failed one task. A count runs out 24 hours after its last failure.labels
A team’s labels.
Indexes:
idx_labels_team_name (team_id, name_key, unique).
task_labels
Which task carries which label.
Indexes:
idx_task_labels_label (label_id).
task_deps
Dependency edges:task_id waits for depends_on_task_id to be done.
Primary key:
task_id, depends_on_task_id. Indexes: idx_task_deps_task (task_id), idx_task_deps_depends (depends_on_task_id).
task_questions
What an agent asked a person about a task, and the answer. A task has at most one question open.
Indexes:
idx_task_questions_task (task_id, status), and the unique idx_task_questions_idempotency (task_id, idempotency_key).
task_documents
A document on a task, one row per revision. A new revision is a new row, so none is ever overwritten. The only key today isplan.
Index: the unique
idx_task_documents_revision (task_id, key, revision).
A team’s switch for asking before a plan starts lives in settings, as team-plan-approval:<teamId>: JSON { on }.
task_comments
Comments and system notes on a task, such as report-backs and verification results.
Indexes:
idx_task_comments_task (task_id).
task_activity
Each task’s newest change a person could want to know about, one row per task. Only triggers write it, so no write path can forget, in any process:task_activity_created on a new task, task_activity_changed when status, title, description, priority or assignee_agent_id really changes, and task_activity_comment on a comment that is not from system. A change deletes the old row and inserts a new one, so each takes a seq no earlier change had. A task last changed before this table existed has no row, and is not unread.
Indexes:
uniq_task_activity_task (task_id, unique).
task_readers
How far each reader has read across the whole board. A reader islocal (the one built-in reader with no sign-in) or person:<id> (a person a sign-in proxy vouched for).
task_reads
The newest change a reader has read on one task, past their baseline. A task is unread when itstask_activity.seq is above both.
Primary key:
reader_id, task_id.
workspaces
The git worktree a task ran in.
Indexes:
idx_workspaces_task (task_id).
pauses
A person’s pause of an agent, a team or a task tree, which every run start reads (see Pauses). A row means paused, and resuming deletes it. It needs no renewal and survives a restart. A row left behind by a deleted agent or team covers nothing.
Indexes:
uniq_pauses_scope (unique: scope_kind, scope_id).
execution_processes
One row per run of a task, on any runtime: its status, git checkpoints, and token and cost totals.
Indexes:
idx_exec_task (task_id), idx_exec_status (status).
Home
From 0.9.0. A team’s goals, KPIs, pages and status line (see the Home API). People and agents in these rows are JSON{ kind: 'person' | 'agent', id, name }. A team’s Home settings live in settings, as team-home:<teamId>: JSON { leadWritesStatus, weeklyUpdatesRoutineId, statusAsks, statusWrites, onSeq, lastAskSeq, pendingAskAt }: the times of the lead’s asks and lines in the last day, the board’s position when the line was turned on and at the last ask, and the newest ask until a line answers it.
team_goals
Indexes:
idx_team_goals_team (team_id, position), idx_team_goals_parent (parent_goal_id).
team_goal_health
One row per health change:id, goal_id (FK team_goals.id, cascade), health, set_by (JSON person), set_at, and update_id, the update whose publishing set it (null for a direct set). Index: idx_team_goal_health_goal (goal_id, set_at).
team_goal_updates
Indexes:
idx_team_goal_updates_goal (goal_id, created_at), idx_team_goal_updates_team_state (team_id, state).
team_kpis
Indexes:
idx_team_kpis_team (team_id, status, position), idx_team_kpis_goal (goal_id).
team_kpi_values
Append-only:id, kpi_id (FK team_kpis.id, cascade), value (REAL), as_of, reported_by (JSON person or agent), execution_id and task_id (the reporting run and its task), source_url, note, created_at. Index: idx_team_kpi_values_kpi (kpi_id, as_of).
team_pages
id, team_id (FK teams.id, cascade), goal_id (FK team_goals.id, set to null), title (the newest revision’s), pinned (INTEGER, default 0), archived_at, created_at, updated_at. Index: idx_team_pages_team (team_id, updated_at).
team_page_revisions
One row per revision, never overwritten:id, page_id (FK team_pages.id, cascade), revision (1, 2, 3 per page; an agent may not add one to a page that has 200, a person may), title, body (up to 200,000 characters from a person, 50,000 from an agent), author (JSON person or agent), execution_id, reverted_from (the revision a revert copied), created_at. Index: the unique idx_team_page_revisions_revision (page_id, revision).
team_home_summary
The status line a team’s lead wrote, one row per team:team_id (PK, FK teams.id, cascade), body (up to 400 characters), author (JSON agent), execution_id, model (what the lead’s registry row says it runs), written_at, and board_seq, the team board’s newest task change when it was written, which tells the next ask whether the board moved.
Routines
scheduled_runs
One row per routine. The row is the source of truth; the in-memory timer re-arms fromnext_run_at when the server starts. See Routines.
Indexes:
idx_scheduled_runs_next (next_run_at), idx_scheduled_runs_status_next (status, next_run_at), idx_scheduled_runs_agent (agent_id).
Memory
Shared memory: facts, versioned procedures, and the feedback that scores them. See Memory.memory_facts
Declarative facts. Keyword search uses thememory_facts_fts table; meaning-based search uses embedding. The created_by_* and source_* columns record who saved a fact and never change who can see it.
Indexes:
idx_memory_facts_team (scope_team_id), idx_memory_facts_agent (scope_agent_id), idx_memory_facts_created (created_at), idx_memory_facts_model_created (embedding_model, created_at, id).
memory_procedures
Versioned procedures. Saving under an existing name and scope adds the next version. The provenance columns matchmemory_facts.
Indexes:
idx_memory_procedures_name (name), idx_memory_procedures_team (scope_team_id).
memory_outcomes
Feedback on facts, append-only. It feeds the learning status that recall shows.
Indexes:
idx_memory_outcomes_fact (fact_id), idx_memory_outcomes_created (created_at).
Tools and approvals
The tool broker behind the Tools MCP server: tool settings, the audit trail, approvals, and stored oversized results.tool_registry
Saved tool metadata and the on/off switch. A tool with no row counts as enabled.
Indexes:
idx_tool_registry_owner (owner), idx_tool_registry_connector (connector_id).
tool_call_audit
Append-only audit of every brokered call, written before and after it runs. Arguments and results are scrubbed of secrets before they are stored; the model still gets the real result.
Indexes:
idx_tool_audit_tool (tool_name), idx_tool_audit_created (created_at), idx_tool_audit_grant (grant_id, created_at).
tool_call_approvals
Approval requests.kind: 'tool' is a call Clawboo itself is holding (the broker, a Clawboo Native agent’s command, or a delegation). kind: 'exec' mirrors a shell command the OpenClaw Gateway is holding: its row id is the Gateway’s request id, tool_name is exec, tool_class is destructive, and args_summary is { command, cwd }.
Indexes:
idx_tool_approvals_status (status), idx_tool_approvals_created (created_at), idx_tool_approvals_grant (grant_id, status).
tool_result_blobs
Tool results too large to hand a model whole (over 16 KiB). The model gets a trimmed view and atr_ handle that read_tool_result reads back. One result keeps at most 8 MiB. Rows older than 7 days are deleted (CLAWBOO_TOOL_RESULT_TTL_MS).
Indexes:
idx_tool_result_blobs_created (created_at).
approval_history
A log of approval decisions posted toPOST /api/approvals.
Indexes:
idx_approval_history_agent_id (agent_id), idx_approval_history_created_at (created_at).
Connectors and grants
Connectors Clawboo runs, and the grants that decide which agents may use them. See Connectors.connectors
One row per connector Clawboo has connected, written only after the connector answered. No secret is stored:spec holds only secret:NAME references.
Indexes:
uniq_connectors_slug (unique: slug), idx_connectors_health (health), idx_connectors_catalog (catalog_id).
capability_grants
Grants: one row lets an agent, a team or every agent use a connector, tool or skill, and is also the edge the graph draws. There is no last-used column; that comes fromtool_call_audit.
Indexes:
uniq_capability_grants_key (unique: grant_key), idx_grants_subject (subject_kind, subject_id), idx_grants_connector (connector_id), idx_grants_capability (capability_id), idx_grants_state (state), idx_grants_expires (expires_at).
approval_rules
Remembered Always decisions, each bound to a grant. Revoking the grant deletes its rules in the same step (there is no foreign key). A rule made from Always expires after 30 days.
Indexes:
uniq_approval_rules_key (unique: rule_key), idx_approval_rules_grant (grant_id), idx_approval_rules_expires (expires_at).
Capabilities and skills
capabilities
Every runtime’s skills, tools and connectors in one list, which the Capabilities panel and the graph read. Each source re-reads its own rows without touching another source’s.
Indexes:
idx_capabilities_source (source_id), idx_capabilities_runtime (runtime), idx_capabilities_agent (agent_id), idx_capabilities_kind (kind).
skills
Skills added to agents from the Marketplace or the Capabilities panel.
Indexes:
idx_skills_source (source), idx_skills_category (category).
Peer room and mailbox
The agents’ peer room behind the TeamChat MCP server, each agent’s mailbox, and the team chat’s outbox of task updates. None of them is the dashboard’s team chat.team_chat
Posts in the agents’ peer room. A post never changes the board. The table has notenant_id column.
Indexes:
uniq_team_chat_room_seq (unique: room_id, seq), idx_team_chat_team (team_id).
agent_inbox
Each agent’s mailbox of coordination notices. A notice is delivered once, by whichever channel reaches the agent first (the digest at the start of a run, or the MCP tool-result piggyback). Undelivered notices survive restarts.
Indexes:
idx_agent_inbox_pending (agent_id, delivered_at).
report_up_outbox
The team chat engine’s[Task Update] items, one row per result waiting to reach whoever handed the work off. A row is written when the engine queues it and settled when the recipient’s run that carried it finishes, when a Stop drops it, or when it is given up. An unsettled row whose run never finished is sent again, by the running engine or, after a restart, by the chat’s next engine. Settled rows are deleted after 7 days; unsettled rows are deleted after 30 days, or as soon as their team is gone.
A row with chat_session_key set belongs to that one-to-one chat: work handed off from Boo Zero’s chat answers there. No team or room reads such a row. The chat sends it itself, under the same rules, and team_id stays the team the work was done in, or is empty for a note about a hand-off that reached no team.
Indexes:
idx_report_up_outbox_pending (team_id, room_id, settled_at), idx_report_up_outbox_chat (chat_session_key, settled_at), idx_report_up_outbox_task (task_id, created_at).
task_wakes
Saved wakes: something happened on a task and its agent has not heard. A row is written when the wake happens, the run that starts the task takes it, and it is settled when that run ends. Deleted 7 days after it settles, or after 30 days still waiting.
Indexes:
uniq_task_wakes_waiting, unique on (agent_id, task_id) where settled_at and carried_exec_id are null; idx_task_wakes_pending (settled_at, carried_exec_id); idx_task_wakes_task (task_id).
agent_wake_gates
One row per job, the task’s top-level ancestor: what a person said about its agents waking each other, the card asking them, and this hour’s count. In the database so a restart resets none of it.
Indexes:
idx_agent_wake_gates_card (card_task_id), idx_agent_wake_gates_team (team_id).
job_runs
One row per job, the task at the top of its tree: how many runs it has started by itself. Written in the transaction that opens the run, so a restart loses none of it.
Indexes:
idx_job_runs_hit (limit_hit_at), idx_job_runs_stopped (stopped_at), idx_job_runs_team (team_id).
agent_wake_chains
One row per pair of agents in a team: how many wakes in a row answered each other. Per pair and not per job, so the brake holds when two helpers each have a top-level task. A chain quiet for an hour is over.Spend, budgets and audit
cost_records
Per-agent token and spend records, which the Tokens Used panel reads. Rows come fromPOST /api/cost-records, from the server watching OpenClaw sessions, and from each Clawboo Native, Claude Code, Codex or Hermes run when the server settles its cost (task-runner runs, team-chat runs and one-to-one chat turns). The latest rows for an agent also size the estimate its runs hold against a budget (see budget_reservations).
Indexes:
idx_cost_records_agent_id (agent_id), idx_cost_records_session (session_key, created_at), idx_cost_records_run_id (run_id), idx_cost_records_created_at (created_at).
budgets
Spend budgets. Spend is tracked in whole and fractional cents so many tiny charges still add up. The defaultmode is warn (track and warn); cap (pause at 100%) is opt-in. See Budgets and spend.
Indexes:
uniq_budgets_scope (unique: scope, scope_id), idx_budgets_status (status).
budget_reservations
What each run that is going holds against a budget it counts toward: its estimated cost, set aside from the moment it is let start until it ends, so runs that start together see each other (see Runs that go at the same time). One row per run and budget. A run’s recorded spend shrinks its row, and the row is deleted when the run ends. At startup the server deletes every row it did not write itself: Clawboo runs one server per database, so those rows were left by a server that stopped while its runs were going.
Indexes:
uniq_budget_reservations_hold (unique: hold_id, budget_id), idx_budget_reservations_budget (budget_id).
governance_audit
Append-only audit of governance decisions, with secrets scrubbed.
Indexes:
idx_gov_audit_agent (agent_id, created_at), idx_gov_audit_created (created_at).
Event log
orchestration_events
The append-only event log that observability reads. Kinds and their data are in Events and errors.
Indexes:
uniq_orch_events_id (unique: id), idx_orch_events_team_seq (team_id, seq), idx_orch_events_task_seq (task_id, seq), idx_orch_events_trace_seq (trace_id, seq), idx_orch_events_kind_ts (kind, ts), idx_orch_events_created (created_at).
Settings and layout
settings
Key and value rows for most dashboard settings and for Clawboo’s own state, including the per-install secret that signs MCP attach URLs (mcp-attach-scope-secret). What the rows hold is listed in Configuration.
No indexes beyond the primary key.
graph_layouts
Saved node positions for the graphs.name is atlas-radial or atlas-top-down for the Org chart, team-<teamId> for a team graph, team-<teamId>-room-<roomId> for a room graph, and default with no team selected.
Indexes:
uniq_graph_layouts_name_url (unique: name, gateway_url).
Full-text search
Keyword search over facts usesmemory_facts_fts, an FTS5 virtual table with the columns title, content and fact_id (fact_id is stored but not indexed). The same schema definition creates it, and it is not counted among the 51 tables. Three triggers keep it in step with memory_facts:
How the schema is created
There is no migration ladder: no numbered migration files, nouser_version bookkeeping, and no db:migrate script. The CREATE TABLE IF NOT EXISTS statements in packages/db/src/schemaBootstrap.ts are the only place tables, indexes and triggers are created. packages/db/src/schema.ts is the Drizzle type layer for typed queries; it never changes the database. Contributor rules for schema changes are in Monorepo and build.
Upgrading an existing database
When the server starts, it brings the file up to the current schema in one transaction:- It compares each existing table’s columns with the schema definition and adds any column the file is missing (
ALTER TABLE ... ADD COLUMN, using the column’s definition from the same source). - It then runs the definition, which creates any missing table, index or trigger.
SQLite: added missing columns to an existing database.
Nothing else changes in an existing database:
- A column whose type,
NOT NULLorDEFAULTchanged keeps its old definition. Only new databases get the new one, and nothing reports the difference. - A column the definition no longer declares stays in place. That is also what an older Clawboo sees when it opens a newer database, so leaving the column keeps the newer version’s data.
- A changed index or trigger is skipped, because
IF NOT EXISTSmatches on the name. New table constraints and changes to the full-text table are not applied either.
PRIMARY KEY, UNIQUE or STORED generated column; a literal DEFAULT, not an expression such as CURRENT_TIMESTAMP; a DEFAULT on every NOT NULL column; and no non-null DEFAULT on a REFERENCES column. If such a column ever reached a user, the start would stop before changing the file. The server keeps running without a usable database, and System Health shows the databaseSchema check as failed with SQLite schema cannot be upgraded in place and an error naming the column. Tests catch such a column before release.
The other databaseSchema failures are core tables missing and schema is missing <n> column(s); queries touching them will fail.
Connection settings
Every connection opens with:BEGIN IMMEDIATE) and retry with jitter for up to 1.5 seconds (CLAWBOO_DB_WRITE_BUDGET_MS), which is why busy_timeout is short. The server holds one connection for as long as it runs, and on shutdown it checkpoints the write-ahead log into the main file (wal_checkpoint(TRUNCATE)) before closing.
Where the file lives
- The dashboard server uses
clawboo.dbin its data folder:~/.clawboo/clawboo.db, or the folderCLAWBOO_HOMEnames. - The stdio MCP bins use
CLAWBOO_DB_PATH, or~/.openclaw/clawboo/clawboo.dbwhen it is unset;CLAWBOO_DB_PATHaffects only the bins. To make a bin share the dashboard’s database, setCLAWBOO_DB_PATHto the dashboard’s file. The stdio snippets fromGET /api/mcp/configdo this. - On open, Clawboo sets the folder to
0700and the database and its-waland-shmfiles to0600, because the file holds the secret that signs MCP attach URLs. Where that fails (for example on Windows, or for a file another user owns), Clawboo logs a warning and opens the file anyway. - At start, System Health runs
PRAGMA quick_check(databaseIntegrity) and the schema check above (databaseSchema). Re-run probe (POST /api/health/recheck) runs the fullPRAGMA integrity_check, which also checks every index. The full check also runs in the background a couple of minutes after a start when the last one is a day old, then once a day, and what it finds replaces the start’s result. All of them run in a worker thread on a read-only connection of their own, so the server keeps answering while they read the file. A check that cannot run there (the file is busy, it takes longer than its limit of 2 minutes for the quick check and 15 for the full one) reads as Degraded with the reason, never as damage.
Related
- Data and state: where Clawboo keeps its files, and how to back up and reset.
- Configuration: what the
settingsrows hold. - Events and errors: the event kinds stored in
orchestration_events. - MCP tools: the tools that read and write the board and memory tables.
- Monorepo and build: the rules for changing the schema.