工作区记忆lgquan/dsh-workspace-memory

dsh-workspace-memory

为 DeepSeek Harness 提供按工作区隔离的长期记忆。

安装后，DSH 可以在后续会话中继续使用已经确认的项目事实、技术决策、工作约定和用户偏好；不同项目的记忆互不混用，全局偏好则可以跨项目共享。插件同时提供记忆检索、显式写入、删除、冲突修正和可审计的历史版本。

适合谁

- 希望同一项目的多个 Session 共享上下文；
- 希望普通 Agent、后台 Agent 和语音 Agent 使用同一份项目记忆；
- 希望长期记忆可查看、可纠错、可删除，而不是无法审计的黑盒；
- 不想额外部署向量数据库或 Embedding 服务。

安装前提

- 已安装 DeepSeek Harness；
- 使用 DSH 的 web profile；
- Node.js >= 22.19.0。

下面两种方式任选一种。两种方式安装的都是已经构建好的插件包，不需要下载源码或准备开发环境。推荐使用 NPM；无法访问 NPM Registry 时可以改用 GitHub Release。

方式一：通过 NPM 安装（推荐）

在 PowerShell 或终端中运行：

dsh plugin --profile web add --config.minimumReleaseAge=0 @flowingspring/dsh-workspace-memory@0.2.15

NPM 包地址：@flowingspring/dsh-workspace-memory

方式二：通过 GitHub 安装

直接安装 GitHub Release 中的预构建插件包：

dsh plugin --profile web add --config.minimumReleaseAge=0 https://github.com/lgquan/dsh-workspace-memory/releases/download/v0.2.15/flowingspring-dsh-workspace-memory-0.2.15.tgz

Release 页面：v0.2.15

安装后怎么使用

1. 重启 dsh web。
2. 打开 DSH 设置。
3. 进入“记忆”页面。
4. 正常与 Agent 对话。插件会自动缓冲、整理并在后续任务中检索相关记忆。

安装成功后，设置页会显示：

- 全局记忆和各项目记忆；
- 自动生成的稳定摘要；
- 可展开查看的结构化记忆；
- 记忆状态、历史修订和冲突信息；
- 已删除项目对应的记忆回收区。

也可以用以下命令确认安装版本：

dsh plugin --profile web list

更新

使用 NPM 更新到指定版本：

dsh plugin --profile web add --config.minimumReleaseAge=0 @flowingspring/dsh-workspace-memory@0.2.15

使用 GitHub 更新到指定标签：

dsh plugin --profile web add --config.minimumReleaseAge=0 https://github.com/lgquan/dsh-workspace-memory/releases/download/v0.2.15/flowingspring-dsh-workspace-memory-0.2.15.tgz

更新后重启 dsh web。

卸载

dsh plugin --profile web remove --config.minimumReleaseAge=0 @flowingspring/dsh-workspace-memory

卸载插件不会自动删除已经保存的记忆数据。确认不再需要后，可以手动删除下文所列的数据目录。

它会记住什么

插件只整理适合长期复用的内容，例如：

- 项目架构、模块职责和稳定约束；
- 已确认的技术选型与决策；
- 用户明确表达的偏好和工作方式；
- 已验证的问题结论、修复方式和注意事项。

临时闲聊、一次性任务细节和明显的凭据内容不应成为长期记忆。凭据形态内容会被拒绝持久化，并在记忆输出前再次脱敏。

记忆什么时候整理

对话完成后，消息会先进入缓冲区，不会每轮都调用模型整理。出现以下任一情况时会评估 checkpoint：

- 后台 Agent 任务完成；
- 累计达到 10 个已完成用户轮次；
- 缓冲内容达到 4000 个字符；
- 连续空闲 5 分钟；
- Session 关闭；
- 调用方显式要求立即整理。

插件会在服务启动时恢复已有项目的待整理消息：已经超过空闲阈值的内容会立即尝试整理，尚未超时的内容会按剩余时间触发。若模型或网络导致一次整理失败，插件会自动使用退避间隔重试，并在成功提交前保留待整理消息。

因此，刚聊完但尚未达到阈值、没有空闲足够时间或 Session 仍在继续时，设置页里暂时看不到新记忆是正常现象。

记忆如何检索和纠错

- 每个 Agent step 都会注入一份有大小上限的稳定摘要；
- Agent 第一个 step 会根据当前问题检索相关结构化记忆；
- Agent 还可以调用 memory_search 做第二次检索；
- memory_remember 可以显式保存一条长期事实；
- memory_forget 可以按记忆 ID 删除条目。

明确的用户纠正可以取代旧事实；证据不足的矛盾不会静默覆盖，而会保留为显式冲突。修订前的内容和被取代条目继续保留用于审计，但不会作为有效事实进入稳定摘要。

数据存在哪里

默认数据目录：

$DSH_HOME/workspace-memory

未设置 DSH_HOME 时使用：

~/.dsh/workspace-memory

记忆数据默认不会写入 Git 项目目录。设置页只能读取经过脱敏的摘要和结构化条目，不会展示完整 checkpoint 对话原文。

与 dsh-voco 一起使用
安装 dsh-voco 0.3.6 或更高版本后，语音主 Session、普通 Session 和语音委派子 Session 只要使用相同的工作目录，就会共享同一个项目记忆范围。每个完成的语音委派任务会以 task-end 触发整理；只提交用户原始请求和最终可见结果，不把 reasoning、工具日志或注入上下文保存为长期记忆。

dsh-voco 不是必需依赖。未安装语音插件时，dsh-workspace-memory 仍可独立服务普通 DSH Agent。

可选配置

默认配置已经可以直接使用。需要调整时，可以在插件 loader 配置中覆盖以下字段：

- insert:
- id: workspace-memory
name: '@flowingspring/dsh-workspace-memory'
config:
memoryDir: ''
checkpointTurns: 10
checkpointChars: 4000
idleCheckpointMs: 300000
consolidateEvery: 5
summaryMaxBytes: 3000
recallMaxBytes: 5000
recallLimit: 8
checkpointMaxChars: 40000
keepSummaryVersions: 10
surfacedPenalty: 8
summarizeProvider: ''
summarizeModel: ''

summarizeProvider 和 summarizeModel 留空时，使用 DSH 当前默认模型。

常见问题

安装后设置里没有“记忆”页面

先运行 dsh plugin --profile web list 确认插件已经安装，然后完整重启 dsh web。正在运行的 Web 进程不会自动加载新插件。

刚结束对话，为什么还没有新记忆

整理由任务完成、轮次、字符数、空闲时间或 Session 关闭触发。未达到任何条件时，内容仍在 checkpoint 缓冲区中。

为什么某些聊天内容没有保存

蒸馏器只应保留长期有效、未来可复用的事实。临时信息、重复内容、低价值闲聊和凭据形态内容会被忽略或拒绝。

删除项目后记忆还在吗

项目从 DSH 注册表中删除后，对应记忆会进入设置页的“回收区”，不再参与正常召回。只有在回收区确认“永久删除”后，相关摘要、结构化条目和审计历史才会物理删除。

更多文档

- 设计与行为契约
- 架构说明
- 问题与处理记录

开发

源码使用 TypeScript。开发者检出仓库后可以运行：

pnpm install
pnpm check
pnpm build
pnpm pack --dry-run

lib/ 是构建产物，不提交到 Git。NPM 包和 GitHub Release 附件都会包含经过发布检查的预构建产物。

License

MIT