Skip to main content

Session State

Session state is a crucial concept in Flows that is automatically handled behind the scenes, enabling persistence of data across multiple Flow requests within the same interaction context. While most of the session management is done for you, you can also interact with the session state when needed for custom functionality.

Understanding Sessions​

A session represents a continuous interaction context, typically linking Flow requests together. For example:

  • In a chat conversation, all messages between the user and the system belong to the same session
  • During a multi-step form submission, each step's data is part of the same session
  • When an LLM needs context from previous interactions, it accesses the session's message history

Session State Storage​

Each session maintains a persistent state that can be accessed by the Flow. The session state system provides two main interfaces:

export interface ISessionState {
    get(key: string): Promise<ISessionStateStore>;
    set(key: string, value: ISessionStateStore): Promise<void>;
    delete(key: string): Promise<void>;
}

export interface ISessionStateStore {
    getMessages(): Promise<ChatMessage[]>;
    addMessage(message: ChatMessage): Promise<void>;
    setVariable(key: string, value: any): Promise<void>;
    getVariable(key: string): Promise<any>;
}

Stores​

A session can contain multiple stores, and each store can maintain:

  1. A list of messages (particularly useful for chat applications)
  2. Variables (key-value pairs for storing arbitrary data)

Common Use Cases​

Chat History​

The Memory Node automatically handles chat message storage in the session state, which:

  • Automatically maintains conversation history
  • Provides context to LLMs without manual intervention
  • Enables coherent multi-turn conversations out of the box

Form Data​

When needed, you can manually store and retrieve form data across multiple steps:

// Store form field
await sessionState.get("formData").setVariable("firstName", "John");

// Retrieve form field later
const firstName = await sessionState.get("formData").getVariable("firstName");

Monitoring State Changes​

You can observe session state changes in traces, which show:

  • Initial state at the start of a Flow request
  • Final state at the end of a Flow request

Important: If a Flow request fails due to a runtime error, the session state is not updated, ensuring data consistency.