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

🧠 dsh-local-memory

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

DSH Suite
Storage
License

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

💡 为什么选择 dsh-local-memory？

DSH 智能体天生是无状态的。每次新对话都从零开始，迫使你反复解释项目规则、环境配置和编码偏好。

dsh-local-memory 为你的智能体赋予真正属于你自己的长期记忆：
- 📝 Markdown 是唯一真相来源：所有记忆都以纯 .md 文件形式存储在 ~/.dsh/memory/ 下。你可以查看、编辑，或用 Git 进行版本控制。
- ⚡ 零缓存未命中：采用按会话冻结的快照（WeakMap）来保持逐字节的前缀缓存稳定性，从而节省 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

| 插件 | 在套件中的角色 | 与 Local Memory 的协同 |
|---|---|---|
| 🧠 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  bundle ：提交关于记忆传递凭证的反馈。

📁 架构与存储布局

~/.dsh/memory/
├── user/                       # 用户级画像与全局记忆（MEMORY.md / USER.md）
├── workspaces//   # 工作区范围的记忆（MEMORY.md）
├── daily//        # 每日草稿笔记（YYYY-MM-DD.md）
├── summaries/                  # 提炼后的摘要
├── pending/memory/             # 暂存的写入审批
├── index/memory.sqlite         # 派生的 FTS5 SQLite 索引镜像（Schema v12）
└── meta.json                   # 元数据与版本跟踪

关键架构不变量：
- 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 冻结 + systemPrompt.section 动态提供者模式。
- Jesse-njx/dsh-memory（MIT）：托管条目内联 HTML 头部元数据格式。
- ben7am1n/dsh-memory（MIT）：实时上下文测试框架架构。

属于 DSH Agent Power Suite 的一部分。基于 BSD-3-Clause 许可。