Managing state in adaptive dialogs


The terms Stateful and stateless are adjectives that describe whether an application is designed to remember one or more preceding events in a given sequence of interactions with a user (or any other activity). Stateful means the application does keep track of the state of its interactions, usually by saving values in memory in the form a property. Stateless means the application does not keep track of the state of its interactions, which means that there is no memory of any previous interactions and all incoming request must contain all relevant information that is required to perform the requested action. You can think of state as the bot's current set of values or contents, such as the conversation ID or the active user's name.

The Bot Framework SDK follows the same paradigms as modern web applications and does not actively manage state, however the Bot Framework SDK does provide some abstractions that make state management much easier to incorporate into your bot. This topic is covered in detail in the Bot Framework SDK Managing state article, it is recommended that you read and understand the information covered in that article before reading this article.


Managing state

A bot is inherently stateless. For some bots, the bot can either operate without additional information, or the information required is guaranteed to be contained within the incoming activity. For other bots, state (such as where in the conversation we are or the response received from the user) is necessary for the bot to have a useful conversation.

The Bot Framework SDK defines memory scopes to help developers store and retrieve values in the bot's memory, for use when processing loops and branches, when creating dynamic messages, and other behaviors in the bot.

This makes it possible for bots built using the Bot Framework SDK to do things like:

  • Pass information between dialogs.
  • Store user profiles and preferences.
  • Remember things between sessions such as the last search query or the last selection made by the user.

Adaptive dialogs provide a way to access and manage memory and all adaptive dialogs use this model, meaning that all components that read from or write to memory have a consistent way to handle information within the appropriate scopes.


All memory properties, in all memory scopes, are property bags, meaning you can add properties to them as needed.

Here are the different memory scopes available in adaptive dialogs, each with a link to additional information contained in the memory states reference article:

  • User scope is persistent data scoped to the ID of the user you are conversing with.
  • Conversation scope is persistent data scoped to the ID of the conversation you are having.
  • Dialog scope persists data for the life of the associated dialog, providing memory space for each dialog to have internal persistent bookkeeping.
  • Turn scope provides a place to share data for the lifetime of the current turn.
  • Settings scope represents any settings that are made available to the bot via the platform specific settings configuration system.
  • This scope persists data for the life of the associated action. This is helpful for input actions since their life type typically lasts beyond a single turn of the conversation.
  • Class scope holds the instance properties of the active dialog.

Memory short-hand notations

There are few short-hand notations supported to access specific memory scopes.

Symbol Usage Expansion Notes
$ $userName dialog.userName Short hand notation that represents the dialog scope.
# #intentName turn.recognized.intents.intentName Short hand used to denote a named intent returned by the recognizer.
@ @entityName turn.recognized.entities.entityName @entityName returns the first and only the first value found for the entity, immaterial of the value's cardinality.
@@ @@entityName turn.recognized.entities.entityName @@entityName will return the actual value of the entity, preserving the value's cardinality.
% %propertyName class.propertyName Used to refer to instance properties (e.g. MaxTurnCount, DefaultValue etc).

Additional information