Sessions

A conversation is a file with a .sss extension. That is the whole idea: no database, no account, no server-side session id.

Where they live

dox-data/agent/sessions/
  20261021-110716-yggu.sss
  20261020-224510-3kfa.sss

Change DOX_DATA_DIR and the whole folder moves with it. Copy the folder and you have every conversation; delete the folder and you start clean.

The filename

YYYYMMDD-HHmmss-<4 base36>.sss

The timestamp gives you readable ordering. The four random characters exist because the timestamp only has one-second resolution: two sessions created in the same second would otherwise collide. defaultSessionPath() also checks whether the name is already taken and draws another random string if so.

The name is not the identity. The path is. Rename a .sss file in the explorer and the agent opens it by its new path; nothing stored inside refers to the filename.

The file

{
  "title": "How does dox persist a workspace?",
  "updatedAt": 1761055200000,
  "messages": [
    { "role": "user", "content": "Where does dox store a layout?" },
    { "role": "assistant", "content": [
      { "type": "thinking", "thinking": "…" },
      { "type": "text", "text": "Let me look at saveState." },
      { "type": "tool_use", "id": "toolu_…", "name": "bash", "input": { "command": "…" } }
    ]},
    { "role": "user", "content": [
      { "type": "tool_result", "tool_use_id": "toolu_…", "content": "…" }
    ]}
  ]
}

Three fields, and the messages array follows the Anthropic messages format directly.

title is derived from the first user message unless you rename the session.

What is stored besides the messages

Three optional fields pin the configuration the conversation was started with:

Field	Meaning
`model`	id of a model file in `models/` (`"mify-claude"`)

It is written only when you pick a model explicitly. A session without it follows config.defaultModel at the time — which is what older sessions do.

Credentials never enter a session file. apiKey lives only in models/*.env, so a .sss can be copied or shared without leaking a key.

What is not stored

The system prompt
The tool definitions
The base URL and key

Those live in the model file and are resolved on every request.

Opening and sharing

Where	How
Explorer	Double-click a `.sss` row — the row shows title, turn count and timestamps from `/api/session-meta`
Agent	Paste a path into the address bar
GUI	`?path=` in the agent URL, or the manifest event `sessionClick → loadSession`
TUI	`/open <path>`
Anywhere else	It is a JSON file; `jq` and `cat` work

Paths can be absolute, or relative to sessions/; the .sss suffix is appended if you leave it off.

The TUI shares them

node app/agent/tui/main.ts reads the same folder. A conversation started in the browser continues in the terminal, and vice versa, because both resolve paths the same way and both write through store.ts.

Migration from the old format

Before sessions were paths, they were ids in a sessions.json index. That compatibility layer is gone. If you have an old install:

Every conversation already exists as an individual file in dox-data/agent/sessions/
Files without .sss are ignored — rename them: mv <old> <old>.sss
Delete sessions.json if it still exists

Nothing inside the files needs to change; the message format is the same.