Class SessionMemoryEntity
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.
-
Nested Class Summary
Nested ClassesModifier and TypeClassDescriptionstatic final record
static final record
static interface
Sealed interface representing events that can occur in the SessionMemory entity.static final record
static final record
static final record
Nested classes/interfaces inherited from class akka.javasdk.eventsourcedentity.EventSourcedEntity
EventSourcedEntity.Effect<T>, EventSourcedEntity.ReadOnlyEffect<T>
-
Constructor Summary
ConstructorsConstructorDescriptionSessionMemoryEntity
(com.typesafe.config.Config config, EventSourcedEntityContext context) -
Method Summary
Modifier and TypeMethodDescriptionEventSourcedEntity.Effect
<akka.Done> This is the main event handler method.EventSourcedEntity.Effect
<akka.Done> EventSourcedEntity.Effect
<akka.Done> delete()
Returns the initial empty state object for this entity.EventSourcedEntity.Effect
<akka.Done> setLimitedWindow
(SessionMemoryEntity.LimitedWindow limitedWindow) Methods inherited from class akka.javasdk.eventsourcedentity.EventSourcedEntity
commandContext, currentState, effects, eventContext, isDeleted
-
Constructor Details
-
SessionMemoryEntity
-
-
Method Details
-
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 classEventSourcedEntity<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) -
addInteraction
public EventSourcedEntity.Effect<akka.Done> addInteraction(SessionMemoryEntity.AddInteractionCmd cmd) -
getHistory
public EventSourcedEntity.ReadOnlyEffect<SessionHistory> getHistory(SessionMemoryEntity.GetHistoryCmd cmd) -
compactHistory
-
delete
-
applyEvent
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.
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 classEventSourcedEntity<SessionMemoryEntity.State,
SessionMemoryEntity.Event>
-