Memory and Constraints - Kore.ai Docs

This page documents two related ABL constructs: the MEMORY: block for managing session and persistent state, and the CONSTRAINTS: block for enforcing business rules.

MEMORY

Memory in ABL defines how an agent stores, retrieves, and persists information across conversation turns, sessions, and users. The MEMORY: block declares four categories: session variables, persistent variables, remember triggers, and recall instructions.

Overview

Every agent has access to a memory configuration that controls data lifecycle:

Session variables exist for the duration of a single conversation session.
Persistent variables survive across sessions, scoped to a user or project.
Remember triggers automatically store values when conditions are met.
Recall instructions load stored facts at specific lifecycle events.

MEMORY:
  session:
    - customer_id
    - order_total
      TYPE: number
      DESCRIPTION: "Running total for the current order"
      INITIAL: 0
      RESET: per_session
  persistent:
    - user.preferred_language
    - user.loyalty_tier
      SCOPE: user
  remember:
    - WHEN: user_language IS SET
      STORE: user_language -> user.language
      TTL: "90d"
  recall:
    - ON: session:start
      ACTION: inject_context
      PATHS: [user.preferred_language, user.loyalty_tier]

Session variables

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).

Syntax

MEMORY:
  session:
    - variable_name
    - variable_name
      TYPE: string
      DESCRIPTION: "Human-readable description"
      INITIAL: "default_value"
      RESET: per_session

You can declare a session variable with a bare name (minimal form) or with additional metadata.

Properties

Property	Type	Required	Default	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	`null`	Initial value assigned when the session starts.
`RESET`	`per_session`, `per_activation`, `per_step`, `never`	No	`per_session`	When to reset the variable. 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_activation`	Variable is reset each time the agent is (re)activated within a session (for example. on re-entry after a handoff).
`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.

Example: typed session variables

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

Persistent variables

Persistent variables survive across sessions. They are stored in a fact store and scoped to either a specific user or to the entire project.

Syntax

MEMORY:
  persistent:
    - user.preferred_chains
    - user.wire_history_30d
      SCOPE: user
      TYPE: array
      DESCRIPTION: "Recent wire transfer history"
      ACCESS: readwrite
      DEFAULT_VALUE: []
    - user.ssn
      SCOPE: user
      SENSITIVE: true
      SENSITIVE_DISPLAY: mask
      MASK_CONFIG:
        showFirst: 0
        showLast: 4
        char: "*"
    - project.exchange_rates
      SCOPE: project
      ACCESS: read

Persistent variable paths use dot notation. The first segment typically indicates the scope (user.* or project.*), but you can override this with the SCOPE property.

Properties

Property	Type	Required	Default	Description
`path`	`string`	Yes	—	Dot-notation path (for example. `user.preferred_chains`).
`SCOPE`	`user`, `project`, `execution_tree`	No	`user`	Ownership scope. See Scoping rules.
`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_VALUE`	any	No	`null`	Default value when no fact exists in the store.
`DESCRIPTION`	`string`	No	—	Human-readable description.
`SENSITIVE`	`boolean`	No	`false`	Marks the value as PII for privacy-aware handling.
`SENSITIVE_DISPLAY`	`redact`, `mask`, `replace`	No	—	How the value is displayed outside its context (when `SENSITIVE: true`).
`MASK_CONFIG`	`{showFirst, showLast, char}`	No	—	Masking configuration when `SENSITIVE_DISPLAY` is `mask`.

Scoping rules

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 handoff tree / long-running execution — visible to the agents participating in that orchestration but not persisted per-user or per-project.

As shorthand, a READS: sub-block declares persistent paths with ACCESS: read, and a WRITES: sub-block declares them with ACCESS: write — an alternative to listing each path under persistent: with an explicit ACCESS.

Remember triggers

Remember triggers define rules for automatically storing values into persistent memory when a condition is met during conversation.

Syntax

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

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 format

TTL values use a duration string:

Suffix	Meaning
`s`	Seconds
`m`	Minutes
`h`	Hours
`d`	Days

Example: "90d" means the stored fact expires 90 days after it was written.

Recall instructions

Recall instructions define when and how to load persistent facts back into the session context. They execute at specific lifecycle events.

Syntax

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

Properties

Property	Type	Required	Default	Description
`ON`	`string`	Yes	—	Lifecycle event that triggers the recall. See Events.
`ACTION`	`string`	No	—	The concrete action to execute. See Actions.
`INSTRUCTION`	`string`	Yes	—	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

ON: accepts these canonical lifecycle event patterns:

Event pattern	When it fires
`session:start`	When a new session initializes, before any user input.
`session:end`	When a session ends.
`agent:<name>:before`	Before a specific agent runs (use `agent:*:before` for any).
`agent:<name>:after`	After a specific agent runs (use `agent:*:after` for any).
`tool:<name>:after`	After a specific tool runs (use `tool:*:after` for any).
`entity:<field>:extracted`	When a named entity/field is extracted from user input.
`step:enter:<name>`	On entering a specific flow step.
`step:exit:<name>`	On exiting a specific flow step.

