dsh-memory

dsh-memory

dsh-memory — Advanced auto-memory plugin for DSH (DeepSeek Harness): layered memory (episodic / semantic / profile), knowledge graph, worldline versioning, vector + RAG retrieval, and incremental graph building. Local SQLite, MIT-licensed. (Body of this README is in Chinese.)

DSH（DeepSeek Harness）进阶自动记忆插件——用户每条消息都触发一次检索注入（v0.16.0，可按需关掉），agent 自主工作的其余步骤按节奏补充相关记忆，并在每个轮次结束时自动沉淀新记忆。

核心诉求：记忆不只是"清单"，而是会生长的知识网络：分层 + 图谱 + 世界线（时间维度）+ 向量语义检索。

✨ 功能总览

🛠 工具面（暴露给模型）

memory_add               主动记录（决策/结论/偏好/教训）
memory_search            检索（语义 + 关键词混合）
memory_forget            删除指定记忆
memory_merge             合并两条相似记忆
memory_purge             清空作用域/全部
memory_list              浏览（可按 scope/layer/type 过滤）
memory_pin               钉选/取消钉选常驻记忆（不看相关性、恒定/会话级注入）
memory_stats             统计（含向量/图谱状态）
memory_reembed           维度迁移或嵌入失败后补写缺失向量
memory_graph_neighbors   记忆图谱邻域（记忆级 k-hop：相邻记忆 id+边类型+跳数）
memory_graph_communities 社区检测/查看
memory_graph_path        记忆最短路径（记忆 id 序列+边类型链）
memory_graph_link        手动连边（8 型语义关系）
memory_graph_unlink      断边（历史保留）
memory_graph_node        节点详情 + 邻域
memory_versions          世界线版本链（回滚前查看）
memory_rollback          回滚到历史版本（时间旅行）
memory_housekeeping      管家巡检与治理（dryRun=false 执行：合并近乎重复 + 归档陈旧情景快照；consolidate=true 再做 LLM 归并）
memory_archive           归档管理（查看被归档的记忆 / 一键恢复；归档不删除）
memory_reprocess         降级记忆重写（v0.12.6 起；v0.14.0 由 memory_rewrite 改名以避免与内核工具撞名：把提取瘫痪期的「任务/结果」产物交回修好的提取器重新处理成正常记忆；默认预演、可分批续跑）
memory_theme_relabel     存量主题治理（簇级 LLM 重命名；dryRun 只报告 / recluster 先全量重聚类）
memory_events            列出记忆事件（时间+因果聚簇；detect=true 强制重检测）
memory_profile_distill   画像蒸馏（偏好/决策聚合为用户画像；需 refiner 启用）
memory_logs               查看运行日志（写入/注入/检索/巡检/蒸馏/错误全透明）
memory_batch_status       批量提取状态（候选池攒了多少、哪些桶快够门槛、最近归纳了什么）
system_now               获取当前系统时间（本地 + ISO + Unix + 星期 + 时区）

🏗 架构

DSH 运行时 ──pre-step──▶ 注入侧 ──查询──▶ 检索器 ──┬─▶ FTS5（BM25）
   ▲                                              ├─▶ sqlite-vec（KNN）
   └──decision.messages── 注入侧 ◀──RRF 结果── 检索器 ─┴─▶ 记忆图谱（邻域/社区）
DSH 运行时 ──session/event──▶ 写入侧 ──沉淀/去重──▶ MemoryStore ──SQL──▶ SQLite
                                └──轮次文本──▶ Refiner ──蒸馏──▶ LLM 服务

📄 交互式架构图：docs/architecture.html（浏览器打开，或 DSH 右侧预览面板直接渲染）

📚 架构文档（v0.20.0，按主题分 11 章）：docs/ARCHITECTURE.md（总入口）→ docs/architecture/（模块构造 / 数据模型 / 写入 / 检索 / 注入 / 图谱 / 遗忘与管家 / 配置与双内核 / 集成与工具面 / 工程约定 / 已知限制）· 开发历程：docs/CHANGELOG.md · 原始设计方案（1406 行）：docs/memory-plugin-proposal.md · 路线图：docs/ROADMAP.md

模块结构（v0.20.0）

