dsh-memory

dsh-memory

DeepSeek Harness（dsh）的分层记忆插件： 项目级 / 全局记忆严格分离，任务前自动召回，任务后自动学习，不依赖模型"记得去复盘"。

• 当前版本 v0.3.2｜变更 CHANGELOG.md｜跨宿主升级 UPGRADE.md
• 宿主兼容见支持矩阵；Node ^22.19 || >=24（依赖内置 node:sqlite）
• 类型：host 插件（cordis v4），TypeScript / ESM，运行期零第三方依赖
• 设计存档（唯一决策来源）：docs/DESIGN.md

它做什么

三条不变量：项目记忆只写 <repo>/.dsh/memory、全局只写 $DSH_HOME/memory（默认 ~/.dsh/memory），跨库写入硬阻断； 插件故障不伤宿主（钩子整体 try/catch）；绝不写 stdout/stderr（日志只落文件）。

快速开始

# 发布版（推荐，固定 tag）
dsh plugin --profile nvim-tui add github:kovey/dsh-memory#v0.3.2
# 再把 "dsh-memory" 追加到 ~/.dsh/profiles/<profile>/package.json 的 dsh.profile.bundles
# ⚠️ dsh plugin add 只是在 profile 里执行 pnpm；只 add 不加 bundles = 装了但不加载

# 本地开发（link 到工作区；tui 是生产面，脚本默认拒绝操作它）
ln -sfn "$PWD" ~/.dsh/profiles/node_modules/dsh-memory
./scripts/install-into-dsh.sh --dry-run   # 先看要改什么
./scripts/install-into-dsh.sh             # nvim-tui / web / headless

重启 profile 后，~/.dsh/memory-plugin.log 出现 memory: ready (…) 即为就绪。 覆盖配置写在 profile 的 cordis.patch.yml，按 id 覆盖、不要重复 insert（loader 对重复 id 直接抛错）：

- id: memory
  config:
    recall: { autoInject: false }          # 只关自动召回
    prompt: { protocol: { enabled: false } }  # 关掉常驻协议段

dsh --patch <file> 的 overlay 实测不作用于本插件 config（六次真机运行 ready 行始终是默认值）——调参请用 profile patch。

支持哪些宿主和端

端无关。 插件只注入 ctx.tools 与 ctx.systemPrompt、只订阅核心 agent 事件，没有任何 surface 专用代码， 所以 nvim-tui / web / headless 同构可用。官方桌面端就是 web 应用的 Electron 壳，同样零适配—— 但它有独立的 $DSH_HOME/profiles/desktop，插件要单独装进那个 profile（CLI 的 web/tui profile 不共享）。

真正会挡住它的是宿主内核版本：5 个 @deepseek-ai/dsh-* peer 不匹配时，加载器会静默跳过整条 bundle （只写日志，记忆功能无声消失）。

被跳过时日志/启动 stderr 会出现 Plugin dsh-memory@… is incompatible with dsh …。 dsh plugin allow-version 能对精确 插件@版本 × 内核 显式豁免，但它只跳门禁、不解决 API 差异，跨大版本别用。

记忆放在哪

<root>（项目根或全局根）内固定这些内容：

