> ## Documentation Index > Fetch the complete documentation index at: https://koreai.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # 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](#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](#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](#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](#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](#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). ### Configure session variables in the UI Open the agent, go to **Capabilities** > **Memory** in the left nav, and scroll to the SESSION VARIABLES section. Click **+ Add Variable** to add a new session variable. Each variable has the following fields. | UI Field | Input Type | Description | | -------------- | --------------------- | ---------------------------------------------------------------------- | | Variable name | Text input | Name of the session variable (top field in card) | | Type | Text input | Value type — string, number, boolean, object, array, date | | Description | Text input | Human-readable purpose for the variable | | Initial value | Text input (optional) | Value assigned when the session starts | | Reset behavior | Dropdown | When to reset — Default reset (`per_session`), `per_step`, or `never`. | ### Declare session variables via ABL Add a `MEMORY:` block with a `session:` section to your agent definition in the ABL editor. ```yaml theme={null} 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. | | per\_activation | Variable is reset to `INITIAL` every time the agent is activated, including repeated activations of the same agent. | For simple tracking without type metadata, declare a bare name: ```yaml theme={null} MEMORY: session: - customer_id - order_total ``` Fields with initial values and reset control: ```yaml theme={null} 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. ```yaml theme={null} 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. ```yaml theme={null} 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. ### Configure persistent variables from UI Navigate to **Memory** > **Persistent Paths**. **Persistent Paths**: Use persistent paths when you want the agent to automatically preserve information without requiring a predefined schema. Examples: ``` user.preference.language user.preference.timezone customer.account_type ``` **Structured Persistent Paths**: Structured Persistent Paths allow you to define persistent memory using a predefined structure or schema. Use structured persistent paths when you want to organize long-term memory into structured objects instead of individual dotted paths. Examples: ```json theme={null} { "userProfile": { "name": "", "email": "", "preferences": { "language": "", "timezone": "" } } } ``` **Read Access Paths**: Stores fields as persistent memory paths with read access. **Write Access Paths**: Stores as persistent memory paths with write access. Use READS/WRITES for quick, intent-clear declarations of access-only paths without other metadata for the fields. ### Declare persistent variables via ABL Add a `persistent:` section under `MEMORY:`. Use dot-notation paths to name each variable and bind them to a scope. ```yaml theme={null} 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 (for example. 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 (for example. 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. | ```yaml theme={null} 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. ```yaml theme={null} 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. ```yaml theme={null} 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. To configure a Remember trigger, provide the following fields: * When: Specifies the condition under which the trigger is executed and the memory value is stored. * Store Value: The value to be written to persistent memory when the trigger condition is met. * Store Target: The persistent memory field where the value will be stored. * TTL: The duration for which the stored value remains in memory. After the specified time elapses, the value is automatically deleted. This field is optional. If not specified, the value is retained indefinitely. ```yaml theme={null} 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. ```yaml theme={null} 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 ```yaml theme={null} 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** | Field | Required | Description | | ------------- | -------- | --------------------------------------------------------------------------- | | `ON` | Yes | Canonical event name such as `session:start` or `tool::after`. | | `ACTION` | Yes | `inject_context`, `load_memory`, or `prompt_llm`. | | `PATHS` | No | Durable memory paths to retrieve for `inject_context` or `load_memory`. | | `DOMAIN` | No | Named memory domain used by `load_memory` when paths are domain-scoped. | | `INSTRUCTION` | No | Prompt text used by `prompt_llm` to shape how retrieved context is applied. | **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. ```yaml theme={null} 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. ```yaml theme={null} 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. ```yaml theme={null} 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. ```yaml theme={null} 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:** ```yaml theme={null} 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:** ```yaml theme={null} SET: - booking.guest_name = guest_name - booking.check_in = checkin_date - booking.total = final_total ``` **In `ON_INPUT` branches:** ```yaml theme={null} FLOW: select_hotel: REASONING: false ON_INPUT: - IF: abl.is_number(input) 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. ```yaml theme={null} 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: ```yaml theme={null} 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:** ```yaml theme={null} 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:** ```yaml theme={null} TRANSFORM: SOURCE: all_bookings AS booking INTO: active_bookings FILTER: booking.status == "active" ``` **Map only:** ```yaml theme={null} 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. *** ## Further Reading * [Memory & Constraints Reference](/agent-platform/abl-reference/memory-and-constraints) -- Full ABL syntax for MEMORY and CONSTRAINTS blocks. * [GATHER Reference](/agent-platform/abl-reference/gather) -- Collecting user input into session variables. * [Flow Reference](/agent-platform/abl-reference/flow) -- Flow step directives including SET, CLEAR, TRANSFORM. ***