Session state management

Agent Builder is currently in preview and is subject to change. Features described in this pattern may evolve in future releases.

Overview

AI nodes in FlowX workflows are stateless — each invocation starts fresh with no memory of previous turns. For multi-turn conversations such as chatbots, advisors, or guided flows, you need a strategy to persist and reload conversation history between interactions. This pattern uses a FlowX Database data source to store session state, loading it at the start of each turn and saving the updated history after the AI response.

When to use

Multi-turn chatbots or conversational assistants
Guided workflows where the AI needs context from earlier steps
Any scenario where the user returns to a conversation after a delay
Task-oriented workflows requiring custom memory strategies

Architecture

The session state management pattern follows a read-process-write cycle on every turn:

User message
  → Load session (DB read)
    → Inject history into prompt
      → AI processing
        → Append exchange to history
          → Save session (DB write)
            → Response to user

Each workflow invocation performs these steps:

Load — Query the ChatSessions data source by sessionId to retrieve existing conversation history.
Inject — Insert the retrieved history into the AI node’s operation prompt as context.
Process — The AI node generates a response informed by the full conversation context.
Append — Add both the user message and the AI response to the messages array.
Save — Write the updated session back to the data source.

Data model

Create a FlowX Database data source named ChatSessions with the following schema:

Field	Type	Description
sessionId	`STRING`	Unique identifier for the conversation session
messages	`OBJECT[]`	Array of message objects storing the conversation history

Each entry in the messages array follows this structure:

Field	Type	Description
role	`STRING`	The message author — `user` or `assistant`
content	`STRING`	The text content of the message

Example stored session:

{
  "sessionId": "sess-a1b2c3d4",
  "messages": [
    { "role": "user", "content": "I want to apply for a mortgage." },
    { "role": "assistant", "content": "I can help with that. What type of property are you looking to finance?" },
    { "role": "user", "content": "A single-family home, around 250,000 EUR." },
    { "role": "assistant", "content": "Great. Do you have a preferred loan term — 15, 20, or 30 years?" }
  ]
}

Implementation

Create the ChatSessions data source

In the Integration Designer, add a new FlowX Database data source named ChatSessions. For its collection schema, select a project data model type with a sessionId attribute (type STRING) and a messages attribute (type OBJECT with the Array flag).

Load session history at workflow start

Add a Database Operation node at the beginning of your workflow, configured with a findOne operation that reads from ChatSessions, filtering by the incoming sessionId. If no session exists, initialize an empty messages array.

Inject history into the AI node context

In the AI node’s Context field, include the loaded conversation history. Format the messages array into a readable block:

Previous conversation:
User: I want to apply for a mortgage.
Assistant: I can help with that. What type of property are you looking to finance?
User: A single-family home, around 250,000 EUR.
Assistant: Great. Do you have a preferred loan term — 15, 20, or 30 years?

Current user message: {currentMessage}

Use a Script node before the AI node to transform the messages array into this string format, and reference the result in the AI node’s Context field with a ${...} key.

Append the new exchange to history

After the AI node produces a response, use a Script node to append two new entries to the messages array:

[
  { "role": "user", "content": "{currentMessage}" },
  { "role": "assistant", "content": "{aiResponse}" }
]

Save the updated session

Add a Database Operation node that writes the updated session back to the ChatSessions data source. Use an updateOne operation keyed by sessionId for existing sessions; when the initial findOne returned no session, route to an insertOne operation instead (for example, via a Condition node on the load result).

Context window management

Long conversations can exceed the AI model’s context window or degrade response quality. Use these strategies to keep history manageable:

Summarization

For conversations exceeding a threshold (for example, 20 turns), use a separate AI node to generate a summary of older messages. Replace the full history with:

Summary of earlier conversation:
The user is applying for a 30-year mortgage on a 250,000 EUR single-family home.
They have a 50,000 EUR down payment and prefer a fixed rate.

Recent conversation:
User: What documents do I need to provide?
Assistant: You will need proof of income, bank statements, and a property appraisal.

This preserves key context while staying within token limits.

Token counting

Track approximate token usage for the history block. When it approaches 60-70% of the model’s context window, trigger summarization. This leaves sufficient room for the system prompt, current message, and the AI response.

Real-world example

The Mortgage advisor chatbot tutorial shows multi-turn advising using the built-in session memory. Use that tutorial for a Chat Driven walkthrough; refer to this pattern if you need a custom memory strategy (sliding window, topic-based, cross-session) for a task-oriented workflow instead. For the tutorial, see the Mortgage advisor tutorial.

Variations

Sliding window

Keep only the last N turns (for example, 10) in the prompt context. Older messages remain stored in the database for audit purposes but are not injected into the prompt. This is the simplest approach and works well for short, focused conversations.

Topic-based memory

Partition conversation history by topic. When the user switches subjects, start a new topic segment while retaining a brief summary of previous topics. This works well for advisor-style bots that cover multiple domains in one session.

Cross-session memory

Maintain a persistent user profile that carries context across separate conversations. Store preferences, decisions, and key facts in a dedicated data source keyed by user ID rather than session ID. Inject a profile summary at the start of each new session so the AI can reference prior interactions.

AI patterns overview

All available AI integration patterns

Chat-driven workflows

Built-in session memory in FlowX 5.6+

Mortgage advisor tutorial

End-to-end chatbot with session persistence

Intent classification pattern

Route user messages to specialized handlers

Cookbooks

Tutorials

AI patterns

Session state management

Overview

When to use

Architecture

Data model

Implementation

Context window management

Summarization

Token counting

Real-world example

Variations

Sliding window

Topic-based memory

Cross-session memory

AI patterns overview

Chat-driven workflows

Mortgage advisor tutorial

Intent classification pattern

​Overview

​When to use

​Architecture

​Data model

​Implementation

​Context window management

​Summarization

​Token counting

​Real-world example

​Variations

​Sliding window

​Topic-based memory

​Cross-session memory

​Related resources

AI patterns overview

Chat-driven workflows

Mortgage advisor tutorial

Intent classification pattern

Overview

When to use

Architecture

Data model

Implementation

Context window management

Summarization

Token counting

Real-world example

Variations

Sliding window

Topic-based memory

Cross-session memory

Related resources