# `Sagents.AgentPersistence`

Behaviour for persisting agent state snapshots.

Implement this behaviour in your application to enable automatic
state persistence at key lifecycle points. If no persistence module
is configured, AgentServer operates entirely in-memory.

## Lifecycle Contexts

The `context` parameter indicates why persistence was triggered:

| Context | When | Notes |
|---------|------|-------|
| `:on_completion` | Agent execution completes successfully (status → :idle) | Most common persistence point |
| `:on_error` | Agent execution fails (status → :error) | Preserves state up to the error |
| `:on_interrupt` | Execution paused for HITL approval (status → :interrupted) | Preserves interrupt context |
| `:on_title_generated` | Conversation title auto-generated | State includes updated metadata |
| `:on_shutdown` | Agent process terminating (inactivity timeout, node shutdown) | Best-effort — DB may also be shutting down |

## Configuration

Per-agent via AgentServer start options (passed through AgentSupervisor):

    supervisor_config = [
      agent_id: agent_id,
      agent_persistence: MyApp.AgentPersistence,
      # ... other config
    ]

No configuration = no persistence. AgentServer works fine without it.

# `context`

```elixir
@type context() ::
  :on_completion
  | :on_error
  | :on_interrupt
  | :on_title_generated
  | :on_shutdown
```

# `load_state`

```elixir
@callback load_state(agent_id :: String.t()) ::
  {:ok, map()} | {:error, :not_found | term()}
```

Called to load a previously persisted state when starting an agent.

Returns the serialized state map, or `{:error, :not_found}` if no
saved state exists (normal for first-time agents).

# `persist_state`

```elixir
@callback persist_state(agent_id :: String.t(), state_data :: map(), context :: context()) ::
  :ok | {:error, term()}
```

Called when the agent should persist its current state.

`agent_id` is the agent's identifier.
`state_data` is the serialized state map (string keys, JSON-compatible)
  as returned by `StateSerializer.serialize_server_state/2`.
`context` indicates why persistence was triggered.

Return `:ok` on success. Errors are logged but do not affect agent operation.

---

*Consult [api-reference.md](api-reference.md) for complete listing*