Session Storage

Session storage is profile-local. SQLite is authoritative; raw logs and blob files are recovery, retention, and large-payload storage helpers.

SQLite Repositories

Repository structs live under internal/state. The aggregate state.Repositories is passed into gateway/runtime services that need storage.

Do not bypass repositories from UI or channel code. Add repository methods and tests when a new query path is needed.

Sessions

SessionRecord stores the session ID, title, scope columns, provider/model snapshot, timestamps, archive status, and metadata.

Role is stored as profile-local persona metadata and legacy scope columns for compatibility. Role is not a profile or permission boundary.

Turns

Turn records track active and completed user turns. Gateway creates a running turn before calling the loop and updates status after completion, cancellation, approval stop, or error.

Messages

Messages store conversation parts. Attachment parts, tool-call parts, tool-result parts, and externalized raw references are represented as structured records.

Search and context windows should use repository queries instead of scanning raw files directly.

Tool Calls

Tool calls and results are stored separately from messages so audit, approval, debug, and result references can address them directly.

Large result content can be externalized to raw/blob storage while the visible result keeps a bounded preview.

Raw Logs And Blobs

Raw logs live under raw/YYYY/MM/DD/<session>.jsonl. Blob storage keeps large or binary payloads referenced by hash.

Maintenance code owns compaction, checkpointing, retention, raw reconciliation, and lifecycle migration. Create backups before destructive state maintenance.