memory

name	memory
description	管理会话记忆的读取与写入。三层记忆体系：Agent 日记 / 需求记忆 / 项目总记忆。

文件路径

<active-root>/.memory/clients/<agent>/tasks/YYYYMMDD.md

MCP memory scope（workspace-namespace）

• <agent> 确定规则（优先级从高到低）：

  1. 当前实际宿主（优先）：以当前会话/工具链可验证的宿主事实为准，产物必须写入对应宿主目录，例如当前在 Codex 中执行时写 .memory/clients/codex/，不得被历史 profile 覆盖。
  2. Profile agent 兜底：仅当当前实际宿主无法可靠判断时，才读取 .devcodex/profile/config.json 的 "agent" 字段作为 fallback hint；它不能覆盖当前会话事实。
  3. 无法判断：写入 unknown-agent，并在报告或记忆中记录宿主无法识别的原因。

  枚举值固定，全部小写连字符分隔：

  • Copilot in VS Code：copilot 或 vscode-copilot
  • Claude Code（CLI/桌面端）：claude-code ⚠️ 禁止使用裸 claude（与 Claude API/Claude.ai 区分）
  • Codex：codex（通过 AGENTS.md / .agents/skills/ / .codex/hooks.json 适配）
  • Cursor IDE：cursor
  • JetBrains Copilot：jetbrains-copilot
  • Grok Build / Grok CLI（xAI）：grok（DEVCODEX_AGENT=grok 或 GROK_AGENT 等；禁止长期误绑 codex）
  • 无法确定：unknown-agent（运行时不得默认 claude-code）
  4. 写入约定：devcodex profile init 生成 config.json 时可以写入当时探测到的 agent 作为兜底提示；devcodex init / devcodex init --claude / devcodex init --codex 只负责分发规则与运行时文件，不直接生成 profile config。
  5. 冲突处理：若 profile agent 与当前实际宿主不同，Agent 日记、SUMMARY、报告路径均按当前实际宿主写入，并在 PC0/doctor/报告中提示差异。

• ⛔ 禁止使用 shell 命令（bash find、PowerShell glob）查找记忆文件（shell glob 会跳过隐藏目录）

• 必须使用宿主文件工具（Copilot: list_dir；Claude Code: Read/Glob；Codex: 当前可用的文件读取/搜索工具）逐层进入：clients/ → <agent>/ → 读取日期文件

读取策略

MemoryContextQueryGate

记忆读取必须绑定当前 ContextReadPlanV2（兼容 ContextReadPlanV1），先取带 ContentIdentityV1 的结构化状态，再按 continuity 精确查询；“必须复证文件真相”不得实现成固定全文读取。

