File Storage

File management, storage configuration, and organization patterns for AI agents and content.

On this page

SystemPrompt includes a built-in file storage system for managing uploads, images, and assets. Files are stored locally with metadata in PostgreSQL, accessible via CLI and API.

Overview

The file storage system provides:

  • Upload management - Store files with context associations
  • MIME type filtering - List and search by file type
  • AI content tracking - Tag AI-generated images
  • Storage statistics - Monitor usage and quotas
  • Context association - Link files to conversations and users

CLI Commands

List Files

# List all files
systemprompt core files list

# Paginated listing
systemprompt core files list --limit 50
systemprompt core files list --limit 20 --offset 40

# Filter by MIME type
systemprompt core files list --mime image/png
systemprompt core files list --mime image/webp
systemprompt core files list --mime application/pdf

Show File Details

systemprompt core files show file_abc123

Returns file metadata including path, size, MIME type, upload time, and associated context.

Upload Files

# Upload with context association
systemprompt core files upload /path/to/image.png --context <context-id>

# Mark as AI-generated
systemprompt core files upload /path/to/image.png --context <context-id> --ai

# Validate before upload
systemprompt core files validate /path/to/image.png
Flag Purpose
--context Required context ID for the upload
--ai Mark as AI-generated content
--user Associate with user ID
--session Associate with session ID

Search Files

# Search by name pattern
systemprompt core files search "blog"
systemprompt core files search "*.png"
systemprompt core files search "images/2026"

Delete Files

# Delete with confirmation
systemprompt core files delete file_abc123

# Skip confirmation
systemprompt core files delete file_abc123 -y

Storage Configuration

View current storage configuration:

systemprompt core files config

Returns:

  • Maximum file size
  • Allowed MIME types
  • Storage directory path

Configure storage in services/storage/config.yaml:

storage:
  path: "/var/data/files"
  max_file_size: 10485760  # 10MB
  allowed_types:
    - image/png
    - image/jpeg
    - image/webp
    - application/pdf

Storage Statistics

systemprompt core files stats

Shows:

  • Total file count
  • Total storage used
  • Files by type breakdown
  • Recent uploads

AI-Generated Images

Track AI-generated content separately:

# List AI-generated images
systemprompt core files ai list

# Show AI image details
systemprompt core files ai show <image-id>

AI images include additional metadata for provenance tracking.

File Organization

Recommended directory structure:

storage/files/
├── images/
│   ├── avatars/
│   ├── uploads/
│   └── generated/
├── documents/
└── assets/
    ├── css/
    └── js/

Context Association

Files are associated with contexts for:

  • Access control (user isolation)
  • Cleanup (delete context, delete files)
  • Organization (group related files)
# Upload to specific context
systemprompt core files upload image.png --context ctx_123

# List files in context
systemprompt core files list --context ctx_123

Troubleshooting

Issue Cause Solution
Upload failed File too large Check core files config for limits
Upload failed Invalid type Check allowed MIME types in config
File not found Wrong ID Search with core files search "partial-name"
Permission denied No context Always provide --context flag

Next Steps

-> See Feature: Embedded AI Platform

Playbooks:

  • systemprompt core playbooks show cli_files - File operations
Previous Next
Internal Tooling Scheduling