LangGraph Checkpointer in Practice: How to Choose Between MemorySaver, SQLite, and Redis

What This Guide Covers

• What core data does the LangGraph Checkpointer actually save in the state machine?
• Can MemorySaver (or InMemorySaver) truly be used in production environments?
• For what kind of projects is the SQLite Checkpointer suitable, and what are its concurrency and read/write limitations?
• In which high-concurrency scenarios is the Redis Checkpointer appropriate, and what prerequisite Redis modules are required?
• What is the underlying physical addressing relationship between thread_id and the Checkpointer?
• Why is the Checkpointer indispensable for Human-in-the-loop workflows and failure recovery mechanisms?
• How should individual developers and professional teams approach Checkpointer architecture selection at different stages of their business?

---

Who This Guide Is For

• Backend and full-stack engineers who have successfully run local LangGraph demos and are preparing to deploy Agent services into production.
• AI system architects designing multi-turn conversations, approval workflows, exception retries, or long-running asynchronous execution tasks.
• Developers struggling to choose between MemorySaver, SQLite, Redis, and Postgres due to uncertainty about their respective pros, cons, and applicable boundaries.
• Designers planning highly available storage architectures for AI Agents on platforms like Synology NAS, lightweight VPSs, or Kubernetes container clouds.

---

1. A Beginner’s Hard-Nosed Practical Observation

In production environments with multiple instances or high concurrency, the state persistence strategy for an Agent is the critical dividing line that determines whether a system survives.

Yesterday, after playing two hours of badminton, I was in the locker room, drenched in sweat and changing clothes, when my phone started blowing up with alert emails. An Agent service for financial bill analysis, deployed in a container on my NAS, had crashed. Because another high-load task on the NAS had exhausted system memory, the Docker daemon triggered its OOM (Out-of-Memory) killer, physically terminating the Agent container.

Although the container automatically restarted via its restart policy, because I had taken a shortcut by passing the default memory-based Checkpointer (InMemorySaver in Python) during compilation, the state of the 15 long-chain financial audit flows—which were suspended and waiting for manual confirmation from an accountant—was completely wiped out. The user interface reset instantly, and the preliminary analysis data, which had taken 20 minutes and consumed tens of thousands of tokens to generate, vanished.

The token cost was minor, but the user’s trust in the system’s stability plummeted to rock bottom. I sat in my car on the drive home, still wearing wet clothes, reflecting on this painful lesson. During local single-machine testing, the out-of-the-box convenience of the memory Checkpointer created an illusion of system stability. However, once real-world concurrency, container drift, human review interrupts, or long-running processes come into play, Checkpointer selection and thread_id design become the only reliable safety net.

---

2. The Underlying Physical Mechanisms and State Anatomy of Checkpointers

Where This Article Fits in the LangGraph Series

