第 37 章 Research Brief：Memory 与 Skill Design Patterns

要解决的工程问题

长期项目中的 Agent 很容易把三种不同东西混入同一处：本轮消息历史、可跨任务复用的项目知识，以及某个 Skill 的操作说明。这样做会让已经过期的推测在下一次检索中被当作事实，也会让只应读取证据的 Skill 获得写入“记忆”的隐式能力。本章研究如何把项目记忆、事件记录、决策记录、证据卡和技能契约拆成可组合、可审查的接口；重点不是增加更多存储，而是让每次读取、写入、升级、弃用都能说明责任和证据。

读者问题与范围

读者问题	本章研究的回答	本章不回答
消息历史、项目记忆和事件记录能否放在同一文件或同一存储里？	先按任务范围、稳定性、证据要求和写入授权划分职责；物理位置相同不等于它们应共享同一读取或写入规则。	为任意 Agent 框架规定唯一的数据库、目录、向量索引或保留期限。
怎样让检索结果不污染可复用知识？	把检索候选与可进入项目记忆的已审查结论分离，并保留来源位置、适用范围、新鲜度和拒绝理由。	仅凭相似度、模型摘要或引用 URL 自动证明内容真实、最新或适用于当前项目。
Skill 怎样复用又不耦合到某个项目的私有状态？	用技能契约声明触发条件、输入、允许读取的记忆类别、是否可以提出写入候选、输出证据与版本；将项目数据留在契约外。	某个 SKILL.md、元数据字段或产品发现规则会自动授予权限、隔离数据或完成审批。
旧记忆与旧 Skill 如何退出？	为本书模式设置所有者、版本、替代关系、迁移证据和弃用状态；读取方应能看到“不可用”而不是静默继承旧结论。	自动迁移、自动删除或跨团队兼容性的产品保证。

范围： 讨论可审查的 Memory／Skill 接口模式、读写分离、版本与弃用。章节会把第 7 章的记忆边界、第 8 章的 Skill 契约、第 33 章的项目记忆系统和第 34 章的团队 Skill Library 组织为同一套选型语言。

非范围： 不实现向量检索、嵌入、数据库、文件同步、权限系统、运行时加载器或具体 Agent 产品；不比较模型、供应商、价格、吞吐量、召回率或上下文长度；不把目录约定写成安全边界。

已核验的一手资料

本地键	来源明确表达的内容	允许用途	不可外推
CH37-REF-01	OpenAI Agents SDK 的 Sessions 在同一 session 的多次 run 间维护对话历史；运行前读取历史、运行后保存本轮项，且不能与服务端延续机制叠加。	将“本轮或会话历史”作为产品特有、范围明确的一类记忆背景。	任意项目记忆、跨任务知识库或组织决策记录都应采用此机制，或该机制自动解决历史污染。
CH37-REF-02	LangChain 将长期记忆描述为可跨会话和 session 保存、召回的数据，并以 namespace 与 key 组织 JSON 文档；其页面也将 thread 内短期记忆与跨 thread 的长期数据区分。	讨论范围标识和键空间是区分可检索记忆的一个框架例子。	命名空间本身保证租户隔离、授权、数据正确性、删除、隐私或任何其他框架行为。
CH37-REF-03	Agent Skills 规范要求最小 Skill 目录包含 SKILL.md，其中有 YAML frontmatter 与 Markdown 指令；规范把 metadata、正文和资源描述为渐进加载的层次。	讨论 Skill 的元数据、指令和按需资源可以分层，而不是把全部项目知识塞进主体指令。	所有 Agent 产品的发现、加载、工具授权、执行顺序或安全模型都相同。
CH37-REF-04	Claude Code 文档把 Skill 与常驻项目指令区分：Skill 主体在使用时才加载；其路径、覆盖和调用控制属于该产品的实现。	讨论“按需调用的过程指令”与常驻项目上下文应分开审查。	其他 Agent、任意版本或本仓库一定使用相同的路径、优先级、命令或动态加载行为。

访问日期均为 2026-07-16。CH37-REF-01 至 CH37-REF-04 已分别映射为 REF-020、REF-022、REF-024、REF-025；完整 URL、限定陈述与刷新要求见本章参考资料。产品文档、默认实现和版本化字段均可能变化；First Draft、Technical Review 与 Fact Check 必须在写作当天重新读取。

本书研究框架

下列模式卡是本书的工程模型，不是上述 SDK、框架、规范或产品的固定 schema。它们的目标是回答“谁可以在什么证据下读取或提出写入”，而不是把记忆层当作万能数据库。

