SMPcosy/dsh-memnexus

DeepSeek Harness 的统一长期记忆插件：本地持久记忆 + L0~L3 分层蒸馏 + 上下文压缩摘要 + Hindsight 桥接 + 可视化记忆面板。

它把市面上几类记忆插件的长处合成一个包：

借鉴来源	拿走的能力	许可证
dsh-memory	插件骨架、检索排序、注入预算与去重	MIT
dsh-prime-memory	L0→L1→L2→L3 分层蒸馏、pre-step 自动召回、turn-stopping 自动捕获	MIT
billion-context-dsh	上下文压缩（compaction）事件的结构化摘要留存	MIT
@kira905/dsh-memory-toolkit	体检 / 导出 / 导入等工具集思路（未复制代码）	AGPL-3.0-only
@vectorize-io/hindsight-coding-agents	Hindsight REST bank 的拉取与推送桥接	上游未声明，见 docs/引用与参考.md

详细版本、代码级出处与合规说明见 docs/引用与参考.md。

它做什么

1. 自动沉淀：每轮对话结束，把这一轮压成结构化 L0 摘要（主题 / 用户诉求 / 结论 / 决定 / 待办 / 动作），不花 token。
2. 自动蒸馏（层数可配）：积累若干条 L0 后调用默认模型，抽取 L1 原子记忆；再把 L1 合成 L2 场景摘要；层数开到 3 才重建 L3 用户画像。默认 distillDepth=2，即在 L2 收手——越往上越抽象，也越容易失真。
3. 自动召回：每一步开始前按当前用户输入检索记忆（BM25 + 字符二元组模糊匹配的混合打分），把最相关的若干条注入上下文（有字符预算、按层配额、工作区隔离、来源标记）。召回走 systemPrompt.context，每步重算、跨步存活、不写进会话历史。
4. 压缩感知：会话发生上下文压缩（compaction）时，把压缩摘要额外留存成 L0 场景记忆，长任务不丢线索。
5. 可视化面板（侧边栏 + 独立整页 + 设置页三入口）：左侧边栏「记忆」图标进入 1180px 版心整页；设置页内保留嵌入版。浏览 / 搜索 / 筛选 / 新增 / 编辑 / 归档 / 删除 / 导入 / 导出 / 一键蒸馏 / Hindsight 拉取与推送；窄窗下可「放大查看」全列弹窗（筛选摘要 + 表头吸顶 + ESC/遮罩关闭）。
6. 模型工具（13 个）：memory_remember、memory_search、memory_recall、memory_get、memory_update、memory_forget、memory_list、memory_stats、memory_distill、memory_lineage、memory_audit、memory_export、memory_import。memory_lineage 回答「这条结论是从哪几条原始记录来的」。
7. Hindsight 桥接（可选，云端或自托管都行）：读 ~/.hindsight/coding-agent.json（或 HINDSIGHT_CONFIG）里的 apiUrl / apiToken / bankId，也可在面板里直接填；bank 留空时按 bankId → bankIdTemplate → Hindsight 使用日志里最近的 bank 自动识别（Hindsight 默认命名是 coding-agent::<项目名>）。云端后端必须配置 apiToken，否则请求会 401；自托管 hindsight-api 一般不需要 token（本机 127.0.0.1:8888 已验证推拉全通）。

安装

本目录就是插件包根目录，两种方式任选：

1. 插件管理器安装目录（推荐）：在 DSH 里让模型执行 plugin_manager 的 install_bundle，target 指向本目录的绝对路径；或 设置 → 插件管理 → 安装本地包。
2. 安装 tgz：解压 dsh-memnexus-0.0.4.tgz，把解压出的 package 目录按方式 1 安装。

装完重启 DSH，设置页出现「记忆」分区即成功。不要手工改 profile 的 package.json / cordis.patch.yml。修改代码后：宿主半（hooks / 工具 / 路由）需要重启 DSH 才生效，客户端半刷新页面即可。

数据在哪里