memory_status、memory_summary_query 与 memory_session_query 可在 source metadata 和 pointer/manifest 校验通过时使用 <active-root>/.runtime-state/derived-indexes/v1/memory/** 的 status/current/month/day byte-range 分区。该索引不是记忆真相源：

• 受管 memory writer 只有在 canonical 文件提交成功后才刷新索引，pointer 最后写并回读。
• source metadata 漂移、schema/digest 损坏、锁竞争或索引缺失时必须回退既有 parser；允许返回 additive indexReceipt/coverage，不得改变旧字段、排序或错误。
• query 与 fallback 均保持 zero-write；不得为了修复索引在读取阶段创建或改写 memory 文件。
• byte-range 或截断结果只能证明已返回范围，不能声明完整 daily/SUMMARY 正文已验证。
• memory_session_query / memory_summary_query 首次可省略 cursor；有安全下一页时读取 MemoryPaginationV1.nextCursor，并把 opaque MemoryCursorV1 原样回传同一 tool。cursor 绑定 tool、target/activeRoot、ContextRead binding、query、source identity 与 offset；绑定或来源变化必须稳定拒绝，禁止静默重置到第一页。partial source 不得签发不安全的下一页 cursor。

场景	读取范围	执行顺序
命名续接 · 首步	完整消息为 继续<任务名>任务 / 继续 <任务名> 时调用 memory_task_resolve(name, project?)；只取 identity/session/CP metadata 与结构化结果	先于通用 resume 查询
命名续接 · 唯一 active	定向读取该任务 .memory/task.json、.memory/sessions.md、当前绑定 artifact/checkpoint；执行 SemanticContinuationDiff	resolver 只定位，不替代复水化
正常会话 · 首步	memory_status(limit <= 5)，只返回今日/昨日 metadata、有限 SUMMARY 行、active 状态与冲突	第一读
正常会话 · 连续性相关	memory_summary_query(status: active/unresolved, limit <= 5)	status 证明需要时再读
intent = resume · 首步	memory_status(limit <= 5)	第一读
intent = resume · 精确恢复	memory_session_query(date/sessionId/status, limit: 1, handoffOnly: true/false, maxChars: 有界)；已知存在卡片时只取 handoff，否则取单个 bounded session，再定向读取需求 sessions、报告或 checklist	第二读
resume · 宏观补充	memory_summary_query(status: unresolved, limit <= 5)	精确 session 不足时
文件不存在 / 旧格式 / 解析失败	bounded empty + warnings；保持 partial/unverified，读取零写入	禁止自动 rename / create
intent = resume · 当前项目无 🔄	告知用户最近任务均已完成（引用最后会话摘要），询问是否切换项目或开始新任务；禁止静默回退旧任务	—
resume 超 14 天	memory_summary_query(status: unresolved, since/limit) 定位 → 提示日期/会话编号 → memory_session_query 精确读取	—
用户明确要求历史回溯	同 resume	—

ConcurrencyPolicy：记忆读取可作为只读通道并发执行；记忆写入、SUMMARY 更新、ContextHandoffCard、任务准入/owner/terminal 和会话状态提交必须按 memory 单写者锁串行完成。

requirement-parallel-orchestration：并行子会话只能把 RequirementIndependenceDecisionV1、ParallelLaunchCardV1 或局部验证证据交回主会话；需求级 sessions、Agent daily、SUMMARY 和 ContextHandoffCard 仍由主会话按 memory 单写者锁串行写入。

TaskRouteAdmissionGate

• WorkspaceSessionRouteIndexV1 只保存有界 live route hint，不保存 CP、approval、artifact/validation authority；命中它只能帮助定位。ProjectTargetLeaseV2 必须继续复证 session/turn、canonical roots、layout/root identity、context 与 route revision。
• 新正式任务使用 memory_task_admit_v2 读取不可变 AdmissionIngressSnapshotV1 并进入可恢复 TaskAdmissionTransactionV1，由服务端生成/复用 ingress idempotency key，create-if-absent 并回读 TaskIdentityV2、canonical overview/问题概况与 CP pending，在同一 MCP 调用内 acquire owner 并 finalize admission。相同 ingress 重放为同一 task/owner；若上一轮在阶段效果落盘后失败，同一请求必须先精确 readback 已存在内容，匹配则以 TaskAdmissionReconciliationReceiptV1 恢复到完整前缀并幂等补齐缺失文件，任一 drift 保持失败关闭，不要求用户复制新的授权句。兼容分步调用只可使用 task/project/root/session/route 绑定、短时、单用途的 AdmissionContinuationLeaseV1，owner 成功后立即 consumed；禁止通过永久保留完整用户原文或手改 lifecycle-state 续接。displayName、目录名、mtime、模型摘要或手工文件不能替代准入。TaskIdentityV2 的 root digest 仅保留首次准入 provenance；迁移后仍须先通过完整 schema/core/identityDigest 校验，只允许相同 taskId + project + taskRootRelative 在当前 active-root containment 与新 ProjectTargetLeaseV2 下重新准入，旧根热态和 authority 不可继承。
• 原子准入取得的 owner 在 CP pending 时不授予 mutation authority。CP confirmation 成功后，若 owner receipt 尚未观察到当前 CP，使用 memory_task_write_owner renew 对 FencedTaskWriteOwnerLeaseV2 做 generation/nonce/CAS 与 CP readback。每次 claim/transition 的公共回执必须带 V5 readback 生成的 CanonicalTaskWriteContextV1；正式 writer 绑定其 task/root、lifecycle revision、state sequence、writer generation、holder session、operation/settled set digest、runtime generation 与 context digest。正式 mutation 只有 finalized admission + exact CP + active owner + fresh write context 才可继续。TTL 只作诊断和清理，不能转移写权；handoff/takeover/reopen 必须形成新 transition receipt，旧 nonce 永不恢复 authority。
• 简单任务只能调用 memory_task_fast_path_lease 取得 SimpleTaskFastPathLeaseV1，最多 2 个同一边界 exact 低风险路径、最多 2 次 create-or-update；正式产物、公共契约、控制面、安全、依赖、发布、跨模块或第 3 个路径在写入前升级正式准入。低风险叙述型 Markdown 可走 dev.docs 轻路径，但配置/API/schema/security/release 文档属于公共契约，不可借此绕过。
• 正式任务终态调用 memory_task_terminal_v1，精确提交当前 write context 的 lifecycle revision、state sequence、writer generation 与 settled-set digest，并以 ECR/report/memory/completion 四个互不复用的证据 identity 写 terminal receipt；未结算/待 reconcile operation、stale fence 或证据漂移都必须零终态提交，相同 replay 零新写。成功后 route/owner 立即解绑。Stop/PreCompact 仅 checkpoint，不等价 terminal。
• 每次正式 artifact mutation 必须先持久化唯一未结算的 TaskOperationRecordV1：prepare 绑定 idempotency key、writer generation、expected state、exact targets 与 before digest，dispatch 后 effect unknown 禁止自动重试，observe 后只能 settle 或进入 reconcile-required。工具返回失败、authority closeout 漂移、partial observation 或零效果进入 时，调用 。完整 observation 直接复证 effect；partial/零效果必须消费 V5 预写保存的 ，从完整 pre-observation 对同一 footprint 重新观察。Tool 还必须复证当前 server-owned ingress、同 session formal route、同一 operation record/closeout CAS、primary 或 emergency reserve 来源，以及普通文件系统快照；只生成 并关闭既有 pending 状态，不执行文件 mutation、不授予权限或 mutation authority。reserve 仅可把主槽中同一 dispatched/observed record 推进到 reconcile-required，并继续匹配 decision、lease 与 footprint；压缩 projection 必须保留 recovered effect 集合供后继消费者验证。

MemoryTransactionWriterGate

当可用 MCP memory writer 时，Agent 不得再用“读取 daily 尾号 → 自行计算会话编号 → 直接编辑 daily/SUMMARY 多文件”的方式作为首选写入路径。

• 新会话必须优先通过 memory_session_allocate(project, date, title, intent, sourceMessage) 原子分配；该工具会在 active-root / agent / date 作用域内持有 writer lock，并写入 reserved daily 段，返回含 sessionId、不透明 sessionBinding 与 transaction 的 MemorySessionAllocationReceiptV1。
• 每次 memory_session_write 都必须原样回传同一 allocation receipt 的 sessionId + sessionBinding。writer 只允许内容进入该绑定会话段，并用 MemorySessionWriteReceiptV1 证明绑定已验证、目标段已变化、非目标段未变化与落盘读回一致；缺字段、错配、目标不存在、无目标、未知参数或超出 262144 字符上限均须零写入失败。旧版无 binding marker 的 daily 会话保持可读但不可继续无绑定写入；需要续接时自动分配一个新的绑定会话，禁止让用户执行额外命令。
• memory_session_allocate、memory_session_write、memory_summary_append 与 CP 状态写入共用 MemoryFileTransactionV1 owner，并必须返回 MemoryFileTransactionReceiptV1：除 activeRoot/agent/file/beforeDigest/afterDigest/transactionId 外，还包含 final CAS、file/directory flush、readback、bytesRead/bytesWritten/writeAmplificationRatio 与 metadata receipt；新会话写入还必须包含 MemorySessionWriteReceiptV1。锁键必须使用 canonical physical active-root + target path。已有文件的纯 EOF 增长走 append fast path，创建走 atomic temp+rename，中段更新才 rewrite；CAS 冲突返回 MemoryTransactionConflictReceiptV2，仅同一 reconcileIdentity 的纯操作可基于当前内容重算并重试一次，语义前置条件变化或第二次冲突零覆盖失败。无法从文件系统证据识别外部 writer 时保持 UNVERIFIED。POSIX 保留 mode/uid/gid 且新文件 0600，Windows DACL 未实证时必须保持 WARN/UNVERIFIED。报告/记忆可引用 receipt，而不是只写“已追加”。
• 上述四类 writer 是 server-owned 单一事务 Owner：Hook 仍校验实际指令、项目/session route 与 PC0～PC10 产物时序，但不得再把其逻辑 URI 套入通用文件 TaskOwnedMutationLeaseV2 / needs-reconcile。memory_workflow_operational_write_lease 等 authority-control Tool 只描述后继权限并由服务端核验 ingress，也不得自消费 artifact mutation authority。直接名、mcp__devcodex_memory__*、mcp__devcodex-memory__*、devcodex-memory/* 与 devcodex-memory__* 必须归一为同一 leaf；未知第三方同名 Tool 不能借此豁免。
• 遇到 MEMORY_TRANSACTION_LOCKED 时，当前写入方必须重读 memory_status / memory_summary_query 后重试或降级为阻塞说明，禁止忽略锁继续手工写同一文件。
• MCP 能力不可用时才可使用宿主增量编辑 fallback：必须以高熵唯一 sessionId 在一次增量编辑中追加“新会话标题 + 本次完整正文”，禁止向任何既有会话段追加；写前后核对 daily 与 SUMMARY digest，检测到并发变化则重读后换新 ID 重试一次，仍冲突即阻塞，并在报告/记忆标记 memoryWriter=fallback。MCP 已返回 binding/target/layout/lock 错误不属于“能力不可用”，禁止绕过 Tool 改用手工写同一 daily 文件。

TaskRecoveryStoreV5

边界	规则
正式任务数量	无计数硬上限；不能用 owner/session 数量裁剪需求或 Bug
hot	每个正式 task 使用稳定 A/B；语义不变返回 semantic-noop，普通 Hook/工具状态变化不得新建 UUID generation 文件
cold	仅在 canonical truth 可重建且 checkpoint 安全时保留有界 resume stub；不得删除正式 task docs、identity 或用户产物
terminal	durable closeout 后立即退出 live route/owner；grace 只读，达到安全退休条件后只回收 V5 runtime cache
soft 256 MiB	先退休 terminal、coldify 非活跃 hot、再回收可重建 runtime stub
hard 512 MiB	bounded safe reclaim 后仍超限则拒绝新 admission/普通 mutation；read/recovery/terminal/abort/reconcile 保持可用
closeout reserve 8 MiB	只用于 terminal/abort/reconcile；耗尽明确失败，禁止旁路普通 mutation
legacy generations	只读兼容；维护只能处理当前任务明确纳入且有 ownership 证据的对象，实际删除权限由宿主策略决定

V5 的 durable 段只保存 admission、fenced owner、TaskRecoveryCommitFenceV1、TaskOperationSetV1、mutation preflight/closeout 与 validation terminal 等有界恢复投影，不复制文件正文或大 stdout。所有正式 envelope commit 必须精确匹配 state sequence + writer generation，force 不得绕过 stale fence，writer generation 只可在受控 owner transition 中增加 1。容量压力不是任务数量上限，也不能成为删除用户任务产物的理由。

ArtifactLinkProjectionGate

• 新增本地 Markdown 关联前，先调用 memory_artifact_link_project(operation: "project", documentPath, artifacts, linkCapability)。documentPath 与每个 targetPath 必须相对 active-root；目标必须是 canonical/reparse containment 校验通过的现存普通文件。ArtifactLinkProjectionSetV1 按 canonical path 去重，以目标文档目录为基准生成 / 分隔相对 href，空格使用 Markdown angle destination；禁止 file://、绝对路径 fallback 与越界链接。
• 推荐写入面直接传结构化字段：daily 使用 memory_session_write.artifacts[]，Agent SUMMARY 使用 memory_summary_append.reportArtifact/memoryArtifact，CP 继续传 digest-bound artifactPath。writer 必须返回投影及 validate-existing readback；SUMMARY 第 5/6 列和 CP artifactPath 单元格由 writer 生成，不能由调用方拼接不受校验的链接。
• 宿主增量编辑 fallback 也必须遵守“先 project、后 write、再 validate-existing”。legacy raw content/row 可继续写，但其中新增的本地 Markdown 链接必须从当前 document 解析且指向 active-root 内现存目标；broken link、file://、绝对/越界/reparse 链接零写入失败。历史 active-root 链接只能先产出有界预览，未经单独确认禁止批量改写。

MemoryCannotSatisfyBootstrapGate

宿主或产品内置的 Memories、模型长期偏好、对话摘要、ContextHandoffCard 或 SUMMARY 都不能替代当前文件真相源读取：

• Memories 只能提示“可能要看哪里”，不得替代 bounded Profile plan、memory_status / memory_session_query / memory_summary_query、需求级 sessions、报告、review checklist、源码或文档的实际读取结果。
• 新线程、resume、summary 恢复、compact 后继续或跨项目切换时，必须重建 context epoch 与计划并重新查询必要来源；不能因为模型“记得上次任务”就跳过复证，也不能因此默认全文读取。
• SUMMARY 是索引，ContextHandoffCard 是交接卡；二者都不能覆盖 daily tasks、已确认需求/问题产物、报告和当前源码真相。
• 报告或最终回复若引用 Memories 辅助判断，必须标记为 navigation-hint，并列出完成真实读取的文件证据；无法读取时写阻塞 / 降级，不写通过。

⛔ 禁止默认读取完整 SUMMARY、完整 daily tasks 或昨日以前正文；精确 resume 查询与用户明确要求除外。 ⚠️ 旧 memory_session_read / memory_summary_read 仅作兼容；no-args 全文读取不是生产默认路径，也不能单独把 ContextReadReceiptV2（或兼容的 ContextReadReceiptV1）推进到 relevant-complete/completed。ContextSnapshotV1 只绑定 planContentId 与有序 source final identity，ContextObservationLeaseV1 才绑定 epoch/session/turn；同 session 普通轮次且 snapshot 稳定可重新绑定，compact/stale、跨 session 或 source drift 必须重读。记忆 projection 的 telemetry 不进入内容身份，cache hit 也不等于当前模型已观察正文。 ⛔ 禁止静默回退：resume 意图检测到当前项目无 🔄 任务时，禁止静默选取历史旧任务继续；必须明确告知用户当前状态并询问意图。 ⚠️ 跨项目 resume：无任务名的普通“继续/恢复”仍只使用当前项目的 WorkspaceSessionRouteIndexV1 hint 与有界记忆，当前项目无 live/🔄 时须询问；完整 继续<任务名>任务 可通过 workspace 派生索引做有界 exact 定位，但同名、规模超限或非 active 状态必须停止消歧，不能猜测。两者都不产生 mutation authority。

ConfirmBindingGate（CP 确认）

memory_cp_confirm 必须传入当前 artifactPath + artifactSha256，并对磁盘文件重算 digest；缺少任一绑定字段返回 MEMORY_CP_CONFIRMATION_UNBOUND、零写入且不得生成伪 ✅：

1. 先完成 对该 artifact 的全部编辑；
2. 再 对当前文件计算 sha256（PowerShell: Get-FileHash -Algorithm SHA256）；
3. 立即 memory_cp_confirm，禁止使用编辑前的旧 hash。

mismatch 错误含 nextStep：改完 rehash 再 confirm。Grok 状态条因此次失败计 1 failed 属工具 outcome，重试成功后任务仍可继续。

packageRoot vs activeRoot（Track Q）

根	含义	典型内容
packageRoot	源码包（如 devcodex/）	package.json、mcp/、scripts/、index.js
activeRoot	.devcodex/<project>/	requirements、reports、.memory

读实现代码用 packageRoot；写需求/记忆用 activeRoot。禁止默认 read_file(.devcodex/**/index.js) 当 package 入口。

