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

Solon AI v4.0.5 introduces session management abstractions that give Java-based AI agents persistent memory across turns, process restarts, and horizontal scaling. The framework's ChatSession and AgentSession interfaces model conversation state and execution snapshots, with pluggable backends including in-memory, file, and Redis storage. This enables multi-turn customer support agents to remember context without hand-rolled history tables.

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: | 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. 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. 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 https://solon.noear.org .