Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.
Python agent-contextagent-memoryagent-pluginsagentic-ragcontext-databasedsh-pluginknowledge-basememorymemory-managementself-evolvingvector-database
fix(hermes): validate OpenViking forget URIs (#5185)
Hao Zheec0863054154
diff --git a/examples/hermes-plugin/README.md b/examples/hermes-plugin/README.mdindex 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 theHermes 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 memoryfile 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. Filesdirectly 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 querydiff --git a/examples/hermes-plugin/__init__.py b/examples/hermes-plugin/__init__.pyindex 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[sif 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.pyindex 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 == 2assert "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)