dsh-persona-memory

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

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

功能清单

A. 存储与共享

| 功能 | 说明 | |---|---| | 跨会话持久记忆 | MEMORY.md（事实/偏好/约定/环境）+ USER.md（用户画像），写入即永久保存 | | 每请求上下文注入 | 每次请求自动把当前记忆注入系统提示词（memory:profile 段，按字符预算截断） | | 与 Pi 共用记忆 | 磁盘格式与 pi-hermes-memory 完全兼容，DSH 与 Pi 读写同一份文件（MEMORY/USER/STANDING/failures/projects） | | 项目级记忆 | 每个项目独立记忆（git 仓库根为身份，worktree 共享），按会话 cwd 自动注入（memory:project 段） | | 记忆老化 | 条目携带 created/last 日期，合并时据此判断陈旧条目 |

B. 读写与检索工具

| 功能 | 说明 | |---|---| | memory 工具 | read / add / update / delete / rewrite；which 选 memory/user/failure；project 参数操作项目记忆 | | memory_search（混合检索） | 优先 FTS5 + 语义向量（RRF 融合）：FTS5 全文索引（<dir>/.memory-index.sqlite，mtime 自动重建）+ 向量索引（vectorIndexDir 下 .memory-vec.sqlite，只存 embedding、指纹增量同步、纯 JS 余弦）；向量未启用时走 FTS5，SQLite 不可用时回退子串扫描；结果始终 ≤searchMaxResults 条、只进工具输出，注入成本不随检索方式增加 | | 用量提示 | 所有 memory 操作返回用量百分比；达 90%（usageNudgeThreshold）提醒用 rewrite 合并 | | /standing 命令 | 用户管理常驻指令（列出 / add / remove / clear） | | WebUI 记忆管理页 | 设置页「记忆管理」区块（settings.section slot）：常驻指令增删改、三记忆文件条目编辑/删除、项目记忆浏览/编辑、FTS5/向量索引状态与重建、向量搜索配置（开关/模型/下载源/缓存目录）、已下载模型扫描与缓存检测、插件配置卡（40 项 schema 驱动全量配置）、本地备份卡（立即备份/恢复、自动备份、Pi 丢失自动切换） |

C. 自动学习机制

| 功能 | 说明 | |---|---| | 后台学习 | 每 learnIntervalTurns（默认 10）轮用会话自身 LLM 路由复习近期对话，自动提取持久事实存入记忆 | | 纠正检测 | /feedback 事件 + 对话内模式检测（强/弱/负向模式 + 指令词，仅直接人工消息，3 轮限频）→ 立即存 [correction] 失败条目 | | 失败记忆 | failures.md 结构化记录 [category] 内容 — Failed: 原因 — Corrected to: 修正；最近 7 天最多 5 条自动注入上下文（memory:failures 段），防止重蹈覆辙 | | 自动合并 | 记忆超限时用 LLM 合并精简（>30 天无引用可删、偏好/纠正优先保留）；只有结果严格更小、可解析且过扫描才提交，失败绝不损坏记忆 |

D. 安全与约束

| 功能 | 说明 | |---|---| | 内容扫描 | 每次写入过安检：提示注入/数据外泄载荷、API key/token/私钥、不可见 Unicode 字符一律拦截（防凭据落盘、防记忆被植入恶意指令） | | 常驻指令 | STANDING.md 每行一条、硬预算（20 条/2000 字符）、始终注入（memory:standing 段，早于其他记忆）；只有 /standing 命令或直接编辑能写——模型无写入口，防止模型把"常驻指令"偷偷注入 |

E. 工程与容错

| 功能 | 说明 | |---|---| | 原子写 + 单锁串行队列 | 临时文件 + rename，崩溃不留半截文件；add/update/remove 走单锁原子读-改-写（mutate），并发工具调用绝不互相覆盖；只读/纯写各自加锁 | | 跨进程写保护 | 写前 sha256 指纹预检（对照 Pi 的 ExternalMemoryWriteConflict）：外部（Pi/手动编辑）改过就不覆盖，重试一次后返回 conflict 提示 | | 与 Pi 字节兼容 | 对齐 pi-hermes-memory v0.9.4 实测：无尾随换行、charCount 含分隔符、USER 上限 5000、超限拒绝写入、failure 去重按 (text, project)、注入 <memory-context> 围栏 | | 优雅降级 | FTS5 不可用回退子串搜索；SQLite 动态 import，插件绝不硬依赖 | | 111 项冒烟测试 | 用真实 hermes 文件副本验证格式兼容、解析、读写、扫描、合并、项目、纠正、FTS、向量索引、溢出拒绝、字节格式、并发、围栏全链路 |

借鉴来源（明确声明）

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

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

| 文件 | 来源 | 移植内容 | |---|---|---| | lib/secret-scanner.ts | hermes content-scanner.ts | 11 条提示注入/外泄威胁模式 + 19 条凭据模式 + 不可见 Unicode 字符集 | | lib/standing.ts（核心） | hermes standing-instructions.ts | 容错解析（# 注释/-/* 列表符/去重）、硬预算（20 条/2000 字符）、<standing-instructions> 渲染块（超预算在块内声明遗漏）、来源约束（仅用户可写） | | lib/correction.ts | hermes correction-detector.ts 的模式部分 | 强/弱/负向三组正则 + 23 个指令词 + extractCorrectionDirective |

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

| 文件 | 来源 | 兼容内容 | |---|---|---| | lib/memory-store.ts（磁盘格式） | hermes MemoryStore | \n§\n 分隔符、encodeEntry/decodeEntry 正则（含 project64 字段）、YYYY-MM-DD 日期 | | lib/failures.ts | hermes buildFailureMemoryText | [category] 内容 — Failed: … — Corrected to: … 结构化文本 | | lib/projects.ts | hermes project.ts / paths.ts | 项目根解析（~/.pi/agent/projects-memory）、git 仓库根身份（worktree 共享）、迁移桥、cwd 检测 |

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

