OpenViking 路线图全解析从三层上下文模型到 Agent 记忆生态的落地版图【免费下载链接】OpenVikingSelf-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.项目地址: https://gitcode.com/GitHub_Trending/op/OpenVikingOpenViking 是一个面向 AI Agent 的自进化上下文数据库以统一 Agent 记忆、知识 RAG 与技能为使命。本文基于仓库中 docs/zh/about/03-roadmap.md 的路线图文档逐项梳理其已完成功能与未来计划并对照仓库源码与配套概念文档给出实现级佐证帮助读者系统理解 OpenViking 当前的技术版图、设计取舍与演进方向。一、核心基础设施一切内容的统一地基路线图把 OpenViking 的地基总结为五件事三层信息模型、Viking URI 寻址、双层存储、异步/同步客户端、QueueFS 存储后端。这五者构成了内容如何组织、如何寻址、如何存储、如何访问的完整闭环。1.1 三层信息模型L0/L1/L2OpenViking 使用 L0/L1/L2 三层信息模型在检索效率、导航能力和原始内容完整性之间取得平衡。其语义定义可在源码 openviking/core/context.py 中找到class ContextLevel(int, Enum): Context level (L0/L1/L2) for vector indexing ABSTRACT 0 # L0: abstract OVERVIEW 1 # L1: overview DETAIL 2 # L2: detail/content各层级的定位与默认正文上限如下完整定义见 docs/zh/concepts/03-context-layers.md层级名称存储形式默认正文上限用途L0摘要目录内的.abstract.md256 字符向量检索、快速过滤L1概览目录内的.overview.md4000 字符Rerank、内容导航L2详情原始文件和子目录无统一上限完整内容、按需加载关键设计是L0/L1 是目录级语义 sidecar描述一个目录而非为每个文件生成同名伴生文件文件摘要会聚合到所在目录的 L1 中。正文上限由semantic.abstract_max_chars与semantic.overview_max_chars配置限制只作用于 Markdown 正文不截断 sidecar 元数据。L0/L1 通常成对生成但允许只存在其中一个——例如mkdir()会先创建 L0未传入description时用目录名作默认正文。从 docs/zh/concepts/03-context-layers.md 可以看到一个已完成语义处理的目录结构viking://resources/docs/auth/ ├── .abstract.md # L0隐藏的目录级 sidecar ├── .overview.md # L1隐藏的目录级 sidecar ├── oauth.md # L2完整内容 ├── jwt.md # L2完整内容 └── api-keys.md # L2完整内容普通ls默认隐藏.abstract.md和.overview.md且不要依赖每个目录始终具有两个 sidecar的假设。新生成的 L0/L1 使用最小 OKF Markdown 格式YAML frontmatter 可见正文frontmatter 中记录directory、source、generated_by、freshness等元数据其中 embedding 输入只采用正文与白名单字段directory保证向量化输入的一致性。1.2 Viking URI 寻址系统所有上下文对象统一用viking://scope/path格式的 URI 标识。URI 解析器实现在 openviking_cli/utils/uri.py其文档注释给出了完整的作用域划分resources独立资源 / 客观知识生命周期长期account 全局可见user用户级数据含 session长期 / 会话生命周期仅当前用户可见agentagent 能力与配置技能、端点、工具、支付等account 全局可见queue / temp / upload内部实现作用域公开 API 的 URI 参数不能直接访问sessionuser session 路径的向后兼容别名新 session 数据位于viking://user/{user_id}/sessions~当前调用方用户根目录的服务端别名viking://~/memories/note.md展开为viking://user/{user_id}/memories/note.md且仅在路径第 0 段生效、响应始终回显 canonical 形式。公开 API 和 CLI 的文件系统/内容操作接受公开作用域resources、user、agent以及根 URIviking://。服务端对用户提交的 URI 进行严格校验见 openviking/core/uri_validation.py 中的validate_viking_uri/validate_request_viking_uri非法作用域、空 URI、权限不足都会抛出InvalidURIError或PermissionDeniedError。完整的目录树示例与 URI 用法见 docs/zh/concepts/04-viking-uri.md。1.3 双层存储AGFS 向量索引OpenViking 将内容存储与索引存储分离存储层职责存储内容AGFS内容存储L0/L1/L2 完整内容、多媒体文件向量库索引存储URI、向量、元数据不存文件内容注AGFS 已重写为 Rust 实现 RAGFS源码位于 crates/ragfs。分层设计带来四点收益职责清晰向量库只检索、AGFS 只存储、内存优化向量库不存文件内容、单一数据源所有内容从 AGFS 读取、独立扩展两层可分别扩容。向量库 Context 集合 schema 包含id、uri、parent_uri、context_type、is_leaf、vector、sparse_vector、abstract、name、description、created_at、active_count等字段索引策略为flat_hybrid混合索引 cosine 距离 int8 量化后端支持local、http、volcengine火山引擎 VikingDB。VikingFS 自动维护内容与向量的一致性rm()同步删除向量记录mv()同步更新向量库中的uri与parent_uri。详见 docs/zh/concepts/05-storage.md。1.4 异步/同步客户端与 QueueFS客户端OpenViking 同时提供 Python HTTP Client 与 Python HTTP Client SDK见 openviking/client 与 sdk/python并在openviking.core.context之上统一了 Context 数据模型Context.to_dict()/from_dict()完成存储与反序列化。QueueFS SQLite 存储后端处理队列以 SQLite 为后端相关实现集中在 openviking/storage/queuefs如queue_manager.py、embedding_msg_converter.py、add_resource_processor.py支撑资源入库、嵌入等异步任务的排队处理。二、资源管理与多模态解析2.1 文本资源管理与自动 L0/L1 生成资源管理支持 Markdown、HTML、PDF 等文本资源入库后自动完成 L0/L1 语义生成与带向量索引的语义搜索并支持资源关联与链接Context.related_uri、内容写入 API、Agent 命名空间管理。L0/L1 的生成由 SemanticProcessor自底向上处理目录文件摘要 → 叶子目录 L1 → 叶子目录 L0 → 父目录 → namespace 根边界子目录 L0 聚合到父目录 L1多模态文件先生成文本摘要再作为普通文件摘要参与所在目录的 L0/L1 生成不会为每个图片/音频/视频创建 per-file sidecar。相关概念见 docs/zh/concepts/06-extraction.md。2.2 多模态解析能力路线图列出的解析器矩阵在 openviking/parse/parsers 下均有对应实现图像 OCR 与解析media/image.py结合 VLM 视觉理解prompt 模板见 openviking/prompts/templates/vision/image_understanding.yaml音频转写Whisper ASRmedia/audio.py视频解析media/相关模块PDF 书签提取PDF 解析器Word / PowerPoint / Excel / EPub / ZIP 解析器anydoc.py及文档类解析器代码文件解析code/code.py配套说明见 openviking/parse/parsers/code/README.md飞书/Lark 文档解析器openviking/parse/feishu_import.py。统一解析入口通过 openviking/parse/parser_router.py 与 openviking/parse/registry.py 按文件类型路由到具体 parserbase_parser.py定义了 parser 基类与通用处理流。三、检索体系从find到search的两阶段链路路线图把检索能力划分为四个层次基本语义搜索find、带意图分析的上下文感知搜索search、基于会话的查询扩展、多供应商重排序流水线。其完整机制记录在 docs/zh/concepts/07-retrieval.md整体流程为查询 → 意图分析 → 层级检索 → Rerank → 结果 ↓ ↓ ↓ TypedQuery 目录递归 精排评分3.1 find() vs search()特性find()search()会话上下文不需要需要意图分析不使用使用 LLM 分析查询数量单一查询0-5 个 TypedQuery延迟低较高适用场景简单查询复杂任务3.2 意图分析IntentAnalyzer实现位于 openviking/retrieve/intent_analyzer.py。IntentAnalyzer输入会话压缩摘要、最近 5 条消息与当前查询输出 0~5 个TypedQuery每个包含重写后的query、context_typeMEMORY/RESOURCE/SKILL、intent、1-5 级priority。查询风格上skill 用动词开头如创建 RFC 文档、resource 用名词短语如RFC 文档模板、memory 用用户XX如用户的代码规范偏好。0 个查询意味着闲聊等无需检索的场景多个查询则覆盖技能 资源 记忆的复合需求。意图分析模型可通过query_planner配置项单独指定未设置时回退到vlm针对特定微调模型还提供了专用 prompt见QUERY_PLANNER_PROMPT_BY_MODEL。3.3 层级检索HierarchicalRetriever核心实现位于 openviking/retrieve/hierarchical_retriever.py。检索流程为按context_type确定根目录MEMORY→viking://~/memories、RESOURCE→viking://resources、SKILL→viking://~/skills→ 全局向量搜索定位起始目录 → 合并起始点并 Rerank 评分 → 优先队列递归搜索 → 转换为MatchedContext。递归搜索采用分数传播final_score score_propagation_alpha * embedding_score (1 - score_propagation_alpha) * parent_score超过阈值则收集目录继续入队递归连续 3 轮 topk 不变即提前收敛。关键常量MAX_CONVERGENCE_ROUNDS 3、GLOBAL_SEARCH_TOPK 10、MAX_PARALLEL_CHILD_SEARCHES 4、DIRECTORY_DOMINANCE_RATIO 1.2retrieval.score_propagation_alpha默认为 1.0仅使用子节点自身分数。3.4 多供应商重排序流水线Rerank 在 THINKING 模式search()默认下对候选精排若 rerank 返回无效结果或 API 调用失败会回退到向量分数。供应商实现位于 openviking/models/rerankOpenAIopenai_rerank.py、LiteLLMlitellm_rerank.py、Coherecohere_rerank.py、Volcenginevolcengine_rerank.py通过 openviking/models/rerank/base.py 的RerankClient统一调度可配置阈值threshold与最大输入 token 数max_input_tokens。四、会话与记忆对话状态、自动记忆提取与 Working Memory V2路线图在会话与记忆标题下列出对话状态追踪、上下文和技能使用追踪、自动记忆提取、使用 LLM 的记忆去重、会话归档和压缩、Working Memory V2 及冷存储归档。会话生命周期创建 → 交互 → 提交。commit()为同步归档 异步后台摘要生成与记忆提取返回task_id供get_task()轮询进度pending/running/completed/failed。API 细节见 docs/zh/concepts/08-session.md。Working Memory V2压缩链路使用ov_wm_v2系列 promptopenviking/prompts/templates/compression/ov_wm_v2.yaml、ov_wm_v2_update.yaml配合会话压缩compressor_v3.py与归档history/archive_*目录实现记忆的持续演进冷存储归档将低频记忆从热路径移出。记忆提取策略可通过memory_policy配置逐项开关self、peer、memory_types、working_memory解析与校验逻辑见 openviking/session/memory_policy.py例如memory_policy.working_memory只支持enabled键其余键会报错字符串布尔值兼容旧行为但会产生FutureWarning。五、技能定义、存储、搜索与 MCP 自动转换技能模块提供技能定义与存储viking://agent/skills/...与viking://~/skills/...、技能搜索与检索以及 MCP 工具自动转换。MCP 工具到技能的转换实现在 openviking/core/mcp_converter.pymcp_to_skill()读取 MCP 工具定义中的name、description、inputSchema生成带 YAML frontmatter 的 Markdown 技能文档含 Parameters 与 Usage 段is_mcp_format()通过是否含inputSchema字段判断输入是否为 MCP 工具格式。技能上下文还会在会话中被注入给 Agent见 openviking/session/skill/session_skill_context_provider.py。六、多租户与安全多租户支持与账户隔离详见 docs/zh/concepts/11-multi-tenant.mdURI 中user、account_id、owner_user_id、owner_space字段在Context中显式建模openviking/core/context.py配合 ACLdocs/zh/concepts/15-acl.md实现跨账户隔离与资源共享。文件和文档加密加密实现位于 openviking/cryptoconfig.py、encryptor.py、providers.py概念说明见 docs/zh/concepts/10-encryption.md。用户级隐私配置 API隐私服务位于 openviking/privacyservice.py、models.py、helpers.py支持技能提取、占位与恢复等细粒度隐私控制见 docs/zh/concepts/13-privacy.md。API Key 认证openviking/server/api_keys 实现配合 openviking/server/auth 的认证体系与 OAuthopenviking/server/oauth。七、配置与供应商可插拔的三类模型提供者路线图强调三类可插拔提供者Embedding、LLM、重排序加上基于 YAML 的配置与安装向导。7.1 Embedding 提供者从 openviking/models/embedder/init.py 可确认完整矩阵供应商实现向量类型OpenAIopenai_embedders.pyDenseVolcenginevolcengine_embedders.pyDense / Sparse / HybridJina AIjina_embedders.pyDenseVoyage AIvoyage_embedders.pyDenseCoherecohere_embedders.pyDenseGoogle Geminigemini_embedders.pyDenseLiteLLMlitellm_embedders.pyDense桥接 OpenRouter、Ollama、vLLM 等MiniMaxminimax_embedders.pyDenseDashScopedashscope_embedders.pyDense本地local_embedders.pyDense本地部署支持 Ollama 等模块还提供FailoverEmbedder故障切换与CompositeHybridEmbedder稠密稀疏组合。LiteLLM 与 Gemini 为可选依赖未安装时对应类置为None。7.2 LLM 与重排序提供者LLM 提供者见 openviking/models 与 openviking_cli/utils/llm.py重排序提供者见 3.4 节。所有配置统一走 YAML 文件配置示例见仓库根目录 examples/ov.conf.example。7.3 安装向导openviking-server init交互式安装向导实现在 openviking_cli/setup_wizard.py引导用户完成模型选择与配置对 macOS/Apple Silicon 初学者的本地 Ollama 部署做了针对性支持内置check_ollama_running、get_ollama_models、ollama_pull_model、start_ollama等工具函数并预设 Codex / Kimi / GLM 等 coding 模型模板。八、Server 与 Client 架构、CLIHTTP ServerFastAPIopenviking/server/app.py路由按领域拆分在 openviking/server/routersresources、filesystem、skills、sessions、retrieval、system、admin 等对应 docs/zh/api 各接口文档。内置 MCP 端点openviking/server/mcp_endpoint.py让任何 MCP 客户端可直接消费 OpenViking 工具面。Web 控制台web-studioReact/TypeScript 实现。Python HTTP Client / SDKopenviking/client与 sdk/python。Rust CLIov命令crates/ov_cli48 个 Rust 源文件命令组约 40 个覆盖隐私、搜索ov find/ov search、会话、资源ov add-resource/ov add-memory/ov add-skill、文件系统ov ls/ov rm与管理操作并带TUI 文件系统浏览器。按 docs/zh/agent-integrations/16-capability-reference.md 的能力矩阵ov是唯一同时支持find/search显式检索、三类内容写入与直接删除的完整工具面。九、Bot 集成与生态插件VikingBot 框架bot/vikingbotagent、channels、bus、cron、hooks 等模块配套文档见 docs/zh/concepts/15-vikingbot.md。飞书/Lark 频道bot/vikingbot/channels中的 feishu/lark 实现。Telegram 频道bot/vikingbot/channels中的 telegram 实现。OpenClaw 插件编程 Agent 上下文引擎examples/openclaw-plugin提供memory_recall、ov_search、memory_store、add_skill等 15 个工具并支持 ContextEngine 压缩接管。Claude Code 记忆插件examples/claude-code-memory-plugin。Codex 记忆插件examples/codex-memory-plugin。生态上还包含 cursor、trae、zcode、opencode、pi、dsh、hermes、Open WebUI、LangChain 等集成examples 与 integrationsMCP 型 harness 的工具面由服务端统一定义、经代理连接~/.openviking/ovcli.conf凭据后获得一致体验。十、可观测性与部署Prometheus 指标指标体系见 openviking/metrics27 个 collector、14 个 datasource、核心 core/ 与 exporters/并配套 Grafana 仪表盘examples/grafana。OpenTelemetry 链路追踪openviking/telemetry14 个模块。HTTP 可观测性中间件openviking/observability/http_observability_middleware.py 及日志链路桥接log_trace_bridge.py。Docker 镜像与 Docker Compose根目录 Dockerfile 与 docker-compose.yml入口脚本见 docker/openviking-entrypoint.sh。Kubernetes Helm Chartdeploy/helm/openviking8 个 YAML 模板 公共 tpl另有 examples/k8s-helm。云端 VikingDB 支持向量库后端volcengine见 openviking/storage/vikingdb_manager.py 与 docs/zh/concepts/05-storage.md。十一、未来计划与演进方向路线图公开了三个明确的未来方向欢迎通过 issue 提出建议与反馈上下文管理上下文修改对上层的传导更新parent-bubbling 的自动化与一致性上下文的版本管理和回滚参考 git 思路。仓库中已有相关设计文档沉淀docs/design/freshness-aware-parent-bubbling-design.md 与 docs/design/git-version-control-design.md且 L0/L1 sidecar 的freshness元数据total_entries/sampled_entries/unsampled_entries/pending_child_changes与稳定采样机制已为传导更新的节流合并、阈值或时间窗口铺路见 docs/zh/concepts/03-context-layers.md 中的 TODO 说明。分布式存储后端在现有 localfs/s3fs 单后端与多写primary/backup模式之上进一步演进相关概念见 docs/zh/concepts/14-multi-write-storage.md。生态更多 Agent 框架适配器进一步扩大 harness 覆盖面。十二、贡献路线图同时是贡献指引OpenViking 欢迎社区贡献以帮助实现这些目标贡献规范见仓库根目录 CONTRIBUTING_CN.md。无论是实现未来计划中的上下文传导更新与版本管理、探索分布式存储后端还是新增 Agent 框架适配器都可以从 docs/zh 各概念文档与 tests 中已有的测试用例入手理解现状后再动手。延伸阅读本文所涉概念均有对应文档可深入架构概述、上下文层级、Viking URI、存储架构、检索机制、会话管理以及完整 API 参考 docs/zh/api/01-overview.md。【免费下载链接】OpenVikingSelf-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.项目地址: https://gitcode.com/GitHub_Trending/op/OpenViking创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考