session-memory

会话记忆（必须遵守）

概述

CC10X 记忆由一个小巧、稳定、带版本的 Markdown 索引和持久化工作流产物构成。 它的作用是在上下文压缩后继续发挥作用、保留决策，并让不同会话中的 BUILD / DEBUG / REVIEW / PLAN 保持一致。

记忆是索引，不是对话记录。 简明扼要。将决策、经验、引用和验证证据提炼成持久、可复用的笔记。

参考索引

将此文件作为控制平面。只阅读所需的参考资料：

• references/memory-model-and-ownership.md：记忆层、所有权、晋升流程和工作流标记
• references/memory-operations.md：无需权限的操作、仅由路由器负责的持久化，以及定向编辑模式
• references/memory-file-contracts.md：必需标题、稳定锚点、模板和自动修复规则
• references/context-budget-and-checkpointing.md：上下文预算规则、警示信号和检查点触发条件

铁律

EVERY WORKFLOW MUST:
1. LOAD memory at START and before key decisions
2. EMIT memory-worthy notes before finishing
3. LET the router/workflow finalizer persist markdown memory

如果跳过记忆，工作流就会依赖对话。 如果只叙述记忆而不加以提炼，就会使上下文臃肿、丢失关键信息。

关键边界

• 记忆存放在 .cc10x/ 下。
• 路由器会在路由或恢复前加载并自动修复记忆文件。
• WRITE Agent 会读取记忆，但不得直接编辑 .cc10x/*.md。
• WRITE Agent 会在其 Router Contract 中输出结构化的 MEMORY_NOTES。
• 只读 Agent 会输出 ### Memory Notes (For Workflow-Final Persistence)。
• 由路由器负责的 memory-finalize 任务是最终写入记忆 Markdown 文件的唯一执行者。
• 持久化前先编辑敏感信息/个人身份信息（仅限对外产物）：路由器将任何由 cc10x 编写的内容持久化到对外产物之前——docs/plans/*、docs/research/*、设计文档和持久化记忆笔记——应编辑 MEMORY_NOTES 或只读 Agent 笔记中记录的粘贴令牌、API 密钥、连接字符串、凭据和个人数据。替换为稳定的占位符（例如 <redacted:secret>），并保留周围的约束。这针对的是编写的内容，与文件级“绝不提交 .env”规则相辅相成。此规则仅适用于对外产物，明确不适用于内部、由机器管理的 .cc10x/ 编排状态（workflows/{wf}.json、.events.jsonl、路由器标记），这些内容必须保持原样，以确保恢复和去重键正常工作。
• .cc10x/workflows/{wf}.json 下的工作流产物是持久化的执行事实；Markdown 记忆是稳定索引。
• 必需的标题和锚点是契约。不要自行设计新的文件布局或标记方案。
• [DEBUG-RESET: wf:{...}] 和 [cc10x-internal] memory_task_id 等由路由器管理的标记会被 Agent 读取并遵守；Agent 不得自行创建替代标记。

记忆层

针对不同类型的信息，使用合适的层：

• activeContext.md：当前重点、近期变更、决策、经验、引用、阻碍
• patterns.md：可复用的项目标准、易错点、约定和技能提示
• progress.md：当前工作流、任务快照、已完成事项、验证证据
• docs/plans/* 和 docs/research/*：详细产物；记忆中记录其引用
• .cc10x/workflows/{wf}.json 和 .events.jsonl：持久化编排事实

如果需要了解完整的所有权模型或晋升流程，请阅读 references/memory-model-and-ownership.md。

精炼规则

记忆条目必须经过精炼，而不是叙述。

保留：

• 有理由支撑的决策
• 因果性经验
• 稳定的模块边界和文件路径
• 验证命令及其退出结果
• 下一轮需要用到的外部产物路径

剔除：

• 装饰性文字
• 逐步记录的过程
• 尚未解决的推测
• 对提示词的冗余复述
• 除非是不变定位信息，否则剔除不稳定的行号

检验：

如果新的 Agent 只阅读记忆，无法在不重读整个对话的情况下还原当前约束和下一步行动， 那么这份记忆就不够精炼。

要加载的内容

始终加载

在工作流开始、继续或恢复时，阅读全部三个记忆文件：

.cc10x/activeContext.md
.cc10x/patterns.md
.cc10x/progress.md

执行以下操作前重新阅读

操作	重新阅读	原因
架构决策	patterns.md + activeContext.md ## Decisions	避免与项目标准相矛盾
选择实现方案	patterns.md + activeContext.md	遵循惯例和近期决策
调试	activeContext.md + patterns.md + progress.md	重用先前的尝试、注意事项和证据
规划后续步骤	progress.md + activeContext.md	避免重复工作并保持顺序
声明已完成	progress.md + 当前计划／设计／研究参考资料	确认依据和范围仍然一致
用户说“继续”	全部三个文件	恢复持久状态，而不是聊天摘要

文件选择矩阵

需求	阅读
当前重点／阻碍	activeContext.md
先前的决策／理由	activeContext.md ## Decisions
已知注意事项	patterns.md
项目惯例	patterns.md
已完成／剩余事项	progress.md
证明命令及退出结果	progress.md ## Verification
详细计划／研究	activeContext.md ## References，然后阅读所引用的文件

要持久化的内容

仅输出值得记录在记忆中的内容：

• 会改变实现方向的决策
• 可避免重蹈覆辙的经验
• 包含命令及退出结果的验证证据
• 应延续到后续会话的非阻塞事项
• 后续工作流必须遵循的计划、设计或研究参考资料
• 应成为持久项目惯例的、已明确的用户标准或规范

不要持久化：

• 整个差异
• 冗长的执行日志
• 庆祝性叙述
• 没有证据支撑的“看起来正确”之类的说法
• 不增加新约束的重复笔记
• 面向外部产物的笔记中包含的原始机密信息／个人身份信息（PII）——在这些内容进入文档／计划／研究资料或持久记忆前，先删去令牌、密钥、连接字符串和个人数据（在内部 .cc10x/ 状态中保留身份／密钥字段原样）

Agent 输出约定

WRITE Agent 通过 Router Contract 持久化记忆：

MEMORY_NOTES:
  learnings: ["Key causal insight"]
  patterns: ["Reusable gotcha or convention"]
  verification: ["`npm test` -> exit 0"]
  deferred: ["Non-blocking follow-up or risk"]

规则：

• 尽可能让每条内容保持一行。
• 优先使用稳定的名词，避免临时措辞。
• 将验证结果放在 verification 中，而不是叙述性文字里。
• 将非阻塞的后续工作放在 deferred 中，而不是临时任务中。
• 如果未能加载互补技能，或缺少重要的持久产物，请在 learnings 或 deferred 中注明。

只读 Agent 使用自己的 ### Memory Notes (For Workflow-Final Persistence) 部分， 但路由器会将这两种格式都写入同一份最终记忆更新。

项目技能提示

加载记忆后，检查 patterns.md ## Project SKILL_HINTS。

• 相关且已安装的技能应在加载记忆后调用。
• 缺少技能不构成阻碍；如果这影响了工作流，请在值得记录的输出中注明。
• 不得臆造或改写此技能中的技能 ID。
• WRITE Agent 不得通过直接编辑记忆来“维护” ## Project SKILL_HINTS。如果有重要的持久建议，请在规划器输出或提供给路由器持久化的记忆笔记中提出。

工作流模式

开始

1. 阅读全部三个记忆文件。
2. 仅当工作流需要时，才从 activeContext.md ## References 中读取当前计划、设计或研究文件。
3. 加载记忆后，从 ## Project SKILL_HINTS 加载已批准的项目／领域技能。
4. 如果上下文已经变得过于庞杂，请使用 references/context-budget-and-checkpointing.md。

期间

• 在作出关键决策前重新阅读记忆，而不是犯错后再读。
• 遵守路由器负责的标记，例如 [DEBUG-RESET: wf:{...}]。
• 保持笔记精炼，以便在压缩后仍能保留。
• 优先使用持久化工件和文件路径，而不是冗长的对话摘要。

结束

1. 将决策、经验、验证结果和待办事项提炼到 MEMORY_NOTES。
2. 确保每条笔记都客观且可复用。
3. 假定路由器／工作流终结器会持久化 Markdown 文件。
4. 如果记忆周期尚未完成，不要声称工作流已真正完成。

上下文预算与检查点

长时间会话会在明显失败前逐渐退化。

遇到以下情况时，请使用 references/context-budget-and-checkpointing.md：

• 调试过程中已多次尝试但均未成功
• 规划／研究涉及许多大型文件
• 会话中已经累积了许多工具调用
• 你注意到表述含糊、跳过协议步骤或不确定性增加

检查点原则：

• 将持久状态保存到工作流工件、计划、研究文件和记忆笔记中
• 不要依赖对话记录来承载关键上下文

压缩内容的保留／概括／丢弃规则

cc10x 的压缩后状态保留机制基于结构——状态存储在 .cc10x/ 中。但原生压缩可能在某个阶段中途触发，早于路由器完成持久化；仅留在对话记录中的内容可能会被悄然丢弃，随后导致相关要求被悄然违反。请使用以下规则对对话记录内容进行分类：

层级	内容	规则
保留	用户的硬性约束和禁止事项（“不要改动 Y”）、确切的下一步、未解决的问题及其错误信息	原文保留——绝不改述约束或错误信息
概括	已解决的决策及其理由、已结束的尝试、发现的文件／模块边界	每项精炼为一条持久记录
丢弃	装饰性文字、逐步日记、已被取代的猜测、冗余的提示复述	丢弃

用户明确提出的禁止事项，应在提出后立即以原文保存到工作流工件的意图字段（.cc10x/workflows/{wf}.json）中，而不是等到工作流结束。这样，即使压缩发生在路由器按常规持久化之前，优先级规则（明确的用户指示优先）也能保留下来。如果暂时无法持久化，就将保留项原文置于工作上下文顶部，直到路由器可以完成最终持久化。

危险信号

如果发现自己正在做以下事情，请停止并纠正方向：

• 未加载记忆就开始工作
• 未检查 ## Decisions 或项目惯例就作出决策
• 撰写冗长的日记式记忆笔记
• 声称会“稍后记住”
• 让写入 Agent 直接编辑 .cc10x/*.md
• 臆造新的标题、标记或记忆文件结构
• 将过时的对话上下文视为比持久化记忆更可靠

防止自我合理化

借口	事实
“任务很小，不需要。”	小任务也会产生决策和证据。
“我会记住的。”	你不会；压缩会占上风。
“对话里已经有了。”	持久化记忆胜过对话记录中的信息。
“我直接改一下 Markdown 就行。”	路由器负责的持久化机制是为了保持记忆连贯。
“笔记详细一点也没关系。”	冗长的笔记会消耗上下文并掩盖重点。

验证清单

• 工作流开始时已加载记忆
• 做出新决策前已检查相关决策／模式
• 已将笔记提炼到 MEMORY_NOTES
• 已以值得记忆的形式记录验证结果
• 写入 Agent 未直接编辑 .cc10x/*.md
• 如果会话负担较重，已考虑进行上下文预算检查点

无法勾选这些选项？记忆循环尚未完成。