dsh-hindsight-memory

DSH ⇄ omp 记忆行为对齐插件（中间层）

把「模型说的话」翻译成「omp 也会做的同一件事」：同一个 Hindsight 记忆库、同一套标签语义、同一套分层、同一套过滤规则。

它解决什么

本插件把 DSH 侧换成受控的中间层：模型只看见 4 个语义化工具，标签与记忆库路由由插件自动处理，模型碰不到 tags、碰不到 bankId。

模型 ──▶ memory_recall / memory_retain / memory_reflect / memory_status
│  （插件盖章：project:<小写仓库名> 或 无标签）
▼
Hindsight 记忆库 `mem-<项目名小写>`
▲
│  （omp 原生后端：自动盖章 + 自动过滤）
omp

九个工具

> 知识页与 initiative 是 Hindsight 服务端原生能力（/knowledge-base），本插件只是把它包成与 omp 同语义的工具：产出盖 project:<小写项目名> 标签、不复用官方的 source:/harness: 标签、写入走 async:true + metadata.session_id。可用配置 knowledgePages: false 整体关掉这两个工具。

标签是插件的事，不是模型的事：模型不传 tags，插件按 basename(主 checkout 根).toLowerCase() 盖章——与 omp 的 projectLabel() 逐字同规则。

与 dsh-mnemon 的分工（重要）

两个插件不冲突，但只有一层能连 Hindsight。当前配置是：

> 🔴 dsh-mnemon 的 Hindsight provider 必须保持「不启用」（enabled.hindsight=false，配置保留可一键回滚）。
> 它的写侧能打标签，但读侧不支持按项目过滤（provider 0.5.6 的 search() 请求体写死 {query,budget,max_tokens,types,prefer_observations}），
> 开着它就会出现「两边都在写、但过滤规则不一致」的分裂。记忆空间组件本身不要关——关掉会让 dsh-mnemon 的检索提醒整片清空。

记忆库布局：每项目一个 bank（2026-10-27 起）

当前这台机器上的实际布局是「每项目一个独立记忆库」，bank 基名 mem，bank 名为 mem-<项目目录名小写>（如 mem-随便问问、mem-blog、mem-毕设）。

• Hindsight 服务里存的是「记忆库（bank）」，每个库是一块独立空间，可以有多个库，服务端有 /v1/default/banks 接口可列。
• omp 与 DSH 仍然共享同一批 bank（两端 bankId 都设为 mem，靠 base 名对齐），但项目之间不再共享同一个库。
• 项目隔离靠库名，不靠标签：每个项目一个库 ⇒ 删除某个项目的全部记忆只需一条命令
  DELETE /v1/default/banks/mem-<项目名小写>，不会误伤其它项目；在官方前端（）切换 bank 即可查看对应项目的记忆。
• 三种作用域模式（global / per-project / per-project-tagged）由 scoping 选择，插件已全部内置，parity.js 的 computeBankScope() 与 omp 同算法。当前取 per-project。
• 代价：跨项目通用经验不再自动共享。迁移时把旧单库里的 96 条无标签全局事实复制进了每一个项目库，所以每个项目仍能召回这些经验，但它们不再有单一真源，后续修改需同步多份。
• 旧的单库 shared（约 2426 条事实、35 个精神模型）完整保留作为回滚点，未删除；回滚只需把两端配置改回 bankId: shared + scoping: per-project-tagged。

一句话：bank 名里的 mem = 记忆库基名；mem-<项目名> = 这个项目自己的那块记忆空间。

面板：三个层次，各管一段

> 插件里的「配置」按钮从哪来：DSH 的插件配置表单不会自动渲染。宿主只在某个 client 半体注册了 plugins.row.config（键 = <包名>#<行 id>）或 plugins.bundle.config（键 = <包名>）渲染槽位时才给出入口。本插件的 client 半体（src/ui-client.js，浏览器经典脚本）同时注册了这两个槽位，所以详情页会出现可编辑表单。
>
> 表单要拿到「可编辑配置项」还差一格（v0.3.0 修的就是这格）：宿主只会把运行中且字段被标成 volatile 的插件行投影成可编辑配置项（dsh-settings 的 volatileForm() 会把非 volatile 字段整段裁掉）。少任何一样，详情页就只写「这个插件行还没有被宿主暴露为可编辑配置项 (settings namespace 未就绪)」——插件照常工作，只是没有表单。本插件的做法与 dsh-mnemon 一致：src/schema.js 导出 LiveConfig（把基础 schema 逐字段 .volatile()），并在 loader/volatile-update 里把改动写回运行中的配置引用（宿主改的是引用里的值，不是替换对象 ⇒ 插件必须每次读当前值，否则拿到的是包装对象）。
>
> ⚠️ 改完 client 半体必须重启 DSH Web：DSH 进程在启动时解析每个包的 package.json 并把结果缓存在进程内（不随磁盘变化失效），所以「装了带 client 半体的新版本 → 刷新页面看不到配置按钮」是预期行为，重启一次即可，别去反复点开关。

