构建可核对的项目记忆

在本章里，“记忆”指跨会话保存、后续能够检索的外部记录。把信息写入文件不会改变模型参数；新会话也不会因为文件存在就自动读到它。

例如，本站“只保留白底浅色模式”值得长期保留；“预览现在运行在 3010 端口”会很快变化，通常只放在当前任务记录。

先区分四种载体

内容	示例	放哪里
必须遵守的规则	不自动部署	AGENTS.md / CLAUDE.md 与权限设置
稳定但可变化的事实或决定	页面外容器共享宽度变量	项目文档或记忆
这一次的进度	手机端还没验证	会话交接记录
可重复执行的方法	如何检查页面对齐	Skill

如果事实已经有权威位置，优先引用它，不另造一份副本。比如最大宽度的实际值应读 CSS，记忆只记录“为何共享、去哪里找”。

一个不需要数据库的方案

下面的目录是可以自行创建的教学方案，本站不因这篇文档而自动创建或启用它：

project-memory/
  index.md
  decisions.md
  pitfalls.md

index.md 只作路由：

- 改布局前：阅读 decisions.md 的“共享容器”，再核对 globals.css。
- 修布局回归：阅读 pitfalls.md 的对应案例。
- 资料与当前代码冲突时：标出冲突，不自动修改用户预期。

在项目规则里明确“涉及布局时先读这个索引”，或每次任务显式指向它。否则这只是存档，不是能参与工作的记忆。

一条可更新的记录

## 共享容器
ID：layout-shared-container
范围：shanshi-site 的 Header、页面外容器和 Footer
事实/决定：使用同一组宽度与横向留白规则。
原因：独立调整 Header 曾造成它与正文不一致。
权威位置：src/app/globals.css；项目布局约定
记录依据：本站对齐调整过程
核对日期：2026-09-05
状态：有效
复核条件：改全局容器，或用户重新确认页面宽度时
不包含：文章内部阅读列的宽度

这里最重要的是范围和依据。只写“页面必须一样宽”会误伤文章阅读列、弹窗、卡片等内部布局。

日期也不是质量保证。重新核对过才更新日期，不要在每次使用时自动刷新。

写入之前做筛选

对一次新结论依次问：

下一次任务还可能用到吗？一次性进度不写。
能找到来源吗？模型猜测不直接写成事实。
已经存在于 README、代码或规则里吗？存在就更新权威位置或放引用。
有敏感信息吗？密钥、客户数据、完整私人对话不进入通用项目记忆。
用户是否授权保存？私人偏好和跨项目信息尤其要明确范围。

这一步可以由 AI 起草候选记录，但应保留审阅机会，不让它默默积累未经确认的人物画像。

检索、冲突与删除

收到“调整工具页宽度”时，先按项目与主题找到 layout-shared-container，再读权威代码。没必要把所有历史决定都加载进来。

假设用户后来确认“工具目录可以更宽，但 Header 仍和站点主容器一致”，旧记录就发生冲突。先确认新设计的适用范围，再更新同一 ID；需要保留历史时将旧条目标为“被替代”，不要留下两个都写着“有效”的版本。

删除时也应按明确 ID 或文件段落处理，检查索引是否还引用它。如果记录曾进入备份或日志，只删除正文文件不等于所有副本已经消失。

怎样测试记忆真的有用

用三个新会话场景检查：

输入	预期
“调整页面外容器宽度”	找到共享规则，并重新读当前 CSS
“修改一个按钮字号”	不把共享容器记录强加给按钮
“预览地址是什么”	检查当前服务，不引用历史端口当事实

Claude Code 的 auto memory属于产品提供的记忆机制。上面的文件方案是手动设计，不依赖它，也不假定 Codex 与 Claude Code 在目录、加载或更新方式上相同。

如果测试总是检索不到，先修入口和描述；如果经常检索到错误记录，先收窄范围。只有文件检索确实成为瓶颈，再考虑索引、检索服务或数据库。