record-memory

记录记忆

对话上下文不会持久保存。当知识能为未来的 Agent 节省大量时间时，请立即写入一条记忆记录。阶段和切片收尾时必须执行提示：检查 notes.md、当前运行阶段说明、审计发现和最新注意事项，找出值得保留的持久指导。

只提升持久指导——可重复的工作流、关键边界、恒定条件、子系统事实。不要记录对话状态。

1. 选择最合适的类型

运行 doctrine memory record --help 查看 --type 的可选值： concept|fact|pattern|signpost|system|thread。

⚠ 在验证之前，thread 不会出现在 find/retrieve 中。 如果你希望按范围重新找到某个工作循环，请优先选择持久类型（pattern/system/concept），或者记录 thread 并在干净的工作树上对其运行 verify。未经验证的 thread 只会显示在 list/show 中，不会参与范围排名。

2. 记录

使用 doctrine memory record 进行记录（运行 --help 查看标志；动词模型参见 lib:reference/using-doctrine.md）。该命令会在 .doctrine/memory/items/ 下生成 TOML 文件和正文；创建时的 git 锚点会自动捕获——不要手动编写。

记录后

建议关系。 如果 record 检测到与现有记忆的高置信度匹配项，会在 stderr 中输出建议关系。请检查这些建议，并对确认的匹配项运行 doctrine link——这会构建持久的图边，供未来的 Agent 遍历。

图关系与正文链接。 使用 [[relation]] 边表示持久的图结构（有类型，可由机器遍历）；使用正文中的 [[mem.…]] wikilink 提供上下文性的“另请参阅”指引。关系会显示在 retrieve --expand 中；wikilink 不会——它们是为人类读者准备的。

选择 --lifespan。 按知识的持久程度，选择最短且合适的生命周期，从最持久到最短：

生命周期	经验法则
identity	永不过时——子系统身份、恒定条件、规范名称
semantic	10:1 衰减——设计理由、架构约束
procedural	3:1 衰减——命令配方、构建步骤、工作流
episodic	基准——一次性发现、错误记录、会话上下文
working	快速衰减——临时待办、短期假设

省略时默认为 episodic。范围和生命周期都选得越精确，检索结果越相关。

3. 设置范围，确保能找到

沿四个维度设置记忆范围（标志详见 --help）：

• path — 精确文件；匹配权重最高。
• glob — 子系统相关性（例如 src/auth/**）。
• command — 关联到某个命令流程（令牌前缀）。
• tag — 稳定的分类方式；不要把标签过度用作范围。

4. 设置风险维度

record 默认设置 [trust] trust_level = "medium"、[ranking] severity = "none"、weight = 0。对于有风险或容易过时的记忆，请在记录时传入标志，或之后更新：

doctrine memory record ... --trust high --severity critical

或者事后调整：

doctrine memory edit <REF> --trust low --severity medium

• --trust = 置信度：low（推断所得，未经验证）· medium （根据合理的上下文得出——默认值）· high（根据代码 / 规范 / 直接观察验证）。
• --severity = 如果内容有误或被忽略，影响有多大： critical · high · medium · low · none（默认值）。

务必如实校准：创建记忆属于撰写，不是验证。

5. 验证后进行确认

doctrine memory verify <UID|KEY>

根据工作树写入 verified_sha（如果工作树不干净则拒绝操作——不会产生虚假确认）。未经确认的记忆会被视为信任度较低。

thread 必须经过此步骤才能显示。 thread_expiry 会在 14 天后，将未同时处于 verified 和 reviewed 状态的 thread 从 find/retrieve 中移除。record 始终会写入 unverified，所以新建的 thread 在运行 verify 之前不会参与范围排名——而 verify 会拒绝不干净的工作树，因此必须在干净的工作树上确认。其他类型不受此限制。

参见 doctrine memory retrieve --help：retrieve 会应用不可绕过的信任限制（低信任度 + 高严重性的记忆会被抑制）。

6. 保持正文简短且可执行

将“执行 X”之类的步骤列为项目符号，并附上准确的命令片段。通过 [[uid]] / [[key]] 在正文中引用相关产物和记忆（比使用关联更省）。如果内容会演变成 ADR 或常青规范，请停止——改用 doctrine adr new，或编写规范或 ADR。记忆只是指针/操作指南层，而非权威内容。

7. 检查是否可检索

运行 doctrine memory search，并将范围限定为未来 Agent 实际会查询的上下文（参见 --help），确认能搜到该记忆。搜索结果只有一页，因此限定范围的浏览可能会漏掉它：请使用包含该记忆自身术语的查询（全文搜索会根据证据找到它）进行确认，或通过 --page 翻页。

例外：即使记录正确（§1/§5），未经验证的 thread 也不会显示在这里——请先对其运行 verify，或改为检查 memory show。