Package com.tnsai.memory

Class AbstractMemoryStore

java.lang.Object
com.tnsai.memory.AbstractMemoryStore
All Implemented Interfaces:
MemoryStore
Direct Known Subclasses:
FileMemoryStore, InMemoryStore, NamespacedMemoryStore
public abstract class AbstractMemoryStore extends Object implements MemoryStore
Abstract base class for memory stores. Provides common functionality for history management, reducing code duplication.

Uses LinkedList for O(1) removal at head during pruning operations, which is more efficient than CopyOnWriteArrayList.remove(0) which is O(n).

Thread safety notes:

  • All mutating operations are guarded by a ReentrantLock (Virtual Thread friendly, avoids carrier thread pinning)
  • Read operations return unmodifiable views
  • Subclasses should call super methods and handle persistence in overridden methods

Subclasses only need to implement:

  • onHistoryChanged() - Called after any history modification
  • loadHistory() - Called during init to load persisted history

  • Method Details

    • init

      public void init(String agentId)
      Description copied from interface: MemoryStore
      Initializes the memory store for a specific agent.
      Specified by:
      init in interface MemoryStore
      Parameters:
      agentId - The unique ID of the agent

    • addMessage

      public void addMessage(String role, String content)
      Description copied from interface: MemoryStore
      Adds a message to the memory.
      Specified by:
      addMessage in interface MemoryStore
      Parameters:
      role - The role of the message sender (user, assistant, system)
      content - The text content of the message

    • addMessage

      public void addMessage(Map<String,Object> message)
      Description copied from interface: MemoryStore
      Adds a structured message (e.g. with tool calls) to memory.
      Specified by:
      addMessage in interface MemoryStore
      Parameters:
      message - The full message object

    • getHistory

      public List<Map<String,Object>> getHistory()
      Description copied from interface: MemoryStore
      Retrieves the full conversation history.
      Specified by:
      getHistory in interface MemoryStore
      Returns:
      List of message maps

    • getRecentHistory

      public List<Map<String,Object>> getRecentHistory(int limit)
      Description copied from interface: MemoryStore
      Retrieves the last N messages.
      Specified by:
      getRecentHistory in interface MemoryStore
      Parameters:
      limit - Number of messages to retrieve
      Returns:
      List of message maps

    • clear

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

    • prune

      public void prune(int maxTokens)
      Description copied from interface: MemoryStore
      Prunes the memory to keep it within a specific token limit. Removes oldest messages first, preserving system prompts if possible.
      Specified by:
      prune in interface MemoryStore
      Parameters:
      maxTokens - The maximum estimated tokens allowed

    • search

      public List<String> search(String query, int limit)
      Performs TF-IDF based semantic search over conversation history.

      This implementation uses term frequency-inverse document frequency (TF-IDF) scoring to find the most relevant messages matching the query. Each message in history is treated as a document, and the query terms are matched against all documents to produce a relevance-ranked result.

      No external dependencies are required -- this is a pure Java implementation.

      Specified by:
      search in interface MemoryStore
      Parameters:
      query - the search query
      limit - maximum number of results to return
      Returns:
      list of message content strings, ranked by relevance (most relevant first)

    • size

      public int size()
      Returns the current size of the history. Useful for monitoring and debugging.
      Returns:
      number of messages in history