长期记忆库 zouyuanqing/dsh-memory-openviking

dsh-memory-openviking

为 DeepSeek Harness 提供原生长期记忆，底层由 OpenViking 支撑（「面向 AI 智能体的自演化上下文数据库」）。不用自建插件框架——集成直接跑在 DSH 原生的 Cordis 组合平面和 OpenViking 的 HTTP 接口上。

dsh-plugin · 全局长期记忆：自动捕获、经验/轨迹闭环、记忆工具、配置档注入、WebUI 设置卡片，以及面向每一个智能体预设的首轮注入控制——不需要专门的「记忆模式」。

你能得到什么

| 能力 | 平面 | 作用范围 |
| 自动捕获 —— session/event（写后即返）→ session/flush（有界等待排空）→ batchAddMessages + 异步 commitSession（服务端 LLM 蒸馏出偏好/实体/事件） | Host（memory-openviking 行） | 每个会话、每个预设 |
| 持久性 —— 失败即保留，配合指数退避重试、磁盘死信队列（deadLetterDir）、长时间中断时的缓冲上限，以及在 agent/disposed / session/disposed 时做最后一次 keepRecentMessages: 0 提交（短会话和尾部消息永不丢失） | Host | 每个会话 |
| 记忆服务 ctx.memory —— write / recall / search / profile / forget / commit / health | Host | 每个预设的行 |
| 轻量工具 —— memory_write / memory_recall / memory_search / memory_profile / memory_forget（forget 限定在 memories/ 命名空间，默认非递归，带审计日志） | 全局注册（tool-memory 行） | 每个智能体（除非预设显式限制全局工具，否则可见） |
| 自动注入 <memory_profile> 提示词 —— 会话工作记忆概览 + 跨会话召回的偏好/实体/事件，1200 字符预算，5 分钟缓存，同步服务商配合异步刷新（永不阻塞提示词组装）；提交级联失效；注入安全的截断与标签清洗 | 全局（system-prompt 段） | 每个会话的每一轮 |
| 按输入定向注入 —— agent/pre-step 读取当前用户输入，检索相关记忆（语义查询 + project= 标签定向，无标签时回退），注入一个 <memory_context> 线索块；每一新轮都表面替换上一块，历史永不累积；琐碎输入和重复输入跳过检索 | 全局（agent/pre-step 瀑布流） | 每一轮 · 约 500 token 预算 · 静默降级 |
| 首轮注入控制 —— firstTurn.skipPresets（按 session.header.agentPreset）和/或 firstTurn.skipAllFirstTurn：选中的（或每一个）预设的首轮完全不注入记忆——没有 <memory_context> 消息，<memory_profile> 段为空——从第 2 轮起恢复正常行为。为极简/路由风格的预设保留干净的首轮提示词 | 全局（tool-memory 配置） | 仅首轮 |
| WebUI 设置卡片 — 两个包都在 设置 → 插件配置（settings.plugin.item）里提供插件配置卡片，与官方卡片模式一致：memory-openviking 分为连接 / 隔离 / 捕获 / 召回几组，tool-memory 分为 section / dynamic / first-turn 几组，支持中英文语言包，分阶段保存 | 客户端（dsh.client bundle 那一半） | 所有浏览器 |
| OpenViking 0.4.6 兼容 — 针对 0.4.6 的 SearchRequest 做了召回归一化（不再有 mode/max_tokens/purpose/peer_scope），并适配其 memories[] 响应结构；已对着 auth_mode: api_key 服务器做过实机验证 | 适配器 | 召回 / 搜索 |
| 经验闭环 — 抽取，experiences/trajectories/cases 演化，以及 used() 复用排序，全部在 OpenViking 服务器内部运行（Agent Evolution）。这个适配器只负责触发提交与打标签，并转发召回 —— 演化逻辑本身不在本仓库里。 | OpenViking 服务器 + 适配器 | 账号级 |
| 租户隔离 — account/user 作用域（按账号、按用户的 API key）让一台机器（或一个智能体）的记忆不会混进另一个的召回结果；可选的 peerPerSession actor peer 能做更细的切分 | 宿主 | 配置 |

「被动工具调用」变成了「自动会话记忆」：模型不必再主动要求记住什么 ——捕获发生在 flush 检查点（带重试，所以能扛过服务器重启的时间窗），下一个会话启动时，system prompt 里已经有了一份 profile，经验复用也会被追踪并反馈进检索排序。

架构

