DOCS · DURABILITY

Conversations & data

Cortex stores coding conversations and run history in a protected SQLite database owned by the server. Browser storage remains a convenience cache rather than the authoritative record.

Durable conversations

Open and archived conversations retain their workspace, title, provider, model, OpenCode session identity, state and ordered transcript events. Refreshing the browser—or opening Cortex from another browser—loads the server-side conversation history after authentication.

Legacy browser migration

Cortex considers browser-local records that are absent from the server for migration, one record at a time. A record that imports successfully becomes server-authoritative and is not reposted or overwritten on later boots. A rejected record remains browser-local with its transcript and can retry after correction even when the database already holds other conversations; established server conversations are never overwritten by stale browser copies.

Agent-run evidence

Each agent invocation records its conversation, prompt, state, start/finish time, OpenCode session identity, token counts, estimated cost and failure text. Conversation snapshots and run records are separate: the transcript provides the human view while run rows preserve execution history.

SQLite foundation

The database lives in Cortex's private data directory as cortex.db, uses numbered transactional migrations, foreign-key enforcement, WAL journaling, a busy timeout and restrictive file permissions. Startup rejects a database schema newer than the running Cortex binary rather than guessing how to interpret it.

Single-binary frontend

Nift remains the source frontend workflow: content/ and templates/ build into public/. Go embeds that generated output, so release archives and go install produce a self-contained Cortex executable. --static and CORTEX_STATIC_DIR remain development/custom-deployment overrides.

Consistency and recovery

Conversation, event and run changes use SQLite transactions. The legacy browser migration imports each record independently: a structurally invalid record is reported without discarding the valid records around it, and an unavailable workspace does not block a record from importing with its transcript. Re-running the same import is idempotent, so a retry never duplicates conversations or events. The browser consumes the deterministic imported/rejected result: only successfully imported records leave browser storage, rejected records are preserved locally with their transcripts and visibly marked, and they are retried automatically on a later boot or via Retry import — even when the database already holds other conversations. A restart marks any persisted running work interrupted before serving clients. Lists and searches are capped at 250 results; narrow the query when the cap is exceeded.

Historical workspaces

Cortex keeps the transcript and metadata of every conversation even when its historical workspace is no longer available. A workspace may be missing (the repository was moved or deleted), renamed, inaccessible, or outside the current --root. Cortex stores the recorded path verbatim and never silently replaces it with the current root. The browser marks such conversations visibly as unavailable and disables Run for them; the transcript stays intact. To keep working with an old conversation, open the workspace picker and select a valid replacement — Run re-enables only after the new workspace passes the same strict root and symlink checks. The execution boundary itself is unchanged: a missing, renamed, inaccessible, out-of-root or symlink-escaping workspace is never used for browsing or agent execution.

Database and accounting

Cortex uses owner-only SQLite with foreign keys, WAL and FULL synchronization. Migrations are transactional and a database newer than the running binary is refused. Token counts and estimated cost come from provider/OpenCode events; use provider billing records for financial reconciliation.