认知记忆运行时 snowfoxHQ/dsh-hmr

dsh-hmr — dsh-Hestia Memory Runtime

全名：dsh-Hestia Memory Runtime（包名 dsh-hmr，工具前缀 hmr_，可简称 HMR 认知记忆）。

把 HMR 认知记忆运行时接入 DeepSeek Harness (dsh) 的 monorepo。

HMR 提供的不只是「存笔记 + 搜笔记」，还有显式推理链、反思循环、主动遗忘曲线和自我演化。
dsh-hmr 把这些能力包装成 dsh 插件，让 harness 里的智能体拥有跨会话的认知上下文。

名称说明：官方 @deepseek-ai/dsh-hmr 是热更新（hot module replacement），与 dsh-Hestia Memory Runtime 同名不同物，二者无代码关联。

目录结构

monorepo 按「可发布的 dsh 插件」「dsh 技能」「共享库」三类分目录：

dsh-hmr/
├── docs/
│ └── dsh-listing.md # 提交给 dsh 插件目录的条目文案（显示名：dsh-Hestia Memory Runtime） ├── packages/ │ └── hmr-client/ # 共享 TS 库，封装 HMR 的 HTTP 接口（独立 npm 包） ├── plugins/ │ └── dsh-hmr/ # dsh 插件本体，注册 hmr_* 工具（独立 npm 包） ├── skills/ # dsh 技能目录（当前为空，见 skills/README.md） ├── patches/ # 插件依赖但上游未合并的服务端修复，构建时打到副本上 └── vendor/ └── hmr/ # HMR 上游仓库（git submodule，保持 origin 原样） ├── hmr/ # Python 认知运行时 └── service/ # FastAPI HTTP 服务（127.0.0.1:8077）

新增内容时的归属：dsh 插件放 plugins/<name>/，dsh 技能放 skills/<name>/，被多个包复用的库放 packages/<name>/；三者都是 npm workspace，都会随 npm run build/test 一起跑。

vendor/hmr 保持上游纯净：子仓永远停在 origin/main 的某个提交上，不改文件、不打本地提交。
插件确实需要的上游修复放在 patches/.patch，由 scripts/vendor-python.mjs 在复制到 plugins/dsh-hmr/python/ 之后应用到副本上（见 patches/README.md）。
这样 git -C vendor/hmr status 恒为干净，发布物里又包含修复。

架构

dsh agent
│ hmr_ 工具 ▼
plugins/dsh-hmr (Node.js 插件)
│ HTTP + x-hmr-token
▼
vendor/hmr/service (Python · FastAPI · 127.0.0.1:8077)
│
▼
vendor/hmr/hmr (认知运行时：SQLite + 向量索引 + 推理链)

插件默认以 managed 模式拉起 Python 子进程；把 dsh-hmr.process 设为 external 则退化为连接已有服务（适合已经常驻跑着 HMR 的场景）。

快速开始

只想用插件、不想改代码？ 不用 clone 本仓库：先装宿主程序 dsh（npm i -g @deepseek-ai/dsh），再 dsh plugin --profile web add dsh-hmr。完整步骤见 plugins/dsh-hmr/README.md。
下面是从源码构建的开发者流程。

1. 拉取 HMR 子模块
git submodule update --init --recursive

2. 安装 Python 依赖（插件通过 PYTHONPATH 直接加载 vendor 源码，无需 pip install -e）
pip install pydantic numpy fastapi uvicorn
pip install sentence-transformers # 可选，缺失时退化为 TF-IDF

3. 安装 Node 依赖并构建
npm install
npm run build

4. 自检 Python 环境与内置运行时
node plugins/dsh-hmr/dist/cli.js doctor

5. 在 dsh 中启用插件
dsh plugin --profile web add ./plugins/dsh-hmr

环境变量

插件会把下列变量透传给 HMR 子进程；embedding 后端完全由你在这里决定：

| 变量 | 默认 | 说明 |
| HMR_STORAGE_PATH | ~/.dsh-hmr/data | 记忆数据目录；盘符不存在时插件会忽略并回退到默认值 |
| HMR_HOST | 127.0.0.1 | 监听地址，不要改成 0.0.0.0 |
| HMR_PORT | 8077 | 服务端口 |
| HMR_TOKEN | 空 | 设置后客户端必须带同名 x-hmr-token |
| HMR_ST_MODEL | all-MiniLM-L6-v2 | 本地 embedding 模型 |
| HMR_OLLAMA_MODEL | 空 | 走 Ollama embedding 时指定模型 |
| OPENAI_API_KEY | 空 | 优先级最高的 embedding 来源 |

优先级：OPENAI_API_KEY > HMR_OLLAMA_MODEL > HMR_ST_MODEL > TF-IDF 兜底。

工具（暴露给智能体）

| 工具 | 作用 |
| hmr_ingest | 写入记忆，可交给 Policy 自动判定类型 |
| hmr_recall | 主动召回，支持 Policy 选策略 |
| hmr_think | 起一条思考链并记录推理步骤 |
| hmr_reflect | 对思考链做反思，产出洞察与建议记忆 |
| hmr_evolve | 运行自我演化周期（支持 dry-run 预览） |

安全

- 服务只绑 127.0.0.1，不要对外开放。
- 不要把抓取来的不可信网页内容直接写进长期记忆（memory poisoning）。
- HMR_TOKEN 建议在多人共用的机器上设置。

开发

git clone --recursive https://github.com/snowfoxHQ/dsh-hmr.git # vendor/hmr 是子模块
npm install
npm run build # 两个包全量构建（插件会先把 vendor/hmr 复制进 python/ 并打 patch）
npm run typecheck
npm test # 两个包的集成测试，会真实拉起 Python 服务

已 clone 但没带 --recursive 时补一步：git submodule update --init --recursive。

全链路回归（用真实 agent 跑一遍 hmr_ 工具）：

dsh plugin --profile headless add ./plugins/dsh-hmr
dsh --profile headless "用 hmr_ingest 记录一条记忆，再用 hmr_recall 查回来"

vendor/hmr 是只读上游子模块，不要在子仓里做任何提交。确实需要的服务端修复写成 patches/.patch，由 vendor:python 在复制副本时应用（详见 patches/README.md）。

发布

npm run preflight # npm pack 预检：元数据、tarball 清单、解包后 import 冒烟
npm run release:dry # 干净工作树 + 构建 + 预检 + npm publish --dry-run
npm run release # 真正发布（默认 latest；可加 -- --tag next --otp 123456）

release 按 @dsh-hmr/hmr-client → dsh-hmr 的顺序发布，两个包共用同一个版本号，版本不一致会直接拒绝。发布前会检查该版本是否已存在于 npm，发布后会回查 npm view 确认。

如果本机 npm 指向镜像（npmmirror / taobao 等），脚本会拒绝发布并提示改用官方源：

npm run release -- --registry https://registry.npmjs.org

首次发布前还需要在 npm 上创建 @dsh-hmr scope，并让 registry 指向官方源（镜像只读）。完整的一次性准备、key/2FA 说明、验证命令与错误排查见 RELEASING.md。

License

MIT，与上游 HMR 一致。