Memory and constraints - Kore.ai Docs

This page documents two related ABL constructs:

MEMORY: manages session and persistent state.
CONSTRAINTS: enforces 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. (`initial_value` is accepted as a legacy alias.)
`RESET`	`per_session`, `per_activation`, `per_step`, `never`	No	`per_session`	When to reset the variable. See Reset behavior.
`SOURCE`	`user`, `tool`	No	—	Restricts who may write the variable. See Write authority, format and derived values.
`FORMAT`	`email`, `phone`, `digits`, `address`, `person_name`	No	—	How a caller’s words are read when grounding the value, and the `kind` used by `MATCH_SCORE`/`MATCHES`/`MATCH_RESULT`. Never changes `TYPE`.
`DERIVED`	expression (string)	No	—	Expression the platform recomputes on every session write. The model cannot set a derived field.
`READONLY`	`boolean`	No	`false`	When `true`, the model’s `__set_context__` cannot write the variable; `SET`, `on_result`, and hooks still can.

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

Write authority, format and derived values

A session variable can also declare who may write it, what kind of caller-supplied value it holds, and an expression the platform computes for it — together these are the building blocks for identity-verification flows (confirming a caller against a stored profile).

MEMORY:
  session:
    - supplied_email
      TYPE: string
      SOURCE: user
      FORMAT: email
    - profile_email
      TYPE: string
      SOURCE: tool
    - email_verified
      TYPE: boolean
      DERIVED: MATCHES(supplied_email, profile_email)

(Legacy .agent.abl format: SOURCE: user, FORMAT: email, DERIVED: MATCHES(supplied_email, profile_email) are written the same way, uppercase, directly under the variable.)

SOURCE: user — the variable is stored only when the value is something the caller actually said; a model write of a value the caller never said is silently refused (the value is not stored) and traced by field name only, never by value. A close spelling is stored as the caller said it — for example the caller spells “Riviera” but the model writes “Rivera”; the stored value is the caller’s own spelling.
SOURCE: tool — only a tool binding (via on_result/on_error mappings) can set the variable; a model write is refused the same way. SET and other FLOW-authored writes still follow the active agent’s own declarations.
FORMAT — one of email, phone, digits, address, person_name. It governs how the caller’s spoken/typed words are read when grounding a SOURCE: user value (for example, “at the rate” → @, spelled-out digits, spoken addresses), and supplies the default kind for a two-argument MATCH_SCORE/MATCHES/MATCH_RESULT call whose operands are both FORMAT-declared fields — but only inside a DERIVED expression. Elsewhere (CONSTRAINTS, WHEN, hooks, and other expressions), a two-argument call is scored as kind: text unless you pass the kind explicitly: MATCHES(a, b, "email").
DERIVED — an expression (typically built from MATCH_SCORE/MATCHES/MATCH_RESULT, or a boolean combination of other fields) that the platform recomputes after every session write. The model can never set a DERIVED field directly. A derived field may reference another derived field in any declaration order. If two or more derived fields depend on each other in a cycle, all of them are left unset — so a rule like verified == true fails closed rather than evaluating against a stale or undefined value (compiler warning DERIVED_CYCLE). A computed value that doesn’t match the field’s declared TYPE is also left unset. A DERIVED expression must be valid CEL with no trailing // comment (CEL has no comments) and no call to a function the evaluator has no overload for — any of those is a compiler warning (DERIVED_EXPRESSION_INVALID); the agent still compiles, but the field never computes correctly.
READONLY: true — a lighter-weight opt-in than SOURCE/DERIVED: it only blocks the model’s own __set_context__ writes. SET, on_result, and hooks can still write it. Only the literal value true opts in.

MATCH_SCORE(said, stored, kind?) returns 0-100 (or -1 when there’s nothing to judge — a missing value, a PII vault token, or an input over 1,024 characters; -1 is below every threshold, so a rule written as MATCH_SCORE(...) >= 70 fails closed). MATCHES(said, stored, kind?) is the pass/fail form on the platform’s own match bands, and MATCH_RESULT(said, stored, kind?) returns "match", "retry", "mismatch", or "missing". These are a said-versus-stored identity comparison, not a regex test — the infix a MATCHES "pattern" operator is the regex form. See Built-in function reference for the full signatures and match bands.

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

Array targets can accumulate values instead of being overwritten, using the block form of STORE:

