SDK Session Layout

Local SDK Agent Sessions are persisted under:

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

agent_id isolates Agents in the same project and session_id isolates each continuous conversation.

• 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 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.