> 终端面板刻意不经过模型：跨 agent 记忆的验收只认服务端原始数据，模型自述不算证据。

安装

# 从 GitHub 装（推荐；仓库即源码）
dsh plugin --profile web add "git+https://github.com/meisijiya/dsh-hindsight-memory.git"

# 或本地开发（包名会被 DSH 用 import(name) 加载；Windows 不能用裸绝对路径）
dsh plugin --profile web add "file:D:/path/to/dsh-hindsight-memory"

> 需要重启 DSH Web 才会装载。回滚：dsh plugin --profile web remove dsh-hindsight-memory。

从插件市场发现页装：DSH → 插件 → 发现 → 索引源，填本仓库的索引地址：

https://raw.githubusercontent.com/meisijiya/dsh-hindsight-memory/main/index.json

索引里锁的是精确 commit（不是浮动 HEAD）；改索引只要重新拉取，不用重启 DSH。索引格式与发布流程见 docs/market-index.md。

包声明了 dsh.bundle.patch，走 bundle 路线，profile 装载时自动组合插件自己的 cordis.patch.yml。

> 🔴 运行时真源是包内默认值，不是 profile 的行配置（2026-10-28 实测）：
> DSH 启动后本插件拿到的配置是空对象 —— 改 ~/.dsh/profiles//cordis.patch.yml
> 里的 hindsight-memory 行、或改包里的 cordis.patch.yml，都不改变运行时行为；
> 只有改 src/config.js 的 DEFAULTS 才立刻生效（判定实验：把 DEFAULTS 的 bankId 改成
> probedefault 后，看板立刻报 Bank 'probedefault' not found）。
> 因此本仓库把 DEFAULTS / 包内 cordis.patch.yml / schema.js / ui-client.js 四层默认值钉成一致
> （test/defaults.test.js 门禁），并要求 profile 里的行配置与之一致
> （scripts/verify-dsh-runtime-e2e.mjs 有一项检查专门比对两者）。
> 宿主将来若开始投递行配置，两边一致 ⇒ 行为不变。

配置

- insert:
- id: hindsight-memory
name: 'dsh-hindsight-memory'
config:
enabled: true          # 总开关
inject: true           # 是否注入常驻系统提示词段
writeEnabled: true     # false = 只读（灰度第一步）
apiUrl: 'http://127.0.0.1:8888'
bankId: mem              # 必须与 omp 的 hindsight.bankId 一致（当前为 mem）
bankIdPrefix: ''
scoping: per-project   # global | per-project | per-project-tagged（当前为 per-project）
types: [world, experience]     # 与 omp 的 recallTypes 同值
budget: mid
reflectBudget: low
maxTokens: 1024
recallMaxQueryChars: 800
autoRecall: true        # 首回合自动召回（与 omp 的 autoRecall 默认值一致）
autoRetain: true        # 回合结束自动留存（与 omp 的 autoRetain 默认值一致）
retainEveryNTurns: 3
sectionOrder: 950
hygieneThreshold: 0.9        # 近重复判定阈值（越高越保守）
hygieneMaxFacts: 500          # 单次扫描的事实条数上限
hygieneProjectMission: '只保留该项目中长期有效的技术决策、约定、硬约束与踩过的坑；不保留一次性进度、临时状态与重复表述。'
hygieneProjectMaxObservations: 40   # 项目层每个 scope 的 observation 上限
hygieneGlobalMission: '只保留跨项目长期有效的约定、环境事实与用户偏好；不保留一次性进度、临时状态与重复表述。'
hygieneGlobalMaxObservations: 30   # 全局层 observation 上限

配置写错不会炸 profile：所有非法输入一律回落到默认值（normalizeConfig 不抛错）。

> autoRecall / autoRetain 与 omp 的默认值对齐（都开）。想改成只读或纯手动，在插件配置面板里把
> writeEnabled 或 autoRetain 关掉即可，不需要改代码。

缓存稳定性（为什么提示词段是常量）

DSH 把工具 schema 放进缓存前缀：工具集合一变 ⇒ 请求头变 ⇒ 重开请求序列 ⇒ 缓存作废。所以：

