Chat Memory Enhancements

* 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 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.
* A ChatMemory bean is auto-configured for you whenever using one of the Spring AI Model starters. By default, it uses the MessageWindowChatMemory implementation and stores the conversation history in memory. If a different repository is already configured (e.g., Cassandra, JDBC, or Neo4j), Spring AI will use that instead.
* First-class documentation has been introduced to describe the ChatMemory API and related features.
* All the changes introduced in this PR are backward-compatible.

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

Author: ThomasVitale

auto-configurations/models/chat/memory/spring-ai-autoconfigure-model-chat-memory-cassandra/pom.xml

@@ -30,6 +30,12 @@
 			<version>${project.parent.version}</version>
 		</dependency>
 
+		<dependency>
+			<groupId>org.springframework.ai</groupId>
+			<artifactId>spring-ai-autoconfigure-model-chat-memory</artifactId>
+			<version>${project.parent.version}</version>
+		</dependency>
+
 		<!-- Boot dependencies -->
 		<dependency>
 			<groupId>org.springframework.boot</groupId>

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

@@ -20,6 +20,7 @@
 
 import org.springframework.ai.chat.memory.cassandra.CassandraChatMemory;
 import org.springframework.ai.chat.memory.cassandra.CassandraChatMemoryConfig;
+import org.springframework.ai.model.chat.memory.autoconfigure.ChatMemoryAutoConfiguration;
 import org.springframework.boot.autoconfigure.AutoConfiguration;
 import org.springframework.boot.autoconfigure.cassandra.CassandraAutoConfiguration;
 import org.springframework.boot.autoconfigure.condition.ConditionalOnClass;
@@ -34,7 +35,7 @@
  * @author Jihoon Kim
  * @since 1.0.0
  */