• 记忆：~/.dsh/storages/dsh-memnexus/memories.jsonl（JSONL，一行一条，可直接备份/手改）
• 配置：~/.dsh/storages/dsh-memnexus/config.json
• 导出：~/.dsh/storages/dsh-memnexus/exports/
• 设置 DSH_HOME 时以上路径随之改变。

配置项（面板「设置」或 config.json）

键	默认	说明
autoCapture	true	每轮结束写 L0 摘要
autoRecall	true	每步前注入相关记忆
autoDistill	true	自动跑 L0→L3 蒸馏
captureMinChars	60	一轮内容太短不沉淀
distillEvery	8	攒够多少条 L0 触发蒸馏
distillDepth	2	蒸馏层数 1/2/3：1=只到 L1 事实，2=再加 L2 场景，3=再加 L3 画像
llmTimeoutMs	120000	单次蒸馏调用的超时（本地 27B 上 L1 一次可能要 5 分钟）
recallLimit / recallMaxChars	8 / 1400	召回条数与字符预算
modelProvider / modelId	空	指定蒸馏模型，空=跟随默认模型
hindsight.enabled	false	启用 Hindsight 桥接
hindsight.apiUrl / apiToken / bank	空	Hindsight 服务地址 / token / bank（bank 留空自动识别）
hindsight.pullOnStart	false	启动时自动拉取

HTTP API（面板与外部共用）

前缀 /api/dsh-memnexus：

• GET /health、GET /stats、GET /config、POST /config
• GET /memories?q=&layer=&scope=&kind=&status=&limit=&offset=
• GET /export?format=json|jsonl|md
• POST /op → { op: 'create' | 'update' | 'delete' | 'bulk' | 'distill' | 'import' | 'config', args }
• POST /hindsight/import → { queries?: string[], limit?: number }
• POST /hindsight/push → { ids?: string[] }

自检与测试

离线测试（不需要 DSH 运行，也不需要网络与 token）：

node smoke-store.mjs      # 存储 / 去重 / 归档 / 替换导入 / 检索打分 / 层配额
node smoke-host.mjs       # 路由 / 工具 / 捕获 / 召回注入 / 蒸馏幂等 / 谱系
node smoke-client.mjs     # 模块契约 / 槽位注册 / 样式 token / i18n / 语言跟随
node smoke-hindsight.mjs  # bank 自动识别 + 本地假 Hindsight 服务的拉取/推送/404
node tests/it.mjs         # 真实 Harness 契约集成（12 项）
node tests/probe4.mjs     # 召回与安全行为探针（11 项）
node tests/probe5.mjs     # 蒸馏失败语义探针（10 项）
node harness/verify-client-next.mjs  # 真浏览器验收：headless Edge + CDP（29 项）
node harness/bench-rank.mjs 30000   # 检索吞吐基准（30k 行）
# 或一次跑完
npm run test:all

2026-11-01 发布前实测：npm run test:all 全绿（exit 0），四套 smoke + 契约集成 + 行为探针共 190+ 断言全部通过；真浏览器验收 29/29。

v0.0.2 自检修复的主要问题：替换导入会把已有行全部清空且重载后旧数据复活；强制蒸馏只标记不处理多余 L0；重复蒸馏会重复生成场景；面板语言不跟随应用语言；刷新按钮在关键词未变时不刷新；窄面板表格溢出；样式里硬编码颜色；召回/配置数值缺少夹取；归档后同文再记忆产生重复行；Hindsight bank 名与实际 bank 不一致。

v0.0.3 起新增：BM25+模糊混合检索（lib/rank.js，30k 行 60ms 内）；蒸馏层数可配（distillDepth，默认 2）；记忆谱系（sourceIds + memory_lineage）；净缩小护栏、分级重试与失败退避。v0.0.4：侧边栏入口 + 独立整页 + 全列弹窗 + 工具栏两级重排。

完整报告见 SELF-CHECK.md；综合评估见 docs/综合评估报告.md（总评 ≈7.9/10，2026-11-01）；制作过程见 docs/制作过程.md。

打包与发布

pnpm pack --pack-destination <输出目录>
# 或 npm pack --pack-destination <输出目录>

