Sessions & Persistence

Every Athena run is persisted to SQLite. You can resume any session, inspect its history, and pick up where you left off.

Storage Location

~/.config/athena/sessions/<session-uuid>/session.db

Each session gets its own isolated database file.

Schema

Five tables:

session

id TEXT, project_dir TEXT, created_at INTEGER, updated_at INTEGER,
label TEXT, event_count INTEGER

runtime_events

Raw hook events as received from the agent harness.

id TEXT, seq INTEGER UNIQUE, timestamp INTEGER, hook_name TEXT,
adapter_session_id TEXT, payload JSON

feed_events

Derived display events for the UI. One runtime event can produce multiple feed events.

event_id TEXT, runtime_event_id TEXT, seq INTEGER UNIQUE,
kind TEXT, run_id TEXT, actor_id TEXT, timestamp INTEGER, data JSON

adapter_sessions

Agent session records with token accounting.

session_id TEXT, started_at INTEGER, ended_at INTEGER, model TEXT, source TEXT,
tokens_input INTEGER, tokens_output INTEGER, tokens_cache_read INTEGER,
tokens_cache_write INTEGER, tokens_context_size INTEGER

schema_version

Migration version tracking.

Resume

Resume the most recent session:

athena-flow resume

Resume a specific session:

athena-flow resume <session-uuid>

Browse sessions interactively:

athena-flow sessions

Resume works by replaying feed_events from the store back into the timeline.

WAL Mode

The database uses WAL (Write-Ahead Logging) with an exclusive write lock. This allows Athena's session registry to read sessions from other instances without contention.

Degraded Mode

If the database cannot be opened (disk full, permissions), Athena continues in degraded mode — events are processed and displayed but not persisted. The header indicates degraded state, and session resume is unavailable.

Ephemeral Mode

Skip persistence entirely:

athena-flow exec "check status" --ephemeral

No session database is created.