持久化模式

通过 liteflow.agent.session.memory.mode 控制 Agent memory 的保存位置：

模式	说明	适用场景
JVM（默认）	内存中的 Session，进程退出后丢失	单进程内多轮对话
NONE	不加载也不保存持久化 Session	不需要持久化、严格无状态
LOCAL_FILE	保存到 workspace.root/.agent-session/	本地持久化、开发测试
REDIS	使用 Redis 客户端 Bean	多实例共享会话
MYSQL	使用 DataSource Bean	数据库持久化、运维治理

通用开关

配置项	默认值	说明
load-on-first-use	true	首次构建 Agent 时尝试恢复历史
save-after-call	true	调用成功后保存记忆
save-on-error	true	调用抛错时也尝试保存记忆

JVM 模式

默认模式，无需额外配置。Agent memory 保存在 JVM 内存中，进程重启后丢失。

liteflow.agent.session.memory.mode=JVM

LOCAL_FILE 模式

记忆文件保存在 workspace.root/.agent-session/ 目录下。

liteflow.agent.session.memory.mode=LOCAL_FILE
liteflow.agent.session.memory.load-on-first-use=true
liteflow.agent.session.memory.save-after-call=true
liteflow.agent.session.memory.save-on-error=true

REDIS 模式

LiteFlow 不创建 Redis 连接，必须由业务框架提供对应 Bean。

liteflow.agent.session.memory.mode=REDIS
liteflow.agent.session.memory.redis.bean-name=redissonClient
liteflow.agent.session.memory.redis.client-type=REDISSON
liteflow.agent.session.memory.redis.key-prefix=liteflow:agent:session

client-type 可选：REDISSON、JEDIS、LETTUCE。

MYSQL 模式

同样，DataSource 需要由业务应用提供。

liteflow.agent.session.memory.mode=MYSQL
liteflow.agent.session.memory.mysql.data-source-bean-name=agentDataSource
liteflow.agent.session.memory.mysql.database-name=agentscope
liteflow.agent.session.memory.mysql.table-name=agentscope_sessions
liteflow.agent.session.memory.mysql.create-if-not-exist=false

热 Session 缓存

热 Session 缓存和 memory 持久化是两件事：热缓存决定当前 JVM 里保留多久，memory 持久化决定重启后能否恢复。

配置项	默认值	说明
liteflow.agent.session.idle-timeout	30m	Session 空闲多久后可被清理
liteflow.agent.session.cleanup-interval	1m	后台清理线程检查间隔
liteflow.agent.session.max-sessions	10000	当前 JVM 中最多保留多少个热 Session

当 Session 数量超过 max-sessions 时，按 lastActive 淘汰最旧的缓存。淘汰只移除热 Agent 实例，不删除 workspace 和持久化记忆。

运行时配置变更

运行中修改 memory、skills、模型、工具或 hook 配置后，已有 (conversationId, agentKey) 不一定立即体现新配置。通常需要使用新的 conversation/agentKey，或重启应用。

自定义持久化后端（SPI）

除上面五种内置 memory.mode 外，框架还通过 AgentSessionFactory SPI 开放了持久化后端扩展点。需要接入 PostgreSQL、对象存储、加密 JSON 等其它后端时，可以实现该接口并在 META-INF/services/com.yomahub.liteflow.agent.session.factory.AgentSessionFactory 中注册：

public class EncryptedFileSessionFactory implements AgentSessionFactory {

    @Override
    public MemoryStorageMode mode() {
        // 绑定到某个已有模式枚举；与内置工厂同模式时由本实现覆盖内置实现
        return MemoryStorageMode.LOCAL_FILE;
    }

    @Override
    public Session create(AgentConfig agentConfig) {
        // 返回 AgentScope Session；返回 null 表示本模式跳过持久化
        return new MyEncryptedJsonSession(agentConfig);
    }
}

规则与边界：

• AgentSessionFactoryRegistry 先注册全部内置工厂，再加载 SPI 工厂；同一个 mode() 冲突时 SPI 工厂优先，因此自定义实现的典型用途是覆盖某个内置模式的 Session 构建逻辑（例如把 LOCAL_FILE 换成加密落盘）
• mode() 返回的是固定的 MemoryStorageMode 枚举，SPI 不能新增模式名，只能复用并覆盖已有的五种之一
• create(...) 在首次执行 Agent 组件时懒调用，而不是框架启动时
• 返回 null 表示该模式不做持久化（内置 NONE 模式即如此）