# AI 编程项目的本地优先记忆：该保存什么，为什么
AI 编程会话很快，也很短暂；产品决策却不是。
如果项目的有效上下文只存在于聊天记录里，每次新会话都要付出同样的成本：重新理解架构、猜测旧决定、重复调查，并承担推翻既有成果的风险。
本地优先的项目记忆解决的是一个具体问题：把可复用上下文保存在代码旁边，由项目所有者掌控，让 Agent 从已验证事实继续，而不是重建过去。
项目记忆不是聊天记录
保存所有提示词和回复，只会得到庞大的档案，并不会自动得到有用记忆。下一个 Agent 仍然要判断哪些说法有效、哪些只是猜测、哪些后来已经被证伪。
真正有用的记忆是经过筛选的，它回答未来仍会遇到的问题：
- 项目当前追求什么结果？
- 哪些产品边界是有意保留的？
- 权威状态究竟在哪里？
- 哪些决策已经确认？
- 什么证据证明当前实现？
- 还有什么没有完成？
- 下一项安全动作是什么？
目标不是记住一切，而是避免昂贵的重复发现和误撤销。
为什么要坚持本地优先
项目记忆包含的不只是技术笔记，还可能暴露产品战略、用户问题、未发布功能、基础设施选择和运行事故。
本地优先意味着这些上下文保存在项目所有者能够检查、版本化、备份和移除的文件中。云服务可以提供协作或可选同步，但服务暂时不可用时，项目不应该因此无法继续。
本地归属也有助于保持准确。记忆文件与代码放在一起，可以随时用当前仓库核验。当记忆与测试、日志或运行证据冲突时，应以当前证据为准。
七类真正值得保存的上下文
1. 当前结果
用一句话描述项目现在追求的用户结果。只有目标真的变化时才更新，不要因为实现方式变化就频繁改写。
2. 产品不变量
记录未来工作必须保留的边界，例如本地数据归属、稳定 URL、单一内容权威、用户已经熟悉的动作，或必须遵守的发布路径。
这些记录能阻止“看起来更好”的改动悄悄重写产品。
3. 已确认决策
一条决策记录应包括选择、理由、影响，以及什么新证据出现时才值得重审。
不要把局部偏好保存成普遍真理，必须写清适用范围。
4. 已验证项目事实
有价值的事实包括真实应用入口、权威数据源、发布命令或服务间关系。
能指向证据时，应同时保存证据位置。如果一件事只是怀疑，先放进临时收件箱，不要进入稳定记忆。
5. 可复用模式
有些教训会跨越一次事故：验证最终生成物而不是只看模板；外部写入使用稳定幂等键；上游暂时失败时保留最近一次正确内容。
只有模式已经验证、未来大概率复用时，才值得沉淀。
6. 当前会话状态
活动交接记录正在发生的工作：已完成步骤、精确标识、当前阻塞和下一动作。
它与稳定决策不同，应该频繁更新，并在工作闭环后清理或替换。
7. 证据引用
记忆指向文件、测试、提交、部署、事件或运行检查时，可信度更高。下一次会话可以重新核验，而不是盲目接受旧结论。
什么不应该进入稳定记忆
不要轻易提升这些内容：
- 原始命令输出；
- 整份 diff；
- Secret 或凭据；
- 尚未验证的猜测；
- 临时调试观察；
- 泛泛的“已完成”套话；
- 只对一次短暂运行有效的说明。
它们会制造噪音，也可能在过期后造成危险误导。
一套简单的文件结构
小项目可以从几类文件开始：
- 保存稳定事实的项目概览；
- 决策目录；
- 模式文件；
- 当前会话交接；
- 存放未验证观察的收件箱。
具体命名并不重要，分层才重要。稳定知识、当前工作和不确定观察拥有不同生命周期，不应彼此覆盖。
证据优先的写入规则
写入记忆前，先给信息分类：
1. 它是偏好、规则、项目事实、决策、模式、领域知识、临时观察，还是当前交接？ 2. 当前证据是否已经验证？ 3. 它未来是否还会用到？ 4. 应该更新哪条既有记录，而不是制造重复？
未验证的信息先保持临时；已经验证但只用一次的信息，也未必需要长期保存。
Agent 应该如何读取记忆
记忆用于缩小调查范围，不能替代现实核验。
一次合理的恢复顺序是：
1. 读取当前目标和活动交接。 2. 只检索与当前功能、边界或故障相关的条目。 3. 沿证据引用检查当前代码或运行状态。 4. 发现不一致时更新记忆，而不是忽略现实。 5. 从最后一个已验证状态继续。
这样可以控制上下文大小，也能减少旧记录支配已变化系统的风险。
记忆与路线图解决不同问题
记忆保存“项目已经知道什么”，路线图决定“项目下一步要实现什么”。
两者应该关联，但不应合并成同一份文档。一项决策可以跨越多个路线图环节，一份活动交接可能只属于一个环节，一个有价值的模式也可能跨多个项目复用。
角色分开后，两种工具都更容易被信任。
会话结束前的实用检查
完成一轮重要工作后，问自己：
- 当前结果是否变化？
- 是否确认了未来会约束工作的决策？
- 是否发现了稳定项目事实？
- 是否存在下一会话必须知道的未完成对象或精确标识？
- 某项临时观察是否已经得到验证？
- 是否有旧交接可以被清理或替换？
只更新相关条目。一份简短、准确的交接，胜过一部面面俱到的日记。
最终结果：连续推进，同时保留控制权
本地优先项目记忆为 AI 编程工作提供了持久骨架。代码仍是实现真相，运行证据仍是行为真相，记忆负责保存理解两者所需的决策与上下文。
它让独立开发者可以随时暂停和恢复，不丢方向，同时把战略性项目知识保留在自己能够检查和拥有的工作空间中。