Storage

Mix employs a sophisticated two-tier storage architecture that separates user-managed collaborative files from agent-managed private working files. This design enables both file sharing across sessions and private agent workspaces.

Storage Overview

Rationale

This architecture separates user collaboration from agent workspace needs, solving three key problems:

Workspace Pollution: Agent temp files, logs, and processing outputs don't clutter the user's shared file space.

Processing Isolation: Multiple sessions can process the same shared file independently without conflicts.

Clean UX: Users manage collaborative files; agents handle implementation details in private storage.

Key Design Decisions

Two Storage Tiers: Shared storage for user collaboration + session storage for agent workspace. Single namespace would mix user assets with agent artifacts.

Agent-Managed Sessions: Agents handle session files programmatically. User CRUD access would expose implementation details unnecessarily.

Session-First Priority: Session files override shared files during serving, allowing agents to create processed versions without breaking originals for other sessions.

Two-Tier Architecture

1. Shared Uploads Storage (/storage/uploads/)

Purpose: User-managed collaborative files accessible by all sessions

• Who manages: Users via upload API
• Access: All sessions can read these files
• Use cases: Shared documents, media files, project assets
• API operations: Upload, list, delete, serve

2. Session Storage (/storage/{session-id}/)

Purpose: Agent-managed private working space per session

• Who manages: AI agents programmatically
• Access: Only the owning session can read these files
• Use cases: Temporary files, processed data, agent-generated content
• API operations: Serve only (agents manage via file system)

File Serving Priority

When a file is requested via /api/sessions/{session-id}/files/{filename}, the system uses this priority order:

1. Session storage first: Check /storage/{session-id}/{filename}
2. Shared uploads fallback: Check /storage/uploads/{filename} if not found in session

This allows agents to "override" shared files with session-specific versions while maintaining access to collaborative files.

Agent Workflow

Agents can download files from shared uploads and create session-specific versions:

1. Access shared file: Agent reads from /storage/uploads/{filename}
2. Process/modify: Agent processes the file contents
3. Store in session: Agent writes to /storage/{session-id}/{filename}
4. Serve processed version: Subsequent requests serve the session version

This enables agents to work with user files while maintaining private working copies.

Session Isolation

• Private storage: Session files are inaccessible to other sessions
• Secure serving: Session ID must match to access session-specific files
• Agent-only management: Users cannot directly manipulate session storage

Storage Paths

/storage/
├── uploads/           # Shared files (user-managed)
│   ├── document.pdf
│   ├── image.jpg
│   └── data.csv
├── {session-1-uuid}/  # Session 1 private files (agent-managed)
│   ├── processed.csv
│   └── temp-output.txt
└── {session-2-uuid}/  # Session 2 private files (agent-managed)
    ├── analysis.json
    └── filtered-data.csv

Key Files

• mix_agent/internal/session/storage.go: Core storage management functions that define the two-tier structure with GetSessionStoragePath() and GetUploadsStoragePath()
• mix_agent/internal/http/session_asset_server.go: Implements two-tier file serving logic with session storage priority over shared uploads
• mix_agent/internal/http/rest_files.go: Implements file management REST APIs including upload, listing, and deletion with secure path validation
• mix_agent/internal/app/app.go: Application initialization that sets up storage configuration and directory structure