前言¶

用 DeepSeek Harness（DSH）开发智能体，绕不开一个问题：会话之间没有记忆。用户的偏好、项目的背景、之前定下的决定，每开一个新会话都得重新交代。

常见的补法有两种。一种是把记忆写成技能文件，靠模型自己主动加载——这是「软保障」，模型哪次忘了调，记忆就没进来；另一种是每次查询现走一遍检索——记忆永远现查现用，缺乏持续沉淀。dsh-plugin-memory 走的是第三条路：把记忆 boot 块随系统提示词运行时上下文在会话开头强制注入，做成「硬保障」。下面介绍这个插件的机制与用法。

这是什么¶

dsh-plugin-memory 是 LittleBlackTong 维护的 DeepSeek Harness 长期记忆插件：跨会话、可迁移、带「灵魂」（SOUL.md 人格文件）的 markdown 记忆库，会话开始自动注入。

基本情况：

• 当前版本 0.5.2，MIT 协议
• 纯 ESM JavaScript，零构建，无编译步骤
• 要求 Node >= 18
• 主入口 lib/index.js，CLI bin 为 scripts/memory.mjs（命令名 dsh-memory）
• peerDependencies：@deepseek-ai/cordis ^4.0.1、@deepseek-ai/dsh-skill ^0.1.2-alpha.1、@deepseek-ai/dsh-system-prompt ^0.1.2-alpha.1、@deepseek-ai/schemastery ^3.18.1

记忆库本身默认在 ~/.memory，是纯 markdown + git + 自描述 schema。插件只负责工作流，不锁定数据格式。

核心机制：开机强制注入¶

插件通过 ctx.systemPrompt.context() 把记忆 boot 块注入每个会话开头。boot 块由四部分组成：SOUL.md 人格、MEMORY.md 协议、index.md 目录，以及最近动态。

注入由宿主按投影去重：记忆内容不变时不重复注入，不白白消耗上下文；记忆更新后，新快照自动取代旧的。

这一点是它和技能文件做法的关键差别。技能只注入简介，正文靠模型主动加载，属于软保障；boot 块随运行时上下文自动进入会话，不依赖模型自觉调技能。

SOUL.md 铸魂¶

安装后的第一次会话，agent 的首要任务不是干活，而是与你对话定义它的灵魂：名字、性格、价值观、语气、边界。整个过程由 BOOTSTRAP.md 清单驱动，complete 之前优先于常规任务。

铸魂有自动引导机制：记忆库尚无灵魂时，boot 块会自动前置一段第一人称引导词，由 agent 在对话里主动发起铸魂，而不是等用户来喂。铸魂完成后引导词自动消失。

复利记忆：四个操作¶

日常记忆维护遵循 Karpathy 的 LLM Wiki 约定：记忆是「一次编译、持续保鲜」的持久产物，不是每次查询重新 RAG。对应四个操作：

1、remember（记）：把值得持久化的内容蒸馏成页面，同步更新 index.md、追加时间线；
2、recall（忆）：会话开始读 boot 块；查询时先查 index.md 再钻页，必要时用 dsh-memory search 全文检索；
3、consolidate（整理）：用 dsh-memory lint 做完整性体检，查矛盾、孤儿页和该归档的冷页；
4、forget（忘）：显式遗忘立即执行；自动衰减按 salience 三级衰减处理。

可迁移与 git 自动提交¶

记忆本体是纯 markdown + git + 自描述 schema，任何能读 markdown 的 agent 都能接手。跨机器迁移时，先在旧机器 pack 打包，再把归档拷到新机器 unpack 恢复，命令见下文 CLI 一节。

git 这一层也有机制兜底：记忆库发生变更后，静默 autoCommitQuietSeconds 无新改动，插件自动执行 git add -A && git commit；目录没有 .git 则跳过。历史可回滚，不再依赖 agent 记得手动 commit。

防懒 digest 与主动追忆¶

插件还提供两个空闲时的行为，都独立于 dsh-plugin-heartbeat，可单独安装、互不依赖。

防懒 digest 唤醒：每轮结束后，如果 agent 空闲、且记忆库超过 digestNudgeAfterMinutes 未写入，插件会注入一条 digest 提醒，把「会话收尾沉淀」从靠自觉变成机制兜底。带冷却与每会话限次，不会反复骚扰。

