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, 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.
An index exists on metadata->>'learning_key' so you can quickly pivot by learning thread. Use review_status to filter exports and harness runs, and join the metadata hash to inspect adaptive_summary, execution_mode, or drift alerts.
  • 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.

​
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 pamphlet.

​
Query Examples

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

-- 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;
⌘I