Skip to main content
Agentium uses a StorageDriver interface for key-value persistence in sessions and memory. Cost accounting has a separate store contract because assessment selection and budget settlement require transactions. Choose the store for the component you need to persist.

StorageDriver Interface

All storage implementations conform to the same interface:
() => 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

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


Persist cost accounting

Cost stores remain part of @agentium/core. They retain usage observations, revisions, assessments, selected views, and budget reservations. Passing a session StorageDriver does not enable this persistence. Configuration factory: supply a writable SQLite path and a reviewed catalog. The caller owns the returned store and must close it after active work and pending writes settle.
Queries are tenant-scoped. queryUsage() and assessment-record queries use cursor pagination; queryCosts() aggregates the selected view. Replaying the same observation is idempotent. Reusing its ID with different content is a conflict. Shared reservation budgets must use one transaction-capable backend for usage and budget state. A generic KV archive cannot promise atomic admission or complete history if listing or retention is limited. See cost accounting and budget controls.

Next Steps