DSH Memory Guardian

面向 DeepSeek Harness 的可治理长期记忆插件：自带本地存储、模型工具和高级 Web 面板，让 Agent 不仅能跨会话记住信息，还能解释“记住了什么、为什么召回、是否存在冲突、占用了多少上下文”。

English: Local-first, governed long-term memory for DeepSeek Harness. It adds provenance, scope isolation, secret rejection, conflict review, bounded recall, model tools, and a polished native Web dashboard.

当前版本：0.1.1-beta.1（Beta），已发布到 npm。源码和构建产物已同步；实际兼容性需按使用的 DSH 版本验证。

它解决什么问题

普通 Memory 插件通常关注“存进去、搜出来”。Memory Guardian 额外处理更难的四件事：

记忆安全：密码、Token、私钥等在写入磁盘之前直接拒绝；邮箱、手机号等个人信息默认进入隔离区。
记忆准确性：同一语义键出现新旧不同内容时，不静默覆盖，而是建立冲突并等待确认。
上下文预算：每次召回同时限制条数和字符数，避免整库内容被塞入 Prompt。
可解释性：每条记忆保留来源、作用域、重要性、召回次数、风险和生命周期记录。

插件完全独立，不要求先安装 Memmy、ExpMem 或向量数据库，也不会主动访问网络。

界面

安装后打开：

Settings → Memory Guardian

面板包含：

页面	用途
Memory Vault	浏览 Active、Review、Archived 记忆，查看来源与作用域，固定或归档
Recall Lab	输入查询，模拟真实召回，查看相关性得分和预算消耗
Review Queue	查看新旧内容，选择替代、同时保留或拒绝；未批准内容不会进入召回
Privacy Ledger	查看创建、去重、隔离、召回、归档和凭据拦截记录

界面跟随 DSH 明暗主题，支持键盘焦点、移动端响应式布局和 prefers-reduced-motion。

模型工具

插件向 Agent 注册三个原生工具：

工具	说明
`memory_remember`	保存一条长期信息；自动去重、敏感检测和冲突隔离
`memory_search`	先检查词法相关性，再按相关性、重要性、新近度和固定状态排序；并存记录整组执行预算
`memory_forget`	将指定记忆归档并立即排除出召回结果，可在面板恢复

同时加入一段简短 Memory Policy，告诉模型何时搜索、何时保存以及哪些内容禁止保存。

用户在会话中明确使用以下格式时，也能自动保存：

记住：这个项目统一使用 pnpm
请记住发布前必须运行 npm test
remember: I prefer concise answers

普通聊天不会被整段自动抓取。

安装

已发布的测试版使用 beta 标签安装。已安装 dsh 命令时：

dsh plugin --profile web add dsh-memory-guardian@beta
dsh web

也可以通过 npx 启动 DSH 完成安装：

npx @deepseek-ai/dsh plugin --profile web add dsh-memory-guardian@beta
npx @deepseek-ai/dsh web

本地开发安装：

cd D:\path\to\parent
npx @deepseek-ai/dsh plugin --profile web add ./dsh-memory-guardian
npx @deepseek-ai/dsh web

也可安装预先构建的独立压缩包：

npx @deepseek-ai/dsh plugin --profile web add ./dsh-memory-guardian-0.1.1-beta.1.tgz

这个安装包仅包含 Memory Guardian。它不依赖 Context Sentinel。通过本地目录链接安装时，请保留该目录；安装 tgz 文件则使用包中的构建产物。

兼容性

DeepSeek Harness：0.1.2-rc.1 或更高版本
Node.js：22 或更高版本
运行模式：Web Profile（Host 存储和模型工具也可用于其他包含所需服务的 Profile）
运行时第三方依赖：无

插件直接使用 ctx.tools、ctx.systemPrompt、session/event 和可选的 ctx.webServer、ctx.sessions，不依赖旧版 conversationEvents / uiConversation 服务。

配置

Bundle 默认配置：

- insert:
    - id: memory-guardian
      name: dsh-memory-guardian
      config:
        maxRecords: 10000
        maxRecallItems: 8
        maxRecallChars: 6000
        captureExplicitRequests: true
        quarantinePersonalData: true

