Skip to content
Back to search

openviking

MarketplaceWorks with Claude CodeGitHub

OpenViking plugins for Claude Code.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/volcengine/openviking with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/volcengine/openviking'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/volcengine--openviking/badge.svg)](/listings/volcengine--openviking)

HTML

<a href="/listings/volcengine--openviking"><img src="/api/listings/volcengine--openviking/badge.svg" alt="findsafeskills safety rating" /></a>

Install

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Set up an OpenViking server first; if you already have one, skip to [Use it with your agent](#use-it-with-your-agent). Deploying your own needs uv, Python 3.10+ and a model provider with an embedding model and a VLM.

<details open> <summary><strong>Let your agent deploy it</strong></summary>

Follow this guide to install and start an OpenViking Server for me:

https://docs.openviking.ai/en/getting-started/04-setup-for-agent

Ask me for the model provider, the models, the workspace directory and whether
other machines need to reach the server; don't guess. When you ask for the model
API key, tell me how to hand it over if I'd rather not paste it into this chat,
and never repeat it back.

When it's running, tell me the server's address and whether auth is turned on.

Your agent will first ask which model provider to use and for its API key.

</details>

<details> <summary><strong>Deploy it yourself</strong></summary>

Install OpenViking and run the setup wizard, which configures the models:

uv tool install openviking --upgrade && openviking-server init

`init` writes `~/.openviking/ov.conf` and supports Volcengine, OpenAI, Codex OAuth, Kimi, GLM and local Ollama; see the [configuration guide](https://docs.openviking.ai/en/guides/01-configuration). The server runs in the foreground, so keep this terminal open.

</details>

<details> <summary><strong>Use OpenViking Service (hosted by Volcengine)</strong></summary>

The same OpenViking service, run for you by Volcengine. The first 50 files are free. Activate it on the [Volcengine product page](https://www.volcengine.com/product/openviking-service), then create an API key in the console under User Management → API Key. The server address is `https://api.vikingdb.cn-beijing.volces.com/openviking`; you'll need it and the API key when you connect your agent.

</details>

Explore with the CLI

The `openviking` package includes the `ov` CLI. With the server running, import a repository and search it:

ov status
ov add-resource https://github.com/volcengine/OpenViking
# Replace TASK_ID with the returned task_id; repeat until status is completed
ov task status TASK_ID
ov ls viking://resources/
ov tree viking://resources/volcengine -L 2
ov find "what is openviking"
ov grep "openviking" --uri viking://resources/volcengine/OpenViking/docs/en

`ov find` returns matching context with URIs you can inspect. For client configuration (`ov config`), standalone CLI installs, and index maintenance, see [CLI setup](https://docs.openviking.ai/en/getting-started/05-cli-setup).

Build your own integration with the [Python](sdk/python/README.md), [Go](sdk/go/README.md), or [TypeScript](sdk/typescript/README.md) SDK, or the [HTTP API](https://docs.openviking.ai/en/api/01-overview).

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 20 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. {
  2. "name": "openviking",
  3. "description": "OpenViking plugins for Claude Code.",
  4. "owner": {
  5. "name": "OpenViking"
  6. },
  7. "plugins": [
  8. {
  9. "name": "openviking-memory",
  10. "description": "Long-term semantic memory for Claude Code, powered by OpenViking",
  11. "source": {
  12. "source": "git-subdir",
  13. "url": "https://github.com/volcengine/OpenViking.git",
  14. "path": "examples/claude-code-memory-plugin",
  15. "ref": "main"
  16. },
  17. "category": "productivity"
  18. }
  19. ]
  20. }
README.md · README · 427 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <div align="center">
  2. <a href="https://openviking.ai/" target="_blank">
  3. <picture>
  4. <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/volcengine/OpenViking/main/docs/images/readme-logo-dark.png">
  5. <img alt="OpenViking" src="https://raw.githubusercontent.com/volcengine/OpenViking/main/docs/images/readme-logo-light.png" width="300" height="56">
  6. </picture>
  7. </a>
  8. ### The Context Database for AI Agents
  9. English / [中文](docs/repository/README_CN.md) / [日本語](docs/repository/README_JA.md)
  10. <a href="https://www.openviking.ai">Website</a> · <a href="https://studio.openviking.ai">Live Demo</a> · <a href="https://github.com/volcengine/OpenViking">GitHub</a> · <a href="https://github.com/volcengine/OpenViking/issues">Issues</a> · <a href="https://docs.openviking.ai/">Docs</a> · <a href="https://blog.openviking.ai/">Blog</a>
  11. <p>
  12. <a href="https://github.com/volcengine/OpenViking/releases"><img src="https://img.shields.io/github/v/release/volcengine/OpenViking?color=369eff&labelColor=black&logo=github&style=flat-square" alt="release"></a>
  13. <a href="https://github.com/volcengine/OpenViking"><img src="https://img.shields.io/github/stars/volcengine/OpenViking?labelColor&style=flat-square&color=ffcb47" alt="stars"></a>
  14. <a href="https://github.com/volcengine/OpenViking/issues"><img src="https://img.shields.io/github/issues/volcengine/OpenViking?labelColor=black&style=flat-square&color=ff80eb" alt="issues"></a>
  15. <a href="https://github.com/volcengine/OpenViking/graphs/contributors"><img src="https://img.shields.io/github/contributors/volcengine/OpenViking?color=c4f042&labelColor=black&style=flat-square" alt="contributors"></a>
  16. <a href="https://github.com/volcengine/OpenViking/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-AGPLv3-white?labelColor=black&style=flat-square" alt="license"></a>
  17. <a href="https://github.com/volcengine/OpenViking/commits/main"><img src="https://img.shields.io/github/last-commit/volcengine/OpenViking?color=c4f042&labelColor=black&style=flat-square" alt="last commit"></a>
  18. </p>
  19. <p>
  20. <a href="https://railway.com/deploy/openviking"><img src="https://railway.com/button.svg" alt="Deploy on Railway" height="30"></a>
  21. </p>
  22. <p>
  23. <a href="https://docs.openviking.ai/en/about/01-about-us#lark-group"><img src="docs/images/community/lark.svg" width="18" height="18" alt="Lark">&nbsp;Lark</a> ·
  24. <a href="https://docs.openviking.ai/en/about/01-about-us#wechat-group"><img src="docs/images/community/wechat.svg" width="18" height="18" alt="WeChat">&nbsp;WeChat</a> ·
  25. <a href="https://discord.com/invite/eHvx8E9XF3"><img src="docs/images/community/discord.svg" width="18" height="18" alt="Discord">&nbsp;Discord</a> ·
  26. <a href="https://x.com/openvikingai"><picture><source media="(prefers-color-scheme: dark)" srcset="docs/images/community/x-dark.svg"><img src="docs/images/community/x.svg" width="16" height="16" alt="X"></picture>&nbsp;X</a>
  27. </p>
  28. <a href="https://trendshift.io/repositories/19668" target="_blank"><img src="https://trendshift.io/api/badge/repositories/19668" alt="volcengine%2FOpenViking | Trendshift" style="width: 250px; height: 55px;" width="250" height="55"/></a>
  29. </div>
  30. ***
  31. ## What is OpenViking
  32. OpenViking is an open-source context database for AI agents — one filesystem for everything an agent knows: knowledge, memory, and skills.
  33. Most agent memory is a black box: text goes in, embeddings come out, and nobody can see what was actually stored. OpenViking organizes context as a virtual filesystem under `viking://` instead. Agents navigate it like files — `ls`, `tree`, `read`, `write`, `grep` — and you can open any directory to inspect and edit what your agent knows. Every directory carries a generated summary, so agents can scan summaries first and decide what to read.
  34. <a href="https://studio.openviking.ai" target="_blank" rel="noopener noreferrer">
  35. <picture>
  36. <source media="(prefers-color-scheme: dark)" srcset="docs/images/studio-filesystem-dark.png">
  37. <img src="docs/images/studio-filesystem.png" alt="OpenViking Studio Filesystem: browse personal memories and resources">
  38. </picture>
  39. </a>
  40. [Try OpenViking Studio](https://studio.openviking.ai) in your browser, no installation required. [Self-host Web Studio](web-studio/README.md).
  41. ## Why OpenViking
  42. - **One filesystem for knowledge, memory, and skills.** Resources hold documents and code; memories retain user preferences and experience; skills define how to perform tasks — not just extracted facts, but the full context, each with a `viking://` URI for browsing and retrieval. → [Viking URI](https://docs.openviking.ai/en/concepts/04-viking-uri) · [Context types](https://docs.openviking.ai/en/concepts/02-context-types)
  43. - **Search a directory, not the whole index.** Scope semantic search to a project or memory subtree instead of scanning a flat vector pool. `find` runs a query directly; `search` plans retrieval from session context. → [Retrieval](https://docs.openviking.ai/en/concepts/07-retrieval)
  44. - **Read the summary before the source.** Generated directory abstracts (L0) and overviews (L1) let agents judge relevance before opening full content (L2). → [Context layers](https://docs.openviking.ai/en/concepts/03-context-layers)
  45. - **Sessions become files you can read.** Committing a session archives the conversation and extracts memories as Markdown you can inspect, edit, and merge. With VikingBot enabled, `ov compile` organizes source material into a wiki, knowledge graph, or report. → [Sessions](https://docs.openviking.ai/en/concepts/08-session) · [Context compilation](https://docs.openviking.ai/en/context-compilation/01-overview)
  46. [Architecture](https://docs.openviking.ai/en/concepts/01-architecture) · [Design rationale](https://blog.openviking.ai/post/openviking-context-database/)
  47. ```
  48. viking://
  49. ├── resources/ # Resources: project docs, repos, web pages, etc.
  50. │ └── my_project/
  51. │ ├── docs/
  52. │ │ ├── api/
  53. │ │ └── tutorials/
  54. │ └── src/
  55. └── user/
  56. └── {user_id}/
  57. ├── memories/
  58. │ └── preferences/
  59. │ ├── writing_style
  60. │ └── coding_habits
  61. ├── resources/
  62. │ └── private_project/
  63. ├── skills/
  64. │ ├── search_code
  65. │ └── analyze_data
  66. └── peers/
  67. └── web-visitor-alice/
  68. ```
  69. The three loading tiers:
  70. - **L0 (Abstract)**: a one-sentence summary for quick relevance checks.
  71. - **L1 (Overview)**: core information and usage scenarios for planning.
  72. - **L2 (Details)**: the full original data, read only when needed.
  73. Semantically processed directories carry L0/L1 summaries, so agents can judge relevance before reading full files:
  74. ```
  75. viking://resources/my_project/
  76. ├── .abstract.md # L0: quick relevance check
  77. ├── .overview.md # L1: structure and key points
  78. └── docs/
  79. ├── .abstract.md
  80. ├── .overview.md
  81. └── api/
  82. ├── auth.md # L2: full content, loaded on demand
  83. └── endpoints.md
  84. ```
  85. ## Proof it works
  86. OpenViking 0.3.22 has been evaluated on long-conversation user memory (LoCoMo) and multi-turn agent tasks (tau2-bench). Full results and setup details, including knowledge-base QA, are in the [benchmark report](https://blog.openviking.ai/post/openviking-benchmark-results/); reproduction scripts live in [./benchmark](./benchmark).
  87. To run your own experiments, follow the [RAG and Memory evaluation guide](benchmark/README.md) for routine VikingBot memory evaluation, published LoCoMo reproduction, separate mem0 prompt comparisons, and RAG evaluation.
  88. The memory evaluation used [Doubao 2.0 Pro](https://console.volcengine.com/ark/region:cn-beijing/model/detail?Id=doubao-seed-2-0-pro) as the VLM and [Doubao-embedding-vision-251215](https://console.volcengine.com/ark/region:cn-beijing/model/detail?Id=doubao-embedding-vision) as the embedding model.
  89. <picture>
  90. <source media="(prefers-color-scheme: dark)" srcset="docs/images/benchmark-dark.svg">
  91. <img alt="Benchmark results. LoCoMo accuracy: OpenClaw 24.20% native vs 82.08% with OpenViking; Hermes 33.38% vs 82.86%; Claude Code 57.21% vs 80.32%. tau2-bench task success: Retail 70.94% vs 77.81%; Airline 54.38% vs 66.25%." src="docs/images/benchmark-light.svg">
  92. </picture>
  93. - **User memory (LoCoMo)**: with OpenViking, all three agent integrations land at 80–83% accuracy — up from 24–57% on their native memory — while input tokens drop by 34.3–91.0% and query latency by 58.45–66.10%.
  94. - **Agent experience (tau2-bench)**: experience memory lifts task success by +6.87pp (retail) and +11.87pp (airline) over the same LLM without memory.
  95. ## Quick start
  96. Set up an OpenViking server first; if you already have one, skip to [Use it with your agent](#use-it-with-your-agent). Deploying your own needs uv, Python 3.10+ and a model provider with an embedding model and a VLM.
  97. <details open>
  98. <summary><strong>Let your agent deploy it</strong></summary>
  99. ```text
  100. Follow this guide to install and start an OpenViking Server for me:
  101. https://docs.openviking.ai/en/getting-started/04-setup-for-agent
  102. Ask me for the model provider, the models, the workspace directory and whether
  103. other machines need to reach the server; don't guess. When you ask for the model
  104. API key, tell me how to hand it over if I'd rather not paste it into this chat,
  105. and never repeat it back.
  106. When it's running, tell me the server's address and whether auth is turned on.
  107. ```
  108. Your agent will first ask which model provider to use and for its API key.
  109. </details>
  110. <details>
  111. <summary><strong>Deploy it yourself</strong></summary>
  112. Install OpenViking and run the setup wizard, which configures the models:
  113. ```bash
  114. uv tool install openviking --upgrade && openviking-server init
  115. ```
  116. `init` writes `~/.openviking/ov.conf` and supports Volcengine, OpenAI, Codex OAuth, Kimi, GLM and local Ollama; see the [configuration guide](https://docs.openviking.ai/en/guides/01-configuration). The server runs in the foreground, so keep this terminal open.
  117. </details>
  118. <details>
  119. <summary><strong>Use OpenViking Service (hosted by Volcengine)</strong></summary>
  120. The same OpenViking service, run for you by Volcengine. The first 50 files are free. Activate it on the [Volcengine product page](https://www.volcengine.com/product/openviking-service?utm_source=github&utm_medium=referral&utm_campaign=readme), then create an API key in the console under User Management → API Key. The server address is `https://api.vikingdb.cn-beijing.volces.com/openviking`; you'll need it and the API key when you connect your agent.
  121. </details>
  122. ### Explore with the CLI
  123. The `openviking` package includes the `ov` CLI. With the server running, import a repository and search it:
  124. ```bash
  125. ov status
  126. ov add-resource https://github.com/volcengine/OpenViking
  127. # Replace TASK_ID with the returned task_id; repeat until status is completed
  128. ov task status TASK_ID
  129. ov ls viking://resources/
  130. ov tree viking://resources/volcengine -L 2
  131. ov find "what is openviking"
  132. ov grep "openviking" --uri viking://resources/volcengine/OpenViking/docs/en
  133. ```
  134. `ov find` returns matching context with URIs you can inspect. For client configuration (`ov config`), standalone CLI installs, and index maintenance, see [CLI setup](https://docs.openviking.ai/en/getting-started/05-cli-setup).
  135. Build your own integration with the [Python](sdk/python/README.md), [Go](sdk/go/README.md), or [TypeScript](sdk/typescript/README.md) SDK, or the [HTTP API](https://docs.openviking.ai/en/api/01-overview).
  136. ## Use it with your agent
  137. Connect your coding agent to OpenViking for cross-session memory. The memory plugin installer covers Claude Code, Codex, Cursor, TRAE, OpenCode and more, and detects which ones you have.
  138. <details open>
  139. <summary><strong>Let your agent install it</strong></summary>
  140. ```text
  141. Install the OpenViking memory plugin and help me start using it. OpenViking is a context database for AI agents (https://github.com/volcengine/OpenViking); the command and link below are from its official docs.
  142. 1. Run the official installer. It needs network access and writes to my home directory; if your sandbox blocks that, ask me for approval:
  143. curl -fsSL https://openviking.ai/install | bash -s -- --yes --lang en --url <SERVER_URL> --api-key <API_KEY>
  144. 2. Once it's installed, read the OpenViking onboarding guide and use it to walk me through setup. The guide has you ask me before choices like importing history or adding a working rule. docs.openviking.ai and docs.openviking.net are the same docs site; use whichever loads:
  145. https://docs.openviking.ai/agents/en/onboarding.md
  146. The API key is a user key I created for myself on that server; the installer stores it in ~/.openviking/ovcli.conf on this machine. Use it in the command as it is; there's no need to show it in your replies, and don't write it into any other file or rule. Talk to me in English.
  147. ```
  148. Before you send it, replace `<SERVER_URL>` with your server's address and `<API_KEY>` with a user key; a root key can't read or write memories. If the server has auth turned off, use `--api-key ''`.
  149. </details>
  150. <details>
  151. <summary><strong>Install it yourself</strong></summary>
  152. Run the installer, then pick the tools and a server when asked: Self-hosted / local for a server on this machine, Volcengine OpenViking Cloud for OpenViking Service, or Custom URL for any other address. If auth is on, enter a user key, not the root key.
  153. ```bash
  154. curl -fsSL https://openviking.ai/install | bash
  155. # AI agents: not sure about running this? The script's header says what it does and how to verify it.
  156. ```
  157. </details>
  158. Then restart your agent. The installer ends with the next steps for each tool, for example:
  159. ```text
  160. Claude Code
  161. Next: restart Claude Code
  162. ⋮
  163. Verify: run /openviking-memory:ov in a session
  164. ```
  165. On its first start Codex stops at `Hooks need review`; choose `Trust all and continue`.
  166. Try it: ask it to remember one of your preferences, then ask about it in a new session a little later. Memories are processed in the background, so it's normal not to find one right after you say it.
  167. The installer needs macOS or Linux, Node.js 18+ and curl, no sudo. On Windows, use the [desktop app](#desktop-app-beta).
  168. Setup guides for each integration:
  169. <table>
  170. <tbody>
  171. <tr>
  172. <td align="center" valign="bottom" width="16%">
  173. <a href="https://docs.openviking.ai/en/agent-integrations/02-claude-code"><img src="docs/images/integrations/logos/claude-code.png" width="32" height="32" alt=""><br><strong>Claude</strong></a><br>
  174. <sub>Hooks&nbsp;+&nbsp;MCP</sub>
  175. </td>
  176. <td align="center" valign="bottom" width="16%">
  177. <a href="https://docs.openviking.ai/en/agent-integrations/04-codex"><picture><source media="(prefers-color-scheme: dark)" srcset="docs/images/integrations/logos/openai-dark.svg"><img src="docs/images/integrations/logos/openai.svg" width="32" height="32" alt=""></picture><br><strong>Codex</strong></a><br>
  178. <sub>Hooks&nbsp;+&nbsp;MCP</sub>
  179. </td>
  180. <td align="center" valign="bottom" width="16%">
  181. <a href="https://docs.openviking.ai/en/agent-integrations/12-cursor"><img src="docs/images/integrations/logos/cursor.png" width="32" height="32" alt=""><br><strong>Cursor</strong></a><br>
  182. <sub>Hooks&nbsp;+&nbsp;MCP</sub>
  183. </td>
  184. <td align="center" valign="bottom" width="16%">
  185. <a href="https://docs.openviking.ai/en/agent-integrations/13-trae"><img src="docs/images/integrations/logos/trae.png" width="32" height="32" alt=""><br><strong>TRAE</strong></a><br>
  186. <sub>Hooks&nbsp;+&nbsp;MCP</sub>
  187. </td>
  188. <td align="center" valign="bottom" width="16%">
  189. <a href="https://docs.openviking.ai/en/agent-integrations/03-openclaw"><img src="docs/images/integrations/logos/openclaw.png" width="32" height="32" alt=""><br><strong>OpenClaw</strong></a><br>
  190. <sub>Context&nbsp;engine</sub>
  191. </td>
  192. <td align="center" valign="bottom" width="16%">
  193. <a href="https://docs.openviking.ai/en/agent-integrations/05-hermes"><img src="docs/images/integrations/logos/hermes-agent.png" width="32" height="32" alt=""><br><strong>Hermes</strong></a><br>
  194. <sub>Built-in</sub>
  195. </td>
  196. </tr>
  197. </tbody>
  198. <tbody>
  199. <tr>
  200. <td align="center" valign="bottom" width="16%">
  201. <a href="https://docs.openviking.ai/en/agent-integrations/10-opencode"><img src="docs/images/integrations/logos/opencode.png" width="32" height="32" alt=""><br><strong>OpenCode</strong></a><br>
  202. <sub>Plugin&nbsp;+&nbsp;MCP</sub>
  203. </td>
  204. <td align="center" valign="bottom" width="16%">
  205. <a href="https://docs.openviking.ai/en/agent-integrations/11-pi"><picture><source media="(prefers-color-scheme: dark)" srcset="docs/images/integrations/logos/pi-dark.svg"><img src="docs/images/integrations/logos/pi.svg" width="32" height="32" alt=""></picture><br><strong>pi</strong></a><br>
  206. <sub>Native&nbsp;extension</sub>
  207. </td>
  208. <td align="center" valign="bottom" width="16%">
  209. <a href="docs/images/agents/en/deerflow-memory-manager.md"><picture><source media="(prefers-color-scheme: dark)" srcset="docs/images/integrations/logos/deerflow-dark.svg"><img src="docs/images/integrations/logos/deerflow.svg" width="32" height="32" alt=""></picture><br><strong>DeerFlow</strong></a><br>
  210. <sub>Plugin&nbsp;+&nbsp;MCP</sub>
  211. </td>
  212. <td align="center" valign="bottom" width="16%">
  213. <a href="https://docs.openviking.ai/en/agent-integrations/17-dsh"><picture><source media="(prefers-color-scheme: dark)" srcset="docs/images/integrations/logos/dsh-dark.svg"><img src="docs/images/integrations/logos/dsh.svg" width="32" height="32" alt=""></picture><br><strong>DSH</strong></a><br>
  214. <sub>Plugin&nbsp;+&nbsp;MCP</sub>
  215. </td>
  216. <td align="center" valign="bottom" width="16%">
  217. <a href="docs/images/agents/en/doubao-work.md"><img src="docs/images/integrations/logos/doubao-work.png" width="32" height="32" alt=""><br><strong>Doubao&nbsp;Work</strong></a><br>
  218. <sub>Connector</sub>
  219. </td>
  220. <td align="center" valign="bottom" width="16%">
  221. <a href="https://docs.openviking.ai/en/agent-integrations/07-langchain-langgraph"><img src="docs/images/integrations/logos/langchain.svg" width="32" height="32" alt=""><br><strong>LangChain</strong></a><br>
  222. <sub>Tools&nbsp;+&nbsp;store</sub>
  223. </td>
  224. </tr>
  225. </tbody>
  226. </table>
  227. **General integrations**
  228. <table>
  229. <tr>
  230. <td align="center" valign="bottom" width="50%">
  231. <a href="https://docs.openviking.ai/en/agent-integrations/15-agent-plugins"><img src="docs/images/integrations/logos/agent-plugins.svg" width="32" height="32" alt=""><br><strong>Agent&nbsp;Plugins&nbsp;1.0</strong></a>
  232. </td>
  233. <td align="center" valign="bottom" width="50%">
  234. <a href="https://docs.openviking.ai/en/agent-integrations/06-mcp-clients"><img src="docs/images/integrations/logos/mcp.svg" width="32" height="32" alt=""><br><strong>MCP&nbsp;clients</strong></a>
  235. </td>
  236. </tr>
  237. </table>
  238. For setup instructions and integration details, see [Integrations](https://openviking.ai/integrations).
  239. For framework applications, see the [LangChain/LangGraph and Microsoft Agent Framework packages](integrations/frameworks/README.md), with a guide to adding other adapters.
  240. ## Desktop App (Beta)
  241. The desktop app is a console for macOS and Windows x64 (beta). It configures supported local agent integrations, inspects recall and capture events in sessions, and syncs local memories and skills to OpenViking.
  242. Download:
  243. - [macOS Apple Silicon (arm64)](https://lf3-cdn-tos.bytegoofy.com/obj/tron-demo/7654844610543360265/420238785/0.0.19/darwin-arm64/openviking-helper-0.0.19-arm64.dmg)
  244. - [macOS Intel (x64)](https://lf3-cdn-tos.bytegoofy.com/obj/tron-demo/7654844610543360265/420238785/0.0.19/darwin-x64/openviking-helper-0.0.19-x64.dmg)
  245. - [Windows (x64)](https://lf3-cdn-tos.bytegoofy.com/obj/tron-demo/7654844610543360265/420238785/0.0.19/win32-x64/openviking-helper-0.0.19-x64.exe)
  246. ## VikingBot
  247. VikingBot is an AI agent framework built on top of OpenViking:
  248. ```bash
  249. pip install "openviking[bot]"
  250. openviking-server --with-bot
  251. ov chat # in another terminal
  252. ```
  253. The official Docker image bundles VikingBot and starts it by default alongside the server and console UI. Details: [VikingBot guide](https://docs.openviking.ai/en/guides/17-vikingbot).
  254. ## Deploy in production
  255. Run the open-source server in your own environment under [AGPLv3](LICENSE). It requires no activation key. Start with [server setup](https://docs.openviking.ai/en/getting-started/03-quickstart-server) or the [Docker and deployment guide](https://docs.openviking.ai/en/guides/03-deployment).
  256. The server supports [accounts and user isolation](https://docs.openviking.ai/en/concepts/11-multi-tenant) and opt-in [resource ACLs](https://docs.openviking.ai/en/concepts/15-acl). Configure [authentication](https://docs.openviking.ai/en/guides/04-authentication) before exposing it beyond localhost.
  257. ## Commercial editions
  258. <table>
  259. <tr>
  260. <td width="50%" valign="top">
  261. <img src="docs/images/commercial-saas.png" alt="Managed SaaS" width="100%" />
  262. <h3>☁️ Managed SaaS</h3>
  263. <p><a href="https://www.volcengine.com/product/openviking-service?utm_source=github&amp;utm_medium=referral&amp;utm_campaign=readme">Volcano Engine</a> hosts and operates OpenViking. Personal and Enterprise plans cover individual and team use, with migration tooling for open-source deployments. See the <a href="https://docs.volcengine.com/docs/84313/2374478">service documentation</a> for plans and limits. Hosting outside China is planned on <a href="https://www.byteplus.com">BytePlus</a>.</p>
  264. </td>
  265. <td width="50%" valign="top">
  266. <img src="docs/images/commercial-self-hosted.png" alt="Self-Managed" width="100%" />
  267. <h3>🏢 Self-Managed</h3>
  268. <p>Deploy in your own cloud account / VPC (BYOC) or an offline environment. This edition adds distributed deployment and official support, activated by a license key. <a href="https://docs.google.com/forms/d/e/1FAIpQLScQqwsm7fvKdjtNiW5rWNXJjoHPtedVzLsKSMJgObtsj2_udA/viewform">Contact the team</a>.</p>
  269. </td>
  270. </tr>
  271. </table>
  272. ## Research
  273. **Memory that evolves with your agent.** VikingMem develops an event-driven approach to extracting, updating, and consolidating long-term memory, giving stateful agents a way to retain useful experience as interactions accumulate. OpenViking open-sources a subset of these core capabilities.
  274. > **VikingMem: A Memory Base Management System for Stateful LLM-based Applications**<br>
  275. > Jiajie Fu, Junwen Chen, Mengzhao Wang, Aoxiang He, Maojia Sheng, Xiangyu Ke, Yifan Zhu, and Yunjun Gao.<br>
  276. > arXiv:2605.29640, 2026. Presented at VLDB 2026 in September.<br>
  277. > 📄 [Read the paper on arXiv](https://arxiv.org/abs/2605.29640) · [Read PDF](https://arxiv.org/pdf/2605.29640)
  278. **Directory structure as retrieval context.** This paper provides the formal foundations, index design, and experimental evidence behind OpenViking’s directory-aware retrieval. It defines directory-scoped query and maintenance operations and introduces TrieHI, which OpenViking integrates to resolve directory scopes before vector ranking. This connects the filesystem paradigm to retrieval: agents can search a project or memory subtree, retain its surrounding context, and reorganize it as knowledge evolves.
  279. > **Directory-Aware Query and Maintenance in Vector Databases**<br>
  280. > Mengzhao Wang, Zheng Gong, Jingpei Hu, Jiajie Fu, Maojia Sheng, Junwen Chen, and Yifan Zhu.<br>
  281. > arXiv:2606.16903, 2026. Accepted by ICDE.<br>
  282. > 📄 [Read the paper on arXiv](https://arxiv.org/abs/2606.16903) · [Read PDF](https://arxiv.org/pdf/2606.16903)
  283. **Retrieve the evidence you need with fewer tokens.** VikingRAG combines semantic search with document structure, exposing relevant directory segments as evidence gaps arise. Its core mechanisms are integrated into OpenViking. The paper further explores reusing retrieval traces and escalating to multi-round retrieval only when needed, reducing repeated exploration while preserving answer quality.
  284. > **VikingRAG: Accurate and Token-efficient Retrieval-augmented Generation over Structured Documents**<br>
  285. > Peiyuan Gao, Gaoyuan Zhang, Haojie Qin, Yahui Sun, Qianyi Zhang, Yunhao Zhang, Zeyu Wang, and Wei Lu.<br>
  286. > arXiv:2609.11390, 2026. Submitted.<br>
  287. > 📄 [Read the paper on arXiv](https://arxiv.org/abs/2609.11390) · [Read PDF](https://arxiv.org/pdf/2609.11390)
  288. ## Partner Projects
  289. - [deer-flow](https://github.com/bytedance/deer-flow) - Open-source long-horizon SuperAgent harness
  290. - [NoKV](https://github.com/NoKV-Lab/NoKV) - AI native distributed file system
  291. - [loopx](https://github.com/huangruiteng/loopx) - Lightweight loop engineering state kernel
  292. - [Hermes Agent](https://github.com/NousResearch/hermes-agent) - The agent that grows with you
  293. - [NVIDIA cuVS](https://github.com/NVIDIA/cuvs) - GPU-accelerated vector search and clustering library
  294. To propose a partnership, [open an issue](https://github.com/volcengine/OpenViking/issues).
  295. ## Community & Contributing
  296. - **Docs**: [docs.openviking.ai](https://docs.openviking.ai/) · [FAQ](https://docs.openviking.ai/en/faq/faq)
  297. - **Blog**: [blog.openviking.ai](https://blog.openviking.ai/)
  298. - **Team**: [About us](https://docs.openviking.ai/en/about/01-about-us)
  299. - **Chat**: <a href="https://docs.openviking.ai/en/about/01-about-us#lark-group"><img src="docs/images/community/lark.svg" width="18" height="18" alt="Lark">&nbsp;Lark</a> · <a href="https://docs.openviking.ai/en/about/01-about-us#wechat-group"><img src="docs/images/community/wechat.svg" width="18" height="18" alt="WeChat">&nbsp;WeChat</a> · <a href="https://discord.com/invite/eHvx8E9XF3"><img src="docs/images/community/discord.svg" width="18" height="18" alt="Discord">&nbsp;Discord</a> · <a href="https://x.com/openvikingai"><picture><source media="(prefers-color-scheme: dark)" srcset="docs/images/community/x-dark.svg"><img src="docs/images/community/x.svg" width="16" height="16" alt="X"></picture>&nbsp;X</a>
  300. - **Contribute**: bug fixes and new features are both welcome — see [CONTRIBUTING.md](CONTRIBUTING.md)
  301. <a href="https://github.com/volcengine/OpenViking/graphs/contributors">
  302. <img src="https://contrib.rocks/image?repo=volcengine/OpenViking&amp;columns=15&amp;max=120" alt="OpenViking contributors" />
  303. </a>
  304. ## Security and privacy
  305. For vulnerability reporting and supported versions, see [SECURITY.md](SECURITY.md)
  306. ## License
  307. Copyright © 2026 Volcano Engine (火山引擎) and the OpenViking contributors.
  308. The OpenViking project uses different licenses for different components:
  309. - **Main Project**: AGPLv3 - see the [LICENSE](./LICENSE) file for details
  310. - **crates/ov\_cli**: Apache 2.0 - see the [LICENSE](./crates/LICENSE) for details
  311. - **examples**: Apache 2.0 - see the [LICENSE](./examples/LICENSE) for details. The Hermes plugin in `examples/hermes-plugin` retains its [MIT license](./examples/hermes-plugin/LICENSE).
  312. - **integrations/frameworks**: the LangChain/LangGraph adapter uses AGPLv3 and the Microsoft Agent Framework adapter uses MIT; see each package's `LICENSE`. Their runnable examples retain Apache 2.0; see each package's `examples/LICENSE`.
  313. - **third\_party**: Respective original licenses of third-party projects
  314. Please also note: any wholesale rewriting and subsequent re-open-sourcing of this project is prohibited; any request to translate all or a substantial portion of the project code into another coding language requires prior written authorization from Volcano Engine. For permission requests, please contact the Volcano Engine team — see [Community & Contributing](#community--contributing) for contact channels.
agent-plugins/skills/ov-kanban/references/loop.sh · Bundled script · 56 lines · 1 finding marked
  1. #!/usr/bin/env bash
  2. # loop.sh — run one CLI agent turn after another against an ov-kanban board
  3. # until no runnable task remains or the tick budget is spent.
  4. #
  5. # bash loop.sh <board> [max_ticks=5] [cwd=$PWD]
  6. #
  7. # env:
  8. # OV_KANBAN_ROOT kanban root (default: viking://agent/kanban, falls back to
  9. # viking://resources/kanban when the server rejects agent/kanban)
  10. # OV_KANBAN_AGENT agent id written as owner (default codex@<host>)
  11. # OV_KANBAN_CMD agent command template with {PROMPT} placeholder
  12. # (default: codex exec, non-interactive, prompt from file)
  13. #
  14. # Each tick = one bounded turn of the ov-kanban skill: pick, claim, one slice,
  15. # verify, write back. The task file in OV is the only state between ticks.
  16. # ponytail: max_ticks is the whole quota model; add per-task budgets if a task
  17. # ever spins.
  18. set -uo pipefail
  19. board="${1:?board}"; max_ticks="${2:-5}"; cwd="${3:-$PWD}"
  20. # root: viking://agent/kanban when the server accepts it, else viking://resources/kanban
  21. ov_ok() { command ov "$@" -o json 2>&1 | grep -q '^{"ok":true'; }
  22. if [ -z "${OV_KANBAN_ROOT:-}" ]; then
  23. if ov_ok stat viking://agent/kanban || ov_ok mkdir viking://agent/kanban; then OV_KANBAN_ROOT=viking://agent/kanban
  24. else OV_KANBAN_ROOT=viking://resources/kanban; fi
  25. fi
  26. : "${OV_KANBAN_AGENT:=codex@$(hostname -s)}"
  27. [ -n "${OV_KANBAN_CMD:-}" ] || OV_KANBAN_CMD="codex exec --dangerously-bypass-approvals-and-sandbox --skip-git-repo-check -C \"${cwd}\" - < {PROMPT}"
  28. skill_md="$(cd "$(dirname "$0")/.." && pwd)/SKILL.md"
  29. board_uri="${OV_KANBAN_ROOT}/${board}"
  30. # ponytail: counts every open|in_progress task, including one another agent
  31. # claimed minutes ago, so a tick can find nothing to claim. Filter on
  32. # owner/updated here if idle ticks start to cost.
  33. runnable() {
  34. command ov grep '^status: (open|in_progress)' -u "$board_uri" -x "$board_uri/archive" -o json 2>/dev/null \
  35. | python3 -c 'import sys,json; d=json.loads(next(l for l in sys.stdin if l.startswith("{"))); print(len({m["uri"] for m in d.get("result",{}).get("matches",[])}))' 2>/dev/null || echo 0
  36. }
  37. notify() { command -v herdr >/dev/null && herdr notification show "$1" --sound done >/dev/null 2>&1; echo "$1"; }
  38. for tick in $(seq 1 "$max_ticks"); do
  39. n=$(runnable)
  40. if [ "$n" = 0 ]; then notify "ov-kanban ${board}: no runnable task (needs_user/blocked/done only)"; exit 0; fi
  41. prompt="$(mktemp "${TMPDIR:-/tmp}/ov-kanban-prompt.XXXXXX")"
  42. cat > "$prompt" <<PROMPT
  43. Read ${skill_md} and follow it exactly.
  44. Kanban root: ${OV_KANBAN_ROOT} board: ${board} your agent id: ${OV_KANBAN_AGENT}
  45. Do exactly ONE turn: pick one runnable task on this board, claim it, do one bounded slice, verify it, fold and write the task file back, then stop.
  46. If the task needs a user answer, set status: needs_user, put the concrete question in ## Questions, write back, and stop.
  47. Do not start a second task in this turn.
  48. PROMPT
  49. echo "== tick ${tick}/${max_ticks} (${n} runnable) =="
  50. eval "${OV_KANBAN_CMD//\{PROMPT\}/$prompt}"
  51. rm -f "$prompt"
  52. done
  53. notify "ov-kanban ${board}: tick budget ${max_ticks} spent, $(runnable) runnable left"
examples/claude-code-memory-plugin/scripts/ov-memory-doctor.mjs · Bundled script · 392 lines · 2 findings marked
  1. #!/usr/bin/env node
  2. /**
  3. * Client-side diagnostics for the OpenViking Claude Code memory plugin.
  4. *
  5. * Covers the three things that go wrong on a user's machine — the plugin
  6. * install (marketplace / enablement / hooks / MCP wiring), the client config
  7. * (which file won, is the JSON valid, what the key claims) and the connection
  8. * to the server (reachability, auth, tenant-data access, /mcp) — plus the
  9. * runtime evidence the hooks leave behind. When the server runs on this
  10. * machine (loopback url) it also checks
  11. * the port, plugin-only keys in ov.conf and `GET /ready`. Provider-level validation stays with `openviking-server doctor`.
  12. *
  13. * Usage:
  14. * node ov-memory-doctor.mjs [--json] [--offline] [--timeout <ms>] [--no-color]
  15. *
  16. * Exit code 1 when any check fails, 0 otherwise. Never prints a full api key.
  17. */
  18. import { realpathSync } from "node:fs";
  19. import { homedir } from "node:os";
  20. import { dirname, join, resolve as resolvePath } from "node:path";
  21. import { fileURLToPath } from "node:url";
  22. import { isPluginEnabled, loadConfig } from "./config.mjs";
  23. import { STATE_DIR } from "./lib/state.mjs";
  24. import {
  25. countDirEntries,
  26. existsPath,
  27. expandHome,
  28. fileInfo,
  29. fmtAge,
  30. fmtBytes,
  31. credentialSources,
  32. homeShort,
  33. inspectConfigFiles,
  34. inspectJsonFile,
  35. readStateFiles,
  36. reportCredentials,
  37. reportPeer,
  38. reportTimeouts,
  39. reportToggles,
  40. runCommand,
  41. runDoctor,
  42. scanDebugLog,
  43. scanRcFiles,
  44. sweepEnv,
  45. tryJson,
  46. } from "./shared/doctor-core.mjs";
  47. import { describeInputFilters } from "./shared/input-filters.mjs";
  48. import { isBypassed } from "./shared/session-model.mjs";
  49. const PLUGIN_ROOT = resolvePath(dirname(fileURLToPath(import.meta.url)), "..");
  50. const PLUGIN_ID = "openviking-memory@openviking";
  51. const PLUGIN_NAME = "openviking-memory";
  52. const MARKETPLACE = "openviking";
  53. const LEGACY_MARKETPLACE = "openviking-plugins-local";
  54. const CLAUDE_DIR = join(homedir(), ".claude");
  55. const STATE_FILES = ["last-recall.json", "last-capture.json", "last-session-event.json", "daily-stats.json", "server-probe.json", "host-cli-probe.json", "context-face.json"];
  56. const REQUIRED_PLUGIN_FILES = [".claude-plugin/plugin.json", "hooks/hooks.json", ".mcp.json", "servers/mcp-proxy.mjs", "scripts/config.mjs", "scripts/auto-recall.mjs", "scripts/auto-capture.mjs"];
  57. function envBoolValue(name) {
  58. const v = process.env[name];
  59. if (v == null || v === "") return undefined;
  60. const lower = v.trim().toLowerCase();
  61. if (["0", "false", "no"].includes(lower)) return false;
  62. if (["1", "true", "yes"].includes(lower)) return true;
  63. return undefined;
  64. }
  65. // ---------------------------------------------------------------------------
  66. // Sections
  67. // ---------------------------------------------------------------------------
  68. function checkInstall(report, { cliOnPath }) {
  69. report.section("Plugin install");
  70. const manifest = tryJson(join(PLUGIN_ROOT, ".claude-plugin", "plugin.json"));
  71. const version = manifest?.version || "?";
  72. const inCache = PLUGIN_ROOT.includes(`${join(".claude", "plugins", "cache")}`);
  73. report.info(`running from ${homeShort(PLUGIN_ROOT)} (version ${version}, ${inCache ? "marketplace cache" : "directory install / dev checkout"})`);
  74. const missing = REQUIRED_PLUGIN_FILES.filter((rel) => !existsPath(join(PLUGIN_ROOT, rel)));
  75. if (missing.length) report.fail("plugin files missing", missing.join(", "), "reinstall: claude plugin uninstall openviking-memory@openviking && claude plugin install openviking-memory@openviking");
  76. else report.ok("plugin files present (hooks, MCP proxy, scripts)");
  77. if (!existsPath(join(PLUGIN_ROOT, "skills"))) {
  78. report.warn("no skills/ directory in this plugin copy", "the installed copy predates the bundled skills; Claude Code caches by version, so `claude plugin update` is a no-op until the version changes",
  79. "claude plugin marketplace update openviking && claude plugin uninstall openviking-memory@openviking && claude plugin install openviking-memory@openviking");
  80. }
  81. // Registry: installed_plugins.json
  82. const installed = inspectJsonFile(join(CLAUDE_DIR, "plugins", "installed_plugins.json"));
  83. let installPath = "";
  84. if (!installed.exists) {
  85. report.warn("~/.claude/plugins/installed_plugins.json not found", "no plugin has ever been installed through the marketplace on this machine");
  86. } else if (!installed.ok) {
  87. report.fail("~/.claude/plugins/installed_plugins.json is unreadable", installed.error);
  88. } else {
  89. const plugins = installed.data.plugins || {};
  90. const ids = Object.keys(plugins).filter((id) => id.startsWith(`${PLUGIN_NAME}@`) || id.startsWith("claude-code-memory-plugin@"));
  91. const entries = Array.isArray(plugins[PLUGIN_ID]) ? plugins[PLUGIN_ID] : (plugins[PLUGIN_ID] ? [plugins[PLUGIN_ID]] : []);
  92. if (!entries.length) {
  93. report.fail(`${PLUGIN_ID} is not registered in installed_plugins.json`, ids.length ? `found instead: ${ids.join(", ")}` : "",
  94. "curl -fsSL https://openviking.ai/install | bash -s -- --harness claude");
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 103 on GitHub
  95. } else {
  96. const entry = entries[0];
  97. installPath = entry.installPath || "";
  98. report.ok(`registered ${PLUGIN_ID} ${entry.version || "?"} (scope ${entry.scope || "?"}, updated ${entry.lastUpdated || "?"})`);
  99. if (installPath && resolvePath(installPath) !== PLUGIN_ROOT) {
  100. const registeredDoctor = join(installPath, "scripts", "ov-memory-doctor.mjs");
  101. report.warn("this script is not running from the registered install", `registered: ${homeShort(installPath)}\nrunning: ${homeShort(PLUGIN_ROOT)}`,
  102. existsPath(registeredDoctor)
  103. ? `Claude Code executes hooks from the registered copy; check that one with: node ${homeShort(registeredDoctor)}`
  104. : `Claude Code executes hooks from the registered copy (${entry.version || "?"}), which predates this script — update the plugin, then rerun from there`);
  105. }
  106. if (installPath && !existsPath(join(installPath, ".claude-plugin", "plugin.json"))) {
  107. report.fail("registered installPath no longer exists", homeShort(installPath), "reinstall the plugin");
  108. }
  109. if (entries.length > 1) report.warn(`${PLUGIN_ID} has ${entries.length} install records`, entries.map((e) => `${e.scope}: ${homeShort(e.installPath || "")}`).join("\n"));
  110. }
  111. const extra = ids.filter((id) => id !== PLUGIN_ID);
  112. if (extra.length) {
  113. report.warn("additional openviking plugin ids are installed", extra.join(", "), `claude plugin uninstall <id> for each stale copy (legacy marketplace ${LEGACY_MARKETPLACE})`);
  114. }
  115. }
  116. // Marketplace
  117. const known = inspectJsonFile(join(CLAUDE_DIR, "plugins", "known_marketplaces.json"));
  118. if (known.ok) {
  119. const entry = known.data[MARKETPLACE];
  120. if (!entry) {
  121. report.fail(`marketplace '${MARKETPLACE}' is not registered`, `known: ${Object.keys(known.data).join(", ") || "(none)"}`,
  122. "re-run the installer: curl -fsSL https://openviking.ai/install | bash -s -- --harness claude");
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 132 on GitHub
  123. } else {
  124. const source = entry.source || {};
  125. const location = entry.installLocation || source.path || "";
  126. const desc = source.source === "directory" ? `directory ${homeShort(source.path || "")}` : source.source === "github" ? `github ${source.repo || ""}` : source.source === "url" ? `url ${source.url || ""}` : JSON.stringify(source);
  127. if (/\.json$/i.test(String(source.path || ""))) {
  128. report.warn(`marketplace '${MARKETPLACE}' is registered as a file (${homeShort(source.path)})`, "file-type marketplaces mis-derive installLocation and `claude plugin marketplace update` fails with EISDIR",
  129. "claude plugin marketplace remove openviking && re-run the installer (it registers a directory)");
  130. } else if (source.source === "url") {
  131. // Claude Code caches a URL marketplace as a bare manifest file, so there
  132. // is no directory at installLocation to check.
  133. report.ok(`marketplace '${MARKETPLACE}' → ${desc}`);
  134. // The user-settings declaration wins; known_marketplaces.json only
  135. // catches up with it on Claude Code's next startup.
  136. const declared = tryJson(join(CLAUDE_DIR, "settings.json"))?.extraKnownMarketplaces?.[MARKETPLACE]?.autoUpdate;
  137. report.info((declared ?? entry.autoUpdate) ?"auto-update is on (Claude Code checks in the background during interactive sessions; a new version loads after restart)" : "auto-update is off: update with claude plugin update openviking-memory@openviking, or enable it for this marketplace in /plugin");
  138. } else if (location && !existsPath(join(location, ".claude-plugin", "marketplace.json"))) {
  139. report.fail(`marketplace '${MARKETPLACE}' points at a missing directory`, `${desc}\nexpected ${homeShort(join(location, ".claude-plugin", "marketplace.json"))}`,
  140. "the checkout/archive was moved or deleted; re-run the installer");
  141. } else {
  142. report.ok(`marketplace '${MARKETPLACE}' → ${desc}`);
  143. if (source.source === "directory" && location) {
  144. const manifest = tryJson(join(location, ".claude-plugin", "marketplace.json"));
  145. const pluginSrc = manifest?.plugins?.find?.((p) => p?.name === PLUGIN_NAME)?.source;
  146. if (pluginSrc && typeof pluginSrc === "object" && pluginSrc.source === "git-subdir") {
  147. report.info(`marketplace fetches ${pluginSrc.url || "?"}@${pluginSrc.ref || "?"} ${pluginSrc.path || ""} (update: claude plugin marketplace update openviking && claude plugin update ${PLUGIN_ID})`);
  148. } else if (pluginSrc) {
  149. report.info("directory marketplace: updates need the installer to be re-run (claude plugin update cannot fetch)");
  150. }
  151. }
  152. }
  153. }
  154. if (known.data[LEGACY_MARKETPLACE]) {
  155. report.warn(`legacy marketplace '${LEGACY_MARKETPLACE}' is still registered`, "", `claude plugin marketplace remove ${LEGACY_MARKETPLACE}`);
  156. }
  157. } else if (known.exists) {
  158. report.fail("~/.claude/plugins/known_marketplaces.json is unreadable", known.error);
  159. }
  160. // settings.json
  161. const settings = inspectJsonFile(join(CLAUDE_DIR, "settings.json"));
  162. if (settings.exists && !settings.ok) {
  163. report.fail("~/.claude/settings.json is not valid JSON", settings.error, "fix the JSON — Claude Code ignores the whole file otherwise");
  164. } else if (settings.ok) {
  165. const enabled = settings.data.enabledPlugins?.[PLUGIN_ID];
  166. if (enabled === true) report.ok(`enabledPlugins["${PLUGIN_ID}"] = true`);
  167. else if (enabled === false) report.fail(`plugin is disabled in ~/.claude/settings.json`, "", `claude plugin enable ${PLUGIN_ID}`);
  168. else report.warn(`enabledPlugins has no entry for ${PLUGIN_ID}`, "installed but never enabled (or enabled at another scope)", `claude plugin enable ${PLUGIN_ID}`);
  169. const otherEnabled = Object.entries(settings.data.enabledPlugins || {}).filter(([id, on]) => on && id !== PLUGIN_ID && /openviking|claude-code-memory-plugin/.test(id));
  170. if (otherEnabled.length) report.warn("more than one openviking plugin is enabled", otherEnabled.map(([id]) => id).join(", "), "disable/uninstall the stale one or hooks fire twice");
  171. const hooksText = JSON.stringify(settings.data.hooks || {});
  172. if (/openviking|auto-recall\.mjs|auto-capture\.mjs/.test(hooksText)) {
  173. report.warn("legacy openviking hooks are still merged into ~/.claude/settings.json", "pre-2.0 installs wrote hooks there; together with the plugin every hook now fires twice (double recall/capture)",
  174. "remove the openviking entries from .hooks in ~/.claude/settings.json (back it up first)");
  175. }
  176. const statusCmd = String(settings.data.statusLine?.command || "");
  177. if (statusCmd.includes("installed_plugins.json")) {
  178. // The installer's command resolves the current plugin install on each run.
  179. report.ok("statusline registered (runs the installed plugin)");
  180. } else if (statusCmd.includes("statusline.mjs")) {
  181. const m = /node\s+"?([^"]+statusline\.mjs)"?/.exec(statusCmd);
  182. const path = m ? expandHome(m[1]) : "";
  183. if (path && !existsPath(path)) report.warn("statusLine points at a missing statusline.mjs", homeShort(path), "re-run the installer or fix .statusLine.command in ~/.claude/settings.json");
  184. else if (path && !path.startsWith(PLUGIN_ROOT) && !(installPath && path.startsWith(resolvePath(installPath)))) {
  185. report.warn("statusline runs from a different plugin copy than the hooks", homeShort(path), "point .statusLine.command at the registered install, or accept that the two may differ in version");
  186. } else report.ok(`statusline registered (${homeShort(path)})`);
  187. } else {
  188. report.info("statusline not registered (optional; OPENVIKING_STATUSLINE=off also silences it)");
  189. }
  190. const envBlock = settings.data.env || {};
  191. const envKeys = Object.keys(envBlock).filter((k) => k.startsWith("OPENVIKING_"));
  192. if (envKeys.length) report.info(`~/.claude/settings.json env block sets ${envKeys.join(", ")}`);
  193. } else {
  194. report.warn("~/.claude/settings.json not found", "no enabledPlugins entry can exist without it");
  195. }
  196. // Legacy MCP registration + rc blocks
  197. const claudeJson = tryJson(join(homedir(), ".claude.json"));
  198. const userMcp = claudeJson?.mcpServers?.openviking;
  199. if (userMcp) {
  200. report.warn("a user-scope MCP server named 'openviking' is registered besides the plugin's", JSON.stringify(userMcp).slice(0, 160),
  201. "claude mcp remove openviking -s user (the plugin ships its own MCP server)");
  202. }
  203. const rc = scanRcFiles([]);
  204. const CONNECTION_VARS = /^OPENVIKING_(URL|BASE_URL|API_KEY|BEARER_TOKEN|ACCOUNT|USER|MEMORY_ENABLED|CONFIG_FILE|CLI_CONFIG_FILE|HOME)$/;
  205. for (const h of rc.filter((h) => h.kind === "export")) {
  206. const conn = h.vars.filter((v) => CONNECTION_VARS.test(v));
  207. if (conn.length) report.warn(`${h.file} exports ${conn.join(", ")}`, "shell exports override ovcli.conf in every session started from that shell", "remove the export or keep ovcli.conf in sync with it");
  208. else report.info(`${h.file} exports ${h.detail}`);
  209. }
  210. if (cliOnPath) {
  211. const list = runCommand("claude", ["plugin", "list", "--json"], { timeoutMs: 30000 });
  212. if (list.ok) {
  213. let rows = [];
  214. try { rows = JSON.parse(list.stdout); } catch { rows = []; }
  215. const mine = rows.filter((r) => r?.id === PLUGIN_ID);
  216. const others = rows.filter((r) => r?.id !== PLUGIN_ID && /openviking|claude-code-memory-plugin/.test(String(r?.id)));
  217. if (!mine.length) report.fail(`claude plugin list does not show ${PLUGIN_ID}`, others.length ? `shows: ${others.map((r) => r.id).join(", ")}` : "", `claude plugin install ${PLUGIN_ID}`);
  218. else {
  219. const row = mine[0];
  220. if (row.enabled === false) report.fail(`claude plugin list: ${PLUGIN_ID} is disabled`, "", `claude plugin enable ${PLUGIN_ID}`);
  221. else report.ok(`claude plugin list: ${PLUGIN_ID} ${row.version || ""} enabled`);
  222. }
  223. if (others.length) report.warn("claude plugin list shows extra openviking plugins", others.map((r) => `${r.id} (${r.enabled ? "enabled" : "disabled"})`).join(", "));
  224. } else {
  225. report.info(`claude plugin list --json failed (${list.error || list.stderr.split("\n")[0]})`);
  226. }
  227. }
  228. report.info("MCP wiring: `claude mcp list` shows the plugin server as plugin:openviking-memory:openviking (slow; run it when MCP tools are missing)");
  229. }
  230. function checkConfig(report, cfg, host) {
  231. report.section("Configuration");
  232. const { cliConf, ovConf } = inspectConfigFiles(report, host);
  233. // Enable verdict
  234. const enabled = isPluginEnabled();
  235. const envEnabled = envBoolValue("OPENVIKING_MEMORY_ENABLED");
  236. let reason;
  237. if (envEnabled === false) reason = "OPENVIKING_MEMORY_ENABLED is set to off";
  238. else if (envEnabled === true) reason = "OPENVIKING_MEMORY_ENABLED=1";
  239. else if (ovConf.ok && ovConf.data.claude_code?.enabled === false) reason = "ov.conf claude_code.enabled = false";
  240. else if (ovConf.ok || cliConf.ok) reason = `${ovConf.ok ? "ov.conf" : "ovcli.conf"} exists and parses`;
  241. else reason = "neither ovcli.conf nor ov.conf parses";
  242. if (enabled) report.ok(`plugin enabled (${reason})`);
  243. else report.fail(`plugin disabled — every hook exits immediately (${reason})`, "", envEnabled === false ? "unset OPENVIKING_MEMORY_ENABLED" : "create ~/.openviking/ovcli.conf with url + api_key, or set OPENVIKING_MEMORY_ENABLED=1 plus OPENVIKING_URL/OPENVIKING_API_KEY");
  244. // Resolved values + sources
  245. const keyInfo = reportCredentials(report, cfg, credentialSources(cfg, cliConf, ovConf), { account: cfg.accountId, user: cfg.userId });
  246. const peer = reportPeer(report, cfg);
  247. reportTimeouts(report, cfg, host);
  248. const toggles = [`auto-inject ${cfg.noAutoInject ? "OFF" : "on"}`, `auto-recall ${cfg.autoRecall ? "on" : "OFF"}`, `auto-capture ${cfg.autoCapture ? "on" : "OFF"}`, `recall compress ${cfg.recallRewrite}`, `write path ${cfg.writePathAsync ? "async" : "sync"}`];
  249. reportToggles(report, cfg, host, toggles);
  250. if (cfg.bypassSession) report.warn("OPENVIKING_BYPASS_SESSION is on — every hook skips the server", "", "unset it");
  251. if (cfg.bypassSessionPatterns?.length) {
  252. const hit = isBypassed(cfg, { cwd: process.cwd() });
  253. report[hit ? "warn" : "info"](`bypass patterns: ${cfg.bypassSessionPatterns.join(", ")}${hit ? " — MATCH the current cwd" : ""}`, hit ? "recall/capture are skipped in this directory" : "", hit ? "narrow OPENVIKING_BYPASS_SESSION_PATTERNS" : "");
  254. }
  255. for (const filters of describeInputFilters(cfg)) {
  256. if (!filters.total) continue;
  257. report.info(`${filters.label} ${filters.summary}`);
  258. for (const e of filters.errors) {
  259. const where = `${filters.env} or ovcli.conf plugin.claude_code.${filters.key}`;
  260. report.warn(
  261. `${filters.key}[${e.index}]: ${e.message}`,
  262. e.source ? `rule: ${e.source}` : "this rule is skipped, the rest still apply",
  263. e.message.startsWith("invalid regular expression")
  264. ? `fix the pattern in ${where} (the u flag rejects escapes that are legal without it)`
  265. : `fix the rule in ${where}`,
  266. );
  267. }
  268. }
  269. report.info(`debug log ${cfg.debug ? "on" : "off"} → ${homeShort(cfg.debugLogPath)}${cfg.debug ? "" : " (set OPENVIKING_DEBUG=1 in Claude Code's environment to record hook errors)"}`);
  270. sweepEnv(report, cfg, host, (r, env) => {
  271. if (env.openviking.some((e) => e.name === "OPENVIKING_MCP_URL")) r.warn("OPENVIKING_MCP_URL has no effect on this plugin", "the proxy always targets <url>/mcp", "unset it and fix url instead");
  272. if (env.openviking.some((e) => ["OPENVIKING_URL", "OPENVIKING_BASE_URL", "OPENVIKING_API_KEY", "OPENVIKING_BEARER_TOKEN"].includes(e.name)) && cliConf.ok && (cliConf.data.url || cliConf.data.api_key)) {
  273. r.info("env vars override the url/api_key in ovcli.conf — edits to the file do not take effect while they are set");
  274. }
  275. });
  276. return { keyInfo, cliConf, ovConf, peer };
  277. }
  278. function checkActivity(report, cfg, connection) {
  279. report.section("Recent activity");
  280. const inject = fileInfo(join(homedir(), ".openviking", "last_inject.md"));
  281. if (inject.exists) report.info(`last session-start injection ${fmtAge(inject.mtimeMs)}, ${fmtBytes(inject.size)} (~/.openviking/last_inject.md)`);
  282. else report.info("no session-start injection recorded yet");
  283. const state = readStateFiles(STATE_DIR, STATE_FILES);
  284. const recall = state["last-recall.json"];
  285. if (recall.exists && recall.data) {
  286. const d = recall.data;
  287. const line = `last auto-recall ${fmtAge(d.ts)} — ${d.count ?? 0} items, ${d.latency_ms ?? "?"}ms, reason=${d.reason || "?"} (server ${d.server_url || "?"})`;
  288. if (d.reason === "offline") report.warn(line, "the hook could not reach the server at that time");
  289. else if (d.reason === "bypass" || d.reason === "disabled") report.warn(line, "recall was switched off for that session");
  290. else report.info(line);
  291. if (d.server_url && d.server_url !== cfg.baseUrl) report.warn("last recall talked to a different server than the current config", `${d.server_url} vs ${cfg.baseUrl}`, "config changed since; restart Claude Code so the MCP proxy follows");
  292. if (typeof d.latency_ms === "number" && d.latency_ms > 45000) report.warn(`recall latency ${d.latency_ms}ms is close to the 60s hook budget`, "", "set OPENVIKING_RECALL_QUERY_EXPANSION=off and OPENVIKING_RECALL_COMPRESS=off, or raise the timeout");
  293. } else {
  294. report.info("no auto-recall recorded yet (UserPromptSubmit hook has not run, or state dir differs)");
  295. }
  296. const capture = state["last-capture.json"];
  297. if (capture.exists && capture.data) {
  298. const d = capture.data;
  299. const line = `last auto-capture ${fmtAge(d.ts)} — captured ${d.turns_captured ?? 0}, queued ${d.turns_queued ?? 0}, failed ${d.turns_failed ?? 0}, pending ${d.pending_tokens ?? 0}/${d.commit_threshold ?? "?"} tokens, ${d.commit_count ?? 0} commits (session ${d.ov_session_id || "?"})`;
  300. if ((d.turns_failed ?? 0) > 0) report.warn(line, "turns_failed > 0 means the server rejected writes with a non-retryable status (401/403/404) and those turns were dropped", "fix credentials, then set OPENVIKING_WRITE_PATH_ASYNC=0 temporarily to see the error on stderr");
  301. else if ((d.turns_queued ?? 0) > 0) report.warn(line, "turns are waiting in the offline queue; they replay at the next session start once /health passes");
  302. else report.info(line);
  303. } else {
  304. report.info("no auto-capture recorded yet (Stop hook has not run)");
  305. }
  306. const probe = state["server-probe.json"];
  307. if (probe.exists && probe.data && probe.data.healthy === false) report.info(`statusline probe last saw the server unhealthy ${fmtAge(probe.data.ts)} (${probe.data.error || "?"})`);
  308. const face = state["context-face.json"];
  309. if (face.exists && face.data?.legacyUntil > Date.now()) report.warn("recall is pinned to the legacy /search/recall endpoint", `context-face.json legacyUntil ${new Date(face.data.legacyUntil).toISOString()} — set after one 4xx that mentioned 'mode'`, `rm ${homeShort(face.path)} to re-probe the context endpoint`);
  310. const hostCli = state["host-cli-probe.json"];
  311. if (hostCli.exists && hostCli.data && hostCli.data.available === false && cfg.recallRewrite !== "off" && cfg.recallRewrite !== "server") report.info(`local compressor probe says '${hostCli.data.command}' is unavailable (cached 7 days) — rm ${homeShort(hostCli.path)} to re-check`);
  312. const pendingDir = process.env.OPENVIKING_PENDING_DIR || join(homedir(), ".openviking", "pending");
  313. const pending = countDirEntries(pendingDir, (n) => n.endsWith(".json") || n.endsWith(".processing"));
  314. if (pending) report.warn(`${pending} capture payload(s) waiting in ${homeShort(pendingDir)}`, "retryable failures are replayed at the next session start after /health passes", connection?.summary?.reachable ? "start a new Claude Code session to drain the queue" : "bring the server back first");
  315. else if (pending === 0) report.ok("offline queue empty");
  316. const log = scanDebugLog(cfg.debugLogPath);
  317. if (!log.exists) {
  318. report.info(`no hook log at ${homeShort(cfg.debugLogPath)}${cfg.debug ? " — debug is on but no hook has run since; if a session ran, hooks are not being spawned (node/PATH/plugin registration)" : ""}`);
  319. } else {
  320. report.info(`hook log ${homeShort(log.path)} — ${fmtBytes(log.size)}, last write ${fmtAge(log.mtimeMs)}, hooks seen: ${log.hooks.join(", ") || "(none)"}`);
  321. if (log.proxyStart?.data?.mcpUrl) {
  322. const want = `${cfg.baseUrl.replace(/\/+$/, "")}/mcp`;
  323. if (log.proxyStart.data.mcpUrl !== want) report.warn(`MCP proxy last started against ${log.proxyStart.data.mcpUrl} (${log.proxyStart.ts})`, `current config resolves to ${want}; a running proxy only re-reads credentials after a 401/403, never a new url`, "if that proxy is still running, restart Claude Code (or /mcp → reconnect); if the line is old, ignore it");
  324. else report.info(`MCP proxy last started against ${log.proxyStart.data.mcpUrl} (${log.proxyStart.ts})`);
  325. }
  326. const notable = log.recentErrors.filter((e) => !(e.hook === "subagent-stop" && e.stage === "transcript_read"));
  327. if (notable.length) report.warn(`hook errors in the last day of logging (${notable.length} shown)`, notable.map((e) => `${e.ts} ${e.hook}/${e.stage}: ${e.message}`).join("\n"));
  328. else if (log.recentErrors.length) report.info("only subagent-stop transcript_read ENOENT errors in the log (harmless: that subagent's transcript was already gone)");
  329. }
  330. }
  331. // ---------------------------------------------------------------------------
  332. const HOST = {
  333. harness: "claude-code",
  334. pluginRoot: PLUGIN_ROOT,
  335. cliName: "claude",
  336. launcherHint: "Claude Code",
  337. nodePathFix: "put node on PATH for the environment that launches Claude Code, or set PATH in the `env` block of ~/.claude/settings.json",
  338. // Recall runs on the plain request timeout here; only Codex gives it its own.
  339. timeoutBudgets: { UserPromptSubmit: "timeoutMs", Stop: "captureTimeoutMs" },
  340. onCliFound(report, cli) {
  341. report.ok(`claude ${cli.stdout.split("\n")[0]}`);
  342. const plugin = runCommand("claude", ["plugin", "--help"], { timeoutMs: 15000 });
  343. if (!plugin.ok) report.warn("`claude plugin` subcommand unavailable", "this Claude Code build predates the plugin system; only the legacy settings.json hook install works", "upgrade Claude Code to 2.0+");
  344. },
  345. loadConfig,
  346. checkInstall,
  347. checkConfig,
  348. checkActivity,
  349. resolveIdentity: (cfg) => ({ account: cfg.accountId, user: cfg.userId }),
  350. };
  351. function isDirectRun() {
  352. if (!process.argv[1]) return false;
  353. try {
  354. return realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url));
  355. } catch {
  356. return resolvePath(process.argv[1]) === fileURLToPath(import.meta.url);
  357. }
  358. }
  359. if (isDirectRun()) {
  360. runDoctor(HOST).catch((err) => {
  361. console.error("ov-memory-doctor failed:", err?.stack || err?.message || err);
  362. process.exit(2);
  363. });
  364. }
examples/claude-code-memory-plugin/setup-helper/tos-install.sh · Bundled script · 28 lines · 1 finding marked
  1. #!/usr/bin/env bash
  2. #
  3. # OpenViking Memory Plugin for Claude Code — TOS bootstrap (China-friendly).
  4. #
  5. # For users who can't reach github.com / raw.githubusercontent.com. Pulls the
  6. # shared installer from Volcengine TOS and runs it with the TOS distribution
  7. # channel preselected (Claude preselected as the harness).
  8. #
  9. # One-liner:
  10. # bash <(curl -fsSL https://ovrelease.tos-cn-beijing.volces.com/claude-code-memory-plugin/tos-install.sh)
    • Note: Runs a downloaded script through process substitution (bash <(curl …))
    • Line 10 on GitHub
  11. #
  12. # Env overrides:
  13. # OPENVIKING_TOS_BASE default: https://ovrelease.tos-cn-beijing.volces.com
  14. # (every install.sh env override applies too.)
  15. set -euo pipefail
  16. TOS_BASE="${OPENVIKING_TOS_BASE:-https://ovrelease.tos-cn-beijing.volces.com}"
  17. TOS_BASE="${TOS_BASE%/}"
  18. export OPENVIKING_TOS_BASE="$TOS_BASE"
  19. export OPENVIKING_SHARED_INSTALL_URL="${OPENVIKING_SHARED_INSTALL_URL:-$TOS_BASE/memory-plugin-shared/install.sh}"
  20. # Fetch the real installer to a file (not a pipe) so it keeps the terminal on
  21. # stdin for its interactive prompts.
  22. installer=$(mktemp "${TMPDIR:-/tmp}/ov-cc-install.XXXXXX") || { echo "mktemp failed" >&2; exit 1; }
  23. trap 'rm -f "$installer"' EXIT
  24. curl -fsSL -o "$installer" "$OPENVIKING_SHARED_INSTALL_URL"
  25. bash "$installer" --harness claude --dist tos "$@"

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.