本地持久记忆 huangjua/dsh-local-memory

🧠 dsh-local-memory

为 DSH 智能体提供跨会话的持久本地记忆 100% 本地 • Markdown 即真相 • 自愈 SQLite 镜像 • 前缀缓存友好

功能 • 快速开始 • DSH Power Suite • 工具 • 架构 • 简体中文

💡 为什么需要 dsh-local-memory？

DSH 智能体天生无状态。每开一个新会话都从零开始，你不得不反复交代项目规则、环境配置和编码偏好。

dsh-local-memory 给智能体装上真正属于你的长期记忆：
- 📝 Markdown 是唯一真相来源：所有记忆都以纯 .md 文件存放在 ~/.dsh/memory/ 下。你可以直接查看、编辑，或用 Git 做版本管理。
- ⚡ 零缓存未命中：按会话冻结快照（WeakMap<Session, ...>），保持逐字节的前缀缓存稳定，省 token，响应更快。
- 🔒 100% 本地，失败即关闭：不会泄露到云端。工作区边界严格对照官方工作区注册表校验。
- 🛡️ 分阶段写入审批：修改全局配置档必须由用户明确确认（memory_pending approve），防止模型幻觉乱改。

🚀 快速开始

安装

In your DSH plugin environment
dev_inject_plugin @dsh-external/dsh-local-memory

典型使用流程

1. 让智能体记住：「记住，我们项目用 pnpm 和严格 TypeScript。」
2. 审阅待写入记忆：运行 /local-memory，或通过 memory_pending 批准待写入条目。
3. 无缝召回：任何新会话里，智能体都会自动拿到冻结的记忆上下文，无需额外提示词。

🧩 DSH Power Suite

本插件属于 DSH Agent Power Suite —— 4 个模块化、零硬依赖的插件，组成完整的开发者工作流闭环：

flowchart LR
M["🧠 dsh-local-memory(1. Remember rules & prefs)"] --> E["⚡ dsh-context-economy(2. Save 80%+ tokens reading code)"]
E --> A["🛡️ dsh-evidence(3. Tamper-proof audit receipts)"]
A --> S["🔍 dsh-session-index(4. CJK search & bookmarks)"]
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 | 记忆层（当前） | 整理持久化的长期知识、开发者配置档和工作区约定。 |
| ⚡ dsh-context-economy | 上下文经济 | 把读代码的 token 砍掉 80–93%，给记忆快照留出充足的提示词预算。 |
| 🛡️ dsh-evidence | 审计与回执 | 为执行运行生成 SHA256 回执，让记忆条目落在可验证的证据上。 |
| 🔍 dsh-session-index | 会话搜索 | 为原始 .jsonl.zstd 日志建索引，支持中日韩文字。记忆整理归这里，日志搜索归那里。 |

📖 深入阅读与参考

🛠️ 可用工具与命令（8 个工具 + 1 个命令）

工具

| 工具 | 说明 | 作用域 / 动作 |
| memory_write | 新增记忆条目 | 用户/配置档 ➡️ 暂存；工作区 ➡️ 直接写入 |
| memory_update | 通过 memoryId 或 oldText 修订条目 | 原先的活跃条目标记为 superseded |
| memory_forget | 从活跃记忆中移除条目 | 替换为最小墓碑记录 |
| memory_pending | 管理暂存的审批 | list、approve、reject |
| memory_append_daily| 向每日笔记追加带时间戳的块 | 只追加的工作区草稿本 |
| memory_search | 用 FTS5 trigram 搜索记忆 | 自动预同步改动过的 Markdown |
| memory_status | 详细文件计数、活跃条目、数据库大小 | 只读诊断 |
| memory_distill | 收集候选每日笔记用于蒸馏 | 只读 + 状态元数据 |

用户命令

- /local-memory feedback <receipt-id> bundle <helpful|harmful>：对记忆投递回执提交反馈。

📁 架构与存储布局

~/.dsh/memory/
├── user/ # User-level profile & global memories (MEMORY.md / USER.md)
├── workspaces/<WorkspaceId>/ # Workspace-scoped memories (MEMORY.md)
├── daily/<WorkspaceId>/ # Daily scratch notes (YYYY-MM-DD.md)
├── summaries/ # Distilled summaries
├── pending/memory/ # Staged write approvals
├── index/memory.sqlite # Derived FTS5 SQLite index mirror (Schema v12)
└── meta.json # Metadata & version tracking

关键架构不变量：
- Markdown 是唯一事实来源：所有文本和元数据都放在 .md 文件里。
- SQLite 是可丢弃的副本：一旦损坏，SQLite 会通过 buildMemoryIndex 从 Markdown 自动恢复。
- 搜索前增量同步：memory_search 按 content_hash 即时同步改动过的文件。

⚖️ 设计取舍与边界

| 优势 | 取舍 / 边界 |
| SSOT/副本分离，确保零数据丢失 | Schema v12 迁移链需要严格维护 |
| 双通道：冻结快照 + 实时工具搜索 | 绑定本机（无云同步） |
| 严格的工作区故障关闭隔离 | 索引含明文（不要在不可信的共享机器上使用） |
| 566 个测试用例，覆盖全面 | forget 只移除活跃表面，不做物理磁盘粉碎 |

🧪 构建与测试

Install dependencies
pnpm install --frozen-lockfile

Build TypeScript to lib/
bash scripts/build.sh

Typecheck & Run test suite
npm run typecheck
npm test

🙏 致谢与参考

- Hermes Agent（Nous Research，MIT）：entries.ts、threat.ts、approval.ts 改编自 memory_tool、threat_patterns、write_approval。
- 官方 dsh-plan-mode（MIT）：WeakMap<Session, ...> 冻结 + systemPrompt.section 动态服务商模式。
- Jesse-njx/dsh-memory（MIT）：托管条目内联 HTML 头部元数据格式。
- ben7am1n/dsh-memory（MIT）：Live Context 测试框架架构。

属于 DSH Agent Power Suite。基于 BSD-3-Clause 许可。