Skip to content

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

feat(memory): agent-scope two-phase trajectory/experience memory pipeline (#1880)

yangxinxin-75de357d7cd7c
diff --git a/openviking/client/local.py b/openviking/client/local.py
index 51e733c4a..f6d9db8c2 100644
--- a/openviking/client/local.py
+++ b/openviking/client/local.py
@@ -56,15 +56,17 @@ class LocalClient(BaseClient):
def __init__(
self,
path: Optional[str] = None,
+ user: Optional[UserIdentifier] = None,
):
"""Initialize LocalClient.
Args:
path: Local storage path (overrides ov.conf storage path)
+ user: Explicit user/account/agent identity for embedded mode
"""
self._service = OpenVikingService(
path=path,
- user=UserIdentifier.the_default_user(),
+ user=user or UserIdentifier.the_default_user(),
)
self._user = self._service.user
self._ctx = RequestContext(user=self._user, role=Role.USER)
diff --git a/openviking/core/directories.py b/openviking/core/directories.py
index 34d0ae496..ae97d7de5 100644
--- a/openviking/core/directories.py
+++ b/openviking/core/directories.py
@@ -94,22 +94,21 @@ PRESET_DIRECTORIES: Dict[str, DirectoryDefinition] = {
children=[
DirectoryDefinition(
path="memories",
- abstract="Agent's long-term memory storage. Contains cases and patterns, managed hierarchically by type.",
+ abstract="Agent's long-term memory storage. Contains trajectories and experiences, managed hierarchically by type.",
overview="Use this directory to access Agent's learning memories. Contains two main categories: "
- "1) cases-specific cases, 2) patterns-reusable patterns.",
+ "1) trajectories-task execution records, 2) experiences-generalized lessons from trajectories.",
children=[
DirectoryDefinition(
- path="cases",
- abstract="Agent's case records. Stores specific problems and solutions, new problems and resolution processes encountered in each interaction.",
- overview="Access cases when encountering similar problems, reference historical solutions. "
- "Cases are records of specific conversations, each independent and not updated.",
+ path="trajectories",
+ abstract="Agent's execution trajectory records. Stores end-to-end task execution traces from each interaction, each trajectory is independent and not updated.",
+ overview="Access when reviewing how the agent handled past tasks or diagnosing execution history. "
+ "Trajectories are records of specific task executions, each independent and not updated once created.",
),
DirectoryDefinition(
- path="patterns",
- abstract="Agent's effective patterns. Stores reusable processes and best practices distilled from multiple interactions, "
- "validated general solutions.",
- overview="Access patterns when executing tasks requiring strategy selection or process determination. "
- "Patterns are highly distilled experiences, each independent and not updated; create new pattern if modification needed.",
+ path="experiences",
+ abstract="Agent's generalized experience memories. Reusable insights and lessons distilled from execution trajectories, updated as new evidence accumulates.",
+ overview="Access when the agent encounters recurring situations or needs guidance from past lessons. "
+ "Experiences are distilled from trajectories and updated incrementally as more supporting evidence accumulates.",
),
],
),
diff --git a/openviking/models/vlm/backends/volcengine_vlm.py b/openviking/models/vlm/backends/volcengine_vlm.py
index f16dce7c1..8ffb11af1 100644
--- a/openviking/models/vlm/backends/volcengine_vlm.py
+++ b/openviking/models/vlm/backends/volcengine_vlm.py
@@ -49,7 +49,8 @@ class VolcEngineVLM(OpenAIVLM):
"""Build response from Chat Completions response. Returns str or VLMResponse based on has_tools."""
choice = response.choices[0]
message = choice.message
- tracer.info(f"message.content={message.content}")
+ if hasattr(message, "tool_calls") and message.tool_calls:
+ tracer.info(f"message.tool_calls={message.tool_calls}")
if has_tools:
usage = {}
if hasattr(response, "usage") and response.usage:
@@ -155,6 +156,8 @@ class VolcEngineVLM(OpenAIVLM):
# 用 tracer.info 打印请求
tracer.info(f"request: {json.dumps(kwargs_messages, ensure_ascii=False, indent=2)}")
+ if tools:
+ tracer.info(f"tools: {json.dumps([t['function']['name'] for t in tools], ensure_ascii=False)}")
client = self.get_async_client()
@@ -168,7 +171,10 @@ class VolcEngineVLM(OpenAIVLM):
result = self._build_vlm_response(response, has_tools=bool(tools))
if tools:
return result
- return self._clean_response(str(result))
+ content = self._clean_response(str(result))
+ if content:
+ tracer.info(f"message.content={content}")
+ return content
except Exception as e:
last_error = e
if attempt < self.max_retries:
diff --git a/openviking/prompts/templates/memory/cases.yaml b/openviking/prompts/templates/memory/cases.yaml
deleted file mode 100644
index 1475b6525..000000000
--- a/openviking/prompts/templates/memory/cases.yaml
+++ /dev/null
@@ -1,41 +0,0 @@
-memory_type: cases
-description: |
- Case memory - captures "what problem was encountered and how it was solved".
- Extract specific problem-solution pairs from the conversation that are worth remembering for future reference.
- Cases should be about specific problems that have clear solutions.
- Each case should include: what the problem was (symptoms, error messages, context), what the solution was (steps taken, principles used), and why it worked.
- Case names should be in "Problem → Solution" format to make them easily searchable.
-directory: "viking://agent/{{ agent_space }}/memories/cases"
-filename_template: "{{ case_name }}.md"
-enabled: false
-fields:
- - name: case_name
- type: string
- description: |
- Case name used to uniquely identify this case memory.
- Should be in "Problem → Solution" format such as "Band not recognized → Request member/album/style details", "Memory merge timeout → Split into smaller chunks", etc.
- Example: "[Problem] → [Solution]"
- merge_op: immutable
-
- - name: problem
- type: string
- description: |
- Problem description specifically detailing what problem was encountered.
- Includes: error messages, symptoms, context, and other specific details.
- Example: "User feedback that a band cannot be recognized by system."
- merge_op: patch
-
- - name: solution
- type: string
- description: |
- Solution description detailing how to solve this problem.
- Includes: solution method, steps, principles, etc.
- Example: "Request user to provide more identification details: band member names, representative album names, music style, etc. This information can improve recognition accuracy."
- merge_op: patch
-
- - name: content
- type: string
- description: |
- Complete case content including full narrative of problem and solution.
- Example: "User feedback mentioned a band that the system could not recognize. Solution is to request user to provide more identification details: band member names, representative album names, music style, etc. This information can improve recognition accuracy."
- merge_op: patch
diff --git a/openviking/prompts/templates/memory/experiences.yaml b/openviking/prompts/templates/memory/experiences.yaml
new file mode 100644
index 000000000..3792bb130
--- /dev/null
+++ b/openviking/prompts/templates/memory/experiences.yaml
@@ -0,0 +1,43 @@
+memory_type: experiences
+description: |
+ A generalizable, reusable insight distilled from agent execution — not a process record.
+ Captures a transferable pattern: what situation triggers it, what approach works, and why.
+
+directory: "viking://agent/{{ agent_space }}/memories/experiences"
+filename_template: "{{ experience_name }}.md"
+enabled: true
+operation_mode: "upsert"
+agent_only: true
+
+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".
+ merge_op: immutable
+
+ - name: content
+ type: string
+ description: |
+ Structured experience extraction in EXACTLY this 3-section format. This output will be injected directly into an autonomous agent's system prompt, so it MUST be written as strict, executable machine instructions:
+
+ ## Situation
+ <markdown bullets: Entry Conditions. Describe the generalized context, user intent, or overarching scenario that dictates when this entire rule block becomes relevant>
+
+ ## Approach
+ <markdown bullets: Active Execution Logic (The "DOs"). The step-by-step optimized path to success. Use direct imperative commands and explicit IF/THEN/ELSE statements for conditional execution. Do NOT place negative constraints or failure warnings here.>
+
+ ## Reflect
+ <markdown bullets: Hard Guardrails & Principles (The "DON'Ts"). Strict negative rules (e.g., "NEVER do Z"), boundary conditions, and failure-prevention heuristics to avoid past mistakes.>
+
+ Rules:
+ - MUTUAL EXCLUSIVITY (NO REDUNDANCY): Strictly separate active steps from constraints to eliminate redundant information. 'Approach' is ONLY for actionable, positive execution steps to advance the task. 'Reflect' is ONLY for negative boundaries, limits, and "what not to do." Do not repeat the same concept across both sections.
+ - OPTIMIZED EXECUTION PATH: You MUST critically analyze the original trajectory and aggressively trim away conversational noise, redundant retry loops, false starts, and irrelevant setup actions. Outline only the essential, efficient path in 'Approach'.
+ - MACHINE READABILITY (IMPERATIVE VOICE): Address the future agent directly using commanding imperatives (e.g., "Ask the user for X", "Call tool Y").
+ - ABSTRACTION MANDATE: Strip away specific entities, IDs, user names, or raw text from the past trajectory. Use generalized abstract descriptions so the rule applies universally.
+ - 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
diff --git a/openviking/prompts/templates/memory/patterns.yaml b/openviking/prompts/templates/memory/patterns.yaml
deleted file mode 100644
index de9f3dcf1..000000000
--- a/openviking/prompts/templates/memory/patterns.yaml
+++ /dev/null
@@ -1,32 +0,0 @@
-memory_type: patterns
-description: |
- Pattern memory - captures "under what circumstances to follow what process".
- Extract reusable workflows, processes, and methods that the agent should follow in similar future situations.
- Patterns should be about: how to approach certain types of tasks, what steps to follow, what considerations to keep in mind.
- Each pattern should include: trigger conditions (when to use this pattern), process steps (what to do), and considerations (what to watch out for).
- Pattern names should be in "Process name: Step description" format.
-directory: "viking://agent/{{ agent_space }}/memories/patterns"
-filename_template: "{{ pattern_name }}.md"
-enabled: false
-fields:
- - name: pattern_name
- type: string
- description: |
- Pattern name used to uniquely identify this pattern memory.
- Should be in "Process name: Step description" format such as "Teaching topic handling: Outline→Plan→Generate PPT", "Code refactoring: Understand→Test→Refactor→Verify", etc.
- Example: "[Pattern name]: [Step sequence]"
- merge_op: immutable
-
- - name: pattern_type
- type: string
- description: |
- Pattern type describing what type of pattern this is.
- Possible values: workflow, method, process, etc.
-
- - name: content
- type: string
- description: |
- Detailed pattern content describing "under what circumstances to follow what process".
- Includes: trigger conditions, process steps, considerations, etc.
- Example: "When user requests teaching content for a topic, use a four-step process: first list the topic outline to understand overall structure; then create a detailed learning plan; next generate PPT framework; finally refine specific content for each section. This process ensures content is systematic and complete."
- merge_op: patch
diff --git a/openviking/prompts/templates/memory/trajectories.yaml b/openviking/prompts/templates/memory/trajectories.yaml
new file mode 100644
index 000000000..8d8633490
--- /dev/null
+++ b/openviking/prompts/templates/memory/trajectories.yaml
@@ -0,0 +1,59 @@
+memory_type: trajectories
+description: |
+ A record of agent execution in one business domain within a conversation.
+
+ Extract when the agent worked through identifiable tasks involving decisions, tool calls, or multi-step actions.
+ Skip pure chitchat or simple Q&A with no execution trace.
+
+directory: "viking://agent/{{ agent_space }}/memories/trajectories"
+filename_template: "{{ trajectory_name }}.md"
+enabled: true
+operation_mode: "add_only"
+agent_only: true
+
+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".
+ merge_op: immutable
+
+ - name: outcome
+ type: string
+ description: |
+ Use exactly one of: success, failure, partial, unfinished, unknown.
+ merge_op: immutable
+
+ - name: content
+ type: string
+ description: |
+ Execution trace in EXACTLY this format:
+ - Goal: <what the user wanted to achieve — one sentence>
+ - Trajectory:
+ 1. <what the agent aimed to achieve>.
+ Actions: <summarized interactions, tools used, and summarized responses>.
+ Progress: <how this shifted the state>.
+ 2. <...>.
+ Actions: <...>.
+ Progress: <...>.
+ 3. <... continue sequentially to capture the entire execution>
+ - Result: <final outcome and any important side effects — one sentence>
+ - Fail reason: <If task succeeded, leave empty or write "None". If failed, provide a detailed analysis of why the failure occurred and suggest how the agent's approach could be improved.>
+
+ Rules for 'Trajectory' section:
+ - STANDALONE COMPLETENESS: The trajectory must be comprehensive enough that a reader can fully understand exactly how the agent performed the task, what attempts it made, and what tools it used, entirely without the raw logs.
+ - EXHAUSTIVE TRACKING: Record every logical interaction, tool use, and system response in chronological order as a numbered list.
+ - SUMMARIZE LONG TEXTS: Do NOT record exact tool responses, raw JSON payloads, or verbatim user/agent messages, especially when they are very long. You MUST use a concise, summarized version that captures the core meaning without losing any key information, constraints, or data points critical to the task.
+ - CAPTURE ALL MISTAKES: You MUST explicitly detail any errors, false attempts, wrong function calls, or agent misunderstandings. Do not gloss over failures, dead ends, or retry loops.
+ - INTENT & PROGRESS TRACKING: Every step must clearly state the current agent intention, summarize the 'Actions/Events' taken, and conclude with 'Progress' (evaluating what was achieved or blocked).
+ - TOOL TRACKING (under 'Actions'):
+ * Format (Success): "Called <tool_name(s)> -> Response: <summarized output retaining key info>."
+ * Format (Error/Mistake): "Called <tool_name(s)> -> Error/Issue: <summarized error> | Context: <why it failed or why it was the wrong call>."
+
+ General Rules:
+ - Use exactly the 4 labels (Goal, Trajectory, Result, Fail reason) in this exact order.
+ - Goal and Result are ONE sentence each.
+ - No extra headings, free paragraphs, or closing remarks.
+ merge_op: patch
diff --git a/openviking/session/compressor_v2.py b/openviking/session/compressor_v2.py
index 00ce66c1e..fc7b1da22 100644
--- a/openviking/session/compressor_v2.py
+++ b/openviking/session/compressor_v2.py
@@ -37,6 +37,47 @@ from openviking_cli.utils.config import get_openviking_config
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."""
@@ -334,6 +375,374 @@ class SessionCompressorV2:
except Exception as e:
logger.warning(f"Failed to release transaction lock: {e}")
+ @tracer("agent.memory.extract", ignore_result=True)
+ async def extract_agent_memories(
+ self,
+ messages: List[Message],
+ ctx: Optional[RequestContext] = None,
+ strict_extract_errors: bool = False,
+ ) -> List[Context]:
+ """Two-phase agent-scope memory extraction (trajectory + experience).
+
+ Phase 1: extract execution trajectories from the conversation and persist them.
+ Phase 2: for each newly written trajectory, decide whether to update an existing
+ experience, create a new one, or do nothing.
+
+ Gated by `config.memory.agent_memory_enabled`. Returns [] when disabled.
+ """
+ config = get_openviking_config()
+ if not getattr(config.memory, "agent_memory_enabled", False):
+ return []
+ if not messages or not ctx:
+ return []
+
+ from openviking.session.memory.agent_experience_context_provider import (
+ AgentExperienceContextProvider,
+ )
+ from openviking.session.memory.agent_trajectory_context_provider import (
+ AgentTrajectoryContextProvider,
+ )
+
+ contexts: List[Context] = []
+
+ # Phase 1: trajectory extraction
+ traj_provider = AgentTrajectoryContextProvider(messages=messages)
+ traj_result = await self._run_extract_phase(
+ provider=traj_provider,
+ messages=messages,
+ ctx=ctx,
+ strict_extract_errors=strict_extract_errors,
+ phase_label="trajectory",
+ )
+ if traj_result is None:
+ return []
+
+ written_trajectory_uris, _, traj_contexts, _ = traj_result
+ contexts.extend(traj_contexts)
+
+ if not written_trajectory_uris:
+ tracer.info("No trajectories extracted; skipping experience phase")
+ return contexts
+
+ # Phase 2: for each new trajectory, consolidate into experiences.
+ viking_fs = get_viking_fs()
+ for traj_uri in written_trajectory_uris:
+ try:
+ from openviking.session.memory.utils.content import deserialize_content as _deser_content
+ traj_content = _deser_content(await viking_fs.read_file(traj_uri, ctx=ctx) or "")
+ except Exception as e:
+ logger.warning(f"Failed to read new trajectory {traj_uri}: {e}")
+ continue
+
+ exp_provider = AgentExperienceContextProvider(
+ messages=messages,
+ trajectory_summary=traj_content,
+ trajectory_uri=traj_uri,
+ )
+ exp_result = await self._run_extract_phase(
+ provider=exp_provider,
+ messages=messages,
+ ctx=ctx,
+ strict_extract_errors=strict_extract_errors,
+ phase_label=f"experience({traj_uri})",
+ )
+
+ exp_dir = exp_provider._render_experience_dir(ctx)
+
+ async def _single_existing_experience_uri() -> List[str]:
+ if not exp_dir:
+ return []
+ try:
+ entries = await viking_fs.ls(exp_dir, output="original", ctx=ctx)
+ except Exception:
+ return []
+ uris = []
+ for e in entries or []:
+ uri = str(e.get("uri", "")) if isinstance(e, dict) else ""
+ name = str(e.get("name", "")) if isinstance(e, dict) else ""
+ if not uri.endswith(".md"):
+ continue
+ if name in {".overview.md", ".abstract.md"}:
+ continue
+ if uri.endswith("/.overview.md") or uri.endswith("/.abstract.md"):
+ continue
+ uris.append(uri)
+ uris = list(dict.fromkeys(uris))
+ return uris if len(uris) == 1 else []
+
+ if exp_result is None:
+ fallback_uris = await _single_existing_experience_uri()
+ if fallback_uris:
+ tracer.info(
+ f"[source_traj] phase2 failed; fallback append to sole experience: {fallback_uris[0]}"
+ )
+ await self._append_trajectories_to_experiences(
+ fallback_uris, [traj_uri], ctx, viking_fs
+ )
+ continue
+
+ exp_written_uris, exp_edited_uris, exp_contexts, inherited_traj_uris = exp_result
+ contexts.extend(exp_contexts)
+
+ all_exp_uris = exp_written_uris + exp_edited_uris
+ if not all_exp_uris:
+ candidate_uris = list(dict.fromkeys(getattr(exp_provider, "prefetched_uris", []) or []))
+ candidate_exp_uris = [
+ uri
+ for uri in candidate_uris
+ if uri.endswith(".md")
+ and not uri.endswith("/.overview.md")
+ and not uri.endswith("/.abstract.md")
+ and "/memories/experiences/" in uri
+ ]
+ if len(candidate_exp_uris) == 1:
+ all_exp_uris = candidate_exp_uris
+ tracer.info(
+ f"[source_traj] fallback append to sole candidate experience: {candidate_exp_uris[0]}"
+ )
+ else:
+ all_exp_uris = await _single_existing_experience_uri()
+ if all_exp_uris:
+ tracer.info(
+ 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
+ )
+
+ return contexts
+
+ async def _run_extract_phase(
+ self,
+ provider,
+ messages: List[Message],
+ ctx: RequestContext,
+ strict_extract_errors: bool,
+ phase_label: str,
+ ):
+ """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
+ the exception is re-raised).
+ """
+ from openviking.session.memory.memory_updater import ExtractContext
+ from openviking.storage.transaction import get_lock_manager, init_lock_manager
+
+ config = get_openviking_config()
+ vlm = config.vlm.get_vlm_instance()
+ viking_fs = get_viking_fs()
+
+ # Build isolation_handler BEFORE creating the orchestrator so that
+ # ExtractLoop.resolve_operations() can call fill_role_ids() correctly.
+ extract_context = ExtractContext(messages)
+ isolation_handler = MemoryIsolationHandler(ctx, extract_context)
+ isolation_handler.prepare_messages()
+
+ # Inject context into provider (mirrors extract_long_term_memories pattern)
+ provider._isolation_handler = isolation_handler
+ provider._ctx = ctx
+ provider._viking_fs = viking_fs
+
+ orchestrator = ExtractLoop(
+ vlm=vlm,
+ viking_fs=viking_fs,
+ ctx=ctx,
+ context_provider=provider,
+ isolation_handler=isolation_handler,
+ )
+
+ lock_manager = None
+ transaction_handle = None
+ if viking_fs and hasattr(viking_fs, "agfs") and viking_fs.agfs:
+ init_lock_manager(viking_fs.agfs)
+ lock_manager = get_lock_manager()
+ transaction_handle = lock_manager.create_handle()
+
+ try:
+ if lock_manager:
+ schemas = provider.get_memory_schemas(ctx)
+ memory_schema_dirs = []
+ for schema in schemas:
+ if not schema.directory:
+ continue
+
+ if ctx and ctx.user:
+ user_space = to_user_space(
+ ctx.namespace_policy, ctx.user.user_id, ctx.user.agent_id
+ )
+ agent_space = to_agent_space(
+ ctx.namespace_policy, ctx.user.user_id, ctx.user.agent_id
+ )
+ else:
+ user_space = "default"
+ agent_space = "default"
+ import jinja2
+
+ env = jinja2.Environment(autoescape=False)
+ template = env.from_string(schema.directory)
+ dir_path = template.render(user_space=user_space, agent_space=agent_space)
+ dir_path = viking_fs._uri_to_path(dir_path, ctx)
+ if dir_path not in memory_schema_dirs:
+ memory_schema_dirs.append(dir_path)
+
+ retry_interval = config.memory.v2_lock_retry_interval_seconds
+ max_retries = config.memory.v2_lock_max_retries
+ retry_count = 0
+ while True:
+ lock_acquired = await lock_manager.acquire_subtree_batch(
+ transaction_handle,
+ memory_schema_dirs,
+ timeout=None,
+ )
+ if lock_acquired:
+ break
+ retry_count += 1
+ if max_retries > 0 and retry_count >= max_retries:
+ raise TimeoutError(
+ f"[{phase_label}] Failed to acquire memory locks after "
+ f"{retry_count} retries (max={max_retries})"
+ )
+ if retry_interval > 0:
+ await asyncio.sleep(retry_interval)
+
+ provider._transaction_handle = transaction_handle
+ orchestrator._transaction_handle = transaction_handle
+ operations, _ = await orchestrator.run()
+
+ if operations is None:
+ tracer.info(f"[{phase_label}] No memory operations generated")
+ return [], [], [], []
+
+ # Log raw LLM operations before applying.
+ _op_items = [
+ f"{op.memory_type}(uris={op.uris!r})"
+ for op in getattr(operations, "upsert_operations", [])
+ ]
+ _delete_uris_raw = [
+ dc.uri for dc in getattr(operations, "delete_file_contents", [])
+ ]
+ tracer.info(
+ 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()
+ )
+
+ # 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)
+ result = await updater.apply_operations(
+ operations, ctx, extract_context=extract_context, isolation_handler=isolation_handler
+ )
+
+ tracer.info(
+ f"[{phase_label}] Applied: written={len(result.written_uris)}, "
+ f"edited={len(result.edited_uris)}, deleted={len(result.deleted_uris)}, "
+ f"errors={len(result.errors)}"
+ )
+
+ contexts: List[Context] = []
+ 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 list(result.written_uris), list(result.edited_uris), contexts, inherited_traj_uris
+ except Exception as e:
+ logger.error(f"[{phase_label}] Failed to extract: {e}", exc_info=True)
+ if strict_extract_errors:
+ raise
+ return None
+ finally:
+ if lock_manager and transaction_handle:
+ try:
+ await lock_manager.release(transaction_handle)
+ except Exception as e:
+ logger.warning(f"[{phase_label}] Failed to release transaction lock: {e}")
+
+ async def _append_trajectories_to_experiences(
+ self,
+ exp_uris: List[str],
+ traj_uris: List[str],
+ ctx,
+ viking_fs,
+ ) -> None:
+ """Append traj_uris to the source_trajectories list of each experience file.
+
+ This is the system-side management of source_trajectories — the LLM never
+ outputs this field; the pipeline appends the batch after a write or edit.
+ """
+ from openviking.session.memory.utils.content import deserialize_full, serialize_with_metadata
+
+ normalized_traj_uris = [uri for uri in traj_uris if uri]
+ if not normalized_traj_uris:
+ return
+
+ for exp_uri in exp_uris:
+ try:
+ raw = await viking_fs.read_file(exp_uri, ctx=ctx) or ""
+ file_content = deserialize_full(raw)
+ plain_content = file_content.plain_content
+ metadata = file_content.memory_fields or {}
+
+ existing = metadata.get("source_trajectories", [])
+ if isinstance(existing, list):
+ uris = list(existing)
+ elif isinstance(existing, str) and existing.strip():
+ uris = [line.strip() for line in existing.splitlines() if line.strip()]
+ else:
+ uris = []
+
+ changed = False
+ for traj_uri in normalized_traj_uris:
+ if traj_uri not in uris:
+ uris.append(traj_uri)
+ changed = True
+
+ # Trim to the most recent N entries so the list doesn't grow unboundedly.
+ if len(uris) > MAX_SOURCE_TRAJECTORIES:
+ uris = uris[-MAX_SOURCE_TRAJECTORIES:]
+ changed = True
+
+ if changed:
+ metadata["source_trajectories"] = uris
+ metadata["content"] = plain_content
+ new_raw = serialize_with_metadata(metadata)
+ await viking_fs.write_file(exp_uri, new_raw, ctx=ctx)
+ tracer.info(
+ f"[source_traj] appended {len(normalized_traj_uris)} trajectories -> {exp_uri}"
+ )
+ else:
+ tracer.info(f"[source_traj] already present, skip: {exp_uri}")
+ except Exception as e:
+ logger.warning(f"Failed to append source trajectories to {exp_uri}: {e}")
+
async def _build_memory_diff(
self,
result: MemoryUpdateResult,
diff --git a/openviking/session/memory/agent_experience_context_provider.py b/openviking/session/memory/agent_experience_context_provider.py
new file mode 100644
index 000000000..5cc578701
--- /dev/null
+++ b/openviking/session/memory/agent_experience_context_provider.py
@@ -0,0 +1,266 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: AGPL-3.0
+"""
+Agent Experience Context Provider - Phase 2 of agent-scope memory extraction.
+
+Given a new trajectory summary from Phase 1, search for candidate experiences and
+let the LLM decide whether to update an existing one, create a new one, or do nothing.
+
+No tool calls — all context is prefetched. Top-3 candidates also include their
+source_trajectories as grounding material.
+"""
+
+import jinja2
+from typing import Any, Dict, List
+
+from openviking.core.namespace import to_user_space, to_agent_space
+from openviking.server.identity import RequestContext, ToolContext
+from openviking.session.memory.dataclass import MemoryFileContent
+from openviking.session.memory.session_extract_context_provider import (
+ SessionExtractContextProvider,
+)
+from openviking.session.memory.tools import get_tool
+from openviking.session.memory.utils import parse_memory_file_with_fields
+from openviking.session.memory.utils.content import deserialize_content, deserialize_metadata
+from openviking.storage.viking_fs import VikingFS
+from openviking_cli.utils import get_logger
+
+logger = get_logger(__name__)
+
+
+EXPERIENCE_MEMORY_TYPE = "experiences"
+SEARCH_TOP_K = 5
+SOURCE_TRAJ_TOP_K = 3 # only attach source_trajectories for the top-3 candidates
+MAX_SOURCE_TRAJS = 3 # max trajectories to load per experience
+
+
+class AgentExperienceContextProvider(SessionExtractContextProvider):
+ """Phase 2 provider: consolidate the new trajectory into experience memories."""
+
+ def __init__(
+ self,
+ messages: Any,
+ trajectory_summary: str,
+ trajectory_uri: str,
+ latest_archive_overview: str = "",
+ ):
+ super().__init__(messages=messages, latest_archive_overview=latest_archive_overview)
+ self.trajectory_summary = trajectory_summary
+ self.trajectory_uri = trajectory_uri
+ self.prefetched_uris: List[str] = []
+
+ def instruction(self) -> str:
+ output_language = self._output_language
+ return f"""You are a memory extraction agent. Your job is to distill experience memories from agent execution trajectories.
+
+You are given:
+- A new trajectory (the latest agent execution to incorporate)
+- Up to {SEARCH_TOP_K} candidate existing experiences (retrieved by relevance). Top candidates also include their source trajectories as grounding material.
+
+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:
+
+- **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.
+
+- **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`.
+
+- **Create**: no existing experience is related to this trajectory.
+ → Write a new experience in the JSON output.
+
+- **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).
+- Follow field descriptions in the schema.
+- Output JSON only. Do not call any tools.
+
+All memory content must be written in {output_language}.
+"""
+
+ def get_memory_schemas(self, ctx: RequestContext) -> List[Any]:
+ registry = self._get_registry()
+ schema = registry.get(EXPERIENCE_MEMORY_TYPE)
+ if schema is None or not schema.enabled:
+ return []
+ return [schema]
+
+ def get_tools(self) -> List[str]:
+ return []
+
+ def _render_experience_dir(self, ctx: RequestContext) -> str:
+ registry = self._get_registry()
+ schema = registry.get(EXPERIENCE_MEMORY_TYPE)
+ if schema is None or not schema.directory:
+ return ""
+
+ if ctx and ctx.user:
+ user_space = to_user_space(ctx.namespace_policy, ctx.user.user_id, ctx.user.agent_id)
+ agent_space = to_agent_space(ctx.namespace_policy, ctx.user.user_id, ctx.user.agent_id)
+ else:
+ user_space = "default"
+ agent_space = "default"
+
+ env = jinja2.Environment(autoescape=False)
+ return env.from_string(schema.directory).render(
+ user_space=user_space, agent_space=agent_space
+ )
+
+ async def _load_source_trajectories(
+ self,
+ exp_uri: str,
+ exp_meta: Dict,
+ viking_fs: VikingFS,
+ ctx: RequestContext,
+ ) -> List[Dict]:
+ """Load the most recent source trajectories for a candidate experience."""
+ raw = exp_meta.get("source_trajectories", [])
+ if isinstance(raw, list):
+ uris = [str(u).strip() for u in raw if str(u).strip()]
+ elif isinstance(raw, str):
+ uris = [line.strip() for line in raw.splitlines() if line.strip()]
+ else:
+ uris = []
+
+ recent_uris = uris[-MAX_SOURCE_TRAJS:]
+ results = []
+ for uri in recent_uris:
+ try:
+ raw = await viking_fs.read_file(uri, ctx=ctx) or ""
+ results.append({"uri": uri, "content": deserialize_content(raw)})
+ except Exception as e:
+ logger.warning(f"Failed to read source trajectory {uri}: {e}")
+ return results
+
+ async def prefetch(self) -> List[Dict]:
+ if not isinstance(self.messages, list):
+ logger.warning(f"Expected List[Message], got {type(self.messages)}")
+ return []
+
+ ctx = self._ctx
+ viking_fs = self._viking_fs
+ transaction_handle = self._transaction_handle
+
+ experience_dir = self._render_experience_dir(ctx)
+ search_tool = get_tool("search")
+
+ candidate_uris: List[str] = []
+ if experience_dir and viking_fs:
+ if search_tool:
+ tool_ctx_search = ToolContext(
+ viking_fs=viking_fs,
+ request_ctx=ctx,
+ transaction_handle=transaction_handle,
+ default_search_uris=[experience_dir],
+ )
+ try:
+ search_result = await search_tool.execute(
+ viking_fs=viking_fs,
+ ctx=tool_ctx_search,
+ query=self.trajectory_summary[:500] or "experience",
+ limit=SEARCH_TOP_K,
+ )
+ if isinstance(search_result, list):
+ candidate_uris = [m.get("uri", "") for m in search_result if m.get("uri")]
+ elif isinstance(search_result, dict) and "memories" in search_result:
+ candidate_uris = [
+ m.get("uri", "")
+ for m in search_result.get("memories", [])
+ if m.get("uri")
+ ]
+ except Exception as e:
+ logger.warning(f"Failed to search experiences in {experience_dir}: {e}")
+
+ if not candidate_uris:
+ try:
+ entries = await viking_fs.ls(experience_dir, output="original", ctx=ctx)
+ fallback_uris: List[str] = []
+ for entry in entries or []:
+ uri = str(entry.get("uri", "")) if isinstance(entry, dict) else ""
+ name = str(entry.get("name", "")) if isinstance(entry, dict) else ""
+ if not uri.endswith(".md"):
+ continue
+ if name in {".overview.md", ".abstract.md"}:
+ continue
+ if uri.endswith("/.overview.md") or uri.endswith("/.abstract.md"):
+ continue
+ fallback_uris.append(uri)
+ candidate_uris = fallback_uris[:SEARCH_TOP_K]
+ except Exception as e:
+ logger.warning(f"Failed to list experiences in {experience_dir}: {e}")
+
+ # Build candidate experiences section
+ exp_sections: List[str] = []
+ for idx, exp_uri in enumerate(candidate_uris):
+ try:
+ exp_raw = await viking_fs.read_file(exp_uri, ctx=ctx)
+ except Exception as e:
+ logger.warning(f"Failed to read experience {exp_uri}: {e}")
+ continue
+
+ self.prefetched_uris.append(exp_uri)
+ # Populate read_file_contents so that:
+ # 1. Update path: _check_unread_existing_files skips refetch (saves 1 LLM call)
+ # 2. Replace path: resolve_operations can build delete_file_contents, enabling
+ # old file deletion and source_trajectories inheritance.
+ parsed_fields = parse_memory_file_with_fields(exp_raw)
+ self._read_file_contents[exp_uri] = MemoryFileContent(
+ uri=exp_uri,
+ plain_content=parsed_fields.get("content", ""),
+ memory_fields=parsed_fields,
+ )
+ body = deserialize_content(exp_raw)
+ meta = deserialize_metadata(exp_raw) or {}
+ exp_name = meta.get("experience_name", "")
+
+ section = f"### Experience {idx + 1}: `{exp_name}`\nURI: `{exp_uri}`\n\n{body}"
+
+ # Attach source trajectories for top-3 only
+ if idx < SOURCE_TRAJ_TOP_K and viking_fs:
+ source_trajs = await self._load_source_trajectories(exp_uri, meta, viking_fs, ctx)
+ if source_trajs:
+ traj_lines = ["\n#### Source Trajectories (for reference only)"]
+ for i, t in enumerate(source_trajs, 1):
+ traj_lines.append(f"\n**Trajectory {i}** (`{t['uri']}`):\n{t['content']}")
+ section += "\n" + "\n".join(traj_lines)
+
+ exp_sections.append(section)
+
+ # Assemble single user message
+ lines = [
+ "## New Trajectory",
+ f"URI: `{self.trajectory_uri}`",
+ "",
+ self.trajectory_summary,
+ ]
+
+ if exp_sections:
+ lines += [
+ "",
+ "---",
+ "",
+ "## Candidate Existing Experiences",
+ "",
+ "\n\n---\n\n".join(exp_sections),
+ ]
+ else:
+ lines += [
+ "",
+ "---",
+ "",
+ "## Candidate Existing Experiences",
+ "",
+ "No existing experiences found.",
+ ]
+
+ lines += [
+ "",
+ "---",
+ "",
+ "Based on the above, decide whether to **Update**, **Replace**, **Create**, or **Skip**. Output JSON only.",
+ ]
+
+ return [{"role": "user", "content": "\n".join(lines)}]
diff --git a/openviking/session/memory/agent_trajectory_context_provider.py b/openviking/session/memory/agent_trajectory_context_provider.py
new file mode 100644
index 000000000..05ab0a9d0
--- /dev/null
+++ b/openviking/session/memory/agent_trajectory_context_provider.py
@@ -0,0 +1,58 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: AGPL-3.0
+"""
+Agent Trajectory Context Provider - Phase 1 of agent-scope memory extraction.
+
+Extracts execution trajectory summaries from the conversation. Only the
+`trajectory` schema participates; no existing memories are prefetched because
+trajectories are add_only.
+"""
+
+from typing import Any, Dict, List
+
+from openviking.server.identity import RequestContext
+from openviking.session.memory.session_extract_context_provider import (
+ SessionExtractContextProvider,
+)
+from openviking.storage.viking_fs import VikingFS
+from openviking_cli.utils import get_logger
+
+logger = get_logger(__name__)
+
+
+TRAJECTORY_MEMORY_TYPE = "trajectories"
+
+
+class AgentTrajectoryContextProvider(SessionExtractContextProvider):
+ """Phase 1 provider: extract trajectory summaries from conversation."""
+
+ 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.
+
+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.
+
+All memory content must be written in {output_language}.
+"""
+
+ def get_memory_schemas(self, ctx: RequestContext) -> List[Any]:
+ """Only expose the trajectory schema."""
+ registry = self._get_registry()
+ schema = registry.get(TRAJECTORY_MEMORY_TYPE)
+ if schema is None or not schema.enabled:
+ return []
+ return [schema]
+
+ async def prefetch(self) -> List[Dict]:
+ """Only inject the conversation. Trajectory is add_only so no ls/search."""
+ if not isinstance(self.messages, list):
+ logger.warning(f"Expected List[Message], got {type(self.messages)}")
+ return []
+ return [self._build_conversation_message()]
+
+ def get_tools(self) -> List[str]:
+ return []
diff --git a/openviking/session/memory/dataclass.py b/openviking/session/memory/dataclass.py
index 46b74c751..3d86a4771 100644
--- a/openviking/session/memory/dataclass.py
+++ b/openviking/session/memory/dataclass.py
@@ -59,6 +59,9 @@ class MemoryTypeSchema(BaseModel):
operation_mode: str = Field(
"upsert", description="Operation mode: 'upsert' (default), 'add_only', or 'update_only'"
)
+ agent_only: bool = Field(
+ False, description="If true, only used by agent memory extraction, not user memory"
+ )
overview_template: Optional[str] = Field(
None, description="Overview template for auto-generating .overview.md files"
)
diff --git a/openviking/session/memory/extract_loop.py b/openviking/session/memory/extract_loop.py
index ab47d8d5f..9d8beeabe 100644
--- a/openviking/session/memory/extract_loop.py
+++ b/openviking/session/memory/extract_loop.py
@@ -410,7 +410,7 @@ The final output of the model must strictly follow the JSON Schema format shown
# Call LLM with tools - use tools from strategy
tools = None
tool_choice = None
- if not self._disable_tools_for_iteration:
+ if not self._disable_tools_for_iteration and self._tool_schemas:
tools = self._tool_schemas
tool_choice = "auto"
with bind_telemetry_stage("memory_extract"):
diff --git a/openviking/session/memory/memory_type_registry.py b/openviking/session/memory/memory_type_registry.py
index de7ac67e7..cdebdcfd9 100644
--- a/openviking/session/memory/memory_type_registry.py
+++ b/openviking/session/memory/memory_type_registry.py
@@ -204,6 +204,7 @@ class MemoryTypeRegistry:
directory=data.get("directory", ""),
enabled=data.get("enabled", data.get("enable", True)),
operation_mode=data.get("operation_mode", "upsert"),
+ agent_only=data.get("agent_only", False),
overview_template=data.get("overview_template"),
)
diff --git a/openviking/session/memory/memory_updater.py b/openviking/session/memory/memory_updater.py
index c6dafd982..235b8078d 100644
--- a/openviking/session/memory/memory_updater.py
+++ b/openviking/session/memory/memory_updater.py
@@ -82,6 +82,26 @@ class ExtractContext:
first_time = msg_range._first_message_time()
return first_time.split("-")[2] if first_time else None
+ def get_timestamp_from_ranges(self, ranges_str: str) -> str:
+ """根据 ranges 获取第一条消息的紧凑时间戳(YYYYMMDDHHMMSS),用于文件名去重。
+
+ Fallback 到 datetime.now() 以保证总是返回非空字符串。
+ """
+ from datetime import datetime
+
+ msg_range = self.read_message_ranges(ranges_str) if ranges_str else None
+ if msg_range:
+ for elem in msg_range.elements:
+ if isinstance(elem, str):
+ continue
+ created_at = getattr(elem, "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:
@@ -353,6 +373,7 @@ class MemoryUpdater:
):
"""Apply upsert operation from a flat model."""
viking_fs = self._get_viking_fs()
+
memory_type = resolved_op.memory_type
schema = self._registry.get(memory_type)
# Process each URI independently
diff --git a/openviking/session/memory/session_extract_context_provider.py b/openviking/session/memory/session_extract_context_provider.py
index 36b9c84f2..0a00753b8 100644
--- a/openviking/session/memory/session_extract_context_provider.py
+++ b/openviking/session/memory/session_extract_context_provider.py
@@ -208,8 +208,11 @@ After exploring, analyze the conversation and output ALL memory write/edit/delet
pre_fetch_messages = []
pre_fetch_messages.append(self._build_conversation_message())
- # 触发 registry 加载
- schemas = self._get_registry().list_all(include_disabled=False)
+ # 触发 registry 加载,过滤掉 agent_only 的 schema(trajectory/experience 只由 agent memory 处理)
+ schemas = [
+ s for s in self._get_registry().list_all(include_disabled=False)
+ if not getattr(s, "agent_only", False)
+ ]
from openviking.server.identity import ToolContext
@@ -347,7 +350,10 @@ After exploring, analyze the conversation and output ALL memory write/edit/delet
def get_memory_schemas(self, ctx: RequestContext) -> List[Any]:
"""获取需要参与的 memory schemas(内部自动加载)"""
- return self._get_registry().list_all(include_disabled=False)
+ return [
+ s for s in self._get_registry().list_all(include_disabled=False)
+ if not getattr(s, "agent_only", False)
+ ]
def get_schema_directories(self) -> List[str]:
"""返回需要加载的 schema 目录"""
diff --git a/openviking/session/memory/utils/content.py b/openviking/session/memory/utils/content.py
index b8f17fe6c..be9152672 100644
--- a/openviking/session/memory/utils/content.py
+++ b/openviking/session/memory/utils/content.py
@@ -80,9 +80,6 @@ def serialize_with_metadata(
# If template rendering fails, use content as-is
pass
- # Restore metadata (we popped content earlier)
- # Note: metadata dict is modified in place, caller should be aware
-
# Clean metadata - remove None values and memory_type
clean_metadata = {k: v for k, v in metadata.items() if v is not None and k != "memory_type"}
diff --git a/openviking/session/session.py b/openviking/session/session.py
index ad143f07a..6b70cb5fc 100644
--- a/openviking/session/session.py
+++ b/openviking/session/session.py
@@ -829,7 +829,7 @@ class Session:
ctx=self.ctx,
)
- # Memory extraction
+ # 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:
@@ -840,14 +840,57 @@ class Session:
logger.info(
f"Starting memory extraction from {len(messages)} archived messages"
)
- extracted = await 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,
+
+ has_agent_memory = hasattr(
+ self._session_compressor, "extract_agent_memories"
+ )
+
+ 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,
+ )
+ )
+
+ async def _noop_agent():
+ return []
+
+ agent_task = asyncio.ensure_future(
+ self._session_compressor.extract_agent_memories(
+ messages=messages,
+ ctx=self.ctx,
+ )
+ if has_agent_memory
+ else _noop_agent()
+ )
+
+ _results = await asyncio.gather(
+ user_task, agent_task, return_exceptions=True
)
+ 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
+
logger.info(f"Extracted {len(extracted)} memories")
for ctx_item in extracted:
cat = getattr(ctx_item, "category", "") or "unknown"
@@ -855,6 +898,13 @@ class Session:
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)
+
# Write relations (using snapshot, not self._usage_records)
if self._viking_fs:
for usage in usage_records:
diff --git a/openviking_cli/utils/config/memory_config.py b/openviking_cli/utils/config/memory_config.py
index 15623b7af..d4811992f 100644
--- a/openviking_cli/utils/config/memory_config.py
+++ b/openviking_cli/utils/config/memory_config.py
@@ -40,6 +40,15 @@ class MemoryConfig(BaseModel):
"0 means unlimited retries."
),
)
+ agent_memory_enabled: bool = Field(
+ default=False,
+ description=(
+ "Enable agent-scope trajectory/experience memory extraction. When true, "
+ "a two-phase pipeline runs after user-memory extraction: Phase 1 extracts "
+ "execution trajectories from the conversation; Phase 2 consolidates them "
+ "into higher-level experience memories."
+ ),
+ )
eager_prefetch: bool = Field(
default=True,
description=(
diff --git a/tests/integration/test_agent_memory_e2e.py b/tests/integration/test_agent_memory_e2e.py
new file mode 100644
index 000000000..09306f9b8
--- /dev/null
+++ b/tests/integration/test_agent_memory_e2e.py
@@ -0,0 +1,315 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: AGPL-3.0
+"""
+End-to-end test for agent memory (trajectory + experience two-phase pipeline).
+
+What this test covers
+---------------------
+1. Two sessions in the same domain (flight booking conflict resolution).
+2. After each session commit, the two-phase pipeline runs:
+ Phase 1 — extract a `trajectory` memory (timestamped filename).
+ Phase 2 — consolidate the trajectory into an `experience` memory.
+3. Round 1 is expected to CREATE the experience.
+4. Round 2 covers the same domain with additional edge cases and is expected
+ to EDIT/UPDATE the existing experience (not create a duplicate).
+
+Prerequisites
+-------------
+- ~/.openviking/ov.conf has:
+ "memory": { "version": "v2", "agent_memory_enabled": true }
+
+Run
+---
+ .venv/bin/pytest tests/integration/test_agent_memory_e2e.py -v -s -m integration
+"""
+
+from __future__ import annotations
+
+import logging
+import shutil
+import time
+import uuid
+import os
+from pathlib import Path
+from typing import Dict, List, Tuple
+
+import pytest
+
+from openviking.client.local import LocalClient
+from openviking.core.namespace import to_agent_space
+from openviking.server.identity import AccountNamespacePolicy
+from openviking.session.memory.session_extract_context_provider import SessionExtractContextProvider
+from openviking.session.memory.utils.content import deserialize_metadata
+from openviking_cli.session.user_id import UserIdentifier
+from openviking_cli.utils import run_async
+from openviking_cli.utils.config import OpenVikingConfigSingleton, get_openviking_config
+
+logger = logging.getLogger(__name__)
+
+# ── 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]] = [
+ ("user", "帮我订一张下周三北京到上海的机票,上午出发"),
+ (
+ "assistant",
+ "好的,我先用 search_flights 工具查询下周三(2026-04-22)北京到上海上午的航班。",
+ ),
+ (
+ "assistant",
+ "[tool_call: search_flights(from=PEK, to=SHA, date=2026-04-22, time=morning)]"
+ " 返回了 3 个候选航班:CA1501 07:30、MU5101 08:00、HU7603 09:45。",
+ ),
+ ("user", "那就订 MU5101 吧"),
+ (
+ "assistant",
+ "[tool_call: book_flight(flight=MU5101, passenger=user_123)]"
+ " 订票失败:该用户已存在一张相同日期的预订 (CA1501)。",
+ ),
+ (
+ "assistant",
+ "检测到重复预订,我先询问你的偏好。你是想取消已有的 CA1501 换成 MU5101,"
+ "还是保留现有预订?",
+ ),
+ ("user", "那就取消 CA1501,改订 MU5101"),
+ ("assistant", "[tool_call: cancel_booking(booking_id=CA1501-xyz)] 已取消原预订。"),
+ (
+ "assistant",
+ "[tool_call: book_flight(flight=MU5101, passenger=user_123)] 预订成功,"
+ "票号 MU5101-abc。已将新票号发送到你的邮箱。",
+ ),
+]
+
+# Round 2: Same domain (booking conflict) with additional edge cases:
+# - User wants to keep both bookings (parallel trips)
+# - Cancellation fails due to departure-within-24h policy
+# Expectation: Phase 2 should EDIT the existing experience and append this
+# trajectory to source_trajectories.
+CONV_B_FLIGHT_DUPLICATE_EXTRA: List[Tuple[str, str]] = [
+ ("user", "帮我订 4 月 28 日北京到广州的机票,下午的"),
+ (
+ "assistant",
+ "[tool_call: search_flights(from=PEK, to=CAN, date=2026-04-28, time=afternoon)]"
+ " 找到了 CZ3101 14:00、CA1315 15:30、MF8023 16:20。",
+ ),
+ ("user", "订 CA1315"),
+ (
+ "assistant",
+ "[tool_call: book_flight(flight=CA1315, passenger=user_123)]"
+ " 订票失败:同一日期已有一张预订 (CZ3101)。",
+ ),
+ (
+ "assistant",
+ "检测到重复预订。这次你想取消 CZ3101 改订 CA1315,还是这两张都要保留?",
+ ),
+ ("user", "这两张都要,是不同行程"),
+ (
+ "assistant",
+ "[tool_call: check_multi_booking_policy(date=2026-04-28)]"
+ " 确认:同一天多个预订是允许的,系统不强制合并。",
+ ),
+ (
+ "assistant",
+ "[tool_call: book_flight(flight=CA1315, passenger=user_123, override_duplicate=true)]"
+ " 预订成功,票号 CA1315-xyz。两张机票均已生效。",
+ ),
+ ("user", "好的,另外我想取消上周订的 MF7801"),
+ (
+ "assistant",
+ "[tool_call: cancel_booking(booking_id=MF7801-001)]"
+ " 取消失败:距出发时间不足 24 小时,航空公司不允许免费取消。",
+ ),
+ (
+ "assistant",
+ "MF7801 的出发时间距现在不足 24 小时,按航空公司政策无法免费取消。"
+ "有两个选择:1) 支付改签费改期;2) 放弃该票(退款仅限税费)。请问你想怎么处理?",
+ ),
+ ("user", "算了,就不管了"),
+ ("assistant", "好的,MF7801 保持原状,CA1315 新预订已生效。"),
+]
+
+
+# ── Helpers ───────────────────────────────────────────────────────────────────
+
+
+def _wait_for_task(client: LocalClient, task_id: str, timeout_s: int = 600) -> None:
+ deadline = time.time() + timeout_s
+ while time.time() < deadline:
+ task = run_async(client.get_task(task_id)) or {}
+ status = task.get("status") if isinstance(task, dict) else getattr(task, "status", None)
+ if status in {"completed", "failed", "cancelled"}:
+ if status != "completed":
+ raise RuntimeError(f"Task failed: {task}")
+ return
+ time.sleep(1)
+ raise TimeoutError(f"Task timed out: {task_id}")
+
+
+def _run_conversation(client: LocalClient, turns: List[Tuple[str, str]]) -> None:
+ session = run_async(client.create_session())
+ session_id = session["session_id"]
+ logger.info(f" session_id = {session_id[:8]}...")
+ for role, content in turns:
+ run_async(client.add_message(session_id=session_id, role=role, content=content))
+ logger.info(f" Committing {len(turns)} messages...")
+ result = run_async(client.commit_session(session_id=session_id))
+ task_id = result.get("task_id") if isinstance(result, dict) else getattr(result, "task_id", None)
+ if task_id:
+ _wait_for_task(client, task_id)
+ logger.info(f" Done (task {task_id[:8]})")
+
+
+def _list_non_overview_entries(client: LocalClient, uri: str) -> List[dict]:
+ try:
+ entries = run_async(client.ls(uri, simple=False)) or []
+ except Exception:
+ return []
+ _INTERNAL_SUFFIXES = (".overview.md", ".abstract.md")
+ return [
+ e
+ for e in entries
+ if not any(
+ (e.get("name", "") if isinstance(e, dict) else getattr(e, "name", "")).endswith(s)
+ for s in _INTERNAL_SUFFIXES
+ )
+ ]
+
+
+def _entry_uri(entry: dict) -> str:
+ if isinstance(entry, dict):
+ return str(entry.get("uri", ""))
+ return str(getattr(entry, "uri", ""))
+
+
+def _collect_source_trajectories(client: LocalClient, exp_entries: List[dict]) -> List[str]:
+ all_uris: List[str] = []
+ for entry in exp_entries:
+ exp_uri = _entry_uri(entry)
+ if not exp_uri:
+ continue
+ raw = run_async(client.read(exp_uri)) or ""
+ metadata = deserialize_metadata(raw) or {}
+ source = metadata.get("source_trajectories", [])
+ if isinstance(source, list):
+ all_uris.extend(str(u).strip() for u in source if str(u).strip())
+ elif isinstance(source, str):
+ all_uris.extend(line.strip() for line in source.splitlines() if line.strip())
+ return list(dict.fromkeys(all_uris))
+
+
+# ── Fixtures ──────────────────────────────────────────────────────────────────
+
+
+def agent_memory_config_check():
+ """Skip unless agent_memory_enabled and memory.version == v2."""
+ OpenVikingConfigSingleton._instance = None
+ config = get_openviking_config()
+ if not getattr(config.memory, "agent_memory_enabled", False):
+ pytest.skip("agent_memory_enabled is not set in config — skipping agent memory tests")
+ if config.memory.version != "v2":
+ pytest.skip("memory.version != v2 — skipping agent memory tests")
+
+
+def local_test_env() -> Dict[str, object]:
+ policy = AccountNamespacePolicy(
+ isolate_user_scope_by_agent=False,
+ isolate_agent_scope_by_user=False,
+ )
+ local_path = Path.cwd() / ".tmp_agent_memory_e2e" / uuid.uuid4().hex[:8]
+ local_path.mkdir(parents=True, exist_ok=True)
+ try:
+ yield {
+ "path": str(local_path),
+ "account_id": "default",
+ "policy": policy,
+ }
+ finally:
+ shutil.rmtree(local_path, ignore_errors=True)
+
+
+def _build_client(env: Dict[str, object], user_id: str, agent_id: str = "travelbot") -> LocalClient:
+ client = LocalClient(
+ path=str(env["path"]),
+ user=UserIdentifier(str(env["account_id"]), user_id, agent_id),
+ )
+ client._ctx.namespace_policy = env["policy"]
+ run_async(client.initialize())
+ return client
+
+
+# ── Tests ─────────────────────────────────────────────────────────────────────
+
+
+ os.environ.get("RUN_AGENT_MEMORY_TESTS") != "1",
+ reason="set RUN_AGENT_MEMORY_TESTS=1 to run agent memory e2e tests",
+)
+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):
+ """
+ Two sessions in the same booking-conflict domain.
+
+ Assertions:
+ - 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,
+ )
+ 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")
+ 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"
+ )
+ finally:
+ run_async(client.close())
+
+class TestAgentMemorySchemas:
+ """Unit tests for agent memory schema filtering — no integration environment needed."""
+
+ def test_no_agent_only_schemas_in_user_memory(self):
+ """
+ Verify that trajectory/experience schemas are filtered out from
+ SessionExtractContextProvider (user memory path).
+ """
+ provider = SessionExtractContextProvider(messages=[])
+ schemas = provider.get_memory_schemas(ctx=None)
+ schema_types = [s.memory_type for s in schemas]
+
+ assert "trajectories" not in schema_types, (
+ "trajectories schema must not appear in user memory extraction"
+ )
+ assert "experiences" not in schema_types, (
+ "experiences schema must not appear in user memory extraction"
+ )
+