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

# Backend

> Zeus CloudDriveBackend storage solution

> DeepAgents Backend manages Agent file system operations, including artifact storage, user cloud drive, and long-term memory.

***

## 1. Overview

### 1.1 Current Issues

| Issue                               | Description                                                            |
| ----------------------------------- | ---------------------------------------------------------------------- |
| **In-memory data loss**             | StateBackend uses InMemoryStore; all data is lost on service restart   |
| **Frontend cannot access data**     | Files in the virtual file system are inaccessible to the frontend      |
| **Sandbox destruction**             | Artifacts are lost when the E2B sandbox times out                      |
| **Multi-environment inconsistency** | Data is fragmented across Desktop, Sandbox, and in-memory environments |

### 1.2 Goals

* All artifacts are automatically persisted to cloud storage
* Users have a "cloud drive" experience with access to their files at any time
* Unified storage architecture to reduce complexity

***

## 2. DeepAgents Backend Types

DeepAgents provides the following Backend types:

| Backend               | Durability          | Storage Location             | Use Case                             |
| --------------------- | ------------------- | ---------------------------- | ------------------------------------ |
| **StateBackend**      | ❌ Temporary         | LangGraph State (in-memory)  | Temporary files for a single session |
| **StoreBackend**      | ✅ Persistent        | LangGraph Store              | Long-term memory                     |
| **FilesystemBackend** | ✅ Persistent        | Local file system            | Desktop mode                         |
| **BaseSandbox**       | ⚠️ Sandbox lifetime | Remote sandbox (E2B)         | Code execution                       |
| **CompositeBackend**  | Composite           | Routes to different Backends | Hybrid architecture                  |

***

## 3. Recommended Solution: CloudDriveBackend

### 3.1 Architecture Design

```mermaid theme={null}
flowchart TB
    subgraph Tools["DeepAgent Tool Calls"]
        direction LR
        FileRead["file_read<br/>file_ls"]
        FileWrite["file_write<br/>file_grep"]
        FileEdit["file_edit<br/>file_glob"]
    end

    subgraph CloudDrive["CloudDriveBackend"]
        subgraph Cache["Redis (Cache Layer)"]
            CacheInfo["Hot file cache TTL: 5min<br/>Reduces Supabase API calls<br/>No persistence needed, pure cache"]
        end
        
        subgraph Storage["Supabase Storage (Persistence Layer)"]
            subgraph Bucket["workspace bucket"]
                subgraph UserDir["users/{user_id}/"]
                    Workspace["workspace/<br/>├── projects/<br/>├── sandbox-output/<br/>└── uploads/"]
                    Memory["memory/<br/>├── user_profile.json<br/>└── facts/"]
                end
            end
        end
        
        Cache --> Storage
    end

    FileRead --> CloudDrive
    FileWrite --> CloudDrive
    FileEdit --> CloudDrive
```

### 3.2 Storage Structure

```mermaid theme={null}
graph LR
    subgraph SupabaseStorage["Supabase Storage: workspace bucket"]
        subgraph Users["users/"]
            subgraph UserID["{user_id}/"]
                subgraph Workspace["workspace/ - Workspace"]
                    Projects["projects/<br/>└── my-app/<br/>    ├── src/main.py<br/>    └── README.md"]
                    SandboxOutput["sandbox-output/<br/>└── 2024-01-31/<br/>    └── result.csv"]
                    Uploads["uploads/<br/>└── data.xlsx"]
                end
                
                subgraph Memory["memory/ - Long-term Memory"]
                    UserProfile["user_profile.json"]
                    Facts["facts/<br/>├── coding_style.json<br/>└── preferences.json"]
                    Conversations["conversations/<br/>└── 2024-01/<br/>    └── summary.json"]
                end
            end
        end
    end
```

***

## 4. CloudDriveBackend Overview

CloudDriveBackend is a persistent file backend built on Supabase Storage with the following features:

* Isolated storage space per user
* All files are automatically persisted
* Redis cache for acceleration
* Support for large files (images, documents, etc.)

Storage structure:

* `/workspace/` - Workspace files (Agent artifacts)
* `/memory/` - Long-term memory (user knowledge)

Path mapping rules:

* Virtual path `/code/main.py` maps to `users/{user_id}/workspace/code/main.py`
* Virtual path `/memory/facts.json` maps to `users/{user_id}/memory/facts.json`

CloudDriveBackend implements the full BackendProtocol interface, including file listing, reading, writing, editing, searching, glob matching, uploading, and downloading operations.

### 4.1 Integration

BaseService manages CloudDriveBackend instances through Redis cache and a per-user Backend cache. Each user has an independent Backend instance, accessed via `get_backend(user_id)`.

***

## 5. Desktop Mode Support

When users are on the Desktop app, the system automatically selects the appropriate Backend based on the device type:

* **Desktop mode**: Uses FilesystemBackend (local file system)
* **Cloud mode**: Uses CloudDriveBackend (Supabase Storage)

***

## 6. Frontend Cloud Drive API

The frontend interacts with the cloud drive through the following API endpoints:

* `GET /api/storage/list?path=...` - List files
* `POST /api/storage/upload` - Upload files
* `GET /api/storage/download?path=...` - Download files
* `DELETE /api/storage/delete?path=...` - Delete files
* `GET /api/storage/url?path=...` - Get preview URL

***

## 7. Sandbox Artifact Sync

When the E2B sandbox generates files, the system automatically syncs the artifacts to the user's cloud drive, stored under the `/workspace/sandbox-output/{date}/` path.

***

## 8. Performance Optimization

### 8.1 Redis Cache Performance

| Operation            | Without Cache | With Cache (hit) | Improvement |
| -------------------- | ------------- | ---------------- | ----------- |
| Read file            | 200-500ms     | 1-5ms            | **100x**    |
| List directory       | 100-300ms     | 5-10ms           | **30x**     |
| Check file existence | 100-200ms     | 1ms              | **100x**    |

### 8.2 Cache Strategy

* Workspace files TTL: 5 minutes
* Memory files TTL: 10 minutes
* Cache is updated immediately after writes/edits

***

## 9. Migration Steps

1. **Create Supabase Storage Bucket** - Create the `workspace` bucket in the Supabase Dashboard
2. **Configure RLS Policies** - Ensure users can only access their own files
3. **Configure Environment Variables** - Set `SUPABASE_URL`, `SUPABASE_SERVICE_KEY`, `REDIS_URL` (optional)
4. **Create CloudDriveBackend** - Implement the core Backend logic
5. **Modify BaseService** - Integrate CloudDriveBackend
6. **Remove Old Code** - Remove StateBackend and InMemoryStore related usage

***

## 10. Summary

| Item            | Current State             | Target State                             |
| --------------- | ------------------------- | ---------------------------------------- |
| Backend         | StateBackend (in-memory)  | CloudDriveBackend (Supabase)             |
| Durability      | ❌ Lost on service restart | ✅ Permanently saved                      |
| User Visibility | ❌ Frontend cannot access  | ✅ Cloud drive experience                 |
| Cache           | ❌ None                    | ✅ Redis acceleration                     |
| Memory          | InMemoryStore             | Supabase Storage (custom implementation) |