┌─ DeepSeek Harness (Cordis runtime) ─────────────────────────────────────┐
│ host composition ($DSH_HOME/profiles/<name>/cordis.patch.yml) │
│ memory-openviking → memory service (capture + recall) │
│ tool-memory → memory_* tools + <memory_profile> section │
│ browser (Client) │
│ memory-openviking / tool-memory → WebUI 设置 → 插件配置 cards │ │ agent plane (ANY preset) → tools & section inherited globally │ └───────────────┬────────────────────────────────────────────────────────┘ │ HTTP (Bearer X-API-Key; per-account/per-user tenant keys) ┌───────────────▼────────────────────────────────────────────────────────┐ │ OpenViking server │ │ viking://user/<user>/memories/{preferences,entities,events, │ │ experiences,trajectories,cases,tools,skills,...} │ │ viking://user/<user>/sessions/dsh-<session>/ (archives + tasks) │ └────────────────────────────────────────────────────────────────────────┘

认证说明。 OpenViking >= 0.4.x 可以用 auth_mode: api_key 运行。这种模式下， root key 只能访问管理类 API；租户作用域的数据 API（会话、搜索、写入）需要某个账号的 user/admin API key。先创建账号（及其第一个用户）用 POST /api/v1/admin/accounts {"account_id","admin_user_id"}，带上 root key，然后读取返回的、可查看的用户 key。把它配置到 account/user/apiKey 下。

通用方向

docs/ 里的研究文档规划了演进路线：走向后端无关的记忆中枢，对齐 DSH 自己的 dsh-storage 模式。具体是一个 @deepseek-ai/dsh-memory 接口包（Memory 中枢 + MemoryBackend 契约，覆盖 write/read/forget/tracking），本仓库的 OpenViking 客户端只是其中一种适配器实现——Mem0/Zep 等按同样方式接入。见 docs/dsh-generic-memory-design.md。

关键实现事实：

- 写入路径用 @openviking/sdk 的 sessions API（getSession(autoCreate) → batchAddMessages → commitSession，服务端异步抽取约 10-30s）。从 v0.4.0 起，适配器在每次 batch/commit 前都会重新确保会话存在，所以服务端重启绝不会让某个 batch 因为会话缺失而变成孤儿。
- 召回路径用原始 POST /api/v1/search/search，语义为 context 模式。
- 提交节流：commitIntervalMessages（16）或 commitIntervalMs（60s），随会话长度增长——避免话多的会话把服务端抽取队列冲垮。

安装

