Interface IStorageAdapter

Initializes the storage adapter.

This should:

• Establish database connections
• Create necessary tables/schemas if they don't exist
• Run migrations if needed
• Validate configuration

Must be called before any other methods.

Throws

If initialization fails (connection errors, invalid config, etc.)

Example

const storage = new SqlStorageAdapter(config);
await storage.initialize(); // Sets up database schema
Copy

Closes the storage adapter and releases resources.

This should:

• Close database connections
• Flush any pending writes
• Clean up temporary resources

Call during application shutdown for graceful cleanup.

Example

process.on('SIGTERM', async () => {
  await storage.close();
  process.exit(0);
});
Copy

Creates a new conversation record.

Throws

If conversation with same ID already exists or validation fails

Example

const conversation = await storage.createConversation({
  id: uuidv4(),
  userId: 'user-123',
  agentId: 'agent-coding',
  createdAt: Date.now(),
  lastActivity: Date.now(),
  title: 'New coding project'
});
Copy

Retrieves a conversation by its ID.

Example

const conv = await storage.getConversation('conv-123');
if (conv) {
  console.log('Found:', conv.title);
}
Copy

Updates an existing conversation's metadata.

Only provided fields will be updated. Omitted fields remain unchanged.

Throws

If conversation doesn't exist

Example

// Update title and last activity
const updated = await storage.updateConversation('conv-123', {
  title: 'Renamed conversation',
  lastActivity: Date.now()
});
Copy

Deletes a conversation and all its messages.

Warning: This is a destructive operation that cannot be undone. Consider implementing soft deletes in production.

Example

const deleted = await storage.deleteConversation('conv-123');
if (deleted) {
  console.log('Conversation deleted successfully');
}
Copy

Lists all conversations for a specific user.

Results are typically ordered by lastActivity (most recent first).

Example

// Get user's 20 most recent conversations
const conversations = await storage.listConversations('user-123', {
  limit: 20
});

// Get conversations for specific agent
const codingConvs = await storage.listConversations('user-123', {
  agentId: 'agent-coding'
});
Copy

Stores a new message in a conversation.

Note: This also updates the parent conversation's lastActivity timestamp.

Throws

If conversation doesn't exist or validation fails

Example

await storage.storeMessage({
  id: uuidv4(),
  conversationId: 'conv-123',
  role: 'user',
  content: 'Explain async/await',
  timestamp: Date.now()
});
Copy

Retrieves a single message by its ID.

Example

const msg = await storage.getMessage('msg-456');
if (msg) {
  console.log(`[${msg.role}]: ${msg.content}`);
}
Copy

Retrieves all messages for a conversation with optional filtering.

This is the primary method for loading conversation history.

Example

// Get all messages (oldest first)
const allMessages = await storage.getMessages('conv-123');

// Get last 50 messages (newest first)
const recent = await storage.getMessages('conv-123', {
  limit: 50,
  order: 'desc'
});

// Get only assistant responses from last hour
const assistantRecent = await storage.getMessages('conv-123', {
  roles: ['assistant'],
  since: Date.now() - 3600000
});
Copy

Deletes a specific message.

Note: This does NOT update the conversation's lastActivity timestamp.

Example

const deleted = await storage.deleteMessage('msg-456');
Copy

Deletes all messages in a conversation.

Warning: Destructive operation. Consider soft deletes in production.

Example

const deletedCount = await storage.deleteMessagesForConversation('conv-123');
console.log(`Deleted ${deletedCount} messages`);
Copy

Counts total messages in a conversation.

Useful for pagination and UI indicators.

Example

const count = await storage.getMessageCount('conv-123');
console.log(`This conversation has ${count} messages`);
Copy

Calculates total token usage for a conversation.

Sums up all message usage statistics.

Example

const usage = await storage.getConversationTokenUsage('conv-123');
console.log(`Total tokens: ${usage.totalTokens}`);
console.log(`Cost estimate: $${usage.totalTokens * 0.00001}`);
Copy