配置项	默认值	说明
`storagePath`	`~/.dsh/memory-guardian/store.json`	本地存储文件；API 不暴露真实路径
`maxRecords`	`10000`	最大记录数，上限 100000
`maxRecallItems`	`8`	单次召回最大条数，上限 50
`maxRecallChars`	`6000`	召回正文字符预算，配置下限 256，上限 100000；不包含工具说明和元数据
`captureExplicitRequests`	`true`	是否识别“记住：……”等明确保存请求
`quarantinePersonalData`	`true`	邮箱、手机号、身份证号是否必须人工批准
`auditLimit`	`500`	本地治理记录数量，上限 5000

记忆数据模型

每条记录包含：

content + semantic key + category + tags + importance
scope(global/project/agent/team) + provenance(session/event)
status(active/quarantined/archived) + risk + conflicts
created/updated/last recalled + recall count + optional expiry

semantic key 用来描述同一事实的稳定身份，例如 preference.editor。如果这个键已经对应“VS Code”，后来又保存“Zed”，新记录会进入 Review Queue，而不是悄悄让两条矛盾记忆同时影响模型。

检索与审核行为

先判断是否匹配，再排序：查询须命中正文、标签或 key 中的词元，或满足非空词法查询的子串匹配。多字中文查询不会仅凭一个相同汉字进入候选；重要性、时间和固定状态只能给候选加分。分数不是准确率，词法匹配也不保证语义正确。
替代旧记录：同一 key、同一作用域的现有 Active 记录归档，新记录生效，作为一次持久化操作提交。
同时保留：记录双方的并存关系。查询命中其中一条时，会把同主题、同作用域且可召回的备选一起返回，并提示模型结合适用条件理解。
预算不足：同主题多条记录作为一组；条数或正文预算容不下整组时，整组跳过并返回 coexistence-budget 提示。可增加预算、归档不需要的记录，或明确作用域和 key。
重新审核：恢复已归档记录、修改内容/key/作用域、去重时补上 key，都会重新检查冲突。修改固定状态等元数据不会撤销已有并存关系。
审核过期：界面提交所看到记录的 reviewToken。新旧内容或冲突集合变化后，服务端返回 HTTP 409，界面刷新后再由用户选择。

项目范围与旧数据

项目标识统一使用规范化后的绝对工作目录。模型工具和“记住”事件使用 Session 的 cwd；面板添加和 Recall Lab 共用项目选择，可从已有会话/记忆目录中选择，也可手输绝对目录。没有 Session 目录时必须显式传入项目路径，或主动选择 Global，不能静默使用 default。

例如 d:\\work\\demo\\ 与 D:/work/demo/ 会归一为 D:/work/demo。这是路径文本规范化，不调用 realpath；符号链接、目录别名和 Windows 目录部分的大小写不会自动合并。

升级会继续读取 schemaVersion 1，不清空已有数据。旧 project/default 或相对路径记录标为“待绑定”，在所有查询中排除；请在 Memory Vault 详情中绑定实际目录，绑定后重新检查冲突。旧版本遗留的多条 Active 同 key 记录会以“未确认的同主题备选”提示，不会假定它们已经获准并存；可归档不需要的记录，或归档后恢复以进入新审核流程。

升级前建议备份现有 store.json。不要让多个 DSH 进程同时操作同一个存储文件。

API

Web Profile 提供四个同源端点：

GET  /memory-guardian/api/snapshot
POST /memory-guardian/api/search
POST /memory-guardian/api/mutate
GET  /memory-guardian/api/export

mutate 支持 remember、update、archive、restore、approve、reject。POST 请求必须使用 application/json，请求体限制为 32 KiB。

冲突批准请求示例（expectedToken 从 snapshot 中对应记录的 reviewToken 获取）：

{
  "action": "approve",
  "id": "<待审核记录 ID>",
  "resolution": "replace",
  "expectedToken": "<当前 reviewToken>"
}

resolution 可为 replace 或 coexist；拒绝新记录使用 action: "reject"。冲突批准缺少选择/令牌返回 409 review-required，过期令牌返回 409 review-stale。普通个人信息审核仍可直接 approve，界面也会携带令牌。

snapshot 新增 projects、metrics.unboundProjects；记录新增 coexistsWith、needsProjectBinding 和待审核时的 reviewToken。search 新增 coexistenceGroups、warnings 和结果项的 includedAsAlternative。

