> For the complete documentation index, see [llms.txt](https://docs.interactive.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.interactive.ai/agents/concepts/memory-and-state.md).

# 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 1.4.0**. Manifest and content shapes are schema-versioned and differ across runtime versions — see [Versioning & compatibility](https://docs.interactive.ai/agents/operations/versioning.md).

## 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](https://docs.interactive.ai/agents/concepts/autonomous-routines.md) 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](https://docs.interactive.ai/agents/guides/integrating-the-sdk.md).
* **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](https://docs.interactive.ai/agents/guides/observability.md#trace-naming).                                                                                                                                                                                                                                                 |
  | `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](https://docs.interactive.ai/agents/concepts/autonomous-routines.md#node-types), keyed by node id.                                                                                                                                                                                                                                                                |
  | `agent_handoff`     | Written by the runtime: escalation intent recorded by [`built-in:initiate_human_handoff`](https://docs.interactive.ai/agents/reference/built-in-tools.md#built-ininitiate_human_handoff) — `{reason, internal_note, customer_message, silent, metadata}`. The customer message (if any) was already emitted as the turn's reply; your integration attaches the staff-facing internal note and commits channel-side effects. |
* **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). Switched by your integration, or by the [`built-in:initiate_human_handoff`](https://docs.interactive.ai/agents/reference/built-in-tools.md#built-ininitiate_human_handoff) tool when a routine escalates. See the [handover section of the SDK guide](https://docs.interactive.ai/agents/guides/integrating-the-sdk.md#8-human-handover).

## 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 |

```python
# 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. The one exception is the `current_datetime` variable: declaring `context.current_datetime` in the manifest makes the engine refresh the current date and time into the model's context automatically on every turn (see [Built-in tools](https://docs.interactive.ai/agents/reference/built-in-tools.md)):

```yaml
context:
  current_datetime:
    timezone: Europe/Lisbon  # optional, defaults to UTC
```

## Step outputs

Each [think node](https://docs.interactive.ai/agents/concepts/autonomous-routines.md#node-types) 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  | **No**           | Demos, tests, stateless autonomous-only agents |
| `agent_config.database` block | PostgreSQL | Yes              | Production conversational agents               |

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

The configured agent database also stores startup evaluation caches (`eval_cache_*`) and replay/scenario execution records (`replays_runs`). A replay run accepted by one pod can be polled through another pod using that same database; records are scoped by agent and run ID.

Without `agent_config.database`, sessions, caches and replay records are ephemeral, process-local memory. They are not shared between replicas and disappear on restart. The server logs a warning; the evaluation cache no longer falls back to a local `evaluation_cache.json` file. Existing JSON cache files are not imported or deleted.

Replay acceptance is persisted before execution starts. Progress and a storage lease are refreshed every five seconds; a run whose owner stops refreshing for 60 seconds is reported as interrupted when polled. Finalized records cannot be overwritten by late results. Execution remains on the accepting pod: this is shared persistence, not a distributed worker queue, automatic resumption or retry after pod death. Scenario definitions and platform experiments remain managed by the platform.

With in-memory storage, open conversations reset mid-dialogue after a restart. If customers ever come back to continue a conversation, use PostgreSQL. Schema migrations run automatically at boot.

The knowledge base is a **separate** Postgres concern (`agent_config.search`, see [Knowledge base & retrieval](https://docs.interactive.ai/agents/concepts/knowledge-base.md)) — 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](https://docs.interactive.ai/agents/concepts/autonomous-routines.md).
* **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.

## See also

* [Integrating the SDK](https://docs.interactive.ai/agents/guides/integrating-the-sdk.md) — reading and writing all of this from code
* [Routines](https://docs.interactive.ai/agents/concepts/routines.md) — think nodes and step outputs
* [Deploying](https://docs.interactive.ai/agents/guides/deploying.md) — provisioning the database


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.interactive.ai/agents/concepts/memory-and-state.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
