1. Overview

Spring AI Infinispan provides Spring AI integration with Infinispan, offering a vector store for similarity search and a chat memory repository for conversational AI applications.

1.1. What is Spring AI Infinispan?

Spring AI Infinispan is a community integration that connects Spring AI with Infinispan.

It provides:

  • Vector Store — Store and search document embeddings using Infinispan vector search capabilities with Ickle query language.

  • Chat Memory Repository — Persist chat conversation history in Infinispan for stateful AI applications.

Both components use Infinispan Hot Rod client for high-performance remote access and Protobuf-based serialization.

1.2. Maven modules

Spring AI Infinispan consists of four Maven modules published under the org.infinispan group ID.

Module Description

spring-ai-infinispan-store

Core vector store implementation with metadata filtering and Protobuf marshalling.

spring-ai-autoconfigure-vector-store-infinispan

Spring Boot auto-configuration for the vector store.

spring-ai-model-chat-memory-repository-infinispan

Chat memory repository implementation with message serialization.

spring-ai-autoconfigure-model-chat-memory-repository-infinispan

Spring Boot auto-configuration for the chat memory repository.

2. Getting started

Add Spring AI Infinispan to your Spring Boot application.

2.1. Adding dependencies

Add Spring AI Infinispan dependencies to your project.

Prerequisites

  • A Spring Boot {spring_boot_version} project.

  • An embedding model dependency (for the vector store).

Procedure

  1. Add the Infinispan Spring Boot starter and the auto-configuration modules to your pom.xml:

    <dependency>
    <groupId>org.infinispan</groupId>
    <artifactId>infinispan-spring-boot4-starter-remote</artifactId>
    <version>{ispn_version}</version>
</dependency>

  2. For the vector store, add:

    <dependency>
    <groupId>org.infinispan</groupId>
    <artifactId>spring-ai-autoconfigure-vector-store-infinispan</artifactId>
    <version>{spring_ai_ispn_version}</version>
</dependency>

  3. For the chat memory repository, add:

    <dependency>
    <groupId>org.infinispan</groupId>
    <artifactId>spring-ai-autoconfigure-model-chat-memory-repository-infinispan</artifactId>
    <version>{spring_ai_ispn_version}</version>
</dependency>

2.2. Starting Infinispan Server

Start an Infinispan Server instance for your Spring AI application to connect to.

Procedure

  1. Run Infinispan Server with Docker:

    docker run -p 11222:11222 -e USER="admin" -e PASS="password" quay.io/infinispan/server:latest

  2. Configure the connection in your application.properties:

    infinispan.remote.server-list=127.0.0.1:11222
infinispan.remote.auth-username=admin
infinispan.remote.auth-password=password
The ProtoStreamMarshaller is configured automatically. No marshaller property is needed.

3. Vector store

Use Infinispan as a vector store for Spring AI similarity search with full metadata filtering support.

3.1. How the vector store works

The Infinispan vector store uses Protobuf schemas to define the structure of stored embeddings. When the application starts, the vector store:

  1. Builds a Protobuf schema based on the embedding model dimensions.

  2. Registers the schema and marshallers with the Infinispan client.

  3. Uploads the schema to Infinispan Server (configurable).

  4. Creates an indexed cache for vector search (configurable).

Similarity search uses the Infinispan Ickle query language with the <→ vector distance operator. The store supports metadata filtering through Ickle query joins on embedded metadata fields.

3.2. Configuring the vector store

Configure the Infinispan vector store with Spring Boot auto-configuration or programmatically.

3.2.1. Using auto-configuration

The vector store is auto-configured when the spring-ai-autoconfigure-vector-store-infinispan module and a RemoteCacheManager bean are on the classpath.

spring.ai.vectorstore.infinispan.store-name=my-vectors
spring.ai.vectorstore.infinispan.distance=3
spring.ai.vectorstore.infinispan.similarity=COSINE

3.2.2. Programmatic configuration

Create an InfinispanVectorStore bean using the builder:

@Bean
public InfinispanVectorStore vectorStore(RemoteCacheManager cacheManager,
                                         EmbeddingModel embeddingModel) {
    return InfinispanVectorStore.builder(cacheManager, embeddingModel)
        .storeName("my-vectors")
        .distance(3)
        .similarity("COSINE")
        .build();
}

3.3. Vector store configuration properties

Properties under the spring.ai.vectorstore.infinispan prefix.

Property Type Default Description

store-name

String

defaultStore

Name of the Infinispan cache for storing embeddings.

store-config

String

auto-generated

XML configuration for the cache. Generated automatically if not specified.

distance

Integer

3

Maximum distance for kNN vector queries.

similarity

String

COSINE

Vector similarity metric. Supported values: COSINE, L2, INNER_PRODUCT.

register-schema

Boolean

true

Register the Protobuf schema on Infinispan Server.

create-store

Boolean

true

Create the cache on Infinispan Server if it does not exist.

schema-file-name

String

