Agentuity provides multiple storage options to match different data access patterns.
Storage Types
Key-Value
Fast lookups, caching, configuration
Vector
Semantic search, embeddings, RAG
Object (S3)
Files, images, documents, media
Durable Streams
Large exports, audit logs, real-time data
When to Use Each Type
| Storage Type | Best For | Access Pattern |
|---|---|---|
| Key-Value | Caching, session data, rate limits | Fast key-based lookups |
| Vector | Semantic search, embeddings, RAG | Similarity search |
| Object | Files, images, large blobs | URL-based access |
| Durable Streams | Logs, exports, event streams | Append-only, ordered reads |
| Database | Relational data, complex queries | SQL queries |
Built-in State vs Storage
Agents have built-in state for request-local work and thread-level conversation history:
| State Type | Scope | Use For |
|---|---|---|
ctx.state | Request | Temporary values used inside the current handler |
ctx.session.state | Request | Values needed during the current request or session-completion callbacks |
ctx.thread.state | Thread | Conversation context across requests |
Use storage services when you need:
- Custom TTL or expiration
- Data shared across agents
- Durable data beyond thread state
- External system integration
Access Patterns
| Context | KV | Vector | Stream |
|---|---|---|---|
| Agents | ctx.kv | ctx.vector | ctx.stream |
| Routes | c.var.kv | c.var.vector | c.var.stream |
Object and Database Storage Use Bun APIs
Database and object storage are not exposed on ctx.* or c.var.*. Use Bun's native sql and s3 APIs for those services. See Storage APIs for the current breakdown.
Custom Storage
For runtime services that need a different backend, you can implement custom Key-Value, Vector, or Durable Stream storage.