Skip to content

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

feat(agent-evolution): track experience trajectory lineage (#3727)

agent2ced3f1539a2
diff --git a/openviking/server/app.py b/openviking/server/app.py
index 6310aacb3..548b24f5a 100644
--- a/openviking/server/app.py
+++ b/openviking/server/app.py
@@ -31,6 +31,7 @@ from openviking.server.profile_middleware import create_profile_http_middleware
from openviking.server.request_id import REQUEST_ID_HEADER, RequestIdMiddleware
from openviking.server.routers import (
admin_router,
+ agent_evolution_router,
bot_router,
console_router,
content_router,
@@ -89,6 +90,7 @@ def create_worker_app() -> FastAPI:
config.bot_api_url = bot_api_url
return create_app(config, config_path=config_path)
+
async def _initialize_auth_plugin(
app: FastAPI,
service: OpenVikingService,
@@ -572,6 +574,7 @@ def create_app(
# Register routers
app.include_router(system_router)
app.include_router(admin_router)
+ app.include_router(agent_evolution_router)
app.include_router(resources_router)
app.include_router(filesystem_router)
app.include_router(content_router)
diff --git a/openviking/server/routers/__init__.py b/openviking/server/routers/__init__.py
index 3c0a519e3..27c68ac95 100644
--- a/openviking/server/routers/__init__.py
+++ b/openviking/server/routers/__init__.py
@@ -3,6 +3,7 @@
"""OpenViking HTTP Server routers."""
from openviking.server.routers.admin import router as admin_router
+from openviking.server.routers.agent_evolution import router as agent_evolution_router
from openviking.server.routers.bot import router as bot_router
from openviking.server.routers.console import router as console_router
from openviking.server.routers.content import router as content_router
@@ -28,6 +29,7 @@ from openviking.server.routers.webdav import router as webdav_router
__all__ = [
"admin_router",
+ "agent_evolution_router",
"bot_router",
"system_router",
"resources_router",
diff --git a/openviking/server/routers/agent_evolution.py b/openviking/server/routers/agent_evolution.py
new file mode 100644
index 000000000..0652e0d0d
--- /dev/null
+++ b/openviking/server/routers/agent_evolution.py
@@ -0,0 +1,38 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: AGPL-3.0
+"""Agent Evolution endpoints."""
+
+from fastapi import APIRouter, Depends, Query
+
+from openviking.server.auth import get_request_context
+from openviking.server.dependencies import get_service
+from openviking.server.identity import RequestContext
+from openviking.server.models import Response
+from openviking.service.agent_evolution_service import (
+ DEFAULT_TRAJECTORY_PAGE_LIMIT,
+ MAX_TRAJECTORY_PAGE_LIMIT,
+)
+
+router = APIRouter(prefix="/api/v1/agent-evolution", tags=["agent-evolution"])
+
+
[email protected]("/experiences/trajectories")
+async def list_experience_trajectories(
+ experience_uri: str = Query(..., description="Experience file URI"),
+ limit: int = Query(
+ DEFAULT_TRAJECTORY_PAGE_LIMIT,
+ ge=1,
+ le=MAX_TRAJECTORY_PAGE_LIMIT,
+ ),
+ offset: int = Query(0, ge=0),
+ _ctx: RequestContext = Depends(get_request_context),
+):
+ """List trajectories produced by commits that read an Experience."""
+ service = get_service()
+ result = await service.agent_evolution.list_trajectories_by_experience(
+ experience_uri=experience_uri,
+ ctx=_ctx,
+ limit=limit,
+ offset=offset,
+ )
+ return Response(status="ok", result=result)
diff --git a/openviking/service/agent_evolution_service.py b/openviking/service/agent_evolution_service.py
new file mode 100644
index 000000000..06844c9d7
--- /dev/null
+++ b/openviking/service/agent_evolution_service.py
@@ -0,0 +1,118 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: AGPL-3.0
+"""Agent Evolution product queries."""
+
+from __future__ import annotations
+
+import asyncio
+from typing import TYPE_CHECKING, Any, Optional
+
+from openviking.core.namespace import canonicalize_uri
+from openviking.server.identity import RequestContext
+from openviking.session.memory.experience_lineage import (
+ canonical_experience_uri,
+ experience_source_tag,
+)
+from openviking.storage.expr import And, Eq, PathScope
+from openviking.storage.viking_fs import VikingFS
+from openviking_cli.exceptions import InvalidArgumentError, NotInitializedError
+
+if TYPE_CHECKING:
+ from openviking.storage.vikingdb_manager import VikingDBManager
+
+DEFAULT_TRAJECTORY_PAGE_LIMIT = 50
+MAX_TRAJECTORY_PAGE_LIMIT = 1000
+
+_TRAJECTORY_OUTPUT_FIELDS = [
+ "uri",
+ "name",
+ "description",
+ "created_at",
+ "updated_at",
+]
+
+
+class AgentEvolutionService:
+ """Serve exact, non-semantic Agent Evolution lineage queries."""
+
+ def __init__(
+ self,
+ viking_fs: Optional[VikingFS] = None,
+ vikingdb: Optional[VikingDBManager] = None,
+ ):
+ self._viking_fs = viking_fs
+ self._vikingdb = vikingdb
+
+ def set_dependencies(self, *, viking_fs: VikingFS, vikingdb: VikingDBManager) -> None:
+ self._viking_fs = viking_fs
+ self._vikingdb = vikingdb
+
+ def _ensure_initialized(self) -> VikingFS:
+ if self._viking_fs is None:
+ raise NotInitializedError("VikingFS")
+ return self._viking_fs
+
+ async def list_trajectories_by_experience(
+ self,
+ *,
+ experience_uri: str,
+ ctx: RequestContext,
+ limit: int = DEFAULT_TRAJECTORY_PAGE_LIMIT,
+ offset: int = 0,
+ ) -> dict[str, Any]:
+ """List trajectories produced by commits that read an Experience."""
+ if limit < 1 or limit > MAX_TRAJECTORY_PAGE_LIMIT:
+ raise InvalidArgumentError(f"limit must be between 1 and {MAX_TRAJECTORY_PAGE_LIMIT}")
+ if offset < 0:
+ raise InvalidArgumentError("offset must be greater than or equal to 0")
+
+ canonical_uri = canonical_experience_uri(experience_uri, ctx)
+ if canonical_uri is None:
+ raise InvalidArgumentError(
+ "experience_uri must identify an Experience owned by the current user"
+ )
+
+ viking_fs = self._ensure_initialized()
+ stat = await viking_fs.stat(canonical_uri, ctx=ctx, skip_count=True)
+ if stat.get("isDir", False):
+ raise InvalidArgumentError("experience_uri must identify an Experience file")
+
+ if self._vikingdb is None:
+ raise NotInitializedError("VikingDB")
+
+ trajectory_root = canonicalize_uri(
+ f"viking://user/{ctx.user.user_id}/memories/trajectories",
+ ctx,
+ )
+ lineage_filter = And(
+ [
+ PathScope("uri", trajectory_root, depth=1),
+ Eq("context_type", "memory"),
+ Eq("level", 2),
+ Eq("search_tags", experience_source_tag(canonical_uri)),
+ ]
+ )
+ records, total = await asyncio.gather(
+ self._vikingdb.filter(
+ filter=lineage_filter,
+ limit=limit,
+ offset=offset,
+ output_fields=_TRAJECTORY_OUTPUT_FIELDS,
+ order_by="updated_at",
+ order_desc=True,
+ ctx=ctx,
+ ),
+ self._vikingdb.count(filter=lineage_filter, ctx=ctx),
+ )
+ items = [
+ {field: record.get(field) for field in _TRAJECTORY_OUTPUT_FIELDS if field in record}
+ for record in records
+ ]
+ return {
+ "experience_uri": canonical_uri,
+ "items": items,
+ "total": total,
+ "limit": limit,
+ "offset": offset,
+ "has_more": offset + len(items) < total,
+ }
diff --git a/openviking/service/core.py b/openviking/service/core.py
index c05db0809..dc1ab27a8 100644
--- a/openviking/service/core.py
+++ b/openviking/service/core.py
@@ -15,6 +15,7 @@ from openviking.core.namespace import canonicalize_uri
from openviking.privacy import UserPrivacyConfigService
from openviking.resource.watch_scheduler import WatchScheduler
from openviking.server.identity import RequestContext, Role
+from openviking.service.agent_evolution_service import AgentEvolutionService
from openviking.service.debug_service import DebugService
from openviking.service.fs_service import FSService
from openviking.service.pack_service import PackService
@@ -104,6 +105,7 @@ class OpenVikingService:
self._resource_service = ResourceService()
self._session_service = SessionService()
self._debug_service = DebugService()
+ self._agent_evolution_service = AgentEvolutionService()
# State
self._initialized = False
@@ -280,6 +282,11 @@ class OpenVikingService:
"""Get DebugService instance."""
return self._debug_service
+ @property
+ def agent_evolution(self) -> AgentEvolutionService:
+ """Get Agent Evolution query service."""
+ return self._agent_evolution_service
+
async def initialize(self) -> None:
"""Initialize OpenViking storage and indexes."""
if self._initialized:
@@ -409,6 +416,10 @@ class OpenVikingService:
config=self._config,
agfs_client=self._agfs_client,
)
+ self._agent_evolution_service.set_dependencies(
+ vikingdb=self._vikingdb_manager,
+ viking_fs=self._viking_fs,
+ )
if self._queue_manager:
for queue_name in (
diff --git a/openviking/session/memory/experience_lineage.py b/openviking/session/memory/experience_lineage.py
new file mode 100644
index 000000000..118a15f8e
--- /dev/null
+++ b/openviking/session/memory/experience_lineage.py
@@ -0,0 +1,125 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: AGPL-3.0
+"""Experience-to-trajectory lineage helpers."""
+
+from __future__ import annotations
+
+import json
+from typing import Any, Iterable
+
+from openviking.core.namespace import canonicalize_uri, uri_parts
+from openviking.message import Message, ToolPart
+from openviking.server.identity import RequestContext
+from openviking.utils.tags import normalize_search_tag
+
+_EXPERIENCE_SIDECAR_FILENAMES = {".abstract.md", ".overview.md", ".relations.json"}
+
+
+def is_experience_uri_for_user(uri: str, user_id: str) -> bool:
+ """Return whether ``uri`` identifies an Experience owned by ``user_id``."""
+ if not uri or "?" in uri or "#" in uri:
+ return False
+ parts = uri_parts(uri)
+ if len(parts) < 5 or parts[:4] != ["user", user_id, "memories", "experiences"]:
+ return False
+ relative_parts = parts[4:]
+ if any(not segment or segment in {".", ".."} for segment in relative_parts):
+ return False
+ return relative_parts[-1] not in _EXPERIENCE_SIDECAR_FILENAMES
+
+
+def canonical_experience_uri(uri: str, ctx: RequestContext) -> str | None:
+ """Canonicalize an Experience URI and enforce current-user ownership."""
+ try:
+ canonical_uri = canonicalize_uri(str(uri or "").strip(), ctx)
+ except (TypeError, ValueError):
+ return None
+ if not is_experience_uri_for_user(canonical_uri, ctx.user.user_id):
+ return None
+ return canonical_uri
+
+
+def experience_source_tag(experience_uri: str) -> str:
+ """Build the exact retrieval tag used for Experience lineage filtering."""
+ uri_key = _escape_search_tag_key(str(experience_uri or "").strip())
+ return normalize_search_tag(f"{uri_key}=1")
+
+
+def _escape_search_tag_key(value: str) -> str:
+ """Preserve URI identity through lowercase-only strict k=v tag normalization."""
+ escaped: list[str] = []
+ for character in value:
+ if character in {"%", "="} or character.lower() != character:
+ escaped.extend(f"%{byte:02x}" for byte in character.encode("utf-8"))
+ else:
+ escaped.append(character)
+ return "".join(escaped)
+
+
+def experience_source_tags(experience_uris: Iterable[str] | None) -> list[str]:
+ """Build stable, de-duplicated lineage tags for Experience URIs."""
+ if isinstance(experience_uris, str):
+ experience_uris = [experience_uris]
+ tags: list[str] = []
+ seen: set[str] = set()
+ for uri in experience_uris or []:
+ normalized = str(uri or "").strip()
+ if not normalized:
+ continue
+ tag = experience_source_tag(normalized)
+ if tag in seen:
+ continue
+ seen.add(tag)
+ tags.append(tag)
+ return tags
+
+
+def collect_read_experience_uris(
+ messages: Iterable[Message] | None,
+ *,
+ ctx: RequestContext,
+) -> list[str]:
+ """Collect Experiences successfully read in a committed session message set."""
+ message_list = list(messages or [])
+ tool_inputs: dict[tuple[str, str], dict[str, Any]] = {}
+ for message in message_list:
+ for part in message.parts:
+ if (
+ isinstance(part, ToolPart)
+ and part.tool_id
+ and isinstance(part.tool_input, dict)
+ and part.tool_input
+ ):
+ tool_inputs[(part.tool_id, part.tool_name)] = part.tool_input
+
+ result: list[str] = []
+ seen: set[str] = set()
+ for message in message_list:
+ for part in message.parts:
+ if not isinstance(part, ToolPart):
+ continue
+ if part.tool_name != "read_experience" or part.tool_status != "completed":
+ continue
+ tool_input = part.tool_input if isinstance(part.tool_input, dict) else {}
+ if not tool_input and part.tool_id:
+ tool_input = tool_inputs.get((part.tool_id, part.tool_name), {})
+ output = _load_mapping(part.tool_output)
+ uri = tool_input.get("uri") or output.get("uri")
+ canonical_uri = canonical_experience_uri(str(uri or ""), ctx)
+ if not canonical_uri or canonical_uri in seen:
+ continue
+ seen.add(canonical_uri)
+ result.append(canonical_uri)
+ return result
+
+
+def _load_mapping(value: Any) -> dict[str, Any]:
+ if isinstance(value, dict):
+ return value
+ if isinstance(value, str) and value.strip():
+ try:
+ parsed = json.loads(value)
+ except json.JSONDecodeError:
+ return {}
+ return parsed if isinstance(parsed, dict) else {}
+ return {}
diff --git a/openviking/session/memory/memory_updater.py b/openviking/session/memory/memory_updater.py
index 2cd9da81e..29ce1b424 100644
--- a/openviking/session/memory/memory_updater.py
+++ b/openviking/session/memory/memory_updater.py
@@ -806,6 +806,7 @@ class MemoryUpdater:
ctx: RequestContext,
extract_context: ExtractContext = None,
isolation_handler: MemoryIsolationHandler = None,
+ search_tags_by_uri: Dict[str, List[str]] = None,
) -> MemoryUpdateResult:
result = MemoryUpdateResult()
viking_fs = self._get_viking_fs()
@@ -925,6 +926,7 @@ class MemoryUpdater:
ctx,
extract_context=extract_context,
uri_memory_type_map=uri_memory_type_map,
+ search_tags_by_uri=search_tags_by_uri,
)
# Apply links to endpoint files not covered by upsert_operations
@@ -1291,6 +1293,7 @@ class MemoryUpdater:
ctx: RequestContext,
extract_context: Any = None,
uri_memory_type_map: Dict[str, str] = None,
+ search_tags_by_uri: Dict[str, List[str]] = None,
) -> int:
"""Vectorize written and edited memory files.
@@ -1299,12 +1302,14 @@ class MemoryUpdater:
ctx: Request context
extract_context: Extract context for embedding template rendering
uri_memory_type_map: Mapping from URI to memory_type
+ search_tags_by_uri: Transient search tags to attach while indexing each URI
"""
if not self._vikingdb:
logger.debug("VikingDB not available, skipping vectorization")
return 0
uri_memory_type_map = uri_memory_type_map or {}
+ search_tags_by_uri = search_tags_by_uri or {}
viking_fs = self._get_viking_fs()
request_wait_tracker = get_request_wait_tracker()
attempted_count = 0
@@ -1385,6 +1390,12 @@ class MemoryUpdater:
# Convert to embedding msg and enqueue
embedding_msg = EmbeddingMsgConverter.from_context(memory_context)
if embedding_msg:
+ transient_tags = search_tags_by_uri.get(uri)
+ if transient_tags:
+ embedding_msg.context_data["search_tags"] = list(transient_tags)
+ embedding_msg.context_data["_upsert_options"] = {
+ "search_tag_mode": "append"
+ }
if embedding_msg.telemetry_id:
request_wait_tracker.register_embedding_root(
embedding_msg.telemetry_id, embedding_msg.id
diff --git a/openviking/session/train/components/trajectory_analyzer.py b/openviking/session/train/components/trajectory_analyzer.py
index 3f2252a13..300d7d305 100644
--- a/openviking/session/train/components/trajectory_analyzer.py
+++ b/openviking/session/train/components/trajectory_analyzer.py
@@ -19,6 +19,10 @@ from openviking.session.memory.dataclass import (
ResolvedOperations,
StoredLink,
)
+from openviking.session.memory.experience_lineage import (
+ collect_read_experience_uris,
+ experience_source_tags,
+)
from openviking.session.memory.memory_isolation_handler import MemoryIsolationHandler
from openviking.session.memory.memory_updater import ExtractContext, MemoryUpdateResult
from openviking.session.memory.utils.memory_file_utils import MemoryFileUtils
@@ -164,6 +168,7 @@ class TrajectoryRolloutAnalyzer:
include_trajectories=include_trajectories,
include_session_skills=include_session_skills,
)
+ consumed_experience_uris = collect_read_experience_uris(messages, ctx=ctx)
phase_result = await self._run_trajectory_extract_phase(
provider=provider,
messages=messages,
@@ -173,6 +178,7 @@ class TrajectoryRolloutAnalyzer:
include_session_skills=include_session_skills,
case_name=case_name,
source_archive_uri=source_archive_uri,
+ consumed_experience_uris=consumed_experience_uris,
)
if phase_result is None:
return empty_result
@@ -191,6 +197,7 @@ class TrajectoryRolloutAnalyzer:
include_session_skills: bool = False,
case_name: str = "",
source_archive_uri: str = "",
+ consumed_experience_uris: list[str] | None = None,
) -> tuple[list[str], list[str], list[Context], list[PatchSemanticGradient]] | None:
config = get_openviking_config()
vlm = self.vlm or config.vlm.get_vlm_instance()
@@ -257,6 +264,7 @@ class TrajectoryRolloutAnalyzer:
ctx=ctx,
extract_context=extract_context,
isolation_handler=isolation_handler,
+ consumed_experience_uris=consumed_experience_uris,
)
tracer.info(
"[trajectory] Applied memory ops: "
@@ -286,6 +294,7 @@ class TrajectoryRolloutAnalyzer:
ctx: RequestContext,
extract_context: ExtractContext,
isolation_handler: MemoryIsolationHandler,
+ consumed_experience_uris: list[str] | None = None,
) -> MemoryUpdateResult:
updater = MemoryUpdater(
registry=provider._get_registry(),
@@ -298,6 +307,10 @@ class TrajectoryRolloutAnalyzer:
ctx,
extract_context=extract_context,
isolation_handler=isolation_handler,
+ search_tags_by_uri=_trajectory_search_tags_by_uri(
+ operations,
+ consumed_experience_uris,
+ ),
)
@tracer(
@@ -410,6 +423,23 @@ def _apply_trajectory_source_archive_uri(
fields["source_archive_uri"] = source_archive_uri
+def _trajectory_search_tags_by_uri(
+ operations: ResolvedOperations,
+ consumed_experience_uris: list[str] | None,
+) -> dict[str, list[str]]:
+ tags = experience_source_tags(consumed_experience_uris)
+ if not tags:
+ return {}
+ result: dict[str, list[str]] = {}
+ for op in getattr(operations, "upsert_operations", []) or []:
+ if getattr(op, "memory_type", None) != _TRAJECTORY_MEMORY_TYPE:
+ continue
+ for uri in getattr(op, "uris", []) or []:
+ if uri:
+ result[uri] = list(tags)
+ return result
+
+
def _messages_with_evaluation_feedback(
messages: list[Message],
*,
diff --git a/openviking/storage/vectordb_adapters/base.py b/openviking/storage/vectordb_adapters/base.py
index 85f416157..2b1050d26 100644
--- a/openviking/storage/vectordb_adapters/base.py
+++ b/openviking/storage/vectordb_adapters/base.py
@@ -79,6 +79,13 @@ def _normalize_collection_names(raw_collections: Iterable[Any]) -> list[str]:
return names
+def _normalize_result_score(value: Any) -> float:
+ """Return a finite numeric score; scalar sort values may be strings or datetimes."""
+ if isinstance(value, (int, float)) and math.isfinite(value):
+ return float(value)
+ return 0.0
+
+
class CollectionAdapter(ABC):
"""Backend-specific adapter for single-collection operations.
@@ -508,10 +515,7 @@ class CollectionAdapter(ABC):
for item in result.data:
record = dict(item.fields) if item.fields else {}
record["id"] = item.id
- raw_score = item.score if item.score is not None else 0.0
- if not math.isfinite(raw_score):
- raw_score = 0.0
- record["_score"] = raw_score
+ record["_score"] = _normalize_result_score(item.score)
record = self._normalize_record_for_read(record)
records.append(record)
return records
diff --git a/tests/server/test_api_agent_evolution.py b/tests/server/test_api_agent_evolution.py
new file mode 100644
index 000000000..8e2a8a5e8
--- /dev/null
+++ b/tests/server/test_api_agent_evolution.py
@@ -0,0 +1,60 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: AGPL-3.0
+
+import httpx
+
+
+async def test_list_experience_trajectories_uses_default_pagination(
+ client: httpx.AsyncClient,
+ service,
+ monkeypatch,
+):
+ captured = {}
+
+ async def fake_list(*, experience_uri, ctx, limit, offset):
+ captured.update(
+ experience_uri=experience_uri,
+ ctx=ctx,
+ limit=limit,
+ offset=offset,
+ )
+ return {
+ "experience_uri": experience_uri,
+ "items": [],
+ "total": 0,
+ "limit": limit,
+ "offset": offset,
+ "has_more": False,
+ }
+
+ monkeypatch.setattr(
+ service.agent_evolution,
+ "list_trajectories_by_experience",
+ fake_list,
+ )
+ uri = "viking://user/default/memories/experiences/exchange.md"
+
+ response = await client.get(
+ "/api/v1/agent-evolution/experiences/trajectories",
+ params={"experience_uri": uri},
+ )
+
+ assert response.status_code == 200
+ assert response.json()["result"]["limit"] == 50
+ assert captured["experience_uri"] == uri
+ assert captured["limit"] == 50
+ assert captured["offset"] == 0
+
+
+async def test_list_experience_trajectories_rejects_limit_above_1000(
+ client: httpx.AsyncClient,
+):
+ response = await client.get(
+ "/api/v1/agent-evolution/experiences/trajectories",
+ params={
+ "experience_uri": "viking://user/default/memories/experiences/exchange.md",
+ "limit": 1001,
+ },
+ )
+
+ assert response.status_code == 400
diff --git a/tests/service/test_agent_evolution_service.py b/tests/service/test_agent_evolution_service.py
new file mode 100644
index 000000000..9aefc288d
--- /dev/null
+++ b/tests/service/test_agent_evolution_service.py
@@ -0,0 +1,137 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: AGPL-3.0
+
+from unittest.mock import AsyncMock, Mock
+
+import pytest
+
+from openviking.server.identity import RequestContext, Role
+from openviking.service.agent_evolution_service import AgentEvolutionService
+from openviking.session.memory.experience_lineage import experience_source_tag
+from openviking.storage.expr import And, Eq, PathScope
+from openviking_cli.exceptions import InvalidArgumentError
+from openviking_cli.session.user_id import UserIdentifier
+
+
+def _ctx() -> RequestContext:
+ return RequestContext(user=UserIdentifier("account", "alice"), role=Role.USER)
+
+
+async def test_list_trajectories_by_experience_uses_exact_scalar_filter_and_pagination():
+ experience_uri = "viking://user/alice/memories/experiences/exchange.md"
+ viking_fs = Mock()
+ viking_fs.stat = AsyncMock(return_value={"isDir": False})
+ vikingdb = Mock()
+ vikingdb.filter = AsyncMock(
+ return_value=[
+ {
+ "uri": "viking://user/alice/memories/trajectories/exchange-2.md",
+ "name": "exchange-2.md",
+ "updated_at": "2026-08-03T12:00:00Z",
+ "_score": 1,
+ }
+ ]
+ )
+ vikingdb.count = AsyncMock(return_value=3)
+ service = AgentEvolutionService(viking_fs=viking_fs, vikingdb=vikingdb)
+
+ result = await service.list_trajectories_by_experience(
+ experience_uri=experience_uri,
+ ctx=_ctx(),
+ limit=1,
+ offset=1,
+ )
+
+ assert result == {
+ "experience_uri": experience_uri,
+ "items": [
+ {
+ "uri": "viking://user/alice/memories/trajectories/exchange-2.md",
+ "name": "exchange-2.md",
+ "updated_at": "2026-08-03T12:00:00Z",
+ }
+ ],
+ "total": 3,
+ "limit": 1,
+ "offset": 1,
+ "has_more": True,
+ }
+ expected_filter = And(
+ [
+ PathScope(
+ "uri",
+ "viking://user/alice/memories/trajectories",
+ depth=1,
+ ),
+ Eq("context_type", "memory"),
+ Eq("level", 2),
+ Eq("search_tags", experience_source_tag(experience_uri)),
+ ]
+ )
+ assert vikingdb.filter.await_args.kwargs["filter"] == expected_filter
+ assert vikingdb.filter.await_args.kwargs["limit"] == 1
+ assert vikingdb.filter.await_args.kwargs["offset"] == 1
+ assert vikingdb.filter.await_args.kwargs["order_by"] == "updated_at"
+ assert vikingdb.filter.await_args.kwargs["order_desc"] is True
+ assert vikingdb.count.await_args.kwargs["filter"] == expected_filter
+
+
+async def test_list_trajectories_by_experience_rejects_other_user_uri():
+ service = AgentEvolutionService(viking_fs=Mock(), vikingdb=Mock())
+
+ with pytest.raises(InvalidArgumentError):
+ await service.list_trajectories_by_experience(
+ experience_uri="viking://user/bob/memories/experiences/exchange.md",
+ ctx=_ctx(),
+ )
+
+
+async def test_list_trajectories_by_experience_rejects_limit_above_1000():
+ service = AgentEvolutionService(viking_fs=Mock(), vikingdb=Mock())
+
+ with pytest.raises(InvalidArgumentError):
+ await service.list_trajectories_by_experience(
+ experience_uri="viking://user/alice/memories/experiences/exchange.md",
+ ctx=_ctx(),
+ limit=1001,
+ )
+
+
+async def test_list_trajectories_by_experience_accepts_1000_and_paginates_all_results():
+ experience_uri = "viking://user/alice/memories/experiences/exchange.md"
+ viking_fs = Mock()
+ viking_fs.stat = AsyncMock(return_value={"isDir": False})
+ vikingdb = Mock()
+ vikingdb.filter = AsyncMock(
+ side_effect=[
+ [
+ {"uri": f"viking://user/alice/memories/trajectories/{index}.md"}
+ for index in range(1000)
+ ],
+ [{"uri": "viking://user/alice/memories/trajectories/1000.md"}],
+ ]
+ )
+ vikingdb.count = AsyncMock(side_effect=[1001, 1001])
+ service = AgentEvolutionService(viking_fs=viking_fs, vikingdb=vikingdb)
+
+ first_page = await service.list_trajectories_by_experience(
+ experience_uri=experience_uri,
+ ctx=_ctx(),
+ limit=1000,
+ )
+ second_page = await service.list_trajectories_by_experience(
+ experience_uri=experience_uri,
+ ctx=_ctx(),
+ limit=1000,
+ offset=1000,
+ )
+
+ assert len(first_page["items"]) == 1000
+ assert first_page["has_more"] is True
+ assert second_page["items"] == [{"uri": "viking://user/alice/memories/trajectories/1000.md"}]
+ assert second_page["has_more"] is False
+ assert [call.kwargs["offset"] for call in vikingdb.filter.await_args_list] == [0, 1000]
diff --git a/tests/session/train/test_trajectory_analyzer_component.py b/tests/session/train/test_trajectory_analyzer_component.py
index fb924d035..500d0ed31 100644
--- a/tests/session/train/test_trajectory_analyzer_component.py
+++ b/tests/session/train/test_trajectory_analyzer_component.py
@@ -7,7 +7,7 @@ from types import SimpleNamespace
import pytest
-from openviking.message import Message, TextPart
+from openviking.message import Message, TextPart, ToolPart
from openviking.session.memory.dataclass import ResolvedOperation, ResolvedOperations
from openviking.session.train import (
Case,
@@ -90,8 +90,8 @@ class FakeVikingFS:
async def read_file(self, uri, ctx=None):
return self.files[uri]
- async def write_file(self, uri, content, ctx=None, lock_handle=None):
- del lock_handle
+ async def write_file(self, uri, content, ctx=None, lock_handle=None, lease_ref=None):
+ del lock_handle, lease_ref
self.files[uri] = content
self.writes.append((uri, content, ctx))
@@ -157,7 +157,24 @@ async def test_trajectory_rollout_analyzer_extracts_and_persists_trajectory(monk
source_archive_uri="viking://user/u/sessions/s1/history/archive_001",
)
- analysis = await analyzer.analyze(_rollout(), context)
+ rollout = _rollout()
+ rollout.messages.append(
+ Message(
+ id="tool-result",
+ role="user",
+ parts=[
+ ToolPart(
+ tool_id="read-1",
+ tool_name="read_experience",
+ tool_input={"uri": "viking://user/u/memories/experiences/exchange.md"},
+ tool_output="experience body",
+ tool_status="completed",
+ )
+ ],
+ )
+ )
+
+ analysis = await analyzer.analyze(rollout, context)
assert FakeExtractLoop.created
created_loop = FakeExtractLoop.created[0]
@@ -173,6 +190,7 @@ async def test_trajectory_rollout_analyzer_extracts_and_persists_trajectory(monk
assert (
'"source_archive_uri": "viking://user/u/sessions/s1/history/archive_001"' in fs.writes[0][1]
)
+ assert '"source_experience_uris"' not in fs.writes[0][1]
assert '"source_session_id"' not in fs.writes[0][1]
assert '"source_messages_uri"' not in fs.writes[0][1]
assert '"source_task_id"' not in fs.writes[0][1]
diff --git a/tests/storage/test_vectordb_adapter_scores.py b/tests/storage/test_vectordb_adapter_scores.py
new file mode 100644
index 000000000..acf1a4906
--- /dev/null
+++ b/tests/storage/test_vectordb_adapter_scores.py
@@ -0,0 +1,17 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: AGPL-3.0
+
+from datetime import datetime, timezone
+
+from openviking.storage.vectordb_adapters.base import _normalize_result_score
+
+
+def test_normalize_result_score_keeps_finite_numeric_scores():
+ assert _normalize_result_score(0.75) == 0.75
+ assert _normalize_result_score(float("nan")) == 0.0
+ assert _normalize_result_score(float("inf")) == 0.0
+
+
+def test_normalize_result_score_ignores_scalar_sort_values():
+ assert _normalize_result_score("viking://user/alice/memories/trajectories/a.md") == 0.0
+ assert _normalize_result_score(datetime.now(timezone.utc)) == 0.0
diff --git a/tests/unit/session/memory/test_embedding_template.py b/tests/unit/session/memory/test_embedding_template.py
index b16c5f311..9c246d33e 100644
--- a/tests/unit/session/memory/test_embedding_template.py
+++ b/tests/unit/session/memory/test_embedding_template.py
@@ -8,6 +8,7 @@ import pytest
from openviking.prompts.manager import PromptManager
from openviking.session.memory.dataclass import MemoryField, MemoryFile
+from openviking.session.memory.experience_lineage import experience_source_tag
from openviking.session.memory.memory_type_registry import MemoryTypeRegistry
from openviking.session.memory.memory_updater import MemoryUpdater, MemoryUpdateResult
from openviking.session.memory.merge_op.base import FieldType
@@ -92,6 +93,53 @@ class TestContentTemplateRendering:
class TestEmbeddingTextConstruction:
+ @pytest.mark.asyncio
+ async def test_trajectory_vectorization_adds_source_experience_search_tags(self):
+ registry = MemoryTypeRegistry(load_schemas=False)
+ memory_dir = PromptManager._get_bundled_templates_dir() / "memory"
+ registry.load_from_yaml(str(memory_dir / "trajectories.yaml"))
+ experience_uri = "viking://user/alice/memories/experiences/exchange.md"
+ trajectory_uri = "viking://user/alice/memories/trajectories/exchange.md"
+ updater = MemoryUpdater(registry=registry, vikingdb=Mock())
+ updater._viking_fs = Mock()
+ updater._viking_fs.read_file = AsyncMock(
+ return_value=MemoryFileUtils.write(
+ MemoryFile(
+ uri=trajectory_uri,
+ memory_type="trajectories",
+ content="# exchange\nbody",
+ extra_fields={
+ "trajectory_name": "exchange",
+ "retrieval_anchor": "Stage: final",
+ },
+ )
+ )
+ )
+ updater._vikingdb.enqueue_embedding_msg = AsyncMock(return_value=True)
+ result = MemoryUpdateResult()
+ result.add_written(trajectory_uri)
+ ctx = SimpleNamespace(user=None, account_id="default")
+
+ with patch.object(EmbeddingMsgConverter, "from_context") as mock_from_context:
+ mock_from_context.side_effect = lambda context: SimpleNamespace(
+ telemetry_id=None,
+ id="msg-1",
+ message=context.get_vectorization_text(),
+ context_data={},
+ )
+ await updater._vectorize_memories(
+ result,
+ ctx,
+ uri_memory_type_map={trajectory_uri: "trajectories"},
+ search_tags_by_uri={
+ trajectory_uri: [experience_source_tag(experience_uri)],
+ },
+ )
+
+ embedding_msg = updater._vikingdb.enqueue_embedding_msg.await_args.args[0]
+ assert embedding_msg.context_data["search_tags"] == [experience_source_tag(experience_uri)]
+ assert embedding_msg.context_data["_upsert_options"] == {"search_tag_mode": "append"}
+
@pytest.mark.asyncio
async def test_logs_final_embedding_text_before_vectorization(self):
registry = MemoryTypeRegistry(load_schemas=False)
diff --git a/tests/unit/session/memory/test_experience_lineage.py b/tests/unit/session/memory/test_experience_lineage.py
new file mode 100644
index 000000000..e72373fa8
--- /dev/null
+++ b/tests/unit/session/memory/test_experience_lineage.py
@@ -0,0 +1,128 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: AGPL-3.0
+
+from openviking.message import Message, ToolPart
+from openviking.server.identity import RequestContext, Role
+from openviking.session.memory.dataclass import ResolvedOperation, ResolvedOperations
+from openviking.session.memory.experience_lineage import (
+ collect_read_experience_uris,
+ experience_source_tag,
+)
+from openviking.session.train.components.trajectory_analyzer import (
+ _trajectory_search_tags_by_uri,
+)
+from openviking_cli.session.user_id import UserIdentifier
+
+
+def _ctx() -> RequestContext:
+ return RequestContext(user=UserIdentifier("account", "alice"), role=Role.USER)
+
+
+def test_collect_read_experience_uris_only_keeps_completed_current_user_reads():
+ uri = "viking://user/alice/memories/experiences/order-exchange.md"
+ messages = [
+ Message(
+ id="call",
+ role="assistant",
+ parts=[
+ ToolPart(
+ tool_id="read-1",
+ tool_name="read_experience",
+ tool_input={"uri": uri},
+ tool_status="pending",
+ ),
+ ToolPart(
+ tool_id="search-1",
+ tool_name="search_experience",
+ tool_input={"query": "exchange"},
+ tool_status="completed",
+ tool_output='{"results":[{"uri":"%s"}]}' % uri,
+ ),
+ ],
+ ),
+ Message(
+ id="result",
+ role="user",
+ parts=[
+ ToolPart(
+ tool_id="read-1",
+ tool_name="read_experience",
+ tool_status="completed",
+ tool_output='{"uri":"%s"}' % uri,
+ ),
+ ToolPart(
+ tool_id="read-2",
+ tool_name="read_experience",
+ tool_input={"uri": "viking://user/bob/memories/experiences/other.md"},
+ tool_status="completed",
+ ),
+ ToolPart(
+ tool_id="read-3",
+ tool_name="read_experience",
+ tool_input={"uri": uri},
+ tool_status="error",
+ ),
+ ],
+ ),
+ ]
+
+ assert collect_read_experience_uris(messages, ctx=_ctx()) == [uri]
+
+
+def test_experience_source_tag_uses_experience_uri_as_key():
+ uri = "viking://user/alice/memories/experiences/无订单号换货处理.md"
+
+ tag = experience_source_tag(uri)
+
+ assert tag == f"{uri}=1"
+ assert tag.count("=") == 1
+
+
+def test_experience_source_tag_preserves_case_and_escapes_equals_without_collisions():
+ uppercase_uri = "viking://user/Alice/memories/experiences/Exchange=Flow.md"
+ lowercase_uri = "viking://user/alice/memories/experiences/exchange=flow.md"
+
+ uppercase_tag = experience_source_tag(uppercase_uri)
+ lowercase_tag = experience_source_tag(lowercase_uri)
+
+ assert uppercase_tag == (
+ "viking://user/%41lice/memories/experiences/%45xchange%3d%46low.md=1"
+ )
+ assert lowercase_tag == "viking://user/alice/memories/experiences/exchange%3dflow.md=1"
+ assert uppercase_tag != lowercase_tag
+ assert uppercase_tag.count("=") == 1
+ assert lowercase_tag.count("=") == 1
+
+
+def test_source_experiences_create_transient_tags_for_every_generated_trajectory():
+ first_uri = "viking://user/alice/memories/experiences/exchange.md"
+ second_uri = "viking://user/alice/memories/experiences/refund.md"
+ operations = ResolvedOperations(
+ upsert_operations=[
+ ResolvedOperation(
+ memory_fields={"trajectory_name": "exchange"},
+ memory_type="trajectories",
+ uris=["viking://user/alice/memories/trajectories/exchange.md"],
+ ),
+ ResolvedOperation(
+ memory_fields={"trajectory_name": "refund"},
+ memory_type="trajectories",
+ uris=["viking://user/alice/memories/trajectories/refund.md"],
+ ),
+ ],
+ delete_file_contents=[],
+ errors=[],
+ )
+
+ tags_by_uri = _trajectory_search_tags_by_uri(
+ operations,
+ [first_uri, second_uri, first_uri],
+ )
+
+ expected_tags = [experience_source_tag(first_uri), experience_source_tag(second_uri)]
+ assert tags_by_uri == {
+ "viking://user/alice/memories/trajectories/exchange.md": expected_tags,
+ "viking://user/alice/memories/trajectories/refund.md": expected_tags,
+ }
+ for operation in operations.upsert_operations:
+ assert "source_experience_uris" not in operation.memory_fields