[Spring AI 2025 Renewal #6] Chat Memory

안녕하세요 dev_writer입니다.
 
이번 시간에는 Spring AI 공식 문서 중 Chat Models에 대해 번역한 내용을 전달해 드리겠습니다.
 

Chat Memory

대형 언어 모델 (LLM)은 상태를 저장하지 않기 때문에 이전 상호작용에 대한 정보를 유지하지 않습니다. 이는 여러 상호작용에 걸쳐 문맥이나 상태를 유지하고자 할 때 한계가 될 수 있습니다. 이를 해결하기 위해 Spring AI는 여러 상호작용에 걸쳐 정보를 저장하고 불러올 수 있는 채팅 메모리 (chat memory) 기능을 제공합니다.
 
ChatMemory 추상화는 다양한 사용 사례를 지원하기 위해 여러 유형의 메모리를 구현할 수 있도록 합니다. 메시지의 실제 저장은 ChatMemoryRepository가 담당하며, 이 컴포넌트는 메시지를 저장하고 검색하는 역할만 합니다. 어떤 메시지를 유지하고 언제 제거할지는 ChatMemory 구현체가 결정합니다. 예를 들어, 최근 N개의 메시지만 유지하거나, 일정 시간 동안만 메시지를 유지하거나, 토큰 수 제한 내에서만 메시지를 유지하는 등의 전략이 가능합니다.
 
메모리 유형을 선택하기 전에 chat memory와 chat history의 차이를 이해하는 것이 중요합니다.

• Chat Memory: 대형 언어 모델이 대화를 통해 문맥 인식을 유지하기 위해 사용하는 정보입니다.
• Chat History: 사용자와 모델 간에 주고받은 전체 메시지 기록입니다.

ChatMemory 추상화는 대화의 현재 문맥에 관련된 메시지를 저장하고 검색하는데 중점을 둡니다. 하지만 전체 대화 기록을 저장하는 용도로는 적합하지 않습니다. 모든 메시지 기록을 완전히 보존할 필요가 있다면, Spring Data 등을 활용하여 효율적인 저장 및 조회가 가능한 별도의 접근 방식을 사용하는 것이 좋습니다.
 

빠른 시작

Spring AI는 애플리케이션에서 직접 사용할 수 있는 ChatMemory 빈을 자동 구성합니다. 기본적으로 InMemoryChatMemoryRepository를 사용하여 메시지를 저장하며, 대화 내역 관리를 위해 MessageWindowChatMemory 구현체를 사용합니다. 만약 Cassandra, JDBC, Neo4j 등 다른 저장소가 이미 구성되어 있다면, Spring AI는 해당 저장소를 대신 사용합니다.
 

@Autowired
ChatMemory chatMemory;

 
다음 섹션에서는 Spring AI에서 제공하는 다양한 메모리 유형과 저장소(repository)에 대해 더 자세히 설명합니다.
 

메모리 유형

ChatMemory 추상화는 다양한 사용 사례에 맞춰 여러 종류의 메모리를 구현할 수 있도록 지원합니다. 메모리 유형 선택은 애플리케이션의 성능과 동작에 큰 영향을 미칠 수 있습니다. 이 섹션에서는 Spring AI가 기본적으로 제공하는 메모리 유형들과 그 특성에 대해 설명합니다.
 

Message Window Chat Memory

MessageWindowChatMemory는 지정된 최대 개수만큼의 메시지를 유지하는 슬라이딩 윈도우 방식의 메모리입니다. 메시지 수가 최대치를 초과하면 오래된 메시지부터 제거되며, 시스템 메시지는 보존됩니다. 기본 최대 메시지 수는 20개입니다.
 

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

 
이 메모리 유형은 Spring AI가 ChatMemory 빈을 자동 구성할 때  사용하는 기본값입니다.
 

Memory Storage

Spring AI는 채팅 메모리를 저장하기 위한 ChatMemoryRepository 추상화를 제공합니다. 이 섹션에서는 Spring AI가 기본적으로 제공하는 저장소(repository)들과 그 사용 방법에 대해 설명하며, 필요에 따라 직접 저장소를 구현할 수도 있습니다.
 

인메모리 저장소 (In-Memory Repository)

InMemoryChatMemoryRepository는 ConcurrentHashMap을 사용하여 메시지를 메모리에 저장합니다.
 
기본적으로 다른 저장소가 구성되어 있지 않은 경우, Spring AI는 InMemoryChatMemoryRepository 타입의 ChatMemoryRepository 빈을 자동으로 구성하여 애플리케이션에서 직접 사용할 수 있도록 합니다.

@Autowired
ChatMemoryRepository chatMemoryRepository;

 
만약 InMemoryChatMemoryRepository를 수동으로 생성하고 싶다면, 다음과 같이 구성할 수 있습니다.

ChatMemoryRepository repository = new InMemoryChatMemoryRepository();

 

JDBC 저장소 (JdbcChatMemoryRepository)

JdbcChatMemoryRepository는 메시지를 관계형 데이터베이스에 저장하기 위해 JDBC를 사용하는 기본 구현체입니다. 여러 데이터베이스를 기본적으로 지원하며, 채팅 메모리를 영구적으로 저장해야 하는 애플리케이션에 적합합니다.
 
먼저, 프로젝트에 다음 의존성을 추가하십시오:
 

Maven

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

 

Gradle

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

 
Spring AI는 JdbcChatMemoryRepository에 대한 자동 구성 (auto-configuration)을 제공하므로, 이를 애플리케이션에서 바로 사용할 수 있습니다.

@Autowired
JdbcChatMemoryRepository chatMemoryRepository;

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

 
직접 JdbcChatMemoryRepository를 사용하고 싶다면, JdbcTemplate 인스턴스와 JdbcChatMemoryRepositoryDialect를 제공하여 수동으로 구성할 수도 있습니다.

ChatMemoryRepository chatMemoryRepository = JdbcChatMemoryRepository.builder()
    .jdbcTemplate(jdbcTemplate)
    .dialect(new PostgresChatMemoryDialect())
    .build();

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

 

지원되는 데이터베이스 및 Dialect 추상화

Spring AI는 dialect 추상화를 통해 여러 관계형 데이터베이스를 지원합니다. 다음 데이터베이스들은 기본적으로 지원됩니다:

• PostgreSQL
• MySQL / MariaDB
• SQL Server
• HSQLDB

JdbcChatMemoryRepositoryDialect.from(DataSource)를 사용할 경우, JDBC URL을 기반으로 올바른 dialect가 자동 감지됩니다. 다른 데이터베이스에 대한 지원을 확장하려면 JdbcChatMemoryRepositoryDialect 인터페이스를 구현하면 됩니다.
 

설정 속성

속성	설명	기본값
spring.ai.chat.memory.repository.jdbc.initialize-schema	스키마 초기화 시점을 제어합니다. 가능한 값: embedded(기본값), always, never	embedded
spring.ai.chat.memory.repository.jdbc.schema	초기화 시 사용할 스키마 스크립트의 위치입니다. classpath: URL과 @@platform@@ 플레이스홀더를 지원합니다.	classpath:org/springframework/ai/chat/memory/repository/jdbc/schema-@@platform@@.sql
spring.ai.chat.memory.repository.jdbc.platform	@@platform@@ 플레이스홀더가 사용될 경우 초기화 스크립트에서 사용할 플랫폼 이름입니다.	자동 감지됨

 

스키마 초기화

자동 구성(auto-configuration)은 애플리케이션 시작 시 데이터베이스 벤더에 맞는 SQL 스크립트를 사용하여 SPRING_AI_CHAT_MEMORY 테이블을 자동으로 생성합니다. 기본적으로 스키마 초기화는 내장형 데이터베이스(H2, HSQL, Derby 등)에 대해서만 실행됩니다.
 
스키마 초기화 동작은 spring.ai.chat.memory.repository.jdbc.initialize-schema 속성을 통해 제어할 수 있습니다.

spring.ai.chat.memory.repository.jdbc.initialize-schema=embedded # Only for embedded DBs (default)
spring.ai.chat.memory.repository.jdbc.initialize-schema=always   # Always initialize
spring.ai.chat.memory.repository.jdbc.initialize-schema=never    # Never initialize (useful with Flyway/Liquibase)

 
스키마 스크립트의 위치를 재정의하려면 다음 속성을 사용하십시오:

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

 

Dialect 확장

새로운 데이터베이스를 지원하려면 JdbcChatMemoryRepositoryDialect 인터페이스를 구현하고, 메시지를 조회(select), 삽입(insert), 삭제(delete) 하기 위한 SQL을 제공해야 합니다. 이후 해당 사용자 정의 dialect를 리포지터리 빌더에 전달하면 됩니다.

ChatMemoryRepository chatMemoryRepository = JdbcChatMemoryRepository.builder()
    .jdbcTemplate(jdbcTemplate)
    .dialect(new MyCustomDbDialect())
    .build();

 

CassandraChatMemoryRepository

CassandraChatMemoryRepository는 Apache Cassandra를 사용하여 메시지를 저장합니다. 고가용성, 내구성, 확장성 및 TTL (Time-To-Live) 기능을 활용해야 하는 경우와 같이, 채팅 메모리를 영구적으로 저장해야 하는 애플리케이션에 적합합니다.
 
CassandraChatMemoryRepository는 시계열 기반 스키마를 사용하여 과거의 모든 채팅 윈도우를 기록하므로, 거버넌스 및 감사 (auditing) 목적으로 유용합니다. 예를 들어 3년과 같은 값으로 TTL을 설정하는 것이 권장됩니다.
 
CassandraChatMemoryRepository를 사용하려면 먼저 프로젝트에 다음 의존성을 추가해야 합니다.
 

Maven

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

 

Gradle

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

 
Spring AI는 CassandraChatMemoryRepository에 대한 자동 구성을 제공하므로, 이를 애플리케이션에서 바로 사용할 수 있습니다.

@Autowired
CassandraChatMemoryRepository chatMemoryRepository;

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

 
만약 직접 CassandraChatMemoryRepository를 생성하려면, CassandraChatMemoryRepositoryConfig 인스턴스를 제공하여 수동으로 구성할 수 있습니다.

ChatMemoryRepository chatMemoryRepository = CassandraChatMemoryRepository
    .create(CassandraChatMemoryConfig.builder().withCqlSession(cqlSession));

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

 

설정 속성

속성	설명	기본값
spring.cassandra.contactPoints	클러스터 검색을 시작할 호스트	http://127.0.0.1
spring.cassandra.port	Cassandra에 연결할 네이티브 프로토콜 포트	9042
spring.cassandra.localDatacenter	연결할 Cassandra 데이터센터	datacenter1
spring.ai.chat.memory.cassandra.time-to-live	Cassandra에 저장된 메시지의 TTL(Time to Live)
spring.ai.chat.memory.cassandra.keyspace	Cassandra 키스페이스	springframework
spring.ai.chat.memory.cassandra.messages-column	메시지를 저장할 Cassandra 컬럼 이름	springframework
spring.ai.chat.memory.cassandra.table	사용할 Cassandra 테이블 이름	ai_chat_memory
spring.ai.chat.memory.cassandra.initialize-schema	애플리케이션 시작 시 스키마를 초기화할지 여부	true

 

스키마 초기화

자동 구성은 ai_chat_memory 테이블을 자동으로 생성합니다.
스키마 초기화를 비활성화하려면, spring.ai.chat.memory.repository.cassandra.initialize-schema 속성을 false로 설정하면 됩니다.
 

Neo4j ChatMemoryRepository

Neo4jChatMemoryRepository는 채팅 메시지를 속성 그래프 데이터베이스의 노드와 관계로 저장하기 위해 Neo4j를 사용하는 기본 구현체입니다. 이 저장소는 Neo4j의 그래프 기능을 활용하여 채팅 메모리를 지속적으로 저장하고자 하는 애플리케이션에 적합합니다.
 
먼저, 프로젝트에 다음 의존성을 추가하십시오:
 

Maven

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

 

Gradle

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

 

Spring AI는 Neo4jChatMemoryRepository에 대한 자동 구성을 제공하므로, 이를 애플리케이션에서 바로 사용할 수 있습니다.

@Autowired
Neo4jChatMemoryRepository chatMemoryRepository;

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

 
직접 Neo4jChatMemoryRepository를 생성하려면, Neo4j Driver 인스턴스를 제공하여 수동으로 구성할 수 있습니다.

ChatMemoryRepository chatMemoryRepository = Neo4jChatMemoryRepository.builder()
    .driver(driver)
    .build();

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

 

설정 속성

속성	설명	기본값
spring.ai.chat.memory.repository.neo4j.sessionLabel	대화 세션을 저장하는 노드의 레이블	Session
spring.ai.chat.memory.repository.neo4j.messageLabel	메시지를 저장하는 노드의 레이블	Message
spring.ai.chat.memory.repository.neo4j.toolCallLabel	도구 호출(예: Assistant 메시지 내)을 저장하는 노드의 레이블	ToolCall
spring.ai.chat.memory.repository.neo4j.metadataLabel	메시지 메타데이터를 저장하는 노드의 레이블	Metadata
spring.ai.chat.memory.repository.neo4j.toolResponseLabel	도구 응답을 저장하는 노드의 레이블	ToolResponse
spring.ai.chat.memory.repository.neo4j.mediaLabel	메시지와 연관된 미디어를 저장하는 노드의 레이블	Media

 

인덱스 초기화 (Index Initialization)

Neo4j 저장소는 성능 최적화를 위해 대화 ID(conversation ID)와 메시지 인덱스(message index)에 대한 인덱스를 자동으로 생성합니다. 사용자 정의 레이블(custom labels)을 사용하는 경우, 해당 레이블에 대해서도 인덱스가 생성됩니다. 별도의 스키마 초기화는 필요하지 않지만, 애플리케이션에서 Neo4j 인스턴스에 접근할 수 있도록 설정되어 있어야 합니다.

Memory in Chat Client

ChatClient API를 사용할 때, 여러 상호작용에 걸쳐 대화 문맥을 유지하기 위해 ChatMemory 구현체를 제공할 수 있습니다.
 
Spring AI는 필요에 따라 메모리 동작을 구성할 수 있도록 몇 가지 기본 제공 Advisor를 제공합니다.
 

주의
현재 툴 호출(tool call)을 수행할 때 LLM과 주고받는 중간 메시지들은 메모리에 저장되지 않습니다. 이는 현재 구현의 제한 사항이며, 향후 릴리스에서 개선될 예정입니다. 이러한 메시지 저장이 필요한 경우 사용자 제어형 도구 실행(User Controlled Tool Execution) 관련 지침을 참조하십시오.

• MessageChatMemoryAdvisor: 주어진 ChatMemory 구현체를 사용하여 대화 메모리를 관리합니다. 각 상호작용 시 메모리에서 대화 이력을 가져와 메시지 컬렉션 형태로 프롬프트에 포함시킵니다.
• PromptChatMemoryAdvisor: 주어진 ChatMemory 구현체를 사용하여 대화 메모리를 관리합니다. 각 상호작용 시 메모리에서 대화 이력을 가져와 시스템 프롬프트에 일반 텍스트 형식으로 추가합니다.
• VectorStoreChatMemoryAdvisor: 주어진 VectorStore 구현체를 사용하여 대화 메모리를 관리합니다. 각 상호작용 시 벡터 저장소에서 대화 이력을 검색하여 시스템 메시지에 일반 텍스트로 추가합니다.

예를 들어, MessageWindowChatMemory를 MessageChatMemoryAdvisor와 함께 사용하려면 다음과 같이 구성할 수 있습니다:

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

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

 
ChatClient를 통해 호출이 수행되면, MessageChatMemoryAdvisor가 자동으로 메모리를 관리합니다. 지정된 대화 ID를 기반으로 메모리에서 대화 이력이 조회됩니다.

String conversationId = "007";

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

 

PromptChatMemoryAdvisor

커스텀 템플릿
PromptChatMemoryAdvisor는 검색된 대화 메모리를 시스템 메시지에 보강하기 위해 기본 템플릿을 사용합니다. 이 동작은 .promptTemplate() 빌더 메서드를 통해 사용자 지정 PromptTemplate 객체를 제공함으로써 커스터마이징 할 수 있습니다.
 

참고
여기에서 제공하는 PromptTemplate은 어드바이저가 검색된 메모리를 시스템 메시지와 결합하는 방식을 정의합니다. 이는 .templateRenderer()를 통해 ChatClient에 설정하는 TemplateRenderer와는 구별됩니다. 후자는 어드바이저가 실행되기 전에 사용자/시스템 프롬프트의 초기 콘텐츠 렌더링 방식에 영향을 줍니다. 클라이언트 수준의 템플릿 렌더링에 대해서는 ChatClient Prompt Templates 항목을 참고하십시오.

 
사용자 지정 PromptTemplate은 어떤 TemplateRenderer 구현체든 사용할 수 있으며(기본값은 StringTemplate 엔진 기반의 StPromptTemplate), 다음 두 개의 플레이스홀더를 반드시 포함해야 합니다:

• instructions: 원본 시스템 메시지를 전달받기 위한 플레이스홀더
• memory: 검색된 대화 메모리를 전달받기 위한 플레이스홀더

 

VectorStoreChatMemoryAdvisor

커스텀 템플릿

VectorStoreChatMemoryAdvisor는 검색된 대화 메모리를 시스템 메시지에 보강하기 위해 기본 템플릿을 사용합니다. 이 동작은 .promptTemplate() 빌더 메서드를 통해 사용자 지정 PromptTemplate 객체를 제공함으로써 커스터마이징 할 수 있습니다.
 

참고
여기서 제공하는 PromptTemplate은 어드바이저가 검색된 메모리를 시스템 메시지와 결합하는 방식을 정의합니다. 이는 ChatClient 자체에 설정하는 TemplateRenderer (예: .templateRenderer() 사용)와는 다릅니다. 후자는 어드바이저가 실행되기 전에 사용자/시스템 프롬프트의 초기 콘텐츠 렌더링 방식에 영향을 줍니다. 클라이언트 수준의 템플릿 렌더링에 대해서는 ChatClient Prompt Templates 항목을 참고하십시오.

 
사용자 지정 PromptTemplate은 어떤 TemplateRenderer 구현체도 사용할 수 있으며(기본값은 StringTemplate 엔진 기반의 StPromptTemplate), 다음 두 개의 플레이스홀더를 반드시 포함해야 합니다:

• instructions: 원본 시스템 메시지를 전달받기 위한 용도
• long_term_memory: 검색된 대화 메모리를 전달받기 위한 용도

 

Memory in Chat Model

ChatClient 대신 ChatModel을 직접 사용하는 경우, 메모리를 명시적으로 관리할 수 있습니다.

// 메모리 인스턴스 생성
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());

// 응답에는 "James Bond"가 포함될 것임

 

Reference

• Spring AI : Chat Memory