Add SDK persistence directory structure documentation and move to top-level

docs.json

@@ -183,6 +183,7 @@
               "sdk/guides/custom-tools",
               "sdk/guides/mcp",
               "sdk/guides/skill",
+              "sdk/guides/convo-persistence",
               "sdk/guides/context-condenser",
               "sdk/guides/agent-delegation",
               "sdk/guides/security",
@@ -209,7 +210,6 @@
               {
                 "group": "Conversation Features",
                 "pages": [
-                  "sdk/guides/convo-persistence",
                   "sdk/guides/convo-pause-and-resume",
                   "sdk/guides/convo-send-message-while-running",
                   "sdk/guides/convo-async"

openapi/agent-sdk.json

@@ -2084,7 +2084,7 @@
           "llm_response_id": {
             "type": "string",
             "title": "Llm Response Id",
-            "description": "Groups related actions from same LLM response. This helps in tracking and managing results of parallel function calling from the same LLM response."
+            "description": "Completion or Response ID of the LLM response that generated this eventE.g., Can be used to group related actions from same LLM response. This helps in tracking and managing results of parallel function calling from the same LLM response."
           },
           "security_risk": {
             "$ref": "#/components/schemas/SecurityRisk",
@@ -3059,10 +3059,18 @@
             ],
             "title": "Summary Offset",
             "description": "An optional offset to the start of the resulting view indicating where the summary should be inserted."
+          },
+          "llm_response_id": {
+            "type": "string",
+            "title": "Llm Response Id",
+            "description": "Completion or Response ID of the LLM response that generated this event"
           }
         },
         "additionalProperties": false,
         "type": "object",
+        "required": [
+          "llm_response_id"
+        ],
         "title": "Condensation",
         "description": "This action indicates a condensation of the conversation history is happening."
       },
@@ -4801,6 +4809,18 @@
             "$ref": "#/components/schemas/Message",
             "description": "The exact LLM message for this message event"
           },
+          "llm_response_id": {
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "title": "Llm Response Id",
+            "description": "Completion or Response ID of the LLM response that generated this eventIf the source != 'agent', this field is None"
+          },
           "activated_skills": {
             "items": {
               "type": "string"

sdk/guides/convo-persistence.mdx

@@ -180,6 +180,31 @@ The conversation state includes comprehensive information that allows seamless r
 
 For the complete implementation details, see the [ConversationState class](https://github.com/OpenHands/software-agent-sdk/blob/main/openhands-sdk/openhands/sdk/conversation/state.py) in the source code.
 
+### Persistence Directory Structure
+
+When you set a `persistence_dir`, your conversation will be persisted to a directory structure where each conversation has its own subdirectory. By default, the persistence directory is `workspace/conversations/` (unless you specify a custom path).
+
+**Directory structure:**
+```
+workspace/conversations/
+├── <conversation-id-1>/
+│   ├── base_state.json       # Base conversation state
+│   └── events/               # Event files directory
+│       ├── event-00000-<event-id>.json
+│       ├── event-00001-<event-id>.json
+│       └── ...
+├── <conversation-id-2>/
+│   ├── base_state.json
+│   └── events/
+│       └── ...
+```
+
+Each conversation directory contains:
+- **`base_state.json`**: The core conversation state including agent configuration, execution status, statistics, and metadata
+- **`events/`**: A subdirectory containing individual event files, each named with a sequential index and event ID (e.g., `event-00000-abc123.json`)
+
+The collection of event files in the `events/` directory represents the same trajectory data you would find in the `trajectory.json` file from OpenHands V0, but split into individual files for better performance and granular access.
+
 ## Next Steps
 
 - **[Pause and Resume](/sdk/guides/convo-pause-and-resume)** - Control execution flow