文件即记忆：让AI编程Agent彻底告别上下文失忆

当AI Agent遭遇"失忆症"

凡是用过Claude Code、Cursor或Codex CLI的开发者，大概都踩过同一个坑：复杂重构进行到一半，上下文窗口被撑爆，或者一次手动 /clear 之后，AI瞬间"断片"——之前的规划、决策、进度，全部归零。

**上下文窗口（Context Window）**是大语言模型在单次推理中能够处理的最大token数量。早期模型如GPT-3仅有4K tokens的窗口，而Claude 3系列已扩展至200K tokens，GPT-4 Turbo支持128K tokens。尽管窗口不断扩大，这一限制依然是实质性瓶颈——不仅因为窗口有上限，还因为随着上下文增长，模型的"注意力"会发生稀释，对早期信息的利用率显著下降（即学术界所称的"Lost in the Middle"问题：模型对位于上下文中段的信息处理效果最差）。

对于需要长时间持续执行的智能体（long-running agentic tasks）而言，上下文丢失几乎是致命伤。模型的记忆本质上是易失的，会话一旦中断或上下文被截断，前期积累的一切就烟消云散。GitHub项目 planning-with-files 正是为这个痛点而生——上线以来收获超过 2.4 万 Stars，单日新增 61 颗，足以说明社区对这一问题有多共鸣。

核心思路：把规划写进磁盘

项目的核心理念可以用一句话概括：用基于文件的持久化规划，取代脆弱的上下文记忆。

Manus 式的持久化策略

planning-with-files 自我定位为"Manus-style"（Manus风格），模仿 Manus 类通用 Agent 的核心做法——不把所有状态都塞进模型上下文，而是将规划、待办事项和执行进度以 Markdown 文件的形式落盘保存。

这套机制带来三个直接好处：

抗崩溃（Crash-proof）：进程崩溃、会话中断、上下文清空，规划文件始终静静躺在磁盘上，随时可重新读取恢复。
可读可审计：Markdown 是人类友好的纯文本，开发者随时可以打开文件查看 AI 的规划逻辑，甚至直接手动修改纠偏。
跨会话延续：新会话启动后，Agent 重新加载文件即可"记起"之前的工作，实现真正的任务接力。

这一设计呼应了 AI Agent 领域的重要范式：外部记忆（External Memory）。在认知科学对人类记忆系统的研究框架中，AI Agent 的记忆通常被分为四类：工作记忆（当前上下文）、情节记忆（历史交互）、语义记忆（知识库）和程序记忆（技能/工具）。planning-with-files 本质上是将工作记忆的一部分持久化为情节记忆，借助文件系统实现跨会话的信息延续。这一设计与认知架构领域的经典框架 ACT-R 和 SOAR 有深刻呼应，后者同样强调将工作记忆内容持续写入长期存储。与其和有限的上下文窗口硬碰硬，不如把文件系统当作 Agent 的"长期记忆"，让上下文只承载当前最相关的信息。

三大关键能力

1. 确定性的完成闸门

planning-with-files 引入了"deterministic completion gate"（确定性完成闸门）机制，专门对付 AI Agent 的另一个老毛病：过早宣称任务完成。

大语言模型的"幻觉"（Hallucination）问题不仅体现在事实错误上，还体现在任务执行的自我评估偏差中。研究表明，模型在自我评估任务完成度时存在系统性高估倾向，这与模型训练时的 RLHF（基于人类反馈的强化学习）过程有关——模型倾向于给出令人满意的答案而非准确的答案。

这套机制的做法是：以规划文件中所有待办项是否全部勾选为判定标准，强制 Agent 在收尾前逐项核对。判定过程基于文件状态，完全确定性，不依赖模型的主观评估——本质上是将"软判断"硬化为"硬约束"——因此更可靠，杜绝"虎头蛇尾"。

2. 多智能体共享状态

项目支持"multi-agent shared state on disk"，即多个 Agent 通过磁盘上的共享文件进行协作。

多智能体系统（Multi-Agent Systems, MAS）的核心挑战在于协调（Coordination）与一致性（Consistency）。传统解决方案包括消息队列（如 Redis Pub/Sub）、共享数据库或专用的 Agent 通信协议（如 FIPA-ACL）。而 planning-with-files 采用的"共享磁盘文件"方案，本质上是将文件系统作为一个简化的元组空间（Tuple Space），类似于经典的 Linda 并发模型——进程通过向共享空间读写数据来协调，而非直接点对点通信。这种设计极大降低了耦合度，同时天然提供了一个所有 Agent 都能读写的"公共黑板"，让协作过程透明可追溯。

3. 基于 SKILL.md 的广泛兼容

最值得关注的是其兼容性策略。项目通过 SKILL.md 标准宣称可与 60+ 种 Agent 工具协同，包括：

Claude Code
Codex CLI
Cursor
Kiro
OpenCode

SKILL.md 代表了 AI 工具生态中正在兴起的"能力描述标准化"趋势，与此类似的还有 Anthropic 推出的 MCP（Model Context Protocol）、OpenAI 的 Assistants API 工具定义格式等。SKILL.md 以 Markdown 文件的形式描述一个 Agent 工具的能力边界、调用方式和使用约定——这种"声明式能力描述"的思路，与软件工程中接口定义语言（IDL）和 OpenAPI 规范的设计哲学一脉相承。遵循这一标准后，planning-with-files 无需为每个工具单独适配，即可"即插即用"地融入现有工作流，大幅降低采用门槛。

为什么值得关注

抓住了 Agent 工程的真实痛点

2.4 万 Stars 不是偶然。当越来越多的开发者把 AI 从"代码补全"升级为"自主执行复杂任务"时，任务的可靠性与可恢复性成了核心诉求。planning-with-files 用最朴素的手段——文件——解决了一个真实的工程问题，这种"大道至简"的思路往往最有生命力。

简单即优雅

相比动辄引入向量数据库或复杂状态机的方案，用 Markdown 文件做持久化几乎零额外依赖，人人都能理解和调试。低复杂度反而带来高鲁棒性——文件系统本身就是操作系统级别高度可靠的基础设施，其可靠性经过了数十年操作系统工程的锤炼，POSIX 文件语义在绝大多数场景下提供了足够强的原子性保证。

对 Agent 工程师的启示

对于正在构建 AI Agent 的开发者，这个项目提供了一套可复用的设计模式：

不要把所有希望寄托在上下文窗口上；
将任务规划、执行进度和中间状态外化到持久存储；
用确定性检查而非模型自评来判定任务完成；
拥抱开放标准（如 SKILL.md），提升工具间的互操作性。

结语

planning-with-files 代表了 AI Agent 工程化的一个务实方向：与其追求让模型"记住一切"，不如设计一套让 Agent "忘了也没关系"的恢复机制。当规划变成磁盘上可靠、可读、可恢复的文件，AI 编程助手才真正具备承担长时间复杂任务的底气。对于追求可靠自动化的团队而言，这或许正是让 AI Agent 从"演示玩具"走向"生产工具"的关键一步。