# 🧠 dsh-local-memory
**让 DSH 拥有看得见、改得了、绝不丢的本地持久记忆**
*100% 纯本地 • Markdown 是唯一真源 • SQLite 派生自愈镜像 • Prefix-Cache 友好*
[](https://github.com/huangjua)
[](#)
[](LICENSE)
[核心亮点](#-为什么需要本地记忆层) • [快速上手](#-快速上手) • [DSH 效率套件](#-dsh-agent-效率套件) • [工具列表](#-深度参考与架构) • [English](README.md)
---
### 💡 为什么需要本地记忆层？
DSH 原生无记忆，每轮对话从零开始，重要结论、开发偏好、项目规则反复重问。
**`dsh-local-memory` 为 Agent 补上真正安全可控的长期记忆：**
- 📝 **Markdown 是唯一真源**：所有记忆明文写在 `~/.dsh/memory/` 的 Markdown 文件中，人可直读、可 Git 版本管理。
- ⚡ **零击穿 Prefix Cache**：每会话采用冻结快照机制（`WeakMap`），保证同一会话多次组装字节级一致，省 Token 又极速。
- 🔒 **100% 纯本地与隔离**：绝不上传任何云端，严格依赖官方 WorkspaceRegistry 进行 Fail-closed 权限隔离。
- 🛡️ **全局写入走审批**：用户/全局级记忆写入先进入 Staged 队列，经用户确认（`memory_pending approve`）后才落盘，防 Agent 幻觉乱写。
---
## 🚀 快速上手
### 安装
```bash
# 在 DSH 插件环境中注入
dev_inject_plugin @dsh-external/dsh-local-memory
```
### 典型使用流程
1. **对 Agent 说**：*“记住我们项目统一使用 pnpm 和严格 TypeScript 规范。”*
2. **审查 Staged 记忆**：使用 `/local-memory` 或通过 `memory_pending approve` 批准落盘。
3. **无感唤醒**：在开启的新会话中，Agent 将自动携带冻结的记忆上下文，无需反复提示。
---
## 🧩 DSH Agent 效率套件
本插件是 **DSH Agent 开发者效率套件** 的核心成员 —— 4 个插件无硬依赖，组合使用实现完整工程闭环：
```mermaid
flowchart LR
M["🧠 dsh-local-memory
(1. 跨会话记住规则与偏好)"] --> E["⚡ dsh-context-economy
(2. 省 80%+ Token 读代码)"]
E --> A["🛡️ dsh-evidence
(3. 任务执行与交付存证)"]
A --> S["🔍 dsh-session-index
(4. 中文会话检索与书签)"]
S --> M
style M fill:#e8f4fd,stroke:#2b7de9,stroke-width:2px
style E fill:#eef9f2,stroke:#1e8e3e,stroke-width:2px
style A fill:#fef7e0,stroke:#f29900,stroke-width:2px
style S fill:#f3e8fd,stroke:#8430ce,stroke-width:2px
```
| 插件 | 套件定位 | 与本地记忆层的协作 |
|---|---|---|
| 🧠 **[dsh-local-memory](https://github.com/huangjua/dsh-local-memory)** | **本地记忆层** (当前) | 负责全局与项目级长期记忆沉淀，为人设与规则提供底座。 |
| ⚡ **[dsh-context-economy](https://github.com/huangjua/dsh-context-economy)** | **上下文经济层** | 读代码节省 80–93% Token，为记忆注入留出充裕的 Prompt 空间。 |
| 🛡️ **[dsh-evidence](https://github.com/huangjua/dsh-evidence)** | **审计存证层** | 为执行结果生成不可抵赖的 SHA256 证据包，支撑记忆事实真实性。 |
| 🔍 **[dsh-session-index](https://github.com/huangjua/dsh-session-index)** | **会话历史检索** | 提供 `.jsonl.zstd` 原始日志检索。提炼记忆归本插件，原始日志检索归 session-index。 |
---
## 📖 深度参考与架构
🛠️ 8 个 memory_* 工具与用户命令
### 工具列表
| 工具 | 用途 | 写入路径 |
|---|---|---|
| `memory_write` | 新增记忆条目 | user/profile ➡️ Staged 审批；workspace ➡️ 直写 |
| `memory_update` | 修订条目（`memoryId` 或 `oldText`） | 旧版本标为 `superseded`，保留版本链 |
| `memory_forget` | 删除记忆（最小 tombstone） | 实时检索面彻底不可达 |
| `memory_pending` | Staged 队列管理 | `list` / `approve` / `reject` |
| `memory_append_daily` | 追加时间戳日志块到每日笔记 | Append-only 工作区日志 |
| `memory_search` | FTS5 全文搜索（支持中英文） | 查询前自动增量同步 Markdown |
| `memory_status` | 查看文件数、条目数、索引体积 | 只读诊断信息 |
| `memory_distill` | 收集提炼候选每日笔记 | 只读 + 状态追踪 |
### 用户命令
- `/local-memory feedback bundle `：对记忆注入结果进行显式反馈。
📁 存储目录结构与核心不变式
```text
~/.dsh/memory/
├── user/ # 用户全局记忆 (MEMORY.md / USER.md)
├── workspaces// # 工作区专属记忆 (MEMORY.md)
├── daily// # 每日工作日志 (YYYY-MM-DD.md)
├── summaries/ # 提炼摘要
├── pending/memory/ # 待审批写入队列
├── index/memory.sqlite # 派生 FTS5 索引镜像 (Schema v12)
└── meta.json # 元数据与版本
```
**关键设计：**
- **Markdown 是唯一真源**：正文和生命周期元数据均存在 `.md` 中。
- **SQLite 纯派生可自愈**：损坏时自动重命名为 `.corrupt-*` 并从 Markdown 重建。
- **前置增量同步**：检索前根据 `content_hash` 自动同步变更文件。
⚖️ 优点与权衡边界
| 优点 | 权衡 / 边界 |
|---|---|
| 真源/镜像分离，架构稳固、自动自愈 | Schema v12 迁移链维护成本高 |
| 冻结快照 + 实时搜索双通道 | 单机绑定，无云端多机同步 |
| 完整条目版本链 + 审批隔离 | 索引含本地明文，请勿在不安全共享机使用 |
| 566 项测试全面覆盖 | `forget` 保证检索面清空，不承诺物理扇区擦除 |
🧪 构建与测试
```bash
pnpm install --frozen-lockfile
bash scripts/build.sh # 编译 src → lib
npm run typecheck # 类型检查
npm test # 运行 566 项测试套件
```
🙏 借鉴与致谢
- **Hermes Agent** (Nous Research, MIT): 移植条目管理、威胁扫描与审批流。
- **官方 dsh-plan-mode** (MIT): 借鉴 `WeakMap` 快照冻结模式。
- **Jesse-njx/dsh-memory** (MIT): 借鉴受管条目内联 HTML 元数据头格式。
- **ben7am1n/dsh-memory** (MIT): 借鉴真实 Context 测试骨架。
---