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

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

Index

Constructors

constructor

Methods

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

Constructors

constructor

new SqlStorageAdapter(config?): SqlStorageAdapter
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']
});
```
- Defined in core/storage/SqlStorageAdapter.ts:126

Methods

initialize

initialize(): Promise<void>
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
- Defined in core/storage/SqlStorageAdapter.ts:153

close

close(): Promise<void>
Closes the database connection and releases resources.

Returns Promise<void>
Example
```
await storage.close();
```
Implementation of IStorageAdapter.close
- Defined in core/storage/SqlStorageAdapter.ts:213

createConversation

createConversation(conversation): Promise<IConversation>
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
- Defined in core/storage/SqlStorageAdapter.ts:227

getConversation

getConversation(conversationId): Promise<null | IConversation>
Retrieves a conversation by ID.
Parameters
- conversationId: string
  The conversation ID
Returns Promise<null | IConversation>
The conversation or null if not found
Implementation of IStorageAdapter.getConversation
- Defined in core/storage/SqlStorageAdapter.ts:255

updateConversation

updateConversation(conversationId, updates): Promise<IConversation>
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
- Defined in core/storage/SqlStorageAdapter.ts:278

deleteConversation

deleteConversation(conversationId): Promise<boolean>
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
- Defined in core/storage/SqlStorageAdapter.ts:316

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
Implementation of IStorageAdapter.listConversations
- Defined in core/storage/SqlStorageAdapter.ts:334

storeMessage

storeMessage(message): Promise<IConversationMessage>
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
- Defined in core/storage/SqlStorageAdapter.ts:373

getMessage

getMessage(messageId): Promise<null | IConversationMessage>
Retrieves a message by ID.
Parameters
- messageId: string
  Message ID
Returns Promise<null | IConversationMessage>
The message or null
Implementation of IStorageAdapter.getMessage
- Defined in core/storage/SqlStorageAdapter.ts:422

getMessages

getMessages(conversationId, options?): Promise<IConversationMessage[]>
Retrieves messages for a conversation with filtering.
Parameters
- conversationId: string
  Conversation ID
- Optional options: IMessageQueryOptions
  Query options
Returns Promise<IConversationMessage[]>
Array of messages
Implementation of IStorageAdapter.getMessages
- Defined in core/storage/SqlStorageAdapter.ts:441

deleteMessage

deleteMessage(messageId): Promise<boolean>
Deletes a specific message.
Parameters
- messageId: string
  Message to delete
Returns Promise<boolean>
True if deleted
Implementation of IStorageAdapter.deleteMessage
- Defined in core/storage/SqlStorageAdapter.ts:489

deleteMessagesForConversation

deleteMessagesForConversation(conversationId): Promise<number>
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
- Defined in core/storage/SqlStorageAdapter.ts:502

getMessageCount

getMessageCount(conversationId): Promise<number>
Counts messages in a conversation.
Parameters
- conversationId: string
  Conversation to count
Returns Promise<number>
Message count
Implementation of IStorageAdapter.getMessageCount
- Defined in core/storage/SqlStorageAdapter.ts:520

getConversationTokenUsage

getConversationTokenUsage(conversationId): Promise<ITokenUsage>
Calculates total token usage for a conversation.
Parameters
- conversationId: string
  Conversation to analyze
Returns Promise<ITokenUsage>
Aggregated token usage
Implementation of IStorageAdapter.getConversationTokenUsage
- Defined in core/storage/SqlStorageAdapter.ts:537

Class SqlStorageAdapter

Implements

Example

Implements

Index

Constructors

Methods

Constructors

constructor

Parameters

Returns SqlStorageAdapter

Example

Methods

initialize

Returns Promise<void>

Throws

Example

close

Returns Promise<void>

Example

createConversation

Parameters

Returns Promise<IConversation>

Throws

getConversation

Parameters

Returns Promise<null | IConversation>

updateConversation

Parameters

Returns Promise<IConversation>

Throws

deleteConversation

Parameters

Returns Promise<boolean>

listConversations

Parameters

Optional limit?: number

Optional offset?: number

Optional agentId?: string

Returns Promise<IConversation[]>

storeMessage

Parameters

Returns Promise<IConversationMessage>

Throws

getMessage

Parameters

Returns Promise<null | IConversationMessage>

getMessages

Parameters

Returns Promise<IConversationMessage[]>

deleteMessage

Parameters

Returns Promise<boolean>

deleteMessagesForConversation

Parameters

Returns Promise<number>

getMessageCount

Parameters

Returns Promise<number>

getConversationTokenUsage

Parameters

Returns Promise<ITokenUsage>

Settings

Member Visibility

Theme

On This Page

`Optional` limit?: number

`Optional` offset?: number

`Optional` agentId?: string