5.2

Checkpointers and threads: short-term memory

A checkpointer saves the state of a thread after each step, so the next turn on the same thread_id starts from the last checkpoint, also after a restart.

You build a chat on create_agent, and the user asks "What did I ask you?". The agent has no idea, because each invoke started from an empty state. The model is not the cause. The agent keeps nothing between runs unless something saves the state.

When you finish this section, you can give an agent short-term memory, read a checkpoint, and size a Postgres saver for many threads.

A thread across two turns

Checkpointer: an object that saves the graph state after each step and loads the latest checkpoint when the next run starts. InMemorySaver, SqliteSaver, and PostgresSaver are checkpointers.

Thread: the series of checkpoints saved under one thread_id. A thread is the conversation, and each invoke on it is one turn.

The kit runs two turns on the thread memory-thread:

pythontwo turns on one threadFull log
def two_turns(cap, checkpointer, name):
    m = llm(name)
    agent = create_agent(m, tools=[add], checkpointer=checkpointer)
    cfg = thread(name)
    agent.invoke(ask("What is 2 + 3?"), cfg)
    out = agent.invoke(ask("What did I ask you?"), cfg)

The second turn passed one new message. The model got the whole first turn before it:

jsonwhat the model received on turn 2Full log
what the model received on turn 2:
[
  "human: What is 2 + 3?",
  "ai: calls add",
  "tool: 5",
  "ai: 2 + 3 = 5.",
  "human: What did I ask you?"
]

Qwen3 4B answered You asked what 2 + 3 is, and I calculated that it equals 5..

So short-term memory is the message list in the checkpoint. The add_messages reducer appends the new human message to it, and every model call gets all of it. The cost of a long thread is in section 5.5.

A run on a checkpointer needs a thread_id. Without one, the agent raises before it runs:

outputa checkpointer with no thread_idFull log
raised builtins.ValueError: Checkpointer requires one or more of the following 'configurable' keys: thread_id, checkpoint_ns, checkpoint_id

A new thread_id starts empty. In the kit, a second agent on the same saver with the thread other-thread saw only its own question. Asked What did I ask you?, the model said that this was their first exchange. delete_thread("memory-thread") removed all 8 checkpoints of the first thread.

You do not create a thread first. The first checkpoint creates it. The checkpointers page says that a thread must be created before a run, and that rule belongs to the Agent Server API. This manual records it as conflict D118.

What a checkpoint holds

Checkpoint tuple: what a checkpointer returns for one checkpoint: its config, its metadata, the checkpoint itself, the config of its parent, and its pending writes.

jsonthe latest checkpoint of the threadFull log
{
  "config": {
    "configurable": {
      "thread_id": "memory-thread",
      "checkpoint_ns": "",
      "checkpoint_id": "<uuid-1>"
    }
  },
  "metadata": {
    "source": "loop",
    "step": 6,
    "parents": {},
    "ls_integration": "langchain_create_agent"
  },
  "checkpoint keys": [
    "channel_values",
    "channel_versions",
    "id",
    "ts",
    "updated_channels",
    "v",
    "versions_seen"
  ],
  "channel_values keys": [
    "__pregel_tasks",
    "messages"
  ],
…
  "v": 4
}
The channel versions are cut.

channel_values holds the state: here the messages list. channel_versions and versions_seen tell the loop which nodes have new input, so a resume runs the right node next. checkpoint_ns is empty for the top graph and names the parent node inside a subgraph.

SqliteSaver across a restart

InMemorySaver keeps its checkpoints in the process. The persistence page says that they are gone when the process restarts. Use it for tests. A file or a database keeps a thread across a restart. The kit runs two turns on SqliteSaver, closes the connection, then opens the file again with a new agent:

pythonopen the file again and continue the threadFull log
    with SqliteSaver.from_conn_string(path) as saver:
        agent = create_agent(llm("after-restart"), tools=[add], checkpointer=saver)
        out = agent.invoke(ask("Remind me what my first question was."), thread("sqlite-thread"))

The third turn got all six earlier messages, and the model answered Your first question was, "What is 2 + 3?". The file has two tables, checkpoints and writes:

outputthe two tables after three turnsFull log
checkpoints: 11 rows, columns ['thread_id', 'checkpoint_ns', 'checkpoint_id', 'parent_checkpoint_id', 'type', 'checkpoint', 'metadata']

writes: 13 rows, columns ['thread_id', 'checkpoint_ns', 'checkpoint_id', 'task_id', 'task_path', 'idx', 'channel', 'type', 'value']

Pending write: a value that a task wrote during a step, saved in the writes table under the checkpoint that the step started from. On a resume, LangGraph applies the pending writes of the last checkpoint and does not run those tasks again.

