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 等字段逐字保留。
不让密钥入库：正文、标题、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

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

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

踩过的两个坑

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

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

碎碎念

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

—— viya

致谢

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

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

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

License

MIT

viya-memory

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

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

亮点

数据是你的：卡片就是 .md 文件，Obsidian 打开就能看、能改、能看图谱。不锁死在任何应用里。
关系白送：memory_link 往两张卡各写一条 [[双链]]，要么两边都写、要么都不写，不留单向边。
不怕误删：删除是两步的——不带 confirm: true 只返回预览，一个字节都不动；默认软删进 _trashed/。
不覆盖你的手改：写入前比对 mtime，你在 Obsidian 里改过的卡不会被旧内容冲掉；你手写的 aliases、cssclasses 等字段逐字保留。
不让密钥入库：正文、标题、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              # 常驻 prompt（你手写）
├── 03-Knowledge/        # 默认目录（可建子文件夹，最深 8 层）
├── 02-Projects/ 04-Content/ 05-Prompts/ 06-Business/ 07-Tools/ 08-Mistakes/
├── _assets/<卡片名>/     # 卡片引用的图片
└── _trashed/            # 软删的卡（恢复 = 拖回原目录）

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

标签与关键词：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

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

踩过的两个坑

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

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

碎碎念

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

—— viya

致谢

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

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

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

License

MIT

MengXinSu/dsh-viya-memory

viya-memory

亮点

安装

配置

七个工具

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

目录结构

测试

踩过的两个坑

碎碎念

致谢

License

Community comments

MengXinSu/dsh-viya-memory

viya-memory

亮点

安装

配置

七个工具

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

目录结构

测试

踩过的两个坑

碎碎念

致谢

License

Community comments

MengXinSu/dsh-viya-memory

viya-memory

亮点

安装

配置

七个工具

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

目录结构

测试

踩过的两个坑

碎碎念

致谢

License

Community comments

MengXinSu/dsh-viya-memory

viya-memory

亮点

安装

配置

七个工具

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

目录结构

测试

踩过的两个坑

碎碎念

致谢

License

Community comments

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

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