Legacy event names such as search:before, ON_START, or ON_SEARCH are no longer supported and are rejected during compilation — use the canonical patterns above. Note that tool:<name>:before is not a valid recall event (only tool:<name>:after).

Recall actions

Action	Behavior
`inject_context`	Loads specified persistent paths directly into the session context as variables.
`load_memory`	Loads all facts in the specified domain into context.
`prompt_llm`	Passes the instruction text to the LLM as additional context. This is the default action.

Accessing memory in expressions

Session variables are accessed by name in expressions and template strings:

RESPOND: "Hello, {{customer_name}}! Your balance is {{available_balance}}."

Persistent variables are accessed through their full dot-notation path:

SET: greeting = COALESCE(user.name, "valued customer")

Variables set via SET assignments in flow steps, ON_START, or hooks are written to session memory and available for the remainder of the session.

CONSTRAINTS

Constraints are deterministic business rules that the runtime evaluates against the current session state. Authors can still group constraints under named phases for readability, but phase names are currently labels only: the compiler flattens constraints into a single runtime list unless a constraint explicitly gates itself with WHEN or a structural checkpoint construct.

Overview

Constraints enforce guardrails on agent behavior that are separate from LLM instructions. They are deterministic checks evaluated by the runtime, not suggestions to the model. A constraint that fails blocks the current operation and triggers an ON_FAIL action.

CONSTRAINTS:
  always:
    - REQUIRE customer_verified == true
      ON_FAIL: "Please verify your identity first."

  pre_booking:
    - REQUIRE amount <= available_balance
      ON_FAIL: "Insufficient funds. Your available balance is {{available_balance}}."

    - REQUIRE sanctions_clear == true
      ON_FAIL: HANDOFF Compliance_Officer

Phases

Named phases are retained as authoring labels for readability, review, and organization. They do not currently create separate runtime execution phases by themselves.

Syntax

CONSTRAINTS:
  phase_name:
    - REQUIRE condition_expression
      ON_FAIL: action_or_message

Use labels like always, pre_booking, or eligibility_check when they help readers understand intent, but use WHEN to gate applicability and BEFORE only for explicit structural checkpoint targets.

Requirement rules

Each requirement within a phase uses one of three keywords: REQUIRE, LIMIT, or RESTRICT.

REQUIRE

The most common form. Asserts that a condition must be true. If the condition evaluates to false, the ON_FAIL action is triggered.

- REQUIRE account_status == "active"
  ON_FAIL: "Wire transfers require an active account."

LIMIT

Expresses a numeric boundary. Semantically equivalent to REQUIRE with a comparison, but communicates intent more clearly.

- LIMIT daily_wire_used + amount <= daily_wire_limit
  ON_FAIL: "This would exceed your daily wire limit of {{daily_wire_limit}}."

RESTRICT

Expresses a prohibition. The condition describes what is forbidden; when it evaluates to true, the constraint fails.

- RESTRICT beneficiary_country IN ["CU", "IR", "KP", "SY"]
  ON_FAIL: "Transfers to that destination are prohibited under sanctions regulations."

WHEN

Use WHEN: to make a constraint apply only in a specific context without overloading the phase label.

- REQUIRE ssn IS NOT SET
  WHEN: channel == "voice"
  ON_FAIL: "SSN cannot be collected on voice."

BEFORE

Use BEFORE for structural checkpoints that the runtime knows how to activate.

- REQUIRE measure_field IS SET BEFORE calling search_aggregate
  ON_FAIL: "Select a measure before running the aggregate search."

- REQUIRE aggregation_validated == true BEFORE returning results
  ON_FAIL: "Validate the aggregation before responding."

Supported structural targets today:

BEFORE calling <tool_name>
BEFORE returning results

Non-structural BEFORE targets are retained for compatibility, but they are warning-only and have no runtime effect. Prefer IMPLIES or WHEN for that form.

IMPLIES

IMPLIES is an inline condition operator (not a top-level keyword) for expressing conditional requirements. A IMPLIES B is lowered to NOT (A) OR (B) — that is, “if A holds, then B must also hold.” Use it inside the condition of a REQUIRE/LIMIT/RESTRICT rule:

- REQUIRE transfer_type == "international" IMPLIES swift_code IS SET
  ON_FAIL: "International transfers require a SWIFT/BIC code."

Constraint properties

Property	Type	Required	Default	Description
`condition`	`string`	Yes	—	Expression to evaluate. See Expressions & functions.
`WHEN`	`string`	No	—	Optional applicability gate. The compiler lowers it to implication semantics so the constraint only applies when the gate is true.
`ON_FAIL`	`string` or action	Yes	`respond`	Action when the condition fails. See ON_FAIL actions.
`severity`	`error` or `warning`	No	`error`	`error` blocks execution; `warning` emits a warning but continues. In text ABL, use the `WARN` keyword instead of a `severity:` line.

