From 3ff634037906ca2af618e7b9d8f394b6d1cbe794 Mon Sep 17 00:00:00 2001
From: Mason Daugherty <mason@langchain.dev>
Date: Mon, 26 Jan 2026 12:09:01 -0800
Subject: [PATCH] docs: add clarity to use of `thread_id` (#6515)

---
 .../langgraph/checkpoint/base/__init__.py     | 19 +++++++++++++++++++
 libs/langgraph/langgraph/graph/state.py       | 13 +++++++++++++
 2 files changed, 32 insertions(+)

diff --git a/libs/checkpoint/langgraph/checkpoint/base/__init__.py b/libs/checkpoint/langgraph/checkpoint/base/__init__.py
index 69901ca5b..f0e05c014 100644
--- a/libs/checkpoint/langgraph/checkpoint/base/__init__.py
+++ b/libs/checkpoint/langgraph/checkpoint/base/__init__.py
@@ -119,6 +119,25 @@ class BaseCheckpointSaver(Generic[V]):
     Checkpointers allow LangGraph agents to persist their state
     within and across multiple interactions.
 
+    When a checkpointer is configured, you should pass a `thread_id` in the config when
+    invoking the graph:
+
+    ```python
+    config = {"configurable": {"thread_id": "my-thread"}}
+    graph.invoke(inputs, config)
+    ```
+
+    The `thread_id` is the primary key used to store and retrieve checkpoints. Without
+    it, the checkpointer cannot save state, resume from interrupts, or enable
+    time-travel debugging.
+
+    How you choose ``thread_id`` depends on your use case:
+
+    - **Single-shot workflows**: Use a unique ID (e.g., uuid4) for each run when
+        executions are independent.
+    - **Conversational memory**: Reuse the same `thread_id` across invocations
+        to accumulate state (e.g., chat history) within a conversation.
+
     Attributes:
         serde (SerializerProtocol): Serializer for encoding/decoding checkpoints.
 
diff --git a/libs/langgraph/langgraph/graph/state.py b/libs/langgraph/langgraph/graph/state.py
index 608c492b0..4d0c90457 100644
--- a/libs/langgraph/langgraph/graph/state.py
+++ b/libs/langgraph/langgraph/graph/state.py
@@ -1057,6 +1057,19 @@ class StateGraph(Generic[StateT, ContextT, InputT, OutputT]):
                 If `None`, it may inherit the parent graph's checkpointer when used as a subgraph.
 
                 If `False`, it will not use or inherit any checkpointer.
+
+                **Important**: When a checkpointer is enabled, you should pass a `thread_id`
+                in the config when invoking the graph:
+
+                ```python
+                config = {"configurable": {"thread_id": "my-thread"}}
+                graph.invoke(inputs, config)
+                ```
+
+                The `thread_id` is the key used to store and retrieve checkpoints. Use a
+                unique ID for independent runs, or reuse the same ID to accumulate state
+                across invocations (e.g., for conversation memory).
+
             interrupt_before: An optional list of node names to interrupt before.
             interrupt_after: An optional list of node names to interrupt after.
             debug: A flag indicating whether to enable debug mode.