写入规则

时机	动作
收到首条消息	创建/追加会话段落，状态 🔄
每轮交互	追加对话记录到 📨 字段
子任务完成（多任务）	追加 T{N}进度：✅
正式复审状态变化	只投影 ReviewStateSnapshotV1 的 snapshotDigest/nextAction/counts；不得在 memory 独立重算 open/blocker/stale/unreviewed
超 13 轮预警（C08）	写编码检查点到当前段落
报告写入后	追加报告路径到 📄 关联报告
完成回复前	确保 📨 对话记录已追加本轮
正式任务结束	memory_task_terminal_v1 四证据 closeout 与 route/owner unbind 成功后状态更新为 ✅；失败保持 🔄/needs-reconcile

约束：

• 🔴 禁止询问用户"是否需要写入记忆"（C05/S05 自动写入）
• 追加段落时优先使用 memory_session_allocate + memory_session_write 事务写入；MCP 不可用时才使用增量编辑 fallback，禁止覆盖已有内容（C06/S04）
• 禁止使用 Set-Content 等命令修改 .md 文件（C09）
• 写入报告路径、ContextHandoffCard 或 artifact-links 前执行 ArtifactLinkSetDedupeGate：同一物理文件按 canonical path 只保留一个主引用，并按 ArtifactLinkProjectionGate 完成写前 project 与写后 validate-existing。session、daily、SUMMARY、task state 和 checkpoint 必须进入 ArtifactDeliveryManifestV1，但默认 internal-only；只有 resume/handoff、状态冲突、写入失败、审计取证或用户明确要求时进入 UserFacingArtifactSetV1。
• 需求修订、再次复审、宣布“可确认 / 暂不通过 / 已修订待复审”或从修复清单回写真相源时，记忆写入必须配合 RequirementVerdictStateSyncGate：daily tasks、需求级 sessions 和 SUMMARY 的状态口径不得与需求真相源顶部状态、推荐结论、修复清单或 audit-state decision 冲突。

