记忆树桥接 gangwolf2312-creator/dsh-memory-bridge

dsh-memory-bridge

为 DeepSeek Harness 提供长期记忆的桥接插件：对话自动沉淀为可检索、可审计、可治理的记忆树，并在后续对话中按需注入上下文。它最初是一个可进化的私人记忆系统——面向个人使用而设计，现在开源出来给有兴趣的人自取。

- 存储：明文 Markdown 真源 + SQLite 索引（可读、可修、可迁移）
- 检索：BM25 + 多路 RRF 相关度排序召回（零 LLM、零外部服务）
- 治理：遗忘曲线、审计闭环、全局收缩——记忆会老化但可解释
- UI：设置页内 7 个可视化 tab（总览 / 事件图谱 / 知识图谱 / 时间线 / 待审 / 画像 / 审计）

项目定位

核心适用场景：上下文窗口受限的记忆系统。

DeepSeek 云端模型（V4）提供 100 万 token 的上下文窗口（公开资料），在这个前提下，DSH 自带的机制（resume 恢复整个会话 + compaction 压缩超长上下文）足以维持记忆——"把历史都塞进窗口"是可行的。

但一旦接入本地模型（Ollama 等），情况完全不同：上下文窗口通常是 4K-32K，且需显式配置、性能随长度显著下降（Ollama 文档）——窗口缩小几十倍，"把历史都塞进去"不再可行。这时候记忆必须结构化、可检索、按需注入，而不是依赖长上下文硬扛。

本插件解决的正是这个实用场景：

当上下文窗口受限（本地模型 / 小窗口模型）时，如何仍然拥有可用的长期记忆？

方案：把对话中值得留存的（你是谁、做过什么、哪些决定被认可、哪些经验被验证）提取、结构化、存储，在每轮对话中只注入相关的几条（而非全部历史）。即使窗口很小，记忆依然可用。

与 DSH 原生上下文的关系（边界说明）：

| 场景 | DSH 原生行为 | 本插件的角色 |
| 新会话 | 历史为空 | 插件注入是唯一的跨会话记忆来源（核心价值）|
| resume 旧会话 | 全部历史重放进上下文 | 插件注入叠加在历史上（不替代）；两者并行占窗口 |
| 长会话超窗 | compaction 压缩历史为摘要 | 插件注入补充摘要缺失的细节（互补）|

明确的边界：本插件注入的是 system prompt 中的动态上下文（systemPrompt.context），不替代、不抑制 DSH 的会话历史注入（历史由 dsh-session 的 deriveMessages 全量生成，插件无 API 裁剪）。会话内的历史瘦身是 DSH compaction 的职责，本插件负责的是跨会话的持久事实——两者互补，不重叠。

用户群体：

| 群体 | 使用方式 |
| 本地模型用户 | 上下文窗口小（4K-32K），最需要"按需注入"而非"全量塞入"——核心场景 |
| DeepSeek 云端用户 | 1M 窗口下是"锦上添花"：获得结构化检索、治理、可视化，而非靠窗口硬扛 |
| 记忆敏感用户 | 明文存储 + 完整溯源 + 人工审批通道，数据透明可控 |
| 开发者 / 自托管者 | 引擎与桥接分离、零外部服务依赖、可二次开发 |

边界声明：这是一个记忆基础设施，不是"记忆完美的智能体"——提取质量依赖所选 LLM，检索是相关度排序召回（非语义联想，也有多跳扩展），这些取舍在"已知局限"中如实说明。

在 Harness 中：提供什么 · 解决什么 · 价值

提供什么（能力清单，站在使用者视角）

| 能力 | 怎么用 |
| 跨会话持久记忆 | 对话自动沉淀为记忆卡，后续会话按需检索注入——补足 DSH 会话上下文之外的持久事实层 |
| 记忆检索工具 | agent 可用 memory_search / memory_add_run / memory_review 三个工具主动读写记忆 |
| 记忆可视化 | 设置页 7 个 tab：事件图谱、知识图谱、时间线、待审、画像、审计、总览 |
| 经验与画像 | "记住教训/踩坑"立即沉淀永久经验；偏好信号聚合提案；画像蒸馏 + 人工审批 |
| 治理闭环 | 遗忘曲线、利用率收缩、审计反馈——记忆库不无限膨胀 |

