持久记忆 annkun/dsh-memory

dsh-memory

给 DeepSeek Harness 的持久记忆 —— 沿用 Claude Code 的记忆模型：智能体跨会话记得住，醒来就带着上下文，项目之间绝不串味。纯文件，零依赖。

它做什么

你的 DSH 智能体和你「初次见面」—— 每一次会话都是。
有了 dsh-memory，它记得住。

Session 1 You: "Remember — this project uses pnpm, not npm." Agent: saved via memory_save

Session 2 You: "Which package manager do we use?"
Agent: "pnpm — you told me yesterday." <- no re-asking, ever

不用服务器，不用账号，不用 embedding 服务商。就是普通的 markdown 文件 —— 删掉目录，那个作用域就忘得一干二净。

亮点

🖥️ 可视化记忆管理器，不是一堆 markdown

Settings → Memory 打开一个完整的管理器：两个作用域的记忆全在一个可搜索列表里，工作区以可展开的树呈现（嵌套的子项目作用域自动发现），按子文件夹分组，还有实时护栏仪表（索引行数 / KB / 文件数）。增、改、打标签、删，直接在面板里完成 —— 走的是和智能体自己调用工具完全相同的受保护管道，所以你在界面上改的，正是模型下个会话看到的。

👆 触碰激活 —— CLAUDE.md 语义（v0.13）

项目记忆带子目录标签。会话的工作目录落在标签内，标签就注入 —— 或者会话一碰到它就注入：一次 read/edit/write/grep/glob/bash/pwsh 调用进入 frontend/src，[frontend] 和 [frontend/src] 就在本次会话余下时间里激活。激活是单调的，会话恢复后依然有效 —— 和嵌套 CLAUDE.md 文件一模一样，由你实际做了什么触发，而不只是启动时 cd 到了哪里。

没碰过的区域只给提示，绝不悄悄藏起来：+3 more tagged to areas you haven't touched — memory_search surfaces them.

🧠 会话作用域 —— 读和写对得上

每个会话的提示词只带它自己工作区的记忆，memory_save 也落在同一个工作区。多会话的 Web 宿主零跨工作区串扰。

📉 天生有界

根级记忆永远注入；区域记忆按工作/触碰加载；25 条注入上限加硬限制 —— 索引 200 行 / 25 KB，每个作用域 500 条记忆 —— 不管你记了多少，提示词都保持平稳。

🔒 安全做在管道里

原子写入（崩溃绝不会留下半个文件）· 每一条写入路径都拒绝密钥，面板也不例外 · 面板 API 有跨源 + 方法门禁 · 防穿越的 id · $HOME、盘符根目录和 tmp 目录永远不能成为项目作用域（Windows 感知护栏）。

🪶 零依赖

无需预置，也不会损坏。精简主机也能优雅降级——每个可选的主机服务都按防御性方式读取，没有它们工具照样能用。

快速开始

前提：DSH 命令行——npm install -g @deepseek-ai/dsh。如果从源码检出运行，命令前加 pnpm。

1 · 安装（一条命令）

dsh plugin --profile web add @fooxe/dsh-memory # DSH CLI installed
pnpm dsh plugin --profile web add @fooxe/dsh-memory # from a source checkout

--profile 必填，且要放在 add 前面——选你实际启动的配置档（Web UI 用 web；见 ~/.dsh/profiles/）。手动 npm i -g @fooxe/dsh-memory + dsh web --patch ./overlay/dsh-memory.cordis.yml 也能用，但推荐走 plugin add。

2 · 重启 DSH——最容易漏掉的一步

工具只在服务启动时注册。先停掉服务（Ctrl+C），再重新启动，然后开一个新会话。

3 · 验证（30 秒）

说 "Remember that I prefer pnpm over npm." → 出现一次 memory_save 调用。开一个新会话，问 "Which package manager do I prefer?" → 从注入的索引里作答。此时 ~/.dsh/memory/MEMORY.md 已存在；在项目里，决策会落到 <project-root>/.dsh/memory/——提交它，整个团队共享。

排障（每一行都在真实安装上验证过）