不要在没有额外访问控制的情况下把 DSH Web 直接暴露到不可信网络。

隐私与安全边界

凭据规则在持久化之前运行；被拒绝内容只留下短指纹和规则名，不保存原文。
召回只读取 active、未过期且作用域可见的记录；尚未绑定的旧项目记录也会排除。
搜索审计只保存查询短指纹，不保存原始搜索词。
插件不会主动发起网络请求，也不依赖云端 Embedding。
JSON 文件默认以仅当前用户可读写的权限创建；Windows 上的最终访问控制仍由用户账户和目录 ACL 决定。
本地存储目前没有额外加密。若设备或用户账户不可信，应结合磁盘加密或将 storagePath 放入受保护目录。

完整威胁模型见 docs/privacy-and-security.md。

开发与测试

npm run check
npm test
npm run pack:check

自动化测试覆盖：

中英文检索分词和排序；
密码、Token、私钥写盘前拦截；
邮箱等个人信息隔离和批准；
精确去重与语义键冲突；
界面、API、模型工具与事件捕获的项目路径一致性，以及旧项目记忆绑定；
无关查询门槛、替代/并存、整组预算、过期审核与写入失败回滚；
归档、恢复重新检查冲突和文件重新加载；
三项模型工具、System Prompt Policy、Host API；
明确“记住”消息的 session/event 捕获；
Web Settings 插槽与响应式/无障碍标记，以及前端表单和审核按钮的请求行为。

Host 测试使用模拟 DSH 服务；前端行为测试使用轻量 Hook 适配器执行真实入口的事件处理函数。这些测试不替代真实 React/DSH 页面验收，也不证明检索质量或隐私检测的完备性。

项目结构

dsh-memory-guardian/
├─ src/
│  ├─ scope.js          # 各入口共用的作用域和项目目录规范化
│  ├─ store.js          # 本地存储、风险、去重、冲突与检索引擎
│  ├─ index.js          # Cordis Host、模型工具、事件捕获与 HTTP API
│  └─ client.js         # DSH 原生高级治理面板
├─ test/                # 单元、Host 集成和包结构测试
├─ docs/                # 架构、安全与发布说明
├─ cordis.patch.yml     # DSH Bundle Patch
└─ package.json

当前限制

v0.1 使用可审计的本地词法检索，不包含 Embedding；这样零依赖、离线且结果可解释。
冲突检测依赖稳定 semantic key，不会假装通过简单文本规则理解所有语义矛盾。
project 从 Agent Session 的 cwd 推导；面板需选择实际绝对目录，不使用默认项目占位符。
JSON 事务队列只协调一个 Store 实例内的操作；没有跨进程文件锁或 fsync 断电持久性保证。
字符预算只计算记忆正文长度，元数据/提示文本和真实模型 Token 数需另行计入。
适配 Memmy、ExpMem 等外部 Provider 的接口已保留为后续方向，v0.1 不接管第三方数据库。

License

MIT

DSH Memory Guardian

English: Local-first, governed long-term memory for DeepSeek Harness. It adds provenance, scope isolation, secret rejection, conflict review, bounded recall, model tools, and a polished native Web dashboard.

当前版本：0.1.1-beta.1（Beta），已发布到 npm。源码和构建产物已同步；实际兼容性需按使用的 DSH 版本验证。

它解决什么问题

普通 Memory 插件通常关注“存进去、搜出来”。Memory Guardian 额外处理更难的四件事：

记忆安全：密码、Token、私钥等在写入磁盘之前直接拒绝；邮箱、手机号等个人信息默认进入隔离区。
记忆准确性：同一语义键出现新旧不同内容时，不静默覆盖，而是建立冲突并等待确认。
上下文预算：每次召回同时限制条数和字符数，避免整库内容被塞入 Prompt。
可解释性：每条记忆保留来源、作用域、重要性、召回次数、风险和生命周期记录。

插件完全独立，不要求先安装 Memmy、ExpMem 或向量数据库，也不会主动访问网络。

界面

安装后打开：

Settings → Memory Guardian

面板包含：

页面	用途
Memory Vault	浏览 Active、Review、Archived 记忆，查看来源与作用域，固定或归档
Recall Lab	输入查询，模拟真实召回，查看相关性得分和预算消耗
Review Queue	查看新旧内容，选择替代、同时保留或拒绝；未批准内容不会进入召回
Privacy Ledger	查看创建、去重、隔离、召回、归档和凭据拦截记录