lessons/*.md       记录，唯一真源（进 git）
MEMORY.md          人读索引，自动重生成（勿手改结构）
metrics.jsonl      任务指标（进 git）
profile/*.md       L5 偏好（进 git）
baseline.md        评估基线任务集（人所有，插件只读）
sessions/  archive/  proposals/    情节 / 归档 / 晋升草稿
memory.db(+wal/shm)  派生索引，不入库（.gitignore 已含）

全局根默认 ~/.dsh/memory，可用 DSH_MEMORY_HOME 重定向（测试用）；项目根由会话 header.cwd 经 git 解析得到（不看进程 cwd，同一仓库的 linked worktree 共享一个记忆根）。

工具

注册失败的工具不会出现在常驻协议段里——能力由实际注册结果推导，不是"打算注册什么"。

常用配置

默认值全在 cordis.patch.yml，profile patch 里只写要改的：

完整键表与取值范围以 src/config.ts 的 DEFAULT_CONFIG 为准。

语义召回（可选，默认关）

词法检索（FTS5 + CJK bigram）零成本、离线可用，是默认路径；只在词法召回不足时才调用 embedding， 失败静默降级为词法，向量按内容哈希缓存、未变动的记录不重复嵌入。默认关是因为它是除蒸馏外唯一会花钱的路径。

- id: memory
  config:
    semantic:
      enabled: true
      baseUrl: 'http://127.0.0.1:11434/v1'   # OpenAI 兼容 /embeddings；也可用 baseUrlEnv
      model: 'bge-m3'
      timeoutMs: 8000        # 冷启动要重载模型（~2.8s），默认 1.5s 会把自己中断
      minLexicalHits: 3      # 词法已召回 ≥3 条时不再调用
      maxAdditions: 2        # 每次最多补几条纯语义命中

19 条真实教训上的对照（复跑需先 npm run build：node scripts/eval-semantic.ts --root ~/.dsh/memory --minLex 3 --weight 0.3 --minSim 0.5 --maxAdd 2）：

结论：它救的是"换个说法就搜不到"那类查询，对原词查询无影响。 前提是端点真有 embedding 模型——本机网关没有该通道（text-embedding-3-small / bge-m3 等全部 model_not_found），所以默认配置下无法真机跑通；接上本地 Ollama 或独立端点后，用 memory_reindex({ embeddings: true }) 做一次全量回填，memory_stats 会显示索引量与最近错误。

上下文会不会被撑爆

不会。三条入口都有硬上限，与库大小无关：

实测 55 次注入：中位 234 tok、最大 592。增长的只有存储，且都有保留策略 （情节 90 天、召回记账 180 天、换模型后的旧向量 30 天宽限；记录只归档不删除）。

评估门禁

memory_stats({ windowDays: 30 })     // 健康度 + 门禁判定：pass / regression / unknown
memory_stats({ setBaseline: true, baselineReason: "用户要求；v0.3.2 发布后 7 天无回归" })

对比四项指标：成功率↑、耗时↓、打扰↓、返工↓（容差：成功率 ±0.05、耗时 ±15%、打扰/返工 ±0.5）。 没有基线时判定只能是 unknown——冻结基线是人工步骤：需要理由，子代理调用会被拒。 baseline.md 里的基线任务集属于其他仓库，插件无法自动重放，只会列出清单供人工回归； 它能自动判定的是任务日志实际承载的指标。

排障

日志 ~/.dsh/memory-plugin.log 超过 5 MB 自动轮转为 .log.1。插件从不写 stdout： TUI 拥有 stdout，web server 有自己的 console。

开发

npm install        # peer @deepseek-ai/* 已在 devDependencies（干净 clone 也能构建）
npm run build      # tsc → dist/（dist/ 入库，github: 安装免构建）
npm test           # 构建后 node --test 跑全量（不写死用例数——写死的数字会过期）
npm run typecheck  # 只做类型检查

测试全部在仓库内 .tmp-tests/ 运行，并把全局记忆根重定向到临时目录，不会触碰真实的 ~/.dsh/memory。 发布与安装链路（dev 链 vs 发布链、tui 为何拒绝 link）见 docs/RELEASE.md。

真机验证（隔离 profile + 隔离记忆根，不碰真实记忆）：

mkdir -p ~/.dsh/profiles/memlive && printf '[]\n' > ~/.dsh/profiles/memlive/cordis.patch.yml
cat > ~/.dsh/profiles/memlive/package.json <<'JSON'
{ "name": "dsh-profile-memlive", "private": true, "dependencies": {},
  "dsh": { "profile": { "bundles": ["@deepseek-ai/dsh-base", "@deepseek-ai/dsh-headless", "dsh-memory"] } } }
JSON
cp -R ~/.dsh/memory/lessons /tmp/dsh-live-mem/lessons      # 用真实语料播种，便于验证召回
DSH_MEMORY_HOME=/tmp/dsh-live-mem dsh --profile memlive "调用 memory_stats 并汇报记录数"
tail -20 ~/.dsh/memory-plugin.log                          # 期望：memory: ready + 注入行

文档