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
"""Session Compressor V3.
V3 keeps the V2 extraction interface while changing user-memory commits to a
patch-merge flow without directory-level memory locks. Training cases are not
extracted by a separate LLM call; they are a normal user-memory ``memory_type``
(``cases``) emitted by the same ExtractLoop that extracts profile/preferences/
events/etc. When such case memories are produced, the same commit rollout is
submitted to the process-global StreamingPolicyTrainer.
"""
from __future__ import annotations
import json
import re
from dataclasses import asdict, dataclass, field, replace
from datetime import datetime, timezone
from typing import TYPE_CHECKING, Any, List, Optional
from uuid import uuid4
from openviking.core.context import Context
from openviking.message import Message
from openviking.server.identity import RequestContext
from openviking.session.memory import ExtractLoop, MemoryUpdater, StreamingMemoryUpdaterConfig
from openviking.session.memory.constants import (
AGENT_EVOLUTION_MEMORY_TYPES,
CASE_MEMORY_TYPE,
EVENT_MEMORY_TYPE,
EXECUTION_MEMORY_TYPES,
EXPERIENCE_MEMORY_TYPE,
TRAJECTORY_MEMORY_TYPE,
)
from openviking.session.memory.dataclass import (
MemoryFile,
MemoryOperationSource,
ResolvedOperation,
ResolvedOperations,
StoredLink,
)
from openviking.session.memory.memory_isolation_handler import MemoryIsolationHandler
from openviking.session.memory.memory_type_registry import get_default_registry
from openviking.session.memory.memory_updater import (
ExtractContext,
MemoryUpdateError,
write_stored_links,
)
from openviking.session.memory.session_extract_context_provider import (
SessionExtractContextProvider,
)
from openviking.session.memory.streaming_memory_updater import (
MemoryUpdateRequest,
get_streaming_memory_updater,
make_streaming_memory_updater_key,
merge_link_lists,
)
from openviking.session.memory.utils.json_parser import JsonUtils
from openviking.session.memory.utils.memory_file_utils import MemoryFileUtils
from openviking.session.memory.utils.uri import generate_uri
from openviking.session.skill.session_skill_context_provider import (
SESSION_SKILL_MEMORY_TYPE,
load_skill_extract_registry,
)
from openviking.session.train import (
Case,
ExperienceGradientContext,
ExperienceGradientEstimator,
ExperienceSetLoader,
MemoryFilePolicyUpdater,
PatchMergePolicyOptimizer,
PatchMergePolicyOptimizerContext,
PipelineContext,
PolicyApplyResult,
PolicyPlanItem,
PolicyUpdatePlan,
Rollout,
RolloutAnalysis,
RolloutTrainingResult,
Rubric,
RubricCriterion,
SkillPolicyUpdater,
SkillSetLoader,
StreamingPolicyTrainerConfig,
TrajectoryAnalyzerContext,
TrajectoryRolloutAnalyzer,
get_streaming_policy_trainer,
make_streaming_policy_trainer_key,
)
from openviking.session.train.components.trajectory_analyzer import _evaluation_feedback_message
from openviking.storage.viking_fs import get_viking_fs
from openviking.telemetry import get_current_telemetry, tracer
from openviking_cli.utils import get_logger
from openviking_cli.utils.config import get_openviking_config
if TYPE_CHECKING:
from openviking.config.vlm import VLMHandle, VLMResolver
logger = get_logger(__name__)
_CASES_MEMORY_TYPE = CASE_MEMORY_TYPE
_TRAJECTORIES_MEMORY_TYPE = TRAJECTORY_MEMORY_TYPE
_EXPERIENCES_MEMORY_TYPE = EXPERIENCE_MEMORY_TYPE
_EVENTS_MEMORY_TYPE = EVENT_MEMORY_TYPE
_AGENT_MEMORY_TYPES = EXECUTION_MEMORY_TYPES
_TRAINING_CASE_SPEC_PROTOCOL = "openviking.batch_train.case_spec.v1"
_TRAINING_CASE_SPEC_HEADER = "# OpenViking Batch Training CaseSpec v1"
_TRAINING_FAST_PATH_MEMORY_TYPES = frozenset({"cases", "trajectories", "experiences"})
_JSON_FENCE_RE = re.compile(r"```(?:json)?\s*(.*?)\s*```", re.DOTALL | re.IGNORECASE)
_EXPERIENCE_TRAJECTORY_MAP_PREFIX = "OpenViking-Experience-Trajectory-Map: "
def _apply_event_search_tags(
operations: Optional["ResolvedOperations"],
event_search_tags: Optional[List[str]],
) -> None:
"""Attach custom scalar tags to event-memory operations in place.
Only ``events``-type upsert operations are tagged so the scalars ride the
same first write into the vector index. Empty/None tags are a no-op, and a
missing operations object is tolerated (the orchestrator may return None).
"""
if not event_search_tags or operations is None:
return
tags = list(event_search_tags)
for op in getattr(operations, "upsert_operations", []) or []:
if getattr(op, "memory_type", None) == _EVENTS_MEMORY_TYPE:
op.search_tags = list(tags)
def _initialize_extraction_telemetry() -> None:
telemetry = get_current_telemetry()
for name in (
"memory.extract.candidates.total",
"memory.extract.candidates.standard",
"memory.extract.candidates.tool_skill",
"memory.extract.created",
"memory.extract.merged",
"memory.extract.deleted",
"memory.extract.skipped",
"memory.extract.failed",
):
telemetry.set(name, 0)
def _memory_type_by_uri(operations: ResolvedOperations) -> dict[str, str]:
"""Map applied memory URIs to their stable extraction schema names."""
types_by_uri: dict[str, str] = {}
for operation in getattr(operations, "upsert_operations", []) or []:
memory_type = str(getattr(operation, "memory_type", "") or "unknown")
for uri in getattr(operation, "uris", []) or []:
types_by_uri[str(uri)] = memory_type
for file_content in getattr(operations, "delete_file_contents", []) or []:
uri = str(getattr(file_content, "uri", "") or "")
if uri:
types_by_uri[uri] = str(
getattr(file_content, "memory_type", "") or "unknown"
)
return types_by_uri
def _report_extraction_telemetry(result: Any, operations: ResolvedOperations) -> None:
telemetry = get_current_telemetry()
telemetry.set(
"memory.extract.candidates.total",
len(result.written_uris) + len(result.edited_uris),
)
telemetry.set("memory.extract.created", len(result.written_uris))
telemetry.set("memory.extract.merged", len(result.edited_uris))
telemetry.set("memory.extract.deleted", len(result.deleted_uris))
telemetry.set("memory.extract.skipped", len(result.skipped_operations))
telemetry.set("memory.extract.failed", len(result.errors))
types_by_uri = _memory_type_by_uri(operations)
actions_by_type: dict[str, dict[str, int]] = {}
def memory_type_for_telemetry(uri: Any) -> str:
if memory_type := types_by_uri.get(str(uri)):
return str(memory_type)
try:
return str(MemoryUpdater.memory_type_from_uri(str(uri)) or "unknown")
except ValueError:
return "unknown"
def add(memory_type: Any, action: str) -> None:
normalized_type = str(memory_type or "unknown")
type_actions = actions_by_type.setdefault(normalized_type, {})
type_actions[action] = type_actions.get(action, 0) + 1
for uri in result.written_uris:
add(memory_type_for_telemetry(uri), "created")
for uri in result.edited_uris:
add(memory_type_for_telemetry(uri), "merged")
for uri in result.deleted_uris:
add(memory_type_for_telemetry(uri), "deleted")
for operation in result.skipped_operations:
add(getattr(operation, "memory_type", None), "skipped")
for uri, _error in result.errors:
add(memory_type_for_telemetry(uri), "failed")
for memory_type, actions in actions_by_type.items():
for action, value in actions.items():
telemetry.set(f"memory.extract.by_type.{memory_type}.{action}", value)
async def _commit_experience_snapshot(
viking_fs: Any,
*,
ctx: RequestContext,
experience_uris: list[str],
archive_uri: str = "",
experience_trajectory_map: Optional[dict[str, list[str]]] = None,
) -> None:
commit = getattr(viking_fs, "commit", None)
if not callable(commit):
return
paths = [
uri
for uri in dict.fromkeys(str(uri or "") for uri in experience_uris)
if "/memories/experiences/" in uri and uri.endswith(".md")
]
if not paths:
return
archive_ref = archive_uri.rstrip("/") if archive_uri else "unknown"
changed_experience_uris = set(paths)
trajectory_map = {
experience_uri: list(dict.fromkeys(trajectory_uris))
for experience_uri, trajectory_uris in (experience_trajectory_map or {}).items()
if experience_uri in changed_experience_uris
}
message = (
f"Update experience memories from session commit {archive_ref}\n"
f"{_EXPERIENCE_TRAJECTORY_MAP_PREFIX}"
f"{json.dumps(trajectory_map, ensure_ascii=False, sort_keys=True, separators=(',', ':'))}"
)
try:
await commit(
message=message,
paths=paths,
ctx=ctx,
)
except Exception as exc:
logger.warning("Failed to commit experience snapshot for %s: %s", paths, exc, exc_info=True)
class SessionCompressorV3:
"""Session compressor with lock-free patch-merge user memory extraction."""
rollout_analyzer: TrajectoryRolloutAnalyzer | Any
streaming_trainer_config: StreamingPolicyTrainerConfig = field(
default_factory=StreamingPolicyTrainerConfig
)
streaming_memory_updater_config: StreamingMemoryUpdaterConfig = field(
default_factory=StreamingMemoryUpdaterConfig
)
def __init__(
self,
vikingdb,
skill_processor: Optional[Any] = None,
*,
rollout_analyzer: TrajectoryRolloutAnalyzer | Any | None = None,
streaming_trainer_config: StreamingPolicyTrainerConfig | None = None,
streaming_memory_updater_config: StreamingMemoryUpdaterConfig | None = None,
vlm_resolver: VLMResolver | None = None,
):
self.vikingdb = vikingdb
self.skill_processor = skill_processor
self.vlm_resolver = vlm_resolver
self.rollout_analyzer = rollout_analyzer or TrajectoryRolloutAnalyzer(
viking_fs=get_viking_fs(),
vikingdb=vikingdb,
vlm_resolver=vlm_resolver,
)
self.streaming_trainer_config = streaming_trainer_config or StreamingPolicyTrainerConfig()
self.streaming_memory_updater_config = (
streaming_memory_updater_config or StreamingMemoryUpdaterConfig()
)
def _get_or_create_react(
self,
ctx: Optional[RequestContext] = None,
messages: Optional[List] = None,
latest_archive_overview: str = "",
isolation_handler: Optional[MemoryIsolationHandler] = None,
transaction_handle=None,
context_provider: Optional[SessionExtractContextProvider] = None,
vlm_config: VLMHandle | None = None,
) -> ExtractLoop:
if vlm_config is None:
raise RuntimeError(
"SessionCompressorV3 requires an explicitly resolved VLM config"
)
vlm = vlm_config
viking_fs = get_viking_fs()
if context_provider is None:
context_provider = SessionExtractContextProvider(
messages=messages,
latest_archive_overview=latest_archive_overview,
isolation_handler=isolation_handler,
ctx=ctx,
viking_fs=viking_fs,
transaction_handle=transaction_handle,
vlm_config=vlm_config,
)
return ExtractLoop(
vlm=vlm,
viking_fs=viking_fs,
ctx=ctx,
context_provider=context_provider,
isolation_handler=isolation_handler,
)
def _get_or_create_updater(self, registry, transaction_handle=None) -> MemoryUpdater:
return MemoryUpdater(
registry=registry,
vikingdb=self.vikingdb,
)
async def _build_memory_diff(
self,
result: Any,
operations: ResolvedOperations,
viking_fs: Any,
ctx: RequestContext,
archive_uri: str = "",
) -> dict[str, Any]:
adds: list[dict[str, Any]] = []
updates: list[dict[str, Any]] = []
deletes: list[dict[str, Any]] = []
upsert_by_uri = {}
for op in operations.upsert_operations:
for uri in op.uris:
upsert_by_uri[uri] = op
delete_by_uri = {dc.uri: dc for dc in operations.delete_file_contents}
for uri in result.written_uris:
op = upsert_by_uri.get(uri)
memory_type = (
op.memory_type if op else MemoryUpdater.memory_type_from_uri(uri) or "unknown"
)
old_file = op.old_memory_file_content if op else None
if old_file:
updates.append(
{
"uri": uri,
"memory_type": memory_type,
"before": old_file.content,
"after": "",
}
)
else:
adds.append({"uri": uri, "memory_type": memory_type, "after": ""})
for uri in result.edited_uris:
op = upsert_by_uri.get(uri)
memory_type = (
op.memory_type if op else MemoryUpdater.memory_type_from_uri(uri) or "unknown"
)
old_file = op.old_memory_file_content if op and op.old_memory_file_content else None
updates.append(
{
"uri": uri,
"memory_type": memory_type,
"before": old_file.content if old_file else "",
"after": "",
}
)
for uri in result.deleted_uris:
deleted = delete_by_uri.get(uri)
deletes.append(
{
"uri": uri,
"memory_type": (deleted.memory_type if deleted else None) or "unknown",
"deleted_content": deleted.content if deleted else "",
}
)
# Read new content for adds and updates.
# Some upsert operations can be reported as successful even when the
# final file body is identical to the pre-existing content (for
# example, a no-op merge/patch or a write that only re-serializes the
# same memory). memory_diff.json should only include effective content
# changes, so filter no-op updates after the final content is known.
for item in adds:
try:
content = await viking_fs.read_file(uri=item["uri"], ctx=ctx)
item["after"] = MemoryFileUtils.read(content).content
except Exception:
pass
effective_updates: list[dict[str, Any]] = []
for item in updates:
op = upsert_by_uri.get(item["uri"])
old_file = op.old_memory_file_content if op else None
new_file: Optional[MemoryFile] = None
try:
content = await viking_fs.read_file(uri=item["uri"], ctx=ctx)
new_file = MemoryFileUtils.read(content, uri=item["uri"])
item["after"] = new_file.content
except Exception:
pass
if old_file is not None and _same_memory_file(old_file, new_file):
logger.info(
"Skipping unchanged memory file in memory_diff.json: %s",
item.get("uri"),
)
continue
effective_updates.append(item)
updates = effective_updates
return _make_memory_diff(
archive_uri=archive_uri,
adds=adds,
updates=updates,
deletes=deletes,
skipped_operations=_serialize_skipped_operations(
getattr(result, "skipped_operations", [])
),
)
@tracer(ignore_result=True)
async def extract_long_term_memories(
self,
messages: List[Message],
user: Optional[Any] = None,
session_id: Optional[str] = None,
ctx: Optional[RequestContext] = None,
strict_extract_errors: bool = False,
latest_archive_overview: str = "",
archive_uri: Optional[str] = None,
allowed_memory_types: Optional[set[str]] = None,
agent_evolution_enabled: bool = True,
allow_self_memory: bool = True,
allowed_peer_ids: Optional[set[str]] = None,
event_search_tags: Optional[List[str]] = None,
peer_memory_enabled: bool = True,
):
if not agent_evolution_enabled:
effective_types = (
set(get_default_registry().list_names(include_disabled=False))
if allowed_memory_types is None
else set(allowed_memory_types)
)
allowed_memory_types = effective_types - AGENT_EVOLUTION_MEMORY_TYPES
message_list = list(messages)
fast_path_case = _training_case_from_first_message(
message_list,
allowed_memory_types,
)
try:
if fast_path_case is not None:
return await self._commit_training_case_fast_path(
case=fast_path_case,
messages=message_list,
ctx=ctx,
session_id=session_id,
archive_uri=archive_uri or "",
strict_extract_errors=strict_extract_errors,
agent_evolution_enabled=agent_evolution_enabled,
allowed_memory_types=allowed_memory_types,
)
result = await self._extract_user_memories(
messages=message_list,
user=user,
session_id=session_id,
ctx=ctx,
strict_extract_errors=strict_extract_errors,
latest_archive_overview=latest_archive_overview,
archive_uri=archive_uri,
allowed_memory_types=allowed_memory_types,
allow_self_memory=allow_self_memory,
peer_memory_enabled=peer_memory_enabled,
allowed_peer_ids=allowed_peer_ids,
event_search_tags=event_search_tags,
)
agent_memory_types = _allowed_agent_memory_types(allowed_memory_types)
cases_allowed = (
allowed_memory_types is None or _CASES_MEMORY_TYPE in allowed_memory_types
)
session_skills_enabled = self._session_skill_extraction_enabled()
if (
agent_evolution_enabled
and cases_allowed
and _TRAJECTORIES_MEMORY_TYPE in agent_memory_types
):
train_result = await self.train_from_extracted_cases(
cases=result.cases,
messages=message_list,
ctx=ctx,
case_uri_by_name=getattr(result, "case_uri_by_name", {}),
session_id=session_id,
archive_uri=archive_uri or "",
strict_extract_errors=strict_extract_errors,
collect_memory_diff=True,
allowed_memory_types=agent_memory_types,
)
elif not agent_evolution_enabled and allow_self_memory and session_skills_enabled:
train_result = await self.extract_session_skills(
messages=message_list,
ctx=ctx,
archive_uri=archive_uri or "",
strict_extract_errors=strict_extract_errors,
)
else:
train_result = {
"case_count": len(result.cases),
"submitted": 0,
"reason": (
"agent_evolution_disabled"
if not agent_evolution_enabled
else "memory_types_filtered"
),
}
await self._write_final_memory_diff(
archive_uri=archive_uri or "",
ctx=ctx,
memory_diffs=[
getattr(result, "memory_diff", None),
train_result.get("memory_diff"),
],
)
return _v3_extraction_response(
contexts=result.contexts,
train_result=train_result,
archive_uri=archive_uri or "",
)
except Exception:
if strict_extract_errors:
raise
logger.warning("V3 memory extraction failed; returning empty result", exc_info=True)
return {"contexts": [], "session_skills": []}
async def _commit_training_case_fast_path(
self,
*,
case: Case,
messages: list[Message],
ctx: Optional[RequestContext],
session_id: Optional[str],
archive_uri: str,
strict_extract_errors: bool,
agent_evolution_enabled: bool,
allowed_memory_types: Optional[set[str]],
) -> dict[str, Any]:
if ctx is None:
logger.warning("No RequestContext provided, skipping training case fast path")
return {"contexts": [], "session_skills": []}
case_write = await self._write_training_case_memory(
case=case,
ctx=ctx,
archive_uri=archive_uri,
)
case_result = _applied_memory_result(case_write)
contexts = _contexts_from_update_result(case_result)
agent_memory_types = _allowed_agent_memory_types(allowed_memory_types)
if agent_evolution_enabled and _TRAJECTORIES_MEMORY_TYPE in agent_memory_types:
train_result = await self.train_from_extracted_cases(
cases=[case],
messages=_training_messages_after_case_spec(messages),
ctx=ctx,
case_uri_by_name={case.name: _first_context_uri(contexts)},
session_id=session_id,
archive_uri=archive_uri,
strict_extract_errors=strict_extract_errors,
collect_memory_diff=True,
allowed_memory_types=agent_memory_types,
)
else:
train_result = {
"case_count": 1,
"submitted": 0,
"reason": "agent_evolution_disabled",
}
await self._write_final_memory_diff(
archive_uri=archive_uri,
ctx=ctx,
memory_diffs=[
_applied_memory_diff(case_write),
train_result.get("memory_diff"),
],
)
return _v3_extraction_response(
contexts=contexts,
train_result=train_result,
archive_uri=archive_uri,
)
@tracer("train.compressor_v3.fast_path.write_case", ignore_result=True, ignore_args=True)
async def _write_training_case_memory(
self,
*,
case: Case,
ctx: RequestContext,
archive_uri: str,
) -> Any:
viking_fs = get_viking_fs()
registry = get_default_registry()
schema = registry.get(_CASES_MEMORY_TYPE)
if schema is None or not schema.enabled:
raise RuntimeError("cases memory schema is not available")
extract_context = ExtractContext([])
fields = _case_to_memory_fields(case)
uri = generate_uri(
memory_type=schema,
fields=fields,
user_space=getattr(getattr(ctx, "user", None), "user_id", None) or "default",
extract_context=extract_context,
)
old_file = None
try:
raw = await viking_fs.read_file(uri, ctx=ctx)
if raw:
old_file = MemoryFileUtils.read(raw, uri=uri)
except Exception:
old_file = None
source = MemoryOperationSource(
extraction_id=(archive_uri.rstrip("/").rsplit("/", 1)[-1] if archive_uri else ""),
archive_uri=archive_uri or None,
trace_id=tracer.get_trace_id() or None,
)
operations = ResolvedOperations(
upsert_operations=[
ResolvedOperation(
old_memory_file_content=old_file,
memory_fields=fields,
memory_type=_CASES_MEMORY_TYPE,
uris=[uri],
source=source,
)
],
delete_file_contents=[],
errors=[],
)
updater = self._get_or_create_updater(registry, transaction_handle=None)
result = await updater.apply_operations(
operations,
ctx,
extract_context=extract_context,
isolation_handler=MemoryIsolationHandler(
ctx,
extract_context,
allowed_memory_types={_CASES_MEMORY_TYPE},
),
)
memory_diff = None
if archive_uri:
memory_diff = await self._build_memory_diff(
result=result,
operations=operations,
viking_fs=viking_fs,
ctx=ctx,
archive_uri=archive_uri,
)
tracer.info(
"Training CaseSpec fast path wrote case memory: "
f"case={case.name} uri={uri} written={result.written_uris} edited={result.edited_uris}"
)
return _V3AppliedMemory(result=result, operations=operations, memory_diff=memory_diff)
@tracer("train.compressor_v3.extract_user_memories", ignore_result=True, ignore_args=True)
async def _extract_user_memories(
self,
messages: List[Message],
user: Optional[Any] = None,
session_id: Optional[str] = None,
ctx: Optional[RequestContext] = None,
strict_extract_errors: bool = False,
latest_archive_overview: str = "",
archive_uri: Optional[str] = None,
allowed_memory_types: Optional[set[str]] = None,
allow_self_memory: bool = True,
peer_memory_enabled: bool = True,
allowed_peer_ids: Optional[set[str]] = None,
event_search_tags: Optional[List[str]] = None,
) -> "_V3ExtractionResult":
del user
if not messages:
return _V3ExtractionResult()
if not ctx:
logger.warning("No RequestContext provided, skipping v3 memory extraction")
return _V3ExtractionResult()
_initialize_extraction_telemetry()
try:
viking_fs = get_viking_fs()
except Exception:
logger.warning("VikingFS unavailable, skipping v3 memory extraction", exc_info=True)
return _V3ExtractionResult()
from openviking.session.memory.account_templates import resolve_account_memory_registry
registry = await resolve_account_memory_registry(
viking_fs, ctx.account_id, get_default_registry()
)
if allow_self_memory:
await registry.initialize_memory_files(
ctx,
allowed_memory_types=allowed_memory_types,
)
if self.vlm_resolver is None:
raise RuntimeError(
"SessionCompressorV3 requires a VLM resolver for account-owned work"
)
vlm_config = await self.vlm_resolver.get_vlm(ctx.account_id)
context_provider = SessionExtractContextProvider(
messages=messages,
latest_archive_overview=latest_archive_overview,
isolation_handler=None,
ctx=ctx,
viking_fs=viking_fs,
transaction_handle=None,
memory_registry=registry,
vlm_config=vlm_config,
)
await context_provider.prepare_extraction_messages()
extract_context = context_provider.get_extract_context()
isolation_handler = MemoryIsolationHandler(
ctx,
extract_context,
allowed_memory_types=allowed_memory_types,
allow_self=allow_self_memory,
allowed_peer_ids=allowed_peer_ids,
peer_memory_enabled=peer_memory_enabled,
)
isolation_handler.prepare_messages()
context_provider._isolation_handler = isolation_handler
orchestrator = self._get_or_create_react(
ctx=ctx,
messages=messages,
latest_archive_overview=latest_archive_overview,
isolation_handler=isolation_handler,
transaction_handle=None,
context_provider=context_provider,
vlm_config=vlm_config,
)
operations, _tools_used = await orchestrator.run()
if operations is None:
tracer.info("[v3_patch_merge] No memory operations generated")
return _V3ExtractionResult()
# Attach caller-provided custom scalar tags to event memories so they
# ride the same first write into the vector index (人填标量).
_apply_event_search_tags(operations, event_search_tags)
extraction_id = uuid4().hex
extracted_at = datetime.now(timezone.utc).isoformat()
updater = await get_streaming_memory_updater(
key=make_streaming_memory_updater_key(request_context=ctx),
registry=registry,
vikingdb=self.vikingdb,
config=self.streaming_memory_updater_config,
vlm_resolver=self.vlm_resolver,
)
update_result = await updater.submit(
MemoryUpdateRequest(
operations=operations,
messages=list(messages),
ctx=ctx,
strict_extract_errors=strict_extract_errors,
memory_registry=registry,
isolation_options={
"allowed_memory_types": allowed_memory_types,
"allow_self": allow_self_memory,
"allowed_peer_ids": allowed_peer_ids,
"peer_memory_enabled": peer_memory_enabled,
},
metadata={
"source_extraction_id": extraction_id,
"session_id": session_id,
"archive_uri": archive_uri,
"trace_id": tracer.get_trace_id(),
"extracted_at": extracted_at,
},
)
)
result = update_result.apply_result
patch_operations = update_result.operations
_report_extraction_telemetry(result, patch_operations)
if strict_extract_errors and result.errors:
raise MemoryUpdateError(result)
memory_diff = None
if archive_uri and viking_fs and result is not None:
memory_diff = await self._build_memory_diff(
result=result,
operations=patch_operations,
viking_fs=viking_fs,
ctx=ctx,
archive_uri=archive_uri,
)
contexts = _contexts_from_update_result(result)
canonical_cases = await _canonical_cases_from_update_result(
operations=patch_operations,
result=result,
viking_fs=viking_fs,
ctx=ctx,
)
return _V3ExtractionResult(
contexts=contexts,
cases=canonical_cases,
memory_diff=memory_diff,
case_uri_by_name=_case_uri_by_name(canonical_cases, patch_operations, result),
skipped_operations=_serialize_skipped_operations(
getattr(result, "skipped_operations", [])
),
)
def _session_skill_extraction_enabled(self) -> bool:
config = get_openviking_config()
return bool(
config.memory.session_skill_extraction_enabled and self.skill_processor is not None
)
async def extract_session_skills(
self,
*,
messages: list[Message],
ctx: Optional[RequestContext],
archive_uri: str = "",
strict_extract_errors: bool = False,
) -> dict[str, Any]:
"""Extract reusable skills without producing Agent Evolution memories."""
if not messages or ctx is None:
return {"case_count": 0, "submitted": 0, "reason": "missing_messages_or_ctx"}
if not self._session_skill_extraction_enabled():
return {"case_count": 0, "submitted": 0, "reason": "session_skills_disabled"}
extract = getattr(self.rollout_analyzer, "extract_trajectory_memories", None)
if not callable(extract):
return {
"case_count": 0,
"submitted": 0,
"reason": "session_skill_extractor_unavailable",
}
try:
result = await extract(
messages=list(messages),
ctx=ctx,
strict_extract_errors=strict_extract_errors,
include_trajectories=False,
include_session_skills=True,
source_archive_uri=archive_uri,
)
skill_gradients = [
gradient
for gradient in list((result or {}).get("skill_gradients", []))
if _gradient_memory_type(gradient) == "skills"
]
if not skill_gradients:
return {
"case_count": 0,
"submitted": 0,
"skill_submitted": 0,
"skill_uris": [],
}
viking_fs = get_viking_fs()
skill_trainer = await self._get_session_skill_trainer(
viking_fs=viking_fs,
ctx=ctx,
messages=messages,
strict_extract_errors=strict_extract_errors,
archive_uri=archive_uri,
)
training_result = await skill_trainer.submit_gradients(skill_gradients)
apply_result = getattr(training_result, "apply_result", None)
skill_uris = [
str(uri) for uri in list(getattr(apply_result, "written_uris", []) or []) if uri
]
return {
"case_count": 0,
"submitted": 0,
"skill_submitted": 1,
"skill_uris": skill_uris,
}
except Exception as exc:
logger.warning("Session skill extraction failed: %s", exc, exc_info=True)
if strict_extract_errors:
raise
return {"case_count": 0, "submitted": 0, "error": str(exc)}
async def _get_session_skill_trainer(
self,
*,
viking_fs: Any,
ctx: RequestContext,
messages: list[Message],
strict_extract_errors: bool,
archive_uri: str,
) -> Any:
skill_root_uri = _skill_root_uri(ctx)
skill_policy_set = await SkillSetLoader(viking_fs=viking_fs).load(
skill_root_uri,
ctx=ctx,
)
analysis_context = TrajectoryAnalyzerContext(
request_context=ctx,
strict_extract_errors=strict_extract_errors,
include_session_skills=True,
source_archive_uri=archive_uri,
)
return await get_streaming_policy_trainer(
key=_skill_trainer_key(ctx),
policy_set=skill_policy_set,
rollout_analyzer=self.rollout_analyzer,
gradient_estimator=_NoopGradientEstimator(),
policy_optimizer=PatchMergePolicyOptimizer(
viking_fs=viking_fs,
memory_type=SESSION_SKILL_MEMORY_TYPE,
memory_registry=load_skill_extract_registry(),
vlm_resolver=self.vlm_resolver,
),
policy_updater=SkillPolicyUpdater(
skill_processor=self.skill_processor,
viking_fs=viking_fs,
vikingdb=self.vikingdb,
memory_type="skills",
),
context=PipelineContext(
analysis_context=analysis_context,
gradient_context=ExperienceGradientContext(
request_context=ctx,
messages=list(messages),
strict_extract_errors=strict_extract_errors,
),
optimization_context=PatchMergePolicyOptimizerContext(
request_context=ctx,
),
apply_context=ctx,
),
config=self.streaming_trainer_config,
)
@tracer("train.compressor_v3.train_from_extracted_cases", ignore_result=True, ignore_args=True)
async def train_from_extracted_cases(
self,
*,
cases: list[Case],
messages: list[Message],
ctx: Optional[RequestContext],
case_uri_by_name: dict[str, str] | None = None,
session_id: Optional[str] = None,
archive_uri: str = "",
strict_extract_errors: bool = False,
collect_memory_diff: bool = False,
allowed_memory_types: Optional[set[str]] = None,
) -> dict[str, Any]:
if not messages or ctx is None:
return {"case_count": 0, "submitted": 0, "reason": "missing_messages_or_ctx"}
if not cases:
tracer.info("No commit training case memories extracted; skipping streaming train")
return {"case_count": 0, "submitted": 0}
agent_memory_types = _allowed_agent_memory_types(allowed_memory_types)
if _TRAJECTORIES_MEMORY_TYPE not in agent_memory_types:
return {
"case_count": len(cases),
"submitted": 0,
"reason": "memory_types_filtered",
}
experiences_allowed = _EXPERIENCES_MEMORY_TYPE in agent_memory_types
skill_enabled = self._session_skill_extraction_enabled()
try:
viking_fs = get_viking_fs()
# --- Experience streaming trainer ---
exp_root_uri = _experience_root_uri(ctx)
exp_policy_set = await ExperienceSetLoader(viking_fs=viking_fs).load(
exp_root_uri,
ctx=ctx,
)
optimizer_context = PatchMergePolicyOptimizerContext(request_context=ctx)
gradient_context = ExperienceGradientContext(
request_context=ctx,
messages=list(messages),
strict_extract_errors=strict_extract_errors,
)
analysis_context = TrajectoryAnalyzerContext(
request_context=ctx,
strict_extract_errors=strict_extract_errors,
include_session_skills=skill_enabled,
source_archive_uri=archive_uri or "",
)
exp_trainer = await get_streaming_policy_trainer(
key=make_streaming_policy_trainer_key(
policy_root_uri=exp_root_uri,
request_context=ctx,
),
policy_set=exp_policy_set,
rollout_analyzer=self.rollout_analyzer,
gradient_estimator=ExperienceGradientEstimator(
viking_fs=viking_fs,
vlm_resolver=self.vlm_resolver,
),
policy_optimizer=PatchMergePolicyOptimizer(
viking_fs=viking_fs,
memory_type="experiences",
vlm_resolver=self.vlm_resolver,
),
policy_updater=MemoryFilePolicyUpdater(viking_fs=viking_fs, vikingdb=self.vikingdb),
context=PipelineContext(
analysis_context=analysis_context,
gradient_context=gradient_context,
optimization_context=optimizer_context,
apply_context=ctx,
),
config=self.streaming_trainer_config,
)
# --- Skill streaming trainer ---
skill_trainer = None
if skill_enabled:
skill_trainer = await self._get_session_skill_trainer(
viking_fs=viking_fs,
ctx=ctx,
messages=messages,
strict_extract_errors=strict_extract_errors,
archive_uri=archive_uri,
)
submitted = 0
skill_submitted = 0
skill_uris: list[str] = []
filtered_exp_gradient_count = 0
memory_diffs: list[dict[str, Any]] = []
policy_snapshot_id = _commit_policy_snapshot_id(
session_id=session_id,
archive_uri=archive_uri,
)
case_uri_map = dict(case_uri_by_name or {})
evaluator = getattr(self.rollout_analyzer, "evaluator", None)
extraction_groups: dict[str, list[Rollout]] = {}
candidates_by_name = {
case.name: {
"id": f"c{index + 1}",
"name": case.name,
"task_signature": case.task_signature,
"input": case.input,
"uri": _case_uri_for_case(case, case_uri_map),
}
for index, case in enumerate(cases)
}
for case in cases:
rollout = Rollout(
case=case,
messages=list(messages),
policy_snapshot_id=policy_snapshot_id,
)
if evaluator is not None:
rollout.evaluation = await evaluator.evaluate(
rollout, analysis_context.evaluator_context
)
feedback = ""
if rollout.evaluation is not None and analysis_context.inject_evaluation_feedback:
feedback = _evaluation_feedback_message(rollout.evaluation).content
extraction_groups.setdefault(feedback, []).append(rollout)
reported_trajectory_uris: set[str] = set()
for rollouts in extraction_groups.values():
rollout = rollouts[0]
candidates = [candidates_by_name[item.case.name] for item in rollouts]
case_context = replace(analysis_context, case_candidates=candidates)
analysis = await self.rollout_analyzer.analyze(rollout, case_context)
analysis.metadata["case_associations_required"] = len(candidates) > 1
if collect_memory_diff:
# Keep every extracted trajectory, including those with no matching case.
memory_diffs.append(
await self._build_training_memory_diff(
training_result=_trajectory_only_training_result(
analysis=analysis,
rollout=rollout,
policy_set=exp_trainer.policy_set,
),
viking_fs=viking_fs,
ctx=ctx,
archive_uri=archive_uri,
reported_trajectory_uris=reported_trajectory_uris,
)
)
# Sharing extraction does not discard case-specific scores used by training.
training_groups: dict[str, list[Rollout]] = {}
for item in rollouts:
evaluation_key = json.dumps(
asdict(item.evaluation) if item.evaluation is not None else None,
sort_keys=True,
default=str,
)
training_groups.setdefault(evaluation_key, []).append(item)
for training_rollouts in training_groups.values():
training_rollout = training_rollouts[0]
trajectories = analysis.trajectories
if len(training_rollouts) < len(rollouts):
case_uris = {
candidates_by_name[item.case.name]["uri"] for item in training_rollouts
}
trajectories = [
trajectory
for trajectory in trajectories
if case_uris.intersection(trajectory.metadata.get("case_uris", []))
]
training_analysis = replace(
analysis,
evaluation=training_rollout.evaluation or analysis.evaluation,
trajectories=trajectories,
)
exp_training_result = await self._train_commit_analysis(
analysis=training_analysis,
rollout=training_rollout,
trainer=exp_trainer,
gradient_context=gradient_context,
experiences_allowed=experiences_allowed,
viking_fs=viking_fs,
ctx=ctx,
archive_uri=archive_uri,
)
for item in training_rollouts:
case_uri = candidates_by_name[item.case.name]["uri"]
if case_uri:
await self._link_case_to_training_outputs(
analysis=training_analysis,
case_uri=case_uri,
plan=exp_training_result.plan,
apply_result=exp_training_result.apply_result,
ctx=ctx,
viking_fs=viking_fs,
)
submitted += len(training_rollouts)
if collect_memory_diff:
memory_diff = await self._build_training_memory_diff(
training_result=exp_training_result,
viking_fs=viking_fs,
ctx=ctx,
archive_uri=archive_uri,
reported_trajectory_uris=reported_trajectory_uris,
)
if _memory_diff_has_changes(memory_diff):
memory_diffs.append(memory_diff)
# Co-extracted skills are submitted once for this extraction result.
if skill_trainer is not None and analysis.gradients:
skill_gradients = [
g for g in analysis.gradients if _gradient_memory_type(g) == "skills"
]
if skill_gradients:
skill_training_result = await skill_trainer.submit_gradients(
skill_gradients,
analysis=analysis,
rollout=rollout,
)
skill_submitted += 1
apply_result = getattr(skill_training_result, "apply_result", None)
if apply_result is not None:
for uri in getattr(apply_result, "written_uris", []) or []:
if uri:
skill_uris.append(str(uri))
tracer.info(
"Submitted commit case memories to streaming train: "
f"case_count={len(cases)} submitted={submitted} "
f"analysis_count={len(extraction_groups)} "
f"skill_submitted={skill_submitted}",
console=self.streaming_trainer_config.trace_console,
)
response: dict[str, Any] = {
"case_count": len(cases),
"submitted": submitted,
"skill_submitted": skill_submitted,
"skill_uris": skill_uris,
"filtered_exp_gradient_count": filtered_exp_gradient_count,
}
if collect_memory_diff:
response["memory_diff"] = _merge_memory_diffs(
memory_diffs,
archive_uri=archive_uri,
)
return response
except Exception as exc:
logger.warning("Commit streaming train failed: %s", exc, exc_info=True)
if strict_extract_errors:
raise
return {"case_count": len(cases), "submitted": 0, "error": str(exc)}
async def _train_commit_analysis(
self,
*,
analysis: RolloutAnalysis,
rollout: Rollout,
trainer: Any,
gradient_context: ExperienceGradientContext,
experiences_allowed: bool,
viking_fs: Any,
ctx: RequestContext,
archive_uri: str,
) -> RolloutTrainingResult:
gradients = []
if experiences_allowed:
gradients = await ExperienceGradientEstimator(
viking_fs=viking_fs,
vlm_resolver=self.vlm_resolver,
).estimate(analysis, trainer.policy_set, gradient_context)
if not gradients:
return _trajectory_only_training_result(
analysis=analysis,
rollout=rollout,
policy_set=trainer.policy_set,
)
async def commit_experience_batch(batch_result: RolloutTrainingResult) -> None:
persisted_result = getattr(batch_result, "batch_result", None) or batch_result
snapshot_apply_result, experience_trajectory_map = _experience_snapshot_provenance(
batch_result,
fallback_trajectory_uris={trajectory.uri for trajectory in analysis.trajectories},
)
await _commit_experience_snapshot(
viking_fs,
ctx=ctx,
experience_uris=_visible_experience_snapshot_uris(
plan=persisted_result.plan,
apply_result=snapshot_apply_result,
),
archive_uri=archive_uri,
experience_trajectory_map=experience_trajectory_map,
)
return await trainer.submit_gradients(
gradients,
analysis=analysis,
rollout=rollout,
batch_finalizer=commit_experience_batch,
)
async def _build_training_memory_diff(
self,
*,
training_result: RolloutTrainingResult,
viking_fs: Any,
ctx: RequestContext,
archive_uri: str,
reported_trajectory_uris: set[str] | None = None,
) -> dict[str, Any]:
adds: list[dict[str, Any]] = []
updates: list[dict[str, Any]] = []
deletes: list[dict[str, Any]] = []
seen_trajectory_uris: set[str] = set()
for analysis in training_result.analyses:
for trajectory in analysis.trajectories:
uri = trajectory.uri
if not uri or uri in seen_trajectory_uris:
continue
seen_trajectory_uris.add(uri)
if reported_trajectory_uris is not None:
if uri in reported_trajectory_uris:
continue
reported_trajectory_uris.add(uri)
adds.append(
{
"uri": uri,
"memory_type": "trajectories",
"after": trajectory.content,
}
)
applied_uris = set(training_result.apply_result.written_uris)
deleted_uris = set(training_result.apply_result.deleted_uris)
root_uri = training_result.apply_result.updated_policy_set.root_uri
if not root_uri:
raise ValueError(
"PolicyApplyResult.updated_policy_set.root_uri is required for training memory diff"
)
source_trajectory_uris = set(seen_trajectory_uris)
for item in training_result.plan.items:
if item.memory_type != "experiences":
continue
if source_trajectory_uris and not _plan_item_has_source_trajectory(
item,
source_trajectory_uris,
):
continue
uri = _experience_plan_item_uri(item, root_uri)
if not uri:
continue
if item.kind == "delete":
if uri in deleted_uris:
deletes.append(
{
"uri": uri,
"memory_type": "experiences",
"deleted_content": item.before_content or "",
}
)
continue
if item.kind != "upsert" or uri not in applied_uris:
continue
after = await _read_plain_memory_content(
viking_fs,
uri=uri,
ctx=ctx,
fallback=item.after_content or "",
)
before = item.before_content
if before is None:
adds.append({"uri": uri, "memory_type": "experiences", "after": after})
else:
# Filter no-op experience updates the same way as user-memory
# updates: a patch that re-serializes to identical content should
# not appear in memory_diff.json.
try:
old_file = MemoryFileUtils.read(before, uri=uri) if before else None
new_file = MemoryFileUtils.read(after, uri=uri) if after else None
except Exception:
old_file, new_file = None, None
if old_file is not None and _same_memory_file(old_file, new_file):
logger.info("Skipping unchanged experience memory in memory_diff.json: %s", uri)
continue
updates.append(
{
"uri": uri,
"memory_type": "experiences",
"before": before,
"after": after,
}
)
return _make_memory_diff(
archive_uri=archive_uri,
adds=adds,
updates=updates,
deletes=deletes,
)
async def _link_case_to_training_outputs(
self,
*,
analysis: RolloutAnalysis,
case_uri: str,
plan: PolicyUpdatePlan,
apply_result: PolicyApplyResult,
ctx: RequestContext,
viking_fs: Any,
) -> None:
links = _case_training_links(
analysis=analysis,
case_uri=case_uri,
plan=plan,
apply_result=apply_result,
)
if not links:
return
await _render_case_links_from_template(
case_uri=case_uri,
links=links,
ctx=ctx,
viking_fs=viking_fs,
)
await write_stored_links(links, ctx, viking_fs, skip_uris={case_uri})
async def _write_final_memory_diff(
self,
*,
archive_uri: str,
ctx: Optional[RequestContext],
memory_diffs: list[Any],
) -> None:
if not archive_uri or ctx is None:
return
merged = _merge_memory_diffs(
[diff for diff in memory_diffs if isinstance(diff, dict)],
archive_uri=archive_uri,
)
viking_fs = get_viking_fs()
if viking_fs is None:
return
await viking_fs.write_file(
uri=f"{archive_uri.rstrip('/')}/memory_diff.json",
content=json.dumps(merged, ensure_ascii=False, indent=4),
ctx=ctx,
)
@dataclass(slots=True)
class _V3ExtractionResult:
contexts: list[Context] = field(default_factory=list)
cases: list[Case] = field(default_factory=list)
memory_diff: dict[str, Any] | None = None
case_uri_by_name: dict[str, str] = field(default_factory=dict)
skipped_operations: list[dict[str, Any]] = field(default_factory=list)
@dataclass(slots=True)
class _V3AppliedMemory:
result: Any
operations: ResolvedOperations
memory_diff: dict[str, Any] | None = None
def _contexts_from_update_result(result: Any) -> list[Context]:
contexts = []
for uri in result.written_uris:
contexts.append(Context(uri=uri, category="memory_write", context_type="memory"))
for uri in result.edited_uris:
contexts.append(Context(uri=uri, category="memory_edit", context_type="memory"))
for uri in result.deleted_uris:
contexts.append(Context(uri=uri, category="memory_delete", context_type="memory"))
return contexts
def _training_case_from_first_message(
messages: list[Message],
allowed_memory_types: Optional[set[str]],
) -> Case | None:
"""Parse a batch-training CaseSpec control message from message[0].
The fast path is deliberately gated by the commit memory policy so normal
user sessions never bypass user-memory extraction. Once the protocol
header is present, malformed payloads are treated as errors instead of
silently falling back to LLM extraction.
"""
if not messages or allowed_memory_types is None:
return None
if not {_CASES_MEMORY_TYPE, _TRAJECTORIES_MEMORY_TYPE}.issubset(allowed_memory_types):
return None
if not set(allowed_memory_types).issubset(_TRAINING_FAST_PATH_MEMORY_TYPES):
return None
payload = _training_case_spec_payload_from_message(messages[0])
if payload is None:
return None
return _case_from_payload(payload)
def _allowed_agent_memory_types(allowed_memory_types: Optional[set[str]]) -> set[str]:
if allowed_memory_types is None:
return set(_AGENT_MEMORY_TYPES)
return set(allowed_memory_types) & _AGENT_MEMORY_TYPES
def _training_case_spec_payload_from_message(message: Message) -> dict[str, Any] | None:
text = _message_text(message).strip()
if not text.startswith(_TRAINING_CASE_SPEC_HEADER):
return None
return _parse_training_case_spec_payload(text)
def _message_text(message: Message) -> str:
content = getattr(message, "content", "")
if content:
return str(content)
texts: list[str] = []
for part in getattr(message, "parts", []) or []:
text = getattr(part, "text", None)
if text:
texts.append(str(text))
return "\n".join(texts)
def _training_messages_after_case_spec(messages: list[Message]) -> list[Message]:
"""Return commit messages after CaseSpec."""
return list(messages[1:])
def _parse_training_case_spec_payload(text: str) -> dict[str, Any]:
match = _JSON_FENCE_RE.search(text)
raw_payload = (
match.group(1).strip() if match else text.removeprefix(_TRAINING_CASE_SPEC_HEADER).strip()
)
if not raw_payload:
raise ValueError("Training CaseSpec fast path payload is empty")
try:
payload = JsonUtils.loads(raw_payload)
except Exception as exc:
raise ValueError("Training CaseSpec fast path payload is not valid JSON") from exc
if not isinstance(payload, dict):
raise ValueError("Training CaseSpec fast path payload must be a JSON object")
protocol = str(payload.get("protocol") or "")
if protocol != _TRAINING_CASE_SPEC_PROTOCOL:
raise ValueError(
"Training CaseSpec fast path protocol mismatch: "
f"expected {_TRAINING_CASE_SPEC_PROTOCOL!r}, got {protocol!r}"
)
if not isinstance(payload.get("case"), dict):
raise ValueError("Training CaseSpec fast path payload must contain a case object")
return payload
def _case_from_payload(payload: dict[str, Any]) -> Case:
raw_case = payload["case"]
name = str(raw_case.get("name") or "").strip()
task_signature = str(raw_case.get("task_signature") or "").strip()
if not name:
raise ValueError("Training CaseSpec case.name is required")
if not task_signature:
raise ValueError("Training CaseSpec case.task_signature is required")
case_input = raw_case.get("input")
if not isinstance(case_input, dict):
raise ValueError("Training CaseSpec case.input must be an object")
rubric = _rubric_from_payload(raw_case.get("rubric"), fallback_name=f"{name}_rubric")
metadata = raw_case.get("metadata") if isinstance(raw_case.get("metadata"), dict) else {}
return Case(
name=name,
task_signature=task_signature,
input=dict(case_input),
rubric=rubric,
metadata={
"source": "batch_training_case_spec",
**dict(metadata),
},
)
def _rubric_from_payload(raw_rubric: Any, *, fallback_name: str) -> Rubric:
if not isinstance(raw_rubric, dict):
raise ValueError("Training CaseSpec case.rubric must be an object")
raw_criteria = raw_rubric.get("criteria")
if not isinstance(raw_criteria, list) or not raw_criteria:
raise ValueError("Training CaseSpec case.rubric.criteria must be a non-empty list")
criteria: list[RubricCriterion] = []
for index, item in enumerate(raw_criteria):
if not isinstance(item, dict):
raise ValueError("Training CaseSpec rubric criteria must be objects")
name = str(item.get("name") or f"criterion_{index + 1}").strip()
description = str(item.get("description") or "").strip()
if not description:
raise ValueError("Training CaseSpec rubric criterion.description is required")
criteria.append(
RubricCriterion(
name=name,
description=description,
required=bool(item.get("required", True)),
weight=_safe_weight(item.get("weight"), default=1.0),
metadata=dict(item.get("metadata") or {})
if isinstance(item.get("metadata"), dict)
else {},
)
)
return Rubric(
name=str(raw_rubric.get("name") or fallback_name),
description=str(
raw_rubric.get("description") or "Defines what good means for this batch training case."
),
criteria=criteria,
metadata=dict(raw_rubric.get("metadata") or {})
if isinstance(raw_rubric.get("metadata"), dict)
else {},
)
def _case_to_memory_fields(case: Case) -> dict[str, Any]:
return {
"case_name": case.name,
"task_signature": case.task_signature,
"input": json.dumps(case.input or {}, ensure_ascii=False, sort_keys=True),
"rubric": json.dumps(
_rubric_to_payload(case.rubric),
ensure_ascii=False,
sort_keys=True,
),
"evidence": _case_evidence(case),
}
def _rubric_to_payload(rubric: Rubric) -> dict[str, Any]:
return {
"name": rubric.name,
"description": rubric.description,
"criteria": [
{
"name": criterion.name,
"description": criterion.description,
"required": criterion.required,
"weight": criterion.weight,
}
for criterion in rubric.criteria
],
}
def _case_evidence(case: Case) -> str:
raw_evidence = (case.metadata or {}).get("evidence")
if raw_evidence:
return str(raw_evidence)
return "Structured batch training CaseSpec supplied by the training pipeline."
async def _canonical_cases_from_update_result(
*,
operations: ResolvedOperations,
result: Any,
viking_fs: Any,
ctx: RequestContext,
) -> list[Case]:
"""Build training cases from canonical case files after patch merge/apply.
The extractor can emit multiple case proposals, but ``StreamingMemoryUpdater``
may merge, rename, or deduplicate them before storage. Training must follow
the actual persisted case-first state, so only cases whose canonical URI was
written/edited by this update are returned.
"""
touched_uris = _case_result_touched_uris(result)
if not touched_uris:
return []
case_ops_by_uri: dict[str, ResolvedOperation] = {}
for op in getattr(operations, "upsert_operations", []) or []:
if getattr(op, "memory_type", None) != _CASES_MEMORY_TYPE:
continue
for uri in getattr(op, "uris", []) or []:
if uri in touched_uris and uri not in case_ops_by_uri:
case_ops_by_uri[uri] = op
cases: list[Case] = []
for uri in touched_uris:
if uri not in case_ops_by_uri:
continue
case = await _case_from_persisted_memory_file(uri=uri, viking_fs=viking_fs, ctx=ctx)
if case is None:
case = _operation_to_case(
case_ops_by_uri[uri].model_copy(update={"uris": [uri]}, deep=True)
)
if case is not None:
cases.append(case)
return cases
def _case_result_touched_uris(result: Any) -> list[str]:
uris = list(getattr(result, "written_uris", []) or []) + list(
getattr(result, "edited_uris", []) or []
)
return [
uri
for uri in dict.fromkeys(str(uri) for uri in uris if uri)
if _uri_is_case_memory_file(uri)
]
def _uri_is_case_memory_file(uri: str) -> bool:
return "/memories/cases/" in str(uri or "") and not str(uri).rstrip("/").endswith(
("/.overview.md", "/.abstract.md")
)
async def _case_from_persisted_memory_file(
*,
uri: str,
viking_fs: Any,
ctx: RequestContext,
) -> Case | None:
try:
raw = await viking_fs.read_file(uri, ctx=ctx)
except Exception as exc:
tracer.info(f"Failed to read canonical case memory for training {uri}: {exc}")
return None
try:
memory_file = MemoryFileUtils.read(raw or "", uri=uri)
except Exception as exc:
tracer.info(f"Failed to parse canonical case memory for training {uri}: {exc}")
return None
return _memory_file_to_case(memory_file)
def _memory_file_to_case(memory_file: MemoryFile) -> Case | None:
fields = dict(getattr(memory_file, "extra_fields", {}) or {})
uri = str(getattr(memory_file, "uri", "") or "")
name = str(fields.get("case_name") or fields.get("name") or _basename_case_name(uri)).strip()
task_signature = str(fields.get("task_signature") or name).strip()
if not name or not task_signature:
return None
memory_fields = dict(fields)
if uri:
memory_fields.setdefault("uri", uri)
return Case(
name=name,
task_signature=task_signature,
input=_parse_case_input(fields.get("input")),
rubric=_parse_rubric(fields.get("rubric"), fallback_name=f"{name}_rubric"),
metadata={
"source": "session_commit_case_memory",
"case_uris": [uri] if uri else [],
"evidence": str(fields.get("evidence") or ""),
"memory_fields": memory_fields,
},
)
def _operation_to_case(op: ResolvedOperation) -> Case | None:
fields = dict(getattr(op, "memory_fields", {}) or {})
name = str(fields.get("case_name") or fields.get("name") or _fallback_case_name(op)).strip()
task_signature = str(fields.get("task_signature") or name).strip()
if not name or not task_signature:
return None
return Case(
name=name,
task_signature=task_signature,
input=_parse_case_input(fields.get("input")),
rubric=_parse_rubric(fields.get("rubric"), fallback_name=f"{name}_rubric"),
metadata={
"source": "session_commit_case_memory",
"case_uris": list(getattr(op, "uris", []) or []),
"evidence": str(fields.get("evidence") or ""),
"memory_fields": fields,
},
)
def _parse_case_input(raw_input: Any) -> dict[str, Any]:
parsed = _parse_jsonish(raw_input)
if isinstance(parsed, dict):
return parsed
if isinstance(parsed, list):
return {"items": parsed}
return {"summary": str(raw_input or "")}
def _parse_rubric(raw_rubric: Any, *, fallback_name: str) -> Rubric:
parsed = _parse_jsonish(raw_rubric)
raw = parsed if isinstance(parsed, dict) else {}
raw_criteria = raw.get("criteria") if isinstance(raw.get("criteria"), list) else []
criteria: list[RubricCriterion] = []
for index, item in enumerate(raw_criteria):
if not isinstance(item, dict):
continue
criteria.append(
RubricCriterion(
name=str(item.get("name") or f"criterion_{index + 1}"),
description=str(item.get("description") or "The rollout satisfies the task."),
required=bool(item.get("required", True)),
weight=_safe_weight(item.get("weight"), default=1.0),
)
)
if not criteria:
criteria = [
RubricCriterion(
name="task_completed",
description="The assistant completed the user's task with verifiable outcome.",
required=True,
weight=1.0,
)
]
return Rubric(
name=str(raw.get("name") or fallback_name),
description=str(raw.get("description") or "Defines what good means for this commit case."),
criteria=criteria,
)
def _parse_jsonish(value: Any) -> Any:
if isinstance(value, (dict, list)):
return value
if not isinstance(value, str) or not value.strip():
return None
try:
return JsonUtils.loads(value)
except Exception:
return None
def _safe_weight(value: Any, *, default: float) -> float:
try:
parsed = float(value)
except (TypeError, ValueError):
return default
return parsed if parsed > 0 else default
def _first_uri(uris: list[str] | None) -> str | None:
return uris[0] if uris else None
def _fallback_case_name(op: ResolvedOperation) -> str:
uri = _first_uri(getattr(op, "uris", []) or [])
name = _basename_case_name(uri)
if name:
return name
return "commit_case"
def _basename_case_name(uri: str | None) -> str:
if uri:
return uri.rstrip("/").split("/")[-1].removesuffix(".md")
return ""
def _user_space_from_ctx(ctx: RequestContext, *, purpose: str) -> str:
user_space = getattr(getattr(ctx, "user", None), "user_id", None)
if not user_space:
raise ValueError(f"RequestContext.user.user_id is required for {purpose}")
return str(user_space)
def _experience_root_uri(ctx: RequestContext) -> str:
user_space = _user_space_from_ctx(ctx, purpose="experience memory root URI")
return f"viking://user/{user_space}/memories/experiences"
def _skill_root_uri(ctx: RequestContext) -> str:
user_space = _user_space_from_ctx(ctx, purpose="skill root URI")
return f"viking://user/{user_space}/skills"
def _skill_trainer_key(ctx: RequestContext) -> tuple[str, str, str]:
"""Registry key for the skill streaming trainer (separate from exp trainer)."""
from openviking.session.train.components.policy_trainer import (
make_streaming_policy_trainer_key,
)
return make_streaming_policy_trainer_key(
policy_root_uri=_skill_root_uri(ctx),
request_context=ctx,
)
@dataclass(slots=True)
class _NoopGradientEstimator:
"""GradientEstimator that returns empty gradients.
Used for the skill trainer because skill gradients are co-extracted
during trajectory analysis and submitted directly via
``submit_gradients``; the estimator is never called in practice but
``StreamingPolicyTrainer`` requires one.
"""
async def estimate(
self,
analysis: Any,
policy_set: Any,
context: Any = None,
) -> list[Any]:
return []
def _case_uri_for_case(case: Case, case_uri_by_name: dict[str, str]) -> str:
if case.name in case_uri_by_name:
return case_uri_by_name[case.name]
uris = (case.metadata or {}).get("case_uris")
if isinstance(uris, list) and uris:
return str(uris[0])
fields = (case.metadata or {}).get("memory_fields")
if isinstance(fields, dict):
uri = fields.get("uri")
if uri:
return str(uri)
return ""
def _case_uri_by_name(
cases: list[Case],
operations: ResolvedOperations,
result: Any,
) -> dict[str, str]:
candidates = set(
(getattr(result, "written_uris", []) or []) + (getattr(result, "edited_uris", []) or [])
)
mapping: dict[str, str] = {}
for op in getattr(operations, "upsert_operations", []) or []:
if getattr(op, "memory_type", None) != _CASES_MEMORY_TYPE:
continue
fields = dict(getattr(op, "memory_fields", {}) or {})
name = str(fields.get("case_name") or fields.get("name") or "").strip()
if not name:
continue
for uri in getattr(op, "uris", []) or []:
if not candidates or uri in candidates:
mapping[name] = uri
break
for case in cases:
if case.name not in mapping:
uri = _case_uri_for_case(case, {})
if uri:
mapping[case.name] = uri
return mapping
def _first_context_uri(contexts: list[Context]) -> str:
for context in contexts or []:
uri = getattr(context, "uri", "")
if uri:
return str(uri)
return ""
def _case_training_links(
*,
analysis: RolloutAnalysis,
case_uri: str,
plan: PolicyUpdatePlan,
apply_result: PolicyApplyResult,
) -> list[StoredLink]:
trajectory_links = _case_trajectory_links(analysis=analysis, case_uri=case_uri)
trajectory_uris = {link.to_uri for link in trajectory_links if link.to_uri}
experience_links = _case_experience_links_via_trajectories(
case_uri=case_uri,
trajectory_uris=trajectory_uris,
plan=plan,
apply_result=apply_result,
)
return merge_link_lists([*trajectory_links, *experience_links])
def _case_trajectory_links(
*,
analysis: RolloutAnalysis,
case_uri: str,
) -> list[StoredLink]:
links: list[StoredLink] = []
for trajectory in getattr(analysis, "trajectories", []) or []:
case_uris = trajectory.metadata.get("case_uris")
if case_uris is not None:
if case_uri not in case_uris:
continue
elif analysis.metadata.get("case_associations_required"):
continue
uri = str(getattr(trajectory, "uri", "") or "")
if not uri or "/memories/trajectories/" not in uri:
continue
links.append(
_stored_link(
from_uri=case_uri,
target_uri=uri,
link_type="related_to",
description="",
)
)
return links
def _case_experience_links_via_trajectories(
*,
case_uri: str,
trajectory_uris: set[str],
plan: PolicyUpdatePlan,
apply_result: PolicyApplyResult,
) -> list[StoredLink]:
if not trajectory_uris:
return []
touched = set(getattr(apply_result, "written_uris", []) or [])
touched.update(getattr(apply_result, "edited_uris", []) or [])
result: list[StoredLink] = []
seen: set[str] = set()
root_uri = getattr(getattr(apply_result, "updated_policy_set", None), "root_uri", "")
if not root_uri:
raise ValueError(
"PolicyApplyResult.updated_policy_set.root_uri is required for case-to-experience links"
)
for item in getattr(plan, "items", []) or []:
if item.memory_type != "experiences" or item.kind != "upsert":
continue
if not _plan_item_has_source_trajectory(item, trajectory_uris):
continue
uri = _experience_plan_item_uri(item, root_uri)
if uri not in touched:
continue
if uri in seen:
continue
seen.add(uri)
result.append(
_stored_link(
from_uri=case_uri,
target_uri=uri,
link_type="related_to",
description="",
)
)
return result
def _plan_item_has_source_trajectory(item: PolicyPlanItem, trajectory_uris: set[str]) -> bool:
return bool(_plan_item_source_trajectory_uris(item, trajectory_uris))
def _plan_item_source_trajectory_uris(
item: PolicyPlanItem,
trajectory_uris: set[str],
) -> list[str]:
result: list[str] = []
seen: set[str] = set()
for link in getattr(item, "links", []) or []:
try:
stored = link if isinstance(link, StoredLink) else StoredLink(**dict(link))
except Exception:
continue
if (
stored.link_type == "derived_from"
and stored.to_uri in trajectory_uris
and "/memories/trajectories/" in str(stored.to_uri or "")
):
uri = str(stored.to_uri)
if uri not in seen:
seen.add(uri)
result.append(uri)
return result
def _experience_trajectory_map(
*,
plan: PolicyUpdatePlan,
apply_result: PolicyApplyResult,
trajectory_uris: set[str],
) -> dict[str, list[str]]:
root_uri = getattr(getattr(apply_result, "updated_policy_set", None), "root_uri", "")
if not root_uri:
return {}
written_uris = set(getattr(apply_result, "written_uris", []) or [])
result: dict[str, list[str]] = {}
for item in getattr(plan, "items", []) or []:
if item.memory_type != "experiences" or item.kind != "upsert":
continue
experience_uri = _experience_plan_item_uri(item, root_uri)
if not experience_uri or experience_uri not in written_uris:
continue
source_uris = _plan_item_source_trajectory_uris(item, trajectory_uris)
if not source_uris:
continue
existing = result.setdefault(experience_uri, [])
existing.extend(uri for uri in source_uris if uri not in existing)
return result
def _visible_experience_snapshot_uris(
*,
plan: PolicyUpdatePlan,
apply_result: PolicyApplyResult,
) -> list[str]:
"""Return successfully applied Experience paths whose visible content changed."""
root_uri = getattr(getattr(apply_result, "updated_policy_set", None), "root_uri", "")
written_uris = set(getattr(apply_result, "written_uris", []) or [])
deleted_uris = set(getattr(apply_result, "deleted_uris", []) or [])
result: list[str] = []
seen: set[str] = set()
for item in getattr(plan, "items", []) or []:
if item.memory_type != _EXPERIENCES_MEMORY_TYPE:
continue
if item.before_content == item.after_content:
continue
uri = _experience_plan_item_uri(item, root_uri)
if not uri or uri in seen:
continue
if item.kind == "upsert":
applied = uri in written_uris
elif item.kind == "delete":
applied = uri in deleted_uris
else:
applied = False
if not applied:
continue
seen.add(uri)
result.append(uri)
return result
def _experience_snapshot_provenance(
training_result: Any,
*,
fallback_trajectory_uris: Optional[set[str]] = None,
) -> tuple[PolicyApplyResult, dict[str, list[str]]]:
"""Return provenance for the complete update that reached storage.
Concurrent submitters can share one streaming trainer flush. Their
top-level result is scoped to one submitter, while ``batch_result`` owns
the complete plan and apply result that were written atomically. Snapshot
history must describe that complete persisted update, regardless of which
waiter reaches the snapshot commit first.
"""
persisted_result = getattr(training_result, "batch_result", None) or training_result
apply_result = persisted_result.apply_result
trajectory_uris = {
uri
for analysis in getattr(persisted_result, "analyses", []) or []
for trajectory in getattr(analysis, "trajectories", []) or []
if (uri := str(getattr(trajectory, "uri", "") or ""))
}
if not trajectory_uris:
trajectory_uris = set(fallback_trajectory_uris or set())
return apply_result, _experience_trajectory_map(
plan=persisted_result.plan,
apply_result=apply_result,
trajectory_uris=trajectory_uris,
)
def _stored_link(
*,
from_uri: str,
target_uri: str,
link_type: str,
description: str,
) -> StoredLink:
return StoredLink(
from_uri=from_uri,
to_uri=target_uri,
link_type=link_type,
weight=1.0,
match_text=None,
description=description,
created_at=datetime.now(timezone.utc).isoformat(),
)
async def _render_case_links_from_template(
*,
case_uri: str,
links: list[StoredLink],
ctx: RequestContext,
viking_fs: Any,
) -> None:
if not links:
return
try:
raw = await viking_fs.read_file(case_uri, ctx=ctx)
except Exception as exc:
tracer.error(f"Failed to read case memory for link rendering {case_uri}: {exc}")
return
mf = MemoryFileUtils.read(raw or "", uri=case_uri)
from openviking.session.memory.merge_op.link_merge import merge_links
merged_links = merge_links(mf.links, [link.model_dump() for link in links])
if merged_links != mf.links:
mf.links = merged_links
schema = get_default_registry().get(_CASES_MEMORY_TYPE)
content_template = schema.content_template if schema is not None else None
await viking_fs.write_file(
case_uri,
MemoryFileUtils.write(mf, content_template=content_template),
ctx=ctx,
)
def _gradient_memory_type(gradient: Any) -> str:
"""Extract memory_type from a semantic gradient."""
after_file = getattr(gradient, "after_file", None)
if after_file is not None:
mt = getattr(after_file, "memory_type", None)
if mt:
return str(mt)
metadata = dict(getattr(gradient, "metadata", {}) or {})
if metadata.get("memory_type"):
return str(metadata["memory_type"])
before_file = getattr(gradient, "before_file", None)
if before_file is not None:
mt = getattr(before_file, "memory_type", None)
if mt:
return str(mt)
return "experiences"
def _trajectory_only_training_result(
*,
analysis: RolloutAnalysis,
rollout: Rollout,
policy_set: Any,
) -> RolloutTrainingResult:
"""Return a typed no-op training result that still carries trajectories.
Some rollouts produce useful trajectory memories but no experience gradients.
The memory diff should still include those trajectory writes, so callers use
this as the baseline result and replace it only when experience training
returns a full RolloutTrainingResult.
"""
return RolloutTrainingResult(
analyses=[analysis],
gradients=[],
plan=PolicyUpdatePlan(items=[], metadata={"no_experience_gradients": True}),
apply_result=PolicyApplyResult(
updated_policy_set=policy_set,
written_uris=[],
errors=[],
metadata={"no_experience_gradients": True},
),
metadata={
"source": "trajectory_only",
"case_name": rollout.case.name,
"trajectory_count": len(analysis.trajectories),
},
)
def _applied_memory_result(value: Any) -> Any:
if isinstance(value, _V3AppliedMemory):
return value.result
result = getattr(value, "result", None)
return result if result is not None else value
def _applied_memory_diff(value: Any) -> dict[str, Any] | None:
if isinstance(value, _V3AppliedMemory):
return value.memory_diff
memory_diff = getattr(value, "memory_diff", None)
return memory_diff if isinstance(memory_diff, dict) else None
def _same_memory_file(before: Optional[MemoryFile], after: Optional[MemoryFile]) -> bool:
"""Return whether two parsed memory files represent the same stored memory."""
if before is None or after is None:
return False
# memory_type is commonly known from the operation/URI even when the raw
# memory file does not serialize it, so do not treat that metadata-only
# representation difference as a real file update.
return before.model_dump(exclude={"uri", "memory_type"}) == after.model_dump(
exclude={"uri", "memory_type"}
)
def _serialize_skipped_operations(items: Any) -> list[dict[str, Any]]:
serialized: list[dict[str, Any]] = []
for item in list(items or []):
if isinstance(item, dict):
payload = dict(item)
else:
model_dump = getattr(item, "model_dump", None)
if not callable(model_dump):
continue
payload = model_dump(mode="json", exclude_none=True)
if isinstance(payload, dict):
payload.pop("source", None)
serialized.append(payload)
return serialized
def _v3_extraction_response(
*,
contexts: list[Context],
train_result: Any,
archive_uri: str,
) -> list[Context] | dict[str, Any]:
"""Build the extraction response.
Historically ``extract_long_term_memories`` returned ``list[Context]`` and
a number of direct callers still index/compare the return value as a list.
Commit orchestration also understands a structured response for session
skills. Preserve the old list shape unless there are actual session skills
to report.
"""
skill_dicts: list[dict[str, Any]] = []
seen: set[str] = set()
if isinstance(train_result, dict):
for uri in train_result.get("skill_uris", []) or []:
uri_str = str(uri or "")
if uri_str and uri_str not in seen:
seen.add(uri_str)
skill_dicts.append({"uri": uri_str, "archive_uri": archive_uri})
if not skill_dicts:
return contexts
return {"contexts": contexts, "session_skills": skill_dicts}
def _make_memory_diff(
*,
archive_uri: str,
adds: list[dict[str, Any]],
updates: list[dict[str, Any]],
deletes: list[dict[str, Any]],
skipped_operations: Optional[list[dict[str, Any]]] = None,
) -> dict[str, Any]:
skipped = list(skipped_operations or [])
return {
"archive_uri": archive_uri,
"trace_id": tracer.get_trace_id() or None,
"extracted_at": datetime.now(timezone.utc).isoformat(),
"operations": {
"adds": list(adds),
"updates": list(updates),
"deletes": list(deletes),
},
"skipped_operations": skipped,
"summary": {
"total_adds": len(adds),
"total_updates": len(updates),
"total_deletes": len(deletes),
"total_skipped": len(skipped),
},
}
def _merge_memory_diffs(
diffs: list[dict[str, Any]],
*,
archive_uri: str,
) -> dict[str, Any]:
adds: list[dict[str, Any]] = []
updates: list[dict[str, Any]] = []
deletes: list[dict[str, Any]] = []
skipped_operations: list[dict[str, Any]] = []
trace_id = tracer.get_trace_id() or None
for diff in diffs:
if not isinstance(diff, dict):
continue
if trace_id is None and diff.get("trace_id"):
trace_id = str(diff.get("trace_id"))
skipped_operations.extend(
item for item in diff.get("skipped_operations", []) if isinstance(item, dict)
)
operations = diff.get("operations")
if not isinstance(operations, dict):
continue
adds.extend([item for item in operations.get("adds", []) if isinstance(item, dict)])
updates.extend([item for item in operations.get("updates", []) if isinstance(item, dict)])
deletes.extend([item for item in operations.get("deletes", []) if isinstance(item, dict)])
merged = _make_memory_diff(
archive_uri=archive_uri,
adds=adds,
updates=updates,
deletes=deletes,
skipped_operations=skipped_operations,
)
merged["trace_id"] = trace_id
return merged
def _memory_diff_has_changes(diff: Any) -> bool:
if not isinstance(diff, dict):
return False
summary = diff.get("summary")
if not isinstance(summary, dict):
return False
return any(
int(summary.get(key) or 0) > 0
for key in ("total_adds", "total_updates", "total_deletes", "total_skipped")
)
async def _read_plain_memory_content(
viking_fs: Any,
*,
uri: str,
ctx: RequestContext,
fallback: str,
) -> str:
try:
raw = await viking_fs.read_file(uri, ctx=ctx)
return MemoryFileUtils.read(raw, uri=uri).content
except Exception:
return fallback
def _experience_plan_item_uri(item: PolicyPlanItem, root_uri: str) -> str:
if item.target_uri:
return item.target_uri
name = item.target_name or "new_experience"
return f"{root_uri.rstrip('/')}/{_safe_experience_filename(name)}.md"
_EXPERIENCE_NAME_RE = re.compile(r"[^a-zA-Z0-9_.-]+")
def _safe_experience_filename(name: str) -> str:
filename = _EXPERIENCE_NAME_RE.sub("_", name.strip()).strip("._-")
return filename or "new_experience"
def _commit_policy_snapshot_id(*, session_id: Optional[str], archive_uri: str) -> str:
if archive_uri:
return f"session-commit:{archive_uri.rstrip('/').rsplit('/', 1)[-1]}"
if session_id:
return f"session-commit:{session_id}"
return f"session-commit:{uuid4().hex}"