MongoDB Chat Memory Store

By default, Quarkus LangChain4j keeps chat memory in the application’s memory, so conversations are lost when the application stops or restarts. The MongoDB chat memory store persists the chat memory of your AI services in a MongoDB collection. Conversations then survive restarts, and several instances of the application can share them.

See Messages and Memory for background on how chat memory works.

Dependency

To use MongoDB as the chat memory store, add the following Maven dependency:

<dependency>
  <groupId>io.quarkiverse.langchain4j</groupId>
  <artifactId>quarkus-langchain4j-memory-store-mongodb</artifactId>
  <version>1.15.0.CR1</version>
</dependency>

Even better, if you use the Quarkus platform BOM (default for projects generated), add the Quarkus Langchain4J BOM and all dependency versions will align:

    <dependencyManagement>
        <dependencies>
            <dependency>
                <groupId>${quarkus.platform.group-id}</groupId>
                <artifactId>${quarkus.platform.artifact-id}</artifactId>
                <version>${quarkus.platform.version}</version>
                <type>pom</type>
                <scope>import</scope>
            </dependency>
            <dependency>
                <groupId>${quarkus.platform.group-id}</groupId>
                <artifactId>quarkus-langchain4j-bom</artifactId> (1)
                <version>${quarkus.platform.version}</version> (2)
                <type>pom</type>
                <scope>import</scope>
            </dependency>
        </dependencies>
    </dependencyManagement>

    <dependencies>
      <dependency>
        <groupId>io.quarkiverse.langchain4j</groupId>
        <artifactId>quarkus-langchain4j-memory-store-mongodb</artifactId>
        (3)
      </dependency>
    </dependencies>
1 In your dependencyManagement section, add the quarkus-langchain4j-bom
2 Inherit the version from your platform version
3 Voilà, no need for version alignment anymore

This extension builds on the Quarkus MongoDB client. Configure the MongoDB connection as described in that guide, for example:

quarkus.mongodb.connection-string=mongodb://localhost:27017

In dev and test mode, if no connection string is configured, the MongoDB Dev Services start a MongoDB container automatically.

Usage

The extension registers a ChatMemoryStore bean backed by MongoDB. Because it replaces the default in-memory store, AI services use it with no code changes:

@RegisterAiService
@ApplicationScoped
public interface Assistant {

    String chat(@MemoryId String conversationId, @UserMessage String message);
}

Each memory ID is stored as one document in the configured collection. The memory window settings (such as quarkus.langchain4j.chat-memory.memory-window.max-messages) still apply: the store only holds the messages kept by the chat memory.

To delete a conversation from MongoDB, use ChatMemoryRemover:

ChatMemoryRemover.remove(assistant, conversationId);

Document Format

The _id field holds the memory ID, converted to a string. The messages field holds the conversation as an array of BSON subdocuments, one per message:

{
  _id: "01",
  messages: [
    {
      contents: [
        {
          text: "Hello, my name is Ricardo",
          type: "TEXT"
        }
      ],
      attributes: {},
      type: "USER"
    },
    {
      toolExecutionRequests: [],
      text: "Nice to meet you Ricardo",
      attributes: {},
      type: "AI"
    }
  ]
}

Because messages are stored as subdocuments, you can query and index their fields directly. For example, the following query finds all conversations that contain an AI response:

db.chat_memory.find({ "messages.type": "AI" })
Upgrading from earlier versions

Earlier versions stored the messages field as a single JSON string. The store still reads documents in that format, and converts them to the BSON array format the next time the conversation is updated.

Downgrading is not supported: once a document has been written in the BSON array format, older versions of the extension cannot read it.

Using a Named MongoDB Client

By default, the store uses the default MongoDB client. To use a named MongoDB client instead, set its name:

quarkus.mongodb.memory.connection-string=mongodb://memory-host:27017
quarkus.langchain4j.memorystore.mongodb.client-name=memory

Configuration Reference

All of these properties are fixed at build time.

Configuration property fixed at build time - All other configuration properties are overridable at runtime

Configuration property

Type

Default

quarkus.langchain4j.memorystore.mongodb.client-name

The name of the MongoDB client to use. These clients are configured by means of the mongodb extension. If unspecified, it will use the default MongoDB client.

Environment variable: QUARKUS_LANGCHAIN4J_MEMORYSTORE_MONGODB_CLIENT_NAME

string

quarkus.langchain4j.memorystore.mongodb.database

The name of the database to use.

Environment variable: QUARKUS_LANGCHAIN4J_MEMORYSTORE_MONGODB_DATABASE

string

langchain4j

quarkus.langchain4j.memorystore.mongodb.collection

The name of the collection to use.

Environment variable: QUARKUS_LANGCHAIN4J_MEMORYSTORE_MONGODB_COLLECTION

string

chat_memory