Orbital 记忆系统深度解析：PROJECT_STATE、DECISIONS、LESSONS如何让Agent跨会话永不失忆-平芜编程栈

【免费下载链接】Orbital

Context is yours. Agents are replaceable.

项目地址：https://gitcode.com/gh_mirrors/orbital10/Orbital

Orbital 是一款面向 AI Agent 的操作系统，它的核心设计哲学是 "Context is yours, Agents are replaceable"——Agent 可以换，但项目上下文必须留得住。本文带你完整拆解 Orbital 的记忆系统：每个项目工作区里的orbital/目录下，Agent 会自主维护 PROJECT_STATE、DECISIONS、LESSONS 三个记忆文件，它们每轮对话自动注入上下文，配合后台记忆编辑器自动归档整理，让 Agent 跨会话、跨模型都"永不失忆"。

📂 记忆长什么样：4个主文件 + 3个归档文件

Orbital 的记忆不是数据库，而是一组人类可读的 Markdown 文件，统一存放在项目的orbital/目录中。所有路径的"唯一事实来源"定义在 agent_os/agent/project_paths.py：

文件	角色	特性
`PROJECT_STATE.md`	当前状态草稿板	易失（volatile），只写"现在"，覆盖式更新
`DECISIONS.md`	决策日志	持久（durable），带 Chose / Reason / Rejected
`LESSONS.md`	踩坑经验手册	持久（durable），编号条目
`INDEX.md`	导航地图	每个重要文件一句话
`*_ARCHIVE.md`× 3	归档文件	按需读取，永不自动注入

这种"文件系统即记忆"的设计意味着：你可以随时用编辑器打开这些文件直接阅读，甚至手动修正 Agent 记错的内容。

🔁 每轮自动注入：记忆如何进入上下文

记忆不会"过期在磁盘上"。在 agent_os/agent/context.py 中，ContextManager每次组装发给大模型的提示词时，都会从磁盘重新读取这 4 个 Layer-1 文件，以[PROJECT_STATE.md]这样的前缀注入为系统消息。新会话、新模型、冷启动恢复，拿到的都是最新记忆——这正是跨会话不失忆的第一支柱。

为防止记忆无限膨胀，每个文件都有独立的 token 预算（见 agent_os/agent/memory_entries.py）：

DECISIONS：soft 7000 / hard 9000 token
LESSONS：soft 5000 / hard 6000 token
PROJECT_STATE：soft 1800 / hard 2000 token
INDEX：soft 1500 / hard 2000 token

超预算时，注入视图（inject_view）会优先保留最新条目 + 最老的 3 条奠基性条目——既保证新信息在场，又不丢失项目最初的关键设定，并在视图中标注"部分旧条目已省略，可读磁盘文件"。

🧠 三大记忆文件各司其职

PROJECT_STATE.md：只记录"现在"，不是变更日志

它回答"项目此刻什么状态"：当前焦点、进行中的工作、阻塞项、下一步。系统契约（见 agent_os/agent/prompt_builder.py）明确要求：覆盖过时行，而不是追加带日期的历史。比如上图中 Agent 把已完成的 "spec written" 任务标注清楚，让下一轮对话一眼看懂进展到哪。

DECISIONS.md：为什么这么做的决策档案

每条决策包含 Chose（选了什么）、Reason（为什么）、Rejected（否掉了什么）。截图里可以看到一条经典条目："此 Agent 只管理 BACKLOG.md，不碰生产代码"——新会话继承后绝不会越权改代码。契约要求：新决策推翻旧决策时必须替换旧条目，绝不让两条互相矛盾的决策并排存在。

LESSONS.md：错误恢复与经验手册

内置的 learning-capture 技能定义了三种触发时机：🔧 用户纠正、🛠️ 工具失败后找到替代方案、💡 非显而易见的发现。每条经验包含"发生了什么 / 下次怎么做 / 关键词标签"，截图中的 PyInstaller 路径问题教训就是一个完整范例。契约还特别强调：不要把真正的 playbook 压缩省空间——教训的价值在于细节。

🧹 后台记忆编辑器：超预算自动整理，永不删除

文件长大了怎么办？Orbital 的答案是后台记忆编辑器（agent_os/agent/memory_editor.py），而非粗暴截断：

触发：任何文件超过 soft 预算，调度器自动在后台启动整理（每项目最多每 30 分钟一次），完全不打断对话。
按 id 操作：编辑器只返回"选择"——archive（归档）、merge（合并）、index（重写导航图）。归档是字节级精确移动到*_ARCHIVE.md，原地留一条指针行：
[archived 2026-09-28 id:entity-pages-memory] 旧条目摘要 → DECISIONS_ARCHIVE.md
未来会话想追溯时，按指针 grep 归档文件即可，无需整读。
安全网：动手前自动滚动备份最近 5 份快照；写入采用 OCC 乐观并发控制（文件被用户改动则跳过）；永远只移动、不删除。
确定性兜底：若达到 hard 预算，系统按"最久未触碰"优先降级条目，但永远保护最老 3 条奠基条目和pinned标记条目——记忆会瘦身，但项目根基不会丢。

⚡ 手动检查点与日常使用建议

手动触发：Agent 可用 checkpoint_state 工具请求立即整理（异步执行，立即返回），适合大任务收尾时主动"存档"。
UI 查看：在 Orbital 桌面端的 Files 标签页可直接浏览、复制、在资源管理器中定位这些记忆文件（见上文三张截图），无需翻命令行。
使用技巧：告诉 Agent "记住 X / 永远做 X / 别做 X" 时，它会自动写入对应记忆文件或项目指令，下一轮对话即刻生效；你也可定期打开LESSONS.md查看 Agent 从错误中学到了什么。

✅ 小结

Orbital 的记忆系统用"三个记忆文件 + 每轮注入 + 后台自动归档"回答了 Agent 长期协作中最常见的问题：换会话、换模型、甚至隔天回来，项目上下文依然完整且自洽。对新手来说，最好的上手方式是打开你项目的orbital/目录，读一遍这三个文件——那就是 Agent 眼中的"项目人格"，而它完全属于你。