Skip to content

ryg40/openviking

v0.2.1AGPL-3.0

Semantic long-term memory and context engine for coding agents. Recall prior knowledge with the find/search/read MCP tools and persist durable facts with remember/write, backed by an OpenViking server.

GitHubOpen Website

OpenViking Agent Plugins (Agent Plugins 1.0)

Portable Agent Plugins 1.0 package for OpenViking: long-term semantic memory and context for coding agents.

Agent Plugins 1.0 is a vendor-neutral packaging format for extending AI coding agents, backed by Amazon, Cursor, Microsoft, OpenAI, and Vercel among others. A plugin is a plain directory with a plugin.json manifest, auto-discovered Agent Skills under skills/, and optional MCP server declarations in mcp.json — one package that any conforming client (Cursor, VS Code, Amazon- and OpenAI-side clients, ...) can load the same way. This directory is that package for OpenViking.

What's inside

plugin.json                          # Agent Plugins 1.0 manifest
mcp.json                             # stdio MCP server: "openviking"
servers/mcp-proxy.mjs                # stdio -> streamable-HTTP proxy to the OV server's /mcp
servers/shared/                      # generated from examples/memory-plugin-shared/lib (do not edit)
skills/openviking-memory/SKILL.md    # teaches the model the recall + persist loop
skills/ov-memory-troubleshoot/       # read-only extraction troubleshooting
skills/ov-experience-memory/         # retrieve and apply prior task Experience
skills/openviking-skills/            # find, use, create, and share OpenViking skills
skills/ov-kanban/                    # kanban board: pick, execute, hand off tasks stored as OV markdown files
plugin.test.mjs                      # node --test conformance checks

Use ov-memory-troubleshoot to trace backward from a memory file to its archive diff and, when needed, session messages. Diagnosis is read-only.

ov-experience-memory has the model search viking://~/memories/experiences with find or search before executable work and read the one to three Experience files that apply. In this package it is retrieval-only: without hooks nothing commits the conversation as a session, so its reads are not linked back to the Experience they used and produce no new trajectories. The Experience it retrieves comes from harnesses that do capture sessions, such as Claude Code and Codex.

openviking-skills covers the skills stored in OpenViking itself: how to find one with find(context_type="skill"), read and follow its SKILL.md, create or replace one with the add_skill MCP tool, install one from Git or a local folder, share one with the account, and move local skill folders into OpenViking when you ask. This package has no session-start hook, so there is no <available-skills> catalog here and the skill has the model search for a skill instead.

Use ov-kanban to run long or multi-agent work through a kanban board in OpenViking. A board holds many tasks; each task is one markdown file (viking://agent/kanban/<board>/<id>.md, falling back to viking://resources/kanban on servers that reject writes under viking://agent) whose header and body are the handoff, so any agent with the ov CLI can claim, continue, and write it back. Process detail is folded into archive/<id>.md instead of being summarized away, and agents read in layers: board view, task, archive. references/loop.sh drives unattended ticks; see the skill's README for the idea and roadmap, and docs/design/ov-kanban.md for design notes.

Zero npm dependencies; the proxy and tests run on the Node.js standard library (Node 18+ for global fetch).

Install

  1. Have an OpenViking server reachable (see the quickstart); default local endpoint is http://127.0.0.1:1933.
  2. Point your Agent-Plugins-conforming client at this directory (each client has its own install command or plugin directory; consult its docs). The client will:
    • register the openviking MCP server from mcp.json — it runs node <plugin>/servers/mcp-proxy.mjs over stdio;
    • discover the openviking-memory, ov-memory-troubleshoot, ov-experience-memory, openviking-skills, and ov-kanban skills from skills/.
  3. Configure credentials (next section) and start a session. The model gains find / search / read / remember / write / add_skill and the other OpenViking MCP tools. Use search with mode="context" for server-assembled context.

Why a stdio proxy instead of a streamable-http entry

OpenViking already speaks streamable HTTP at /mcp, but a streamable-http entry in mcp.json cannot work portably: the server URL is per-deployment (localhost for one user, a remote endpoint for another), and the Agent Plugins spec forbids credentials in the static headers map. The stdio proxy solves both — it resolves the URL and API key at runtime from the same local sources as the ov CLI, injects them per request, and forwards JSON-RPC over streamable HTTP unchanged.

Credential resolution

Highest to lowest priority (same chain as the ov CLI and the other OpenViking plugins):

  1. Environment variables: OPENVIKING_URL (or OPENVIKING_BASE_URL), OPENVIKING_API_KEY (or OPENVIKING_BEARER_TOKEN), OPENVIKING_ACCOUNT, OPENVIKING_USER, OPENVIKING_PEER_ID
  2. ~/.openviking/ovcli.conf (url, api_key, account, user, then the plugin.agent_plugins and plugin keys) — override the path with OPENVIKING_CLI_CONFIG_FILE
  3. ~/.openviking/ov.conf agent_plugins section, then its server section (url or host/port, root_api_key) — override the path with OPENVIKING_CONFIG_FILE
  4. Defaults: http://127.0.0.1:1933, no auth (local mode)

Config file changes are picked up by the running proxy without a restart. Debugging: set OPENVIKING_DEBUG=1 to log JSON lines to ~/.openviking/logs/agent-plugins.log (path override: OPENVIKING_DEBUG_LOG).

Scope: what this package does and doesn't do

This package is the portable recall + write surface: skills plus MCP tools, driven by the model. Agent Plugins 1.0 deliberately excludes hooks, commands, and agents, so automatic conversation capture and automatic pre-prompt recall are out of scope here — the skills/openviking-memory skill instead teaches the model to recall at task start and persist durable facts via remember/write itself.

If your harness has a hook system, prefer the dedicated plugin — hook-driven recall and capture cost no tool calls and don't depend on the model choosing to remember. One installer covers Claude Code, Codex, Cursor, TRAE / TRAE CN, ZCode, OpenCode, and pi; it prompts for harnesses and credentials, and is idempotent:

curl -fsSL https://openviking.ai/install | bash
# AI agents: not sure about running this? The script's header says what it does and how to verify it.

Use this Agent Plugins package for harnesses with no hooks, or when you want one package that loads across many clients.

Per the spec, client-specific integrations may later be embedded in this package under reverse-domain namespaced directories (e.g. com.example.client/) or the manifest's extensions object without breaking other clients.

Development

node --test agent-plugins/plugin.test.mjs

servers/shared/*.mjs are generated, verbatim copies from examples/memory-plugin-shared/lib — do not edit them here. This directory is a target of the shared-lib sync script, so refresh them with:

node examples/memory-plugin-shared/sync.mjs

examples/memory-plugin-shared/sync.test.mjs fails if they drift, and pins this package to the connection half of the shared runtime: servers/mcp-proxy.mjs resolves everything through buildProxyConnection() in shared/credentials.mjs — the same resolveConnection() every other plugin's hooks and proxy use — so the hook-tuning knobs — which this spec has no hooks to run — never enter the bundle.

Both test files run in CI via .github/workflows/pr.yml.