lib/index.js           装配壳：settings/init/Web API/管线/工具/ctx.memory（253 行）
lib/config.js          配置 schema + 默认值
lib/util.js            纯函数：scopeOf / formatNow / 注入渲染 / 消息提取 / 凭据读取
lib/store.js           存储层（sqlite + 检索 + 图谱 + 世界线 + 事件 + 日志）
lib/embedder.js        Embedder/Reranker seam（降级链）
lib/refiner.js         LLM 蒸馏提取
lib/graph-snapshot.js  记忆级图谱快照投影
lib/pipelines/        write（沉淀）/ inject（注入）/ preheat（预热）——工厂化，依赖显式注入
lib/tools/            工具注册（time / memory / housekeeping / graph 分域 + shared + index）
client/index.jsx       客户端插槽装配壳
client/settings.jsx    GUI 设置面板
client/graph.jsx       GUI 记忆图谱（力导向画布）
client/graph-geometry.js 主题区域几何（贴合凸包/最小外接圆/就地聚簇/密度核心；纯函数，与守护测试共用）
client/layout-cache.js  布局落盘（收敛坐标存 localStorage，按 id 复用；打开即全局平衡）
client/layout-policy.js 布局计划（质量档位/时间预算/步数上限/自动降档；纯函数，与守护测试共用）
client/logs.jsx        GUI 记忆日志面板

🏔 里程碑（compaction-smart，502 行六维度压缩方案）：docs/compaction-smart-proposal.md

📦 安装

# 方式一（推荐，0.2.0-rc.2 与 0.1.x 都适用）：官方插件命令
# 本包声明了 dsh.bundle.patch（见 package.json），安装时自动把本包追加进 profile 的
# dsh.profile.bundles —— 不需要手改 profile 的任何文件。
dsh plugin --profile web add ./dsh-memory

# 方式二：手工挂载（老内核/老流程；0.2.x 上也能用，但**绝不能与方式一同时存在**）
# 1) 复制本目录到 <profile>/node_modules/dsh-memory/
# 2) 在 profile 的 cordis.patch.yml 里加一条 insert（见下）

⚠️ 先读：npm 上的名字与仓库对不上 dsh-memory = 0.1.0（旧物）、dsh-advanced-memory = 0.9.17（落后仓库四个 minor），本仓库这份 0.19.0 从未发布。 想装本仓库的版本，只能用本地路径（上面的 add ./dsh-memory）或先自己 npm publish。 另外：方式一用的 entry id 是 memory（随包 patch 里写死的），方式二手工行历史上用的是 dsh-memory——客户端两个 id 都认，所以换挂载方式时设置面板不会掉，但两条挂载行同时存在会让 loader 报 duplicate，切换前请先删旧行。

cordis.patch.yml 条目示例（仓库根的随包 patch 只有 disabled 守卫 + 这一条；手工挂载照抄 insert 部分即可）：

- insert:
    - id: memory
      name: dsh-memory
      config:
        enabled: true
        features:
          autoWrite: true
          valueGate: true
          dedupMerge: true
          preStepInject: true
          manageTools: true
          time: true
          graph: true

ℹ️ 设置面板可见性（两代内核的机制不一样，v0.14.0 起两条都走通）

设置面板出不出内容，取决于内核那一代怎么"注册"设置：

这就是 lib/config.js 里 Config = volatileTable(z.object(...)) 和 lib/compat.js 存在的原因——同一个包在两条内核线上都要能显示、能改。仍然：0.2.0-rc.2 上没有 volatile 标记的 entry 在设置页里根本不出现（不是显示成灰）。

🔁 开发期部署（改完仓库 ≠ 线上生效）

三种形态，先认清楚跑的是哪一份再动手：

• 方式一（dsh plugin add）：包作为 pnpm 依赖装在 profile 里，改仓库不会影响线上，要重新 add（或让 pnpm 走本地链接）。
• 方式二（Junction / 符号链接）：profile 的 node_modules/dsh-memory 指向仓库，改仓库即改线上代码——只需重启该实例（客户端改动再刷新页面）。查法：Get-Item "<profile>\node_modules\dsh-memory" | Select LinkType,Target。2026-10-06 实测本机 web-2 就是这种（Junction → 开发目录），所以那次改动根本不需要同步副本。
• 方式三（手工副本）：包是 profile node_modules 里的真实目录，改完仓库必须同步进去——用仓库自带脚本（它只认默认 ~/.dsh 下的那份副本）：

node tools/deploy.mjs                     # 同步 lib/ 与 package.json 并复验 md5
node tools/deploy.mjs --check             # 只比对（有漂移退出码 1，可用于收尾自检）
node tools/deploy.mjs --profile <name>    # 换 profile（默认 web-desktop）

