Class: SqlStorageAdapter

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

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

SqlStorageAdapter

Implements

Example

// Node.js with SQLite
const storage = new SqlStorageAdapter({
  type: 'better-sqlite3',
  database: './data/agentos.db',
  enableWAL: true
});

await storage.initialize();

// Browser with SQL.js
const browserStorage = new SqlStorageAdapter({
  type: 'sql.js',
  database: 'agentos.db',
  enableAutoMigration: true
});

await browserStorage.initialize();

Implements

• IStorageAdapter

Constructors

Constructor

new SqlStorageAdapter(config?): SqlStorageAdapter

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

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:213

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:227

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:316

Deletes a conversation and all its messages.

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:489

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:502

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:255

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:537

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:422

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:520

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:441

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:153

Initializes the storage adapter and creates the database schema.

Schema created:

• conversations table with indexes on userId and agentId
• messages table with indexes on conversationId and timestamp
• Foreign key constraints for referential integrity

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:334

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:373

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:278

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