Sessions, memory & state

Sessions, customers, context variables, metadata, step outputs, and the storage backends that persist them.

Context — This page maps every kind of state an agent holds, who writes it, who sees it, and where it lives. The distinction that trips everyone up at least once: variables are agent-visible, metadata is not.
YAML examples follow manifest schema 6.1.5. Manifest and content shapes are schema-versioned and differ across runtime versions — see Versioning & compatibility.

The state model

Customer ──── has many ──── Sessions ──── contain ──── Events (offset-ordered)
   │                            │
   ├─ variables (agent-visible) ├─ metadata (integration-only)
   └─ metadata (integration-only)└─ mode: auto | manual

Customers (optional)

A customer is the stable identity across conversations — keyed by an id your integration chooses (a CRM id, an email, a ticket-system user id). Customers carry:

Variables — agent-visible context (see below).
Metadata — integration-only key/values the agent never sees.
A display name.

Customers are a convenience for customer-facing agents — they let you carry variables and group sessions across one end-user's conversations. An agent that isn't customer-facing doesn't need the concept at all: a backend automation is triggered with typed input and never references a customer, and even a simple chat integration can open sessions without modelling end-users as customers. Reach for customers only when you have a recurring end-user whose context should persist across sessions.

Sessions

A session is one conversation. A customer can have many (a "new conversation" button, one per support ticket). Sessions carry:

The event log: every message, tool call, and status change, each with a monotonically increasing integer offset. The offset is your resume-and-dedupe cursor — see Integrating the SDK.
Metadata — integration-only. Well-known keys the runtime understands:
Key
Effect
session_key
Stable human-meaningful id (e.g. a ticket id) used to name and group traces — see Observability.
event_webhook_url
Where the agent POSTs events for webhook-mode delivery (the SDK writes this for you).
external_id
Convention for finding a session by your channel's conversation id.
step_outputs
Written by the runtime: validated outputs of think nodes (autonomous routines), keyed by node id.
Mode — auto (the engine replies to customer messages) or manual (a human has taken over; the engine stays silent while your integration posts human-authored messages). See the handover section of the SDK guide.

Variables vs metadata

Variables

Metadata

Visible to the agent

Yes — injected into context on the next turn

No — never reaches a prompt

Lives on

Customer

Customer or session

Written by

Your integration (SDK), any time

Your integration; a few keys by the runtime

Use for

Anything the agent should know: plan tier, loyalty status, open-ticket count, "documents were just uploaded"

Anything you need to look up later: channel ids, webhook URLs, bookkeeping

# Agent-visible — readable from routines/policies on the next turn.
await client.customers.set_variables(
    customer.id,
    {"loyalty_tier": "gold", "open_tickets": 3},
)

# Integration-only — the agent does NOT see this.
await sess.update_metadata({"chatwoot_conversation_id": "789"})

Variables take effect on the next turn — the engine snapshots context when a turn starts. Any JSON-serialisable value works (values are stringified for the model). Variables are referenced naturally from content: a routine condition can say "the customer's loyalty_tier is gold".

Variables are configured per-deployment through the SDK at runtime — they are not declared in the manifest.

Step outputs

Each think node persists its validated JSON to session.metadata.step_outputs[<node-id>], merged across the nodes of a run. Downstream nodes see the inference call and result in history; your integration can read the typed values off the session after the fact — useful for auditing what the agent concluded mid-flow.

Storage backends

Where all of this lives is one manifest decision:

Configuration

Backend

Survives restart

Use for

omit agent_config.database

In-memory

Demos, tests, stateless autonomous-only agents

agent_config.database block

PostgreSQL

Yes

Production conversational agents

agent_config:
  database:
    hostname: agent-postgres.internal.example.com
    port: 5432
    user: postgres
    password: ${DB_PASSWORD}
    dbname: postgres
    sslmode: require

(hostname and password are required; port/user/dbname/sslmode default to 5432/postgres/postgres/require.)

With in-memory storage, a restart or redeploy erases every session — open conversations reset mid-dialogue. If customers ever come back to continue a conversation, use Postgres. Schema migrations run automatically at boot.

The knowledge base is a separate Postgres concern (agent_config.search, see Knowledge base & retrieval) — the two may share a server but are configured independently.

Lifecycle notes

Ephemeral autonomous sessions — a triggered run without a session_id creates a throwaway customer + session and deletes both after the callback settles. Pass your own session_id to keep the run's history. See Autonomous routines.
History is the agent's memory. There is no hidden long-term memory beyond what this page lists: the event log, variables, metadata, and step outputs. What you see in the session is what the model can know.