⚠️ deploy.mjs 的目标写死为 ~/.dsh/profiles/<profile>/node_modules/dsh-memory。DSH_HOME 不在默认位置时，它认不出真正在跑的那个实例：2026-10-06 实测 DSH_HOME 指向别处的 web-2 走 Junction，而脚本默认指向默认家目录下一份停在 0.13.3 的旧副本。先按端口查进程命令行（Get-NetTCPConnection -LocalPort <port> | Select OwningProcess → Get-CimInstance Win32_Process）确认 DSH_HOME 与 profile，再决定要不要同步。

2026-09-17 抓到一次真实漂移：仓库已含 v0.9.31 的降级保护（degraded 禁破坏性维度迁移 + 30s 超时），部署副本还停在 9/8 的旧版——于是向量表被 rule 兜底迁移成 256 维，向量路实际已瘫，日志里只有一行 warning。改 lib/ 后先 --check 再收工。重启 DSH 才生效（客户端 lib/client.js 改动只需刷新页面 + 重建产物 node build-client.mjs）。

⚙️ 配置（settings.yaml 的 memory 段）

memory:
  dbFile: ''                # 留空 = ~/.dsh/memory.db
  scope: ''                 # 留空 = global
  injectMaxTokens: 800      # 每次注入 token 预算
  injectMinScore: 0.02      # 注入最低相关分（RRF 融合量纲，三路全中 ~0.049；0.02 ≈ 至少一路排前 10）
  injectPace: steady        # 注入节奏档位：aggressive 激进=每 4 步 / steady 平稳=每 12 步（默认）/ lazy 懒惰=每 30 步 / custom 自定义
  stepInterval: 12          # 仅 injectPace=custom 时生效（1~60）
  pinnedLimit: 8            # 常驻（钉选）记忆每次注入最多带几条
  pinnedMaxTokens: 600      # 常驻块的独立 token 预算（不与被检索到的记忆抢 injectMaxTokens）
  pinnedInjection: session  # v0.18.0 常驻注入粒度：session 会话级（默认，首轮一次+变化时增量）/ step 每步（旧行为）
  maxRecentPerAgent: 6      # 防循环窗口
  maxVersionsPerMemory: 8   # 世界线长度
  features:
    autoWrite: true         # 自动写入（turn/end 沉淀）
    valueGate: true         # 价值门（噪音过滤）
    dedupMerge: true        # 去重合并
    preStepInject: true     # pre-step 自动注入
    userMessageTrigger: true # v0.16.0 每条用户消息都重新检索一次（不看步距）；关掉则回到纯步距节奏
    writeGate: true         # v0.16.0 轮次结束先预筛"这段对话值得记吗"（只有高把握说不值得才省 LLM）
    manageTools: true       # 管理工具集
    time: true              # 时间维度（版本化世界线）
    graph: true             # 图谱构建
  decision:                 # v0.16.0 写入侧决策门（本机 StartLux-Decision 的接入参数；检索路径不用它）
    endpoint: http://127.0.0.1:8090/v1/systemone
    timeoutMs: 2000         # 单次判断超时（200~10000）；到点即放弃、照常提取
    writeMinConfidence: 0.9 # 采信门槛（0.5~0.99）：只有把握度不低于它才采信"不值得记"
  refiner:
    enabled: false          # LLM 蒸馏提取（默认关，省成本）
    provider: deepseek-official  # 供应商（GUI 下拉预设）
    model: deepseek-v4-flash
    apiKeyEnv: MEMORY_REFINER_API_KEY  # 独立密钥槽（供应商未声明 apiKeyEnv 时生效）
    reasoningEffort: off    # v0.16.0 默认不思考。⚠️ 这里的 off 由插件翻译成「不带该参数」——
                            # pi-ai 的 deepseek 格式下，只要该字段存在（哪怕是 'off'）就会发出
                            # thinking:{type:'enabled'}；不带它才会按模型的 off 映射发 disabled。
                            # 还要求 provider 侧给该模型声明非 null 的 off 映射（本机已声明，
                            # 见 README §开发期部署 同级的 profile 配置）。改回思考就填 low/high/max
    maxTokens: 0            # v0.12.0：0 = 不限制（不传该参数）。约束交给下面的时间预算
    timeBudgetMs: 120000    # v0.12.0：单次调用时间预算（2 分钟）；到点掐断并带已写内容续跑
    maxContinuations: 3     # v0.12.0：续跑轮数上限（续跑写不出东西会自动停）
  embedding:
    provider: remote        # rule（离线哈希兜底）| remote（OpenAI 兼容 API）| onnx（预留）
    model: Qwen/Qwen3-VL-Embedding-8B  # 4096 维（硅基流动实测）
    baseUrl: https://api.siliconflow.cn/v1
    apiKeyEnv: MEMORY_EMBEDDING_API_KEY
    cacheSize: 1024
  reranker:
    enabled: false          # RRF 融合后精排（需配置密钥；失败降级 RRF 顺序）
    provider: remote
    model: Qwen/Qwen3-VL-Reranker-8B
    baseUrl: ''             # 留空 = 跟随嵌入端点
    apiKeyEnv: MEMORY_RERANK_API_KEY
    topK: 20                # 精排候选数
    minCandidates: 3        # 候选不足不重排
    rrfWeight: 0.7          # final = w×RRF + (1-w)×重排分
  graphView:
    spring: 0.13            # 图谱力导向：弹簧强度
    field: 1                # 邻域场强度倍率
    spacing: 1.2            # 平衡间距（×k）：比它近互相排斥、比它远互相吸引
    attract: 0.06           # 远场引力峰值（必须小：引力是累加的、斥力是封顶的）
    maxSpeed: 4             # 单帧速度上限（"拖动乱飞"的物理护栏）
    damping: 0.3            # 速度阻尼
    range: 4.5              # 邻域半径（×k）：每个节点自己的影响范围
    wobble: 0.04            # 常活微动幅度（收敛后仍缓慢游走）
  housekeeping:
    enabled: true           # 管家自动巡检
    interval: 20            # 每沉淀 N 条记忆巡检一次
    maxIntervalHours: 24    # 时间兜底（距上次巡检超 N 小时）
    dedupThreshold: 0.92    # 近重复相似度阈值
    agingDays: 30           # 老化报告天数
    autoApply: true         # v0.12.1：真治理（false = 只报告不动手）
    autoMergeThreshold: 0.95 # 近乎重复的自动合并阈值（0.92~此值留给 LLM 归并）
    archiveEpAfterDays: 45  # 情景快照闲置多少天后归档（0 = 不归档）
  events:
    enabled: true           # 事件分类（时间+因果聚簇，管家自动检测）
    gapHours: 2             # 时间线扫描间隔阈值（相邻记忆间隔 < 2h 且同主题/共享实体 → 同一事件）
  sessionSummary:
    enabled: true           # v0.12.2 会话级汇总（"整段会话最后落在哪里"）
    rounds: 12              # 累积多少轮后汇总一次
  logging:
    enabled: true           # 运行日志（背后做了什么全透明）
    maxRows: 2000           # 日志保留条数（惰性裁剪）

