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 problem with hand-rolled memory

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:

• Unbounded growth - a 200-turn ticket means 400 messages re-sent (and re-billed as tokens) on every call.
• System prompt pollution - if you persist everything, stale system prompts pile up inside the history.
• No place for workflow state - agents don't just remember text; they remember where they are in a plan, which steps finished, what a human approved.
• Restart amnesia - in-memory lists die with the JVM.

Solon AI answers each of these with a dedicated layer.

ChatSession: the message ledger

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) is the windowing primitive. The framework itself uses it to inject only the last N turns into the prompt - the unbounded-growth problem is solved at the retrieval side, not by deleting history. The full ledger stays available for audit.
• attrs() is explicitly documented as not needing persistence - a place for per-request scratch data that must never leak into your storage layer.

AgentSession: memory plus workflow state

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.

Attaching a session to an agent

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):

1. Builds the agent prompt, pulling session.getLatestMessages(config.getSessionWindowSize()) as history (default window: 5).
2. Stamps __sessionId into both the prompt attributes and the tool context - so custom tools you write can correlate database writes with the conversation.
3. Appends the assistant's reply with session.addMessage(...) and calls updateSnapshot() - your code never mutates history manually.

Pluggable backends

Sessions are an interface, and three backends ship in the box:

Backend	Messages	Snapshot	Use case
InMemoryAgentSession	JVM heap	JVM heap	tests, single-node demos
FileAgentSession	NDJSON append log	JSON file	single instance, zero infra
RedisAgentSession	Redis list (<id>:messages)	Redis key (<id>:snapshot)	production, multi-instance

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 reloading 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.

One provider to route them all

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 loading: 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.

Windows, not truncation

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

• getLatestMessages(n) - what the model sees (token cost control)
• getMessages() - what your system knows (audit, analytics, compliance)

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.

Closing thoughts

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.