Conversations

Chat applications need to persist messages and manage history across sessions. The SDK’s conversation system handles this automatically — when you send a message, it’s saved locally along with the response.

Persistence

The Portal API is stateless. It processes your request and returns a response, but doesn’t remember anything. The SDK bridges this gap by saving everything to a local WatermelonDB database in the browser. Messages survive page refreshes, conversation data never leaves the device unless you explicitly send it, and users control their own data.

Previous messages are included as context automatically when you send new messages, giving the AI awareness of the ongoing discussion. You can configure how many messages to include or disable history entirely for standalone requests.

Conversations can optionally belong to a project, letting users group related chats together.

Usage

The useChatStorage hook handles persistent conversations:

const {
  sendMessage,
  conversationId,
  createConversation,
  setConversationId,
  deleteConversation,
  getConversations,
} = useChatStorage({ database, getToken });

When you call sendMessage, the message is saved to the database first, then sent to the Portal API along with conversation history. The response streams back in real-time, and once complete, it’s saved locally. If the user cancels mid-stream, partial responses are still preserved.

The Chat with Storage tutorial walks through a complete implementation.

For simple one-off completions without persistence, use useChat instead.