dsh-memory-library

记忆图书馆（Memory Library）

在你手动开启记忆的对话里，把聊天沉淀成本地记忆库，用「标题 → 简介 → 正文」三级结构控制读取量，并按放慢的艾宾浩斯曲线逐步压缩。规则文件只在你确认后才会被写入。默认每个工作区独立；也可以选择与另一个项目共用同一套记忆，或只读接取老库后继续写新库。

定位

一句话：按工作区隔离、由你手动开启、规则必须经你确认的本地记忆库。

它把「这个项目长期有效的决定、偏好、约束」沉淀下来，而不是把所有聊天自动灌进模型。

它不是什么：

• 不是全局自动记忆：新对话默认关闭，必须你手动开启。
• 不是语义检索引擎：当前版本按标题、简介、标签、正文做关键词匹配，不做 embedding。
• 不是逐字聊天归档：只保留你的原话和 AI 回复摘录；完整原文以会话日志为准。
• 不是 dsh-memory / dsh-memory-vault / dsh-mnemosyne / dsh-recall 的替代品：它们偏全局、自动或语义检索，这个插件偏项目隔离和可控性。

适合谁 / 不适合谁

适合：

• 同时维护多个项目，不希望 A 项目的记忆污染 B 项目。
• 只想在部分对话里记忆，而不是所有聊天都被记录。
• 希望规则必须自己确认，AI 不能偷偷改。
• 希望记忆是可直接阅读、备份、进 Git 的文本。
• 能接受 0.x 早期版本，并愿意备份。

不适合：

• 想装完就自动记住一切的人。
• 需要“换个说法也能搜到”的语义检索的人。
• 完全不想配置、希望有完整设置页的人。
• 需要百万级条目、复杂结构化查询的人（当前是文件扫描，不是数据库）。

成熟度与兼容性

• 当前是 0.x 早期版本：工具参数、数据格式、整理策略都可能调整。
• 升级前请备份 <工作区>/.dsh-memory/；它就是一个普通文件夹，复制即备份。
• 版本遵循 semver；0.x 的 minor 版本可能包含不兼容变更，CHANGELOG 会写明。
• 当前版本用 Markdown/JSON 纯文本保存；未来可能增加 SQLite 索引、可选语义检索或设置页。
• 不承诺存储实现永远不变；承诺的是：变更会写进 CHANGELOG，并提供迁移说明，不把记忆锁在不可读的格式里。

和同类插件的区别

插件	更偏什么	和本插件的差异
dsh-memory	全局、自动、SQLite FTS	本插件按工作区隔离，且默认不自动记录
dsh-memory-vault	跨会话记忆 + 设置页	本插件有规则确认、三种共享模式、遗忘曲线
dsh-mnemosyne	SQLite / CLI / 管理面板 / 语义	本插件更轻，纯文本、无外部 CLI
dsh-recall	对话历史三层检索、本地语义	本插件不索引全部聊天原文，只沉淀整理后的记忆

以上只描述定位差异，不代表谁更好；具体能力以各自 README 为准。

设计原则（相对稳定）

1. 手动开启：默认关闭；只有你确认的对话才捕获、注入和使用工具。
2. 项目隔离：默认每个工作区一套；跨项目必须显式共用或只读接取。
3. 规则优先且需确认：RULES.md 在提示最前；AI 只能提议，不能直接写。
4. 分级读取：标题 → 简介 → 正文，先给索引，细节按需读取。
5. 可审计：条目、规则、日志都是本地文件，能直接看和备份。
6. 不静默改规则：write / edit 被 guard 拦截，规则只能走审批。

实现细节（可能变化）

• 存储：Markdown 记忆卡 + JSON 状态文件；另有一个可重建的 SQLite 目录柜 catalog.db。
• 检索：目录柜先查标题、一句话、标签；中文按二字/三字切分，短查询回退模糊匹配；没有 embedding。
• 激活：每轮只把 5–8 张“当前最容易想起”的卡放进提示，不是整个目录。
• 整理：调用默认模型做合并/摘要；模型不可用时保留日志重试。
• 遗忘：每条卡有 0–100 的清晰度，按重要度做连续衰减；普通卡约 3 周开始明显变模糊。
• 文件：可选 files/ 文件区，放在记忆库里，共用模式天然共享。
• 界面：当前只有输入框左侧开关；设置通过工具或 settings.json。

