diff --git a/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/chat-memory.adoc b/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/chat-memory.adoc index 828ce772bf..30967f28d9 100644 --- a/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/chat-memory.adoc +++ b/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/chat-memory.adoc @@ -24,6 +24,36 @@ ChatMemory chatMemory; The following sections will describe further the different memory types and repositories available in Spring AI. +== Working with Conversation IDs + +Every chat memory operation is keyed on a conversation ID. +The `ChatMemory` and `ChatMemoryRepository` abstractions use this identifier to decide which conversation to read, append to, or delete, and it must always be provided explicitly. + +The conversation ID is the only thing that scopes a conversation. +Messages are stored and retrieved for exactly the conversation ID that is supplied, so choosing how those IDs are assigned is what determines whether interactions are grouped together or kept apart. + +In a multi-user application, make the conversation ID unique per user (and per conversation, if a user can have more than one) so that each user's messages stay in their own conversation. +A common approach is to derive the ID on the server from the current user or session rather than using a fixed or shared value: + +[source,java] +---- +// Build the conversation ID from the current user/session so each +// user's messages are kept in their own conversation. +String conversationId = currentUser.getId() + ":" + httpSession.getId(); + +chatClient.prompt() + .user(userInput) + .advisors(a -> a.param(ChatMemory.CONVERSATION_ID, conversationId)) + .call() + .content(); +---- + +A few practices help keep conversations organized as an application grows: + +* Assign a distinct conversation ID per user, and per conversation when a single user can hold several. +* Derive the conversation ID on the server from the user or session rather than reusing a fixed value across users. +* When listing or deleting conversations, operate on the conversation IDs that belong to the current user rather than across all conversation IDs. + == Memory Types The `ChatMemory` abstraction allows you to implement various types of memory to suit different use cases. The choice of memory type can significantly impact the performance and behavior of your application. This section describes the built-in memory types provided by Spring AI and their characteristics.