SDK Session layout

A local SDK Agent stores Sessions under the City-provided storage root, usually ~/.downcity:

~/.downcity/agents/<agent_id>/sessions/<origin_type>/<session_id>/
├── session.db
└── attachments/

A Session is identified by (origin.type, session_id); the default partition is chat. Other non-empty origin types are safely encoded as one directory segment. The project directory never receives a .downcity directory.

Core session.db tables:

• session_state: identity, Workspace ownership, title, model label, timestamps, and system snapshot.
• messages: the User/Agent Message envelope.
• message_parts: each Part and its content, ordered by sequence.

A Composer Policy may maintain its own composer_<policy>_* derived tables in the same database. Derived tables can be rebuilt without changing canonical Messages. Use session.messages() to read history; do not write these files or tables directly.

See Session metadata and storage for the full design.