ON_FAIL actions

The ON_FAIL value determines what happens when a constraint fails.

String message (respond)

The most common form. Sends a message to the user and halts the current operation.

ON_FAIL: "Insufficient funds. Available balance: {{available_balance}}."

HANDOFF

Transfers control to another agent. Active flow and reasoning runtime checkpoints execute the handoff immediately when the constraint fails.

ON_FAIL: HANDOFF Compliance_Officer

ESCALATE

Triggers human escalation.

ON_FAIL: ESCALATE

Block

Silently blocks the operation without a user-facing message.

ON_FAIL: BLOCK

Structured ON_FAIL block

For more control, use a structured block that combines multiple actions.

- REQUIRE payment_method IS SET
  ON_FAIL:
    RESPOND: "I need your payment method before proceeding."
    COLLECT: [payment_method]
    THEN: retry

Structured ON_FAIL properties

Property	Type	Required	Default	Description
`RESPOND`	`string`	No	—	Message to send to the user.
`COLLECT`	`string[]`	No	—	Fields to collect from the user before re-evaluating.
`GOTO`	`string`	No	—	Flow step to jump to.
`RETRY`	`boolean`	No	`false`	Retry the current step after handling the constraint.
`THEN`	`continue` or `retry`	No	—	What to do after collection: `continue` proceeds, `retry` re-checks.

Collect and retry example

CONSTRAINTS:
  pre_booking:
    - REQUIRE departure_date IS SET AND return_date IS SET
      ON_FAIL:
        RESPOND: "I need your travel dates to check availability."
        COLLECT: [departure_date, return_date]
        THEN: retry

    - REQUIRE departure_date > NOW()
      ON_FAIL:
        RESPOND: "The departure date must be in the future. What date works for you?"
        COLLECT: [departure_date]
        THEN: retry

GOTO example

- REQUIRE user.verified == true
  ON_FAIL:
    RESPOND: "You need to verify your identity first."
    GOTO: identity_verification_step

Severity levels

Severity	Behavior
`error`	Blocks the current operation. The `ON_FAIL` action executes. This is the default.
`warning`	Emits a warning event and continues execution. The `ON_FAIL` message is logged, not sent.

- WARN fraud_score < 60
  ON_FAIL: "Transaction flagged for review."

Constraint evaluation order

Constraint phase names such as always or pre_booking are labels only; the compiler flattens all constraints into one runtime list.
WHEN gates a constraint to a specific context, and structural BEFORE gates it to supported checkpoints such as tool calls or final responses.
Inline flow-step CHECK expressions are separate from CONSTRAINTS and evaluate directly against step.check.
Declaration order is preserved in the flattened list.
Evaluation stops at the first error-severity failure. Warnings do not halt evaluation.

Template interpolation in messages

ON_FAIL message strings support {{variable}} interpolation using the current session context:

- REQUIRE (daily_wire_used + amount) <= daily_wire_limit
  ON_FAIL: "This wire would exceed your daily limit of {{daily_wire_limit}}. You've sent {{daily_wire_used}} today."

Guardrails — input/output safety checks (distinct from business rule constraints)
Expressions & functions — condition expression syntax
Multi-Agent & Supervisor — HANDOFF and ESCALATE actions referenced in ON_FAIL
Lifecycle & hooks — ON_START handler where initial memory setup occurs
Data types — type definitions used in TYPE declarations

​MEMORY

​Overview

​Session variables

​Syntax

​Properties

​Reset behavior

​Example: typed session variables

​Persistent variables

​Syntax

​Properties

​Scoping rules

​Remember triggers

​Syntax

​Properties

​TTL format

​Recall instructions

​Syntax

​Properties

​Recall events

​Recall actions

​Accessing memory in expressions

​CONSTRAINTS

​Overview

​Phases

​Syntax

​Requirement rules

​REQUIRE

​LIMIT

​RESTRICT

​WHEN

​BEFORE

​IMPLIES

​Constraint properties

​ON_FAIL actions

​String message (respond)

​HANDOFF

​ESCALATE

​Block

​Structured ON_FAIL block

Structured ON_FAIL properties

​Collect and retry example

​GOTO example

​Severity levels

​Constraint evaluation order

​Template interpolation in messages

​Related pages

MEMORY

Overview

Session variables

Syntax

Properties

Reset behavior

Example: typed session variables

Persistent variables

Syntax

Properties

Scoping rules

Remember triggers

Syntax

Properties

TTL format

Recall instructions

Syntax

Properties

Recall events

Recall actions

Accessing memory in expressions

CONSTRAINTS

Overview

Phases

Syntax

Requirement rules

REQUIRE

LIMIT

RESTRICT

WHEN

BEFORE

IMPLIES

Constraint properties

ON_FAIL actions

String message (respond)

HANDOFF

ESCALATE

Block

Structured ON_FAIL block

Collect and retry example

GOTO example

Severity levels

Constraint evaluation order

Template interpolation in messages

Related pages