Interface ChatMemory

All Known Implementing Classes:
MessageWindowChatMemory, TokenWindowChatMemory
public interface ChatMemory
Represents the memory (history) of a chat conversation. Since language models do not keep the state of the conversation, it is necessary to provide all previous messages on every interaction with the language model. ChatMemory helps with keeping track of the conversation and ensuring that messages fit within language model's context window.

  • Method Details

    • id

      Object id()
      The ID of the ChatMemory.
      Returns:
      The ID of the ChatMemory.

    • add

      void add(ChatMessage message)
      Adds a message to the chat memory.
      Parameters:
      message - The ChatMessage to add.

    • add

      default void add(ChatMessage... messages)
      Adds messages to the chat memory
      Parameters:
      messages - The ChatMessages to add

    • add

      default void add(Iterable<ChatMessage> messages)
      Adds messages to the chat memory
      Parameters:
      messages - The ChatMessages to add

    • set

      default void set(ChatMessage... messages)
      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.

      The default implementation delegates to set(Iterable<ChatMessage>).

      NOTE: This method is never called automatically by LangChain4j.

      Parameters:
      messages - The ChatMessages to set. Must not be null or empty.
      Since:
      1.11.0

    • set

      default void set(Iterable<ChatMessage> messages)
      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 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.

      Parameters:
      messages - The ChatMessages to set. Must not be null or empty.
      Since:
      1.11.0

    • messages

      List<ChatMessage> messages()
      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.
      Returns:
      A list of ChatMessage objects that represent the current state of the chat memory.

    • addAsync

      @Experimental default CompletableFuture<Void> addAsync(List<ChatMessage> messages)
      Non-blocking counterpart of 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 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.

      Parameters:
      messages - The ChatMessages to add.
      Returns:
      A future that completes when the messages have been added.
      Since:
      1.20.0

    • setAsync

      @Experimental default CompletableFuture<Void> setAsync(List<ChatMessage> messages)
      Non-blocking counterpart of 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 addAsync(List) for the rationale.

      Parameters:
      messages - The ChatMessages to set.
      Returns:
      A future that completes when the messages have been set.
      Since:
      1.20.0

    • messagesAsync

      @Experimental default CompletableFuture<List<ChatMessage>> messagesAsync()
      Non-blocking counterpart of messages(), used by the asynchronous (CompletableFuture/CompletionStage) and reactive (Flow.Publisher) AI Service APIs.

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

      Returns:
      A future that completes with the current state of the chat memory.
      Since:
      1.20.0

    • clear

      void clear()
      Clears the chat memory.