Obsidian 记忆库 MengXinSu/dsh-viya-memory

viya-memory

给 DeepSeek Harness 的本地长期记忆 —— 卡片就是 Markdown 文件，存在你自己的 Obsidian vault 里。

一个 DSH host 插件：单文件、零构建、零外部依赖（只用 DSH 自带的 @deepseek-ai/schemastery），提供七个记忆工具，卡片以 Markdown + YAML frontmatter + [[]] 双链 落盘。

save · search · read · update · link · forget · stats

English: A local long-term memory plugin for DeepSeek Harness. Cards are plain Markdown files in
your own Obsidian vault — graph, backlinks, search and manual editing come for free. Seven model-facing tools, no database, no background process, no lock-in.

亮点

- 数据是你的：卡片就是 .md 文件，Obsidian 打开就能看、能改、能看图谱。不锁死在任何应用里。
- 关系白送：memory_link 往两张卡各写一条 [[双链]]，要么两边都写、要么都不写，不留单向边。
- 不怕误删：删除是两步的——不带 confirm: true 只返回预览，一个字节都不动；默认软删进 _trashed/。
- 不覆盖你的手改：写入前比对 mtime，你在 Obsidian 里改过的卡不会被旧内容冲掉；你手写的 aliases、cssclasses 等字段逐字保留。
- 自动补 aliases：卡的文件名是 slug 版（标题-变成-这样.md）、标题是空格版，而卡之间的边又按标题记——少一行 aliases，[[卡片标题]] 在 Obsidian 里就解析不了（插件的死链判据认标题，所以从插件侧看不见）。写入时自动补；手写过 aliases 的卡绝不覆盖，标题含 | # [ ] 时跳过（那几种写在 [[]] 里本来就会被截断）；想彻底关掉，手写一行任意 aliases 即可。
- 不让密钥入库：正文、标题、tags、keywords、关系说明命中密钥特征就拒绝写入（库常常会同步到网盘 / 手机）。
- 关得住：save / update / link / forget 只认库内，路径穿越、junction 绕路都会被拒。
- 调用即走：没有定时器、子进程、监听，不驻留后台；写入原子（临时文件 → rename）。1000 张卡规模下实测单次调用约 50–100ms（本机自测，非基准测试）。

安装

dsh plugin --profile <你的 profile 名> add github:MengXinSu/dsh-viya-memory

装完必须配置 library，否则第一次调用会直接报错——这是刻意的，免得卡片被静默写进意外目录。
host 插件改动后需重启 DSH 才生效。

配置

在 profile 的 cordis.patch.yml 里：

- id: viya-memory
name: viya-memory
config:
必填：你的 Obsidian vault 绝对路径 library: '/home/you/Obsidian/MyVault' # Windows: 'D:\Obsidian\MyVault'

| 键 | 默认 | 说明 |
| library | （必填） | vault 绝对路径 |
| userFile | 空（回落 <vault>/user.md） | 常驻 system prompt 的那份文件 |
| softLimit | 1000 | 正文软限（字），超了只提示、不拦 |
| hardLimit | 4000 | 正文硬限（字），超了报错 |
| searchBudget | 2000 | 检索结果总字符预算，超出的条目降级为截短摘要 |
| sensitiveScan | true | 写入前扫描密钥特征 |

七个工具

| 工具 | 参数（加粗必填） | 行为 |
| memory_save | title · content · kind · tags · keywords · importance · links · severity · occurred_at | 新建一张卡；同名卡已存在时，内容高度重合就跳过，否则另起 ## 更新 YYYY-MM-DD 一节追加。正文里的本地图片搬进 _assets/ 并原地改写引用 |
| memory_search | query · limit · tags · threshold · start_time · end_time | 返回标题 + 路径 + 标签 + 摘要。空格或 \| 分关键词（AND）， 通配，只传 返回全部；默认 10 条、无上限 |
| memory_read | title / path（二选一） | 全文 + status / updated / links + 附件绝对路径；找不到时附最多 3 个相近标题 |
| memory_update | title · content · tags · status · importance · keywords · occurred_at | 给哪个改哪个，created 不动、updated 自动刷新 |
| memory_link | source · target · type · weight · description | 两张卡各写一条关系边（related / causes / explains / part_of / contradicts） |
| memory_forget | title · confirm · permanent | 两步删：先预览（删哪张、谁引用了它），confirm: true 才软删；permanent: true 真删，同样要确认 |
| memory_stats | （无） | 只读体检：卡数 / 分布 / 超长卡 / 死链 / 库外链接 / 重名卡 / 回收站 |

