dsh-memory-protocol v1

状态：社区预演——官方 ctx.memory seam 的候选形态。 规范性机器可读 Schema：schemas/dsh-memory-protocol-v1.schema.json； 一致性套件：test/protocol-conformance/。 English version: protocol-v1.md。

dsh-memory-protocol/v1 是 DeepSeek Harness 中有界、分层、带审批门、可审计的跨会话记忆 互操作协议。dsh-memento 是参考实现；任何其它记忆插件实现同一 Provider 面并通过同一套 一致性用例，即可声称协议兼容。

设计锚点（任何兼容 Provider 都不可妥协）：

• 审批门在服务内部，不在工具层。 每条写路径（add/replace/remove/consolidate/seed） 都被强制经过 Provider 内部的审批传输，任何模型路径都无法绕过（Hermes issue #48181 的教训）。
• 模型可见 ⟺ 可重建。 任何写入都必须能由审计证据重建：审批对（携带完整载荷的 approval/asked + 携带结果的 approval/decided）+ Provider 自有审计账本。被拒写同样留痕。
• 本地优先。 零网络、零凭据；存储是用户自有的本地文件。
• 有界且诚实。 每轨每层硬字符预算；超预算写以结构化错误失败。绝不截断、绝不静默丢弃。

1. 协议标识与版本规则

字段	值
协议 id	dsh-memory-protocol
版本	1（URI 形：dsh-memory-protocol/v1）
条目 schema 版本	按条目存储（version，从 1 起，每次 replace 自增）
库 schema 版本	单调整数（参考实现 SCHEMA_VERSION = 4）
导出信封	{plugin: "dsh-memento", schema: "memory-export-v1", …}

规则：

• 协议版本只在契约变化时提升（新必填字段、新错误语义）；纯增量的可选字段不提版本。
• 库 schema 逐级前向迁移；库版本高于 Provider 认知时响亮拒绝（STORE_UNSUPPORTED_VERSION）—— 绝不盲读、绝不静默降级。
• 条目自带 version，审计链可以不经文本比对重建同一 id 的演进史。

2. 条目模型

条目是协议的记忆单元：

字段	类型	含义
id	string（UUID v4）	跨会话稳定身份，由 Provider 生成
track	user | agent	user = 用户画像（偏好/风格/雷区）；agent = 环境事实/约定/教训
scope	user-global | workspace	user-global 对所有工作区生效；workspace 只对会话规范化 cwd 生效
workspaceKey	string	workspace 条目的规范化绝对 cwd 键；user-global 为空串（Windows 大小写不敏感）
agentKey	string	规范化 agentPreset 键；'' = 所有 agent 可见的共享层
text	string，非空	记忆内容；预算计数单位 = JS 字符串长度
source	string	来源标注（dsh-memento、memory-tool、claude、适配器 id…）
tags	string[]	短标签：≤16 个、每个 ≤32 字符、trim、去重、无控制字符
version	integer ≥ 1	从 1 起；replace 自增；consolidate/seed/导入产生全新 version 1 条目
createdAt / updatedAt	integer（epoch ms）	updatedAt >= createdAt
lastRecalled	integer | null	最近一次 query 命中时间（epoch ms）
recallCount	integer ≥ 0	query 命中次数（排序：高频即重要）
sessionId	string | null	最近一次写它的会话 id

可见性：会话只能看到（replace/remove/consolidate 也只能改到）共享层（agentKey === ''）

• 本 agentPreset 的条目，且 workspace 条目仅限本会话 cwd。管理面（命令、面板）与不带 会话上下文的 Provider 调用保持全量视图。

3. 写操作

所有写共享同一条流水线——预算预检 → 审批传输 → 预算复审 → 原子落盘 → 审计行—— 任何一步失败都零部分写入。

操作	输入	语义
add	条目输入	插入新条目（新 id、version 1）。不按值去重：重复文本合法；整合是调用方的工具。
replace	唯一子串 match、新 text、可选 tags	按文本的大小写不敏感唯一子串定位并改写恰好一条。id 稳定；version 自增；给 tags 则更新，否则保留。
remove	唯一子串 match	删除恰好一条。
consolidate	1..20 个 matches、新 text、可选 tags	原子删除全部目标并插入一条新条目（version 1）——一次审批、一个事务。
seed	条目输入列表	一次审批批量插入；全有或全无（任一条超预算整批拒绝）；每条新 id、version 1。

幂等与冲突裁决：

• replace/remove/consolidate 是以唯一子串匹配为键的条件写：成功后重跑同一操作会以 ENTRY_NOT_FOUND 失败（匹配已不存在），重试不可能造成双写。零命中 → ENTRY_NOT_FOUND； 多命中 → AMBIGUOUS_MATCH（带候选数与文本样例）——调用方必须给更长、唯一的子串。
• 权威目标在审批返回后重新解析（审批等待期间并发写可能已改库）；最终预算复审与落盘之间 无 await，不存在陈旧写窗口。
• consolidate 在单事务内解析全部目标：任何不匹配整体回滚。

