From 5799daec2152b12d230ed0ecb0517ce2daacc2a7 Mon Sep 17 00:00:00 2001
From: openhands <openhands@all-hands.dev>
Date: Tue, 25 Feb 2025 22:43:05 +0000
Subject: [PATCH 1/3] docs: Add documentation for conversation storage
 implementation

---
 .../conversation_store.py.summary.md          | 19 +++++++++++++
 .../file_conversation_store.py.summary.md     | 27 ++++++++++++++++++
 openhands/storage/conversation/summary.md     | 28 +++++++++++++++++++
 3 files changed, 74 insertions(+)
 create mode 100644 openhands/storage/conversation/conversation_store.py.summary.md
 create mode 100644 openhands/storage/conversation/file_conversation_store.py.summary.md
 create mode 100644 openhands/storage/conversation/summary.md

diff --git a/openhands/storage/conversation/conversation_store.py.summary.md b/openhands/storage/conversation/conversation_store.py.summary.md
new file mode 100644
index 000000000000..5cc9d99d1af7
--- /dev/null
+++ b/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).
\ No newline at end of file
diff --git a/openhands/storage/conversation/file_conversation_store.py.summary.md b/openhands/storage/conversation/file_conversation_store.py.summary.md
new file mode 100644
index 000000000000..1d2ad266ee22
--- /dev/null
+++ b/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
\ No newline at end of file
diff --git a/openhands/storage/conversation/summary.md b/openhands/storage/conversation/summary.md
new file mode 100644
index 000000000000..1fefc946acbb
--- /dev/null
+++ b/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.
\ No newline at end of file

From 824e587cd8fe975280a9d11d4801dac2e1bd87a1 Mon Sep 17 00:00:00 2001
From: openhands <openhands@all-hands.dev>
Date: Wed, 26 Feb 2025 02:49:25 +0000
Subject: [PATCH 2/3] Add comprehensive documentation for storage modules

---
 openhands/storage/files.py.summary.md        |  88 +++++++++++
 openhands/storage/google_cloud.py.summary.md | 125 ++++++++++++++++
 openhands/storage/local.py.summary.md        | 124 ++++++++++++++++
 openhands/storage/locations.py.summary.md    | 134 +++++++++++++++++
 openhands/storage/memory.py.summary.md       | 146 +++++++++++++++++++
 openhands/storage/s3.py.summary.md           | 140 ++++++++++++++++++
 6 files changed, 757 insertions(+)
 create mode 100644 openhands/storage/files.py.summary.md
 create mode 100644 openhands/storage/google_cloud.py.summary.md
 create mode 100644 openhands/storage/local.py.summary.md
 create mode 100644 openhands/storage/locations.py.summary.md
 create mode 100644 openhands/storage/memory.py.summary.md
 create mode 100644 openhands/storage/s3.py.summary.md