1. 工具只在装载时注册一次，任何回合都不注册/注销。
2. 系统提示词段是编译期常量（无时间戳、无项目名、无记忆内容）；关闭时返回空串而不是换文本。
3. 变化的内容（召回结果）走用户消息，落在缓存边界之后。
4. 绝不改共享配置对象——请求配置在宿主侧是 deepFreeze(structuredClone(...))。

详见 docs/design.md §12。

隔离分层观测（怎么验证「隔离真的按预期分层」）

node scripts/isolation-check.mjs --a "D:/26code/随便问问" --b "D:/26code/测试hindsight"

脚本用两个项目目录写三条探针（项目A 事实 / 项目B 事实 / 全局层事实），然后打出可见性矩阵，
观测完自动作废探针（--keep 可保留）。2026-10-22 实测结果（DSH 插件侧，走插件自己的读写路径）：

同一结论用真实 omp 客户端复核过（读 omp 会话文件里注入的 `` 块，不采信模型自述）：

整库分层（87 条活跃事实）按两个目录各看一次：

> 结论：项目隔离靠标签，不靠库名；同一块 shared 库里，靠 project:<仓库名小写> 区分项目层、
> 靠「无 tag」区分全局层。DSH 与 omp 读写同一批数据、各自只看自己该看的那一层。

记忆卫生（共享 bank 层，两端同时受益）

omp 自己没有清理能力（实测：omp 二进制里没有任何去重/整理逻辑，只有 retain/recall/reflect）。
所以「记忆越写越胖、召回里出现四五条近义重复」这件事，必须由中间层在共享 bank 上做——
只有这样 omp 与 DSH 才不会行为分裂（整理一处，两端同时受益；整理在某一侧做 ⇒ 立刻分裂）。

分两层，各管一段：

# 只读预览（默认）
node scripts/hygiene.mjs --bank shared --threshold 0.8

# 真正作废近重复事实（服务端可逆：state 改回 valid 即恢复）
node scripts/hygiene.mjs --threshold 0.8 --apply

# 顺带触发服务端合并 observation
node scripts/hygiene.mjs --consolidate

工具版：memory_hygiene(action=preview|prune|consolidate|scopes|strategies-preview)，prune 默认 dryRun=true。

去重规则（三条护栏，缺一条就会误伤）

1. 只在同一层内找重复：项目层与全局层语义不同，同文也不同义 ⇒ 分组签名 = fact_type + 标签集。
2. 不动 observation：服务端每次 retain 会同时产出 world 原始事实与 observation 归纳事实，两者文本高度相似但语义不同；把归纳层当重复删掉＝删掉归纳成果（默认跳过，--include-observations 才纳入）。
3. 每组保留最新的一条，其余作废；作废是可逆的（PATCH /memories/{id} {"state":"invalidated"} → {"state":"valid"} 即可恢复）。

2026-10-22 实测：93 条活跃事实 → 清理 6 条近重复 → 触发 consolidation（服务端返回 deduplicated: true）→ 88 条活跃；
召回命中 14 条、近重复组 0；node scripts/verify-live.mjs 8/8 通过（分层可见性、跨项目硬隔离负例 count=0 全部复验）。

> 阈值怎么选：0.9 只抓逐字重复；0.8 能抓「同一件事换个说法」（本机这轮的真实情况）；0.7 起要人工看一眼再下手。

精神模型（mental models）：跨会话的经验总结

精神模型是 Hindsight 的第三层记忆：服务端用 LLM 从事实层归纳出的一份长期画像文档，
客户端负责确保它存在、并把正文注入会话提示。omp 启动时幂等建三个，本插件对齐同样的三件套：

id 与 omp 完全相同 ⇒ 两端共用同一份模型（2026-10-27 起）。
id 规则随作用域变化，与 omp 逐字对齐：

> 🔴 为什么必须两端同名：omp 注入精神模型时只按 scope 过滤、不按 id 过滤
> （loadMentalModelsBlock 传的是 recallTags；per-project 下为空 ⇒ bank 里每个模型都注入）。
> 两端各建一份同语义模型 ⇒ 上下文里出现两份「Project Conventions」，
> 并把渲染预算（hindsight.mentalModelMaxRenderChars，默认 16000 字符）吃光、
> 触发 [mental-model snapshot truncated at render budget]。
> 实测（切换前）：同一 bank 里 7 个模型被注入，标题「Project Conventions」出现两次。
> 统一后：4 个模型、无重复。
>
> 本插件的注入过滤也改成与 omp 同规则（parity.js 的 mentalModelVisible()：只按 scope 过滤，不按 id 白名单），
> 否则自定义模型（例如手写的架构文档）在一端可见、另一端不可见。