解决什么（痛点）

| 痛点 | 本插件的解法 |
| 跨会话记忆缺失：新会话/压缩后不携带旧事实，resume 只能续旧对话 | 自动提取沉淀到持久层，注入相关记忆恢复背景（跨会话的持久事实，非会话内历史）|
| 窗口小存不下全部记忆：本地模型 4K-32K 塞不下全部历史；会话内超长由 DSH compaction 处理，跨会话事实由本插件按需注入（分档限量）| 只注入相关的几条记忆（L2≤3/L1≤1/寒暄 0），避免把全部历史塞进提示词 |
| 历史不可检索/治理：会话日志是流水文本，不可查"我之前说过什么偏好" | 结构化记忆卡 + 相关度排序检索 + 分档注入 + 治理闭环 |
| 记忆不可信：模型"记得"可能是幻觉 | 检索零 LLM 相关度召回；写入带证据标签 + 溯源；低置信走人工审批 |
| 数据黑盒：记忆锁在数据库/向量库里，不可读不可改 | 明文 Markdown 真源，可读可修可迁移 |
| 记忆库膨胀：越积越多，噪音淹没信号 | 遗忘曲线（30 天闲置完结）+ 利用率治理 + 降权淡出 |
| 投入产出不明：装了记忆插件不知道有没有用 | 审计 tab：注入命中率 / 利用率 / 提取成本，闭环可量化 |

价值

- 对对话质量：关键轮次注入相关记忆（偏好、项目背景、既定决策），减少重复说明与前后矛盾——模型基于检索到的记忆回应，而非凭空"记得"。
- 对成本：注入按需限量 + 寒暄零注入 + 提取门卫（寒暄轮跳过 LLM 提取），记忆不成为每轮的 token 负担；KV-cache 友好（常驻基线 digest 未变不重建）。
- 对可靠性：记忆是独立数据层而非模型自律——检索可复现、写入可溯源、治理可审计；即使提取失败，原始对话永远在 runs 表。
- 对掌控感：数据明文在本地，可人工编辑/删除；经验与画像经人工审批才固化；全部决策写 decision_log。

设计理念

一句话：记忆是独立可靠的数据层，不是模型自律的产物。

四条原则：

1. 明文为真源，索引只做加速。每张记忆卡是一个 Markdown 文件，SQLite 只是可重建的检索索引——数据不锁死、可人工编辑、索引坏了不丢数据。
2. 确定性算法检索，读取端零 LLM。读取端（检索）零 LLM：BM25 + 多路 RRF 融合，同一数据状态下结果可复现、可审计。LLM 只参与写入端（从对话提取），不确定性被关在写入管道里。
3. 提取主动写，注入克制读。每轮对话自动提取（LLM + 零 LLM 规则双通道）；注入按对话意图分档（关键 ≤3 条、一般 ≤1 条、寒暄 0 条），记忆是"按需翻阅"不是"无脑塞进上下文"。
4. 遗忘是记忆的一部分。30 天闲置枝完结、低利用卡降权、关键事实豁免——遗忘由规则驱动，可解释、可翻查、可恢复。

记忆树形态：记忆不是平铺列表，而是按时间生长的树——枝 = 事件链（主题演进），叶 = 事件卡（发生了什么）；事件完结生成"果摘要"作为导航路标；版本演化走 supersedes 时序链（旧事实失效但保留审计）；每条卡带溯源（来源文件 / 回合 / 证据标签 / 佐证计数），可回到原始对话。

记忆与知识分离：memory-tree（关于"你"的经历）与 memory-wiki（关于"世界"的规范）是两个独立库，知识条目不进记忆树，避免污染画像与经历。

重大决策

