AgentuityAgentuity
BlogConsoleDiscordCommunity

Custom Storage

Local development storage and bringing your own storage implementations

Agentuity provides managed storage in both development and production. You can also bring your own storage implementations.

Local Development

During local development, storage is backed by SQLite and persists between runs. This happens automatically when you're not authenticated, or when you explicitly enable local mode:

import { createApp } from '@agentuity/runtime';
 
const app = await createApp({
  services: {
    useLocal: true,  // Force local storage even when authenticated
  },
});

Local storage data is saved to your project directory, so you can develop with realistic data without affecting production.

Production

When deployed to Agentuity, your agents automatically use managed cloud storage. No configuration required.

Custom Storage Implementations

You can replace any storage type with your own implementation. This is useful when you need to:

  • Use existing infrastructure: Connect to your company's Redis, Postgres, or S3
  • Meet compliance requirements: Keep data in specific regions or systems
  • Self-host: Run entirely on your own infrastructure

Pass your implementation to createApp():

import { createApp } from '@agentuity/runtime';
import { MyRedisKV, MyPineconeVector } from './my-storage';
 
const app = await createApp({
  services: {
    keyvalue: new MyRedisKV(),
    vector: new MyPineconeVector(),
    // object and stream use Agentuity defaults
  },
});

Storage Interfaces

Your implementation must satisfy the interface for each storage type. When your agent calls ctx.kv.get(), the SDK calls your implementation's get() method.

These interfaces are exported from @agentuity/core:

KeyValueStorage

interface KeyValueStorage {
  get<T>(name: string, key: string): Promise<DataResult<T>>;
  set<T>(name: string, key: string, value: T, params?: { ttl?: number; contentType?: string }): Promise<void>;
  delete(name: string, key: string): Promise<void>;
  getStats(name: string): Promise<KeyValueStats>;
  getNamespaces(): Promise<string[]>;
  search<T>(name: string, keyword: string): Promise<Record<string, KeyValueItemWithMetadata<T>>>;
  getKeys(name: string): Promise<string[]>;
}

VectorStorage

interface VectorStorage {
  upsert(name: string, ...documents: VectorUpsertParams[]): Promise<VectorUpsertResult[]>;
  get<T>(name: string, key: string): Promise<VectorResult<T>>;
  getMany<T>(name: string, ...keys: string[]): Promise<Map<string, VectorSearchResultWithDocument<T>>>;
  search<T>(name: string, params: VectorSearchParams<T>): Promise<VectorSearchResult<T>[]>;
  delete(name: string, ...keys: string[]): Promise<number>;
  exists(name: string): Promise<boolean>;
}

ObjectStorage

interface ObjectStorage {
  get(bucket: string, key: string): Promise<ObjectResult>;
  put(bucket: string, key: string, data: Uint8Array | ArrayBuffer | ReadableStream, params?: ObjectStorePutParams): Promise<void>;
  delete(bucket: string, key: string): Promise<boolean>;
  createPublicURL(bucket: string, key: string, params?: CreatePublicURLParams): Promise<string>;
  listBuckets(): Promise<BucketInfo[]>;
  listObjects(bucket: string, options?: { prefix?: string; limit?: number }): Promise<ObjectInfo[]>;
  headObject(bucket: string, key: string): Promise<ObjectInfo>;
}

StreamStorage

interface StreamStorage {
  create(name: string, props?: CreateStreamProps): Promise<Stream>;
  get(id: string): Promise<StreamInfo>;
  download(id: string): Promise<ReadableStream<Uint8Array>>;
  list(params?: ListStreamsParams): Promise<ListStreamsResponse>;
  delete(id: string): Promise<void>;
}

Production Requirements

Custom storage must be accessible from Agentuity's infrastructure when deployed. Ensure your storage endpoints are reachable and properly authenticated.

Next Steps

Need Help?

Join our DiscordCommunity for assistance or just to hang with other humans building agents.

Send us an email at hi@agentuity.com if you'd like to get in touch.

Please Follow us on

If you haven't already, please Signup for your free account now and start building your first agent!

Edit on GitHub