Chats, sessions, and turns

MarkDB organizes agent activity into three nested levels.

Turn

A turn is one unit of the conversation: a user message, or an assistant response together with its thinking and tool invocations. Turns are the smallest retrievable unit.

Session

A session is a single bout of work -- one "sitting" with the agent. A session groups the turns that happened together in time.

Chat

A chat is a single conversation thread that can span many sessions over days, weeks, or months. A chat is identified by a stable chat_key.

How sessions roll over

Within a chat, MarkDB keeps appending to the active session while the conversation is live. After a configurable idle gap (3 hours by default), the next request rolls into a new session row while preserving the same chat_key. This keeps a long-running chat stitched together while still marking the natural breaks between sittings.

chat (chat_key = abc...)
├─ session 1   (Monday morning)
│   ├─ turn, turn, turn
├─ session 2   (Monday afternoon, after a 3h+ gap)
│   ├─ turn, turn
└─ session 3   (Wednesday)
    └─ turn

For clients that rotate session ids on every request (like Cursor), MarkDB derives the chat_key from the opening messages so the chat stays a single thread instead of fragmenting into one session per request.