Skip to main content
This page is for developers and operators who query or back up Clawboo’s database directly. Clawboo keeps its durable state in one SQLite file, 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 INTEGER epoch milliseconds (columns ending in _at, plus ts and timestamp_ms).
  • Flags are INTEGER 0 or 1. JSON is stored as TEXT.
  • tenant_id columns are unused and always null.
  • Most ids are TEXT: UUIDs, or ids from an agent source. chat_messages, cost_records, graph_layouts and approval_history use an autoincrement INTEGER id, and orchestration_events is keyed by seq.
  • Foreign keys are switched on, but only the columns below are declared as foreign keys. Every other id column (for example tasks.team_id or tasks.assignee_agent_id) is a plain reference that SQLite does not check.
  • Nothing deletes rows from orchestration_events, tool_call_audit or governance_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 key agent:<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 is plan. 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 is local (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 its task_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 from next_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 the memory_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 match memory_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 a tr_ 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 to POST /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 from tool_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 no tenant_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 from POST /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 default mode 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). Keyword search over facts uses memory_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, no user_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:
  1. 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).
  2. It then runs the definition, which creates any missing table, index or trigger.
Columns go first because a new column usually comes with a new index on it. If any step fails, the transaction rolls back and the file stays exactly as it was. The one start that adds columns logs SQLite: added missing columns to an existing database. Nothing else changes in an existing database:
  • A column whose type, NOT NULL or DEFAULT changed 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 EXISTS matches on the name. New table constraints and changes to the full-text table are not applied either.
Clawboo never drops, rebuilds or resets a table to apply a change. A change of those kinds reaches only databases created after it. A column added to an existing table must be one SQLite can add in place: no 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:
Several processes can open the file at once, for example the server and a stdio MCP bin pointed at it. Board writes take the write lock up front (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.db in its data folder: ~/.clawboo/clawboo.db, or the folder CLAWBOO_HOME names.
  • The stdio MCP bins use CLAWBOO_DB_PATH, or ~/.openclaw/clawboo/clawboo.db when it is unset; CLAWBOO_DB_PATH affects only the bins. To make a bin share the dashboard’s database, set CLAWBOO_DB_PATH to the dashboard’s file. The stdio snippets from GET /api/mcp/config do this.
  • On open, Clawboo sets the folder to 0700 and the database and its -wal and -shm files to 0600, 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 full PRAGMA 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.
Last modified on November 18, 2026