记忆守卫 Ukashi0/dsh-memory-guardian

DSH Memory Guardian

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

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

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

界面

安装后打开：

Settings → Memory Guardian

面板包含：

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

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

模型工具

插件向智能体注册三个原生工具：

| 工具 | 说明 |
| 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