docs: Add documentation for conversation storage implementation

openhands/storage/conversation/conversation_store.py.summary.md

@@ -0,0 +1,19 @@
+# ConversationStore (conversation_store.py)
+
+This file defines an abstract base class `ConversationStore` that serves as an interface for storing and managing conversation metadata. 
+
+## Key Features
+- Abstract class that defines the contract for conversation storage implementations
+- Supports operations for both single and multi-user environments
+- Provides methods for CRUD operations on conversation metadata
+
+## Core Methods
+- `save_metadata`: Store conversation metadata
+- `get_metadata`: Load conversation metadata by ID
+- `delete_metadata`: Remove conversation metadata
+- `exists`: Check if a conversation exists
+- `search`: Search conversations with pagination support
+- `get_instance`: Factory method to create store instances
+
+## Usage
+This abstract class should be implemented by concrete storage classes that provide specific storage mechanisms (e.g., file-based, database-based).

openhands/storage/conversation/file_conversation_store.py.summary.md

@@ -0,0 +1,27 @@
+# FileConversationStore (file_conversation_store.py)
+
+This file implements a file-based storage system for conversation metadata, implementing the `ConversationStore` abstract class.
+
+## Key Features
+- File-based implementation of the ConversationStore interface
+- Uses JSON for metadata serialization
+- Supports pagination in search operations
+- Handles backward compatibility for GitHub user IDs (converts int to str)
+
+## Implementation Details
+- Uses a FileStore backend for actual file operations
+- Stores conversations in a directory structure defined by CONVERSATION_BASE_DIR
+- Implements all required CRUD operations from the base class
+- Includes sorting functionality based on conversation creation time
+
+## Notable Methods
+- `save_metadata`: Saves conversation metadata as JSON files
+- `get_metadata`: Reads and deserializes JSON metadata with type validation
+- `delete_metadata`: Removes conversation metadata files
+- `search`: Implements paginated search with sorting by creation date
+- `get_instance`: Factory method that creates FileConversationStore instances
+
+## Error Handling
+- Handles FileNotFoundError for non-existent conversations
+- Includes logging for errors during metadata loading
+- Validates metadata using Pydantic type adapters

openhands/storage/conversation/summary.md

@@ -0,0 +1,28 @@
+# Conversation Storage Directory
+
+This directory contains the implementation of conversation metadata storage for the OpenHands system.
+
+## Files Overview
+
+### conversation_store.py
+Defines the abstract interface for conversation storage operations through the `ConversationStore` class. This serves as the contract that all conversation storage implementations must follow.
+
+### file_conversation_store.py
+Provides a concrete file-based implementation of the `ConversationStore` interface, storing conversation metadata as JSON files in a structured directory hierarchy.
+
+## Architecture
+- Uses an abstract base class pattern to allow for different storage implementations
+- Currently implements a file-based storage system
+- Supports metadata operations (CRUD) with pagination
+- Designed to work in both single-user and multi-user environments
+
+## Key Features
+- Abstract interface for storage operations
+- File-based implementation with JSON serialization
+- Pagination support for conversation listing
+- Sorting by conversation creation time
+- Error handling and logging
+- Type validation using Pydantic
+
+## Usage
+The storage system is used to persist conversation metadata, allowing conversations to be saved, retrieved, and searched. The file-based implementation is suitable for development and small-scale deployments, while the abstract interface allows for other implementations (e.g., database-based) to be added as needed.