auto-generated

Protobuf schema file name on the server.

package-name

String

dev.spring_ai

Protobuf schema package name.

item-name

String

SpringAiItem

Protobuf message name for the embedding item.

metadata-item-name

String

SpringAiMetadata

Protobuf message name for the metadata item.

3.4. Adding documents

Add documents to the Infinispan vector store.

Procedure

  1. Create documents with text and optional metadata:

    List<Document> documents = List.of(
    new Document("Spring AI integrates with Infinispan",
        Map.of("category", "integration")),
    new Document("Infinispan provides vector search capabilities",
        Map.of("category", "search", "year", 2025))
);

  2. Add them to the vector store:

    vectorStore.add(documents);

The vector store computes embeddings using the configured EmbeddingModel and stores them in Infinispan along with the document text and metadata.

3.5. Performing similarity search

Search for documents similar to a query using the Infinispan vector store.

Procedure

  1. Perform a basic similarity search:

    List<Document> results = vectorStore.similaritySearch(
    SearchRequest.builder()
        .query("vector search")
        .topK(5)
        .build()
);

  2. Search with a similarity threshold:

    List<Document> results = vectorStore.similaritySearch(
    SearchRequest.builder()
        .query("vector search")
        .topK(5)
        .similarityThreshold(0.7)
        .build()
);

  3. Search with metadata filters:

    List<Document> results = vectorStore.similaritySearch(
    SearchRequest.builder()
        .query("vector search")
        .topK(5)
        .filterExpression("category == 'integration'")
        .build()
);

4. Chat memory repository

Use Infinispan as a persistent chat memory repository for Spring AI conversational applications.

4.1. How the chat memory repository works

The Infinispan chat memory repository stores conversation messages in an indexed Infinispan cache. Each message is serialized as a Protobuf entry with fields for the conversation ID, message type, content, sequence number, timestamp, metadata, tool calls, and tool responses.

The repository supports all Spring AI message types: USER, ASSISTANT, SYSTEM, and TOOL.

Messages are ordered by sequence number within a conversation and can be queried by conversation ID.

4.2. Configuring the chat memory repository

Configure the Infinispan chat memory repository with Spring Boot auto-configuration or programmatically.

4.2.1. Using auto-configuration

The chat memory repository is auto-configured when the spring-ai-autoconfigure-model-chat-memory-repository-infinispan module and a RemoteCacheManager bean are on the classpath.

spring.ai.chat.memory.repository.infinispan.cache-name=my-chat-memory

4.2.2. Programmatic configuration

Create an InfinispanChatMemoryRepository bean using the builder:

@Bean
public InfinispanChatMemoryRepository chatMemoryRepository(
        RemoteCacheManager cacheManager) {
    return InfinispanChatMemoryRepository.builder(cacheManager)
        .cacheName("my-chat-memory")
        .build();
}

4.2.3. Usage with Spring AI advisors

Use the repository with MessageChatMemoryAdvisor:

@Bean
public ChatClient chatClient(ChatClient.Builder builder,
                              InfinispanChatMemoryRepository repository) {
    return builder
        .defaultAdvisors(MessageChatMemoryAdvisor.builder(repository).build())
        .build();
}

4.3. Chat memory configuration properties

Properties under the spring.ai.chat.memory.repository.infinispan prefix.

Property Type Default Description

cache-name

String

chat_memory

Name of the Infinispan cache for storing messages.

package-name

String

dev.spring_ai

Protobuf schema package name.

item-name

String

ChatMemoryItem

Protobuf message name for the chat memory entry.

register-schema

Boolean

true

Register the Protobuf schema on Infinispan Server.

create-cache

Boolean

true

Create the cache on Infinispan Server if it does not exist.

5. Metadata filtering

Filter similarity search results using metadata expressions with the Infinispan vector store.

5.1. How metadata filtering works

The Infinispan vector store supports Spring AI filter expressions for narrowing similarity search results based on document metadata.

Metadata is stored as embedded Protobuf messages within each document entry, with typed fields for strings, integers, floats, booleans, and dates. Filter expressions are translated to Infinispan Ickle queries with metadata joins.

Date strings in ISO-8601 format (yyyy-MM-dd’T’HH:mm:ss’Z') are automatically normalized to Date objects for consistent filtering.

5.2. Supported filter operations

The Infinispan vector store supports the following Spring AI filter expression operations.

Operation Expression Example

Equals

==

country == 'BG'

Not equals

!=

status != 'active'

Greater than

>

year > 2020

Greater or equal

>=

score >= 4.5

Less than

<

price < 100

Less or equal

<=

rating <= 3

In

in

country in ['BG', 'NL']

Not in

not in

status not in ['deleted']

Is null

IS NULL

year IS NULL

Is not null

IS NOT NULL

year IS NOT NULL

And

&&

country == 'BG' && year == 2020

Or

||

country == 'BG' || country == 'NL'

Not

NOT(…​)

NOT(country == 'BG')