Sessions

Session Metadata and Storage

SDK Session metadata, message files, and directory layout

Session Metadata and Storage

SDK sessions are persisted by default under:

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

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
session metadata
archive directories

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

SDK Session layout

session.fork()

Copy the current Session into a branch for trying alternate directions

Embed in a Node App

Recommended pattern for creating and using a local Agent directly inside a Node.js application

Table of Contents

Session Metadata and Storage Why storage is partitioned by agentIdWhat you can usually find here Related docs