Memory and State

Agents on the platform use two kinds of memory: session memory and persistent memory. Learn how to declare, access, and manage session variables, persistent memory, and set up auto-recall using the ABL Editor.

Key Concepts

Concept	Description
Session Memory	Declare and use variables that hold data within a single conversation — collected values, flags, and intermediate results that are discarded when the session ends.
Persistent Memory	Store facts that survive across sessions, such as user preferences and history. Covers user-scoped, project-scoped and execution-tree scoped variables and access control.
Recall	Automatically loads values from persistent memory into session context at lifecycle events like session start or before a search.
Remember Triggers	Automatically stores values into persistent memory when a condition is met.
Manipulate State: SET, CLEAR, and TRANSFORM	Assign values, remove variables, and reshape data arrays during flow execution using `SET`, `CLEAR`, and `TRANSFORM` directives.
Best Practices	Recommended patterns for naming variables, providing fallback values, and managing reset behavior.

Session Memory

Session variables hold data that is relevant only during a single conversation. They are created when the session starts and discarded when the session ends (unless RESET: never is specified).

Declare session variables

Add a MEMORY: block with a session: section to your agent definition in the ABL editor.

AGENT: Booking_Agent
GOAL: "Help users book hotels"

MEMORY:
  session:
    - selected_booking
      TYPE: string
      DESCRIPTION: "The booking ID the customer is currently managing"
    - action_type
      TYPE: string
      DESCRIPTION: "What the customer wants to do"
    - pending_changes
      TYPE: object
      DESCRIPTION: "Proposed changes awaiting confirmation"
    - quoted_fee
      TYPE: number
      DESCRIPTION: "Fee quoted for the pending modification"

Session Variable Properties

Property	Type	Required	Description
name	string	Yes	Variable name, used as the key in session context.
TYPE	string \| number \| boolean \| date \| array \| object	No	Value type for runtime validation and field resolution.
DESCRIPTION	string	No	Human-readable description of the variable’s purpose.
INITIAL	any	No	Initial value assigned when the session starts. Initial value is `null` by default.
RESET	per_session \| per_step \| never	No	When to reset the variable. Default is `per_session`. See Reset behavior.

Reset Behavior

Value	Behavior
per_session	Variable is initialized at session start and cleared when the session ends. This is the default.
per_step	Variable is reset to its initial value at the start of each flow step. Useful for step-scoped accumulators.
never	Variable persists for the lifetime of the runtime process. Use sparingly; prefer persistent memory instead.

For simple tracking without type metadata, declare a bare name:

MEMORY:
  session:
    - customer_id
    - order_total

Fields with initial values and reset control:

MEMORY:
  session:
    - cart_items
      TYPE: array
      DESCRIPTION: "Items currently in the shopping cart"
      INITIAL: []
      RESET: per_session
    - attempt_count
      TYPE: number
      INITIAL: 0
      RESET: per_step

Access session variables in response templates

Reference session variables by name inside {{ }} in RESPOND blocks.

FLOW:
  confirm_booking:
    REASONING: false
    RESPOND: |
      Booking summary:
      Hotel: {{selected_hotel.name}}
      Guest: {{guest_name}}
      Total: ${{quoted_fee}}
    THEN: COMPLETE

Access session variables in step conditions

Use session variables in CHECK, constraint expressions, and ON_INPUT transition logic.

FLOW:
  check_eligibility:
    REASONING: false
    CHECK: attempt_count < 3
    ON_FAIL: too_many_attempts
    THEN: process_request

Troubleshooting

Variable is undefined in template. The variable has not been set yet in the current flow. Ensure the step that sets it executes before the step that reads it.
Variable resets unexpectedly. Check RESET. Variables with RESET: per_step clear at each step transition. Use per_session or never for longer-lived values.
Type mismatch at runtime. TYPE enables runtime validation. If you declare TYPE: number but assign a string, the runtime logs a warning. Coerce tool results and user inputs to the declared type.

Persistent Memory

Persistent variables are stored in the platform’s fact store and survive across sessions. Persistent memory fields are scoped to a user, a execution chain or an entire project.

Declare persistent variables

Add a persistent: section under MEMORY:. Use dot-notation paths to name each variable and bind them to a scope.

AGENT: Support_Agent
GOAL: "Help customers with personalized support"

MEMORY:
  persistent:
    - user.preferred_language
    - user.loyalty_tier
      SCOPE: user
    - user.booking_history
      SCOPE: user
      TYPE: array
      DESCRIPTION: "Recent booking history"
    - user.notification_preference
      TYPE: string
      DEFAULT: "email"
      SCOPE: user

Persistent Variable Properties

