dsh-mnemon 使用指南
适用环境：DSH Desktop 0.2.1-rc.3（Windows） / dsh-mnemon 0.5.34 / Mnemon CLI 0.2.12 说明：本版已脱敏——个人账号、仓库地址、本机目录均替换为占位符；请按自己的环境替换后再使用。
0. 安装与配置检查清单
5 分钟上手清单：
在对话里说一句：
记住：……（例如你的偏好/项目约定）。看回复下方的回合记忆栏是否出现写入；点开确认。
开一个新会话问“你还记得……吗”，验证跨会话召回。
侧栏记忆系统里确认条目所在层（运行时记忆 / 项目档案 / 记忆空间），各层操作见第 2 节。
需要同步时点存储 → Git 同步 → 立即同步；远端仓库的
mnemon-sync分支应出现新提交。
1. 三层记忆：先搞清“记到哪”
dsh-mnemon 把记忆分成三层，每层职责不同：
策略（Strategy）决定哪些层常驻、哪些可按需读取；增强（Enhancement）补充能力；Core 会校验成本轮唯一的上下文视图。
一句话选择：偏好/人格 → 运行时记忆；项目知识 → 项目档案；长期证据与关系 → 记忆空间。
2. 三层记忆怎么掌控（实际操作）
三层的控制方式完全不同：运行时记忆是“常驻热缓存”，项目档案是“项目知识库”，记忆空间是“长期证据库”。
2.1 掌控模型
2.2 运行时记忆（最常动的层）
看：侧栏 记忆系统 → 运行时记忆，分
USER.md（用户画像）和MEMORY.md（工作记忆）两页，能看到每条内容与修订。写：
对话直接说：
记住：我偏好简洁中文回答。回复下方出现 「本回合记忆 · 写入 1」，点开能看到写到了哪一层哪一条。
或点回复下的脑形图标（存入记忆）：在弹出的候选内容里改成一句准确的话，选择存成 工作记忆 / 用户画像 / 某个记忆空间，回执会写明去向。
改 / 删：直接在运行时记忆页面编辑或删除条目；或对话里说“不对，改成……”“忘掉关于……的那条”。
容量掌控：
USER.md满 4KB 会做保守整合（不发送到记忆空间）；MEMORY.md满 10KB 会把已提交的工作记忆归档到记忆空间再压缩。所以它只该放“热事实”，不是仓库。
生效：写入后下一轮就进注入快照；新会话开场自动带上，不用问。
2.3 项目档案（按工作区的知识库）
看：记忆系统 → 项目档案，分 active / archived，可搜索、打开、编辑。
写：
对话里说：“把刚才的结论存成项目档案”；agent 认为有可复用项目知识时也会创建。
页面上可以直接新建/编辑 Markdown。
检索：agent 在需要时检索项目档案（按需，不占常驻上下文）；你也可以在页面里搜。
归档 / 删除：归档进 archived，不真正删除，可恢复；不需要的条目可以清理。
范围：
workspaces模式按工作区隔离——换个工作区看到的是另一套档案，这是防跨项目污染的边界。
2.4 记忆空间（长期证据）
看：记忆系统 → 记忆空间 → default，包含 直接检索、内容、实体、图谱、Agent 查询 几个入口；
Agent 查询用自然语言提问并带引用。写：
对话里说：“把这条记到记忆空间”；或脑形图标时选择某个记忆空间。
agent 侧用记忆写入工具，会返回写入回执（可点开定位）。
查：直接检索（关键词/语义）；实体页看实体与关联；图谱看关系；Agent 查询做归纳式回答。
改 / 删：单条记忆的“遗忘”是 Provider 支持的软删除（当前 Mnemon Native 支持）；关联关系可用工具建立/调整。
容量：本地数据库，不受 4KB/10KB 限制；但记忆空间是长期资产，建议定期整理、合并重复。
2.5 行为开关（控制它“注什么、注多少”）
在 插件 → 可组合记忆：
主策略：
default-three-tier（运行时常驻、档案/空间按需），推荐保持；general是全部来源共享预算，能力更强但更费上下文。增强：
auto-capture（主动记录提示）、light-context（常驻内容设共同上限）、scoped（限定可写子集）。想减少打扰可关 auto-capture。召回/写入模式：建议
guided，agent 会先问/确认；改成全自动更容易记错。召回条数/质量：
defaultRecallLimit（默认 10）、recallQuality strict-v1；觉得召回少可放宽阈值，太多则收紧。总开关：
writeEnabled（关闭 = 只读）。存储范围：
workspaces决定按项目隔离；要跨项目共享改global/centralized（换位置不搬数据，迁移用 ZIP）。
2.6 三个实操剧本（照着走一遍）
剧本 A：偏好跨会话
新会话说：
记住：我在 <工作区目录> 做 <你的方向>，回答尽量简洁。看回复下是否出现“本回合记忆 · 写入 1”，点开确认在用户画像。
再开一个新会话直接提问，它应当已经知道这个偏好（无需再提醒）。
剧本 B：项目决策进档案
说：
把刚才关于 <某个技术结论> 的结论存成项目档案。到 记忆系统 → 项目档案 找到并检查内容。
下次问相关问题，agent 应检索到它。
剧本 C：长期证据进记忆空间
说：
把“<一条长期事实>”这条记到记忆空间。到 记忆系统 → 记忆空间 → 直接检索 输入关键词确认；或用 Agent 查询 提问。
新会话问相关问题，应能召回。
日常核对：看每轮回复下的回合记忆栏（这一轮到底读写什么）、看记忆系统 → 状态（健康度与 Provider）、定期看记忆空间里有没有该清理的重复。
2.7 掌控原则
一条一个事实；偏好放 USER、项目事实放 MEMORY/项目档案、长期证据放记忆空间。
不要直接编辑
USER.md/MEMORY.md文件（它们是投影），用记忆系统/记忆工具改。子代理会话不参与记忆；换工作区看到的是该工作区的数据。
不存密码/密钥/令牌；记忆空间默认本地库，第三方 Provider 未启用。
每周看“状态 + 同步”，每月做一次 ZIP 备份。
3. 日常使用
3.1 让它记住
自然语言：直接说“记住：……”，“以后回答尽量简洁”。
回合记忆栏：每条回复下方会列出这一轮读到/写入了什么记忆，点开即可在记忆系统中定位。
脑形图标（存入记忆）：对某条回复点脑形图标，可把其中值得保留的事实提炼后写入你选择的位置（工作记忆 / 用户画像 / 某个记忆空间），回执会写明存到了哪里。
主动记录（auto-capture）：开启后，对话中出现值得保留的事实时，插件会提示保留，由你确认后写入。
3.2 纠正与忘记
直接说“不对，改成……”“忘掉关于……的那条”。
在记忆系统里直接编辑或删除：运行时记忆、项目档案都可编辑；记忆空间的“遗忘”是 Provider 支持的软删除。
不要直接编辑
MEMORY.md/USER.md文件——它们是投影文件，请通过记忆系统/记忆工具修改，否则会被覆盖。
3.3 查看与检索
侧栏 记忆系统：
状态：引擎、CLI、Provider、记忆空间健康度；
运行时记忆：
USER.md、MEMORY.md的当前内容与修订记录；项目档案：按工作区浏览、检索、新建、编辑、归档；
记忆空间：内容、直接检索、实体、图谱、Agent 查询；
技能管理（实验性）：技能版本与自进化建议，自进化默认关闭。
对话内也可以用自然语言让 agent 查：“用记忆工具搜一下我们之前关于 X 的结论”。
3.4 Agent 侧的记忆工具（了解即可）
4. 配置说明（插件 → 可组合记忆）
当前值来自 profile 的 cordis.patch.yml（id: mnemon 行）；界面修改会写回该文件，手动改文件后需重启 DSH。
5. 数据位置、备份与 Git 同步
5.1 数据在哪里
5.2 ZIP 备份（首选）
入口：插件页的备份/导出（ZIP）。
内容：运行时记忆、项目档案、Mnemon Native 记忆空间；不含第三方 Provider 的数据与密钥。
备份包含私有记忆，请妥善保管；恢复时导入 ZIP。
建议每月做一次。
5.3 Git 同步（可选）
仓库：
git@<git-host>:<你的账号>/<仓库名>.git（HTTPS 亦可，私有仓库更合适）分支：
mnemon-sync；目录：mnemon/操作：立即同步（合并 → 导出完整包 → 提交 → 推送）、检查远端（只读预览差异）、自动同步（可设间隔或关闭）
规则要点：
每次推送前先合并远端分支；被其他设备抢先推送会再合并重试一次；
两边都改过的项目档案会保留副本，不会静默覆盖；
换仓库/分支会重建镜像；空仓库第一次同步会创建分支；
同步只带记忆内容（运行时、档案、Mnemon Native 空间），不带 profile 配置和第三方凭据。
跨设备：另一台机器安装 dsh-mnemon 后填同一个仓库地址，点“立即同步”即可拉取；两台设备各自保留本机设置。
⚠️ 同步仓库与 ZIP 备份都包含私有记忆，不要设为公开仓库。
检查远端命令：
git ls-remote --heads <你的仓库地址>
5.4 中文用户名下的 SSH 问题（可选阅读）
Git 自带 ssh 在用户名含中文时，可能把 ~/.ssh/known_hosts 解析成乱码路径，导致 Host key verification failed。可让 git 使用 Windows 自带 OpenSSH：
git config --global core.sshCommand "C:/Windows/System32/OpenSSH/ssh.exe"
# 需要回退时：
git config --global --unset core.sshCommand
6. 维护节奏（建议）
每周：打开“记忆系统 → 状态”看一眼健康度；确认
last-run.json正常；在记忆空间做一次整理（合并重复、裁决冲突）。每月：做一次 ZIP 备份。
版本更新：记忆系统 → 状态 → 检查版本 → 更新；桌面端更新后完全退出 DSH 再打开。不要用插件页更新（旧版本会卡
already-installed）。不要同时安装第二个记忆插件（会重复注入、互相干扰）。
7. 常见问题
8. 命令速查（PowerShell）
# Mnemon CLI
Get-Command mnemon; mnemon --version
# git 的 ssh 配置（修复中文用户名问题）
git config --global core.sshCommand
# 远端同步分支
git ls-remote --heads <你的仓库地址>
# 最近一次同步结果
Get-Content "<数据根目录>\workspaces\*\state\sync\last-run.json"
# 当前插件版本 / npm 最新版
(Get-Content "<DSH_HOME>\profiles\<profile>\node_modules\dsh-mnemon\package.json" -Raw | ConvertFrom-Json).version
npm view dsh-mnemon version
9. 记忆写作建议（决定效果）
记稳定、可复用的东西：偏好、称呼、项目约定、决策、环境/工具坑；不要记临时进度、原始日志、一次性问题。
一条一个事实，尽量带上项目/来源上下文，方便以后检索。
分层投放：用户偏好 →
USER.md；项目/环境事实 →MEMORY.md或项目档案；长期证据与关系 → 记忆空间。不要记密码、密钥、令牌；确需记录凭据请用环境变量或专门的密钥管理。
定期整理：合并重复、裁决冲突、归档过期内容（记忆整理功能）。
10. 参考
dsh-mnemon GitHub：https://github.com/omdsh-dev/dsh-mnemon
官方中文文档：
docs/zh-CN/guides/installation.md、getting-started.md、operations.md、memory-providers.md、skills.md（在仓库 docs 目录）Git 同步源码说明：
docs/zh-CN/guides/operations.md#git-仓库同步
本文档为脱敏公开版；个人账号、仓库地址、本机目录均以占位符表示。插件升级后如界面名称/字段有变化，以“记忆系统 → 状态”和插件页为准。