Package com.tnsai.memory

Class NamespacedMemoryStore

java.lang.Object
com.tnsai.memory.AbstractMemoryStore
com.tnsai.memory.NamespacedMemoryStore
All Implemented Interfaces:
MemoryStore
public class NamespacedMemoryStore extends AbstractMemoryStore
Memory store with hierarchical namespace support.

Enables scoped retrieval across a workspace > session hierarchy. Each namespace maintains its own isolated message history, and cross-namespace merged retrieval allows combining, for example, global context with session-local conversation history.

Standard MemoryStore methods delegate to a configurable default namespace, preserving full backward compatibility with code that is namespace-unaware.

Thread safety: Each namespace has its own ReentrantLock for fine-grained concurrency. Cross-namespace operations acquire locks in deterministic order to prevent deadlocks.

Since:
0.1.0
See Also:

  • Constructor Details

    • NamespacedMemoryStore

      public NamespacedMemoryStore()
      Creates a NamespacedMemoryStore with MemoryNamespace.GLOBAL as the default.

    • NamespacedMemoryStore

      public NamespacedMemoryStore(MemoryNamespace defaultNs)
      Creates a NamespacedMemoryStore with the given default namespace.
      Parameters:
      defaultNs - the namespace used when standard MemoryStore methods are called

  • Method Details

    • addMessage

      public void addMessage(String namespace, String role, String content)
      Adds a message to a specific namespace.
      Parameters:
      namespace - the target namespace key (e.g. "workspace:session")
      role - the message role (user, assistant, system)
      content - the message content

    • addMessage

      public void addMessage(String namespace, Map<String,Object> message)
      Adds a structured message to a specific namespace.
      Parameters:
      namespace - the target namespace key
      message - the full message object

    • getHistory

      public List<Map<String,Object>> getHistory(String namespace)
      Retrieves the full history from a specific namespace.
      Parameters:
      namespace - the namespace key
      Returns:
      unmodifiable list of messages, or empty list if namespace does not exist

    • getRecentHistory

      public List<Map<String,Object>> getRecentHistory(String namespace, int limit)
      Retrieves the last N messages from a specific namespace.
      Parameters:
      namespace - the namespace key
      limit - number of messages to retrieve
      Returns:
      unmodifiable list of the most recent messages

    • getMergedHistory

      public List<Map<String,Object>> getMergedHistory(String... namespaceKeys)
      Retrieves history merged from multiple namespaces, in the order provided. Messages from each namespace are appended sequentially.
      Parameters:
      namespaceKeys - the namespace keys to merge
      Returns:
      unmodifiable merged list of messages

    • search

      public List<String> search(String query, int limit, String... namespaceKeys)
      Searches across specified namespaces (or all if none specified) using TF-IDF.
      Parameters:
      query - the search query
      limit - max results
      namespaceKeys - namespaces to search (empty = all)
      Returns:
      list of relevant content strings, ranked by relevance

    • clear

      public void clear(String namespace)
      Clears a specific namespace.
      Parameters:
      namespace - the namespace key to clear

    • prune

      public void prune(String namespace, int maxTokens)
      Prunes a specific namespace to fit within the token budget.
      Parameters:
      namespace - the namespace key
      maxTokens - the token budget

    • size

      public int size(String namespace)
      Returns the number of messages in a specific namespace.
      Parameters:
      namespace - the namespace key
      Returns:
      the message count, or 0 if namespace does not exist

    • getNamespaceKeys

      public Set<String> getNamespaceKeys()
      Returns all active namespace keys.
      Returns:
      unmodifiable set of namespace keys

    • 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
      Overrides:
      addMessage in class AbstractMemoryStore
      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
      Overrides:
      addMessage in class AbstractMemoryStore
      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
      Overrides:
      getHistory in class AbstractMemoryStore
      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
      Overrides:
      getRecentHistory in class AbstractMemoryStore
      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
      Overrides:
      clear in class AbstractMemoryStore

    • 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
      Overrides:
      prune in class AbstractMemoryStore
      Parameters:
      maxTokens - The maximum estimated tokens allowed

    • search

      public List<String> search(String query, int limit)
      Description copied from class: AbstractMemoryStore
      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
      Overrides:
      search in class AbstractMemoryStore
      Parameters:
      query - the search query
      limit - maximum number of results to return
      Returns:
      list of message content strings, ranked by relevance (most relevant first)