模式卡	解决的问题	最小接口	关键限制
任务范围记忆（Task-Scoped Memory）	防止一轮任务的临时判断被误作项目结论。	task_id、输入摘要、临时观察、失效时点。	结束任务后不能自动升级为长期知识。
决策账本（Decision Ledger）	保留“为何采用此规则”及其适用条件。	决策、证据、所有者、日期、替代或复核条件。	历史决策不是当前事实，过期时应标为待复核。
证据卡（Evidence Card）检索	让候选材料可回到来源、范围和新鲜度。	来源位置、可支持主张、限制、访问日期、选择理由。	检索命中只产生候选，不产生可写入结论。
事件记录（Event Record）	记录某次观察、失败或人工决定，避免把运行状态改写成经验。	关联任务、时间、观察、证据位置、未知项。	事件不是根因、长期偏好或可复用规则。
只读 Skill（Read-Only Skill）	让检索、审查或摘要流程不能隐式改写项目知识。	允许来源、输入、输出证据、禁止写入声明。	“只读”不证明读取内容正确、完整或可信。
提议写入 Skill（Propose-Write Skill）	允许自动化整理候选记忆，同时保留人工或独立门。	候选内容、来源、变更理由、目标类别、审查状态。	产生候选不等于已经写入、批准或迁移成功。
版本与弃用（Version-and-Retirement）	防止旧契约和旧记录静默参与新任务。	版本、兼容范围、替代项、迁移证据、弃用日期或条件。	版本号不自动表示兼容、迁移已执行或旧数据可安全删除。

本章延用既有术语：长期记忆（Long-term Memory）、证据卡（Evidence Card）、检索策略（Retrieval Policy）和技能契约（Skill Contract）。如 First Draft 需要将“事件记录”或“决策账本”提升为全书术语，必须先由主线程检查 .ai/glossary.md 与前置章节，不能在 Research 阶段擅自改写共享词表。

教学案例、图示与示例计划

教学案例是一个虚构的“事实核验 Skill”。它可读取项目引用库和候选证据卡，为某句待核验陈述给出三种结果：证据不足、可供人工审查的候选结论、或因来源过期而停止。它只能产生“提议写入”的记录，不能自行修改项目记忆、全局引用、正文或发布状态。案例中的书名、URL、文件、账户、审核人和运行结果均为教学假设，不对应真实项目操作。

后续图示应画出四个不可省略的断点：任务范围记忆只能向当前任务提供信息；证据卡在读取后仍是候选；技能契约决定该 Skill 是只读还是提议写入；人工或独立审查门才可把候选结论送入决策账本或长期记忆。图不能把“检索命中”“Skill 被调用”或“写入请求返回”画成事实已经核验、记忆已经更新或外部系统已经执行。

后续最小示例应只评估注入的 Memory／Skill Pattern Card：检查 Skill 是否声明可读类别、禁止或限制写入、候选是否带来源和范围、弃用项是否被拒绝。Example Implementation 阶段才决定是否实现纯内存评估器与测试；本阶段没有运行 Skill、记忆系统、模型、网络、文件操作、检索、写入、审批或外部系统。

风险、非范围与后续核验

• 污染风险： 将模型摘要、测试输出、检索片段或人工猜测直接写入长期记忆，会使后续任务无法区分事实、候选和历史。First Draft 应要求写入候选保留来源、范围和审查状态。
• 耦合风险： 把项目路径、私密资料、一次性命令或隐式写入步骤嵌入可复用 Skill，会让迁移与审查失去边界。Skill 契约应只声明需求，项目适配层再提供具体资源。
• 陈旧风险： 决策、资料和 Skill 版本都会过期。弃用不是删除同义词；需要说明替代项、还未迁移的读取方以及何时停止使用旧项。
• 权限风险： 元数据、文件位置、命名空间和“只读”文字均不是执行环境的权限保证。实际访问控制、密钥、租户隔离、数据删除和审计留给第 35、41、42 章与具体运行环境资料。
• TODO(verify)： First Draft 写作当天重读 CH37-REF-01 至 CH37-REF-04，确认动态 SDK／框架／产品文档的 URL、版本、路径和加载语义；未复核时，不写入具体 API、默认值或产品比较。
• TODO(verify)： Example Implementation 前确认本仓是否已有可复用的纯内存模式评估器；没有时只创建无 I/O 的教学实现，并将所有真实存储、检索、权限和审批标为未执行。

下一阶段

Chapter Outline 应把模式卡拆成逐节论证：先区分会话、任务、项目和事件四类记录，再定义检索与写入门；随后用 Skill Contract 分别描述只读与提议写入；最后给出版本、迁移和弃用检查表。每节必须标出允许使用的来源、教学案例、本书工程模型、最小可观察证据和不能据此主张的结论。