Stateless vs stateful turns

/v1/respond runs in one of two modes. The difference is whether uniqOS persists a relationship with the end user.

Stateless (default)

A stateless turn adds personality and emotional intelligence for this one call and persists nothing. There is no end user, no relationship, no memory. This is the default and needs no extra fields:

await client.respond({ personality_id: 'pers_...', message: 'Hello!' })

Use stateless when each interaction is independent, or while you are prototyping.

Stateful

A stateful turn activates relational memory: uniqOS creates or updates a per-user model and remembers the user across turns. Two things are required — mode: 'stateful' and a user_id, your own stable identifier for the end user:

await client.respond({
  personality_id: 'pers_...',
  message: 'Hello again!',
  mode: 'stateful',
  user_id: 'user_42',
})

client.respond(
    personality_id="pers_...",
    message="Hello again!",
    mode="stateful",
    user_id="user_42",
)

The user_id is yours — any stable identifier for the person (your own user id, a hashed handle, etc.). uniqOS keys the relationship to it; the same user_id on later turns continues the same relationship.

The SDKs enforce the pairing

mode: 'stateful' without a user_id is rejected by the SDKs before any HTTP call (a ConfigurationError, code stateful_requires_user_id), so you never pay for a turn that was going to fail. A plain stateless call needs no user_id.

:::note Personality default mode A personality can declare a default_mode of stateful. In that case the API requires a user_id even when you omit mode. The SDK can't know a personality's default without a lookup, so pass a user_id (or an explicit mode: 'stateless') to be unambiguous. :::

Which to use

	Stateless	Stateful
Persists a relationship	No	Yes
Requires user_id	No	Yes
Remembers across turns	No	Yes (per user_id)
Billing	per turn	per turn + active relationship/month

Stateful mode adds an active relationship billing dimension (each user–agent pair active in a month). See the API Reference for the usage fields returned on each turn.

Next: what you can read back and how erasure works.