iii-state-management

Original：🇺🇸 English

Translated

Creates scoped key-value stores, reads and writes state entries, lists keys, and performs partial updates across functions. Use when persisting data between invocations, managing user sessions, caching computed values, storing feature flags, sharing state between workers, or building a KV data layer as an alternative to Redis or DynamoDB.

5installs

Sourceiii-hq/skills

Added on2026-04-21

NPX Install

npx skill4agent add iii-hq/skills iii-state-management

SKILL.md Content

View Translation Comparison →

State Management

Comparable to: Redis, DynamoDB, Memcached

Key Concepts

Use the concepts below when they fit the task. Not every state operation needs all of them.

State is a scoped key-value store accessed via built-in trigger functions
state::set writes a value; state::get reads it (returns
```
null
```
for missing keys)
state::list retrieves all keys in a scope; state::delete removes a key
state::update performs a partial merge using an
```
ops
```
array for fine-grained changes
Payloads use
```
scope
```
,
```
key
```
, and
```
value
```
to address state entries
State is shared across all functions — use meaningful scope names to avoid collisions

Architecture

Function
  → trigger('state::set', { scope, key, value })
  → trigger('state::get', { scope, key })
  → trigger('state::update', { scope, key, ops })
  → trigger('state::delete', { scope, key })
  → trigger('state::list', { scope })
    → StateModule → KvStore / Redis adapter

iii Primitives Used

Primitive	Purpose
`trigger({ function_id: 'state::set', payload })`	Write a value to state
`trigger({ function_id: 'state::get', payload })`	Read a value from state
`trigger({ function_id: 'state::list', payload })`	List all keys in a scope
`trigger({ function_id: 'state::delete', payload })`	Remove a key from state
`trigger({ function_id: 'state::update', payload: { ops } })`	Partial merge with operations array

Reference Implementation

See ../references/state-management.js for the full working example — functions that read, write, update, and delete state entries across a shared scope.

Also available in Python: ../references/state-management.py

Also available in Rust: ../references/state-management.rs

Common Patterns

Code using this pattern commonly includes, when relevant:

```
registerWorker(url, { workerName })
```
— worker initialization

trigger({ function_id: 'state::set', payload: { scope, key, value } })

— write state

trigger({ function_id: 'state::get', payload: { scope, key } })

— read state (returns

null

if missing)

trigger({ function_id: 'state::update', payload: { scope, key, ops } })

— partial merge

trigger({ function_id: 'state::list', payload: { scope } })

— enumerate keys

trigger({ function_id: 'state::delete', payload: { scope, key } })

— remove entry

```
const logger = new Logger()
```
— structured logging

Adapting This Pattern

Use the adaptations below when they apply to the task.

Name scopes after your domain (e.g.
```
user-sessions
```
,
```
order-data
```
,
```
config
```
)
Use
```
state::get
```
with a
```
null
```
check to handle missing keys gracefully
Use
```
state::update
```
with
```
ops
```
for partial updates instead of read-modify-write cycles
Combine with
```
iii-queue-processing
```
to persist results after async job completion

Engine Configuration

StateModule must be enabled in iii-config.yaml with a KvStore adapter (file-based or Redis). See ../references/iii-config.yaml for the full annotated config reference.

Pattern Boundaries

If the task needs reactive side effects when state changes, prefer
```
iii-state-reactions
```
.
If the task needs real-time client push when data updates, prefer
```
iii-realtime-streams
```
.
Stay with
```
iii-state-management
```
when the primary need is reading and writing persistent key-value data.

When to Use

Use this skill when the task is primarily about
```
iii-state-management
```
in the iii engine.
Triggers when the request directly asks for this pattern or an equivalent implementation.

Boundaries

Never use this skill as a generic fallback for unrelated tasks.
You must not apply this skill when a more specific iii skill is a better fit.
Always verify environment and safety constraints before applying examples from this skill.