给 AI Agent 加一层「项目记忆」：context.md 提案解读

独立研究者 Pavel Kerbel 在 Hacker News 发布了一份名为《Repository Context Layer》的提案，建议在代码仓库内增加一层由 Git 管理的「项目上下文」文件，让 AI Agent 在每次执行任务前可以读取、在执行后可以更新，从而摆脱「每次会话都从零开始」的失忆状态。提案以单文件 Markdown（默认路径 context.md）为载体，并附带 PDF、最小规范与示例。

问题的提出：Agent 的「失忆症」

Kerbel 认为，当前主流 Agent 在仓库中执行任务时面临一个结构性短板：它们能看到代码、测试、文档与配置，却看不到「为什么代码长这样」。

设计决策、被否决的备选方案、凌晨两点才排查出的边界条件，这些信息大多只存在于聊天记录和开发者脑中。
于是 Agent 会反复重提已被否决的方案，重新引入生产环境验证失败的抽象层。
这些不是模型能力的问题，而是「仓库里最贵的知识」——否定性知识（什么被试过、被拒绝）——没有标准载体可供 Agent 读取。

提案者将这种状况描述为「每次会话都要重新向同一个模型解释同一个项目」。

为什么现有方案不够

提案逐一回应了可能的反驳：

README 描述的是「如何使用」，而非「如何修改」，决策被推翻后通常没人更新。
ADR（架构决策记录）虽是最近的近亲，但定位是写给人类的一次性文档，Agent 没有强制阅读义务，更不被期望去追加内容。
RAG 按相似度检索，对「约束类规则」天然不利——约束往往在提示中毫无相似语义时才最关键。
IDE 记忆仅限单一工具、单一机器，无法进入代码评审。
Agent 指令文件（如 AGENTS.md）只能由人类向 Agent 单向传递，缺少 Agent 回写自身经验的通路。

Kerbel 总结：现有方案各自解决了一小片，但没有任何一种既「与代码一起版本化」、又「Agent 按约定必须读」、又「可在人工审阅下由 Agent 改写」。这一组合即是「缺失的那一层」。

提案方案：Repository Context Layer

核心定义：Repository Context Layer 是一个与代码一同版本化、人类可读的上下文存储，作为在该仓库内工作的 AI Agent 的权威运行上下文。它与 Git 共享同一个版本库，遵循 Git 的分支、合并、回滚与审计机制。

为强调与传统「记忆」概念的差异，提案者刻意区分了二者：

Memory：私人、模糊、可选，随会话消失。
Context：确定性控制平面，落盘、与代码同版本、地址固定，Agent 被要求读取并被期望维护。

提案还给出一句类似座右铭的口号：「Git 存的是改了什么；Repository Context 存的是项目知道什么。」

四步生命周期

提案定义的 Agent 使用上下文的契约分为四步：

Consult（读取）：在制定计划前先读上下文。没有先验的计划只是格式整齐的猜测。
Execute（执行）：将 Constraints 视为硬约束，将 Intent 作为开放式设计选择的裁决依据。
Update（更新）：把执行中学到的新知识追加进去——例如某个包破坏 ARM64 构建、某个代理超时无人记录。这是多数系统跳过的环节。
Commit（提交）：代码与精炼后的上下文一起进入同一次评审。

由于上下文与代码共用 Git，任何分支差异、合并冲突、回滚都会自然落到上下文上，不需要额外的同步机制。

设计原则与最小规范

提案列出了六条设计原则：人类可读（纯 Markdown）、可评审（Agent 修改自身规则时与代码同 diff，由人审批）、分支感知、工具无关（无需 SDK、无需服务器、无需特定厂商）、渐进演化（不必一开始就写满）、确定性发现（Agent 不用搜索就能定位）。

最小规范方面，提案建议默认实现为单一 Markdown 文件 context.md，发现顺序为 .repo/context.md 优先，其次为仓库根目录的 context.md。该文件至少需要包含三个章节：

Intent：项目是什么，以及所有其他决策必须服从的设计哲学。
Constraints：不可谈判的硬规则。
（第三章节在原文中被截断，提案者同时附上了 PDF 与 Minimal spec 链接供查阅。）

现状与局限

需要指出的是，这份提案来自独立研究者，目前没有大型厂商背书，也没有公开的 benchmark 或实际采用数据。与其思路相近、但由不同社区驱动的实践已经存在，例如 Anthropic 的 CLAUDE.md、GitHub 的 AGENTS.md 等。Repository Context Layer 的差异点在于更强调「Agent 在人工审阅下回写自身所学」这一双向机制，但能否被主流 Agent 框架采纳，仍有待观察。