这些属于当前实现，不是永久承诺；后续版本可能替换为向量检索或完整设置页，但上面六条设计原则不变。

安装

dsh plugin --profile web add @wafernm/dsh-memory-library

安装后在 Harness 的插件页能看到「记忆图书馆 / Memory Library」。源码仓库根目录仍使用 @local/... 便于本地开发；npm run release:prepare 会生成 dist-release/，其中名称、patch 行和客户端模块 id 会统一替换成发布名。

开发与发布

npm test
npm run release:prepare
npm pack ./dist-release

发布包只包含 index.js、client.js、lib/、cordis.patch.yml、locale/、icon.svg、README、LICENSE、CHANGELOG。

数据放在哪

每个工作区一个目录：<工作区>/.dsh-memory/

以下是当前版本的目录布局，属于实现细节；后续版本可能调整内部文件，但 .dsh-memory/ 这个根目录会保持。

.dsh-memory/
├── RULES.md              # 你确认过的规则（优先级最高）
├── INDEX.md              # 给人看的目录，按主题分组
├── catalog.db            # 目录柜（可重建；卡片仍是唯一真相）
├── settings.json         # 本工作区的覆盖设置（容量、遗忘、注入、文件）
├── mode.json             # 共用模式指针（可选；只读接取用 mounts.json）
├── mounts.json           # 只读接取的外部记忆库及其过滤条件
├── sessions.json         # 哪些对话手动开启了记忆（默认全部关闭）
├── .state.json           # 上次整理 / 容量检查 / 待确认大文件
├── journal/
│   └── 2026-10-24.md     # 每轮聊天：你的原话 + AI 回复要点摘录
├── library/
│   └── mem-xxxx.md       # 记忆卡（front matter + 正文）
├── files/                # 可选：共用文件区（默认不存）
│   └── ab/cd/<hash>-原文件名.png
└── archive/
    └── mem-yyyy.md       # 已归档的记忆卡

记忆卡与目录柜

• 卡片正文是 Markdown，永远可以直接读、直接改、直接备份。
• 目录柜（catalog.db）只存标题、一句话、标签、关联、文件信息、清晰度、上次想起时间；它丢了可以扫卡片重建。
• 日记保留“今天发生了什么”，卡片是从日记里提炼出的“以后还可能用到的事”。
• 每张卡有：重要度、确定程度（原话/整理/推测/有冲突）、关联、文件、清晰度、状态（全文→摘要→短摘要→仅标题→归档）。
• 旧原型的卡片会自动补默认字段，不改写正文，不丢数据。

工作方式

1. 按对话手动开启：每个新对话默认关闭记忆；开关在输入框左侧。
2. 每轮落盘：开启后的对话在 turn/end 时把本轮你的消息和 AI 回复摘录写入当天日记；开启文件保存时，聊天附件也会复制进 files/。
3. 此刻想起：每轮只把 5–8 张“当前最容易想起”的卡放进提示；规则永远排最前；不是把整个目录塞进去。
4. 按需检索：先查标题、一句话、标签；细节用 memory_search / memory_read。全文/深挖不是默认行为。
5. 连续遗忘：清晰度每天缓慢下降，被想起会回春；整理时摘要逐渐变短，不是到点突然删除。
6. 定时整理：每天 3 次（每 8 小时）；合并重复、系关联、标冲突、按清晰度压缩。
7. 容量上限：默认 5 GiB，统计卡片 + 日记 + 文件 + 目录柜；超限先删无引用文件，再压缩低价值卡片，最后才动低价值归档。
8. 规则确认：AI 调 memory_propose_rule 只会弹出审批；你点允许后才追加到 RULES.md。

工具

