# dsh-memory-graph vs OpenViking dsh-memory-plugin 对比分析

> 对比对象:[OpenViking / examples/dsh-memory-plugin](https://github.com/volcengine/OpenViking/tree/main/examples/dsh-memory-plugin)(Apache-2.0,是 [OpenViking](https://github.com/volcengine/OpenViking)(AGPLv3,Volcengine)上下文数据库的 DSH 适配插件)
> 审查时间:2026-08,基于 OpenViking 仓库 main 分支快照；本项目状态更新至 v0.7.0。

---

## 一、定位差异(最重要的一句话)

| | dsh-memory-graph(你的项目) | OpenViking dsh-memory-plugin |
|---|---|---|
| 本质 | **自包含的本地记忆/知识图谱插件** | **外部上下文数据库(OpenViking server)的瘦客户端适配器** |
| 数据归属 | 本地 SQLite,数据不出主机 | 转录内容同步到远程/本地 OpenViking 服务 |
| 依赖 | 仅 DSH peer 依赖 + `node:sqlite` | **零运行时 npm 依赖**,但必须有可用的 OpenViking server |
| 记忆形态 | 结构化记忆 + 实体-关系图谱 + 稳定事实版本链 | `viking://` 虚拟文件系统(memories/skills/resources 目录树 + 三级摘要) |
| 检索 | 本地 FTS5 trigram + 图距离 + 意图信号 + 可选 embedding 混合召回 | 服务端语义检索 + 查询扩展 + 跨轮去重 + 服务端组装 |
| UI | DSH Web 侧边栏仪表盘 + 交互式工具卡片 | **无任何前端**(工具只返回文本) |
| 测试 | 40 个 vitest 单测，覆盖 schema、单轮策略、archive、outbox、CJK 与受保护 Web 操作 | 多个 node:test 文件(含离线队列、重试分类、dispose 顺序等对抗性场景)+ 可选的 E2E 门禁 |

两者唯一的共性:都是 Cordis 插件、都用 `agent/pre-step` 注入、都用 `defineTool` 注册工具。**它们不是同一类产品的竞争,而是"本地单机自建"与"对接外部大脑"两条路线。**

---

## 二、架构对比

```
dsh-memory-graph(全本地)
  turn ─▶ 单轮策略 ─▶ 本地 archive ─▶ LLM 摘要抽取 ─▶ SQLite
  pre-step ─▶ FTS/图/意图/可选 embedding 混合召回 ─▶ 注入上下文
  写失败 ─▶ 本地 outbox ─▶ 启动重放
  DSH Web ─▶ snapshot + 受保护 action ─▶ 图谱/开关/删除

OpenViking 插件(server 中心)
  turn ─▶ capture 事件 ─▶ HTTP 同步到 server session
       └─ 失败 ─▶ 本地 pending 队列(磁盘 JSON,启动时重放)
  turn/end ─▶ 到达 token 阈值 ─▶ commit(归档 + 摘要)
  session-start ─▶ 注入 <user-profile> + <available-memories>
  pre-step ─▶ 服务端 /search(context face)组装 ─▶ 注入
  tools/pre-execute ─▶ 拦截 viking:// URI 进入文件工具
```

关键差异点:

| 维度 | dsh-memory-graph | OpenViking 插件 |
|---|---|---|
| 知识图谱 | 实体/别名/关系/kind 投票/merge/rename/GC,真正的连通图 | 无关系图;`entities/` 只是文件目录,节点间无 relation |
| 版本化 | stableKey 超替链 + `memory_revert` | 无版本;`viking_forget` 永久删除 |
| 原始会话保留 | 本地有界 turn archive + `memory_archive_expand` + 失败重试 | 全量消息归档 + 三级摘要 + `viking_archive_expand` 还原原文 |
| 工具结果记忆 | 可配置捕获有界 tool result 文本，默认关闭 | 可配置捕获 tool 调用/结果(`captureToolResults`) |
| 离线韧性 | SQLite 写 outbox + 启动重放 + dead-letter；模型抽取失败保留 archive | 磁盘 pending 队列 + 重试分类(retryable/permanent)+ TTL |
| 多用户/隔离 | 无(单进程单库) | peer 体系:workspace 派生 peer、recall peer scope(actor/all) |
| 上下文预算 | CJK-aware token 估算 + 字符硬上限 + preview/full 展开 | token 预算 + **CJK 感知估算** + 服务端分层(abstract/overview/full)+ 压缩 |
| 召回来源 | 纯 SQL,瞬时、可离线 | 网络往返,可含查询扩展(5s)/服务端重写(45s)阶段 |
| 备份恢复 | 精确 JSONL 快照 | 无 |

---

## 三、你的项目的优势(相对 OpenViking 插件)

1. **本地优先、零外部依赖**:不启动任何服务即可用,数据完全留在主机,没有把对话转录发给第三方服务的隐私问题(OpenViking 默认把每轮消息同步到 server)。
2. **真正的知识图谱**:实体规范化 + 别名 + 关系 + kind 投票收敛 + merge/rename/delete/orphans/GC 完整维护链;OpenViking 的"entities"只是目录里的 markdown 文件,节点之间没有关系,谈不上图谱。
3. **图谱可视化**:DSH Web 侧边栏仪表盘 + 交互式图谱卡片(力导向布局、搜索、缩放、选中联动记忆),且工具结果有结构化 schema + 可重放元数据(`graphFromMeta`);OpenViking 插件完全没有前端。
4. **稳定事实版本链 + 回退**:`stableKey` 超替、`memory_revert` 恢复上一版;OpenViking 只知永久删除。
5. **精确备份/恢复**:JSONL 全量快照;OpenViking 无备份概念。
6. **可审计性**:每条记忆带 sourceSession/sourceTurn/sourceEventSeqs;摘要保留完整 request/response JSON;召回带 reason 列表;OpenViking 归档粒度较粗。
7. **工具返回结构化 schema**:`output.schema` 精确描述,模型和 UI 都能可靠消费;OpenViking 7 个工具全部只返回纯文本。
8. **MIT 许可证 + 体积小、自包含**,个人项目可自由定制。

## 四、OpenViking 插件的优势(你的项目相对劣势)

1. **服务端语义能力更完整**:OpenViking 负责 embedding、查询扩展、context face 组装和跨资源检索;本项目只提供可选 OpenAI-compatible embedding 适配器,查询改写和语义服务运维仍由用户负责。
2. **分层内容模型更成熟**:OpenViking 原生提供 abstract/overview/full 与目录浏览;本项目是 preview/full 两级,archive 以 turn 为单位,没有虚拟目录。
3. **多用户/多空间隔离**:peer 体系支持 workspace 派生 actor 和 actor/all recall;本项目仍是单用户、单库全局作用域。
4. **外部资源摄取**:`viking_add_resource` 可摄取 HTTP/git 资源;本项目只沉淀对话与显式工具写入。
5. **远端 pending queue 更成熟**:OpenViking 队列针对 HTTP 状态、TTL 和 session commit 顺序设计;本项目 outbox 只保护本地 SQLite remember/commitSummary,模型抽取失败通过 archive 人工重试。
6. **真实服务 E2E**:OpenViking 提供可选 live server gate;本项目覆盖本地向量与降级逻辑,尚无带外部 embedding secret 的 CI E2E。

---

## 五、可借鉴的改进点(按优先级,与 IMPROVEMENTS.md 配套)

### A. 能力补齐(OpenViking 明显领先的领域)

| 优先级 | 改进点 | 说明 | 工作量 |
|---|---|---|---|
| 已完成 | **语义召回作为可选模块** | v0.7.0 增加后台写入队列、短查询超时、缓存/冷却、轮转候选与有限分数降级 | 高 |
| 已完成 | **原始会话碎档(archive)** | schema v6 增加裁剪状态、独立预算、TTL/条目上限、展开工具和启动离线重试 | 中 |
| 已完成 | **工具结果捕获** | 默认关闭;启用后捕获有界结果文本,不保存调用参数 | 低 |
| 已完成 | **写失败 outbox** | remember/commitSummary 可重试失败进入 0600 文件队列,启动重放,永久失败 dead-letter | 中 |

### B. 检索质量工程(便宜、立即可做)

| 优先级 | 改进点 | 说明 | 工作量 |
|---|---|---|---|
| 已完成 | **CJK-aware 上下文预算** | recall 与摘要输入同时使用 token 估算和字符硬上限 | 低 |
| 已完成 | **查询意图信号 + 词法 boost** | preference/temporal 信号和词法重叠均可配置 | 低 |
| 已完成 | **召回结果去重** | 规范化 content 去重;逻辑边继续按 `(S,P,T)` 聚合 | 低 |
| 已完成 | **分层摘要返回** | recall 返回 preview、原长度和 expandable,`memory_expand` 读取全文 | 低 |

### C. 生命周期与多租户

| 优先级 | 改进点 | 说明 | 工作量 |
|---|---|---|---|
| 中 | **profile 开局注入** | 从高置信稳定事实组一个 `<user-profile>` 块,在 `agent/session-start` 注入(仅 idle 时),减少首轮召回盲区 | 低 |
| 中 | **scope 隔离** | 加 `scope` 列(如 profile/workspace 名),recall/图/仪表盘按 scope 过滤;对齐 IMPROVEMENTS.md 的功能清单 | 中 |

### D. 工程健壮性(承接 IMPROVEMENTS.md)

| 优先级 | 改进点 | 说明 |
|---|---|---|
| 高 | 摘要器重试与失败分类 | 判 JSON 解析失败/超时为 permanent,`5xx`/网络为 retryable,retryable 进重试队列(上限 3、退避) |
| 中 | 测试补对抗性场景 | 队列顺序、dispose 竞态、备份旧格式、合并回滚——按 OpenViking 的测试写法补 |

### E. 不建议照搬的点

- **不引入 OpenViking server 依赖**:你的本地优先/自包含是核心卖点,语义召回应做成可选本地/远程 embedding 服务,而不是强制。
- **不照搬"每轮同步全量消息到远程"**:隐私与成本都不划算;若要做存档,存本地(见 A2)。
- **不学其纯文本工具输出**:你现在的结构化 schema 更利于 UI 与模型可靠消费。

---

## 六、结论

1. **路线本质不同**:本项目是"本地自建记忆 + 显式图谱 + DSH UI",OpenViking 是"外部上下文数据库的接入层"。前者胜在自包含、可审计、可视化和版本化;后者胜在服务端语义编排、多用户隔离、资源摄取与三级内容模型。
2. **v0.6 已补齐主要单机工程差距**:可选语义召回、archive、tool result、outbox、CJK 预算、意图信号和分层展开均已落地;当前最大的能力差距转为多租户/作用域和外部资源体系。
3. **两者可以共存**:同一 DSH 实例安装两个插件不冲突(tools 前缀不同:memory_* vs viking_*),若未来接入 OpenViking server,你的 UI/图谱仍可保留为本地侧视图。
4. **后续顺序**:优先做 workspace scope 与 archive 保留策略,再评估资源摄取和更成熟的本地 embedding provider;不应为对齐功能表而引入强制 OpenViking server。