Skip to content

Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.

refactor(agent-plugins): split optional MCP tools into a skill reference subdirectory (#4199)

Zayn Jarvis2cc7ec47241c
diff --git a/agent-plugins/plugin.test.mjs b/agent-plugins/plugin.test.mjs
index 12e6daeb6..ec0f46b85 100644
--- a/agent-plugins/plugin.test.mjs
+++ b/agent-plugins/plugin.test.mjs
@@ -174,6 +174,24 @@ test("every skills/* child ships a SKILL.md with name + description frontmatter"
}
});
+test("relative markdown links inside skills resolve to real files", () => {
+ const skillsDir = join(PLUGIN_ROOT, "skills");
+ const children = readdirSync(skillsDir).filter((entry) =>
+ statSync(join(skillsDir, entry)).isDirectory(),
+ );
+ for (const child of children) {
+ const skillPath = join(skillsDir, child, "SKILL.md");
+ const raw = readFileSync(skillPath, "utf-8");
+ const links = [...raw.matchAll(/\]\((?!https?:|#)([^)]+)\)/g)].map((m) => m[1]);
+ for (const rel of links) {
+ assert.ok(
+ existsSync(join(skillsDir, child, rel)),
+ `${child}/SKILL.md links to missing file: ${rel}`,
+ );
+ }
+ }
+});
+
test("all .mjs files in the plugin pass node --check", () => {
const files = listMjsFiles(PLUGIN_ROOT);
assert.ok(files.length > 0, "expected vendored .mjs files");
diff --git a/agent-plugins/skills/openviking-memory/SKILL.md b/agent-plugins/skills/openviking-memory/SKILL.md
index 6a22f6840..cf46ff535 100644
--- a/agent-plugins/skills/openviking-memory/SKILL.md
+++ b/agent-plugins/skills/openviking-memory/SKILL.md
@@ -1,6 +1,6 @@
---
name: openviking-memory
-description: Recall and persist long-term memory through the OpenViking MCP tools. Use at the start of any substantive task (coding, configuration, debugging, multi-step or tool-based work) to retrieve relevant prior knowledge with find/search/read, and during or after work to persist durable facts, preferences, decisions, and lessons with remember/write. Do not use for casual chat or simple factual questions the model can answer directly.
+description: Recall and persist long-term memory through the OpenViking MCP tools. Use at the start of any substantive task (coding, configuration, debugging, multi-step or tool-based work) to retrieve relevant prior knowledge with find/search/read, and during or after work to persist durable facts, preferences, decisions, and lessons with remember. Do not use for casual chat or simple factual questions the model can answer directly.
---
# OpenViking Memory
@@ -8,16 +8,22 @@ description: Recall and persist long-term memory through the OpenViking MCP tool
OpenViking is a long-term semantic memory store addressed by `viking://` URIs.
This client has no lifecycle hooks, so nothing is recalled or captured
automatically — you drive both halves of the loop with the `openviking` MCP
-tools:
+tools.
-- Recall: `find`, `search`, `read`, `list`, `tree`, `grep`, `glob`
-- Persist: `remember`, `write`, `edit`, `add_resource`
+Core tools, available on every supported deployment:
+
+- Recall: `find`, `search`, `read`, `list`, `grep`, `glob`
+- Persist: `remember`, `add_resource`
- Maintain: `forget`, `health`
-Use only the tools the session actually registered — the exact set depends on
-the server version, and `tree`, `write`, and `edit` are absent on older
-deployments. If no OpenViking tools are registered at all, continue without
-memory. Do not fabricate tool calls or fall back to raw HTTP.
+Some deployments register more than the core set — `tree`, `write`, `edit`,
+`list_watches`, `cancel_watch`. These are optional: which ones exist depends
+on the server version and hosting mode (the managed cloud service trims some
+of them). Check the session's registered tool list; if any optional tool is
+present, read [references/optional-tools.md](references/optional-tools.md)
+before using it. Never call a tool that is not registered, and do not fall
+back to raw HTTP. If no OpenViking tools are registered at all, continue
+without memory.
## Recall: at task start
@@ -55,12 +61,13 @@ session:
(preferences, entities, events, experience) on its own. Use it when the user
says "remember this", states a lasting preference or decision, or when a
hard-won lesson (root cause, working procedure, environment quirk) emerges.
-- `write(uri, content)` / `edit` — when you need an exact document at a known
- location, such as curated notes under `viking://~/` (your own user root) or shared reference
- material under `viking://resources/`. Prefer `edit` over rewriting whole
- files. If neither tool is registered, fall back to `remember`.
- `add_resource` — to import external documents or URLs as searchable
resources.
+- When you need an exact document at a known location (curated notes under
+ `viking://~/` — your own user root — or shared reference material under
+ `viking://resources/`), the optional `write` / `edit` tools cover that — see
+ [references/optional-tools.md](references/optional-tools.md). If they are
+ not registered, fall back to `remember`.
What to persist: stable preferences and conventions, environment facts,
decisions with their rationale, and reusable procedures or fixes. What not to
diff --git a/agent-plugins/skills/openviking-memory/references/optional-tools.md b/agent-plugins/skills/openviking-memory/references/optional-tools.md
new file mode 100644
index 000000000..5ddbe495a
--- /dev/null
+++ b/agent-plugins/skills/openviking-memory/references/optional-tools.md
@@ -0,0 +1,47 @@
+# Optional OpenViking MCP tools
+
+Tools listed here are not part of the core set: whether they exist depends on
+the server version and hosting mode. Only read the sections for tools that
+actually appear in this session's registered tool list, and never call one
+that is absent — SKILL.md's core loop works without any of them.
+
+Availability summary:
+
+| Tool | Server requirement | Managed cloud service |
+|---|---|---|
+| `tree` | ≥ 0.4.14 | after the cloud rolls to 0.4.14 |
+| `write`, `edit` | ≥ 0.4.14 | after the cloud rolls to 0.4.14 |
+| `list_watches`, `cancel_watch` | ≥ 0.3.18, self-hosted / private | not exposed |
+
+The managed cloud runs stateless multi-instance serving, so account-level
+stateful tools (`list_watches`, `cancel_watch`) are trimmed there even when
+the underlying version has them.
+
+## `tree(uri, level_limit?)`
+
+Directory tree of a `viking://` scope, deeper than one `list` level. Use it to
+orient inside an unfamiliar scope before deciding what to `read`; prefer
+`list` for a single known directory — it is cheaper.
+
+## `write(uri, content, mode?)` and `edit(uri, ...)`
+
+Exact-document persistence at a known URI, complementing `remember` (which
+lets the server file extracted memories on its own):
+
+- `write` replaces, appends to, or creates a file. Creating requires the
+ parent directory to exist.
+- `edit` performs targeted string replacement inside an existing file. Prefer
+ `edit` over rewriting whole files, and re-`read` the file first if your copy
+ of its content might be stale.
+
+Use them for curated notes under `viking://~/` (your own user root) and shared
+reference material under `viking://resources/`. When neither is registered,
+fall back to `remember` as SKILL.md describes.
+
+## `list_watches()` and `cancel_watch(to_uri)`
+
+Manage auto-refresh subscriptions created by `add_resource` with a watch
+interval (private / self-hosted deployments only). `list_watches` shows the
+account's active subscriptions; `cancel_watch` stops one by its target URI.
+Only touch watches the user asked about — cancelling someone's subscription is
+destructive.