必须初始化Session并绑定project_id和user_id，自动加载AGENTS.md等结构化上下文，再通过mark_for_persistence和persist_async将关键状态持久化至MemOS长期记忆。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
要在Agent Space中稳定保存AI项目的上下文和会话状态，避免每次新开对话就丢失项目结构、约束条件或用户偏好，必须绕过单纯依赖LLM上下文窗口的陷阱，建立分层、可持久、可检索的状态管理路径。
初始化Session并绑定项目标识
启动Agent时，调用create_session()并显式传入project_id和user_id参数，例如create_session(project_id="fscloud-v2", user_id="u_7a9b")。不传project_id会导致后续所有上下文注入失去项目锚点，Session将退化为通用聊天流。
这一步必须在首次消息发送前完成。如果先发了用户提问再补建Session，已产生的message将无法自动归属到该Session，需手动迁移——而多数Agent Space SDK不提供此接口。
【project_id必须与代码仓库根目录名或CI/CD流水线ID严格一致】，否则后续基于项目名的上下文文件（如AGENTS.md）加载会失败，且MemoraX Code等记忆模块无法匹配Repo Memory。
注入结构化项目上下文
方法一：自动加载本地上下文文件
确保项目根目录存在AGENTS.md，Agent Space启动时会自动读取并注入system prompt。内容须控制在1200 tokens内，超长将触发静默截断，且不报错。
方法二：运行时动态注入关键约束
调用session.inject_context("constraint", {"db_compatibility": "v3.2+", "lang_preference": "TypeScript"})。该操作会将键值对写入Session Memory层，并参与后续所有LLM调用的上下文组装。注意：此方法注入的内容不会持久化到长期记忆，仅存活于当前Session生命周期。
方法三：挂载Codex-style全局上下文
在~/.codex/AGENTS.md中声明跨项目通用规则，例如“✅ 所有生成代码必须含JSDoc注释”“⚠️ 禁止修改package-lock.json”。Agent Space会合并该文件与项目级AGENTS.md，但若两者冲突，以项目级为准。
持久化Session状态到长期记忆
第一步：确认longMemoryProvider已启用
检查Agent配置中openLongMemory是否为true，且longMemoryProvider明确设为MEMOS或Mem0。若为null或未配置，所有Session结束后的状态将直接丢弃。
第二步：定义沉淀触发条件
在Session结束前调用session.mark_for_persistence(["user_preference", "arch_decision", "failed_fix"])。只标记你确认具有跨会话复用价值的字段，盲目全量沉淀会污染长期记忆库，导致后续RAG检索噪声增大。
第三步：执行异步沉淀
调用session.persist_async()。该操作不阻塞响应，但必须在onSessionEndAsync钩子中显式调用——若遗漏，标记的数据将滞留在Session Memory中，随Session销毁而清空。MemOS会在此阶段对数据去重、打标scope（如scope: project_fscloud-v2），并写入text_mem或pref_mem分区。
这一步操作起来很简单，直接把文件拖进去就行。但要注意：沉淀过程不可逆，一旦写入MemOS，只能通过API手动删除，没有图形界面清理入口。