| 决策 | 选择 | 理由（反对方案） |
| 记忆存储 | Markdown 真源 + SQLite 索引 | 纯数据库不可读不可人工核对；纯文件检索慢。双写兼顾透明与速度 |
| 检索算法 | BM25 + RRF（jieba 分词 + FTS5）| 向量库需模型常驻、结果不可复现、依赖外部服务；词级相关度排序 + 多跳扩展对记忆场景足够且可审计 |
| 写入管线 | LLM 提取 + 零 LLM 规则（双通道）| 单一 LLM 提取慢且贵；规则通道让"记住/踩坑/偏好"即时落卡 |
| 读取注入 | 拉式检索 + 常驻基线，分档限量 | 全量注入污染上下文、稀释注意力 |
| 真值裁决 | LLM 只输出"证据标签"，系统算置信、做准入 | 模型自评当事实源会放大幻觉；directive/explicit 自动固化，uncertain 强制人工审 |
| 归链 | 确定性裁决（resolve_chain，别名/相似度/实体消歧）| 直接哈希 LLM 标题会因措辞漂移分裂成"同名假链" |
| 对话保底 | 原始对话先落盘 runs 表，幂等状态机 | 提取失败/禁用都不删原文——记忆管道出错，原始语料永远在 |
| 进程模型 | host JS + Python sidecar（进程隔离）| 引擎生态成熟；sidecar 崩溃只影响记忆，不拖垮 harness |
| Python 依赖 | 声明式（install-deps.ps1），不内嵌、不静默安装 | 静默 pip install = 在用户机器执行任意代码 |
| 密钥 | apiKeyEnv 环境变量优先，明文回退兼容 | 明文 key 不落盘入库；.gitignore 排除 config.json |

关键工程实现

架构

DeepSeek Harness (host 插件进程) ├── lib/index.js 宿主：拉起 sidecar、HTTP 路由、agent 工具、 │ 事件钩子（自动提取 / 零 LLM recorder / 注入 / 审计闭环） ├── python/memory_bridge_server.py sidecar：JSON-RPC over HTTP（127.0.0.1 随机端口）， │ 承载引擎、衰减治理、画像蒸馏 ├── engine/ 记忆树引擎源码（core/ + memory/，依赖声明式安装） └── client/client.js 设置页 UI（7 tab，浏览器直连 host 代理）

存储层：明文真源 + 幂等写

- 卡 = Markdown 文件（front matter 元数据 + 正文），目录按类型分（events/cards、events/chains、lessons/pending、lessons/permanent、profiles）
- 全部写操作幂等（同 id 覆盖 / INSERT OR IGNORE），崩溃重启对账（extracting 回滚为 staged）
- 溯源字段贯穿：source_path（文件）、trace_event_id（回合）、evidence（证据标签）、corroborations（佐证）

写入管线（双通道）

1. LLM 提取（turn/end 自动）：增量扫本轮 user+assistant 文本 → 入 runs 队列 → 门卫 should_extract（零 LLM，寒暄轮标记 skipped 省调用）→ LLM 提取 → 事件卡/经验/知识分流落库 → 归链 → 冲突裁决 → 失败退避。JSON 输出有截断容错（补引号/插逗号/补闭合括号）；截断降级（v0.3 抢救修复）：finish_reason=length 或 JSON 需结构修复 → 本批卡/wiki 强制 evidence=uncertain → 卡进 lesson_pending / wiki 进 pending（待审），残缺内容不自动固化（此前修复器成功会掩盖内容残缺）；单条提取 max_tokens 已由 1024 提至 2048。
2. 零 LLM 规则 recorder（user/message 即时，纯规则不抢 TTFT）：
- "记住教训/踩坑/经验教训" → 立即 lesson_permanent（永久经验）
- "记住/记下/别忘了" → 立即事件卡
- "我喜欢/习惯/别用" → 偏好信号入账 → 聚合 ≥3 同类 → lesson_pending 提案

读取管线（注入 + 审计闭环）

