Workspace Memory — Persistent File Storage
Cloud Storage Support! Your agents can store files on AWS S3 or Cloudflare R2 for production-grade, distributed persistence.
A persistent file storage system that gives your agents a dedicated workspace to save, manage, and share files across sessions. Choose from local filesystem for development, or cloud storage (S3/R2) for production deployments.
Storage Backends
| Backend | Use Case | Benefits |
|---|
local | Development, single-server | Zero config, instant setup |
s3 | Production, AWS infrastructure | Scalable, durable, global access |
r2 | Production, edge computing | Zero egress fees, Cloudflare ecosystem |
Quick Setup
# Local storage (development)
agent_config = {
"memory_tool_backend": "local"
}
# AWS S3 storage (production)
agent_config = {
"memory_tool_backend": "s3"
}
# Cloudflare R2 storage (production)
agent_config = {
"memory_tool_backend": "r2"
}
Environment Variables
For S3
AWS_S3_BUCKET=my-agent-memories
AWS_ACCESS_KEY_ID=AKIA...
AWS_SECRET_ACCESS_KEY=your-secret
AWS_REGION=us-east-1 # optional, defaults to us-east-1
For R2
R2_BUCKET_NAME=my-agent-memories
R2_ACCOUNT_ID=your-cloudflare-account-id
R2_ACCESS_KEY_ID=your-r2-key
R2_SECRET_ACCESS_KEY=your-r2-secret
When enabled, your agent automatically gets these tools:
| Tool | Purpose |
|---|
memory_view | View/list files in memory workspace |
memory_create_update | Create, append, or overwrite files |
memory_str_replace | Find and replace text within files |
memory_insert | Insert text at specific line numbers |
memory_delete | Delete files from workspace |
memory_rename | Rename or move files |
memory_clear_all | Clear entire workspace |
Production Features
| Feature | Local | S3 | R2 |
|---|
| Persistent across restarts | ✅ | ✅ | ✅ |
| Multi-server access | ❌ | ✅ | ✅ |
| Global CDN distribution | ❌ | ✅ | ✅ |
| Zero egress fees | N/A | ❌ | ✅ |
| Auto-retry on failure | ❌ | ✅ | ✅ |
| Concurrent access safety | ✅ | ✅ | ✅ |
Use Cases
| Use Case | Recommended Backend |
|---|
| Local development | local |
| Single-server production | local or s3 |
| Multi-server / Kubernetes | s3 or r2 |
| Edge computing / Workers | r2 |
| Cost-sensitive workloads | r2 (zero egress) |
Example: Research Agent with Cloud Storage
import os
# Set environment for S3
os.environ["AWS_S3_BUCKET"] = "research-agent-memories"
os.environ["AWS_ACCESS_KEY_ID"] = "AKIA..."
os.environ["AWS_SECRET_ACCESS_KEY"] = "..."
os.environ["AWS_REGION"] = "us-east-1"
os.environ["AWS_ENDPOINT_URL"] = "https://s3.amazonaws.com" # Optional
agent = OmniCoreAgent(
name="research_agent",
system_instruction="You are a research assistant. Save your findings to memory.",
model_config={"provider": "openai", "model": "gpt-4o"},
agent_config={
"memory_tool_backend": "s3", # Files persist in S3
"max_steps": 50,
}
)
# Agent can now save research notes that persist across:
# - Server restarts
# - Multiple instances
# - Different geographic locations
result = await agent.run(
"Research the latest AI developments and save a summary to /notes/ai_trends_2024.md"
)
Use local for development. Use s3 or r2 when you need files to persist across server restarts, multiple agent instances accessing the same workspace, or production-grade durability.