界面跟随 DSH 明暗主题，支持键盘焦点、移动端响应式布局和 prefers-reduced-motion。

模型工具

插件向 Agent 注册三个原生工具：

工具	说明
`memory_remember`	保存一条长期信息；自动去重、敏感检测和冲突隔离
`memory_search`	先检查词法相关性，再按相关性、重要性、新近度和固定状态排序；并存记录整组执行预算
`memory_forget`	将指定记忆归档并立即排除出召回结果，可在面板恢复

同时加入一段简短 Memory Policy，告诉模型何时搜索、何时保存以及哪些内容禁止保存。

用户在会话中明确使用以下格式时，也能自动保存：

记住：这个项目统一使用 pnpm
请记住发布前必须运行 npm test
remember: I prefer concise answers

普通聊天不会被整段自动抓取。

安装

已发布的测试版使用 beta 标签安装。已安装 dsh 命令时：

dsh plugin --profile web add dsh-memory-guardian@beta
dsh web

也可以通过 npx 启动 DSH 完成安装：

npx @deepseek-ai/dsh plugin --profile web add dsh-memory-guardian@beta
npx @deepseek-ai/dsh web

本地开发安装：

cd D:\path\to\parent
npx @deepseek-ai/dsh plugin --profile web add ./dsh-memory-guardian
npx @deepseek-ai/dsh web

也可安装预先构建的独立压缩包：

npx @deepseek-ai/dsh plugin --profile web add ./dsh-memory-guardian-0.1.1-beta.1.tgz

这个安装包仅包含 Memory Guardian。它不依赖 Context Sentinel。通过本地目录链接安装时，请保留该目录；安装 tgz 文件则使用包中的构建产物。

兼容性

DeepSeek Harness：0.1.2-rc.1 或更高版本
Node.js：22 或更高版本
运行模式：Web Profile（Host 存储和模型工具也可用于其他包含所需服务的 Profile）
运行时第三方依赖：无

插件直接使用 ctx.tools、ctx.systemPrompt、session/event 和可选的 ctx.webServer、ctx.sessions，不依赖旧版 conversationEvents / uiConversation 服务。

配置

Bundle 默认配置：

- insert:
    - id: memory-guardian
      name: dsh-memory-guardian
      config:
        maxRecords: 10000
        maxRecallItems: 8
        maxRecallChars: 6000
        captureExplicitRequests: true
        quarantinePersonalData: true

配置项	默认值	说明
`storagePath`	`~/.dsh/memory-guardian/store.json`	本地存储文件；API 不暴露真实路径
`maxRecords`	`10000`	最大记录数，上限 100000
`maxRecallItems`	`8`	单次召回最大条数，上限 50
`maxRecallChars`	`6000`	召回正文字符预算，配置下限 256，上限 100000；不包含工具说明和元数据
`captureExplicitRequests`	`true`	是否识别“记住：……”等明确保存请求
`quarantinePersonalData`	`true`	邮箱、手机号、身份证号是否必须人工批准
`auditLimit`	`500`	本地治理记录数量，上限 5000

记忆数据模型

每条记录包含：

content + semantic key + category + tags + importance
scope(global/project/agent/team) + provenance(session/event)
status(active/quarantined/archived) + risk + conflicts
created/updated/last recalled + recall count + optional expiry

检索与审核行为

先判断是否匹配，再排序：查询须命中正文、标签或 key 中的词元，或满足非空词法查询的子串匹配。多字中文查询不会仅凭一个相同汉字进入候选；重要性、时间和固定状态只能给候选加分。分数不是准确率，词法匹配也不保证语义正确。
替代旧记录：同一 key、同一作用域的现有 Active 记录归档，新记录生效，作为一次持久化操作提交。
同时保留：记录双方的并存关系。查询命中其中一条时，会把同主题、同作用域且可召回的备选一起返回，并提示模型结合适用条件理解。
预算不足：同主题多条记录作为一组；条数或正文预算容不下整组时，整组跳过并返回 coexistence-budget 提示。可增加预算、归档不需要的记录，或明确作用域和 key。
重新审核：恢复已归档记录、修改内容/key/作用域、去重时补上 key，都会重新检查冲突。修改固定状态等元数据不会撤销已有并存关系。
审核过期：界面提交所看到记录的 reviewToken。新旧内容或冲突集合变化后，服务端返回 HTTP 409，界面刷新后再由用户选择。