user.md：唯一常驻 prompt 的东西

<vault>/user.md 会被注入 system prompt 末尾——这是插件唯一常驻上下文的部分，只放低频变化的东西：称呼、禁忌、偏好。它由你手写，插件不提供写入工具（模型不该有权改你的规矩）。改完下一次请求即生效——每次组装 system prompt 都现读该文件，不缓存。

目录结构

<你的 vault>/ ├── user.md # 常驻 prompt（你手写） ├── 03-Knowledge/ # 默认目录（可建子文件夹，最深 8 层） ├── 02-Projects/ 04-Content/ 05-Prompts/ 06-Business/ 07-Tools/ 08-Mistakes/ ├── _assets/<卡片名>/ # 卡片引用的图片 └── _trashed/ # 软删的卡（恢复 = 拖回原目录）

kind 走三道闸匹配目录（精确 → 归一化 → 互为子串），都不中才新建 NN-slug 一级目录并在返回里报备。
_ / . 前缀目录（_trashed、_assets、.git、.obsidian）是保留区，不算卡目录。

行为细则（几个不写下来一定会踩的地方）

- 标签与关键词：tags: [a, b] 与标量 tags: a 都认；值里可带逗号（序列化自动加引号）、换行会压成空格。关键词中英文逗号都算分隔。
- frontmatter 兼容：认行尾注释 # …、块标量 | / >、CRLF、BOM；status 大小写不敏感。
- 文件名只是存储：Windows 非法字符（* : ? / \ " < > |）转成全角同形字，文件名可读；按字节截断到 150；撞名自动让位成 名-2.md。判重看标题，不看文件名。
- 路径口径：相对路径以库根为基准（与 Obsidian 一致）。memory_read 可读库外文件（看附件用）；其余工具只认库内。路径形式的 title 只能写进卡目录或其子目录。
- 回收站：save / update / link 看不见回收站里的卡；往已标 deleted 的同名卡追加会报错，要先改回 approved 或换标题。
- 边的来源：frontmatter links 是声明过的边；正文里的 [[X]] 是派生边，不写回 frontmatter（正文删掉就没了）；![[嵌入]] 不算边；同目标同类型只留一条。换 type 会把 weight / description 重置为默认值，除非同一次调用里显式给出。
- 删除预览的引用数按 Obsidian 口径：标题、文件名、目录前缀、锚点 / 别名都认，大小写不敏感。
- 图片：只搬明确的图片扩展名；代码块和行内代码里的图片语法不算图片；同名不同内容的图另起名字，不覆盖。
- 追加更新：kind 跟着卡的实际目录走；传了 occurred_at 就采用，不传保留原值。

测试

node --test tests/selftest.mjs

146 项，全部走真实执行路径（mock 一个 ctx 调 apply()，捕获实际注册的工具再真的调用）：frontmatter 往返、 slug 与撞名、kind 三道闸、长度闸、敏感扫描、图片搬运、检索与预算降级、七个工具的完整行为、路径夹取与 junction、删除硬闸、user.md 注入，以及真文件系统端到端冒烟。

大部分用例是被测出来的 bug 反向补的回归；关键修复都做过变异验证（故意改坏 → 确认测试报警 → 恢复比对哈希）。

踩过的两个坑

1. cordis 的服务访问必须先声明 inject。 apply() 用了 ctx.systemPrompt 却没写进 inject，插件整条不激活——不报错，只是一个工具都没注册。mock 的 ctx 是普通对象，自测全绿也抓不到。
2. schemastery 的 .volatile() 字段是盒子对象。 解析后是 { get() } 而不是值：String(库路径) 得到 "[object Object]"，数字阈值全变 NaN 比较、静默失效。

两条都补成了防复发自测。

碎碎念

调研了 23 款现成的记忆插件，然后忘了当初为什么要调研 —— 直接自己写了一个。

—— viya

致谢

感谢 Ww 为本项目的开发与测试提供了模型支持。

本项目由作者与 AI 协作完成：

- DeepSeek V4.1 Flash —— 从零写出第一版，陪作者一起干到凌晨；
- Claude Opus 5.5（Anthropic）—— 负责后续的代码审查、安全加固与测试补全。

License

MIT