| 功能 | 来源概念 | 本插件实现 | |---|---|---| | 后台学习 | hermes 每 10 轮复习 | DSH session/event 钩子 + ctx.llm.stream + 自写提示词 | | 自动合并 | hermes auto-consolidate.ts | 超限触发、合并规则、严格更小才提交安全护栏 | | 纠正检测落库 | hermes 自动失败捕获 | feedback/record 事件 + 对话内模式 → [correction] 失败条目 | | 记忆老化 | hermes Memory Aging | created/last 日期驱动合并决策 |

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

| 模块 | 基于的 DSH 能力 | |---|---| | memory / memory_search 工具 | ctx.tools.register + defineTool | | 记忆注入段落 | ctx.systemPrompt 注册表（variable + section） | | /standing 命令 | ctx.commands 注册 | | lib/llm-helper.ts | 会话 request/header 路由解析 + ctx.llm.stream | | lib/fts.ts | node:sqlite FTS5（DSH dsh-session-query-sqlite 同款契约） | | 存储实现（原子写/队列/API） | 全新编写（hermes 的 MemoryStore 耦合 Pi API，无法直接复用） |

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

工具与命令

| 工具/命令 | 说明 | |---|---| | memory | read / add / update / delete / rewrite，which 选 memory / user / failure；project 参数操作项目记忆；failure 支持 category / failure_reason / corrected_to | | memory_search | query + 可选 which（memory/user/failure/all）+ 可选 project | | /standing | 列出常驻指令 | | /standing add <文本> | 钉住一条常驻指令 | | /standing remove <n> | 按 1 起编号移除 | | /standing clear | 清空 |

安装到 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 | 见下 | 记忆文件目录；显式设置优先 | | memoryCharLimit | 5000 | MEMORY.md 注入上下文的最大字符数 | | userCharLimit | 8000 | USER.md 注入上下文的最大字符数 | | enableSecretScanning | true | 是否启用写入扫描 | | inject | true | 是否注册系统提示词注入段落 | | sectionOrder | 55 | 注入段落在系统提示词中的顺序 | | searchMaxResults | 10 | memory_search 单次最多返回条数 | | usageNudgeThreshold | 0.9 | 达到该用量比例（如 90%）时在结果中提醒合并 | | correctionDetection | true | 收到 feedback/record 时自动存 [correction] 失败条目 | | correctionPatternDetection | true | 对话内纠正模式检测（强/弱/负向模式，仅直接人工消息） | | correctionRateLimitTurns | 3 | 对话内纠正保存的最小间隔（轮） | | memoryFtsEnabled | true | 启用 SQLite FTS5 记忆镜像（memory_search 全文检索） | | vectorEnabled | false | 启用语义向量搜索（memory_search 变混合检索：FTS5 + 向量 RRF 融合） | | vectorIndexDir | $DSH_HOME/memory | 向量索引目录（DSH 侧，绝不写入 Pi 共享记忆目录） | | embeddingProvider | remote | remote（OpenAI 兼容 /embeddings API）或 local（自带 transformers.js，模型自动下载） | | embeddingBaseUrl | '' | 远程 embedding API 基址（如 https://api.openai.com/v1） | | embeddingApiKey | '' | 远程 embedding API Key；不填则读 DSH_EMBEDDING_API_KEY 环境变量 | | embeddingModel | text-embedding-3-small | embedding 模型名（local 默认 Xenova/all-MiniLM-L6-v2） | | embeddingCacheDir | $DSH_HOME/models | local 模型缓存目录（首次自动下载到此处） | | embeddingRemoteHost | https://huggingface.co | local 模型下载源；大陆可用 https://hf-mirror.com | | adminProfile | web | 记忆管理页配置写回的目标 profile（~/.dsh/profiles/<名>/cordis.patch.yml） | | autoBackupMin | 60 | 自动备份间隔（分钟）；0 关闭；只保留最新一份快照到 $DSH_HOME/memory-backup/latest/ | | autoSwitchOnPiLoss | true | Pi 共享记忆丢失（曾见 MEMORY.md 后消失）时自动切到 $DSH_HOME/memory 并从最新备份恢复 | | learnEnabled | true | 是否启用后台自动学习 | | learnIntervalTurns | 10 | 每 N 轮（turn/end）触发一次复习 | | learnRecentTurns | 2 | 每次复习取最近多少个轮次的对话 | | learnMaxChars | 6000 | 复习用的对话/记忆摘要最大字符数 | | learnTimeoutMs | 120000 | 学习 LLM 调用的超时 | | standingEnabled | true | 是否启用常驻指令（STANDING.md + /standing 命令） | | standingCharLimit | 2000 | STANDING.md 注入预算（硬上限） | | standingMaxEntries | 20 | STANDING.md 最大条数（硬上限） | | autoConsolidate | true | 超限时自动 LLM 合并（严格更小才提交） | | consolidateStaleDays | 30 | 合并时判定"陈旧可删"的天数（无近期引用） | | consolidateTimeoutMs | 120000 | 合并 LLM 调用的超时 | | failureInjectionEnabled | true | 是否注入最近失败（learn from mistakes） | | failureMaxAgeDays | 7 | 失败注入窗口（按 created 日期） | | failureMaxEntries | 5 | 失败注入最多条数 | | failureCharLimit | 10000 | failures.md 字符上限（hermes 默认 memory×2） | | projectEnabled | true | 是否启用项目级记忆 | | projectCharLimit | 5000 | 单项目记忆字符上限 |

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。具体移植清单见上文「借鉴来源」。