Managing Multi-Turn Conversations

Introduction

In our last lesson, we established a system for short-term, single-request memory using a SharedState "blackboard" and an active memoryTool. While powerful, this memory is ephemeral—it vanishes the moment a request completes. For any meaningful, ongoing interaction with a user, this is a significant limitation.

Today, we will address this by implementing a persistent memory layer. This lesson focuses on the crucial next step: implementing conversation history storage and retrieval for multi-turn interactions. You will learn how to design a database schema to store conversations, and how to integrate this persistence layer into your application's lifecycle, enabling your agents to remember interactions across sessions. This moves us from single-transaction intelligence to building long-term contextual understanding, a cornerstone of your goal to create a production-grade agentic system.

The Shift from Stateless to Stateful Conversation

In our previous explorations, we've relied on a common pattern where the client maintains the full conversation history and sends it with every request. This is the simplest way to provide context to the LLM.

This client-managed, stateless server approach is excellent for prototypes but has two major drawbacks for a production system:

1. Lack of Persistence: If the user refreshes their browser, the entire context is lost.
2. Inefficiency: As the conversation grows, the JSON payload sent from the client to the server on every turn becomes increasingly large, adding network latency and cost.

The professional standard is to move this responsibility to the server. The server stores the authoritative conversation history, and the client simply references it using a unique identifier (a chatId or sessionId).

Your experience with databases like PostgreSQL makes you well-equipped for this task. We'll use a database to store chat messages, creating a stateful backend that can recall past interactions.

Designing the Persistence Schema

To store conversations effectively, we need a clear database schema. A conversation is a collection of messages, and each conversation should be distinct. This naturally leads to a relational model with two primary tables: Session (or Chat) and Message.

1. Session: Represents a single, continuous conversation. It primarily needs a unique id.
2. Message: Represents a single turn in a conversation. It contains the content, the role ('user' or 'assistant'), and a foreign key linking it back to its Session.

The Prisma documentation provides an excellent guide for creating such a schema, which is perfectly suited for our Node.js environment.

The resulting Message table in your database would look something like this:

Implementing the Persistence Flow: Saving and Loading

With our schema defined, we can now implement the two core operations: saving a new message and loading an existing conversation.

Saving the Conversation History

The Vercel AI SDK provides a clean and convenient hook for persisting data: the onFinish callback within streamText. This function is executed on the server after the AI model has finished generating its response, making it the perfect place to write the latest messages to our database.

Here is a conceptual summary of the server-side API route:

// app/api/chat/route.ts
import { openai } from '@ai-sdk/openai';
import { streamText, UIMessage } from 'ai';
import { saveChat } from '@/lib/save-chat'; // Our database logic

export async function POST(req: Request) {
  const { messages, id }: { messages: UIMessage[]; id: string } = await req.json();

  const result = streamText({
    model: openai('gpt-4o'),
    messages,
  });

  // The 'onFinish' callback is the key to persistence.
  // It runs after the stream is complete.
  return result.toUIMessageStreamResponse({
    onFinish: async ({ messages: finalMessages }) => {
      // `finalMessages` includes the user's prompt and the AI's full response.
      await saveChat(id, finalMessages);
    },
  });
}

The saveChat function, using Prisma, would handle the database interaction, ensuring the conversation is durably stored. This pattern is also endorsed in the official Vercel AI SDK documentation.

Loading the Conversation History

To achieve persistence, a returning user must be able to see their previous conversation. This "read" path is typically initiated by the client-side UI when the chat component loads. The client requests the history for a given chatId from a dedicated API endpoint.

The flow is straightforward:

1. The React chat component mounts.
2. A useEffect hook fires, making a GET request to an endpoint like /api/messages?chatId=....
3. The server-side endpoint queries the database for all messages associated with that chatId.
4. The messages are returned to the client.
5. The client uses the setMessages function from the useChat hook to populate the chat history, instantly displaying it to the user.

Production-Ready Considerations

While the above implementation is functional, your goal is a production-grade system. Here are three critical refinements to consider as you build out this feature.

1. Server-Side ID Generation: By default, the useChat hook generates message IDs on the client. For a persistent system, this is risky as it can lead to ID collisions. The server should be the source of truth. The AI SDK allows you to enforce this.

2. Performance Optimization: Sending the entire chat history from the client is inefficient. A better pattern is to send only the new message along with the chatId. The server is then responsible for loading the previous messages from the database, combining them with the new message, and then proceeding with the LLM call.

3. Handling Disconnects: What if the user closes their browser tab while the AI is generating a response? By default, the stream might be aborted, and the onFinish callback might not run. To ensure the full response is generated and saved regardless, you can use result.consumeStream().

Conclusion

In this lesson, you have bridged the gap between ephemeral, single-request context and durable, multi-turn memory. By moving state management from the client to the server and leveraging a database, you've laid the foundation for agents that can build relationships and maintain context over time.

Key Takeaways:

• For production systems, server-managed state is superior to client-managed state for persistence and efficiency.
• A relational database with Session and Message tables is a robust way to model and store conversation histories.
• The onFinish callback in the Vercel AI SDK's streamText function is the ideal server-side hook for saving conversation history after a response is generated.
• The "read" path involves a client-side useEffect hook that fetches history from a dedicated API endpoint to populate the UI on load.
• Production systems should eventually incorporate server-side ID generation, performance optimizations, and resilient stream handling.

You now have a mechanism to remember every turn of a conversation. However, as conversations grow longer, they will inevitably hit the token limits of AI models. In our next lesson, we will confront this challenge directly by learning to implement a token-aware truncation strategy to manage conversation history size, ensuring your agents can have long conversations without breaking.