Skip to content

Getting Started

Requirements

  • Java 17+
  • Spring AI 2.0.0-M4+
  • Spring Boot 4.0.2+

Import the BOM so all module versions stay in sync:

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>org.springaicommunity</groupId>
            <artifactId>spring-ai-session-bom</artifactId>
            <version>${spring-ai-session.version}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

Choose a setup

Add the session management module:

<dependency>
    <groupId>org.springaicommunity</groupId>
    <artifactId>spring-ai-session-management</artifactId>
</dependency>

Create the service in your application:

@Bean
SessionService sessionService() {
    return new DefaultSessionService(InMemorySessionRepository.builder().build());
}

Warning

InMemorySessionRepository is not suitable for production — sessions are lost on restart and not shared across instances. Use the JDBC repository for persistence.

Add the starter:

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

Spring Boot will automatically create:

  • a JdbcSessionRepository bean backed by the auto-configured DataSource
  • a DefaultSessionService bean wrapping the repository
  • SQL dialect detection from the DataSource URL
  • schema initialisation for embedded databases (H2)

To initialise the schema for PostgreSQL or MySQL, set:

spring:
  ai:
    session:
      repository:
        jdbc:
          initialize-schema: always

No additional bean declarations are required. To override the auto-configured SessionService, declare your own @Bean SessionService and it will take precedence.

Add the JDBC module:

<dependency>
    <groupId>org.springaicommunity</groupId>
    <artifactId>spring-ai-session-jdbc</artifactId>
</dependency>

Apply the DDL script for your database (see Session JDBC → Overview & Setup), then define the bean:

@Bean
SessionRepository sessionRepository(DataSource dataSource) {
    return JdbcSessionRepository.builder()
        .dataSource(dataSource)   // dialect auto-detected
        .build();
}

@Bean
SessionService sessionService(SessionRepository repository) {
    return new DefaultSessionService(repository);
}

Wire the ChatClient advisor

SessionMemoryAdvisor is the recommended way to use sessions with a ChatClient. It automatically loads history before each request, appends the user and assistant messages after each response, and runs compaction when a trigger fires.

@Bean
SessionMemoryAdvisor sessionMemoryAdvisor(SessionService sessionService) {
    return SessionMemoryAdvisor.builder(sessionService)
        .defaultUserId("alice")
        // Compact when 20 turns accumulate, keeping the last 10 events
        .compactionTrigger(new TurnCountTrigger(20))
        .compactionStrategy(SlidingWindowCompactionStrategy.builder().maxEvents(10).build())
        .build();
}

@Bean
ChatClient chatClient(ChatModel chatModel, SessionMemoryAdvisor advisor) {
    return ChatClient.builder(chatModel)
        .defaultAdvisors(advisor)
        .build();
}

Pass a session ID at call time via the advisor context:

String response = chatClient.prompt()
    .user("Hello!")
    .advisors(a -> a.param(SessionMemoryAdvisor.SESSION_ID_CONTEXT_KEY, "session-abc"))
    .call()
    .content();

If no session exists for the given ID, the advisor creates one automatically.

Repositories

Spring AI Session is available from the Spring snapshot repository:

<repositories>
    <repository>
        <id>spring-snapshots</id>
        <url>https://repo.spring.io/snapshot</url>
        <snapshots><enabled>true</enabled></snapshots>
        <releases><enabled>false</enabled></releases>
    </repository>
</repositories>

Next steps