Any good chatbot probably needs to be able to save and work with information gathered from the user at some point. The memory API provided in CSML is one of the most important parts of the language.
As you will see, some variables need to be stored in a long-term memory, while some variables are just temporary variables needed for local work. Some information is also provided by the context of the user and injected by the channel itself at the beginning of the conversation.
In this chapter, we will see how to save and use various types of memories depending on your scenario.
Inside any given step, a number of global variables are made available to the developer. These variables include past memories, step context, and request metadata. Some of these variables are available globally, including in CSML functions:
event: contains the user input, or NULL when empty. See The Event.
_metadata: read-only object that is injected into the conversation by the channel.
Usage: _metadata.something
_env: read-only object containing the bot's defined environment variables.
Usage: _env.something
_memory: read-only object containing the user's current memory state. This is especially helpful if you need to print the full state of the user's memory for debugging purposes!
The _metadata global contains user-level context for each request.
This memory type is injected by the channel at the beginning of the conversation and contains any data that the channel already knows about the user that can be used in the conversation later. For example, this could include the user's full name or email address, their job title, where they are from...
The _context can be found under _metadata and contains current_step, current_flow and default_flow
This memory type is injected and updated automaticaly at the start of each step
The _env global contains bot-level context for the entire bot and is shared across all users of the bot.
This memory type is injected by the bot itself and is meant to contain any data that the bot would need for common tasks across all users. For example, this is where you store the API keys, endpoints, feature flags...
To output the value of any variable in a string, you can use the string interpolation helper: double curly braces {{ }}.
This makes it extremely easy to concatenate multiple values of any type into a single string. Objects, arrays and numbers will be stringified automatically and missing properties will be evaluated as NULL.
To concatenate two strings, you can also use the + operator (starting in CSML v1.8.0):
Local or temporary variables are only usable within the current step. It is rather a way to write more readable, expressive code. But they are really powerful, because they allow you to do everything that a regular memory does, but temporarily. For more information about local variables, see the as keyword.
Local variables are useful for temporary calculations. You do not want to memorize your internal temporary steps, rather save useful information about the user.
Long-term memories on the other hand are at the core of the purpose of CSML. When two persons converse, they constantly memorize information, which they can reuse in other discussions. For example, if I gathered that my friend likes Iron Man, I might propose later that we go see Captain America together. I do not have to ask them again about their favorite film, because I already learned this information before, even if it was in a different conversation, even if the topic of that conversation might have been completely unrelated.
The memory API is very powerful: by default a bot never forgets anything about the current user. For more information, see the remember keyword.
CSML provides a _memory global, read-only variable, which contains all variables saved until now for the current user. This especially useful if you need to debug the state of a user's memory at any given step:
Variables and memories (of any type) can not be larger than 50KB. Using data larger than 50KB in variables (for example as the return value of a function) may result in undefined behavior. Also, please note that messages larger than 30KB in size can not be displayed in the test webapp.