
PraisonAI Agents 会话持久化完全指南零配置 JSON 存储、多进程安全与上下文缓存【免费下载链接】PraisonAIPraisonAI — Hire a 24/7 AI Workforce. Stop writing boilerplate and start shipping autonomous self-improving agents that research, plan, code, and execute tasks. Deployed in 5 lines of code with built-in memory, RAG, and support for 100 LLMs.项目地址: https://gitcode.com/GitHub_Trending/pr/PraisonAI导读PraisonAI Agents 内置了一套零配置的会话Session持久化机制只要在 Agent 的MemoryConfig中指定一个session_id对话历史就会自动落盘保存并在新进程、新实例中自动恢复无需搭建任何数据库。本文以 session/README.md 为骨架结合 store.py 等源码实现完整讲解会话的存储位置与文件格式、元数据契约、行为矩阵、直接存储访问、DB 适配器、多进程文件锁与原子写、以及上下文缓存prompt caching。读完你可以在自己的 Agent 应用中原样复刻这套即插即用的记忆恢复方案。快速开始两条语句开启会话记忆会话持久化的核心配置项是session_id它属于 Agent 的记忆配置memory configuration而不是 Agent 的顶层参数。最简单的用法如下from praisonaiagents import Agent, MemoryConfig # 启用会话持久化自动开启 agent Agent( nameAssistant, memoryMemoryConfig(session_idmy-session-123), ) agent.start(Hello, my name is Alice) # 稍后在一个全新进程中 —— 历史记录自动恢复 agent Agent( nameAssistant, memoryMemoryConfig(session_idmy-session-123), ) agent.start(What is my name?) # Agent 记得Alice核心语义自动持久化Agent 每轮对话结束后历史消息自动写入磁盘自动恢复用相同session_id创建新 Agent 时历史自动载入上下文零配置默认使用 JSON 文件存储无需初始化任何数据库。参数归属为什么session_id必须放在memory里需要特别注意的是Agent本身没有顶层session_id参数。直接传入会抛出TypeError: Agent.__init__() got unexpected keyword argument(s): session_idsession_id必须通过MemoryConfig传入。在源码中MemoryConfig 统一管理了user_id、session_id、db、auto_memory、learn、history、prefetch等与会话、记忆相关的配置项session_id: Optional[str] None是其标准字段。简写普通 dict 等价于 MemoryConfigmemory参数接受普通 dict 作为MemoryConfig的简写形式agent Agent(nameAssistant, memory{session_id: my-session-123})两种写法完全等价推荐在配置较长时使用显式的MemoryConfig以获得类型提示。默认存储位置与路径解析规则会话文件默认存放在~/.praisonai/sessions/{session_id}.json其中{session_id}会被做文件系统安全化处理非字母数字与-/_的字符替换为_见 store.py 中的_get_session_path。实际路径解析由集中的路径工具 paths.py 负责get_sessions_dir()返回get_data_dir() / sessions并遵循以下规则设置环境变量PRAISONAI_HOME可将所有数据根目录重定向到自定义路径如export PRAISONAI_HOME/custom/path若存在旧的~/.praisonai或~/.praison目录则保持向后兼容沿用之全新安装无上述任何目录时遵循XDG Base Directory 规范数据目录优先使用$XDG_DATA_HOME/praisonai否则回退到~/.praisonai。值得注意的实现细节store.py刻意不在模块导入时冻结默认目录而是通过 PEP 562 的模块级__getattr__在访问DEFAULT_SESSION_DIR时实时解析store.py从而保证容器运行时导出PRAISONAI_HOME、测试 monkeypatch 路径等场景下读写始终落在正确的存储目录。全局默认存储单例get_default_session_store()同样按当前解析出的目录为键重建不会因首次导入时的目录而写错位置store.py。会话元数据契约Issue #48列表接口List endpoints与 UI 仪表盘可能暴露以下可选的根级字段这些字段同时写入会话 JSON 的metadata中并在保存时镜像到根级字段类型描述modelstring会话使用的 LLM 模型total_tokensint累计的输入输出 token 数costfloat估算的美元成本agent_idstringGateway 或注册表中的 Agent idsourcestring来源chat、gateway、cli、apiagent_namestring人类可读的 Agent 名称这些字段在默认会话存储下会在每一轮 assistant 回合之后自动填充。源码层面SessionData.to_dict()会将metadata中的model、llm、total_tokens、token_count、cost、source、reasoning_effort等键镜像到 JSON 根级store.py而from_dict()在加载时会把根级遗留的这些键折叠回metadata确保恢复会话时能取回上次记录的模型而不是悄悄回退到当前默认模型Issue #3685store.py。对应的读取接口为get_session_model()与get_session_reasoning_effort()。会话文件格式默认会话文件是一个 JSON 文件结构如下{ session_id: my-session-123, messages: [ {role: user, content: Hello, timestamp: 1704153600.0}, {role: assistant, content: Hi there!, timestamp: 1704153601.5} ], created_at: 2026-01-02T04:00:0000:00, updated_at: 2026-01-02T04:01:0000:00, agent_name: Assistant, agent_id: agent-abc, source: chat, model: gpt-4o-mini, total_tokens: 128, cost: 0.0004, metadata: {} }工具回合的结构化保存Issue #3089除了纯文本的 user/assistant 消息SessionMessage还支持保存结构化的工具调用回合使恢复后的消息列表与模型原先看到的一致tool_callsassistant 回合请求的工具调用{id, type, function: {name, arguments}}列表tool_call_idroletool结果回合所对应的 assistant 工具调用 id。两者均为可选、增量字段——旧的纯文本四键会话文件role/content/timestamp/metadata依然可以原样加载保持完全向后兼容store.py。行为矩阵场景行为memoryMemoryConfig(session_id...)未提供 DBJSON 持久化自动memoryMemoryConfig(session_id..., db...)使用 DB 适配器无session_id同一 Agent 实例仅内存无session_id新 Agent 实例无历史当同时指定了session_id与db时DB 适配器优先于 JSON 持久化。MemoryConfig中的db字段正是为此设计feature_configs.py。高级用法直接访问默认会话存储不经过 Agent直接操作底层存储from praisonaiagents.session import get_default_session_store store get_default_session_store() # 添加消息 store.add_user_message(session-123, Hello) store.add_assistant_message(session-123, Hi there!) # 获取历史 history store.get_chat_history(session-123) # [{role: user, content: Hello}, {role: assistant, content: Hi there!}] # 列出所有会话 sessions store.list_sessions() # 删除会话 store.delete_session(session-123)get_default_session_store()返回进程级全局单例并可通过环境变量PRAISONAI_SESSION_RETENTIONcompact|truncate|keep_all与PRAISONAI_SESSION_ACTIVE_WINDOW整数活跃窗口保留的最近轮数在不改代码的情况下调整保留策略方便 CLI/YAML 场景复用store.py。自定义会话目录通过DefaultSessionStore直接实例化自定义存储位置与容量参数from praisonaiagents.session import DefaultSessionStore store DefaultSessionStore( session_dir/custom/path/sessions, max_messages200, # 默认100 lock_timeout10.0, # 默认5.0 秒 )使用 DB 适配器提供 DB 适配器后其优先级高于 JSON 持久化from praisonaiagents import Agent, MemoryConfig from praisonaiagents.db import db agent Agent( nameAssistant, memoryMemoryConfig( session_idmy-session, dbdb(database_urlpostgresql://localhost/mydb), ), )除 JSON 与自定义 DB 外仓库还提供了基于 SQLite 的 SqliteSessionStore在DefaultSessionStore基础上增加了全文检索search()、按 gateway 会话/Agent id 查询等能力以及支持加密落盘的EncryptedSessionStore见 session/init.py 的导出可按需选用。多进程安全会话存储通过文件锁保证并发访问安全Unix使用fcntl.flock()进行文件锁Windows使用msvcrt.locking()进行文件锁原子写入采用临时文件 rename方式防止文件损坏。多个进程可以安全地读写同一个会话文件。源码实现位于 store.py 的FileLock类锁文件为session.json.lock获取锁失败时按lock_timeout默认 5 秒内以 50ms 间隔重试写入时先写同目录下的临时文件NamedTemporaryFile再通过os.replace原子替换目标文件_atomic_write_jsonstore.py。此外每次读改写都在持锁状态下重新从磁盘加载会话避免跨进程的读改写竞态。可靠性细节损坏隔离、溢出保留与写失败抢救从源码看默认存储还内置了三层可靠性保障损坏文件隔离quarantine读取到非法 JSON/UTF-8 时不会静默覆盖而是将原文件重命名为file.json.corrupt-epoch_ms保留现场并通过SESSION_PERSIST_FAILED钩子对外可观测store.py保留策略Issue #2709活跃窗口溢出时支持三种策略——compact默认将最旧回合压缩为一条合成摘要并归档原始回合非破坏性、truncate硬截断尾部、keep_all无界历史compact策略还提供archived_messages追加归档与last_compaction检查点配合get_working_history()实现廉价恢复store.py写失败抢救spillIssue #3597持久化写失败时如磁盘满将未落盘回合原子写入~/.praisonai/state/session_spill/*.json0600 权限下次加载时自动合并回会话并删除消费掉的 spill 文件store.py。上下文缓存Prompt Caching提示词缓存是显式开启的通过cachingCachingConfig(prompt_cachingTrue)启用——Agent同样没有顶层prompt_caching参数。开启后Agent 会检查praisonaiagents.llm.model_capabilities.supports_prompt_caching(model)对于需要显式断点标记的提供商如 Anthropic框架会自动注入cache_control标记OpenAI/Gemini 使用自动前缀缓存因此不会产生标记from praisonaiagents import Agent, MemoryConfig, CachingConfig agent Agent( nameAssistant, llmanthropic/claude-sonnet-4-5, memoryMemoryConfig(session_idmy-session), cachingCachingConfig(prompt_cachingTrue), )该机制会缓存系统提示词在重复对话场景下显著降低 token 成本。不设置prompt_cachingTrue时Anthropic 路径不会注入任何cache_control断点。CachingConfig由 feature_configs.py 定义除prompt_caching外还提供enabled响应缓存开关默认True。API 参考DefaultSessionStoreclass DefaultSessionStore: def __init__( self, session_dir: Optional[str] None, # 默认~/.praisonai/sessions/ max_messages: int 100, lock_timeout: float 5.0, ): ... def add_message(self, session_id: str, role: str, content: str) - bool: ... def add_user_message(self, session_id: str, content: str) - bool: ... def add_assistant_message(self, session_id: str, content: str) - bool: ... def get_chat_history(self, session_id: str, max_messages: int None) - List[Dict]: ... def get_session(self, session_id: str) - SessionData: ... def clear_session(self, session_id: str) - bool: ... def delete_session(self, session_id: str) - bool: ... def list_sessions(self, limit: int 50) - List[Dict]: ... def session_exists(self, session_id: str) - bool: ...add_message的role支持user、assistant、system、tool四种取值并可通过可选参数metadata、tool_calls、tool_call_id保存结构化工具回合store.py。SessionDatadataclass class SessionData: session_id: str messages: List[SessionMessage] created_at: str updated_at: str agent_name: Optional[str] user_id: Optional[str] metadata: Dict[str, Any] def get_chat_history(self, max_messages: int None) - List[Dict[str, str]]: ...从源码看SessionData还额外携带gateway_session_id、agent_id、runtime_state、archived_messages、last_compaction等字段分别服务于 Gateway 集成、运行时转录镜像、归档与压缩恢复store.py。get_chat_history()在按数量截断时还会保证不会从孤立的tool结果回合开始_trim_preserving_tool_exchanges避免向严格校验的提供商提交非法转录Issue #3089。SessionMessagedataclass class SessionMessage: role: str # user, assistant, system content: str timestamp: float metadata: Dict[str, Any]小结PraisonAI Agents 的会话持久化把跨进程记忆恢复压缩到了最小的 API 面上memoryMemoryConfig(session_id...)一行配置即可获得自动落盘、自动恢复、多进程安全与零数据库依赖需要更精细控制时可以通过DefaultSessionStore自定义目录与容量、通过db适配器切换后端、通过CachingConfig开启提示词缓存以降低成本。其底层的文件锁、原子写、损坏隔离、溢出压缩与写失败抢救机制为长时间运行的 Agent 应用提供了可靠的状态底座值得作为实现参考深入研究 store.py 与 paths.py 中的完整设计。【免费下载链接】PraisonAIPraisonAI — Hire a 24/7 AI Workforce. Stop writing boilerplate and start shipping autonomous self-improving agents that research, plan, code, and execute tasks. Deployed in 5 lines of code with built-in memory, RAG, and support for 100 LLMs.项目地址: https://gitcode.com/GitHub_Trending/pr/PraisonAI创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考