# dsh-simple-memory 🧠

[English](README.md) | [简体中文](README.zh-CN.md)

![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)

[![Awesome DSH Plugin](https://awesome-dsh-plugin.com/badge.svg)](https://awesome-dsh-plugin.com)

面向 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)（`dsh`）web 的**简单记忆管家**：检索式记忆，存储零代码。不建数据库、不搞向量检索——就是"组织好的 md 文件 + 一个只管入口的薄插件"。正常干活不受打扰，记忆作为**外挂文件系统**在旁边积累，规则时不时提醒你记一笔。

> **状态：核心链路已通（0.2.0），真实使用效果待长期测试**——测试流程与结果见 [docs/全链路验证记录](docs/全链路验证记录-2026-08-18.md)，设计原理见 [docs/记忆系统设计说明](docs/记忆系统设计说明.md)。

*非官方项目：社区成员独立开发维护，非 DeepSeek 官方产品。*

## 截图

**记忆按钮**（输入框左侧灯泡）：点一下弹出**四动作菜单**——联想（回顾本轮列候选，等你确认才写）/ 升格（整理暂存池与做梦池，提议去向）/ 查记忆库（列表 + 搜索 + 读全文）/ 做梦（随机组合记忆找跨界洞察）：

![记忆按钮的四动作菜单](assets/memory-button.png)

**记忆库浮层**（菜单里选「查记忆库」）：就地弹出——项目/全局分组 + **搜索框** + 点开读全文，顶部带三个池子计数（全局 · 暂存池 · 做梦池）；再点灯泡、点 ×、或点界面其他位置都会收起：

![记忆库浮层](assets/memory-browse.png)

**记忆管理页**（设置 → 记忆）：状态总览、记忆根目录配置、平级项目列表 + 全局，点开即读：

![记忆管理设置页](assets/memory-settings.png)

## 功能

| 操作 | 效果 |
|---|---|
| 开会话 | 自动注入**三段式**记忆索引（当前项目进度正文 + 最近动过 6 条 + 其余分类计数），每会话首轮一次——模型既"想得起"有什么，也看得到项目现状 |
| 点记忆按钮 | 弹出**四动作菜单**：**联想**（回顾本轮 → 列值得记的候选 + scope + 理由 → 等你确认才写）/ **升格**（整理 staging 与 dreams 两个池子 → 提议去向 → 确认后执行出池）/ **查记忆库**（就地浮层：分组列表 + 搜索框 + 点开读全文）/ **做梦**（随机组合 3~5 条记忆找跨界洞察，产出进做梦池等确认） |
| 写记忆 | `memory-write` 工具强制格式（文件名 `分类-主题.md`、≤2KB、日期首行；scope=项目/全局） |
| 浏览记忆 | 输入框浮层或设置页内嵌：所有项目平级列表 + 全局 common/，**带搜索框**，点开即读全文 |
| 做梦池 | `dreams.md` 暂存梦到的洞察（入场记忆 + 连接 + 建议去向 + 状态）；**用户确认后才升格**进 common/ 或对应项目——机制同 staging：暂存 → 确认 → 升格 |
| 跨会话检索 | `session_search` 工具按关键词搜历史会话正文（返回时间 / 工作区 / 标题 / 命中片段）；需先在 profile 打开官方会话全文索引 |
| 初始化 | 设置页一键建目录骨架（common/projects/references/archive/staging）+ `git init` |
| 改位置 | 设置页改记忆根目录（写 patch 配置，重启生效） |

## 安装

```bash
dsh plugin --profile web add "github:a903067276-rgb/dsh-simple-memory#main"
```

装完重启 `dsh web`，设置 → 记忆 → 初始化记忆仓库。
手动兜底安装：见 [docs/install.md](docs/install.md)。

## 用法

- **记忆按钮**（输入框左侧灯泡）——点一下弹出**四动作菜单**（指令自包含，不依赖 AGENTS.md）：
  - **联想**：回顾本轮对话 → 列出值得记的内容（决策/踩坑/新约定/偏好）并标明 scope（项目/全局）+ 理由 → **等你确认后才写** → 贴产出物 → commit。
  - **升格**：读 `staging.md`（升格暂存池）与 `dreams.md`（做梦池）→ 逐条判断去向（升格进 `common/` 或对应项目；重复/已被替代的建议弃用）→ 提议给你确认 → 确认后执行升格并出池。
  - **查记忆库**：就地弹出浏览浮层（项目/全局分组 + **搜索框** + 点开读全文），不占用对话轮次。
  - **做梦**：从全库随机抽 3~5 条记忆做跨界组合，找共性模式 / 矛盾过时 / 迁移机会 / 空白 → 最多产出 2~3 条洞察 → 写入做梦池（含建议去向，状态「待确认」）。
- **设置 → 记忆**——状态总览（全局条数 · 暂存池 · 做梦池）、记忆根目录配置、一键初始化仓库、内嵌浏览（所有项目平级 + 全局，点开即读）。

## 平台支持

| 平台 | 状态 |
|---|---|
| macOS | ✅ 开发环境 |
| Linux | ⚠️ 预期可用（纯文件操作），未实测 |
| Windows | ⚠️ 预期可用（纯文件操作），未实测 |

## 环境要求

- DSH web（≥ 0.1.0-rc.6）
- **版本兼容**（尽力兼容——设置卡片用双字段 `key`+`id` 注册，同满足 rc.6（id 契约）与 rc.7+（key 契约）；已在本地实测 rc.6/rc.8/0.1.1-rc.2/0.1.5-rc.1，**不保证每个 DSH 版本**）：
  - DSH 0.1.0-rc.6 及以上（含 0.1.1-rc.1/rc.2）：装 `main`（默认）。
  - **DSH 0.1.5-rc.1：加载实测通过**（插件已进客户端 bundle、host 半加载、设置分区渲染）；记忆读写走自有 `/api/dsh-simple-memory` 路由，不依赖 0.1.5 变更过的契约。UI 交互未逐项肉眼复测。
  - 保守回退（升级前的最后版本）：DSH 0.1.0-rc.7/rc.8 → `v0.2.5`（`dsh plugin add github:a903067276-rgb/dsh-simple-memory#v0.2.5`）；DSH 0.1.0-rc.6 → 冻结 `rc6-compat`（不再维护）。
- git CLI（可选：没有 git，记忆目录就是普通文件夹）
- **维护策略**：本插件将持续跟随 DSH 最新版本演进；对旧版 DSH 的兼容仅是尽力而为、不保证长期有效。

## 工作原理

检索式记忆：**文件即存储，插件只管入口**。完整设计见 [docs/记忆系统设计说明](docs/记忆系统设计说明.md)。

- **存储（零代码）**：记忆统一收在记忆根 `~/Documents/DSH/memory/`（设置页可改）：
  ```
  memory/
  ├── common/          全局经验（活跃区，跨项目复用）
  ├── projects/<项目名>/  项目经验（首次写入自动建目录）
  ├── references/      冷区：参考资料（命中搜索才读）
  ├── archive/         冷区：被遗忘移出的旧记忆
  ├── staging.md       升格暂存池（跨项目复用候选）
  └── .git/            整个记忆根一个 git 仓库——回滚保障
  ```
  项目记忆**不落项目目录**（`.gitignore` 掉 `memory/` 会挡住 grep）——收在共享根，发布隔离天然成立、检索全局覆盖。

- **索引注入（想得起，三段式）**：每会话首步（`agent/pre-step`）注入——① **当前项目进度正文**（`progress/<项目>.md`，让接续时看到真实现状而不是滞后状态；超 14 天标"已滞后"，时间给到分钟/小时）；② **最近动过的 6 条**记忆（标题 + 首行结论，跨项目 + 全局按 mtime，让"最近踩过的坑"自动浮现）；③ 其余只给**分类计数 + 检索入口**（要哪条用 `memory_search` 检索，不通读）。`docs/` 保留文件名——它在记忆根之外，检索覆盖不到。实测注入约 **2536 字符 / 2024 token**（cl100k 口径，DeepSeek 中文分词约 1450~1700），且**不随记忆条数增长**。冷区（references/、archive/）不注入，命中搜索才读。

- **写入工具（记得住）**：`memory-write` 强制格式（文件名 `分类-主题.md`、首行日期、≤2KB、分类开放自造：踩坑/流程/决策/偏好/背景起步）；`scope` 二选一（项目/全局）。写工作区外自动弹审批（= 写入前确认）。

- **记忆按钮（四动作菜单）**：输入框左侧灯泡，点击弹出——**联想**（回顾对话 → 逐条提议并标 scope（项目/全局）+ 理由 → 等确认 → memory-write 写入 → 贴产出物 → commit）/ **升格**（整理 staging + dreams 两个池子 → 提议去向 → 确认后执行出池）/ **查记忆库**（就地浮层：分组列表 + 搜索 + 读全文）/ **做梦**（随机抽 3~5 条记忆跨界组合 → 最多 2~3 条洞察 → 写入做梦池待确认）。

- **设置页（管理+浏览）**：状态行（活跃条数 · staging 条数 · 做梦池条数）、记忆根目录配置、一键初始化骨架（含 `staging.md` / `dreams.md` 模板）、内嵌浏览（所有项目平级 + 全局，点开即读）。

- **检索（找得到）**：不建索引文件，agent 的 grep 直接搜整个记忆根（所有项目 + 全局 + 冷区），先活跃后冷区。

- **跨会话检索（问得到"上次聊过什么"）**：`session_search` 调官方会话全文索引（`session-query-sqlite`），返回命中会话的时间 / 工作区 / 标题 / 命中片段。
  - 前置：profile 的 `cordis.patch.yml` 把 `session-query-sqlite` 的 `openAt` 覆盖为 `first-search`（建议同时配持久 `path`），重启 dsh 生效；索引没开时工具返回可操作提示，不算错误。
  - **已知限制（2026-09-10 实测）**：官方索引建库是**全量扫描**历史会话，任何一条读不动的老日志都会让检索**整体失败**（`session-search persistence observation failed: …`）。实测本机 150 条会话里 27 条 v0 老格式日志会触发（多为 `subagent/descriptor … uses unsupported descriptor version 2`，另有手工修过的 `chunk provenance`）；把这些日志移出 sessions 目录后检索恢复正常。验证记录：[docs/验证记录-2026-09-10-session_search.md](docs/验证记录-2026-09-10-session_search.md)。

- **升格（跨项目复用）**：项目经验看着可复用 → 入 `staging.md`（低摩擦，不逼当场决策）；池子非空提醒（索引尾部 + 写入工具提示）→ 用户点头 → 提炼入 `common/` 或对应项目 → 出池删条目。

- **做梦（随机组合找洞察）**：从全库**纯随机**抽 3~5 条记忆做跨界组合，找共性模式 / 矛盾过时 / 迁移机会 / 空白；产出写 `dreams.md`（含建议去向 + 状态「待确认」），**用户确认后才升格**——与 staging 同一套下游动作（暂存 → 确认 → 升格）。**联想策略（2026-09-13）**：抽样保持纯随机，但优先从「零碎经验」（踩坑 / 未消化的原始记录）下手，成熟决策之间硬凑的连接要克制；产出的结论必须是入场记忆原文里**都没明说**的，只是复述原文不算洞察——抠不出真东西就直说"这次没梦到"，池子留空。

- **池子计数统一规则（2026-09-13 定）**：索引尾部提示与设置页的池子计数**只算待处理条目**——`dreams.md` 里标了 `[已弃]`/`[已采纳]` 的行、以及任何非 `- 日期` 格式的留痕都**不计入**；漏标状态的条目照常计入（宁可多提示，绝不漏提示）。留痕推荐写成 `（已弃：…）` 这类非条目格式。

- **遗忘（上下文保鲜）**：过期的活跃记忆移入 `archive/`（软删除：还在硬盘，只退出索引）。上下文永远清爽，硬盘永远完整。

- **回滚**：每次记忆操作立即 commit（`mem: <操作> <对象>`），写错一个 `git checkout` 回来。

## 注意事项

- 记忆 git 仓库仅本地，不推远端
- 写记忆在工作区外会弹审批（= 写入前确认，符合记忆规范）
- 四动作指令（联想 / 升格 / 做梦）均自包含，不依赖全局 AGENTS.md；AGENTS.md 里的判断标准仅作参考

## 许可证

[MIT](LICENSE)