| 现象 | 修复 |
| dsh: command not found | 先安装 DSH 命令行——见前提 |
| required option '--profile <name>' | 它要放在子命令前面：dsh plugin --profile web add ... |
| pnpm ERR_P..._STORE: Unexpected store location | 你终端的 pnpm 和 DSH 内置的（11.7.0）不一致。删掉配置档目录（~/.dsh/profiles/web），重新跑 plugin add——会干净重建 |
| 已安装并重启，仍没有 memory 工具 | 查启动日志里有没有 warning: ... did not activate，并用 dsh --profile web --dump-config \| grep fooxe 确认树里有对应条目；若仍存在，带上日志提 issue |
| 安装后出现 ERR_PNPM_IGNORED_BUILDS | 这里无害（零原生依赖）；在配置档目录里跑 pnpm approve-builds 即可清除 |
| plugin add 装的是旧版本 | 你的默认 registry（某个镜像）落后于 npmjs。显式锁定：npx pnpm@11.7.0 add @fooxe/dsh-memory@latest --registry=https://registry.npmjs.org，或在 ~/.npmrc 里加 @fooxe:registry=https://registry.npmjs.org |

工具

| 工具 | 用途 |
| memory_save | 保存一条持久记忆；在检测到项目根目录时作用域默认是项目，否则是用户 |
| memory_search | 跨两个作用域做不区分大小写的关键词搜索（id、标题、标签、内容） |
| memory_read | 读取一条完整记忆——沿用 Claude Code 的 project_memory_read 字段约定（content?、local_file?、size_bytes、updated_at、truncated） |
| memory_list | 按作用域列出最近的记忆，最新的在前 |
工具描述里嵌了一道保存闸门，参照 Claude Code / Codex 的做法：只存以月为单位仍然成立的事实，在得出结论时保存（绝不保存中途状态）；边界情况先问用户；密钥永不保存。

写入规则（移植自 Claude Code / Gemini CLI 实践）：
- 强证据闸门——保存前，模型先问自己「这事一个月后还重要吗？」；拿不准就跳过或问用户（噪声的代价高于遗漏）
- 去重并更新——一个主题（同一个功能 / bug / 排查）对应一条记忆：注入的带日期索引会显示已有内容，同主题保存时就地更新，而不是再写一条近似重复的
- 带日期的索引行——每条记录都带 YYYY-MM-DD，模型在注入时据此判断新鲜还是过期
- 拒绝密钥——凭据 / token / 密码一律明确拒绝，所有写入路径都如此
- 指令式内容——条目写成给未来智能体的祈使句（2-5 句，自包含）；标题是简短指令；索引行最多带 3 个标签

何时存 · 存什么 · 存哪个作用域

何时保存：用户说出偏好或纠正（纠正是价值最高的记忆）、做出决定、出现关键数字 / ID、错误加修复收尾。绝不保存：密钥、临时状态、能从仓库直接读到的东西、未经确认的猜测。

存哪个作用域——一句话判断：这条事实是关于这个人，还是关于这个项目？

| 用户作用域 ~/.dsh/memory | 项目作用域 <project-root>/.dsh/memory |
| 个人偏好（pnpm、中文注释） | 技术决策（选 A 不选 B，因为 C） |
| 工作习惯（提交前先跑测试） | 约定（目录结构、命名、构建命令） |
| 跨项目经验 | 关键数字 / ID（端口、服务器、app ID） |
| 沟通风格 | 团队该通过仓库共享的任何内容 |

换个项目还成立？→ 用户作用域。只在这里成立？→ 项目作用域。

工作原理

两个物理隔离的存储——用户 ~/.dsh/memory 和项目 <project-root>/.dsh/memory——永远不会混在一起。项目根按优先级链自动探测，信号最明确的排在最前：

1. DSH_MEMORY_PROJECT_DIR 环境变量覆盖
2. 上层已存在的 .dsh/memory 标记（支持嵌套的子项目作用域）
3. 上层任意 VCS 根：.git / .svn / .hg
4. 宿主工作区注册表（DSH 的官方项目注册表）
5. 当前目录本身——没有 VCS 的项目也拿到自己的作用域

存储布局

~/.dsh/memory/ <- user scope (personal, cross-project)
|-- MEMORY.md <- guarded index, newest first
|-- memories/20261004-181500-prefer-pnpm.md
<project-root>/.dsh/memory/ <- project scope (team-shared, commit it)
注入发生在会话启动时，通过 ctx.systemPrompt 完成：用户记忆始终注入；项目根级记忆始终注入；带路径标签的记忆，在标签命中会话工作目录链或命中被触碰目录的链时注入（见上文「触碰激活」）；未触碰的标签计入提示行；在作用域级护栏之上再加 25 条上限。