diff --git a/openhands/storage/files.py.summary.md b/openhands/storage/files.py.summary.md
new file mode 100644
index 000000000000..f6f041797dd7
--- /dev/null
+++ b/openhands/storage/files.py.summary.md
@@ -0,0 +1,88 @@
+# FileStore (files.py)
+
+This module implements the core file system operations for the OpenHands framework, providing a robust and safe interface for file manipulation.
+
+## Key Features
+
+### File Operations
+- Safe file reading and writing
+- Atomic operations
+- Directory management
+- File locking mechanisms
+- Path normalization
+
+### Safety Mechanisms
+- Thread-safe operations
+- Error handling
+- Path validation
+- Permission checks
+- Resource cleanup
+
+### Storage Management
+- File organization
+- Temporary file handling
+- Directory structure
+- Path resolution
+- Extension handling
+
+## Implementation Details
+
+### Core Operations
+1. File Reading
+   - Binary and text modes
+   - Buffered operations
+   - Encoding handling
+   - Stream support
+
+2. File Writing
+   - Atomic writes
+   - Backup creation
+   - Temporary files
+   - Lock management
+
+3. Directory Operations
+   - Creation/deletion
+   - Recursive operations
+   - Permission management
+   - Path traversal
+
+### Integration Points
+- Used by ConversationStore
+- Supports SettingsStore
+- Provides backup functionality
+- Handles resource files
+
+## Usage Patterns
+
+### Basic Operations
+```python
+store = FileStore()
+store.write_file("path/to/file", content)
+content = store.read_file("path/to/file")
+```
+
+### Directory Management
+```python
+store.ensure_directory("path/to/dir")
+store.remove_directory("path/to/dir")
+```
+
+### Safe Operations
+```python
+with store.atomic_write("path/to/file") as f:
+    f.write(content)
+```
+
+## Error Handling
+- File not found
+- Permission denied
+- Lock timeouts
+- Resource busy
+- Path validation
+
+## Security Considerations
+- Path sanitization
+- Permission checks
+- Resource limits
+- Lock management
+- Cleanup procedures
\ No newline at end of file
diff --git a/openhands/storage/google_cloud.py.summary.md b/openhands/storage/google_cloud.py.summary.md
new file mode 100644
index 000000000000..61d3ae8b4cac
--- /dev/null
+++ b/openhands/storage/google_cloud.py.summary.md
@@ -0,0 +1,125 @@
+# Google Cloud Storage (google_cloud.py)
+
+This module implements Google Cloud Storage integration for the OpenHands framework, providing cloud-based file storage capabilities.
+
+## Key Features
+
+### Cloud Operations
+- Google Cloud Storage API integration
+- Bucket management
+- Object lifecycle
+- Access control
+- Metadata handling
+
+### Storage Features
+- File upload/download
+- Stream operations
+- Blob management
+- Cache control
+- Content types
+
+### Configuration
+- Authentication
+- Project settings
+- Regional options
+- Storage classes
+- Retention policies
+
+## Implementation Details
+
+### Core Operations
+1. Upload Operations
+   - Single file uploads
+   - Multipart uploads
+   - Resumable transfers
+   - Progress tracking
+
+2. Download Operations
+   - File downloads
+   - Streaming downloads
+   - Partial downloads
+   - Range requests
+
+3. Management Operations
+   - Object listing
+   - Metadata updates
+   - Access control
+   - Object deletion
+
+### Integration Points
+- Works with FileStore interface
+- Supports ConversationStore
+- Backup functionality
+- Resource management
+
+## Usage Patterns
+
+### Basic Operations
+```python
+store = GoogleCloudStorage(bucket_name="my-bucket")
+store.upload_file("local/path", "cloud/path")
+store.download_file("cloud/path", "local/path")
+```
+
+### Advanced Features
+```python
+# With metadata
+store.upload_with_metadata("path", metadata={
+    "content-type": "application/json",
+    "cache-control": "public, max-age=3600"
+})
+
+# Stream operations
+with store.stream_upload("path") as stream:
+    stream.write(data)
+```
+
+## Error Handling
+- Network errors
+- Authentication failures
+- Quota exceeded
+- Invalid operations
+- Timeout handling
+
+## Security Features
+- IAM integration
+- Encryption at rest
+- Access control lists
+- Signed URLs
+- Service accounts
+
+## Performance Considerations
+- Caching strategies
+- Batch operations
+- Parallel transfers
+- Retry mechanisms
+- Connection pooling
+
+## Configuration Options
+```python
+config = {
+    "project_id": "my-project",
+    "bucket": "my-bucket",
+    "location": "us-central1",
+    "storage_class": "STANDARD"
+}
+```
+
+## Best Practices
+1. Error Handling
+   - Implement retries
+   - Handle timeouts
+   - Log operations
+   - Monitor quotas
+
+2. Performance
+   - Use appropriate storage classes
+   - Implement caching
+   - Optimize transfers
+   - Batch operations
+
+3. Security
+   - Minimal permissions
+   - Secure credentials
+   - Monitor access
+   - Regular audits
\ No newline at end of file
diff --git a/openhands/storage/local.py.summary.md b/openhands/storage/local.py.summary.md
new file mode 100644
index 000000000000..688ef0e1cfed
--- /dev/null
+++ b/openhands/storage/local.py.summary.md
@@ -0,0 +1,124 @@
+# Local Storage (local.py)
+
+This module implements local file system storage functionality for the OpenHands framework, providing a simple and efficient way to store files on the local machine.
+
+## Key Features
+
+### Local Storage Operations
+- Direct file system access
+- Path management
+- Directory operations
+- File permissions
+- Symbolic links
+
+### Storage Management
+- Space monitoring
+- Cleanup operations
+- Temporary storage
+- Cache management
+- File organization
+
+### Performance Features
+- Direct I/O operations
+- Memory mapping
+- Buffer management
+- File locking
+- Atomic operations
+
+## Implementation Details
+
+### Core Operations
+1. File Operations
+   - Read/Write
+   - Copy/Move
+   - Delete/Rename
+   - Permissions
+   - Attributes
+
+2. Directory Operations
+   - Creation
+   - Deletion
+   - Listing
+   - Traversal
+   - Permissions
+
+3. Path Management
+   - Resolution
+   - Normalization
+   - Validation
+   - Security checks
+   - Relative paths
+
+### Integration Points
+- Base for FileStore
+- Supports ConversationStore
+- Temporary storage
+- Cache backend
+
+## Usage Patterns
+
+### Basic Operations
+```python
+store = LocalStorage(root_dir="/path/to/storage")
+store.write_file("file.txt", content)
+content = store.read_file("file.txt")
+```
+
+### Directory Management
+```python
+store.create_directory("new_dir")
+files = store.list_directory("path")
+store.remove_directory("old_dir")
+```
+
+## Error Handling
+- Permission errors
+- Disk space issues
+- File locks
+- Path validation
+- I/O errors
+
+## Security Features
+- Path sanitization
+- Permission checks
+- Symbolic link handling
+- Resource limits
+- Access control
+
+## Performance Optimization
+1. Caching
+   - File handles
+   - Directory listings
+   - Metadata
+   - Path resolution
+
+2. I/O Operations
+   - Buffered I/O
+   - Direct I/O
+   - Memory mapping
+   - Asynchronous I/O
+
+3. Resource Management
+   - File descriptors
+   - Memory usage
+   - Disk space
+   - Open handles
+
+## Best Practices
+1. File Operations
+   - Use atomic operations
+   - Implement proper locking
+   - Handle cleanup
+   - Validate paths
+
+2. Error Management
+   - Handle disk full
+   - Check permissions
+   - Validate input
+   - Log operations
+
+3. Resource Usage
+   - Monitor space
+   - Limit file sizes
+   - Control concurrency
+   - Manage handles
\ No newline at end of file
diff --git a/openhands/storage/locations.py.summary.md b/openhands/storage/locations.py.summary.md
new file mode 100644
index 000000000000..e2109cbab657
--- /dev/null
+++ b/openhands/storage/locations.py.summary.md
@@ -0,0 +1,134 @@
+# Storage Locations (locations.py)
+
+This module manages storage location definitions and resolution for the OpenHands framework, providing a unified way to handle different storage locations and paths.
+
+## Key Features
+
+### Location Management
+- Storage location definitions
+- Path resolution
+- Location types
+- Default locations
+- Location validation
+
+### Path Handling
+- Path normalization
+- Location prefixes
+- Path translation
+- URI handling
+- Protocol support
+
+### Configuration
+- Location settings
+- Default paths
+- Environment integration
+- Override management
+- Validation rules
+
+## Implementation Details
+
+### Location Types
+1. Local Storage
+   - File system paths
+   - Relative paths
+   - Absolute paths
+   - Home directory
+
+2. Remote Storage
+   - Cloud storage
+   - Network paths
+   - URI schemes
+   - Protocol handlers
+
+3. Special Locations
+   - Temporary storage
+   - Cache directories
+   - Configuration paths
+   - Data directories
+
+### Core Operations
+1. Location Resolution
+   ```python
+   # Convert location identifier to actual path
+   actual_path = resolve_location("data://conversations")
+   ```
+
+2. Path Translation
+   ```python
+   # Translate between different location types
+   cloud_path = translate_path(local_path, "gcs://bucket")
+   ```
+
+3. Location Validation
+   ```python
+   # Validate location configuration
+   is_valid = validate_location_config({
+       "type": "local",
+       "path": "/data/storage"
+   })
+   ```
+
+## Usage Patterns
+
+### Basic Usage
+```python
+# Get path for a location
+path = get_location_path("conversations")
+
+# Check if location exists
+exists = location_exists("cache")
+
+# Create new location
+create_location("backups", "/path/to/backups")
+```
+
+### Advanced Features
+```python
+# Location with options
+configure_location("temp", {
+    "path": "/tmp/openhands",
+    "cleanup": True,
+    "max_size": "1GB"
+})
+
+# Location inheritance
+create_sublocation("cache", "temp/cache")
+```
+
+## Integration Points
+- Used by storage backends
+- Supports file operations
+- Configuration system
+- Path resolution
+
+## Error Handling
+1. Location Errors
+   - Invalid locations
+   - Missing paths
+   - Permission issues
+   - Configuration errors
+
+2. Path Errors
+   - Invalid paths
+   - Resolution failures
+   - Access denied
+   - Protocol errors
+
+## Best Practices
+1. Location Management
+   - Use consistent naming
+   - Validate configurations
+   - Handle missing locations
+   - Document locations
+
+2. Path Handling
+   - Normalize paths
+   - Validate access
+   - Handle errors
+   - Clean up resources
+
+3. Configuration
+   - Use environment variables
+   - Provide defaults
+   - Document options
+   - Validate settings
\ No newline at end of file
diff --git a/openhands/storage/memory.py.summary.md b/openhands/storage/memory.py.summary.md
new file mode 100644
index 000000000000..5cae829e18a8
--- /dev/null
+++ b/openhands/storage/memory.py.summary.md
@@ -0,0 +1,146 @@
+# Memory Storage (memory.py)
+
+This module implements in-memory storage functionality for the OpenHands framework, providing fast access to temporary data and caching capabilities.
+
+## Key Features
+
+### Memory Management
+- In-memory data storage
+- Cache implementation
+- Memory limits
+- Garbage collection
+- Resource tracking
+
+### Storage Operations
+- Key-value storage
+- Object caching
+- Temporary storage
+- Data expiration
+- Atomic operations
+
+### Performance Features
+- Fast access times
+- Thread safety
+- Memory efficiency
+- Resource limits
+- Eviction policies
+
+## Implementation Details
+
+### Core Operations
+1. Data Storage
+   - Set/Get operations
+   - Delete operations
+   - Clear operations
+   - Existence checks
+   - Size tracking
+
+2. Cache Management
+   - TTL support
+   - LRU eviction
+   - Size limits
+   - Statistics
+   - Monitoring
+
+3. Resource Control
+   - Memory limits
+   - Item counts
+   - Usage tracking
+   - Cleanup policies
+   - Resource alerts
+
+### Integration Points
+- Temporary storage backend
+- Cache layer
+- Session storage
+- Quick lookups
+- Data buffering
+
+## Usage Patterns
+
+### Basic Operations
+```python
+store = MemoryStorage()
+store.set("key", "value")
+value = store.get("key")
+store.delete("key")
+```
+
+### Cache Operations
+```python
+cache = MemoryCache(max_size=1000)
+cache.set("key", data, ttl=3600)
+data = cache.get("key")
+```
+
+### Advanced Features
+```python
+# With automatic expiration
+store.set_with_ttl("key", value, ttl=60)
+
+# Atomic operations
+store.increment("counter")
+store.append("list", item)
+```
+
+## Error Handling
+- Memory exhaustion
+- Key conflicts
+- Type errors
+- Limit exceeded
+- Timeout errors
+
+## Performance Considerations
+1. Memory Usage
+   - Size monitoring
+   - Eviction policies
+   - Garbage collection
+   - Resource limits
+
+2. Concurrency
+   - Thread safety
+   - Lock management
+   - Atomic operations
+   - Race conditions
+
+3. Efficiency
+   - Fast lookups
+   - Minimal copying
+   - Resource pooling
+   - Cache hits
+
+## Best Practices
+1. Resource Management
+   - Set size limits
+   - Monitor usage
+   - Handle eviction
+   - Clean up regularly
+
+2. Error Handling
+   - Check memory
+   - Validate input
+   - Handle timeouts
+   - Log operations
+
+3. Performance
+   - Use appropriate structures
+   - Implement caching
+   - Monitor metrics
+   - Optimize access
+
+## Configuration Options
+```python
+config = {
+    "max_size": "1GB",
+    "max_items": 10000,
+    "ttl_default": 3600,
+    "eviction_policy": "lru"
+}
+```
+
+## Monitoring
+- Memory usage
+- Item counts
+- Hit rates
+- Eviction rates
+- Error rates
\ No newline at end of file
diff --git a/openhands/storage/s3.py.summary.md b/openhands/storage/s3.py.summary.md
new file mode 100644
index 000000000000..739283ba2aa6
--- /dev/null
+++ b/openhands/storage/s3.py.summary.md
@@ -0,0 +1,140 @@
+# S3 Storage (s3.py)
+
+This module implements Amazon S3 storage integration for the OpenHands framework, providing cloud-based object storage capabilities.
+
+## Key Features
+
+### S3 Operations
+- Bucket management
+- Object operations
+- Multipart uploads
+- Versioning
+- Access control
+
+### Storage Features
+- File upload/download
+- Stream handling
+- Metadata management
+- Lifecycle policies
+- Storage classes
+
+### Configuration
+- AWS credentials
+- Region settings
+- Bucket policies
+- Encryption
+- Access points
+
+## Implementation Details
+
+### Core Operations
+1. Upload Operations
+   - Single uploads
+   - Multipart uploads
+   - Stream uploads
+   - Progress tracking
+   - Retry logic
+
+2. Download Operations
+   - File downloads
+   - Stream downloads
+   - Range requests
+   - Conditional gets
+   - Transfer acceleration
+
+3. Management Operations
+   - Object listing
+   - Metadata handling
+   - Versioning control
+   - Lifecycle rules
+   - Tag management
+
+### Integration Points
+- Works with FileStore
+- Supports ConversationStore
+- Backup storage
+- Resource management
+- CDN integration
+
+## Usage Patterns
+
+### Basic Operations
+```python
+store = S3Storage(bucket="my-bucket")
+store.upload_file("local/path", "s3/path")
+store.download_file("s3/path", "local/path")
+```
+
+### Advanced Features
+```python
+# With metadata
+store.upload_with_metadata("path", {
+    "ContentType": "application/json",
+    "CacheControl": "max-age=3600"
+})
+
+# Multipart upload
+with store.multipart_upload("large-file") as upload:
+    upload.upload_part(data)
+```
+
+## Error Handling
+- Network errors
+- Authentication failures
+- Quota limits
+- Access denied
+- Timeout handling
+
+## Security Features
+- IAM integration
+- Server-side encryption
+- Client-side encryption
+- Bucket policies
+- Access points
+
+## Performance Optimization
+1. Transfer
+   - Multipart uploads
+   - Transfer acceleration
+   - Parallel operations
+   - Connection pooling
+   - Request batching
+
+2. Caching
+   - Object caching
+   - Metadata caching
+   - DNS resolution
+   - Connection reuse
+   - Response caching
+
+## Configuration Options
+```python
+config = {
+    "bucket": "my-bucket",
+    "region": "us-east-1",
+    "storage_class": "STANDARD",
+    "encryption": "AES256"
+}
+```
+
+## Best Practices
+1. Error Handling
+   - Implement retries
+   - Handle timeouts
+   - Log operations
+   - Monitor quotas
+   - Validate inputs
+
+2. Performance
+   - Use appropriate storage classes
+   - Implement caching
+   - Optimize transfers
+   - Batch operations
+   - Monitor metrics
+
+3. Security
+   - Minimal permissions
+   - Encrypt data
+   - Secure credentials
+   - Regular audits
+   - Access logging
\ No newline at end of file

