AI 助手真正难维护的，往往不是“不会回答”，而是每次新建会话、切换任务或更换运行环境后，都要重新解释项目背景、目录边界、历史结论和已经踩过的坑。
当项目同时包含本地文件、云端任务、自动化脚本和多个长期分支时，仅依赖聊天上下文会出现几个典型问题：
- 新会话丢失历史背景；
- 同一个故障被重复排查；
- 已经验证过的方法无法跨任务复用；
- 任务做到一半，切换后不知道从哪里继续；
- AI 知道“要谨慎”，但不知道哪些目录只读、哪些操作必须人工确认。
我的解决思路是：把记忆、状态和规则从对话中抽离，写入可迁移、可审查的本地文件；再让 OpenClaw 或 Codex 在执行任务前主动读取。
这套方法先用于 OpenClaw，随后也被我迁移到 Codex 的自定义规则中。它不是隐藏记忆，也不是逐字备份聊天，而是一套面向长期工程任务的状态管理方式。
1. 为什么选择文件化记忆
聊天上下文适合短期推理，不适合充当长期项目数据库。
文件化有四个直接优势：
- 可迁移：更换模型、客户端或云端环境时，Markdown 文件仍然可用。
- 可审查：人可以直接检查 AI 记录了什么，也可以删除、修正或脱敏。
- 可版本化：规则和结论可以通过 Git 或备份保留变更历史。
- 可分层：当天记录、任务状态、踩坑日志和长期知识不必混在一起。
需要明确边界：
- 文件化记忆保存的是摘要、结论、方法和状态，不是逐字聊天备份。
- 涉及隐私、密钥、客户数据和未公开材料时，必须先脱敏。
- 文件存在不等于结论永久正确，容易变化的信息需要标注最近验证日期。
2. 整体结构
我把工作区中的信息分成四层：
workspace/ ├── AGENTS.md # 当前工作区的执行规则 ├── MEMORY.md # 经过筛选的长期事实 ├── memory/ │ └── YYYY-MM-DD.md # 每日摘要与临时信号 ├── data/ │ ├── common_knowledge.md # 跨任务复用的方法 │ └── <task>/ │ ├── task_state.md # 任务进度、当前状态、下一步 │ ├── pitfall_log.md # 故障、排查、方案、预防 │ └── AGENTS.md # 任务专属边界与规范 └── scripts/ └── bin/ # 经过审查的低风险自动化脚本核心思想不是目录名称，而是职责分离：
- 每日记录允许不完整；
- 任务状态回答“现在做到哪里”；
- 踩坑日志回答“这个错误下次怎么避免”；
- 通用知识只保留经过重复验证的方法；
- 长期记忆保存稳定、仍然有效的事实。
3. 三类关键文件
3.1 task_state.md：让任务可以续接
推荐记录：
## 【日期】任务进度 - 任务目标： - 已完成： - 当前状态： - 已验证证据： - 风险或边界： - 下一步计划：它的作用不是写日报，而是在任务被中断后，下一次会话可以直接恢复上下文。
3.2 pitfall_log.md：避免重复踩坑
推荐格式：
## 【日期】踩坑记录 - 问题场景： - 排查过程： - 最终方案： - 预防建议：我要求一个问题经过多轮排查，或者同类错误再次出现时，必须写入踩坑日志。这样 AI 下次先检索日志，而不是重新猜一遍。
3.3 common_knowledge.md：把重复方法提升为公共能力
单次成功不应立刻变成“全局真理”。我的提升规则是：
- 单次经验先进入每日记录；
- 同一任务中重复使用的方法进入任务状态；
- 跨多个任务复用、或在单一任务中多次验证后，再进入通用知识；
- 容易变化的结论补充来源和最近验证日期。
推荐格式：
## 【日期】通用知识 - 类别： - 名称： - 用法： - 适用场景： - 验证证据： - 最近验证日期： - 不适用场景：4. 本地与云端的路径设计
本地和云端的目录可以不同，但逻辑职责应一致。
| 用途 | 本地示例 | 云端示例 |
|---|---|---|
| 工作区 | 本地持久目录中的workspace/ | 持久卷中的workspace/ |
| 每日记忆 | workspace/memory/ | 持久卷中的workspace/memory/ |
| 任务记录 | workspace/data/<task>/ | 持久卷中的同构目录 |
| 可执行脚本 | workspace/scripts/bin/ | 独立脚本目录或只读镜像 |
云端部署时最重要的不是目录写得多漂亮，而是确认：
- 数据写入持久卷，而不是容器临时文件系统；
- 备份能够恢复；
- 运行用户对目标目录拥有最小必要权限；
- 敏感文件不进入公开仓库或日志。
5. 自动化机制：什么时候写，什么时候整理
我把自动化分为事件触发和定时整理两类。
| 机制 | 触发时机 | 用途 |
|---|---|---|
| 会话收尾 | 新建、重置或明确结束任务时 | 保存本轮摘要和下一步 |
| 状态检查 | 长任务执行过程中 | 检查是否遗漏进度、风险和验证结果 |
| 每日整理 | 每天固定时间 | 合并当天记录、去除重复内容 |
| 每周复核 | 每周固定时间 | 更新长期结论，清理过期知识 |
| 人工审阅 | 高风险或外部写操作前 | 确认权限、目标和影响范围 |
定时任务依赖实际运行环境。网关、调度器或容器未运行时，计划任务不会因为“配置存在”就自动完成。因此验收自动化时，要同时检查配置、调度状态和真实输出文件。
6. 在 Codex 中复用这套方法
OpenClaw 解决了长期工作区的文件化记忆后，我又把相同思路迁移到 Codex 的自定义设置中。
6.1 执行前先检索，而不是重新询问
任务启动时先读取：
- 当前任务的
AGENTS.md； task_state.md中的进度和下一步；pitfall_log.md中已经出现过的错误；- 跨任务的
common_knowledge.md。
这样能自动读取的背景不再要求用户重复发送，已经验证过的方案也不会被轻易覆盖。
6.2 把权限边界写成机器可执行的规则
例如把目录明确分为：
- 可写工作区；
- 只读知识库；
- 允许跨任务复用的公共文件；
- 禁止自动提交、必须人工确认的高风险操作。
“谨慎一点”是模糊要求；“这个目录只读，外部提交必须人工确认”才是可以稳定执行的工程规则。
6.3 给任务切换设计交接协议
任务切换时不只说“下次继续”，而是写入：
- 已完成进度；
- 当前可验证状态；
- 未完成事项；
- 下一步明确计划；
- 必要的回退点。
下一次会话读取状态文件后，可以从断点继续，而不是重新建立项目认知。
6.4 把高风险操作留给人
自动化并不等于取消人工控制。我的规则是：
- 读取、检索、核验等低风险操作可以主动完成；
- 修改本地任务文件需要保持明确范围和回退点；
- 外部发布、权限扩大、敏感内容提交等操作必须由人确认；
- 不因为“提高效率”而跨越数据与权限边界。
这使 Codex 的行为更像一套可审计的工程流程，而不是只依赖当前对话中的临时提醒。
7. 一次任务的实际流转
收到任务 -> 识别任务目录与角色 -> 读取规则、状态和踩坑记录 -> 执行低风险检查 -> 实施修改 -> 验证结果 -> 更新 task_state / pitfall_log -> 提升可复用知识 -> 输出交付与下一步这套流程带来的变化包括：
- 减少重复解释项目背景；
- 避免历史修复被后续修改覆盖；
- 为长期任务保留连续状态；
- 让外部写入和敏感操作拥有清晰确认点；
- 更容易检查“AI 到底依据了什么结论”。
8. 常见问题
文件已经存在，为什么 AI 仍然像没看到？
优先检查：
- 任务启动时是否真的执行了检索；
- 文件是否位于允许访问的真实路径；
- 软链接是否越过沙箱或工作区边界；
- 索引是否覆盖目标目录；
- 文件编码和权限是否正常。
是否应该把所有对话都保存？
不建议。逐字保存会带来噪音、隐私和检索成本。更适合保存的是决策、证据、失败路径、稳定方法和下一步。
自动化越多越好吗？
不是。高频写入可能制造重复记录，危险命令自动执行则会扩大风险。自动化应优先覆盖低风险、可回退、可验证的动作。
9. 局限与边界
这套方案不能保证 AI 永远正确，也不能替代版本控制、数据库、监控或正式审计系统。
它更适合：
- 多会话的长期个人项目；
- 有明确目录边界的本地与云端工作区；
- 需要持续积累排障经验的工程任务；
- 希望在不同 AI 工具之间迁移工作方法的场景。
对于多人生产系统，还需要补充身份认证、权限管理、变更审批、集中日志、备份恢复和合规策略。
10. 总结
真正可持续的 AI 工作流，不是让模型“记住更多”，而是把重要状态放到模型之外：
- 用文件保存事实；
- 用任务状态维持连续性；
- 用踩坑日志减少重复失败；
- 用通用知识沉淀可复用方法；
- 用权限边界和人工确认控制风险。
OpenClaw、Codex 或其他 AI 工具都可以替换，但这些文件、规则和验证过程能够继续迁移。这也是我在长期工程任务中最看重的部分：工具可以变化，状态必须可追踪，边界必须可执行，结果必须可验证。
公开说明：本文只展示脱敏后的方法与目录职责，不包含个人绝对路径、账号、密钥、未公开项目内容或敏感提交规则。