验证

npm install && npm run build && npm test # 64 tests, zero type errors

单元测试 + 针对随包发布的官方类型做类型编译 + 运行时冒烟测试（真实 defineTool，端到端跑通保存 → 搜索 → 读取 → 列表）+ 真实 cordis 激活护栏，CI 覆盖 Ubuntu 和 Windows。

dsh-memory 与 DSH 官方 MCP 记忆方案可以愉快共存——挑适合你工作流的那个，或者两个都用。

许可证

MIT。与 DeepSeek 或 Anthropic 无隶属关系。

中文版

给 DeepSeek Harness 装上跨会话持久记忆——Claude Code 的记忆模型：你的 agent 记得住、醒得来、项目之间不串味。纯文件、零依赖。（English）

这个插件做什么

你的 DSH agent 每次开会话都是"初次见面"。
装上 dsh-memory，它记得你。

会话 1 你："记住——这个项目用 pnpm，不用 npm。"
Agent：memory_save 已保存

会话 2 你："我们用什么包管理器？"
Agent："pnpm——你昨天告诉我的。" <- 从此不用重复解释

无服务端、无账号、无 embedding——只有纯 markdown 文件，删掉目录就是彻底遗忘。

亮点

🖥️ 可视化记忆管理器，不是一堆 markdown

打开 Settings → Memory：双域全部记忆一屏可搜、工作区树形展开（嵌套子项目自动发现）、子文件夹分组、护栏仪表实时可见（行数 / KB / 文件数）。面板内直接新增、改写、打标签、删除任意记忆——和 agent 工具调用走同一条带护栏管线，你在界面改的就是模型下次看到的。

👆 触碰激活——CLAUDE.md 语义（v0.13）

项目记忆带子目录标签。标签命中会话工作目录（含祖先链）时注入——会话触碰它的那一刻也注入：一次 read/edit/write/grep/glob/bash/pwsh 调用进了 frontend/src，[frontend] 和 [frontend/src] 立即激活并保持到会话结束。单调递增、会话恢复后仍在——和嵌套 CLAUDE.md 完全同理，由你实际做了什么触发，而不只是启动时 cd 在哪。

未触碰区域不静默隐藏，始终提示：+3 more tagged to areas you haven't touched — memory_search surfaces them.

🧠 会话级——读写同桶

每个会话的提示词携带它自己工作区的记忆，保存也落进同一个工作区——多会话 web 宿主零串味。

📉 天生防膨胀

根级记忆恒注入；区域记忆工作/触碰才加载；注入 25 条上限 + 硬护栏（每域 200 行 / 25KB 索引、500 条）——记得再多也不撑爆上下文。

🔒 管线内置安全

原子写入（崩溃不留半截文件）· 所有写入路径拒存密钥（面板也算）· 面板 API 跨源 + method 双栅栏 · 防 id 路径穿越 · $HOME、盘符根、tmp 目录永不成为项目作用域（Windows 感知）。

🪶 零依赖

没有要部署的、没有会坏的。精简宿主优雅降级——可选宿主服务全部防御式读取，缺了工具照常工作。

快速开始

前置：先装 DSH 本体——npm install -g @deepseek-ai/dsh（源码检出则命令加 pnpm 前缀）。

dsh plugin --profile web add @fooxe/dsh-memory # 已装 DSH CLI
pnpm dsh plugin --profile web add @fooxe/dsh-memory # 源码检出方式

--profile 必填且放在 add 前面——填你实际启动的 profile（Web 界面就是 web；已有哪些看 ~/.dsh/profiles/）。

装完必须重启 DSH（工具只在启动时注册），再开新会话说"记住我喜欢 pnpm"验证。~/.dsh/memory/MEMORY.md 随之出现；项目内决策落在 <项目根>/.dsh/memory/——提交版本库全组共享。

安装排障（每行来自真实安装实测）

