Data Model

Paperclip’s data model is built around a simple rule: the first-party control plane owns business state, runtime state, and plugin metadata. External tools can be connected and queried, but they stay external.

​

How To Read This Page

The model is organized from the board outward:

1. Identity and access establish who can act.
2. Companies, agents, goals, projects, and issues define the work graph.
3. Heartbeats and runtime tables record execution.
4. Cost, finance, performance, evaluation, and memory tables record quality and improvement loops.
5. Plugins and external tools extend the system without taking over ownership.

If you want the route and service mapping for the same tables, see Schema Map.

​

Ownership Boundaries

Paperclip is the source of truth for:

• company structure
• agent registry and reporting lines
• work hierarchy and task ownership
• approvals and audit trail
• heartbeat execution history
• budgets, spend, and performance state
• plugin metadata and integration state
• evaluation, memory, and review records

External systems remain external:

• Langfuse owns its own product stores
• Gigapipe owns observability ingest and storage
• Redash owns dashboard metadata
• Bytebase owns change workflow metadata
• ChartDB owns diagram export state
• source tools like GitHub, Linear, Gmail, and Slack own their own records

The practical boundary is simple:

• if Paperclip uses the row to govern work, it belongs here
• if Paperclip only reads, maps, or mirrors it, the source system still owns it

​

Major Entity Groups

​

Identity And Access

These tables define people, sessions, permissions, and join flows.

• user
• session
• account
• verification
• board_api_keys
• cli_auth_challenges
• instance_user_roles
• company_memberships
• invites
• join_requests
• principal_permission_grants

Use these tables when you are dealing with login, board access, CLI auth, or membership changes.

​

Company And Org

These tables define the company shell and the agent workforce.

• companies
• company_logos
• agents
• agent_api_keys
• agent_config_revisions
• agent_runtime_state
• agent_task_sessions
• agent_wakeup_requests
• company_secrets
• company_secret_versions
• company_skills
• instance_settings

This layer is the board-facing view of the company: what it is, who works there, what they can do, and which skills or secrets they are allowed to use.

​

Planning And Execution

These tables define goals, projects, issues, workspaces, work products, and the documents attached to them.

• goals
• projects
• project_goals
• project_workspaces
• execution_workspaces
• workspace_operations
• workspace_runtime_services
• issues
• issue_comments
• issue_labels
• labels
• issue_approvals
• approvals
• approval_comments
• issue_attachments
• assets
• issue_documents
• documents
• document_revisions
• issue_work_products
• issue_inbox_archives
• issue_read_states
• feedback

This is the main work graph. Goals anchor the company. Projects group work. Issues carry the task hierarchy. Workspaces and runtime services bind issues to execution environments. Work products and documents capture the results.

​

Automation And Runtime

These tables describe how work is triggered, run, logged, and observed.

• routines
• routine_triggers
• routine_runs
• heartbeat_runs
• heartbeat_run_events
• activity_log
• run_file_writes
• run_output_artifacts
• issue_active_executions

This layer is where agent activity becomes durable. Heartbeats are the primary execution unit. run_file_writes and run_output_artifacts capture artifacts produced during a run. issue_active_executions tracks checkout and active execution state.

​

Finance And Performance

These tables answer the question: what did it cost, how did it perform, and what should change next?

• budget_policies
• budget_incidents
• cost_events
• finance_events
• performance_ledger
• performance_snapshots
• performance_signals
• performance_interventions
• performance_evaluations

The performance_ledger is the compact run-level record used for quality and cost analysis. performance_snapshots, performance_signals, performance_interventions, and performance_evaluations form the improvement loop.

​

Evaluation And Review

These tables support scoring, review queues, annotated judgment, and dataset curation.

• evaluation_queue_assignments
• evaluation_rubrics
• evaluation_runs
• evaluation_scores
• human_annotations
• evaluation_datasets
• evaluation_dataset_items

This layer is the bridge between runtime output and review. It is where the system turns outputs into measured quality.

​

Memory And Coordination

These tables hold the higher-level control and learning layer used for director mode, agent handoff, and memory-rich workflows.

• mom_control_contracts
• mom_skill_profiles
• mom_experience_records
• mom_a2a_messages
• mom_events

This is the “how agents work together” layer. It records contracts, skill profiles, experience histories, A2A coordination, and traceable memory events.

​

Plugins And Extensions

These tables describe first-party plugin metadata, not the external systems themselves.

• plugins
• plugin_config
• plugin_company_settings
• plugin_state
• plugin_entities
• plugin_jobs
• plugin_job_runs
• plugin_webhook_deliveries
• plugin_logs

Plugins can point at Linear, GitHub, Gmail, Slack, or similar tools, but the mapping and runtime state remain Paperclip-owned.

​

ER-Style Overview

This diagram shows the main relationships that matter day to day.

​

Where The Code Lives

The schema definitions live in packages/db/src/schema/. The main route and service surfaces follow the same groupings:

• identity and access
• company and org
• planning and execution
• runtime and automation
• finance and performance
• evaluation and review
• memory and coordination
• plugins and extensions

If you need the HTTP surface for a table family, open Schema Map.

​

Practical Rules

• Treat Postgres tables as canonical first-party state.
• Treat ClickHouse tables as derived analytics or observability facts unless the schema says otherwise.
• Treat plugin metadata as Paperclip-owned integration state.
• Treat external tool records as external, even when Paperclip correlates them with company, issue, or run IDs.

That separation is what keeps the model understandable as the system grows.