LangGraph Checkpoint Base Interfaces

4.0.1 · active · verified Sun Mar 29

LangGraph-checkpoint provides the base interfaces for checkpoint savers within the LangGraph framework (version 4.0.1). It defines the fundamental persistence layer, allowing LangGraph agents to save and restore their state across interactions, which is crucial for features like human-in-the-loop workflows, conversational memory, and time-travel debugging. This library also includes a default in-memory checkpointer for testing and experimentation. It releases frequently, often in conjunction with the main `langgraph` library.

Warnings

breaking The `thread_ts` parameter was renamed to `checkpoint_id` in `langgraph-checkpoint` v1.0.0. While `thread_ts` is currently still recognized, it's deprecated. Update your code to use `checkpoint_id` for clarity and future compatibility.
Fix: Replace `thread_ts` with `checkpoint_id` in your graph configuration (e.g., `{"configurable": {"thread_id": "1", "checkpoint_id": "some_uuid"}}`).
breaking Due to the move to namespace packages, direct imports like `from langgraph.checkpoint import BaseCheckpointSaver` are no longer valid. You must use the fully qualified path.
Fix: Change import statements from `from langgraph.checkpoint import Symbol` to `from langgraph.checkpoint.module import Symbol` (e.g., `from langgraph.checkpoint.base import BaseCheckpointSaver`).
gotcha When using any checkpointer, `thread_id` is a mandatory configuration parameter for graph invocations to enable state persistence. Without it, the checkpointer cannot save or retrieve state.
Fix: Always include `{"configurable": {"thread_id": "your_unique_thread_id"}}` in your `graph.invoke()` or `graph.stream()` calls.
gotcha For database-backed checkpointers (e.g., SQLite, PostgreSQL, MySQL), the `.setup()` method must be called on the checkpointer instance to create necessary tables before first use.
Fix: Ensure you call `checkpointer.setup()` (or `await checkpointer.asetup()` for async) after initializing a database checkpointer.
gotcha In `langgraph-checkpoint-postgres` versions 2.0.22 and higher, metadata serialization changed. Non-JSON serializable objects (e.g., `HumanMessage` instances directly) stored in checkpoint metadata will now raise errors, as metadata is passed as JSONB.
Fix: Ensure that any objects stored in checkpoint metadata are JSON serializable. Convert complex Python objects to their JSON-compatible representations before storing them, or move non-JSON data to dedicated channel blobs.
breaking Security vulnerabilities (CVE-2026-28277 for unsafe msgpack deserialization and CVE-2026-27022 for Redis query injection) have been disclosed impacting LangGraph's checkpoint system for certain backend implementations. These can lead to remote code execution or query injection.
Fix: Immediately update to the latest versions of `langgraph-checkpoint` and any specific `langgraph-checkpoint-*` backend libraries you are using. Review your usage of community-contributed checkpointers for similar vulnerabilities.

Install

pip install langgraph-checkpoint Install base library

Imports

BaseCheckpointSaver
```
from langgraph.checkpoint.base import BaseCheckpointSaver
```
Due to the transition to namespace packages, direct re-exported imports from `langgraph.checkpoint` are no longer supported since LangGraph v0.2 / langgraph-checkpoint v1.0.0.
InMemorySaver
```
from langgraph.checkpoint.memory import InMemorySaver
```
The in-memory saver is provided for development and testing.
JsonPlusSerializer
```
from langgraph.checkpoint.serde.jsonplus import JsonPlusSerializer
```
The default serializer for checkpoint data, handling various Python types.

Quickstart

This quickstart demonstrates how to set up a basic `StateGraph` and configure it with the `InMemorySaver` from `langgraph-checkpoint`. The `InMemorySaver` is suitable for local development and testing, saving state in memory. For persistent storage, you would typically use an external checkpointer like `PostgresSaver` or `SqliteSaver` from their respective `langgraph-checkpoint-*` libraries.

import os
from typing_extensions import TypedDict
from langgraph.graph import StateGraph, START, END
from langgraph.checkpoint.memory import InMemorySaver

# Define the state for the graph
class AgentState(TypedDict):
    messages: list[str]

# Define a simple node
def chat_node(state: AgentState) -> AgentState:
    # In a real agent, this would involve LLM calls or tool execution
    print(f"Processing: {state['messages'][-1]}")
    new_message = f"Echo: {state['messages'][-1]}"
    return {"messages": state["messages"] + [new_message]}

# Build the graph
builder = StateGraph(AgentState)
builder.add_node("echo_chat", chat_node)
builder.add_edge(START, "echo_chat")
builder.add_edge("echo_chat", END)

# Initialize the in-memory checkpointer
checkpointer = InMemorySaver()

# Compile the graph with the checkpointer
# A real LangGraph application would likely use a more complex graph and invoke it
# to test persistence.
# For this quickstart, we just demonstrate setup.
graph = builder.compile(checkpointer=checkpointer)

# Example of how you would invoke (not part of langgraph-checkpoint itself, but for context)
# config = {"configurable": {"thread_id": "1"}}
# inputs = {"messages": ["Hello LangGraph!"]}
# result = graph.invoke(inputs, config=config)
# print(result)

view raw JSON →