dsh-memory

本插件属于 @max-null/* 插件系列——这一系列共同构成 SSID（思灵 · Seek Soul in Darkness） 桌面体验。SSID 是整合它们的盒：dsh-capture · dsh-chat-rail · dsh-chinese-thinking · dsh-draft-polish · dsh-guardian · dsh-habit · dsh-memory · dsh-node-appearance · dsh-plugin-center · dsh-quick-toolbar · dsh-skill-mcp-center · dsh-ssid-panels · dsh-ssid-zh-ui · dsh-achievements。

This plugin belongs to the @max-null/* family — a set of plugins that together form the SSID (思灵 · Seek Soul in Darkness) desktop experience.

一个面向 DeepSeek Harness 的跨会话明文记忆插件。遵循「一切皆插件」——它不修改 DSH 源码，声明 name/inject/apply，由 Loader 从 cordis.yml 加载。

设计原则

1. 写入即生效，人是例外干预者：模型写入的记忆直接生效（approved），不再逐条等人放行；人保留随时查看、改写、删除、钉住或回滚的能力——人不在场不等于失控。
2. 可观测先于精准：每条记忆是明文，memory_list 随时可见、memory_forget 随时删除——不存在"静默暗礁"。
3. 明文是人机共享的审计窗口：记忆是可读文本，模型可自检其是否过期（有效性锚点会在所绑环境值变化后标记 stale），人可随时查看与改写。
4. 确定性且缓存安全：BM25 关键词检索是存储的纯函数、无 LLM 调用；固定指引进 system-prompt section，approved + injected 记忆进 recall context（global 全量 + 当前会话工作区），逐条为单行摘要并按注入预算截断（超预算按最近使用优先，省略数在面板可见）。

截图

装完后在设置里多出「记忆」一项，可查看与管理跨会话记忆：

入口： 设置 → 记忆

设置入口与面板

用法

npm install @max-null/dsh-memory

在你的 cordis.yml 加一条（其余 storage / system-prompt / tools 由宿主已有；记忆的存储后端由插件自己注册）：

- id: memory
  name: '@max-null/dsh-memory'

提供的服务与工具

• 服务 ctx.memory：remember / list / search / forget / setStatus
• 工具：memory_save、memory_list、memory_search、memory_confirm、memory_forget、memory_update
• 注入：tool:memory 指引 section + memory:recall 召回 context（global 的 approved + injected + 当前会话工作区的 approved + injected，带 [memory:<id>:<namespace>] 来源标记；摘要化 + 预算截断）
• 检索：BM25（CJK 单字 + 2-gram，content 与 keywords 字段分离加权；中文多字查询精度显著优于单字切分）；可选语义融合（见「可选配置」）

两层存储（global / project）

记忆按 namespace 分两层物理存储，各落在独立的明文 JSON：

两个根都可用 config 覆盖（globalRoot / projectRoot）。memory_list / memory_search 不带 namespace 过滤时会同时查两层。旧版双重前缀文件名（memory_project_memory_project_<hash>.json）在打开时自动迁移为规范名。

使用流程（写入即生效，人为例外干预）

提示词模板库（0.6.0）：prompt_search / prompt_get / prompt_list / prompt_add 四个工具管理模板库—— md 文件是唯一事实源（~/.dsh/prompt-library/*.md 为 global；<workspace>/.dsh/prompt-library/ 随工作区分享）， 前端（记忆面板「模板」tab / 模型工具）检索同一份索引；模板存在即生效（source: agent 角标标识模型新增）， 永不注入 system prompt。

模型 memory_save     →  status: approved，立即生效；命中密钥/凭据规则则隔离（不进检索也不进注入）
memory_search        →  关键词/语义召回（只搜记忆；模板走 prompt_search 通道，不会混进候选池）
命中累计 2 次         →  injected: true（自动打开常驻：global + 当前会话工作区，摘要化 + 预算截断）
30 天未再命中         →  自动撤下常驻（只撤自动开的；人工动过的开关双向豁免）
人（面板 / 开关）     →  钉住 / 删除 / 放行隔离记录 / 回滚
memory_forget        →  随时删除（删除始终是人的动作）

两条自动规则撑起淘汰机制：反复被检索命中是它值得每轮付费的证据，长期不再被命中则自动退出常驻。两者都不删除任何内容——记忆不会无限累积，也不会被系统自行清空。

记忆还可声明有效性锚点（环境变量 / 工具清单 / 插件版本）：所绑的值变化后，这条记忆被标记 stale 并撤下常驻，检索结果里也带出失效提示——环境变了，旧结论就不再被当成仍然正确。

模型写入不需要人点头，但人始终能看见并推翻：面板按「隔离区 / 常驻 / 冷数据」分组，被隔离的记录必须由人放行才会重新进入检索。

为什么明文 + BM25，而不是向量检索

向量检索的记忆本体是一串不可读的数字，过期信息会成为无法观测、无法修复的静默暗礁；BM25 + 明文让每一次召回都可解释、每一条记忆都可见可删。语义（向量）检索作为可插拔的可选项（0.5.2，见「可选配置」）——记忆本体仍是明文，向量仅作为检索辅助字段（vector，明文可读），且以"可观测 + 可修复"为门槛。

明文还有一层跟随仓库分享的好处：project 命名空间的记忆落在项目文件夹内（<cwd>/.dsh/storages/memory_project_<hash>.json），随 git 提交、分享给所有协作者；global 命名空间的记忆留在本地 $DSH_HOME。团队的共识（"本项目统一用 Vue3 <script setup>"）能沉淀进仓库，而不是散落在每个人的本地。FTS5 的 SQLite 二进制无法这样"跟着仓库走"。

可选配置

在 cordis.yml 的 config 里传给插件（均可省略）：

- id: memory
  name: '@max-null/dsh-memory'
  config:
    injectionBudget: 1500        # 常驻注入预算（字符；null = 不限制）
    summaryChars: 80             # 单条注入摘要截断上限（字符）
    semanticTopK: 5              # 语义侧参与融合的 topK（仅配置 embeddings 时生效）
    # 混合语义检索（可插拔；缺省 = 纯 BM25）
    # embeddings: { embed: '...' 提供 embed(texts) 的宿主函数 或 插件名 ... }

embeddings 接受 { embed(texts): Promise<number[][]>, similarity? } 对象——由宿主装配层提供嵌入实现（如 DeepSeek 嵌入端点）；配置后 memory_search 以 BM25 + 语义 RRF 融合，向量增量生成并持久化，嵌入调用失败自动降级为纯 BM25。

SSID 系列

开发

npm install
npm run typecheck   # tsc 严格类型检查
npm test            # vitest 单测
npm run build       # 产出 dist/
node scripts/verify-loader.mjs   # 用 Loader 端到端验证插件可加载

依赖（peerDependencies，由宿主提供）

@deepseek-ai/cordis、@deepseek-ai/dsh-storage、@deepseek-ai/dsh-storage-domain、@deepseek-ai/dsh-storage-json、@deepseek-ai/dsh-system-prompt、@deepseek-ai/dsh-tools