openviking integration

https://www.openviking.ai/

Installing with uv tool

uv tool install openviking --python 3.12

In theory, once this is installed you can already use Ov and OpenViking Server. You can also hook it into OpenCode — OpenCode needs a plugin installed. But right now I need to sort out the embedding model and the VLM model.
For VLM I can use Xiaomi’s model.
For the embedding model, let’s go with the one bundled with Agent Plan.

Embedding:

  • embedding model id: doubao-embedding-vision
  • baseURL: https://ark.cn-beijing.volces.com/api/plan/v3
    VLM:
  • Opencode Go’s mimo2.5

While putting this documentation together, I picked up a few new things:

  • Pythons managed by uv only take up a single shared storage footprint
  • uv tool install installs globally, and each tool uses its own Python interpreter, independent of the others
  • markitdown could actually have been installed with uv tool install too, instead of hunting down a path and installing it with uv sync

Alright, let’s start installing openviking.
Recording the specific steps:

Installing ov

uv tool install openviking --upgrade

Installed 4 executables: openviking, openviking-server, ov, vikingbot

Installation done. You can now use the client command ov (openviking is its alias) and the server command openviking-server.

Configuration

openviking-server init

I ran its built-in configuration. Then I noticed the URL it configured for Volcano Engine was wrong, because I’m on an Agent plan. So I went into the config file and changed it by hand.

Then running openviking-server doctor threw a socks error (because I sometimes have a proxy enabled in my shell):

 openviking-server doctor

OpenViking Doctor

  Config:        PASS  /Users/rhett/.openviking/ov.conf
  Python:        PASS  3.14.2 (>= 3.10 required)
  Native Engine: PASS  variant=native
  AGFS:          PASS  AGFS SDK 0.1.7
13:05:11 - LiteLLM:WARNING: get_model_cost_map.py:264 - LiteLLM: Failed to fetch remote model cost map from https://raw.githubusercontent.com/BerriAI/litellm/main/model_prices_and_context_window.json: Using SOCKS proxy, but the 'socksio' package is not installed. Make sure to install httpx using `pip install httpx[socks]`.. Falling back to local backup.
  Embedding:     FAIL  volcengine/doubao-embedding-vision api_base=https://ark.cn-beijing.volces.com/api/plan/v3 dimension=1024 (invalid embedding config: Using SOCKS proxy, but the 'socksio' package is not installed. Make sure to install httpx using `pip install httpx[socks]`.)
                 Fix: Fix embedding.dense provider/model/api_base/dimension in ov.conf
  VLM:           PASS  openai/mimo-v2.5
  Ollama:        PASS  not configured
  VikingBot:     PASS  VikingBot aligned with dev OpenViking auth
  Disk:          PASS  2164.6 GB free in /Users/rhett/.openviking/data

  1 check(s) failed. See above for fix suggestions.

But I’m not sure how to fix this — since I installed ov with UV tool install, how do I install httpx[socks] for ov’s dependencies?

After looking it up, I found you can use --with.

Reinstalled with the extra dependency:

uv tool install openviking --reinstall --with "httpx[socks]"

This time the check passed.


at 13:09 ❯ openviking-server doctor

OpenViking Doctor

  Config:        PASS  /Users/rhett/.openviking/ov.conf
  Python:        PASS  3.14.2 (>= 3.10 required)
  Native Engine: PASS  variant=native
  AGFS:          PASS  AGFS SDK 0.1.7
  Embedding:     PASS  volcengine/doubao-embedding-vision api_base=https://ark.cn-beijing.volces.com/api/plan/v3 dimension=1024 probe ok (dimension=1024)
  VLM:           PASS  openai/mimo-v2.5
  Ollama:        PASS  not configured
  VikingBot:     PASS  VikingBot aligned with dev OpenViking auth
  Disk:          PASS  2164.5 GB free in /Users/rhett/.openviking/data

  All checks passed.

Running the server

And of course it errored out:

openviking-server

Traceback (most recent call last):
  File "/Users/rhett/.local/bin/openviking-server", line 10, in <module>
    sys.exit(main())
             ~~~~^^
  File "/Users/rhett/.local/share/uv/tools/openviking/lib/python3.14/site-packages/openviking_cli/server_bootstrap.py", line 104, in main
    _real_main()
    ~~~~~~~~~~^^
  File "/Users/rhett/.local/share/uv/tools/openviking/lib/python3.14/site-packages/openviking/server/bootstrap.py", line 282, in main
    app = create_app(config)
  File "/Users/rhett/.local/share/uv/tools/openviking/lib/python3.14/site-packages/openviking/server/app.py", line 716, in create_app
    from openviking.server.mcp_endpoint import create_mcp_app
  File "/Users/rhett/.local/share/uv/tools/openviking/lib/python3.14/site-packages/openviking/server/mcp_endpoint.py", line 27, in <module>
    from mcp.server.fastmcp import FastMCP
ModuleNotFoundError: No module named 'mcp.server.fastmcp'

$ uv tool uninstall openviking && uv tool install openviking --python 3.12 --with "httpx[socks]" 2>&1 | tail -15

Downgrading to 3.12 still didn’t work,

$ uv tool install openviking --python 3.12 --with "httpx[socks]" --with "mcp<2" --reinstall 2>&1 | tail -6

