Skip to content

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

fix(memory): make generated URIs Windows-safe (#4517)

DuTao76ab53ac67e3
diff --git a/openviking/session/memory/utils/uri.py b/openviking/session/memory/utils/uri.py
index d3ca152be..feb724efc 100644
--- a/openviking/session/memory/utils/uri.py
+++ b/openviking/session/memory/utils/uri.py
@@ -6,6 +6,7 @@ URI generation and validation utilities.
from __future__ import annotations
+import hashlib
import re
from typing import Any, Dict, Set
@@ -13,6 +14,110 @@ from openviking.session.memory.dataclass import MemoryTypeSchema
from openviking.session.memory.utils.model import model_to_dict
from openviking.session.memory.utils.template_utils import TemplateUtils
+_PORTABLE_SEGMENT_MARKER = "~ov~"
+_PORTABLE_SEGMENT_HASH_LENGTH = 16
+_WINDOWS_INVALID_CHARS = frozenset('<>:"\\|?*')
+_WINDOWS_RESERVED_STEMS = frozenset(
+ {
+ "CON",
+ "PRN",
+ "AUX",
+ "NUL",
+ *(f"COM{index}" for index in range(1, 10)),
+ *(f"LPT{index}" for index in range(1, 10)),
+ }
+)
+
+
+def _windows_reserved_stem(segment: str) -> str:
+ """Return the Win32 device-name stem used for portability checks."""
+ return segment.split(".", 1)[0].rstrip(" .").upper()
+
+
+def _is_portable_uri_segment(segment: str) -> bool:
+ """Return whether a rendered URI segment is safe as a Windows path component."""
+ if not segment or segment in {".", ".."}:
+ return False
+ if segment.endswith((" ", ".")):
+ return False
+ if _PORTABLE_SEGMENT_MARKER in segment:
+ # Reserve the generated marker so a literal segment cannot alias one.
+ return False
+ for character in segment:
+ codepoint = ord(character)
+ if (
+ character in _WINDOWS_INVALID_CHARS
+ or codepoint < 32
+ or codepoint == 127
+ or 0xD800 <= codepoint <= 0xDFFF
+ ):
+ return False
+ return _windows_reserved_stem(segment) not in _WINDOWS_RESERVED_STEMS
+
+
+def _split_safe_extension(segment: str) -> tuple[str, str]:
+ """Split a conventional final extension so rewritten memory files keep it."""
+ stem, separator, extension = segment.rpartition(".")
+ if not separator or not stem or not extension:
+ return segment, ""
+ if any(
+ character in _WINDOWS_INVALID_CHARS
+ or ord(character) < 32
+ or ord(character) == 127
+ or 0xD800 <= ord(character) <= 0xDFFF
+ for character in extension
+ ):
+ return segment, ""
+ return stem, f".{extension}"
+
+
+def _portable_uri_segment(segment: str) -> str:
+ """Rewrite one non-portable segment without collapsing distinct logical names."""
+ if _is_portable_uri_segment(segment):
+ return segment
+
+ digest = hashlib.sha256(segment.encode("utf-8", errors="surrogatepass")).hexdigest()
+ suffix = f"{_PORTABLE_SEGMENT_MARKER}{digest[:_PORTABLE_SEGMENT_HASH_LENGTH]}"
+
+ cleaned = "".join(
+ character
+ if (
+ character not in _WINDOWS_INVALID_CHARS
+ and ord(character) >= 32
+ and ord(character) != 127
+ and not 0xD800 <= ord(character) <= 0xDFFF
+ )
+ else "_"
+ for character in segment
+ ).rstrip(" .")
+ if not cleaned or cleaned in {".", ".."}:
+ cleaned = "_"
+ if _windows_reserved_stem(cleaned) in _WINDOWS_RESERVED_STEMS:
+ cleaned = f"_{cleaned}"
+
+ stem, extension = _split_safe_extension(cleaned)
+ stem = stem.rstrip(" .") or "_"
+ return f"{stem}{suffix}{extension}"
+
+
+def _make_uri_path_segments_portable(uri: str) -> str:
+ """Make every rendered memory URI segment portable on supported filesystems.
+
+ Clean segments remain byte-identical. A non-portable segment keeps a readable
+ safe prefix and receives a deterministic digest of its original value, so
+ values such as ``Desktop``, ``Desktop ``, and ``Desktop.`` stay distinct.
+ """
+ scheme_separator = "://"
+ if scheme_separator in uri:
+ scheme, _, path = uri.partition(scheme_separator)
+ prefix = f"{scheme}{scheme_separator}"
+ else:
+ prefix, path = "", uri
+
+ if not path:
+ return uri
+ return prefix + "/".join(_portable_uri_segment(segment) for segment in path.split("/"))
+
def render_template(
template: str,
@@ -46,7 +151,7 @@ def generate_uri(
fields: Dict[str, Any],
user_space: str = "default",
extract_context: Any = None,
-) -> tuple[str, str]:
+) -> str:
"""
Generate a full URI from memory type schema and field values.
@@ -81,7 +186,7 @@ def generate_uri(
raise ValueError(f"Template variable '{var}' has None value")
# Render using unified render_template method (same as content_template)
uri = render_template(uri_template, context, extract_context)
- return uri
+ return _make_uri_path_segments_portable(uri)
def validate_uri_template(memory_type: MemoryTypeSchema) -> bool:
diff --git a/tests/session/memory/test_memory_utils.py b/tests/session/memory/test_memory_utils.py
index 5ae21225a..1b7a3f61c 100644
--- a/tests/session/memory/test_memory_utils.py
+++ b/tests/session/memory/test_memory_utils.py
@@ -141,6 +141,118 @@ class TestUriGeneration:
with pytest.raises(ValueError, match="has None value"):
generate_uri(memory_type, {"topic": None})
+ def test_generate_uri_makes_windows_unsafe_directory_segment_collision_resistant(self):
+ """The exact #4308 shape is portable without changing the LLM field."""
+ memory_type = MemoryTypeSchema(
+ memory_type="events",
+ description="Event memory",
+ directory="viking://user/{{ user_space }}/memories/events",
+ filename_template="2026/07/30/{{ event_name }}.md",
+ fields=[
+ MemoryField(
+ name="event_name",
+ field_type=FieldType.STRING,
+ merge_op=MergeOp.IMMUTABLE,
+ )
+ ],
+ )
+ fields = {"event_name": "Desktop /new report"}
+
+ uri = generate_uri(memory_type, fields, user_space="default")
+
+ assert uri == (
+ "viking://user/default/memories/events/2026/07/30/"
+ "Desktop~ov~02970756851a43cf/new report.md"
+ )
+ assert fields == {"event_name": "Desktop /new report"}
+
+ def test_generate_uri_keeps_colliding_windows_names_distinct(self):
+ memory_type = MemoryTypeSchema(
+ memory_type="scratch",
+ description="Scratch memory",
+ directory="viking://user/{{ user_space }}/memories/scratch",
+ filename_template="{{ name }}/item",
+ fields=[
+ MemoryField(
+ name="name",
+ field_type=FieldType.STRING,
+ merge_op=MergeOp.IMMUTABLE,
+ )
+ ],
+ )
+
+ uris = {
+ name: generate_uri(memory_type, {"name": name})
+ for name in ("Desktop", "Desktop ", "Desktop.", "Desktop~notes", "_", " ")
+ }
+
+ assert len(set(uris.values())) == len(uris)
+ assert uris["Desktop"].endswith("/Desktop/item")
+ assert uris["Desktop "].endswith("/Desktop~ov~02970756851a43cf/item")
+ assert uris["Desktop."].endswith("/Desktop~ov~3c65b627123c925e/item")
+ assert uris["Desktop~notes"].endswith("/Desktop~notes/item")
+ assert uris["_"].endswith("/_/item")
+ assert uris[" "].endswith("/_~ov~0aad7da77d2ed59c/item")
+
+ @pytest.mark.parametrize(
+ ("name", "expected_filename"),
+ [
+ ("CON.md", "_CON~ov~ab20d2f97c036c47.md"),
+ ("bad:name.md", "bad_name~ov~a5895459cfd9b57c.md"),
+ ],
+ )
+ def test_generate_uri_rewrites_other_windows_invalid_names_and_keeps_extension(
+ self,
+ name,
+ expected_filename,
+ ):
+ memory_type = MemoryTypeSchema(
+ memory_type="scratch",
+ description="Scratch memory",
+ directory="viking://user/{{ user_space }}/memories/scratch",
+ filename_template="{{ name }}",
+ fields=[],
+ )
+
+ uri = generate_uri(memory_type, {"name": name})
+
+ assert uri.endswith(f"/{expected_filename}")
+
+ def test_generate_uri_reserved_marker_cannot_alias_generated_name(self):
+ memory_type = MemoryTypeSchema(
+ memory_type="scratch",
+ description="Scratch memory",
+ directory="viking://user/{{ user_space }}/memories/scratch",
+ filename_template="{{ name }}/item",
+ fields=[],
+ )
+ generated_uri = generate_uri(memory_type, {"name": "Desktop "})
+ generated_name = generated_uri.rsplit("/", 2)[-2]
+
+ literal_uri = generate_uri(memory_type, {"name": generated_name})
+
+ assert literal_uri != generated_uri
+
+ def test_generate_uri_portability_applies_to_every_template_segment(self):
+ memory_type = MemoryTypeSchema(
+ memory_type="preferences",
+ description="Preference memory",
+ directory="viking://user/{{ user_space }}/memories/preferences",
+ filename_template="{{ user }}/{{ topic }}",
+ fields=[],
+ )
+ fields = {"user": "Alice ", "topic": "CON"}
+
+ first_uri = generate_uri(memory_type, fields, user_space="default")
+ second_uri = generate_uri(memory_type, fields, user_space="default")
+
+ assert first_uri == second_uri
+ assert first_uri == (
+ "viking://user/default/memories/preferences/"
+ "Alice~ov~11f75fc2e111eb7d/_CON~ov~a3dbc4b644a9a2c5"
+ )
+ assert fields == {"user": "Alice ", "topic": "CON"}
+
def test_validate_uri_template_valid(self):
"""Test validating a valid URI template."""
memory_type = MemoryTypeSchema(
diff --git a/tests/session/memory/test_streaming_memory_updater.py b/tests/session/memory/test_streaming_memory_updater.py
index 0a2ff297a..43d18cdf6 100644
--- a/tests/session/memory/test_streaming_memory_updater.py
+++ b/tests/session/memory/test_streaming_memory_updater.py
@@ -970,6 +970,28 @@ def test_enforce_merge_group_peer_id_rewrites_merged_output_scope():
assert op.uris == ["viking://user/u/peers/conv-42/memories/notes/peer_note.md"]
+def test_enforce_merge_group_reapplies_portable_uri_without_changing_memory_name():
+ op = ResolvedOperation(
+ old_memory_file_content=None,
+ memory_fields={"note_name": "Desktop /new", "content": "peer content"},
+ memory_type="notes",
+ uris=["viking://user/u/memories/notes/temporary.md"],
+ )
+
+ enforce_merge_group_peer_id(
+ [op],
+ peer_id="conv-42",
+ memory_type="notes",
+ registry=_registry(),
+ ctx=_ctx(),
+ )
+
+ assert op.memory_fields["note_name"] == "Desktop /new"
+ assert op.uris == [
+ "viking://user/u/peers/conv-42/memories/notes/Desktop~ov~02970756851a43cf/new.md"
+ ]
+
+
def test_enforce_merge_group_self_scope_removes_peer_id():
op = ResolvedOperation(
old_memory_file_content=None,