The loop saves each pending write in the background, as the task finishes, and it does not wait for that call. So a pending write can reach the saver after the checkpoint of its own step. A trace in section 2.3 shows a model write saved after that checkpoint, on SqliteSaver with durability="sync". That order is harmless, because the checkpoint already holds the value. The window that matters comes earlier in a step, and section 5.3 measures it.

Each turn starts with a checkpoint whose source is input, and the step count goes on across turns. Figure 5.5 draws the 11 rows.

Fig. 5.5three turns of one thread in the SQLite filetimeline
Three turns of one thread in the SQLite file 11 rows of the checkpoints table of SqliteSaver for the thread sqlite-thread, on one step axis from -1 to 9. Turn 1, "What is 2 + 3?", has an input checkpoint at step -1 and loop checkpoints at steps 0, 1, 2, 3, and leaves 4 messages in the state. Turn 2, "What did I ask you?", has an input checkpoint at step 4 and loop checkpoints at steps 5, 6, and leaves 6 messages in the state. Turn 3, "Remind me what my first question was.", has an input checkpoint at step 7 and loop checkpoints at steps 8, 9, and leaves 8 messages in the state. Between turn 2 and turn 3 the connection was closed and a new process opened the same file. The file holds 11 checkpoint rows and 13 rows of pending writes. THREAD SQLITE-THREAD, ONE ROW PER CHECKPOINT turn 1 What is 2 + 3? input loop loop loop loop 4 messages in the state after turn 2 What did I ask you? input loop loop 6 messages in the state after turn 3 Remind me what my first question was. input loop loop 8 messages in the state after -1 0 1 2 3 4 5 6 7 8 9 metadata.step connection closed, a new process opens the same file checkpoints.db checkpoints 11 writes 13 input the new message is in loop saved after a step
Each turn adds an input checkpoint and then one loop checkpoint per step, and the step numbers keep counting across the turns and the restart. Read left to right along the step axis. Each mark is one row of the checkpoints table. Amber marks are input checkpoints, teal marks are loop checkpoints.

Every row has the type msgpack. That is the serializer of the checkpoint, and section 5.6 shows what it keeps.

Many threads on one Postgres saver

A server runs many threads at once on one checkpointer. The question is how many connections it needs.

We measured this on the x86 server guest, 32 vCPU and 48 GiB, with AsyncPostgresSaver on PostgreSQL 16.15 and Qwen3 4B on Ollama on CPU. One asyncio process ran 1, 4, 16, and 64 threads at once, two runs per cell, with one connection and with a pool of 20. Each thread ran two agent runs of two model calls and one tool call. All 680 runs answered right, with 0 errors. The model set the pace, at 0.42 to 0.44 model calls per second in every cell from 4 threads up. So 64 threads of two runs took 587 to 589 s, with one connection and with the pool. Raw runs

The saver stayed fast at the median. aput took 2.8 to 4.5 ms and aput_writes 3.7 to 5.8 ms in every cell. At 64 threads, the p99 of aput was 318 and 450 ms with one connection, and 254 and 273 ms with the pool. The client measured these times, so they include the wait of the event loop. Keep them as client p99 values, and do not read the gap between the two setups as an effect of the pool. The pool opened up to 21 connections and had at most 3 active at a sample.

Fig. 5.6runs per second and checkpoint write p99 on one AsyncPostgresSaver, by threadschart
Runs per second and checkpoint write p99 on one AsyncPostgresSaver, by threads Two dot charts against threads at once, 1, 4, 16, and 64, on a log scale, two runs per point, on the x86 server guest with Qwen3 4B on CPU. Left: runs per second. One connection gives 0.18 and 0.22 at 1 thread and 0.22 and 0.22 at 64. A pool of 20 gives 0.23 and 0.23 at 1 thread and 0.22 and 0.22 at 64. Right: the p99 of aput in ms, on a log scale. At 64 threads it is 450 and 318 ms with one connection and 273 and 254 ms with the pool. 0 0.1 0.2 0.3 1 4 16 64 threads at once runs per second 1 10 100 1k 1 4 16 64 threads at once aput p99, ms one connection pool of 20 Each dot is one run. All 680 of 680 runs answered right, with 0 errors. The p99 is timed in the client, so it holds the wait of the event loop.
One connection and a pool of 20 both give 0.22 runs per second at 64 threads with Qwen3 4B, and the aput p99 does not separate them. Each dot is one run, two runs per point. Each line joins the means of one connection setup. The left chart gives runs per second, and the right chart gives the p99 of aput in ms on a log scale. The x axis is the number of threads at once, on a log scale.

With a model on CPU, the model limits throughput long before the saver does. Size the pool to the threads that run at once. Our p99 values do not show that the pool lowers the tail of checkpoint writes. A second run on a thread that is still running is a different problem, double texting, and section 8.1 covers it on Agent Server.

LangChain (Python): langchain, langchain-core, langgraph, deepagents, langsmith 1.5.0 · c2f4036 · 2026-11-11 · Edition 2026.11