Class MessageWindowChatMemory

java.lang.Object
dev.langchain4j.memory.chat.MessageWindowChatMemory
All Implemented Interfaces:
ChatMemory
public class MessageWindowChatMemory extends Object implements ChatMemory
This chat memory operates as a sliding window whose size is controlled by a maxMessagesProvider. It retains as many of the most recent messages as can fit into the window. If there isn't enough space for a new message, the oldest one is evicted.

The maximum number of messages can be provided either statically or dynamically through the maxMessagesProvider. When supplied dynamically, the effective window size can change at runtime, and the sliding-window behavior always respects the most recent value returned by the provider.

The rules for SystemMessage:

  • Once added, a SystemMessage is always retained, it cannot be removed.
  • Only one SystemMessage can be held at a time.
  • If a new SystemMessage with the same content is added, it is ignored.
  • If a new SystemMessage with different content is added, the previous SystemMessage is removed. Unless MessageWindowChatMemory.Builder.alwaysKeepSystemMessageFirst(Boolean) is set to true, the new SystemMessage is added to the end of the message list.
If an AiMessage containing ToolExecutionRequest(s) is evicted, the following orphan ToolExecutionResultMessage(s) are also automatically evicted to avoid problems with some LLM providers (such as OpenAI) that prohibit sending orphan ToolExecutionResultMessage(s) in the request.

The state of chat memory is stored in ChatMemoryStore (SingleSlotChatMemoryStore is used by default).

  • Method Details

    • id

      public Object id()
      Description copied from interface: ChatMemory
      The ID of the ChatMemory.
      Specified by:
      id in interface ChatMemory
      Returns:
      The ID of the ChatMemory.

    • add

      public void add(ChatMessage message)
      Description copied from interface: ChatMemory
      Adds a message to the chat memory.
      Specified by:
      add in interface ChatMemory
      Parameters:
      message - The ChatMessage to add.

    • addAsync

      public CompletableFuture<Void> addAsync(List<ChatMessage> messagesToAdd)
      Description copied from interface: ChatMemory
      Non-blocking counterpart of ChatMemory.add(Iterable), used by the asynchronous (CompletableFuture/CompletionStage) and reactive (Flow.Publisher) AI Service APIs. It takes a list (rather than a single message) so that adding several messages at once is a single operation; to add one message, pass a singleton list.

      The default implementation returns a failed future carrying AsyncNotSupportedException: a memory backed by a blocking ChatMemoryStore is not silently offloaded to a worker thread. Implementations should compose the store's getMessagesAsync/ updateMessagesAsync, persisting all messages in a single read-modify-write (fewer round trips and an atomic update).

      Callers must not invoke this method concurrently for the same memory: implementations typically read, modify and write the store, so concurrent calls would race. The AI Service chains its calls sequentially. Note that this race window is wider than with the blocking ChatMemory.add(Iterable): here the read and the write are separated by future composition and thread hops rather than a single uninterrupted call, so sharing one memory across concurrent invocations is more likely to silently drop an update than it was with the synchronous API.

      Specified by:
      addAsync in interface ChatMemory
      Parameters:
      messagesToAdd - The ChatMessages to add.
      Returns:
      A future that completes when the messages have been added.

    • set

      public void set(Iterable<ChatMessage> iter)
      Description copied from interface: ChatMemory
      Replaces all messages in the chat memory with the specified messages. Unlike add, this method replaces the entire message history rather than appending to it.

      Implementations should override this method to provide more efficient atomic operations if possible. The default implementation calls ChatMemory.clear() followed by add(Iterable<ChatMessage>) which is not atomic.

      This method will typically be used when chat memory needs to be re-written to implement things like memory compaction.

      NOTE: This method is never called automatically by LangChain4j.

      Specified by:
      set in interface ChatMemory
      Parameters:
      iter - The ChatMessages to set. Must not be null or empty.

    • setAsync

      public CompletableFuture<Void> setAsync(List<ChatMessage> messages)
      Description copied from interface: ChatMemory
      Non-blocking counterpart of ChatMemory.set(Iterable), used by the asynchronous (CompletableFuture/CompletionStage) and reactive (Flow.Publisher) AI Service APIs (e.g. to rewrite memory for tool compensation without blocking the model-delivery thread).

      Replaces the entire message history with messages. Like the other async methods, callers must not invoke it concurrently for the same memory. The default implementation returns a failed future carrying AsyncNotSupportedException; see ChatMemory.addAsync(List) for the rationale.

      Specified by:
      setAsync in interface ChatMemory
      Parameters:
      messages - The ChatMessages to set.
      Returns:
      A future that completes when the messages have been set.

    • messages

      public List<ChatMessage> messages()
      Description copied from interface: ChatMemory
      Retrieves messages from the chat memory. Depending on the implementation, it may not return all previously added messages, but rather a subset, a summary, or a combination thereof.
      Specified by:
      messages in interface ChatMemory
      Returns:
      A list of ChatMessage objects that represent the current state of the chat memory.

    • messagesAsync

      public CompletableFuture<List<ChatMessage>> messagesAsync()
      Description copied from interface: ChatMemory
      Non-blocking counterpart of ChatMemory.messages(), used by the asynchronous (CompletableFuture/CompletionStage) and reactive (Flow.Publisher) AI Service APIs.

      The default implementation returns a failed future carrying AsyncNotSupportedException; see ChatMemory.addAsync(List) for the rationale.

      Specified by:
      messagesAsync in interface ChatMemory
      Returns:
      A future that completes with the current state of the chat memory.

    • clear

      public void clear()
      Description copied from interface: ChatMemory
      Clears the chat memory.
      Specified by:
      clear in interface ChatMemory

    • builder

      public static MessageWindowChatMemory.Builder builder()

    • withMaxMessages

      public static MessageWindowChatMemory withMaxMessages(int maxMessages)