Package com.tnsai.memory

Class SharedMemoryStore

java.lang.Object
com.tnsai.memory.SharedMemoryStore
All Implemented Interfaces:
MemoryStore
public class SharedMemoryStore extends Object implements MemoryStore
A memory store wrapper that enables memory sharing between agents.

SharedMemoryStore wraps any MemoryStore and provides thread-safe read/write access across multiple agents. It maintains an access control list of agent IDs that are permitted to read from and write to the shared memory.

Usage with @Memory(shared = true, shareWith = {"agent-a", "agent-b"}): 


 MemoryStore base = new InMemoryStore();
 SharedMemoryStore shared = new SharedMemoryStore(base, "namespace-1");
 shared.grantAccess("agent-a");
 shared.grantAccess("agent-b");
 shared.init("agent-a"); // First agent initializes

Viewer-bound views and per-operation ACL

The directly constructed instance is the canonical handle for the namespace: it owns the ACL and performs the once-only delegate initialization. It is a trusted handle — its data operations do not check the ACL.

Agents that resolve shared memory through AgentMemoryResolver receive a viewer-bound view created via viewFor(String). A view shares the delegate, ACL and lock with the canonical handle, but every operation (including init(String)) verifies that the bound viewer is authorized and throws IllegalStateException otherwise. Views created for a previously authorized agent start throwing as soon as access is revoked.

Thread safety: All operations are protected by a ReentrantReadWriteLock for high-throughput concurrent reads with exclusive writes.

See Also:

  • Constructor Details

    • SharedMemoryStore

      public SharedMemoryStore(MemoryStore delegate, String namespace)
      Creates a SharedMemoryStore wrapping the given delegate.
      Parameters:
      delegate - the underlying memory store
      namespace - the shared memory namespace (isolates different shared contexts)

  • Method Details

    • viewFor

      public SharedMemoryStore viewFor(String agentId)
      Creates a view of this shared store bound to the given agent.

      The view shares state with this store but enforces the ACL on every operation: all MemoryStore methods throw IllegalStateException once the viewer is not (or no longer) authorized for the namespace.

      Parameters:
      agentId - the agent ID to bind the view to
      Returns:
      a viewer-bound view of this store

    • grantAccess

      public void grantAccess(String agentId)
      Grants access to an agent ID.
      Parameters:
      agentId - the agent ID to authorize

    • revokeAccess

      public void revokeAccess(String agentId)
      Revokes access from an agent ID.
      Parameters:
      agentId - the agent ID to deauthorize

    • hasAccess

      public boolean hasAccess(String agentId)
      Checks whether the given agent has access.
      Parameters:
      agentId - the agent ID to check
      Returns:
      true if authorized

    • getNamespace

      public String getNamespace()
      Returns the namespace of this shared memory.
      Returns:
      the namespace

    • 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)
      Description copied from interface: MemoryStore
      Performs a semantic search on the memory (Optional). Useful for RAG (Retrieval-Augmented Generation).
      Specified by:
      search in interface MemoryStore
      Parameters:
      query - The search query
      limit - Max results
      Returns:
      List of relevant memory segments