Agent Teams Lite 四种持久化模式解析：engram、openspec、hybrid 与 none 该如何选

Agent Teams Lite 是一个零依赖、纯 Markdown的 Spec-Driven Development（SDD）工具：它用一个 orchestrator 调度 9 个专业 sub-agent，把「一个功能」拆成探索、提案、规格、设计、任务、实现、验证、归档等阶段。当你关掉终端、下次再打开时，之前生成的提案、规格、设计稿该存到哪？这正是artifact_store.mode要解决的问题。本文带你 5 分钟搞懂engram、openspec、hybrid、none四种持久化模式的区别，并给出一套可以直接套用的选择方法。

完整规范见 docs/persistence.md，底层契约见 skills/_shared/persistence-contract.md。

先理解痛点：为什么 SDD 需要「持久化」

AI 助手每一轮对话都要重新处理全部历史。当上下文撑到上限时，模型会做compaction（有损压缩）——文件内容、工具结果都可能丢失。而 sub-agent 每次都以全新上下文启动，干完活把结果交回 orchestrator。

如果没有一个持久的存储后端，这些产物（proposal / spec / design / tasks）在对话结束时就会彻底丢失，下次也没法从中间那个阶段继续。docs/token-economics.md 专门分析了这一点：持久化后端能让跨会话恢复用「引用」代替「重读文件」，省下数万 token。

一张表看懂四种模式 🧭

行为对比（读/写到哪、是否动项目文件）详见 skills/_shared/persistence-contract.md。

逐个模式详解

1. engram：默认推荐，持久且仓库干净 ⭐

• 读、写都走Engram 记忆库，从不创建任何项目文件，git 工作区保持干净。
• 跨会话恢复靠两步：mem_search拿到 ID →mem_get_observation取完整内容。
• 所有产物用确定性命名：sdd/{change-name}/{artifact-type}，保证下次能精确匹配到。
• 命名规则与恢复协议见 skills/_shared/engram-convention.md。

适合：大多数日常场景。想要跨会话记忆、又不想把一堆 md 文件塞进仓库。

2. openspec：文件即产物，可进版本库 📁

开启后，一个 change 会生成一套自包含文件夹：

openspec/ ├── config.yaml ← 项目上下文（技术栈、约定） ├── specs/ ← 当前系统的「真源」规格 └── changes/ └── {change-name}/ ├── proposal.md ← 为什么改 + 范围 ├── specs/ ← 增量规格（新增/修改/删除） ├── design.md ← 怎么做（架构决策） └── tasks.md ← 实现清单

• 产物都是人类可读的 Markdown 文件，可 review、可提交 git、可追溯。
• 归档时 change 文件夹会移动到changes/archive/YYYY-MM-DD-{change-name}/作为审计轨迹。
• 目录结构与产物路径表见 skills/_shared/openspec-convention.md 与 docs/persistence.md。

适合：团队项目、希望 spec/design 文件进版本库、需要审计留痕。

3. hybrid：双写双保险 🔒

• 同时把每个产物写到 Engram 和文件系统。
• 读优先 Engram，查不到再回退文件系统；写必须两边都成功才算完成。
• 代价：每次操作消耗更多 token（双写双读）。官方明确提醒——只在「既要跨会话持久、又要本地可读文件」时才用。
• 详细说明见 skills/_shared/persistence-contract.md。

适合：合规 / 审计场景，既想要跨会话恢复，又想要本地可查的文件副本。

4. none：不持久化 🚫

• 不创建、不修改任何项目文件，结果只在当前对话里 inline 返回。
• 连 DAG 状态都不会保存，因此无法跨会话恢复。
• 一旦落到none，系统会建议你改用engram或openspec。

适合：隐私敏感、一次性实验、临时跑一个想法，不想留下任何痕迹。

默认解析规则：系统到底怎么选？

当 orchestrator 没有显式指定时，解析逻辑非常保守（见 skills/_shared/persistence-contract.md）：

1. Engram 可用→ 用engram；
2. 否则→ 用none。

⚠️ 关键点：openspec和hybrid永远不会被自动选择，只有用户显式要求时才会启用。这样默认策略既安全（不污染仓库）又不会静默地多花 token。

怎么选？场景速查表 ✅

一句话决策：默认engram；想把文件留进项目就openspec；两个都要就hybrid；什么都不想留就none。

快速配置

在 orchestrator 配置里设置artifact_store.mode即可：

# 默认推荐：持久、仓库干净 artifact_store: mode: engram

# 隐私 / 本地优先：不落任何文件 artifact_store: mode: none

其余openspec、hybrid同理，把mode换成对应值（示例见 docs/persistence.md）。

常见问题 FAQ

Q：没装 Engram 会怎样？A：自动回退到none，并提示你启用engram或openspec。

Q：hybrid比engram多花多少？A：每个产物都要双写、双读，token 明显更高，官方明确标注「更耗 token，按需使用」。

Q：none模式还能接着上次的改动继续吗？A：不能。none不保存任何状态，对话一结束产物就没了，只能重头再来。

Q：为什么默认不自动用openspec？A：为避免在没授权的情况下往仓库里写一堆文件，官方坚持「除非显式要求，否则不碰文件系统」。

小结

• 想要省心 + 跨会话：engram（默认）。
• 想要文件进版本库、可 review：openspec。
• 想要两者兼得（愿意多花 token）：hybrid。
• 想要无痕、一次性：none。

理解了这个artifact_store.mode开关，你就掌握了 Agent Teams Lite 里「产物存到哪、能否续命」的核心机制——这也是 SDD 工作流能够稳定跨阶段、跨会话跑下去的关键。