Repository Selection Guide

Choose the right ChatMemoryRepository implementation for your use case.

Decision Matrix

Repository Details

In-Memory Repository (Default)

Use When:

• Developing locally
• Running tests
• Prototyping
• Short-lived conversations

Configuration:

// Auto-configured by default - no setup needed

Limitations:

• ⚠️ All data lost on application restart
• ⚠️ Not suitable for production
• ⚠️ Memory usage grows with conversations

JDBC Repository

Use When:

• Using relational databases (PostgreSQL, MySQL, etc.)
• Need ACID transactions
• Have existing database infrastructure
• Want familiar SQL tooling

Setup:

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

Configuration:

spring.ai.chat.memory.repository.jdbc.initialize-schema=always
spring.ai.chat.memory.repository.jdbc.platform=postgresql

Supported Databases:

• PostgreSQL
• MySQL / MariaDB
• SQL Server
• H2
• HSQLDB
• SQLite
• Oracle

MongoDB Repository

Use When:

• Using MongoDB
• Need flexible schema
• Want TTL (time-to-live) support
• Building document-centric applications

Setup:

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-autoconfigure-model-chat-memory-repository-mongodb</artifactId>
    <version>1.1.2</version>
</dependency>

Configuration:

spring.ai.chat.memory.repository.mongo.create-indices=true
spring.ai.chat.memory.repository.mongo.ttl=PT24H

Features:

• Automatic TTL expiration
• Index management
• Flexible document structure

Cassandra Repository

Use When:

• Need high write throughput
• Building distributed systems
• Require horizontal scalability
• Have large-scale data

Setup:

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

Configuration:

spring.ai.chat.memory.repository.cassandra.keyspace=my_keyspace
spring.ai.chat.memory.repository.cassandra.table=chat_memory
spring.ai.chat.memory.repository.cassandra.time-to-live=P30D

Features:

• TTL support
• Automatic schema creation
• Custom partition/clustering keys

Neo4j Repository

Use When:

• Modeling conversation relationships
• Need graph queries
• Building knowledge graphs
• Complex relationship traversal

Setup:

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

Configuration:

spring.ai.chat.memory.repository.neo4j.session-label=ChatSession
spring.ai.chat.memory.repository.neo4j.message-label=ChatMessage

Features:

• Rich graph relationships
• Customizable node labels
• Automatic index creation

Cosmos DB Repository

Use When:

• Deploying on Azure
• Need global distribution
• Require multi-region writes
• Want SLA guarantees

Setup:

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-autoconfigure-model-chat-memory-repository-cosmos-db</artifactId>
    <version>1.1.2</version>
</dependency>

Configuration:

spring.ai.chat.memory.repository.cosmosdb.endpoint=https://myaccount.documents.azure.com:443/
spring.ai.chat.memory.repository.cosmosdb.key=your-account-key
spring.ai.chat.memory.repository.cosmosdb.database-name=chat_memory_db

Features:

• Global distribution
• Multiple consistency levels
• Azure integration

Selection Flowchart

Start
  ↓
Production? → No → In-Memory
  ↓ Yes
  ↓
Using Azure? → Yes → Cosmos DB
  ↓ No
  ↓
Need graph queries? → Yes → Neo4j
  ↓ No
  ↓
Need high write throughput? → Yes → Cassandra
  ↓ No
  ↓
Using MongoDB? → Yes → MongoDB
  ↓ No
  ↓
Use JDBC (default for relational DBs)

Migration Considerations

From In-Memory to Persistent

1. Add repository dependency
2. Configure connection properties
3. Test with existing code (no code changes needed)
4. Monitor performance

Between Persistent Repositories

Repositories use the same ChatMemoryRepository interface, so switching requires:

1. Change dependency
2. Update configuration properties
3. Migrate existing data (if needed)

Performance Comparison

Recommendations by Use Case

Small Application (< 1000 users)

Recommended: JDBC with PostgreSQL

• Simple setup
• Reliable
• Good performance
• Easy backup/restore

Medium Application (1000-100K users)

Recommended: MongoDB or JDBC

• MongoDB for flexible schema
• JDBC for existing SQL infrastructure
• Both scale well at this level

Large Application (> 100K users)

Recommended: Cassandra or Cosmos DB

• Cassandra for on-premise/multi-cloud
• Cosmos DB for Azure
• Both handle high throughput

Microservices Architecture

Recommended: MongoDB or Cassandra

• Independent scaling
• Distributed by design
• Service-specific databases

Graph-Based Features

Recommended: Neo4j

• Conversation relationship tracking
• Knowledge graph integration
• Complex traversal queries

Next Steps

• Configuration Guide - Detailed configuration for each repository
• Performance Reference - Optimization tips
• API Reference - Repository interface details