新会话 🔄 检测

新会话开始时调用 memory_status 检查今日/昨日 metadata、有限 SUMMARY 行和状态冲突；发现 active / unresolved 候选后，才用 memory_session_query(limit: 1) 取得对应片段：

• 有 🔄 → 输出提示：⚠️ 上次存在未完成任务：[简述]，建议先 resume
• 用户说"继续"/"恢复" + 存在 🔄 → 判定为 resume

会话字段

必填

字段	说明
🎯 任务摘要	本次任务的核心目标和意图
状态	🔄 进行中 / ✅ 已完成（v1.9.4+ 必填且单独成行，作为 PC7 新会话首步检测的唯一权威标记）
📨 对话记录	四列表格：`轮次
📋 任务清单（多任务会话 ≥2 时必填，v1.9.4+）	顶部小节列出本次会话所有独立任务及进度，格式：T1 [任务摘要] ✅/🔄/❌ 每行一项 — 解决 M2 多任务进度散布表格中难以快速追踪问题

按需（有内容时写入）

字段	说明
📄 关联报告	报告文件路径表格（含链接）
💡 关键决策	本次会话中产生的重要决策
⚠️ 待跟进	未完成事项或下次需要继续的内容
📦 编码检查点	编码任务且变更 ≥3 文件时
🧭 HostCapabilityRoutingRef	命中时记录 instructionRefId / decisionId / authority / digestStrength / selectedPortableDecision / nativeEligibility.status / fallback.reasonCode；只存 bounded projection
🧾 Governance Intake	candidate IDs、assessmentVerdict、generalizationScope、existingRuleState、复合 record intents、target ledgers、write requirement/evidence、verification state；只存最小锚点，不复制完整 prompt
🔎 ReviewState	planId、snapshotDigest、stage、reviewClass、open/blocker/stale/unreviewed、saturation、nextAction；正文以 review checklist/runtime 为准

HostCapabilityRoutingRef 不得复制完整用户原文、附件正文或 catalog row。confirm、compact、resume、host/session/task 变化后，若只剩 compat/none、conversation-visible 或 readback 未验证 authority，停止自动 mutation 并优先回绑 digest-bound CP/task artifact；无法回绑时请求重述或重新确认。Agent SUMMARY 仍保持纯索引。

格式选择

场景	格式
chat / 简单 analyze	紧凑
audit（多轮）	紧凑
dev/fix（≤2 文件变更）	紧凑
dev/fix（≥3 文件变更）	完整
多任务会话（≥3 任务）	完整

可从紧凑升级为完整（追加缺失字段），无需重写已有内容。

SUMMARY 文件

Agent SUMMARY（每 Agent 独立）

<active-root>/.memory/clients/<agent>/SUMMARY.md

• 每次会话结束前（SC6 检查）追加一行索引
• 模板：prompts/agent-summary.prompt.md
• 🔴 状态事件延迟写入（append-only）：会话进行中先追加 🔄；任务完整结束、合规检查全通过、V8 部署同步通过后，再为同一“日期 + 会话”追加 ✅。读取端由 scripts/lib/memory-summary-state.js 以最后事件投影当前状态；正常的 🔄→✅ 是历史而非冲突，只有完成后又回退到 active/blocked 才进入冲突诊断。禁止要求 append-only writer 原地改写旧行。

文件格式（首次创建时用此表头，之后只追加行）：

# Agent SUMMARY — [agent-id]

> 项目：[项目名]

| 日期 | 会话 | 类型 | 摘要 | 关联报告 | 关联记忆 | 状态 |
|------|:----:|------|------|---------|---------|:----:|
| YYYY-MM-DD HH:MM | NN | dev/fix/... | [50~100字摘要，含关键数字/结果] | [NN--简述.md](workspace相对路径/NN--简述.md) | [YYYYMMDD.md §NN](workspace相对路径/YYYYMMDD.md) | ✅/🔄 |

字段规则：

• 类型（SummaryTypeCanonGate）：仅 dev|fix|analyze|audit|self-fix|chat|resume|other；多意图用 +（如 fix+audit）。禁止 /、自由标签（ops/ledger/release/governance-record）与把状态写入类型列。审查/复审→audit；分析结论→analyze；ECR/实施闭环→dev 或 self-fix。机器真相源：scripts/lib/summary-type-canon.js；memory_summary_append 硬校验，非法则拒写。memory_session_allocate.intent 额外允许 unspecified。
• 摘要：一行 50~100 字，包含做了什么 + 关键数字/结果
• 多任务会话：一行覆盖全部任务，不拆多行
• 排序：按时间正序追加（最新在最后）
• 状态折叠：同一“日期 + 会话”允许有多个 append-only 状态事件；最后一行是当前状态，早期行是历史，不得让 stale-index fallback 重新暴露已完成的旧 🔄；合法的前向转移不报冲突，completed 后的状态回退必须报冲突
• 关联报告与关联记忆按 ArtifactLinkSetDedupeGate 只写当前主报告 / 主记忆索引；同一物理文件用 canonical path 归并，并优先通过 memory_summary_append.reportArtifact/memoryArtifact 生成相对链接与回读 receipt。内部索引不因用户面默认隐藏而停止写入或从 ECR 排除。

🔴 SUMMARY 纯索引约束：SUMMARY 仅包含表头 + 会话索引行，禁止添加任何自由文本段落（如"当前状态""关键决策""待处理事项"等非索引内容）。🔄 状态标记仅出现在索引表的「状态」列，不得出现在表外文本中。已有旧格式 SUMMARY 应在下次写入时迁移（移除非索引段落，内容转入 daily file 或 profile）。

ContextHandoffCard

跨会话、跨 Agent、多批次、summary/compact 前、用户要求“传递上下文”或即将中断时，daily tasks 或报告必须写入 ContextHandoffCard，字段至少包含：source-of-truth、confirmed-decisions、open-risks、next-action、blocked-reason、must-not-overwrite、validation-state、artifact-links。ContextHandoffCard 是交接卡，恢复方仍须按 Context Rehydration Contract 重新核对文件真相源；禁止把交接卡写成 SUMMARY 自由文本段落。

NewSessionContinuationCard（ABS-11 / PI-114）

凡 AI 主动建议或因 C08 / 规模门禁要求切换新会话，必须在同一最终回复交付用户可复制的 NewSessionContinuationCard，字段至少：targetProject、稳定 taskId（已有时）、task、phaseAndConfirmationState（CP pending 不得写成已确认）、sourceOfTruth、confirmedDecisions、mustNotOverwrite、validationState、nextAction、copyReadyPrompt。面向用户的 copyReadyPrompt 固定收敛为 继续<displayName>任务；长 Card 留在内部/报告作降级证据。接收方仍须用 resolver 定位并重建 ContextReadPlan，禁止默认全读 Profile/SUMMARY。

SessionTimingCard（ABS-18 / PI-117）

长任务（non-chat 的 analyze/audit/dev/fix、多批次、用户抱怨慢、完整深度等）须在会话段或报告附录记录：

字段	说明
startedAt / endedAt 或 lastActiveAt	ISO 墙钟
wallClock	总时长（含等待）
executionMs / waitingUserMs / waitingExternalMs	ExternalWaitAccountingGate：执行 / 等人 / 外部等待分列
phases[]	至少覆盖：context-acquire / plan-or-cp / execute-or-read / validate / report-memory / waiting-user /（条件）waiting-external
slowTags	可选 1～3 个有证据标签（large-corpus / waiting-user / full-profile-load…）
cycleId / budget	条件：命中 ExecutionBudgetGate 时记录 cycle 与 maxWallClock 等预算快照
authorizationEvidence	条件：命中 LongTaskAuthorizationGate 时记录续跑/Auto 授权

等人确认与外部等待必须单独计时，不得并入「AI 执行慢」，也不得消耗 maxWallClock 执行预算。纯 chat 秒回可 N/A + skipReason。用户面可给一行：耗时 XhYm（执行 … · 等人 … · 外部 …）。

ExecutionBudget 记忆锚点（PI-118 / PF-137）

命中长任务预算时，daily tasks 须能定位当前 cycleId、预算上限、已消耗执行墙钟、StopSnapshot 路径（若已触发）与「继续=新 cycle」状态。禁止在记忆里把用户「继续」写成同一 cycle 预算清零。

ProjectKnowledgeSnapshot 边界

incremental-project-analysis 的知识快照/digest 不得写入 SUMMARY 正文（SUMMARY 纯索引）；快照落独立产物路径，daily tasks 只链路径。

全局 SUMMARY（项目共用）

<active-root>/.memory/SUMMARY.md

• 仅记录关键决策（规范变更/架构决策/P0修复）
• SC7 检查时追加，纯 chat/无重要决策时 N/A

三层记忆职责

层级	文件	写入频率
Agent 日记	.memory/clients/<agent>/tasks/YYYYMMDD.md	每会话必写
需求记忆	<需求>/.memory/sessions.md	路由确定后追加
项目总记忆	.memory/SUMMARY.md	有关键决策时

需求级记忆路径构建

<active-root>/requirements/<描述>/.memory/sessions.md   # dev 需求
<active-root>/bugs/<描述>/.memory/sessions.md           # fix Bug
<active-root>/optimizations/<描述>/.memory/sessions.md  # dev 优化

<描述> 与 02-output-paths.instructions.md 中的任务目录名一致。

模板引用

产出物	模板
记忆日文件	prompts/memory-session.prompt.md
Agent SUMMARY	prompts/agent-summary.prompt.md
需求级记忆	prompts/requirement-session.prompt.md