> ⚠️ 服务端 POST /mental-models 是仅创建：重复 id 返 409 且不改写已有 tags。
> 所以插件的做法是「缺就建、标签不对就 PATCH、对的就原样保留」——planEnsure() 干这件事。
> 两端同时启动时，第二个端拿到 409 就跳过（模型已存在且就是它要的那份）⇒ 不会互相覆盖。

# 插件工具：memory_mental_models(action=ensure|list|content|refresh|patch)

实测（2026-10-27，per-project 作用域）：ensure 返回 created:0 patched:0 kept:3，
三个模型齐全且与 omp 侧同名；同一 bank 内不再有 dsh- 前缀的副本。

> mentalModelPrefix 配置项保留为可选隔离层：默认空 = 与 omp 完全同名；
> 填值（如 dsh）就在 omp 的 id 前再加一层，用于「同一 bank 内两端必须用不同模型」的特殊场景。

渲染预算：两端内容可能不等长

omp 把精神模型正文渲染成 ` 块，受hindsight.mentalModelMaxRenderChars约束 （默认 16000 字符，**在模型之间等分**，超了块尾出现…[mental-model snapshot truncated at render budget]）。 本插件的renderMentalModelMessage()` 不设预算、渲染全量。

所以「共用同一份模型」不等于「两端看到的字符数一样」：模型正文够长时 omp 会被截断，DSH 不会。
模型正文越长的项目越明显（实测 mem-随便问问 无截断需 34000 字符，7 个 bank 里有 6 个在默认 16000 下被截断）。
需要两端内容对齐时，把 omp 侧的 hindsight.mentalModelMaxRenderChars 调到覆盖最长的一节
（代价：静态系统提示前缀变大）。

运维观测：失败任务不会自动重试

Hindsight 的抽取/刷新/合并任务都进 operations 队列，失败不会自动重试
（retry_count 不涨、next_retry_at 为空）。所以必须有观测手段，否则「记忆写不进去」会静默。

# 插件工具：memory_operations(action=list|retry|delete)

action=delete 是「先取消、再真删」两步：服务端的 DELETE /operations/{id} 只取消
（任务已是终态时返回 409），真删要走 DELETE /operations/{id}/delete。
所以 pending/processing 的行会先被推到终态再删掉，completed/failed 的行直接删。

memory_status 里已经带了队列体检：按状态/任务类型统计 + 最近任务的 error 与 retryCount。
实测：total 248 / processing 8 / completed 11 / failed 1，那条 failed 是探针 mental model 被删后
遗留的 refresh_mental_model（ValueError: Mental model probe-mm-测试 not found）。

> 排查「召回为空」的第一步：memory_status 里的 bank.factCount 与 bank.warnings
> ——同名空 legacy bank 会伪装成零结果，先核对 bank 名字再下结论。

知识页与 initiative（服务端原生能力，本插件只做对齐）

Hindsight 服务端自带 /knowledge-base（页 + 文件夹 + 全文检索）。本插件把它包成两个工具，
沿用与 omp 完全一致的写入纪律：

三条守则（与 omp 对齐的具体含义）：

1. 产出必须盖本项目标签 —— 这是 per-project-tagged 作用域下的硬要求：不盖标签的页 omp 召回看不见（它只认「无标签」或「带本项目标签」）。当前 scoping: per-project 时标签是冗余的（bank 本身已隔离），但盖上无害且便于跨模式回退时仍可判层。
2. 不复用官方的 source:/harness: 标签 —— 那两个前缀是官方包的 provenance，混进来会让 DSH 侧按白名单过滤时把自家内容挡掉。
3. 写操作异步 + 带 metadata.session_id —— 页正文要等服务端合成（实测几十秒到几分钟），刚建完立刻 search 可能只拿到 No content yet.。

实测（v0.5.0，bank shared）：

memory_pages list      → ok, folders=[], pages=[]
memory_pages create   → ok, pageId=kp-…, operationId=41e2e487…（异步合成）
memory_pages search   → ok, count=1, snippet="No content yet."（合成未完成）
memory_initiative capture → ok, 自动建 Initiatives 文件夹 kf-…, 页 kp-…，标记事实 ok
memory_initiative list → ok, count=1, markers=[]（标记事实异步落库，1~2 分钟后才有）

> ⚠️ 标记事实是异步的：capture 立刻返回 marker: {ok:true} 只代表入队成功，
> 事实真正落库要 1~2 分钟（服务端抽取 + 异步写）。刚 capture 就 list 看到 markers: [] 是正常的，不是失败。

knowledgePages: false 可整体关掉这一层（工具在 apply 时决定是否注册，见「缓存稳定性」）。

