Package com.redis.vl.extensions.messagehistory

Class SemanticMessageHistory

java.lang.Object
com.redis.vl.extensions.messagehistory.BaseMessageHistory
com.redis.vl.extensions.messagehistory.SemanticMessageHistory
public final class SemanticMessageHistory extends BaseMessageHistory
Semantic Message History for storing and retrieving LLM conversation history with vector embeddings for semantic search.

Stores user prompts and LLM responses with vector embeddings to allow for enriching future prompts with semantically relevant session context. Messages are tagged by session to support multiple concurrent conversations.

Matches the Python SemanticMessageHistory from redisvl.extensions.message_history.semantic_history

This class is final to prevent finalizer attacks (SEI CERT OBJ11-J).

  • Field Details

    • DEFAULT_DISTANCE_THRESHOLD

      public static final double DEFAULT_DISTANCE_THRESHOLD
      Default distance threshold for semantic search.
      See Also:

  • Constructor Details

    • SemanticMessageHistory

      public SemanticMessageHistory(String name, BaseVectorizer vectorizer, redis.clients.jedis.UnifiedJedis redisClient)
      Initialize semantic message history with required parameters.
      Parameters:
      name - The name of the message history index
      vectorizer - The vectorizer used to create embeddings
      redisClient - A Jedis client instance

    • SemanticMessageHistory

      public SemanticMessageHistory(String name, String sessionTag, String prefix, BaseVectorizer vectorizer, redis.clients.jedis.UnifiedJedis redisClient)
      Initialize semantic message history with session tag and prefix.
      Parameters:
      name - The name of the message history index
      sessionTag - Tag to be added to entries to link to a specific conversation session. Defaults to instance ULID.
      prefix - Prefix for the keys for this conversation data. Defaults to the index name.
      vectorizer - The vectorizer used to create embeddings
      redisClient - A Jedis client instance

    • SemanticMessageHistory

      public SemanticMessageHistory(String name, String sessionTag, String prefix, BaseVectorizer vectorizer, double distanceThreshold, redis.clients.jedis.UnifiedJedis redisClient, boolean overwrite)
      Initialize semantic message history with all parameters.
      Parameters:
      name - The name of the message history index
      sessionTag - Tag to be added to entries to link to a specific conversation session. Defaults to instance ULID.
      prefix - Prefix for the keys for this conversation data. Defaults to the index name.
      vectorizer - The vectorizer used to create embeddings
      distanceThreshold - The maximum semantic distance for results. Defaults to 0.3.
      redisClient - A Jedis client instance
      overwrite - Whether to overwrite existing index schema. Defaults to false.

  • Method Details

    • getDistanceThreshold

      public double getDistanceThreshold()
      Get the distance threshold for semantic search.
      Returns:
      The current distance threshold

    • setDistanceThreshold

      public void setDistanceThreshold(double distanceThreshold)
      Set the distance threshold for semantic search.
      Parameters:
      distanceThreshold - The new distance threshold

    • getVectorizer

      public BaseVectorizer getVectorizer()
      Get the vectorizer used for embeddings.
      Returns:
      The vectorizer

    • getIndex

      public SearchIndex getIndex()
      Get the underlying search index.
      Returns:
      The search index

    • clear

      public void clear()
      Description copied from class: BaseMessageHistory
      Clears the chat message history.
      Specified by:
      clear in class BaseMessageHistory

    • delete

      public void delete()
      Description copied from class: BaseMessageHistory
      Clear all conversation history and remove any search indices.
      Specified by:
      delete in class BaseMessageHistory

    • drop

      public void drop(String id)
      Description copied from class: BaseMessageHistory
      Remove a specific exchange from the conversation history.
      Specified by:
      drop in class BaseMessageHistory
      Parameters:
      id - The id of the entry to delete. If null then the last entry is deleted.

    • getMessages

      public List<Map<String,Object>> getMessages()
      Description copied from class: BaseMessageHistory
      Returns the full chat history.
      Specified by:
      getMessages in class BaseMessageHistory

    • getRecent

      public <T> List<T> getRecent(int topK, boolean asText, boolean raw, String sessionTag)
      Retrieve the recent conversation history in sequential order.
      Parameters:
      topK - The number of previous messages to return
      asText - Whether to return as text strings or maps
      raw - Whether to return full Redis hash entries
      sessionTag - Session tag to filter by
      Returns:
      List of messages

    • getRecent

      public <T> List<T> getRecent(int topK, boolean asText, boolean raw, String sessionTag, Object role)
      Description copied from class: BaseMessageHistory
      Retrieve the recent conversation history in sequential order.
      Specified by:
      getRecent in class BaseMessageHistory
      Parameters:
      topK - The number of previous messages to return. Default is 5.
      asText - Whether to return the conversation as a list of content strings, or list of message maps.
      raw - Whether to return the full Redis hash entry or just the role/content/tool_call_id.
      sessionTag - Tag of the entries linked to a specific conversation session. Defaults to instance ULID.
      role - Filter messages by role(s). Can be a single role string ("system", "user", "llm", "tool"), a List of role strings, or null for no filtering.
      Returns:
      List of messages (either as text strings or maps depending on asText parameter)

    • getRelevant

      public <T> List<T> getRelevant(String prompt, boolean asText, int topK, boolean fallBack, String sessionTag, Double distanceThreshold, Object role)
      Search the message history for information semantically related to the specified prompt.

      This method uses vector similarity search with a text prompt as input. It checks for semantically similar prompts and responses and gets the top k most relevant previous prompts or responses to include as context to the next LLM call.

      Parameters:
      prompt - The message text to search for in message history
      asText - Whether to return as text strings or maps
      topK - The number of previous messages to return (default is 5)
      fallBack - Whether to fall back to recent conversation history if no relevant context
      sessionTag - Tag of the entries linked to a specific conversation session
      distanceThreshold - The threshold for semantic vector distance (null uses instance threshold)
      role - Filter messages by role(s) - single string or List of strings
      Returns:
      List of semantically relevant messages
      Throws:
      IllegalArgumentException - if topK is negative or role contains invalid values

    • store

      public void store(String prompt, String response, String sessionTag)
      Description copied from class: BaseMessageHistory
      Insert a prompt:response pair into the message history.
      Specified by:
      store in class BaseMessageHistory
      Parameters:
      prompt - The user prompt to the LLM
      response - The corresponding LLM response
      sessionTag - The tag to mark the messages with. Defaults to instance session tag.

    • store

      public void store(String prompt, String response)
      Insert a prompt:response pair into the message history using the default session tag.
      Parameters:
      prompt - The user prompt to the LLM
      response - The corresponding LLM response

    • addMessages

      public void addMessages(List<Map<String,String>> messages, String sessionTag)
      Description copied from class: BaseMessageHistory
      Insert a list of prompts and responses into the message history.
      Specified by:
      addMessages in class BaseMessageHistory
      Parameters:
      messages - The list of user prompts and LLM responses
      sessionTag - The tag to mark the messages with. Defaults to instance session tag.

    • addMessage

      public void addMessage(Map<String,String> message, String sessionTag)
      Description copied from class: BaseMessageHistory
      Insert a single prompt or response into the message history.
      Specified by:
      addMessage in class BaseMessageHistory
      Parameters:
      message - The user prompt or LLM response
      sessionTag - The tag to mark the message with. Defaults to instance session tag.

    • addMessage

      public void addMessage(Map<String,String> message)
      Insert a single prompt or response into the message history using the default session tag.
      Parameters:
      message - The user prompt or LLM response

    • addMessages

      public void addMessages(List<Map<String,String>> messages)
      Insert a list of prompts and responses into the message history using the default session tag.
      Parameters:
      messages - The list of user prompts and LLM responses

    • formatContext

      protected <T> List<T> formatContext(List<Map<String,Object>> messages, boolean asText)
      Format messages with metadata deserialization support.
      Overrides:
      formatContext in class BaseMessageHistory
      Parameters:
      messages - The raw messages from Redis
      asText - Whether to return as text
      Returns:
      Formatted messages