Add SDK persistence directory structure documentation and move to top-level #68
Conversation
…-level - Add information about persistence directory containing JSON files similar to trajectory.json from V0 - Move Persistence guide from Conversation Features to top-level in SDK Guides - Include directory structure example showing how conversations are stored
Synced from agent-sdk ref: main
…versation - Clarify structure is .conversations/<conversation-id>/ with each conversation in its own subdirectory - Update directory tree to show state.json files within conversation subdirectories
sdk/guides/convo-persistence.mdx
Outdated
| └── ... | ||
| ``` | ||
|
|
||
| Each `state.json` file contains the serialized conversation state with all events, messages, and metadata - similar to how `trajectory.json` worked in V0. This makes it easy to inspect, debug, or migrate conversation data between systems. |
There was a problem hiding this comment.
@OpenHands this is wrong. Please review https://github.com/OpenHands/software-agent-sdk/blob/main/openhands-sdk/openhands/sdk/conversation/state.py for more accurate folder structure
There was a problem hiding this comment.
I'm on it! xingyaoww can track my progress at all-hands.dev
There was a problem hiding this comment.
Summary
I've successfully corrected the persistence directory structure documentation in PR #68 based on the actual SDK source code.
Changes Made:
Fixed the "Persistence Directory Structure" section in sdk/guides/convo-persistence.mdx to accurately reflect the SDK implementation:
-
Corrected default path: Changed from
.conversations/toworkspace/conversations/(the actual default fromstate.py) -
Fixed filename: Changed
state.jsontobase_state.json(the actual constant frompersistence_const.py) -
Added missing structure: Documented the
events/subdirectory that contains individual event files -
Added event file pattern: Showed the naming convention
event-00000-<event-id>.jsonwith sequential indexing -
Improved clarity: Explained that
base_state.jsonholds core conversation state while individual events are stored separately for granular access
The documentation now accurately matches the implementation in the SDK's state.py and persistence_const.py files.
Commit: a9fedb5 - "Fix persistence directory structure documentation"
Status: Pushed to branch sdk-persistence-docs-update ✅
- Update directory structure to show accurate file organization from SDK source
- Change default path from .conversations/ to workspace/conversations/
- Show base_state.json (not state.json) as the main state file
- Document events/ subdirectory with individual event files
- Add event file naming pattern (event-{idx:05d}-{event-id}.json)
- Clarify that events are stored separately for granular access
Co-authored-by: openhands <openhands@all-hands.dev>
- Explain that events/ directory contains the same data as trajectory.json from V0 - Highlight the benefit of splitting into individual files (performance, granular access) - Mention memory efficiency advantage Co-authored-by: openhands <openhands@all-hands.dev>
neubig
left a comment
neubig
left a comment
There was a problem hiding this comment.
LGTM, but is there a way we can use these with the trajectory visualizer?
|
@neubig not really, we need to rewrite the visualizer for new event schema :( |
Co-authored-by: openhands <openhands@all-hands.dev>
Summary
This PR updates the SDK persistence documentation to clarify that the persistence directory contains JSON files similar to
trajectory.jsonfrom OpenHands V0, and moves the Persistence guide to top-level in the navigation.Changes Made
Added Persistence Directory Structure section in
sdk/guides/convo-persistence.mdx:persistence_dircreates JSON files that mirrortrajectory.jsonfrom V0Moved Persistence to top-level in
docs.json:sdk/guides/convo-persistencefrom "Conversation Features" group to top-level under "Guides"Context
Users were asking about how to access trajectory data similar to the
trajectory.jsonfile available in the OpenHands Web UI. This documentation update clarifies that the SDK provides the same capability through thepersistence_dirparameter.Related to the discussion about making persistence more discoverable and documenting the JSON file format compatibility with V0.
@xingyaoww can click here to continue refining the PR