StorageDriver Interface
All storage implementations conform to the same interface:Optional. Postgres and Mongo call this to create tables/indexes. SQLite and in-memory no-op. Agentium calls it for you when memory starts.
Retrieves a value by namespace and key. Returns
null if not found.Lists all keys in a namespace, optionally filtered by prefix.
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 messagesmemory:long— Long-term summariessession:*— Session metadata
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.
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
- 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