SDK Session Layout

Local SDK Agent Sessions are persisted under ~/.downcity; tests and multi-instance hosts can override the internal root with DC_PLATFORM_ROOT:

~/.downcity/agents/<agent_id>/workspaces/<workspace_id>/sessions/<session_id>/
├── meta.json
└── messages/
    ├── active.jsonl
    ├── assistant_message.json
    └── segments/
        └── <start_sequence>-<end_sequence>.jsonl

workspace_id locates the Workspace data root, and session_id is unique within that Workspace. meta.json records the owning agent_id and workspace_id; an Agent's Session list returns only matching metadata. The project directory never receives a .downcity directory.

• active.jsonl: complete SessionMessage snapshots retained after the latest Compact.
• assistant_message.json: the one complete in-progress Assistant draft.
• segments/*.jsonl: immutable history ranges with real Messages first and a cumulative Summary footer last.
• meta.json: a lightweight index of Agent and Workspace ownership, title, model label, timestamps, message count, and storage bytes; it never stores the runtime model instance.

Segment filenames use zero-padded 12-digit sequences, such as 000000000001-000000000900.jsonl. There is no manifest; scanning filenames determines history order. A Summary is not a Message and consumes no sequence.

Applications should call session.messages() for Active and use before_sequence to load older Segments. Do not write these files directly.

See Session metadata and storage for progression, Compact, and recovery behavior.