# dsh-memory-system

> 为 DSH 提供本地优先的跨会话持久记忆，零外部依赖，Markdown 存数据，写入需确认。

## Metadata

- Author: [@zhujunpeng12](https://github.com/zhujunpeng12)
- Repo: <https://github.com/zhujunpeng12/dsh-memory-system.git>
- GitHub: [zhujunpeng12/dsh-memory-system](https://github.com/zhujunpeng12/dsh-memory-system)
- Stars: 8
- Language: TypeScript
- License: [MIT](https://spdx.org/licenses/MIT.html)
- Topics: `agent-memory`, `ai-agents`, `chinese-bm25`, `coding-agent`, `deepseek-harness`, `dsh`, `dsh-plugin`, `local-first`, `memory-system`, `persistent-memory`, `plugin-evolution`
- Forks: 0
- Open Issues: 0
- Last push: 2026-08-21T03:05:38.000Z
- Added: 2026-08-15T00:00:00.000Z

## Install

```bash
dsh plugin --profile web add github:zhujunpeng12/dsh-memory-system
```

## Wiki

## 一句话定位
为 DeepSeek Harness (DSH) 提供本地优先的跨会话持久记忆能力：每次新会话开始自动注入一个 ≤14KB 的"热记忆包"（门禁/规则/项目摘要/近期事件），需要时再按需召回历史细节，所有数据以纯 Markdown 形式留在用户自己的电脑里。

## 核心能力
- 自动注入热记忆包：每个新会话的首轮自动读取门禁状态、用户画像、活跃规则、当前项目摘要与近期事件标题，组成一个 ≤14KB 的上下文一次注入（可设置 DSH_MEMORY_AUTO_INJECT=false 关闭）
- 按需冷召回：当用户提到历史、纠正或具体主题时，触发中文 BM25 + 精确匹配 + 元数据重排的冷检索，返回带来源与 trace 的 ≤4.2KB 上下文
- 机械门禁体检（memory_gate）：自动检查"原始记录是否被提炼""体量是否超标""规则核心是否同步""是否有未释放的写锁"等健康项，收尾时配合 --closing/--expect-write 模式使用
- 只读治理扫描（memory_govern）：找出重复、冲突、过期、体量超标或生命周期异常的候选条目，只给证据和建议，绝不自动删改
- 轨迹复盘（memory_trajectory_review）：扫描会话轨迹，用"用户纠正"作为硬信号产出复盘候选（场景→错误→根因→先决动作），配合可选的 evidence-ledger 插件可读取工具调用账本
- 安全的授权写入（memory_write）：默认 dry-run 预览，必须用户确认后才进入租约锁事务写入，纠错通过 supersedes 链接到原条目而非覆盖

## 技术实现
- **语言**: JavaScript（ESM，`type: module`）作为宿主插件外壳，记忆引擎全部用 Python 标准库实现
- **关键依赖**: 零 npm 运行时依赖（仅使用 Node 内置的 `node:child_process`/`node:crypto`/`node:fs`/`node:os`/`node:path`/`node:url`）；Python 侧仅依赖标准库（argparse/hashlib/json/pathlib/re 等）
- **架构模式**: Cordis 双注入插件（`inject: ["tools", "agents"]`），通过 `apply(ctx)` 钩入 DSH——`ctx.agents.roots()` 给每个 root agent 注册 6 个工具，`ctx.on("agent/pre-step", ...)` 在每个 session 首轮自动注入热包，`ctx.on("tools/pre-execute", ...)` 拦截写入类工具强制弹确认；Python 脚本通过子进程调用，结果以 JSON 回传
- **入口文件**: `index.js`（宿主侧）+ `bridge.js`（工具参数到 Python CLI argv 的纯函数映射，零依赖便于单测）+ `vault-guard/*.py`（记忆引擎脚本集）

## 适用场景
适合在 DSH 里持续做同一个项目、需要跨会话记住自己之前的决策和偏好的个人开发者与小团队——尤其是中文场景下希望保留可审计的"事实"流水、对隐私敏感、不愿意把对话内容上传到第三方向量服务的工作流。不适合需要多 Agent 高频并发写同一个记忆库、依赖语义向量召回、或希望 AI 自动无审批写记忆的场景。

## 前置依赖与兼容性
| 依赖 | 最低版本 | 说明 |
|---|---|---|
| DeepSeek Harness (DSH) | 0.1.0-rc.7 | 通过 `cordis.patch.yml` 与 `dsh.plugin.json` 注册为 scoped bundle；早期 0.1.0 安装会因 loader 名未加 scope 包或 `agents` 注入缺失而报错，必须升级到 0.1.1+ |
| Node.js | 22 或 24 | `package.json#engines` 未声明，但 TROUBLESHOOTING.md 与 README 一致标注 Node 22/24 可用 |
| Python | 3.10+ | 记忆引擎依赖 Python 标准库；命令名需可用为 `python`，否则通过 `PYTHON` 环境变量指向实际可执行文件（如 Windows 的 `py`） |
| 默认存储 | 无限制 | 默认在 `~/.dsh-memory/` 自动初始化；可通过 `MEMORY_VAULT` 指向任意目录（常见用法：Obsidian Vault 根目录） |

## 安装方式
```bash
dsh plugin --profile web add github:zhujunpeng12/dsh-memory-system
```

## 配置项
| 配置 | 类型 | 说明 | 默认值 |
|---|---|---|---|
| `MEMORY_VAULT` | 路径 | 记忆库根目录（含 `memory/` 与 `projects/` 子目录），留空则用基础模式（普通 Markdown 文件夹） | `~/.dsh-memory` |
| `DSH_HOME` | 路径 | DSH 运行时家目录（hooks 配置、storages 等），影响配套插件 `evidence-ledger` 写入的工具账本位置 | `~/.dsh` |
| `PYTHON` | 可执行文件名 | 调用 Python 脚本所用的解释器命令 | `python` |
| `DSH_MEMORY_AUTO_INJECT` | 布尔 | 设为 `false` 关闭每个新会话首轮自动注入热记忆包的能力 | `true`（默认开启） |

## 常见问题

**Q: 这个插件和 DSH 自带的会话记忆有什么区别？**

A: DSH 默认会话之间是失忆的；本插件把每次会话产生的规则、项目笔记、纠正等"事实"沉淀到本机 Markdown（默认 `~/.dsh-memory`），下次新会话开始时自动注入一个 ≤14KB 的"热记忆包"，需要时再按需召回历史细节，整套数据存你自己电脑里，无需数据库或外部向量服务。

**Q: 记忆数据存在哪里？会泄露到云端吗？**

A: 默认存储在用户主目录的 `~/.dsh-memory/` 目录下，是普通 Markdown 文件夹，仓库本身不含任何个人数据。如需可视化可以设置 `MEMORY_VAULT` 环境变量指向你自己的 Obsidian Vault，所有读写都发生在你本机。

**Q: 安装后还要手动配置什么吗？**

A: 首次运行会自动创建 `~/.dsh-memory/` 骨架（包含 `memory/events/index/projects` 等子目录和空的 `user_profile.md`/`rules.md`），无需任何手动配置。如要切换到 Obsidian 模式或自定义路径，再设置 `MEMORY_VAULT` 和 `DSH_HOME` 环境变量。

**Q: Agent 会偷偷修改我的记忆文件吗？**

A: 不会。所有写入操作（`memory_write`）默认是 dry-run（预览），只在用户明确确认并设置 `apply=true` 时才真正落盘；写入还有 30 秒租约锁、SHA-256 前置条件、before-image 备份、提交回执四层保护，纠错必须 `supersedes` 原条目且不覆盖历史 raw 流水。

**Q: 必须装 Python 才能用吗？**

A: 是的。记忆引擎由 Python 标准库脚本实现（无需 pip 安装任何包），要求 Python 3.10+ 且命令名可用为 `python`；如果你的可执行文件名是 `py` 或 `python3`，启动 Harness 前设置 `PYTHON` 环境变量指向它。

**Q: 怎么卸载？会留下残留文件吗？**

A: 在 web profile 目录执行 `npx @deepseek-ai/dsh plugin --profile web remove @zhujunpeng12/dsh-memory-system` 即可卸载插件本身；插件不会删除 `~/.dsh-memory/` 下的记忆数据，卸载前如不再使用需自行备份或手动删除该目录。

**Q: 需要 Obsidian 吗？**

A: 不需要。默认就是普通本地 Markdown 文件夹，用任何编辑器都能查看；只有想用 Obsidian 双链、关系图谱等可视化功能时，把 `MEMORY_VAULT` 指向你的 Vault 即可切换到 Vault 模式，模板在 `templates/vault/` 里。

**Q: 冷包召回能不能理解同义改写？**

A: 不能。冷召回基于 exact 匹配 + 中文 bigram BM25 + 元数据重排，适合精确/近精确匹配（专有名词、代码标识符、日期、明确主题）；同义改写、长尾表达、跨语言召回能力有限，向量语义检索默认关闭以保持零依赖。

## 上手难度
入门 — 安装一行命令、首次运行自动建库、无需配置即可用；进阶能力（租约锁、SHA-256 事务、trajectory review）可按需了解，不影响日常使用。

## 已知问题与限制
- **写入默认是 dry-run**：不显式 `apply=true` 且经用户确认就不落盘，"Agent 说记下了"不等于真正写入了，需要时用 `memory_gate` 或直接查看 events 文件确认
- **冷召回不是语义向量检索**：基于 BM25 关键词匹配，对同义改写、长尾表达、跨语言召回能力有限；这是零依赖代价的取舍
- **单写者租约锁**：同一记忆库同一时刻只有一个写者，多 Agent 并发写会串行等待；高频多写者场景需拆分记忆库或错峰
- **项目隔离仅按 cwd 祖先匹配**：同一目录的不同 git 分支共享同一记忆库，分支级隔离在路线图中，尚未实现
- **热包按会话注入一次**：会话中途新增的记忆不会自动出现在当前会话的热包里，需显式调用 `memory_recall` 或 `memory_bootstrap` 刷新
- **轨迹复盘的定量维度依赖配套插件**：不装 `plugins/evidence-ledger/` 时只扫描 session 日志中的用户纠正信号（定性），没有工具账本数据可分析
- **首次安装失败常见原因**：早期 0.1.0 版本会因 scoped 包名 loader 问题或 `agents` 注入缺失报错，必须装 0.1.1 或之后的版本
- **Node.js 进程超时保护**：所有脚本调用默认 60 秒超时，`memory_bootstrap`/`memory_recall`/`memory_govern`/`memory_trajectory_review`/`memory_write` 单独放宽到 120 秒

---

This document is auto-generated by [deepseek-plugin.org](https://deepseek-plugin.org). HTML page: [dsh-memory-system](https://deepseek-plugin.org/plugins/zhujunpeng12/dsh-memory-system)
Wiki generated by AI (model: `MiniMax-M3`)