This version is still in development and is not considered stable yet. For the latest stable version, please use Spring AI 2.1.0!

Session API

The Session API keeps what happens in a conversation as an append-only log of events. Its first use is session memory: the prompt the model sees is built from a view of that log. The log is not limited to the messages of the conversation: an application or a library can record events of its own in it, for example the state of an agent harness, as Extension Points describes. Where Chat Memory stores a flat list of messages per conversation id, a session adds what an agent needs over a long conversation:

  • Structured events. Every message is a SessionEvent with an id, a timestamp, its session and metadata; other event types record what happened in the same log.

  • Turn-aware compaction. Triggers decide when the history grew too large, and a strategy decides what leaves the view, always on a turn boundary, so the model never sees a tool call without its result or an answer without its question. A compaction never changes the log: it appends a boundary that defines the view from then on.

  • A repository SPI. SessionRepository has an in-memory implementation for tests and a JDBC one for production; a store of your own passes the same contract tests.

The session is the state; what runs on it is not. A ChatClient with the session advisors is one such runtime, a harness: it reads the view, calls the model, appends what happened, and keeps nothing of its own, so a turn can be run by any instance, and the next turn by another one. Another harness, a loop of your own for example, runs on the same session through the same SessionService.

Modules

Module Artifact Contents

Session

spring-ai-session

The core: Session, SessionEvent, SessionService, SessionRepository with InMemorySessionRepository, EventFilter and compaction, the ChatModelSummarizer included. No dependency on ChatClient.

Session Advisor

spring-ai-session-advisor

The ChatClient integration: SessionMemoryAdvisor, SessionTurnAdvisor and SessionAdvisors.

JDBC Session

spring-ai-session-jdbc

JdbcSessionRepository for PostgreSQL, MySQL, MariaDB, Microsoft SQL Server and H2, with the schema scripts.

Auto-configuration

spring-ai-autoconfigure-model-session, spring-ai-autoconfigure-model-session-jdbc

The SessionService and JdbcSessionRepository beans and their properties.

Starter

spring-ai-starter-model-session-jdbc

All of the above with Spring Boot’s JDBC starter.

Quick Start

Add the starter:

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-starter-model-session-jdbc</artifactId>
</dependency>

When the application has a single DataSource bean, or one marked @Primary, Spring Boot creates a JdbcSessionRepository and a SessionService bean, detects the SQL dialect from the database metadata, and initializes the schema of an embedded database. The SessionService bean likewise needs a single, or primary, SessionRepository bean. Without the JDBC starter, no SessionService bean exists unless you declare a SessionRepository bean yourself. For PostgreSQL or MySQL in development, initialize the schema with spring.ai.session.repository.jdbc.initialize-schema=always.

Wire the advisors into a ChatClient and pass a session id with every call:

@Bean
ChatClient chatClient(ChatModel chatModel, SessionService sessionService) {
    return ChatClient.builder(chatModel)
        .defaultAdvisors(SessionAdvisors.builder(sessionService)
            .compaction(new TurnCountTrigger(20), WindowCompactionStrategy.builder().lastTurns(10).build())
            .build())
        .build();
}

String answer = chatClient.prompt()
    .user("Hello!")
    .advisors(SessionAdvisors.session("session-abc"))
    .call()
    .content();

A session that does not exist yet is created on first use. The session id is required on every call: there is no fallback, because a shared default session would silently merge the history of different users.

Without Spring Boot, or in a test, build the service on the in-memory repository:

SessionService sessionService = DefaultSessionService.builder()
    .sessionRepository(InMemorySessionRepository.builder().build())
    .build();
InMemorySessionRepository is for tests and demos: sessions are lost on restart and not shared across instances.

Where to go next

  • Concepts: sessions, events, turns, the active view and the SessionService API.

  • Event Filtering: what a read returns, and why a window keeps turns whole.

  • Compaction: triggers, the window strategy, summarization and how a pass is recorded.

  • Recall: a keyword search over the log, and the conversation_search tool that gives it to the model.

  • System Messages: why the system prompt is configuration, and the opt-in to store it.

  • ChatClient Integration: the advisors, their context keys and what they store.

  • JDBC Repository: the tables, the dialects, the auto-configuration properties, and how to write a repository of your own.

  • Extension Points: event types of your own, state derived from the log, advisors around the session advisors, and a decorated service.