docs: add clarity to use of thread_id (#6515)

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.
 

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.