Property	Type	Required	Default	Description
path	string	Yes	—	Dot-notation path (e.g., user.preferred_chains), where the first segment indicates the scope(user, project or workflow) and second indicates the name of the field.
SCOPE	user \| project \| execution_tree	No	user	Ownership scope. user is per-user; project is shared across all users. execution_tree is for an entire execution workflow across agents. If this scope differs from the scope in the path, scope takes precedence.
ACCESS	read \| write \| readwrite	No	readwrite	Access direction. Constrains whether the agent can read, write, or both.
TYPE	string \| number \| boolean \| date \| array \| object	No	—	Value type for runtime validation.
UNIT	string	No	—	Unit of the stored value (e.g., USD, km). Informational metadata only.
DEFAULT	any	No	null	Default value when no fact exists in the store.
DESCRIPTION	string	No	—	Human-readable description.

Scoping rules

Scope	Description
User scope (SCOPE: user)	Values are unique per authenticated user. Two users in the same project see different values for the same path.
Project scope (SCOPE: project)	Values are shared across all users within the project. Useful for reference data, feature flags, or global configuration.
Execution-tree scope (SCOPE: execution_tree)	Values are shared across one workflow / handoff tree only. This is the preferred scope for cross-agent state such as auth tokens, selected account IDs, or in-flight case context.

MEMORY:
  persistent:
    - user.preferred_chains
      SCOPE: user
      DESCRIPTION: "User's preferred hotel chains"

    - user.wire_history_30d
      SCOPE: user
      TYPE: array
      ACCESS: readwrite
      DEFAULT: []

    - project.exchange_rates
      SCOPE: project
      ACCESS: read
      DESCRIPTION: "Current exchange rates (shared across all users)"

Access Control

Restrict whether the agent can read, write, or both for each persistent path.

MEMORY:
  persistent:
    - user.preferences
      ACCESS: readwrite

    - user.account_status
      ACCESS: read

    - user.interaction_log
      ACCESS: write

Value	Behavior
`read`	Agent can read but not modify the value.
`write`	Agent can write but not read the current value.
`readwrite`	Agent can both read and modify. (Default.)

Access Persistent Variables in Expressions

Use the full dot-notation path within {{ }} to read persistent variables in SET expressions and RESPOND templates.

SET: greeting = COALESCE(user.name, "valued customer")
RESPOND: "Welcome back, {{greeting}}! Your tier is {{user.loyalty_tier}}."

Troubleshooting

Persistent value is null on first session. The value has not been stored yet. Use DEFAULT to provide a fallback, or use COALESCE() in expressions.
Value not persisting across sessions. Ensure the value is written using a remember trigger or SET statement. Declaring a persistent path does not automatically populate it.
Wrong user sees another user’s data. Verify SCOPE: user is set. Project-scoped variables are shared. User-scoped variables require user authentication to resolve correctly.

Remember Triggers

Remember triggers write values to persistent memory when a condition evaluates to true during conversation.

AGENT: Support_Agent
GOAL: "Help customers with personalized support"

MEMORY:
  persistent:
    - user.name
    - user.language
    - user.booking_history

  remember:
    - WHEN: user_name IS SET
      STORE: user_name -> user.name
      TTL: "90d"
    - WHEN: preferred_language IS SET
      STORE: preferred_language -> user.language

When user_name gets a value during the conversation (from a GATHER step, SET assignment, or tool result), the trigger fires and stores it to user.name. TTL: "90d" means the stored fact expires after 90 days. Remember Trigger Properties

Property	Type	Required	Default	Description
WHEN	string	Yes	—	Condition expression that triggers the store operation. Evaluated after each turn.
STORE	object	Yes	—	Defines the value expression and the target persistent path. Syntax: `value_expr -> target_path`.
TTL	string	No	—	Time-to-live for the stored fact. After expiration, the value is deleted. Examples: “30d”, “24h”. TTL values use a duration string: s - Seconds, m - Minutes, h - Hours, d - Days

Store computed values

Store a computed object instead of a raw variable value.

MEMORY:
  remember:
    - WHEN: action_completed == true
      STORE: {booking_id: selected_booking, action: action_type, date: now} -> user.booking_history

Recall

Recall automatically stores values into persistent memory when conditions are met, and loads stored facts back into the session at specific lifecycle events.

Add recall instructions

MEMORY:
  recall:
    - ON: session:start
      ACTION: inject_context
      PATHS: [user.name, user.language, user.preferred_agent]
    - ON: session:start
      ACTION: prompt_llm
      INSTRUCTION: "Greet the user by name if known"

When a new session starts, the platform loads user.name, user.language, and user.preferred_agent from persistent memory and injects them into the session context. Recall Properties

