agent - 会话与长久记忆 (Session & Memory)

在多轮对话或复杂的团队协作中，智能体需要通过长久“记忆”来维持上下文的连贯性。Solon AI 通过 AgentSession 和 sessionWindowSize 提供了灵活的记忆管理机制。

1、基础用法：开启记忆能力

通过关联 AgentSession 并设置 sessionWindowSize（默认为 8），智能体即可自动加载历史对话。

示例：

// 1. 创建具备记忆窗口的 Agent
ReActAgent agent = ReActAgent.of(chatModel)
                .sessionWindowSize(5) // 仅保留最近 5 条消息，降低 Token 成本
                .build();

// 2. 创建或获取会话（以 sessionId 隔离不同用户的记忆）
AgentSession session = InMemoryAgentSession.of("user_123");

// 3. 执行调用
String content = agent.prompt("我想延续上次的话题...")
                .session(session) // 关联会话上下文
                .call()
                .getContent();

每个内置的智能体，都支持 prompt, session 接口。

2、记忆管理机制

会话窗口化记忆 (History Window)。sessionWindowSize 决定了发送给 LLM 的短期记忆深度。

• 作用：自动截断过旧的消息，确保不超出大模型的上下文长度限制（Context Limit），同时节省费用。
• 策略：建议根据模型能力设置，通常 5-15 之间较为理想。

会话隔离 (Session Isolation)。AgentSession 不仅仅是存储 ChatMessage 的集合，它还承担了状态机的职责：

• 隔离性：不同 sessionId 之间的对话互不干扰。
• 持久化：通过不同的实现类，可以将记忆存放在内存、Redis 或数据库中。

3、AgentSession 内置实现对比

生成情况复杂，可能需要进一步定制（可复制它们进行修改定制）

4、高级扩展：AgentSession 接口定义

如果你需要将记忆存入自定义数据库（如 MongoDB, MySQL），可以实现 AgentSession 接口。它核心处理两类数据：对话消息 (Messages) 和 执行快照 (Snapshot)。

实践建议

• 及时更新 Snapshot：在工作流（Flow）模式下，updateSnapshot 会保存当前变量池（Context）的状态，确保 Agent 在下次唤醒时能感知到之前的业务变量。
• 分布式环境强制使用 Redis：在生产集群环境下，请务必使用 RedisAgentSession，否则由于负载均衡，用户的请求可能会落到没有记忆的节点上。

AgentSession 扩展自 ChatSession，并增加会话快照（消息之外的其它记忆）的支持。

package org.noear.solon.ai.agent;

import org.noear.solon.ai.chat.message.ChatMessage;
import org.noear.solon.flow.FlowContext;
import org.noear.solon.lang.NonSerializable;
import org.noear.solon.lang.Preview;

import java.util.Collection;

/**
 * 智能体会话接口
 * <p>负责维护智能体的运行状态、上下文记忆以及执行流快照。
 * 继承自 {@link ChatSession}，扩展了对工作流（Flow）状态的支持。</p>
 */
public interface AgentSession extends ChatSession, NonSerializable {
    /**
     * 同步/更新执行快照
     */
    void updateSnapshot();

    /**
     * 获取当前状态快照（用于状态回溯或持久化导出）
     */
    FlowContext getSnapshot();
}