From a6fa3f21a4c7ea320427f5f699090fb686519f4d Mon Sep 17 00:00:00 2001
From: openhands <openhands@all-hands.dev>
Date: Wed, 26 Feb 2025 02:49:50 +0000
Subject: [PATCH 3/3] Add comprehensive documentation summaries for OpenHands
 modules

---
 openhands/agenthub/summary.md   | 51 +++++++++++++++++++
 openhands/controller/summary.md | 57 +++++++++++++++++++++
 openhands/core/summary.md       | 77 ++++++++++++++++++++++++++++
 openhands/events/summary.md     | 78 +++++++++++++++++++++++++++++
 openhands/llm/summary.md        | 79 +++++++++++++++++++++++++++++
 openhands/memory/summary.md     | 81 ++++++++++++++++++++++++++++++
 openhands/storage/summary.md    | 89 +++++++++++++++++++++++++++++++++
 7 files changed, 512 insertions(+)
 create mode 100644 openhands/agenthub/summary.md
 create mode 100644 openhands/controller/summary.md
 create mode 100644 openhands/core/summary.md
 create mode 100644 openhands/events/summary.md
 create mode 100644 openhands/llm/summary.md
 create mode 100644 openhands/memory/summary.md
 create mode 100644 openhands/storage/summary.md

