Skip to content

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

fix(hermes): validate OpenViking forget URIs (#5185)

Hao Zheec0863054154
diff --git a/examples/hermes-plugin/README.md b/examples/hermes-plugin/README.md
index d92d2f7f6..f2936f44f 100644
--- a/examples/hermes-plugin/README.md
+++ b/examples/hermes-plugin/README.md
@@ -63,11 +63,11 @@ The plugin connects over HTTP. Do not install the OpenViking server into the
Hermes environment. For local server start from the setup wizard, make the
`openviking-server` command available on `PATH`.
-OpenViking 0.2.10 or newer is recommended. For backward compatibility,
-Hermes can identify older servers that expose the legacy status-only health
-response, but only when anonymous OpenAPI metadata also identifies the service
-as OpenViking. OpenViking 0.2.6 and earlier are deprecated for this integration;
-upgrade them to receive the current health contract and compatibility fixes.
+OpenViking 0.2.14 or newer is required. Hermes can identify older servers that
+expose the legacy status-only health response, but those releases do not provide
+the authenticated-user identity contract required by this integration.
+The `viking://~` home alias requires OpenViking 0.4.16 or newer for user and
+admin credentials, and OpenViking 0.4.17 or newer for root or local development.
## Setup
@@ -222,9 +222,10 @@ memory URI.
`viking_forget` is intentionally narrow. It only accepts concrete user memory
file URIs, such as
-`viking://user/default/peers/hermes/memories/preferences/mem_abc123.md` (any
-explicit user id works; `viking://~/...` input is passed through untouched for
-deployments where the server expands the home alias). Files
+`viking://user/default/peers/hermes/memories/preferences/mem_abc123.md`, or the
+`viking://~/...` self alias. Under `viking://user/...` the user id is required
+and must match the calling identity; the uid-less `viking://user/memories/...`
+and `viking://user/peers/...` shorthands are deprecated and rejected. Files
directly under `memories/`, such as `viking://user/default/memories/profile.md`,
are also allowed because OpenViking supports them. The tool rejects directories,
resources, skills, sessions, generated summary files, and URIs with query
diff --git a/examples/hermes-plugin/__init__.py b/examples/hermes-plugin/__init__.py
index 07331b3fa..59f62a683 100644
--- a/examples/hermes-plugin/__init__.py
+++ b/examples/hermes-plugin/__init__.py
@@ -107,9 +107,9 @@ _CONFIG_SCHEMA = [
# Typed settings (config.yaml primary, env override) keyed by config key.
_SETTING_SPECS = {f["key"]: f for f in _CONFIG_SCHEMA if "type" in f}
_RECALL_SETTING_KEYS = tuple(k for k in _SETTING_SPECS if k.startswith("recall_"))
-# Explicit-uid URIs (viking://user/<uid>/...) work under every auth mode; the `~`
-# alias only expands for USER/ADMIN roles and is rejected with 400 under dev/ROOT,
-# so the user space is resolved client-side from /api/v1/system/status.
+# Explicit-uid URIs (viking://user/<uid>/...) work under every auth mode and
+# supported OpenViking version. The `~` alias requires OpenViking 0.4.16+ for
+# USER/ADMIN roles and 0.4.17+ for ROOT, so internal paths remain explicit.
_SESSION_START_SUFFIXES = ("memories/profile.md", "memories/preferences", "memories/entities")
_SESSION_START_LIST_PARAMS = {"output": "agent", "recursive": True, "abs_limit": 512, "node_limit": 512}
# Built-in memory tool `target` -> mirror subdir (user facts -> preferences, agent notes -> patterns).
@@ -136,7 +136,7 @@ _FIX_ENDPOINT = "OpenViking memory is temporarily unavailable; correct the endpo
_HTTPX_MISSING = "httpx not installed — OpenViking plugin disabled"
_LEGACY_OPENVIKING_IDENTITY_DETAIL = (
"returned OpenViking's legacy health response, but its anonymous OpenAPI metadata did not identify OpenViking. "
- "If this is OpenViking 0.2.6 or earlier, upgrade to OpenViking 0.2.10 or newer."
+ "If this is OpenViking 0.2.6 or earlier, upgrade to OpenViking 0.2.14 or newer."
)
_PENDING_SESSIONS_RELATIVE_DIR = Path("openviking") / "pending_sessions"
_RUN_LOCKS_RELATIVE_DIR = Path("openviking") / "runs"
@@ -500,7 +500,7 @@ def _is_windows_absolute_path(value: str) -> bool:
return len(value) >= 3 and value[0].isalpha() and value[1] == ":" and value[2] in {"/", "\\"}
-def _validate_forget_memory_uri(raw_uri: Any) -> tuple[Optional[str], Optional[str]]:
+def _validate_forget_memory_uri(raw_uri: Any, *, user_space: Optional[str] = None) -> tuple[Optional[str], Optional[str]]:
uri = raw_uri.strip() if isinstance(raw_uri, str) else ""
if not uri:
return None, "uri is required"
@@ -512,11 +512,23 @@ def _validate_forget_memory_uri(raw_uri: Any) -> tuple[Optional[str], Optional[s
if uri.endswith("/") or not uri.endswith(".md"):
return None, "viking_forget only deletes concrete .md memory files"
parts = [part for part in uri[len("viking://") :].split("/") if part]
- # ``memories`` segment index for the user / user-uid / peer / uid-peer layouts.
- memories_idx = next((idx for idx, peer_at in ((1, None), (2, None), (3, 1), (4, 2))
- if parts[:1] == ["user"] and len(parts) > idx and parts[idx] == "memories" and (peer_at is None or parts[peer_at] == "peers")), None)
+ if any(unquote(part) in {".", ".."} for part in parts):
+ return None, "viking_forget does not accept dot path segments"
+ # ``memories`` index for ``<scope>/[peers/<agent>/]memories/``; under ``user`` the uid is
+ # required, since the uid-less shorthands are deprecated upstream.
+ offsets = ((1, None), (3, 1)) if parts[:1] == ["~"] else ((2, None), (4, 2)) if parts[:1] == ["user"] else ()
+ memories_idx = next((idx for idx, peer_at in offsets
+ if len(parts) > idx and parts[idx] == "memories" and (peer_at is None or parts[peer_at] == "peers")), None)
if memories_idx is None or len(parts) < memories_idx + 2:
return None, "viking_forget only deletes user memory file URIs"
+ # An explicit uid can name someone else's space. Do not send a destructive
+ # request unless the server has confirmed that this uid belongs to the caller.
+ if parts[0] == "user":
+ if not user_space:
+ return None, "viking_forget could not verify the current OpenViking user identity; retry or use viking://~/..."
+ if parts[1] != user_space:
+ return None, (f"viking_forget only deletes your own memories; use viking://user/{user_space}/... "
+ "or viking://~/... instead")
if uri.rsplit("/", 1)[-1] in _GENERATED_MEMORY_SUMMARY_FILENAMES:
return None, "viking_forget cannot delete generated memory summary files"
return uri, None
@@ -2484,9 +2496,8 @@ class OpenVikingMemoryProvider(MemoryProvider):
reload mid-write can't borrow a later peer; an empty peer there is intentional.
getattr(): hand-wired providers (``__new__``) may lack ``_client`` / ``_agent``.
"""
- # Explicit-uid URIs are canonical under every auth mode; the uid-less `viking://user/peers/...`
- # shorthand was removed upstream (#4196) and `viking://~/...` only expands for USER/ADMIN roles, not
- # dev/ROOT.
+ # Explicit-uid URIs are canonical across supported OpenViking versions. The
+ # uid-less shorthand was removed upstream, and `viking://~` is newer.
active_client = client if client is not None else getattr(self, "_client", None)
agent = str(getattr(active_client, "_agent", getattr(self, "_agent", "")) or "").strip()
peer_prefix = f"peers/{agent}/" if agent else ""
@@ -2696,10 +2707,12 @@ class OpenVikingMemoryProvider(MemoryProvider):
})
def _tool_forget(self, args: dict) -> str:
- uri, error = _validate_forget_memory_uri(args.get("uri"))
+ # _resolve_user_space, not _user_space: its "default" fallback is a guess, not an identity.
+ client = self._client
+ uri, error = _validate_forget_memory_uri(args.get("uri"), user_space=_resolve_user_space(client))
if error:
return tool_error(error)
- result = self._unwrap_result(self._client.delete("/api/v1/fs", params={"uri": uri, "recursive": False}))
+ result = self._unwrap_result(client.delete("/api/v1/fs", params={"uri": uri, "recursive": False}))
result = result if isinstance(result, dict) else {}
payload = {"status": "deleted", "uri": result.get("uri") or uri,
**{key: result[key] for key in ("estimated_deleted_count", "memory_cleanup", "semantic_root_uri", "semantic_status", "queue_status") if key in result}}
diff --git a/examples/hermes-plugin/tests/test_standalone.py b/examples/hermes-plugin/tests/test_standalone.py
index 4fd3b98a4..2cead086f 100644
--- a/examples/hermes-plugin/tests/test_standalone.py
+++ b/examples/hermes-plugin/tests/test_standalone.py
@@ -179,3 +179,163 @@ def test_cloud_recall_legacy_fallback(external_provider, monkeypatch):
assert provider._search_prefetch_context("deployment preferences", client=client) == ""
assert client.post.call_count == 2
assert "rewrite" not in client.post.call_args.args[1]
+
+
+ "uri",
+ [
+ "viking://user/zayn/memories/profile.md",
+ "viking://user/zayn/memories/preferences/mem_abc123.md",
+ "viking://user/zayn/peers/hermes/memories/preferences/mem_abc123.md",
+ "viking://~/memories/profile.md",
+ "viking://~/memories/preferences/mem_abc123.md",
+ "viking://~/peers/hermes/memories/preferences/mem_abc123.md",
+ ],
+)
+def test_external_provider_accepts_canonical_forget_uris(external_provider, uri):
+ _, _, module, _ = external_provider("forget-canonical")
+ user_space = "zayn" if uri.startswith("viking://user/") else None
+
+ assert module._validate_forget_memory_uri(uri, user_space=user_space) == (uri, None)
+
+
+ "uri",
+ [
+ "viking://user/memories/preferences/mem_abc123.md",
+ "viking://user/peers/hermes/memories/preferences/mem_abc123.md",
+ ],
+)
+def test_external_provider_rejects_uidless_forget_uris(external_provider, uri):
+ _, _, module, _ = external_provider("forget-uidless")
+
+ resolved, error = module._validate_forget_memory_uri(uri)
+
+ assert resolved is None
+ assert "user memory file URIs" in error
+
+
+def test_external_provider_rejects_other_user_forget_uri(external_provider):
+ _, _, module, _ = external_provider("forget-other-user")
+ uri = "viking://user/someone-else/memories/preferences/mem_abc123.md"
+
+ resolved, error = module._validate_forget_memory_uri(uri, user_space="zayn")
+
+ assert resolved is None
+ assert "your own memories" in error
+
+
+def test_external_provider_forget_fails_closed_without_identity(external_provider):
+ _, provider, _, _ = external_provider("forget-unverified")
+ delete_calls = []
+
+ class UnverifiedClient:
+ def get(self, _path, **_kwargs):
+ raise RuntimeError("identity probe unavailable")
+
+ def delete(self, path, **kwargs):
+ delete_calls.append((path, kwargs))
+ return {"result": {}}
+
+ provider._client = UnverifiedClient()
+ result = json.loads(
+ provider._tool_forget({"uri": "viking://user/alice/memories/preferences/mem_abc123.md"})
+ )
+
+ assert "identity" in result["error"].lower()
+ assert delete_calls == []
+
+
+ "uri",
+ [
+ "viking://user/alice/memories/./x.md",
+ "viking://user/alice/memories/../../user/bob/memories/x.md",
+ "viking://user/alice/memories/%2e/x.md",
+ "viking://user/alice/memories/%2e%2e/x.md",
+ "viking://~/memories/../x.md",
+ ],
+)
+def test_external_provider_rejects_dot_segments_in_forget_uri(external_provider, uri):
+ _, _, module, _ = external_provider("forget-dot-segments")
+
+ resolved, error = module._validate_forget_memory_uri(uri, user_space="alice")
+
+ assert resolved is None
+ assert "dot path segments" in error
+
+
+ "uri",
+ [
+ "viking://user/alice/memories/preferences/mem_abc123.md",
+ "viking://~/memories/preferences/mem_abc123.md",
+ ],
+)
+def test_external_provider_forget_keeps_verified_connection(external_provider, uri):
+ _, provider, module, _ = external_provider("forget-connection-snapshot")
+ identity_requested = threading.Event()
+ continue_identity = threading.Event()
+ requests = {"a": [], "b": []}
+
+ def handler_for(server_name):
+ class Handler(BaseHTTPRequestHandler):
+ def do_GET(self):
+ requests[server_name].append(("GET", self.path))
+ identity_requested.set()
+ assert continue_identity.wait(timeout=5)
+ self._respond({"status": "ok", "result": {"user": "alice"}})
+
+ def do_DELETE(self):
+ requests[server_name].append(("DELETE", self.path))
+ self._respond({"status": "ok", "result": {"uri": uri}})
+
+ def _respond(self, payload):
+ body = json.dumps(payload).encode()
+ self.send_response(200)
+ self.send_header("Content-Type", "application/json")
+ self.send_header("Content-Length", str(len(body)))
+ self.end_headers()
+ self.wfile.write(body)
+
+ def log_message(self, *_args):
+ pass
+
+ return Handler
+
+ servers = [
+ HTTPServer(("127.0.0.1", 0), handler_for(server_name))
+ for server_name in ("a", "b")
+ ]
+ server_threads = [
+ threading.Thread(target=server.serve_forever, daemon=True) for server in servers
+ ]
+ for server_thread in server_threads:
+ server_thread.start()
+
+ provider._client = module._VikingClient(f"http://127.0.0.1:{servers[0].server_port}")
+ result = []
+ tool_thread = threading.Thread(
+ target=lambda: result.append(provider.handle_tool_call("viking_forget", {"uri": uri}))
+ )
+ tool_thread.start()
+ try:
+ assert identity_requested.wait(timeout=5)
+ provider._client = module._VikingClient(
+ f"http://127.0.0.1:{servers[1].server_port}"
+ )
+ continue_identity.set()
+ tool_thread.join(timeout=5)
+
+ assert not tool_thread.is_alive()
+ assert json.loads(result[0])["status"] == "deleted"
+ assert [method for method, _ in requests["a"]] == ["GET", "DELETE"]
+ assert requests["b"] == []
+ finally:
+ continue_identity.set()
+ tool_thread.join(timeout=5)
+ for server in servers:
+ server.shutdown()
+ server.server_close()
+ for server_thread in server_threads:
+ server_thread.join(timeout=5)