Introduce first-class chat memory support

- ChatMemory will become a generic interface to implement different memory management strategies. It’s been moved from the “”spring-ai-client-chat” package to “spring-ai-model” package while retaining the same package, so it’s transparent to users.
- A MessageWindowChatMemory has been introduced to provide support for a chat memory that keeps at most N messages in the memory.

- A MessageWindowProcessingPolicy API has been introduced to customise the processing policy for the message window. A default implementation is provided out-of-the-box.
- A ChatMemoryRepository interface has been introduced to support different storage strategies for the chat memory. It’s meant to be used as part of a ChatMemory implementation. This is different than before, where the storage-specific implementation was directly tied to the ChatMemory. This design is familiar to Spring users since it’s used already in the ecosystem. The goal was to use a programming model similar to Spring Session and Spring Data.
- The JdbcChatMemory has been supersed by JdbcChatMemoryRepository.
- The ChatClient now supports memory as a first-class citizen, superseding the need for an Advisor to manage the chat memory. It also simplifies providing a conversationId. This feature lays the foundation for including the intermediate messages in tool calling in the memory as well.
- All the changes introduced in this PR are backword-compatible.

Signed-off-by: Thomas Vitale <[email protected]>

Author: ThomasVitale

auto-configurations/models/chat/memory/spring-ai-autoconfigure-model-chat-memory-jdbc/src/main/java/org/springframework/ai/model/chat/memory/jdbc/autoconfigure/JdbcChatMemoryAutoConfiguration.java

@@ -23,6 +23,7 @@
 
 import org.springframework.ai.chat.memory.jdbc.JdbcChatMemory;
 import org.springframework.ai.chat.memory.jdbc.JdbcChatMemoryConfig;
+import org.springframework.ai.chat.memory.jdbc.JdbcChatMemoryRepository;
 import org.springframework.boot.autoconfigure.AutoConfiguration;
 import org.springframework.boot.autoconfigure.condition.ConditionalOnClass;
 import org.springframework.boot.autoconfigure.condition.ConditionalOnMissingBean;
@@ -35,6 +36,7 @@
 
 /**
  * @author Jonathan Leijendekker
+ * @author Thomas Vitale
  * @since 1.0.0
  */
 @AutoConfiguration(after = JdbcTemplateAutoConfiguration.class)
