@dsh-external/dsh-global-memory
DSH Agent 跨会话全局记忆插件（toolkit 形态）。数据仅存本机 $DSH_HOME/memory/，不进入任何业务仓库，也不会上传到远端。
runtime 兼容性：DSH 0.1.x（会话格式 v3）与 0.2.x（会话格式 v4）均可使用。0.2.x 起注入消息必须使用 v4 producer-owned 的 source.kind（plugin:<插件名>），插件已按此写入；历史会话中的旧 kind 会在首次加载时自动修复（见「历史会话兼容迁移」）。
设计原则
- 会话开始自动注入条目级索引：每个会话首 step 自动注入一次全部记忆的轻量索引（按分类分组，列出 key 与 tags），位于 system prompt + tools 之后，不注入全文。
- 模型按需查阅：模型在工作过程中发现记忆里可能有相关内容时，自行调用
memory_recall(key) 读取全文；全文仅在当轮工具结果中返回，用完即止。
- 显式写入：不自动记录对话内容。只有用户明确要求“帮我记一下”，或模型判断应全局保存时，才调用
memory_save 落盘。
- 用户可直接保存：
/memory_save <key> <content...> 命令直接落盘，不经过 LLM，结果不进模型上下文。
工具
| 工具 | 参数 | 行为 |
|---|
memory_save | key*, category*, content*, summary?, tags? | 创建或覆盖一条记忆 |
memory_recall | key* | 按 key 返回该条完整内容 |
memory_search | query*, category?, tag?, limit? | 对 key/content/tags 做大小写不敏感子串搜索，返回摘要 |
memory_delete | key* | 删除一条记忆 |
用户命令
| 命令 | 语法 | 行为 |
|---|
/memory_save | /memory_save <key> <content...> | 直接保存；category 默认 general，summary 自动截取 |
/memory_delete | /memory_delete <key> | 直接删除 |
命令在 UI 命令面执行，内容不经过 LLM、不进模型历史、不占 token。
数据位置与格式
$DSH_HOME/memory/
index.json # 索引缓存，可由 m*.json 重建
m0001_<key>.json # 单条记忆
key：[a-zA-Z0-9_-]，1–64 字符category：[a-zA-Z0-9_-]，1–32 字符，由模型在保存时自行总结content：UTF-8，单条上限 256 KBsummary：可选，缺省自动截取 content 首行/前 80 字tags：可选，单 tag ≤ 32 字符
安装
- 内部开发调试：
dev_build_plugin 构建 + dev_inject_plugin 运行时注入（免重启，无需改 profile）。
- 常驻装配：
dsh plugin --profile <name> add link:<本目录>（或 super-injector 的 dev_install_package）。该路径会把包写进 profile 的 dsh.profile.bundles，要求本包 package.json 具备 dsh.bundle.patch 声明并随仓库提供 cordis.patch.yml（本仓库已提供）。
历史会话兼容迁移
0.0.5 起，插件写入的索引消息使用 v4 producer-owned 的 source.kind = "plugin:@dsh-external/dsh-global-memory"。DSH 0.2.x 的会话格式 v4 原生准入明确拒绝 kind === "plugin" 的包裹式 source（format v4 message requires a producer-owned source kind）；v3 runtime 也接纳命名空间形态，因此无需按版本分支。
升级后首次加载插件时，会在任何会话被打开之前自动扫描 $DSH_HOME/sessions：
- 处理本插件历史上写出的两代载荷：
source.kind = "memory-index"（≤ 0.0.3）与 { kind: "plugin", plugin: <本插件名> }（0.0.4），统一改写为 plugin:@dsh-external/dsh-global-memory；
- 只改写
plugin 字段等于本插件名的记录，其他插件的 source 一律不动；
- 每个会话目录只处理当前代次的活跃工件（
session.v4.jsonl.zstd 等），旧代次备份保持原样；
- 修改前为每个会话文件创建
session.<ver>.jsonl.zstd.bak-dsh-global-memory-2 备份；
- 迁移完成状态记录在
$DSH_HOME/memory/.legacy-session-source-migration.json，重复启动不会重复修改（版本号提升后会自动重跑一次）；
- 单个文件迁移失败时不会写完成标记，下次启动会重试。
⚠️ 0.0.4 的迁移会把 memory-index 改写成 kind: "plugin" 包裹形态。该形态在 v3 下正确，但在 DSH 0.2.x（会话格式 v4）下非法，会让整轮运行失败。0.0.5 的迁移（版本号 2）会修复这批历史文件。
隐私说明
- 本插件只做显式记忆，不自动采集对话内容。
- 记忆文件只存在于本机
$DSH_HOME/memory/，不进入 git 仓库（见 .gitignore），也不会上传远端。
