> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hopx.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Cache Management

> Cache management resource for managing execution result cache in HopX sandboxes using the Python SDK. Complete reference for the Cache class including methods for viewing cache statistics and clearing execution cache. Includes code examples for cache optimization and performance tuning.

**Version:** 0.3.0\
**Last Verified:** 2025-01-27\
**Package:** `hopx-ai` on [PyPI](https://pypi.org/project/hopx-ai/)

## Overview

The `Cache` resource provides methods for managing the execution result cache in sandboxes. The cache stores execution results to improve performance for repeated code executions. Use this resource to view cache statistics and clear the cache when needed.

## Access

```python theme={null}
from hopx_ai import Sandbox

sandbox = Sandbox.create(template="code-interpreter")
cache = sandbox.cache  # Lazy-loaded
```

## Methods

### `stats`

Get cache statistics.

```python theme={null}
cache.stats(*, timeout=None) -> Dict[str, Any]
```

**Returns:** `Dict[str, Any]` - Cache statistics dictionary with:

* `cache.total_hits` (`int`): Total cache hits
* `cache.size` (`int`): Current cache size
* `cache.max_size` (`int`): Maximum cache size
* `cache.ttl` (`int`): Time-to-live in seconds
* `timestamp` (`str`): Timestamp of the statistics

**Example:**

```python theme={null}
stats = sandbox.cache.stats()
cache_data = stats['cache']
print(f"Cache hits: {cache_data['total_hits']}")
print(f"Cache size: {cache_data['size']} / {cache_data['max_size']}")
```

***

### `clear`

Clear the execution result cache.

```python theme={null}
cache.clear(*, timeout=None) -> Dict[str, Any]
```

**Returns:** `Dict[str, Any]` - Confirmation message

<Warning>
  This clears all cached execution results. Subsequent executions will not benefit from cached results until cache is repopulated.
</Warning>

**Example:**

```python theme={null}
# Check cache size before clearing
stats_before = sandbox.cache.stats()
print(f"Cache size before: {stats_before['cache']['size']}")

# Clear cache
sandbox.cache.clear()

# Check cache size after clearing
stats_after = sandbox.cache.stats()
print(f"Cache size after: {stats_after['cache']['size']}")
```

**See Also:**

* [API: Clear Cache](/api/vm-agent/clear-cache)

***

## Examples

### Example 1: Viewing Cache Statistics

```python theme={null}
from hopx_ai import Sandbox

sandbox = Sandbox.create(template="code-interpreter")

# Get cache statistics
stats = sandbox.cache.stats()
cache_data = stats['cache']

print(f"Total cache hits: {cache_data['total_hits']}")
print(f"Current size: {cache_data['size']}")
print(f"Max size: {cache_data['max_size']}")
print(f"TTL: {cache_data['ttl']} seconds")

sandbox.kill()
```

### Example 2: Clearing Cache

```python theme={null}
from hopx_ai import Sandbox

sandbox = Sandbox.create(template="code-interpreter")

# Execute code (may be cached)
result1 = sandbox.run_code("print('Hello')")

# Clear cache
sandbox.cache.clear()
print("Cache cleared")

# Execute again (not cached)
result2 = sandbox.run_code("print('Hello')")

sandbox.kill()
```

### Example 3: Monitoring Cache Usage

```python theme={null}
from hopx_ai import Sandbox

sandbox = Sandbox.create(template="code-interpreter")

# Check initial cache state
initial_stats = sandbox.cache.stats()
print(f"Initial cache size: {initial_stats['cache']['size']}")

# Run multiple executions
for i in range(5):
    sandbox.run_code(f"print('Execution {i}')")

# Check cache after executions
final_stats = sandbox.cache.stats()
print(f"Final cache size: {final_stats['cache']['size']}")
print(f"Cache hits: {final_stats['cache']['total_hits']}")

sandbox.kill()
```

***

## Related Classes

* **[Sandbox](/sdk/python/sandbox)** - Main sandbox class
* **[Core Concepts: Cache](/core-concepts/cache/statistics)** - Learn about cache management

## See Also

* [Sandbox Class](/sdk/python/sandbox) - Access cache via `sandbox.cache`
* [Cache Statistics](/core-concepts/cache/statistics) - Detailed cache documentation

## Related

* **[Code Execution](/core-concepts/code-execution/synchronous)** - Execution results are cached
* **[API: Cache Management](/api/vm-agent/get-cache-stats)** - VM Agent API endpoints

## Next Steps

* Learn about [Code Execution](/core-concepts/code-execution/synchronous) to see cached results
* Review [Cache Statistics](/core-concepts/cache/statistics) for detailed cache information
* **[CLI Cache](/cli/commands/system)** - View cache statistics from CLI