为 DeerFlow 接入 OpenViking 长期记忆后端MemoryManager 配置、验证与故障排查全指南【免费下载链接】OpenVikingSelf-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.项目地址: https://gitcode.com/GitHub_Trending/op/OpenViking本指南讲解如何将开源上下文数据库 OpenViking 作为 DeerFlow 的长期记忆后端接入通过 DeerFlow 的 MemoryManager 机制对话消息会自动写入 OpenViking并在每次模型调用前自动召回相关记忆、注入上下文。读完本文你将掌握.env与config.yaml的完整配置方法、五步验证流程接入确认、写入确认、召回确认以及七类常见故障的定位与修复手段并理解这些配置在 OpenViking 服务端对应的真实 API 实现。接入方式与适用场景DeerFlow 生态中有两种把 OpenViking 能力接进来的方式本文聚焦第一种MemoryManager 长期记忆后端本文DeerFlow 在对话过程中自动把消息写入 OpenViking并在模型调用前自动召回记忆、注入上下文全程无需 Agent 主动调用工具适合作为自动记忆层。MCP Server 接入通过extensions_config.json注册 OpenViking 的 MCP Server由 Agent 在任务执行中主动搜索、读取记忆与知识适合作为按需检索的知识层见 DeerFlow MCP 接入文档。两种方式可以同时存在、各司其职MemoryManager 负责记住并自动想起MCP 负责被问到再去查。前置条件OpenViking 服务与鉴权信息接入前需要一台可访问的 OpenViking 服务。OpenViking 的默认本地端点通常为http://127.0.0.1:1933远程部署时使用实际的 Gateway 地址即下文配置中的base_url。OpenViking 服务端的鉴权方式如下参见 API 概览文档推荐方式Authorization: Bearer your-key兼容方式X-API-Key: your-key请求头。普通api_key部署下只需要设置 API Key服务端会从 API Key 推导租户身份只有在 trusted 部署或网关显式透传租户身份时才需要额外设置 Account 和 User。对 DeerFlow 接入而言通常只需一个 API Key 即可。步骤 1配置 OpenViking 鉴权信息在 DeerFlow 项目根目录下编辑.env文件把 API Key 填进去。原文档中该处为文档模板占位符{{OPENVIKING_API_KEY_BLOCK}}实际内容对应 OpenViking 官方接入文档中的标准凭据写法例如# DeerFlow 项目根目录 .env OPENVIKING_API_KEYyour-openviking-api-key-here其中变量名OPENVIKING_API_KEY必须与后续config.yaml中backend_config.api_key_env的取值保持一致——MemoryManager 会从该环境变量读取 API Key 用于服务端鉴权。若你的 OpenViking 服务也要求显式指定服务地址可同时配置OPENVIKING_BASE_URL对应config.yaml中的base_url。步骤 2修改 DeerFlow 的 memory 配置打开 DeerFlow 项目根目录下的config.yaml找到memory:配置段将默认的 DeerMem 配置替换为 OpenViking 配置memory: enabled: true injection_enabled: true shutdown_flush_timeout_seconds: 30 manager_class: openviking mode: middleware backend_config: base_url: {{OPENVIKING_BASE_URL}} owner_user_id: default api_key_env: OPENVIKING_API_KEY startup_policy: fail_fast failure_policy: read: fail_open write: log_and_drop retrieval: top_k: 8 score_threshold: 0.25 max_injection_chars: 12000 content_mode: overview injection_query: - user profile preferences important entities events ongoing goals constraints and prior decisions其中{{OPENVIKING_BASE_URL}}为文档模板占位符实际替换为你的 OpenViking Gateway 地址如http://127.0.0.1:1933。各字段的作用如下字段取值示例含义enabledtrue是否启用 memory 后端必须为trueinjection_enabledtrue是否在模型调用前自动注入召回的记忆shutdown_flush_timeout_seconds30服务关闭时等待未完成记忆操作落盘的超时时间秒manager_classopenviking使用 OpenViking 实现的 MemoryManager是切换接入方式的关键字段modemiddleware记忆以中间件方式工作在模型调用前插入上下文backend_config.base_urlhttp://127.0.0.1:1933OpenViking 服务地址backend_config.owner_user_iddefault记忆归属的用户标识多租户场景可区分不同用户backend_config.api_key_envOPENVIKING_API_KEY从哪个环境变量读取 API Keybackend_config.startup_policyfail_fast启动时若 OpenViking 配置/连接异常则立即失败避免带病运行failure_policy.readfail_open检索失败时放行不注入记忆但正常回复保证主链路可用failure_policy.writelog_and_drop写入失败时记录日志并丢弃不阻塞对话retrieval.top_k8每次召回的记忆条数上限retrieval.score_threshold0.25相关性分数阈值低于该分数的记忆不注入retrieval.max_injection_chars12000单次注入上下文的最大字符数防止上下文膨胀retrieval.content_modeoverview注入内容的形态概览式摘要retrieval.injection_query长文本模型调用前用于召回的固定查询描述用户画像、偏好、关键实体、事件、进行中的目标、约束与历史决策等步骤 3重启 DeerFlow保存.env和config.yaml后重新启动 DeerFlowmake dev由于startup_policy: fail_fast若 OpenViking 配置不完整或不可达DeerFlow 会在此阶段直接报错方便第一时间暴露配置问题。步骤 4验证 OpenViking 是否接入成功在 DeerFlow 项目根目录下查看 Gateway 日志grep -i memory manager resolved\|openviking\|deermem logs/gateway.log成功日志示例Memory manager resolved: OpenVikingMemoryManager (manager_classopenviking) HTTP Request: GET {{OPENVIKING_BASE_URL}}/health HTTP/1.1 200 OK日志中两条关键信息分别代表Memory manager resolved: OpenVikingMemoryManagerDeerFlow 已按manager_class: openviking加载 OpenViking 记忆管理器替代了默认的 DeerMemGET .../health HTTP/1.1 200 OKMemoryManager 启动时对 OpenViking 服务发起了健康检查并成功。这里的/health是 OpenViking 服务端免鉴权的健康检查端点实现在 openviking/server/routers/system.py返回{status: ok, healthy: true, version: ...}同时探测 AGFS 文件系统与 VectorDB 存储健康状态。DeerFlow 用它在启动阶段确认后端可用与日志中启动失败提示配置错误的故障现象一一对应。步骤 5验证写入与召回可通过以下日志确认写入和召回是否正常grep -Ei messages/batch|commit|search/find|has_memory logs/gateway.log | tail -100成功日志示例/messages/batch HTTP/1.1 200 OK /commit HTTP/1.1 200 OK /search/find HTTP/1.1 200 OK has_memoryTrue逐条解读/messages/batchDeerFlow 把一轮对话消息批量写入 OpenViking 会话/commit触发会话归档与记忆提取/search/find模型调用前执行记忆召回检索has_memoryTrue本次调用成功召回了记忆并注入上下文。这三类 HTTP 请求在 OpenViking 服务端均有对应实现见下文底层实现原理日志出现200 OK即代表写入、提交、召回三个环节全部打通。底层实现原理OpenViking 侧 API 如何支撑记忆写入与召回从 OpenViking 仓库源码可以确认DeerFlow MemoryManager 依赖的三类请求全部落在真实可用的服务端端点上1. 批量写入POST /api/v1/sessions/{session_id}/messages/batch实现在 openviking/server/routers/sessions.pyrouter 前缀为/api/v1/sessions。该端点一次接收多条消息且缺失的会话会在首次写入时自动创建auto_createTrue因此 DeerFlow 无需预先建会话即可直接写入。写入完成后服务端还会触发maybe_schedule_auto_commitmessage_write 原因按提交策略自动调度后续归档这正是日志中/messages/batch之后出现/commit的由来。2. 记忆提交POST /api/v1/sessions/{session_id}/commit实现在 openviking/server/routers/sessions.py。归档Phase 1在请求返回前完成记忆提取Phase 2在后台异步执行并返回task_id供轮询。这就是故障排查表中已写入消息但页面未立即看到记忆——OpenViking 的摘要和记忆提取是异步完成的这一条的技术根源。3. 记忆召回POST /api/v1/search/find实现在 openviking/server/routers/search.pyrouter 前缀为/api/v1/search。请求模型FindRequest定义见 openviking/server/routers/search.py核心字段与 DeerFlow 侧retrieval配置的对应关系为query↔retrieval.injection_query模型调用前的召回查询limit↔retrieval.top_k返回条数上限score_threshold↔retrieval.score_threshold相关性分数门槛target_uri/tags/filter可进一步限定召回范围多租户或分类场景可用。也就是说DeerFlow 的top_k、score_threshold、injection_query等配置最终会映射为 OpenVikingsearch/find的参数content_mode: overview对应注入内容的概览形态控制注入到上下文的记忆呈现方式配合max_injection_chars限制 token 开销。4. 鉴权细节写入、提交、召回端点均要求携带有效凭据DeerFlow 侧由api_key_env: OPENVIKING_API_KEY指定的环境变量提供服务端支持Authorization: Bearer与X-API-Key两种头见 API 概览文档。若 Key 缺失、错误或无权限对应请求会返回 401/403与故障排查表中的远程认证失败现象吻合。故障排查现象原因修复DeerFlow 启动失败提示 OpenViking 配置错误config.yaml中 OpenViking 配置不完整或格式错误检查config.yaml中是否已配置manager_class: openviking并确认base_url、api_key_env等字段正确DeerFlow 未接入 OpenVikingmemory.manager_class未改为openviking或修改配置后未重启服务保存配置后重新启动 DeerFlow并确认日志中出现OpenVikingMemoryManager远程认证失败返回 401 或 403OpenViking API Key 缺失、错误或无权限检查.env中的OPENVIKING_API_KEY是否正确检索失败但 DeerFlow 仍继续回复当前配置采用read: fail_open属于预期行为OpenViking 检索失败时不会注入记忆但不会影响主 Agent 正常回复回复已生成但记忆写入失败当前配置采用write: log_and_drop写入失败会被记录到日志中检查并修复 OpenViking 服务、网络和鉴权配置后续新消息可继续写入已写入消息但页面未立即看到记忆OpenViking 的摘要和记忆提取是异步完成的等待后台任务完成后再查看服务关闭时仍有记忆操作未完成系统会在shutdown_flush_timeout_seconds配置的时间内等待其完成若等待超时或 OpenViking 在关闭期间不可用部分记忆写入可能无法完成。可适当调大该配置并检查关闭期间 OpenViking 的网络和服务状态两个软失败策略值得再次强调read: fail_open与write: log_and_drop把 OpenViking 的故障与 DeerFlow 主对话链路彻底解耦——检索挂了不影响回复写入挂了不影响对话代价只是这一轮没有记忆。这属于设计内的预期行为而非异常。进阶MemoryManager 与 MCP 两种接入如何配合如果你的场景不仅需要自动记忆还需要 Agent 在推理过程中主动检索知识库可以在 DeerFlow MCP 接入文档 的指引下通过extensions_config.json注册 OpenViking 的 MCP Servertype: http、url: {{OPENVIKING_BASE_URL}}/mcp、X-API-Key请求头与本文的 MemoryManager 配置并存。二者定位互补MemoryManagermiddleware 模式无感自动写入 每次模型调用前的自动召回负责持续记忆MCP Server由模型按需调用检索工具负责主动深查。两者共用同一套.env凭据OPENVIKING_API_KEY鉴权方式一致配置时可复用本文步骤 1 的产物。小结完成上述五步后DeerFlow 便获得了基于 OpenViking 的长期记忆能力消息自动沉淀、模型调用前自动召回、故障时优雅降级。接入是否成功可通过Memory manager resolved、/messages/batch、/commit、/search/find四类 Gateway 日志逐层确认而这些日志背后对应的正是 OpenViking 服务端 会话消息批量写入、会话提交归档 与 语义检索 三个真实端点。若需进一步了解 OpenViking 的检索能力与上下文组装细节可继续阅读 API 概览 与 DeerFlow MCP 接入。【免费下载链接】OpenVikingSelf-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.项目地址: https://gitcode.com/GitHub_Trending/op/OpenViking创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考