记忆维护（不只增）

Hindsight 的事实没有 DELETE 端点，只有软退役（state: "invalidated"）与可回滚改写。所以「维护」不是额外功能，而是记忆系统的必需品：写错的事实如果只能靠再写一条去覆盖，旧错事实仍会参与召回，认知错位就是这么积累出来的。

维护并入既有工具的动作（不新增工具，工具总数仍是 9）：

护栏（src/maintenance.js 的 guardAction）：

• 破坏性动作（retract / restore / correct / supersede / delete / clear）缺 confirm=true ⇒ 返回 {ok:false,error:"confirm_required"}，一个服务端请求都不发。
• 需要理由的动作（retract / correct / supersede）缺 reason ⇒ 返回 {ok:false,error:"reason_required"}。
• 事实层的退役是可逆的：restore 能把 invalidated 改回 valid——「删错」有回头路。
• 每条写路径都带 timestamp（本地时区）+ metadata.session_id，与 memory_retain 同口径。

配置：maintenanceStaleDays（默认 180，陈旧判定）、maintenanceStuckMinutes（默认 30，卡住任务判定）、maintenanceRequireConfirm（默认 true；不建议关）。

> 实测提醒：GET /memories/{id}/history 目前返回空数组（服务端还没记变更历史），所以「这条记忆什么时候被改的」只能看 edited_at；另外 correct 会让服务端重新嵌入该事实并丢弃它派生的 observation（宁可少一条观察，也不要留一条错的）。

三层模型：配方 / 事实 / 落后（维护能力的认知骨架）

知识页 = 内部 mental model 的外壳（页与内部模型 last_refreshed_at 同秒、字段一致）；正文永远由服务端 LLM 合成（UpdateNodeRequest 没有 body 字段）——所以「可维护」= 配方可改 + 落后可查 + 可删，不是「人能改正文」。手改正文会被下一次 consolidate 整个覆盖。

闭环：事实变 → is_stale=true → consolidate / refresh 按配方重算 → 新正文 → is_stale=false。删除知识页不可逆，且会让内部 mental model 变孤儿（后续刷新报 not found），慎用。

开发

node --test "test/*.test.js"     # 85 个单测（Windows 上不能写 node --test test/，会被当成模块解析）
node scripts/validate-market-index.mjs    # 市场索引闸门（格式 1 契约 + commit 与版本号对账）
node scripts/verify-live.mjs    # 活体自检（需要 Hindsight 服务在跑，8 项检查；per-project-tagged 口径）
node scripts/verify-live-per-project.mjs [apiUrl] [bankBase] [项目名]   # per-project 口径活体自检（9 项：写入落在独立 bank + 跨 bank 硬隔离负例）
node scripts/verify-dsh-runtime-e2e.mjs [apiUrl] [项目名]   # DSH 运行时端到端（从 dsh --dump-config 取真实配置喂插件，10 项）
node scripts/panel.mjs          # 状态面板（项目标签自动按 omp 同规则推导）
node scripts/hygiene.mjs        # 记忆卫生（默认只读预览；--apply 才作废，--consolidate 顺带合并）
node scripts/isolation-check.mjs --a <项目目录> --b <另一个项目目录>   # 两项目隔离可见性矩阵

已知差异（与 omp 的诚实账）

• 召回注入载体是 DSH 的用户消息，omp 是 `` 背景块——形状已对齐，载体不同。
• 自动召回结果未持久化进 session 文件，resume 会重查一次（omp 会重放缓存块）。
• 自动留存是「本回合文本」简化版，未实现 omp 的 full-session 整段重发 + document_id=sessionId；
  节奏已对齐（每 retainEveryNTurns=3 回合一次）。
• DSH 侧纯全局层读取需要「整库读 + 客户端过滤」（服务端没有「只取无标签」的表达）。
• omp 自己产不出全局层（它的 retain 恒带 project: 标签）；全局层目前只由 DSH 侧不传标签写入。
• 精神模型：DSH 与 omp 各建各的（id 前缀不同、互不覆盖）；DSH 侧不会去改 omp 建的模型。
• mental model 刷新要能跑完，得同时放宽服务端三个超时（REFLECT_WALL_TIMEOUT / LLM_TIMEOUT / worker 存活），
  客户端改不了；本机已把服务端超时放宽（1800/600/600）。
• 服务端版本：插件对齐 Hindsight 1.0 与 1.1（两版的 MCP 工具面与 REST 契约一致，recall 只多可选参数），
  所以升级服务端不需要改插件；反过来插件也不挑服务端小版本。

排障（踩过的坑，别重复踩）

版本沿革