xiaono1/dsh-ov-memory

dsh-ov-memory

License: MIT
Node
Language

把 OpenViking 持久记忆接入
DeepSeek Harness（DSH）的插件。
OpenViking 负责「记住」，本插件负责把记忆在合适的时候送进对话、把对话送回去沉淀。

简体中文 | English

功能特性

- 自动召回 —— 每一步开始前，用当前输入在 OpenViking 中检索相关内容并注入对话（context 模式检索，服务端完成去重与 token 预算控制）
- 会话镜像 —— 把 user / assistant（可选 tool 结果）消息实时写入 OpenViking 的 dsh- 会话流，供后台抽取为长期记忆
- 阈值提交 —— 服务端 pending_tokens 达到阈值自动 commit（保留最近 N 条为活跃消息）；会话关闭时兜底提交
- 离线出站队列（outbox） —— OpenViking 不可达时写操作落盘持久化，下次会话启动时幂等重放（内容哈希去重、重试上限、TTL 清理）
- /memlearn 人工沉淀 —— 斜杠命令直接把一条经验写入长期记忆：不开启模型回合、原文不进会话日志；密钥先脱敏，再语义查重合并进最相近的已有记忆（OpenViking 无新建记忆文件 API，低于分数下限时诚实拒绝写入）；离线时自动进 outbox，恢复后重放
- 完整工具面 —— 自研最小 MCP 实现（stdio 服务器 + streamable-HTTP 上游，无第三方 MCP SDK），把服务器全部工具以 mcp__openviking__ 暴露；服务器工具表变化自动同步
- viking:// URI 守卫 —— 拦截本地 fs/shell 工具把 viking:// 虚拟路径当成本地文件
- 自带技能 —— 独立 skill provider 提供 ov-memory 使用指南，不污染默认技能目录
- 零运行时依赖 —— 复用 DSH 已安装的 @deepseek-ai/ peer 包，无额外 npm 依赖

环境要求

- DeepSeek Harness：@deepseek-ai/ 0.1.x（≥ 0.1.0-rc.6）release 线
- Node.js ^22.19.0 或 >=24
- 一个可访问的 OpenViking 服务器（本地 openviking-server，或远程实例）

安装

从 GitHub 源码安装（lib/ 已预构建提交，无需本机构建）
dsh plugin --profile  add github:xiaono1/dsh-ov-memory

本地开发安装
dsh plugin --profile  add /path/to/dsh-ov-memory

插件通过自带的 cordis.patch.yml 注册为一个隔离的 cordis group（服务命名空间 ovMemory）。
若 profile 中已存在其它占用 mcp__openviking__ 命名空间的桥接插件，请先移除再启用本插件，两者不能共存。

配置

默认连接 http://127.0.0.1:1933。凭据沿用 OpenViking 生态的统一解析顺序：
OPENVIKING_ 环境变量 → ~/.openviking/ovcli.conf → ~/.openviking/ov.conf。
如需显式覆盖，在 profile 的 cordis.patch.yml 中写入：

- insert:
- id: ov-memory
config:
- id: ov-memory-runtime
config:
endpoint: 'http://127.0.0.1:1933'   # REST base
apiKey: 'your-user-key'              # 留空则走 env / ovcli.conf
account: ''
user: ''
recall:
enabled: true
budgetTokens: 2000      # 每次召回的注入预算（服务端 context 模式）
scoreFloor: 0.35        # 相关度下限
refreshEverySteps: 0    # >0 时按步数周期强制刷新；0=仅查询变化时
capture:
toolResults: false      # 是否把工具结果也镜像进记忆流
skipSubagentSessions: false
commit:
thresholdTokens: 20000  # pending_tokens 达到即提交
keepRecentCount: 10     # 提交后保留为活跃的最近消息数
learn:
minScore: 0.5           # /memlearn 合并进已有记忆的语义分下限

常用环境变量：

| 变量 | 作用 |
| --- | --- |
| OPENVIKING_URL / OPENVIKING_BASE_URL | 服务器地址 |
| OPENVIKING_API_KEY / OPENVIKING_BEARER_TOKEN | 鉴权凭据 |
| OPENVIKING_ACCOUNT / OPENVIKING_USER | 租户/用户（trusted 模式）|
| OPENVIKING_PEER_ID | 固定 actor peer |
| OPENVIKING_MCP_URL | MCP 端点覆盖（默认 /mcp）|
| OPENVIKING_PENDING_DIR | outbox 目录（默认 ~/.openviking/pending）|

工作原理

DSH agent 钩子                    本插件（进程内）                        OpenViking 服务器
─────────────────                ─────────────────                      ──────────────────
agent/session-start ──► 建档 + outbox 重放 ───────────► POST /api/v1/sessions
agent/pre-step     ──► 召回注入（plugin user 消息）──► POST /api/v1/search/search (mode=context)
session/event      ──► 会话镜像 ──服务器不可达──► outbox(本地持久化) ──重放──► POST .../messages
turn/end           ──► pending_tokens ≥ 阈值 → commit
session/flush      ──► 兜底提交
/memlearn 命令     ──► 脱敏 → 语义查重 → append（离线进 outbox）──► POST /api/v1/search/find → POST /api/v1/content/write
工具面 mcp__openviking__ ◄── dsh-mcp-client ◄── stdio ── 自研 MCP 代理 ──► POST /mcp (streamable HTTP)

设计决策与实现说明见 docs/DESIGN.md，验证手册见 docs/E2E.md。

开发

npm ci
npm run typecheck   # tsc --noEmit
npm run build       # TypeScript → lib/（已随仓库提交）
npm test            # node --test（内置 mock OpenViking 服务器，无需真实服务）

测试不依赖真实服务器：test/*.test.mjs 用自建 node:http 模拟 OpenViking REST 与 MCP 端点，
覆盖捕获/提交/outbox/凭据链/peer 解析/MCP 会话与工具调用/URI 守卫//memlearn（脱敏、查重合并、离线入队与重放）等路径。

可选真实服务器端到端验证见 docs/E2E.md。

License

MIT