Docs: MongoChatmemoryRepository message ordering

ilayaperumalg · ilayaperumalg · commit dbde175a2cec · 2026-01-28T10:49:25.000Z
- Update upgrade notes
 - Fix MongoChatMemoryRepositoryIT to include DataMongoAutoConfiguration
 - Fix the chat memory docs to explicitly specify the message ordering

Signed-off-by: Ilayaperumal Gopinathan &lt;ilayaperumal.gopinathan@broadcom.com&gt;
diff --git a/memory/repository/spring-ai-model-chat-memory-repository-mongodb/src/test/java/org/springframework/ai/chat/memory/repository/mongo/MongoChatMemoryRepositoryIT.java b/memory/repository/spring-ai-model-chat-memory-repository-mongodb/src/test/java/org/springframework/ai/chat/memory/repository/mongo/MongoChatMemoryRepositoryIT.java
@@ -34,6 +34,7 @@
 import org.springframework.beans.factory.annotation.Autowired;
 import org.springframework.boot.SpringBootConfiguration;
 import org.springframework.boot.autoconfigure.ImportAutoConfiguration;
+import org.springframework.boot.data.mongodb.autoconfigure.DataMongoAutoConfiguration;
 import org.springframework.boot.mongodb.autoconfigure.MongoAutoConfiguration;
 import org.springframework.boot.test.context.SpringBootTest;
 import org.springframework.boot.testcontainers.service.connection.ServiceConnection;
@@ -155,7 +156,7 @@ void deleteMessagesByConversationId() {
 	}
 
 	@SpringBootConfiguration
-	@ImportAutoConfiguration({ MongoAutoConfiguration.class })
+	@ImportAutoConfiguration({ MongoAutoConfiguration.class, DataMongoAutoConfiguration.class })
 	static class TestConfiguration {
 
 		@Bean
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
@@ -68,6 +68,8 @@ ChatMemoryRepository repository = new InMemoryChatMemoryRepository();
 
 `JdbcChatMemoryRepository` is a built-in implementation that uses JDBC to store messages in a relational database. It supports multiple databases out-of-the-box and is suitable for applications that require persistent storage of chat memory.
 
+Messages are retrieved in ascending timestamp order (oldest-to-newest), which is the expected format for LLM conversation history.
+
 First, add the following dependency to your project:
 
 [tabs]
@@ -181,6 +183,8 @@ ChatMemoryRepository chatMemoryRepository = JdbcChatMemoryRepository.builder()
 
 `CassandraChatMemoryRepository` has a time-series schema, keeping record of all past chat windows, valuable for governance and auditing.  Setting time-to-live to some value, for example three years, is recommended.
 
+Messages are retrieved in ascending timestamp order (oldest-to-newest), which is the expected format for LLM conversation history.
+
 To use `CassandraChatMemoryRepository` first, add the dependency to your project:
 
 [tabs]
@@ -256,6 +260,8 @@ You can disable the schema initialization by setting the property `spring.ai.cha
 
 `Neo4jChatMemoryRepository` is a built-in implementation that uses Neo4j to store chat messages as nodes and relationships in a property graph database. It is suitable for applications that want to leverage Neo4j's graph capabilities for chat memory persistence.
 
+Messages are retrieved in ascending message index order (oldest-to-newest), which is the expected format for LLM conversation history.
+
 First, add the following dependency to your project:
 
 [tabs]
@@ -328,6 +334,8 @@ The Neo4j repository will automatically ensure that indexes are created for conv
 
 `CosmosDBChatMemoryRepository` is a built-in implementation that uses Azure Cosmos DB NoSQL API to store messages. It is suitable for applications that require a globally distributed, highly scalable document database for chat memory persistence. The repository uses the conversation ID as the partition key to ensure efficient data distribution and fast retrieval.
 
+Messages are retrieved in ascending timestamp order (oldest-to-newest), which is the expected format for LLM conversation history.
+
 First, add the following dependency to your project:
 
 [tabs]
@@ -412,6 +420,8 @@ You can customize the database and container names using the configuration prope
 
 `MongoChatMemoryRepository` is a built-in implementation that uses MongoDB to store messages. It is suitable for applications that require a flexible, document-oriented database for chat memory persistence.
 
+Messages are retrieved in ascending timestamp order (oldest-to-newest), which is the expected format for LLM conversation history. This ordering is consistent across all chat memory repository implementations.
+
 First, add the following dependency to your project:
 
 [tabs]
@@ -484,6 +494,8 @@ It is suitable for applications that require high-performance, low-latency chat
 The repository stores messages as JSON documents and creates a search index for efficient querying.
 It also provides extended query capabilities through the `AdvancedRedisChatMemoryRepository` interface for searching messages by content, type, time range, and metadata.
 
+Messages are retrieved in ascending timestamp order (oldest-to-newest), which is the expected format for LLM conversation history.
+
 First, add the following dependency to your project:
 
 [tabs]
diff --git a/spring-ai-docs/src/main/antora/modules/ROOT/pages/upgrade-notes.adoc b/spring-ai-docs/src/main/antora/modules/ROOT/pages/upgrade-notes.adoc
@@ -4,6 +4,33 @@
 [[upgrading-to-2-0-0-M2]]
 == Upgrading to 2.0.0-M2
 
+=== Breaking Changes
+
+==== MongoDB Chat Memory Message Ordering Fixed
+
+The `MongoChatMemoryRepository` has been fixed to return messages in the order they were sent (oldest-to-newest), matching all other chat memory repository implementations. Previously, it incorrectly returned messages in reverse order (newest-to-oldest), which broke conversation flow for LLMs.
+
+===== Impact
+
+If your application was using `MongoChatMemoryRepository` and working around the incorrect ordering (e.g., by reversing messages after retrieval), you will need to remove that workaround.
+
+===== Migration
+
+Remove any code that reverses the message order after retrieving from MongoDB chat memory:
+
+[source,java]
+----
+// BEFORE (with workaround for bug):
+List<Message> messages = chatMemoryRepository.findByConversationId(conversationId);
+Collections.reverse(messages); // Remove this workaround
+
+// AFTER (correct ordering):
+List<Message> messages = chatMemoryRepository.findByConversationId(conversationId);
+// Messages are now correctly ordered chronologically
+----
+
+All chat memory repositories now consistently return messages in the order they were sent (oldest-to-newest), which is the expected format for LLM conversation history.
+
 === Development-time Services
 
 * Docker Compose and Testcontainers support for MongoDB Atlas is now provided natively by the Spring Boot MongoDB module. The migration should be transparent and not require any code change. Regarding dependencies, you don't need to import `org.springframework.ai:spring-ai-spring-boot-testcontainers` anymore. A dependency on `org.springframework.boot:spring-boot-testcontainers` is sufficient.
