轻量跨会话记忆 pacoyi/dsh-memory-lite

dsh-memory-lite

DeepSeek Harness 的轻量跨会话记忆插件 —— 一个 memory 工具（save / recall / list / forget）+ 带导入向导与导出面板的设置页"记忆库"卡片，带作用域隔离、写入审批、审计与崩溃安全存储。

为什么需要它

dsh 的每个会话都是白纸开局：转录落盘是为了审计，但模型再也看不到它。这个插件给 agent 一个小巧、显式的 memory 工具，让那些值得跨会话保留的事实——用户偏好、项目决策、关键约束——在重启、升级、换 profile 之后依然健在。

设计目标（按优先级）：

- 零依赖 —— 只用 Node 内置模块；peerDependencies 仅两个（@deepseek-ai/cordis、@deepseek-ai/dsh-tools）。
- 人类可读的存储 —— 一切都在 ~/.dsh/memory-lite.json。可以直接打开、编辑、备份、删除。没有数据库，没有索引。
- 受约束、可检视的效果 —— 作用域可见性、持久写入需审批、逐变更审计日志、模型可见内容的字节与条数预算。

安装

需要 dsh CLI。装进某个 profile（如 web）：

dsh plugin --profile web add github:pacoyi/dsh-memory-lite

或从本地目录安装：

git clone https://github.com/pacoyi/dsh-memory-lite.git
dsh plugin --profile web add file:./dsh-memory-lite

重启 profile（dsh --profile web），memory 工具即生效。

隐私 —— 存敏感内容前必读

存储文件在本地；被 recall 的内容不是仅本地的。

- 插件自身零网络请求、无遥测。
- 但 recall / list 的结果是普通工具结果：会进入模型可见的会话表面、在下一个模型步骤发送给你配置的模型提供方，并与其他工具输出一样持久化进 Session 日志。
- 因此：不要在本存储中存放凭证、API 密钥、客户数据、私有源码或认证材料。把它当作你会粘贴进聊天的内容来对待。
- 每条被 recall 的条目在工具输出中都标注为 untrusted evidence（不可信证据）——可能过期的历史数据，永远不是指令来源。

作用域与隔离

- 记忆作用域从宿主执行上下文（agent 会话的工作目录）派生，绝不来自模型编写的参数。
- recall / list / forget 只能看到当前项目作用域 + 显式存为 global 的条目——一个项目读不到也删不掉另一个项目的条目。
- 设置页卡片展示全部作用域（人类主人拥有完整视野），手动记笔记时可选择归属。

审批、幂等与审计

- save 与 forget 请求宿主审批（tools/pre-execute → ask）。web profile 中会弹出标准审批卡片；未组装审批通道的部署会拒绝这两个操作（fail closed，安全失败）。
- 重放同一工具调用（如会话恢复后）不会产生重复条目——save 按调用 id 去重。
- 每次变更以双相审计落盘：原子发布前先写一条 pending 意图行，发布后再补 committed 行。若进程死在两行之间，下次启动的对账会把孤儿意图关闭为显式的 reconciled-applied / reconciled-orphan 记录——审计链能检测并命名崩溃窗口，而不是静默缺失。
- 审计记录在 ~/.dsh/.memory-lite.audit.jsonl：时间戳、操作、存储版本号（rev）、阶段（phase）、条目 id、作用域、来源（agent / user / import）、结果。
- forget 把条目移入回收站（可从设置卡片恢复）；永久删除是单独的、需确认的操作。

存储耐久性

- 所有变更经单一进程内队列 + 跨进程锁（原子 mkdir + PID 存活检测 + 陈旧接管）串行化——共享同一 OS home 的两个 host 不会丢写。
- 写入原子发布：临时文件 → fsync → rename，前一代保留为 .memory-lite.bak，目录 fsync 尽力而为。
- 损坏的存储被隔离（.memory-lite.corrupt.json），所有变更安全失败——损坏绝不悄悄降级为空库并覆盖你唯一的副本。
- 条目 id 来自持久计数器，永不复用。
- 预算：笔记 ≤ 2000 字符、标签 ≤ 8 个 × 32 字符、条目 ≤ 1000 条、文件 ≤ 512 KB、渲染输出 ≤ 16000 字符。

