Choose storage by access pattern first: key lookup, semantic search, files, streams, or relational SQL. Start with the direct storage client or API, and use Hono c.var.* when you want the same managed clients injected into routes.
Storage Types
When to use each type
| Storage Type | Best For | Client Path |
|---|---|---|
| Key-Value | Caching, session data, rate limits | @agentuity/keyvalue |
| Vector | Semantic search, embeddings, RAG | @agentuity/vector |
| Object | Files, images, large blobs | @agentuity/storage, with Bun S3 APIs for Bun-only helpers |
| Durable Streams | Logs, exports, event streams | @agentuity/stream |
| Database | Relational data, complex queries | DATABASE_URL with your app's database client, or a database helper when you choose one |
Use storage services when data must outlive the current request, be shared across workers or routes, or be inspected and managed as an Agentuity resource.
Access Patterns
| App Shape | KV | Vector | Durable Streams | Object Storage | Database |
|---|---|---|---|---|---|
| Any server framework or script | new KeyValueClient() | new VectorClient() | new StreamClient() | createS3Client(bucketConfigFromEnv()) | use your app's database client with DATABASE_URL |
Hono with @agentuity/hono | c.var.kv | c.var.vector | c.var.stream | create @agentuity/storage clients in server code | use your app's database client |
| Browser code | Call your backend route | Call your backend route | Call your backend route | Call your backend route | Call your backend route |
@agentuity/hono creates the same dedicated clients used in standalone examples and stores them on c.var.*. Database clients are not injected by the Hono middleware; create them directly where your app initializes database access.
Database is listed here for relational SQL. For KV, vector, streams, queues, tasks, schedules, email, webhooks, or sandboxes, use that service's dedicated client instead.
Wire Storage from Server Code
Install only the package for the storage surface you use, then create the client in server-only code. KV, vector, and stream clients read AGENTUITY_SDK_KEY, then AGENTUITY_CLI_KEY. Object storage reads the S3 env vars written when a bucket is linked to the project.
import { KeyValueClient } from '@agentuity/keyvalue';
import { bucketConfigFromEnv, createS3Client } from '@agentuity/storage';
export const kv = new KeyValueClient();
export const objectStorage = createS3Client(bucketConfigFromEnv());Use the storage guide for the access pattern first, then open the generated API reference when you need REST fields, status codes, or method-level details.
Custom Storage
For service code that needs a different backend, you can implement custom Key-Value, Vector, or Durable Stream storage.
Next Steps
- Key-Value Storage: store exact-key cache and state
- Vector Storage: use semantic search when exact keys are not enough
- Object Storage: store files and binary blobs
- Durable Streams: write generated output that remains readable by URL
- API Reference: inspect generated REST details for KV, vector, streams, and object storage