Chat Memory

Use Spring AI chat memory with Oracle AI Database to persist conversation context for Spring chat applications.

Large language models do not retain previous interactions. Spring AI chat memory stores and retrieves selected conversation messages so an application can provide relevant context on later calls.

Contents

Understand Chat Memory and Chat History

Chat memory is the selected information that an application keeps available for model context during a conversation. Chat history is the complete record of all exchanged messages.

Use ChatMemory for the subset of messages that the model needs in the current prompt. Use a separate persistence design when your application must retain a complete audit history of every message.

Spring AI separates these responsibilities:

Use Auto-Configured Chat Memory

Spring AI can auto-configure a ChatMemory bean for your application.

@Autowired
ChatMemory chatMemory;

By default, Spring AI uses MessageWindowChatMemory with InMemoryChatMemoryRepository. If a supported persistent repository is configured, Spring AI uses that repository instead.

Note: In-memory chat memory does not survive application restarts. Use JDBC-backed memory when conversation context must persist.

Configure Message Window Memory

Use MessageWindowChatMemory to keep the most recent messages in each conversation.

ChatMemory memory = MessageWindowChatMemory.builder()
    .maxMessages(10)
    .build();

The default message window size is 20 messages. When the number of messages exceeds the configured maximum, older messages are removed while system messages remain available.

Persist Memory with JDBC

Use JdbcChatMemoryRepository to persist chat memory in Oracle AI Database through JDBC.

Add the JDBC chat memory repository starter to your Maven build.

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-starter-model-chat-memory-repository-jdbc</artifactId>
</dependency>

For Gradle, add the starter as an implementation dependency.

dependencies {
    implementation 'org.springframework.ai:spring-ai-starter-model-chat-memory-repository-jdbc'
}

Configure the Oracle JDBC data source in application.yml.

spring:
  datasource:
    url: jdbc:oracle:thin:@//localhost:1521/freepdb1
    username: mlops
    password: mlops
  ai:
    chat:
      memory:
        repository:
          jdbc:
            initialize-schema: always

Autowire the JDBC repository and use it with MessageWindowChatMemory.

@Autowired
JdbcChatMemoryRepository chatMemoryRepository;

ChatMemory chatMemory = MessageWindowChatMemory.builder()
    .chatMemoryRepository(chatMemoryRepository)
    .maxMessages(10)
    .build();

JdbcChatMemoryRepository retrieves messages from oldest to newest, which is the expected order for model conversation context.

Configure JDBC Schema Initialization

Spring AI can initialize the SPRING_AI_CHAT_MEMORY table on application startup. For external databases such as Oracle AI Database, set schema initialization explicitly.

Property Description Default
spring.ai.chat.memory.repository.jdbc.initialize-schema Controls schema initialization. Use embedded, always, or never. embedded
spring.ai.chat.memory.repository.jdbc.schema Schema script location. Supports classpath: URLs and platform placeholders. classpath:org/springframework/ai/chat/memory/repository/jdbc/schema-@@platform@@.sql
spring.ai.chat.memory.repository.jdbc.platform Platform name to use when the schema location contains the @@platform@@ placeholder. Auto-detected

Use always for local development when the application should create the table. Use never when Flyway, Liquibase, or another migration process owns schema changes.

spring.ai.chat.memory.repository.jdbc.initialize-schema=always

To use a custom schema script, set the schema property.

spring.ai.chat.memory.repository.jdbc.schema=classpath:/custom/path/schema-oracle.sql

Spring AI supports Oracle Database through the JDBC chat memory repository dialect abstraction. The dialect can be auto-detected from the JDBC URL.

Use Memory with ChatClient

Use MessageChatMemoryAdvisor when a ChatClient must include conversation memory in later model calls.

ChatMemory chatMemory = MessageWindowChatMemory.builder().build();

ChatClient chatClient = ChatClient.builder(chatModel)
    .defaultAdvisors(MessageChatMemoryAdvisor.builder(chatMemory).build())
    .build();

Pass ChatMemory.CONVERSATION_ID on each call that uses a memory advisor.

String conversationId = "007";

String content = chatClient.prompt()
    .user("Do I have license to code?")
    .advisors(a -> a.param(ChatMemory.CONVERSATION_ID, conversationId))
    .call()
    .content();

The conversation ID identifies which messages belong to the same conversation. Calls that omit this parameter fail at run time.

Use Memory with ChatModel

When you call a ChatModel directly, add user and assistant messages to memory yourself.

ChatMemory chatMemory = MessageWindowChatMemory.builder().build();
String conversationId = "007";

UserMessage userMessage1 = new UserMessage("My name is James Bond");
chatMemory.add(conversationId, userMessage1);
ChatResponse response1 = chatModel.call(new Prompt(chatMemory.get(conversationId)));
chatMemory.add(conversationId, response1.getResult().getOutput());

UserMessage userMessage2 = new UserMessage("What is my name?");
chatMemory.add(conversationId, userMessage2);
ChatResponse response2 = chatModel.call(new Prompt(chatMemory.get(conversationId)));
chatMemory.add(conversationId, response2.getResult().getOutput());

Use this approach when the application needs direct control over message insertion and retrieval.

Choose a Memory Advisor

Spring AI provides advisors for different chat memory patterns.

Advisor Use
MessageChatMemoryAdvisor Passes conversation history as message objects. Use this advisor for most chat memory workflows.
PromptChatMemoryAdvisor Deprecated since Spring AI 1.1.3. Migrate to MessageChatMemoryAdvisor.
VectorStoreChatMemoryAdvisor Retrieves memory from a VectorStore and appends it to the system message for long-term memory patterns.

VectorStoreChatMemoryAdvisor can use the Oracle vector store when conversation memory must be retrieved semantically. For tool-enabled agents, prefer typed message memory with MessageChatMemoryAdvisor when possible.

Review Reference Links