Package akka.javasdk.agent

Class SessionMemoryEntity

Object

akka.javasdk.eventsourcedentity.EventSourcedEntity<SessionMemoryEntity.State,SessionMemoryEntity.Event>

akka.javasdk.agent.SessionMemoryEntity

@Component(id="akka-session-memory",
           name="Agent Session Memory",
           description="Stores the recent conversation history for each agent session, including user, AI, and tool messages.\nUse this component to view or inspect the memory that the agents uses for context during interactions.\n")
@EnableReplicationFilter
public final class SessionMemoryEntity
extends EventSourcedEntity<SessionMemoryEntity.State,SessionMemoryEntity.Event>

Built-in Event Sourced Entity that provides persistent session memory for agent interactions with the AI model.

SessionMemoryEntity maintains a limited history of contextual messages in FIFO (First In, First Out) style, automatically managing memory size to prevent unbounded growth. It serves as the default implementation of session memory for agents.

Automatic Registration: This entity is automatically registered by the Akka runtime when Agent components are detected. Each session is identified by the entity id, which corresponds to the agent's session id.

Memory Management:

• Configurable maximum memory size via akka.javasdk.agent.memory.limited-window.max-size
• Automatic removal of oldest messages when size limit is exceeded
• Orphan message cleanup (removes AI/tool messages when their triggering user message is removed)

Direct Access: You can interact directly with session memory using ComponentClient.

Event Subscription: You can subscribe to session memory events using a Consumer to monitor session activity, implement custom analytics, or trigger compaction when memory usage exceeds thresholds.

The session memory has the multi-region replication filter enabled to only include the local region when using `request-region` primary selection. When accessed from another region the filter will be expanded to include the other region too.

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static final record	SessionMemoryEntity.AddInteractionCmd
static final record	SessionMemoryEntity.AddMultimodalInteractionCmd
static final record	SessionMemoryEntity.CompactionCmd
static interface	SessionMemoryEntity.Event	Sealed interface representing events that can occur in the SessionMemory entity.
static final record	SessionMemoryEntity.GetHistoryCmd
static final record	SessionMemoryEntity.LimitedWindow
static final record	SessionMemoryEntity.State

Nested classes/interfaces inherited from class akka.javasdk.eventsourcedentity.EventSourcedEntity

EventSourcedEntity.Effect<T>, EventSourcedEntity.ReadOnlyEffect<T>

Field Summary

Fields

Modifier and Type	Field	Description
final AgentRegistry	agentRegistry
static final String	COMPONENT_ID

Constructor Summary

Constructors

Constructor	Description
SessionMemoryEntity(com.typesafe.config.Config config, EventSourcedEntityContext context, AgentRegistry agentRegistry)

Method Summary

Modifier and Type	Method	Description
EventSourcedEntity.Effect<akka.Done>	addInteraction(SessionMemoryEntity.AddInteractionCmd cmd)
EventSourcedEntity.Effect<akka.Done>	addMultimodalInteraction(SessionMemoryEntity.AddMultimodalInteractionCmd cmd)
SessionMemoryEntity.State	applyEvent(SessionMemoryEntity.Event event)	This is the main event handler method.
EventSourcedEntity.Effect<akka.Done>	compactHistory(SessionMemoryEntity.CompactionCmd cmd)
EventSourcedEntity.Effect<akka.Done>	delete()
SessionMemoryEntity.State	emptyState()	Returns the initial empty state object for this entity.
EventSourcedEntity.Effect<SessionHistoryResult>	fetchHistory(SessionMemoryEntity.GetHistoryCmd cmd)	Like getHistory(akka.javasdk.agent.SessionMemoryEntity.GetHistoryCmd) but signals via a SessionHistoryResult.Truncated reply when the entity has dropped older messages because of its size limit.
EventSourcedEntity.Effect<SessionHistory>	getHistory(SessionMemoryEntity.GetHistoryCmd cmd)	Consistent read (not ReadOnlyEffect).
EventSourcedEntity.Effect<SessionMessage.TokenUsage>	getTokenUsage()	Consistent read (not ReadOnlyEffect).
EventSourcedEntity.Effect<akka.Done>	setLimitedWindow(SessionMemoryEntity.LimitedWindow limitedWindow)

Methods inherited from class akka.javasdk.eventsourcedentity.EventSourcedEntity

