Storage Overview

Agentium uses a StorageDriver interface for key-value persistence. Storage drivers power session management, memory, and any component that needs to store state across requests. Choose the right driver based on your deployment environment, scale, and persistence requirements.

StorageDriver Interface

All storage implementations conform to the same interface:

interface StorageDriver {
  initialize?(): Promise<void>;  // Postgres/Mongo call this; SQLite/memory skip it
  get<T>(namespace: string, key: string): Promise<T | null>;
  set<T>(namespace: string, key: string, value: T): Promise<void>;
  delete(namespace: string, key: string): Promise<void>;
  list<T>(namespace: string, prefix?: string): Promise<Array<{ key: string; value: T }>>;
  close(): Promise<void>;
}

() => Promise<void>

Optional. Postgres and Mongo call this to create tables/indexes. SQLite and in-memory no-op. Agentium calls it for you when memory starts.

(namespace, key) => Promise<T | null>

Retrieves a value by namespace and key. Returns null if not found.

(namespace, key, value) => Promise<void>

Stores a value. Values are JSON-serialized automatically.

(namespace, key) => Promise<void>

Removes a key from the namespace.

(namespace, prefix?) => Promise<Array<{key, value}>>

Lists all keys in a namespace, optionally filtered by prefix.

() => Promise<void>

Closes connections and releases resources.

Choosing a Driver

Development & Testing

Use InMemoryStorage—no setup, no dependencies. Data is lost on restart.

Single-Node Production

Use SqliteStorage or PostgresStorage for durable, file-based or relational persistence.

Distributed / Scale

Use PostgresStorage or MongoDBStorage for multi-instance deployments.

Document-Oriented

Use MongoDBStorage if you already run MongoDB or prefer document storage.

Comparison Table

Driver	Constructor	Dependencies	Persistence	Best For
InMemoryStorage	`new InMemoryStorage()`	None	No	Dev, tests
SqliteStorage	`new SqliteStorage(path)` or `{ path }`	`better-sqlite3`	File	Single node
PostgresStorage	`new PostgresStorage(url)`	`pg`	Yes	Production
MongoDBStorage	`new MongoDBStorage({ uri, dbName?, collectionName? })`	`mongodb`	Yes	Document stores
MySQLStorage	`new MySQLStorage({ host, user, password, database })`	`mysql2`	Yes	MySQL shops
RedisStorage	`new RedisStorage(url \| ioredis)`	`ioredis`	Yes	Fast KV / cache
DynamoDBStorage	`new DynamoDBStorage({ tableName, region? })`	AWS SDK	Yes	AWS serverless

Clients are optional peer dependencies. Importing Agent does not install them. Only the driver you construct needs its client.

Namespaces

Storage uses namespaces to isolate data. Agentium reserves namespaces such as:

memory:short — Short-term conversation messages
memory:long — Long-term summaries
session:* — Session metadata

You can use custom namespaces for your own key-value data.

Quick Example

import { InMemoryStorage } from "@agentium/core";

const storage = new InMemoryStorage();
await storage.set("myapp", "config", { theme: "dark" });
const config = await storage.get("myapp", "config");

import { SqliteStorage } from "@agentium/core";

const storage = new SqliteStorage("./data/agentium.db");
await storage.set("sessions", "user-123", { lastActive: Date.now() });

import { PostgresStorage } from "@agentium/core";

const storage = new PostgresStorage(process.env.DATABASE_URL!);
await storage.initialize();
await storage.set("cache", "key1", { value: 42 });

import { MongoDBStorage } from "@agentium/core";

const storage = new MongoDBStorage(
  process.env.MONGO_URI!,
  "myapp",
  "kv_store"
);
await storage.initialize();
await storage.set("users", "prefs", { notifications: true });

Next Steps

In-Memory Storage — Zero-config, ephemeral storage
SQLite Storage — File-based persistence with better-sqlite3
PostgreSQL Storage — Production-grade relational storage
MongoDB Storage — Document-based storage for scale

Find an integration

Voice and call adapters

Sandbox and telemetry

Providers and services

Protocols and devices

StorageDriver Interface

Choosing a Driver

Development & Testing

Single-Node Production

Distributed / Scale

Document-Oriented

Comparison Table

Namespaces

Quick Example

Next Steps

​StorageDriver Interface

​Choosing a Driver

Development & Testing

Single-Node Production

Distributed / Scale

Document-Oriented

​Comparison Table

​Namespaces

​Quick Example

​Next Steps

StorageDriver Interface

Choosing a Driver

Comparison Table

Namespaces

Quick Example

Next Steps