Package com.tnsai.memory

Interface MemoryStore

All Known Implementing Classes:
AbstractMemoryStore, FileMemoryStore, InMemoryStore, ManagedConversationMemory, NamespacedMemoryStore, SharedMemoryStore, VectorSearchMemoryStore
public interface MemoryStore
Abstraction for agent memory (conversation history). Supports storage, retrieval, semantic search, and pruning.

  • Method Details

    • init

      void init(String agentId)
      Initializes the memory store for a specific agent.
      Parameters:
      agentId - The unique ID of the agent

    • addMessage

      void addMessage(String role, String content)
      Adds a message to the memory.
      Parameters:
      role - The role of the message sender (user, assistant, system)
      content - The text content of the message

    • addMessage

      void addMessage(Map<String,Object> message)
      Adds a structured message (e.g. with tool calls) to memory.
      Parameters:
      message - The full message object

    • getHistory

      List<Map<String,Object>> getHistory()
      Retrieves the full conversation history.
      Returns:
      List of message maps

    • getRecentHistory

      List<Map<String,Object>> getRecentHistory(int limit)
      Retrieves the last N messages.
      Parameters:
      limit - Number of messages to retrieve
      Returns:
      List of message maps

    • clear

      void clear()
      Clears the memory.

    • prune

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

    • replaceHistory

      default void replaceHistory(List<Map<String,Object>> newHistory)
      Atomically replaces the entire conversation history with the given list.

      Used by MemoryConsolidationPipeline to swap in a consolidated history (summary + preserved messages) in a single call, minimizing the window in which concurrently added messages could be lost (TAN-5180).

      The default implementation falls back to clear() followed by addMessage(Map) for each message — behaviorally identical to the legacy rewrite, so existing stores remain source- and behavior-compatible. Implementations with an internal lock (e.g. those based on AbstractMemoryStore) SHOULD override this to perform the swap under a single lock hold, making the rewrite atomic with respect to concurrent writers.

      Parameters:
      newHistory - the complete new history, in order (must not be null)
      Since:
      0.13.0

    • search

      default List<String> search(String query, int limit)
      Performs a semantic search on the memory (Optional). Useful for RAG (Retrieval-Augmented Generation).
      Parameters:
      query - The search query
      limit - Max results
      Returns:
      List of relevant memory segments