Agent State Management

How agents persist and manage their internal state.

State Storage

Agent state is stored in the SQLite database. Each agent has a JSON state blob that persists across restarts.

Saving State

Agents can save state during execution:

Agent Runtime
     │
     ├── save_state(key, value)
     │        ↓
     │   SQLite database
     │
     ├── load_state(key) → value
     │        ↑
     │   SQLite database
     │
     └── clear_state(key)

State and Restarts

When a supervisor restarts an agent:

1. The agent's WASM instance is destroyed
2. A new WASM instance is created
3. The agent can load its previous state from the database
4. Execution continues from the saved state

State Inspection

naos inspect researcher --state

# Agent: researcher
# State:
#   last_query: "AI trends 2025"
#   results_count: 15
#   checkpoint: "step-3"

State Size Limits

Best Practices

1. Save frequently — Don't lose work on crashes
2. Save incrementally — Don't rewrite the entire state every time
3. Keep state small — Large states slow down restarts
4. Use checkpoints — For long-running tasks, save progress markers