/memory

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

文件路径

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

<!-- devcodex:include shared/memory/active-root-layout.md -->

MCP memory scope（workspace-namespace）

<!-- devcodex:include shared/memory/workspace-selection.md -->

<!-- devcodex:include shared/memory/ambiguous-workspace-error.md -->

• `<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。

| 场景 | 读取范围 | 执行顺序 | |------|---------|---------| | **命名续接 · 首步** | 用户意图为续接明确任务时，将任务名或稳定 ID 与项目范围提交给 `memory_task_resolve(name, project?, locale?)`；locale 来自当前用户意图和已确认会话语言，不能从任务名字符推断；只取 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`、`HostSubagentDispatchPlanV1`、`AgentWorkLeaseV1` 或 digest-bound `ChildAgentEvidenceV1` 交回根会话；child 不得写需求级 sessions、Agent daily、SUMMARY、ContextHandoffCard、CP、owner、terminal 或 Auto 状态。timeout/cancel/late/invalid 结果只进入 quarantine 与串行接管摘要，不恢复旧 lease；所有正式 memory 仍由根会话按 `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