密钥自动跟随：选中供应商后，GUI 密钥输入的目标引用自动切换为该供应商声明的 apiKeyEnv；密钥本体写入 ~/.dsh/.credentials.yaml（私有文件），不进设置文档、不进记忆库、界面不回显。

🩺 连通性自检（v0.11.1）

设置面板顶部的「连通性自检」按钮打 GET /dsh-memory/health?llm=1，对嵌入 / 重排 / 提取各发一次真实最小请求，并同时报出配置值、凭据存在性、以及向量路的实况（谁在算向量、几维、多少条、是否降级）。

为什么要它：「● 已配置」只证明凭据文件里有这个键，不证明它能用。本机真实事故——硅基流动余额 402 → 嵌入静默降级到 rule 哈希、重排每次白等，界面上却一切正常；memory_stats 也只回一个 vector: true。现在 stats() 一并返回 vecDim / vecRows / embedder / degraded：embedder: "rule" 就是那句一直没被说出口的实话。

切换嵌入模型会在重启后触发向量库重建：维度变了就清空向量表并全量重嵌入（期间语义检索暂弱，FTS/关键词照常）；远程嵌入初始化失败则进入降级态暂停向量路（v0.9.31 保护，不破坏现有向量）。

🧪 测试

node tools/run-tests.mjs            # 全量：发现 tests/ 下全部套件，逐条汇总
node tools/run-tests.mjs --offline  # 离线：跳过需要 @deepseek-ai 私有 peer 包的套件

28 套 / 约 980 项断言。按域分：

注：test.mjs、test-inject-pipeline、test-profile、test-tool-add、test-crash-safety、test-governance、test-rewrite 依赖 @deepseek-ai 私有 peer 包，在部署副本或 harness 环境运行；CI 只跑离线白名单。

📄 License

MIT