主动追忆：对话空下来时，插件以第一人称主动提起一件真实记得的事——用户偏好、往事、未了的决定或最近进展。间隔在最短与最长之间随机取值，每会话限次；纯对话行为，不写记忆库，不编造。

内嵌技能与文件技能的关系¶

插件通过 ctx.skills.register() 注册内嵌的 memory 技能，操作协议随插件分发。如果你项目里已有手写的 .dsh/skills/memory 文件技能，两者可以共存：文件技能（rank 100）会覆盖插件内嵌技能（rank 250）。

另一个注意点：如果你之前为了「软保障」改过系统提示词 persona（比如 profile 补丁里的开机指令），装上本插件后建议移除那段 persona，避免双份注入。

安装与启用¶

安装命令：

dsh plugin --profile <profile> add dsh-plugin-memory

包内置 dsh.bundle manifest，dsh plugin add 会自动把它挂进 profile 的 bundles 层。安装后重启 profile（DSH Desktop 重启应用）即生效。

有一个实机踩过的坑要强调：不要往 profile 的 cordis.patch.yml 手写 - insert: {id: dsh-memory, ...}。这会与 bundle manifest 的自动挂载产生两条同名 entry，profile 会以 duplicate loader entry id "dsh-memory" 启动失败（2026-08-18 实机事故）。需要覆盖 composition 配置时，用不带 insert 的 id 覆盖条目，例如把 boot 块字符预算调大：

- id: dsh-memory
  config:
    bootMaxChars: 12000

配置：热改层与 composition 层¶

配置分两层，改动方式不同。

运行期配置走 <dshHome>/memory.json（schema 校验、原子落盘），由插件自注册的 GET/POST /api/memory/config 路由服务，在 DSH 设置页「记忆 Memory」区块修改。可热改的共八项，立即生效、无需重启：

• enabled：总开关
• memoryDir：记忆库目录
• autoInject：开机注入
• registerSkill：技能注册
• recallEnabled / recallIntervalMinMinutes / recallIntervalMaxMinutes / recallMaxPerSession：主动追忆的开关、随机间隔范围与每会话次数

其余键——bootFiles、bootMaxChars、scaffold、configFile、digestNudge、autoCommit 等——只在 composition 配置层生效，改完需重启。完整键表见仓库 README 的配置一节。

CLI 工具¶

插件自带 dsh-memory 命令行，覆盖从初始化到迁移的完整流程：

dsh-memory init [dir]                 # 创建记忆库脚手架
dsh-memory search <query>             # 全文检索
dsh-memory lint                       # 完整性体检
dsh-memory status                     # 健康概览
dsh-memory pack [out.tar.gz]          # 打包导出
dsh-memory unpack <archive> [--force] # 从归档恢复

CLI 定位记忆库的顺序是：$MEMORY_DIR → ./.memory（存在时）→ ~/.memory。

开发与自测¶

想看实现或做改动，先克隆仓库，再跑一次冒烟测试：

git clone https://github.com/LittleBlackTong/dsh-plugin-memory.git
cd dsh-plugin-memory
node scripts/memory.mjs --self-test

--self-test 无需安装依赖即可运行。零构建意味着 lib/ 直接就是运行时代码。

适用场景与注意¶

适合的场景：

• 希望 agent 跨会话记住用户偏好、项目背景与历史决定；
• 需要按项目隔离记忆时，把 memoryDir 配到项目内（CLI 会优先识别项目内的 ./.memory）；
• 记忆含敏感内容时，可把 memoryDir 放进加密卷或私有仓库，格式不变，插件无感知。

安装前的两点提醒：

1、插件以当前 dsh 进程的权限运行，安装前应检查插件源码与许可证（MIT）；
2、本插件与 dsh-plugin-heartbeat 相互独立，按需选用即可。

结尾¶

回顾一下：boot 块强制注入解决「新会话必先加载记忆」，SOUL.md 铸魂解决身份一致，markdown + git + pack/unpack 解决迁移，digest 提醒与主动追忆让记忆被真正用起来。如果你在 DSH 上做需要长期陪伴的 agent，值得装上试一次。

DSH 的理念是「一切皆插件」，dsh-plugin-memory 是这个生态里的一员。插件同时收录在社区目录 skillhub.cn——该目录为独立站点，与 DeepSeek、幻方无官方从属关系。

• GitHub：https://github.com/LittleBlackTong/dsh-plugin-memory
• 目录页：https://www.skillhub.cn/plugins/LittleBlackTong/dsh-plugin-memory