This article specifically addresses “Checkpointer Selection and State Persistence.” If you haven’t yet designed your ID hierarchy, start with [how to design thread_id, session_id, and user_id hierarchies (). If you already need human approval pauses and resumption, move on to [Human-in-the-loop Approval Workflows (). If you are concerned about recovery strategies after errors, see [Tool Errors, Timeouts, and Retry Strategies ().

Practical Review Checklist

Before pushing the Checkpointer to production, complete at least these 5 checks:

• After a container restart, can the same thread_id be restored to its last checkpoint?
• Will multiple concurrent tasks from the same user write to different thread_id instances?
• Have the backup and recovery commands for SQLite / Redis / Postgres actually been tested in practice?
• If a Human-in-the-loop suspension exceeds 24 hours, can the state still be recovered?
• Can error logs simultaneously pinpoint thread_id, the checkpoint ID, the current node, and the cause of failure?

The Checkpointer captures snapshots of the directed graph at the end of each node’s execution, serializes them, and binds them to a unique thread_id. This provides the physical foundation for Agent task retries, time travel, and human approval.

We need to make one thing clear: the Checkpointer does not solve ordinary caching problems; it solves durable execution. When we pass a checkpointer during Graph compilation, LangGraph automatically intercepts and saves the current graph state snapshot after every step of the graph’s execution (i.e., after each node finishes running).

These snapshots are organized by thread_id. A thread is like a branch in Git, recording all historical commits (checkpoints) for that thread. Each checkpoint contains not only the current state dictionary but also extremely rich physical metadata.

To give everyone an intuitive sense of this, let’s look at the simplified physical data structure of a real LangGraph checkpoint after serialization:

{
  "thread_id": "usr_9982:billing_audit:task_20260615_001",
  "checkpoint_id": "1ef23b8f-89a1-6a20-b001-c91823abf100",
  "current_node": "agent_review_node",
  "state": {
    "messages": [
      {
        "type": "human",
        "content": "帮我审计 5 月份的差旅发票"
      },
      {
        "type": "ai",
        "content": "",
        "tool_calls": [
          {
            "name": "fetch_invoices",
            "args": {
              "month": "2026-05"
            },
            "id": "call_tx_9982"
          }
        ]
      }
    ],
    "invoice_list": [],
    "audit_status": "pending_fetch"
  },
  "pending_action": null,
  "error_state": null,
  "metadata": {
    "source": "loop",
    "step": 2,
    "run_id": "run_0f8e91cd-89b2-44a1-b873-120aef2b001f"
  },
  "created_at": "2026-06-15T10:28:29Z"
}

As the structure above shows, the Checkpointer records:

• The specific node in the current graph: This tells the state machine which Node to start executing from when it is next awakened.
• Complete State data: Including conversation message history (the messages list) and custom business state fields (such as invoice_list).
• Error states and pending actions: If a node throws an exception during execution, or if an interrupt_before breakpoint is configured before a node, this records the pending tool calls or exception information.
• Metadata: Contains step counts, run_id for individual runs, etc., for observability path analysis.

With this foundation, when an Agent is unexpectedly interrupted due to network fluctuations, API timeouts, or container restarts, we only need to pass the same thread_id. LangGraph will retrieve the latest physical snapshot from the underlying Checkpointer, perfectly restoring the context and continuing unfinished steps without needing to reissue requests to the LLM for preceding nodes.

---

3. MemorySaver / InMemorySaver: Suitable for Demos, Not for Production

The sole value of memory-based Checkpointers is zero-configuration out-of-the-box usability. Because they lack persistent storage, any process restart or multi-instance load balancing will cause the state to vanish instantly.

In the Python documentation, the official examples commonly use InMemorySaver; in the JavaScript/TypeScript version, the corresponding name is MemorySaver. Their physical essence is identical: they maintain a dict or Map in process memory to read and write checkpoint objects.

When used for local development, running unit tests, or quickly validating a state machine branch logic, their usage is extremely straightforward:

from langgraph.checkpoint.memory import MemorySaver
from langgraph.graph import StateGraph

# 初始化内存 checkpointer
memory_checkpointer = MemorySaver()

# 编译 Graph 并挂载持久化组件
graph = builder.compile(checkpointer=memory_checkpointer)

# 传入 thread_id 启动多轮交互
config = {"configurable": {"thread_id": "local_demo_thread"}}
result = graph.invoke({"input": "开始我的分析任务"}, config=config)

However, the in-memory checkpointer has three fatal physical flaws that make it absolutely unsuitable for production deployment:

1. Process-resident limitations: If your application is deployed on a Kubernetes cluster, managed by PM2, or hosted on a Serverless platform like Vercel, new processes start empty during container scaling, node drift, or automatic restarts after crashes. Once user requests are routed to a new instance by the load balancer, the preceding state is lost, resulting in errors.

2. Memory capacity exhaustion (OOM) risk: As conversation turns and concurrent users accumulate, the checkpoint list stored in process memory grows indefinitely. The message history within each checkpoint consumes significant memory, which can directly cause the application process to be forcibly killed by the system due to memory leaks or exhaustion.

3. Inability to persistently audit state: Once the service undergoes a hot update or a normal maintenance restart, all historical execution chains physically evaporate, making them unavailable for subsequent product data tracing and compliance auditing.

Therefore, unless you are writing single-machine scripts or running local pytest tests, you should physically remove InMemorySaver from your dependencies at the very beginning of the project’s inception.

---

4. SQLite Checkpointer: A Low-Cost Choice for Personal Projects and Single-Machine Deployments

SQLite provides zero-deployment-cost disk-level persistence with support for both synchronous and asynchronous drivers, making it an ideal choice for single-machine applications and small-scale tool sites, though it requires handling database lock barriers under concurrent writes.

If your Agent service is currently a tool-type site developed by a single person, or if it is deployed on an independent cloud server or even a private NAS device, SQLite is an extremely cost-effective choice. It ensures that state remains intact after process restarts without requiring you to additionally manage complex database clusters.

LangGraph officially provides a standalone extension package langgraph-checkpoint-sqlite to support SQLite persistence. It includes the synchronous SqliteSaver and the asynchronous AsyncSqliteSaver implemented based on aiosqlite.

Let’s look at a practical code example of standard initialization for AsyncSqliteSaver in an asynchronous application (such as FastAPI):

import asyncio
import os
from langgraph.checkpoint.sqlite.aio import AsyncSqliteSaver
from langgraph.graph import StateGraph

# 定义 SQLite 数据库文件路径
DB_PATH = "data/agent_checkpoints.db"
os.makedirs(os.path.dirname(DB_PATH), exist_ok=True)

async def run_agent_workflow():
    # 使用上下文管理器安全创建并管理 SQLite 连接池
    async with AsyncSqliteSaver.from_conn_string(DB_PATH) as checkpointer:
        # 执行一次性的物理建表操作（如果表不存在）
        await checkpointer.asetup()

        # 编译有向图，绑定 SQLite 异步 Checkpointer
        graph = builder.compile(checkpointer=checkpointer)

        # 定义唯一的 thread_id 进行任务追踪
        config = {"configurable": {"thread_id": "sqlite_user_task_4451"}}

        # 启动异步图执行
        async for event in graph.astream(
            {"messages": [("user", "分析这篇文档的结构")]},
            config=config,
            stream_mode="values"
        ):
            print(event)

# 启动任务
asyncio.run(run_agent_workflow())

When using SQLite, you need to be aware of the following two physical pitfalls:

• Database connection lock barrier: SQLite is essentially a single-file database. While it supports concurrent reads across multiple processes and threads, high-frequency concurrent writes (e.g., 10 users concurrently calling an Agent) can easily trigger sqlite3.OperationalError: database is locked. To mitigate this issue, you must add the check_same_thread=False parameter to your connection string and enable WAL (Write-Ahead Logging) mode when necessary to allow concurrent read/write operations.
• Data fragmentation and capacity bloat: As the number of Agent execution steps increases, data in the checkpoints and checkpoint_writes tables expands rapidly. You need to configure Cron on the server to periodically execute the VACUUM command; otherwise, the database file will grow uncontrollably and quickly consume all available disk space.

---

5. Redis Checkpointer: A Tool for High Concurrency and Low-Latency State Management

Redis Checkpointer is the preferred choice for horizontally scaling multiple instances and managing low-latency, high-concurrency Agents. However, because it relies on memory, it requires an additional relational database mount for long-term auditing and compliance tracing.

If your Agent service has a large daily active user base and is deployed across multiple instances in a distributed Kubernetes cluster, where users have strict requirements for response latency, a Redis-based persistence solution is the best match.

Redis operates in memory, offering sub-millisecond read/write response speeds, which significantly reduces the overhead of saving snapshots during state machine transitions on each node. The official LangGraph integration package provides langgraph-checkpoint-redis, which includes RedisSaver and ShallowRedisSaver for memory optimization.

There is one mandatory prerequisite when using the Redis Saver: the connected Redis instance must support the “RedisJSON” and “RediSearch” official modules. This is because LangGraph relies on JSON format parsing and secondary index searching when retrieving states and backtracking historical snapshots for specific threads. If you are using an older version of Redis or a default Redis container image without these modules installed, calling the setup method will result in an immediate error and crash.

Let’s look at the complete practical code for the Redis Saver:

from langgraph.checkpoint.redis import RedisSaver
from langgraph.graph import StateGraph

# Redis 连接字符串，注意在生产环境一定要开启认证和 SSL
REDIS_URI = "redis://:[email protected]:6379/0"

# 初始化 RedisSaver
redis_checkpointer = RedisSaver.from_conn_string(REDIS_URI)

# 物理建索引，对于一个全新的 Redis 实例，这一步必须执行且只需执行一次
redis_checkpointer.setup()

# 编译 Graph 绑定 Redis 持久化层
graph = builder.compile(checkpointer=redis_checkpointer)

# 设置 thread_id 并唤醒执行
config = {"configurable": {"thread_id": "redis_thread_9872"}}
graph.invoke({"messages": [("user", "执行系统健康检查")]}, config=config)

In Redis architecture selection, we must consider the following critical design factors:

• Memory capacity protection (ShallowRedisSaver): The default RedisSaver saves the complete checkpoint history for every thread. If an Agent engages in hundreds of rounds of conversation with a user, the state is saved verbatim each time. This causes Redis memory to fill up rapidly. To mitigate this, use ShallowRedisSaver, which employs an overwrite mechanism, retaining only the latest checkpoint node per thread_id in Redis. While this prevents “time travel” (loading historical versions), it ensures constant memory usage.

• Memory eviction and persistence strategies: In production environments, you must disable the allkeys-lru or volatile-lru memory eviction policies on your Redis instances. If Redis automatically evicts the latest checkpoint for active threads due to memory pressure, the user’s Agent workflow will crash with errors in the next conversation turn. Additionally, you must enable AOF (Append Only File) persistence with everysec sync mode to prevent data loss from uncommitted states in the event of a Redis process crash or physical power outage.

---

6. Postgres: The Ultimate Physical Home for Production

The PostgresCheckpointer provides the most secure and reliable persistence guarantees for large-scale distributed Agent systems by leveraging robust relational database transactions, efficient JSONB retrieval, and high-availability disaster recovery capabilities.

When building an enterprise-grade, multi-tenant Agent platform that supports long task lifecycles and requires regulatory compliance, data auditing, and historical call analysis, Postgres is the only viable physical storage solution.

In fact, LangChain’s official managed service, LangSmith Agent Server, uses Postgres as the underlying storage medium for checkpoint data by default. Through the langgraph-checkpoint-postgres package, we can easily build highly available enterprise-grade Agents.

Here, I must share a subtle pitfall that cost me an entire day: If you prefer not to use the default connection string factory and instead want to manually manage the connection pool (e.g., reusing an existing database connection pool in FastAPI), you must enable the following two configurations during initialization:

1. 1 and autocommit=True: LangGraph’s table creation and state update operations rely on non-blocking transaction commits. If these are not enabled, the .setup() method will either deadlock permanently or throw a transaction exception when creating the checkpoints table.
2. 2 and row_factory=dict_row: LangGraph internally extracts database rows based on column name key-value pairs (e.g., row["checkpoint_id"]). Using the default tuple row factory will cause parsing errors, resulting in an KeyError exception and a crash.

Below is the production-grade code for manually managing connections and initializing PostgresSaver:

import psycopg
from psycopg.rows import dict_row
from langgraph.checkpoint.postgres import PostgresSaver

DB_URI = "postgresql://agent_admin:[email protected]:5432/agent_store"

# 建立数据库连接，必须配置 autocommit 和 dict_row
conn = psycopg.connect(DB_URI, autocommit=True, row_factory=dict_row)

# 将连接对象传给 PostgresSaver
postgres_checkpointer = PostgresSaver(conn)

# 创建 checkpoints 相关的物理表结构
postgres_checkpointer.setup()

# 编译 Graph，开启生产级安全策略
graph = builder.compile(checkpointer=postgres_checkpointer)

# 传入符合企业级规范的 thread_id
config = {
    "configurable": {
        "thread_id": "org_100:user_200:task_abc",
        "strict_msgpack": True # 开启此选项，可物理限制反序列化安全类型
    }
}

To mitigate the physical risk of remote code execution (RCE) caused by third-party library deserialization vulnerabilities, you must set the LANGGRAPH_STRICT_MSGPACK=true environment variable in production. This ensures that when reading and restoring State from Postgres, only trusted built-in data types are deserialized.

---

7. Deep Dive: Benchmarking the Four Checkpointer Backends

When selecting an architecture, we need to compare each solution’s latency, concurrency, disaster recovery capabilities, and operational complexity to determine the most suitable persistence backend for the current business stage.

To facilitate quick decision-making, I have organized these four typical Checkpointer options into a comparative table:

Physical Dimension	MemorySaver	SQLite	Redis	Postgres
Ideal Use Case	Tutorial demos, local unit tests	Personal tools, single-node deployment, lightweight backends	High-concurrency short sessions, low-latency distributed services	Distributed multi-user, enterprise-grade long-task auditing
Operational Cost	Zero cost, no external dependencies	Extremely low, single-file management	Moderate, requires additional memory module configuration	High, requires a highly available relational database
Concurrency Capability	Limited to single-process concurrency	Weak; multi-threaded writes easily lock the database	Extremely strong, high-throughput concurrency	Strong, supports connection pools and high-concurrency transactions
Disaster Recovery & Persistence	Physically evaporates upon restart	Disk-level persistence; backups are required	Primarily memory-based, relies on AOF disk sync	Physically persisted, mature backup and recovery mechanisms
Time Travel Support	Supports full historical rollback	Supports full historical rollback	Configurable full or Shallow overwrite modes	Supports full history, facilitating JSONB query analysis
Physical Constraints	Limited by process-assigned RAM	Write locks limit suitability for high concurrency	Must be Redis Stack 8.0 or higher	Must configure autocommit and dict_row

---

8. Thread ID and State Isolation: Preventing Cross-Thread Contamination

The thread_id serves as the physical primary key for the Checkpointer when reading state. Without strict tenant isolation and robust owner verification, the system will inevitably face unauthorized access and catastrophic context cross-contamination.

In my recent development summaries, I explored this issue in depth. If all user requests blindly share a single thread_id, or if user_id is used directly as the thread_id, then under high-concurrency scenarios, User A’s operation snapshots will physically overwrite User B’s preceding states in the Checkpointer tables, causing the state machine’s context to instantly cross-contaminate.

When designing production interfaces, we must standardize thread_id as a composite key. For example, we define: thread_id = user_id + business_type + task_id

Furthermore, the API gateway layer must not pass the client-supplied thread_id directly to the directed graph compilation layer. Instead, it must construct a physical barrier based on owner verification to prevent privilege escalation. Below is the pseudo-code for the strong validation logic I designed at the gateway interception layer:

# API 属主强校验层
def process_incoming_request(user_context: dict, client_payload: dict):
    current_user_id = user_context["user_id"]
    requested_thread_id = client_payload["thread_id"]

    # 物理截取校验：thread_id 的第一段必须是当前已登录的用户 ID
    thread_parts = requested_thread_id.split(":")
    if len(thread_parts) < 3 or thread_parts[0] != current_user_id:
        raise PermissionError("物理安全阻断：试图读取不属于当前登录用户的 Checkpoint 状态")

    config = {
        "configurable": {
            "thread_id": requested_thread_id,
            "user_id": current_user_id
        }
    }

    # 从数据库中拉取并恢复
    return graph.invoke({"input": client_payload["prompt"]}, config=config)

9. Common Pitfalls and Error Logs

Avoiding common compilation and runtime errors is a necessary prerequisite for ensuring that the Checkpointer reliably performs state recovery.

Based on my practical experience troubleshooting these issues, the following error messages appear most frequently. If you see similar logs in your console, you can directly apply my step-by-step troubleshooting guide to resolve them:

1. SQLite Lock Database Errors

sqlite3.OperationalError: database is locked

• Cause: Under high-concurrency requests, multiple threads attempt to write to the SQLite checkpoint_writes table simultaneously.
• Solution: When configuring AsyncSqliteSaver.from_conn_string, ensure that a connection timeout is set (timeout=30) and configure WAL mode at the SQLite database level.

2. Postgres Connection Hangs and Configuration Errors

psycopg.errors.ActiveSqlTransaction: CREATE TABLE cannot run inside a transaction block

Or throw it when reading the data:

KeyError: 'checkpoint_id'

• Root cause: The absence of an explicit autocommit=True configuration causes DDL statements to deadlock, or the lack of row_factory=dict_row prevents LangGraph from physically extracting data rows as dictionaries.
• Solution: When creating the psycopg connection object, explicitly specify autocommit=True, row_factory=dict_row.

3. Redis Index Missing Error

redis.exceptions.ResponseError: Cannot create index: ft.create require RediSearch module v2.0+

• Cause: The Redis image used is a standard Redis Server, which lacks the core RedisJSON or RediSearch modules.
• Solution: Replace the Redis image with redis/redis-stack-server:latest, or confirm with your Redis cloud hosting provider that these two module plugins are enabled.

4. Serialization Failure Error

TypeError: Object of type CustomToolResult is not JSON serializable

• Root cause: Your Tool returned an object that is a custom Python class instance (for example, directly returning a database ORM object) instead of converting it to a basic dict or JSON string. The Checkpointer cannot serialize this complex object into a byte stream when saving the graph state to disk.
• Solution: Ensure that all data returned by your Tool function to the Node consists of standard primitive types (str, int, dict, list).

---

10. Production Readiness Checklist & FAQ

Production Readiness Checklist

• Have you completely removed MemorySaver / InMemorySaver from your production dependencies?
• If using SQLite, have you enabled WAL mode and configured a script for automatic VACUUM?
• If using Redis, have you selected the redis-stack image and disabled the automatic memory eviction policy to prevent loss of active states?
• If using Postgres, did you force-enable autocommit=True and row_factory=dict_row during connection initialization?
• Have you configured LANGGRAPH_STRICT_MSGPACK=true in your environment variables to ensure secure deserialization?
• Does your API interface layer perform strict validation on the thread_id passed by clients to prevent cross-tenant state leakage due to unauthorized access?
• When a Tool execution throws an exception, can the Checkpointer correctly save error_state and suspend the state to support subsequent retries?

---

FAQ

Since MemorySaver is not suitable for production, why is it still a staple in official examples?

Its sole purpose is to lower the barrier to entry. To help beginners quickly run Agent demos without needing to install and configure SQLite, Redis, or Postgres, the default configuration uses an in-memory Saver. However, in real-world commercial applications, process memory is an unsafe, temporary medium.

If my SQLite file gets corrupted, can the Agent recover?

If the database file is corrupted and there is no backup, all thread states stored within that file are permanently lost. The Agent will be forced to create a new thread and start from scratch. For projects using SQLite, it is recommended to schedule a daily late-night backup of the .db file to physical cold storage (such as a dedicated drive on a Synology NAS).

How do I choose between ShallowRedisSaver and the standard RedisSaver?

If your business scenario does not require users to “click on a historical message card to restore to a specific past version” (i.e., Time Travel is unnecessary) and only requires the Agent to remember the most recent conversation state, we recommend using ShallowRedisSaver. This helps you save over 80% of Redis memory consumption.

Will frequent read/write operations by the Postgres Checkpointer slow down the Agent’s response time?

Under high-concurrency write loads, Postgres’s I/O overhead is indeed higher than Redis’s pure memory writes. If performance becomes a bottleneck, you can adopt a read-write separation architecture in your application design. Alternatively, use a Redis checkpointer to handle short-term conversation states, and asynchronously sync to Postgres for long-term persistent auditing only when the workflow is fully archived or at critical nodes such as triggering interrupts.

---

Series Navigation

LangGraph Production-Grade Agent Orchestration in Practice Series:

• Part 1: Supervisor / Worker
• Part 2: State Isolation
• Part 3: Human-in-the-loop
• Part 4: Failure Recovery
• Part 5: Observability
• Part 6: Checkpointer
• The 7th article in the Subgraph series

Continue reading

• LangGraph State Isolation in Practice: How to Design thread_id, session_id, and user_id?
• LangGraph Human-in-the-loop in Practice: How to Implement Multi-Agent Approval Workflows?
• LangGraph Multi-Agent Failure Recovery: Tool Errors, Timeouts, and Retry Strategies
• LangGraph Observability in Practice: How to Track the Decision Path of Each Agent?
• LangGraph Multi-Agent Collaboration in Practice: How to Design Supervisor, Worker, and State Handoff?
• LangGraph Memory and Checkpointing for Production AI Agents

Topic path / LangGraph

Continue through the production LangGraph learning path

The LangGraph hub organizes state isolation, checkpointing, human approval, retries, observability, supervisors, subgraphs and memory into one reviewable path.

Open LangGraph hub → Start with state isolation Subscribe for updates