Class: SqlStorageAdapter

Defined in: packages/agentos/src/core/storage/SqlStorageAdapter.ts:143

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

• IStorageAdapter

Constructors

Constructor

new SqlStorageAdapter(config?): SqlStorageAdapter

Defined in: packages/agentos/src/core/storage/SqlStorageAdapter.ts:162

Creates a new SQL storage adapter instance.

Parameters

config?

AgentOsSqlStorageConfig = {}

Storage configuration

Returns

SqlStorageAdapter

Example

const storage = new SqlStorageAdapter({
  filePath: './agentos.db',
  priority: ['better-sqlite3']
});

Methods

close()

close(): Promise<void>

Defined in: packages/agentos/src/core/storage/SqlStorageAdapter.ts:224

Closes the database connection and releases resources.

Returns

Promise<void>

Example

await storage.close();

Implementation of

IStorageAdapter.close

---

createConversation()

createConversation(conversation): Promise<IConversation>

Defined in: packages/agentos/src/core/storage/SqlStorageAdapter.ts:241

Creates a new conversation record.

Parameters

conversation

IConversation

Conversation to create

Returns

Promise<IConversation>

The created conversation

Throws

If conversation with same ID exists or validation fails

Implementation of

IStorageAdapter.createConversation

---

deleteConversation()

deleteConversation(conversationId): Promise<boolean>

Defined in: packages/agentos/src/core/storage/SqlStorageAdapter.ts:336

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

Implementation of

IStorageAdapter.deleteConversation

---

deleteMessage()

deleteMessage(messageId): Promise<boolean>

Defined in: packages/agentos/src/core/storage/SqlStorageAdapter.ts:501

Deletes a specific message.

Parameters

messageId

string

Message to delete

Returns

Promise<boolean>

True if deleted

Implementation of

IStorageAdapter.deleteMessage

---

deleteMessagesForConversation()

deleteMessagesForConversation(conversationId): Promise<number>

Defined in: packages/agentos/src/core/storage/SqlStorageAdapter.ts:514

Deletes all messages in a conversation.

Parameters

conversationId

string

Conversation whose messages to delete

Returns

Promise<number>

Number of messages deleted

Implementation of

IStorageAdapter.deleteMessagesForConversation

---

getConversation()

getConversation(conversationId): Promise<IConversation | null>

Defined in: packages/agentos/src/core/storage/SqlStorageAdapter.ts:269

Retrieves a conversation by ID.

Parameters

conversationId

string

The conversation ID

Returns

Promise<IConversation | null>

The conversation or null if not found

Implementation of

IStorageAdapter.getConversation

---

getConversationTokenUsage()

getConversationTokenUsage(conversationId): Promise<ITokenUsage>

Defined in: packages/agentos/src/core/storage/SqlStorageAdapter.ts:549

Calculates total token usage for a conversation.

Parameters

conversationId

string

Conversation to analyze

Returns

Promise<ITokenUsage>

Aggregated token usage

Implementation of

IStorageAdapter.getConversationTokenUsage

---

getMessage()

getMessage(messageId): Promise<IConversationMessage | null>

Defined in: packages/agentos/src/core/storage/SqlStorageAdapter.ts:441

Retrieves a message by ID.

Parameters

messageId

string

Message ID

Returns

Promise<IConversationMessage | null>

The message or null

Implementation of

IStorageAdapter.getMessage

---

getMessageCount()

getMessageCount(conversationId): Promise<number>

Defined in: packages/agentos/src/core/storage/SqlStorageAdapter.ts:532

Counts messages in a conversation.

Parameters

conversationId

string

Conversation to count

Returns

Promise<number>

Message count

Implementation of

IStorageAdapter.getMessageCount

---

getMessages()

getMessages(conversationId, options?): Promise<IConversationMessage[]>

Defined in: packages/agentos/src/core/storage/SqlStorageAdapter.ts:462

Retrieves messages for a conversation with filtering.

Parameters

conversationId

string

Conversation ID

options?

IMessageQueryOptions

Query options

Returns

Promise<IConversationMessage[]>

Array of messages

Implementation of

IStorageAdapter.getMessages

---

initialize()

initialize(): Promise<void>

Defined in: packages/agentos/src/core/storage/SqlStorageAdapter.ts:192

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!');

Implementation of

IStorageAdapter.initialize

---

listConversations()

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

Defined in: packages/agentos/src/core/storage/SqlStorageAdapter.ts:353

Lists conversations for a user with optional filtering.

Parameters

userId

string

User whose conversations to list

options?

Query options

agentId?

string

limit?

number

offset?

number

Returns

Promise<IConversation[]>

Array of conversations

Implementation of

IStorageAdapter.listConversations

---

storeMessage()

storeMessage(message): Promise<IConversationMessage>

Defined in: packages/agentos/src/core/storage/SqlStorageAdapter.ts:383

Stores a message and updates conversation's lastActivity.

Parameters

message

IConversationMessage

Message to store

Returns

Promise<IConversationMessage>

The stored message

Throws

If conversation doesn't exist

Implementation of

IStorageAdapter.storeMessage

---

updateConversation()

updateConversation(conversationId, updates): Promise<IConversation>

Defined in: packages/agentos/src/core/storage/SqlStorageAdapter.ts:292

Updates a conversation's fields.

Parameters

conversationId

string

Conversation to update

updates

Partial<IConversation>

Fields to update

Returns

Promise<IConversation>

Updated conversation

Throws

If conversation doesn't exist

Implementation of

IStorageAdapter.updateConversation