---
title: "Agent State"
description: "How agents persist and manage their internal state. Agent state is stored in the SQLite database. Each agent has a JSON state blob that persists across restarts. Agents can save state during execution: When a supervisor "
resource: https://www.aiagents.nexus/docs/manual/agents/agent-state
generated: { by: "process:nexus-agent-assets", at: 2026-09-07T09:13:03Z }
status: stable
---

# 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

```bash
naos inspect researcher --state

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

## State Size Limits

| Tier | Max State Size |
|------|---------------|
| Default | 1 MB |
| Extended | 10 MB |
| Edge (Durable Objects) | 128 KB per key |

## 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