OpenViking v0.4.21 教程：先验证本地上下文库
OpenViking 把 Agent 的资源、长期记忆和技能放进 viking:// 虚拟文件系统。你可以像检查目录一样查看已存内容，再用搜索找到相关上下文。第一次测试只导入公开小样本，先确认数据流、召回和删除流程。
1. 安装并只启动本地服务
uv tool install openviking==0.4.21
openviking-server init
openviking-server doctor
openviking-server
初始化向导会写入 ~/.openviking/ov.conf。先让服务保持在 127.0.0.1:1933，不要直接把无认证端口映射到公网。另开终端检查健康状态：
curl http://127.0.0.1:1933/health
2. 先画清模型的数据边界
自托管服务器仍需要 embedding 模型和 VLM。若选择 OpenAI、火山引擎、Kimi 或 GLM API，待解析内容或查询会进入对应服务边界；使用本地 Ollama 等模型可减少外发。测试时使用独立凭证、无敏感文档，并记录提供方、区域、日志和保留政策。
3. 导入一份公开小文档
ov status
ov add-resource ./samples/public-note.md
ov task status TASK_ID
导入是后台任务。拿到 task_id 后要等状态完成，不能把“请求已接受”当成“索引已可用”。导入远程 Git 或网页时，是服务端访问目标地址，还要考虑内网地址、凭证和恶意内容。
4. 分别检查目录、原文和搜索
ov ls viking://resources/
ov tree viking://resources/ -L 3
ov find "样本文档里的唯一短语"
ov grep "唯一短语" --uri viking://resources/
先用 tree 找到实际 URI，再 read 原文和生成摘要。find 的命中要回到原文核对；目录摘要由模型生成，可能遗漏或写错事实。把召回结果、URI 和源文件位置一并记录。
5. 再接 Agent 记忆
自动捕获会把对话或工具轨迹变成长期记忆。接入 Claude、Codex、OpenClaw 等插件前，先测试用户隔离、错误记忆更正、单条删除、账号删除和备份恢复。API key 按用户与管理权限分开，root key 只用于管理。
6. 升级 v0.4.21 前读迁移项
MCP search 在 list 模式下会拒绝一批只属于 context 模式的参数；Docker 默认工作目录改到持久化目录；旧 Codex 模型配置不会自动改写；远程 VikingDB 对超长字符串会截断。生产升级前先备份，再在副本上跑现有查询和权限用例。
与 Mem0 对比
Mem0 的开源 SDK 以 add、search、get 等记忆 API 为中心，也提供托管平台。OpenViking 把资源、记忆和技能统一成可浏览的 viking:// 目录，并带服务端、Studio 和文件式命令。应用只要简洁的用户记忆 API 时先评估 Mem0；需要目录结构、资源摄取和技能统一管理时评估 OpenViking。两者都要单独核对开源版与托管版的数据边界。
这里仅补原教程没有展开的事实和边界。安装命令与操作步骤仍以前文为准。
先判断这个项目是否适合你
适合谁用
适合需要跨会话记忆、可浏览知识目录或多 Agent 共享上下文的自托管项目。它不是无需模型的普通文件管理器：导入与检索质量依赖所选 embedding/VLM，长期记忆还会保存对话衍生信息。启用自动捕获前要定义用户隔离、删除、保留和审计规则。
采用建议
适合需要跨会话记忆、可浏览知识目录或多 Agent 共享上下文的自托管项目。它不是无需模型的普通文件管理器：导入与检索质量依赖所选 embedding/VLM，长期记忆还会保存对话衍生信息。启用自动捕获前要定义用户隔离、删除、保留和审计规则。采用前需要核对：主项目是 AGPL-3.0，网络服务和修改分发要先评估许可证义务。
原教程未展开的系统信息
核心功能
可检查的上下文文件系统
资源、记忆和技能都有 viking:// URI，可用 ls、tree、read、write、find 和 grep 浏览，不必把向量库当作不可见黑盒。
服务端与多客户端
主包提供服务端和 Python 运行时；另有 Rust/npm CLI、Python/Go/TypeScript SDK、HTTP API、Studio 与 MCP/插件集成。
记忆与资源摄取
可导入文件、网页和代码仓库，生成目录摘要，并把会话经验写入长期记忆；远程来源由服务端访问。
权限与运维入口
共享资源支持 ACL、用户和 API key；v0.4.21 继续修复路径锁、队列隔离、状态归属和远程 VikingDB 行为。
技术栈和运行条件
语言
Python 主运行时，Rust CLI，Python/Go/TypeScript SDK
框架
FastAPI/Uvicorn 服务；可配置 embedding 模型与 VLM
关键依赖
- 主包 Python 3.10+
- openviking 0.4.21
- 独立 Python SDK 0.1.12 支持 Python 3.8+
- 可选 Node.js 的 @openviking/cli
- AGPL-3.0 主项目
运行环境
可自托管或连接火山引擎托管端点；自托管仍需模型服务或本地模型。Docker 要持久化 /app/.openviking
常见问题
OpenViking v0.4.21 完全免费吗？
主项目源码采用 AGPL-3.0，可自行部署。embedding、VLM、托管 OpenViking 或火山引擎服务可能另有费用，应按实际提供方核对价格与数据政策。
OpenViking 会把记忆发送到云端吗？
取决于配置。服务器可以自托管，但若选择 OpenAI、火山引擎、Kimi、GLM 等 API，相关内容会进入对应服务边界；本地模型可减少外发。
为什么主包要求 Python 3.10，而 SDK 支持 3.8？
它们是不同发布物。openviking 主包包含本地服务器和完整功能，pyproject 要求 Python 3.10+；独立 openviking-sdk 0.1.12 只是连接现有服务器的轻量客户端，已把下限降到 3.8。
升级 OpenViking v0.4.21 要注意什么？
要检查 MCP search 的模式参数、Docker 工作目录、旧 Codex 模型配置和远程 VikingDB 字段长度。发布说明还给出了回滚到 v0.4.20 的建议。