审批载荷（approve-what-you-see）： 审批请求携带完整变更而非抽象动作：add/seed 带新文本； replace 带 from:（旧条目全文）+ to:（新文本）；remove 带被删条目全文；consolidate 带每个目标的定位原文（单条 300 字摘录上限）+ 新文本。

4. 读操作

• query(filter?, opts?)——子串检索（ASCII 大小写不敏感折叠；对 CJK 正确）。无审批。 选项：track/scope/text/limit（Provider 硬钳 1000）、opts.sessionId（落 recalled 审计行）、opts.agentKey（会话可见集过滤）。
• budgets()——每轨每层用量报表（{track, scope, used, limit} 行）。
• 排序：命中 query 的条目 recallCount + 1 并更新 lastRecalled；结果按 recall_count DESC, updated_at DESC 排序。

5. 预算模型

• 每轨每层硬字符预算（参考默认：user 2000 / agent 4000 每层）。预算只计 text—— tags 与元数据不计入。
• 超预算写以 BUDGET_EXCEEDED 失败，携带 {track, scope, used, limit, needed}； 调用方整合/删除后重试。绝不截断、绝不自动压缩。
• seed 先全量预检；任一条超预算整批拒绝，写任何内容之前即失败。

6. 审计与重建

• 每次放行写落一行审计：{seq, ts, action, track, scope, entryId, text, outcome, source, sessionId}。outcome 标注真实裁决来源（allowed-once (via approval, writePolicy ask) / … (via write gate)）。
• 每次被拒/取消/不可用的写在 WRITE_DENIED 错误传播前落 <action>-denied 行——turn 外 gate 路径没有审批审计对，denied 行是那里的唯一证据链。
• 读召回落 recalled 行；注入快照落 snapshot 行（与模型所见逐字一致）。
• 配合审批对（approval/asked 完整载荷 + approval/decided 结果），任何状态变化都能从 会话日志 + Provider 审计账本重建。

7. 错误码

结构化错误暴露稳定 code；工具与模型按 code 分支而非 message（message 刻意保持英文—— 它们是跨语言的审计契约）。

Code	触发	Details
INVALID_INPUT	非法 track/scope/text/tags/match/matches/信封	—
WRITE_REQUIRES_AGENT	写缺少 owning agent 会话	—
BUDGET_EXCEEDED	超预算写或 seed 批次	track, scope, used, limit, needed
ENTRY_NOT_FOUND	零命中匹配	track, scope, match
AMBIGUOUS_MATCH	多命中匹配	candidates, sample
WRITE_DENIED	审批 rejected/cancelled/unavailable	outcome
PROPOSAL_NOT_FOUND	对非 pending 提案裁决	id
STORE_CORRUPT / STORE_UNSUPPORTED_VERSION	库不可读 / schema 过新	path
ADAPTER_NOT_FOUND / ADAPTER_PAYLOAD	未知适配器 id / 载荷不可转换	adapterId

8. 导入 / 导出信封

• /memory export 产出一份 JSON 文档 {plugin: "dsh-memento", schema: "memory-export-v1", exportedAt, budgets, entries}—— 完整的备份/迁移往返。导出只读（无审批、不落审计）。
• /memory import（及 import --adapter=<id>）经 seed 恢复条目——一次审批、全量 预算预检、单事务原子落盘、逐条审计。导入条目获得新 id/时间戳、version 1、召回计数归零； 未知信封 schema 版本响亮拒绝；单次导入上限 1000 条。

9. 适配器注册表（ctx.memoryAdapters）

第三方记忆插件通过注册适配器（register(adapter) 返回 disposer——注册可逆，归属插件自己的 ctx.effect）把自己的 store 接进协议。适配器是纯数据转换器：adapt(payload) → {entries} 与 export(entries) → payload；绝不调用模型抽取。未知适配器 id 报 ADAPTER_NOT_FOUND；不可转换 载荷报 ADAPTER_PAYLOAD。dsh-memento 随附参考适配器：mem0、hermes-memory-md、 claude-code-memory-md。见 adapters-guide.zh.md。

10. 一致性

任何声称 dsh-memory-protocol/v1 兼容的 Provider 实现 test/protocol-conformance/README.md 的 Provider 面， 并通过一致性套件——与本仓库 CI 中黄金参考（dsh-memento 自己的 Provider）跑的同一套用例。套件可对外分发（拷贝即跑，任意 Provider 工厂），自包含（仅 node:assert）。

11. 与官方 seam 的关系

协议是对 dsh-memento 现有 ctx.memory seam 的规范化与扩展——不是重写；0.3.x 的一切行为保持 兼容。协议在此之上的新增：条目级 tags/version、机器可读 JSON Schema、可分发的一致性套件、 适配器注册表。官方 seam 为何应采纳本协议及迁移路径，论证见 upstream-proposal.zh.md。