- user/message 预取：意图分档（L2 ≤3 / L1 ≤1 / 寒暄 L0 零注入——寒暄按整句近似匹配判定，含「好/行/嗯」的真实问题不误判；50ms 超时宁缺勿滥）+ 数据驱动相关度门槛（v0.5 起废除人工词表，v0.6 校准：query 核心词经 jieba 词性提取（实词）；事件卡需 Σ idf ≥ 6.0 的多词重叠，或名词/形容词单稀有词（idf ≥ 4.2），或 query 相邻核心词对在卡/链标题中相邻（短语精确命中，救「记忆插件」类高频项目专名）——实测排障问句「问题+解决=5.78」不再误注入无关卡，「数据库迁移」不再因动词「迁移」单词命中 apiKey 卡；事实卡（偏好/经验）≥1 核心词重叠即注入）+ 只读注入检索（v0.5：注入查询不写命中/未命中/归档记账，防无关查询批量归档；UI 检索记账不受影响）+ 事实卡优先（v0.3：lesson/permanent/偏好卡置顶，事件流水补位）+ 常驻基线快照（approved 画像 + 高置信永久经验，相关性闸门：query 不含身份/偏好/经验类语义词时不注入画像经验；digest 变更检测、KV-cache 友好）→ 缓存 → system prompt 渲染时注入带溯源文本
- 审计闭环：turn 结束后判定注入是否被回复利用（规则归因零 LLM）→ 命中滚动 / 连续 ≥3 次未命中降权淡出（「没被利用」 ≠ 「记忆错误」）

生命周期治理（规则驱动，零 LLM）

- 遗忘曲线：30 天闲置枝自动完结、子卡枯萎（status=wilted、排除检索但保留数据）
- 全局治理：inject_used_rate < 0.3 → 自动收缩注入条数（3→2→1）；动作写 decision_log 可审计
- 安全豁免：lesson_permanent / approved / explicit / directive / 佐证 ≥1 的卡豁免衰减

画像蒸馏

- 手动触发（UI「画像」tab 或 RPC distill）：收集事件树 → LLM 生成画像摘要 + 用户人格维度（MBTI + 8 轴，属画像数据而非 persona 库）→ 防抖/去重 → 草稿 → 人工采纳固化（version+1，草稿移入 approved/ 防重复采纳）→ 进入注入常驻基线
- 画像 = 用户画像信息（身份/偏好/协作方式），作为模型的稳定用户背景；相关性闸门（v0.3 抢救修复）：仅在 query 含身份/偏好/经验类语义词时随常驻基线注入，无关主题/寒暄不携带

工程保障

- 故障隔离：sidecar 崩溃只影响记忆，不拖垮 harness；jieba 缺失时返回可操作安装指引而非崩溃
- 安全：POST 严格同源校验；GET 无 Origin 须带本地标记 header（防跨站状态污染）；RPC 参数路径穿越白名单；Sidecar 仅监听 127.0.0.1；密钥脱敏回显 + apiKeyEnv 渐进迁移
- 可移植：引擎路径自动探测（env → config → 自动），Python 可执行文件同理；无 Node 原生依赖
- 可测试：独立冒烟脚本（真实 spawn sidecar）、引擎 324 个单元测试、JSON 修复器专项用例
- 版本规范（2026-08-19 起）：每次 bug 修复或功能更新变更版本号（semver：修复=patch、新功能=minor）并随代码同 commit、打 vX.Y.Z tag 同步推送；当前 v0.1.1

特色

- 为受限上下文而生：本地模型窗口 4K-32K 也能有可用的长期记忆——注入只带相关几条，不靠大窗口硬扛（云端 1M 窗口下同样省 token）
- 本地零外部服务：读取端（检索/注入/治理）零 LLM、零向量库、零外部依赖；写入端可选本地模型或云端 API（mode 决定）
- 记忆与知识分离：记忆 = 关于「你」的经历（会变、有时效）；知识 = 关于「世界」的规范（稳定、可复用）。分开存是为了检索不被污染——搜规范时不会翻出私人经历，反之亦然；两者检索策略也不同（记忆 BM25+RRF，知识条文级倒排）
- 树状组织、弱图谱关系：事件按链聚合（枝=主题演进，叶=单次事件）。树是确定性归链（resolve_chain，标题/别名/实体消歧），图谱只是树的可视化投影——不强依赖实体关系网（实体关系提取难且不稳），用确定性的「归属链」组织记忆
- 记忆会「生长」：事件 → 事件链 → 经验 → 画像的蒸馏路径，不是日志堆积
- 双通道写入：LLM 提取的广度 + 规则即时响应的速度（「记住教训」立即沉淀）
- 克制注入：按意图分档 + 常驻基线 + 审计反馈，控制注入量、避免占满上下文
- 可视化：力导向事件图谱 / 知识图谱 / 时间线，图谱与树联动

