# Persistence and scaling

> Make Slack and Teams workflow state restart-safe, implement the StateStore contract, and deploy within the managed listener's concurrency model.

A deploy or a crash restarts your Channels process. State that lives only in
process memory is lost. Intelligence keeps provider ingress and canonical
Thread history. Your Channels process owns SDK workflow state.

## Know what is process-local by default [#know-what-is-process-local-by-default]

Without `createChannel({ store: { adapter } })`, a managed Channel uses a store
from Intelligence. Its key-value data is durable, so these values survive a
restart:

- `thread.state()`
- registered component snapshots used to restore callbacks

These values stay in process memory and disappear when the process restarts:

- SDK transcript lists
- SDK locks, deduplication windows, and queues

Managed conversation history is different: Intelligence reconstructs recent
provider turns even when the SDK store is in memory.

<Callout type="warn" title="Online does not mean restart-safe">
  The Intelligence **Online** state proves that the listener is connected. It
  does not prove that a pending approval or application workflow survives a
  deployment.
</Callout>

## Configure typed workflow state [#configure-typed-workflow-state]

Use a Standard Schema to type reads and validate complete replacement values:

```bash title="Terminal"
npm install zod
```

```ts title="channel.ts"
import { createChannel } from "@copilotkit/channels";
import { z } from "zod";
import { makeAgent } from "./agent.js";
import { durableStateStore } from "./state-store.js";

const workflowState = z.object({
  incidentId: z.string(),
  stage: z.enum(["triage", "awaiting-approval", "resolved"]),
});

const channel = createChannel({
  name: process.env.CHANNEL_CODE,
  identifyUser: "platform",
  agent: makeAgent,
  store: {
    adapter: durableStateStore,
    state: workflowState,
  },
});

channel.onMessage(async ({ thread, message }) => {
  const current = await thread.state();

  await thread.setState({
    incidentId: current?.incidentId ?? "INC-421",
    stage: "triage",
  });

  await thread.runAgent({ prompt: message.text });
});
```

`setState(value)` replaces the whole value. It does not merge a partial patch.
Store JSON-serializable values; remote backends do not preserve `Date`, `Map`,
class instances, or functions.

## Implement every StateStore facet [#implement-every-statestore-facet]

Read this section only if you write your own `StateStore`, for example on Redis
or Postgres. A complete production store implements:

| Facet   | Required behavior                                          |
| ------- | ---------------------------------------------------------- |
| `kv`    | Get, set with optional TTL, atomic consume, and delete     |
| `list`  | Oldest-first append/range, cap, trim, delete, and list TTL |
| `lock`  | Atomic acquire plus token-checked release                  |
| `dedup` | Atomic first-seen check with TTL                           |
| `queue` | FIFO enqueue/dequeue/depth with bounded overflow policy    |

Locks, deduplication, and queues must be atomic across every process sharing the
backend. Namespacing must prevent one project or Channel from reading another
one's keys.

Run the SDK's Vitest conformance suite against your adapter:

```bash title="Terminal"
npm install -D vitest
```

```ts title="state-store.test.ts"
import { runStateStoreConformance } from "@copilotkit/channels/testing";
import { createRedisStateStore, closeRedisStateStore } from "./redis-store.js";

runStateStoreConformance(
  "redis",
  () => createRedisStateStore(),
  (store) => closeRedisStateStore(store),
);
```

Run it against the real backend:

```bash title="Terminal"
npx vitest run state-store.test.ts
```

The SDK ships `MemoryStore` and the conformance suite; it does not ship a fully
durable Redis or Postgres implementation in the umbrella package.

## Preserve interactive callbacks across restarts [#preserve-interactive-callbacks-across-restarts]

A callback survives only when both conditions are true:

1. The JSX comes from a named component registered in
   `createChannel({ components })`.
2. The action snapshot is stored in a durable `StateStore`: the default
   managed store, or your own `store.adapter`.

```tsx title="channel.tsx"
const channel = createChannel({
  name: process.env.CHANNEL_CODE,
  identifyUser: "platform",
  agent: makeAgent,
  components: [ApprovalCard],
  store: { adapter: durableStateStore },
});
```

Keep registered component props JSON-serializable and derive the handler from
those props. Test by posting a card, restarting the process, then clicking the
old card.

## Match the managed concurrency model [#match-the-managed-concurrency-model]

### Delivery claims (multi-replica) [#delivery-claims-multi-replica]

Each prepared delivery has one claim winner. Every connected runtime process
that declares the matching Channel can receive the invitation, check local
capacity, and attempt the claim. Different runtime processes can serve
different conversations at the same time; there is no Channel-wide leader.

Keep the Channel declarations and agent code aligned across runtime processes.
Each runtime process bounds its active and pending delivery work internally. A
runtime process that has reached its internal capacity declines new invitations
before claiming them; that capacity is not currently a public Channel
configuration option.

Provider effects use one ordered packet at a time. The SDK retries that exact
packet after a known retry wait or reconnect. If a provider call becomes
uncertain, Gateway records an uncertain terminal result instead of sending it
again. Application tools still need their own idempotency keys when the
application may call them more than once; use `message.eventId`,
`message.turnId`, or a durable operation ID.

### Turn concurrency (same conversation) [#turn-concurrency-same-conversation]

Managed admission keeps one canonical Thread exclusive on one runtime process.
A second invitation for that Thread is not claimed while the first delivery is
active. Unrelated Threads continue in parallel within the bounded capacity of
each runtime process.

This delivery guard is separate from the SDK `store.concurrency` setting used
by other adapter paths. Choose that setting for your application-state rules;
do not use it to raise the managed same-Thread delivery limit. See
[`StoreConfig`](/reference/channels/types/StoreConfig).

## Production checklist [#production-checklist]

Before you deploy:

- Provide a durable `store.adapter` before you rely on SDK transcripts, locks,
  or queues after a restart.
- Run the StateStore conformance suite against the real backend.
- Test a restart while a card is awaiting a click.
- Make external writes idempotent.
- Stop the listener on `SIGINT` and `SIGTERM`.

When you scale:

- Prefer an agent factory; singletons are cloned per run automatically.
- Choose `store.concurrency` deliberately if you need serial workflow state.
- Keep Channel declarations aligned across runtime processes. Scale
  horizontally when the bounded capacity of one runtime process is not enough.
- Alert on Intelligence **Conflict**, **Offline**, and **Delivery failing**.

Continue with [history and transcripts](/slack/history-and-transcripts), or
use the [`StateStore` reference](/reference/channels/types/StateStore).