工具	用途
memory_session	开启/关闭本对话的记忆（默认关闭；开启需审批），status 查看状态
memory_search	检索标题、一句话、标签；可按重要度、标签、确定程度过滤
memory_read	按 id 读卡片全文；也接受 journal:YYYY-MM-DD、index、rules。读卡片会刷新清晰度
memory_write	写入/更新记忆卡：标题、简介、正文、重要度、确定程度、标签、关联
memory_forget	主动遗忘一张卡（不是自动衰减，是你的明确选择）
memory_pin	钉住/取消钉住；钉住的卡不自动变模糊
memory_status	容量、卡片数、文件数、日志、上次整理、文件保存开关
memory_configure	改容量、遗忘、注入预算、文件保存开关和 100 MB 阈值
memory_mode	共用 / 只读接取+新库 / 完全独立；status 查看
memory_link	只读接取另一个项目的记忆库：按标签/重要度/条数过滤，需审批
memory_file_save	把工作区文件复制进 files/，可挂到某张卡；超过阈值需确认
memory_file_list	列出记忆库文件（可按卡片过滤）
memory_file_read	查看文件信息和本机路径
memory_file_forget	删除文件；被卡片引用时需要 force
memory_consolidate	立即执行一次整理（平时自动运行）
memory_propose_rule	提议新增规则，需在审批弹窗中确认

会话开关按钮

输入框工具行左侧有一个紧凑开关：

• 记忆 关（灰色圆点）：本对话不捕获、不注入，记忆工具报“本会话尚未开启记忆”。
• 记忆 开（绿色圆点 + 品牌色边框）：点击即开启；再点一次关闭。
• 点击按钮绕过了 memory_session 的审批弹窗，因为按钮点击本身就是你的手动选择。
• 状态每 5 秒同步一次；切换后下一轮开始注入/停止注入。
• 显示「记忆 !」表示本地 API 没连通，悬停可看错误（通常是页面需要刷新，或 Host 路由未加载）。

按钮走插件自己的本地接口：

GET  /dsh-memory-api/session?id=<sessionId>   -> { enabled, mode, dir }
POST /dsh-memory-api/session {sessionId, enabled}

接口要求页面内注入的随机 x-dsh-memory-token，并在 Host 侧复用同一套 store/mode 解析。如果浏览器的 CSP 拦掉了内联 token 脚本，同源请求（Sec-Fetch-Site: same-origin 或匹配的 Origin/Referer）以及本机回环请求也会被接受；跨站请求拒绝。

遗忘曲线

• 每条卡有 0–100 的清晰度，每天缓慢下降；被 memory_read / 搜索到会回春。
• 普通卡（重要度 3）大约 3 周开始明显变模糊，半年到一年进档案馆；重要度 4 更慢，5 / 钉住不自动缩。
• 清晰度只决定“现在有多清楚”；整理时再按台阶缩短摘要：
  • 75+：全文
  • 50–75：摘要
  • 25–50：短摘要
  • 10–25：仅标题
  • 10 以下：档案馆
• 这是连续的衰减 + 分次整理，不是第 21 天突然删除。
• 归档卡片在 180 天后、且重要度 ≤1 时删除；你可以随时主动 memory_forget。

三种记忆模式

先在本对话开启记忆（memory_session action=on），再选模式；模式是工作区级设置，会话开关单独控制这个对话用不用记忆。在目标工作区的会话里说一句即可，AI 会调 memory_mode 并弹审批：

模式	你可以这样说	行为
共用	「当前项目和源工作区 D:\projects\other-project 共用记忆库」	读写都落到源库：条目、日志、规则、整理全部共用
只读 + 新建	「只读接取 D:\projects\other-project 的 shared 标签、重要度 ≥3、最多 30 条，新记忆写本地」	老库只读；当前项目继续写自己的新库
完全独立	「切回完全独立的记忆库」	清空外链，只用本地库；原有本地库保留

示例里的 D:\projects\other-project 只是占位，换成你自己的源工作区路径即可；macOS/Linux 上就是 /path/to/other-project。

共用模式

• 在目标库写 mode.json：

{
  "mode": "shared",
  "source": "D:\\projects\\other-project\\.dsh-memory"
}

• 之后目标项目的读写、日志、整理、规则都直接操作源库，等于两个项目共用一套记忆。
• 目标项目原来自带的库不会被删除，只是暂不使用；切回独立模式就恢复使用。
• 禁止链式共用（源库本身不能再是另一个库的 shared 目标），避免循环。

只读 + 新建模式

