Package akka.javasdk.agent

Interface SessionMemoryInterceptor

public interface SessionMemoryInterceptor
Interceptor for write operations on SessionMemory.

An interceptor transforms session messages immediately before they are persisted to session memory. Each method has an identity default that returns the message unchanged, so implementations only need to override the variant(s) they want to transform.

Hooks are provided for each top-level SessionMessage variant: user messages (text and multimodal), AI replies, and tool call responses. Tool requests are nested inside SessionMessage.AiMessage and are not exposed as a dedicated hook; rewrite them by overriding beforeWrite(String, SessionMessage.AiMessage) and rebuilding the message with the transformed list.

Read-side behavior (history limit, filters, read/write toggles) is configured through MemoryProvider and is not exposed here.

Thread-safety: an interceptor instance is shared across every session and concurrent request that uses it. The SDK does not synchronize, copy, or pool it. Keep interceptors stateless, or rely only on immutable / thread-safe state (for example, a precompiled Pattern or a final configuration object). Mutable fields on the interceptor will be hit concurrently and must be avoided unless you guard the access yourself.

Attach an interceptor to a memory provider with withInterceptor: 


 MemoryProvider.fromConfig().withInterceptor(new SessionMemoryInterceptor() {
   @Override
   public SessionMessage.UserMessage beforeWrite(
       String sessionId, SessionMessage.UserMessage userMessage) {
     return new SessionMessage.UserMessage(
         userMessage.timestamp(),
         redact(userMessage.text()),
         userMessage.componentId());
   }
 });

  • Method Details

    • beforeWrite

      default SessionMessage.UserMessage beforeWrite(String sessionId, SessionMessage.UserMessage userMessage)
      Called immediately before a SessionMessage.UserMessage is persisted to session memory. The returned message is what gets written. The default implementation returns the input unchanged.
      Parameters:
      sessionId - The unique identifier for the contextual session
      userMessage - The user message about to be persisted
      Returns:
      The (possibly transformed) message to persist; must not be null

    • beforeWrite

      default SessionMessage.MultimodalUserMessage beforeWrite(String sessionId, SessionMessage.MultimodalUserMessage userMessage)
      Called immediately before a SessionMessage.MultimodalUserMessage is persisted to session memory. The returned message is what gets written. The default implementation returns the input unchanged.
      Parameters:
      sessionId - The unique identifier for the contextual session
      userMessage - The multimodal user message about to be persisted
      Returns:
      The (possibly transformed) message to persist; must not be null

    • beforeWrite

      default SessionMessage.AiMessage beforeWrite(String sessionId, SessionMessage.AiMessage aiMessage)
      Called immediately before an SessionMessage.AiMessage is persisted to session memory. The returned message is what gets written. The default implementation returns the input unchanged.

      Common uses include stripping SessionMessage.AiMessage.thinking() from persistence, redacting content from text, or rewriting toolCallRequests arguments.

      Parameters:
      sessionId - The unique identifier for the contextual session
      aiMessage - The AI message about to be persisted
      Returns:
      The (possibly transformed) message to persist; must not be null

    • beforeWrite

      default SessionMessage.ToolCallResponse beforeWrite(String sessionId, SessionMessage.ToolCallResponse toolCallResponse)
      Called immediately before a SessionMessage.ToolCallResponse is persisted to session memory. The returned message is what gets written. The default implementation returns the input unchanged.

      Common uses include truncating large tool outputs (e.g., search results or file dumps) or redacting sensitive content before it lands in long-term memory.

      Parameters:
      sessionId - The unique identifier for the contextual session
      toolCallResponse - The tool call response about to be persisted
      Returns:
      The (possibly transformed) message to persist; must not be null