Sessions

How conversation context is maintained across multiple messages.

How Sessions Work

Every chat request either creates a new session or continues an existing one. Sessions store the conversation history so the agent can reference previous messages and prior structured results.

Automatic Creation

When you send a chat request without a session_id, a new session is created automatically. The response includes the new session ID in the first SSE event:

{"type": "session", "session_id": "550e8400-e29b-41d4-a716-446655440000", "is_new": true}

Save this session_id and pass it in subsequent requests to continue the conversation.

Context Window

When continuing a session, Galadri loads the conversation summary when one exists, then the most recent messages in chronological order. Stored capability results are compacted into the history automatically, and each historical message includes its UTC send time. By default, compaction starts around 10 recent messages or roughly 5,000 recent-message tokens.

Developers can adjust the per-agent auto compaction limits in the console. Compaction runs when either the recent message limit or recent token limit is crossed, whichever happens first. These are soft triggers, not hard cutoffs. Compaction runs in the background and does not interrupt the live turn, so recent history can temporarily exceed the configured trigger while compaction finishes. By default, the live window can temporarily expand to 50 recent messages and about 20,000 recent-message tokens, still bounded by the selected model context length. The configurable trigger floor is 10 messages and 5,000 tokens unless the selected model context is smaller, and the token limit cannot exceed the selected model's context length.

Cross-Channel Context

Web chat, email, and SMS sessions stay separate so each channel can keep the right user experience. When another visible channel has recent activity for the same end user, Galadri adds a small cross-channel brief to the next agent turn. The brief identifies the current channel and includes a bounded set of recent transcript excerpts from other channels, excluding hidden sessions.

Agents are instructed that the same end user may interact through web chat, SMS, email, and voice. If the supplied brief is not enough to answer safely, the agent can use conversation history search for deeper same-user recall.

Runtime Data Context

At the start of each request, Galadri builds a scoped data snapshot for the end user. The profile is always included when available. The remaining sections are included only when the agent has relevant enabled capabilities, so the model receives useful context without loading unrelated records.

• End-user profile, including contact fields, location, unit preferences, currency, readiness score, and long-term memory notes
• Up to 10 vehicles and 10 vehicle groups when vehicle-aware capabilities are enabled
• Next 5 upcoming schedules and last 3 recent schedules when schedule-aware capabilities are enabled
• Next 5 upcoming milestones and last 5 recent milestones when vehicle-aware capabilities are enabled
• Last 5 documents when document-aware capabilities are enabled

If a start hook runs before the answer and changes managed data, Galadri refreshes this scoped data snapshot before the model continues. See runtime hooks for the supported customization points.

Async Continuations

Some capabilities finish after the user's original chat request has already returned. For example, an agent can call a repair shop, receive the post-call result later, and then continue the same chat session with a new assistant update. Galadri stores the external communication result as session context, runs the owning agent again, and appends the assistant's follow-up message to the same session.

The user does not need to keep the app open for the result to be saved. Galadri deduplicates repeated delivery attempts for the same communication result and separately deduplicates the follow-up assistant turn. If a worker is interrupted after claiming the continuation, Galadri can retry with the same assistant message id instead of billing a hidden failed turn. If your client subscribes to session message changes, it can render the new assistant message when it arrives. When the agent has thinking enabled, the follow-up message may include stored thinking content. When streaming is enabled, Galadri may update the assistant message while it is being generated instead of waiting for the final text.

Hidden Sessions

Set "overrides": { "hidden": true } when creating a new session to mark it as hidden. Hidden sessions function identically at runtime. The flag is for your application's chat history UI, so you can exclude background or automated sessions from end-user-visible history.

Hidden sessions are still persisted, returned by the Sessions API unless you filter them, and visible in the Galadri Console data browser for auditing and debugging. Use cases:

• Automated background tasks, such as nightly data enrichment or report generation
• System-initiated interactions (proactive recall checks, maintenance reminders)
• Internal testing or monitoring

Session Properties

List sessions via the Sessions endpoint.