@@ -46,19 +48,30 @@ public class JdbcChatMemoryAutoConfiguration {
 
 	@Bean
 	@ConditionalOnMissingBean
-	public JdbcChatMemory chatMemory(JdbcTemplate jdbcTemplate) {
+	JdbcChatMemoryRepository jdbcChatMemoryRepository(JdbcTemplate jdbcTemplate) {
 		var config = JdbcChatMemoryConfig.builder().jdbcTemplate(jdbcTemplate).build();
+		return JdbcChatMemoryRepository.create(config);
+	}
 
+	/**
+	 * @deprecated in favor of providing ChatClient directly a
+	 * {@link org.springframework.ai.chat.memory.MessageWindowChatMemory} with a
+	 * {@link JdbcChatMemoryRepository} instance.
+	 */
+	@Bean
+	@ConditionalOnMissingBean
+	@Deprecated
+	JdbcChatMemory chatMemory(JdbcTemplate jdbcTemplate) {
+		var config = JdbcChatMemoryConfig.builder().jdbcTemplate(jdbcTemplate).build();
 		return JdbcChatMemory.create(config);
 	}
 
 	@Bean
 	@ConditionalOnMissingBean
 	@ConditionalOnProperty(value = "spring.ai.chat.memory.jdbc.initialize-schema", havingValue = "true",
 			matchIfMissing = true)
-	public DataSourceScriptDatabaseInitializer jdbcChatMemoryScriptDatabaseInitializer(DataSource dataSource) {
+	DataSourceScriptDatabaseInitializer jdbcChatMemoryScriptDatabaseInitializer(DataSource dataSource) {
 		logger.debug("Initializing JdbcChatMemory schema");
-
 		return new JdbcChatMemoryDataSourceScriptDatabaseInitializer(dataSource);
 	}
 

auto-configurations/models/chat/memory/spring-ai-autoconfigure-model-chat-memory-jdbc/src/test/java/org/springframework/ai/model/chat/memory/jdbc/autoconfigure/JdbcChatMemoryAutoConfigurationIT.java

@@ -26,6 +26,7 @@
 import org.testcontainers.utility.DockerImageName;
 
 import org.springframework.ai.chat.memory.jdbc.JdbcChatMemory;
+import org.springframework.ai.chat.memory.jdbc.JdbcChatMemoryRepository;
 import org.springframework.ai.chat.messages.AssistantMessage;
 import org.springframework.ai.chat.messages.Message;
 import org.springframework.ai.chat.messages.UserMessage;
@@ -38,6 +39,7 @@
 
 /**
  * @author Jonathan Leijendekker
+ * @author Thomas Vitale
  */
 @Testcontainers
 class JdbcChatMemoryAutoConfigurationIT {
@@ -96,4 +98,30 @@ void addGetAndClear_shouldAllExecute() {
 		});
 	}
 
+	@Test
+	void useAutoConfiguredJdbcChatMemoryRepository() {
+		this.contextRunner.withPropertyValues("spring.ai.chat.memory.jdbc.initialize-schema=true").run(context -> {
+			var chatMemoryRepository = context.getBean(JdbcChatMemoryRepository.class);
+			var conversationId = UUID.randomUUID().toString();
+			var userMessage = new UserMessage("Message from the user");
+
+			chatMemoryRepository.save(conversationId, List.of(userMessage));
+
+			assertThat(chatMemoryRepository.findById(conversationId)).hasSize(1);
+			assertThat(chatMemoryRepository.findById(conversationId)).isEqualTo(List.of(userMessage));
+
+			chatMemoryRepository.deleteById(conversationId);
+
+			assertThat(chatMemoryRepository.findById(conversationId)).isEmpty();
+
+			var multipleMessages = List.<Message>of(new UserMessage("Message from the user 1"),
+					new AssistantMessage("Message from the assistant 1"));
+
+			chatMemoryRepository.save(conversationId, multipleMessages);
+
+			assertThat(chatMemoryRepository.findById(conversationId)).hasSize(multipleMessages.size());
+			assertThat(chatMemoryRepository.findById(conversationId)).isEqualTo(multipleMessages);
+		});
+	}
+
 }

memory/spring-ai-model-chat-memory-jdbc/src/main/java/org/springframework/ai/chat/memory/jdbc/JdbcChatMemory.java

@@ -38,7 +38,11 @@
  *
  * @author Jonathan Leijendekker
  * @since 1.0.0
+ * @deprecated in favor of providing ChatClient directly a
+ * {@link org.springframework.ai.chat.memory.MessageWindowChatMemory} with a
+ * {@link JdbcChatMemoryRepository} instance.
  */
+@Deprecated
 public class JdbcChatMemory implements ChatMemory {
 
 	private static final String QUERY_ADD = """

memory/spring-ai-model-chat-memory-jdbc/src/main/java/org/springframework/ai/chat/memory/jdbc/JdbcChatMemoryConfig.java

@@ -20,7 +20,7 @@
 import org.springframework.util.Assert;
 
 /**
- * Configuration for {@link JdbcChatMemory}.
+ * Configuration for {@link JdbcChatMemoryRepository}.
  *
  * @author Jonathan Leijendekker
  * @since 1.0.0

memory/spring-ai-model-chat-memory-jdbc/src/main/java/org/springframework/ai/chat/memory/jdbc/JdbcChatMemoryRepository.java

@@ -0,0 +1,115 @@
+/*
+ * Copyright 2023-2025 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.springframework.ai.chat.memory.jdbc;
+
+import org.springframework.ai.chat.memory.ChatMemoryRepository;
+import org.springframework.ai.chat.messages.*;
+import org.springframework.jdbc.core.BatchPreparedStatementSetter;
+import org.springframework.jdbc.core.JdbcTemplate;
+import org.springframework.jdbc.core.RowMapper;
+import org.springframework.lang.Nullable;
+import org.springframework.util.Assert;
+
+import java.sql.PreparedStatement;
+import java.sql.ResultSet;
+import java.sql.SQLException;
+import java.util.List;
+
+/**
+ * An implementation of {@link ChatMemoryRepository} for JDBC.
+ *
+ * @author Jonathan Leijendekker
+ * @author Thomas Vitale
+ * @since 1.0.0
+ */
+public class JdbcChatMemoryRepository implements ChatMemoryRepository {
+
+	private static final String QUERY_ADD = """
+			INSERT INTO ai_chat_memory (conversation_id, content, type) VALUES (?, ?, ?)""";
+
+	private static final String QUERY_GET = """
+			SELECT content, type FROM ai_chat_memory WHERE conversation_id = ? ORDER BY "timestamp" DESC""";
+
+	private static final String QUERY_CLEAR = "DELETE FROM ai_chat_memory WHERE conversation_id = ?";
+
+	private final JdbcTemplate jdbcTemplate;
+
+	private JdbcChatMemoryRepository(JdbcChatMemoryConfig config) {
+		Assert.notNull(config, "config cannot be null");
+		this.jdbcTemplate = config.getJdbcTemplate();
+	}
+
+	public static JdbcChatMemoryRepository create(JdbcChatMemoryConfig config) {
+		return new JdbcChatMemoryRepository(config);
+	}
+
+	@Override
+	public List<Message> findById(String conversationId) {
+		Assert.hasText(conversationId, "conversationId cannot be null or empty");
+		return this.jdbcTemplate.query(QUERY_GET, new MessageRowMapper(), conversationId);
+	}
+
+	@Override
+	public void save(String conversationId, List<Message> messages) {
+		Assert.hasText(conversationId, "conversationId cannot be null or empty");
+		Assert.notNull(messages, "messages cannot be null");
+		Assert.noNullElements(messages, "messages cannot contain null elements");
+		this.jdbcTemplate.batchUpdate(QUERY_ADD, new AddBatchPreparedStatement(conversationId, messages));
+	}
+
+	@Override
+	public void deleteById(String conversationId) {
+		Assert.hasText(conversationId, "conversationId cannot be null or empty");
+		this.jdbcTemplate.update(QUERY_CLEAR, conversationId);
+	}
+
+	private record AddBatchPreparedStatement(String conversationId,
+			List<Message> messages) implements BatchPreparedStatementSetter {
+		@Override
+		public void setValues(PreparedStatement ps, int i) throws SQLException {
+			var message = this.messages.get(i);
+
+			ps.setString(1, this.conversationId);
+			ps.setString(2, message.getText());
+			ps.setString(3, message.getMessageType().name());
+		}
+
+		@Override
+		public int getBatchSize() {
+			return this.messages.size();
+		}
+	}
+
+	private static class MessageRowMapper implements RowMapper<Message> {
+
+		@Override
+		@Nullable
+		public Message mapRow(ResultSet rs, int i) throws SQLException {
+			var content = rs.getString(1);
+			var type = MessageType.valueOf(rs.getString(2));
+
+			return switch (type) {
+				case USER -> new UserMessage(content);
+				case ASSISTANT -> new AssistantMessage(content);
+				case SYSTEM -> new SystemMessage(content);
+				case TOOL -> null;
+			};
+		}
+
+	}
+
+}

memory/spring-ai-model-chat-memory-jdbc/src/main/java/org/springframework/ai/chat/memory/jdbc/aot/hint/JdbcChatMemoryRuntimeHints.java renamed to memory/spring-ai-model-chat-memory-jdbc/src/main/java/org/springframework/ai/chat/memory/jdbc/aot/hint/JdbcChatMemoryRepositoryRuntimeHints.java

@@ -27,7 +27,7 @@
  *
  * @author Jonathan Leijendekker
  */
-class JdbcChatMemoryRuntimeHints implements RuntimeHintsRegistrar {
+class JdbcChatMemoryRepositoryRuntimeHints implements RuntimeHintsRegistrar {
 
 	@Override
 	public void registerHints(RuntimeHints hints, ClassLoader classLoader) {

memory/spring-ai-model-chat-memory-jdbc/src/main/java/org/springframework/ai/chat/memory/jdbc/package-info.java

@@ -0,0 +1,22 @@
+/*
+ * Copyright 2023-2025 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+@NonNullApi
+@NonNullFields
+package org.springframework.ai.chat.memory.jdbc;
+
+import org.springframework.lang.NonNullApi;
+import org.springframework.lang.NonNullFields;

memory/spring-ai-model-chat-memory-jdbc/src/main/resources/META-INF/spring/aot.factories

@@ -1,2 +1,2 @@
 org.springframework.aot.hint.RuntimeHintsRegistrar=\
-org.springframework.ai.chat.memory.jdbc.aot.hint.JdbcChatMemoryRuntimeHints
+org.springframework.ai.chat.memory.jdbc.aot.hint.JdbcChatMemoryRepositoryRuntimeHints