Class SqlStorageAdapter

SQL storage adapter implementation for AgentOS.

Provides full persistence for conversations and messages using a SQL database. Wraps @framers/sql-storage-adapter to provide AgentOS-specific schema and operations.

Features:

  • Cross-platform SQL support (SQLite, PostgreSQL, SQL.js, Capacitor)
  • Automatic schema creation and migration
  • Efficient querying with indexes
  • Transaction support for atomic operations
  • Type-safe API with full TypeScript support

Database Schema:

  • conversations table: Stores conversation metadata
  • messages table: Stores individual messages with foreign key to conversations
  • Indexes on frequently queried columns for performance
  • Timestamps are milliseconds in BIGINT columns

Implements

Example

// Node.js: better-sqlite3, or sql.js when the native module does not load
const storage = new SqlStorageAdapter({
  filePath: './data/agentos.db',
  priority: ['better-sqlite3', 'sqljs'],
});
await storage.initialize();

// PostgreSQL, with the tables in a schema of their own
const pgStorage = new SqlStorageAdapter({
  priority: ['postgres'],
  postgres: { connectionString: process.env.DATABASE_URL },
  segment: 'agentos',
  messageRetentionDays: 90,
});
await pgStorage.initialize();

Implements

Constructors

constructor

Methods

initialize close createConversation getConversation updateConversation deleteConversation listConversations storeMessage getMessage getMessages deleteMessage deleteMessagesForConversation getMessageCount getConversationTokenUsage

Constructors

constructor

Methods

initialize

  • initialize(): Promise<void>

  • Initializes the storage adapter and creates the database schema.

    Schema created (unless enableAutoMigration is false):

    • conversations table with indexes on userId, agentId and lastActivity
    • messages table with indexes on conversationId, timestamp and role
    • Foreign key constraints for referential integrity
    • On PostgreSQL, INTEGER timestamp columns of an older table widened to BIGINT

    With messageRetentionDays set, it then deletes the messages older than that.

    Must be called before any other operations.

    Returns Promise<void>

    Throws

    If database connection or schema creation fails

    Example

    await storage.initialize();
    console.log('Storage ready!');

close

createConversation

getConversation

updateConversation

deleteConversation

  • deleteConversation(conversationId): Promise<boolean>

  • Deletes a conversation and all its messages, in one transaction.

    The messages are deleted by their own statement. The table's ON DELETE CASCADE acts only where foreign keys are enforced, and SQLite leaves them off on a connection that does not turn them on (https://www.sqlite.org/foreignkeys.html), as the sql.js, IndexedDB and Capacitor adapters do.

    Parameters

    • conversationId: string

      Conversation to delete

    Returns Promise<boolean>

    True if deleted, false if not found

listConversations

  • listConversations(userId, options?): Promise<IConversation[]>

  • Lists conversations for a user with optional filtering.

    Parameters

    • userId: string

      User whose conversations to list

    • Optional options: {
          limit?: number;
          offset?: number;
          agentId?: string;
      }

      Query options

      • Optional limit?: number
      • Optional offset?: number
      • Optional agentId?: string

    Returns Promise<IConversation[]>

    Array of conversations

storeMessage

getMessage

getMessages

deleteMessage

deleteMessagesForConversation

getMessageCount

getConversationTokenUsage

Settings

Member Visibility

Theme

On This Page

constructorinitializeclosecreateConversationgetConversationupdateConversationdeleteConversationlistConversationsstoreMessagegetMessagegetMessagesdeleteMessagedeleteMessagesForConversationgetMessageCountgetConversationTokenUsage