Spring AI Session

A Spring AI library that provides structured, event-sourced session management with context compaction for AI applications.

Overview

Most AI frameworks store conversation history as a flat list of messages. That works for short conversations — but as sessions grow, you hit the model's context window. Truncating the oldest messages breaks tool-call sequences and discards coherent turns mid-conversation.

Spring AI Session solves this with:

• Structured events — every message is a SessionEvent with identity, timestamp, session ownership, and an optional branch label for multi-agent hierarchies
• Turn-aware compaction — configurable triggers fire when history grows too large; pluggable strategies decide what to keep, always respecting turn boundaries
• Persistent repositories — a clean SPI (SessionRepository) makes it trivial to swap the in-memory store for JDBC, Redis, or any other backend

Project Structure

spring-ai-session/
├── spring-ai-session-bom/                               # Bill of Materials for version 
├── spring-ai-session-management/                        # Core SPI, compaction framework, SessionMemoryAdvisor
├── spring-ai-session-jdbc/                              # JDBC-backed SessionRepository (PostgreSQL, MySQL, H2) management
└── auto-configurations/
    └── session/
        ├── spring-ai-autoconfigure-session/             # Spring Boot auto-configuration for DefaultSessionService
        └── spring-ai-autoconfigure-session-jdbc/        # Spring Boot auto-configuration for the JDBC repository
└── boot-starters/
    └── spring-ai-starter-session-jdbc/                  # Spring Boot starter (JDBC session, one-dependency setup)

Modules

Module	Artifact	Description
Session Management	spring-ai-session-management	Session, SessionEvent, SessionService, SessionRepository SPI, compaction framework, SessionMemoryAdvisor
Session JDBC	spring-ai-session-jdbc	JDBC-backed SessionRepository for PostgreSQL, MySQL, MariaDB, and H2
Session Auto-configuration	spring-ai-autoconfigure-session	Spring Boot auto-configuration for DefaultSessionService (repository-agnostic)
Session JDBC Auto-configuration	spring-ai-autoconfigure-session-jdbc	Spring Boot auto-configuration for the JDBC repository
Session JDBC Starter	spring-ai-starter-session-jdbc	Spring Boot starter — pulls in JDBC repository, auto-configurations, and spring-boot-starter
Session BOM	spring-ai-session-bom	Bill of Materials for managing all module versions together

Quick Start

1. Add the BOM:

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

2. Add a module dependency:

<!-- Core only (in-memory repository) -->
<dependency>
    <groupId>org.springaicommunity</groupId>
    <artifactId>spring-ai-session-management</artifactId>
</dependency>

<!-- Or JDBC starter (Spring Boot, recommended) -->
<dependency>
    <groupId>org.springaicommunity</groupId>
    <artifactId>spring-ai-starter-session-jdbc</artifactId>
</dependency>

3. Wire a SessionMemoryAdvisor into your ChatClient:

SessionService sessionService = DefaultSessionService.builder().sessionRepository(InMemorySessionRepository.builder().build()).build();

SessionMemoryAdvisor advisor = SessionMemoryAdvisor.builder(sessionService)
    .defaultUserId("alice")
    .compactionTrigger(new TurnCountTrigger(20))
    .compactionStrategy(SlidingWindowCompactionStrategy.builder().maxEvents(10).build())
    .build();

ChatClient client = ChatClient.builder(chatModel)
    .defaultAdvisors(advisor)
    .build();

// Every call automatically loads history, appends messages, and compacts when needed
String answer = client.prompt()
    .user("What is Spring AI?")
    .advisors(a -> a.param(SessionMemoryAdvisor.SESSION_ID_CONTEXT_KEY, "session-abc"))
    .call()
    .content();

Documentation

Full reference documentation is available at:

https://spring-ai-community.github.io/spring-ai-session/

Topics covered:

• Getting Started — setup options (in-memory, JDBC auto-config, JDBC manual)
• Session Concepts — Session, SessionEvent, turns, and architecture
• Event Filtering — composable EventFilter API
• Context Compaction — triggers, strategies, turn-boundary safety
• ChatClient Integration — SessionMemoryAdvisor setup and options
• Multi-Agent Branch Isolation — sharing sessions across parallel agents
• Recall Storage — keyword search over the full verbatim history
• Session JDBC — JDBC repository setup, schema, and design notes

Requirements

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

Building

./mvnw clean install

To skip tests:

./mvnw clean install -DskipTests

Snapshot Repository

Snapshot artifacts are published to 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>

License

Apache License 2.0

Links

• Documentation
• Issue Tracker
• Spring AI Documentation
• Spring AI Community

Contributing

Contributions are welcome! Please open an issue or submit a pull request.