diff --git a/openhands/agenthub/summary.md b/openhands/agenthub/summary.md
new file mode 100644
index 000000000000..0f118e27c88a
--- /dev/null
+++ b/openhands/agenthub/summary.md
@@ -0,0 +1,51 @@
+# Agent Hub Directory
+
+The `agenthub` directory contains various specialized agent implementations for different tasks and capabilities.
+
+## Agent Types
+
+### Browsing Agent (`browsing_agent/`)
+- Main agent for web browsing interactions
+- Includes response parsing and utility functions
+- Handles web navigation and content extraction
+
+### CodeAct Agent (`codeact_agent/`)
+- Specialized for code-related actions
+- Implements function calling capabilities
+- Handles code analysis and modifications
+
+### Delegator Agent (`delegator_agent/`)
+- Manages task delegation between agents
+- Coordinates complex multi-agent operations
+- Handles agent selection and task distribution
+
+### Visual Browsing Agent (`visualbrowsing_agent/`)
+- Enhanced browsing agent with visual capabilities
+- Handles visual element interaction
+- Supports screenshot analysis and visual navigation
+
+### Micro Agents (`micro/`)
+- Lightweight agent implementation
+- Registry for micro-agent management
+- Handles simple, focused tasks
+
+### Dummy Agent (`dummy_agent/`)
+- Test implementation for agent interface
+- Used for development and testing
+- Provides basic agent functionality examples
+
+## Key Features
+- Modular agent design allowing easy extension
+- Specialized agents for specific task types
+- Common utilities and shared functionality
+- Clear separation of concerns between agent types
+
+## Implementation Details
+Each agent type follows a consistent pattern:
+- Clear interface definition
+- Task-specific implementations
+- Utility functions for common operations
+- Error handling and logging
+
+## Usage
+Agents can be used individually or composed together for complex tasks. The delegator agent can coordinate between different agent types when needed.
\ No newline at end of file
diff --git a/openhands/controller/summary.md b/openhands/controller/summary.md
new file mode 100644
index 000000000000..af6edc451dfe
--- /dev/null
+++ b/openhands/controller/summary.md
@@ -0,0 +1,57 @@
+# Controller Directory
+
+The `controller` directory manages agent execution and task control, serving as the orchestration layer for the OpenHands framework.
+
+## Core Components
+
+### Agent Controller (`agent_controller.py`)
+- Main controller for agent execution
+- Manages agent lifecycle and state
+- Handles task progression and control flow
+
+### Action Parser (`action_parser.py`)
+- Parses and validates agent actions
+- Converts raw actions to structured formats
+- Handles action validation and normalization
+
+### State Management (`state/`)
+- `state.py`: Manages agent and task state
+- `task.py`: Task definition and management
+- Handles state transitions and persistence
+
+### Replay System (`replay.py`)
+- Implements action replay capabilities
+- Useful for debugging and testing
+- Supports step-by-step replay of agent actions
+
+### Stuck Detection (`stuck.py`)
+- Detects when agents are stuck or in loops
+- Implements recovery strategies
+- Monitors agent progress and performance
+
+## Key Features
+- Centralized control of agent execution
+- Robust state management system
+- Action validation and parsing
+- Replay capabilities for debugging
+- Stuck detection and recovery
+
+## Implementation Details
+The controller system:
+- Maintains agent state throughout execution
+- Validates and processes agent actions
+- Handles error conditions and recovery
+- Provides debugging and monitoring tools
+
+## Usage
+The controller is the central coordination point for agent operations:
+1. Initialize controller with agent configuration
+2. Submit tasks for execution
+3. Monitor and manage task progression
+4. Handle completion and error states
+
+## Integration Points
+- Works with the event system for action/observation flow
+- Integrates with runtime for execution environment
+- Connects with memory system for state persistence
+- Interfaces with security for action validation
\ No newline at end of file
diff --git a/openhands/core/summary.md b/openhands/core/summary.md
new file mode 100644
index 000000000000..6bf73f754e6b
--- /dev/null
+++ b/openhands/core/summary.md
@@ -0,0 +1,77 @@
+# Core Directory
+
+The `core` directory contains the fundamental components and infrastructure of the OpenHands framework.
+
+## Key Components
+
+### Configuration (`config/`)
+- `app_config.py`: Main application configuration
+- `agent_config.py`: Agent-specific settings
+- `llm_config.py`: Language model configuration
+- `sandbox_config.py`: Sandbox environment settings
+- `security_config.py`: Security policy configuration
+- `extended_config.py`: Extended configuration options
+- Configuration utilities and helpers
+
+### Schema (`schema/`)
+- `action.py`: Action data structures
+- `agent.py`: Agent interface definitions
+- `observation.py`: Observation data models
+- Type definitions and validation
+
+### Main Components
+- `main.py`: Application entry point
+- `loop.py`: Main event loop implementation
+- `cli.py`: Command-line interface
+- `setup.py`: Framework initialization
+
+### Messaging System
+- `message.py`: Message data structures
+- `message_utils.py`: Message handling utilities
+- Event and message routing
+
+### Utilities
+- `logger.py`: Logging infrastructure
+- `download.py`: Resource downloading
+- `exceptions.py`: Framework exceptions
+
+## Key Features
+- Centralized configuration management
+- Type-safe schema definitions
+- Robust logging system
+- Exception handling framework
+- Resource management
+
+## Implementation Details
+
+### Configuration System
+- Hierarchical configuration structure
+- Environment-aware settings
+- Validation and type checking
+- Extension points for custom config
+
+### Schema System
+- Strong type definitions
+- Validation rules
+- Serialization support
+- Extensible data models
+
+### Event Loop
+- Asynchronous operation support
+- Event handling and routing
+- Resource management
+- Error handling and recovery
+
+## Usage
+The core components provide the foundation for:
+1. Application configuration
+2. Type safety and validation
+3. Event handling and messaging
+4. Resource management
+5. Logging and monitoring
+
+## Integration Points
+- Used by all other framework components
+- Provides base classes and interfaces
+- Manages framework lifecycle
+- Handles cross-cutting concerns
\ No newline at end of file
diff --git a/openhands/events/summary.md b/openhands/events/summary.md
new file mode 100644
index 000000000000..81e99fddcc45
--- /dev/null
+++ b/openhands/events/summary.md
@@ -0,0 +1,78 @@
+# Events Directory
+
+The `events` directory implements the event system that handles actions, observations, and their serialization in the OpenHands framework.
+
+## Core Components
+
+### Action Events (`action/`)
+- `action.py`: Base action event definitions
+- `agent.py`: Agent-specific actions
+- `browse.py`: Web browsing actions
+- `commands.py`: Command execution actions
+- `files.py`: File operation actions
+- `message.py`: Message handling actions
+- `empty.py`: Empty action handling
+
+### Observation Events (`observation/`)
+- `observation.py`: Base observation types
+- `agent.py`: Agent observations
+- `browse.py`: Browser operation results
+- `commands.py`: Command execution results
+- `delegate.py`: Delegation results
+- `error.py`: Error observations
+- `files.py`: File operation results
+- `reject.py`: Action rejection events
+- `success.py`: Success event handling
+
+### Serialization (`serialization/`)
+- `action.py`: Action serialization
+- `event.py`: Event serialization base
+- `observation.py`: Observation serialization
+- `utils.py`: Serialization utilities
+
+### Event Management
+- `stream.py`: Event streaming
+- `tool.py`: Tool event handling
+- `utils.py`: Event utilities
+- `event.py`: Base event definitions
+
+## Key Features
+- Comprehensive event type system
+- Bidirectional event flow (actions/observations)
+- Serialization support for all events
+- Stream-based event processing
+- Error handling and recovery
+
+## Implementation Details
+
+### Event Types
+- Actions: Commands from agents
+- Observations: Results and feedback
+- Tools: Tool-specific events
+- System: Framework events
+
+### Event Flow
+1. Actions generated by agents
+2. Actions processed by handlers
+3. Observations generated from results
+4. Observations routed to agents
+
+### Serialization
+- JSON-based serialization
+- Type preservation
+- Validation on serialization/deserialization
+- Stream support
+
+## Usage
+The event system is used for:
+1. Agent-system communication
+2. Action processing and routing
+3. Result observation handling
+4. Tool integration
+5. System state management
+
+## Integration Points
+- Used by controller for action handling
+- Integrated with runtime for execution
+- Connected to memory for event storage
+- Used by agents for communication
\ No newline at end of file
diff --git a/openhands/llm/summary.md b/openhands/llm/summary.md
new file mode 100644
index 000000000000..3a1c6bc4469a
--- /dev/null
+++ b/openhands/llm/summary.md
@@ -0,0 +1,79 @@
+# LLM (Language Model) Directory
+
+The `llm` directory contains components for interacting with Large Language Models, providing abstractions and utilities for model integration.
+
+## Core Components
+
+### Base Implementations
+- `llm.py`: Base LLM interface and implementation
+- `async_llm.py`: Asynchronous LLM operations
+- `streaming_llm.py`: Streaming response handling
+- `bedrock.py`: AWS Bedrock integration
+
+### Function Calling
+- `fn_call_converter.py`: Function call parsing and conversion
+- Handles structured function calls from LLM responses
+- Converts between different function calling formats
+
+### Mixins
+- `debug_mixin.py`: Debugging capabilities
+- `retry_mixin.py`: Retry logic for failed calls
+- Enhances base LLM functionality
+
+### Metrics
+- `metrics.py`: Performance and usage metrics
+- Tracks token usage, latency, and costs
+- Provides monitoring capabilities
+
+## Key Features
+- Unified LLM interface
+- Async and streaming support
+- Function calling capabilities
+- Retry and error handling
+- Performance monitoring
+- Multiple model support
+
+## Implementation Details
+
+### LLM Interface
+- Common interface for all models
+- Support for different model providers
+- Configurable parameters
+- Response validation
+
+### Async Operations
+- Non-blocking API calls
+- Concurrent request handling
+- Stream processing
+- Resource management
+
+### Function Calling
+- Structured output parsing
+- Function definition handling
+- Type validation
+- Error recovery
+
+### Monitoring
+- Token counting
+- Cost tracking
+- Latency monitoring
+- Usage statistics
+
+## Usage
+The LLM components are used for:
+1. Model interaction
+2. Function calling
+3. Response streaming
+4. Error handling
+5. Performance monitoring
+
+## Integration Points
+- Used by agents for decision making
+- Integrated with memory system
+- Connected to security for validation
+- Used by controller for task processing
+
+## Supported Models
+- OpenAI GPT models
+- AWS Bedrock models
+- Extensible for other providers
\ No newline at end of file
diff --git a/openhands/memory/summary.md b/openhands/memory/summary.md
new file mode 100644
index 000000000000..3f17a5f2ee20
--- /dev/null
+++ b/openhands/memory/summary.md
@@ -0,0 +1,81 @@
+# Memory Directory
+
+The `memory` directory implements memory management and conversation history handling for the OpenHands framework.
+
+## Core Components
+
+### Condenser System (`condenser/`)
+Base implementation and interface:
+- `condenser.py`: Base condenser interface
+- `__init__.py`: Condenser registration and utilities
+
+#### Condenser Implementations (`condenser/impl/`)
+- `amortized_forgetting_condenser.py`: Gradual memory decay
+- `llm_attention_condenser.py`: Attention-based memory management
+- `llm_summarizing_condenser.py`: Summary-based memory compression
+- `no_op_condenser.py`: Pass-through implementation
+- `observation_masking_condenser.py`: Selective observation storage
+- `recent_events_condenser.py`: Recent history management
+
+### Long-term Memory
+- `long_term_memory.py`: Persistent memory storage
+- Handles long-term information retention
+- Manages memory retrieval and storage
+
+## Key Features
+- Multiple memory management strategies
+- Configurable memory retention
+- Memory compression techniques
+- Long-term storage support
+- Memory search and retrieval
+
+## Implementation Details
+
+### Memory Management Strategies
+
+#### Amortized Forgetting
+- Gradual decay of old memories
+- Importance-based retention
+- Memory cleanup
+
+#### Attention-based
+- LLM-guided memory focus
+- Context-aware retention
+- Dynamic memory prioritization
+
+#### Summarization
+- Memory compression through summarization
+- Key information extraction
+- Context preservation
+
+#### Observation Masking
+- Selective memory storage
+- Pattern-based filtering
+- Memory optimization
+
+### Long-term Memory
+- Persistent storage
+- Indexing and retrieval
+- Memory search
+- Context management
+
+## Usage
+The memory system is used for:
+1. Conversation history management
+2. Context preservation
+3. Memory optimization
+4. Information retrieval
+5. Long-term storage
+
+## Integration Points
+- Used by agents for context
+- Connected to LLM for processing
+- Integrated with storage system
+- Used by controller for state management
+
+## Memory Lifecycle
+1. Event/observation capture
+2. Memory processing (condensing)
+3. Storage optimization
+4. Retrieval on demand
+5. Gradual decay or archival
\ No newline at end of file
diff --git a/openhands/storage/summary.md b/openhands/storage/summary.md
new file mode 100644
index 000000000000..3dd6e2807ba4
--- /dev/null
+++ b/openhands/storage/summary.md
@@ -0,0 +1,89 @@
+# Storage Directory
+
+The `storage` directory implements data persistence and storage management for the OpenHands framework.
+
+## Core Components
+
+### Conversation Storage
+- `conversation_store.py`: Base conversation storage interface
+- `file_conversation_store.py`: File-based conversation storage
+- Handles persistent storage of conversations and related data
+
+### File Storage
+- `file_store.py`: File system operations
+- `file_utils.py`: File handling utilities
+- Manages file operations and persistence
+
+### Settings Storage
+- `settings_store.py`: Application settings storage
+- `settings_utils.py`: Settings management utilities
+- Handles configuration persistence
+
+### Storage Types
+- Local file system storage
+- Memory-based storage
+- Database storage options
+- Cloud storage integration
+
+## Key Features
+- Multiple storage backends
+- Atomic operations
+- Data integrity checks
+- Concurrent access support
+- Backup and recovery
+
+## Implementation Details
+
+### Conversation Storage
+- Thread-safe operations
+- Versioning support
+- Search capabilities
+- Compression options
+- Cleanup utilities
+
+### File Operations
+- Safe file handling
+- Path management
+- Permission handling
+- Temporary file support
+- File locking
+
+### Settings Management
+- Configuration persistence
+- Default handling
+- Environment integration
+- Override management
+
+### Storage Backends
+- File system implementation
+- Memory cache support
+- Database integration
+- Cloud storage options
+
+## Usage
+The storage system is used for:
+1. Conversation persistence
+2. File management
+3. Settings storage
+4. Data backup
+5. Resource management
+
+## Integration Points
+- Used by memory system
+- Connected to controller
+- Integrated with security
+- Used by agents for data access
+
+## Data Lifecycle
+1. Data creation/modification
+2. Storage selection
+3. Persistence handling
+4. Retrieval operations
+5. Cleanup and maintenance
+
+## Security Features
+- Access control
+- Data encryption
+- Integrity verification
+- Audit logging
+- Backup protection
\ No newline at end of file