• 源库以「外部接取（只读）」出现在系统提示里，条目 id 形如 m-xxx:mem-yyy。
• memory_search 同时搜本地和外链；memory_read 可读外链正文。
• 实时同步：源库条目更新、压缩、归档后，目标项目下次读取就是最新状态。
• 永远只读：不能写回源库；外链读取也不改变源库的复习计数和遗忘进度。
• 过滤条件写在 mounts.json（tags 任一命中、minImportance、limit），可用 memory_link action=list 查看、action=remove 断开。

[
  {
    "id": "m-abc123",
    "label": "other-project",
    "source": "D:\\projects\\other-project\\.dsh-memory",
    "tags": ["shared"],
    "minImportance": 3,
    "limit": 30
  }
]

完全新建模式

• 默认状态，不读别人的库；别人也不会自动读到它（除非对方显式接取）。
• 切回时删除 mode.json 并清空 mounts.json；本地库内容不受影响。

文件保存

文件放在记忆库的 files/ 里，所以共用模式下所有对话共用同一套文件；只读接取模式下源库文件只读。

设置：

{
  "files": {
    "enabled": false,
    "confirmOverMb": 100
  }
}

• 默认关闭：聊天里的图片/文件不进入记忆库。
• 打开后：聊天附件自动复制进 files/，同一文件只存一份（按内容哈希去重）。
• 超过 100 MB：不自动复制，记为“待确认的大文件”；你明确要求保存时再走一次审批。
• 手动保存：即使总开关关着，memory_file_save 也可以显式保存；超过阈值同样确认。
• 类型：图片、PDF、音视频、文本/文档；可执行文件和脚本默认拒绝。
• 不压缩：图片/视频按原样保存；容量满时先删无引用文件，再动低价值卡片关联文件。

配置（cordis.patch.yml）

插件默认值，可被每个工作区的 .dsh-memory/settings.json 覆盖（可用 memory_configure 工具改）：

maxStorageBytes: 5368709120   # 5 GiB（卡片 + 日记 + 文件 + 目录柜）
consolidationsPerDay: 3
slowdown: 2.5
captureSubagents: false
indexMaxChars: 3500
promptMaxChars: 4200
journalRetentionDays: 45
archiveRetentionDays: 180
files:
  enabled: false              # 默认不保存聊天附件
  confirmOverMb: 100          # 超过 100 MB 单独确认
provider: ''                  # 留空使用默认模型
model: ''

// .dsh-memory/settings.json（只写你想覆盖的键）
{
  "maxStorageBytes": 10737418240,
  "slowdown": 3,
  "promptMaxChars": 5000,
  "files": { "enabled": true, "confirmOverMb": 100 }
}

已知边界

• 默认关闭：新对话不会捕获、不会注入，也不能调用记忆工具；必须由你手动开启本对话。
• 关键词而非语义：目录柜按标题/简介/标签查，中文按二字/三字切分；同义词、意译、模糊描述仍可能搜不到。
• 目录柜可重建：catalog.db 丢了可以扫卡片重建；清晰度、上次想起次数会重置（卡片正文不丢）。
• 规模目标 10,000 张：超过后需要“厚目录”或分区；5 GiB 是安全上限，不是推荐容量。
• 整理质量取决于模型：合并、摘要、重要度、冲突判断都由默认模型完成；模型不可用时只做确定性压缩。
• 遗忘曲线是启发式：连续衰减 + 分次摘要，不是经过论文验证的认知模型；重要度 5 / 钉住有保护，但分类可能出错。
• 共用模式没有并发保护：两个项目同时改同一套文件时，以最后一次写入为准；不要两边同时改规则。
• 文件不压缩：图片/视频按原样保存；容量满时先删无引用文件，再动低价值卡片关联文件；重要文件不动。
• 外链只读：不能写回源库，源库的复习计数与遗忘进度也不受外链读取影响。
• guard 有边界：只能拦 write / edit；绕过工具用 shell 直接改文件，插件无法阻止。
• 不保留逐字全文：只保留“用户原话 + 回复摘录”；需要完整原文时以会话日志为准。
• 0.x 兼容性：数据格式和工具参数仍可能调整；升级前请备份 .dsh-memory/。