记忆管理插件（dsh-memory-manager）
为 DSH（DeepSeek Harness）打造的记忆管理插件：跨会话记忆库、规约记忆自动注入、会话总结、上下文计划注入、Agent 记忆工具、力导向图谱与完整的对话侧栏面板。
Memory Manager for DSH — cross-session memory library, conventions auto-injection, session summaries, context planning & Agent memory tools.
功能特性
- 文件夹记忆库：以「文件夹 + Markdown」形式存放记忆（
memories/*.md），front-matter 元数据，Obsidian 兼容，可直接用任意编辑器或图谱工具打开。
- 记忆 = 不可变快照 + 可编辑标注层：快照保存历史事实，
<!-- mem:notes --> 标注层可随时补充说明，互不污染。
- 记忆标签（tags）与启用开关（enabled）：每条记忆可带分类标签与记忆级启用开关；
tags 含 convention 即规约记忆、含 会话总结 即会话总结记忆，enabled=false 的记忆不参与自动注入、不能加入注入计划。
- 规约记忆自动注入（autoInjectConvention）：开启后，每个新会话默认常驻所有启用中的规约记忆（
tags 含 convention）与最近 8 条会话总结记忆（tags 含 会话总结）；旧会话不自动注入，可在「记忆库」页手动加入。
- 会话总结（session.summarize）：把所选会话的对话轮次交给 LLM 提炼为「会话id / 轮次 / 用户请求 / 思考链 / 处理链 / 结果」六要素记忆；支持「最近 N 轮」范围与「智能合并」（LLM 判断哪些连续轮次处理同一事务并合并为一条）。生成即自动入库，并默认参与新会话自动注入。
- 印象（impressions）：每记忆可带少量简短标签，作为检索主键与图谱节点；支持 LLM 生成印象建议。
- 组合（composedOf）与双向链接（backlink）：可把多条记忆非破坏性聚合成一条组合记忆；
links 自动建立反向引用索引。
- 上下文计划注入（agent/pre-step 消息注入）：按会话维护一份注入计划（固定消息 + 勾选记忆），记忆模式开启后每次发送自动注入到模型请求（
form: 'snapshot' 的 plugin 消息，UI 折叠显示、模型可见），带单条 / 总量 / 固定消息三级字符上限与紧凑视图；对极简模式（persona complete: true）等任何会话形态都生效。
- 6 个 Agent 记忆工具：
memory_search / memory_recall / memory_save / memory_set_enabled / session_inject / memory_pin，可整体开关，模型可直接读写记忆库、按需管理会话注入计划。
- 完整对话侧栏面板：三个标签页 —— 计划 / 记忆库 / 消息；从浏览器输入栏的「记忆」按钮、消息动作条或面板直接操作。
- 力导向图谱（左侧浮层）：独立于右侧面板的左侧浮层面板，含语义分层全景与焦点探索双视图（
mg-* 组件）；按标签着色（规约 / 会话总结 / 复盘 / 其他），支持搜索定位、聚焦邻域、缩放 / 平移与详情 / 相关记忆跳转。
- 消息跳转（JumpReceiver）：在消息页 / 记忆详情可一键在对话中定位到来源消息——
conversation.session.header.actions 插槽内的隐藏接收器按 anchorSeq 匹配并滚动高亮，跨会话自动切换。
- 跨工作区会话列表（sessions.list）：可在面板消息页 / 会话总结中浏览并选择全部工作区的会话（含归档标记）。
- 跨会话共享：宿主级插件，记忆库数据跨会话共享，不受进程重启影响（存于磁盘）。
- 设置页自由开关：宿主启用后可在 DSH 设置页独立控制启用、注入模式、注入视图、新会话自动注入规约/会话总结、Agent 工具开关、记忆库路径与字符上限。
- 非破坏性轮次排除 / 恢复：可把某轮对话排除出注入（不删除），随时恢复参与。
架构一句话
插件是宿主级（Host）插件：lib/ 按职责分模块（index 装配 / memory 记忆库 / plan 计划 / sessions 会话 / llm 摘要 / tools 工具 / api 接口 / util 工具），只依赖 DSH 核心扩展点（settings.register / tools.register / agent/pre-step、agent/created / webServer），记忆库、注入计划、轮次排除、会话总结与图谱数据全部自实现，不依赖任何官方插件包。客户端 lib/client.js 为标准 window.__ModuleLoader__.load({ id, factory }) 浏览器 bundle，经 dsh.client 声明由 DSH 客户端模块系统自动发现；两端通过 /_dsh/memory-manager/api（JSON 信封 {op, sessionId, args}）通信，存在 ctx.connection 时同时注册 /api/memory-manager/<op> 标准通道。
兼容性（跨版本适配策略）
0.4.0 面向 DSH 0.1.2-rc.1+（按实际源码验证），并对官方升级做了隔离设计：
| 集成面 | 策略 |
|---|
设置 / 工具 / 注入 / webServer | 只用核心服务与事件，ctx.get 可选探测，缺失即降级（如工具不注册、注入不激活），不阻断启动 |
| 会话读取 | 优先 live ctx.sessions，回退 ctx.sessionQuery.readSurface；不再依赖 foldSurface 等内部 API |
| LLM | 直接调 ctx.llm.stream + ctx.agentDefaultModel.currentSelection() —— 会话总结 / 印象建议自包含 |
| 记忆库 / 计划 / 排除 | node:fs 纯文件层（.dsh-memory），与 DSH 存储完全隔离 |
| 客户端 | 只用新版本仍在的插槽（conversation.input.left / session.header.actions / shell.overlay / settings.section / chat.assistant-actions）与标准 props（sessionId / useSession / useSessions） |
| 工具定义 | 优先 defineTool，@deepseek-ai/dsh-tools 不可用时回退内置等价实现（形状一致） |
目标：官方 DSH 升级到下一个小版本时，插件最坏情况是「个别能力降级」，而不是「页面无法启动 / 插件加载失败」。
安装与挂载
请参阅 docs/INSTALL.md —— 简要而言，在 DSH 所在环境执行 dsh plugin --profile <profile名> add file:<本仓库路径> 即可（Windows 示例：file:D:/dshTools/dsh-memory-manager；WSL 示例：file:/mnt/d/dshTools/dsh-memory-manager；开发迭代推荐 link:<路径>，改动即生效）。插件通过包内 cordis.patch.yml 以 insert 方式挂载进 profile 层栈，重启 DSH 即可。
快速开始
- 按 docs/INSTALL.md 完成安装并重启 DSH。
- 在浏览器打开对话，输入栏左侧出现「记忆 · 已关闭」按钮；DSH 设置页出现「记忆管理」区块。
- 点击「记忆 · 已关闭」按钮打开侧栏面板；如记忆库为空，可先用示例库或「消息」页把某条消息保存为记忆。
- 在「记忆库」页把记忆「加入计划」，或在「计划」页打开「临时记忆模式」（或将某条消息「固定」）。
- 若记忆库中存在规约记忆或会话总结记忆，新会话会自动常驻注入；下一次发送消息时，模型请求即携带「=== 记忆库上下文 ===」注入内容（UI 折叠显示，模型可见）。
- 点面板头部的「图谱」按钮可打开左侧力导向图谱浮层；消息页 / 记忆详情可一键跳转到对话中的来源消息。
提示：也可直接用 examples/memory-library/ 作为记忆库路径，快速体验图谱与检索。
使用规约记忆（委派-验证-复盘闭环规约）
仓库根目录 CONVENTIONS.md 是一份可直接使用的规约详情文件（委派-验证-复盘闭环规约 v4：打包 → 委派 → 验证 → 复盘 → 并入 的五阶段闭环）。把它作为规约记忆接入插件后，DSH 会在每个新会话中自动注入规约内容，让主 agent 按规约处理问题。
接入流程
- 添加规约记忆：在「记忆库」页保存一条规约记忆——
- 标题：
委派-验证-复盘闭环规约 (v4)（示例）
- 快照：规约要点（可参考 CONVENTIONS.md 的「目的 / 五阶段流程 / 边界规则」章节）
- 标签：
tags 填入 convention（规约记忆标记；也可以直接对 agent 说"把 CONVENTIONS.md 保存为规约记忆"，由模型用 memory_save 完成）
- 保持「启用注入」开启（默认开启）
- 加入计划：在「记忆库」页点该记忆的「加入计划」；或直接说"把规约加入会话计划"（
session_inject）。
- 新会话：无需手动操作——
autoInjectConvention 开启时，所有启用中的规约记忆自动常驻每个新会话。
- 旧会话：手动「加入计划」一次，之后该会话每轮自动注入。
- 生效：开启「临时记忆模式」（计划页开关）后，你每次发送消息，模型请求都会携带规约内容（UI 折叠显示、模型可见），主 agent 即按「打包 → 委派 → 验证 → 复盘 → 并入」流程处理问题。
配套机制
- 自动注入：
tags 含 convention 且启用中的记忆 → 每个新会话自动常驻（设置页「新会话自动注入规约/会话总结记忆」可整体关闭）。
- 记忆即经验库：每次复盘由 agent
memory_save 入库（impressions 含 复盘 与领域关键词），打包前 memory_search 检索历史经验——规约闭环中的「检索先行」要求记忆库持续沉淀、不断成长。
- 备用：记忆库未开启时，直接读取仓库根目录
CONVENTIONS.md 执行即可。
配置项（settings 命名空间 memory-manager）
| 字段 | 类型 | 默认值 | 含义 |
|---|
enabled | boolean | true | 总开关。关闭后不注入、Agent 工具拒绝执行、API 仅返回状态（供设置页重新开启） |
mode | 'on' | 'off' | 'off' | 临时记忆模式。on = 每次发送自动注入固定消息与勾选记忆；off = 不自动注入，可用 plan.injectOnce 做单次注入 |
view | 'full' | 'compact' | 'full' | 记忆注入视图。full = 注入完整快照；compact = 仅标题 + 印象 + 预览（模型可 memory_recall 读全文） |
modelTools | boolean | true | 是否向 Agent 注册 6 个记忆工具 |
libraryPath | string | '' | 记忆库文件夹绝对路径；为空时自动锚定到默认记忆库（工作区下的 .dsh-memory） |
memoryChars | number | 6000 | 单条记忆注入字符上限 |
totalChars | number | 12000 | 单次计划注入的总字符上限 |
pinChars | number | 6000 | 固定消息合计字符上限 |
autoInjectConvention | boolean | true | 新会话自动注入开关。开启后新会话默认常驻启用中的规约记忆（tags 含 convention）与最近 8 条会话总结记忆（tags 含 会话总结）；旧会话不自动注入，可手动加入 |
Agent 工具
| 工具 | 参数 | 行为 |
|---|
memory_search | query: string（必填） | 按关键词匹配记忆标题、印象与正文，返回 id / 标题 / 印象 / 预览（最多 20 条） |
memory_recall | id: string（必填） | 读取一条记忆的完整快照与标注，及其链接、组合来源、被引用关系 |
memory_save | title / impressions（数组，必填）/ snapshot（必填）/ notes（必填）/ tags（数组）/ enabled | 保存一条新记忆到记忆库，返回记忆元数据；tags 填 convention 即规约记忆、填 会话总结 即会话总结记忆（两者新会话默认自动注入）；enabled 默认 true |
memory_set_enabled | id（必填）/ enabled（必填） | 启用或禁用一条记忆。禁用后不参与新会话自动注入、不能加入注入计划（已在计划中的也不再注入），直到重新启用 |
session_inject | id（必填）/ inject（必填） | 把一条记忆加入或移出当前会话的注入计划；记忆模式开启时每轮自动注入 |
memory_pin | content: string（必填）、label: string（必填，可为空） | 把一段文本固定为当前会话的临时记忆（记忆模式开启时每次发送自动注入） |
行为受 modelTools 与 enabled 双重门控；memory_pin / session_inject 需要能确定当前会话。
记忆文件格式示例
记忆存放在记忆库的 memories/<id>.md，<id> 为 3–64 位字母 / 数字 / _ / -：
---
id: "m_example_planning"
title: "示例：季度产品规划"
impressions: ["产品规划", "路线图", "示例"]
tags: []
composedOf: []
links: []
sourceSession: null
sourceSeqs: []
createdAt: 1750000000000
updatedAt: 1750000000000
revision: 1
enabled: true
---
## 快照
此处为不可变的记忆正文快照。
<!-- mem:notes -->
此为可编辑的标注层，随时可补充说明。
完整字段说明见 docs/ARCHITECTURE.md#记忆文件格式。
示例记忆库
examples/memory-library/ 是一个开箱即用的示例记忆库：
memories/m_example_planning.md —— 基础记忆，演示 front-matter 与标注层memories/m_example_meeting.md —— 演示 links 关联与自动反向链接memories/m_example_composite.md —— 演示 composedOf 非破坏组合pinned/example-session.json —— 演示某会话的注入计划文件（固定消息 + 勾选记忆）config.json —— 兼容旧版的迁移配置形态
把 libraryPath 指向该目录即可体验图谱与检索。
开发与测试
参见 docs/DEVELOPMENT.md。要点：lib/client.js 是浏览器 bundle 构建产物格式（factory 内为 CJS），修改后需保持 window.__ModuleLoader__.load({ id, factory }) 包裹格式；回归测试有两套 —— tests/test-apply.mjs（Host apply 回归）与 tests/smoke-client.mjs（mock 浏览器 + SSR 渲染各组件 + 按钮断言）。
许可证
MIT
English Summary
dsh-memory-manager is a host-level plugin for the DeepSeek Harness that gives agents a durable, cross-session memory. Memories are plain Markdown files with front-matter metadata (Obsidian-compatible), each composed of an immutable snapshot plus an editable annotations layer. Memories carry short "impression" tags plus a classification tags field and a per-memory enabled switch; a memory tagged convention is a convention memory, and one tagged 会话总结 is a session summary. With autoInjectConvention on, every new session automatically receives all enabled convention memories plus the latest 8 session-summary memories. A per-session context plan — pinned messages plus checked memories — is injected into the model's system prompt on each send, with per-memory and total character caps and a compact view. Six model tools (memory_search, memory_recall, memory_save, memory_set_enabled, session_inject, memory_pin) give the agent direct read / write / plan control. The browser side provides a right-side panel (plan / library / messages tabs), a separate left-side force-directed knowledge graph overlay with semantic-panorama and focus-exploration views, a session-summarize dialog (session.summarize), cross-workspace session listing (sessions.list), and message jump-to-conversation, plus settings switches. The Host half exposes an HTTP JSON-RPC-style endpoint (/_dsh/memory-manager/api) that the browser Client calls. It is MIT-licensed and published to open source.
