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

# Checkpoint

> Zeus Checkpoint state persistence

> LangGraph Checkpointer is used to persist Agent execution state, supporting HITL (Human-in-the-Loop) interrupt recovery and session persistence.

***

## 1. Overview

### 1.1 Role of Checkpointer

| Feature                       | Description                                                                                       |
| ----------------------------- | ------------------------------------------------------------------------------------------------- |
| **Session State Persistence** | Saves message history, tool call stack, and current step during Agent execution                   |
| **HITL Interrupt Recovery**   | Pauses execution and saves state when a tool requires human approval, then resumes after approval |
| **History Replay**            | Navigate to any checkpoint to view or replay the execution process                                |
| **Service Restart Recovery**  | Resume execution from the most recent checkpoint after a service restart                          |

### 1.2 Differences from Other Components

| Component        | Stored Content                                    | Granularity        | Lifecycle                  |
| ---------------- | ------------------------------------------------- | ------------------ | -------------------------- |
| **Checkpointer** | Agent execution state (messages, tool call stack) | Per execution step | Session-level (thread\_id) |
| **Backend**      | File system (user artifacts)                      | File operations    | User-level (user\_id)      |
| **Memory**       | Long-term memory (user knowledge, preferences)    | Concept-level      | Permanent                  |

***

## 2. Solution Comparison

### 2.1 Storage Solution Options

| Solution                             | Latency  | Durability                     | Cost   | Use Case                       |
| ------------------------------------ | -------- | ------------------------------ | ------ | ------------------------------ |
| **MemorySaver**                      | \~0.1ms  | ❌ Lost on service restart      | Free   | Development environment        |
| **PostgresSaver**                    | 5-20ms   | ✅ Strong durability            | Low    | **Recommended for production** |
| **RedisSaver**                       | 1-5ms    | ⚠️ Requires persistence config | Medium | High-frequency HITL scenarios  |
| **DrizzleCheckpointSaver (current)** | 50-100ms | ✅ Durable                      | Low    | Compatible with Next.js API    |

### 2.2 Recommendation: PostgresSaver

**Rationale**:

1. We already have a PostgreSQL database (Supabase/Drizzle), no additional dependencies required
2. Officially supported by LangGraph, stable and reliable
3. Acceptable latency (5-20ms)
4. Checkpoint history can be queried via SQL for easy debugging

***

## 3. Implementation Plan

### 3.1 Replace DrizzleCheckpointSaver with PostgresSaver

Use the official LangGraph `AsyncPostgresSaver`, connecting to the database via the `DATABASE_URL` environment variable. During initialization, `setup()` is automatically called to create the required database tables.

### 3.2 Database Table Structure

PostgresSaver automatically creates a `checkpoints` table with the following key fields:

* `thread_id` - Session identifier
* `checkpoint_id` - Checkpoint identifier
* `parent_checkpoint_id` - Parent checkpoint identifier
* `checkpoint` - Checkpoint data (JSONB)
* `metadata` - Metadata (JSONB)
* `created_at` - Creation timestamp

The primary key is a composite key of `(thread_id, checkpoint_id)`, with indexes on `thread_id` and `created_at`.

***

## 4. HITL Workflow

```mermaid theme={null}
sequenceDiagram
    autonumber
    participant Agent
    participant Checkpointer as PostgresSaver
    participant Frontend as Frontend
    participant User as User

    rect rgb(240, 248, 255)
        Note over Agent: 1. Agent Execution
        Agent->>Agent: Step 1: Analyze user requirements
        Agent->>Checkpointer: aput() save state
        Agent->>Agent: Step 2: Prepare to call dangerous_tool
        Agent->>Agent: interrupt_on match
    end

    rect rgb(255, 240, 240)
        Note over Agent,Frontend: 🛑 Interrupted!
        Agent->>Checkpointer: aput() save interrupt state
        Agent->>Frontend: Return on_interrupt event
        Note over Agent: Agent process can be released
    end

    rect rgb(255, 255, 240)
        Note over Frontend,User: 2. Awaiting User Approval
        Frontend->>User: Display approval request
        Note over User: Could be seconds, minutes, or even hours
        User->>Frontend: Approval decision
    end

    rect rgb(240, 255, 240)
        Note over Agent: 3. Resume After User Approval
        Frontend->>Agent: Command(resume=user_decision)
        Agent->>Checkpointer: aget() load state from interruption
        Agent->>Agent: Continue execution from Step 2...
    end
```

***

## 5. Migration Steps

### 5.1 Migrating from DrizzleCheckpointSaver to PostgresSaver

1. **Install dependencies** - Install `langgraph-checkpoint-postgres>=1.0.0`
2. **Modify base\_service.py** - Replace DrizzleCheckpointSaver references with AsyncPostgresSaver
3. **Update get\_checkpointer method** - Initialize using `AsyncPostgresSaver.from_conn_string()`
4. **Run database migration** - PostgresSaver will automatically create the required table structure
5. **Remove old code** - Delete DrizzleCheckpointSaver and related Next.js APIs

***

## 6. Monitoring and Debugging

Checkpoint history can be queried via SQL, including viewing all checkpoints for a session, finding checkpoints in an interrupted state, and cleaning up expired checkpoint data. It is recommended to add logging to track checkpoint load, save, and interrupt operations.

***

## 7. Summary

| Item         | Current State                     | Target State                      |
| ------------ | --------------------------------- | --------------------------------- |
| Checkpointer | DrizzleCheckpointSaver (HTTP API) | PostgresSaver (direct connection) |
| Latency      | 50-100ms                          | 5-20ms                            |
| Dependencies | Next.js API                       | No additional dependencies        |
| Durability   | ✅                                 | ✅                                 |
| HITL Support | ✅                                 | ✅                                 |