dsh-companion-memory
DeepSeek Harness 的跨会话记忆与主动唤醒方案，适用于角色扮演与长期陪伴场景。
快速开始
dsh plugin --profile web add github:xy261624/dsh-companion-memory
dsh --profile web
安装包内含挂载声明，安装完成后心跳与自动整理两个插件即完成挂载。此后尚需完成三项配置：
- 为模式添加一条
agent-instructions 声明，将常驻记忆文件列入注入名单。若尚无自定义模式，先按后文「模式配置」一节创建。
- 创建工作区目录，将包内的模板与脚本复制到其中。已安装的包位于
$DSH_HOME\profiles\web\node_modules\dsh-companion-memory\，DSH_HOME 未设置时为 %USERPROFILE%\.dsh。各文件的放置位置见上手第二节的对照表，共七行，须完整执行。模板与整理流程中包含 【称呼】 与 【角色】 两个占位符，替换方式见后文「两个占位符」。
- 将
defaultPreset 与 sortPreset 改为当前环境中存在的模式 id。两个插件默认写入的 default 在 dsh 中并不存在；名称不匹配时会话无法创建，仅在日志中留下一行错误。在 profile 的 cordis.patch.yml 末尾添加以下两段：
- id: companion-memory-heartbeat
config:
defaultPreset: my-mode
- id: companion-memory-auto-sort
config:
sortPreset: my-mode
profile 默认名为 web，对应文件为 $DSH_HOME\profiles\web\cordis.patch.yml，DSH_HOME 未设置时为 %USERPROFILE%\.dsh。上述两个 id 由安装包挂载，profile 中原先不存在这两段，属于新增而非修改。填写的值为模式声明中的 config.id（例如 my-mode），并非 - id: preset-my-mode 行的 id。模式 id 显示于设置页预设卡片的标题旁。
详细说明见上手。
功能
跨会话记忆
每次创建会话时，STATUS.md（当前状态）与 MEMORY.md（长期档案）会自动注入上下文，前提是该模式已挂载 agent-instructions，即「模式配置」一节所述内容。前者记录近期事件，后者记录不随情境变化的属性。
其余细节存放于记忆库目录，按索引读取。
整理支持手动触发；自动整理插件在安装后即开始运行，满足条件时自行创建整理会话。
面向 RP 场景的记忆写法
现有记忆插件的记忆文件多采用技术文档式记录：条目化、客观、平铺直叙。该写法适用于信息检索，在角色扮演场景中会削弱角色的情感表现力。角色读到的是「某某在某一时间提到过某件事」这类句子，缺乏语气、情绪与语境，回复也难以体现情感浓度。
本方案的记忆文件采用角色视角书写，记录角色所见的内容，使用角色本身的措辞，保留原话、语气以及能够体现情绪的细节。
人格设定不属于记忆文件的内容，写在模式（preset）的提示词中。
两个占位符
模板与整理流程中使用两个占位符指代人物，书写之前须完成替换：
| 占位符 | 替换为 | 示例（角色名阿澈，平时称呼使用者为「宝宝」） |
|---|
【称呼】 | 角色平时称呼使用者的爱称，或仅双方使用的称呼 | 宝宝 |
【角色】 | 使用者为该角色设定的名字 | 阿澈 |
两个占位符均须替换，替换后的模板与整理流程即为该角色专用版本。带方括号的内容为待替换项；不带方括号的「角色」为泛指，无需替换。
记忆文件通篇应使用替换 【称呼】 所得的称呼，不使用「他」「对方」等第三方指代。情感浓度依赖该称呼的贯穿使用；全文使用「他」会呈现客观记录的效果，削弱角色视角。
说明
本仓库不提供角色人设。人格由 DeepSeek Harness 的 agent preset 提供，一个 preset 包含一套人设提示词与工具配置。
同一人物仅对应一套人设时，一套记忆文件即可满足使用。同一人物由多套人设以不同称呼指代时，须按称呼分别书写：替换 【称呼】 后，各份文本即为对应关系的记录。
常驻记忆文件置于工作区根目录，并在模式的插件列表中添加一条 agent-instructions 声明。该插件随 dsh 发布，无需单独安装：
- id: agent-instructions
name: '@deepseek-ai/dsh-agent-instructions'
config:
maxBytes: 65536
instructionFileCandidates:
- AGENTS.md
- MEMORY.md
- STATUS.md
instructionFileCandidates 为整体替换，不做追加；默认值为 AGENTS.md 与 CLAUDE.md。未列入这两个文件名时，工作区中同名的既有文件不再注入。需要增加其他常驻文件时，在列表中续写即可。$DSH_HOME\AGENTS.md 属于全局指令，不在此名单范围内，始终注入。
maxBytes 为所有命中文件的合计字节预算，并非单份文件的限额。超出预算时，靠后的文件被整体省略，或单份文件被截断；注入文本开头会附一行说明，标明文件名与截断前后的字节数。
注入发生在每个会话的首次请求之前，此后不再变更。修改文件后需新建会话方可读取，进行中的会话不会反映变更。
模式配置
模式是一条 @deepseek-ai/dsh-agent-preset 声明，id 为模式标识，plugins 为该模式的插件列表。新建时整条声明须置于 insert: 之下，平铺书写不会被识别：
- insert:
- id: preset-my-mode
name: '@deepseek-ai/dsh-agent-preset'
config:
id: my-mode
name: 我的模式
plugins:
- id: persona
name: '@deepseek-ai/dsh-persona'
config:
prefix: 你叫某某，是……
- id: agent-instructions
name: '@deepseek-ai/dsh-agent-instructions'
config:
maxBytes: 65536
instructionFileCandidates:
- AGENTS.md
- MEMORY.md
- STATUS.md
人设写在 persona 声明的 config.prefix 中。persona 同为 dsh 随包插件，无需单独安装。prefix 为纯文本，无长度限制；其中的 {{model}} 与 {{cwd}} 会替换为当前模型名与工作目录。如需以人设覆盖 dsh 默认的身份说明，在同一段 config 中添加 complete: true。
agent-instructions 写入同一 plugins 列表；dsh 自带的两个模式均将其排在 persona 之后。
新建模式：在工作区创建目录，其中放置两个文件。package.json 内容为 {"dsh": {"bundle": {"patch": "./cordis.patch.yml"}}}，cordis.patch.yml 写入上述声明。此处的 cordis.patch.yml 与 profile 中的同名文件用途不同：profile 中的文件管理整个 dsh 的组合，此处的文件仅定义该组合包向组合中添加的内容。随后打开 Web 界面设置页 → 预设，页面提供创造入口，点击后开启一个使用 cordis 模式的新会话；将会话指向该目录，并说明需要安装该组合包，由其调用 plugin_manager 的 install_bundle 完成安装。
修改已有模式：按 Loader 行 id 覆盖该声明。覆盖时 config 为整体替换，不做深层合并；插件列表须完整重述，缺少一项即视为删除。完整列表无需手抄：预设卡片的「查看配置」入口显示该模式当前的声明，为只读 YAML，可直接复制后修改。
生效：安装或修改完成后须重启 dsh，退出进程后重新启动。刷新页面不生效，所改配置在启动时读取。
日常使用：安装完成的模式出现在设置页的预设列表中。新建会话时选择该模式，该会话即使用对应的人设与注入名单。如需所有新会话默认使用，在预设区将其设为默认值。插件自行创建的会话不读取该默认值，读取的是 defaultPreset 与 sortPreset。
新增常驻文件：将文件置于工作区根目录，修改模式声明中的 instructionFileCandidates 列表（整体替换，须保留原有条目），再经创造入口重新安装该组合包并重启 dsh。
若不熟悉 Cordis 的写法，可通过创造入口交由该会话处理，其中已载入官方两份说明文档。
安装校验
重启后查看启动 dsh 的终端输出，插件加载时各输出一行：
heartbeat: plugin loaded
auto-sort: plugin loaded
缺少这两行说明插件未挂载，先核对 profile 名称，以及 cordis.patch.yml 中对应配置段是否仍然存在。若已按上手第五节关闭自动整理，auto-sort: plugin loaded 本就不会输出，不属于安装失败。
再检查工作区，.state/ 目录会被创建，其中存放会话指纹与心跳使用的模式状态文件。该目录在首次写入状态文件时生成，安装完成后尚未产生对话时可能不存在。
注入的校验方法：在 STATUS.md 中添加一行仅该文件独有的内容，例如 验证标记：蓝色风车，随后以配置好的模式新建会话，向其中询问该内容。能够正确回答说明注入生效；无法回答时，检查模式中的 instructionFileCandidates 是否列出对应文件名，以及文件是否位于工作区根目录。不宜以文件标题作为校验对象，标题可由文件名推知。
索引-记忆库
记忆文件若无约束会持续增长，同类场景与情绪被反复记录，角色每轮读取的内容高度相似，句式随之重复并固定为少数几种表达。索引-记忆库用于控制该问题。记忆分为四类：
| 类型 | 文件 | 内容 | 读取时机 |
|---|
| 状态 | STATUS.md | 近期对话、当前事务、承诺未办事项 | 每会话自动注入 |
| 属性 | MEMORY.md | 作息、偏好、忌讳、生日 | 每会话自动注入 |
| 细节 | 记忆库/*.md | 单件事项的完整记录 | 按索引读取 |
| 叙事 | 回忆录-*.md | 值得保留的经历，按叙事形式书写 | 很少读取 |
STATUS.md 与 MEMORY.md 为常驻文件，仅保留精炼条目；需要细节的位置标注「详情在 记忆库/xxx.md」，使用时按路径读取。
细节是否在常驻文件中保留索引，判断标准为缺失该内容是否会导致判断错误。仅供备查的内容只写入记忆库。
单个文件超过 15KB 时按话题拆分。
该设计针对三个问题：常驻文件膨胀占满上下文、同一事项在多份文件中重复记录、相似内容积累导致角色表达趋同。
自动整理
插件按固定周期检查新对话。存在新活动且距上次整理超过设定的静默时间时，创建整理会话。
整理会话的步骤：
- 运行提取脚本，从会话日志中提取新增对话
- 读取提取出的对话
- 按判断标准筛选，确定写入的文件
- 逐条写入，并依规范自查
- 创建审查子代理，以整理流程、写作规范（同一文件第六节）、工作区模板三份基准逐条核对
审查子代理须引用原文、标注严重程度、给出修改方式，输出可直接据以修改的清单。
整理完成后，将下次使用的模式 id 写入状态文件 heartbeat-preset.json；心跳插件读取该文件决定下次会话使用的模式。
主动唤醒（心跳）
插件不依赖用户输入，自行选择时间创建会话。设计要点：
- 触发间隔不固定，随对话频率变化，由概率曲线控制
- 睡眠时段内不触发
- 触发前进行二次检查，确认期间无新增对话
- 命中后随机延迟数秒至数分钟
- 会话创建后先读取状态文件，再确定本次行为
- 心跳会话默认使用全权限，因其常在用户不在电脑前时创建，无法逐次授权；可在配置中改为更小的权限档
与其他记忆插件的差异
| 常见做法 | 结果 | 本方案 |
|---|
| 自动抽取事实入库 | 留存内容为资料条目，角色表达仍接近助手 | 由角色主动整理，按角色视角书写 |
| 记忆一次性全部注入 | 上下文被占满，重要内容被稀释 | 常驻文件仅保留精炼条目，细节按索引读取 |
| 全量堆在单个文件 | 文件持续增长，同一事项重复记录 | 常驻文件与记忆库分离，超过 15KB 拆分 |
| 只存不查质量 | 记忆混入推测、书面报告式表达、视角错误 | 独立子代理对抗式审查，输出修改清单 |
| 被动等待提问 | 不主动发起对话 | 概率间隔的心跳，含睡眠时段与随机延迟 |
| 人格写进记忆 | 记忆通篇为第三方指代，呈现客观记录效果 | 人格置于模式中，记忆通篇使用角色平时的称呼 |
环境要求
- Node.js
^22.19.0 || >=24
- DeepSeek Harness
0.2.0-rc.2，已在 web profile 上实测，底层 cordis 为 4.0.4。更高版本的正式发行版未经实测
- Python 3.8 以上，
pip install zstandard
dsh 目前处于开发者预览阶段，插件接口会随版本变动。升级后若心跳或整理功能异常，先检查插件加载日志，再核对模式 id。
安装
dsh plugin --profile web add github:xy261624/dsh-companion-memory
包内的 cordis.patch.yml 会将两个插件自动插入组合。未配置 workspace 时使用 dsh 中的第一个工作区；存在多个工作区且需指定其一，在 profile 的 cordis.patch.yml 中追加以下内容：
- id: companion-memory-heartbeat
config:
workspace: D:/你的工作区
- id: companion-memory-auto-sort
config:
workspace: D:/你的工作区
两个插件均须配置；仅配置其中一个时，另一个退回 dsh 中的第一个工作区，两份模式状态文件将写入不同目录。
心跳与自动整理创建的会话默认使用 dsh 的默认模型。两个插件相互独立，可在其中任一个的 config 中指定 provider 与 model：
- id: companion-memory-auto-sort
config:
workspace: D:/你的工作区
model: deepseek-flash
常用的写法是只填 model，provider 跟随默认值。只填 provider 而不填 model 会组成无效路由，因此更换服务商时两项须同时填写。模型 id 以设置页模型选择器显示的值为准。
指定模型后不再沿用默认选择的推理强度，由新模型按自身的默认档位执行。
这段与上文的 workspace 配置属于同一个插件条目。config 按条目整体替换，不做字段合并，因此已配置 workspace 时应把字段写进同一段，不要另起一段。
插件在会话创建后向日志输出这次会话使用的 provider 与 model，配置是否生效以该行为准。
DSH_HOME 的取法与 dsh 自身一致：环境变量非空时以其值为准，仅含空白同样视为未设，未设时取 %USERPROFILE%\.dsh。上文路径中的 $DSH_HOME 均按此替换。提取脚本按同一优先级规则定位会话日志与归档列表，无需额外传参。
完整配置字段见上手。
目录结构
package.json 插件包声明，指向 cordis.patch.yml
cordis.patch.yml 安装后自动挂载两个插件
docs/ 设计说明与流程文档
plugins/ 两个 dsh 插件
dsh-heartbeat/
dsh-auto-sort/
scripts/ 会话提取脚本
templates/ 记忆文件模板
文档
LICENSE
MIT