-@AutoConfiguration(after = CassandraAutoConfiguration.class)
+@AutoConfiguration(after = CassandraAutoConfiguration.class, before = ChatMemoryAutoConfiguration.class)
 @ConditionalOnClass({ CassandraChatMemory.class, CqlSession.class })
 @EnableConfigurationProperties(CassandraChatMemoryProperties.class)
 public class CassandraChatMemoryAutoConfiguration {

auto-configurations/models/chat/memory/spring-ai-autoconfigure-model-chat-memory-jdbc/pom.xml

@@ -29,6 +29,12 @@
 			<version>${project.parent.version}</version>
 		</dependency>
 
+		<dependency>
+			<groupId>org.springframework.ai</groupId>
+			<artifactId>spring-ai-autoconfigure-model-chat-memory</artifactId>
+			<version>${project.parent.version}</version>
+		</dependency>
+
 		<!-- Boot dependencies -->
 		<dependency>
 			<groupId>org.springframework.boot</groupId>

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

@@ -21,45 +21,93 @@
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 
+import org.springframework.ai.chat.memory.ChatMemory;
+import org.springframework.ai.chat.memory.MessageWindowChatMemory;
 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.ai.model.chat.memory.autoconfigure.ChatMemoryAutoConfiguration;
 import org.springframework.boot.autoconfigure.AutoConfiguration;
 import org.springframework.boot.autoconfigure.condition.ConditionalOnClass;
 import org.springframework.boot.autoconfigure.condition.ConditionalOnMissingBean;
-import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
+import org.springframework.boot.autoconfigure.condition.ConditionMessage;
+import org.springframework.boot.autoconfigure.condition.ConditionOutcome;
+import org.springframework.boot.autoconfigure.condition.SpringBootCondition;
 import org.springframework.boot.autoconfigure.jdbc.JdbcTemplateAutoConfiguration;
 import org.springframework.boot.context.properties.EnableConfigurationProperties;
-import org.springframework.boot.jdbc.init.DataSourceScriptDatabaseInitializer;
 import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.ConditionContext;
+import org.springframework.context.annotation.Conditional;
+import org.springframework.core.type.AnnotatedTypeMetadata;
 import org.springframework.jdbc.core.JdbcTemplate;
 
 /**
  * @author Jonathan Leijendekker
+ * @author Thomas Vitale
  * @since 1.0.0
  */
-@AutoConfiguration(after = JdbcTemplateAutoConfiguration.class)
-@ConditionalOnClass({ JdbcChatMemory.class, DataSource.class, JdbcTemplate.class })
+@AutoConfiguration(after = JdbcTemplateAutoConfiguration.class, before = ChatMemoryAutoConfiguration.class)
+@ConditionalOnClass({ JdbcChatMemoryRepository.class, DataSource.class, JdbcTemplate.class })
 @EnableConfigurationProperties(JdbcChatMemoryProperties.class)
 public class JdbcChatMemoryAutoConfiguration {
 
 	private static final Logger logger = LoggerFactory.getLogger(JdbcChatMemoryAutoConfiguration.class);
 
 	@Bean
 	@ConditionalOnMissingBean
-	public JdbcChatMemory chatMemory(JdbcTemplate jdbcTemplate) {
-		var config = JdbcChatMemoryConfig.builder().jdbcTemplate(jdbcTemplate).build();
+	JdbcChatMemoryRepository chatMemoryRepository(JdbcTemplate jdbcTemplate) {
+		return JdbcChatMemoryRepository.builder().jdbcTemplate(jdbcTemplate).build();
+	}
 
+	/**
+	 * @deprecated in favor of building a {@link MessageWindowChatMemory} (or other
+	 * {@link ChatMemory} implementations) 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) {
-		logger.debug("Initializing JdbcChatMemory schema");
-
+	@Conditional(OnSchemaInitializationEnabledCondition.class)
+	JdbcChatMemoryDataSourceScriptDatabaseInitializer jdbcChatMemoryScriptDatabaseInitializer(DataSource dataSource) {
+		logger.debug("Initializing schema for JdbcChatMemoryRepository");
 		return new JdbcChatMemoryDataSourceScriptDatabaseInitializer(dataSource);
 	}
 
+	/**
+	 * Condition to check if the schema initialization is enabled, supporting both
+	 * deprecated and new property.
+	 *
+	 * @deprecated to be removed in 1.0.0-RC1.
+	 */
+	@Deprecated
+	static class OnSchemaInitializationEnabledCondition extends SpringBootCondition {
+
+		@Override
+		public ConditionOutcome getMatchOutcome(ConditionContext context, AnnotatedTypeMetadata metadata) {
+			Boolean initializeSchemaEnabled = context.getEnvironment()
+				.getProperty("spring.ai.chat.memory.jdbc.initialize-schema", Boolean.class);
+
+			if (initializeSchemaEnabled != null) {
+				return new ConditionOutcome(initializeSchemaEnabled,
+						ConditionMessage.forCondition("Enable JDBC Chat Memory Schema Initialization")
+							.because("spring.ai.chat.memory.jdbc.initialize-schema is " + initializeSchemaEnabled));
+			}
+
+			initializeSchemaEnabled = context.getEnvironment()
+				.getProperty(JdbcChatMemoryProperties.CONFIG_PREFIX + ".initialize-schema", Boolean.class, true);
+
+			return new ConditionOutcome(initializeSchemaEnabled, ConditionMessage
+				.forCondition("Enable JDBC Chat Memory Schema Initialization")
+				.because(JdbcChatMemoryProperties.CONFIG_PREFIX + ".initialize-schema is " + initializeSchemaEnabled));
+		}
+
+	}
+
 }

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

@@ -25,6 +25,11 @@
 import org.springframework.boot.sql.init.DatabaseInitializationMode;
 import org.springframework.boot.sql.init.DatabaseInitializationSettings;
 
+/**
+ * Performs database initialization for the JDBC Chat Memory Repository.
+ *
+ * @since 1.0.0
+ */
 class JdbcChatMemoryDataSourceScriptDatabaseInitializer extends DataSourceScriptDatabaseInitializer {
 
 	private static final String SCHEMA_LOCATION = "classpath:org/springframework/ai/chat/memory/jdbc/schema-@@platform@@.sql";

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

@@ -20,13 +20,17 @@
 
 /**
  * @author Jonathan Leijendekker
+ * @author Thomas Vitale
  * @since 1.0.0
  */
 @ConfigurationProperties(JdbcChatMemoryProperties.CONFIG_PREFIX)
 public class JdbcChatMemoryProperties {
 
-	public static final String CONFIG_PREFIX = "spring.ai.chat.memory.jdbc";
+	public static final String CONFIG_PREFIX = "spring.ai.chat.memory.repository.jdbc";
 
+	/**
+	 * Whether to initialize the schema on startup.
+	 */
 	private boolean initializeSchema = true;
 
 	public boolean isInitializeSchema() {

auto-configurations/models/chat/memory/spring-ai-autoconfigure-model-chat-memory-jdbc/src/main/resources/META-INF/additional-spring-configuration-metadata.json

@@ -0,0 +1,14 @@
+{
+  "groups": [],
+  "properties": [
+    {
+      "name": "spring.ai.chat.memory.jdbc.initialize-schema",
+      "type": "java.lang.Boolean",
+      "description": "Whether to initialize the schema on startup.",
+      "deprecation": {
+        "replacement": "spring.ai.chat.memory.repository.jdbc.initialize-schema"
+      }
+    }
+  ],
+  "hints": []
+}

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

@@ -35,7 +35,7 @@
  * @author Jonathan Leijendekker
  */
 @Testcontainers
-class JdbcChatMemoryDataSourceScriptDatabaseInitializerTests {
+class JdbcChatMemoryDataSourceScriptDatabaseInitializerPostgresqlTests {
 
 	static final DockerImageName DEFAULT_IMAGE_NAME = DockerImageName.parse("postgres:17");