dsh-memory-bridge

English | 中文

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

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

项目定位

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

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

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

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

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

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

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

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

用户群体：

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

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

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

解决什么（痛点）

价值

• 对对话质量：关键轮次注入相关记忆（偏好、项目背景、既定决策），减少重复说明与前后矛盾——模型基于检索到的记忆回应，而非凭空"记得"。
• 对成本：注入按需限量 + 寒暄零注入 + 提取门卫（寒暄轮跳过 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（关于"世界"的规范）是两个独立库，知识条目不进记忆树，避免污染画像与经历。

重大决策

关键工程实现

架构

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，是设计边界或未完成项）：

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

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

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

安装

适配版本

说明：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。

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

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

UI（设置页 → 记忆）

界面预览

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

Agent 工具

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