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
# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
# SPDX-License-Identifier: AGPL-3.0
"""RolloutAnalyzer that extracts persistent trajectory memories directly."""
from __future__ import annotations
from dataclasses import dataclass, field
from typing import Any
from openviking.config.vlm import VLMResolver
from openviking.core.context import Context
from openviking.message import Message, TextPart
from openviking.server.identity import RequestContext
from openviking.session.memory import ExtractLoop, MemoryUpdater
from openviking.session.memory.agent_trajectory_context_provider import (
AgentTrajectoryContextProvider,
)
from openviking.session.memory.dataclass import (
MemoryFile,
ResolvedOperations,
StoredLink,
)
from openviking.session.memory.experience_lineage import (
collect_read_experience_uris,
experience_source_tags,
trajectory_outcome_tag,
)
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
from openviking.session.skill.session_skill_context_provider import (
SESSION_SKILL_MEMORY_TYPE,
)
from openviking.session.train.domain import (
CriterionResult,
Rollout,
RolloutAnalysis,
RubricEvaluation,
Trajectory,
)
from openviking.session.train.gradients import PatchSemanticGradient
from openviking.session.train.interfaces import RolloutEvaluator
from openviking.storage.viking_fs import get_viking_fs
from openviking.telemetry import tracer
from openviking_cli.utils import get_logger
logger = get_logger(__name__)
_TRAJECTORY_MEMORY_TYPE = "trajectories"
@dataclass(slots=True)
class TrajectoryAnalyzerContext:
"""Runtime context for TrajectoryRolloutAnalyzer."""
request_context: RequestContext
strict_extract_errors: bool = False
latest_archive_overview: str = ""
evaluator_context: Any = None
inject_evaluation_feedback: bool = True
include_session_skills: bool = False
source_archive_uri: str = ""
case_candidates: list[dict[str, Any]] = field(default_factory=list)
@dataclass(slots=True)
class TrajectoryRolloutAnalyzer:
"""Analyze rollouts by extracting persistent trajectory memory files.
This implementation owns the trajectory extraction/apply flow directly. It
intentionally does not depend on a compressor implementation, and it only
exposes the trajectory memory schema to ExtractLoop.
"""
viking_fs: Any = None
vikingdb: Any = None
vlm: Any = None
evaluator: RolloutEvaluator | None = None
vlm_resolver: VLMResolver | None = None
@tracer("train.rollout_analyzer.trajectory.analyze", ignore_result=True, ignore_args=True)
async def analyze(
self,
rollout: Rollout,
context: TrajectoryAnalyzerContext,
) -> RolloutAnalysis:
if context is None or context.request_context is None:
raise ValueError("TrajectoryAnalyzerContext.request_context is required")
evaluation = await self._evaluate_rollout(rollout, context)
feedback_injected = evaluation is not None and context.inject_evaluation_feedback
extraction_messages = _messages_with_evaluation_feedback(
rollout.messages,
evaluation=evaluation,
enabled=feedback_injected,
)
result = await self.extract_trajectory_memories(
messages=extraction_messages,
ctx=context.request_context,
strict_extract_errors=context.strict_extract_errors,
latest_archive_overview=context.latest_archive_overview,
include_session_skills=context.include_session_skills,
case_name=getattr(rollout.case, "name", ""),
source_archive_uri=context.source_archive_uri,
case_candidates=context.case_candidates,
# Only feedback present in the extraction input changes trajectory identity.
extraction_scope=extraction_messages[-1].content if feedback_injected else "",
)
contexts = list((result or {}).get("contexts", []))
skill_gradients = list((result or {}).get("skill_gradients", []))
trajectory_uris = [
item.uri
for item in contexts
if getattr(item, "category", "") == "memory_write"
and "/memories/trajectories/" in getattr(item, "uri", "")
]
trajectory_uris = list(dict.fromkeys(trajectory_uris))
trajectories = await self._read_trajectories(
trajectory_uris,
ctx=context.request_context,
)
evaluation = evaluation or _evaluation_from_trajectories(trajectories)
return RolloutAnalysis(
evaluation=evaluation,
trajectories=trajectories,
gradients=skill_gradients,
metadata={
"context_count": len(contexts),
"policy_snapshot_id": rollout.policy_snapshot_id,
"rollout_messages": rollout.messages,
"extraction_message_count": len(extraction_messages),
},
)
async def _evaluate_rollout(
self,
rollout: Rollout,
context: TrajectoryAnalyzerContext,
) -> RubricEvaluation | None:
if rollout.evaluation is not None:
return rollout.evaluation
if self.evaluator is None:
return None
return await self.evaluator.evaluate(rollout, context.evaluator_context)
async def extract_trajectory_memories(
self,
*,
messages: list[Message],
ctx: RequestContext | None,
strict_extract_errors: bool = False,
latest_archive_overview: str = "",
include_trajectories: bool = True,
include_session_skills: bool = False,
case_name: str = "",
source_archive_uri: str = "",
case_candidates: list[dict[str, Any]] | None = None,
extraction_scope: str = "",
) -> dict[str, list[Any]]:
"""Extract trajectory and/or reusable skill operations from rollout messages.
When ``include_session_skills`` is True, session skill patches are
co-extracted in the same ExtractLoop pass and returned as
``PatchSemanticGradient`` instances in the ``"skill_gradients"`` key.
Skill patches are *not* applied to disk by this method — they are
returned as gradient signals for downstream policy training. Setting
``include_trajectories`` to False keeps the pass skill-only and prevents
trajectory operations from being persisted.
"""
empty_result: dict[str, list[Any]] = {"contexts": [], "skill_gradients": []}
if not messages or ctx is None:
return empty_result
vlm_config = None
if self.vlm is None:
if self.vlm_resolver is None:
raise RuntimeError(
"TrajectoryRolloutAnalyzer requires a VLM resolver for account-owned work"
)
vlm_config = await self.vlm_resolver.get_vlm(ctx.account_id)
provider = AgentTrajectoryContextProvider(
messages=messages,
latest_archive_overview=latest_archive_overview,
include_trajectories=include_trajectories,
include_session_skills=include_session_skills,
vlm_config=vlm_config,
source_archive_uri=source_archive_uri,
case_candidates=case_candidates,
extraction_scope=extraction_scope,
)
consumed_experience_uris = collect_read_experience_uris(messages, ctx=ctx)
phase_result = await self._run_trajectory_extract_phase(
provider=provider,
messages=messages,
ctx=ctx,
strict_extract_errors=strict_extract_errors,
include_trajectories=include_trajectories,
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
_, _, contexts, skill_gradients = phase_result
return {"contexts": contexts, "skill_gradients": skill_gradients}
async def _run_trajectory_extract_phase(
self,
*,
provider: AgentTrajectoryContextProvider,
messages: list[Message],
ctx: RequestContext,
strict_extract_errors: bool,
include_trajectories: bool = True,
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:
if self.vlm is None:
vlm_config = provider._vlm_config
if vlm_config is None:
raise RuntimeError("Trajectory provider is missing its resolved VLM config")
vlm = vlm_config
else:
vlm = self.vlm
viking_fs = self.viking_fs or get_viking_fs()
if viking_fs is None:
raise RuntimeError("VikingFS is required to extract trajectory memories")
extract_context = provider.get_extract_context()
allowed_types: set[str] = set()
if include_trajectories:
allowed_types.add(_TRAJECTORY_MEMORY_TYPE)
if include_session_skills:
allowed_types.add(SESSION_SKILL_MEMORY_TYPE)
isolation_handler = MemoryIsolationHandler(
ctx,
extract_context,
allowed_memory_types=allowed_types,
)
isolation_handler.prepare_messages()
provider._isolation_handler = isolation_handler
provider._ctx = ctx
provider._viking_fs = viking_fs
orchestrator = ExtractLoop(
vlm=vlm,
viking_fs=viking_fs,
ctx=ctx,
context_provider=provider,
isolation_handler=isolation_handler,
thinking=True,
)
try:
provider._transaction_handle = None
orchestrator._transaction_handle = None
operations, _ = await orchestrator.run()
if operations is None:
tracer.info("[trajectory] No memory operations generated")
return [], [], [], []
_log_operations(operations)
# Split operations into trajectory (applied to disk) and skill
# (returned as gradients). Skill ops are *not* written here —
# they flow through the patch-merge trainer.
traj_ops, skill_ops = _split_operations_by_type(
operations, target_type=_TRAJECTORY_MEMORY_TYPE
)
skill_gradients = _skill_operations_to_gradients(
skill_ops,
viking_fs=viking_fs,
ctx=ctx,
)
_bind_trajectory_cases(
traj_ops,
case_name=case_name,
case_candidates=provider.case_candidates,
)
_apply_trajectory_source_archive_uri(traj_ops, source_archive_uri)
memory_result = MemoryUpdateResult()
if include_trajectories:
memory_result = await self._apply_trajectory_operations(
operations=traj_ops,
provider=provider,
ctx=ctx,
extract_context=extract_context,
isolation_handler=isolation_handler,
consumed_experience_uris=consumed_experience_uris,
)
tracer.info(
"[trajectory] Applied memory ops: "
f"written={len(memory_result.written_uris)}, "
f"edited={len(memory_result.edited_uris)}, "
f"deleted={len(memory_result.deleted_uris)}, "
f"errors={len(memory_result.errors)}"
)
contexts = _contexts_from_memory_result(memory_result)
return (
list(memory_result.written_uris),
list(memory_result.edited_uris),
contexts,
skill_gradients,
)
except Exception as exc:
logger.error("[trajectory] Failed to extract: %s", exc, exc_info=True)
if strict_extract_errors:
raise
return None
async def _apply_trajectory_operations(
self,
*,
operations: ResolvedOperations,
provider: AgentTrajectoryContextProvider,
ctx: RequestContext,
extract_context: ExtractContext,
isolation_handler: MemoryIsolationHandler,
consumed_experience_uris: list[str] | None = None,
) -> MemoryUpdateResult:
updater = MemoryUpdater(
registry=provider._get_registry(),
vikingdb=self.vikingdb,
transaction_handle=None,
)
updater._viking_fs = self.viking_fs or get_viking_fs()
return await updater.apply_operations(
operations,
ctx,
extract_context=extract_context,
isolation_handler=isolation_handler,
search_tags_by_uri=_trajectory_search_tags_by_uri(
operations,
consumed_experience_uris,
),
)
@tracer(
"train.rollout_analyzer.trajectory.read_trajectories", ignore_result=True, ignore_args=True
)
async def _read_trajectories(
self,
trajectory_uris: list[str],
*,
ctx: RequestContext,
) -> list[Trajectory]:
viking_fs = self.viking_fs or get_viking_fs()
if viking_fs is None:
raise RuntimeError("VikingFS is required to read extracted trajectories")
trajectories: list[Trajectory] = []
for uri in dict.fromkeys(trajectory_uris):
try:
raw = await viking_fs.read_file(uri, ctx=ctx) or ""
mf = MemoryFileUtils.read(raw, uri=uri)
except Exception as exc:
logger.warning("Failed to read trajectory %s: %s", uri, exc)
continue
fields = dict(mf.extra_fields or {})
name = str(
fields.get("trajectory_name") or uri.rstrip("/").split("/")[-1].removesuffix(".md")
)
outcome = str(fields.get("outcome") or "unknown")
retrieval_anchor = str(fields.get("retrieval_anchor") or "")
case_name = str(fields.get("case_name") or "")
metadata = dict(fields)
metadata.setdefault("memory_type", mf.memory_type or fields.get("memory_type"))
metadata.setdefault("case_name", case_name)
trajectories.append(
Trajectory(
name=name,
uri=uri,
content=mf.plain_content(),
outcome=outcome,
retrieval_anchor=retrieval_anchor,
metadata=metadata,
)
)
return trajectories
def _log_operations(operations: ResolvedOperations) -> None:
op_items = [
f"{op.memory_type}(uris={op.uris!r})" for op in getattr(operations, "upsert_operations", [])
]
delete_uris = [dc.uri for dc in getattr(operations, "delete_file_contents", [])]
tracer.info(f"[trajectory] LLM operations: ops={op_items}, delete_uris={delete_uris}")
def _contexts_from_memory_result(memory_result: MemoryUpdateResult) -> list[Context]:
contexts: list[Context] = []
for uri in memory_result.written_uris:
contexts.append(Context(uri=uri, category="memory_write", context_type="memory"))
for uri in memory_result.edited_uris:
contexts.append(Context(uri=uri, category="memory_edit", context_type="memory"))
for uri in memory_result.deleted_uris:
contexts.append(Context(uri=uri, category="memory_delete", context_type="memory"))
return contexts
def _evaluation_from_trajectories(trajectories: list[Trajectory]) -> RubricEvaluation:
passed = bool(trajectories)
return RubricEvaluation(
passed=passed,
score=1.0 if passed else 0.0,
criterion_results=[
CriterionResult(
criterion_name="trajectory_extracted",
passed=passed,
score=1.0 if passed else 0.0,
feedback=[] if passed else ["No trajectory was extracted from the rollout."],
evidence=[trajectory.uri for trajectory in trajectories],
)
],
feedback=[] if passed else ["No trajectory was extracted from the rollout."],
metadata={"trajectory_count": len(trajectories)},
)
def _bind_trajectory_cases(
operations: ResolvedOperations,
*,
case_name: str,
case_candidates: list[dict[str, Any]],
) -> None:
cases_by_id = {case["id"]: case for case in case_candidates}
for op in getattr(operations, "upsert_operations", []) or []:
if getattr(op, "memory_type", None) != _TRAJECTORY_MEMORY_TYPE:
continue
fields = op.memory_fields
related_ids = fields.pop("related_case_ids", None) or []
if not case_candidates:
if case_name:
fields["case_name"] = case_name
continue
if len(case_candidates) == 1:
related_ids = list(cases_by_id)
fields["case_name"] = case_candidates[0]["name"]
else:
fields.pop("case_name", None)
unknown_ids = set(related_ids) - cases_by_id.keys()
if unknown_ids:
logger.warning("Ignoring unknown trajectory case IDs: %s", sorted(unknown_ids))
fields["case_uris"] = list(
dict.fromkeys(
cases_by_id[case_id]["uri"]
for case_id in related_ids
if case_id in cases_by_id and cases_by_id[case_id]["uri"]
)
)
def _apply_trajectory_source_archive_uri(
operations: ResolvedOperations,
source_archive_uri: str,
) -> None:
source_archive_uri = str(source_archive_uri or "").rstrip("/")
if not source_archive_uri:
return
for op in getattr(operations, "upsert_operations", []) or []:
if getattr(op, "memory_type", None) != _TRAJECTORY_MEMORY_TYPE:
continue
fields = getattr(op, "memory_fields", None)
if not isinstance(fields, dict):
continue
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]]:
source_tags = experience_source_tags(consumed_experience_uris)
result: dict[str, list[str]] = {}
for op in getattr(operations, "upsert_operations", []) or []:
if getattr(op, "memory_type", None) != _TRAJECTORY_MEMORY_TYPE:
continue
fields = getattr(op, "memory_fields", None)
outcome = fields.get("outcome") if isinstance(fields, dict) else None
tags = [*source_tags, trajectory_outcome_tag(outcome)]
for uri in getattr(op, "uris", []) or []:
if uri:
result[uri] = list(tags)
return result
def _messages_with_evaluation_feedback(
messages: list[Message],
*,
evaluation: RubricEvaluation | None,
enabled: bool,
) -> list[Message]:
result = list(messages)
if not enabled or evaluation is None:
return result
result.append(_evaluation_feedback_message(evaluation))
return result
def _evaluation_feedback_message(evaluation: RubricEvaluation) -> Message:
lines = [
"[Rollout Evaluation]",
f"passed: {evaluation.passed}",
f"score: {evaluation.score}",
]
if evaluation.feedback:
lines.extend(["", "feedback:", *[f"- {item}" for item in evaluation.feedback]])
criterion_lines: list[str] = []
evidence_lines: list[str] = []
for criterion in evaluation.criterion_results:
criterion_lines.append(
f"- {criterion.criterion_name}: passed={criterion.passed}, score={criterion.score}"
)
criterion_lines.extend(f" feedback: {item}" for item in criterion.feedback)
evidence_lines.extend(criterion.evidence)
if criterion_lines:
lines.extend(["", "criteria:", *criterion_lines])
if evidence_lines:
lines.extend(["", "evidence:", *[f"- {item}" for item in dict.fromkeys(evidence_lines)]])
return Message(
id="rollout-evaluation-feedback",
role="user",
parts=[TextPart(text="\n".join(lines))],
)
def _split_operations_by_type(
operations: ResolvedOperations, *, target_type: str
) -> tuple[ResolvedOperations, ResolvedOperations]:
"""Split operations into (target_type_ops, other_ops)."""
target_upserts = [op for op in operations.upsert_operations if op.memory_type == target_type]
other_upserts = [op for op in operations.upsert_operations if op.memory_type != target_type]
target_deletes = [dc for dc in operations.delete_file_contents if dc.memory_type == target_type]
other_deletes = [dc for dc in operations.delete_file_contents if dc.memory_type != target_type]
target_ops = ResolvedOperations(
upsert_operations=target_upserts,
delete_file_contents=target_deletes,
errors=list(operations.errors),
resolved_links=[
link
for link in operations.resolved_links
if getattr(link, "from_uri", "").endswith("/trajectories/")
or target_type in getattr(link, "from_uri", "")
],
)
other_ops = ResolvedOperations(
upsert_operations=other_upserts,
delete_file_contents=other_deletes,
errors=[],
resolved_links=[],
)
return target_ops, other_ops
def _skill_operations_to_gradients(
operations: ResolvedOperations,
*,
viking_fs: Any = None,
ctx: Any = None,
) -> list[PatchSemanticGradient]:
"""Convert skill ResolvedOperations to PatchSemanticGradient instances.
The resulting gradients carry the full proposed skill content in their
``after_file`` so the patch-merge optimizer can reconcile multiple
proposals against the current policy set.
"""
gradients: list[PatchSemanticGradient] = []
for op in operations.upsert_operations or []:
if op.memory_type != SESSION_SKILL_MEMORY_TYPE:
continue
fields = dict(op.memory_fields or {})
skill_name = str(fields.get("skill_name") or _fallback_skill_name(op))
target_uri = (op.uris or [None])[0]
after_content = str(fields.get("content") or "")
if not after_content.strip():
continue
old_file = op.old_memory_file_content
after_file = MemoryFile(
uri=target_uri,
content=after_content,
memory_type="skills",
extra_fields={
**dict(getattr(old_file, "extra_fields", {}) or {}),
**{k: v for k, v in fields.items() if k != "content"},
"memory_type": "skills",
"skill_name": skill_name,
},
)
links: list[StoredLink] = []
# Build derived_from links from the source trajectory(s).
for link in getattr(operations, "resolved_links", []) or []:
try:
stored = link if isinstance(link, StoredLink) else StoredLink(**dict(link))
if stored.link_type == "derived_from" and stored.to_uri:
if "/memories/trajectories/" in stored.to_uri:
links.append(stored.model_copy(update={"from_uri": target_uri or ""}))
except Exception:
continue
gradients.append(
PatchSemanticGradient(
before_file=old_file,
after_file=after_file,
base_version=_base_version_from_old_file(old_file),
rationale=(
"Session skill patch extracted from rollout trajectory "
"by AgentTrajectoryContextProvider."
),
links=links,
confidence=0.7,
metadata={
"source": "trajectory_co_extract",
"memory_fields": fields,
"skill_name": skill_name,
"uris": list(op.uris or []),
},
)
)
return gradients
def _fallback_skill_name(op: Any) -> str:
uris = getattr(op, "uris", None) or []
if uris:
uri = str(uris[0])
# path/to/skills/my_skill/SKILL.md → my_skill
parts = uri.rstrip("/").split("/")
if len(parts) >= 2 and parts[-1] == "SKILL.md":
return parts[-2]
return parts[-1].removesuffix(".md")
return "unknown_skill"
def _base_version_from_old_file(old_file: Any) -> int | None:
if old_file is None:
return None
fields = getattr(old_file, "extra_fields", {}) or {}
try:
v = int(fields.get("version"))
return v if v > 0 else None
except (TypeError, ValueError):
return None