Property	Type	Required	Description
ON	string	Yes	Lifecycle event that triggers the recall. See Events.
ACTION	string	No	The concrete action to execute. See Actions.
INSTRUCTION	string	No	Human-readable instruction for the recall behavior.
PATHS	array	No	Persistent paths to inject (for inject_context action).
DOMAIN	string	No	Memory domain filter (for load_memory action).

Recall Events

Event	When it fires
session:start	When a new session initializes, before any user input.
search:before	Before a search or retrieval operation.

Recall Actions

Action	Behavior
inject_context	Loads specified persistent paths directly into session variables.
load_memory	Loads all facts in the specified domain into context.
prompt_llm	Passes the instruction text to the LLM as additional context. (Default.)

Recall before search operations

Load relevant user context before a knowledge base search executes.

MEMORY:
  recall:
    - ON: search:before
      ACTION: load_memory
      DOMAIN: "travel_preferences"

This loads all facts tagged with the travel_preferences domain into the session, allowing the search to incorporate user preferences.

Inject recalled data as an LLM instruction

Instead of directly injecting variables, pass an instruction to the LLM on how to use the recalled information.

MEMORY:
  recall:
    - ON: session:start
      ACTION: prompt_llm
      INSTRUCTION: |
        Check if you have the user's name and preferences from previous
        conversations. If so, greet them personally and reference their
        past interactions. If not, introduce yourself and start fresh.

Combined remember and recall pattern

A complete pattern that stores user preferences during a conversation and recalls them at the start of future sessions.

MEMORY:
  session:
    - selected_booking
      TYPE: string
    - action_type
      TYPE: string

  persistent:
    - user.booking_history
    - user.preferences

  remember:
    - WHEN: action_completed == true
      STORE: {booking_id: selected_booking, action: action_type, date: now} -> user.booking_history
    - WHEN: user_preference IS SET
      STORE: user_preference -> user.preferences

  recall:
    - ON: session:start
      ACTION: inject_context
      PATHS: [user.booking_history, user.preferences]
    - ON: tool:list_user_bookings:after
      ACTION: inject_context
      PATHS: [user.preferences]

Troubleshooting

Remember trigger never fires. The WHEN condition references a variable that is never set during conversation. Verify the variable name matches what your flow or tools produce.
Recalled value is stale. The fact may have expired (TTL elapsed). Check the TTL setting and extend it if needed.
Recall injects null values. The persistent path has not been written to yet. Use DEFAULT on the persistent variable declaration to provide a fallback.

Manipulate State: SET, CLEAR, and TRANSFORM

Use SET, CLEAR, and TRANSFORM directives in flow steps to assign values, remove variables, and reshape data arrays during execution.

SET a variable

Use SET in a flow step to assign a value to a session variable. The expression is resolved at execution time.

FLOW:
  calculate_total:
    REASONING: false
    SET:
      - total_price = nights * price_per_night
      - tax_amount = total_price * 0.12
      - final_total = total_price + tax_amount
    RESPOND: "Your total is ${{final_total}} (including ${{tax_amount}} tax)."
    THEN: confirm_booking

SET expressions support arithmetic, string interpolation, dot-notation access, and function calls. From tool results:

FLOW:
  process_search:
    REASONING: false
    CALL: search_hotels(destination, checkin_date, checkout_date, num_guests)
    ON_SUCCESS:
      SET:
        - hotel_count = call_result.hotels.length
        - cheapest_price = call_result.hotels[0].price
      RESPOND: "Found {{hotel_count}} hotels. Prices start at ${{cheapest_price}}."
      THEN: select_hotel

Nested objects using dot notation:

SET:
  - booking.guest_name = guest_name
  - booking.check_in = checkin_date
  - booking.total = final_total

In ON_INPUT branches:

FLOW:
  select_hotel:
    REASONING: false
    ON_INPUT:
      - IF: input is_number AND input >= 1 AND input <= hotels.length
        SET:
          - selected_hotel = hotels[input - 1]
          - need_price_quote = true
        THEN: collect_guest_info
      - ELSE:
        RESPOND: "Please enter a valid hotel number."

CLEAR a variable

Use CLEAR to remove one or more variables from the session. After a CLEAR, the variable is undefined and any template reference to it renders as empty.

FLOW:
  restart_search:
    REASONING: false
    CLEAR: [destination, checkin_date, checkout_date, search_results]
    RESPOND: "Let's start fresh. Where would you like to go?"
    THEN: collect_trip_info

In sub-intents — allow users to clear and re-enter specific fields:

