dsh-memory
Progressive long-term memory for DeepSeek Harness (DSH) — memory lives as sharded plain
markdown, and only a live-generated index enters the system prompt, so the prompt cost
stays flat however large the memory grows. Two layers (global + per-project) plus the global
rule files, viewable and editable right in DSH Settings, zero extra LLM cost, live re-read.
给 DeepSeek Harness 的渐进式长期记忆：正文是分片的纯 markdown，进系统提示词的只有
实时生成的索引（片 · 条数 · 路径 · 条目行号），记忆再长、提示词开销也恒定。两层结构
（全局层 + 项目层）外加全局规则文件，在设置里就能查看并编辑、不产生任何额外 LLM 调用、写完即生效。
它解决什么
Agent 每次会话都是失忆的。让记忆活下来通常只有两条路：
| 做法 | 代价 |
|---|
| 把记忆塞进系统提示词 | 需要"谁来写、写到哪、怎么注入"的一整套机制 |
| 用 LLM 从会话里提炼事实 | 每轮会话都在后台烧钱，且内容进了别人的向量库 |
本插件的取舍是：记忆就是几个 markdown 文件，注入走 DSH 原生的提示词 seam，写入由当前会话的
agent 顺手完成 —— 于是它既不花钱，也不出本机，还能被 git 跟踪、被人手编辑。
特性
- 两层：
~/.dsh/memory/topics/*.md（全局，按主题分片：用户偏好 / 环境事实 / 通用坑……）
- 零 LLM 成本：插件本身不调用任何模型，只读文件；写记忆用的是会话已经在跑的那个模型。
- 写完即生效：注册的是函数式
text，每次提示词组装都重读文件 —— 不需要重启、不需要刷新。
（对比：cordis.patch.yml 里 personaPrefix 的 !!js 只在 boot 求值一次。）
- 渐进式注入，记忆再长也不炸上下文：注入的是实时生成的索引 —— 每片一行
「片名 · 条数 · 体量 · 路径」，片内每条一行「标题 + 行号」；需要细节时 agent 按行号
read
那一片即可。索引每次组装现算，所以永远不会和正文脱节，正文怎么长、注入体积都恒定。
实测：把 58k 字符的记忆分成 10 片后，每轮注入从 29931 → 约 6.6k 字符。
想要老行为？设置 → 记忆 →「注入方式」切成全文注入（保留字符预算，超预算时给溢出索引）。
- 设置面板可读可写：DSH 设置里多一个「记忆」分栏 —— 每层一个开关，点标题即可展开正文，
还能就地把改动保存回文件（保存前自动留一份
.bak）。全局层按片一个页签；同一个分栏里
可以查看并编辑全局规则文件 ~/.dsh/AGENTS.md。
- 明文、可移植：就是 markdown。可以 git、可以 diff、可以手改；删掉文件即停用（段渲染为空串，
被
renderPrompt() 过滤，零残留）。
安装
从 npm（推荐）
已发布为 @jipika/dsh-memory，也收录在 DSH 1024Store 目录里：
dsh plugin --profile web add @jipika/dsh-memory
本插件自带 cordis.patch.yml（package.json 里声明了 dsh.bundle.patch），安装时 DSH 会自动把它
挂进 profile 的组合树，不需要手工编辑任何 profile 文件。
从源码（想改代码时）
git clone https://github.com/jipika/dsh-memory.git ~/.dsh/local-plugins/dsh-memory
然后以 link: 方式挂进 profile（以 desktop 为例）：
# 1) 依赖（~/.dsh/profiles/desktop/package.json）
# "@jipika/dsh-memory": "link:../../local-plugins/dsh-memory"
# 2) 挂载（~/.dsh/profiles/desktop/cordis.patch.yml 末尾追加）
# - insert:
# - id: dsh-memory
# name: '@jipika/dsh-memory'
cd ~/.dsh/profiles/desktop && pnpm install
装完后若是 link: 方式，pnpm install 会重建 node_modules 链接并把 HMR 的基线路径换掉 —— 建议
重启一次 DSH（host 半在 boot 时加载）。之后改记忆、翻开关都不再需要重启。
记忆文件布局
~/.dsh/memory/topics/ ← 全局层：按主题分片（**新记忆写这里**）
├── preferences.md ← 用户偏好
├── dsh-platform.md ← 环境 / 平台事实
└── … ← 想加几片就加几片，索引自动收录
~/.dsh/memory.md ← 导航索引（人读用；注入不读它）
~/.dsh/AGENTS.md ← 全局规则（新会话注入，面板里也能编辑）
~/.dsh/memory/projects/
├── --Users-me-code-repo--/ ← 项目层：目录形式
│ ├── MEMORY.md ← 索引（同样只注入索引 + 行号）
│ ├── some-topic.md ← 主题正文，按需读
│ └── another-topic.md
└── --Users-me-other-repo--.md ← 项目层：单文件形式（同样支持）
两种形态都支持：有分片目录就按分片走，没有就回落到单文件 —— 所以从单文件迁移到分片
（或反过来）都不需要改配置。分片的片名优先取文件里的 H1 标题。
项目层两种形态的注入方式刻意不同（这点踩过坑）：单文件形式的内容本身就是条目集合
（- [日期] 事实），所以走索引化、只给标题与行号；目录形式里 MEMORY.md 已经是人写的
索引、其余 .md 是带 frontmatter 的正文段落，所以直接注入 MEMORY.md 正文（标题 + 链接 +
摘要，超长时仍走 clamp），另外只列出没被索引登记的正文文件 —— 顺带当索引一致性检查用。
反过来对正文再套一遍条目索引，只会退化成一张纯路径清单（实测某项目 74 篇正文被压成
14340 字符的文件列表，而 MEMORY.md 的摘要一条都没进来）。
从单文件迁移过来：tools/migrate-to-shards.mjs 是当时用的迁移脚本（人工语义分类 + 生成
导航文件 + 先备份），可以按自己的分类改写它。
项目层目录名由会话的 cwd 推出，规则与 DSH 自己的会话目录一致——路径里的 / 换成 -，
两端各加 --：
/Users/me/code/repo → --Users-me-code-repo--
所以 ~/.dsh/sessions/--Users-me-code-repo--/ 与 ~/.dsh/memory/projects/--Users-me-code-repo--/
是同一个项目的两份数据，一眼能对上。
记忆怎么写
由 agent 顺手写（这也是"零 LLM 成本"的来源：写入搭的是本来就跑着的会话）。建议在
~/.dsh/AGENTS.md 里放几条纪律，例如：
Memory upkeep (long-term memory):
- TWO layers, both injected on every assembly (no restart needed):
· GLOBAL `~/.dsh/memory/topics/*.md` — facts that would bite in ANY repo,
sharded by topic (each file starts with a comment saying what belongs there).
`~/.dsh/memory.md` is only a navigation index — never append memory to it.
· PROJECT `~/.dsh/memory/projects/--<cwd-with-slashes-as-dashes>--.md` — facts
that only hold in this workspace.
- What the prompt shows is an INDEX (shard · count · path), not the full text:
read that shard when you need the detail. Index lines carry line numbers.
- Append one line `- [YYYY-MM-DD] fact` under the matching section, in the SAME
turn you learn it. Do not batch for "later". Keep each shard small (~12k chars)
— when one outgrows that, split it by sub-topic in the same directory.
- Do NOT log narration or anything re-derivable from the repo.
- NEVER put secrets in it — both layers ride every request to the model provider.
- Record what IS true, never a removal: "X was uninstalled" is stale the moment
it is written and taxes every future session.
设置面板
设置里会出现一个「记忆」分栏，三组内容：
| 分组 | 条目 | 可编辑的文件 |
|---|
| 全局规则文件 | AGENTS.md（无开关） | ~/.dsh/AGENTS.md |
| 全局层（跨项目） | 全局记忆（带开关） | ~/.dsh/memory/topics/*.md（一片一个页签） |
| 项目层（按工作区） | 每个项目一行（带开关） | 该项目目录下的全部 .md（MEMORY.md + 主题文件） |
- 点任意一行展开：先看到只读正文，点「编辑」变成可写的编辑器，
⌘/Ctrl + S 或「保存」写回文件。
- 一层里有多个文件时（项目记忆的主题文件），用页签切换；未保存的页签带
●。
- 保存是原子写（先写临时文件再 rename），改动前的内容自动留一份
<文件名>.bak；
新建的文件用 0600，已有文件沿用原权限。
AGENTS.md 的生效时机（面板底部也写了）：它在每个新会话开头注入，改完对新会话生效。- 记忆两层是每次提示词组装时实时重读的：保存后下一条消息就带上新内容，不需要重启。
- 关掉的那一层不再注入；再次开启立即重新读取文件。
- 开关存在
~/.dsh/memory/settings.json（与记忆正文同根，面板改、手改文件都即刻生效）：
{
"globalEnabled": true,
"projectEnabled": { "--Users-me-code-repo--": false },
"maxChars": 24000
}
钩子（v0.5.0）
「该不该写记忆 / 有没有好好读记忆」不再只靠提示词劝 —— 钩子直接挂在 DSH 原生工具管线
（tools/pre-execute / tools/post-execute，与官方 dsh-hooks-claude-code 桥同一批事件）上，
在动作发生时硬性判定：
写入钩子（write-guard，tools/pre-execute）
agent 用 write / edit 触碰记忆管辖路径（~/.dsh/memory/**、~/.dsh/memory.md、~/.dsh/AGENTS.md）时，
先跑内置规则引擎，deny 的原因会成为这次工具调用的 Error 结果、直接回到模型面前：
| 规则 | 判定 |
|---|
碰插件内部资产（.bak / audit.log / 记忆目录里的非 md） | deny |
往 memory.md（现役纯导航索引）写正文条目 | deny + 指路 topics/ |
新条目格式不是 - [YYYY-MM-DD] 事实（或日期非法/在未来） | deny + 给出正确格式 |
| 新增内容疑似凭据（sk- / AKIA / ghp_ / Bearer / password= 等 8 类） | deny（只报行号与模式名，不回显值） |
write 整文件覆写导致既有条目变少 | deny + 要求改追加/edit |
bash 重定向/tee/sed -i 改记忆文件 | ask（转人工确认） |
| 过时陈述（「已卸载/不再使用」式）、单条超长 | allow + 审计 note |
writeGuard: "full" 时在内置规则之上再跑一个外部判定命令（writeHookCommand）：
stdin 收到完整 payload JSON（tool/path/layer/oldText/newText/added/removed…），
exit 2 = 拒绝（stderr 为原因）、exit 0 + stdout JSON {decision, reason} 出决策
（兼容 hookSpecificOutput.permissionDecision）—— 所以**「这条值不值得记」的语义判断可以接任意 LLM 脚本**，
不再受提示词约束力上限的限制。决策合并取最严（deny > ask > allow），钩子故障放行不误伤。
审计与读取钩子（tools/post-execute）
- 写入审计：每次记忆写入落盘后追加一行 JSONL 到
~/.dsh/memory/audit.log
（时间/工具/路径/增删行数/判定），超 2MB 自动轮转 .1；落盘内容再校验一遍，
条目格式有问题时附加提醒让模型立即自修。
- 读取提醒：
read 命中记忆文件时附加一条上下文：条目数/字符数、按行号引用、
禁止凭索引臆测、发现过时就地修正。
注入层约束（读取侧）
- 记忆纪律块：注入正文末尾强制附加一段「纪律」（值不值得记才写、格式、钩子会拒绝什么、按行号读）——
提示词约束还在，但背后有钩子兜底。
- 注入过滤命令（可选，
injectHookCommand）：组装好的注入文本过一遍外部命令
（stdin 进、stdout 出，失败/空输出回落原文），可做脱敏或按需裁剪。
开关
设置 → 记忆 → 「写入 / 读取钩子」区块（或手改 ~/.dsh/memory/settings.json）：
{
"writeGuard": "rules", // rules（默认，内置规则）| full（规则+外部命令）| off
"writeHookCommand": "", // writeGuard: full 时的外部判定命令
"hookTimeoutMs": 10000, // 外部命令超时
"discipline": true, // 注入层记忆纪律块
"readReminder": true, // 读取记忆文件时的附加提醒
"audit": true, // 写入审计 audit.log
"injectHookCommand": "" // 注入文本过滤命令（留空不过滤）
}
工作原理
ctx.systemPrompt.section({
name: "dsh-memory:long-term",
order: 1, // 紧跟 DEPLOYMENT_PERSONA_PREFIX(order 0)，先于工具规范
text: compose, // ← 函数：每次 assemble() 重新求值
});
compose() 按当前 cwd 决定注入哪些层，并遵守开关；任一层不可用（文件缺失 / 开关关闭）就返回空串，
而空段会被 dsh-system-prompt 的 renderPrompt() 过滤掉。
插件同时注册：
- 开关存在插件自持的
~/.dsh/memory/settings.json：注入与钩子每次现读，面板改完即刻生效，
也不经过会换代的宿主设置 API；已知项目清单由 host 直接扫盘，不落第二份状态。
- 三条 HTTP 路由（读写共用同一个白名单解析函数，越不出记忆目录与规则文件）：
GET /dsh-memory/content?target=global|rules|<slug>[&file=<名>][&format=text]
POST /dsh-memory/write { target, file, text } # 需请求头 x-dsh-memory: 1
GET /dsh-memory/settings # 开关当前值 + 已知项目
POST /dsh-memory/settings { patch } # 合并写开关，需请求头 x-dsh-memory: 1
target 只认 global（~/.dsh/memory/topics/*.md，无分片时回落 ~/.dsh/memory.md）、
rules（~/.dsh/ 下的两个规则文件）、
或形如 --Users-me-code-repo-- 的项目 slug；file 只认该层里真实存在的 .md（或 MEMORY.md 新建）。
写路由要求 x-dsh-memory: 1 —— 浏览器跨站简单请求带不上自定义头，省掉一整类 CSRF。
验证
node tests/probe.mjs
93 项断言，全部在临时 HOME 里跑（自造记忆文件，不碰你的真实数据），覆盖：两层注入、
cwd→slug 推导、无 agent 时只注入全局、两个开关的开/关/重开、索引模式（片名取文件 H1、
条目带行号、分片目录优先于单文件、injectMode=full 时回退全文、超预算时给溢出索引）、
注入前拆开 {{（否则整段组装会被 dsh-system-prompt 当未知变量抛错）、读路由（层内文件清单、AGENTS.md、
单文件形式、路径穿越被拒）、写路由（原子写、.bak 回滚点、权限保留、首次建 MEMORY.md、内容未变不重复写、
白名单外写不进去、缺 x-dsh-memory 头 → 403），以及设置面板的渲染与「展开 → 编辑 → 保存」全流程。
兼容性
依赖 DSH 的四个 seam：systemPrompt.section()（函数式 text）、webServer.register({kind:"prefix"})、
tools/pre-execute / tools/post-execute，以及 client 的 settings.section 槽位。
开关走插件自持的 settings.json 与自己的路由，不经过宿主设置服务 —— 0.1.7 把 settings 换成
cordis Config 表单那次换代不影响它。
在 DSH 0.1.7-rc.2（Desktop 应用）上验证通过：node tests/probe.mjs 166 项全绿。
License
MIT