commandContext, currentState, effects, eventContext, isDeleted

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Details

COMPONENT_ID

public static final String COMPONENT_ID

See Also:

• Constant Field Values

agentRegistry

public final AgentRegistry agentRegistry

Constructor Details

SessionMemoryEntity

public SessionMemoryEntity(com.typesafe.config.Config config,
 EventSourcedEntityContext context,
 AgentRegistry agentRegistry)

Method Details

emptyState

public SessionMemoryEntity.State emptyState()

Description copied from class: EventSourcedEntity

Returns the initial empty state object for this entity. This state is used when the entity is first created and before any events have been persisted and applied.

Also known as "zero state" or "neutral state". This method is called when the entity is instantiated for the first time or when recovering from the journal without any persisted events.

The default implementation returns null. Override this method to provide a more meaningful initial state for your entity.

Overrides:

emptyState in class EventSourcedEntity<SessionMemoryEntity.State,SessionMemoryEntity.Event>

Returns:

the initial state object, or null if no initial state is needed

setLimitedWindow

public EventSourcedEntity.Effect<akka.Done> setLimitedWindow(SessionMemoryEntity.LimitedWindow limitedWindow)

addMultimodalInteraction

public EventSourcedEntity.Effect<akka.Done> addMultimodalInteraction(SessionMemoryEntity.AddMultimodalInteractionCmd cmd)

addInteraction

public EventSourcedEntity.Effect<akka.Done> addInteraction(SessionMemoryEntity.AddInteractionCmd cmd)

getTokenUsage

public EventSourcedEntity.Effect<SessionMessage.TokenUsage> getTokenUsage()

Consistent read (not ReadOnlyEffect). Replication filter for the local region is enabled by default and when accessing from another region it's important to trigger a region event sync also for reads.

getHistory

public EventSourcedEntity.Effect<SessionHistory> getHistory(SessionMemoryEntity.GetHistoryCmd cmd)

Consistent read (not ReadOnlyEffect). Replication filter for the local region is enabled by default and when accessing from another region it's important to trigger a region event sync also for reads.

fetchHistory

public EventSourcedEntity.Effect<SessionHistoryResult> fetchHistory(SessionMemoryEntity.GetHistoryCmd cmd)

Like getHistory(akka.javasdk.agent.SessionMemoryEntity.GetHistoryCmd) but signals via a SessionHistoryResult.Truncated reply when the entity has dropped older messages because of its size limit. Callers that receive a Truncated marker should stream the journal in [fromSequenceNr, toSequenceNr] to reconstruct the full history.

Internal SDK use: SessionMemoryClient calls this and, on a Truncated reply, transparently falls back to a chunked journal read bounded by the sequence numbers in the reply so the caller never sees an incomplete history.

See Also:

• for the meaning of the returned sequence numbers.

compactHistory

public EventSourcedEntity.Effect<akka.Done> compactHistory(SessionMemoryEntity.CompactionCmd cmd)

delete

public EventSourcedEntity.Effect<akka.Done> delete()

applyEvent

public SessionMemoryEntity.State applyEvent(SessionMemoryEntity.Event event)

Description copied from class: EventSourcedEntity

This is the main event handler method. Whenever an event is persisted, this handler will be called. It should return the new state of the entity.

Note that this method is called in two situations:

• when one or more events are persisted by the command handler, this method is called to produce the new state of the entity.
• when instantiating an entity from the event journal, this method is called to restore the state of the entity.

It's important to keep the event handler side effect free. This means that it should only apply the event on the current state and return the updated state. This is because the event handler is called during recovery.

Events are required to inherit from a common sealed interface, and it's recommend to implement this method using a switch statement. As such, the compiler can check if all existing events are being handled.

 // example of sealed event interface with concrete events implementing it
 public sealed interface Event {
   @TypeName("created")
   public record UserCreated(String name, String email) implements Event {};
   @TypeName("email-updated")
   public record EmailUpdated(String newEmail) implements Event {};
 }

 // example of applyEvent implementation
 public User applyEvent(Event event) {
    return switch (event) {
      case UserCreated userCreated -> new User(userCreated.name, userCreated.email);
      case EmailUpdated emailUpdated -> this.copy(email = emailUpdated.newEmail);
    }
 }
 

Specified by:

applyEvent in class EventSourcedEntity<SessionMemoryEntity.State,SessionMemoryEntity.Event>