FLOW:
  collect_trip_info:
    REASONING: false
    GATHER:
      - destination: required
      - checkin_date: required
      - checkout_date: required

    SUB_INTENTS:
      - INTENT: "change destination"
        CLEAR: [destination]
        RESPOND: "What's the new destination?"
      - INTENT: "change dates"
        CLEAR: [checkin_date, checkout_date]
        RESPOND: "What are your new travel dates?"

    COMPLETE_WHEN: destination AND checkin_date AND checkout_date
    THEN: search_hotels

TRANSFORM an array

Use TRANSFORM to filter, map, sort, and limit array data in a single pipeline. In the following example TRANSFORM creates a new array affordable_hotels without modifying the source array. Full pipeline:

FLOW:
  filter_hotels:
    REASONING: false
    TRANSFORM:
      SOURCE: search_results AS hotel
      INTO: affordable_hotels
      FILTER: hotel.price <= budget
      MAP:
        name: hotel.name
        price: hotel.price
        rating: hotel.rating
      SORT_BY: price asc
      LIMIT: 5
    RESPOND: |
      Here are {{affordable_hotels.length}} hotels within your budget:
      {{#each affordable_hotels}}
      {{add @index 1}}. {{name}} - ${{price}}/night ({{rating}} stars)
      {{/each}}
    THEN: select_hotel

Filter only:

TRANSFORM:
  SOURCE: all_bookings AS booking
  INTO: active_bookings
  FILTER: booking.status == "active"

Map only:

TRANSFORM:
  SOURCE: raw_results AS item
  INTO: formatted_results
  MAP:
    title: item.name
    summary: item.description
    link: item.url

Troubleshooting

SET expression produces null. The right-hand variable may not be defined yet. Verify the data source (tool result, gathered field, or prior SET) runs before this step.
CLEAR does not reset a GATHER field. Clearing a variable removes it from the session, but the GATHER step may not re-prompt for it unless the step is re-entered. Use CLEAR within a SUB_INTENT or DIGRESSION that resumes the same step.
TRANSFORM produces empty array. The FILTER condition may be too strict, or the source array is empty. Check the source variable and filter expression.

Best Practices

Use meaningful variable names. Use names like user_preferences, order_history, or conversation_context. Avoid generic names like var1, data, or temp.
Use COALESCE() for persistent variables. Persistent paths may not be populated on a user’s first session. Use COALESCE(user.name, "valued customer") to provide a safe fallback.
Set defaults on persistent variables. Declare DEFAULT values so the agent behaves correctly before any data has been stored.
Use CLEAR within sub-intents to reset state. Clearing a variable removes it from the session, but a GATHER step only re-prompts when the step is re-entered. Pair CLEAR with a SUB_INTENT or DIGRESSION that resumes the same step.
Prefer per_session reset over never. Variables with RESET: never persist for the lifetime of the runtime process. Reserve this for counters or flags where cross-session accumulation is intentional.

Building Agents

Administration

References

Key Concepts

Session Memory

Declare session variables

Access session variables in response templates

Access session variables in step conditions

Troubleshooting

Persistent Memory

Declare persistent variables

Scoping rules

Access Control

Access Persistent Variables in Expressions

Troubleshooting

Remember Triggers

Store computed values

Recall

Add recall instructions

Recall before search operations

Inject recalled data as an LLM instruction

Combined remember and recall pattern

Troubleshooting

Manipulate State: SET, CLEAR, and TRANSFORM

SET a variable

CLEAR a variable

TRANSFORM an array

Troubleshooting

Best Practices

Further Reading

Building Agents

Administration

References

Documentation Index

​Key Concepts

​Session Memory

​Declare session variables

​Access session variables in response templates

​Access session variables in step conditions

​Troubleshooting

​Persistent Memory

​Declare persistent variables

​Scoping rules

​Access Control

​Access Persistent Variables in Expressions

​Troubleshooting

​Remember Triggers

​Store computed values

​Recall

​Add recall instructions

​Recall before search operations

​Inject recalled data as an LLM instruction

​Combined remember and recall pattern

​Troubleshooting

​Manipulate State: SET, CLEAR, and TRANSFORM

​SET a variable

​CLEAR a variable

​TRANSFORM an array

​Troubleshooting

​Best Practices

​Further Reading

Key Concepts

Session Memory

Declare session variables

Access session variables in response templates

Access session variables in step conditions

Troubleshooting

Persistent Memory

Declare persistent variables

Scoping rules

Access Control

Access Persistent Variables in Expressions

Troubleshooting

Remember Triggers

Store computed values

Recall

Add recall instructions

Recall before search operations

Inject recalled data as an LLM instruction

Combined remember and recall pattern

Troubleshooting

Manipulate State: SET, CLEAR, and TRANSFORM

SET a variable

CLEAR a variable

TRANSFORM an array

Troubleshooting

Best Practices

Further Reading