已知局限

如实披露（非 bug，是设计边界或未完成项）：

| 项 | 状态 | 说明 |
| 提取质量依赖所选 LLM | 设计边界 | 写入端用 LLM，选错模型（如 reasoner 思考模型）会污染提取；默认预设已关思考，文档有「非思考模型」选型建议 |
| 检索是词级相关度召回，非语义联想 | 设计边界 | BM25+RRF 按词命中相关度排序（含沿链/实体多跳扩展），对措辞漂移召回有限（靠别名/归链缓解），不适合「语义联想」类查询（如「和上次那个类似的东西」）|
| 画像蒸馏为手动触发 | 未完成 | DistillWorker（每周 + idle 门槛自动调度）已实现，sidecar 未启动后台线程，当前需手动点「蒸馏画像」 |
| persona.py（引擎内置人格库）| 刻意不接线 | agent 人格由 DSH 侧 persona 插件/系统提示词管理（引擎 README §9.5 明确不迁移清单）；本插件只负责「记忆」，不负责「分身人格」 |
| 偏好信号需 ≥3 次同类提及才提案 | 设计边界 | 避免单次随口一说即沉淀；反复表达才入 pending |
| 无法替代会话历史全量重放 | 设计边界 | resume 旧会话时 DSH 会把全部历史重放进上下文，插件注入叠加在历史上、无法替代或抑制（历史由 dsh-session deriveMessages 全量生成，插件无裁剪 API）；会话内历史瘦身需靠 DSH compaction |
| 本地小模型边缘波动 | 设计边界 | 4B 级本地模型在规范条文/别名等边缘用例有波动，云端全绿，低置信走 pending 人工兜底 |

语言环境说明（当前主要面向中文）

当前插件主要面向中文环境。以下环节深度依赖中文，英文用户需要自行改造：

| 环节 | 依赖中文的位置 | 英文用户改造建议 |
| 零 LLM 规则触发词 | rules.py（记住/记下/记住教训/踩坑/我喜欢/习惯/别用 等）+ guard.py（_DIRECTIVE / _FACT_HINTS / _CHIT_CHAT 等）| 在对应元组中追加英文触发词（如 remember / lesson learned / I like / don't use / today / project / thanks）——纯数据改动，不影响逻辑 |
| LLM 提取提示词 | extract.py 的 _EXTRACT_PROMPT / _EXTRACT_PROMPT_SMALL（中文提取指令 + 示例）| 编写英文版提示词并实测提取质量（提示词是提取质量命门，不能照译）|
| 画像蒸馏提示词 | distill.py 的 DISTILL_PROMPT（中文）| 同步英文版 |
| UI 文案 | client/client.js 的 141 行中文 UI 字符串（tab 名/标签/提示）| 替换为英文或中英并存 |
| Agent 工具描述 | lib/index.js 的 3 个工具 description（模型可见）| 英文化利于模型理解工具用途 |

注意：中英并存（方案 A）时，若需按对话语言自动切换提示词，还需要新增语言检测逻辑（当前未实现，提取提示词固定为中文）。不做语言检测也可用——英文内容仍会被中文提示词提取（LLM 能理解中文指令），只是英文用户需自行评估提取质量是否可接受。

安装

适配版本

| 依赖 | 版本要求 | 依据 |
| DeepSeek Harness | 0.1.0-rc.7+ | 插件依赖 @deepseek-ai/dsh-tools@^0.1.0-rc.7，client 注入的 5 个服务（connection/runtime/locale/ui-settings/ui-theme）在 rc.7 下实测可用 |
| Python | 3.10+ | sidecar 使用 X \| Y 类型语法（3.10+）|
| Node 原生依赖 | 无 | 纯 JS host + Python sidecar |

