Skip to main content
Atlas persists runtime activity to Postgres so you can replay discovery runs, audit sessions, and power evaluation reports. This reference summarizes the tables the SDK creates by default and how they relate to each other.

​
Overview

discovery_runs ─┐
                │
                ▼
            sessions ── plans / step_results / guidance_notes
                │
                ├─ trajectory_events
                │
                └─ learning_registry
  • discovery_runs captures onboarding metadata produced by atlas env init.
  • sessions stores per-request telemetry, review status, reward stats, and learning notes.
  • trajectory_events holds fine-grained telemetry (plan approvals, guidance, validations, tool calls).
  • learning_registry caches the latest playbooks per learning_key.
A complete schema is defined in atlas-sdk/atlas/runtime/storage/schema.sql. The sections below call out the columns you are most likely to query.

​
discovery_runs

ColumnTypeNotes
idSERIALPrimary key.
project_rootTEXTAbsolute path recorded during discovery; use it to group runs by repository.
taskTEXTSample task executed during discovery (--task).
sourceTEXTDefaults to "discovery"; other tooling can reuse the table by setting custom sources.
payloadJSONBThe discovery artefact (.atlas/discover.json equivalent).
metadataJSONBAdditional notes (preflight, scaffold results, template info).
created_atTIMESTAMPTZIngestion timestamp.
Link discovery runs back to runtime sessions through shared metadata (for example, metadata.learning_key or metadata.discovery.environment_factory entries).

​
sessions

ColumnTypeNotes
idSERIALPrimary key referenced by all child tables.
taskTEXTUser task prompt.
statusTEXTRuntime status (running, succeeded, failed).
metadataJSONBRich telemetry (adaptive summary, triage dossier, drift info, learning history, etc.).
final_answerTEXTStudent output persisted at completion.
reward / reward_stats / reward_auditJSONBJudge outputs and aggregate statistics.
student_learning / teacher_learningTEXTPer-session learning notes (pre-registry).
review_statusTEXTpending, approved, or quarantined. Defaults to pending.
review_notesTEXTReviewer-supplied context.
created_at / completed_atTIMESTAMPTZRun timing.
Three performance indexes optimize training data queries:
  • sessions_reward_score_idx: Functional index on (reward_stats->>'score')::float for 10-100x faster reward filtering
  • sessions_created_at_idx: Index on created_at DESC for 50-100x faster date range queries
  • sessions_metadata_gin_idx: GIN index on metadata JSONB for learning key queries
Use review_status to filter exports and harness runs, and join the metadata hash to inspect adaptive_summary, execution_mode, learning_history, or drift alerts.

​
Metadata Schema Fields (v0.1.13+)

The metadata JSONB column contains structured telemetry. Key fields accessible via AtlasSessionTrace dataclass: Essential fields:
  • session_reward: Aggregate reward with score and uncertainty
  • trajectory_events: Ordered list of runtime events
  • student_learning: Student persona learning notes
  • teacher_learning: Teacher persona learning notes
  • learning_history: Historical learning data
  • adaptive_summary: Mode selection (auto/paired/coach) and probe evidence
Property accessors (loaded on demand):
  • learning_key: Task identifier for grouping sessions
  • teacher_notes: Guidance provided during execution
  • reward_summary: Simplified reward statistics
  • drift: Detected schema or behavior drift
  • drift_alert: Critical drift warnings requiring review
  • triage_dossier: Pre-execution risk assessment
  • reward_audit: Detailed judge breakdowns
  • plans – JSON plan snapshot keyed by session_id.
  • step_results / step_attempts – per-step traces and validation payloads.
  • guidance_notes – ordered teacher guidance emitted during execution.

​
step_results Schema Fields (v0.1.13+)

Step-level telemetry accessible via AtlasStepTrace dataclass: Essential fields:
  • runtime: Step execution time in milliseconds
  • depends_on: Array of step IDs this step depends on (dependency graph)
Property accessors:
  • attempt_history: Previous attempt records if step was retried
Query step execution times and dependencies for performance analysis: 
-- Average step runtime by tool
SELECT
  metadata->>'tool' AS tool_name,
  AVG((metadata->>'runtime')::float) AS avg_runtime_ms
FROM step_results
WHERE metadata->>'runtime' IS NOT NULL
GROUP BY tool_name
ORDER BY avg_runtime_ms DESC;

​
trajectory_events

ColumnTypeNotes
idSERIALPrimary key.
session_idINTEGERForeign key to sessions.
eventJSONBEnvelope containing event_type, actor, timestamps, payload, etc.
created_atTIMESTAMPTZEvent timestamp.
The learning evaluation harness samples these events to count validations, guidance injections, and reward updates. Filter by event->>'event_type' to narrow to specific telemetry (e.g., reward, learning_playbook, tool_call).

​
learning_registry

ColumnTypeNotes
learning_keyTEXTPrimary identifier (task, project, or domain).
student_learningTEXTLatest student playbook body.
teacher_learningTEXTLatest teacher playbook body.
metadataJSONBOptional synthesizer audit info or hashes.
updated_atTIMESTAMPTZLast update timestamp.
The runtime loads this table at session start and updates it after successful learning synthesis (subject to learning.update_enabled). Join back to sessions via metadata.learning_key to reconstruct the history that produced the current playbook.

​
Query Examples

-- High-reward sessions for training (using performance index)
SELECT id, task, (reward_stats->>'score')::float AS reward
FROM sessions
WHERE (reward_stats->>'score')::float >= 0.8
  AND status = 'succeeded'
ORDER BY created_at DESC
LIMIT 1000;

-- Sessions awaiting review with drift alerts
SELECT id, task, metadata->'drift_alert' AS drift_alert
FROM sessions
WHERE review_status = 'pending'
  AND metadata ? 'drift_alert';

-- Latest playbooks for a service
SELECT learning_key, updated_at, student_learning
FROM learning_registry
WHERE learning_key LIKE 'service:%'
ORDER BY updated_at DESC;

-- Count validation events per session
SELECT session_id, COUNT(*) AS validation_events
FROM trajectory_events
WHERE event ->> 'event_type' = 'validation'
GROUP BY session_id;

-- Learning history for a task (using GIN index)
SELECT
  id,
  task,
  metadata->'learning_history' AS learning_history,
  (reward_stats->>'score')::float AS reward
FROM sessions
WHERE metadata @> '{"learning_key": "security-review"}'
ORDER BY created_at DESC;

-- Step performance analysis
SELECT
  s.task,
  sr.metadata->>'tool' AS tool,
  AVG((sr.metadata->>'runtime')::float) AS avg_runtime_ms,
  COUNT(*) AS step_count
FROM step_results sr
JOIN sessions s ON sr.session_id = s.id
WHERE sr.metadata->>'runtime' IS NOT NULL
GROUP BY s.task, sr.metadata->>'tool'
ORDER BY avg_runtime_ms DESC;