The cause of the mcp error (unrelated to httpx[socks]):

  • openviking declares a dependency on mcp>=1.27.0 with no upper bound, so when uv resolved it, it grabbed the freshly released mcp 2.0.0
  • mcp 2.0 is a breaking rewrite that removed the mcp.server.fastmcp module, while openviking 0.4.11 still uses the old API
    Fix: reinstall and pin mcp<2:
uv tool install openviking --python 3.12 --with "httpx[socks]" --with "mcp<2" --reinstall

Two key choices:

  1. Python 3.12 (not 3.14): mcp 1.x doesn’t support 3.14, and 3.14 would force uv to use mcp 2.0
  2. --with "mcp<2": explicitly locking mcp to 1.x — this is the core fix

It starts successfully now, and you can open http://localhost:1933/ in the browser.

Configuring the OpenCode integration

bash <(curl -fsSL https://ovrelease.tos-cn-beijing.volces.com/memory-plugin-shared/install.sh) --harness opencode
# 输入 http://127.0.0.1:1933；如果启用了认证，再输入 API Key

at 13:31 ❯ bash <(curl -fsSL https://ovrelease.tos-cn-beijing.volces.com/memory-plugin-shared/install.sh) --harness opencode
Language / 语言
   ( ) English
 > (•) 中文
   ↑/↓ move · 1-9 jump · enter confirm

1. 环境检查
==> OS: Darwin
==> 已选择： opencode
安装源模式
   ( ) GitHub  （默认；支持远程更新）
 > (•) 火山引擎 TOS 镜像（无法访问 GitHub 时使用）
   ↑/↓ 移动 · 数字直选 · 回车确认

2. OpenViking 凭据配置 (/Users/rhett/.openviking/ovcli.conf)
==> 未找到已有配置。
连接到哪个 OpenViking 服务？
   ( ) 自建 / 本地  [http://127.0.0.1:1933]
   ( ) 火山引擎 OpenViking 云服务  [api.vikingdb.cn-beijing.volces.com]
 > (•) 自定义 URL / 保持当前  [http://127.0.0.1:1933]
   ↑/↓ 移动 · 数字直选 · 回车确认
??  服务地址 [http://127.0.0.1:1933]:
??  API key（本地免鉴权模式请直接回车）:
==> 已更新： url: — -> http://127.0.0.1:1933
==> 凭据已就绪： /Users/rhett/.openviking/ovcli.conf
==> 之后可重跑本安装脚本重新配置。
==> 安装源模式： archive (渠道: tos)

3. Marketplace 归档
==> 下载归档
==>   https://ovrelease.tos-cn-beijing.volces.com/releases/latest/memory-plugin-marketplace.zip

4. OpenCode 插件
==> OpenCode 文件插件已安装： /Users/rhett/.config/opencode/plugins/openviking

5. 安装校验
==> opencode: openviking-memory 看起来已安装
==> opencode: MCP server 已注册

完成
==> 凭据： /Users/rhett/.openviking/ovcli.conf
==> OpenCode: @openviking/opencode-plugin

~/Downloads took 42s
at 13:32 ❯

Restart Opencode for it to take effect; you can see it in /status.
Subsequent chats will automatically be hooked and written into openviking as memories.

Setting up the server to auto-start on boot

Manually create ~/Library/LaunchAgents/com.openviking.server.plist:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.openviking.server</string>

    <key>ProgramArguments</key>
    <array>
        <string>/Users/rhett/.local/bin/openviking-server</string>
    </array>

    <key>RunAtLoad</key>
    <true/>

    <key>KeepAlive</key>
    <true/>

    <key>WorkingDirectory</key>
    <string>/Users/rhett/.openviking</string>

    <key>StandardOutPath</key>
    <string>/Users/rhett/.openviking/openviking.log</string>

    <key>StandardErrorPath</key>
    <string>/Users/rhett/.openviking/openviking.err.log</string>
</dict>
</plist>

Configuring the hermes integration

Original state:

at 13:55 ❯ hermes memory status

Memory status
────────────────────────────────────────
  Built-in:  always active
  Provider:  (none — built-in only)

  Installed plugins:
    • byterover  (API key / local)
    • hindsight  (API key / local)
    • holographic  (local)
    • honcho  (API key / local)
    • mem0  (API key / local)
    • openviking  (API key / local)
    • retaindb  (API key / local)
    • supermemory  (requires API key)

Changed to hook into openviking:

hermes memory setup
# 选择 openviking，然后输入 endpoint / API Key
hermes memory status

Hands-on impressions

Whether I’m chatting with OpenCode in Paseo or talking to Hermes directly in the terminal, at the end of the conversation it automatically files away some memories — extracting and archiving them. At the same time the session is saved in full into the database, which is pretty convenient.

But docs like Identity and Soul aren’t synced over from Hermes in full — instead it automatically extracts some key information as needed.

Right now the thing I can really feel is that Hermes and Open Code can share memories with each other, whereas before they each kept their own. Of course, if I really wanted to pull from one into the other before, I could do it too — it’s all stored on local disk anyway, just at different paths. But now there’s unified management, which is also fine. And with unified management, it embeds every conversation, which is essentially a fully automated retrospective. That’s a bit more scientific than just storing raw conversation records.

The biggest benefit I feel so far is that the various tasks I scatter across Open Code during the day can be reviewed and summarized in one sentence at night.

References
License

Licensed under CC BY-NC-SA 4.0. Please credit the source when reposting.

Join the discussion