| 症状 | 解法 |
| dsh: command not found | DSH 本体没装，看前置步骤 |
| required option '--profile <name>' | 参数放在子命令前面：dsh plugin --profile web add ... |
| pnpm ERR_P..._STORE: Unexpected store location | 终端 pnpm 与 DSH 自带（11.7.0）不一致——删掉整个 profile 目录（~/.dsh/profiles/web）重跑 plugin add，全新重建 |
| 装了也重启了还是没有记忆工具 | 看启动日志 warning: ... did not activate；跑 dsh --profile web --dump-config \| grep fooxe 确认在插件树里；仍在就把日志发 issue |
| ERR_PNPM_IGNORED_BUILDS | 对本插件无害（零原生依赖）；profile 目录跑 pnpm approve-builds 清掉 |
| plugin add 装到旧版本 | 默认源（镜像）滞后。显式官方源：npx pnpm@11.7.0 add @fooxe/dsh-memory@latest --registry=https://registry.npmjs.org；或 ~/.npmrc 加 @fooxe:registry=https://registry.npmjs.org |

四个工具

| 工具 | 作用 |
| memory_save | 保存持久记忆；项目内默认存项目级，否则存用户级 |
| memory_search | 大小写不敏感关键词检索（id/标题/标签/正文，跨双域） |
| memory_read | 完整读取——字段与 Claude Code 官方 project_memory_read 一致（content?、local_file?、size_bytes、updated_at、truncated） |
| memory_list | 双域最近记忆列表（新→旧） |

工具描述内置保存门槛（参照 Claude Code / Codex）——只存月度级稳定事实、结论时刻保存（过程状态不存）、拿不准先问用户；密钥永不存。

写入规则（移植自 Claude Code / Gemini CLI 实践）：
- 强证据门槛——存前自问“一个月后还有用吗？”，不确定就跳过或先问用户（噪音比缺口更贵）
- 同主题原地更新——一个主题（同一功能/缺陷/调查）只留一条记忆：注入的带日期索引就是现存清单，同主题保存原地更新而非近似复制
- 日期索引——每条带 YYYY-MM-DD，注入时模型可推理新旧
- 密钥拒存——凭据/令牌/密码一律拒绝并明说，覆盖所有写入路径
- 指令式内容——记忆是写给未来 agent 的祈使句（2-5 句自包含）；标题=短指令；索引行标签至多 3 个

何时记 · 记什么 · 记哪级

何时记：偏好/纠正出现（纠正是最高价值记忆）、决策诞生、关键数字/ID 出现、踩坑+解法闭环。永不记：密钥、临时状态、代码里直接能读到的、未证实的猜测。

记哪级——一句话判定：关于"这个人"还是"这个工程"？

| 记用户级 ~/.dsh/memory | 记项目级 <项目根>/.dsh/memory |
| 个人偏好（我用 pnpm、注释用中文） | 技术决策（用 A 方案，因为 C） |
| 工作习惯（先跑测试再提交） | 项目约定（目录结构、命名、构建命令） |
| 跨项目经验（"这类库都有 X 坑"） | 关键数字/ID（端口、服务器、AppID） |
| 沟通风格 | 一切该随版本库共享给团队的 |

换个项目这条还成立？→ 用户级。只在这里成立？→ 项目级。

工作原理

两个物理隔离的存储域——用户级 ~/.dsh/memory + 项目级 <项目根>/.dsh/memory——永不混淆。项目根按优先级链自动判定，越明确的信号越优先：

1. DSH_MEMORY_PROJECT_DIR 环境变量
2. 向上找已存在的 .dsh/memory 标记（支持嵌套子项目）
3. 向上找任意 VCS 根：.git / .svn / .hg
4. 宿主 workspace 注册表（DSH 官方项目注册表）
5. 当前目录兜底——无 VCS 项目也拥有自己的作用域

存储布局

~/.dsh/memory/ <- 用户级（个人，跨项目）
|-- MEMORY.md <- 护栏索引，新→旧
|-- memories/20261004-181500-prefer-pnpm.md
<项目根>/.dsh/memory/ <- 项目级（团队共享，随版本库提交）

注入发生在会话启动时（ctx.systemPrompt）：user 域记忆恒注入；项目根级恒注入；带路径标签的按"命中工作目录链 或 触碰目录链"注入（见上方触碰激活）；未触碰的计数进提示行；注入另有 25 条上限叠在域级护栏之上。

验证

npm install && npm run build && npm test # 64 项测试，0 类型错误

单元 + 对官方类型真实编译 + 运行时冒烟（真实 defineTool，save → search → read → list 端到端）+ 真实 cordis 激活守卫；CI 跑 Ubuntu 和 Windows。

与 DSH 官方 MCP 记忆方案完全共存——按工作流任选，或两者同用。MIT 协议，与 DeepSeek、Anthropic 无关联。