项目范围与旧数据

升级前建议备份现有 store.json。不要让多个 DSH 进程同时操作同一个存储文件。

API

Web Profile 提供四个同源端点：

GET  /memory-guardian/api/snapshot
POST /memory-guardian/api/search
POST /memory-guardian/api/mutate
GET  /memory-guardian/api/export

mutate 支持 remember、update、archive、restore、approve、reject。POST 请求必须使用 application/json，请求体限制为 32 KiB。

冲突批准请求示例（expectedToken 从 snapshot 中对应记录的 reviewToken 获取）：

{
  "action": "approve",
  "id": "<待审核记录 ID>",
  "resolution": "replace",
  "expectedToken": "<当前 reviewToken>"
}

不要在没有额外访问控制的情况下把 DSH Web 直接暴露到不可信网络。

隐私与安全边界

凭据规则在持久化之前运行；被拒绝内容只留下短指纹和规则名，不保存原文。
召回只读取 active、未过期且作用域可见的记录；尚未绑定的旧项目记录也会排除。
搜索审计只保存查询短指纹，不保存原始搜索词。
插件不会主动发起网络请求，也不依赖云端 Embedding。
JSON 文件默认以仅当前用户可读写的权限创建；Windows 上的最终访问控制仍由用户账户和目录 ACL 决定。
本地存储目前没有额外加密。若设备或用户账户不可信，应结合磁盘加密或将 storagePath 放入受保护目录。

完整威胁模型见 docs/privacy-and-security.md。

开发与测试

npm run check
npm test
npm run pack:check

自动化测试覆盖：

中英文检索分词和排序；
密码、Token、私钥写盘前拦截；
邮箱等个人信息隔离和批准；
精确去重与语义键冲突；
界面、API、模型工具与事件捕获的项目路径一致性，以及旧项目记忆绑定；
无关查询门槛、替代/并存、整组预算、过期审核与写入失败回滚；
归档、恢复重新检查冲突和文件重新加载；
三项模型工具、System Prompt Policy、Host API；
明确“记住”消息的 session/event 捕获；
Web Settings 插槽与响应式/无障碍标记，以及前端表单和审核按钮的请求行为。

项目结构

dsh-memory-guardian/
├─ src/
│  ├─ scope.js          # 各入口共用的作用域和项目目录规范化
│  ├─ store.js          # 本地存储、风险、去重、冲突与检索引擎
│  ├─ index.js          # Cordis Host、模型工具、事件捕获与 HTTP API
│  └─ client.js         # DSH 原生高级治理面板
├─ test/                # 单元、Host 集成和包结构测试
├─ docs/                # 架构、安全与发布说明
├─ cordis.patch.yml     # DSH Bundle Patch
└─ package.json

当前限制

v0.1 使用可审计的本地词法检索，不包含 Embedding；这样零依赖、离线且结果可解释。
冲突检测依赖稳定 semantic key，不会假装通过简单文本规则理解所有语义矛盾。
project 从 Agent Session 的 cwd 推导；面板需选择实际绝对目录，不使用默认项目占位符。
JSON 事务队列只协调一个 Store 实例内的操作；没有跨进程文件锁或 fsync 断电持久性保证。
字符预算只计算记忆正文长度，元数据/提示文本和真实模型 Token 数需另行计入。
适配 Memmy、ExpMem 等外部 Provider 的接口已保留为后续方向，v0.1 不接管第三方数据库。

License

MIT

Ukashi0/dsh-memory-guardian

DSH Memory Guardian

它解决什么问题

界面

模型工具

安装

兼容性

配置

记忆数据模型

检索与审核行为

项目范围与旧数据

API

隐私与安全边界

开发与测试

项目结构

当前限制

License

Community comments

Ukashi0/dsh-memory-guardian

DSH Memory Guardian

它解决什么问题

界面

模型工具

安装

兼容性

配置

记忆数据模型

检索与审核行为

项目范围与旧数据

API

隐私与安全边界

开发与测试

项目结构

当前限制

License

Community comments