1. Copy/install both packages so the DSH loader resolves them (e.g. into the
web profile's node_modules), then add two rows to $DSH_HOME/profiles/web/cordis.patch.yml:
- id: memory-openviking
name: '@deepseek-ai/dsh-memory-openviking'
- id: tool-memory
name: '@deepseek-ai/dsh-tool-memory'
2. OpenViking must be up BEFORE DSH starts.
3. Restart DSH.

两个包都是纯 ESM，零构建步骤，并且各自带一个浏览器半边（client.js，通过 dsh.client + exports["./client"] 声明），所以下次重启时 WebUI 配置卡片会自动加载。

pnpm 的 file: 复制行为。 在 Windows 上，pnpm 安装 file: 依赖时是复制整个
文件夹，而不是建符号链接。安装之后如果你在源码检出里改了这些包，要把改动过的文件（lib/.js、client.js、package.json）重新复制到 profile 的 node_modules 副本里——或者重跑一次安装。不要在 profile 里直接跑裸的 pnpm install，那会连带复制/提升 @deepseek-ai/ 核心包（会产生双模块实例，把 harness 搞坏——见 release 里的「dual instance」说明）。

跑单元测试（注入的是假传输层，不需要真实服务器）：

npm install # workspace root (also brings dev deps)
node --test "packages//test/.test.js" # 77 tests

配置

memory-openviking 行（全部可选）

| 字段 | 默认值 | 含义 |
| baseUrl | http://127.0.0.1:18770 | OpenViking 服务器地址 |
| apiKey | — | 某个账号的用户/管理员 API key（root key 碰不了数据 API） |
| account / user | — | 租户隔离范围；同时设置可实现按账号/按用户隔离 |
| peerPerSession | false | 把每个 DSH 会话映射到它自己的 OpenViking actor peer |
| peerScope | all | all = 所有 peer，actor = 仅当前 actor |
| capture. | 见 Config | toolResults、nonUserSources、subagentSessions、flushThresholdBytes、commitIntervalMessages、commitIntervalMs、keepRecentMessages、maxBufferBytes、flushTimeoutMs、retryMaxAttempts、retryBaseDelayMs、retryMaxDelayMs |
| recall. | 见 Config | maxTokens、scoreThreshold、cacheTtlMs、purpose |
| timeoutMs | 15000 | 每次调用超时 |
| deadLetterDir | "" | 重试耗尽后失败批次的死信目录 |

tool-memory 行（全部可选）

| 字段 | 默认值 | 含义 |
| section.enabled | true | 把 <memory_profile> 注入系统提示词 |
| section.maxChars | 1200 | 配置档块预算 |
| section.minScore | 0.2 | 注入配置档条目的最低召回分数 |
| section.query | 宽泛的配置档查询 | 跨会话召回查询 |
| dynamic.enabled | true | 按输入注入 <memory_context> |
| dynamic.minScore | 0.25 | 按输入注入的最低召回分数（调高可减少噪声） |
| dynamic.maxEntries | 5 | 每轮注入的记忆条数上限（调低可减少噪声/token） |
| dynamic.maxTokens / inputMaxChars / minInputChars / projectTagPrefix | 见 Config | 预算与标签控制 |
| firstTurn.skipPresets | [] | 预设名列表（按 session.header.agentPreset），这些预设首轮不注入记忆 |
| firstTurn.skipAllFirstTurn | false | 所有预设都跳过首轮 |

api_key 0.4.6 服务端的完整示例，带租户隔离与低噪声注入：

- insert:
- id: memory-openviking
name: '@deepseek-ai/dsh-memory-openviking'
config:
baseUrl: 'http://192.168.3.205:1933'
account: 'dsh'
user: 'main'
apiKey: '<user-api-key-of-account-dsh>'
- id: tool-memory
name: '@deepseek-ai/dsh-tool-memory'
config:
firstTurn:
skipAllFirstTurn: true
skipPresets: [minimal, router-standard, router-spec]
dynamic:
minScore: 0.35
maxEntries: 3
section:
minScore: 0.3

WebUI 配置卡片

两个包都带一个浏览器端，会在设置 → 插件配置（settings.plugin.item）里注册一张卡片，样式和结构与官方插件卡片一致：

- OpenViking long-term memory（memory-openviking）—— 连接（baseUrl / API key / account / user / timeout / dead-letter dir）、会话隔离（peerPerSession / peerScope）、可折叠的 Auto capture 与 Recall 分组，包含所有 capture/recall 开关。
- Memory tools & profile injection（tool-memory）—— 可折叠的 Profile section、Per-input injection 与 First-turn injection control 分组。

保存后写入设置层（覆盖行配置）；宿主服务会读取改动会立即对新会话、新客户端生效。API key 字段是密文输入，绝不回显。

合理使用建议（噪声、token、隔离）

- 隔离租户：用 account/user 区分，避免一台机器（或一个智能体）的记忆混进另一个的召回——这是降噪效果最大的一招。
- 调高 dynamic.minScore（比如 0.35–0.5），调低 dynamic.maxEntries（2–3），让每一轮只带几条高置信度的线索。
- firstTurn.skipAllFirstTurn（或按预设的 skipPresets）能给 minimal/router 预设一个干净的首次提示词。
- 记忆是异步提炼的（提交后约 10–30s）；刚 memory_write 写入的事实不会马上可召回——这是正常现象，不是故障。

多租户部署

如果没设 account/user，且 peerPerSession: false、peerScope: 'all'，那么所有 DSH 会话共用一个 OpenViking actor——记忆会在用户之间串（服务启动时会警告）。要做隔离部署，就设置 account/user、peerPerSession: true 和 peerScope: 'actor'，这是最严格的分割方式；或者为每个租户单独配一对 account/user 来共享。

评测

scripts/memory-eval/ 提供了一套 LoCoMo 风格的基准，分三层：

- run-eval.mjs —— 实测 OpenViking 的检索质量：合成多轮数据集（带共享 token 的跨会话干扰项）→ 用 SDK 回放并定期提交 → 按上下文模式给召回打分，输出 MRR 和 precision@5。
- pipeline-check.mjs —— 离线运行，把同一份数据集回放进真实的插件 MemoryService（用假传输层）：写后延迟、去重、按字节阈值触发排空、会话重新确保、keepRecent 提交、失败保留重试、销毁时最终提交、状态回收。
- token-eval.mjs —— 归档存储压缩（存储侧）和端到端每请求的提示词开销。

见 scripts/memory-eval/README.md 和 docs/ 里的评测说明。

已知限制

- 召回/搜索按本仓库验证过的 0.4.6 线上格式做归一化（见 packages/dsh-memory-openviking/lib/client.js）；其他 OpenViking 小版本可能在 SearchRequest 字段或响应字段上有差异——在那里调整归一化逻辑。
- 屏幕端安装注意事项：pnpm 的 file: 在 Windows 上会复制文件夹；改过的文件要重新复制（见安装部分）。

许可证

MIT（各包）。OpenViking 服务端是 AGPLv3——本集成只通过 HTTP 与它通信，从不内嵌或链接服务端代码。