> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usefused.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Checkpoints

> Persist private in-progress execution state for recovery, durable waits, and multiple replicas.

A checkpointer owns private state for an active invocation. It is separate from the [session store](/harnest/runtime/session-storage), which owns committed conversation history and application session data.

When Harnest owns portable checkpoint storage, it keeps:

| Harnest-owned checkpoint state | Purpose                                                                   |
| ------------------------------ | ------------------------------------------------------------------------- |
| Run status                     | Coordinate running, waiting, completed, failed, and cancelled transitions |
| Framework snapshots            | Resume ADK or LangGraph execution through the selected adapter            |
| Pending writes                 | Preserve parallel framework work until it commits                         |
| Wait metadata                  | Resume durable tools and external continuations                           |

Native `LangGraphStore` and `ADKStore` authorities expose their framework's narrower checkpoint contract. They do not provide every Harnest-owned capability in this table.

Every application resolves exactly one checkpoint factory across its root and Runtime Plugin extensions. This example assumes the shared `PostgresStore` from `lib/state.py` in the [storage overview](/harnest/runtime/checkpoints-and-storage):

```python extensions/checkpoints.py theme={null}
from harnest.lib.state import state
from harnest.lifecycle import lifecycle


@lifecycle.storage.checkpoints
def checkpoints():
    """Provide the application's private checkpoint authority."""

    return state
```

Harnest-owned checkpoint operations are scoped by application, authenticated user, session, and run. Knowing a run ID alone does not grant access. Agent code should not read or mutate framework checkpoint state directly.

## Run multiple replicas

Point every replica at the same Harnest checkpointer. Atomic run and continuation transitions allow one replica to claim a resume while another safely observes it.

<Warning>
  `MemoryStore` cannot recover a durable tool across processes. Queued or external waits need a Harnest-owned checkpointer; an opaque native advanced-mode saver is insufficient.
</Warning>

See [Durable execution](/harnest/runtime/durable-execution) for replica recovery and response polling.

## Configure advanced framework ownership

Advanced LangGraph can compile with a Harnest adapter:

```python agent.py theme={null}
from harnest.agent import Agent
from harnest.lib.state import state

graph = builder.compile(
    checkpointer=state.as_langgraph_checkpointer(),
)
root_agent = Agent.advanced(graph)
```

If LangGraph owns a native saver, wrap that saver in `LangGraphStore`, use the wrapper to compile the graph, and return the same wrapper from `@lifecycle.storage.checkpoints`. Keep a separate `SessionStore` factory for committed conversation state.

For ADK-native ownership, create one `ADKStore(session_service)` in `lib/state.py`. Return that same object from the session and checkpoint factories so Harnest does not create a second session authority.

## Switch frameworks safely

Framework checkpoints are opaque and cannot be translated between ADK and LangGraph. Finish or cancel active runs before switching. Committed session state remains portable when the new application uses compatible session storage.

Harnest records privacy-safe OTEL mutation events, never checkpoint payloads, prompts, arguments, credentials, or results.

<Card title="Configure sessions separately" icon="messages" href="/harnest/runtime/session-storage">
  Persist committed conversation history and application data through the session authority.
</Card>