记忆图书馆（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 为准。
设计原则（相对稳定）
- 手动开启：默认关闭；只有你确认的对话才捕获、注入和使用工具。
- 项目隔离：默认每个工作区一套；跨项目必须显式共用或只读接取。
- 规则优先且需确认：
RULES.md在提示最前；AI 只能提议，不能直接写。 - 分级读取：标题 → 简介 → 正文，先给索引，细节按需读取。
- 可审计：条目、规则、日志都是本地文件，能直接看和备份。
- 不静默改规则：
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/-原文件名.png
└── archive/
└── mem-yyyy.md # 已归档的记忆卡
记忆卡与目录柜
- 卡片正文是 Markdown，永远可以直接读、直接改、直接备份。
- 目录柜（
catalog.db）只存标题、一句话、标签、关联、文件信息、清晰度、上次想起时间；它丢了可以扫卡片重建。 - 日记保留“今天发生了什么”，卡片是从日记里提炼出的“以后还可能用到的事”。
- 每张卡有：重要度、确定程度（原话/整理/推测/有冲突）、关联、文件、清晰度、状态（全文→摘要→短摘要→仅标题→归档）。
- 旧原型的卡片会自动补默认字段，不改写正文，不丢数据。
工作方式
- 按对话手动开启：每个新对话默认关闭记忆；开关在输入框左侧。
- 每轮落盘：开启后的对话在
turn/end时把本轮你的消息和 AI 回复摘录写入当天日记；开启文件保存时，聊天附件也会复制进files/。 - 此刻想起：每轮只把 5–8 张“当前最容易想起”的卡放进提示；规则永远排最前；不是把整个目录塞进去。
- 按需检索：先查标题、一句话、标签；细节用
memory_search/memory_read。全文/深挖不是默认行为。 - 连续遗忘：清晰度每天缓慢下降，被想起会回春；整理时摘要逐渐变短，不是到点突然删除。
- 定时整理：每天 3 次（每 8 小时）；合并重复、系关联、标冲突、按清晰度压缩。
- 容量上限：默认 5 GiB，统计卡片 + 日记 + 文件 + 目录柜；超限先删无引用文件，再压缩低价值卡片，最后才动低价值归档。
- 规则确认：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= -> { 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/。
