iii-state

Distributed key-value state storage with scope-based organization and reactive triggers that fire on any state change.

State is server-side key-value storage with trigger-based reactivity. Unlike streams, state does not push updates to WebSocket clients — it fires triggers that workers handle server-side.

Install

iii worker add iii-state

Resolves from the worker registry at workers.iii.dev.

Skills

Install the iii-state agent skill for Claude Code, Cursor, and 30+ other agents:

npx skills add iii-hq/iii --full-depth --skill iii-state

Sample Configuration

- name: iii-state
  config:
    adapter:
      name: kv
      config:
        store_method: file_based
        file_path: ./data/state_store
        save_interval_ms: 5000

Configuration

Runtime configuration (hot reload)

iii-state registers its configuration with the builtin configuration worker under the id iii-state, so the settings above can be read and changed at runtime (e.g. configuration::set { id: "iii-state", value: { ... } }) without restarting the engine. The config.yaml block is the seed used on first boot only; afterwards the configuration entry is the runtime source of truth and a runtime edit survives engine restarts (read back via a boot-read). Values are validated against the schema at set time, and ${VAR:default} placeholders are expanded on read.

Apply tiers:

The configuration worker must be file-backed (the default fs adapter) at its default directory for the restart-tier boot-read to pick up persisted adapter edits; otherwise the config.yaml block is used at boot.

Adapters

The adapter set is closed: configuration::set accepts only the built-in adapters below, each with its own typed config schema, so an agent introspecting the schema (or the console) sees concrete per-adapter fields rather than a free-form object.

kv

Built-in key-value store with in-memory or file-based persistence.

name: kv
config:
  store_method: file_based
  file_path: ./data/state_store
  save_interval_ms: 5000

redis

Uses Redis as the state backend.

name: redis
config:
  redis_url: ${REDIS_URL:redis://localhost:6379}

bridge

Forwards state operations to a remote III Engine instance via the Bridge Client.

name: bridge

Functions

state::set

Set a value in state. Fires state:created if the key did not exist, or state:updated if it did.

Parameters: scope (string), key (string), value (any)

Returns: old_value (any), new_value (any)

state::get

Get a value from state.

Parameters: scope (string), key (string)

Returns: value (any), or null if the key does not exist.

state::delete

Delete a value from state. Fires a state:deleted trigger.

Parameters: scope (string), key (string)

Returns: value (the deleted value, or null)

state::update

Atomically update a value using one or more operations. Fires state:created or state:updated.

Parameters: scope (string), key (string), ops (UpdateOp[])

Returns: old_value (any), new_value (any)

state::list

List all values within a scope.

Parameters: scope (string)

Returns: a flat JSON array of all stored values within the scope.

state::list_groups

List all scopes that contain state data.

Returns: groups (string[]) — sorted, deduplicated array of all scope names.

Trigger Type: state

Fires when a state value is created, updated, or deleted.

State Event Payload

Sample Code

const fn = iii.registerFunction(
  { id: 'state::onUserUpdated' },
  async (event) => {
    console.log('State changed:', event.event_type, event.key)
    console.log('Previous:', event.old_value)
    console.log('Current:', event.new_value)
    return {}
  },
)

iii.registerTrigger({
  type: 'state',
  function_id: fn.id,
  config: { scope: 'users', key: 'profile' },
})