Session Metadata and Storage

SDK sessions are persisted by default under:

<projectRoot>/.downcity/agents/<agentId>/sessions/<sessionId>/messages/messages.jsonl

The same directory also contains:

<projectRoot>/.downcity/agents/<agentId>/sessions/<sessionId>/messages/meta.json

and the in-progress assistant snapshot:

<projectRoot>/.downcity/agents/<agentId>/sessions/<sessionId>/messages/inflight.json

Why storage is partitioned by agentId

Because multiple SDK agents can exist inside the same project directory.

agentId keeps their session data isolated.

This is also one of the reasons why id should not be treated as a casual display string.

What you can usually find here

• message history
• in-progress assistant snapshot
• session metadata
• archive directories

messages.jsonl stores stable history.

inflight.json stores the current unfinished assistant UIMessage. During multi-step tool execution, the SDK keeps rewriting this snapshot so already-produced text and tool parts survive interruptions. When execution finishes normally, the final assistant message is committed into messages.jsonl and inflight.json is removed.

If you are troubleshooting, replaying history, or running multi-agent experiments, this persisted data is extremely useful.

meta.json

meta.json stores the lightweight fields used by session lists and detail views:

• sessionId
• agentId
• title
• modelLabel
• createdAt
• updatedAt
• timezone

title is persisted. After the first user message, the SDK first tries to generate a title with the configured model. If generation fails, it writes a truncated version of the first user message as title.

Related docs

• SDK Session layout