docs: add clarity to use of thread_id

Author: mdrxy

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 **must** 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., `uuid.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

@@ -845,6 +845,19 @@ def compile(
                 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 must 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.