Principle:Langchain ai Langgraph Graph Persistence Compilation

Attribute	Value
Page Type	Principle
Library	langgraph
Workflow	Persistence_and_Memory_Setup
Principle	Graph_Persistence_Compilation
Implementation	Langchain_ai_Langgraph_StateGraph_Compile_With_Persistence
Source	`libs/langgraph/langgraph/graph/state.py:L1035-1153`

Overview

Compiling a graph with a checkpointer is the step that activates automatic state persistence. When StateGraph.compile() is called with a checkpointer argument, every subsequent invocation of the compiled graph automatically saves and restores state using the provided backend. Optionally, a store can also be provided at compile time to enable cross-thread long-term memory.

Description

The compile() method transforms a StateGraph definition into a CompiledStateGraph (which extends Pregel), a runnable object that can be invoked, streamed, and managed. The persistence-related parameters are:

Checkpointer Parameter

The checkpointer parameter accepts three forms:

A checkpoint saver instance (e.g., InMemorySaver(), SqliteSaver(...), PostgresSaver(...)): Enables full persistence. The graph saves a checkpoint after each step and can resume from any checkpoint.
None (default): The graph may inherit the parent graph's checkpointer when used as a subgraph. As a top-level graph, no persistence is enabled.
False: Explicitly disables checkpointing. The graph will not use or inherit any checkpointer, even as a subgraph.

When a checkpointer is enabled, the caller must provide a thread_id in the config:

config = {"configurable": {"thread_id": "my-thread"}}
graph.invoke(inputs, config)

The thread_id serves as the primary key for state isolation. Each unique thread ID maintains its own independent state history.

Store Parameter

The store parameter accepts a BaseStore instance (e.g., InMemoryStore(), PostgresStore(...)). Unlike the checkpointer which provides thread-scoped short-term memory, the store provides cross-thread long-term memory. Data stored in the store is accessible from any thread and persists independently of graph execution state.

Interrupt Parameters

The interrupt_before and interrupt_after parameters work in conjunction with the checkpointer to enable human-in-the-loop workflows. When a graph is interrupted, its state is saved to the checkpoint, and execution can be resumed later by invoking the graph with the same thread_id.

Usage

The typical compilation flow for persistence:

Define your graph using StateGraph.
Create a checkpointer instance appropriate for your environment.
Optionally create a store instance for cross-thread memory.
Call compile(checkpointer=..., store=...).
Invoke the compiled graph with a thread_id in the config.

The checkpointer and store are injected into the compiled graph and become available to all nodes during execution. Nodes do not need to be aware of persistence details; the runtime handles save/restore transparently.

Theoretical Basis

The compilation step implements the Dependency Injection pattern: persistence backends are provided as external dependencies at compile time rather than being hardcoded into graph nodes. This separation of concerns means that:

The same graph definition can be compiled with different persistence backends for different environments (e.g., in-memory for tests, PostgreSQL for production).
Nodes remain pure functions of their inputs, with no side effects related to persistence.
The persistence layer can be tested independently of the graph logic.

The compiled graph acts as a Pregel-style computation engine (inspired by Google's Pregel system for graph processing). Each "super-step" corresponds to a batch of node executions, and the checkpointer captures the state between super-steps. This provides exactly-once execution semantics when combined with the channel versioning system.

The distinction between checkpointer (thread-scoped, automatic, checkpoint-based) and store (cross-thread, explicit, key-value-based) reflects the separation between working memory and long-term memory in cognitive architectures.

Related Pages

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment