YaoQC-Ai/dsh-memory-plugin

dsh-memory-plugin

Give your DeepSeek-Harness a memory that actually sticks. —— 让你的 DSH 真正记住每一次对话，长出一只可用的“长期记忆”。

每个 Agent 都会在会话结束那一刻“失忆”。dsh-memory-plugin 给
DeepSeek-Harness（dsh）装上真正的
记忆骨架 —— 下一个会话能顺接着上一个往下聊。
无需外部服务、无需构建、无需维护 schema。零依赖。

开箱即得：

- 🧠 跨会话记忆 —— 每轮自动捕获，新会话开始时将最近几轮重新注入为背景（L1 短时记忆）。
- 📚 沉淀重要内容 —— 一等模型工具（memory_save）写入持久、自足的知识页，在对话结束后长久留存（L2 写入半）。
- ⏰ 保持新鲜 —— 定时维护任务（memory-timer）每天 02:00 照看记忆仓，dry-run 安全。
- 🔍 可选语义召回 —— 叠加官方 Memorix MCP memory
server
做真正的语义搜索（L3）。

所有 Agent 都会在会话结束那一刻“失忆”。dsh-memory-plugin 给 DSH 装上真正的记忆骨架——
下一个会话能顺接着上一个往下聊。无需外部服务、无需构建、无需维护 schema，零依赖。

开箱即得：

- 🧠 跨会话记忆（L1）—— 每轮自动捕获，新会话自动召回注入；
- 📚 知识沉淀（L2 写入）—— memory_save 模型工具落盘自足的概念页；
- ⏰ 自动维护（定时器）—— 每天 02:00 温控记忆仓，dry-run 安全；
- 🔍 可选语义召回（L3）—— 叠加官方 Memorix MCP，做真正的语义搜索。

一个包、三个宿主插件（每个都是 cordis.patch.yml 的一行；本 README 详述 L1 插件，并概述两个兄弟插件）：

| 插件行 | 文件 | 作用 |
|---|---|---|
| dsh-memory-plugin | index.js | L1 跨会话短时记忆 —— 捕获 / 召回 / 淘汰 / 恢复（本文档） |
| dsh-memory-plugin/save | save.js | memory_save 模型工具 —— 把概念页写入 /memory/knowledge/ |
| dsh-memory-plugin/timer | timer.js | memory-timer —— 定时维护任务（默认本地时钟 02:00，dry-run 安全） |

为 DeepSeek-Harness（dsh）提供跨会话短时记忆（L1）。零依赖、零构建 —— 纯 Node 内置模块 + 内联构造 UserMessage。

一个包、三个宿主插件（每个都是 cordis.patch.yml 的一行；本 README 详述 L1 插件，并概述两个兄弟插件）：

| 插件行 | 文件 | 作用 |
|---|---|---|
| dsh-memory-plugin | index.js | L1 跨会话短时记忆 —— 捕获 / 召回 / 淘汰 / 恢复（本文档） |
| dsh-memory-plugin/save | save.js | memory_save 模型工具 —— 把概念页写入 /memory/knowledge/ |
| dsh-memory-plugin/timer | timer.js | memory-timer —— 定时维护任务（默认本地时钟 02:00，dry-run 安全） |

English

What it does

让 Agent 在新会话开始时记住最近几次会话聊过什么。

- 捕获（Capture） —— 在 agent/turn-stopping 时，将该轮的用户 + 助手文本提炼为按会话划分的 Markdown 摘要。
- 召回（Recall） —— 在 agent/session-start（任意来源：startup | resume | clear | compact）时，聚合最近的会话文件，并将其作为背景上下文注入到第一轮。
这就是整个插件。它刻意不是一个 LLM 流水线：捕获是基于规则的文本提取，因此零成本，且绝不会阻塞某一轮对话。

工作原理

两个 ctx.on 监听器，不注入任何服务：

| 事件 | 使用的载荷 | 操作 |
|---|---|---|
| agent/session-start | { agent } | agent.inject(userMessage(digest)) —— 同步执行，因此能可靠地落入第一轮对话 |
| agent/turn-stopping | { agent } | 读取 agent.session.snapshotEvents()，提取本轮内容，前插到 .md |

会话事件的形状是不对称的（已对照 packages/core/session/src/types.ts 验证）：

user/message      → data 就是 UserMessage        （使用 data.content，仅当 data.source.kind === 'user' 时）
assistant/message → data 是 {turn, step, message}   （使用 data.message.content）
turn/start        → data 是 {turn}                  （反向扫描的边界）

DSH 还会注入脚手架内容——工作区的 AGENTS.md、运行时上下文快照、技能目录——作为 user/message 事件，每个都带有自己的 source.kind 标记。只有真正的用户提示才携带 source.kind === 'user'（headless bundle 和 session-controller 都如此标记，DSH 自己的测试也通过 source.kind !== 'user' 来区分注入的上下文）。因此 extractTurn 采用白名单方式只保留 kind === 'user'，而不是把已知的插件 kind 列入黑名单——source map 是可合并扩展的，所以黑名单会泄漏每一个新增的注入 kind。若没有这个过滤器，摘要会被样板内容填满，而这些内容又会被作为“背景”重新注入，并在每次会话中被放大。

session.append 只检查 JSON 往返安全性，而不检查严格的逐字段 schema——因此，一个内联的冻结字面量加上一个全新的 randomUUID()，其注入效果与 llm.createUserMessage() 完全一致，且无需导入任何 DSH 内部模块。

安装

发布在 GitHub 所有者 YaoQC-Ai 下（包 name 为
dsh-memory-plugin，因此 dsh plugin add github:YaoQC-Ai/dsh-memory-plugin 会解析出引用
dsh-memory-plugin[/save|/timer] 的那三行插件记录）。

从 git 主机安装（pnpm 会链接该检出目录；不会构建任何内容）：

dsh plugin --profile  add github:YaoQC-Ai/dsh-memory-plugin

从本地检出目录安装：

dsh plugin --profile  add ./dsh-memory-plugin

验证该层，然后启动：

dsh --profile  --dump-config   # 显示一个 "# == dsh-memory-plugin" 层
dsh --profile

配置

每个配置项都是可选的；在 patch 行中添加一个 config: 块即可覆盖。

| 键 | 默认值 | 含义 |
|---|---|---|
| dir | $DSH_HOME 或 ~/.dsh | 基础目录；摘要存放在 /memory/shortterm/ 下 |
| maxChars | 2048 | 注入摘要的字符上限 |
| maxEntries | 50 | 每个会话文件保留的轮数 |
| recentFilesCap | 20 | 回忆时聚合的会话文件数（最近的优先） |
| assistantMaxChars | 280 | 摘要中单条 assistant 行的截断长度 |
| maxCandidates | 500 | 保留在 compile_candidates.md 中的被淘汰轮次候选（L1 老化归档——不参与召回，因此不会污染注入的摘要） |

存储

/memory/shortterm/
├── .md    # 最新轮次在前，上限为 maxEntries
├── .md
└── ...

被淘汰的轮次不会被丢弃：它们会滚入 /memory/shortterm/compile_candidates.md（一个共享的老化归档，上限为 maxCandidates）。该文件与各会话摘要并存，但不参与召回——buildDigest 从不读取它，因此该归档不会挤占真正的近期内容，也不会被作为“背景”重新注入。两个文件中的条目边界都是 ##  行；助手回复中形如 ## foo 的 Markdown 标题仍属于其所在轮次的一部分，不会被拆分为虚假条目。

各会话文件避免了并发写入竞争。它们是用于注入的快速摘要，而非事实来源——DSH 已经持久化了完整的会话事件日志，因此裁剪旧条目不会丢失任何可恢复的内容。

本包中的同级插件

- memory_save (save.js) —— 一个模型工具，用于将自包含的概念页面写入 /memory/knowledge/（同时维护 /memory/knowledge/_index.md）。它接收 title（概念名称）、content（自足的主体内容）和 domain，后者为 persona | execution | knowledge 之一；写入前会校验该值是否为这三者之一。这是 L2 的写入部分——读取/检索部分（memory_search）尚未实现。
- memory-timer (timer.js) —— 一个定时维护任务：每个自然日 02:00（可通过补丁行上的 hour / minute 配置）触发一次，并且——默认情况下——空运行：它会向 /memory/_log.md 追加一条触发回执，并将状态记录到 /memory/timer-state.json，因此你可以在将其接入实际工作之前观察其节奏。连续失败会根据 failAlertThreshold 进行跟踪。它从基础包 cordis-plugin-timer 注入 timer（ctx.interval）。

可选：添加 L3 语义召回

L1 提供近期性；它不做语义搜索。为此，请将官方 Memorix MCP 记忆示例 MCP 记忆服务器分层添加到你自己配置文件的 cordis.patch.yml 中（不要将其复刻到此包中——它需要外部 memorix 二进制文件，强行加入会破坏没有该文件的安装）：

- insert:
- id: memory-memorix
name: '@deepseek-ai/dsh-mcp-client'
config:
serverName: memorix
transport: stdio
command: memorix
args: [serve]
cwd: !!js process.cwd()

这会暴露模型可原生调用的 mcp__memorix__ 工具。

路线图（不在本切片中）
- L2 编译 —— 将摘要按计划交由 LLM 编译为概念页（主题 / 决策 / 待办）。wiki 的写入半边（memory_save）已经交付；计划编译器与 memory_search 检索尚未交付。
- N1 —— dsh 中会话全文搜索默认禁用；session-query patch 覆盖将随 memory_search 迭代一同提供。

开发

node --test    # 对纯逻辑进行零依赖自检

许可证

MIT

中文

它做什么

让 agent 在新会话开始时「记得」最近若干会话聊过什么。

- 捕获 —— 每轮结束（agent/turn-stopping），把这一轮的 user + assistant 文本蒸馏进「按会话 id 分文件」的 Markdown 摘要。
- 召回 —— 每次会话开始（agent/session-start，任何来源：startup | resume | clear | compact），聚合最近的会话文件，作为背景注入首轮。

这就是插件的全部。它有意不是一条 LLM 流水线：捕获是规则化文本提取，零成本、绝不阻塞对话轮次。

工作原理

两个 ctx.on 监听器，不注入任何服务：

| 事件 | 用到的 payload | 动作 |
|---|---|---|
| agent/session-start | { agent } | agent.inject(userMessage(digest)) —— 同步，稳进首轮 |
| agent/turn-stopping | { agent } | 读 agent.session.snapshotEvents()，抽取本轮，prepend 到 .md |

会话事件形状不对称（已对照 packages/core/session/src/types.ts 核对）：

user/message      → data 本身就是 UserMessage     （取 data.content，且仅当 data.source.kind === 'user'）
assistant/message → data 是 {turn, step, message}  （取 data.message.content）
turn/start        → data 是 {turn}                 （反向扫描的边界）

DSH 还会把工作区 AGENTS.md、runtime-context 快照、skills 目录这些脚手架也作为 user/message 事件注入，各自带着不同的 source.kind。唯有真实用户 prompt 才是 source.kind === 'user'（headless bundle 与 session-controller 都如此打标，DSH 自身测试也用 source.kind !== 'user' 区分注入上下文）。因此 extractTurn 采用白名单 kind === 'user'，而非黑名单已知插件 kind——source map 可被插件扩展，黑名单会漏掉每一种新增的注入 kind。不加这道过滤，digest 会被样板塞满，再作为「背景」注入下一会话，逐次放大。

session.append 只校验 JSON 无损可序列化，不做逐字段严格 schema 校验 —— 所以内联一个带新 randomUUID() 的冻结字面量，注入效果与 llm.createUserMessage() 完全一致，且无需 import 任何 DSH 内部模块。

安装

发布时把下面的 you 换成实际 GitHub owner（包 name 是 dsh-memory-plugin，
所以 dsh plugin add github:/dsh-memory-plugin 能解析引用
dsh-memory-plugin[/save|/timer] 的三行插件）。

从 git 托管安装（pnpm 链接该 checkout，不跑任何构建）：

dsh plugin --profile  add github:YaoQC-Ai/dsh-memory-plugin

从本地 checkout 安装：

dsh plugin --profile  add ./dsh-memory-plugin

先验证层、再启动：

dsh --profile  --dump-config   # 会显示一层 "# == dsh-memory-plugin"
dsh --profile

配置

所有旋钮都可选；在 patch 行补 config: 块即可覆盖。

| 键 | 缺省 | 含义 |
|---|---|---|
| dir | $DSH_HOME 或 ~/.dsh | 基准目录；摘要存放在 /memory/shortterm/ |
| maxChars | 2048 | 注入摘要的字符上限 |
| maxEntries | 50 | 每个会话文件保留的轮次条数 |
| recentFilesCap | 20 | 召回时聚合的会话文件数（最近优先） |
| assistantMaxChars | 280 | 摘要里单条助手文本的截断长度 |
| maxCandidates | 500 | compile_candidates.md 候选池保留的淘汰轮次块数（L1 老化留档 —— 召回时排除，不会污染注入摘要） |

存储

/memory/shortterm/
├── .md    # 最新轮次在最前，上限 maxEntries
├── .md
└── ...
被挤出的轮次不丢弃：滚动进入 /memory/shortterm/compile_candidates.md（全会话共享的老化留档，上限 maxCandidates）。它与各会话摘要同目录，但召回时被排除 —— buildDigest 从不读它，所以留档不会挤占「近期性」、也不会被当作「背景」重新注入。两类文件的条目边界都是 ##  行；assistant 正文里的 Markdown 标题（如 ## foo）仍属于本轮，不会被误切成伪条目。

按会话分文件避免并发写竞态。它们是供注入的快速摘要，不是事实源 —— DSH 本就持久化完整会话事件日志，所以裁剪旧条目不会丢失任何不可恢复的信息。

同包兄弟插件

- memory_save（save.js） —— 一个模型工具：把自足的概念页写入 /memory/knowledge/（并维护 /memory/knowledge/_index.md）。入参 title（概念名）、content（自足正文）、domain（三选一：persona 用户/人格 · execution 工作方式 · knowledge 其它），写入前校验取值必须属于这三者。这是 L2 的写半边；读/检索半边（memory_search）尚未实现。
- memory-timer（timer.js） —— 定时维护任务：每个自然日本地时钟 02:00（patch 行 hour/minute 可改）触发一次，默认只 dry-run：向 /memory/_log.md 追加触发凭证、状态记入 /memory/timer-state.json，便于先观察节奏再接真实任务；连续失败次数按 failAlertThreshold 跟踪告警。它从 base bundle 的 cordis-plugin-timer 注入 timer（ctx.interval）。

可选：叠加 L3 语义召回

L1 提供的是「近期性」，不做语义检索。要语义召回，请把官方的 Memorix MCP memory 示例 MCP memory 服务叠进你自己 profile 的 cordis.patch.yml（不要 fork 进本包 —— 它需要外部 memorix 二进制，强加进来会让没装它的用户安装即坏）：

- insert:
- id: memory-memorix
name: '@deepseek-ai/dsh-mcp-client'
config:
serverName: memorix
transport: stdio
command: memorix
args: [serve]
cwd: !!js process.cwd()

它会暴露 mcp__memorix__ 工具，模型可原生调用。

路线图（不在本切片内）

- L2 编译 —— 定时用 LLM 把摘要编译成概念页（主题 / 决定 / 待办）。概念页的写半边（memory_save）已随包落地；定时编译器与 memory_search 检索尚未实现。
- N1 —— dsh 的会话全文搜索默认关闭；session-query 的 patch 覆盖将随 memory_search 迭代一起提供。

开发

node --test    # 对纯逻辑做零依赖自检

许可

MIT