dsh-persona-memory

持久化长期人格记忆插件 for DeepSeek Harness（DSH）。

让 agent 跨会话记住用户、项目与教训：事实写入磁盘永久保存，每次请求注入上下文；后台自动学习、纠正检测、失败记忆、容量合并让记忆"自己长出来且不失控"；磁盘格式与 pi-hermes-memory 字节兼容，DSH 与 Pi 可读写同一份记忆文件。

---

功能清单

A. 存储与共享

B. 读写与检索工具

C. 自动学习机制

D. 安全与约束

E. 工程与容错

---

借鉴来源（明确声明）

本插件大量借鉴 pi-hermes-memory（MIT，作者 chandra447，其本身移植自 hermes-agent）。按借鉴程度分四档：

1. 代码级移植（近逐行，MIT 保留声明）

2. 格式级兼容（字节兼容，实现重写）

3. 概念级移植（思路照搬，代码全新）

4. DSH 原生（未借鉴 hermes，基于 DSH API 构建）

> 刻意未移植：hermes 的 SQLite 会话搜索（DSH 原生 dsh-session-query-sqlite 已具备）、程序性技能（DSH 原生 skills 已具备）、子进程传输与 SQLite 锁协调器（DSH 插件进程内运行，不需要）。

---

工具与命令

安装到 DSH profile

源码为 TypeScript（index.ts + lib/*.ts + client/src/*.ts），发布产物由构建生成：npm run build（tsc 编译 Host 半区到 dist/ + esbuild 打包 Client bundle 到 client/client.js）。本地路径安装前需先构建。

插件声明了 "dsh": { "bundle": { "patch": "./cordis.patch.yml" } }，安装后 dsh 自动激活为 profile 层（无需手动挂载）：

# 构建（本地路径开发每次改代码后必做）
npm run build

# 安装（本地路径开发 / npm 发布版均可）
dsh plugin --profile web add file:E:/GitHub/lian_dsh
# 或：dsh plugin --profile web add dsh-persona-memory

# 重启 dsh web
dsh --profile web

file: 安装是真实副本——改代码后须重新构建、dsh plugin --profile web remove dsh-persona-memory 再 add（pnpm 有 store 缓存，只 add 可能装旧副本），最后重启 web。

如需覆盖配置（如 dir），在 profile 的 cordis.patch.yml 里按 id 覆盖即可（bundle 行在后层会被 profile 行覆盖）：

- id: persona-memory
  config:
    dir: C:/Users/Quophic/.pi/agent/pi-hermes-memory

配置（均可选）

dir 默认解析顺序：① 显式 config.dir → ② ~/.pi/agent/pi-hermes-memory（若已存在 MEMORY.md，即与 Pi 共用）→ ③ $DSH_HOME/memory（默认 ~/.dsh/memory）。

磁盘格式（与 pi-hermes-memory 一致）

<条目文本> <!-- created=2026-08-13, last=2026-08-13 -->
§
<另一条目文本> <!-- created=2026-08-13, last=2026-08-13 -->

• 条目以 \n§\n 分隔，每条是单行文本 + 行尾 <!-- created=YYYY-MM-DD, last=YYYY-MM-DD --> 注释。
• 无注释的旧条目照常解析（日期默认为今天）。
• 写入采用原子写（临时文件 + rename），并按文件串行化，避免并发工具调用互相覆盖。
• STANDING.md 例外：每行一条，无分隔符、无元数据（见下节）。

语义向量搜索（可选，默认关闭）

memory_search 默认走 FTS5 全文检索（字面匹配）；开启 vectorEnabled 后升级为混合检索：

• 存储不变：MEMORY.md / USER.md / failures.md 仍是唯一真相源，与 Pi 逐字节共用不变。
• 索引在 DSH 侧：.memory-vec.sqlite 存在 vectorIndexDir（默认 $DSH_HOME/memory），只存 embedding 数据（每条记忆的向量 BLOB + sha256 指纹），Pi 完全不感知；索引可随时删除重建。
• 指纹增量同步：每次搜索前对比文件条目 sha256，只对新增/变化的条目重新 embedding——Pi 改共享文件后自动跟上，不重复计算存量。
• 混合排序：FTS5 精确匹配 + 向量语义匹配通过 RRF（倒数排名融合） 合并，精确词与近义命中互相补足；向量不可用自动降级 FTS5/子串。
• 注入成本不变：结果仍 ≤searchMaxResults 条、只进工具输出，不常驻上下文。

启用示例（profile 的 cordis.patch.yml 覆盖）：

- id: persona-memory
  config:
    vectorEnabled: true
    embeddingProvider: local
    # embeddingModel: Xenova/all-MiniLM-L6-v2   # 默认，可换
    # embeddingCacheDir: C:/Users/xxx/.dsh/models # 默认 $DSH_HOME/models
    # embeddingRemoteHost: https://hf-mirror.com  # 大陆镜像（可选）

> 本地模型自动下载：embeddingProvider: local 时，插件自带 @xenova/transformers，首次使用自动从 HuggingFace 下载模型（默认 Xenova/all-MiniLM-L6-v2，约 80MB）到 $DSH_HOME/models，之后完全离线运行；下载进度会打印到 dsh 日志。网络受限时可用 embeddingRemoteHost: https://hf-mirror.com 走镜像，或预下载模型放入 embeddingCacheDir。 > > 远程方案（备选）：embeddingProvider: remote + embeddingBaseUrl（如 https://api.openai.com/v1）+ embeddingApiKey（或 DSH_EMBEDDING_API_KEY 环境变量）。DeepSeek 官方 /v1/embeddings 接口曾出现可用性问题（见 deepseek-ai/DeepSeek-R1#652），不建议依赖。

常驻指令（STANDING.md）

与 pi-hermes-memory 一致：每行一条，无分隔符、无元数据；容忍空行、# 注释和行首 -/* 列表符，手改时仍是普通 Markdown。注入块用 <standing-instructions> 围栏，声明"用户亲写的规则、始终生效、高于默认行为"；超预算时在块内部声明被省略的条数，绝不静默丢弃。

来源约束：只有 /standing 命令或用户直接编辑文件能写入——模型无写入口（后台学习、合并、纠正检测都不碰它）。

与 Pi 共用的注意点

• 避免同时写：两边都是原子写，但 Pi 有跨进程锁（.pi-hermes-locks.sqlite + recovery 文件），DSH 侧用写前指纹预检兜底——检测到外部改动就不覆盖并提示冲突。极端并发下仍可能互相感知不到，不同时运行最安全。
• 本插件覆盖 MEMORY.md / USER.md / STANDING.md / failures.md / projects-memory/（项目根与 Pi 一致）。
• 两边扫描标准一致（同一份 content-scanner 移植），hermes 写入的内容 DSH 直接可读，反之亦然；磁盘格式（含无尾随换行、project64、超限拒绝）已对齐 Pi v0.9.4 实测。

许可与致谢

MIT。磁盘格式、内容扫描器、常驻指令、纠正模式与合并策略移植自 pi-hermes-memory（MIT，作者 chandra447），其本身又移植自 hermes-agent。具体移植清单见上文「借鉴来源」。