Storage Overview

StorageDriver interface, choosing a driver, and comparison of InMemory, SQLite, PostgreSQL, and MongoDB storage backends in RadarOS.

Storage Overview

RadarOS 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 {
  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>;
}

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

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

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

Stores a value. Values are JSON-serialized automatically.

delete · (namespace, key) => Promise<void>

Removes a key from the namespace.

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

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

close · () => 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	Dependencies	Initialize Required	Persistence	Best For
InMemoryStorage	None	No	No (lost on restart)	Dev, tests, demos
SqliteStorage	better-sqlite3	No	Yes (file)	Single-node, embedded
PostgresStorage	pg	Yes	Yes	Production, multi-instance
MongoDBStorage	mongodb	Yes	Yes	Document stores, scale

---

Namespaces

Storage uses namespaces to isolate data. RadarOS 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

In-memory (default)

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

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

---

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