magnus919_agent-skills/langgraph/references/persistence.md

Persistence — Checkpointers and Stores

LangGraph provides two complementary persistence systems: checkpointers for short-term, thread-scoped memory and stores for long-term, cross-thread memory.

Checkpointer vs Store

Dimension	Checkpointer	Store
Persists	Graph state snapshots	Application-defined key-value data
Scope	A single thread	Across threads
Memory type	Short-term, thread-scoped	Long-term, cross-thread
Use for	Conversation continuity, HITL, time travel, fault tolerance	User preferences, facts, shared knowledge
Access	Pass thread_id in graph config	Read/write from nodes or application code

Checkpointers (Short-Term Memory)

A checkpointer saves snapshots of graph state after each superstep (node execution). This enables:

• Conversation continuity — resume a thread where it left off
• Human-in-the-loop — pause for input, then resume
• Time travel — replay from any checkpoint
• Fault tolerance — recover from crashes

Backends

from langgraph.checkpoint.memory import MemorySaver   # in-memory (dev only)
from langgraph.checkpoint.sqlite import SqliteSaver   # file-based (dev)
from langgraph.checkpoint.postgres import PostgresSaver  # production

Usage

checkpointer = MemorySaver()  # or PostgresSaver.from_conn_string(...)
checkpointer.setup()          # creates tables for persistent backends

graph = builder.compile(checkpointer=checkpointer)

# Each thread gets a unique thread_id
config = {"configurable": {"thread_id": "thread-123"}}

result = graph.invoke(
    {"messages": [{"role": "user", "content": "Hi, my name is Bob."}]},
    config=config,
)

# Resume on the same thread — graph remembers previous messages
result2 = graph.invoke(
    {"messages": [{"role": "user", "content": "What's my name?"}]},
    config=config,
)

Agent Server Handles Persistence Automatically

When deploying via LangSmith Agent Server, you do not need to implement or configure checkpointers manually. The server handles persistence infrastructure.

Stores (Long-Term Memory)

A store persists key-value data outside graph state, accessible across threads and sessions.

Usage

from langgraph.store.memory import InMemoryStore

store = InMemoryStore()

# Write to store from a node
def remember_user(state: MessagesState, store: InMemoryStore):
    user_id = extract_user_id(state["messages"])
    store.put(
        ("users", user_id),
        "preferences",
        {"theme": "dark", "language": "en"},
    )
    return {"messages": [AIMessage(content="Saved your preferences!")]}

# Read from store
config = {"configurable": {"thread_id": "1"}}
result = graph.invoke(inputs, config=config, store=store)

When to Use Store vs Checkpointer

Need	Use
Resume a conversation mid-stream	Checkpointer
Undo/redo across steps (time travel)	Checkpointer
Pause for human approval	Checkpointer
Remember user preferences across sessions	Store
Share data between unrelated threads	Store
Learn facts that persist beyond conversation	Store

Checkpointer Troubleshooting

thread_id too long (PostgresSaver)

Keep thread_id under 255 characters. Use UUID or hash:

import uuid
config = {"configurable": {"thread_id": str(uuid.uuid4())[:255]}}

MemorySaver doesn't persist between restarts

In-memory checkpointers are lost on process restart. Use PostgresSaver or SqliteSaver for persistence.

Checkpoints growing unboundedly

Long conversations accumulate checkpoints. Prune periodically or set retention:

# PostgresSaver — add a cron job to delete old checkpoints:
# DELETE FROM langgraph_checkpoints WHERE created_at < NOW() - INTERVAL '7 days'

State access from parent to subgraph

Subgraphs manage their own checkpoint namespace. Use Store for data that needs to cross graph boundaries, or configure the subgraph to write to the parent checkpoint.

Advanced: Subgraph Persistence Modes

See references/multi-agent-hierarchical.md for the full subgraph persistence reference. Summary:

Mode	checkpointer=	Behavior
Per-invocation (default)	None	Fresh each call, inherits parent checkpointer for HITL
Per-thread	True	State accumulates across calls
Stateless	False	No checkpointing, runs like plain function