dsh-memoir 使用指南

为 DSH Agent 提供本地项目记忆层：把工作结论、经验教训、后续行动沉淀跨会话，并通过有界 Hot Memory 自动注入 + BM25 排序召回 + Web 面板管理。

本文为派生内容（基于 wiki / faq / compatibility_json 自动组装），非 AI 即时创作。

本文由本站基于该插件已收录的字段自动派生（wiki / faq / compatibility_json / readme），非 AI 即时创作。每节末尾标源字段。

快速上手

— 源: plugin_wiki.wiki_content

dsh plugin --profile web add dsh-memoir

复制以上命令在 DSH Web Profile 内运行。安装完成后在「插件列表」启用即可。

— 源: plugins.install

Local-only：全部数据留在本机（~/.dsh/dsh-memoir.json + 项目内 PROJECT_MEMORY.md）
Zero external memory service：无向量数据库、无 embedding API、无云端记忆服务
Bounded hot-memory injection：token 预算内的 Hot Memory 自动注入 system prompt（默认 900/1200）
Ranked local recall：倒排索引 + BM25 本地排序召回，memoir_read 按需检索长尾历史
Web GUI：侧边栏「记忆」面板——项目/全局浏览、相关排序搜索、Hot Memory Inspector、Retrieval Diagnostics

— 源: plugin_wiki.readme_zh (fallback readme_raw)

不做任何配置能直接用吗？

可以。cordis.patch.yml 把所有配置项都标为可选默认值（enabled/announceToAgent/autoDistill 默认 true，hotMemoryTokens 默认 900，hotMemoryMaxTokens 默认 1200），不写 config 块也能正常使用。

数据存在哪里？会不会上云？

全部留在本机。结构化 JSON 存在 ~/.dsh/dsh-memoir.json（唯一事实源），每个项目根目录还会自动生成 PROJECT_MEMORY.md 人类可读投影（可随 git 提交）。源码中没有任何 embedding API、向量库或云端记忆服务的调用。

会把全部历史都塞进 system prompt 吗？

不会。v0.4 起只把 token 预算内的 Hot Memory（默认软目标 900 token、硬上限 1200 token）注入 system prompt；长尾历史需要时由 Agent 主动调用 memoir_read 触发 BM25 排序召回。

同会话里我刚记录的内容，下一轮就自动生效吗？

不会立刻生效。注入文本会在同一会话首轮构建后冻结（保证 prompt 前缀稳定以命中前缀缓存），本会话不再重读；下一个新会话会重建并看到最新记录。

同时开两个 DSH 进程会冲突丢数据吗？

不会。store 的读写走 ~/.dsh/dsh-memoir.lock 跨进程互斥（O_EXCL 独占创建 + 25ms 重试 + 5s 超时），临界区内强制重读磁盘再改写。锁带 pid/createdAt/nonce 元信息，仅在 60s 以上且 pid 已死亡时才会回收。

Windows 路径大小写不同会被当成不同项目吗？

会被识别为同一个项目。canonical key 把整条 Windows 路径全小写（C:\A、c:\a\、C:/A 归到同一个 c:/a 桶），但显示用的 path 仍然保留原始大小写。

如何标记一条过时记忆？会删除历史吗？

用 memoir_update 把 status 设为 superseded 或 archived，或在 Web 面板里点相应按钮。源码明确不删除历史，被替代的条目留在 store 里，Web 面板可切换状态查看。

怎么卸载？

从 web profile 的 bundle 配置里移除这个插入行（cordis.patch.yml 里的 memoir / dsh-memoir 行），重启 dsh web 生效；插件本身不写 DSH 源码，移除后宿主立即回到无该插件状态。

找不到合适的 FAQ？

仓库 README 和 README.en.md 没有专门的 FAQ 章节，上面 8 条问题均基于源码（src/host/store.ts、snapshot.ts、autodistill.ts、tools.ts、retrieval.ts）与 cordis.patch.yml 行为推断。

— 源: plugin_wiki.faq_json

— 源: plugin_wiki.compatibility_json

安装前请审阅上游仓库；本指南基于已收录字段自动派生，可能滞后于最新版本。如发现与官方文档冲突，请以上游为准。

— 来源：通用规则