MEMORY:
  remember:
    - WHEN: search_completed
      STORE:
        value: last_query
        target: user.recent_searches
        operation: append   # overwrite (default) | set | append
        unique: true        # optional — skip duplicates
        maxSize: 10         # optional — FIFO cap

The modifiers are only read from the block form; the inline value -> target arrow form always uses overwrite. append, unique, and maxSize apply to array-typed targets in user, project, and execution_tree scopes.

Properties

Property	Type	Required	Default	Description
`WHEN`	`string`	Yes	—	Condition expression that triggers the store operation. Evaluated after each turn.
`STORE`	`object`	Yes	—	Value expression and target path. Inline syntax: `value_expr -> target_path`; block form to add modifiers.
`operation`	`overwrite`, `append`	No	`overwrite`	Array-write mode. `append` adds to the existing array; `overwrite` replaces the whole value. Block form only.
`unique`	`boolean`	No	`false`	When `append`, drop duplicate items (first occurrence kept; deep-equality for objects). Block form only.
`maxSize`	`number`	No	—	When `append`, cap array length, evicting oldest items first (FIFO). Block form only.
`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.

A BEFORE calling <tool_name> rule’s condition (REQUIRE/LIMIT/RESTRICT) or WHEN can read the about-to-be-sent arguments via tool_args, but only when the agent sets EXECUTION: guardrail_builtins: true. Without it, tool_args is unbound: the rule cannot read the arguments, so it never holds, and the tool call is refused. The compiler warns GUARDRAIL_BUILTIN_NOT_BOUND for this case.

EXECUTION:
  guardrail_builtins: true

CONSTRAINTS:
  always:
    - REQUIRE tool_args.amount <= daily_wire_limit BEFORE calling wire_transfer
      ON_FAIL: "That exceeds your daily wire limit."

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

ON_FAIL actions

ON_FAIL accepts a single-line action — a message string, HANDOFF <Agent>, or ESCALATE — or a structured block. The block form can respond, reset state, and route in one place:

- REQUIRE amount <= daily_wire_limit
  ON_FAIL:
    RESPOND: "That exceeds your daily limit. Let's re-enter the amount."
    CLEAR: [amount, raw_amount]
    GOTO: collect_amount

Key	Type	Description
`RESPOND`	`string`	Message sent to the user on failure.
`CLEAR`	`string[]`	Session variables to reset on failure, so stale values are recollected.
`COLLECT`	`string[]`	Fields to re-collect before retrying.
`GOTO`	`string`	Step to route to. A single identifier naming a declared FLOW step; anything else is spoken literally.
`RETRY`	`boolean`	Whether to retry the failed operation.
`MAX_REPEATS`	`number`	Failures of this constraint (per conversation) this block answers before `ON_EXHAUSTED` takes over. Omit for no cap.
`ON_EXHAUSTED`	string or action	Inline action run once `MAX_REPEATS` is used up, for example `ESCALATE "identity_not_confirmed"`.

The CLEAR key lets an ON_FAIL block reset dependent state directly — you no longer need a separate CLEAR-only step solely to clear variables before a retry.

An ON_FAIL RESPOND message may use {{_abl_constraint_fail_count}} — this failure’s 1-based ordinal for the constraint within the current conversation. Pair it with MAX_REPEATS/ON_EXHAUSTED to vary the message as attempts run out, then hand off once the cap is reached:

- REQUIRE MATCH_SCORE(supplied_email, profile_email) >= 70
  ON_FAIL:
    RESPOND: "That doesn't match what's on file (attempt {{_abl_constraint_fail_count}})."
    MAX_REPEATS: 2
    ON_EXHAUSTED: ESCALATE "identity_not_confirmed"

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.
`MAX_REPEATS`	`number`	No	—	Failures of this constraint (per conversation) answered before `ON_EXHAUSTED` takes over.
`ON_EXHAUSTED`	string or action	No	—	Inline action run once `MAX_REPEATS` is used up.

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

Related articles:

Guardrails — input/output safety checks (distinct from business rule constraints)
Expressions and functions — condition expression syntax
Multi-Agent and Supervisor — HANDOFF and ESCALATE actions referenced in ON_FAIL
Lifecycle and 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

​Write authority, format and derived values

​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

​ON_FAIL actions

​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

MEMORY

Overview

Session variables

Syntax

Properties

Reset behavior

Example: typed session variables

Write authority, format and derived values

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

ON_FAIL actions

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