tarball 只包含运行时代码与公开文档（见 package.json 的 files 白名单），不含测试、研究笔记、复盘或记忆数据。发布前建议：

npm run test:all
pnpm pack --dry-run
pnpm publish --dry-run

设计取舍

• 不引入 SQLite：记忆条数是千级，JSONL + 内存索引足够，还免掉原生依赖与 Windows 路径坑；文件可直接备份、可读、可手改。
• 蒸馏失败不阻塞：没有模型、断网、超时都只记日志，已沉淀的 L0 摘要照样保留，下一轮再试。
• 注入有标记：注入消息的 source.kind 是 plugin:dsh-memnexus，捕获时自动跳过，不会自我污染。
• 越往上越抽象，所以默认在 L2 收手：L0 是原话，L1 是原子事实，L2 是场景摘要，L3 是画像。 每多折一层，文字就不再是原话；distillDepth 默认 2，需要画像再手动开到 3。
• 摘要必须真的更短：L2 折叠后若字数超过源文本 1.05 倍就拒收，宁可不折叠，也不写一条比原文还长的「摘要」。
• 结论要能回溯：L1/L2/L3 都记 sourceIds，memory_lineage 一路走回原始 L0 行，摘要不再吞掉出处。
• Hindsight 是可选桥：未配置时全部功能照常，只是拉取/推送按钮会提示未配置。
• 面板失败不影响工具：客户端注册全部包在 try/catch 里，slots 不可用就退化为「仅工具」形态。

已知限制

• 检索是中文友好的词 + 字符二元组匹配（BM25 + 模糊混合），没有向量语义检索；跨语言同义改写、意译可能搜不到（可配 Hindsight 走语义通道，混合检索在路线图 v0.3.0）。
• 召回文本每步重算、内容随检索结果变化，与上下文压缩类插件同场时会周期性打掉 system prompt 中段之后的部分前缀缓存（代价可量化、可缓解；召回文本稳定化排在路线图 v0.1.0）。
• 检索打分在内存里现算：万级记忆单次 10–60ms，十万级会明显变慢，届时该上倒排索引或向量库。
• L3 画像每次重建会整体覆盖（内容未变时不重复写盘），历史画像不留档（需要对比可先导出）。
• 面板删除是物理删除；日常清理建议用「归档」。
• 使用统计（useCount/lastUsedAt）批量落盘：进程被强杀时最后至多 50 次使用记录可能丢失。
• 插件重载后第一次 turn-stopping 会重扫整段会话；哈希去重能避免重复行，但那一次摘要会包含历史轮次。
• Hindsight 推送会把本地全部有效记忆写入 bank（自动去重由 Hindsight 侧决定），量大时注意 bank 体积。
• Hindsight 云端需要 apiToken；没有 token 时拉取/推送会返回 502/401，本地库不受影响。
• 面板视觉已用真浏览器（headless Edge + 主题 token）验收过深色对比度、640px 窄窗与键盘焦点，但真机 DSH 里的观感仍建议自己扫一眼。
• 蒸馏质量依赖所用模型：小模型容易被截断（已做拆分重试）或抽空（已做分级重试），提示词已要求逐字保留硬约束与版本号，但仍会有损。
• 层数开到 3 时 L3 画像会整体覆盖，不保留历史版本（需要对比请先导出）。

文档

• docs/制作过程.md — 调研、设计、实现、自检、打包全过程
• docs/引用与参考.md — 上游版本 / 许可证 / 代码级出处
• docs/发布与迁移指南.md — 新机器安装、打包、发布、迁移、卸载
• docs/ROADMAP.md — 升级路线与方案：v0.1.0 召回稳定化 → v0.2.0 记忆治理 → v0.3.0 混合检索 → v1.0.0 量化成熟
• docs/综合评估报告.md — 2026-11-01 综合评估（评分卡 / 竞品对比 / SWOT）
• CHANGELOG.md — 0.0.1 → 0.0.4 变更记录

许可

MIT，见 LICENSE。上游参考与许可证兼容性说明见 docs/引用与参考.md。