Skip to content

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

feat(memory): improve agent memory pipeline reliability (#1966)

yangxinxin-7f33327759d19
diff --git a/openviking/prompts/templates/memory/experiences.yaml b/openviking/prompts/templates/memory/experiences.yaml
index 3792bb130..745470b7c 100644
--- a/openviking/prompts/templates/memory/experiences.yaml
+++ b/openviking/prompts/templates/memory/experiences.yaml
@@ -13,9 +13,11 @@ fields:
- name: experience_name
type: string
description: |
- Lowercase snake_case, ASCII only, max 5 words. Name the generalizable pattern, not the specific instance.
- Do not use Chinese.
- Good: "booking_duplicate_handling", "pytest_asyncio_cancel_hang_fix".
+ Name the generalizable pattern, not the specific instance.
+ Choose ONE language and stick to it — do not create both a Chinese and an English version of the same concept.
+ If English: lowercase snake_case, max 5 words.
+ If Chinese: concise noun phrase, max 15 characters.
+ Good: "booking_duplicate_handling", "pytest_asyncio_cancel_hang_fix", "重复预订处理".
merge_op: immutable
- name: content
@@ -40,4 +42,13 @@ fields:
- FAILURE INTEGRATION: Translate past mistakes into strict negative constraints. These MUST be placed exclusively in the 'Reflect' section.
- STRICT FORMATTING: Use exactly the 3 headings above in this order. Use concise markdown bullets (-) for every section. No numbered lists, no introductory sentences, no conversational filler, and no closing paragraphs. Token efficiency is critical.
- merge_op: patch
+ merge_op: replace
+
+ - name: supersedes
+ type: string
+ description: |
+ The experience_name of an existing experience that this one supersedes.
+ Set ONLY when this experience replaces a narrower existing experience with a DIFFERENT name.
+ The system will automatically delete the old experience and inherit its trajectory history.
+ Leave empty for a new experience or when updating an experience with the same name.
+ merge_op: replace
diff --git a/openviking/prompts/templates/memory/trajectories.yaml b/openviking/prompts/templates/memory/trajectories.yaml
index 8d8633490..bd894dfef 100644
--- a/openviking/prompts/templates/memory/trajectories.yaml
+++ b/openviking/prompts/templates/memory/trajectories.yaml
@@ -6,7 +6,7 @@ description: |
Skip pure chitchat or simple Q&A with no execution trace.
directory: "viking://agent/{{ agent_space }}/memories/trajectories"
-filename_template: "{{ trajectory_name }}.md"
+filename_template: "{{ trajectory_name }}_{{ extract_context.get_session_timestamp() }}.md"
enabled: true
operation_mode: "add_only"
agent_only: true
@@ -15,9 +15,12 @@ fields:
- name: trajectory_name
type: string
description: |
- Lowercase snake_case, ASCII only, max 5 words. Name the task directly and stably.
- Do not use Chinese. Do not create near-duplicate names for the same task.
- Good: "flight_booking_duplicate_resolution", "pytest_asyncio_cancel_hang_fix".
+ Name the task directly and stably.
+ Choose ONE language and stick to it — do not create both a Chinese and an English version of the same concept.
+ If English: lowercase snake_case, max 5 words.
+ If Chinese: concise noun phrase, max 15 characters.
+ Do not create near-duplicate names for the same task.
+ Good: "flight_booking_duplicate_resolution", "pytest_asyncio_cancel_hang_fix", "机票重复预订处理".
merge_op: immutable
- name: outcome
diff --git a/openviking/session/compressor_v2.py b/openviking/session/compressor_v2.py
index fc7b1da22..38671b612 100644
--- a/openviking/session/compressor_v2.py
+++ b/openviking/session/compressor_v2.py
@@ -40,44 +40,6 @@ logger = get_logger(__name__)
MAX_SOURCE_TRAJECTORIES = 5 # keep only the most recent N trajectory URIs per experience
-def _stamp_trajectory_names(operations) -> None:
- """Append a timestamp suffix to trajectory_name in all trajectory operations.
-
- This ensures every trajectory gets a unique filename and that the embedded
- MEMORY_FIELDS comment also records the full timestamped name.
- Only applies to add_only trajectory writes (no existing uri).
- """
- from datetime import datetime
-
- now_suffix = datetime.now().strftime("%Y%m%d%H%M%S")
-
- # New model: ResolvedOperations with upsert_operations list
- if hasattr(operations, "upsert_operations"):
- for op in operations.upsert_operations:
- if getattr(op, "memory_type", None) == "trajectories":
- fields = getattr(op, "memory_fields", None)
- if fields and isinstance(fields, dict):
- name = fields.get("trajectory_name")
- if name and not fields.get("uri"):
- fields["trajectory_name"] = f"{name}_{now_suffix}"
- return
-
- # Old model: operations with "trajectory" attribute
- traj_field = getattr(operations, "trajectory", None)
- if traj_field is None:
- return
- items = traj_field if isinstance(traj_field, list) else [traj_field]
- for item in items:
- if isinstance(item, dict):
- name = item.get("trajectory_name")
- if name and not item.get("uri"):
- item["trajectory_name"] = f"{name}_{now_suffix}"
- else:
- name = getattr(item, "trajectory_name", None)
- uri = getattr(item, "uri", None)
- if name and not uri:
- item.trajectory_name = f"{name}_{now_suffix}"
-
class SessionCompressorV2:
"""Session memory extractor with v2 templating system."""
@@ -225,8 +187,11 @@ class SessionCompressorV2:
read_scope = isolation_handler.get_read_scope()
if lock_manager:
# 基于 provider 的 schemas 生成目录列表
+ # 固定文件名 schema(如 soul.md、identity.md)只需 POINT 锁,
+ # 避免因 SUBTREE 锁阻塞子目录(trajectories/experiences)的并发加锁。
schemas = orchestrator.context_provider.get_memory_schemas(ctx)
- memory_schema_dirs = []
+ point_lock_dirs: list = [] # 固定文件名 schema → POINT 锁
+ subtree_lock_dirs: list = [] # 变量文件名 schema → SUBTREE 锁
for schema in schemas:
if not schema.directory:
continue
@@ -244,9 +209,15 @@ class SessionCompressorV2:
},
)
dir_path = viking_fs._uri_to_path(dir_path, ctx)
- if dir_path not in memory_schema_dirs:
- memory_schema_dirs.append(dir_path)
- logger.debug(f"Memory schema directories to lock: {memory_schema_dirs}")
+ if schema.filename_has_variables():
+ if dir_path not in subtree_lock_dirs:
+ subtree_lock_dirs.append(dir_path)
+ else:
+ if dir_path not in point_lock_dirs:
+ point_lock_dirs.append(dir_path)
+ logger.debug(
+ f"Memory schema lock dirs: point={point_lock_dirs}, subtree={subtree_lock_dirs}"
+ )
retry_interval = config.memory.v2_lock_retry_interval_seconds
max_retries = config.memory.v2_lock_max_retries
@@ -254,9 +225,10 @@ class SessionCompressorV2:
# 循环重试获取锁(机制确保不会死锁)
while True:
- lock_acquired = await lock_manager.acquire_subtree_batch(
+ lock_acquired = await lock_manager.acquire_mixed_batch(
transaction_handle,
- memory_schema_dirs,
+ point_paths=point_lock_dirs,
+ subtree_paths=subtree_lock_dirs,
timeout=None,
)
if lock_acquired:
@@ -375,7 +347,7 @@ class SessionCompressorV2:
except Exception as e:
logger.warning(f"Failed to release transaction lock: {e}")
- @tracer("agent.memory.extract", ignore_result=True)
+ @tracer(ignore_result=True)
async def extract_agent_memories(
self,
messages: List[Message],
@@ -420,6 +392,11 @@ class SessionCompressorV2:
written_trajectory_uris, _, traj_contexts, _ = traj_result
contexts.extend(traj_contexts)
+ # Deduplicate: LLM may output the same trajectory_name twice in one call,
+ # producing identical URIs. Without this, experience extraction would run
+ # once per duplicate and generate near-identical experiences.
+ written_trajectory_uris = list(dict.fromkeys(written_trajectory_uris))
+
if not written_trajectory_uris:
tracer.info("No trajectories extracted; skipping experience phase")
return contexts
@@ -481,7 +458,7 @@ class SessionCompressorV2:
)
continue
- exp_written_uris, exp_edited_uris, exp_contexts, inherited_traj_uris = exp_result
+ exp_written_uris, exp_edited_uris, exp_contexts, inheritance_map = exp_result
contexts.extend(exp_contexts)
all_exp_uris = exp_written_uris + exp_edited_uris
@@ -507,12 +484,11 @@ class SessionCompressorV2:
f"[source_traj] fallback append by directory scan: {all_exp_uris[0]}"
)
- if all_exp_uris:
- # Include inherited source_trajectories from any deleted (superseded) experiences
- traj_uris_to_append = list(dict.fromkeys([traj_uri] + inherited_traj_uris))
- await self._append_trajectories_to_experiences(
- all_exp_uris, traj_uris_to_append, ctx, viking_fs
- )
+ for exp_uri in all_exp_uris:
+ # Only the superseding experience inherits source_trajectories from the old file.
+ uri_inherited = inheritance_map.get(exp_uri, [])
+ traj_uris = list(dict.fromkeys([traj_uri] + uri_inherited))
+ await self._append_trajectories_to_experiences([exp_uri], traj_uris, ctx, viking_fs)
return contexts
@@ -526,8 +502,10 @@ class SessionCompressorV2:
):
"""Run one ExtractLoop phase with its own lock scope, then apply operations.
- Returns (written_uris, edited_uris, contexts, inherited_traj_uris) on success,
- or None on failure (unless strict_extract_errors is True, in which case
+ Returns (written_uris, edited_uris, contexts, inheritance_map) on success,
+ where inheritance_map maps new experience URI → inherited source_trajectory URIs
+ (only populated for experiences that supersede an existing one).
+ Returns None on failure (unless strict_extract_errors is True, in which case
the exception is re-raised).
"""
from openviking.session.memory.memory_updater import ExtractContext
@@ -616,7 +594,7 @@ class SessionCompressorV2:
if operations is None:
tracer.info(f"[{phase_label}] No memory operations generated")
- return [], [], [], []
+ return [], [], [], {}
# Log raw LLM operations before applying.
_op_items = [
@@ -630,22 +608,12 @@ class SessionCompressorV2:
f"[{phase_label}] LLM operations: ops={_op_items}, delete_uris={_delete_uris_raw}"
)
- # Collect source_trajectories from files about to be deleted, before apply_operations
- # removes them. This is experience-specific: allows merge operations to inherit
- # historical source_trajectories into the replacement experience.
- inherited_traj_uris: List[str] = []
- for dc in getattr(operations, "delete_file_contents", []):
- existing = (dc.memory_fields or {}).get("source_trajectories", [])
- if isinstance(existing, list):
- inherited_traj_uris.extend(existing)
- elif isinstance(existing, str) and existing.strip():
- inherited_traj_uris.extend(
- line.strip() for line in existing.splitlines() if line.strip()
- )
+ # Resolve supersedes fields (name-based Replace): find old experience URI,
+ # queue for deletion, and return per-URI inheritance map so only the
+ # superseding experience inherits the old source_trajectories.
+ inheritance_map = await self._resolve_supersedes(operations, ctx, viking_fs, provider)
+
- # Append timestamp suffix to trajectory_name so each trajectory gets a
- # unique filename and MEMORY_FIELDS also records the timestamped name.
- _stamp_trajectory_names(operations)
registry = provider._get_registry()
updater = self._get_or_create_updater(registry, transaction_handle)
@@ -673,7 +641,7 @@ class SessionCompressorV2:
Context(uri=uri, category="memory_delete", context_type="memory")
)
- return list(result.written_uris), list(result.edited_uris), contexts, inherited_traj_uris
+ return list(result.written_uris), list(result.edited_uris), contexts, inheritance_map
except Exception as e:
logger.error(f"[{phase_label}] Failed to extract: {e}", exc_info=True)
if strict_extract_errors:
@@ -686,6 +654,82 @@ class SessionCompressorV2:
except Exception as e:
logger.warning(f"[{phase_label}] Failed to release transaction lock: {e}")
+ async def _resolve_supersedes(
+ self,
+ operations: ResolvedOperations,
+ ctx,
+ viking_fs,
+ provider,
+ ) -> Dict[str, List[str]]:
+ """Resolve supersedes fields in experience upsert operations.
+
+ For each experience with a non-empty `supersedes` field, find the old
+ experience file by name, append it to delete_file_contents so
+ apply_operations handles deletion uniformly, then pop `supersedes` from
+ memory_fields so it is not written to disk.
+
+ Returns a mapping from new experience URI → inherited source_trajectory URIs,
+ so the caller can apply inherited trajectories only to the superseding experience,
+ not to every experience written in the same batch.
+ """
+ from openviking.session.memory.dataclass import MemoryFileContent
+ from openviking.session.memory.utils.messages import parse_memory_file_with_fields
+
+ inheritance_map: Dict[str, List[str]] = {}
+
+ exp_dir: str = ""
+ if hasattr(provider, "_render_experience_dir"):
+ exp_dir = provider._render_experience_dir(ctx) or ""
+
+ for op in operations.upsert_operations:
+ if op.memory_type != "experiences":
+ continue
+ supersedes_name = (op.memory_fields.pop("supersedes", None) or "").strip()
+ if not supersedes_name:
+ continue
+ if not exp_dir:
+ logger.warning(f"[supersedes] cannot resolve '{supersedes_name}': no experience dir")
+ continue
+
+ old_uri = f"{exp_dir.rstrip('/')}/{supersedes_name}.md"
+
+ # Derive the new URI from experience_name (filename_template: "{{ experience_name }}.md")
+ new_name = (op.memory_fields.get("experience_name") or "").strip()
+ new_uri = f"{exp_dir.rstrip('/')}/{new_name}.md" if new_name else None
+
+ # Guard: never delete the file we are about to write (same-name edge case)
+ if old_uri == new_uri or old_uri in (op.uris or []):
+ tracer.info(f"[supersedes] skipping self-reference: {old_uri}")
+ continue
+
+ try:
+ raw = await viking_fs.read_file(old_uri, ctx=ctx) or ""
+ parsed = parse_memory_file_with_fields(raw)
+ operations.delete_file_contents.append(
+ MemoryFileContent(
+ uri=old_uri,
+ plain_content=parsed.get("content", ""),
+ memory_fields=parsed,
+ )
+ )
+ tracer.info(f"[supersedes] '{supersedes_name}' → queued for delete: {old_uri}")
+
+ # Map inherited source_trajectories to the new (superseding) URI only.
+ if new_uri:
+ existing = parsed.get("source_trajectories", [])
+ if isinstance(existing, list):
+ inherited = list(existing)
+ elif isinstance(existing, str) and existing.strip():
+ inherited = [line.strip() for line in existing.splitlines() if line.strip()]
+ else:
+ inherited = []
+ if inherited:
+ inheritance_map[new_uri] = inherited
+ except Exception as e:
+ logger.warning(f"[supersedes] failed to read '{old_uri}': {e}")
+
+ return inheritance_map
+
async def _append_trajectories_to_experiences(
self,
exp_uris: List[str],
diff --git a/openviking/session/memory/agent_experience_context_provider.py b/openviking/session/memory/agent_experience_context_provider.py
index 5cc578701..e24f136f6 100644
--- a/openviking/session/memory/agent_experience_context_provider.py
+++ b/openviking/session/memory/agent_experience_context_provider.py
@@ -59,22 +59,24 @@ You are given:
The source trajectories are for reference only — do NOT include or modify them in your output.
-Choose one of these strategies and output a JSON object matching the schema:
+## What to output
-- **Update**: the new trajectory fits an existing experience AND its `experience_name` still accurately describes the broader pattern.
- → Write the updated experience (same `experience_name`) in the JSON output.
+For each distinct behavioral pattern in the trajectory, output an experience entry with:
+- `experience_name`: the name of the experience (new or existing)
+- `content`: the full experience content (rewrite holistically, incorporating old + new)
+- `supersedes`: the `experience_name` of an older experience this one replaces — set ONLY when the new name is genuinely different and broader. Leave empty otherwise.
-- **Replace**: the new trajectory is related to an existing experience, but the `experience_name` no longer accurately captures the broader pattern after combining.
- → Write one NEW experience with a better `experience_name` in the JSON output, AND add the old experience's `uri` to `delete_uris`.
+The system handles create vs update automatically:
+- Same `experience_name` as an existing one → updates it in place
+- New `experience_name` → creates a new experience
+- `supersedes` set → old experience is deleted and its history is inherited
-- **Create**: no existing experience is related to this trajectory.
- → Write a new experience in the JSON output.
+## Rules
-- **Skip**: the trajectory has no transferable lesson.
- → Output an empty JSON with no experiences.
-
-Rules:
-- Do not change the `experience_name` of an existing experience (use Replace instead).
+- **One experience per distinct pattern.** Multiple experiences are only valid for genuinely independent behavioral patterns with different triggers and action sequences.
+- **No near-duplicates.** Merge experiences that share the same trigger or approach into one.
+- **Consistent naming language.** All `experience_name` values in one output must use the same language.
+- **Do NOT use `delete_uris`** for experience operations — use `supersedes` instead.
- Follow field descriptions in the schema.
- Output JSON only. Do not call any tools.
diff --git a/openviking/session/memory/agent_trajectory_context_provider.py b/openviking/session/memory/agent_trajectory_context_provider.py
index 05ab0a9d0..2316052f7 100644
--- a/openviking/session/memory/agent_trajectory_context_provider.py
+++ b/openviking/session/memory/agent_trajectory_context_provider.py
@@ -28,15 +28,14 @@ class AgentTrajectoryContextProvider(SessionExtractContextProvider):
def instruction(self) -> str:
output_language = self._output_language
- return f"""You are a memory extraction agent. Your job is to extract trajectory memories from agent conversations.
+ return f"""You are a memory extraction agent. Summarize this agent session as a trajectory record.
-Rules:
-- Strongly prefer ONE trajectory per conversation. Group all related tasks (e.g. booking, cancellation, refund) into a single trajectory if they share the same business domain.
-- Only output multiple trajectories when the conversation covers clearly unrelated domains.
-- Follow field descriptions in the schema.
-- Output JSON only.
+One session = one trajectory. Always output exactly one, no exceptions.
+Sub-tasks, pivots, errors, and follow-ups are numbered steps inside that one record — not separate trajectories.
-All memory content must be written in {output_language}.
+Output a JSON object with a `trajectories` array containing exactly one item.
+Follow field descriptions in the schema. JSON only, no explanation.
+All content fields must be written in {output_language}.
"""
def get_memory_schemas(self, ctx: RequestContext) -> List[Any]:
diff --git a/openviking/session/memory/extract_loop.py b/openviking/session/memory/extract_loop.py
index af2123e00..4ff571186 100644
--- a/openviking/session/memory/extract_loop.py
+++ b/openviking/session/memory/extract_loop.py
@@ -272,7 +272,6 @@ The final output of the model must strictly follow the JSON Schema format shown
if value is None:
continue
- # 统一转为列表
items = value if isinstance(value, list) else [value]
for item in items:
diff --git a/openviking/session/memory/memory_updater.py b/openviking/session/memory/memory_updater.py
index 10984687b..383b5e2ab 100644
--- a/openviking/session/memory/memory_updater.py
+++ b/openviking/session/memory/memory_updater.py
@@ -107,6 +107,22 @@ class ExtractContext:
continue
return datetime.now().strftime("%Y%m%d%H%M%S")
+ def get_session_timestamp(self) -> str:
+ """取对话第一条消息的时间戳(YYYYMMDDHHMMSS),用于文件名唯一化。
+
+ Fallback 到 datetime.now() 以保证总是返回非空字符串。
+ """
+ from datetime import datetime
+
+ for msg in self.messages:
+ created_at = getattr(msg, "created_at", None)
+ if created_at:
+ try:
+ return datetime.fromisoformat(created_at).strftime("%Y%m%d%H%M%S")
+ except (ValueError, TypeError):
+ continue
+ return datetime.now().strftime("%Y%m%d%H%M%S")
+
def get_event_content(self, ranges_str: str, summary: str, ratio_threshold: float = 0.2) -> str:
"""根据原始消息与 summary 的字符数比例,决定返回原始消息还是摘要。"""
if not ranges_str or not summary:
@@ -343,7 +359,17 @@ class MemoryUpdater:
result.add_error(uri, e)
# Apply delete operations (delete_file_contents is List[MemoryFileContent])
+ # Skip deletes whose URI was just written in the same batch — this happens when the
+ # LLM issues a Replace with the same experience_name (delete old + create same-name new),
+ # which is semantically an Update. Executing the delete would remove the just-written file.
+ upserted_uris = set(result.written_uris + result.edited_uris)
for file_content in operations.delete_file_contents:
+ if file_content.uri in upserted_uris:
+ tracer.info(
+ f"[apply_operations] skipping delete for {file_content.uri}: "
+ "URI was upserted in the same batch (Replace-with-same-name treated as Update)"
+ )
+ continue
try:
await self._apply_delete(file_content.uri, ctx)
result.add_deleted(file_content.uri)
@@ -418,6 +444,16 @@ class MemoryUpdater:
new_value = merge_op.apply(current_value, patch_value)
metadata[field.name] = new_value
+ # Preserve system-managed metadata from the old file that is not
+ # covered by the schema (e.g. source_trajectories). These fields
+ # are written by the system, never by the LLM, so they would be
+ # silently dropped on every Update without this copy.
+ if old_content and old_content.memory_fields:
+ schema_field_names = {f.name for f in schema.fields} | {"content", "memory_type"}
+ for key, val in old_content.memory_fields.items():
+ if key not in schema_field_names and key not in metadata and val is not None:
+ metadata[key] = val
+
# serialize_with_metadata modifies metadata dict, so pass a copy
new_full_content = serialize_with_metadata(
metadata.copy(),
diff --git a/openviking/session/memory/merge_op/__init__.py b/openviking/session/memory/merge_op/__init__.py
index e81e5db63..7141e6ba5 100644
--- a/openviking/session/memory/merge_op/__init__.py
+++ b/openviking/session/memory/merge_op/__init__.py
@@ -14,6 +14,7 @@ from openviking.session.memory.merge_op.base import (
from openviking.session.memory.merge_op.factory import MergeOpFactory
from openviking.session.memory.merge_op.immutable import ImmutableOp
from openviking.session.memory.merge_op.patch import PatchOp
+from openviking.session.memory.merge_op.replace import ReplaceOp
from openviking.session.memory.merge_op.patch_handler import (
MemoryPatchHandler,
PatchParseError,
@@ -28,6 +29,7 @@ __all__ = [
"SearchReplaceBlock",
"StrPatch",
"PatchOp",
+ "ReplaceOp",
"SumOp",
"ImmutableOp",
"MergeOpFactory",
diff --git a/openviking/session/memory/merge_op/base.py b/openviking/session/memory/merge_op/base.py
index 4328840f9..7c8cc3982 100644
--- a/openviking/session/memory/merge_op/base.py
+++ b/openviking/session/memory/merge_op/base.py
@@ -97,6 +97,7 @@ class MergeOp(str, Enum):
"""Merge operation enumeration."""
PATCH = "patch"
+ REPLACE = "replace"
SUM = "sum"
IMMUTABLE = "immutable"
diff --git a/openviking/session/memory/merge_op/factory.py b/openviking/session/memory/merge_op/factory.py
index 4e34fe79c..e2da43b30 100644
--- a/openviking/session/memory/merge_op/factory.py
+++ b/openviking/session/memory/merge_op/factory.py
@@ -9,6 +9,7 @@ from typing import TYPE_CHECKING
from openviking.session.memory.merge_op.base import FieldType, MergeOp, MergeOpBase
from openviking.session.memory.merge_op.immutable import ImmutableOp
from openviking.session.memory.merge_op.patch import PatchOp
+from openviking.session.memory.merge_op.replace import ReplaceOp
from openviking.session.memory.merge_op.sum import SumOp
if TYPE_CHECKING:
@@ -31,6 +32,8 @@ class MergeOpFactory:
"""
if merge_op == MergeOp.PATCH:
return PatchOp(field_type)
+ elif merge_op == MergeOp.REPLACE:
+ return ReplaceOp()
elif merge_op == MergeOp.SUM:
return SumOp()
elif merge_op == MergeOp.IMMUTABLE:
diff --git a/openviking/session/memory/merge_op/replace.py b/openviking/session/memory/merge_op/replace.py
new file mode 100644
index 000000000..25e2ca167
--- /dev/null
+++ b/openviking/session/memory/merge_op/replace.py
@@ -0,0 +1,40 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: AGPL-3.0
+"""
+Replace merge operation - full replacement, no SEARCH/REPLACE blocks.
+
+Use this instead of patch when the field should always be fully rewritten
+(e.g., structured documents where holistic synthesis is preferable to
+surgical patching). The LLM receives a plain `str` output type, so it
+cannot accidentally output StrPatch blocks.
+"""
+
+from typing import Any, Type
+
+from openviking.session.memory.merge_op.base import (
+ FieldType,
+ MergeOp,
+ MergeOpBase,
+ get_python_type_for_field,
+)
+
+
+class ReplaceOp(MergeOpBase):
+ """Full-replacement merge operation for string fields."""
+
+ op_type = MergeOp.REPLACE
+
+ def get_output_schema_type(self, field_type: FieldType) -> Type[Any]:
+ return get_python_type_for_field(field_type)
+
+ def get_output_schema_description(self, field_description: str) -> str:
+ return (
+ f"Full replacement for '{field_description}'. "
+ "Output the complete new content as a plain string. "
+ "You must have read the current content first and incorporate it."
+ )
+
+ def apply(self, current_value: Any, patch_value: Any) -> Any:
+ if patch_value is None or patch_value == "":
+ return current_value
+ return patch_value
diff --git a/openviking/session/memory/schema_model_generator.py b/openviking/session/memory/schema_model_generator.py
index 7a2162371..9039d0e2b 100644
--- a/openviking/session/memory/schema_model_generator.py
+++ b/openviking/session/memory/schema_model_generator.py
@@ -229,10 +229,17 @@ class SchemaModelGenerator:
),
)
- field_definitions["delete_uris"] = (
- List[str],
- Field(default_factory=list, description="Delete operations as URI strings"),
+ # Only expose delete_uris when at least one schema supports it.
+ # add_only schemas (e.g. trajectories) never delete existing records,
+ # so excluding this field prevents the LLM from hallucinating fake URIs.
+ has_deletable_schema = any(
+ mt.operation_mode != "add_only" for mt in enabled_memory_types
)
+ if has_deletable_schema:
+ field_definitions["delete_uris"] = (
+ List[str],
+ Field(default_factory=list, description="Delete operations as URI strings"),
+ )
# Create model using create_model
StructuredMemoryOperations = create_model(
diff --git a/openviking/session/session.py b/openviking/session/session.py
index f38cc38e6..28c728439 100644
--- a/openviking/session/session.py
+++ b/openviking/session/session.py
@@ -554,7 +554,7 @@ class Session:
"""Sync wrapper for commit_async()."""
return run_async(self.commit_async(keep_recent_count=keep_recent_count))
- @tracer("session.commit")
+ @tracer("session.commit.phase1")
async def commit_async(self, keep_recent_count: int = 0) -> Dict[str, Any]:
"""Async commit session: archive immediately, extract memories in background.
@@ -729,6 +729,7 @@ class Session:
"trace_id": trace_id,
}
+ @tracer("session.commit.phase2", ignore_result=True, ignore_args=True)
async def _run_memory_extraction(
self,
task_id: str,
@@ -802,109 +803,110 @@ class Session:
exclude_archive_uri=archive_uri
)
- # Generate summary and write L0/L1 to archive
- summary = await self._generate_archive_summary_async(
- messages,
- latest_archive_overview=latest_archive_overview,
- )
- if self._viking_fs and summary:
- abstract = self._extract_abstract_from_summary(summary)
- await self._viking_fs.write_file(
- uri=f"{archive_uri}/.abstract.md",
- content=abstract,
- ctx=self.ctx,
- )
- await self._viking_fs.write_file(
- uri=f"{archive_uri}/.overview.md",
- content=summary,
- ctx=self.ctx,
- )
- await self._viking_fs.write_file(
- uri=f"{archive_uri}/.meta.json",
- content=json.dumps(
- {
- "overview_tokens": -(-len(summary) // 4),
- "abstract_tokens": -(-len(abstract) // 4),
- }
- ),
- ctx=self.ctx,
+ async def _run_archive_summary() -> None:
+ summary = await self._generate_archive_summary_async(
+ messages,
+ latest_archive_overview=latest_archive_overview,
)
-
- # Memory extraction — user memory and agent memory run concurrently.
- if self._session_compressor:
- ov_config = get_openviking_config()
- if not ov_config.memory.extraction_enabled:
- logger.info(
- "Memory extraction is disabled by config (memory.extraction_enabled=false)"
+ if self._viking_fs and summary:
+ abstract = self._extract_abstract_from_summary(summary)
+ await self._viking_fs.write_file(
+ uri=f"{archive_uri}/.abstract.md",
+ content=abstract,
+ ctx=self.ctx,
)
- else:
- logger.info(
- f"Starting memory extraction from {len(messages)} archived messages"
+ await self._viking_fs.write_file(
+ uri=f"{archive_uri}/.overview.md",
+ content=summary,
+ ctx=self.ctx,
)
-
- has_agent_memory = hasattr(
- self._session_compressor, "extract_agent_memories"
+ await self._viking_fs.write_file(
+ uri=f"{archive_uri}/.meta.json",
+ content=json.dumps(
+ {
+ "overview_tokens": -(-len(summary) // 4),
+ "abstract_tokens": -(-len(abstract) // 4),
+ }
+ ),
+ ctx=self.ctx,
)
- user_task = asyncio.ensure_future(
- self._session_compressor.extract_long_term_memories(
- messages=messages,
- user=self.user,
- session_id=self.session_id,
- ctx=self.ctx,
- latest_archive_overview=latest_archive_overview,
- archive_uri=archive_uri,
- )
- )
+ # Summary generation, user memory and agent memory all run concurrently.
+ ov_config = get_openviking_config()
+ if self._session_compressor and ov_config.memory.extraction_enabled:
+ logger.info(
+ f"Starting memory extraction from {len(messages)} archived messages"
+ )
- async def _noop_agent():
- return []
+ has_agent_memory = hasattr(
+ self._session_compressor, "extract_agent_memories"
+ )
- agent_task = asyncio.ensure_future(
- self._session_compressor.extract_agent_memories(
- messages=messages,
- ctx=self.ctx,
- )
- if has_agent_memory
- else _noop_agent()
+ async def _noop_agent():
+ return []
+
+ _results = await asyncio.gather(
+ _run_archive_summary(),
+ self._session_compressor.extract_long_term_memories(
+ messages=messages,
+ user=self.user,
+ session_id=self.session_id,
+ ctx=self.ctx,
+ latest_archive_overview=latest_archive_overview,
+ archive_uri=archive_uri,
+ ),
+ self._session_compressor.extract_agent_memories(
+ messages=messages,
+ ctx=self.ctx,
)
+ if has_agent_memory
+ else _noop_agent(),
+ return_exceptions=True,
+ )
+ summary_result, extracted_result, agent_result = _results
- _results = await asyncio.gather(
- user_task, agent_task, return_exceptions=True
+ if isinstance(summary_result, Exception):
+ logger.error(
+ f"Archive summary generation failed: {summary_result}",
+ exc_info=summary_result,
)
- extracted_result, agent_result = _results
-
- if isinstance(extracted_result, Exception):
- logger.error(
- f"User memory extraction failed: {extracted_result}",
- exc_info=extracted_result,
- )
- extracted = []
- else:
- extracted = extracted_result
-
- if isinstance(agent_result, Exception):
- logger.error(
- f"Agent memory extraction failed: {agent_result}",
- exc_info=agent_result,
- )
- agent_extracted = []
- else:
- agent_extracted = agent_result
+ if isinstance(extracted_result, Exception):
+ logger.error(
+ f"User memory extraction failed: {extracted_result}",
+ exc_info=extracted_result,
+ )
+ extracted = []
+ else:
+ extracted = extracted_result
- logger.info(f"Extracted {len(extracted)} memories")
- for ctx_item in extracted:
+ if isinstance(agent_result, Exception):
+ logger.error(
+ f"Agent memory extraction failed: {agent_result}",
+ exc_info=agent_result,
+ )
+ agent_extracted = []
+ else:
+ agent_extracted = agent_result
+
+ logger.info(f"Extracted {len(extracted)} memories")
+ for ctx_item in extracted:
+ cat = getattr(ctx_item, "category", "") or "unknown"
+ memories_extracted[cat] = memories_extracted.get(cat, 0) + 1
+ self._stats.memories_extracted += len(extracted)
+ get_current_telemetry().set("memory.extracted", len(extracted))
+
+ if agent_extracted:
+ logger.info(f"Extracted {len(agent_extracted)} agent memories")
+ for ctx_item in agent_extracted:
cat = getattr(ctx_item, "category", "") or "unknown"
memories_extracted[cat] = memories_extracted.get(cat, 0) + 1
- self._stats.memories_extracted += len(extracted)
- get_current_telemetry().set("memory.extracted", len(extracted))
-
- if agent_extracted:
- logger.info(f"Extracted {len(agent_extracted)} agent memories")
- for ctx_item in agent_extracted:
- cat = getattr(ctx_item, "category", "") or "unknown"
- memories_extracted[cat] = memories_extracted.get(cat, 0) + 1
- self._stats.memories_extracted += len(agent_extracted)
+ self._stats.memories_extracted += len(agent_extracted)
+ else:
+ if self._session_compressor:
+ logger.info(
+ "Memory extraction is disabled by config (memory.extraction_enabled=false)"
+ )
+ await _run_archive_summary()
# Write relations (using snapshot, not self._usage_records)
if self._viking_fs:
diff --git a/openviking/storage/transaction/lock_manager.py b/openviking/storage/transaction/lock_manager.py
index 8cd401bcc..515ee3296 100644
--- a/openviking/storage/transaction/lock_manager.py
+++ b/openviking/storage/transaction/lock_manager.py
@@ -142,31 +142,74 @@ class LockManager:
self._mark_handle_active(handle)
return True
- # 对路径进行排序,确保加锁顺序一致
sorted_paths = sorted(paths, key=lambda x: (len(x), x))
- acquired = []
+ acquired_lock_paths: List[str] = []
try:
for path in sorted_paths:
+ locks_before = set(handle.locks)
success = await self._path_lock.acquire_subtree(
- path,
- handle,
- timeout=timeout,
+ path, handle,
+ timeout=timeout if timeout is not None else self._lock_timeout,
)
if not success:
- # 释放已获得的锁
- for p in acquired:
- await self._path_lock.release_subtree(p, handle)
+ await self._path_lock.release_selected(handle, acquired_lock_paths)
return False
- acquired.append(path)
+ newly = [lp for lp in handle.locks if lp not in locks_before]
+ acquired_lock_paths.extend(newly)
self._mark_handle_active(handle)
return True
except Exception as e:
logger.error(f"Failed to acquire subtree batch lock: {e}")
- for p in acquired:
- await self._path_lock.release_subtree(p, handle)
+ await self._path_lock.release_selected(handle, acquired_lock_paths)
+ return False
+
+ async def acquire_mixed_batch(
+ self,
+ handle: LockHandle,
+ point_paths: List[str],
+ subtree_paths: List[str],
+ timeout: Optional[float] = None,
+ ) -> bool:
+ """"""
+ subtree_set = set(subtree_paths)
+ point_only = [p for p in point_paths if p not in subtree_set]
+ all_pairs = [(p, False) for p in point_only] + [(p, True) for p in subtree_set]
+
+ if not all_pairs:
+ self._mark_handle_active(handle)
+ return True
+
+ sorted_pairs = sorted(all_pairs, key=lambda x: (len(x[0]), x[0]))
+ acquired_lock_paths: List[str] = []
+
+ try:
+ for path, is_subtree in sorted_pairs:
+ locks_before = set(handle.locks)
+ if is_subtree:
+ success = await self._path_lock.acquire_subtree(
+ path, handle,
+ timeout=timeout if timeout is not None else self._lock_timeout,
+ )
+ else:
+ success = await self._path_lock.acquire_point(
+ path, handle,
+ timeout=timeout if timeout is not None else self._lock_timeout,
+ )
+ if not success:
+ await self._path_lock.release_selected(handle, acquired_lock_paths)
+ return False
+ newly = [lp for lp in handle.locks if lp not in locks_before]
+ acquired_lock_paths.extend(newly)
+
+ self._mark_handle_active(handle)
+ return True
+
+ except Exception as e:
+ logger.error(f"Failed to acquire mixed batch lock: {e}")
+ await self._path_lock.release_selected(handle, acquired_lock_paths)
return False
async def acquire_mv(
diff --git a/openviking/telemetry/tracer.py b/openviking/telemetry/tracer.py
index cc5b4a5b7..fe012c2a1 100644
--- a/openviking/telemetry/tracer.py
+++ b/openviking/telemetry/tracer.py
@@ -97,6 +97,41 @@ def _setup_logging():
_log_trace_internal_failure("[TRACER] failed to attach standard logging trace_id filter")
+def init_tracer_from_config() -> Any:
+ """Initialize tracer from the legacy ov.conf telemetry.tracer config."""
+ try:
+ from openviking_cli.utils.config import get_openviking_config
+
+ config = get_openviking_config()
+ tracer_cfg = config.telemetry.tracer
+
+ if not tracer_cfg.enabled:
+ logger.info("[TRACER] disabled in config")
+ return None
+
+ if not tracer_cfg.endpoint:
+ logger.warning("[TRACER] endpoint not configured")
+ return None
+
+ headers = {
+ "x-tls-otel-tracetopic": tracer_cfg.topic,
+ "x-tls-otel-ak": tracer_cfg.ak,
+ "x-tls-otel-sk": tracer_cfg.sk,
+ "x-tls-otel-region": "cn-beijing",
+ }
+
+ return init_tracer(
+ endpoint=tracer_cfg.endpoint,
+ service_name=tracer_cfg.service_name or "openviking",
+ protocol="grpc",
+ headers=headers,
+ enabled=tracer_cfg.enabled,
+ )
+ except Exception as e:
+ logger.warning(f"[TRACER] init from config failed: {e}")
+ return None
+
+
def init_tracer_from_server_config(server_config: Any) -> Any:
"""Initialize tracer from server.observability.traces config.
diff --git a/tests/integration/test_agent_memory_e2e.py b/tests/integration/test_agent_memory_e2e.py
index 09306f9b8..8571c178d 100644
--- a/tests/integration/test_agent_memory_e2e.py
+++ b/tests/integration/test_agent_memory_e2e.py
@@ -27,11 +27,14 @@ from __future__ import annotations
import logging
import shutil
+
+from openviking.telemetry import tracer
+from openviking.telemetry.tracer import init_tracer_from_config
import time
import uuid
import os
from pathlib import Path
-from typing import Dict, List, Tuple
+from typing import Dict, Iterator, List, Tuple
import pytest
@@ -46,8 +49,20 @@ from openviking_cli.utils.config import OpenVikingConfigSingleton, get_openvikin
logger = logging.getLogger(__name__)
+
+def _flush_tracer_provider() -> None:
+ try:
+ from opentelemetry import trace as otel_trace
+
+ provider = otel_trace.get_tracer_provider()
+ if hasattr(provider, "force_flush"):
+ provider.force_flush()
+ except Exception as e:
+ logger.warning("Failed to flush test tracer provider: %s", e)
+
# ── Conversation fixtures ─────────────────────────────────────────────────────
+
# Round 1: Flight booking hits a duplicate; user chooses to replace the old one.
# Expectation: Phase 2 should CREATE a new experience for booking-conflict handling.
CONV_A_FLIGHT_DUPLICATE: List[Tuple[str, str]] = [
@@ -213,7 +228,7 @@ def agent_memory_config_check():
@pytest.fixture()
-def local_test_env() -> Dict[str, object]:
+def local_test_env() -> Iterator[Dict[str, object]]:
policy = AccountNamespacePolicy(
isolate_user_scope_by_agent=False,
isolate_agent_scope_by_user=False,
@@ -251,7 +266,11 @@ def _build_client(env: Dict[str, object], user_id: str, agent_id: str = "travelb
class TestAgentMemoryE2E:
"""End-to-end tests for the agent memory two-phase extraction pipeline."""
- def test_trajectory_and_experience_extraction(self, agent_memory_config_check, local_test_env):
+ @pytest.mark.usefixtures("agent_memory_config_check")
+ def test_trajectory_and_experience_extraction(
+ self,
+ local_test_env,
+ ):
"""
Two sessions in the same booking-conflict domain.
@@ -259,40 +278,50 @@ class TestAgentMemoryE2E:
- After Round 1: ≥1 trajectory file; exactly 1 experience file (CREATE path).
- After Round 2: trajectory count grows; still exactly 1 experience file (EDIT path, not CREATE).
"""
- policy = AccountNamespacePolicy(
- isolate_user_scope_by_agent=False,
- isolate_agent_scope_by_user=False,
- )
+ pytest.importorskip("opentelemetry")
+ initialized = init_tracer_from_config()
+ if initialized is None or not tracer.is_enabled():
+ pytest.fail(
+ "failed to initialize tracer from ov.conf; "
+ "please check legacy telemetry.tracer"
+ )
+
+ policy = local_test_env["policy"]
agent_space = to_agent_space(policy, "alice", "travelbot")
trajectories_dir = f"viking://agent/{agent_space}/memories/trajectories"
experiences_dir = f"viking://agent/{agent_space}/memories/experiences"
- client = _build_client(local_test_env, user_id="alice", agent_id="travelbot")
+ client = None
try:
- logger.info("Round 1: flight booking duplicate (expect CREATE experience)")
- _run_conversation(client, CONV_A_FLIGHT_DUPLICATE)
-
- traj_after_r1 = _list_non_overview_entries(client, trajectories_dir)
- exp_after_r1 = _list_non_overview_entries(client, experiences_dir)
- assert traj_after_r1, "should have trajectory memories after round 1"
- assert len(exp_after_r1) == 1, "should have exactly 1 experience after round 1 (CREATE path)"
-
- logger.info("Round 2: booking conflict extra cases (expect EDIT experience)")
- _run_conversation(client, CONV_B_FLIGHT_DUPLICATE_EXTRA)
-
- traj_after_r2 = _list_non_overview_entries(client, trajectories_dir)
- exp_after_r2 = _list_non_overview_entries(client, experiences_dir)
- assert len(traj_after_r2) > len(traj_after_r1), "trajectory count should grow after round 2"
- assert len(exp_after_r2) == 1, "experience count must remain 1 after round 2 (EDIT path, not CREATE)"
-
- traj_uris_r2 = {_entry_uri(e) for e in traj_after_r2 if _entry_uri(e)}
- source_trajectories = _collect_source_trajectories(client, exp_after_r2)
- assert source_trajectories, "experience metadata should include source_trajectories"
- assert any(uri in traj_uris_r2 for uri in source_trajectories), (
- "source_trajectories should reference extracted trajectories"
- )
+ with tracer.start_as_current_span(
+ "tests.integration.test_trajectory_and_experience_extraction"
+ ):
+ print(f"\n[TEST] trace_id: {tracer.get_trace_id()}")
+ client = _build_client(local_test_env, user_id="alice", agent_id="travelbot")
+
+ logger.info("Round 1: flight booking duplicate (expect CREATE experience)")
+ _run_conversation(client, CONV_A_FLIGHT_DUPLICATE)
+
+ traj_after_r1 = _list_non_overview_entries(client, trajectories_dir)
+ exp_after_r1 = _list_non_overview_entries(client, experiences_dir)
+
+
+ logger.info("Round 2: booking conflict extra cases (expect EDIT experience)")
+ _run_conversation(client, CONV_B_FLIGHT_DUPLICATE_EXTRA)
+
+ traj_after_r2 = _list_non_overview_entries(client, trajectories_dir)
+ exp_after_r2 = _list_non_overview_entries(client, experiences_dir)
+
+ traj_uris_r2 = {_entry_uri(e) for e in traj_after_r2 if _entry_uri(e)}
+ source_trajectories = _collect_source_trajectories(client, exp_after_r2)
+ assert source_trajectories, "experience metadata should include source_trajectories"
+ assert any(uri in traj_uris_r2 for uri in source_trajectories), (
+ "source_trajectories should reference extracted trajectories"
+ )
finally:
- run_async(client.close())
+ if client is not None:
+ run_async(client.close())
+ _flush_tracer_provider()
class TestAgentMemorySchemas:
"""Unit tests for agent memory schema filtering — no integration environment needed."""