使用

正常对话即可——模型自己决定何时存取（审批卡片会先问你）：

"记住：这个项目用 pnpm，不要用 npm" "我之前跟你说过什么关于部署的事？"

工具参数：

| 参数 | 适用操作 | 说明 |
| operation | 全部 | save \| recall \| list \| forget |
| text | save | 要记住的内容——自包含、具体，≤ 2000 字符 |
| tags | save | 可选标签，如 ["preference", "project-x"] |
| query | recall | 关键字，对文本和标签做大小写不敏感匹配 |
| tag | recall | 精确匹配携带该标签的条目 |
| limit | list/recall | 返回条数上限（默认 10，最大 100） |
| id | forget | 要移入回收站的条目 id |

导入向导（从其他 agent 迁移）

设置卡片内置三步向导，用于从其他编码 agent 迁移精选记忆（Claude Code CLAUDE.md、Codex AGENTS.md，或任意粘贴文本）：

1. 选择源 —— 自动探测常见文件（~/.claude/CLAUDE.md、~/.codex/AGENTS.md），或直接粘贴；选择目标作用域。
2. 逐条策展 —— 源文本被切分为候选条目（markdown 列表、标题、段落；代码块跳过）。规则样文本（"必须"、"总是"、"must"、"always"…）会被标记且默认不勾选——每次必须执行的规则属于 Skill / 工作区指令，不属于语义记忆。你保留全部控制权：逐条编辑、勾选/取消、应用统一标签。
3. 原子提交 —— 一批提交走同一套加锁引擎。勾选动作即人类批准（与手动保存同等地位——导入是一次性人类决策，永远不是模型工具）。

重跑幂等且冲突敏感：每条导入条目携带溯源信息（源路径 + 文档/条目 digest）。重导入未变更的源会跳过已有条目；源文件变更后再从同路径导入会被拒绝并报告冲突——精选事实绝不会被静默覆盖或重复。

导出

同一张卡片带导出面板：把活跃条目（全库或单个作用域）渲染为纯 markdown 列表——只含内容与标签，不含 id/时间戳——复制到剪贴板。输出可直接粘进其他 agent 的记忆文件；粘回本插件的导入向导则是无操作：内容 digest 让"导出→导入"往返对任何来源的条目（agent / 手动 / 导入）都幂等。

设置页 UI

web 客户端在设置页提供"记忆库"卡片：按作用域分组展示条目（含来源与时间戳）、两击确认删除、回收站视图（恢复 / 永久删除）、以及上述导入向导与导出面板。卡片能做的一切，直接编辑 ~/.dsh/memory-lite.json 也都能做——但仅限 host 停止时，因为并发写归插件所有。

开发

这是一个"双半"（two-half）dsh 插件：

- index.js —— agent 半：注册 memory 工具、审批门、导入向导纯函数（解析 / 规则样分类 / 批次分类）与浏览器 RPC 桥。
- storage.js —— 存储引擎：锁、原子发布、双相审计 + 启动对账、损坏隔离、预算、去重、批量导入。
- client.js —— web 半：由浏览器 module loader 惰性加载，用宿主提供的 React 渲染设置卡片。
- cordis.patch.yml —— bundle 层，插入插件行。
- package.json —— 在 dsh 键下声明 dsh.bundle（patch）与 dsh.client（inject 列表）。
- SPEC.md —— 维护者规格：需求、安全契约溯源、设计决策、版本史（中文）。

跑契约测试（并发、崩溃安全、审计对账、损坏、预算、作用域隔离、导入/导出往返幂等——零依赖，node:test）与 client.js 渲染冒烟套件（hook-mock React 下断言每张卡片的元素树结构——RPC 测试看不见的 UI 层；曾有一个多余的括号吞掉了导入结果页而不触发任何语法检查失败）：

npm test

最快的开发循环：用 file: 把工作目录装进 profile（同上）——修改在 profile 重启后生效。

许可证

MIT © pacoyi