说明：rc.7 之前的版本未验证（settings 挂载机制在 rc.7 有调整），建议使用 rc.7 及以上。

:: 1) 从 GitHub 安装
dsh plugin --profile web add github:<owner>/dsh-memory-bridge

:: 2) 安装 Python 依赖（jieba 分词，声明式；清华镜像，失败自动回退阿里云）
pwsh <你的插件目录>/engine/install-deps.ps1

重启 harness 后生效。卸载：dsh plugin --profile web remove dsh-memory-bridge

已带 dsh-plugin / dsh-category-memory topics——可从 DSH 设置 → 插件市场（Marketplace） 的 memory 分类下发现并一键安装。

依赖策略：jieba 走声明式安装，不内嵌、不在安装时静默 pip install；缺失时 sidecar 返回可操作指引，不拖垮 harness。

配置（设置页 → 记忆 → 提取配置）

| 项 | 说明 |
| mode | off 纯规则 / local 本地模型 / cloud 云端记忆 API / main 主对话模型兜底 / hybrid 本地优先·云端兜底 |
| local.preset | qwen3-it-4b-flm（推荐，内置关思考）或 custom（自填 baseUrl/model/apiKey/apiKeyEnv）|
| cloud.* | 云端记忆 API（baseUrl / model / apiKey / apiKeyEnv / batchSize / maxCallsPerMinute）|
| sanitize | 提取前脱敏（手机号/邮箱/身份证/密钥），云端默认开启 |

- 模型选择：提取/注入用非思考模型最稳（reasoning 输出推理链会污染 JSON 提取）；默认预设已关思考；custom 请选 instruct 变体；云端用 deepseek-chat 勿用 deepseek-reasoner
- API key：apiKeyEnv 环境变量优先，回退明文；回读一律脱敏；配置先校验后落盘

UI（设置页 → 记忆）

| Tab | 内容 |
| 总览 | 统计 / 状态 / 审计摘要 / 最近活动 |
| 事件图谱 | 力导向图 + 记忆树导航联动、孤立节点/实体开关、方向箭头流动线 |
| 知识图谱 | wiki 条目力导向图（上位/版本关系）+ 搜索 + 列表 |
| 时间线 | 事件流按日分组（今天/昨天/2-6 天前），倒序 |
| 待审 | 提取队列 / pending 经验审批 |
| 画像 | 已审批画像 + 「蒸馏画像」 + 草稿采纳/驳回 |
| 审计 | 注入/提取统计 + 「立即维护」 + 决策日志 |

界面预览

| 总览：统计卡片 / 记忆构成 / 本地推理状态 / 提取注入审计 / 配置表单 | 事件图谱：力导向图 + 记忆树联动导航 |
| 总览 | 事件图谱 |
| 审计：注入/提取统计 + 手动维护 + 决策日志 | |
| 审计 | |

Agent 工具

| 工具 | 用途 |
| memory_search | 确定性算法检索记忆卡（BM25+RRF，零 LLM），返回链上下文与反馈提示 |
| memory_add_run | agent 主动把当前轮写入 run 队列（可指定 tier）|
| memory_review | 查看待提取 run 队列 / 指定 run 状态 |

HTTP API

- GET：overview health search?q= browse?kind= card?id= review?runId= wiki?q= config lemonade-status audit graph profile-status（需 x-dsh-memory: 1 header 或同源 Origin）
- POST：card-action add-run config lemonade-ensure extract maintenance distill distill-approve distill-reject（同源校验）
- inject / recordUsage / recorder 不暴露为 HTTP 路由：宿主在事件钩子内部直连 sidecar

开发与测试

REM 独立启动 sidecar（脱离 harness 联调）
python -u <插件目录>\python\memory_bridge_server.py --root <引擎目录> --config <插件目录>\config.example.json

REM 冒烟测试（bundled engine 缺 jieba → 可操作指引；本地引擎 → 全功能）
python smoke_sidecar.py

REM 引擎单元测试（324 个）
python -m pytest <引擎目录>\tests -q