Give Your Java Agents a Memory - Session Management with Solon AI

Most LLM demos are amnesiacs. The user says "my name is noear and I like blue" in turn one, asks "what's my name?" in turn two, and the model shrugs - because every HTTP call to the chat API is stateless, and nobody fed the history back in. In production this is not a cosmetic issue: a support agent that forgets the ticket the customer opened 30 seconds ago is worse than no agent at all.

Solon AI (v4.0.5) treats conversation state as a first-class, pluggable construct. In this article we build a multi-turn customer support agent whose memory survives process restarts and horizontal scaling, using only the framework's session abstractions - no hand-rolled history tables.

The naive fix is to append every message to a List<ChatMessage>

in your own code and resend it with each request. That works until it doesn't:

Solon AI answers each of these with a dedicated layer.

At the core sits ChatSession

(org.noear.solon.ai.chat

, since 3.1) - a deliberately small interface that models the conversation as an append-only message sequence:

public interface ChatSession {
    String getSessionId();

    List<ChatMessage> getMessages();
    List<ChatMessage> getLatestMessages(int windowSize);
    void removeLatestMessage(int windowSize);

    void addMessage(Collection<? extends ChatMessage> messages);
    void addMessage(String userMessage);          // convenience: user role

    boolean isEmpty();
    void clear();

    Map<String, Object> attrs();                  // transient, never persisted
}

Two details are worth calling out:

getLatestMessages(windowSize)

attrs()

Agents need more than a transcript. AgentSession

(since 3.8.1) extends ChatSession

with the state of the agent's execution flow:

public interface AgentSession extends ChatSession {
    void updateSnapshot();          // sync execution snapshot
    FlowContext getContext();       // live flow context

    void pending(boolean pending, String reason); // suspend / resume
    boolean isPending();
    String getPendingReason();
}

The pending(...)

family is how human-in-the-loop agents park themselves mid-plan: suspend with a reason ("waiting for expense approval"), serialize the whole session, and resume the exact step when the human answers. Because the snapshot lives inside the session object, one storage backend covers both transcript and workflow state.

Every agent request carries its session explicitly:

ChatModel chatModel = ...;

SimpleAgent agent = SimpleAgent.of(chatModel)
        .name("SupportAgent")
        .role("A customer support assistant")
        .instruction("Track the customer's issue across the whole conversation.")
        .sessionWindowSize(10)   // inject last 10 messages as history
        .build();

AgentSession session = InMemoryAgentSession.of("customer-8837");

// Turn 1
agent.prompt("My order #5521 arrived broken, I want a replacement.")
     .session(session)
     .call()
     .getMessage();

// Turn 2 - minutes later, same session: the agent already knows the order number
String answer = agent.prompt("It was the blue ceramic mug, by the way.")
     .session(session)
     .call()
     .getContent();

What the framework does per call (from the SimpleAgent

source):

session.getLatestMessages(config.getSessionWindowSize())

as history (default window: 5).__sessionId

into both the prompt attributes and the tool context - so custom tools you write can correlate database writes with the conversation.session.addMessage(...)

and calls updateSnapshot()

• your code never mutates history manually.Sessions are an interface, and three backends ship in the box:

The FileAgentSession

behaves like a proper write-ahead log. The official test suite demonstrates the property that matters most - restart recovery:

FileAgentSession session = new FileAgentSession(sessionId, tempDir);
session.addMessage(ChatMessage.ofUser("hello"),
                   ChatMessage.ofAssistant("hi, how can I help?"));
session.getContext().put("user_name", "noear");
session.updateSnapshot();

// simulate a process restart: new instance, same directory
FileAgentSession recovered = new FileAgentSession(sessionId, tempDir);

recovered.getMessages().size();                 // 2 - transcript survived
recovered.getContext().get("user_name");        // "noear" - snapshot survived

Note the subtlety verified by the same tests: system messages are filtered out of the NDJSON log. Persisted history contains only the real conversation (user/assistant/tool), so re never stacks stale system prompts.

RedisAgentSession

adds an in-memory cache layer with per-session locking, so hot conversations don't pay a network round trip per message, while the canonical state lives in Redis - which is what you want when the support team's traffic lands on a load balancer and turn two may hit a different pod than turn one.

The last piece is AgentSessionProvider

• a one-method factory the framework uses to resolve sessions by business ID:

@Bean
public AgentSessionProvider redisSession(RedisClient redisClient) {
    Map<String, AgentSession> map = new ConcurrentHashMap<>();
    return sessionId -> map.computeIfAbsent(
            sessionId, k -> new RedisAgentSession(k, redisClient));
}

The contract is lazy : return the existing session if there is one (keeping context continuous), create one on demand otherwise. Inject it wherever agents are used:

@Inject AgentSessionProvider sessionProvider;
@Inject ReActAgent supportAgent;

public String reply(String customerId, String message) throws Throwable {
    AgentSession session = sessionProvider.getSession("customer-" + customerId);
    return supportAgent.prompt(message)
            .session(session)
            .call()
            .getContent();
}

Because the session ID is your business key ("customer-8837"), memory becomes addressable: the same customer chatting from the app and from email can be routed to the same session, and your data retention tooling can age sessions out by exactly the keys it already knows.

A common misconception is that windowing means deleting history. In Solon AI the two are separate concerns:

getLatestMessages(n)

• what the model getMessages()

• what your system So a support platform can show the customer their full transcript in the UI, feed the agent only the last 10 messages for cost, and keep everything in NDJSON or Redis for the retention policy - one session object, three views.

Statelessness is the LLM's constraint, not yours. Solon AI's session layer turns "agent with memory" from a hand-rolled liability (growing lists, lost state on deploy, no audit trail) into a configuration decision: pick a backend, set a window, inject a provider. The transcript, the workflow snapshot and the human-in-the-loop suspension point all ride in the same persistent object - and swapping the demo InMemoryAgentSession

for the production RedisAgentSession

is a one-line change.

If you want to dig into the agent framework, chat models, RAG or tool calling, the docs live at solon.noear.org.