convex/schema/ and assembled by convex/schema.ts. This page provides a domain-by-domain overview of the schema.
Tables use Convex’s document model — no SQL joins, no migrations in the traditional sense. Relationships are expressed through ID references and indexed queries.
⚡ Core Execution Data Chain
The most important tables form the execution data pipeline. Understanding this chain is essential for working with Forge.CORE EXECUTION DATA CHAIN
workflowRuns
status, startedAt, totalCost, pendingApprovalsOne record per execution. Tracks status, cost, active approvals, pinned definition.
has many↓
stepResults
runId, stepId, status, output, costCents, durationMsOne record per step attempt. Agent output, token usage, cost, metadata.
generates↓
tokenEvents
runId, stepId, agentId, inputTokens, outputTokens, costCentsRaw token consumption events. One per LLM call. Attributed to worker, task, model.
rolled up into↓
costAggregates
Pre-aggregated cost data. Hourly rollups, daily/weekly compaction.
Workflow: 13Agents: 6Governance: 5Gateway: 5Registries: 10Analytics: 3Budget: 4Chat: 8Factories: 7Workforce: 7
📊 Domain Tables
Gateway Infrastructure (5 tables)
Gateway Infrastructure (5 tables)
| Table | Description | Key indexes |
|---|---|---|
gatewayRegistry | Registered gateways with URL, token, capabilities, health status | by_gatewayId, by_token, by_status |
gatewayHealthHistory | Historical health check results (retained 90 days) | by_gateway |
gatewayModelAccess | Per-gateway model availability and access rules | by_gateway |
apiKeys | Platform API keys for external integrations | by_key |
glooCredentials | OAuth credentials for Gloo AI provider | — |
Workflow Execution (13 tables)
Workflow Execution (13 tables)
| Table | Description | Key indexes |
|---|---|---|
workflows | Workflow metadata (name, description, creator) | by_name |
workflowDocuments | Pinned .lobsterX YAML definitions | by_workflow |
workflowVersions | Version history for workflow definitions | by_workflow |
workflowRuns | Active and completed run records | by_status, by_workflow |
workflowCheckpoints | Interpreter snapshots for rewind/branch | by_run |
deployments | Workflow-to-gateway deployment bindings | by_workflow, by_status |
stepResults | Per-step execution results | by_run, by_run_step |
stepThreads | Agent conversation thread IDs for step executions | by_run_step |
executionEvents | Granular execution events (tool calls, progress) | by_run, by_step |
handoffs | Step-to-step output handoff records | by_run |
humanInputRequests | Human input requests during workflow execution | by_run |
approvals | HITL approval records (pending/approved/rejected) | by_status, by_run_step |
runArtifacts | Files and artifacts produced during runs | by_run |
Agent Management (6 tables)
Agent Management (6 tables)
| Table | Description | Key indexes |
|---|---|---|
agentRegistry | Canonical agent records from gateway runtimes | by_agentId, by_gateway |
agentDefinitions | Forge-managed agent definitions with lifecycle stages | by_agentId, by_status |
agentDeployments | Agent deployment state per gateway | by_agent, by_gateway |
agentConfigRevisions | Agent config change history (retained 50/agent or 90 days) | by_agent |
agentSkillDelegations | Skill delegation rules between agents | by_agent |
agentTemplates | One-click deploy agent templates for the gallery | by_category |
Registries (10 tables)
Registries (10 tables)
| Table | Description | Key indexes |
|---|---|---|
skillRegistry | Registered skills (gateway-sourced) | by_name, by_gateway |
skillDefinitions | Forge-managed skill definitions | by_name |
modelRegistry | Per-gateway model availability | by_gateway |
modelCatalog | Platform-wide model catalog with pricing and lifecycle | by_provider |
modelSlots | Agent-to-model assignment slots | by_agent |
modelRoutingConfig | Model routing rules and fallback chains | — |
stepLibrary | Reusable step definitions | by_name |
stepCategories | Step categorization | by_name |
promptLibrary | Managed prompt templates | by_name |
promptVersions | Prompt version history | by_prompt |
Analytics & Cost Tracking (3 tables)
Analytics & Cost Tracking (3 tables)
| Table | Description | Key indexes |
|---|---|---|
tokenEvents | Raw token consumption events (retained 90 days) | by_run, by_agent |
costAggregates | Rolled-up cost data (hourly, daily, weekly) | by_period, by_scope |
priceHistory | Model pricing snapshots for cost calculation | by_model |
Budget Management (4 tables)
Budget Management (4 tables)
| Table | Description | Key indexes |
|---|---|---|
budgets | Budget envelopes (daily/weekly/monthly) with spend limits | by_scope |
budgetHierarchy | Parent-child budget relationships | by_parent, by_child |
budgetTransactions | Debit/credit ledger entries | by_budget |
budgetAlerts | Budget threshold breach alerts | by_budget |
Audit & Compliance (2 tables)
Audit & Compliance (2 tables)
| Table | Description | Key indexes |
|---|---|---|
auditEvents | Append-only audit trail (retained 365 days) | by_run, by_category |
platformEvents | Platform-level operational events | by_type |
Governance & Policies (5 tables)
Governance & Policies (5 tables)
| Table | Description | Key indexes |
|---|---|---|
workerRoles | Role definitions with scope constraints and authority bounds | by_name |
policies | Governance policy rules | by_scope |
approvalPolicies | Approval trigger configurations | by_scope |
authorityGrants | Authority delegation grants | by_grantee |
orgTierGrants | Org-level tier-based permission grants | by_org |
Chat & Memory (8 tables)
Chat & Memory (8 tables)
| Table | Description | Key indexes |
|---|---|---|
channels | Chat channels (factory/project/team/direct/personal) | by_type, by_factory |
channelSessions | Finite conversation sessions within channels | by_channel |
chatMessages | Messages in chat sessions | by_session |
agentChannelMemory | Institutional knowledge across sessions | by_channel_agent |
agentSessionMemory | Working context within a session | by_session_agent |
agentLongTermMemory | Durable RAG-indexed memory archive | by_agent |
externalChannelLinks | External chat integrations (Slack syndication) | by_channel |
relevancyGateLog | Multi-agent relevancy gating decisions | by_channel |
Factories (7 tables)
Factories (7 tables)
| Table | Description | Key indexes |
|---|---|---|
factories | Factory definitions (type, manager, team, budget) | by_type, by_status |
factoryTypes | Factory type templates | by_name |
factoryBlueprints | Factory team composition blueprints | by_factory |
factoryAssignments | Work assignments within factories | by_factory |
factoryTeamMembers | Team member roster per factory | by_factory |
factoryDevEnvironments | exe.dev cloud development environments | by_factory |
factoryTokenEvents | Factory-scoped token attribution | by_factory |
Workforce & Org Structure (7 tables)
Workforce & Org Structure (7 tables)
| Table | Description | Key indexes |
|---|---|---|
workers | Unified worker records (EMPLOYEE, CONTRACTOR, AGENT) | by_type, by_team |
departments | Organizational departments | by_company |
teams | Teams within departments | by_department |
positions | Role positions in the org hierarchy | by_team |
positionAssignments | Worker-to-position assignments | by_position, by_worker |
orgUnits | Configurable org structure units | by_type |
orgUnitMemberships | Unit membership records | by_unit |
🗂️ Data Retention
Forge applies automatic data retention policies via scheduled crons:| Data | Retention | Schedule |
|---|---|---|
| Token events | 90 days | Daily at 03:00 UTC |
| Audit events | 365 days | Daily at 03:15 UTC |
| Callback dedup | 24 hours | Hourly |
| Agent config revisions | 50 per agent or 90 days | Daily at 03:30 UTC |
| Gateway health history | 90 days | Daily at 03:45 UTC |
| Event outbox (delivered) | 7 days | Weekly (Sunday 03:50 UTC) |
| Webhook deliveries | 30 days | Daily |