Chat Sessions
Chat sessions are persistent conversation threads between a user and an agent. Each session captures the full exchange — messages, tool calls, model responses, and token usage — so you can resume, review, and export your work.
What a session is
Section titled “What a session is”A session belongs to a single user within an organization and is optionally scoped to a project. It records:
- The model used for the conversation
- A running count of messages and tokens
- A timeline of events stored for replay and analysis
Sessions are created automatically when you start a conversation in the CLI or Studio. You can also save, load, and manage sessions explicitly.
Session events
Section titled “Session events”Every interaction within a session is recorded as a typed event. Events are stored in order and include metadata like the model, role, tool name, and token counts.
| Event type | What it captures |
|---|---|
| User message | Text sent by the user |
| Agent response | Model-generated reply |
| Tool call | Tool invocation and its result |
| Generation start | Beginning of a model inference call |
| Generation end | Completion of inference with token counts |
| Heartbeat | Keepalive signal during long-running events |
Events are stored in ClickHouse for efficient querying and are partitioned by month.
Lifecycle
Section titled “Lifecycle”| Action | What happens |
|---|---|
| Create | Session is created when you start a conversation |
| Update | Message and token counts increment as the conversation grows |
| Title | An AI-generated title is produced from the first message |
| Archive | Session is soft-deleted and hidden from listings |
| Delete | Session and all its events are permanently removed |
Managing sessions
Section titled “Managing sessions”Sessions can be managed from the CLI or the API:
- CLI: Use
/save,/load,/sessions,/delete,/export, and/clearduring a conversation. See Chat & Sessions for the full command reference. - API: Sessions are available at
GET /api/v1/user/sessionand scoped to the authenticated user.
Project scoping
Section titled “Project scoping”Sessions can be associated with a project. When scoped to a project, sessions appear in that project’s context and their events contribute to project-level analytics. Unscoped sessions live at the organization level.