Skip to content

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

Feat/memory link (#2010)

chenjw85908e241ad2
diff --git a/openviking/models/vlm/backends/openai_vlm.py b/openviking/models/vlm/backends/openai_vlm.py
index 513cd0402..0145b32be 100644
--- a/openviking/models/vlm/backends/openai_vlm.py
+++ b/openviking/models/vlm/backends/openai_vlm.py
@@ -208,8 +208,9 @@ class OpenAIVLM(VLMBase):
tools: Optional[List[Dict[str, Any]]] = None,
tool_choice: Optional[str] = None,
messages: Optional[List[Dict[str, Any]]] = None,
- thinking: bool = False,
+ thinking: Optional[bool] = None,
) -> Dict[str, Any]:
+ effective_thinking = self.thinking if thinking is None else thinking
kwargs_messages = messages or [{"role": "user", "content": prompt}]
model = self.model or "gpt-4o-mini"
is_reasoning = _is_reasoning_model(model)
@@ -221,7 +222,7 @@ class OpenAIVLM(VLMBase):
kwargs["reasoning_effort"] = self.reasoning_effort
else:
kwargs["temperature"] = self.temperature
- self._apply_provider_specific_extra_body(kwargs, thinking)
+ self._apply_provider_specific_extra_body(kwargs, effective_thinking)
max_tokens = self.max_tokens or 32768
kwargs["max_completion_tokens" if is_reasoning else "max_tokens"] = max_tokens
if tools:
@@ -236,8 +237,9 @@ class OpenAIVLM(VLMBase):
tools: Optional[List[Dict[str, Any]]] = None,
tool_choice: Optional[str] = None,
messages: Optional[List[Dict[str, Any]]] = None,
- thinking: bool = False,
+ thinking: Optional[bool] = None,
) -> Dict[str, Any]:
+ effective_thinking = self.thinking if thinking is None else thinking
if messages:
kwargs_messages = messages
else:
@@ -258,7 +260,7 @@ class OpenAIVLM(VLMBase):
kwargs["reasoning_effort"] = self.reasoning_effort
else:
kwargs["temperature"] = self.temperature
- self._apply_provider_specific_extra_body(kwargs, thinking)
+ self._apply_provider_specific_extra_body(kwargs, effective_thinking)
max_tokens = self.max_tokens or 32768
kwargs["max_completion_tokens" if is_reasoning else "max_tokens"] = max_tokens
if tools:
@@ -279,14 +281,15 @@ class OpenAIVLM(VLMBase):
def get_completion(
self,
prompt: str = "",
- thinking: bool = False,
+ thinking: Optional[bool] = None,
tools: Optional[List[Dict[str, Any]]] = None,
tool_choice: Optional[str] = None,
messages: Optional[List[Dict[str, Any]]] = None,
) -> Union[str, VLMResponse]:
"""Get text completion"""
+ effective_thinking = self.thinking if thinking is None else thinking
client = self.get_client()
- kwargs = self._build_text_kwargs(prompt, tools, tool_choice, messages, thinking)
+ kwargs = self._build_text_kwargs(prompt, tools, tool_choice, messages, effective_thinking)
def _call() -> Union[str, VLMResponse]:
t0 = time.perf_counter()
@@ -308,14 +311,15 @@ class OpenAIVLM(VLMBase):
async def get_completion_async(
self,
prompt: str = "",
- thinking: bool = False,
+ thinking: Optional[bool] = None,
tools: Optional[List[Dict[str, Any]]] = None,
tool_choice: Optional[str] = None,
messages: Optional[List[Dict[str, Any]]] = None,
) -> Union[str, VLMResponse]:
"""Get text completion asynchronously"""
+ effective_thinking = self.thinking if thinking is None else thinking
client = self.get_async_client()
- kwargs = self._build_text_kwargs(prompt, tools, tool_choice, messages, thinking)
+ kwargs = self._build_text_kwargs(prompt, tools, tool_choice, messages, effective_thinking)
async def _call() -> Union[str, VLMResponse]:
t0 = time.perf_counter()
@@ -391,14 +395,17 @@ class OpenAIVLM(VLMBase):
self,
prompt: str = "",
images: Optional[List[Union[str, Path, bytes]]] = None,
- thinking: bool = False,
+ thinking: Optional[bool] = None,
tools: Optional[List[Dict[str, Any]]] = None,
tool_choice: Optional[str] = None,
messages: Optional[List[Dict[str, Any]]] = None,
) -> Union[str, VLMResponse]:
"""Get vision completion"""
+ effective_thinking = self.thinking if thinking is None else thinking
client = self.get_client()
- kwargs = self._build_vision_kwargs(prompt, images, tools, tool_choice, messages, thinking)
+ kwargs = self._build_vision_kwargs(
+ prompt, images, tools, tool_choice, messages, effective_thinking
+ )
def _call() -> Union[str, VLMResponse]:
t0 = time.perf_counter()
@@ -420,14 +427,17 @@ class OpenAIVLM(VLMBase):
self,
prompt: str = "",
images: Optional[List[Union[str, Path, bytes]]] = None,
- thinking: bool = False,
+ thinking: Optional[bool] = None,
tools: Optional[List[Dict[str, Any]]] = None,
tool_choice: Optional[str] = None,
messages: Optional[List[Dict[str, Any]]] = None,
) -> Union[str, VLMResponse]:
"""Get vision completion asynchronously"""
+ effective_thinking = self.thinking if thinking is None else thinking
client = self.get_async_client()
- kwargs = self._build_vision_kwargs(prompt, images, tools, tool_choice, messages, thinking)
+ kwargs = self._build_vision_kwargs(
+ prompt, images, tools, tool_choice, messages, effective_thinking
+ )
async def _call() -> Union[str, VLMResponse]:
t0 = time.perf_counter()
diff --git a/openviking/models/vlm/backends/volcengine_vlm.py b/openviking/models/vlm/backends/volcengine_vlm.py
index 5429d5a4c..9549f5ea2 100644
--- a/openviking/models/vlm/backends/volcengine_vlm.py
+++ b/openviking/models/vlm/backends/volcengine_vlm.py
@@ -103,18 +103,19 @@ class VolcEngineVLM(OpenAIVLM):
def get_completion(
self,
prompt: str = "",
- thinking: bool = False,
+ thinking: Optional[bool] = None,
tools: Optional[List[Dict[str, Any]]] = None,
tool_choice: Optional[str] = None,
messages: Optional[List[Dict[str, Any]]] = None,
) -> Union[str, VLMResponse]:
"""Get text completion via Chat Completions API."""
+ effective_thinking = self.thinking if thinking is None else thinking
kwargs_messages = messages or [{"role": "user", "content": prompt}]
kwargs = {
"model": self.model or "doubao-seed-2-0-pro-260215",
"messages": kwargs_messages,
"temperature": self.temperature,
- "thinking": {"type": "disabled" if not thinking else "enabled"},
+ "thinking": {"type": "disabled" if not effective_thinking else "enabled"},
}
max_tokens = self.max_tokens or 32768
kwargs["max_tokens"] = max_tokens
@@ -136,18 +137,19 @@ class VolcEngineVLM(OpenAIVLM):
async def get_completion_async(
self,
prompt: str = "",
- thinking: bool = False,
+ thinking: Optional[bool] = None,
tools: Optional[List[Dict[str, Any]]] = None,
tool_choice: Optional[str] = None,
messages: Optional[List[Dict[str, Any]]] = None,
) -> Union[str, VLMResponse]:
"""Get text completion asynchronously via Chat Completions API."""
+ effective_thinking = self.thinking if thinking is None else thinking
kwargs_messages = messages or [{"role": "user", "content": prompt}]
kwargs = {
"model": self.model or "doubao-seed-2-0-pro-260215",
"messages": kwargs_messages,
"temperature": self.temperature,
- "thinking": {"type": "disabled" if not thinking else "enabled"},
+ "thinking": {"type": "disabled" if not effective_thinking else "enabled"},
}
max_tokens = self.max_tokens or 32768
kwargs["max_tokens"] = max_tokens
@@ -306,12 +308,13 @@ class VolcEngineVLM(OpenAIVLM):
self,
prompt: str = "",
images: Optional[List[Union[str, Path, bytes]]] = None,
- thinking: bool = False,
+ thinking: Optional[bool] = None,
tools: Optional[List[Dict[str, Any]]] = None,
tool_choice: Optional[str] = None,
messages: Optional[List[Dict[str, Any]]] = None,
) -> Union[str, VLMResponse]:
"""Get vision completion via Chat Completions API."""
+ effective_thinking = self.thinking if thinking is None else thinking
if messages:
kwargs_messages = messages
else:
@@ -326,7 +329,7 @@ class VolcEngineVLM(OpenAIVLM):
"model": self.model or "doubao-seed-2-0-pro-260215",
"messages": kwargs_messages,
"temperature": self.temperature,
- "thinking": {"type": "disabled" if not thinking else "enabled"},
+ "thinking": {"type": "disabled" if not effective_thinking else "enabled"},
}
max_tokens = self.max_tokens or 32768
kwargs["max_tokens"] = max_tokens
@@ -348,12 +351,13 @@ class VolcEngineVLM(OpenAIVLM):
self,
prompt: str = "",
images: Optional[List[Union[str, Path, bytes]]] = None,
- thinking: bool = False,
+ thinking: Optional[bool] = None,
tools: Optional[List[Dict[str, Any]]] = None,
tool_choice: Optional[str] = None,
messages: Optional[List[Dict[str, Any]]] = None,
) -> Union[str, VLMResponse]:
"""Get vision completion asynchronously via Chat Completions API."""
+ effective_thinking = self.thinking if thinking is None else thinking
if messages:
kwargs_messages = messages
else:
@@ -368,7 +372,7 @@ class VolcEngineVLM(OpenAIVLM):
"model": self.model or "doubao-seed-2-0-pro-260215",
"messages": kwargs_messages,
"temperature": self.temperature,
- "thinking": {"type": "disabled" if not thinking else "enabled"},
+ "thinking": {"type": "disabled" if not effective_thinking else "enabled"},
}
max_tokens = self.max_tokens or 32768
kwargs["max_tokens"] = max_tokens
diff --git a/openviking/models/vlm/base.py b/openviking/models/vlm/base.py
index 25443584e..d5294f3d1 100644
--- a/openviking/models/vlm/base.py
+++ b/openviking/models/vlm/base.py
@@ -76,6 +76,7 @@ class VLMBase(ABC):
self.extra_headers = config.get("extra_headers")
self.extra_request_body = dict(config.get("extra_request_body") or {})
self.stream = config.get("stream", False)
+ self.thinking = config.get("thinking", False)
# Token usage tracking
self._token_tracker = TokenUsageTracker()
@@ -84,7 +85,7 @@ class VLMBase(ABC):
def get_completion(
self,
prompt: str = "",
- thinking: bool = False,
+ thinking: Optional[bool] = None,
tools: Optional[List[Dict[str, Any]]] = None,
tool_choice: Optional[str] = None,
messages: Optional[List[Dict[str, Any]]] = None,
@@ -101,13 +102,14 @@ class VLMBase(ABC):
Returns:
str if no tools provided, VLMResponse if tools provided
"""
+ effective_thinking = self.thinking if thinking is None else thinking
pass
@abstractmethod
async def get_completion_async(
self,
prompt: str = "",
- thinking: bool = False,
+ thinking: Optional[bool] = None,
tools: Optional[List[Dict[str, Any]]] = None,
tool_choice: Optional[str] = None,
messages: Optional[List[Dict[str, Any]]] = None,
@@ -124,6 +126,7 @@ class VLMBase(ABC):
Returns:
str if no tools provided, VLMResponse if tools provided
"""
+ effective_thinking = self.thinking if thinking is None else thinking
pass
@abstractmethod
@@ -131,7 +134,7 @@ class VLMBase(ABC):
self,
prompt: str = "",
images: Optional[List[Union[str, Path, bytes]]] = None,
- thinking: bool = False,
+ thinking: Optional[bool] = None,
tools: Optional[List[Dict[str, Any]]] = None,
tool_choice: Optional[str] = None,
messages: Optional[List[Dict[str, Any]]] = None,
@@ -149,6 +152,7 @@ class VLMBase(ABC):
Returns:
str if no tools provided, VLMResponse if tools provided
"""
+ effective_thinking = self.thinking if thinking is None else thinking
pass
@abstractmethod
@@ -156,7 +160,7 @@ class VLMBase(ABC):
self,
prompt: str = "",
images: Optional[List[Union[str, Path, bytes]]] = None,
- thinking: bool = False,
+ thinking: Optional[bool] = None,
tools: Optional[List[Dict[str, Any]]] = None,
tool_choice: Optional[str] = None,
messages: Optional[List[Dict[str, Any]]] = None,
@@ -174,6 +178,7 @@ class VLMBase(ABC):
Returns:
str if no tools provided, VLMResponse if tools provided
"""
+ effective_thinking = self.thinking if thinking is None else thinking
pass
def _clean_response(self, content: str) -> str:
diff --git a/openviking/models/vlm/llm.py b/openviking/models/vlm/llm.py
index 422bbe6bb..6337510bc 100644
--- a/openviking/models/vlm/llm.py
+++ b/openviking/models/vlm/llm.py
@@ -175,17 +175,18 @@ class StructuredVLM:
self,
prompt: str = "",
schema: Optional[Dict[str, Any]] = None,
- thinking: bool = False,
+ thinking: Optional[bool] = None,
tools: Optional[List[Dict[str, Any]]] = None,
messages: Optional[List[Dict[str, Any]]] = None,
) -> Optional[Dict[str, Any]]:
"""Get JSON completion from VLM."""
+ effective_thinking = self._get_vlm().thinking if thinking is None else thinking
if schema and not messages:
prompt = f"{prompt}\n\n{get_json_schema_prompt(schema)}"
response = self._get_vlm().get_completion(
prompt=prompt,
- thinking=thinking,
+ thinking=effective_thinking,
tools=tools,
messages=messages,
)
@@ -195,17 +196,18 @@ class StructuredVLM:
self,
prompt: str = "",
schema: Optional[Dict[str, Any]] = None,
- thinking: bool = False,
+ thinking: Optional[bool] = None,
tools: Optional[List[Dict[str, Any]]] = None,
messages: Optional[List[Dict[str, Any]]] = None,
) -> Optional[Dict[str, Any]]:
"""Async version of complete_json."""
+ effective_thinking = self._get_vlm().thinking if thinking is None else thinking
if schema and not messages:
prompt = f"{prompt}\n\n{get_json_schema_prompt(schema)}"
response = await self._get_vlm().get_completion_async(
prompt=prompt,
- thinking=thinking,
+ thinking=effective_thinking,
tools=tools,
messages=messages,
)
@@ -215,11 +217,12 @@ class StructuredVLM:
self,
prompt: str,
model_class: Type[T],
- thinking: bool = False,
+ thinking: Optional[bool] = None,
) -> Optional[T]:
"""Get structured completion validated against a Pydantic model."""
+ effective_thinking = self._get_vlm().thinking if thinking is None else thinking
schema = model_class.model_json_schema()
- response = self.complete_json(prompt, schema=schema, thinking=thinking)
+ response = self.complete_json(prompt, schema=schema, thinking=effective_thinking)
if response is None:
return None
@@ -233,11 +236,12 @@ class StructuredVLM:
self,
prompt: str,
model_class: Type[T],
- thinking: bool = False,
+ thinking: Optional[bool] = None,
) -> Optional[T]:
"""Async version of complete_model."""
+ effective_thinking = self._get_vlm().thinking if thinking is None else thinking
schema = model_class.model_json_schema()
- response = await self.complete_json_async(prompt, schema=schema, thinking=thinking)
+ response = await self.complete_json_async(prompt, schema=schema, thinking=effective_thinking)
if response is None:
return None
@@ -251,15 +255,16 @@ class StructuredVLM:
self,
prompt: str = "",
images: Optional[list] = None,
- thinking: bool = False,
+ thinking: Optional[bool] = None,
tools: Optional[List[Dict[str, Any]]] = None,
messages: Optional[List[Dict[str, Any]]] = None,
) -> Union[str, Any]:
"""Get vision completion."""
+ effective_thinking = self._get_vlm().thinking if thinking is None else thinking
return self._get_vlm().get_vision_completion(
prompt=prompt,
images=images,
- thinking=thinking,
+ thinking=effective_thinking,
tools=tools,
messages=messages,
)
@@ -268,15 +273,16 @@ class StructuredVLM:
self,
prompt: str = "",
images: Optional[list] = None,
- thinking: bool = False,
+ thinking: Optional[bool] = None,
tools: Optional[List[Dict[str, Any]]] = None,
messages: Optional[List[Dict[str, Any]]] = None,
) -> Union[str, Any]:
"""Async vision completion."""
+ effective_thinking = self._get_vlm().thinking if thinking is None else thinking
return await self._get_vlm().get_vision_completion_async(
prompt=prompt,
images=images,
- thinking=thinking,
+ thinking=effective_thinking,
tools=tools,
messages=messages,
)
diff --git a/openviking/prompts/templates/memory/entities.yaml b/openviking/prompts/templates/memory/entities.yaml
index ab01affec..2990d70b5 100644
--- a/openviking/prompts/templates/memory/entities.yaml
+++ b/openviking/prompts/templates/memory/entities.yaml
@@ -18,14 +18,17 @@ fields:
- name: category
type: string
description: |
- - Category name in Chinese or English. If English, use lowercase with underscores, max 3 words.
+ - Category name written in {{ language }}.
+ {% if language == 'en' %}Use lowercase with underscores, max 3 words.{% else %}Keep it concise and natural in {{ language }}.{% endif %}
merge_op: immutable
+ searchable: true
- name: name
type: string
description: |
- Entity name in Chinese or English. If English, use lowercase with underscores, max 3 words.
merge_op: immutable
+ searchable: true
- name: content
type: string
diff --git a/openviking/prompts/templates/memory/events.yaml b/openviking/prompts/templates/memory/events.yaml
index e1a6d66a1..ebf726f51 100644
--- a/openviking/prompts/templates/memory/events.yaml
+++ b/openviking/prompts/templates/memory/events.yaml
@@ -17,10 +17,10 @@ enabled: true
# upsert 表示新增或更新(默认行为)
operation_mode: "add_only"
content_template: |
- {{extract_context.get_first_message_time_with_weekday_from_ranges(ranges|default(''))|default('N/A')}} ChatLog:
+ {{ summary }}
+ {{extract_context.get_first_message_time_with_weekday_from_ranges(ranges|default(''))|default('N/A')}} ChatLog:
{{ extract_context.get_event_content(ranges, summary, 0) }}
-
overview_template: |-
# Events Overview
{% if items %}**Date:** {{ extract_context.get_year(items[0].file_content.ranges|default(''))|default('') }}/{{ extract_context.get_month(items[0].file_content.ranges|default(''))|default('') }}/{{ extract_context.get_day(items[0].file_content.ranges|default(''))|default('') }}{% endif %}
@@ -34,25 +34,28 @@ fields:
description: |
Output a concrete noun phrase representing a real-world activity or occurrence.
Rules:
- 1. Can be Chinese or English;
- 2. If English: all lowercase, use underscore instead of space, maximum 3 words;
+ 1. Must be written in {{ language }};
+ 2. {% if language == 'en' %}Use lowercase with underscores instead of spaces, maximum 3 words;{% else %}Keep it concise and natural in {{ language }};{% endif %}
3. Never include any date, time, year or number;
4. Must name the real-world activity/occurrence, NOT the conversation about it;
5. Names ending with _chat, _talk, _conversation, _catchup, _discussion are forbidden;
6. Patterns like "person_chat", "chat_about_xxx", "daily_talk" are forbidden;
7. Output only the event name, no extra explanation.
merge_op: immutable
+ searchable: true
- name: goal
type: string
description: |
Summarize the purpose of the content in 5 words or less
+ searchable: true
- name: summary
type: string
description: |
Based on the content of the above fields, compile a description to outline the complete Fact content.
Use specific year-month-day dates instead of vague terms such as yesterday, last week, and tomorrow.
+ searchable: true
- name: ranges
type: string
diff --git a/openviking/prompts/templates/memory/experiences.yaml b/openviking/prompts/templates/memory/experiences.yaml
index 745470b7c..21f3b1930 100644
--- a/openviking/prompts/templates/memory/experiences.yaml
+++ b/openviking/prompts/templates/memory/experiences.yaml
@@ -14,9 +14,8 @@ fields:
type: string
description: |
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.
+ Must be written in {{ language }}.
+ {% if language == 'en' %}Use lowercase snake_case, max 5 words.{% else %}Use a concise noun phrase, max 15 characters.{% endif %}
Good: "booking_duplicate_handling", "pytest_asyncio_cancel_hang_fix", "重复预订处理".
merge_op: immutable
diff --git a/openviking/prompts/templates/memory/preferences.yaml b/openviking/prompts/templates/memory/preferences.yaml
index d275b93d5..010275243 100644
--- a/openviking/prompts/templates/memory/preferences.yaml
+++ b/openviking/prompts/templates/memory/preferences.yaml
@@ -2,9 +2,12 @@ memory_type: preferences
description: |
User preference memory - captures "what the user likes/dislikes or is accustomed to".
Extract specific preferences the user has expressed across conversations.
+ Keep each preference memory Complete but minimal.
Each preference should be about a specific topic (not generic).
Topics can be: code style, communication style, tools, workflow, food, commute, etc.
Store different topics as separate memory files, do NOT mix unrelated preferences.
+ Each topic should stay small and should not become a second profile.
+ Keep each topic to roughly 3-8 bullets; if it grows beyond that or past 800 characters, split it into semantic subtopics.
directory: "viking://user/{{ user_space }}/memories/preferences"
filename_template: "{{ user }}/{{ topic }}.md"
enabled: true
@@ -23,19 +26,27 @@ fields:
description: |
Username for the preference owner
merge_op: immutable
+ searchable: true
- name: topic
type: string
description: |
- Preference topic in Chinese or English. If English, use lowercase with underscores, max 3 words.
+ Preference topic written in {{ language }}.
+ {% if language == 'en' %}Use lowercase with underscores, max 3 words.{% else %}Keep the topic concise and natural in {{ language }}.{% endif %}
Preference topic used to uniquely identify this preference memory.
Should be a semantic topic description such as "Python code style", "Communication style", "Food preference", "Commute preference", etc.
Different preference topics should be stored as separate memories, do not mix unrelated preferences.
+ If a topic becomes too broad, split it into smaller semantic subtopics.
merge_op: immutable
+ searchable: true
- name: content
type: string
description: |
Preference content in Markdown format describing "what the user prefers/is accustomed to".
+ Rewrite each topic into a Complete but minimal version rather than letting it grow indefinitely.
+ Keep each topic concise, usually 3-8 bullets; if it exceeds 8 bullets or 800 characters, split it into semantic subtopics.
+ Use compact statements, and when useful include light evidence such as "evidenced by ... (as of YYYY-MM-DD)".
+ Slight identity context is allowed only when it helps explain the preference, but this memory should not become a second profile.
Example: "User has shown clear preferences for Python code style in multiple conversations: dislikes using type hints, considers them redundant; requires concise function comments, limited to 1-2 lines; prefers direct implementation, avoids excessive fallbacks and over-engineering."
merge_op: patch
diff --git a/openviking/prompts/templates/memory/profile.yaml b/openviking/prompts/templates/memory/profile.yaml
index 3786c7cbf..4a84e1fd9 100644
--- a/openviking/prompts/templates/memory/profile.yaml
+++ b/openviking/prompts/templates/memory/profile.yaml
@@ -1,18 +1,25 @@
memory_type: profile
description: |
# Task Objective
- User profile memory - captures "who the user is" as a person.
- Extract relatively stable personal attributes that define the user's identity, work style, and preferences.
- Include: profession, experience level, technical background, communication style, work habits, etc.
+ User profile memory - captures an identity summary of who the user is as a person.
+ Extract relatively stable personal attributes that define the user's identity at a high level.
+ Keep the result Complete but minimal.
+ Profile should stay as an identity summary, not a place for endlessly growing details.
Do NOT include transient conversation content or temporary mood states.
# Rules
+ - Rewrite the full profile into a Complete but minimal version each time
+ - Do not append to the old profile
+ - Keep the profile to 5-8 bullets total
- Each item: self-contained, declarative sentence, < 30 words
- Extract only facts stated/confirmed by user; no guesses
- Focus on persistent information, not temporary situations
+ - Keep only high-level identity facts in profile
+ - If preference, habit, taste, workflow style, or other reusable behavioral detail would make profile grow, migrate it to preferences instead
+ - Do not keep concrete preference examples in profile
- Forbidden: events, only-assistant content, sensitive/private info, trivial updates
- - Merge similar items; keep latest if conflicting
-
+ - Merge similar items; keep latest if conflicting
+
directory: "viking://user/{{ user_space }}/memories"
filename_template: "profile.md"
@@ -21,10 +28,14 @@ fields:
- name: content
type: string
description: |
- User profile content in Markdown format describing "who the user is".
- Includes relatively stable personal attributes: profession, experience, tech stack, communication style, etc.
+ User profile content in Markdown format describing "who the user is" as an identity summary.
+ Rewrite the full profile as a Complete but minimal version, rather than extending the old text.
+ Keep only the most important high-level identity facts, with 5-8 bullets total.
Only record objective statuses, do not record events or similar information.
- [IMPORTANT] For changeable statuses, must include the last updated time in the format: (as of 2023-06-09)
+ If reusable preference-oriented details overflow profile scope, migrate them to preferences instead.
+ Even though this field uses patch semantics, you may use patch to rewrite the whole profile into a shorter minimal version when needed.
+ Prefer large-scale replacement over local edits when compressing an oversized profile.
+ [IMPORTANT] For changeable statuses, must include the last updated time in the format: (as of 2023-06-09)
Example:
# Caroline
- Date of birth
diff --git a/openviking/prompts/templates/memory/skills.yaml b/openviking/prompts/templates/memory/skills.yaml
index b2a1670ae..82d06e2ff 100644
--- a/openviking/prompts/templates/memory/skills.yaml
+++ b/openviking/prompts/templates/memory/skills.yaml
@@ -91,4 +91,4 @@ fields:
- "### Good Cases" - successful usage examples
- "### Bad Cases" - failed usage examples
Headings must be in English, content can be in target language.
- merge_op: patch
\ No newline at end of file
+ merge_op: patch
diff --git a/openviking/prompts/templates/memory/trajectories.yaml b/openviking/prompts/templates/memory/trajectories.yaml
index d369a93c5..5c0209b32 100644
--- a/openviking/prompts/templates/memory/trajectories.yaml
+++ b/openviking/prompts/templates/memory/trajectories.yaml
@@ -16,9 +16,8 @@ fields:
type: string
description: |
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.
+ Must be written in {{ language }}.
+ {% if language == 'en' %}Use lowercase snake_case, max 5 words.{% else %}Use a concise noun phrase, max 15 characters.{% endif %}
Do not create near-duplicate names for the same task.
Good: "duplicate_request_resolution", "pytest_asyncio_cancel_hang_fix", "重复请求处理".
merge_op: immutable
diff --git a/openviking/server/identity.py b/openviking/server/identity.py
index e9a5a9c0b..116be5da0 100644
--- a/openviking/server/identity.py
+++ b/openviking/server/identity.py
@@ -113,6 +113,7 @@ class ToolContext:
default_search_uris: List[str] = field(default_factory=list)
transaction_handle: Optional[Any] = None
read_file_contents: Optional[Any] = None # 用于记录已读取的文件内容
+ page_id_map: Optional[Any] = None # PageIdMap for annotating read results
@property
def user(self):
diff --git a/openviking/server/routers/content.py b/openviking/server/routers/content.py
index 544c43e23..79d1d5b2b 100644
--- a/openviking/server/routers/content.py
+++ b/openviking/server/routers/content.py
@@ -87,9 +87,10 @@ async def read(
text = None
if text:
- from openviking.session.memory.utils.content import deserialize_content
+ from openviking.session.memory.utils.memory_file_utils import MemoryFileUtils
- result = deserialize_content(text)
+ mf = MemoryFileUtils.read(text)
+ result = mf.content
return Response(status="ok", result=result)
diff --git a/openviking/server/routers/relations.py b/openviking/server/routers/relations.py
index ce9b533f6..b1ad890ac 100644
--- a/openviking/server/routers/relations.py
+++ b/openviking/server/routers/relations.py
@@ -75,3 +75,26 @@ async def unlink(
to_uri = resolve_path_variables(request.to_uri)
await service.relations.unlink(from_uri, to_uri, ctx=_ctx)
return Response(status="ok", result={"from": from_uri, "to": to_uri})
+
+
+class BuildGraphRequest(BaseModel):
+ """Request model for build_graph."""
+
+ space_uris: List[str]
+ output_uri: str
+
+
[email protected]("/build_graph")
+async def build_graph(
+ request: BuildGraphRequest,
+ _ctx: RequestContext = Depends(get_request_context),
+):
+ """Generate a self-contained HTML graph from multiple memory roots into one output file."""
+ from openviking.session.memory.graph_view import MemoryGraph
+
+ service = get_service()
+ space_uris = [resolve_path_variables(uri) for uri in request.space_uris]
+ output_uri = resolve_path_variables(request.output_uri)
+ graph = MemoryGraph(viking_fs=service.viking_fs)
+ graph_path = await graph.build_graph(space_uris, output_uri, ctx=_ctx)
+ return Response(status="ok", result={"graph_uri": graph_path})
diff --git a/openviking/service/reindex_executor.py b/openviking/service/reindex_executor.py
index 42ebd1de8..eb89e1e95 100644
--- a/openviking/service/reindex_executor.py
+++ b/openviking/service/reindex_executor.py
@@ -24,7 +24,7 @@ from openviking.core.namespace import (
from openviking.server.dependencies import get_service
from openviking.server.identity import RequestContext
from openviking.service.task_tracker import get_task_tracker
-from openviking.session.memory.utils.messages import parse_memory_file_with_fields
+from openviking.session.memory.utils.memory_file_utils import MemoryFileUtils
from openviking.storage.queuefs.embedding_msg_converter import EmbeddingMsgConverter
from openviking.storage.queuefs.semantic_msg import SemanticMsg
from openviking.storage.queuefs.semantic_processor import SemanticProcessor
@@ -1088,8 +1088,8 @@ class ReindexExecutor:
for file_uri in file_uris:
counters.scanned_records += 1
body = await self._safe_read_text(file_uri, ctx=ctx)
- parsed_body = parse_memory_file_with_fields(body) if body else {"content": ""}
- memory_content = parsed_body.get("content", "")
+ mf = MemoryFileUtils.read(body) if body else MemoryFile()
+ memory_content = mf.content
existing = await self._fetch_existing_record(uri=file_uri, level=2, ctx=ctx)
abstract = self._best_non_empty(
self._record_abstract(existing),
diff --git a/openviking/session/compressor_v2.py b/openviking/session/compressor_v2.py
index ab473f88c..3deaf36fe 100644
--- a/openviking/session/compressor_v2.py
+++ b/openviking/session/compressor_v2.py
@@ -20,11 +20,11 @@ from openviking.core.namespace import (
from openviking.message import Message
from openviking.server.identity import RequestContext
from openviking.session.memory import ExtractLoop, MemoryUpdater
-from openviking.session.memory.dataclass import ResolvedOperations
+from openviking.session.memory.dataclass import MemoryFile, ResolvedOperations
from openviking.session.memory.memory_isolation_handler import MemoryIsolationHandler
from openviking.session.memory.memory_updater import MemoryUpdateResult
from openviking.session.memory.utils.json_parser import JsonUtils
-from openviking.session.memory.utils.messages import parse_memory_file_with_fields
+from openviking.session.memory.utils.memory_file_utils import MemoryFileUtils
from openviking.session.memory.utils.uri import render_template
from openviking.storage import VikingDBManager
from openviking.storage.viking_fs import VikingFS, get_viking_fs
@@ -183,7 +183,7 @@ class SessionCompressorV2:
return []
tracer.info("Starting v2 memory extraction from conversation")
- tracer.info(f"messages={JsonUtils.dumps(messages)}")
+ tracer.info(f"origin_messages={JsonUtils.dumps(messages)}")
config = get_openviking_config()
# Initialize default memory files (soul.md, identity.md) if not exist
@@ -214,7 +214,7 @@ class SessionCompressorV2:
lock_manager = get_lock_manager()
transaction_handle = lock_manager.create_handle()
else:
- logger.warning("VikingFS or AGFS not available, running without lock mechanism")
+ logger.debug("AGFS unavailable, running memory extraction without locks")
try:
# Create extract context from messages
@@ -433,11 +433,10 @@ class SessionCompressorV2:
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,
- )
+ from openviking.session.memory.utils.memory_file_utils import MemoryFileUtils
- traj_content = _deser_content(await viking_fs.read_file(traj_uri, ctx=ctx) or "")
+ mf = MemoryFileUtils.read(await viking_fs.read_file(traj_uri, ctx=ctx) or "")
+ traj_content = mf.content
except Exception as e:
logger.warning(f"Failed to read new trajectory {traj_uri}: {e}")
continue
@@ -733,8 +732,7 @@ class SessionCompressorV2:
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
+ from openviking.session.memory.utils.memory_file_utils import MemoryFileUtils
inheritance_map: Dict[str, List[str]] = {}
@@ -767,19 +765,13 @@ class SessionCompressorV2:
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,
- )
- )
+ old_mf = MemoryFileUtils.read(raw, uri=old_uri)
+ operations.delete_file_contents.append(old_mf)
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", [])
+ existing = old_mf.extra_fields.get("source_trajectories", [])
if isinstance(existing, list):
inherited = list(existing)
elif isinstance(existing, str) and existing.strip():
@@ -806,6 +798,7 @@ class SessionCompressorV2:
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.memory_file_utils import MemoryFileUtils
normalized_traj_uris = [uri for uri in traj_uris if uri]
if not normalized_traj_uris:
return
@@ -848,17 +841,10 @@ class SessionCompressorV2:
ctx,
viking_fs,
) -> None:
- from openviking.session.memory.utils.content import (
- deserialize_full,
- serialize_with_metadata,
- )
-
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 {}
+ mf = MemoryFileUtils.read(raw, uri=exp_uri)
- existing = metadata.get("source_trajectories", [])
+ existing = mf.extra_fields.get("source_trajectories", [])
if isinstance(existing, list):
uris = list(existing)
elif isinstance(existing, str) and existing.strip():
@@ -877,9 +863,8 @@ class SessionCompressorV2:
changed = True
if changed:
- metadata["source_trajectories"] = uris
- metadata["content"] = plain_content
- new_raw = serialize_with_metadata(metadata)
+ mf.extra_fields["source_trajectories"] = uris
+ new_raw = MemoryFileUtils.write(mf)
await viking_fs.write_file(exp_uri, new_raw, ctx=ctx)
tracer.info(f"[source_traj] appended {len(traj_uris)} trajectories -> {exp_uri}")
else:
@@ -927,13 +912,12 @@ class SessionCompressorV2:
if old_file:
# Old content existed, this is an update
- raw_before = old_file.plain_content
- parsed = parse_memory_file_with_fields(raw_before)
+ before_content = old_file.content
updates.append(
{
"uri": uri,
"memory_type": memory_type,
- "before": parsed.get("content", raw_before),
+ "before": before_content,
"after": "", # Will be filled after
}
)
@@ -951,16 +935,13 @@ class SessionCompressorV2:
for uri in result.edited_uris:
op = upsert_by_uri.get(uri)
memory_type = op.memory_type if op else self._get_memory_type_from_uri(uri)
- old_content = None
- if op and op.old_memory_file_content:
- old_content = op.old_memory_file_content.plain_content
- raw_before = old_content or ""
- parsed = parse_memory_file_with_fields(raw_before)
+ old_mf = op.old_memory_file_content if op and op.old_memory_file_content else None
+ before_content = old_mf.content if old_mf else ""
updates.append(
{
"uri": uri,
"memory_type": memory_type,
- "before": parsed.get("content", raw_before) if raw_before else "",
+ "before": before_content,
"after": "", # Will be filled after
}
)
@@ -969,16 +950,17 @@ class SessionCompressorV2:
for uri in result.deleted_uris:
deleted_content = None
dc = delete_by_uri.get(uri)
- memory_type = dc.memory_fields.get("memory_type", "unknown") if dc else "unknown"
if dc:
- deleted_content = dc.plain_content
- raw_deleted = deleted_content or ""
- parsed = parse_memory_file_with_fields(raw_deleted)
+ memory_type = dc.memory_type or "unknown"
+ deleted_content = dc.content
+ else:
+ memory_type = "unknown"
+ deleted_content = ""
deletes.append(
{
"uri": uri,
"memory_type": memory_type,
- "deleted_content": parsed.get("content", raw_deleted),
+ "deleted_content": deleted_content,
}
)
@@ -986,9 +968,8 @@ class SessionCompressorV2:
for item in adds + updates:
try:
content = await viking_fs.read_file(uri=item["uri"], ctx=ctx)
- # Strip MEMORY_FIELDS comment from content
- parsed = parse_memory_file_with_fields(content)
- item["after"] = parsed.get("content", content)
+ mf = MemoryFileUtils.read(content)
+ item["after"] = mf.content
except Exception:
pass
diff --git a/openviking/session/memory/__init__.py b/openviking/session/memory/__init__.py
index 61f004177..82e9fb49f 100644
--- a/openviking/session/memory/__init__.py
+++ b/openviking/session/memory/__init__.py
@@ -19,7 +19,7 @@ from openviking.session.memory.extract_loop import (
)
from openviking.session.memory.memory_type_registry import MemoryTypeRegistry
from openviking.session.memory.memory_updater import MemoryUpdater, MemoryUpdateResult
-from openviking.session.memory.merge_op import FieldType, MemoryPatchHandler, MergeOp
+from openviking.session.memory.merge_op import FieldType, MergeOp
from openviking.session.memory.schema_model_generator import (
SchemaModelGenerator,
SchemaPromptGenerator,
@@ -56,8 +56,6 @@ __all__ = [
# Schema models
"SchemaModelGenerator",
"SchemaPromptGenerator",
- # Patch
- "MemoryPatchHandler",
# Updater
"MemoryUpdater",
"MemoryUpdateResult",
diff --git a/openviking/session/memory/agent_experience_context_provider.py b/openviking/session/memory/agent_experience_context_provider.py
index 84cbd159f..8481e6f6c 100644
--- a/openviking/session/memory/agent_experience_context_provider.py
+++ b/openviking/session/memory/agent_experience_context_provider.py
@@ -10,20 +10,19 @@ No tool calls — all context is prefetched. Top-3 candidates also include their
source_trajectories as grounding material.
"""
-from typing import Any, Dict, List
-
import jinja2
+from typing import Any, Dict, List, Optional
from openviking.core.namespace import to_agent_space, to_user_space
from openviking.server.identity import RequestContext, ToolContext
-from openviking.session.memory.dataclass import MemoryFileContent
+from openviking.session.memory.dataclass import MemoryFile
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.session.memory.tools import add_tool_call_pair_to_messages
+from openviking.session.memory.utils.memory_file_utils import MemoryFileUtils
from openviking.storage.viking_fs import VikingFS
+from openviking.telemetry import tracer
from openviking_cli.utils import get_logger
logger = get_logger(__name__)
@@ -133,49 +132,48 @@ All memory content must be written in {output_language}.
for uri in recent_uris:
try:
raw = await viking_fs.read_file(uri, ctx=ctx) or ""
- results.append({"uri": uri, "content": deserialize_content(raw)})
+ mf = MemoryFileUtils.read(raw, uri=uri)
+ result = mf.to_metadata()
+ result["content"] = mf.content
+ result["uri"] = uri
+ results.append(result)
except Exception as e:
- logger.warning(f"Failed to read source trajectory {uri}: {e}")
+ tracer.error(f"Failed to read source trajectory {uri}: {e}")
return results
+ def _build_context_result(
+ self,
+ *,
+ uri: str,
+ context_role: str,
+ result: Optional[Dict[str, Any]] = None,
+ memory_file: Optional[MemoryFile] = None,
+ ) -> Dict[str, Any]:
+ payload = dict(result or {})
+ if memory_file is not None:
+ payload = memory_file.to_metadata()
+ payload["content"] = memory_file.content
+ payload["uri"] = uri
+ payload["context_role"] = context_role
+ return payload
+
async def prefetch(self) -> List[Dict]:
if not isinstance(self.messages, list):
- logger.warning(f"Expected List[Message], got {type(self.messages)}")
+ tracer.error(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}")
+ candidate_uris = await self.search_files(
+ query=self.trajectory_summary[:500] or "experience",
+ search_uris=[experience_dir],
+ limit=SEARCH_TOP_K,
+ )
if not candidate_uris:
try:
@@ -193,77 +191,78 @@ All memory content must be written in {output_language}.
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}")
+ tracer.error(f"Failed to list experiences in {experience_dir}: {e}")
+
+ prefetch_messages: List[Dict[str, Any]] = [self._build_conversation_message()]
+ add_tool_call_pair_to_messages(
+ messages=prefetch_messages,
+ call_id="new-trajectory",
+ tool_name="read",
+ params={"uri": self.trajectory_uri},
+ result=self._build_context_result(
+ uri=self.trajectory_uri,
+ context_role="new_trajectory",
+ result={
+ "memory_type": "trajectories",
+ "content": self.trajectory_summary,
+ },
+ ),
+ )
+ call_id_seq = 0
- # 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}")
+ result = await self.read_file(exp_uri)
+ if result is None:
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", "")
+ mf = self._read_file_contents.get(exp_uri)
+ if not mf:
+ continue
- section = f"### Experience {idx + 1}: `{exp_name}`\nURI: `{exp_uri}`\n\n{body}"
+ add_tool_call_pair_to_messages(
+ messages=prefetch_messages,
+ call_id=call_id_seq,
+ tool_name="read",
+ params={"uri": exp_uri},
+ result=self._build_context_result(
+ uri=exp_uri,
+ context_role="candidate_experience",
+ result=result,
+ ),
+ )
+ call_id_seq += 1
- # 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)}]
+ source_trajs = await self._load_source_trajectories(
+ exp_uri, mf.extra_fields, viking_fs, ctx
+ )
+ for source_idx, source_result in enumerate(source_trajs):
+ source_uri = source_result["uri"]
+ add_tool_call_pair_to_messages(
+ messages=prefetch_messages,
+ call_id=f"source-{idx}-{source_idx}",
+ tool_name="read",
+ params={"uri": source_uri},
+ result=self._build_context_result(
+ uri=source_uri,
+ context_role="candidate_source_trajectory",
+ result=source_result,
+ ),
+ )
+
+ prefetch_messages.append(
+ {
+ "role": "user",
+ "content": "\n".join(
+ [
+ "You have already read the conversation, one `new_trajectory`, candidate experience memories, and optional `candidate_source_trajectory` references.",
+ "Treat `new_trajectory` as the new execution to incorporate.",
+ "Treat `candidate_experience` as existing memories you may update, replace, or skip.",
+ "Treat `candidate_source_trajectory` as reference-only context for understanding a candidate experience; do not modify it directly.",
+ "Based on the above, decide whether to **Update**, **Replace**, **Create**, or **Skip**. Output JSON only.",
+ ]
+ ),
+ }
+ )
+ return prefetch_messages
diff --git a/openviking/session/memory/dataclass.py b/openviking/session/memory/dataclass.py
index 3d86a4771..75a785cf6 100644
--- a/openviking/session/memory/dataclass.py
+++ b/openviking/session/memory/dataclass.py
@@ -5,8 +5,11 @@ Core domain data classes for memory system.
"""
import json
+import re
from datetime import datetime
+from enum import Enum
from typing import (
+ Annotated,
Any,
Dict,
List,
@@ -19,7 +22,7 @@ from typing import (
get_type_hints,
)
-from pydantic import BaseModel, Field, model_validator
+from pydantic import BaseModel, Field, WithJsonSchema, model_validator
from openviking.session.memory.merge_op.base import (
FieldType,
@@ -29,6 +32,109 @@ from openviking.session.memory.merge_op.base import (
T = TypeVar("T")
+# ============================================================================
+# Link Type and Link Models
+# ============================================================================
+
+
+LINK_TYPE_DEFAULT = "related_to"
+_LINK_TYPE_RE = re.compile(r"^[a-z]+(?:_[a-z]+){0,2}$")
+
+
+class LinkType(str, Enum):
+ """Legacy predefined link labels kept for compatibility in tests/call sites."""
+
+ RELATED_TO = LINK_TYPE_DEFAULT
+ BELONGS_TO = "belongs_to"
+ CAUSED_BY = "caused_by"
+ DERIVED_FROM = "derived_from"
+ CONTRADICTS = "contradicts"
+ EVOLVED_FROM = "evolved_from"
+
+
+class WikiLink(BaseModel):
+ """Link output by LLM during extraction, using temporary page_ids.
+
+ f and t use WithJsonSchema to appear as required int in the JSON schema
+ sent to the LLM, but parse as Optional[int] to tolerate null values.
+ Invalid links (null f/t) are filtered in _resolve_links.
+ """
+
+ @model_validator(mode="before")
+ @classmethod
+ def normalize_link_fields(cls, data: Any) -> Any:
+ if isinstance(data, dict):
+ raw_link_type = data.get("link_type")
+ if raw_link_type is not None:
+ normalized = str(raw_link_type).strip().lower().replace("-", "_").replace(" ", "_")
+ if _LINK_TYPE_RE.fullmatch(normalized):
+ data["link_type"] = normalized
+ else:
+ data["link_type"] = LINK_TYPE_DEFAULT
+
+ raw_weight = data.get("weight")
+ if raw_weight is not None:
+ try:
+ data["weight"] = min(1.0, max(0.0, float(raw_weight)))
+ except (TypeError, ValueError):
+ data["weight"] = 0.5
+ return data
+
+ f: Annotated[Optional[int], WithJsonSchema({"type": "integer"})] = Field(
+ ..., description="From page_id. Use the page_id from the item's 'page_id' field."
+ )
+ t: Annotated[Optional[int], WithJsonSchema({"type": "integer"})] = Field(
+ ..., description="To page_id. Use the page_id from the item's 'page_id' field."
+ )
+ link_type: str = Field(
+ LINK_TYPE_DEFAULT,
+ description=(
+ "A short relation label describing how the source relates to the target. "
+ "Prefer one of these lowercase snake_case values: belongs_to, related_to, "
+ "derived_from, caused_by, contradicts, evolved_from. "
+ "Use belongs_to for part-of/profile membership, related_to for general association, "
+ "derived_from for extracted/summary facts, caused_by for direct causation, "
+ "contradicts for mutually inconsistent facts, and evolved_from for time-based changes. "
+ "Do not invent new link_type values unless absolutely necessary."
+ ),
+ )
+ weight: float = Field(
+ 0.5,
+ description=(
+ "Relative ranking score from 0 to 1; use higher values for the best link "
+ "when multiple links compete for the same anchor or attention."
+ ),
+ )
+ match_text: Annotated[
+ Optional[str],
+ WithJsonSchema({"anyOf": [{"type": "string"}, {"type": "null"}]}),
+ ] = Field(
+ ...,
+ description=(
+ "A single WORD from the original conversation to be linkified. "
+ "This field must always be included in link output. "
+ "Use a single exact word from the original conversation whenever possible; "
+ "only use null when no valid single-word anchor exists. "
+ "Rules: (1) must be a single word only (NOT a phrase or multi-word text); "
+ "(2) must exist verbatim in the original conversation messages; "
+ "(3) pick the most specific/identifying word"
+ ),
+ )
+ description: str = Field("", description="Brief explanation of the relationship")
+
+
+class StoredLink(BaseModel):
+ """Persisted link in MEMORY_FIELDS, with URIs instead of page_ids."""
+
+ from_uri: str
+ to_uri: str
+ link_type: str = LINK_TYPE_DEFAULT
+ weight: float = 0.5
+ match_text: Optional[str] = None # single word, must exist verbatim in conversation
+ description: str = ""
+ created_at: str = ""
+
+
# ============================================================================
# Memory Field and Schema Definitions
# ============================================================================
@@ -42,6 +148,9 @@ class MemoryField(BaseModel):
description: str = Field("", description="Field description")
merge_op: MergeOp = Field(MergeOp.PATCH, description="Merge strategy")
init_value: Optional[str] = Field(None, description="Initial value for this field")
+ searchable: bool = Field(
+ False, description="Whether this field's value contributes to embedding text"
+ )
class MemoryTypeSchema(BaseModel):
@@ -93,17 +202,59 @@ class MemoryData(BaseModel):
self.fields[field_name] = value
-class MemoryFileContent(BaseModel):
+class MemoryFile(BaseModel):
+ """Typed representation of a memory file's parsed content."""
+
uri: Optional[str] = None
- plain_content: str
- memory_fields: Dict
+ content: str = ""
+ links: List[Dict[str, Any]] = []
+ backlinks: List[Dict[str, Any]] = []
+ memory_type: Optional[str] = None
+ extra_fields: Dict[str, Any] = {}
+
+ def plain_content(self) -> str:
+ from openviking.session.memory.utils.link_renderer import LinkRenderer
+
+ return LinkRenderer.strip_links(self.content)
+
+ @classmethod
+ def from_parsed(cls, uri: Optional[str] = None, parsed: Dict[str, Any] = None) -> "MemoryFile":
+ """Build from parse_memory_file_with_fields result."""
+ if parsed is None:
+ parsed = {}
+ content = parsed.pop("content", "")
+ links = parsed.pop("links", []) or []
+ backlinks = parsed.pop("backlinks", []) or []
+ memory_type = parsed.pop("memory_type", None)
+ # Remaining keys are dynamic schema fields + system fields
+ return cls(
+ uri=uri,
+ content=content,
+ links=links,
+ backlinks=backlinks,
+ memory_type=memory_type,
+ extra_fields=parsed,
+ )
+
+ def to_metadata(self) -> Dict[str, Any]:
+ """Flatten to a dict suitable for serialize_with_metadata."""
+ metadata = dict(self.extra_fields)
+ metadata["content"] = self.content
+ if self.links:
+ metadata["links"] = self.links
+ if self.backlinks:
+ metadata["backlinks"] = self.backlinks
+ if self.memory_type:
+ metadata["memory_type"] = self.memory_type
+ return metadata
class ResolvedOperation(BaseModel):
- old_memory_file_content: Optional[MemoryFileContent]
+ old_memory_file_content: Optional[MemoryFile] = None
memory_fields: Dict
memory_type: str # The memory type (e.g., 'tools', 'skills', 'events')
uris: List[str]
+ page_id: Optional[int] = None # Temporary page_id for link resolution (not persisted)
def is_edit(self):
return self.old_memory_file_content is not None
@@ -111,8 +262,9 @@ class ResolvedOperation(BaseModel):
class ResolvedOperations(BaseModel):
upsert_operations: List[ResolvedOperation]
- delete_file_contents: List[MemoryFileContent]
+ delete_file_contents: List[MemoryFile]
errors: List[str]
+ resolved_links: List[StoredLink] = Field(default_factory=list)
def has_errors(self) -> bool:
return len(self.errors) > 0
@@ -191,6 +343,7 @@ class FaultTolerantBaseModel(BaseModel):
- str -> int/float (目标是数字)
- str/dict -> list (目标是 list)
- list 元素类型容错
+ - 非法 LinkType -> related_to
"""
origin_type = cls.get_origin_type(field_type)
@@ -198,6 +351,13 @@ class FaultTolerantBaseModel(BaseModel):
if value == "None" and origin_type is not str:
return None
+ if isinstance(origin_type, type) and issubclass(origin_type, Enum):
+ if origin_type is LinkType:
+ try:
+ return origin_type(value)
+ except (ValueError, TypeError):
+ return LinkType.RELATED_TO
+
if origin_type is str:
return cls.any_to_str(value)
elif origin_type is int:
diff --git a/openviking/session/memory/extract_loop.py b/openviking/session/memory/extract_loop.py
index 9ef3fad3c..05701baa0 100644
--- a/openviking/session/memory/extract_loop.py
+++ b/openviking/session/memory/extract_loop.py
@@ -13,11 +13,13 @@ from typing import Any, Dict, List, Optional, Tuple
from openviking.models.vlm.base import ToolCall, VLMBase
from openviking.server.identity import RequestContext
from openviking.session.memory.dataclass import (
- MemoryFileContent,
+ MemoryFile,
ResolvedOperation,
ResolvedOperations,
+ StoredLink,
)
from openviking.session.memory.memory_isolation_handler import MemoryIsolationHandler
+from openviking.session.memory.merge_op import MergeOp
from openviking.session.memory.schema_model_generator import (
SchemaModelGenerator,
SchemaPromptGenerator,
@@ -31,10 +33,10 @@ from openviking.session.memory.utils import (
pretty_print_messages,
)
from openviking.session.memory.utils.json_parser import JsonUtils
-from openviking.session.memory.utils.uri import supplement_operation_uris
from openviking.storage.viking_fs import VikingFS, get_viking_fs
from openviking.telemetry import bind_telemetry_stage, tracer
from openviking_cli.utils import get_logger
+from openviking_cli.utils.config import get_openviking_config
logger = get_logger(__name__)
@@ -108,16 +110,25 @@ class ExtractLoop:
iteration = 0
max_iterations = self.max_iterations
final_operations = None
+ raw_links = []
tools_used: List[Dict[str, Any]] = []
# Reset format retry counter for each run
self._format_retry_count = 0
+ patch_repair_count = 0
# 从 provider 获取 schemas(内部自动加载 registry)
schemas = self.context_provider.get_memory_schemas(self.ctx)
# 初始化 schema 生成器(使用 schemas 而非 registry)
- self.schema_model_generator = SchemaModelGenerator(schemas)
- self.schema_prompt_generator = SchemaPromptGenerator(schemas)
+ output_language = self.context_provider.get_output_language()
+ self.schema_model_generator = SchemaModelGenerator(
+ schemas,
+ template_context={"language": output_language},
+ )
+ self.schema_prompt_generator = SchemaPromptGenerator(
+ schemas,
+ template_context={"language": output_language},
+ )
self.schema_model_generator.generate_all_models()
# 预计算工具 schemas
@@ -129,7 +140,11 @@ class ExtractLoop:
]
# 预计算 expected_fields
+ config = get_openviking_config()
+ self._link_enabled = config.memory.link_enabled if config.memory else False
self._expected_fields = ["delete_uris"]
+ if self._link_enabled:
+ self._expected_fields.append("links")
# 获取 ExtractContext(整个流程复用)
self._extract_context = self.context_provider.get_extract_context()
@@ -153,12 +168,31 @@ class ExtractLoop:
schema_str = json.dumps(json_schema, ensure_ascii=False)
messages = []
+ page_id_rules = """
+## Page ID Rules
+- Every memory item you create or edit MUST include "page_id".
+- For existing items, use the page_id shown in read/search results.
+- For new items, assign a unique page_id >= 100.
+- When editing an existing item, reuse its existing page_id.
+"""
+ link_rules = ""
+ if self._link_enabled:
+ link_rules = """
+## Link Rules
+- Link fields `f` and `t` must reference these page_id values.
+- Only create links when the relationship is meaningful and clear from the conversation. Do NOT force links between unrelated items.
+"""
messages.append(
{
"role": "system",
"content": f"""
{self.context_provider.instruction()}
-
+{page_id_rules}
+{link_rules}
+## Read Format Rules
+- The read tool accepts `uri`, optional `offset` (0-indexed), and optional `limit`.
+- Read content is returned in Claude Code format: each visible line is prefixed with `line_number<TAB>`.
+- When you copy text from read results into SEARCH/REPLACE operations, copy the exact text after the line-number prefix. Never include the line-number prefix itself in `search` or `replace`.
## Output Format
The final output of the model must strictly follow the JSON Schema format shown below:
```json
@@ -169,10 +203,14 @@ The final output of the model must strictly follow the JSON Schema format shown
)
await self._mark_cache_breakpoint(messages)
+
# Pre-fetch context via provider
tool_call_messages = await self.context_provider.prefetch()
messages.extend(tool_call_messages)
+ for uri in self.context_provider.read_file_contents:
+ self._extract_context.page_id_map.get_page_id(uri)
+
while iteration < max_iterations:
iteration += 1
tracer.info(f"ReAct iteration {iteration}/{max_iterations}")
@@ -209,7 +247,7 @@ The final output of the model must strictly follow the JSON Schema format shown
# If model returned final operations, check if refetch is needed
if operations is not None:
- final_operations = await self.resolve_operations(operations)
+ final_operations, raw_links = await self.resolve_operations(operations)
# Check if any write_uris target existing files that weren't read
refetch_uris = await self._check_unread_existing_files(final_operations)
if refetch_uris:
@@ -222,9 +260,25 @@ The final output of the model must strictly follow the JSON Schema format shown
tracer.info(f"Extended max_iterations to {max_iterations} for refetch")
continue
+ patch_errors = self._validate_patch_operations(final_operations)
+ if patch_errors and patch_repair_count == 0:
+ patch_repair_count += 1
+ max_iterations += 1
+ self._disable_tools_for_iteration = True
+ messages.append(
+ {
+ "role": "user",
+ "content": self._build_patch_repair_instruction(patch_errors),
+ }
+ )
+ tracer.info(
+ f"Extended max_iterations to {max_iterations} for retry patch repair",
+ console=True,
+ )
+ continue
break
# If no tool calls either, continue to next iteration (don't break!)
- logger.warning(
+ tracer.error(
f"LLM returned neither tool calls nor operations (iteration {iteration}/{max_iterations})"
)
# Add format error message if parse failed (max 1 retry)
@@ -252,19 +306,20 @@ The final output of the model must strictly follow the JSON Schema format shown
tracer.info(f"final_operations={final_operations.model_dump_json(indent=4)}")
+ # Resolve links after the loop completes using the URIs already bound in resolve_operations().
+ await self.finalize_operations(final_operations, raw_links)
+
return final_operations, tools_used
- async def resolve_operations(self, operations) -> ResolvedOperations:
+ async def resolve_operations(self, operations) -> tuple[ResolvedOperations, List]:
tracer.info(f"operations={JsonUtils.dumps(operations)}")
upsert_operations: List[ResolvedOperation] = []
- delete_file_contents: List[MemoryFileContent] = []
+ delete_file_contents: List[MemoryFile] = []
errors: List[str] = []
- # 获取 registry
- registry = self.context_provider._get_registry()
role_scope = self._isolation_handler.get_read_scope()
+ page_id_map = getattr(self._extract_context, "page_id_map", None)
- # 遍历每个 memory_type 字段
for schema in self.context_provider.get_memory_schemas(self.ctx):
memory_type = schema.memory_type
value = getattr(operations, memory_type, None)
@@ -274,50 +329,67 @@ The final output of the model must strictly follow the JSON Schema format shown
items = value if isinstance(value, list) else [value]
for item in items:
- # 转换为 dict
item_dict = dict(item)
item_dict["memory_type"] = memory_type
- # 填充 user_id 和 agent_id
self._isolation_handler.fill_role_ids(item_dict, role_scope=role_scope)
- # 构建 ResolvedOperation
- # 注意:此时 uris 为空,稍后由 supplement_operation_uris 填充
-
+ page_id = item_dict.pop("page_id", None)
resolved_op = ResolvedOperation(
old_memory_file_content=None,
memory_fields=item_dict,
memory_type=memory_type,
uris=[],
+ page_id=page_id,
)
+
+ if page_id is not None and page_id_map is not None:
+ resolved_uri = page_id_map.resolve(page_id)
+ if resolved_uri:
+ resolved_op.uris = [resolved_uri]
+ old_content = self.context_provider.read_file_contents.get(resolved_uri)
+ if old_content is not None:
+ resolved_op.old_memory_file_content = old_content
+ immutable_fields = {
+ field.name
+ for field in schema.fields
+ if field.merge_op != MergeOp.PATCH
+ }
+ for field_name in immutable_fields:
+ if field_name in old_content.extra_fields:
+ resolved_op.memory_fields[field_name] = (
+ old_content.extra_fields[field_name]
+ )
+ else:
+ resolved_op.uris = self._isolation_handler.calculate_memory_uris(
+ memory_type_schema=schema,
+ operation=resolved_op,
+ extract_context=self._extract_context,
+ )
+ else:
+ resolved_op.uris = self._isolation_handler.calculate_memory_uris(
+ memory_type_schema=schema,
+ operation=resolved_op,
+ extract_context=self._extract_context,
+ )
+
upsert_operations.append(resolved_op)
- # 处理 delete_uris - 转换为 delete_file_contents
delete_uris_raw = getattr(operations, "delete_uris", []) or []
for uri_str in delete_uris_raw:
uri_str = uri_str.strip()
if not uri_str:
continue
- # 尝试从已读取的文件内容中获取
old_content = self.context_provider.read_file_contents.get(uri_str)
if old_content:
delete_file_contents.append(old_content)
- # 构建 ResolvedOperations
+ raw_links = getattr(operations, "links", None) or []
resolved = ResolvedOperations(
upsert_operations=upsert_operations,
delete_file_contents=delete_file_contents,
errors=errors,
)
- # 调用 supplement_operation_uris 填充 uris
- if self._isolation_handler:
- supplement_operation_uris(
- operations=resolved,
- registry=registry,
- extract_context=self._extract_context,
- isolation_handler=self._isolation_handler,
- )
- # 填充 old_memory_file_content:从 _read_file_contents 获取已读取的文件内容
for op in upsert_operations:
for uri in op.uris:
old_content = self.context_provider.read_file_contents.get(uri)
@@ -325,7 +397,154 @@ The final output of the model must strictly follow the JSON Schema format shown
op.old_memory_file_content = old_content
break
- return resolved
+ return resolved, raw_links
+
+ async def finalize_operations(self, operations: ResolvedOperations, raw_links: List) -> None:
+ """Register new page_ids and resolve links after refetch is complete.
+
+ Must be called after resolve_operations() and any refetch rounds,
+ so that existing files discovered by refetch get 1-99 page_ids
+ instead of 100+ IDs from register_new_page_id.
+ """
+ if not self._link_enabled:
+ return
+
+ upsert_operations = operations.upsert_operations
+
+ # URIs are already bound in resolve_operations() before any refetch rounds.
+ # finalize_operations only consumes them to register new page_ids and resolve links.
+ page_id_map = self._extract_context.page_id_map
+
+ # Register new page_ids (100+) after URI resolution, using LLM-declared page_id
+ for op in upsert_operations:
+ if op.page_id is not None and op.page_id >= 100:
+ for uri in op.uris:
+ page_id_map.register_new_page_id(uri, op.page_id)
+
+ # Resolve links from WikiLink (page_ids) to StoredLink (URIs)
+ resolved_links = self._resolve_links(raw_links, upsert_operations)
+
+ operations.resolved_links = resolved_links
+
+ def _pair_link_uris(self, from_uris: List[str], to_uris: List[str]) -> List[tuple[str, str]]:
+ namespace_pairs = []
+ seen_pairs = set()
+
+ for from_uri in from_uris:
+ from_namespace = from_uri.split("/memories/", 1)[0]
+ for to_uri in to_uris:
+ if from_uri == to_uri:
+ continue
+ if from_namespace != to_uri.split("/memories/", 1)[0]:
+ continue
+ pair = (from_uri, to_uri)
+ if pair in seen_pairs:
+ continue
+ seen_pairs.add(pair)
+ namespace_pairs.append(pair)
+
+ if namespace_pairs:
+ return namespace_pairs
+
+ all_pairs = []
+ for from_uri in from_uris:
+ for to_uri in to_uris:
+ if from_uri == to_uri:
+ continue
+ pair = (from_uri, to_uri)
+ if pair in seen_pairs:
+ continue
+ seen_pairs.add(pair)
+ all_pairs.append(pair)
+ return all_pairs
+
+ def _resolve_links(self, raw_links: List, upsert_operations: List = None) -> List[StoredLink]:
+ """Resolve WikiLinks with page_ids to StoredLinks with URIs.
+
+ Returns a flat list of StoredLink objects. Each link is stored once.
+ Links go into from_uri's "links" field; backlinks go into to_uri's "backlinks" field.
+ The routing is handled by memory_updater based on which file each link belongs to.
+ """
+ from datetime import datetime, timezone
+
+ if not raw_links:
+ return []
+
+ op_page_map = {}
+ if upsert_operations:
+ for op in upsert_operations:
+ if op.page_id is None or not op.uris:
+ continue
+ op_page_map.setdefault(op.page_id, [])
+ for uri in op.uris:
+ if uri not in op_page_map[op.page_id]:
+ op_page_map[op.page_id].append(uri)
+
+ page_id_map = self._extract_context.page_id_map
+
+ if not page_id_map._id_to_uri and not op_page_map:
+ return []
+
+ resolved_links = []
+ seen_links = set()
+ now = datetime.now(timezone.utc).isoformat()
+
+ for link in raw_links:
+ if link.f is None or link.t is None:
+ tracer.info(f"Skipping link with null page_ids: f={link.f}, t={link.t}")
+ continue
+
+ from_uris = []
+ to_uris = []
+
+ from_uri = page_id_map.resolve(link.f)
+ to_uri = page_id_map.resolve(link.t)
+ if from_uri:
+ from_uris.append(from_uri)
+ if to_uri:
+ to_uris.append(to_uri)
+
+ for uri in op_page_map.get(link.f, []):
+ if uri not in from_uris:
+ from_uris.append(uri)
+ for uri in op_page_map.get(link.t, []):
+ if uri not in to_uris:
+ to_uris.append(uri)
+
+ if not from_uris or not to_uris:
+ tracer.info(
+ f"Skipping link with unresolved page_ids: f={link.f}, t={link.t}, "
+ f"from_uri={from_uris[0] if from_uris else None}, "
+ f"to_uri={to_uris[0] if to_uris else None}, "
+ f"op_page_map_keys={list(op_page_map.keys())}"
+ )
+ continue
+
+ for from_uri, to_uri in self._pair_link_uris(from_uris, to_uris):
+ link_key = (
+ from_uri,
+ to_uri,
+ link.link_type,
+ link.weight,
+ link.match_text,
+ link.description,
+ )
+ if link_key in seen_links:
+ continue
+ seen_links.add(link_key)
+
+ stored_link = StoredLink(
+ from_uri=from_uri,
+ to_uri=to_uri,
+ link_type=link.link_type,
+ weight=link.weight,
+ match_text=link.match_text,
+ description=link.description,
+ created_at=now,
+ )
+ resolved_links.append(stored_link)
+
+ return resolved_links
@tracer("extract_loop.execute_tool_calls")
async def _execute_tool_calls(self, messages, tool_calls, tools_used) -> bool:
@@ -357,7 +576,7 @@ The final output of the model must strictly follow the JSON Schema format shown
has_unknown_tool = True
# Skip if arguments is None
if tool_call.arguments is None:
- logger.warning(f"Tool call {tool_call.name} has no arguments, skipping")
+ tracer.error(f"Tool call {tool_call.name} has no arguments, skipping")
continue
tools_used.append(
@@ -406,7 +625,7 @@ The final output of the model must strictly follow the JSON Schema format shown
tools=tools,
tool_choice=tool_choice,
)
- tracer.info(f"response={response}")
+ tracer.info(f"llm_response={response}")
# print(f'response={response}')
# Log cache hit info
if hasattr(response, "usage") and response.usage:
@@ -468,7 +687,7 @@ The final output of the model must strictly follow the JSON Schema format shown
if error is not None:
print(f"content={content}")
- logger.warning(f"Failed to parse memory operations: {error}")
+ tracer.error(f"Failed to parse memory operations: {error}")
return (None, None)
return (None, operations)
@@ -476,7 +695,7 @@ The final output of the model must strictly follow the JSON Schema format shown
logger.exception(f"Error parsing operations: {e}")
# Case 3: No tool calls and no parsable operations
- print("No tool calls or operations parsed")
+ tracer.error("No tool calls or operations parsed")
return (None, None)
async def _execute_in_parallel(
@@ -539,6 +758,74 @@ The final output of the model must strictly follow the JSON Schema format shown
f"{skeleton}"
)
+ def _validate_patch_operations(self, operations: ResolvedOperations) -> List[Dict[str, Any]]:
+ from openviking.session.memory.merge_op.base import SearchReplaceBlock, StrPatch
+ from openviking.session.memory.merge_op.patch_handler import apply_str_patch
+
+ errors = []
+ read_files = self.context_provider.read_file_contents or {}
+ for operation in operations.upsert_operations:
+ if operation.old_memory_file_content is None:
+ continue
+ current_content = operation.old_memory_file_content.content or ""
+ target_uri = (
+ operation.uris[0] if operation.uris else operation.old_memory_file_content.uri
+ )
+ for field_name, patch_value in operation.memory_fields.items():
+ blocks = []
+ if isinstance(patch_value, StrPatch):
+ blocks = patch_value.blocks
+ elif isinstance(patch_value, dict) and "blocks" in patch_value:
+ for raw_block in patch_value.get("blocks", []):
+ if isinstance(raw_block, SearchReplaceBlock):
+ blocks.append(raw_block)
+ elif isinstance(raw_block, dict):
+ blocks.append(SearchReplaceBlock(**raw_block))
+ if not blocks:
+ continue
+ patch = StrPatch(blocks=blocks)
+ try:
+ applied_content = apply_str_patch(current_content, patch)
+ except Exception:
+ applied_content = current_content
+ if applied_content != current_content:
+ continue
+ for block in blocks:
+ search = block.search or ""
+ if not search:
+ continue
+ found_in = [
+ uri
+ for uri, memory_file in read_files.items()
+ if uri != target_uri and search in (memory_file.content or "")
+ ]
+ errors.append(
+ {
+ "uri": target_uri,
+ "page_id": operation.page_id,
+ "field": field_name,
+ "search": search,
+ "found_in_other_uris": found_in,
+ }
+ )
+ break
+ if errors:
+ tracer.info(f"SEARCH/REPLACE patch validation failed before apply: {errors}")
+ return errors
+
+ def _build_patch_repair_instruction(self, patch_errors: List[Dict[str, Any]]) -> str:
+ details = json.dumps(patch_errors, ensure_ascii=False, indent=2)
+ return (
+ "SEARCH/REPLACE patch could not be applied to the target memory file. "
+ "The SEARCH text must be copied exactly from the read result of the file bound to that operation's page_id. "
+ "Do not use SEARCH text from the conversation or from another page. "
+ "If you copy from numbered read output, exclude the `line_number<TAB>` prefix from SEARCH and REPLACE text. "
+ "If found_in_other_uris is non-empty, diagnose this as a possible page_id mismatch and choose the correct target page_id or rewrite the patch for the current page_id; do not silently move the patch. "
+ "Regenerate the complete operations JSON, including previous successful operations and fixed failed operations. "
+ "Output ONLY the complete JSON object matching the required schema.\n\n"
+ f"Failed patch operations:\n{details}"
+ )
+
async def _add_refetch_results_to_messages(
self,
messages: List[Dict[str, Any]],
@@ -548,7 +835,6 @@ The final output of the model must strictly follow the JSON Schema format shown
# Calculate call_id based on existing tool messages
call_id_seq = len([m for m in messages if m.get("role") == "tool"]) + 1000
for uri, parsed in refetch_uris.items():
- # Add as read tool call + result
add_tool_call_pair_to_messages(
messages=messages,
call_id=call_id_seq,
@@ -568,5 +854,8 @@ The final output of the model must strictly follow the JSON Schema format shown
async def _mark_cache_breakpoint(self, messages):
# 支持 dict 消息和 object 消息
- last_msg = messages[-1]
- last_msg["cache_control"] = {"type": "ephemeral"}
+ # last_msg = messages[-1]
+ # last_msg["cache_control"] = {"type": "ephemeral"}
+
+ # 暂时注释掉,不确定对所有模型的影响
+ pass
diff --git a/openviking/session/memory/graph_view.py b/openviking/session/memory/graph_view.py
new file mode 100644
index 000000000..d577bbcbe
--- /dev/null
+++ b/openviking/session/memory/graph_view.py
@@ -0,0 +1,688 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: AGPL-3.0
+"""
+Memory graph generator — builds a self-contained D3.js force-directed HTML graph
+from all links stored in MEMORY_FIELDS across one or more memory spaces.
+
+Usage:
+ graph = MemoryGraph(viking_fs)
+ path = await graph.gen_graph("viking://user/{space}/memories", ctx=ctx)
+ path = await graph.build_graph(["viking://user/a/memories", "viking://user/b/memories"], "viking://user/default/memories/.graph.html", ctx=ctx)
+"""
+
+import hashlib
+import json
+from typing import Any, Dict, List
+
+from openviking.server.identity import RequestContext
+from openviking.session.memory.utils.link_renderer import LinkRenderer
+from openviking.session.memory.utils.memory_file_utils import MemoryFileUtils
+from openviking.storage.viking_fs import get_viking_fs
+from openviking.telemetry import tracer
+from openviking_cli.utils import get_logger
+
+logger = get_logger(__name__)
+
+# Memory type → color mapping
+TYPE_COLORS = {
+ "profile": "#e74c3c",
+ "preferences": "#3498db",
+ "entities": "#2ecc71",
+ "events": "#f39c12",
+ "skills": "#9b59b6",
+ "identity": "#1abc9c",
+ "tools": "#e67e22",
+ "experiences": "#fd79a8",
+ "trajectories": "#6c5ce7",
+}
+
+
+def _color_for_link_type(link_type: str) -> str:
+ normalized = (link_type or "related_to").strip() or "related_to"
+ digest = hashlib.sha256(normalized.encode("utf-8")).hexdigest()
+ hue = int(digest[:8], 16) % 360
+ return f"hsl({hue}, 72%, 58%)"
+
+
+class MemoryGraph:
+ """Generate an Obsidian-style force-directed graph of memory links."""
+
+ def __init__(self, viking_fs=None):
+ self._viking_fs = viking_fs
+
+ def _get_viking_fs(self):
+ if self._viking_fs is None:
+ self._viking_fs = get_viking_fs()
+ return self._viking_fs
+
+ @staticmethod
+ def _build_content_preview(content: str, limit: int = 600) -> str:
+ text = (content or "").strip()
+ if len(text) <= limit:
+ return text
+ return text[:limit].rstrip() + "…"
+
+ @staticmethod
+ def _is_content_truncated(content: str, limit: int = 600) -> bool:
+ return len((content or "").strip()) > limit
+
+ @staticmethod
+ def _infer_memory_type(uri: str, parsed_memory_type: str) -> str:
+ if parsed_memory_type:
+ return parsed_memory_type
+ parts = [part for part in uri.split("/") if part]
+ if len(parts) >= 2 and parts[-1].endswith(".md"):
+ parent = parts[-2]
+ if parent != "memories":
+ return parent
+ return parts[-1].replace(".md", "")
+ return ""
+
+ async def _collect_graph_data(
+ self,
+ space_uris: List[str],
+ ctx: RequestContext,
+ ) -> tuple[List[Dict[str, Any]], List[Dict[str, Any]]]:
+ viking_fs = self._get_viking_fs()
+ if not viking_fs:
+ raise ValueError("VikingFS not available")
+
+ nodes: Dict[str, Dict[str, Any]] = {}
+ edges: List[Dict[str, Any]] = []
+
+ for space_uri in space_uris:
+ entries = await viking_fs.tree(
+ space_uri,
+ node_limit=1000000,
+ level_limit=None,
+ ctx=ctx,
+ )
+ md_uris = [
+ entry["uri"]
+ for entry in entries
+ if not entry.get("isDir")
+ and entry.get("rel_path", "").endswith(".md")
+ and not entry.get("rel_path", "").endswith("/.overview.md")
+ and not entry.get("rel_path", "").endswith("/.abstract.md")
+ ]
+
+ logger.info(f"[build_graph] Found {len(md_uris)} memory files under {space_uri}")
+
+ for uri in md_uris:
+ try:
+ content = await viking_fs.read_file(uri, ctx=ctx)
+ if not content:
+ continue
+ mf = MemoryFileUtils.read(content, uri=uri)
+ except Exception as e:
+ logger.error(f"Failed to read/parse {uri}: {e}")
+ raise
+
+ inferred_memory_type = self._infer_memory_type(uri, mf.memory_type or "")
+ category = mf.extra_fields.get("category", "")
+ name = mf.extra_fields.get("name", "")
+ label = name if name else uri.split("/")[-1].replace(".md", "")
+
+ rendered_content = LinkRenderer.render_links(mf.content or "", uri, mf.links)
+
+ nodes[uri] = {
+ "id": uri,
+ "uri": uri,
+ "label": label,
+ "memory_type": inferred_memory_type,
+ "category": category,
+ "content_preview": self._build_content_preview(rendered_content),
+ "content_full": rendered_content,
+ "content_truncated": self._is_content_truncated(rendered_content),
+ }
+
+ for link_data in mf.links:
+ if not isinstance(link_data, dict):
+ continue
+ to_uri = link_data.get("to_uri", "")
+ if not to_uri:
+ continue
+ edges.append(
+ {
+ "source": link_data.get("from_uri", uri),
+ "target": to_uri,
+ "link_type": link_data.get("link_type", "related_to"),
+ "weight": float(link_data.get("weight", 1.0)),
+ "description": link_data.get("description", ""),
+ }
+ )
+
+ seen = set()
+ unique_edges = []
+ for e in edges:
+ if e["source"] not in nodes or e["target"] not in nodes:
+ continue
+ key = (e["source"], e["target"], e["link_type"])
+ if key not in seen:
+ seen.add(key)
+ unique_edges.append(e)
+
+ logger.info(f"[build_graph] Built graph: {len(nodes)} nodes, {len(unique_edges)} edges")
+ return list(nodes.values()), unique_edges
+
+ async def gen_graph(
+ self,
+ space_uri: str,
+ ctx: RequestContext,
+ ) -> str:
+ """Scan a memory space, extract links, build graph HTML, write to that space."""
+ graph_path = f"{space_uri.rstrip('/')}/.graph.html"
+ return await self.build_graph([space_uri], graph_path, ctx)
+
+ async def build_graph(
+ self,
+ space_uris: List[str],
+ output_uri: str,
+ ctx: RequestContext,
+ ) -> str:
+ """Scan multiple memory roots, extract links, build graph HTML, and write to output URI."""
+ if not space_uris:
+ raise ValueError("space_uris must not be empty")
+ if not output_uri:
+ raise ValueError("output_uri must not be empty")
+
+ viking_fs = self._get_viking_fs()
+ if not viking_fs:
+ raise ValueError("VikingFS not available")
+
+ nodes, edges = await self._collect_graph_data(space_uris, ctx)
+ html = _render_graph_html(nodes, edges)
+ try:
+ await viking_fs.write_file(output_uri, html, ctx=ctx)
+ tracer.info(f"[build_graph] Generated graph: {output_uri}")
+ except Exception as e:
+ logger.error(f"Failed to write graph {output_uri}: {e}")
+ raise
+
+ return output_uri
+
+
+# ---------------------------------------------------------------------------
+# HTML template — self-contained D3.js force graph (Obsidian-style)
+# ---------------------------------------------------------------------------
+
+
+def _render_graph_html(nodes: List[Dict], edges: List[Dict]) -> str:
+ def _script_safe_json(value: Any) -> str:
+ return json.dumps(value, ensure_ascii=False).replace("</", r"<\/")
+
+ vis_nodes = []
+ for node in nodes:
+ color = TYPE_COLORS.get(node.get("memory_type") or "", "#64748b")
+ vis_nodes.append(
+ {
+ "id": node["id"],
+ "label": node.get("label") or node["id"],
+ "shape": "box",
+ "color": {
+ "background": "#0f172a",
+ "border": color,
+ "highlight": {"background": "#f8fafc", "border": color},
+ "hover": {"background": "#0f172a", "border": color},
+ },
+ "font": {"color": "#f8fafc", "size": 12},
+ "margin": 10,
+ "widthConstraint": {"minimum": 120, "maximum": 180},
+ "memory_type": node.get("memory_type", ""),
+ "category": node.get("category", ""),
+ "uri": node.get("uri", ""),
+ "content_preview": node.get("content_preview", ""),
+ "content_full": node.get("content_full", ""),
+ "content_truncated": node.get("content_truncated", False),
+ }
+ )
+
+ vis_edges = []
+ for idx, edge in enumerate(edges):
+ link_type = edge.get("link_type") or "related_to"
+ color = _color_for_link_type(link_type)
+ vis_edges.append(
+ {
+ "id": f"edge-{idx}",
+ "from": edge["source"],
+ "to": edge["target"],
+ "label": link_type,
+ "color": {"color": color, "highlight": color, "hover": color},
+ "dashes": False,
+ "width": max(2, float(edge.get("weight", 1.0)) * 4),
+ "arrows": "to",
+ "smooth": {"type": "dynamic"},
+ "link_type": link_type,
+ "weight": float(edge.get("weight", 1.0)),
+ "description": edge.get("description", ""),
+ }
+ )
+
+ nodes_json = _script_safe_json(vis_nodes)
+ edges_json = _script_safe_json(vis_edges)
+ type_colors_json = _script_safe_json(TYPE_COLORS)
+
+ return rf"""<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<title>Graph</title>
+<style>
+ * {{ box-sizing: border-box; }}
+ body {{ margin: 0; font-family: -apple-system, BlinkMacSystemFont, sans-serif; background: #0f172a; color: #e2e8f0; }}
+ #app {{ display: grid; grid-template-columns: 1fr 320px; height: 100vh; }}
+ #graph {{ width: 100%; height: 100vh; background: radial-gradient(circle at top, #1e293b 0%, #0f172a 60%); }}
+ #sidebar {{ border-left: 1px solid #334155; background: rgba(15, 23, 42, 0.96); padding: 16px; overflow: auto; }}
+ #sidebar h3 {{ margin: 0 0 12px; font-size: 16px; }}
+ #sidebar .muted {{ color: #94a3b8; font-size: 12px; }}
+ #sidebar .block {{ margin-top: 14px; padding-top: 14px; border-top: 1px solid #1e293b; }}
+ #detail-content {{ white-space: normal; word-break: break-word; font-size: 12px; line-height: 1.6; color: #cbd5e1; }}
+ #detail-content p, #detail-content ul, #detail-content ol, #detail-content pre, #detail-content blockquote, #detail-content h1, #detail-content h2, #detail-content h3, #detail-content h4 {{ margin: 0 0 12px; }}
+ #detail-content ul, #detail-content ol {{ padding-left: 18px; }}
+ #detail-content code {{ font-family: ui-monospace, SFMono-Regular, Menlo, monospace; background: rgba(30, 41, 59, 0.9); padding: 1px 4px; border-radius: 4px; }}
+ #detail-content pre {{ overflow-x: auto; background: rgba(15, 23, 42, 0.72); padding: 10px 12px; border-radius: 8px; }}
+ #detail-content pre code {{ background: transparent; padding: 0; }}
+ #detail-content blockquote {{ border-left: 3px solid #475569; padding-left: 10px; color: #94a3b8; }}
+ #detail-content a {{ color: #60a5fa; text-decoration: underline; cursor: pointer; }}
+ #legend {{ position: fixed; left: 16px; top: 16px; z-index: 10; background: rgba(15, 23, 42, 0.92); border: 1px solid #334155; border-radius: 12px; padding: 12px 14px; max-width: 300px; box-shadow: 0 10px 30px rgba(0,0,0,0.25); }}
+ #legend h4 {{ margin: 0 0 8px; font-size: 13px; }}
+ .legend-item {{ display: flex; align-items: center; gap: 8px; margin: 4px 0; font-size: 12px; color: #cbd5e1; }}
+ .legend-item button {{ all: unset; display: flex; align-items: center; gap: 8px; cursor: pointer; width: 100%; border-radius: 8px; padding: 4px 6px; }}
+ .legend-item button.active {{ background: rgba(51, 65, 85, 0.85); }}
+ .legend-item button.dimmed {{ opacity: 0.55; }}
+ .legend-chip {{ width: 12px; height: 12px; border-radius: 4px; flex: 0 0 12px; }}
+ .legend-line {{ width: 22px; height: 3px; border-radius: 999px; flex: 0 0 22px; }}
+ #tooltip {{ position: fixed; display: none; max-width: 420px; pointer-events: none; z-index: 20; background: rgba(15,23,42,0.96); border: 1px solid #475569; border-radius: 12px; padding: 12px 14px; box-shadow: 0 18px 50px rgba(0,0,0,0.35); }}
+ #tooltip .title {{ font-weight: 600; margin-bottom: 4px; }}
+ #tooltip .meta {{ font-size: 12px; color: #94a3b8; margin-bottom: 8px; }}
+ #tooltip .desc {{ font-size: 12px; line-height: 1.5; color: #cbd5e1; white-space: pre-wrap; word-break: break-word; }}
+</style>
+<script>
+window.__OPENVIKING_VIS_NETWORK_SOURCE__ = "external";
+</script>
+<script src="https://unpkg.com/vis-network/standalone/umd/vis-network.min.js"></script>
+</head>
+<body>
+<div id="legend"></div>
+<div id="tooltip"><div class="title"></div><div class="meta"></div><div class="desc"></div></div>
+<div id="app">
+ <div id="graph"></div>
+ <aside id="sidebar">
+ <div class="block">
+ <div id="detail-title">No selection</div>
+ <div id="detail-meta" class="muted"></div>
+ <div id="detail-content">Move the mouse over a node or edge to inspect it.</div>
+ </div>
+ </aside>
+</div>
+<script>
+const originalNodes = {nodes_json};
+const originalEdges = {edges_json};
+const typeColors = {type_colors_json};
+const tooltip = document.getElementById('tooltip');
+const detailTitle = document.getElementById('detail-title');
+const detailMeta = document.getElementById('detail-meta');
+const detailContent = document.getElementById('detail-content');
+const legend = document.getElementById('legend');
+
+function renderInitError(message) {{
+ const graph = document.getElementById('graph');
+ if (graph) {{
+ graph.innerHTML = `<div style="display:flex;align-items:center;justify-content:center;height:100%;padding:24px;color:#e2e8f0;text-align:center;line-height:1.6;">${{message}}</div>`;
+ }}
+ detailTitle.textContent = 'Graph unavailable';
+ detailMeta.textContent = '';
+ detailContent.textContent = message;
+ legend.innerHTML = '';
+}}
+
+if (!window.vis || !window.vis.DataSet || !window.vis.Network) {{
+ renderInitError('Graph library failed to load. If you opened this file locally, check network access or regenerate it with an embedded graph library bundle.');
+}} else {{
+const nodes = new vis.DataSet(originalNodes);
+const edges = new vis.DataSet(originalEdges);
+const activeMemoryTypes = new Set();
+const activeLinkTypes = new Set();
+
+const network = new vis.Network(
+ document.getElementById('graph'),
+ {{ nodes, edges }},
+ {{
+ autoResize: true,
+ interaction: {{ hover: true, tooltipDelay: 100, navigationButtons: true, keyboard: true }},
+ physics: {{
+ stabilization: {{ iterations: 250, updateInterval: 25 }},
+ barnesHut: {{
+ gravitationalConstant: -7000,
+ centralGravity: 0.18,
+ springLength: 120,
+ springConstant: 0.02,
+ damping: 0.24,
+ avoidOverlap: 0.2,
+ }},
+ minVelocity: 0.75,
+ }},
+ nodes: {{
+ shape: 'box',
+ borderWidth: 2,
+ shadow: false,
+ scaling: {{
+ min: 18,
+ max: 42,
+ label: {{ enabled: true, min: 11, max: 20 }},
+ }},
+ chosen: {{
+ node(values, id, selected) {{
+ if (!selected) {{
+ return;
+ }}
+ values.borderWidth = 4;
+ values.size = Math.max(values.size || 18, 34);
+ values.shadow = true;
+ values.shadowColor = 'rgba(148, 163, 184, 0.55)';
+ values.shadowSize = 28;
+ values.shadowX = 0;
+ values.shadowY = 0;
+ values.color = {{ background: '#f8fafc', border: values.color.border }};
+ }},
+ label(values, id, selected) {{
+ values.size = Math.max(values.size || 12, 18);
+ values.bold = true;
+ if (!selected) {{
+ return;
+ }}
+ values.color = '#0f172a';
+ }},
+ }},
+ }},
+ edges: {{ smooth: true, font: {{ color: '#cbd5e1', size: 10, strokeWidth: 0 }}, arrows: {{ to: {{ enabled: true, scaleFactor: 0.7 }} }} }},
+ }}
+);
+
+function resolveRelativeUri(baseUri, relativeUri) {{
+ if (!relativeUri) {{
+ return '';
+ }}
+ if (relativeUri.startsWith('viking://')) {{
+ return relativeUri;
+ }}
+ if (!baseUri.startsWith('viking://')) {{
+ return relativeUri;
+ }}
+
+ const baseParts = baseUri.split('/');
+ baseParts.pop();
+
+ for (const segment of relativeUri.split('/')) {{
+ if (!segment || segment === '.') {{
+ continue;
+ }}
+ if (segment === '..') {{
+ if (baseParts.length > 3) {{
+ baseParts.pop();
+ }}
+ continue;
+ }}
+ baseParts.push(segment);
+ }}
+
+ return baseParts.join('/');
+}}
+
+function escapeHtml(text) {{
+ return (text || '')
+ .replace(/&/g, '&amp;')
+ .replace(/</g, '&lt;')
+ .replace(/>/g, '&gt;')
+ .replace(/"/g, '&quot;')
+ .replace(/'/g, '&#39;');
+}}
+
+function escapedPreviewText(text, truncated) {{
+ return text || '(empty)';
+}}
+
+function renderMarkdown(text, baseUri = '') {{
+ const source = text || '';
+ if (!source.trim()) {{
+ return '<p>(empty)</p>';
+ }}
+
+ const codeBlocks = [];
+ let html = escapeHtml(source).replace(/```([\s\S]*?)```/g, (_, code) => {{
+ const token = `__CODE_BLOCK_${{codeBlocks.length}}__`;
+ codeBlocks.push(`<pre><code>${{code.trim()}}</code></pre>`);
+ return token;
+ }});
+
+ html = html.replace(/^###\s+(.*)$/gm, '<h3>$1</h3>');
+ html = html.replace(/^##\s+(.*)$/gm, '<h2>$1</h2>');
+ html = html.replace(/^#\s+(.*)$/gm, '<h1>$1</h1>');
+ html = html.replace(/^>\s?(.*)$/gm, '<blockquote>$1</blockquote>');
+ html = html.replace(/\[([^\]]+)\]\(([^)]+)\)/g, (_, label, href) => {{
+ const resolvedUri = resolveRelativeUri(baseUri, href);
+ if (resolvedUri.startsWith('viking://')) {{
+ return `<a href="${{href}}" data-target-uri="${{resolvedUri}}">${{label}}</a>`;
+ }}
+ return `<a href="${{href}}">${{label}}</a>`;
+ }});
+ html = html.replace(/\*\*(.*?)\*\*/g, '<strong>$1</strong>');
+ html = html.replace(/\*(.*?)\*/g, '<em>$1</em>');
+ html = html.replace(/`([^`]+)`/g, '<code>$1</code>');
+
+ const lines = html.split('\\n');
+ const rendered = [];
+ let listItems = [];
+
+ const flushList = () => {{
+ if (listItems.length > 0) {{
+ rendered.push(`<ul>${{listItems.join('')}}</ul>`);
+ listItems = [];
+ }}
+ }};
+
+ for (const line of lines) {{
+ if (/^<h[1-3]>|^<blockquote>|^<pre>/.test(line)) {{
+ flushList();
+ rendered.push(line);
+ continue;
+ }}
+ if (/^[-*]\s+/.test(line)) {{
+ listItems.push(`<li>${{line.replace(/^[-*]\s+/, '')}}</li>`);
+ continue;
+ }}
+ if (!line.trim()) {{
+ flushList();
+ continue;
+ }}
+ flushList();
+ rendered.push(`<p>${{line}}</p>`);
+ }}
+ flushList();
+
+ html = rendered.join('');
+ codeBlocks.forEach((block, index) => {{
+ html = html.replace(`__CODE_BLOCK_${{index}}__`, block);
+ }});
+ return html;
+}}
+
+function showTooltip(x, y, title, meta, desc, baseUri = '') {{
+ tooltip.style.display = 'block';
+ tooltip.querySelector('.title').textContent = title || '';
+ tooltip.querySelector('.meta').textContent = meta || '';
+ tooltip.querySelector('.desc').innerHTML = renderMarkdown(desc || '', baseUri);
+ tooltip.style.left = (x + 16) + 'px';
+ tooltip.style.top = (y + 16) + 'px';
+}}
+
+function hideTooltip() {{
+ tooltip.style.display = 'none';
+}}
+
+function focusNodeById(targetNodeId, options = {{}}) {{
+ if (!targetNodeId || !nodes.get(targetNodeId)) {{
+ return;
+ }}
+ const shouldCenter = options.center === true;
+ network.unselectAll();
+ network.selectNodes([targetNodeId]);
+ if (shouldCenter) {{
+ network.focus(targetNodeId, {{ animation: {{ duration: 350, easingFunction: 'easeInOutQuad' }}, scale: network.getScale() }});
+ }}
+ showNodeDetails(nodes.get(targetNodeId));
+}}
+
+function showNodeDetails(node) {{
+ detailTitle.textContent = node.label || node.id;
+ detailMeta.textContent = `${{node.memory_type || 'unknown'}} · ${{node.uri || ''}}`;
+ detailContent.innerHTML = renderMarkdown(node.content_full || node.content_preview || '', node.uri || '');
+}}
+
+function showEdgeDetails(edge) {{
+ detailTitle.textContent = edge.link_type || 'relation';
+ detailMeta.textContent = `${{edge.link_type}} · weight=${{edge.weight}}`;
+ const sourceUri = edge.from || edge.source || '';
+ const targetUri = edge.to || edge.target || '';
+ detailContent.innerHTML = renderMarkdown(`- from_uri: ${{escapeHtml(sourceUri)}}\n- to_uri: ${{escapeHtml(targetUri)}}\n\n${{escapeHtml(edge.description || '(no description)')}}`);
+}}
+
+function renderLegend() {{
+ const typeItems = Object.entries(typeColors).map(([k, v]) => {{
+ const isActive = activeMemoryTypes.has(k);
+ const activeClass = isActive ? 'active' : (activeMemoryTypes.size > 0 ? 'dimmed' : '');
+ return `<div class="legend-item"><button class="${{activeClass}}" data-memory-type="${{k}}"><span class="legend-chip" style="background:${{v}}"></span><span>${{k}}</span></button></div>`;
+ }}).join('');
+ const linkTypes = [...new Set(originalEdges.map((edge) => edge.link_type).filter(Boolean))].sort();
+ const edgeItems = linkTypes.map((linkType) => {{
+ const color = originalEdges.find((edge) => edge.link_type === linkType)?.color?.color || '#94a3b8';
+ const isActive = activeLinkTypes.has(linkType);
+ const activeClass = isActive ? 'active' : (activeLinkTypes.size > 0 ? 'dimmed' : '');
+ return `<div class="legend-item"><button class="${{activeClass}}" data-link-type="${{linkType}}"><span class="legend-line" style="background:${{color}}"></span><span>${{linkType}}</span></button></div>`;
+ }}).join('');
+ const linkSection = edgeItems ? `<h4 style="margin-top:12px;">Link Types</h4>${{edgeItems}}` : '';
+ legend.innerHTML = `<h4>Memory Types</h4>${{typeItems}}<div class="muted" style="margin:6px 0 10px;">Click types to filter. Click again to clear each selection.</div>${{linkSection}}`;
+ legend.querySelectorAll('button[data-memory-type]').forEach((button) => {{
+ button.addEventListener('click', () => {{
+ const memoryType = button.dataset.memoryType;
+ if (activeMemoryTypes.has(memoryType)) {{
+ activeMemoryTypes.delete(memoryType);
+ }} else {{
+ activeMemoryTypes.add(memoryType);
+ }}
+ applyFilter();
+ renderLegend();
+ }});
+ }});
+ legend.querySelectorAll('button[data-link-type]').forEach((button) => {{
+ button.addEventListener('click', () => {{
+ const linkType = button.dataset.linkType;
+ if (activeLinkTypes.has(linkType)) {{
+ activeLinkTypes.delete(linkType);
+ }} else {{
+ activeLinkTypes.add(linkType);
+ }}
+ applyFilter();
+ renderLegend();
+ }});
+ }});
+}}
+
+function restoreVisibleGraph(selectedNodeIds = []) {{
+ const nodeSelection = new Set(selectedNodeIds);
+ nodes.update(originalNodes.map(node => ({{
+ id: node.id,
+ hidden: false,
+ }})));
+ edges.update(originalEdges.map((edge, index) => ({{
+ id: edge.id || `edge-${{index}}`,
+ hidden: false,
+ }})));
+ network.unselectAll();
+ if (selectedNodeIds.length > 0) {{
+ network.selectNodes(selectedNodeIds);
+ }}
+ network.setOptions({{ physics: false }});
+}}
+
+function applyFilter(shouldFit = false) {{
+ if (activeMemoryTypes.size === 0 && activeLinkTypes.size === 0) {{
+ restoreVisibleGraph();
+ return;
+ }}
+
+ const visibleNodes = originalNodes.filter(node => activeMemoryTypes.size === 0 || activeMemoryTypes.has(node.memory_type));
+ const visibleNodeIds = new Set(visibleNodes.map(node => node.id));
+ const visibleEdges = originalEdges.filter(edge => (activeLinkTypes.size === 0 || activeLinkTypes.has(edge.link_type)) && visibleNodeIds.has(edge.from) && visibleNodeIds.has(edge.to));
+ const visibleEdgeIds = new Set(visibleEdges.map(edge => edge.id));
+
+ nodes.update(originalNodes.map(node => ({{
+ id: node.id,
+ hidden: !visibleNodeIds.has(node.id),
+ }})));
+ edges.update(originalEdges.map((edge, index) => ({{
+ id: edge.id || `edge-${{index}}`,
+ hidden: !visibleEdgeIds.has(edge.id || `edge-${{index}}`),
+ }})));
+
+ network.unselectAll();
+ network.selectNodes(visibleNodes.map(node => node.id));
+ network.setOptions({{ physics: false }});
+}}
+
+detailContent.addEventListener('click', (event) => {{
+ const link = event.target.closest('a[data-target-uri]');
+ if (!link) {{
+ return;
+ }}
+ event.preventDefault();
+ const targetNodeId = link.dataset.targetUri;
+ focusNodeById(targetNodeId, {{ center: true }});
+}});
+
+network.once('stabilized', () => {{
+ network.fit({{ animation: false, padding: 80 }});
+ network.setOptions({{ physics: false }});
+}});
+
+network.on('hoverNode', (params) => {{
+ const node = nodes.get(params.node);
+ const meta = `${{node.memory_type || 'unknown'}} · ${{node.uri || ''}}`;
+ const desc = escapedPreviewText(node.content_preview, node.content_truncated);
+ showTooltip(params.event.srcEvent.clientX, params.event.srcEvent.clientY, node.label || node.id, meta, desc, node.uri || '');
+ showNodeDetails(node);
+}});
+
+network.on('hoverEdge', (params) => {{
+ const edge = edges.get(params.edge);
+ const meta = `${{edge.link_type}} · weight=${{edge.weight}}`;
+ showTooltip(params.event.srcEvent.clientX, params.event.srcEvent.clientY, edge.description || edge.link_type, meta, edge.description || '(no description)', '');
+ showEdgeDetails(edge);
+}});
+
+network.on('blurNode', hideTooltip);
+network.on('blurEdge', hideTooltip);
+network.on('click', (params) => {{
+ if (params.nodes.length > 0) {{
+ const focusNodeId = params.nodes[0];
+ focusNodeById(focusNodeId);
+ return;
+ }}
+
+ if (params.edges.length > 0) {{
+ showEdgeDetails(edges.get(params.edges[0]));
+ return;
+ }}
+
+ restoreVisibleGraph();
+ detailTitle.textContent = 'No selection';
+ detailMeta.textContent = '';
+ detailContent.innerHTML = '<p>Move the mouse over a node or edge to inspect it.</p>';
+}});
+
+renderLegend();
+}}
+</script>
+</body>
+</html>"""
diff --git a/openviking/session/memory/memory_type_registry.py b/openviking/session/memory/memory_type_registry.py
index a4e81077b..c674158a5 100644
--- a/openviking/session/memory/memory_type_registry.py
+++ b/openviking/session/memory/memory_type_registry.py
@@ -209,6 +209,7 @@ class MemoryTypeRegistry:
description=field_data.get("description", ""),
merge_op=MergeOp(field_data.get("merge_op", "patch")),
init_value=field_data.get("init_value"),
+ searchable=field_data.get("searchable", False),
)
fields.append(field)
@@ -290,16 +291,16 @@ class MemoryTypeRegistry:
pass
# Add MEMORY_FIELDS comment with field metadata
- # Template rendering is handled inside serialize_with_metadata
- from openviking.session.memory.utils.content import serialize_with_metadata
+ from openviking.session.memory.dataclass import MemoryFile
+ from openviking.session.memory.utils.memory_file_utils import MemoryFileUtils
- metadata = {
- "memory_type": schema.memory_type,
- **fields_with_init,
- "content": "", # content will come from content_template rendering
- }
- full_content = serialize_with_metadata(
- metadata,
+ mf = MemoryFile(
+ uri=file_uri,
+ memory_type=schema.memory_type,
+ extra_fields=fields_with_init,
+ )
+ full_content = MemoryFileUtils.write(
+ mf,
content_template=schema.content_template,
)
diff --git a/openviking/session/memory/memory_updater.py b/openviking/session/memory/memory_updater.py
index aff12bb50..bdc13570d 100644
--- a/openviking/session/memory/memory_updater.py
+++ b/openviking/session/memory/memory_updater.py
@@ -17,17 +17,16 @@ if TYPE_CHECKING:
from openviking.message import Message
from openviking.server.identity import RequestContext
from openviking.session.memory.dataclass import (
- MemoryFileContent,
+ MemoryFile,
ResolvedOperation,
ResolvedOperations,
+ StoredLink,
)
from openviking.session.memory.memory_type_registry import MemoryTypeRegistry
from openviking.session.memory.merge_op import MergeOpFactory
-from openviking.session.memory.utils import (
- parse_memory_file_with_fields,
- serialize_with_metadata,
-)
-from openviking.session.memory.utils.uri import render_template, supplement_operation_uris
+from openviking.session.memory.page_id_map import PageIdMap
+from openviking.session.memory.utils.memory_file_utils import MemoryFileUtils
+from openviking.session.memory.utils.uri import render_template
from openviking.storage.viking_fs import get_viking_fs
from openviking.telemetry import tracer
from openviking.telemetry.request_wait_tracker import get_request_wait_tracker
@@ -43,6 +42,7 @@ class ExtractContext:
def __init__(self, messages: List[Message]):
self.messages = messages
+ self.page_id_map = PageIdMap()
def get_first_message_time_from_ranges(self, ranges_str: str) -> str | None:
"""根据 ranges 字符串获取第一条消息的时间(YAML 日期格式)"""
@@ -305,7 +305,7 @@ class MemoryUpdater:
viking_fs = self._get_viking_fs()
if not viking_fs:
- logger.warning("VikingFS not available, skipping memory operations")
+ tracer.error("VikingFS not available, skipping memory operations")
return result
# Use provided registry or fall back to self._registry
@@ -314,20 +314,27 @@ class MemoryUpdater:
raise ValueError("MemoryTypeRegistry is required for URI resolution")
# Resolve all URIs first (pass extract_context for template rendering)
- logger.info(f"[MemoryUpdater] applying operations, isolation_handler={isolation_handler}")
+ tracer.info(f"[MemoryUpdater] applying operations, isolation_handler={isolation_handler}")
if operations.has_errors():
for error in operations.errors:
result.add_error("unknown", ValueError(error))
return result
- # 为每个upsert operation填充需要更新的uri列表
- supplement_operation_uris(
- operations,
- self._registry,
- extract_context=extract_context,
- isolation_handler=isolation_handler,
- )
+ unresolved_ops = [
+ resolved_op for resolved_op in operations.upsert_operations if not resolved_op.uris
+ ]
+ if unresolved_ops:
+ missing = [
+ f"{resolved_op.memory_type}(page_id={resolved_op.page_id})"
+ for resolved_op in unresolved_ops
+ ]
+ raise ValueError(
+ f"Cannot apply operations: missing resolved URIs for {', '.join(missing)}"
+ )
+
+ # Distribute resolved_links to corresponding upsert operations
+ self._distribute_links_to_operations(operations)
# Apply unified operations - _apply_edit returns True if edited, False if written
for resolved_op in operations.upsert_operations:
@@ -352,7 +359,7 @@ class MemoryUpdater:
for uri in resolved_op.uris:
result.add_error(uri, e)
- # Apply delete operations (delete_file_contents is List[MemoryFileContent])
+ # Apply delete operations (delete_file_contents is List[MemoryFile])
# 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.
@@ -372,7 +379,20 @@ class MemoryUpdater:
result.add_error(file_content.uri, e)
# Vectorize written and edited memories
- await self._vectorize_memories(result, ctx)
+ uri_memory_type_map = {}
+ for op in operations.upsert_operations:
+ for uri in op.uris:
+ uri_memory_type_map[uri] = op.memory_type
+ await self._vectorize_memories(result, ctx, uri_memory_type_map=uri_memory_type_map)
+
+ # Apply links to endpoint files not covered by upsert_operations
+ if operations.resolved_links:
+ await self._apply_links_to_existing_files(
+ operations.resolved_links,
+ result,
+ ctx,
+ deleted_uris=set(result.deleted_uris),
+ )
tracer.info(f"Memory operations applied: {result.summary()}")
@@ -385,10 +405,13 @@ class MemoryUpdater:
dirs[dir_path] = operation.memory_type
for file_content in operations.delete_file_contents:
dir_path = "/".join(file_content.uri.split("/")[:-1])
- dirs[dir_path] = file_content.memory_fields.get("memory_type", "unknown")
+ dirs[dir_path] = (
+ file_content.extra_fields.get("memory_type")
+ or file_content.memory_type
+ or "unknown"
+ )
for dir, memory_type in dirs.items():
- logger.info(f"[apply_operations] Generating overview for {memory_type} at {dir}")
await self.generate_overview(memory_type, dir, ctx, extract_context)
return result
@@ -405,14 +428,11 @@ class MemoryUpdater:
for uri in resolved_op.uris:
# Always read from disk first to get the latest content,
# so consecutive patches to the same URI see each other's changes.
- old_content = None
+ old_content: Optional[MemoryFile] = None
try:
content = await viking_fs.read_file(uri, ctx=ctx)
if content:
- parsed = parse_memory_file_with_fields(content)
- old_content = MemoryFileContent(
- uri=uri, plain_content=parsed.get("content", ""), memory_fields=parsed
- )
+ old_content = MemoryFileUtils.read(content, uri=uri)
except Exception:
# File doesn't exist yet, that's okay
pass
@@ -430,32 +450,174 @@ class MemoryUpdater:
current_value = None
else:
if field.name == "content":
- current_value = old_content.plain_content
+ current_value = old_content.plain_content()
else:
- current_value = old_content.memory_fields.get(field.name)
+ current_value = old_content.extra_fields.get(field.name)
# Use merge_op to process field value
merge_op = MergeOpFactory.from_field(field)
- new_value = merge_op.apply(current_value, patch_value)
+ try:
+ new_value = merge_op.apply(current_value, patch_value)
+ except Exception as e:
+ tracer.info(
+ f"[memory_updater] Skipping field update after merge_op failure: uri={uri}, field={field.name}, error={e}"
+ )
+ if current_value is None:
+ metadata.pop(field.name, None)
+ else:
+ metadata[field.name] = current_value
+ continue
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:
+ if old_content and old_content.extra_fields:
schema_field_names = {f.name for f in schema.fields} | {"content", "memory_type"}
- for key, val in old_content.memory_fields.items():
+ for key, val in old_content.extra_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(),
+ # Handle links/backlinks fields: merge with existing
+ incoming_links_by_uri = getattr(resolved_op, "_incoming_links_by_uri", {})
+ incoming_backlinks_by_uri = getattr(resolved_op, "_incoming_backlinks_by_uri", {})
+ incoming_links = incoming_links_by_uri.get(uri, [])
+ incoming_backlinks = incoming_backlinks_by_uri.get(uri, [])
+ has_existing_links = old_content is not None
+ if (
+ incoming_links
+ or incoming_backlinks
+ or (has_existing_links and old_content.links)
+ or (has_existing_links and old_content.backlinks)
+ ):
+ from openviking.session.memory.merge_op.link_merge import merge_links
+
+ # Merge links
+ existing_links = old_content.links if has_existing_links else []
+ if incoming_links:
+ merged_links = merge_links(
+ existing_links,
+ [link.model_dump() for link in incoming_links],
+ )
+ metadata["links"] = merged_links
+ elif existing_links:
+ metadata["links"] = existing_links
+
+ # Merge backlinks
+ existing_backlinks = old_content.backlinks if has_existing_links else []
+ if incoming_backlinks:
+ merged_backlinks = merge_links(
+ existing_backlinks,
+ [link.model_dump() for link in incoming_backlinks],
+ )
+ metadata["backlinks"] = merged_backlinks
+ elif existing_backlinks:
+ metadata["backlinks"] = existing_backlinks
+
+ mf = MemoryFile.from_parsed(uri=uri, parsed=metadata)
+ new_full_content = MemoryFileUtils.write(
+ mf,
content_template=schema.content_template,
extract_context=extract_context,
)
await viking_fs.write_file(uri, new_full_content, ctx=ctx)
+ def _distribute_links_to_operations(self, operations: ResolvedOperations) -> None:
+ """Distribute resolved_links to corresponding upsert operations by URI.
+
+ Links go into from_uri's "links" field; backlinks go into to_uri's "backlinks" field.
+ """
+ # Collect all URIs that will be upserted
+ upserted_uris = set()
+ for op in operations.upsert_operations:
+ op._incoming_links_by_uri = {uri: [] for uri in op.uris}
+ op._incoming_backlinks_by_uri = {uri: [] for uri in op.uris}
+ for uri in op.uris:
+ upserted_uris.add(uri)
+
+ # Attach links to their corresponding upsert operations
+ for link in operations.resolved_links:
+ # Forward link -> stored in from_uri's "links"
+ if link.from_uri in upserted_uris:
+ for op in operations.upsert_operations:
+ if link.from_uri in op.uris:
+ op._incoming_links_by_uri[link.from_uri].append(link)
+ break
+ # Backlink -> stored in to_uri's "backlinks"
+ if link.to_uri in upserted_uris:
+ for op in operations.upsert_operations:
+ if link.to_uri in op.uris:
+ op._incoming_backlinks_by_uri[link.to_uri].append(link)
+ break
+
+ async def _apply_links_to_existing_files(
+ self,
+ resolved_links: List[StoredLink],
+ result: MemoryUpdateResult,
+ ctx: RequestContext,
+ deleted_uris: Optional[set[str]] = None,
+ ) -> None:
+ """Apply links to endpoint files that are NOT in the current upsert batch.
+
+ Links go into from_uri's "links" field; backlinks go into to_uri's "backlinks" field.
+ """
+ from openviking.session.memory.merge_op.link_merge import merge_links
+
+ viking_fs = self._get_viking_fs()
+ if not viking_fs:
+ return
+
+ # Collect URIs of files being upserted (links handled in _apply_upsert)
+ upserted_uris = set()
+ deleted_uris = deleted_uris or set()
+ for op in result.written_uris + result.edited_uris:
+ upserted_uris.add(op)
+
+ skipped_uris = upserted_uris | deleted_uris
+
+ # Group remaining links by target file and field
+ # file_links[uri]["links"] = forward links, file_links[uri]["backlinks"] = backlinks
+ file_links: Dict[str, Dict[str, List[StoredLink]]] = {}
+ for link in resolved_links:
+ # Forward link -> from_uri's "links"
+ if link.from_uri not in skipped_uris:
+ file_links.setdefault(link.from_uri, {"links": [], "backlinks": []})
+ file_links[link.from_uri]["links"].append(link)
+ # Backlink -> to_uri's "backlinks"
+ if link.to_uri not in skipped_uris:
+ file_links.setdefault(link.to_uri, {"links": [], "backlinks": []})
+ file_links[link.to_uri]["backlinks"].append(link)
+
+ # Apply links to each remaining file
+ for uri, link_groups in file_links.items():
+ try:
+ content = await viking_fs.read_file(uri, ctx=ctx)
+ if not content:
+ continue
+ mf = MemoryFileUtils.read(content, uri=uri)
+
+ # Merge links
+ if link_groups["links"]:
+ merged_links = merge_links(
+ mf.links,
+ [link.model_dump() for link in link_groups["links"]],
+ )
+ mf.links = merged_links
+
+ # Merge backlinks
+ if link_groups["backlinks"]:
+ merged_backlinks = merge_links(
+ mf.backlinks,
+ [link.model_dump() for link in link_groups["backlinks"]],
+ )
+ mf.backlinks = merged_backlinks
+
+ # Re-serialize with updated links
+ new_full_content = MemoryFileUtils.write(mf)
+ await viking_fs.write_file(uri, new_full_content, ctx=ctx)
+ except Exception as e:
+ tracer.error(f"Failed to apply links to existing file {uri}: {e}")
+
async def _apply_delete(self, uri: str, ctx: RequestContext) -> None:
"""Apply delete operation (uri is already a string)."""
viking_fs = self._get_viking_fs()
@@ -474,12 +636,14 @@ class MemoryUpdater:
self,
result: MemoryUpdateResult,
ctx: RequestContext,
+ uri_memory_type_map: Dict[str, str],
) -> None:
"""Vectorize written and edited memory files.
Args:
result: MemoryUpdateResult with written_uris and edited_uris
ctx: Request context
+ uri_memory_type_map: Mapping from URI to memory_type
"""
if not self._vikingdb:
logger.debug("VikingDB not available, skipping vectorization")
@@ -507,9 +671,39 @@ class MemoryUpdater:
# Read the memory file to get content
content = await viking_fs.read_file(uri, ctx=ctx) or ""
- # Use parse_memory_file_with_fields to strip MEMORY_FIELDS comment
- parsed = parse_memory_file_with_fields(content)
- abstract = parsed.get("content", "")
+ mf = MemoryFileUtils.read(content, uri=uri)
+ abstract = mf.plain_content()
+
+ # Build embedding text from only searchable fields
+ embedding_parts = []
+ if abstract:
+ embedding_parts.append(abstract)
+
+ memory_type = uri_memory_type_map.get(uri)
+
+ if memory_type and self._registry:
+ schema = self._registry.get(memory_type)
+ if schema:
+ searchable_fields = {f.name for f in schema.fields if f.searchable}
+ searchable_data = {}
+ for field_name in searchable_fields:
+ if field_name == "content":
+ continue
+ field_value = mf.extra_fields.get(field_name)
+ if field_value is not None:
+ field_str = (
+ str(field_value)
+ if not isinstance(field_value, str)
+ else field_value
+ )
+ if field_str.strip():
+ searchable_data[field_name] = field_str.strip()
+ if searchable_data:
+ import json
+
+ embedding_parts.append(json.dumps(searchable_data, ensure_ascii=False))
+
+ embedding_text = "\n\n".join(embedding_parts) if embedding_parts else abstract
# Get parent URI
from openviking_cli.utils.uri import VikingURI
@@ -530,7 +724,7 @@ class MemoryUpdater:
user=ctx.user,
account_id=ctx.account_id,
)
- memory_context.set_vectorize(Vectorize(text=content))
+ memory_context.set_vectorize(Vectorize(text=embedding_text))
# Convert to embedding msg and enqueue
embedding_msg = EmbeddingMsgConverter.from_context(memory_context)
@@ -549,7 +743,7 @@ class MemoryUpdater:
logger.debug(f"Enqueued memory for vectorization: {uri}")
except Exception as e:
- logger.warning(f"Failed to vectorize memory {uri}: {e}")
+ tracer.error(f"Failed to vectorize memory {uri}: {e}")
async def generate_overview(
self,
@@ -566,7 +760,7 @@ class MemoryUpdater:
directory: Directory path containing memory files
ctx: Request context
"""
- from openviking.session.memory.utils.messages import parse_memory_file_with_fields
+ from openviking.session.memory.utils.memory_file_utils import MemoryFileUtils
# Get the schema for this memory type
registry = self._registry
@@ -596,7 +790,7 @@ class MemoryUpdater:
md_files.append(f"{base_uri}/{name}")
except Exception as e:
- logger.warning(f"Failed to list files in {directory}: {e}")
+ tracer.error(f"Failed to list files in {directory}: {e}")
return
# If no memory files, delete the .overview.md and the directory if empty
@@ -604,13 +798,11 @@ class MemoryUpdater:
overview_path = f"{directory.rstrip('/')}/.overview.md"
try:
await viking_fs.delete_file(overview_path, ctx=ctx)
- tracer.info(f"[generate_overview] Removed orphaned overview: {overview_path}")
except Exception:
pass
# Try to delete empty directory
try:
await viking_fs.delete_file(directory, ctx=ctx)
- tracer.info(f"[generate_overview] Removed empty directory: {directory}")
except Exception:
pass
return
@@ -620,7 +812,7 @@ class MemoryUpdater:
for file_path in md_files:
try:
content = await viking_fs.read_file(file_path, ctx=ctx)
- parsed = parse_memory_file_with_fields(content)
+ mf = MemoryFileUtils.read(content, uri=file_path)
# Extract filename from path
filename = file_path.split("/")[-1]
@@ -628,11 +820,11 @@ class MemoryUpdater:
items.append(
{
"file_name": filename,
- "file_content": parsed,
+ "file_content": mf.to_metadata(),
}
)
except Exception as e:
- logger.warning(f"Failed to parse {file_path}: {e}")
+ tracer.error(f"Failed to parse {file_path}: {e}")
continue
if not items:
@@ -650,13 +842,12 @@ class MemoryUpdater:
extract_context=extract_context,
)
except Exception as e:
- logger.error(f"Failed to render overview template for {memory_type}: {e}")
+ tracer.error(f"Failed to render overview template for {memory_type}: {e}")
return
# Write .overview.md to the directory
overview_path = f"{directory.rstrip('/')}/.overview.md"
try:
await viking_fs.write_file(overview_path, rendered, ctx=ctx)
- tracer.info(f"[generate_overview] Generated overview: {overview_path}")
except Exception as e:
- logger.error(f"Failed to write overview {overview_path}: {e}")
+ tracer.error(f"Failed to write overview {overview_path}: {e}")
diff --git a/openviking/session/memory/merge_op/__init__.py b/openviking/session/memory/merge_op/__init__.py
index 7141e6ba5..e8c2bafdf 100644
--- a/openviking/session/memory/merge_op/__init__.py
+++ b/openviking/session/memory/merge_op/__init__.py
@@ -16,7 +16,6 @@ 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,
apply_str_patch,
)
@@ -33,7 +32,6 @@ __all__ = [
"SumOp",
"ImmutableOp",
"MergeOpFactory",
- "MemoryPatchHandler",
"PatchParseError",
"apply_str_patch",
]
diff --git a/openviking/session/memory/merge_op/base.py b/openviking/session/memory/merge_op/base.py
index 7c8cc3982..3f678d8df 100644
--- a/openviking/session/memory/merge_op/base.py
+++ b/openviking/session/memory/merge_op/base.py
@@ -55,11 +55,11 @@ class SearchReplaceBlock(BaseModel):
search: str = Field(
...,
- description="The text to replace. Use the smallest unique fragment - usually 2-4 adjacent lines is sufficient. Only include the exact lines that need to change, never the entire section. Preserve the exact indentation from the original. Must be unique in the file.",
+ description="The text to replace. Use the smallest unique fragment - usually 2-4 adjacent lines is sufficient. Only include the exact lines that need to change, never the entire section. Preserve the exact indentation from the original. Must be unique in the file. Choose page_id first. SEARCH must be copied exactly from the read result of the file bound to that page_id. Never use SEARCH text from another memory or page. If the read result includes `line_number<TAB>` prefixes, exclude those prefixes from SEARCH. Multi-line SEARCH must be contiguous; split non-adjacent edits into separate blocks.",
)
replace: str = Field(
...,
- description="The text to replace it with (must be different from search). Use empty string to delete the matched content.",
+ description="The text to replace it with (must be different from search). Use empty string to delete the matched content. Never include `line_number<TAB>` prefixes in REPLACE text.",
)
diff --git a/openviking/session/memory/merge_op/link_merge.py b/openviking/session/memory/merge_op/link_merge.py
new file mode 100644
index 000000000..c0f4fb301
--- /dev/null
+++ b/openviking/session/memory/merge_op/link_merge.py
@@ -0,0 +1,51 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: AGPL-3.0
+"""
+Link merge and dedup logic for MEMORY_FIELDS links field.
+
+Dedup key: from_uri + to_uri + match_text
+Merge rules:
+- Weight conflict: take max
+- link_type and description: latest write wins
+"""
+
+from typing import Any, Dict, List
+
+
+def _dedup_key(link: Dict[str, Any]) -> str:
+ """Compute dedup key for a link."""
+ return f"{link.get('from_uri', '')}|{link.get('to_uri', '')}|{link.get('match_text', '')}"
+
+
+def merge_links(existing_links: List[Dict], new_links: List[Dict]) -> List[Dict]:
+ """
+ Merge link lists with dedup and conflict resolution.
+
+ Dedup key: from_uri + to_uri + match_text
+ Weight conflict: take max
+ link_type and description: latest write wins
+ """
+ link_map: Dict[str, Dict[str, Any]] = {}
+
+ # Process existing links first
+ for link in existing_links:
+ key = _dedup_key(link)
+ link_map[key] = dict(link)
+
+ # Process new links (override existing on conflict)
+ for link in new_links:
+ key = _dedup_key(link)
+ if key in link_map:
+ existing = link_map[key]
+ # Weight: take max
+ existing["weight"] = max(existing.get("weight", 1.0), link.get("weight", 1.0))
+ # link_type and description: latest write wins
+ if "link_type" in link:
+ existing["link_type"] = link["link_type"]
+ if "description" in link:
+ existing["description"] = link["description"]
+ # created_at: keep the original
+ else:
+ link_map[key] = dict(link)
+
+ return list(link_map.values())
diff --git a/openviking/session/memory/merge_op/patch.py b/openviking/session/memory/merge_op/patch.py
index f9c26b79c..06b46c95f 100644
--- a/openviking/session/memory/merge_op/patch.py
+++ b/openviking/session/memory/merge_op/patch.py
@@ -4,7 +4,7 @@
Patch merge operation - SEARCH/REPLACE for strings, direct replace for others.
"""
-from typing import TYPE_CHECKING, Any, Type
+from typing import Any, Type
from openviking.session.memory.merge_op.base import (
FieldType,
@@ -15,9 +15,6 @@ from openviking.session.memory.merge_op.base import (
get_python_type_for_field,
)
-if TYPE_CHECKING:
- from openviking.session.memory.merge_op.patch_handler import MemoryPatchHandler
-
class PatchOp(MergeOpBase):
"""Patch merge operation - SEARCH/REPLACE for strings, direct replace for others."""
@@ -26,7 +23,6 @@ class PatchOp(MergeOpBase):
def __init__(self, field_type: FieldType):
self._field_type = field_type
- self._patch_handler: "MemoryPatchHandler | None" = None
def get_output_schema_type(self, field_type: FieldType) -> Type[Any]:
if field_type == FieldType.STRING:
@@ -35,7 +31,7 @@ class PatchOp(MergeOpBase):
def get_output_schema_description(self, field_description: str) -> str:
if self._field_type == FieldType.STRING:
- return f"PATCH operation for '{field_description}'. Use SEARCH/REPLACE blocks to modify content. You must have read the current content first."
+ return f"PATCH operation for '{field_description}'. Follow the shared SEARCH/REPLACE rules above."
return f"Replace value for '{field_description}'"
def apply(self, current_value: Any, patch_value: Any) -> Any:
diff --git a/openviking/session/memory/merge_op/patch_handler.py b/openviking/session/memory/merge_op/patch_handler.py
index f78d17cd2..88b6ad04a 100644
--- a/openviking/session/memory/merge_op/patch_handler.py
+++ b/openviking/session/memory/merge_op/patch_handler.py
@@ -24,6 +24,12 @@ from enum import Enum
from typing import TYPE_CHECKING, Any, Dict, List, Optional
from openviking.session.memory.merge_op.base import StrPatch
+from openviking.session.memory.utils.line_numbers import (
+ add_line_numbers,
+ every_line_has_line_numbers,
+ extract_start_line_number,
+ strip_line_numbers,
+)
from openviking_cli.utils import get_logger
if TYPE_CHECKING:
@@ -221,43 +227,6 @@ def _find_best_substring_match(line: str, search_str: str) -> tuple[float, str]:
return best_score, best_content
-# ============================================================================
-# Line Number Utilities (from RooCode)
-# ============================================================================
-
-
-def add_line_numbers(content: str, start_line: int = 1) -> str:
- """Add line numbers to content."""
- lines = content.split("\n")
- numbered_lines = [f"{start_line + i} | {line}" for i, line in enumerate(lines)]
- return "\n".join(numbered_lines)
-
-
-def strip_line_numbers(content: str, aggressive: bool = False) -> str:
- """
- Strip line numbers from content.
-
- Args:
- content: Content with line numbers
- aggressive: If True, strip all line numbers regardless of format
- """
- if aggressive:
- # Aggressive: remove anything that looks like a line number at the start
- return re.sub(r"^\s*\d+\s*[|:]\s*", "", content, flags=re.MULTILINE)
- else:
- # Standard: only strip "N | " format
- return re.sub(r"^\d+\s*\|\s*", "", content, flags=re.MULTILINE)
-
-
-def every_line_has_line_numbers(content: str) -> bool:
- """Check if every line in content has a line number."""
- lines = content.split("\n")
- if not lines:
- return False
- # Check if all lines match the pattern "N | " at the start
- return all(re.match(r"^\d+\s*\|\s*", line) for line in lines)
-
-
# ============================================================================
# Marker Utilities (from RooCode)
# ============================================================================
@@ -574,10 +543,9 @@ class MultiSearchReplaceDiffStrategy:
) or (every_line_has_line_numbers(search_content) and replace_content.strip() == "")
if has_all_line_numbers and start_line == 0:
- # Extract start line from first line
- first_line = search_content.split("\n")[0]
- if "|" in first_line:
- start_line = int(first_line.split("|")[0].strip())
+ inferred_start_line = extract_start_line_number(search_content)
+ if inferred_start_line is not None:
+ start_line = inferred_start_line
if has_all_line_numbers:
search_content = strip_line_numbers(search_content)
@@ -876,86 +844,10 @@ class MultiSearchReplaceDiffStrategy:
# ============================================================================
-# MemoryPatchHandler
+# Structured patch application
# ============================================================================
-class MemoryPatchHandler:
- """Handler for applying patches to memory content."""
-
- # Patch format markers
- SEARCH_MARKER = "<<<<<<< SEARCH"
- SPLIT_MARKER = "======="
- REPLACE_MARKER = ">>>>>>> REPLACE"
- LINE_NUMBER_PREFIX = ":start_line:"
-
- def __init__(self, fuzzy_threshold: float = 1.0, buffer_lines: int = 40):
- """
- Initialize the patch handler.
-
- Args:
- fuzzy_threshold: Similarity threshold for fuzzy matching (0.0 to 1.0, default 1.0 = exact match)
- buffer_lines: Number of extra context lines to search (default 40)
- """
- self._strategy = MultiSearchReplaceDiffStrategy(
- fuzzy_threshold=fuzzy_threshold, buffer_lines=buffer_lines
- )
-
- def apply_content_patch(self, original_content: str, patch: str) -> str:
- """
- Apply SEARCH/REPLACE format patch to content.
-
- Patch format:
- <<<<<<< SEARCH
- :start_line:10
- -------
- Original content
- =======
- New content
- >>>>>>> REPLACE
-
- Supports multiple SEARCH/REPLACE blocks in a single patch.
-
- Args:
- original_content: Original content string
- patch: Patch string in SEARCH/REPLACE format
-
- Returns:
- Updated content
-
- Raises:
- PatchParseError: If patch format is invalid
- """
- if not patch or not patch.strip():
- return original_content
-
- # First validate marker sequencing - raise PatchParseError for invalid patches
- valid_seq = validate_marker_sequencing(patch)
- if not valid_seq["success"]:
- raise PatchParseError(valid_seq["error"])
-
- result = self._strategy.apply_diff(original_content, patch)
-
- if result.success:
- return result.content if result.content is not None else original_content
- else:
- error_msg = result.error or "Unknown error"
- logger.warning(
- f"Patch application failed, skipping update: {error_msg}, original_content={original_content}, patch={patch}"
- )
- raise PatchParseError(f"Patch application failed: {error_msg}")
-
- def _extract_replace_content(self, patch: str) -> str:
- """Extract replace content from patch for fallback append."""
- try:
- matches = self._strategy._parse_diff_blocks(patch)
- if matches:
- return matches[-1].get("replaceContent", "")
- except Exception:
- pass
- return patch
-
-
def apply_str_patch(original_content: str, patch: StrPatch) -> str:
"""Apply a StrPatch to original content.
@@ -1044,10 +936,9 @@ def apply_str_patch(original_content: str, patch: StrPatch) -> str:
) or (every_line_has_line_numbers(search_content) and replace_content.strip() == "")
if has_all_line_numbers and start_line == 0:
- # Extract start line from first line
- first_line = search_content.split("\n")[0]
- if "|" in first_line:
- start_line = int(first_line.split("|")[0].strip())
+ inferred_start_line = extract_start_line_number(search_content)
+ if inferred_start_line is not None:
+ start_line = inferred_start_line
if has_all_line_numbers:
search_content = strip_line_numbers(search_content)
@@ -1262,7 +1153,6 @@ def apply_str_patch(original_content: str, patch: StrPatch) -> str:
has_failures = any(not result.get("success", False) for result in diff_results)
if applied_count == 0 and has_failures:
- logger.warning("Patch application failed, skipping update")
raise PatchParseError(
f"Patch application failed: search content not found in original, original_content={original_content}, patch={patch}"
)
diff --git a/openviking/session/memory/page_id_map.py b/openviking/session/memory/page_id_map.py
new file mode 100644
index 000000000..691579b41
--- /dev/null
+++ b/openviking/session/memory/page_id_map.py
@@ -0,0 +1,54 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: AGPL-3.0
+"""
+PageIdMap - Temporary page_id to URI mapping for one ExtractLoop lifecycle.
+
+Existing pages (from prefetch/read): IDs 1-99
+New pages (from LLM output): IDs 100+
+
+A URI can have multiple page_ids pointing to it (e.g. existing page_id=1 from
+prefetch, plus LLM-declared page_id=100 when editing the same page).
+Both IDs resolve to the same URI.
+
+page_id information is injected into LLM context by annotating read results
+with [page_id: N], not by generating a separate mapping table.
+"""
+
+from typing import Dict, Optional
+
+from openviking_cli.utils import get_logger
+
+logger = get_logger(__name__)
+
+
+class PageIdMap:
+ """Temporary mapping from page_id to URI for one ExtractLoop run."""
+
+ def __init__(self):
+ self._next_id: int = 1
+ self._id_to_uri: Dict[int, str] = {}
+ self._uri_to_id: Dict[str, int] = {}
+
+ def get_page_id(self, uri: str) -> int:
+ """Register an existing page (from prefetch/read). Returns page_id in 1-99 range."""
+ if uri in self._uri_to_id:
+ return self._uri_to_id[uri]
+ page_id = self._next_id
+ self._next_id += 1
+ self._id_to_uri[page_id] = uri
+ self._uri_to_id[uri] = page_id
+ return page_id
+
+ def register_new_page_id(self, uri: str, page_id: int) -> None:
+ self._id_to_uri[page_id] = uri
+ if uri not in self._uri_to_id:
+ self._uri_to_id[uri] = page_id
+
+ def resolve(self, page_id: int) -> Optional[str]:
+ """Resolve page_id to URI."""
+ return self._id_to_uri.get(page_id)
+
+ @property
+ def has_links_enabled(self) -> bool:
+ """Whether any pages have been registered (links feature is active)."""
+ return len(self._id_to_uri) > 0
diff --git a/openviking/session/memory/schema_model_generator.py b/openviking/session/memory/schema_model_generator.py
index 26d464e16..2a336b2d3 100644
--- a/openviking/session/memory/schema_model_generator.py
+++ b/openviking/session/memory/schema_model_generator.py
@@ -8,12 +8,13 @@ definitions, with discriminator support for polymorphic fields.
"""
import re
-from typing import Any, Dict, List, Optional, Tuple, Type, Union
+from typing import Annotated, Any, Dict, List, Optional, Tuple, Type, Union
-from pydantic import BaseModel, Field, create_model
+import jinja2
+from pydantic import BaseModel, Field, WithJsonSchema, create_model
from pydantic.config import ConfigDict
-from openviking.session.memory.dataclass import FaultTolerantBaseModel, MemoryTypeSchema
+from openviking.session.memory.dataclass import FaultTolerantBaseModel, MemoryTypeSchema, WikiLink
from openviking.session.memory.memory_isolation_handler import RoleScope
from openviking.session.memory.merge_op import MergeOp, MergeOpFactory
from openviking.session.memory.merge_op.base import FieldType, get_python_type_for_field
@@ -39,13 +40,26 @@ class SchemaModelGenerator:
for polymorphic memory data.
"""
- def __init__(self, schemas: List[MemoryTypeSchema]):
+ def __init__(
+ self,
+ schemas: List[MemoryTypeSchema],
+ template_context: Optional[Dict[str, Any]] = None,
+ ):
self.schemas = schemas
+ self._template_context = dict(template_context or {})
+ self._template_env = jinja2.Environment(autoescape=False)
self._model_cache: Dict[str, Type[BaseModel]] = {}
self._flat_data_models: Dict[str, Type[BaseModel]] = {}
self._union_model: Optional[Type[BaseModel]] = None
self._operations_model: Optional[Type[BaseModel]] = None
+ def _render_description(self, description: str) -> str:
+ if not description:
+ return description
+ if "{{" not in description and "{%" not in description and "{#" not in description:
+ return description
+ return self._template_env.from_string(description).render(**self._template_context)
+
def _map_field_type(self, field_type: FieldType) -> Type[Any]:
"""Map YAML field type to Python type."""
return get_python_type_for_field(field_type)
@@ -95,6 +109,14 @@ class SchemaModelGenerator:
Field(..., description="Agent ID to distinguish which agent's memory to write"),
)
+ field_definitions["page_id"] = (
+ Annotated[int, WithJsonSchema({"type": "integer"})],
+ Field(
+ ...,
+ description="Temporary page_id for identifying the target memory item.",
+ ),
+ )
+
# Add business fields from schema
for field in memory_type.fields:
base_type = self._map_field_type(field.field_type)
@@ -102,14 +124,16 @@ class SchemaModelGenerator:
# Immutable fields: only base type, required
field_definitions[field.name] = (
base_type,
- Field(..., description=field.description),
+ Field(..., description=self._render_description(field.description)),
)
else:
# Mutable fields: Union[base_type, patch_type], optional
merge_op = MergeOpFactory.from_field(field)
patch_type = merge_op.get_output_schema_type(field.field_type)
union_type = Union[base_type, patch_type]
- desc = merge_op.get_output_schema_description(field.description)
+ desc = merge_op.get_output_schema_description(
+ self._render_description(field.description)
+ )
field_definitions[field.name] = (
Optional[union_type],
Field(None, description=desc),
@@ -224,7 +248,10 @@ class SchemaModelGenerator:
List[flat_model], # type: ignore
Field(
default_factory=list,
- description=f"{mt.memory_type} memories: {mt.description} (top-level field, do not nest inside other arrays)",
+ description=(
+ f"{mt.memory_type} memories: {self._render_description(mt.description)} "
+ "(top-level field, do not nest inside other arrays)"
+ ),
),
)
@@ -238,6 +265,23 @@ class SchemaModelGenerator:
Field(default_factory=list, description="Delete operations as URI strings"),
)
+ # Add links field for link extraction (only when enabled globally)
+ from openviking_cli.utils.config import get_openviking_config
+
+ config = get_openviking_config()
+ link_enabled = config.memory.link_enabled if config.memory else False
+ if link_enabled:
+ field_definitions["links"] = (
+ List[WikiLink],
+ Field(
+ default_factory=list,
+ description=(
+ "Links between memory pages. Follow the link rules above. "
+ "Use page_ids for `f` and `t`. Use `weight` from 0 to 1 to rank competing links."
+ ),
+ ),
+ )
+
# Create model using create_model
StructuredMemoryOperations = create_model(
"StructuredMemoryOperations",
@@ -314,8 +358,21 @@ class SchemaPromptGenerator:
based on the YAML schema definitions.
"""
- def __init__(self, schemas: List[MemoryTypeSchema]):
+ def __init__(
+ self,
+ schemas: List[MemoryTypeSchema],
+ template_context: Optional[Dict[str, Any]] = None,
+ ):
self.schemas = schemas
+ self._template_context = dict(template_context or {})
+ self._template_env = jinja2.Environment(autoescape=False)
+
+ def _render_description(self, description: str) -> str:
+ if not description:
+ return description
+ if "{{" not in description and "{%" not in description and "{#" not in description:
+ return description
+ return self._template_env.from_string(description).render(**self._template_context)
def generate_type_descriptions(self) -> str:
"""
@@ -328,7 +385,7 @@ class SchemaPromptGenerator:
for mt in self.schemas:
lines.append(f"\n### {mt.memory_type}")
- lines.append(f"{mt.description}")
+ lines.append(f"{self._render_description(mt.description)}")
# Add URI format information
if mt.directory or mt.filename_template:
@@ -352,7 +409,7 @@ class SchemaPromptGenerator:
lines.append("\n**Fields:**")
for field in mt.fields:
lines.append(
- f"- `{field.name}` ({field.field_type.value}): {field.description}"
+ f"- `{field.name}` ({field.field_type.value}): {self._render_description(field.description)}"
)
return "\n".join(lines)
@@ -373,7 +430,7 @@ class SchemaPromptGenerator:
lines = [f"### {mt.memory_type} Fields"]
for field in mt.fields:
- lines.append(f"- `{field.name}`: {field.description}")
+ lines.append(f"- `{field.name}`: {self._render_description(field.description)}")
return "\n".join(lines)
diff --git a/openviking/session/memory/session_extract_context_provider.py b/openviking/session/memory/session_extract_context_provider.py
index 1829fe39e..731352580 100644
--- a/openviking/session/memory/session_extract_context_provider.py
+++ b/openviking/session/memory/session_extract_context_provider.py
@@ -8,14 +8,14 @@ Session Extract Context Provider - 会话提取 Provider 实现
import json
import os
-from typing import TYPE_CHECKING, Any, Dict, List
+from typing import TYPE_CHECKING, Any, Dict, List, Optional
from openviking.core.namespace import to_agent_space, to_user_space
from openviking.message.part import ToolPart
from openviking.prompts.manager import PromptManager
from openviking.server.identity import RequestContext, ToolContext
from openviking.session.memory.core import ExtractContextProvider
-from openviking.session.memory.dataclass import MemoryFileContent
+from openviking.session.memory.dataclass import MemoryFile
from openviking.session.memory.memory_isolation_handler import MemoryIsolationHandler, RoleScope
from openviking.session.memory.memory_type_registry import (
MemoryTypeRegistry,
@@ -62,7 +62,7 @@ class SessionExtractContextProvider(ExtractContextProvider):
self._schema_directories = None
self._extract_context = None # 缓存 ExtractContext 实例
self._isolation_handler = isolation_handler
- self._read_file_contents: Dict[str, MemoryFileContent] = {}
+ self._read_file_contents: Dict[str, MemoryFile] = {}
# 读取 eager_prefetch 配置
config = get_openviking_config()
self._eager_prefetch = config.memory.eager_prefetch if config.memory else False
@@ -70,11 +70,23 @@ class SessionExtractContextProvider(ExtractContextProvider):
self._ctx = ctx
self._viking_fs = viking_fs
self._transaction_handle = transaction_handle
+ self._link_enabled = config.memory.link_enabled if config.memory else False
@property
- def read_file_contents(self) -> Dict[str, MemoryFileContent]:
+ def read_file_contents(self) -> Dict[str, MemoryFile]:
return self._read_file_contents
+ def get_conversation_text(self) -> str:
+ """Get the full conversation text for match_text validation."""
+ from openviking.message.part import TextPart
+
+ text_parts = []
+ for message in self.messages or []:
+ for part in getattr(message, "parts", []):
+ if isinstance(part, TextPart) and part.text:
+ text_parts.append(part.text)
+ return "\n".join(text_parts)
+
def set_transaction_handle(self, handle):
"""Set transaction handle after lock is acquired."""
self._transaction_handle = handle
@@ -83,8 +95,8 @@ class SessionExtractContextProvider(ExtractContextProvider):
"""获取或创建 ExtractContext 实例(缓存)"""
from openviking.session.memory.memory_updater import ExtractContext
- if self._extract_context is None and self.messages:
- self._extract_context = ExtractContext(self.messages)
+ if self._extract_context is None:
+ self._extract_context = ExtractContext(self.messages or [])
return self._extract_context
def _detect_language(self) -> str:
@@ -100,6 +112,9 @@ class SessionExtractContextProvider(ExtractContextProvider):
return resolve_output_language("\n".join(text_parts))
+ def get_output_language(self) -> str:
+ return self._output_language
+
def instruction(self) -> str:
output_language = self._output_language
goal = f"""You are a memory extraction agent. Your task is to analyze conversations and update memories.
@@ -119,7 +134,6 @@ All memory content MUST be written in {output_language}.
## URI Handling
The system automatically generates URIs based on memory_type and fields. Just provide correct memory_type and fields.
-
"""
return goal
@@ -295,15 +309,73 @@ After exploring, analyze the conversation and output ALL memory write/edit/delet
return self._truncate_prefetch_query_text(query, _PREFETCH_SEARCH_QUERY_MAX_CHARS)
def create_tool_context(self, default_search_uris=[]):
+ extract_context = self.get_extract_context()
tool_ctx = ToolContext(
viking_fs=self._viking_fs,
request_ctx=self._ctx,
transaction_handle=self._transaction_handle,
default_search_uris=default_search_uris,
read_file_contents=self._read_file_contents,
+ page_id_map=extract_context.page_id_map,
)
return tool_ctx
+ async def read_file(self, uri: str) -> Optional[Dict]:
+ """Read a file via MemoryReadTool (auto-registers page_id, fills read_file_contents)."""
+ read_tool = get_tool("read")
+ if not read_tool:
+ return None
+ try:
+ result = await read_tool.execute(self.create_tool_context(), uri=uri)
+ if isinstance(result, dict) and "error" in result:
+ tracer.info(f"Failed to read {uri}: {result['error']}")
+ return None
+ return result
+ except Exception as e:
+ tracer.error(f"Failed to read {uri}: {e}")
+ return None
+
+ async def search_files(
+ self, query: str, search_uris: List[str] = None, limit: int = 5
+ ) -> List[str]:
+ """Search via MemorySearchTool, returns list of URIs."""
+ search_tool = get_tool("search")
+ if not search_tool:
+ return []
+ try:
+ result = await search_tool.execute(
+ viking_fs=self._viking_fs,
+ ctx=self.create_tool_context(search_uris or []),
+ query=query,
+ limit=limit,
+ )
+ if isinstance(result, list):
+ return [m.get("uri", "") for m in result if m.get("uri")]
+ elif isinstance(result, dict) and "memories" in result:
+ return [m.get("uri", "") for m in result.get("memories", []) if m.get("uri")]
+ return []
+ except Exception as e:
+ tracer.error(f"Failed to search: {e}")
+ return []
+
+ async def _append_structured_read_result(
+ self,
+ messages: List[Dict[str, Any]],
+ call_id: int,
+ file_uri: str,
+ ) -> int:
+ result = await self.read_file(file_uri)
+ if result is not None:
+ add_tool_call_pair_to_messages(
+ messages=messages,
+ call_id=call_id,
+ tool_name="read",
+ params={"uri": file_uri},
+ result=result,
+ )
+ return call_id + 1
+ return call_id
+
async def prefetch(self) -> List[Dict]:
"""
执行 prefetch - 从会话消息中提取相关记忆上下文
@@ -314,7 +386,7 @@ After exploring, analyze the conversation and output ALL memory write/edit/delet
messages = self.messages
if not isinstance(messages, list):
- logger.warning(f"Expected List[Message], got {type(messages)}")
+ tracer.error(f"Expected List[Message], got {type(messages)}")
return []
# 先构建 Conversation History user message
@@ -362,8 +434,6 @@ After exploring, analyze the conversation and output ALL memory write/edit/delet
call_id_seq = 0
# Step 2: Execute search for each ls directory (instead of ls)
- read_tool = get_tool("read")
- search_tool = get_tool("search")
# 首先读取所有 .overview.md 文件(截断以避免窗口过大)
# 为 overview 读取创建一个基本的 tool_ctx
@@ -373,74 +443,46 @@ After exploring, analyze the conversation and output ALL memory write/edit/delet
# 批量 search:所有目录一次搜索
if ls_dirs:
- try:
- # 将所有目录作为 target_uri 传入(支持 List[str])
- dir_list = list(ls_dirs)
- search_query = self._build_prefetch_search_query()
- if not search_query:
- search_query = "conversation"
- search_result = await search_tool.execute(
- viking_fs=self._viking_fs,
- ctx=self.create_tool_context(dir_list),
- query=search_query,
- )
- # 处理搜索结果
- if isinstance(search_result, list):
- result_value = [m.get("uri", "") for m in search_result]
- if self._eager_prefetch:
- files_to_read_from_search.extend(result_value)
- elif isinstance(search_result, dict):
- if "error" in search_result:
- result_value = f"Error: {search_result.get('error')}"
- else:
- result_value = []
-
- add_tool_call_pair_to_messages(
- messages=pre_fetch_messages,
- call_id=call_id_seq,
- tool_name="search",
- params={"query": "[Keywords]", "search_uri": dir_list},
- result=result_value,
- )
- call_id_seq += 1
- except Exception as e:
- logger.warning(f"Failed to search in {ls_dirs}: {e}")
+ dir_list = list(ls_dirs)
+ search_query = self._build_prefetch_search_query()
+ if not search_query:
+ search_query = "conversation"
+ search_uris = await self.search_files(
+ query=search_query,
+ search_uris=dir_list,
+ )
+ result_value = search_uris
+ if self._eager_prefetch:
+ files_to_read_from_search.extend(search_uris)
+
+ add_tool_call_pair_to_messages(
+ messages=pre_fetch_messages,
+ call_id=call_id_seq,
+ tool_name="search",
+ params={"query": "[Keywords]", "search_uri": dir_list},
+ result=result_value,
+ )
+ call_id_seq += 1
# 读取单文件 schema 的文件(只对非 add_only 模式)
for file_uri in read_files:
- try:
- result_str = await read_tool.execute(self.create_tool_context(), uri=file_uri)
- add_tool_call_pair_to_messages(
- messages=pre_fetch_messages,
- call_id=call_id_seq,
- tool_name="read",
- params={"uri": file_uri},
- result=result_str,
- )
- # read_file_contents
- call_id_seq += 1
- except Exception as e:
- logger.warning(f"Failed to read {file_uri}: {e}")
+ call_id_seq = await self._append_structured_read_result(
+ messages=pre_fetch_messages,
+ call_id=call_id_seq,
+ file_uri=file_uri,
+ )
# eager_prefetch 模式:读取搜索结果 top-N
- if self._eager_prefetch and read_tool:
- # 只读取 top-N 个文件
+ if self._eager_prefetch:
topn_files = files_to_read_from_search[: self._prefetch_search_topn]
for file_uri in topn_files:
if not file_uri:
continue
- try:
- result_str = await read_tool.execute(self.create_tool_context(), uri=file_uri)
- add_tool_call_pair_to_messages(
- messages=pre_fetch_messages,
- call_id=call_id_seq,
- tool_name="read",
- params={"uri": file_uri},
- result=result_str,
- )
- call_id_seq += 1
- except Exception as e:
- logger.warning(f"Failed to read {file_uri}: {e}")
+ call_id_seq = await self._append_structured_read_result(
+ messages=pre_fetch_messages,
+ call_id=call_id_seq,
+ file_uri=file_uri,
+ )
return pre_fetch_messages
diff --git a/openviking/session/memory/tools.py b/openviking/session/memory/tools.py
index 640dce259..84ee418a7 100644
--- a/openviking/session/memory/tools.py
+++ b/openviking/session/memory/tools.py
@@ -10,9 +10,9 @@ import json
from abc import ABC, abstractmethod
from typing import TYPE_CHECKING, Any, Dict, List, Optional, Union
-from openviking.session.memory.dataclass import MemoryFileContent
-from openviking.session.memory.utils import parse_memory_file_with_fields
-from openviking.session.memory.utils.content import truncate_content
+from openviking.session.memory.dataclass import MemoryFile
+from openviking.session.memory.utils import add_line_numbers, line_count, slice_content_lines
+from openviking.session.memory.utils.memory_file_utils import MemoryFileUtils
from openviking.telemetry import tracer
from openviking_cli.exceptions import NotFoundError
from openviking_cli.utils import get_logger
@@ -49,7 +49,7 @@ def optimize_tool_result(tool_name: str, result: Any) -> Any:
# 对 read 工具返回的 dict,如果包含 content 字段,则截断 content
if tool_name == "read" and isinstance(result, dict) and "content" in result:
result = result.copy()
- result["content"] = truncate_content(result["content"])
+ result["content"] = MemoryFileUtils.truncate_content(result["content"])
return result
@@ -157,6 +157,18 @@ class MemoryReadTool(MemoryTool):
"type": "string",
"description": "Memory URI to read, e.g., 'viking://user/user123/memories/profile.md'",
},
+ "offset": {
+ "type": "integer",
+ "description": "Starting line number to read from (0-indexed)",
+ "default": 0,
+ "minimum": 0,
+ },
+ "limit": {
+ "type": "integer",
+ "description": "Number of lines to read. -1 means read to end",
+ "default": -1,
+ "minimum": -1,
+ },
},
"required": ["uri"],
}
@@ -167,19 +179,39 @@ class MemoryReadTool(MemoryTool):
**kwargs: Any,
) -> Any:
uri = kwargs.get("uri", "")
+ offset = kwargs.get("offset", 0)
+ limit = kwargs.get("limit", -1)
try:
content = await ctx.viking_fs.read_file(
uri,
ctx=ctx.request_ctx,
)
# Parse MEMORY_FIELDS from comment and return dict directly
- parsed = parse_memory_file_with_fields(content)
- ctx.read_file_contents[uri] = MemoryFileContent(
- uri=uri,
- plain_content=parsed.get("content", ""),
- memory_fields=parsed,
- )
- return parsed
+ mf = MemoryFileUtils.read(content, uri=uri)
+ ctx.read_file_contents[uri] = mf
+ # Remove links/backlinks from LLM-visible output (not needed for extraction)
+ llm_result = mf.to_metadata()
+ llm_result.pop("links", None)
+ llm_result.pop("backlinks", None)
+ # Annotate with page_id for link extraction
+ if ctx and ctx.page_id_map:
+ page_id = ctx.page_id_map.get_page_id(uri)
+ if page_id is not None:
+ llm_result["page_id"] = page_id
+ plain_content = mf.plain_content() or ""
+ visible_content = slice_content_lines(plain_content, offset=offset, limit=limit)
+ if visible_content:
+ llm_result["content"] = add_line_numbers(visible_content, start_line=offset + 1)
+ elif line_count(plain_content) == 0:
+ llm_result["content"] = (
+ "<system-reminder>Warning: the file exists but the contents are empty.</system-reminder>"
+ )
+ else:
+ llm_result["content"] = (
+ "<system-reminder>Warning: the file exists but is shorter than the provided "
+ f"offset ({offset + 1}). The file has {line_count(plain_content)} lines.</system-reminder>"
+ )
+ return llm_result
except NotFoundError as e:
tracer.info(f"read not found: {uri}")
return {"error": str(e)}
diff --git a/openviking/session/memory/utils/__init__.py b/openviking/session/memory/utils/__init__.py
index 8920ab100..85fe0f557 100644
--- a/openviking/session/memory/utils/__init__.py
+++ b/openviking/session/memory/utils/__init__.py
@@ -4,13 +4,6 @@
Memory utilities package.
"""
-from openviking.session.memory.utils.content import (
- deserialize_content,
- deserialize_full,
- deserialize_metadata,
- serialize_with_metadata,
- truncate_content,
-)
from openviking.session.memory.utils.json_parser import (
JsonUtils,
_any_to_str,
@@ -28,6 +21,15 @@ from openviking.session.memory.utils.language import (
resolve_output_language_from_conversation,
resolve_with_override,
)
+from openviking.session.memory.utils.line_numbers import (
+ add_line_numbers,
+ every_line_has_line_numbers,
+ extract_start_line_number,
+ line_count,
+ slice_content_lines,
+ split_content_lines,
+ strip_line_numbers,
+)
from openviking.session.memory.utils.messages import (
parse_memory_file_with_fields,
pretty_print_messages,
@@ -36,25 +38,22 @@ from openviking.session.memory.utils.model import (
flat_model_to_dict,
model_to_dict,
)
-from openviking.session.memory.utils.uri import (
- ResolvedOperations,
- generate_uri,
- is_uri_allowed,
- validate_uri_template,
-)
__all__ = [
- # Content serialization
- "serialize_with_metadata",
- "deserialize_content",
- "deserialize_metadata",
- "deserialize_full",
- "truncate_content",
+ # MemoryFile + MemoryFileUtils
+ "MemoryFileUtils",
# Language
"detect_language_from_conversation",
"resolve_output_language",
"resolve_output_language_from_conversation",
"resolve_with_override",
+ "add_line_numbers",
+ "every_line_has_line_numbers",
+ "extract_start_line_number",
+ "line_count",
+ "slice_content_lines",
+ "split_content_lines",
+ "strip_line_numbers",
# Messages
"pretty_print_messages",
"parse_memory_file_with_fields",
@@ -62,7 +61,6 @@ __all__ = [
"generate_uri",
"validate_uri_template",
"is_uri_allowed",
- "ResolvedOperations",
# JSON Parser
"extract_json_content",
"remove_json_trailing_content",
@@ -77,3 +75,23 @@ __all__ = [
"model_to_dict",
"flat_model_to_dict",
]
+
+
+def __getattr__(name: str):
+ if name == "MemoryFileUtils":
+ from openviking.session.memory.utils.memory_file_utils import MemoryFileUtils
+
+ return MemoryFileUtils
+ if name in {"generate_uri", "is_uri_allowed", "validate_uri_template"}:
+ from openviking.session.memory.utils.uri import (
+ generate_uri,
+ is_uri_allowed,
+ validate_uri_template,
+ )
+
+ return {
+ "generate_uri": generate_uri,
+ "is_uri_allowed": is_uri_allowed,
+ "validate_uri_template": validate_uri_template,
+ }[name]
+ raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
diff --git a/openviking/session/memory/utils/content.py b/openviking/session/memory/utils/content.py
deleted file mode 100644
index 664312dbb..000000000
--- a/openviking/session/memory/utils/content.py
+++ /dev/null
@@ -1,189 +0,0 @@
-# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
-# SPDX-License-Identifier: AGPL-3.0
-"""
-Memory content serialization with metadata in HTML comments.
-
-This module handles the serialization and deserialization of memory content
-with metadata stored in HTML comments at the end of the file.
-"""
-
-import json
-import re
-from datetime import datetime
-from typing import Any, Dict, Optional, Tuple
-
-from openviking.session.memory.dataclass import MemoryFileContent
-from openviking.utils.time_utils import parse_iso_datetime
-
-# Regex pattern to match the MEMORY_FIELDS HTML comment
-MEMORY_FIELDS_PATTERN = re.compile(r"\n\n<!--\s*MEMORY_FIELDS\s*\n(.*?)\n-->", re.DOTALL)
-
-# Alternative pattern that might appear at the end without leading newlines
-MEMORY_FIELDS_PATTERN_END = re.compile(r"<!--\s*MEMORY_FIELDS\s*\n(.*?)\n-->$", re.DOTALL)
-
-
-def _serialize_datetime(obj: Any) -> Any:
- """Serialize datetime objects to ISO format strings."""
- if isinstance(obj, datetime):
- return obj.isoformat()
- raise TypeError(f"Object of type {obj.__class__.__name__} is not JSON serializable")
-
-
-def _deserialize_datetime(metadata: Dict[str, Any]) -> Dict[str, Any]:
- """Deserialize ISO format datetime strings back to datetime objects."""
- result = metadata.copy()
- for key in ["created_at", "updated_at"]:
- if key in result and isinstance(result[key], str):
- try:
- result[key] = parse_iso_datetime(result[key])
- except (ValueError, TypeError):
- # Keep as string if parsing fails
- pass
- return result
-
-
-def serialize_with_metadata(
- metadata: Dict[str, Any],
- content_template: str = None,
- extract_context: Any = None,
-) -> str:
- """
- Serialize content and metadata into a single string.
-
- The metadata is stored in an HTML comment at the end of the content.
-
- Args:
- metadata: Dictionary containing all fields including "content".
- content is extracted and used as the main body.
- content_template: Optional Jinja2 template to render content.
- extract_context: Optional context for template rendering.
-
- Returns:
- Combined string with content followed by metadata in HTML comment
- """
- # Extract content from metadata (default to empty string)
- content = metadata.pop("content", "") or ""
-
- # Render template if provided
- if content_template:
- try:
- import jinja2
- from jinja2 import Environment
-
- env = Environment(autoescape=False, undefined=jinja2.DebugUndefined)
- template_vars = metadata.copy()
- template_vars["extract_context"] = extract_context
-
- jinja_template = env.from_string(content_template)
- content = jinja_template.render(**template_vars).strip()
- except Exception as e:
- from openviking.telemetry import tracer
-
- tracer.error(f"Template rendering failed, skipping write: {e}")
- raise
-
- # 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"}
-
- if not clean_metadata:
- return content
-
- # Serialize metadata to JSON with datetime handling
- metadata_json = json.dumps(
- clean_metadata, indent=2, default=_serialize_datetime, ensure_ascii=False
- )
-
- # Combine content and metadata
- comment = f"\n\n<!-- MEMORY_FIELDS\n{metadata_json}\n-->"
-
- # If content is empty, just return the comment (but trim leading newlines)
- if not content or not content.strip():
- return comment.lstrip()
-
- return content + comment
-
-
-def deserialize_content(full_content: str) -> str:
- """
- Extract the main content from a serialized string (strip metadata comment).
-
- Args:
- full_content: Complete content including metadata comment
-
- Returns:
- The main content without the metadata comment
- """
- if not full_content:
- return ""
-
- # Try to remove the MEMORY_FIELDS comment
- content = MEMORY_FIELDS_PATTERN.sub("", full_content)
-
- # If no match, check if it's at the very end
- if content == full_content:
- content = MEMORY_FIELDS_PATTERN_END.sub("", content)
-
- return content.rstrip()
-
-
-def deserialize_metadata(full_content: str) -> Optional[Dict[str, Any]]:
- """
- Extract and parse metadata from a serialized string.
-
- Args:
- full_content: Complete content including metadata comment
-
- Returns:
- Parsed metadata dictionary, or None if no metadata found
- """
- if not full_content:
- return None
-
- # Try to find the MEMORY_FIELDS comment
- match = MEMORY_FIELDS_PATTERN.search(full_content)
- if not match:
- match = MEMORY_FIELDS_PATTERN_END.search(full_content)
-
- if not match:
- return None
-
- try:
- json_str = match.group(1).strip()
- metadata = json.loads(json_str)
- return _deserialize_datetime(metadata)
- except (json.JSONDecodeError, IndexError, AttributeError):
- # Failed to parse, return None
- return None
-
-
-def deserialize_full(full_content: str) -> MemoryFileContent:
- content = deserialize_content(full_content)
- metadata = deserialize_metadata(full_content)
- return MemoryFileContent(plain_content=content, memory_fields=metadata)
-
-
-# 默认截断配置
-DEFAULT_TRUNCATE_MAX_CHARS = 1000
-
-
-def truncate_content(content: str, max_chars: int = DEFAULT_TRUNCATE_MAX_CHARS) -> str:
- """
- Truncate content to max_chars while keeping complete lines.
-
- Args:
- content: Content to truncate
- max_chars: Maximum number of characters to keep (default: 1000)
-
- Returns:
- Truncated content with truncation note appended
- """
- if len(content) <= max_chars:
- return content
-
- # 从 max_chars 位置向前找最近的换行符,保持完整行
- truncated = content[:max_chars]
- last_newline = truncated.rfind("\n")
- if last_newline > 0:
- truncated = truncated[:last_newline]
-
- return truncated + f"\n... [truncated {len(content) - len(truncated)} chars]"
diff --git a/openviking/session/memory/utils/json_parser.py b/openviking/session/memory/utils/json_parser.py
index d117add76..4cda6ea11 100644
--- a/openviking/session/memory/utils/json_parser.py
+++ b/openviking/session/memory/utils/json_parser.py
@@ -28,6 +28,7 @@ from typing import (
import json_repair
from pydantic import BaseModel, TypeAdapter
+from openviking.telemetry import tracer
from openviking_cli.utils import get_logger
logger = get_logger(__name__)
@@ -352,7 +353,7 @@ def parse_value_with_tolerance(value, annotation):
try:
return TypeAdapter(annotation).validate_python(parsed_value, strict=False)
except Exception as e:
- logger.warning(f"TypeAdapter validation failed: {e}")
+ tracer.info(f"TypeAdapter validation failed (recoverable): {e}")
# For list types, try filtering invalid items
if get_origin(annotation) is list and isinstance(parsed_value, list):
@@ -364,13 +365,13 @@ def parse_value_with_tolerance(value, annotation):
validated_item = TypeAdapter(item_type).validate_python(item, strict=False)
filtered_items.append(validated_item)
except Exception:
- logger.warning(f"Skipping invalid list item: {item}")
+ tracer.info(f"Skipping invalid list item: {item}")
continue
if filtered_items:
return filtered_items
else:
- logger.warning("All list items were filtered out, returning empty list")
+ tracer.info("All list items were filtered out, returning empty list")
return []
# Re-raise for non-list types
@@ -408,7 +409,7 @@ def parse_json_with_stability(
if not cleaned_content:
return None, "No JSON content found after cleanup"
except Exception as e:
- logger.warning(f"Layer 1 cleanup failed: {e}")
+ tracer.error(f"Layer 1 cleanup failed: {e}")
cleaned_content = content
# Layer 2: Parse with json_repair
@@ -416,7 +417,7 @@ def parse_json_with_stability(
try:
parsed_data = json_repair.loads(cleaned_content)
except Exception as e:
- logger.warning(f"Layer 2 json_repair failed: {e}")
+ tracer.error(f"Layer 2 json_repair failed: {e}")
# Fallback: try regular json.loads
try:
parsed_data = json.loads(cleaned_content)
@@ -427,7 +428,7 @@ def parse_json_with_stability(
# Handle case where model returns [{"xxx": ...}] instead of {"xxx": ...}
if isinstance(parsed_data, list) and len(parsed_data) > 0:
parsed_data = parsed_data[0]
- logger.info("Extracted first item from list response")
+ tracer.info("Extracted first item from list response")
if not isinstance(parsed_data, dict):
return None, f"Expected dict after parsing, got {type(parsed_data)}"
@@ -449,8 +450,8 @@ def parse_json_with_stability(
# First try direct model validation
return model_class.model_validate(parsed_data, strict=False), None
except Exception as e:
- logger.exception(f"Direct model validation failed, trying parse_value_with_tolerance: {e}")
- logger.exception(f"content={content}")
+ tracer.info(f"Direct model validation failed, trying parse_value_with_tolerance: {e}")
+ tracer.info(f"content={content}")
# Fallback: Apply value fault tolerance to each field individually
try:
field_types = get_type_hints(model_class)
@@ -462,7 +463,7 @@ def parse_json_with_stability(
field_value, field_types[field_name]
)
except Exception as field_e:
- logger.warning(f"Field {field_name} parsing failed: {field_e}")
+ tracer.error(f"Field {field_name} parsing failed: {field_e}")
# Skip this field rather than failing the whole parse
continue
diff --git a/openviking/session/memory/utils/language.py b/openviking/session/memory/utils/language.py
index a26154643..bfcd3c158 100644
--- a/openviking/session/memory/utils/language.py
+++ b/openviking/session/memory/utils/language.py
@@ -65,7 +65,9 @@ def resolve_with_override(config, detect: Callable[[], str]) -> str:
def resolve_output_language(text: str, config=None) -> str:
"""Resolve output language from text, honoring config override before detection."""
- return resolve_with_override(config, lambda: _detect_language_from_text(text, "en"))
+ result = resolve_with_override(config, lambda: _detect_language_from_text(text, "en"))
+ # result = '中文(必须遵守)'
+ return result
def resolve_output_language_from_conversation(conversation: str, config=None) -> str:
diff --git a/openviking/session/memory/utils/line_numbers.py b/openviking/session/memory/utils/line_numbers.py
new file mode 100644
index 000000000..7b8c0635d
--- /dev/null
+++ b/openviking/session/memory/utils/line_numbers.py
@@ -0,0 +1,55 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: AGPL-3.0
+
+import re
+from typing import Optional
+
+_LINE_NUMBER_PREFIX_RE = re.compile(r"^(\d+)\t")
+_LINE_NUMBER_PREFIX_WITH_LEADING_SPACE_RE = re.compile(r"^\s*(\d+)\t")
+_LINE_SPLIT_RE = re.compile(r"\r?\n")
+
+
+def split_content_lines(content: str) -> list[str]:
+ if content == "":
+ return []
+ return _LINE_SPLIT_RE.split(content)
+
+
+def add_line_numbers(content: str, start_line: int = 1) -> str:
+ if not content:
+ return ""
+ return "\n".join(
+ f"{index + start_line}\t{line}" for index, line in enumerate(split_content_lines(content))
+ )
+
+
+def slice_content_lines(content: str, offset: int = 0, limit: int = -1) -> str:
+ lines = split_content_lines(content)
+ if offset >= len(lines):
+ return ""
+ end = None if limit < 0 else offset + limit
+ return "\n".join(lines[offset:end])
+
+
+def line_count(content: str) -> int:
+ return len(split_content_lines(content))
+
+
+def extract_start_line_number(content: str) -> Optional[int]:
+ first_line = content.split("\n", 1)[0]
+ match = _LINE_NUMBER_PREFIX_WITH_LEADING_SPACE_RE.match(first_line)
+ if match is None:
+ return None
+ return int(match.group(1))
+
+
+def strip_line_numbers(content: str, aggressive: bool = False) -> str:
+ pattern = _LINE_NUMBER_PREFIX_WITH_LEADING_SPACE_RE if aggressive else _LINE_NUMBER_PREFIX_RE
+ return "\n".join(pattern.sub("", line) for line in split_content_lines(content))
+
+
+def every_line_has_line_numbers(content: str) -> bool:
+ lines = split_content_lines(content)
+ if not lines:
+ return False
+ return all(_LINE_NUMBER_PREFIX_RE.match(line) for line in lines)
diff --git a/openviking/session/memory/utils/link_renderer.py b/openviking/session/memory/utils/link_renderer.py
new file mode 100644
index 000000000..ce2695083
--- /dev/null
+++ b/openviking/session/memory/utils/link_renderer.py
@@ -0,0 +1,143 @@
+import re
+from typing import Dict, List, Optional
+
+from openviking.core.namespace import uri_parts
+from openviking.session.memory.dataclass import StoredLink
+
+
+class LinkRenderer:
+ """Renders and strips local markdown links in memory file content based on StoredLink metadata."""
+
+ _RELATIVE_LINK_RE = re.compile(r"\[(?P<text>[^\]]+)\]\((?P<target>[^)\s]+)\)")
+ _MEMORY_FIELDS_RE = re.compile(r"(\n\n<!--\s*MEMORY_FIELDS\s*\n)", re.DOTALL)
+ _CJK_RE = re.compile(r"[㐀-䶿一-鿿豈-﫿]")
+ _ASCII_WORD_CHAR_RE = re.compile(r"[A-Za-z0-9_]")
+
+ @staticmethod
+ def _contains_cjk(text: str) -> bool:
+ return bool(LinkRenderer._CJK_RE.search(text))
+
+ @staticmethod
+ def _is_ascii_word_char(char: str) -> bool:
+ return bool(char and LinkRenderer._ASCII_WORD_CHAR_RE.fullmatch(char))
+
+ @staticmethod
+ def _find_match_span(content: str, match_text: str) -> Optional[tuple[int, int]]:
+ escaped = re.escape(match_text)
+ if LinkRenderer._contains_cjk(match_text):
+ match = re.search(escaped, content)
+ if not match:
+ return None
+ return match.start(), match.end()
+
+ pattern = re.compile(escaped, re.IGNORECASE)
+ for match in pattern.finditer(content):
+ start, end = match.start(), match.end()
+ left_char = content[start - 1] if start > 0 else ""
+ right_char = content[end] if end < len(content) else ""
+ if LinkRenderer._is_ascii_word_char(left_char) or LinkRenderer._is_ascii_word_char(
+ right_char
+ ):
+ continue
+ return start, end
+ return None
+
+ @staticmethod
+ def render_links(content: str, source_uri: str, links: List[Dict]) -> str:
+ """Replace match_text in content with relative markdown links.
+
+ Args:
+ content: Plain markdown body.
+ source_uri: The viking:// URI of the file being written.
+ links: List of link dicts (from links + backlinks in MEMORY_FIELDS).
+ """
+ eligible = [l for l in links if l.get("match_text")]
+ if not eligible:
+ return content
+
+ eligible.sort(key=lambda l: l.get("weight", 0), reverse=True)
+
+ replacements: List[tuple] = [] # (start, end, replacement_text)
+ for link in eligible:
+ match_text = link["match_text"]
+ to_uri = link["to_uri"]
+
+ if to_uri == source_uri:
+ continue
+
+ rel = LinkRenderer.relative_path(source_uri, to_uri)
+ link_target = rel if rel is not None else to_uri
+
+ match_span = LinkRenderer._find_match_span(content, match_text)
+ if not match_span:
+ continue
+
+ start, end = match_span
+ # Skip if overlaps with an existing replacement
+ if any(not (end <= rs or start >= re_) for rs, re_, _ in replacements):
+ continue
+
+ rendered = f"[{content[start:end]}]({link_target})"
+ replacements.append((start, end, rendered))
+
+ # Apply in reverse order to preserve indices
+ result = list(content)
+ for start, end, repl in sorted(replacements, key=lambda x: x[0], reverse=True):
+ result[start:end] = list(repl)
+
+ return "".join(result)
+
+ @staticmethod
+ def strip_links(content: str) -> str:
+ """Remove relative markdown links, keeping only the link text.
+
+ External links, viking:// links, anchor links, and absolute-path links are preserved.
+ """
+
+ def _replace_link(m: re.Match) -> str:
+ target = m.group("target")
+ if target.startswith("#"):
+ return m.group(0)
+ if target.startswith("/"):
+ return m.group(0)
+ if "://" in target:
+ return m.group(0)
+ return m.group("text")
+
+ return LinkRenderer._RELATIVE_LINK_RE.sub(_replace_link, content)
+
+ @staticmethod
+ def relative_path(source_uri: str, target_uri: str) -> Optional[str]:
+ """Compute a relative path from source_uri to target_uri in the viking:// namespace.
+
+ Returns None if the URIs are in incompatible scopes (e.g. user vs agent).
+ """
+ src = uri_parts(source_uri)
+ tgt = uri_parts(target_uri)
+
+ if not src or not tgt:
+ return None
+ if src[0] != tgt[0]:
+ return None
+ if len(src) < 2 or len(tgt) < 2 or src[1] != tgt[1]:
+ return None
+
+ common = 0
+ for s, t in zip(src, tgt):
+ if s == t:
+ common += 1
+ else:
+ break
+
+ if common < 1:
+ return None
+
+ # -1 because the last segment of source is a filename, not a directory
+ up_count = len(src) - common - 1
+ down_parts = tgt[common:]
+
+ if up_count == 0:
+ return "/".join(down_parts) or "./"
+
+ up_parts = [".."] * up_count
+ return "/".join(up_parts + list(down_parts))
diff --git a/openviking/session/memory/utils/memory_file_utils.py b/openviking/session/memory/utils/memory_file_utils.py
new file mode 100644
index 000000000..531ed4268
--- /dev/null
+++ b/openviking/session/memory/utils/memory_file_utils.py
@@ -0,0 +1,111 @@
+import json
+import re
+from datetime import datetime
+from typing import Any, Dict, Optional
+
+from openviking.session.memory.dataclass import MemoryFile
+from openviking.session.memory.utils.link_renderer import LinkRenderer
+from openviking.session.memory.utils.messages import parse_memory_file_with_fields
+from openviking.utils.time_utils import parse_iso_datetime
+
+# Regex patterns for MEMORY_FIELDS HTML comment
+_MEMORY_FIELDS_PATTERN = re.compile(r"\n\n<!--\s*MEMORY_FIELDS\s*\n(.*?)\n-->", re.DOTALL)
+_MEMORY_FIELDS_PATTERN_END = re.compile(r"<!--\s*MEMORY_FIELDS\s*\n(.*?)\n-->$", re.DOTALL)
+
+DEFAULT_TRUNCATE_MAX_CHARS = 1000
+
+
+def _serialize_datetime(obj: Any) -> Any:
+ if isinstance(obj, datetime):
+ return obj.isoformat()
+ raise TypeError(f"Object of type {obj.__class__.__name__} is not JSON serializable")
+
+
+def _deserialize_datetime(metadata: Dict[str, Any]) -> Dict[str, Any]:
+ result = metadata.copy()
+ for key in ["created_at", "updated_at"]:
+ if key in result and isinstance(result[key], str):
+ try:
+ result[key] = parse_iso_datetime(result[key])
+ except (ValueError, TypeError):
+ pass
+ return result
+
+
+def _serialize_with_metadata(
+ metadata: Dict[str, Any],
+ content_template: str = None,
+ extract_context: Any = None,
+) -> str:
+ content = metadata.pop("content", "") or ""
+
+ if content_template:
+ try:
+ import jinja2
+ from jinja2 import Environment
+
+ env = Environment(autoescape=False, undefined=jinja2.DebugUndefined)
+ template_vars = metadata.copy()
+ template_vars["extract_context"] = extract_context
+
+ jinja_template = env.from_string(content_template)
+ content = jinja_template.render(**template_vars).strip()
+ except Exception:
+ pass
+
+ clean_metadata = {k: v for k, v in metadata.items() if v is not None}
+
+ if not clean_metadata:
+ return content
+
+ metadata_json = json.dumps(
+ clean_metadata, indent=2, default=_serialize_datetime, ensure_ascii=False
+ )
+
+ comment = f"\n\n<!-- MEMORY_FIELDS\n{metadata_json}\n-->"
+
+ if not content or not content.strip():
+ return comment.lstrip()
+
+ return content + comment
+
+
+class MemoryFileUtils:
+ """Unified read/write API for memory files.
+
+ Encapsulates parsing + strip_links (read) and serialize + render_links (write).
+ All other utilities (deserialize_content, serialize_with_metadata, etc.) are
+ internal implementation details not exposed to callers.
+ """
+
+ @staticmethod
+ def read(raw_content: str, uri: Optional[str] = None) -> MemoryFile:
+ """Parse a memory file and return a MemoryFile with markdown links preserved."""
+ parsed = parse_memory_file_with_fields(raw_content)
+ parsed = _deserialize_datetime(parsed)
+ return MemoryFile.from_parsed(uri=uri, parsed=parsed)
+
+ @staticmethod
+ def write(
+ memory_file: MemoryFile,
+ content_template: Optional[str] = None,
+ extract_context: Any = None,
+ ) -> str:
+ """Serialize a MemoryFile as plain-text body plus MEMORY_FIELDS metadata."""
+ metadata = memory_file.to_metadata()
+ return _serialize_with_metadata(
+ metadata,
+ content_template=content_template,
+ extract_context=extract_context,
+ )
+
+ @staticmethod
+ def truncate_content(content: str, max_chars: int = DEFAULT_TRUNCATE_MAX_CHARS) -> str:
+ """Truncate content to max_chars while keeping complete lines."""
+ if len(content) <= max_chars:
+ return content
+ truncated = content[:max_chars]
+ last_newline = truncated.rfind("\n")
+ if last_newline > 0:
+ truncated = truncated[:last_newline]
+ return truncated + f"\n... [truncated {len(content) - len(truncated)} chars]"
diff --git a/openviking/session/memory/utils/messages.py b/openviking/session/memory/utils/messages.py
index 483175fe0..657e85b37 100644
--- a/openviking/session/memory/utils/messages.py
+++ b/openviking/session/memory/utils/messages.py
@@ -10,7 +10,6 @@ from typing import Any, Dict, List
import json_repair
-from openviking.session.memory.utils import truncate_content
from openviking.telemetry import tracer
from openviking_cli.utils import get_logger
@@ -74,7 +73,7 @@ def pretty_print_messages(messages: List[Dict[str, Any]]) -> None:
output.append(json.dumps(tool_calls, indent=2, ensure_ascii=False))
output.append("\n=== End Messages ===")
- tracer.info("messages=" + "\n".join(output))
+ tracer.info("llm_input_messages=" + "\n".join(output))
def parse_memory_file_with_fields(content: str) -> Dict[str, Any]:
diff --git a/openviking/session/memory/utils/uri.py b/openviking/session/memory/utils/uri.py
index bd4d7841f..a5a795f89 100644
--- a/openviking/session/memory/utils/uri.py
+++ b/openviking/session/memory/utils/uri.py
@@ -7,20 +7,12 @@ URI generation and validation utilities.
from __future__ import annotations
import re
-from typing import TYPE_CHECKING, Any, Dict, Set
-
-if TYPE_CHECKING:
- from openviking.session.memory.memory_isolation_handler import MemoryIsolationHandler
- from openviking.session.memory.memory_updater import ExtractContext
+from typing import Any, Dict, Set
import jinja2
-from openviking.session.memory.dataclass import MemoryTypeSchema, ResolvedOperations
-from openviking.session.memory.memory_type_registry import MemoryTypeRegistry
+from openviking.session.memory.dataclass import MemoryTypeSchema
from openviking.session.memory.utils.model import model_to_dict
-from openviking_cli.utils import get_logger
-
-logger = get_logger(__name__)
def _render_jinja_template(template: str, context: Dict[str, Any]) -> str:
@@ -218,20 +210,3 @@ def extract_uri_fields_from_flat_model(model: Any, schema: MemoryTypeSchema) ->
if name in schema_field_names and isinstance(value, (str, int, float, bool)):
uri_fields[name] = value
return uri_fields
-
-
-def supplement_operation_uris(
- operations: ResolvedOperations,
- registry: MemoryTypeRegistry,
- extract_context: ExtractContext = None,
- isolation_handler: MemoryIsolationHandler = None,
-):
- logger.info(f"[supplement_operation_uris] isolation_handler: {isolation_handler}")
- for operation in operations.upsert_operations:
- memory_type_schema = registry.get(operation.memory_type)
- uris = isolation_handler.calculate_memory_uris(
- memory_type_schema=memory_type_schema,
- operation=operation,
- extract_context=extract_context,
- )
- operation.uris = uris
diff --git a/openviking/storage/content_write.py b/openviking/storage/content_write.py
index 53074ed64..fcd956264 100644
--- a/openviking/storage/content_write.py
+++ b/openviking/storage/content_write.py
@@ -10,7 +10,7 @@ from typing import Any, Dict, Optional
from openviking.core.namespace import NamespaceShapeError, canonicalize_uri, context_type_for_uri
from openviking.resource.watch_storage import is_watch_task_control_uri
from openviking.server.identity import RequestContext
-from openviking.session.memory.utils.content import deserialize_full, serialize_with_metadata
+from openviking.session.memory.utils.memory_file_utils import MemoryFileUtils
from openviking.storage.queuefs import SemanticMsg, get_queue_manager
from openviking.storage.queuefs.semantic_msg import build_semantic_coalesce_key
from openviking.storage.queuefs.semantic_processor import SemanticProcessor
@@ -43,14 +43,6 @@ class ContentWriteCoordinator:
def __init__(self, viking_fs: VikingFS):
self._viking_fs = viking_fs
- @staticmethod
- def _memory_content_parts(raw: str) -> tuple[str, Dict[str, Any]]:
- try:
- parsed = deserialize_full(raw)
- except Exception:
- return raw, {}
- return parsed.plain_content, parsed.memory_fields or {}
-
async def write(
self,
*,
@@ -356,24 +348,17 @@ class ContentWriteCoordinator:
) -> None:
if mode == "replace" and context_type_for_uri(uri) == "memory":
existing_raw = await self._viking_fs.read_file(uri, ctx=ctx)
- _, metadata = self._memory_content_parts(existing_raw)
- if metadata:
- metadata_with_content = metadata.copy()
- metadata_with_content["content"] = content
- content = serialize_with_metadata(metadata_with_content)
+ mf = MemoryFileUtils.read(existing_raw, uri=uri)
+ mf.content = content
+ content = MemoryFileUtils.write(mf)
await self._viking_fs.write_file(uri, content, ctx=ctx)
return
if mode == "append":
existing_raw = await self._viking_fs.read_file(uri, ctx=ctx)
- existing_content, metadata = self._memory_content_parts(existing_raw)
- updated_content = existing_content + content
- if metadata:
- metadata_with_content = metadata.copy()
- metadata_with_content["content"] = updated_content
- updated_raw = serialize_with_metadata(metadata_with_content)
- else:
- updated_raw = updated_content
+ mf = MemoryFileUtils.read(existing_raw, uri=uri)
+ mf.content = mf.content + content
+ updated_raw = MemoryFileUtils.write(mf)
await self._viking_fs.write_file(uri, updated_raw, ctx=ctx)
return
await self._viking_fs.write_file(uri, content, ctx=ctx)
diff --git a/openviking/storage/transaction/lock_manager.py b/openviking/storage/transaction/lock_manager.py
index 8eccd14ab..f2a7bcd41 100644
--- a/openviking/storage/transaction/lock_manager.py
+++ b/openviking/storage/transaction/lock_manager.py
@@ -16,6 +16,7 @@ from openviking_cli.utils.logger import get_logger
logger = get_logger(__name__)
_HANDLE_CLEANUP_INTERVAL_SECONDS = 60.0
+_USE_MANAGER_DEFAULT_TIMEOUT = object()
class LockManager:
@@ -46,6 +47,9 @@ class LockManager:
def redo_recovery_enabled(self) -> bool:
return self._redo_recovery_enabled
+ def _resolve_timeout(self, timeout: Optional[float]) -> Optional[float]:
+ return self._lock_timeout if timeout is _USE_MANAGER_DEFAULT_TIMEOUT else timeout
+
def _mark_handle_active(self, handle: LockHandle) -> None:
handle.last_active_at = time.time()
@@ -94,20 +98,26 @@ class LockManager:
return handle
async def acquire_exact_path(
- self, handle: LockHandle, path: str, timeout: Optional[float] = None
+ self,
+ handle: LockHandle,
+ path: str,
+ timeout: Optional[float] = _USE_MANAGER_DEFAULT_TIMEOUT,
) -> bool:
acquired = await self._path_lock.acquire_exact_path(
- path, handle, timeout=timeout if timeout is not None else self._lock_timeout
+ path, handle, timeout=self._resolve_timeout(timeout)
)
if acquired:
self._mark_handle_active(handle)
return acquired
async def acquire_tree(
- self, handle: LockHandle, path: str, timeout: Optional[float] = None
+ self,
+ handle: LockHandle,
+ path: str,
+ timeout: Optional[float] = _USE_MANAGER_DEFAULT_TIMEOUT,
) -> bool:
acquired = await self._path_lock.acquire_tree(
- path, handle, timeout=timeout if timeout is not None else self._lock_timeout
+ path, handle, timeout=self._resolve_timeout(timeout)
)
if acquired:
self._mark_handle_active(handle)
@@ -117,7 +127,7 @@ class LockManager:
self,
handle: LockHandle,
paths: List[str],
- timeout: Optional[float] = None,
+ timeout: Optional[float] = _USE_MANAGER_DEFAULT_TIMEOUT,
) -> bool:
"""
一次性对多个路径进行树锁加锁,使用有序加锁法防止死锁
@@ -151,7 +161,7 @@ class LockManager:
success = await self._path_lock.acquire_tree(
path,
handle,
- timeout=timeout if timeout is not None else self._lock_timeout,
+ timeout=self._resolve_timeout(timeout),
)
if not success:
await self._path_lock.release_selected(handle, acquired_lock_paths)
@@ -171,7 +181,7 @@ class LockManager:
self,
handle: LockHandle,
paths: List[str],
- timeout: Optional[float] = None,
+ timeout: Optional[float] = _USE_MANAGER_DEFAULT_TIMEOUT,
) -> bool:
if not paths:
self._mark_handle_active(handle)
@@ -186,7 +196,7 @@ class LockManager:
success = await self._path_lock.acquire_exact_path(
path,
handle,
- timeout=timeout if timeout is not None else self._lock_timeout,
+ timeout=self._resolve_timeout(timeout),
)
if not success:
await self._path_lock.release_selected(handle, acquired_lock_paths)
@@ -207,7 +217,7 @@ class LockManager:
handle: LockHandle,
exact_paths: List[str],
tree_paths: List[str],
- timeout: Optional[float] = None,
+ timeout: Optional[float] = _USE_MANAGER_DEFAULT_TIMEOUT,
) -> bool:
exact_set = set(exact_paths)
tree_set = set(tree_paths)
@@ -228,13 +238,13 @@ class LockManager:
success = await self._path_lock.acquire_tree(
path,
handle,
- timeout=timeout if timeout is not None else self._lock_timeout,
+ timeout=self._resolve_timeout(timeout),
)
else:
success = await self._path_lock.acquire_exact_path(
path,
handle,
- timeout=timeout if timeout is not None else self._lock_timeout,
+ timeout=self._resolve_timeout(timeout),
)
if not success:
await self._path_lock.release_selected(handle, acquired_lock_paths)
@@ -256,13 +266,13 @@ class LockManager:
src: str,
dst: str,
src_is_dir: bool = True,
- timeout: Optional[float] = None,
+ timeout: Optional[float] = _USE_MANAGER_DEFAULT_TIMEOUT,
) -> bool:
acquired = await self._path_lock.acquire_mv(
src,
dst,
handle,
- timeout=timeout if timeout is not None else self._lock_timeout,
+ timeout=self._resolve_timeout(timeout),
src_is_dir=src_is_dir,
)
if acquired:
diff --git a/openviking/storage/transaction/path_lock.py b/openviking/storage/transaction/path_lock.py
index e72277f3d..f788174d9 100644
--- a/openviking/storage/transaction/path_lock.py
+++ b/openviking/storage/transaction/path_lock.py
@@ -23,6 +23,7 @@ _READ_ONLY_TREE_LOCK_TYPES = {"P", "S"}
# Default poll interval when waiting for a lock (seconds)
_POLL_INTERVAL = 0.2
+_WAIT_LOG_INTERVAL = 10.0
@dataclass
@@ -216,6 +217,11 @@ class PathLockEngine:
async def _owned_lock_type(self, path: str, owner: LockOwner) -> Optional[str]:
lock_path = self._get_lock_path(path)
+ return await self._owned_lock_type_for_lock_path(lock_path, owner)
+
+ async def _owned_lock_type_for_lock_path(
+ self, lock_path: str, owner: LockOwner
+ ) -> Optional[str]:
if lock_path not in owner.locks:
return None
token = self._read_token(lock_path)
@@ -349,6 +355,8 @@ class PathLockEngine:
deadline = float("inf")
else:
deadline = asyncio.get_running_loop().time() + timeout
+ wait_start = asyncio.get_running_loop().time()
+ next_wait_log_at = wait_start + _WAIT_LOG_INTERVAL
while True:
existing_exact_lock = await self._check_exact_path_lock(path, owner_id)
@@ -360,6 +368,13 @@ class PathLockEngine:
if asyncio.get_running_loop().time() >= deadline:
logger.warning(f"[EXACT] Timeout waiting for exact lock on: {path}")
return False
+ now = asyncio.get_running_loop().time()
+ if timeout is None and now >= next_wait_log_at:
+ logger.info(
+ f"[EXACT] Still waiting for lock on: {path} "
+ f"(waited={now - wait_start:.1f}s)"
+ )
+ next_wait_log_at = now + _WAIT_LOG_INTERVAL
await asyncio.sleep(_POLL_INTERVAL)
continue
@@ -392,6 +407,13 @@ class PathLockEngine:
f"[EXACT] Timeout waiting for ancestor TREE lock: {ancestor_conflict}"
)
return False
+ now = asyncio.get_running_loop().time()
+ if timeout is None and now >= next_wait_log_at:
+ logger.info(
+ f"[EXACT] Still waiting for ancestor TREE lock: {ancestor_conflict} "
+ f"(path={path}, waited={now - wait_start:.1f}s)"
+ )
+ next_wait_log_at = now + _WAIT_LOG_INTERVAL
await asyncio.sleep(_POLL_INTERVAL)
continue
@@ -438,6 +460,13 @@ class PathLockEngine:
if self.is_lock_owned_by(lock_path, owner_id):
await self._remove_lock_file(lock_path)
return False
+ now = asyncio.get_running_loop().time()
+ if timeout is None and now >= next_wait_log_at:
+ logger.info(
+ f"[EXACT] Still waiting after conflict check on: {path} "
+ f"(waited={now - wait_start:.1f}s)"
+ )
+ next_wait_log_at = now + _WAIT_LOG_INTERVAL
await asyncio.sleep(_POLL_INTERVAL)
continue
@@ -445,6 +474,13 @@ class PathLockEngine:
logger.debug(f"[EXACT] Lock ownership verification failed: {path}")
if asyncio.get_running_loop().time() >= deadline:
return False
+ now = asyncio.get_running_loop().time()
+ if timeout is None and now >= next_wait_log_at:
+ logger.info(
+ f"[EXACT] Still waiting for lock ownership verification: {path} "
+ f"(waited={now - wait_start:.1f}s)"
+ )
+ next_wait_log_at = now + _WAIT_LOG_INTERVAL
await asyncio.sleep(_POLL_INTERVAL)
continue
@@ -471,6 +507,8 @@ class PathLockEngine:
else:
# 有限超时
deadline = asyncio.get_running_loop().time() + timeout
+ wait_start = asyncio.get_running_loop().time()
+ next_wait_log_at = wait_start + _WAIT_LOG_INTERVAL
while True:
if await self._is_locked_by_other(lock_path, owner_id):
@@ -481,6 +519,13 @@ class PathLockEngine:
if asyncio.get_running_loop().time() >= deadline:
logger.warning(f"[TREE] Timeout waiting for lock on: {path}")
return False
+ now = asyncio.get_running_loop().time()
+ if timeout is None and now >= next_wait_log_at:
+ logger.info(
+ f"[TREE] Still waiting for lock on: {path} "
+ f"(waited={now - wait_start:.1f}s)"
+ )
+ next_wait_log_at = now + _WAIT_LOG_INTERVAL
await asyncio.sleep(_POLL_INTERVAL)
continue
@@ -496,6 +541,13 @@ class PathLockEngine:
f"[TREE] Timeout waiting for ancestor TREE lock: {ancestor_conflict}"
)
return False
+ now = asyncio.get_running_loop().time()
+ if timeout is None and now >= next_wait_log_at:
+ logger.info(
+ f"[TREE] Still waiting for ancestor TREE lock: {ancestor_conflict} "
+ f"(path={path}, waited={now - wait_start:.1f}s)"
+ )
+ next_wait_log_at = now + _WAIT_LOG_INTERVAL
await asyncio.sleep(_POLL_INTERVAL)
continue
@@ -520,6 +572,13 @@ class PathLockEngine:
if asyncio.get_running_loop().time() >= deadline:
logger.warning(f"[TREE] Timeout waiting for descendant lock: {desc_conflict}")
return False
+ now = asyncio.get_running_loop().time()
+ if timeout is None and now >= next_wait_log_at:
+ logger.info(
+ f"[TREE] Still waiting for descendant lock: {desc_conflict} "
+ f"(path={path}, waited={now - wait_start:.1f}s)"
+ )
+ next_wait_log_at = now + _WAIT_LOG_INTERVAL
await asyncio.sleep(_POLL_INTERVAL)
continue
@@ -555,6 +614,13 @@ class PathLockEngine:
if not backed_off:
await self._remove_lock_file(lock_path)
return False
+ now = asyncio.get_running_loop().time()
+ if timeout is None and now >= next_wait_log_at:
+ logger.info(
+ f"[TREE] Still waiting after conflict check on: {path} "
+ f"(waited={now - wait_start:.1f}s)"
+ )
+ next_wait_log_at = now + _WAIT_LOG_INTERVAL
await asyncio.sleep(_POLL_INTERVAL)
continue
@@ -562,6 +628,13 @@ class PathLockEngine:
logger.debug(f"[TREE] Lock ownership verification failed: {path}")
if asyncio.get_running_loop().time() >= deadline:
return False
+ now = asyncio.get_running_loop().time()
+ if timeout is None and now >= next_wait_log_at:
+ logger.info(
+ f"[TREE] Still waiting for lock ownership verification: {path} "
+ f"(waited={now - wait_start:.1f}s)"
+ )
+ next_wait_log_at = now + _WAIT_LOG_INTERVAL
await asyncio.sleep(_POLL_INTERVAL)
continue
diff --git a/openviking/storage/viking_fs.py b/openviking/storage/viking_fs.py
index 615d79a37..35d41e611 100644
--- a/openviking/storage/viking_fs.py
+++ b/openviking/storage/viking_fs.py
@@ -1057,7 +1057,7 @@ class VikingFS:
ctx: Optional[RequestContext] = None,
) -> Dict:
"""File pattern matching, supports **/*.md recursive."""
- entries = await self.tree(uri, node_limit=1000000, ctx=ctx)
+ entries = await self.tree(uri, node_limit=1000000, level_limit=None, ctx=ctx)
base_uri = uri.rstrip("/")
matches = []
for entry in entries:
@@ -2014,11 +2014,14 @@ class VikingFS:
async def _ensure_parent_dirs(self, path: str) -> None:
"""Recursively create all parent directories."""
- try:
- await self._run_in_threadpool(self.agfs.ensure_parent_dirs, path)
- except Exception as e:
- # Log the error but continue
- logger.debug(f"Failed to ensure parent directories for {path}: {e}")
+ parts = path.lstrip("/").split("/")
+ for i in range(1, len(parts)):
+ parent = "/" + "/".join(parts[:i])
+ try:
+ await self._run_in_threadpool(self.agfs.mkdir, parent)
+ except Exception as e:
+ if "exist" not in str(e).lower() and "already" not in str(e).lower():
+ logger.debug(f"Failed to create parent directory {parent}: {e}")
# ========== Relation Table Internal Methods ==========
diff --git a/openviking/telemetry/tracer.py b/openviking/telemetry/tracer.py
index 1cfefe755..784f6b4d0 100644
--- a/openviking/telemetry/tracer.py
+++ b/openviking/telemetry/tracer.py
@@ -78,11 +78,13 @@ def _setup_logging():
try:
# Configure logger to patch records with trace_id
- logger.configure(
- patcher=lambda record: record.__setitem__(
- "extra", {**record["extra"], "trace_id": get_trace_id()}
- )
- )
+ def _patch_trace_id(record):
+ trace_id = get_trace_id()
+ record["extra"]["trace_id"] = trace_id
+ if trace_id:
+ record["message"] = f"[{trace_id}] {record['message']}"
+
+ logger.configure(patcher=_patch_trace_id)
_trace_id_filter_added = True
except Exception:
_log_trace_internal_failure("[TRACER] failed to configure loguru trace_id patcher")
@@ -547,7 +549,7 @@ class tracer:
def info(line: str, console: bool = False) -> None:
"""Add an event to the current span."""
if console:
- logger.info(line)
+ logger.opt(depth=1).info(line)
if _otel_tracer is None:
return
@@ -567,7 +569,7 @@ class tracer:
def info_span(line: str, console: bool = False) -> None:
"""Create a new span with the given name."""
if console:
- logger.info(line)
+ logger.opt(depth=1).info(line)
if _otel_tracer is None:
return
with tracer.start_as_current_span(name=line):
@@ -578,9 +580,9 @@ class tracer:
"""Record an error on the current span."""
if console:
if e is not None:
- logger.exception(f"{line}", exc_info=e)
+ logger.opt(depth=1).exception(f"{line}", exc_info=e)
else:
- logger.exception(line)
+ logger.opt(depth=1).error(line)
if _otel_tracer is None:
return
diff --git a/openviking_cli/utils/config/memory_config.py b/openviking_cli/utils/config/memory_config.py
index 698b36be4..3ef871705 100644
--- a/openviking_cli/utils/config/memory_config.py
+++ b/openviking_cli/utils/config/memory_config.py
@@ -90,6 +90,14 @@ class MemoryConfig(BaseModel):
"is ignored and the login user from the request context is used instead."
),
)
+ link_enabled: bool = Field(
+ default=False,
+ description=(
+ "When enabled, memory extraction supports link extraction between "
+ "memory items (page_id, links field, and link resolution). When disabled (default), "
+ "no page_id or link fields are generated, and link resolution is skipped."
+ ),
+ )
model_config = {"extra": "forbid"}
diff --git a/openviking_cli/utils/config/vlm_config.py b/openviking_cli/utils/config/vlm_config.py
index d8b7dc812..a3ae470ef 100644
--- a/openviking_cli/utils/config/vlm_config.py
+++ b/openviking_cli/utils/config/vlm_config.py
@@ -323,14 +323,15 @@ class VLMConfig(BaseModel):
def get_completion(
self,
prompt: str = "",
- thinking: bool = False,
+ thinking: Optional[bool] = None,
tools: Optional[List[Dict[str, Any]]] = None,
messages: Optional[List[Dict[str, Any]]] = None,
) -> Union[str, Any]:
"""Get LLM completion."""
+ effective_thinking = self.thinking if thinking is None else thinking
return self.get_vlm_instance().get_completion(
prompt=prompt,
- thinking=thinking,
+ thinking=effective_thinking,
tools=tools,
messages=messages,
)
@@ -338,15 +339,16 @@ class VLMConfig(BaseModel):
async def get_completion_async(
self,
prompt: str = "",
- thinking: bool = False,
+ thinking: Optional[bool] = None,
tools: Optional[List[Dict[str, Any]]] = None,
tool_choice: Optional[Any] = None,
messages: Optional[List[Dict[str, Any]]] = None,
) -> Union[str, Any]:
"""Get LLM completion asynchronously."""
+ effective_thinking = self.thinking if thinking is None else thinking
return await self.get_vlm_instance().get_completion_async(
prompt=prompt,
- thinking=thinking,
+ thinking=effective_thinking,
tools=tools,
tool_choice=tool_choice,
messages=messages,
@@ -366,15 +368,16 @@ class VLMConfig(BaseModel):
self,
prompt: str = "",
images: Optional[list] = None,
- thinking: bool = False,
+ thinking: Optional[bool] = None,
tools: Optional[List[Dict[str, Any]]] = None,
messages: Optional[List[Dict[str, Any]]] = None,
) -> Union[str, Any]:
"""Get LLM completion with images."""
+ effective_thinking = self.thinking if thinking is None else thinking
return self.get_vlm_instance().get_vision_completion(
prompt=prompt,
images=images,
- thinking=thinking,
+ thinking=effective_thinking,
tools=tools,
messages=messages,
)
@@ -383,15 +386,16 @@ class VLMConfig(BaseModel):
self,
prompt: str = "",
images: Optional[list] = None,
- thinking: bool = False,
+ thinking: Optional[bool] = None,
tools: Optional[List[Dict[str, Any]]] = None,
messages: Optional[List[Dict[str, Any]]] = None,
) -> Union[str, Any]:
"""Get LLM completion with images asynchronously."""
+ effective_thinking = self.thinking if thinking is None else thinking
return await self.get_vlm_instance().get_vision_completion_async(
prompt=prompt,
images=images,
- thinking=thinking,
+ thinking=effective_thinking,
tools=tools,
messages=messages,
)
diff --git a/tests/agfs/test_fs_binding.py b/tests/agfs/test_fs_binding.py
index 3a5748889..5cdcde749 100644
--- a/tests/agfs/test_fs_binding.py
+++ b/tests/agfs/test_fs_binding.py
@@ -111,6 +111,22 @@ class TestVikingFSBindingLocal:
await vfs.rm(f"viking://temp/{base_dir}/", recursive=True)
+ async def test_glob_matches_deep_markdown_files(self, viking_fs_binding_instance):
+ """Test glob recursively matches markdown files beyond tree's default depth."""
+ vfs = viking_fs_binding_instance
+ base_dir = f"binding_glob_test_{uuid.uuid4().hex}"
+ deep_dir_uri = f"viking://temp/{base_dir}/events/2023/05/08/"
+ deep_file_uri = f"{deep_dir_uri}entry.md"
+
+ await vfs.mkdir(deep_dir_uri)
+ await vfs.write(deep_file_uri, "# deep event")
+
+ result = await vfs.glob("**/*.md", uri=f"viking://temp/{base_dir}/")
+
+ assert deep_file_uri in result["matches"]
+
+ await vfs.rm(f"viking://temp/{base_dir}/", recursive=True)
+
async def test_binary_operations(self, viking_fs_binding_instance):
"""Test VikingFS binary file operations."""
vfs = viking_fs_binding_instance
diff --git a/tests/query_trace.py b/tests/debug_trace.py
similarity index 100%
rename from tests/query_trace.py
rename to tests/debug_trace.py
diff --git a/tests/integration/test_agent_memory_e2e.py b/tests/integration/test_agent_memory_e2e.py
index 0f4473b23..1acbdb0c6 100644
--- a/tests/integration/test_agent_memory_e2e.py
+++ b/tests/integration/test_agent_memory_e2e.py
@@ -39,7 +39,7 @@ 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.session.memory.utils import MemoryFileUtils
from openviking.telemetry import tracer
from openviking.telemetry.tracer import init_tracer_from_config
from openviking_cli.session.user_id import UserIdentifier
@@ -205,7 +205,8 @@ def _collect_source_trajectories(client: LocalClient, exp_entries: List[dict]) -
if not exp_uri:
continue
raw = run_async(client.read(exp_uri)) or ""
- metadata = deserialize_metadata(raw) or {}
+ mf = MemoryFileUtils.read(raw) if raw else None
+ metadata = mf.extra_fields if mf else {}
source = metadata.get("source_trajectories", [])
if isinstance(source, list):
all_uris.extend(str(u).strip() for u in source if str(u).strip())
@@ -302,8 +303,12 @@ class TestAgentMemoryE2E:
logger.info("Round 1: flight booking duplicate (expect CREATE experience)")
_run_conversation(client, CONV_A_FLIGHT_DUPLICATE)
- _list_non_overview_entries(client, trajectories_dir)
- _list_non_overview_entries(client, experiences_dir)
+ 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)
diff --git a/tests/integration/test_compressor_v2_xiaowang.py b/tests/integration/test_compressor_v2_xiaowang.py
new file mode 100644
index 000000000..5077e13c9
--- /dev/null
+++ b/tests/integration/test_compressor_v2_xiaowang.py
@@ -0,0 +1,268 @@
+#!/usr/bin/env python3
+"""
+OpenViking 记忆演示脚本 — 用户: 小王(5类工作方式及对应技能)
+"""
+
+import argparse
+import time
+from datetime import datetime
+
+from rich import box
+from rich.console import Console
+from rich.panel import Panel
+from rich.table import Table
+
+import openviking as ov
+
+# ── 常量 ───────────────────────────────────────────────────────────────────
+
+DISPLAY_NAME = "小王"
+DEFAULT_URL = "http://localhost:1934"
+PANEL_WIDTH = 78
+DEFAULT_API_KEY = "1cf407c39990e5dc874ccc697942da4892208a86a44c4781396dfdc57aa5c98d"
+DEFAULT_AGENT_ID = "test"
+DEFAULT_SESSION_ID = "xiaowang-demo"
+
+
+console = Console()
+
+# ── 对话数据 ──────────────────────────────────────────────────────────────
+
+CONVERSATION = [
+ {
+ "user": "小王的5类工作方式及对应技能:1. 小王内容账号复盘技能:B站复盘需结合数据+多维度分析+可复用选题经验,重点是数字+解释+可改建议,不混淆其他场景;2. 小王LLM早学技能:早7点左右30分钟学习,少术语多例子,含小练习和小产物,陪练语气、短学习、递进练习,非学院派;3. 小王家庭消费决策技能:数码购买分人群匹配需求,优先官方可靠渠道,重点说明适配性、原因、风险,不替下单;4. 小王建材门店宣传技能:短视频脚本朴实实用,核对门店真实信息,15秒内节奏,产品图与名称对应;5. 小王家庭健康轻量打卡技能:记录3-5项易填内容,温和趋势提醒,非诊断口吻,不编造医疗相关内容",
+ "assistant": "好的,我已经记录了小王的5类工作方式及对应技能:内容账号复盘、LLM早学、家庭消费决策、建材门店宣传、家庭健康轻量打卡。每项技能的特点和注意事项都记下了。",
+ },
+]
+
+# ── 验证查询 ──────────────────────────────────────────────────────────────
+
+VERIFY_QUERIES = [
+ {
+ "query": "小王有哪些工作方式或技能",
+ "expected_keywords": ["复盘", "LLM", "消费决策", "门店宣传", "打卡"],
+ },
+ {
+ "query": "小王的LLM早学技能具体是什么",
+ "expected_keywords": ["早7点", "少术语", "陪练", "递进"],
+ },
+ {
+ "query": "小王做建材门店宣传时要注意什么",
+ "expected_keywords": ["短视频", "15秒", "产品图"],
+ },
+]
+
+
+# ── Phase 1: 写入对话并提交 ────────────────────────────────────────────────
+
+
+def run_ingest(client: ov.SyncHTTPClient, session_id: str, wait_seconds: float):
+ console.print()
+ console.rule(f"[bold]Phase 1: 写入对话 — {DISPLAY_NAME} ({len(CONVERSATION)} 轮)[/bold]")
+
+ # 获取 session;若不存在则由服务端按 session_id 自动创建
+ session = client.create_session()
+ session_id = session.get("session_id")
+ print(f"session_id={session_id}")
+ console.print(f" Session: [bold cyan]{session_id}[/bold cyan]")
+ console.print()
+
+ # 设置一个测试用的会话时间
+ session_time = datetime(2026, 5, 6, 3, 21)
+ session_time_str = session_time.isoformat()
+
+ # 逐轮添加消息
+ total = len(CONVERSATION)
+ for i, turn in enumerate(CONVERSATION, 1):
+ console.print(f" [dim][{i}/{total}][/dim] 添加 user + assistant 消息...")
+ client.add_message(
+ session_id,
+ role="user",
+ parts=[{"type": "text", "text": turn["user"]}],
+ created_at=session_time_str,
+ )
+ client.add_message(
+ session_id,
+ role="assistant",
+ parts=[{"type": "text", "text": turn["assistant"]}],
+ created_at=session_time_str,
+ )
+
+ console.print()
+ console.print(f" 共添加 [bold]{total * 2}[/bold] 条消息")
+
+ # 提交 session — 触发记忆抽取
+ console.print()
+ console.print(" [yellow]提交 Session(触发记忆抽取)...[/yellow]")
+ commit_result = client.commit_session(session_id)
+ task_id = commit_result.get("task_id")
+ trace_id = commit_result.get("trace_id")
+ console.print(f" [bold cyan]trace_id: {trace_id}[/bold cyan]")
+ console.print(f" Commit 结果: {commit_result}")
+
+ # 轮询后台任务直到完成
+ if task_id:
+ now = time.time()
+ console.print(f" [yellow]等待记忆提取完成 (task_id={task_id})...[/yellow]")
+ while True:
+ task = client.get_task(task_id)
+ if not task or task.get("status") in ("completed", "failed"):
+ break
+ time.sleep(1)
+ elapsed = time.time() - now
+ status = task.get("status", "unknown") if task else "not found"
+ console.print(f" [green]任务 {status},耗时 {elapsed:.2f}s[/green]")
+ console.print(f" Task 详情: {task}")
+
+ # 等待向量化队列处理完成
+ console.print(f" [yellow]等待向量化完成...[/yellow]")
+ client.wait_processed()
+
+ if wait_seconds > 0:
+ console.print(f" [dim]额外等待 {wait_seconds:.0f}s...[/dim]")
+ time.sleep(wait_seconds)
+
+ session_info = client.get_session(session_id)
+ console.print(f" Session 详情: {session_info}")
+
+ return session_id
+
+
+# ── Phase 2: 验证记忆召回 ─────────────────────────────────────────────────
+
+
+def run_verify(client: ov.SyncHTTPClient):
+ console.print()
+ console.rule(
+ f"[bold]Phase 2: 验证记忆召回 — {DISPLAY_NAME} ({len(VERIFY_QUERIES)} 条查询)[/bold]"
+ )
+
+ results_table = Table(
+ title=f"记忆召回验证 — {DISPLAY_NAME}",
+ box=box.ROUNDED,
+ show_header=True,
+ header_style="bold",
+ )
+ results_table.add_column("#", style="bold", width=4)
+ results_table.add_column("查询", style="cyan", max_width=30)
+ results_table.add_column("召回数", justify="center", width=8)
+ results_table.add_column("命中关键词", style="green")
+
+ total = len(VERIFY_QUERIES)
+ for i, item in enumerate(VERIFY_QUERIES, 1):
+ query = item["query"]
+ expected = item["expected_keywords"]
+
+ console.print(f"\n [dim][{i}/{total}][/dim] 搜索: [cyan]{query}[/cyan]")
+ console.print(f" [dim]期望关键词: {', '.join(expected)}[/dim]")
+
+ try:
+ results = client.find(query, limit=5)
+
+ # 收集所有召回内容
+ recall_texts = []
+ count = 0
+ if hasattr(results, "memories") and results.memories:
+ for m in results.memories:
+ text = getattr(m, "content", "") or getattr(m, "text", "") or str(m)
+ print(f" [DEBUG] memory text: {repr(text)}")
+ recall_texts.append(text)
+ uri = getattr(m, "uri", "")
+ score = getattr(m, "score", 0)
+ console.print(f" [green]Memory:[/green] {uri} (score: {score:.4f})")
+ console.print(
+ f" [dim]{text[:120]}...[/dim]"
+ if len(text) > 120
+ else f" [dim]{text}[/dim]"
+ )
+ count += len(results.memories)
+
+ if hasattr(results, "resources") and results.resources:
+ for r in results.resources:
+ text = getattr(r, "content", "") or getattr(r, "text", "") or str(r)
+ print(f" [DEBUG] resource text: {repr(text)}")
+ recall_texts.append(text)
+ console.print(f" [blue]Resource:[/blue] {r.uri} (score: {r.score:.4f})")
+ count += len(results.resources)
+
+ if hasattr(results, "skills") and results.skills:
+ count += len(results.skills)
+
+ # 检查关键词命中
+ all_text = " ".join(recall_texts)
+ hits = [kw for kw in expected if kw in all_text]
+ hit_str = ", ".join(hits) if hits else "[dim]无[/dim]"
+
+ results_table.add_row(str(i), query, str(count), hit_str)
+
+ except Exception as e:
+ console.print(f" [red]ERROR: {e}[/red]")
+ results_table.add_row(str(i), query, "[red]ERR[/red]", str(e)[:40])
+
+ console.print()
+ console.print(results_table)
+
+
+# ── 入口 ───────────────────────────────────────────────────────────────────
+
+
+def main():
+ parser = argparse.ArgumentParser(description=f"OpenViking 记忆演示 — {DISPLAY_NAME}")
+ parser.add_argument("--url", default=DEFAULT_URL, help=f"Server URL (默认: {DEFAULT_URL})")
+ parser.add_argument("--api-key", default=DEFAULT_API_KEY, help="API key")
+ parser.add_argument("--agent-id", default=DEFAULT_AGENT_ID, help="Agent ID")
+ parser.add_argument(
+ "--phase",
+ choices=["all", "ingest", "verify"],
+ default="all",
+ help="all=全部, ingest=仅写入, verify=仅验证 (默认: all)",
+ )
+ parser.add_argument(
+ "--session-id", default=DEFAULT_SESSION_ID, help=f"Session ID (默认: {DEFAULT_SESSION_ID})"
+ )
+ parser.add_argument("--wait", type=float, default=5.0, help="提交后额外等待秒数 (默认: 5)")
+ args = parser.parse_args()
+
+ console.print(
+ Panel(
+ f"[bold]OpenViking 记忆演示 — {DISPLAY_NAME}[/bold]\n"
+ f"Server: {args.url} | Phase: {args.phase}",
+ style="magenta",
+ width=PANEL_WIDTH,
+ )
+ )
+
+ client = ov.SyncHTTPClient(
+ url=args.url, api_key=args.api_key, agent_id=args.agent_id, timeout=180
+ )
+
+ try:
+ client.initialize()
+ console.print(f" [green]已连接[/green] {args.url}")
+
+ if args.phase in ("all", "ingest"):
+ run_ingest(client, session_id=args.session_id, wait_seconds=args.wait)
+
+ if args.phase in ("all", "verify"):
+ run_verify(client)
+
+ console.print(
+ Panel(
+ "[bold green]演示完成[/bold green]",
+ style="green",
+ width=PANEL_WIDTH,
+ )
+ )
+
+ except Exception as e:
+ console.print(Panel(f"[bold red]Error:[/bold red] {e}", style="red", width=PANEL_WIDTH))
+ import traceback
+
+ traceback.print_exc()
+
+ finally:
+ client.close()
+
+
+if __name__ == "__main__":
+ main()
diff --git a/tests/server/test_content_write_service.py b/tests/server/test_content_write_service.py
index bb70021cd..e005611f2 100644
--- a/tests/server/test_content_write_service.py
+++ b/tests/server/test_content_write_service.py
@@ -6,7 +6,8 @@
import pytest
from openviking.server.identity import RequestContext, Role
-from openviking.session.memory.utils.content import deserialize_full, serialize_with_metadata
+from openviking.session.memory.dataclass import MemoryFile
+from openviking.session.memory.utils import MemoryFileUtils
from openviking.storage.content_write import ContentWriteCoordinator
from openviking_cli.exceptions import (
AlreadyExistsError,
@@ -70,8 +71,9 @@ async def test_memory_replace_preserves_metadata(service):
"updated_at": "2026-04-01T10:05:00",
"fields": {"topic": "theme"},
}
- full_content = serialize_with_metadata({**metadata, "content": "Original preference"})
- expected_metadata = deserialize_full(full_content).memory_fields
+ original_mf = MemoryFile(content="Original preference", extra_fields=metadata)
+ full_content = MemoryFileUtils.write(original_mf)
+ expected_mf = MemoryFileUtils.read(full_content)
await service.viking_fs.write_file(memory_uri, full_content, ctx=ctx)
await service.fs.write(
@@ -82,10 +84,10 @@ async def test_memory_replace_preserves_metadata(service):
)
stored = await service.viking_fs.read_file(memory_uri, ctx=ctx)
- stored_result = deserialize_full(stored)
+ stored_result = MemoryFileUtils.read(stored)
- assert stored_result.plain_content == "Updated preference"
- assert stored_result.memory_fields == expected_metadata
+ assert stored_result.content == "Updated preference"
+ assert stored_result.extra_fields == expected_mf.extra_fields
@pytest.mark.asyncio
@@ -98,8 +100,9 @@ async def test_memory_append_preserves_metadata(service):
"updated_at": "2026-04-01T10:05:00",
"fields": {"topic": "theme"},
}
- full_content = serialize_with_metadata({**metadata, "content": "Original preference"})
- expected_metadata = deserialize_full(full_content).memory_fields
+ original_mf = MemoryFile(content="Original preference", extra_fields=metadata)
+ full_content = MemoryFileUtils.write(original_mf)
+ expected_mf = MemoryFileUtils.read(full_content)
await service.viking_fs.write_file(memory_uri, full_content, ctx=ctx)
await service.fs.write(
@@ -110,10 +113,10 @@ async def test_memory_append_preserves_metadata(service):
)
stored = await service.viking_fs.read_file(memory_uri, ctx=ctx)
- stored_result = deserialize_full(stored)
+ stored_result = MemoryFileUtils.read(stored)
- assert stored_result.plain_content == "Original preference\nUpdated preference"
- assert stored_result.memory_fields == expected_metadata
+ assert stored_result.content == "Original preference\nUpdated preference"
+ assert stored_result.extra_fields == expected_mf.extra_fields
@pytest.mark.asyncio
diff --git a/tests/session/memory/test_agent_experience_context_provider.py b/tests/session/memory/test_agent_experience_context_provider.py
new file mode 100644
index 000000000..0083f6178
--- /dev/null
+++ b/tests/session/memory/test_agent_experience_context_provider.py
@@ -0,0 +1,105 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: AGPL-3.0
+
+from types import SimpleNamespace
+from unittest.mock import AsyncMock, patch
+
+import pytest
+
+from openviking.server.identity import AccountNamespacePolicy, RequestContext, Role
+from openviking.session.memory.agent_experience_context_provider import AgentExperienceContextProvider
+from openviking.session.memory.memory_updater import ExtractContext
+from openviking_cli.session.user_id import UserIdentifier
+
+
+def test_create_tool_context_uses_extract_context_page_id_map():
+ provider = AgentExperienceContextProvider(
+ messages=[],
+ trajectory_summary="album release party discussion",
+ trajectory_uri="viking://agent/agent_sample_9/memories/trajectories/album_release_party_discussion.md",
+ )
+
+ extract_context = provider.get_extract_context()
+ extract_context.page_id_map.get_page_id(
+ "viking://agent/agent_sample_9/memories/trajectories/album_release_party_discussion.md"
+ )
+
+ tool_ctx = provider.create_tool_context()
+
+ assert tool_ctx.page_id_map is extract_context.page_id_map
+
+
+async def test_agent_experience_prefetch_starts_with_conversation_and_new_trajectory_read():
+ provider = AgentExperienceContextProvider(
+ messages=[],
+ trajectory_summary="album release party discussion",
+ trajectory_uri="viking://agent/agent_sample_9/memories/trajectories/album_release_party_discussion.md",
+ )
+ provider._ctx = RequestContext(
+ user=UserIdentifier(account_id="acc", user_id="user_1", agent_id="agent_sample_9"),
+ role=Role.USER,
+ namespace_policy=AccountNamespacePolicy(),
+ )
+ provider._viking_fs = AsyncMock()
+ provider._transaction_handle = None
+ provider.search_files = AsyncMock(return_value=[])
+
+ with patch(
+ "openviking.session.memory.agent_experience_context_provider.add_tool_call_pair_to_messages"
+ ) as add_tool_call_pair:
+ messages = await provider.prefetch()
+
+ assert messages[0]["role"] == "user"
+ assert "## Conversation History" in messages[0]["content"]
+ assert "After exploring, analyze the conversation" in messages[0]["content"]
+ assert add_tool_call_pair.call_count == 1
+ assert add_tool_call_pair.call_args_list[0].kwargs["result"]["context_role"] == "new_trajectory"
+ assert add_tool_call_pair.call_args_list[0].kwargs["result"]["memory_type"] == "trajectories"
+ assert add_tool_call_pair.call_args_list[0].kwargs["result"]["uri"] == provider.trajectory_uri
+ assert messages[-1]["role"] == "user"
+ assert "candidate_experience" in messages[-1]["content"]
+
+
+async def test_agent_experience_prefetch_includes_structured_read_results():
+ provider = AgentExperienceContextProvider(
+ messages=[],
+ trajectory_summary="album release party discussion",
+ trajectory_uri="viking://agent/agent_sample_9/memories/trajectories/album_release_party_discussion.md",
+ )
+ provider._ctx = RequestContext(
+ user=UserIdentifier(account_id="acc", user_id="user_1", agent_id="agent_sample_9"),
+ role=Role.USER,
+ namespace_policy=AccountNamespacePolicy(),
+ )
+ provider._viking_fs = AsyncMock()
+ provider._transaction_handle = None
+
+ provider.search_files = AsyncMock(
+ return_value=["viking://agent/agent_sample_9/memories/experiences/personal_experience_sharing_conversation_flow.md"]
+ )
+
+ read_result = {
+ "experience_name": "personal_experience_sharing_conversation_flow",
+ "content": "1 | line one\n2 | line two",
+ "page_id": 1,
+ "memory_type": "experiences",
+ }
+ provider.read_file = AsyncMock(return_value=read_result)
+ provider._read_file_contents = {
+ "viking://agent/agent_sample_9/memories/experiences/personal_experience_sharing_conversation_flow.md": SimpleNamespace(
+ extra_fields={"experience_name": "personal_experience_sharing_conversation_flow"},
+ content="line one\nline two",
+ )
+ }
+
+ with patch(
+ "openviking.session.memory.agent_experience_context_provider.add_tool_call_pair_to_messages"
+ ) as add_tool_call_pair:
+ messages = await provider.prefetch()
+
+ assert any(msg.get("role") == "user" for msg in messages)
+ assert add_tool_call_pair.call_count == 2
+ assert add_tool_call_pair.call_args_list[1].kwargs["result"]["context_role"] == "candidate_experience"
+ assert add_tool_call_pair.call_args_list[1].kwargs["result"]["page_id"] == 1
diff --git a/tests/session/memory/test_compressor_v2.py b/tests/session/memory/test_compressor_v2.py
index 6e86dc5a0..594b4537f 100644
--- a/tests/session/memory/test_compressor_v2.py
+++ b/tests/session/memory/test_compressor_v2.py
@@ -16,8 +16,12 @@ import pytest
from openviking.message import Message, TextPart
from openviking.server.identity import RequestContext, Role
from openviking.session.compressor_v2 import SessionCompressorV2
-from openviking.session.memory.memory_updater import MemoryUpdateResult
-from openviking.session.memory.utils.content import deserialize_metadata, serialize_with_metadata
+from openviking.session.memory.dataclass import MemoryField, MemoryFile, MemoryTypeSchema
+from openviking.session.memory.memory_isolation_handler import RoleScope
+from openviking.session.memory.memory_updater import ExtractContext, MemoryUpdateResult
+from openviking.session.memory.merge_op import FieldType, MergeOp
+from openviking.session.memory.extract_loop import ExtractLoop
+from openviking.session.memory.utils.memory_file_utils import MemoryFileUtils
from openviking_cli.session.user_id import UserIdentifier
from openviking_cli.utils.config import get_openviking_config, initialize_openviking_config
@@ -422,8 +426,44 @@ class TestCompressorV2:
logger.info("Test completed successfully!")
@pytest.mark.asyncio
- async def test_v2_lock_acquire_respects_max_retries(self):
- """v2 memory extraction should stop after configured lock retry limit."""
+ async def test_extract_long_term_memories_logs_agfs_fallback_at_debug(self):
+ compressor = SessionCompressorV2(vikingdb=None)
+ user = UserIdentifier.the_default_user()
+ ctx = RequestContext(user=user, role=Role.ROOT)
+ messages = [Message.create_user("test")]
+
+ dummy_registry = SimpleNamespace(initialize_memory_files=AsyncMock())
+ dummy_orchestrator = SimpleNamespace(
+ context_provider=SimpleNamespace(get_memory_schemas=lambda _ctx: []),
+ _transaction_handle=None,
+ run=AsyncMock(return_value=(None, [])),
+ )
+
+ with (
+ patch("openviking.storage.viking_fs.get_viking_fs", return_value=None),
+ patch("openviking.storage.transaction.init_lock_manager"),
+ patch("openviking.storage.transaction.get_lock_manager", return_value=None),
+ patch(
+ "openviking.session.memory.memory_type_registry.create_default_registry",
+ return_value=dummy_registry,
+ ),
+ patch.object(compressor, "_get_or_create_react", return_value=dummy_orchestrator),
+ patch("openviking.session.compressor_v2.logger.warning") as warning_mock,
+ patch("openviking.session.compressor_v2.logger.debug") as debug_mock,
+ ):
+ result = await compressor.extract_long_term_memories(
+ messages=messages,
+ ctx=ctx,
+ strict_extract_errors=False,
+ )
+
+ assert result == []
+ warning_mock.assert_not_called()
+ debug_mock.assert_any_call("AGFS unavailable, running memory extraction without locks")
+
+ @pytest.mark.asyncio
+ async def test_v2_lock_acquire_waits_without_retry_loop(self):
+ """v2 memory extraction should delegate waiting to lock manager without local retries."""
compressor = SessionCompressorV2(vikingdb=None)
user = UserIdentifier.the_default_user()
ctx = RequestContext(user=user, role=Role.ROOT)
@@ -478,7 +518,6 @@ class TestCompressorV2:
return_value=SimpleNamespace(initialize_memory_files=AsyncMock()),
),
patch.object(compressor, "_get_or_create_react", return_value=DummyOrchestrator()),
- patch("openviking.session.compressor_v2.asyncio.sleep", new=AsyncMock()),
):
initialize_openviking_config()
config = get_openviking_config()
@@ -596,11 +635,12 @@ class TestCompressorV2:
class FakeVikingFS:
def __init__(self):
- self.content = serialize_with_metadata(
- {
- "content": "debug login issue",
- "source_trajectories": ["traj-0"],
- }
+ self.content = MemoryFileUtils.write(
+ MemoryFile(
+ uri="viking://agent/default/memories/experiences/debug.md",
+ content="debug login issue",
+ extra_fields={"source_trajectories": ["traj-0"]},
+ )
)
def _uri_to_path(self, uri: str, ctx=None) -> str:
@@ -638,11 +678,298 @@ class TestCompressorV2:
viking_fs,
)
- metadata = deserialize_metadata(viking_fs.content)
- assert metadata["source_trajectories"] == ["traj-0", "traj-1"]
+ mf = MemoryFileUtils.read(viking_fs.content, uri=exp_uri)
+ assert mf.extra_fields["source_trajectories"] == ["traj-0", "traj-1"]
assert events == [
"exact:/local/default/agent/default/memories/experiences/debug.md",
"read",
"write",
"release",
]
+
+
+class TestExtractLoopPatchRepair:
+ """Tests for ExtractLoop patch validation and repair retry."""
+
+ @pytest.mark.asyncio
+ async def test_invalid_patch_search_triggers_one_repair_retry(self):
+ schema = MemoryTypeSchema(
+ memory_type="profile",
+ description="User profile",
+ directory="viking://user/{{ user_space }}/memories",
+ filename_template="profile.md",
+ fields=[
+ MemoryField(
+ name="content",
+ field_type=FieldType.STRING,
+ description="Profile content",
+ merge_op=MergeOp.PATCH,
+ )
+ ],
+ )
+ target_uri = "viking://user/default/memories/profile.md"
+ other_uri = "viking://user/default/memories/other.md"
+ target_file = MemoryFile(uri=target_uri, content="# Tim\n- Likes reading")
+ other_file = MemoryFile(uri=other_uri, content="# Other\n- Has been reading as usual")
+
+ class DummyRegistry:
+ def get(self, memory_type):
+ assert memory_type == "profile"
+ return schema
+
+ class DummyProvider:
+ read_file_contents = {
+ target_uri: target_file,
+ other_uri: other_file,
+ }
+
+ def __init__(self):
+ self.extract_context = ExtractContext([])
+
+ def get_memory_schemas(self, _ctx):
+ return [schema]
+
+ def get_output_language(self):
+ return "English"
+
+ def get_tools(self):
+ return []
+
+ def instruction(self):
+ return "Extract memories."
+
+ async def prefetch(self):
+ return []
+
+ def get_extract_context(self):
+ return self.extract_context
+
+ def _get_registry(self):
+ return DummyRegistry()
+
+ class DummyIsolationHandler:
+ def get_read_scope(self):
+ return RoleScope(user_ids=["default"], agent_ids=["default"])
+
+ def fill_role_ids(self, item_dict, role_scope):
+ item_dict.setdefault("user_id", "default")
+ item_dict.setdefault("agent_id", "default")
+
+ def calculate_memory_uris(self, memory_type_schema, operation, extract_context):
+ return [target_uri]
+
+ class DummyVLM:
+ model = "dummy"
+
+ def __init__(self):
+ self.responses = [
+ '{"profile":[{"page_id":1,"content":{"blocks":[{"search":"- Has been reading as usual","replace":"- Has been reading as usual (as of 2023-11-11)"}]} }],"delete_uris":[]}',
+ '{"profile":[{"page_id":1,"content":{"blocks":[{"search":"- Likes reading","replace":"- Likes reading\n- Has been reading as usual (as of 2023-11-11)"}]} }],"delete_uris":[]}',
+ ]
+ self.messages = []
+
+ async def get_completion_async(self, messages, tools=None, tool_choice=None):
+ self.messages.append(list(messages))
+ return self.responses.pop(0)
+
+ vlm = DummyVLM()
+ loop = ExtractLoop(
+ vlm=vlm,
+ viking_fs=MockVikingFS(),
+ max_iterations=1,
+ context_provider=DummyProvider(),
+ isolation_handler=DummyIsolationHandler(),
+ )
+
+ operations, _tools_used = await loop.run()
+
+ assert len(vlm.messages) == 2
+ second_call_content = "\n".join(message["content"] for message in vlm.messages[1])
+ assert "SEARCH/REPLACE patch could not be applied" in second_call_content
+ assert "Regenerate the complete operations JSON" in second_call_content
+ assert target_uri in second_call_content
+ assert other_uri in second_call_content
+ assert operations.upsert_operations[0].memory_fields["content"].blocks[0].search == "- Likes reading"
+
+ @pytest.mark.asyncio
+ async def test_invalid_patch_search_repairs_only_once(self):
+ schema = MemoryTypeSchema(
+ memory_type="profile",
+ description="User profile",
+ directory="viking://user/{{ user_space }}/memories",
+ filename_template="profile.md",
+ fields=[
+ MemoryField(
+ name="content",
+ field_type=FieldType.STRING,
+ description="Profile content",
+ merge_op=MergeOp.PATCH,
+ )
+ ],
+ )
+ target_uri = "viking://user/default/memories/profile.md"
+ target_file = MemoryFile(uri=target_uri, content="# Tim\n- Likes reading")
+
+ class DummyRegistry:
+ def get(self, memory_type):
+ assert memory_type == "profile"
+ return schema
+
+ class DummyProvider:
+ read_file_contents = {target_uri: target_file}
+
+ def __init__(self):
+ self.extract_context = ExtractContext([])
+
+ def get_memory_schemas(self, _ctx):
+ return [schema]
+
+ def get_output_language(self):
+ return "English"
+
+ def get_tools(self):
+ return []
+
+ def instruction(self):
+ return "Extract memories."
+
+ async def prefetch(self):
+ return []
+
+ def get_extract_context(self):
+ return self.extract_context
+
+ def _get_registry(self):
+ return DummyRegistry()
+
+ class DummyIsolationHandler:
+ def get_read_scope(self):
+ return RoleScope(user_ids=["default"], agent_ids=["default"])
+
+ def fill_role_ids(self, item_dict, role_scope):
+ item_dict.setdefault("user_id", "default")
+ item_dict.setdefault("agent_id", "default")
+
+ def calculate_memory_uris(self, memory_type_schema, operation, extract_context):
+ return [target_uri]
+
+ class DummyVLM:
+ model = "dummy"
+
+ def __init__(self):
+ self.responses = [
+ '{"profile":[{"page_id":1,"content":{"blocks":[{"search":"- Missing one","replace":"- Fixed one"}]} }],"delete_uris":[]}',
+ '{"profile":[{"page_id":1,"content":{"blocks":[{"search":"- Missing two","replace":"- Fixed two"}]} }],"delete_uris":[]}',
+ ]
+ self.messages = []
+
+ async def get_completion_async(self, messages, tools=None, tool_choice=None):
+ self.messages.append(list(messages))
+ return self.responses.pop(0)
+
+ vlm = DummyVLM()
+ loop = ExtractLoop(
+ vlm=vlm,
+ viking_fs=MockVikingFS(),
+ max_iterations=1,
+ context_provider=DummyProvider(),
+ isolation_handler=DummyIsolationHandler(),
+ )
+
+ operations, _tools_used = await loop.run()
+
+ assert len(vlm.messages) == 2
+ all_messages = "\n".join(
+ message["content"] for call_messages in vlm.messages for message in call_messages
+ )
+ assert all_messages.count("SEARCH/REPLACE patch could not be applied") == 1
+ assert operations.upsert_operations[0].memory_fields["content"].blocks[0].search == "- Missing two"
+
+ @pytest.mark.asyncio
+ async def test_fuzzy_patch_success_does_not_trigger_repair(self):
+ schema = MemoryTypeSchema(
+ memory_type="profile",
+ description="User profile",
+ directory="viking://user/{{ user_space }}/memories",
+ filename_template="profile.md",
+ fields=[
+ MemoryField(
+ name="content",
+ field_type=FieldType.STRING,
+ description="Profile content",
+ merge_op=MergeOp.PATCH,
+ )
+ ],
+ )
+ target_uri = "viking://user/default/memories/profile.md"
+ target_file = MemoryFile(uri=target_uri, content="# Tim\n- Likes reading every night")
+
+ class DummyRegistry:
+ def get(self, memory_type):
+ assert memory_type == "profile"
+ return schema
+
+ class DummyProvider:
+ read_file_contents = {target_uri: target_file}
+
+ def __init__(self):
+ self.extract_context = ExtractContext([])
+
+ def get_memory_schemas(self, _ctx):
+ return [schema]
+
+ def get_output_language(self):
+ return "English"
+
+ def get_tools(self):
+ return []
+
+ def instruction(self):
+ return "Extract memories."
+
+ async def prefetch(self):
+ return []
+
+ def get_extract_context(self):
+ return self.extract_context
+
+ def _get_registry(self):
+ return DummyRegistry()
+
+ class DummyIsolationHandler:
+ def get_read_scope(self):
+ return RoleScope(user_ids=["default"], agent_ids=["default"])
+
+ def fill_role_ids(self, item_dict, role_scope):
+ item_dict.setdefault("user_id", "default")
+ item_dict.setdefault("agent_id", "default")
+
+ def calculate_memory_uris(self, memory_type_schema, operation, extract_context):
+ return [target_uri]
+
+ class DummyVLM:
+ model = "dummy"
+
+ def __init__(self):
+ self.responses = [
+ '{"profile":[{"page_id":1,"content":{"blocks":[{"search":"- Likes reading","replace":"- Likes reading every night (as of 2023-11-11)"}]} }],"delete_uris":[]}',
+ ]
+ self.messages = []
+
+ async def get_completion_async(self, messages, tools=None, tool_choice=None):
+ self.messages.append(list(messages))
+ return self.responses.pop(0)
+
+ vlm = DummyVLM()
+ loop = ExtractLoop(
+ vlm=vlm,
+ viking_fs=MockVikingFS(),
+ max_iterations=1,
+ context_provider=DummyProvider(),
+ isolation_handler=DummyIsolationHandler(),
+ )
+
+ operations, _tools_used = await loop.run()
+
+ assert len(vlm.messages) == 1
+ assert operations.upsert_operations[0].memory_fields["content"].blocks[0].search == "- Likes reading"
diff --git a/tests/session/memory/test_graph_view.py b/tests/session/memory/test_graph_view.py
new file mode 100644
index 000000000..fd1b3ea34
--- /dev/null
+++ b/tests/session/memory/test_graph_view.py
@@ -0,0 +1,295 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: AGPL-3.0
+
+import py_compile
+import warnings
+from pathlib import Path
+
+from openviking.session.memory.graph_view import _render_graph_html
+
+
+def test_graph_view_module_compiles_without_escape_warnings():
+ path = Path(__file__).resolve().parents[3] / "openviking" / "session" / "memory" / "graph_view.py"
+ with warnings.catch_warnings():
+ warnings.simplefilter("error", SyntaxWarning)
+ py_compile.compile(str(path), doraise=True)
+
+
+def test_render_graph_html_supports_relative_markdown_links():
+ nodes = [
+ {
+ "id": "viking://user/Caroline/memories/profile.md",
+ "uri": "viking://user/Caroline/memories/profile.md",
+ "label": "profile",
+ "memory_type": "profile",
+ "category": "",
+ "content_preview": "[music](./preferences/music.md)",
+ "content_full": "[music](./preferences/music.md)\n[up](../events/2023/05/08/test.md)",
+ "content_truncated": False,
+ }
+ ]
+
+ html = _render_graph_html(nodes, [])
+
+ assert "function resolveRelativeUri(baseUri, relativeUri)" in html
+ assert "const resolvedUri = resolveRelativeUri(baseUri, href);" in html
+ assert "data-target-uri=\"${resolvedUri}\"" in html
+
+
+def test_render_graph_html_renders_tooltip_content_as_markdown():
+ html = _render_graph_html([], [])
+
+ assert "tooltip.querySelector('.desc').innerHTML = renderMarkdown(desc || '', baseUri);" in html
+ assert "tooltip.querySelector('.desc').textContent = desc || '';" not in html
+
+
+def test_render_graph_html_embeds_full_markdown_content_and_link_targets():
+ nodes = [
+ {
+ "id": "viking://user/Caroline/memories/profile.md",
+ "uri": "viking://user/Caroline/memories/profile.md",
+ "label": "profile",
+ "memory_type": "profile",
+ "category": "",
+ "content_preview": "# Caroline",
+ "content_full": "# Caroline\n\nSee [music](viking://user/Caroline/memories/preferences/music.md)",
+ "content_truncated": False,
+ }
+ ]
+ edges = [
+ {
+ "source": "viking://user/Caroline/memories/profile.md",
+ "target": "viking://user/Caroline/memories/preferences/music.md",
+ "link_type": "related_to",
+ "weight": 1.0,
+ "description": "music preference",
+ }
+ ]
+
+ html = _render_graph_html(nodes, edges)
+
+ assert '"content_full": "# Caroline\\n\\nSee [music](viking://user/Caroline/memories/preferences/music.md)"' in html
+ assert "function renderMarkdown" in html
+ assert "detailContent.innerHTML = renderMarkdown(node.content_full || node.content_preview || '', node.uri || '');" in html
+ assert "detailContent.addEventListener('click'" in html
+ assert "const targetNodeId = link.dataset.targetUri;" in html
+ assert "network.focus(targetNodeId, { animation: { duration: 350, easingFunction: 'easeInOutQuad' }, scale: network.getScale() });" in html
+
+
+def test_render_graph_html_clicking_detail_link_centers_target_node():
+ html = _render_graph_html([], [])
+
+ assert "network.focus(targetNodeId, { animation: { duration: 350, easingFunction: 'easeInOutQuad' }, scale: network.getScale() });" in html
+
+
+def test_render_graph_html_uses_dark_node_background_with_light_text():
+ nodes = [
+ {
+ "id": "viking://agent/demo/memories/experiences/a.md",
+ "uri": "viking://agent/demo/memories/experiences/a.md",
+ "label": "a",
+ "memory_type": "experiences",
+ "category": "",
+ "content_preview": "hello world",
+ "content_truncated": False,
+ }
+ ]
+
+ html = _render_graph_html(nodes, [])
+
+ assert '"background": "#0f172a"' in html
+ assert '"hover": {"background": "#0f172a", "border": "#fd79a8"}' in html
+ assert '"font": {"color": "#f8fafc", "size": 12}' in html
+ assert '"border": "#fd79a8"' in html
+
+
+def test_render_graph_html_embeds_vis_network_viewer_metadata():
+ nodes = [
+ {
+ "id": "viking://agent/demo/memories/experiences/a.md",
+ "uri": "viking://agent/demo/memories/experiences/a.md",
+ "label": "a",
+ "memory_type": "experiences",
+ "category": "",
+ "content_preview": "hello world",
+ "content_truncated": False,
+ }
+ ]
+ edges = [
+ {
+ "source": "viking://agent/demo/memories/experiences/a.md",
+ "target": "viking://agent/demo/memories/experiences/b.md",
+ "link_type": "related_to",
+ "weight": 0.8,
+ "description": "same topic",
+ }
+ ]
+
+ html = _render_graph_html(nodes, edges)
+
+ assert "vis-network" in html.lower()
+ assert "new vis.Network" in html
+ assert "shape: 'box'" in html or 'shape: "box"' in html
+ assert "content_preview" in html
+ assert "content_truncated" in html
+ assert "same topic" in html
+ assert "related_to" in html
+ assert "experiences" in html
+ assert "memory_type" in html
+ assert "cytoscape" not in html.lower()
+
+
+def test_render_graph_html_embeds_vis_network_load_guard():
+ html = _render_graph_html([], [])
+
+ assert 'window.__OPENVIKING_VIS_NETWORK_SOURCE__ = "external";' in html
+ assert '<script src="https://unpkg.com/vis-network/standalone/umd/vis-network.min.js"></script>' in html
+ assert "if (!window.vis || !window.vis.DataSet || !window.vis.Network)" in html
+ assert "Graph library failed to load. If you opened this file locally" in html
+
+
+def test_render_graph_html_keeps_newline_escape_in_split_call():
+ html = _render_graph_html([], [])
+
+ split_snippet = "const lines = html.split('\\\\n');"
+ assert split_snippet in html
+ assert "const lines = html.split('\n');" not in html
+
+
+def test_render_graph_html_stops_physics_after_stabilization():
+ html = _render_graph_html([], [])
+
+ assert "network.once('stabilized'" in html
+ assert "network.fit({ animation: false, padding: 80 });" in html
+ assert "network.setOptions({ physics: false })" in html
+
+
+def test_render_graph_html_uses_tighter_layout_configuration():
+ html = _render_graph_html([], [])
+
+ assert "gravitationalConstant: -7000" in html
+ assert "springLength: 120" in html
+ assert "avoidOverlap: 0.2" in html
+ assert "stabilization: { iterations: 250" in html
+
+
+def test_render_graph_html_supports_multi_select_memory_type_filter():
+ html = _render_graph_html([], [])
+
+ assert "const activeMemoryTypes = new Set();" in html
+ assert "activeMemoryTypes.has(memoryType)" in html
+ assert "activeMemoryTypes.size === 0" in html
+ assert "activeMemoryTypes.add(memoryType)" in html
+ assert "activeMemoryTypes.delete(memoryType)" in html
+
+
+def test_render_graph_html_restores_visibility_without_rebuilding_dataset():
+ html = _render_graph_html([], [])
+
+ assert "nodes.clear()" not in html
+ assert "edges.clear()" not in html
+ assert "restoreVisibleGraph()" in html
+ assert "hidden: false" in html
+
+
+
+
+def test_render_graph_html_inverts_selected_node_colors():
+ nodes = [
+ {
+ "id": "viking://agent/demo/memories/experiences/a.md",
+ "uri": "viking://agent/demo/memories/experiences/a.md",
+ "label": "a",
+ "memory_type": "experiences",
+ "category": "",
+ "content_preview": "hello world",
+ "content_truncated": False,
+ }
+ ]
+
+ html = _render_graph_html(nodes, [])
+
+ assert '"highlight": {"background": "#f8fafc", "border": "#fd79a8"}' in html
+ assert '"font": {"color": "#f8fafc", "size": 12}' in html
+ assert "node(values, id, selected) {" in html
+ assert "if (!selected) {" in html
+ assert "return;" in html
+ assert "values.color = { background: '#f8fafc', border: values.color.border };" in html
+ assert "label(values, id, selected) {" in html
+ assert "if (!selected) {" in html
+ assert "values.color = '#0f172a';" in html
+
+
+def test_render_graph_html_edge_details_include_source_and_target_uris():
+ html = _render_graph_html([], [])
+
+ assert "detailMeta.textContent = `${edge.link_type} · weight=${edge.weight}`;" in html
+ assert "const sourceUri = edge.from || edge.source || '';" in html
+ assert "const targetUri = edge.to || edge.target || '';" in html
+ assert """detailContent.innerHTML = renderMarkdown(`- from_uri: ${escapeHtml(sourceUri)}
+- to_uri: ${escapeHtml(targetUri)}
+
+${escapeHtml(edge.description || '(no description)')}`);""" in html
+
+
+
+
+
+
+def test_render_graph_html_renders_dynamic_relationship_legend_from_edges():
+ edges = [
+ {
+ "source": "viking://user/Caroline/memories/profile.md",
+ "target": "viking://user/Caroline/memories/preferences/music.md",
+ "link_type": "inspired_by",
+ "weight": 1.0,
+ "description": "same hash color",
+ },
+ {
+ "source": "viking://user/Caroline/memories/preferences/music.md",
+ "target": "viking://user/Caroline/memories/events/show.md",
+ "link_type": "works_with",
+ "weight": 1.0,
+ "description": "different hash color",
+ },
+ {
+ "source": "viking://user/Caroline/memories/events/show.md",
+ "target": "viking://user/Caroline/memories/entities/band.md",
+ "link_type": "inspired_by",
+ "weight": 0.5,
+ "description": "same hash color again",
+ },
+ ]
+
+ html = _render_graph_html([], edges)
+
+ assert "const activeLinkTypes = new Set();" in html
+ assert "const linkTypes = [...new Set(originalEdges.map((edge) => edge.link_type).filter(Boolean))].sort();" in html
+ assert "activeLinkTypes.has(linkType)" in html
+ assert "activeLinkTypes.add(linkType)" in html
+ assert "activeLinkTypes.delete(linkType)" in html
+ assert "inspired_by" in html
+ assert "works_with" in html
+
+
+
+
+def test_render_graph_html_keeps_node_label_plain_text_while_rendering_body_links():
+ nodes = [
+ {
+ "id": "viking://user/Caroline/memories/profile.md",
+ "uri": "viking://user/Caroline/memories/profile.md",
+ "label": "Caroline profile",
+ "memory_type": "profile",
+ "category": "",
+ "content_preview": "她喜欢[角色扮演游戏](entities/games/rpg.md),也喜欢开放世界游戏。",
+ "content_full": "她喜欢[角色扮演游戏](entities/games/rpg.md),也喜欢开放世界游戏。",
+ "content_truncated": False,
+ }
+ ]
+
+ html = _render_graph_html(nodes, [])
+
+ assert '"label": "Caroline profile"' in html
+ assert '"content_full": "她喜欢[角色扮演游戏](entities/games/rpg.md),也喜欢开放世界游戏。"' in html
+ assert '"content_preview": "她喜欢[角色扮演游戏](entities/games/rpg.md),也喜欢开放世界游戏。"' in html
diff --git a/tests/session/memory/test_graph_view_collect.py b/tests/session/memory/test_graph_view_collect.py
new file mode 100644
index 000000000..8b78d7793
--- /dev/null
+++ b/tests/session/memory/test_graph_view_collect.py
@@ -0,0 +1,198 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: AGPL-3.0
+
+from unittest.mock import AsyncMock, MagicMock
+
+import pytest
+
+from openviking.server.identity import RequestContext, Role
+from openviking.session.memory.graph_view import MemoryGraph
+from openviking_cli.session.user_id import UserIdentifier
+
+
+def _file_entry(uri: str, rel_path: str) -> dict:
+ return {"uri": uri, "rel_path": rel_path, "isDir": False}
+
+
+async def test_collect_graph_data_preserves_markdown_links_in_content_full():
+ content = """2023-08-22 (Tuesday) ChatLog:\n[Calvin]: I scored a deal with [Frank Ocean](../../../../entities/personal/calvin.md)!\n\n<!-- MEMORY_FIELDS\n{\"memory_type\": \"events\", \"links\": [{\"to_uri\": \"viking://user/Calvin/memories/entities/personal/calvin.md\", \"link_type\": \"related_to\", \"match_text\": \"Frank\"}]}\n-->"""
+
+ mock_fs = MagicMock()
+ mock_fs.tree = AsyncMock(
+ return_value=[
+ _file_entry(
+ "viking://user/Calvin/memories/events/2023/08/22/collab_with_frank_ocean.md",
+ "events/2023/08/22/collab_with_frank_ocean.md",
+ )
+ ]
+ )
+ mock_fs.read_file = AsyncMock(return_value=content)
+
+ graph = MemoryGraph(viking_fs=mock_fs)
+ ctx = RequestContext(user=UserIdentifier("acme", "alice", "bot"), role=Role.USER)
+
+ nodes, edges = await graph._collect_graph_data(["viking://user/Calvin/memories"], ctx)
+
+ assert len(nodes) == 1
+ assert (
+ nodes[0]["content_full"]
+ == "2023-08-22 (Tuesday) ChatLog:\n[Calvin]: I scored a deal with [Frank Ocean](../../../../entities/personal/calvin.md)!"
+ )
+ assert edges == []
+
+
+async def test_collect_graph_data_includes_root_level_profile_markdown():
+ content = """# Caroline\n- likes painting\n\n<!-- MEMORY_FIELDS\n{\"memory_type\": \"profile\", \"links\": []}\n-->"""
+
+ mock_fs = MagicMock()
+ mock_fs.tree = AsyncMock(
+ return_value=[_file_entry("viking://user/Caroline/memories/profile.md", "profile.md")]
+ )
+ mock_fs.read_file = AsyncMock(return_value=content)
+
+ graph = MemoryGraph(viking_fs=mock_fs)
+ ctx = RequestContext(user=UserIdentifier("acme", "alice", "bot"), role=Role.USER)
+
+ nodes, edges = await graph._collect_graph_data(["viking://user/Caroline/memories"], ctx)
+
+ assert [node["uri"] for node in nodes] == ["viking://user/Caroline/memories/profile.md"]
+ assert nodes[0]["memory_type"] == "profile"
+ assert nodes[0]["content_preview"] == "# Caroline\n- likes painting"
+ assert edges == []
+
+
+async def test_collect_graph_data_includes_content_preview():
+ content = """Demo content line 1\nDemo content line 2\n\n<!-- MEMORY_FIELDS\n{\"memory_type\": \"experiences\", \"links\": []}\n-->"""
+
+ mock_fs = MagicMock()
+ mock_fs.tree = AsyncMock(
+ return_value=[_file_entry("viking://agent/demo/memories/experiences/a.md", "experiences/a.md")]
+ )
+ mock_fs.read_file = AsyncMock(return_value=content)
+
+ graph = MemoryGraph(viking_fs=mock_fs)
+ ctx = RequestContext(user=UserIdentifier("acme", "alice", "bot"), role=Role.USER)
+
+ nodes, edges = await graph._collect_graph_data(["viking://agent/demo/memories"], ctx)
+
+ assert len(nodes) == 1
+ assert nodes[0]["memory_type"] == "experiences"
+ assert "Demo content line 1" in nodes[0]["content_preview"]
+ assert nodes[0]["content_truncated"] is False
+ assert edges == []
+
+
+async def test_collect_graph_data_keeps_profile_body_as_content_preview():
+ content = """# Caroline\n- likes painting\n\n<!-- MEMORY_FIELDS\n{\"memory_type\": \"profile\", \"links\": []}\n-->"""
+
+ mock_fs = MagicMock()
+ mock_fs.tree = AsyncMock(
+ return_value=[_file_entry("viking://user/Caroline/memories/profile.md", "profile.md")]
+ )
+ mock_fs.read_file = AsyncMock(return_value=content)
+
+ graph = MemoryGraph(viking_fs=mock_fs)
+ ctx = RequestContext(user=UserIdentifier("acme", "alice", "bot"), role=Role.USER)
+
+ nodes, edges = await graph._collect_graph_data(["viking://user/Caroline/memories"], ctx)
+
+ assert len(nodes) == 1
+ assert nodes[0]["memory_type"] == "profile"
+ assert nodes[0]["content_preview"] == "# Caroline\n- likes painting"
+ assert nodes[0]["content_truncated"] is False
+ assert edges == []
+
+
+async def test_collect_graph_data_infers_memory_type_from_parent_directory():
+ content = """# Caroline\n- likes painting\n\n<!-- MEMORY_FIELDS\n{\"links\": []}\n-->"""
+
+ mock_fs = MagicMock()
+ mock_fs.tree = AsyncMock(
+ return_value=[_file_entry("viking://user/Caroline/memories/profile.md", "profile.md")]
+ )
+ mock_fs.read_file = AsyncMock(return_value=content)
+
+ graph = MemoryGraph(viking_fs=mock_fs)
+ ctx = RequestContext(user=UserIdentifier("acme", "alice", "bot"), role=Role.USER)
+
+ nodes, edges = await graph._collect_graph_data(["viking://user/Caroline/memories"], ctx)
+
+ assert len(nodes) == 1
+ assert nodes[0]["memory_type"] == "profile"
+ assert "# Caroline" in nodes[0]["content_preview"]
+ assert edges == []
+
+
+async def test_collect_graph_data_reads_all_nodes_before_filling_edge_targets():
+ profile_uri = "viking://user/Caroline/memories/profile.md"
+ child_uri = "viking://user/Caroline/memories/preferences/color.md"
+ profile_content = """# Caroline\n- likes painting\n\n<!-- MEMORY_FIELDS\n{\"memory_type\": \"profile\", \"links\": []}\n-->"""
+ child_content = f"""Blue\n\n<!-- MEMORY_FIELDS\n{{\"memory_type\": \"preferences\", \"links\": [{{\"to_uri\": \"{profile_uri}\", \"link_type\": \"belongs_to\"}}]}}\n-->"""
+
+ mock_fs = MagicMock()
+ mock_fs.tree = AsyncMock(
+ return_value=[
+ _file_entry(child_uri, "preferences/color.md"),
+ _file_entry(profile_uri, "profile.md"),
+ ]
+ )
+ mock_fs.read_file = AsyncMock(side_effect=[child_content, profile_content])
+
+ graph = MemoryGraph(viking_fs=mock_fs)
+ ctx = RequestContext(user=UserIdentifier("acme", "alice", "bot"), role=Role.USER)
+
+ nodes, edges = await graph._collect_graph_data(["viking://user/Caroline/memories"], ctx)
+
+ profile_node = next(node for node in nodes if node["uri"] == profile_uri)
+ assert profile_node["memory_type"] == "profile"
+ assert profile_node["content_preview"] == "# Caroline\n- likes painting"
+ assert profile_node["content_full"] == "# Caroline\n- likes painting"
+ assert {
+ "source": child_uri,
+ "target": profile_uri,
+ "link_type": "belongs_to",
+ "weight": 1.0,
+ "description": "",
+ } in edges
+
+
+async def test_collect_graph_data_raises_when_reading_memory_file_fails():
+ mock_fs = MagicMock()
+ mock_fs.tree = AsyncMock(
+ return_value=[_file_entry("viking://user/Caroline/memories/profile.md", "profile.md")]
+ )
+ mock_fs.read_file = AsyncMock(side_effect=RuntimeError("boom"))
+
+ graph = MemoryGraph(viking_fs=mock_fs)
+ ctx = RequestContext(user=UserIdentifier("acme", "alice", "bot"), role=Role.USER)
+
+ with pytest.raises(RuntimeError, match="boom"):
+ await graph._collect_graph_data(["viking://user/Caroline/memories"], ctx)
+
+
+async def test_collect_graph_data_drops_edges_to_unloaded_external_nodes():
+ external_profile_uri = "viking://user/Caroline/memories/profile.md"
+ child_uri = "viking://user/Melanie/memories/preferences/color.md"
+ child_content = f"""Blue\n\n<!-- MEMORY_FIELDS\n{{\"memory_type\": \"preferences\", \"links\": [{{\"to_uri\": \"{external_profile_uri}\", \"link_type\": \"belongs_to\"}}]}}\n-->"""
+
+ mock_fs = MagicMock()
+ mock_fs.tree = AsyncMock(
+ return_value=[_file_entry(child_uri, "preferences/color.md")]
+ )
+ mock_fs.read_file = AsyncMock(return_value=child_content)
+
+ graph = MemoryGraph(viking_fs=mock_fs)
+ ctx = RequestContext(user=UserIdentifier("acme", "alice", "bot"), role=Role.USER)
+
+ nodes, edges = await graph._collect_graph_data(["viking://user/Melanie/memories"], ctx)
+
+ assert [node["uri"] for node in nodes] == [child_uri]
+ assert edges == []
diff --git a/tests/session/memory/test_json_stability.py b/tests/session/memory/test_json_stability.py
index 3c1f37811..bec614699 100644
--- a/tests/session/memory/test_json_stability.py
+++ b/tests/session/memory/test_json_stability.py
@@ -5,7 +5,9 @@ Tests for JSON stable parsing utilities.
"""
import json
+import logging
from typing import List, Optional
+from unittest.mock import patch
from pydantic import BaseModel, Field
@@ -286,6 +288,88 @@ class TestMemoryOperationsIntegration:
assert error is None
assert data["delete_uris"] == "viking://user/default/memories/old.md"
+ def test_recoverable_invalid_list_item_logs_below_error(self):
+ """Test recoverable invalid list items do not emit error-level logs."""
+
+ class SearchReplaceBlock(BaseModel):
+ search: str
+ replace: str
+
+ class StrPatch(BaseModel):
+ blocks: List[SearchReplaceBlock] = Field(default_factory=list)
+
+ class PreferenceItem(BaseModel):
+ content: str | StrPatch | None = None
+ page_id: int | None = None
+
+ class PreferenceOperations(BaseModel):
+ preferences: List[PreferenceItem] = Field(default_factory=list)
+
+ content = json.dumps(
+ {
+ "preferences": [
+ {
+ "content": {
+ "blocks": [
+ {"search": "old", "replace": "new"},
+ {"page_id": 8},
+ ]
+ },
+ "page_id": 8,
+ }
+ ]
+ }
+ )
+
+ with patch("openviking.session.memory.utils.json_parser.tracer.error") as mock_error:
+ with patch("openviking.session.memory.utils.json_parser.tracer.info") as mock_info:
+ data, error = parse_json_with_stability(content, model_class=PreferenceOperations)
+
+ assert error is None
+ assert data.preferences == []
+ assert mock_error.call_count == 0
+ assert mock_info.call_count >= 1
+
+ def test_recoverable_model_fallback_does_not_log_exception(self):
+ """Test recoverable model fallback avoids exception-level logging."""
+
+ class SearchReplaceBlock(BaseModel):
+ search: str
+ replace: str
+
+ class StrPatch(BaseModel):
+ blocks: List[SearchReplaceBlock] = Field(default_factory=list)
+
+ class PreferenceItem(BaseModel):
+ content: str | StrPatch | None = None
+ page_id: int | None = None
+
+ class PreferenceOperations(BaseModel):
+ preferences: List[PreferenceItem] = Field(default_factory=list)
+
+ content = json.dumps(
+ {
+ "preferences": [
+ {
+ "content": {
+ "blocks": [
+ {"search": "old", "replace": "new"},
+ {"page_id": 8},
+ ]
+ },
+ "page_id": 8,
+ }
+ ]
+ }
+ )
+
+ with patch("openviking.session.memory.utils.json_parser.logger.exception") as mock_exception:
+ data, error = parse_json_with_stability(content, model_class=PreferenceOperations)
+
+ assert error is None
+ assert data.preferences == []
+ assert mock_exception.call_count == 0
+
class TestParseMemoryFileWithFields:
"""Tests for parse_memory_file_with_fields function."""
diff --git a/tests/session/memory/test_memory_diff.py b/tests/session/memory/test_memory_diff.py
index 406d8c1e6..1eb8ad159 100644
--- a/tests/session/memory/test_memory_diff.py
+++ b/tests/session/memory/test_memory_diff.py
@@ -12,11 +12,7 @@ from unittest.mock import AsyncMock, MagicMock, patch
import pytest
from openviking.session.compressor_v2 import SessionCompressorV2
-from openviking.session.memory.dataclass import (
- MemoryFileContent,
- ResolvedOperation,
- ResolvedOperations,
-)
+from openviking.session.memory.dataclass import MemoryFile, ResolvedOperation, ResolvedOperations
from openviking.session.memory.memory_updater import MemoryUpdateResult
from openviking.storage.viking_fs import VikingFS
@@ -111,34 +107,27 @@ class TestMemoryDiffArchive:
"""Test building memory_diff for modified memory files (updates)."""
# Setup: files exist
- async def mock_read(uri, ctx=None):
- if uri == "memory/user/test/identity.md":
- return "# Identity\n\nOld identity content"
- raise Exception("File not found")
-
- mock_viking_fs.read_file.side_effect = mock_read
-
result = MemoryUpdateResult()
result.written_uris = ["memory/user/test/identity.md"]
+ old_mf = MemoryFile(
+ uri="memory/user/test/identity.md",
+ content="# Identity\n\nOld identity content",
+ memory_type="identity",
+ )
+ op = ResolvedOperation(
+ uris=["memory/user/test/identity.md"],
+ memory_type="identity",
+ memory_fields={},
+ old_memory_file_content=old_mf,
+ )
operations = ResolvedOperations(
- upsert_operations=[],
+ upsert_operations=[op],
delete_file_contents=[],
errors=[],
)
- # First call returns old content, second returns new content
- call_count = 0
-
- async def mock_read_multiple(uri, ctx=None):
- nonlocal call_count
- call_count += 1
- if call_count == 1:
- return "# Identity\n\nOld identity content"
- else:
- return "# Identity\n\nNew identity content"
-
- mock_viking_fs.read_file.side_effect = mock_read_multiple
+ mock_viking_fs.read_file = AsyncMock(return_value="# Identity\n\nNew identity content")
diff = await compressor._build_memory_diff(
result=result,
@@ -156,11 +145,11 @@ class TestMemoryDiffArchive:
result = MemoryUpdateResult()
result.deleted_uris = ["memory/user/test/context/old_project.md"]
- deleted_content = MemoryFileContent(
+ deleted_content = MemoryFile(
uri="memory/user/test/context/old_project.md",
- plain_content="# Old Project\n\nThis project was deleted",
+ content="# Old Project\n\nThis project was deleted",
memory_type="context",
- memory_fields={"project": "test"},
+ extra_fields={"project": "test"},
)
operations = ResolvedOperations(
@@ -188,22 +177,16 @@ class TestMemoryDiffArchive:
result.edited_uris = ["memory/user/test/identity.md"]
# Setup operation with old content
- old_content = MemoryFileContent(
+ old_content = MemoryFile(
uri="memory/user/test/identity.md",
- plain_content="# Identity\n\nOld content",
+ content="# Identity\n\nOld content",
memory_type="identity",
- memory_fields={"name": "test"},
+ extra_fields={"name": "test"},
)
operation = ResolvedOperation(
uris=["memory/user/test/identity.md"],
memory_type="identity",
memory_fields={"name": "test"},
- new_memory_file_content=MemoryFileContent(
- uri="memory/user/test/identity.md",
- plain_content="# Identity\n\nNew content",
- memory_type="identity",
- memory_fields={"name": "test"},
- ),
old_memory_file_content=old_content,
)
@@ -254,8 +237,24 @@ class TestMemoryDiffArchive:
"memory/user/test/context/new.md", # new -> add
]
+ old_mf = MemoryFile(
+ uri="memory/user/test/identity.md",
+ content="# Existing\n\nOld content",
+ memory_type="identity",
+ )
+ op_existing = ResolvedOperation(
+ uris=["memory/user/test/identity.md"],
+ memory_type="identity",
+ memory_fields={},
+ old_memory_file_content=old_mf,
+ )
+ op_new = ResolvedOperation(
+ uris=["memory/user/test/context/new.md"],
+ memory_type="context",
+ memory_fields={},
+ )
operations = ResolvedOperations(
- upsert_operations=[],
+ upsert_operations=[op_existing, op_new],
delete_file_contents=[],
errors=[],
)
diff --git a/tests/session/memory/test_memory_patch.py b/tests/session/memory/test_memory_patch.py
index 856d5f950..89ee0e8a4 100644
--- a/tests/session/memory/test_memory_patch.py
+++ b/tests/session/memory/test_memory_patch.py
@@ -1,155 +1,13 @@
# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
# SPDX-License-Identifier: AGPL-3.0
"""
-Tests for MemoryPatchHandler.
+Tests for removed text patch API.
"""
-import pytest
+import openviking.session.memory.merge_op as merge_op
+from openviking.session.memory.merge_op import patch_handler
-from openviking.session.memory.merge_op import MemoryPatchHandler, PatchParseError
-
-class TestMemoryPatchHandler:
- """Tests for MemoryPatchHandler."""
-
- def setup_method(self):
- self.handler = MemoryPatchHandler()
-
- def test_apply_content_patch_basic(self):
- """Test basic SEARCH/REPLACE patch."""
- original = "Hello world\nThis is a test"
- patch = """<<<<<<< SEARCH
-:start_line:1
--------
-Hello world
-=======
-Hello everyone
->>>>>>> REPLACE
-"""
-
- result = self.handler.apply_content_patch(original, patch)
- assert "Hello everyone" in result
- assert "This is a test" in result
-
- def test_apply_content_patch_without_line_number(self):
- """Test patch without line number."""
- original = "Line 1\nLine 2\nLine 3"
- patch = """<<<<<<< SEARCH
-Line 2
-=======
-Line 2 modified
->>>>>>> REPLACE
-"""
-
- result = self.handler.apply_content_patch(original, patch)
- assert "Line 2 modified" in result
-
- def test_apply_content_patch_not_found_raises_error(self):
- """Test that search not found raises PatchParseError."""
- original = "Original content"
- patch = """<<<<<<< SEARCH
-Non-existent content
-=======
-New content
->>>>>>> REPLACE
-"""
-
- with pytest.raises(PatchParseError):
- self.handler.apply_content_patch(original, patch)
-
- def test_parse_patch_invalid_missing_search(self):
- """Test invalid patch missing SEARCH marker."""
- patch = """=======
-content
->>>>>>> REPLACE
-"""
-
- with pytest.raises(PatchParseError):
- self.handler.apply_content_patch("original", patch)
-
- def test_parse_patch_invalid_missing_split(self):
- """Test invalid patch missing split marker."""
- patch = """<<<<<<< SEARCH
-content
->>>>>>> REPLACE
-"""
-
- with pytest.raises(PatchParseError):
- self.handler.apply_content_patch("original", patch)
-
- def test_apply_content_patch_multiple_blocks(self):
- """Test applying patch with multiple SEARCH/REPLACE blocks."""
- original = """Line 1
-Line 2
-Line 3
-Line 4"""
- patch = """<<<<<<< SEARCH
-:start_line:1
--------
-Line 1
-=======
-Line 1 modified
->>>>>>> REPLACE
-<<<<<<< SEARCH
-:start_line:3
--------
-Line 3
-=======
-Line 3 modified
->>>>>>> REPLACE
-"""
- result = self.handler.apply_content_patch(original, patch)
- assert "Line 1 modified" in result
- assert "Line 3 modified" in result
- assert "Line 2" in result
- assert "Line 4" in result
-
- def test_apply_content_patch_with_indentation(self):
- """Test that indentation is preserved."""
- original = """def func():
- if True:
- print("hello")
- return"""
- patch = """<<<<<<< SEARCH
-:start_line:2
--------
- if True:
- print("hello")
-=======
- if True:
- print("hello world")
- print("another line")
->>>>>>> REPLACE
-"""
- result = self.handler.apply_content_patch(original, patch)
- assert " if True:" in result
- assert ' print("hello world")' in result
- assert ' print("another line")' in result
-
- def test_apply_content_patch_fuzzy_matching(self):
- """Test fuzzy matching with a lower threshold."""
- handler = MemoryPatchHandler(fuzzy_threshold=0.8)
- original = """def calculate():
- total = 0
- for i in range(10):
- total += i
- return total"""
- # Search content has a small difference (missing space)
- patch = """<<<<<<< SEARCH
-:start_line:1
--------
-def calculate():
- total = 0
- for i in range(10):
- total += i
- return total
-=======
-def calculate():
- sum = 0
- for i in range(10):
- sum += i
- return sum
->>>>>>> REPLACE
-"""
- result = handler.apply_content_patch(original, patch)
- assert "sum = 0" in result
+def test_text_patch_handler_api_is_removed():
+ assert not hasattr(patch_handler, "MemoryPatchHandler")
+ assert not hasattr(merge_op, "MemoryPatchHandler")
diff --git a/tests/session/memory/test_memory_read_tool_strip_links.py b/tests/session/memory/test_memory_read_tool_strip_links.py
new file mode 100644
index 000000000..08626f540
--- /dev/null
+++ b/tests/session/memory/test_memory_read_tool_strip_links.py
@@ -0,0 +1,72 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: AGPL-3.0
+
+import pytest
+
+from openviking.server.identity import RequestContext, Role, ToolContext
+from openviking.session.memory.dataclass import MemoryFile
+from openviking.session.memory.tools import MemoryReadTool
+from openviking_cli.session.user_id import UserIdentifier
+
+
+class MockPageIdMap:
+ def get_page_id(self, uri):
+ return None
+
+
+class MockVikingFS:
+ async def read_file(self, uri, ctx=None, **kwargs):
+ return (
+ "Gina values [emotional support](../../events/2023/03/23/mutual_business_support.md) "
+ "with Jon.\n\n"
+ "<!-- MEMORY_FIELDS\n"
+ "{\"memory_type\": \"experiences\"}\n"
+ "-->"
+ )
+
+
+async def test_read_tool_strips_local_memory_links_from_llm_content():
+ tool_ctx = ToolContext(
+ viking_fs=MockVikingFS(),
+ request_ctx=RequestContext(user=UserIdentifier.the_default_user(), role=Role.USER),
+ default_search_uris=[],
+ read_file_contents={},
+ page_id_map=MockPageIdMap(),
+ )
+
+ result = await MemoryReadTool().execute(
+ tool_ctx,
+ uri="viking://user/default/memories/experiences/test.md",
+ )
+
+ assert result["content"] == "1 | Gina values emotional support with Jon."
+
+
+async def test_read_tool_uses_memory_file_plain_content(monkeypatch):
+ called = False
+ original_plain_content = MemoryFile.plain_content
+
+ def tracking_plain_content(self):
+ nonlocal called
+ called = True
+ return original_plain_content(self)
+
+ monkeypatch.setattr(MemoryFile, "plain_content", tracking_plain_content)
+
+ tool_ctx = ToolContext(
+ viking_fs=MockVikingFS(),
+ request_ctx=RequestContext(user=UserIdentifier.the_default_user(), role=Role.USER),
+ default_search_uris=[],
+ read_file_contents={},
+ page_id_map=MockPageIdMap(),
+ )
+
+ result = await MemoryReadTool().execute(
+ tool_ctx,
+ uri="viking://user/default/memories/experiences/test.md",
+ )
+
+ assert called is True
+ assert result["content"] == "1 | Gina values emotional support with Jon."
diff --git a/tests/session/memory/test_memory_timestamp_parsing.py b/tests/session/memory/test_memory_timestamp_parsing.py
index f4f32f0f5..c930abe39 100644
--- a/tests/session/memory/test_memory_timestamp_parsing.py
+++ b/tests/session/memory/test_memory_timestamp_parsing.py
@@ -11,7 +11,8 @@ from openviking.session.memory.memory_updater import MessageRange
from openviking.session.memory.session_extract_context_provider import (
SessionExtractContextProvider,
)
-from openviking.session.memory.utils import deserialize_full, serialize_with_metadata
+from openviking.session.memory.utils import MemoryFileUtils
+from openviking.session.memory.dataclass import MemoryFile
def _message(*, created_at: str, role: str = "user", text: str = "hello") -> Message:
@@ -26,7 +27,7 @@ def _message(*, created_at: str, role: str = "user", text: str = "hello") -> Mes
@pytest.fixture
def stub_provider_config(monkeypatch):
config = SimpleNamespace(
- memory=SimpleNamespace(eager_prefetch=False),
+ memory=SimpleNamespace(eager_prefetch=False, prefetch_search_topn=5, link_enabled=True),
language_fallback="en",
)
monkeypatch.setattr(
@@ -56,11 +57,13 @@ def test_conversation_message_accepts_z_suffix_timestamps(stub_provider_config):
def test_message_range_accepts_extended_fractional_seconds():
msg_range = MessageRange(
[
- _message(created_at="2026-04-17T09:10:11.1234567+08:00"),
- _message(
- created_at="2026-04-17T09:12:13.7654321+08:00",
- role="assistant",
- ),
+ [
+ _message(created_at="2026-04-17T09:10:11.1234567+08:00"),
+ _message(
+ created_at="2026-04-17T09:12:13.7654321+08:00",
+ role="assistant",
+ ),
+ ]
]
)
@@ -69,17 +72,18 @@ def test_message_range_accepts_extended_fractional_seconds():
def test_deserialize_full_parses_memory_metadata_timestamps_with_z_suffix():
- full_content = serialize_with_metadata(
- {
- "content": "memory body",
+ mf = MemoryFile(
+ content="memory body",
+ extra_fields={
"created_at": "2026-04-17T01:26:14.481Z",
"updated_at": "2026-04-17T09:10:11.1234567+08:00",
- }
+ },
)
+ full_content = MemoryFileUtils.write(mf)
- result = deserialize_full(full_content)
+ result = MemoryFileUtils.read(full_content)
- assert result.plain_content == "memory body"
- assert result.memory_fields is not None
- assert result.memory_fields["created_at"].isoformat() == "2026-04-17T01:26:14.481000+00:00"
- assert result.memory_fields["updated_at"].isoformat() == "2026-04-17T09:10:11.123456+08:00"
+ assert result.content == "memory body"
+ assert result.extra_fields is not None
+ assert result.extra_fields["created_at"].isoformat() == "2026-04-17T01:26:14.481000+00:00"
+ assert result.extra_fields["updated_at"].isoformat() == "2026-04-17T09:10:11.123456+08:00"
diff --git a/tests/session/memory/test_memory_tools.py b/tests/session/memory/test_memory_tools.py
index fc9eac81e..05a9087ad 100644
--- a/tests/session/memory/test_memory_tools.py
+++ b/tests/session/memory/test_memory_tools.py
@@ -6,13 +6,14 @@ Tests for memory tools.
import pytest
+from openviking.session.memory.dataclass import MemoryFile
from openviking.server.identity import RequestContext, Role, ToolContext
from openviking.session.memory.tools import (
+ MEMORY_TOOLS_REGISTRY,
MemoryLsTool,
MemoryReadTool,
MemorySearchTool,
get_tool,
- list_tools,
get_tool_schemas,
)
from openviking_cli.session.user_id import UserIdentifier
@@ -28,8 +29,140 @@ class TestMemoryTools:
assert tool.name == "read"
assert "Read single file" in tool.description
assert "uri" in tool.parameters["properties"]
+ assert "offset" in tool.parameters["properties"]
+ assert "limit" in tool.parameters["properties"]
assert "required" in tool.parameters
+ @pytest.mark.asyncio
+ async def test_read_tool_strips_local_memory_links_from_llm_content(self):
+ class MockPageIdMap:
+ def get_page_id(self, uri):
+ return None
+
+ class MockVikingFS:
+ async def read_file(self, uri, ctx=None, **kwargs):
+ return (
+ "Gina values [emotional support](../../events/2023/03/23/mutual_business_support.md) "
+ "with Jon.\n\n"
+ "<!-- MEMORY_FIELDS\n"
+ "{\"memory_type\": \"experiences\"}\n"
+ "-->"
+ )
+
+ tool_ctx = ToolContext(
+ viking_fs=MockVikingFS(),
+ request_ctx=RequestContext(user=UserIdentifier.the_default_user(), role=Role.USER),
+ default_search_uris=[],
+ read_file_contents={},
+ page_id_map=MockPageIdMap(),
+ )
+
+ result = await MemoryReadTool().execute(
+ tool_ctx,
+ uri="viking://user/default/memories/experiences/test.md",
+ )
+
+ assert result["content"] == "1\tGina values emotional support with Jon."
+
+ @pytest.mark.asyncio
+ async def test_read_tool_uses_memory_file_plain_content(self, monkeypatch):
+ class MockPageIdMap:
+ def get_page_id(self, uri):
+ return None
+
+ class MockVikingFS:
+ async def read_file(self, uri, ctx=None, **kwargs):
+ return (
+ "Gina values [emotional support](../../events/2023/03/23/mutual_business_support.md) "
+ "with Jon.\n\n"
+ "<!-- MEMORY_FIELDS\n"
+ '{"memory_type": "experiences"}\n'
+ "-->"
+ )
+
+ called = False
+ original_plain_content = MemoryFile.plain_content
+
+ def tracking_plain_content(self):
+ nonlocal called
+ called = True
+ return original_plain_content(self)
+
+ monkeypatch.setattr(MemoryFile, "plain_content", tracking_plain_content)
+
+ tool_ctx = ToolContext(
+ viking_fs=MockVikingFS(),
+ request_ctx=RequestContext(user=UserIdentifier.the_default_user(), role=Role.USER),
+ default_search_uris=[],
+ read_file_contents={},
+ page_id_map=MockPageIdMap(),
+ )
+
+ result = await MemoryReadTool().execute(
+ tool_ctx,
+ uri="viking://user/default/memories/experiences/test.md",
+ )
+
+ assert called is True
+ assert result["content"] == "1\tGina values emotional support with Jon."
+
+ @pytest.mark.asyncio
+ async def test_read_tool_uses_offset_and_limit_for_visible_content(self):
+ class MockPageIdMap:
+ def get_page_id(self, uri):
+ return 42
+
+ class MockVikingFS:
+ async def read_file(self, uri, ctx=None, **kwargs):
+ return "line1\nline2\nline3\n\n<!-- MEMORY_FIELDS\n{\"memory_type\": \"experiences\"}\n-->"
+
+ tool_ctx = ToolContext(
+ viking_fs=MockVikingFS(),
+ request_ctx=RequestContext(user=UserIdentifier.the_default_user(), role=Role.USER),
+ default_search_uris=[],
+ read_file_contents={},
+ page_id_map=MockPageIdMap(),
+ )
+
+ result = await MemoryReadTool().execute(
+ tool_ctx,
+ uri="viking://user/default/memories/experiences/test.md",
+ offset=1,
+ limit=1,
+ )
+
+ assert result["page_id"] == 42
+ assert result["content"] == "2\tline2"
+
+ @pytest.mark.asyncio
+ async def test_read_tool_warns_when_offset_is_past_end_of_file(self):
+ class MockPageIdMap:
+ def get_page_id(self, uri):
+ return None
+
+ class MockVikingFS:
+ async def read_file(self, uri, ctx=None, **kwargs):
+ return "line1\nline2\n\n<!-- MEMORY_FIELDS\n{\"memory_type\": \"experiences\"}\n-->"
+
+ tool_ctx = ToolContext(
+ viking_fs=MockVikingFS(),
+ request_ctx=RequestContext(user=UserIdentifier.the_default_user(), role=Role.USER),
+ default_search_uris=[],
+ read_file_contents={},
+ page_id_map=MockPageIdMap(),
+ )
+
+ result = await MemoryReadTool().execute(
+ tool_ctx,
+ uri="viking://user/default/memories/experiences/test.md",
+ offset=5,
+ )
+
+ assert result["content"] == (
+ "<system-reminder>Warning: the file exists but is shorter than the provided "
+ "offset (6). The file has 2 lines.</system-reminder>"
+ )
+
def test_search_tool_properties(self):
"""Test MemorySearchTool properties."""
tool = MemorySearchTool()
@@ -120,10 +253,9 @@ class TestMemoryTools:
def test_tool_registry(self):
"""Test tool registry functions."""
# Check that default tools are registered
- all_tools = list_tools()
- assert "read" in all_tools
- assert "search" in all_tools
- assert "ls" in all_tools
+ assert "read" in MEMORY_TOOLS_REGISTRY
+ assert "search" in MEMORY_TOOLS_REGISTRY
+ assert "ls" in MEMORY_TOOLS_REGISTRY
# Check get_tool
read_tool = get_tool("read")
@@ -134,4 +266,4 @@ class TestMemoryTools:
schemas = get_tool_schemas()
schema_names = [s["function"]["name"] for s in schemas]
assert "read" in schema_names
- assert all(name in all_tools for name in schema_names)
+ assert all(name in MEMORY_TOOLS_REGISTRY for name in schema_names)
diff --git a/tests/session/memory/test_memory_updater.py b/tests/session/memory/test_memory_updater.py
index 9f6b4254c..caf9cea2e 100644
--- a/tests/session/memory/test_memory_updater.py
+++ b/tests/session/memory/test_memory_updater.py
@@ -9,16 +9,20 @@ from unittest.mock import AsyncMock, MagicMock
import pytest
+from openviking.message import Message
+from openviking.message.part import TextPart
from openviking.server.identity import AccountNamespacePolicy, RequestContext, Role
from openviking.session.memory.dataclass import (
+ MemoryFile,
MemoryField,
- MemoryFileContent,
MemoryTypeSchema,
ResolvedOperation,
ResolvedOperations,
+ StoredLink,
)
from openviking.session.memory.memory_type_registry import MemoryTypeRegistry
from openviking.session.memory.memory_updater import (
+ ExtractContext,
MemoryUpdater,
MemoryUpdateResult,
)
@@ -29,9 +33,8 @@ from openviking.session.memory.merge_op import (
StrPatch,
)
from openviking.session.memory.utils import (
- deserialize_full,
+ MemoryFileUtils,
parse_memory_file_with_fields,
- serialize_with_metadata,
)
from openviking_cli.session.user_id import UserIdentifier
@@ -90,6 +93,15 @@ class TestMemoryUpdateResult:
class TestMemoryUpdater:
"""Tests for MemoryUpdater."""
+ def test_extract_context_initializes_page_id_map(self):
+ extract_context = ExtractContext(
+ messages=[Message(id="1", role="user", parts=[TextPart(text="hi")])]
+ )
+
+ assert extract_context.page_id_map is not None
+ page_id = extract_context.page_id_map.get_page_id("viking://user/a/memories/profile.md")
+ assert page_id == 1
+
def test_create(self):
"""Test creating a MemoryUpdater."""
updater = MemoryUpdater()
@@ -114,6 +126,86 @@ class TestMemoryUpdater:
assert updater._registry == registry
+ @pytest.mark.asyncio
+ async def test_apply_operations_preserves_pre_resolved_multi_uris_for_new_page_ids(self):
+ registry = MagicMock()
+ registry.get.return_value = MemoryTypeSchema(
+ memory_type="entities",
+ description="entity memory",
+ directory="viking://user/{{ user_space }}/memories/entities",
+ filename_template="{{ name }}.md",
+ fields=[],
+ )
+
+ updater = MemoryUpdater(registry=registry)
+ updater._get_viking_fs = MagicMock(return_value=MagicMock())
+ updater._apply_upsert = AsyncMock(return_value=None)
+ updater._vectorize_memories = AsyncMock()
+ updater.generate_overview = AsyncMock()
+
+ alice_uri = "viking://user/alice/memories/entities/SharedFact.md"
+ bob_uri = "viking://user/bob/memories/entities/SharedFact.md"
+ operation = ResolvedOperation(
+ memory_fields={"name": "SharedFact", "content": "shared content"},
+ memory_type="entities",
+ uris=[alice_uri, bob_uri],
+ page_id=100,
+ )
+ operations = ResolvedOperations(
+ upsert_operations=[operation],
+ delete_file_contents=[],
+ errors=[],
+ )
+
+ extract_context = ExtractContext([])
+ extract_context.page_id_map.register_new_page_id(alice_uri, 100)
+ extract_context.page_id_map.register_new_page_id(bob_uri, 100)
+ isolation_handler = MagicMock()
+
+ ctx = RequestContext(user=UserIdentifier("acme", "alice", "bot"), role=Role.USER)
+
+ result = await updater.apply_operations(
+ operations=operations,
+ ctx=ctx,
+ extract_context=extract_context,
+ isolation_handler=isolation_handler,
+ )
+
+ assert set(operation.uris) == {alice_uri, bob_uri}
+ assert set(result.written_uris) == {alice_uri, bob_uri}
+ isolation_handler.calculate_memory_uris.assert_not_called()
+
+ @pytest.mark.asyncio
+ async def test_apply_operations_requires_pre_resolved_uris(self):
+ registry = MagicMock()
+ registry.get.return_value = MemoryTypeSchema(
+ memory_type="entities",
+ description="entity memory",
+ directory="viking://user/{{ user_space }}/memories/entities",
+ filename_template="{{ name }}.md",
+ fields=[],
+ )
+
+ updater = MemoryUpdater(registry=registry)
+ updater._get_viking_fs = MagicMock(return_value=MagicMock())
+
+ operations = ResolvedOperations(
+ upsert_operations=[
+ ResolvedOperation(
+ memory_fields={"name": "SharedFact", "content": "shared content"},
+ memory_type="entities",
+ uris=[],
+ page_id=100,
+ )
+ ],
+ delete_file_contents=[],
+ errors=[],
+ )
+ ctx = RequestContext(user=UserIdentifier("acme", "alice", "bot"), role=Role.USER)
+
+ with pytest.raises(ValueError, match="missing resolved URIs"):
+ await updater.apply_operations(operations=operations, ctx=ctx)
+
@pytest.mark.asyncio
@pytest.mark.parametrize(
("policy", "schema_directory", "resolved_uri", "expected_directory", "memory_type"),
@@ -167,17 +259,16 @@ class TestMemoryUpdater:
updater._vectorize_memories = AsyncMock()
updater.generate_overview = AsyncMock()
- resolved = ResolvedOperations()
- resolved.operations.append(
- ResolvedOperation(
- model={"name": "demo"},
- uri=resolved_uri,
- memory_type=memory_type,
- )
- )
- monkeypatch.setattr(
- "openviking.session.memory.memory_updater.resolve_all_operations",
- lambda *args, **kwargs: resolved,
+ resolved = ResolvedOperations(
+ upsert_operations=[
+ ResolvedOperation(
+ memory_fields={"name": "demo"},
+ memory_type=memory_type,
+ uris=[resolved_uri],
+ )
+ ],
+ delete_file_contents=[],
+ errors=[],
)
ctx = RequestContext(
@@ -186,7 +277,7 @@ class TestMemoryUpdater:
namespace_policy=policy,
)
- result = await updater.apply_operations(operations=SimpleNamespace(), ctx=ctx)
+ result = await updater.apply_operations(operations=resolved, ctx=ctx)
assert result.written_uris == [resolved_uri]
updater.generate_overview.assert_awaited_once_with(
@@ -195,6 +286,134 @@ class TestMemoryUpdater:
ctx,
None,
)
+ @pytest.mark.asyncio
+ async def test_apply_operations_skips_link_updates_for_deleted_uris(self, monkeypatch):
+ deleted_uri = "viking://agent/agent_sample_3/memories/experiences/old.md"
+ written_uri = "viking://agent/agent_sample_3/memories/experiences/new.md"
+
+ schema = MemoryTypeSchema(
+ memory_type="experiences",
+ description="experience memory",
+ directory="viking://agent/{{ agent_space }}/memories/experiences",
+ filename_template="{{ experience_name }}.md",
+ fields=[],
+ overview_template="overview",
+ )
+ registry = MagicMock()
+ registry.get.return_value = schema
+
+ updater = MemoryUpdater(registry=registry)
+ updater._vectorize_memories = AsyncMock()
+ updater.generate_overview = AsyncMock()
+
+ mock_viking_fs = MagicMock()
+ mock_viking_fs.read_file = AsyncMock(side_effect=AssertionError("deleted URI should not be read"))
+ mock_viking_fs.write_file = AsyncMock()
+ updater._get_viking_fs = MagicMock(return_value=mock_viking_fs)
+
+ resolved = ResolvedOperations(
+ upsert_operations=[
+ ResolvedOperation(
+ memory_fields={"experience_name": "new"},
+ memory_type="experiences",
+ uris=[written_uri],
+ )
+ ],
+ delete_file_contents=[MemoryFile(uri=deleted_uri, extra_fields={"memory_type": "experiences"})],
+ errors=[],
+ resolved_links=[
+ StoredLink(
+ from_uri=deleted_uri,
+ to_uri=written_uri,
+ )
+ ],
+ )
+
+
+ async def mock_apply_upsert(resolved_op, ctx, extract_context=None):
+ return None
+
+ async def mock_apply_delete(uri, ctx):
+ assert uri == deleted_uri
+
+ updater._apply_upsert = AsyncMock(side_effect=mock_apply_upsert)
+ updater._apply_delete = AsyncMock(side_effect=mock_apply_delete)
+
+ ctx = RequestContext(user=UserIdentifier("acme", "alice", "bot"), role=Role.USER)
+
+ result = await updater.apply_operations(operations=resolved, ctx=ctx)
+
+ assert result.written_uris == [written_uri]
+ assert result.deleted_uris == [deleted_uri]
+ mock_viking_fs.read_file.assert_not_awaited()
+
+ @pytest.mark.asyncio
+ async def test_apply_operations_routes_backlinks_to_matching_uri_only(self):
+ caroline_uri = "viking://user/Caroline/memories/events/2023/05/08/career_education_planning.md"
+ melanie_uri = "viking://user/Melanie/memories/events/2023/05/08/career_education_planning.md"
+ profile_uri = "viking://user/Caroline/memories/profile.md"
+
+ schema = MemoryTypeSchema(
+ memory_type="events",
+ description="event memory",
+ directory="viking://user/{{ user_space }}/memories/events/{{ year }}/{{ month }}/{{ day }}",
+ filename_template="{{ event_name }}.md",
+ fields=[],
+ overview_template="overview",
+ )
+ registry = MagicMock()
+ registry.get.return_value = schema
+
+ store = {}
+ mock_viking_fs = MagicMock()
+
+ async def mock_read_file(uri, **kwargs):
+ return store.get(uri)
+
+ async def mock_write_file(uri, content, **kwargs):
+ store[uri] = content
+
+ mock_viking_fs.read_file = mock_read_file
+ mock_viking_fs.write_file = mock_write_file
+
+ updater = MemoryUpdater(registry=registry)
+ updater._get_viking_fs = MagicMock(return_value=mock_viking_fs)
+ updater._vectorize_memories = AsyncMock()
+ updater.generate_overview = AsyncMock()
+
+ operations = ResolvedOperations(
+ upsert_operations=[
+ ResolvedOperation(
+ memory_fields={
+ "event_name": "career_education_planning",
+ "content": "Career planning conversation",
+ },
+ memory_type="events",
+ uris=[caroline_uri, melanie_uri],
+ page_id=101,
+ )
+ ],
+ delete_file_contents=[],
+ errors=[],
+ resolved_links=[
+ StoredLink(
+ from_uri=profile_uri,
+ to_uri=caroline_uri,
+ match_text="career",
+ description="Caroline's profile references her career plans",
+ )
+ ],
+ )
+
+ ctx = RequestContext(user=UserIdentifier("acme", "alice", "bot"), role=Role.USER)
+
+ await updater.apply_operations(operations=operations, ctx=ctx)
+
+ caroline = parse_memory_file_with_fields(store[caroline_uri])
+ melanie = parse_memory_file_with_fields(store[melanie_uri])
+
+ assert [link["to_uri"] for link in caroline["backlinks"]] == [caroline_uri]
+ assert melanie.get("backlinks", []) == []
# The TestApplyWriteWithContentInFields tests are outdated because WriteOp no longer exists
@@ -206,19 +425,33 @@ class TestMemoryUpdater:
class TestApplyEditWithSearchReplacePatch:
"""Tests for _apply_edit with SEARCH/REPLACE patches."""
+ def _make_updater_with_registry(self):
+ content_field = MemoryField(
+ name="content",
+ field_type=FieldType.STRING,
+ merge_op=MergeOp.PATCH,
+ )
+ schema = MemoryTypeSchema(
+ memory_type="test",
+ description="test",
+ fields=[content_field],
+ )
+ registry = MemoryTypeRegistry()
+ registry.register(schema)
+ return MemoryUpdater(registry=registry)
+
@pytest.mark.asyncio
async def test_apply_edit_with_str_patch_instance(self):
"""Test _apply_edit with StrPatch instance."""
- updater = MemoryUpdater()
+ updater = self._make_updater_with_registry()
# Original content
original_content = """Line 1
Line 2
Line 3
Line 4"""
- original_metadata = {"name": "test"}
- original_metadata_with_content = {**original_metadata, "content": original_content}
- original_full_content = serialize_with_metadata(original_metadata_with_content)
+ original_mf = MemoryFile(content=original_content, extra_fields={"name": "test"})
+ original_full_content = MemoryFileUtils.write(original_mf)
# Mock VikingFS
mock_viking_fs = MagicMock()
@@ -246,28 +479,32 @@ Line 4"""
mock_ctx = MagicMock()
# Apply edit
- await updater._apply_upsert({"content": patch}, "viking://test/test.md", mock_ctx)
+ op = ResolvedOperation(
+ memory_fields={"content": patch},
+ memory_type="test",
+ uris=["viking://test/test.md"],
+ )
+ await updater._apply_upsert(op, mock_ctx)
# Verify
assert written_content is not None
- result = deserialize_full(written_content)
- assert "Line 1" in result.plain_content
- assert "Line 2 modified" in result.plain_content
- assert "Line 3 modified" in result.plain_content
- assert "Line 4" in result.plain_content
+ result = MemoryFileUtils.read(written_content)
+ assert "Line 1" in result.content
+ assert "Line 2 modified" in result.content
+ assert "Line 3 modified" in result.content
+ assert "Line 4" in result.content
@pytest.mark.asyncio
async def test_apply_edit_with_str_patch_dict(self):
"""Test _apply_edit with StrPatch in dict form (from JSON parsing)."""
- updater = MemoryUpdater()
+ updater = self._make_updater_with_registry()
# Original content
original_content = """Hello world
This is a test
Goodbye"""
- original_metadata = {"name": "test"}
- original_metadata_with_content = {**original_metadata, "content": original_content}
- original_full_content = serialize_with_metadata(original_metadata_with_content)
+ original_mf = MemoryFile(content=original_content, extra_fields={"name": "test"})
+ original_full_content = MemoryFileUtils.write(original_mf)
# Mock VikingFS
mock_viking_fs = MagicMock()
@@ -288,27 +525,37 @@ Goodbye"""
mock_ctx = MagicMock()
# Apply edit
- await updater._apply_upsert({"content": patch_dict}, "viking://test/test.md", mock_ctx)
+ op = ResolvedOperation(
+ memory_fields={"content": patch_dict},
+ memory_type="test",
+ uris=["viking://test/test.md"],
+ )
+ await updater._apply_upsert(op, mock_ctx)
# Verify
assert written_content is not None
- result = deserialize_full(written_content)
- assert "Hello world" in result.plain_content
- assert "This has been modified" in result.plain_content
- assert "Goodbye" in result.plain_content
+ result = MemoryFileUtils.read(written_content)
+ assert "Hello world" in result.content
+ assert "This has been modified" in result.content
+ assert "Goodbye" in result.content
@pytest.mark.asyncio
- async def test_apply_edit_with_simple_string_replacement(self):
- """Test _apply_edit with simple string full replacement."""
- updater = MemoryUpdater()
-
- # Original content
- original_content = "Old content"
- original_metadata = {"name": "test"}
- original_metadata_with_content = {**original_metadata, "content": original_content}
- original_full_content = serialize_with_metadata(original_metadata_with_content)
+ async def test_apply_edit_with_stripped_search_content_against_linked_storage(self):
+ """Patch content should match the stripped read-tool view, not raw markdown links."""
+ updater = self._make_updater_with_registry()
+
+ uri = "viking://test/test.md"
+ original_full_content = (
+ "# [John](entities/fitness/beginner-yoga.md)\n"
+ "- [爱好](entities/hobbies/reading.md):游戏开发、音乐演奏、公益活动\n\n"
+ "<!-- MEMORY_FIELDS\n"
+ '{"memory_type": "test", "name": "test", "links": ['
+ '{"from_uri": "viking://test/test.md", "to_uri": "viking://test/entities/fitness/beginner-yoga.md", "match_text": "John"}, '
+ '{"from_uri": "viking://test/test.md", "to_uri": "viking://test/entities/hobbies/reading.md", "match_text": "爱好"}'
+ "]}\n"
+ "-->"
+ )
- # Mock VikingFS
mock_viking_fs = MagicMock()
mock_viking_fs.read_file = AsyncMock(return_value=original_full_content)
written_content = None
@@ -320,19 +567,27 @@ Goodbye"""
mock_viking_fs.write_file = mock_write_file
updater._get_viking_fs = MagicMock(return_value=mock_viking_fs)
- # Simple string replacement
- new_content = "Completely new content"
+ patch = StrPatch(
+ blocks=[
+ SearchReplaceBlock(
+ search="# John\n- 爱好:游戏开发、音乐演奏、公益活动",
+ replace="# John\n- 爱好:游戏开发、音乐演奏、公益活动\n- 近期动态:加入志愿者队伍",
+ )
+ ]
+ )
- # Mock request context
mock_ctx = MagicMock()
+ op = ResolvedOperation(
+ memory_fields={"content": patch},
+ memory_type="test",
+ uris=[uri],
+ )
- # Apply edit
- await updater._apply_upsert({"content": new_content}, "viking://test/test.md", mock_ctx)
+ await updater._apply_upsert(op, mock_ctx)
- # Verify
assert written_content is not None
- result = deserialize_full(written_content)
- assert result.plain_content == new_content
+ result = MemoryFileUtils.read(written_content)
+ assert "近期动态:加入志愿者队伍" in result.plain_content()
class TestConsecutivePatchesSameURI:
@@ -405,6 +660,141 @@ class TestConsecutivePatchesSameURI:
parsed = parse_memory_file_with_fields(final_content)
assert parsed["content"] == "Step B"
+ @pytest.mark.asyncio
+ async def test_apply_upsert_skips_failed_field_and_keeps_other_fields(self, monkeypatch):
+ memory_type = "notes"
+ uri = "viking://user/test/memories/notes/demo.md"
+
+ schema = MemoryTypeSchema(
+ memory_type=memory_type,
+ description="notes",
+ fields=[
+ MemoryField(name="title", field_type=FieldType.STRING, merge_op=MergeOp.REPLACE),
+ MemoryField(name="content", field_type=FieldType.STRING, merge_op=MergeOp.PATCH),
+ ],
+ )
+ registry = MemoryTypeRegistry()
+ registry.register(schema)
+
+ store: dict[str, str] = {}
+ mock_viking_fs = MagicMock()
+
+ async def mock_read_file(uri, **kwargs):
+ return store.get(uri)
+
+ async def mock_write_file(uri, content, **kwargs):
+ store[uri] = content
+
+ mock_viking_fs.read_file = mock_read_file
+ mock_viking_fs.write_file = mock_write_file
+
+ updater = MemoryUpdater(registry=registry)
+ updater._get_viking_fs = MagicMock(return_value=mock_viking_fs)
+
+ patch_op = MagicMock()
+ patch_op.apply.side_effect = ValueError("patch failed")
+ replace_op = MagicMock()
+ replace_op.apply.return_value = "Updated Title"
+
+ def mock_from_field(field):
+ if field.name == "content":
+ return patch_op
+ if field.name == "title":
+ return replace_op
+ raise AssertionError(f"unexpected field: {field.name}")
+
+ trace_info = MagicMock()
+ monkeypatch.setattr(
+ "openviking.session.memory.memory_updater.MergeOpFactory.from_field",
+ mock_from_field,
+ )
+ monkeypatch.setattr("openviking.session.memory.memory_updater.tracer.info", trace_info)
+
+ op = ResolvedOperation(
+ old_memory_file_content=MemoryFile(
+ uri=uri,
+ content="Original body",
+ extra_fields={"title": "Original Title"},
+ ),
+ memory_fields={
+ "title": "Updated Title",
+ "content": StrPatch(blocks=[SearchReplaceBlock(search="old", replace="new")]),
+ },
+ memory_type=memory_type,
+ uris=[uri],
+ )
+
+ await updater._apply_upsert(op, MagicMock())
+
+ parsed = parse_memory_file_with_fields(store[uri])
+ assert parsed["title"] == "Updated Title"
+ assert parsed["content"] == "Original body"
+ trace_info.assert_any_call(
+ f"[memory_updater] Skipping field update after merge_op failure: uri={uri}, field=content, error=patch failed"
+ )
+
+ @pytest.mark.asyncio
+ async def test_apply_upsert_logs_patch_failure_from_memory_updater_only(self, monkeypatch):
+ memory_type = "notes"
+ uri = "viking://user/test/memories/notes/demo.md"
+
+ schema = MemoryTypeSchema(
+ memory_type=memory_type,
+ description="notes",
+ fields=[
+ MemoryField(name="content", field_type=FieldType.STRING, merge_op=MergeOp.PATCH),
+ ],
+ )
+ registry = MemoryTypeRegistry()
+ registry.register(schema)
+
+ store: dict[str, str] = {}
+ mock_viking_fs = MagicMock()
+
+ async def mock_read_file(uri, **kwargs):
+ return store.get(uri)
+
+ async def mock_write_file(uri, content, **kwargs):
+ store[uri] = content
+
+ mock_viking_fs.read_file = mock_read_file
+ mock_viking_fs.write_file = mock_write_file
+
+ updater = MemoryUpdater(registry=registry)
+ updater._get_viking_fs = MagicMock(return_value=mock_viking_fs)
+
+ existing_content = MemoryFileUtils.write(MemoryFile(content="Original body"))
+ store[uri] = existing_content
+
+ trace_info = MagicMock()
+ patch_warning = MagicMock()
+ monkeypatch.setattr("openviking.session.memory.memory_updater.tracer.info", trace_info)
+ monkeypatch.setattr("openviking.session.memory.merge_op.patch_handler.logger.warning", patch_warning)
+
+ op = ResolvedOperation(
+ old_memory_file_content=MemoryFile(
+ uri=uri,
+ content="Original body",
+ ),
+ memory_fields={
+ "content": StrPatch(blocks=[SearchReplaceBlock(search="missing", replace="new")]),
+ },
+ memory_type=memory_type,
+ uris=[uri],
+ )
+
+ await updater._apply_upsert(op, MagicMock())
+
+ parsed = parse_memory_file_with_fields(store[uri])
+ assert parsed["content"] == "Original body"
+ patch_warning.assert_not_called()
+ assert any(
+ "[memory_updater] Skipping field update after merge_op failure" in call.args[0]
+ and f"uri={uri}" in call.args[0]
+ and "field=content" in call.args[0]
+ for call in trace_info.call_args_list
+ )
+
@pytest.mark.asyncio
async def test_two_patches_same_uri_second_sees_first_patch(self):
"""Two patches to the same URI: second SEARCH/REPLACE must apply
@@ -426,7 +816,7 @@ class TestConsecutivePatchesSameURI:
registry.register(schema)
# In-memory store with initial content
- initial_content = serialize_with_metadata({"content": "alpha beta gamma"})
+ initial_content = MemoryFileUtils.write(MemoryFile(content="alpha beta gamma"))
store: dict[str, str] = {uri: initial_content}
mock_viking_fs = MagicMock()
@@ -447,10 +837,9 @@ class TestConsecutivePatchesSameURI:
# First patch: "alpha" -> "ALPHA"
patch1 = StrPatch(blocks=[SearchReplaceBlock(search="alpha", replace="ALPHA")])
op1 = ResolvedOperation(
- old_memory_file_content=MemoryFileContent(
+ old_memory_file_content=MemoryFile(
uri=uri,
- plain_content="alpha beta gamma",
- memory_fields={"content": "alpha beta gamma"},
+ content="alpha beta gamma",
),
memory_fields={"content": patch1},
memory_type=memory_type,
@@ -463,10 +852,9 @@ class TestConsecutivePatchesSameURI:
# but _apply_upsert reads from disk which now has "ALPHA beta gamma"
patch2 = StrPatch(blocks=[SearchReplaceBlock(search="beta", replace="BETA")])
op2 = ResolvedOperation(
- old_memory_file_content=MemoryFileContent(
+ old_memory_file_content=MemoryFile(
uri=uri,
- plain_content="alpha beta gamma",
- memory_fields={"content": "alpha beta gamma"},
+ content="alpha beta gamma",
),
memory_fields={"content": patch2},
memory_type=memory_type,
diff --git a/tests/session/memory/test_memory_utils.py b/tests/session/memory/test_memory_utils.py
index 081c6f8e5..0ce531d0d 100644
--- a/tests/session/memory/test_memory_utils.py
+++ b/tests/session/memory/test_memory_utils.py
@@ -8,6 +8,7 @@ import pytest
from openviking.session.memory.dataclass import (
MemoryField,
+ MemoryFile,
MemoryOperations,
MemoryTypeSchema,
)
@@ -23,6 +24,7 @@ from openviking.session.memory.utils import (
resolve_all_operations,
validate_uri_template,
)
+from openviking.session.memory.utils.memory_file_utils import MemoryFileUtils
class TestUriGeneration:
@@ -521,3 +523,43 @@ Content"""
assert result["tool_name"] == "test"
assert result["value"] == 42
assert result["content"] == "Content"
+
+ def test_write_preserves_memory_type_in_memory_fields_comment(self):
+ memory_file = MemoryFile(
+ uri="viking://user/default/memories/preferences/code_style.md",
+ memory_type="preferences",
+ content="Prefers concise responses.",
+ extra_fields={"topic": "code_style"},
+ )
+
+ written = MemoryFileUtils.write(memory_file)
+ parsed = parse_memory_file_with_fields(written)
+
+ assert parsed["memory_type"] == "preferences"
+ assert parsed["topic"] == "code_style"
+ assert parsed["content"] == "Prefers concise responses."
+
+ def test_read_preserves_markdown_links_in_content(self):
+ raw_content = """2023-08-22 ChatLog\n\n[Calvin]: Worked with [Frank Ocean](../../../../entities/personal/calvin.md).\n\n<!-- MEMORY_FIELDS\n{\"memory_type\": \"events\", \"links\": [{\"to_uri\": \"viking://user/Calvin/memories/entities/personal/calvin.md\", \"link_type\": \"related_to\", \"match_text\": \"Frank\"}]}\n-->"""
+
+ memory_file = MemoryFileUtils.read(
+ raw_content,
+ uri="viking://user/Calvin/memories/events/2023/08/22/collab_with_frank_ocean.md",
+ )
+
+ assert "[Frank Ocean](../../../../entities/personal/calvin.md)" in memory_file.content
+
+ def test_memory_file_plain_content_strips_markdown_links(self):
+ memory_file = MemoryFile(
+ uri="viking://user/Calvin/memories/events/2023/08/22/collab_with_frank_ocean.md",
+ content="Worked with [Frank Ocean](../../../../entities/personal/calvin.md).",
+ links=[
+ {
+ "to_uri": "viking://user/Calvin/memories/entities/personal/calvin.md",
+ "link_type": "related_to",
+ "match_text": "Frank",
+ }
+ ],
+ )
+
+ assert memory_file.plain_content() == "Worked with Frank Ocean."
diff --git a/tests/session/memory/test_merge_ops.py b/tests/session/memory/test_merge_ops.py
index 5932b4292..a74f9d44c 100644
--- a/tests/session/memory/test_merge_ops.py
+++ b/tests/session/memory/test_merge_ops.py
@@ -54,6 +54,18 @@ class TestPatchOp:
assert "PATCH" in desc
assert "test content" in desc
+ def test_get_output_schema_description_string_mentions_shared_search_replace_rules(self):
+ """String patch description should defer to the shared SEARCH/REPLACE rules."""
+ op = PatchOp(FieldType.STRING)
+ desc = op.get_output_schema_description("test content")
+ assert "Follow the shared SEARCH/REPLACE rules above." in desc
+
+ def test_get_output_schema_description_string_drops_line_number_prefix_reminder(self):
+ """String patch description should rely on the shared line-prefix guidance."""
+ op = PatchOp(FieldType.STRING)
+ desc = op.get_output_schema_description("test content")
+ assert "line_number<TAB>" not in desc
+
def test_get_output_schema_description_other(self):
"""Non-string field description should mention replace."""
op = PatchOp(FieldType.INT64)
@@ -106,9 +118,9 @@ class TestSumOp:
assert op.apply(None, 10) == 10
def test_apply_invalid_values(self):
- """Invalid values should fall back to patch."""
+ """Invalid values should keep current."""
op = SumOp()
- assert op.apply("not a number", 10) == 10
+ assert op.apply("not a number", 10) == "not a number"
class TestImmutableOp:
@@ -185,6 +197,38 @@ class TestSearchReplaceBlock:
assert block.search == "old content"
assert block.replace == "new content"
+ def test_search_description_mentions_page_bound_target_file(self):
+ """SEARCH description should require exact text from the target file."""
+ description = SearchReplaceBlock.model_fields["search"].description
+ assert description is not None
+ assert "page_id" in description
+ assert "read result" in description
+ assert "another memory or page" in description
+ assert "exact" in description
+ assert "Choose page_id first" in description
+ assert "Never use SEARCH text" in description
+
+ def test_search_description_mentions_contiguous_multiline_search(self):
+ """SEARCH description should require contiguous multi-line matches."""
+ description = SearchReplaceBlock.model_fields["search"].description
+ assert description is not None
+ assert "Multi-line SEARCH must be contiguous" in description
+ assert "split non-adjacent edits into separate blocks" in description
+
+ def test_search_description_mentions_line_number_prefix_exclusion(self):
+ """SEARCH description should require stripping Claude Code line prefixes."""
+ description = SearchReplaceBlock.model_fields["search"].description
+ assert description is not None
+ assert "line_number<TAB>" in description
+ assert "exclude those prefixes from SEARCH" in description
+
+ def test_replace_description_mentions_line_number_prefix_exclusion(self):
+ """REPLACE description should forbid tab-prefixed line numbers."""
+ description = SearchReplaceBlock.model_fields["replace"].description
+ assert description is not None
+ assert "line_number<TAB>" in description
+ assert "Never include" in description
+
class TestStrPatch:
"""Tests for StrPatch."""
@@ -225,6 +269,38 @@ class TestApplyStrPatch:
# Directly test apply_str_patch
assert result == "hello there"
+ def test_numbered_multiline_patch_uses_inferred_start_line(self):
+ """Tab-prefixed read output should target the numbered range."""
+ original = "keep\nsame\nkeep\nsame"
+ patch = StrPatch(
+ blocks=[
+ SearchReplaceBlock(
+ search="3\tkeep\n4\tsame",
+ replace="3\tKEEP\n4\tSAME",
+ )
+ ]
+ )
+
+ result = apply_str_patch(original, patch)
+
+ assert result == "keep\nsame\nKEEP\nSAME"
+
+ def test_numbered_patch_uses_aggressive_strip_with_leading_spaces(self):
+ """Aggressive stripping should still handle tab-prefixed line numbers."""
+ original = "alpha\nbeta\ngamma"
+ patch = StrPatch(
+ blocks=[
+ SearchReplaceBlock(
+ search=" 2\tbeta",
+ replace=" 2\tBETA",
+ )
+ ]
+ )
+
+ result = apply_str_patch(original, patch)
+
+ assert result == "alpha\nBETA\ngamma"
+
# ============================================================================
# Test Schema Generation Integration - tested in test_schema_models.py
diff --git a/tests/session/memory/test_schema_models.py b/tests/session/memory/test_schema_models.py
index d11260d3b..2a8be0b63 100644
--- a/tests/session/memory/test_schema_models.py
+++ b/tests/session/memory/test_schema_models.py
@@ -11,6 +11,7 @@ import yaml
from openviking.session.memory.dataclass import (
MemoryField,
MemoryTypeSchema,
+ WikiLink,
)
from openviking.session.memory.memory_type_registry import (
MemoryTypeRegistry,
@@ -90,6 +91,67 @@ class TestSchemaModelGenerator:
)
return create_default_registry(str(schemas_dir))
+ def test_render_description_template_with_language(self):
+ memory_type = MemoryTypeSchema(
+ memory_type="templated",
+ description="Summary must be written in {{ language }}.",
+ fields=[
+ MemoryField(
+ name="content",
+ field_type=FieldType.STRING,
+ description="Write this field in {{ language }}.",
+ merge_op=MergeOp.PATCH,
+ )
+ ],
+ filename_template="templated.md",
+ directory="test://dir",
+ )
+
+ generator = SchemaModelGenerator([memory_type], template_context={"language": "zh-CN"})
+ model = generator.create_flat_data_model(memory_type)
+ ops_model = generator.create_structured_operations_model(role_scope=None)
+
+ content_description = model.model_fields["content"].description
+ memory_description = ops_model.model_fields["templated"].description
+
+ assert "{{ language }}" not in content_description
+ assert "{{ language }}" not in memory_description
+ assert "zh-CN" in content_description
+ assert "zh-CN" in memory_description
+
+ def test_keep_plain_description_unchanged(self, sample_memory_type):
+ generator = SchemaModelGenerator([sample_memory_type], template_context={"language": "ja"})
+ model = generator.create_flat_data_model(sample_memory_type)
+
+ assert "First test field" in model.model_fields["field1"].description
+
+ def test_render_description_template_conditional_branch(self):
+ memory_type = MemoryTypeSchema(
+ memory_type="conditional",
+ description="{% if language == 'en' %}English summary{% else %}{{ language }} summary{% endif %}",
+ fields=[
+ MemoryField(
+ name="topic",
+ field_type=FieldType.STRING,
+ description="{% if language == 'en' %}snake_case only{% else %}natural {{ language }} phrase{% endif %}",
+ merge_op=MergeOp.IMMUTABLE,
+ )
+ ],
+ filename_template="conditional.md",
+ directory="test://dir",
+ )
+
+ en_generator = SchemaModelGenerator([memory_type], template_context={"language": "en"})
+ zh_generator = SchemaModelGenerator([memory_type], template_context={"language": "zh-CN"})
+
+ en_model = en_generator.create_flat_data_model(memory_type)
+ zh_model = zh_generator.create_flat_data_model(memory_type)
+ zh_ops_model = zh_generator.create_structured_operations_model(role_scope=None)
+
+ assert en_model.model_fields["topic"].description == "snake_case only"
+ assert zh_model.model_fields["topic"].description == "natural zh-CN phrase"
+ assert "zh-CN summary" in zh_ops_model.model_fields["conditional"].description
+
def test_create_flat_data_model(self, sample_memory_type, registry_with_sample):
"""Test creating a flat data model for a single memory type."""
generator = SchemaModelGenerator(registry_with_sample)
@@ -116,6 +178,119 @@ class TestSchemaModelGenerator:
assert "created_at" in model.model_fields
assert "updated_at" in model.model_fields
+ def test_page_id_field_is_emitted_before_mutable_content(self, registry_with_sample):
+ """page_id should appear before mutable fields so the model anchors target page first."""
+ from unittest.mock import patch
+
+ generator = SchemaModelGenerator(registry_with_sample)
+ with patch(
+ "openviking_cli.utils.config.get_openviking_config"
+ ) as mock_get_openviking_config:
+ mock_get_openviking_config.return_value = type(
+ "Config",
+ (),
+ {"memory": type("MemoryCfg", (), {"link_enabled": True})()},
+ )()
+ model = generator.create_flat_data_model(registry_with_sample.get("test_type"))
+
+ field_names = list(model.model_fields.keys())
+
+ assert "page_id" in field_names
+ assert "field1" in field_names
+ assert field_names.index("page_id") < field_names.index("field1")
+
+ def test_page_id_field_is_emitted_when_links_disabled(self, registry_with_sample):
+ """page_id anchors edits even when link extraction is disabled."""
+ from unittest.mock import patch
+
+ generator = SchemaModelGenerator(registry_with_sample)
+ with patch(
+ "openviking_cli.utils.config.get_openviking_config"
+ ) as mock_get_openviking_config:
+ mock_get_openviking_config.return_value = type(
+ "Config",
+ (),
+ {"memory": type("MemoryCfg", (), {"link_enabled": False})()},
+ )()
+ model = generator.create_flat_data_model(registry_with_sample.get("test_type"))
+
+ field_names = list(model.model_fields.keys())
+ assert "page_id" in field_names
+ assert field_names.index("page_id") < field_names.index("field1")
+
+ page_id_field = model.model_fields["page_id"]
+ assert page_id_field.is_required()
+ assert (
+ page_id_field.description == "Temporary page_id for identifying the target memory item."
+ )
+ assert model.model_validate({"page_id": 1, "field1": "value"}).page_id == 1
+ with pytest.raises(ValueError):
+ model.model_validate({"field1": "value"})
+
+ def test_page_id_schema_is_required_and_short_when_links_enabled(self, registry_with_sample):
+ from unittest.mock import patch
+
+ generator = SchemaModelGenerator(registry_with_sample)
+ with patch(
+ "openviking_cli.utils.config.get_openviking_config"
+ ) as mock_get_openviking_config:
+ mock_get_openviking_config.return_value = type(
+ "Config",
+ (),
+ {"memory": type("MemoryCfg", (), {"link_enabled": True})()},
+ )()
+ model = generator.create_flat_data_model(registry_with_sample.get("test_type"))
+
+ page_id_field = model.model_fields["page_id"]
+ assert page_id_field.is_required()
+ assert (
+ page_id_field.description == "Temporary page_id for identifying the target memory item."
+ )
+
+ schema = model.model_json_schema()
+ assert "page_id" in schema["required"]
+ assert schema["properties"]["page_id"]["description"] == (
+ "Temporary page_id for identifying the target memory item."
+ )
+
+ def test_links_field_is_not_emitted_when_links_disabled(self, registry_with_sample):
+ from unittest.mock import patch
+
+ generator = SchemaModelGenerator([registry_with_sample.get("test_type")])
+ with patch(
+ "openviking_cli.utils.config.get_openviking_config"
+ ) as mock_get_openviking_config:
+ mock_get_openviking_config.return_value = type(
+ "Config",
+ (),
+ {"memory": type("MemoryCfg", (), {"link_enabled": False})()},
+ )()
+ model = generator.create_structured_operations_model(role_scope=None)
+
+ assert "links" not in model.model_fields
+
+ def test_links_field_description_uses_shared_link_rules_when_links_enabled(
+ self, registry_with_sample
+ ):
+ from unittest.mock import patch
+
+ generator = SchemaModelGenerator([registry_with_sample.get("test_type")])
+ with patch(
+ "openviking_cli.utils.config.get_openviking_config"
+ ) as mock_get_openviking_config:
+ mock_get_openviking_config.return_value = type(
+ "Config",
+ (),
+ {"memory": type("MemoryCfg", (), {"link_enabled": True})()},
+ )()
+ model = generator.create_structured_operations_model(role_scope=None)
+
+ links_field = model.model_fields["links"]
+ assert links_field.description == (
+ "Links between memory pages. Follow the link rules above. "
+ "Use page_ids for `f` and `t`. Use `weight` from 0 to 1 to rank competing links."
+ )
+
def test_generate_all_models(self, real_registry):
"""Test generating models for all real schemas."""
generator = SchemaModelGenerator(real_registry)
@@ -223,6 +398,52 @@ class TestSchemaModelGenerator:
assert "uri" in model.model_fields
+class TestWikiLink:
+ def test_invalid_link_type_keeps_freeform_short_label(self):
+ link = WikiLink.model_validate(
+ {
+ "f": 1,
+ "t": 2,
+ "link_type": "inspired_by",
+ "weight": 0.7,
+ "match_text": "memory",
+ "description": "derived by model",
+ }
+ )
+
+ assert link.link_type == "inspired_by"
+
+ def test_link_type_schema_is_open_string_without_enum(self):
+ schema = WikiLink.model_json_schema()
+ link_type_schema = schema["properties"]["link_type"]
+
+ assert link_type_schema["type"] == "string"
+ assert "enum" not in link_type_schema
+
+ def test_schema_prompt_generator_renders_conditional_descriptions(self):
+ memory_type = MemoryTypeSchema(
+ memory_type="conditional_prompt",
+ description="{% if language == 'en' %}English type{% else %}{{ language }} type{% endif %}",
+ fields=[
+ MemoryField(
+ name="topic",
+ field_type=FieldType.STRING,
+ description="{% if language == 'en' %}english topic{% else %}{{ language }} topic{% endif %}",
+ merge_op=MergeOp.IMMUTABLE,
+ )
+ ],
+ )
+
+ generator = SchemaPromptGenerator([memory_type], template_context={"language": "zh-CN"})
+
+ type_descriptions = generator.generate_type_descriptions()
+ field_descriptions = generator.generate_field_descriptions("conditional_prompt")
+
+ assert "zh-CN type" in type_descriptions
+ assert "zh-CN topic" in type_descriptions
+ assert "zh-CN topic" in field_descriptions
+
+
class TestSchemaPromptGenerator:
"""Tests for SchemaPromptGenerator."""
@@ -314,7 +535,7 @@ class TestIntegration:
generator = SchemaModelGenerator(registry)
# Get the operations model
- operations_model = generator.create_structured_operations_model()
+ generator.create_structured_operations_model()
# Get JSON schema
json_schema = generator.get_llm_json_schema()
diff --git a/tests/test_link_renderer.py b/tests/test_link_renderer.py
new file mode 100644
index 000000000..60874d7b7
--- /dev/null
+++ b/tests/test_link_renderer.py
@@ -0,0 +1,441 @@
+import pytest
+
+from openviking.session.memory.dataclass import MemoryFile
+from openviking.session.memory.utils.link_renderer import LinkRenderer
+from openviking.session.memory.utils.memory_file_utils import MemoryFileUtils
+
+
+class TestRelativePath:
+ def test_same_directory(self):
+ result = LinkRenderer.relative_path(
+ "viking://user/Caroline/memories/profile.md",
+ "viking://user/Caroline/memories/identity.md",
+ )
+ assert result == "identity.md"
+
+ def test_target_in_subdirectory(self):
+ result = LinkRenderer.relative_path(
+ "viking://user/Caroline/memories/profile.md",
+ "viking://user/Caroline/memories/events/2023/08/17/pride.md",
+ )
+ assert result == "events/2023/08/17/pride.md"
+
+ def test_source_in_subdirectory(self):
+ result = LinkRenderer.relative_path(
+ "viking://user/Caroline/memories/events/2023/08/17/pride.md",
+ "viking://user/Caroline/memories/profile.md",
+ )
+ assert result == "../../../../profile.md"
+
+ def test_cross_subdirectory(self):
+ result = LinkRenderer.relative_path(
+ "viking://user/Caroline/memories/events/2023/08/17/pride.md",
+ "viking://user/Caroline/memories/entities/people/alice.md",
+ )
+ assert result == "../../../../entities/people/alice.md"
+
+ def test_cross_scope_returns_none(self):
+ result = LinkRenderer.relative_path(
+ "viking://user/Caroline/memories/profile.md",
+ "viking://agent/Bot/memories/skills/pdf.md",
+ )
+ assert result is None
+
+ def test_different_user_returns_none(self):
+ result = LinkRenderer.relative_path(
+ "viking://user/Caroline/memories/profile.md",
+ "viking://user/Melanie/memories/profile.md",
+ )
+ assert result is None
+
+ def test_different_user_same_scope_prefix(self):
+ # "user" matches, but "Caroline" != "Melanie" so common < 2
+ result = LinkRenderer.relative_path(
+ "viking://user/Caroline/memories/profile.md",
+ "viking://user/Melanie/memories/events/2023/pride.md",
+ )
+ assert result is None
+
+ def test_same_file_returns_empty(self):
+ result = LinkRenderer.relative_path(
+ "viking://user/Caroline/memories/profile.md",
+ "viking://user/Caroline/memories/profile.md",
+ )
+ # Same file: common = all segments, up=0, down=empty -> empty string
+ assert result == ""
+
+
+class TestRenderLinks:
+ def test_single_link(self):
+ content = "Caroline attended a support group meeting."
+ links = [
+ {
+ "from_uri": "viking://user/Caroline/memories/profile.md",
+ "to_uri": "viking://user/Caroline/memories/entities/groups/lgbtq_support_group.md",
+ "weight": 1.0,
+ "match_text": "support",
+ }
+ ]
+ result = LinkRenderer.render_links(
+ content,
+ "viking://user/Caroline/memories/profile.md",
+ links,
+ )
+ assert (
+ result
+ == "Caroline attended a [support](entities/groups/lgbtq_support_group.md) group meeting."
+ )
+
+ def test_case_insensitive_match(self):
+ content = "Caroline attended a Support group meeting."
+ links = [
+ {
+ "from_uri": "viking://user/Caroline/memories/profile.md",
+ "to_uri": "viking://user/Caroline/memories/entities/groups/lgbtq_support_group.md",
+ "weight": 1.0,
+ "match_text": "support",
+ }
+ ]
+ result = LinkRenderer.render_links(
+ content,
+ "viking://user/Caroline/memories/profile.md",
+ links,
+ )
+ assert (
+ result
+ == "Caroline attended a [Support](entities/groups/lgbtq_support_group.md) group meeting."
+ )
+
+ def test_word_boundary_no_substring_match(self):
+ content = "She is a car enthusiast."
+ links = [
+ {
+ "from_uri": "viking://user/Caroline/memories/profile.md",
+ "to_uri": "viking://user/Caroline/memories/entities/vehicles/car.md",
+ "weight": 1.0,
+ "match_text": "car",
+ }
+ ]
+ result = LinkRenderer.render_links(
+ content,
+ "viking://user/Caroline/memories/profile.md",
+ links,
+ )
+ assert result == "She is a [car](entities/vehicles/car.md) enthusiast."
+
+ def test_word_boundary_no_match_inside_word(self):
+ content = "Caroline went to the store."
+ links = [
+ {
+ "from_uri": "viking://user/Caroline/memories/profile.md",
+ "to_uri": "viking://user/Caroline/memories/entities/vehicles/car.md",
+ "weight": 1.0,
+ "match_text": "car",
+ }
+ ]
+ result = LinkRenderer.render_links(
+ content,
+ "viking://user/Caroline/memories/profile.md",
+ links,
+ )
+ assert result == "Caroline went to the store."
+
+ def test_ascii_boundary_matches_when_surrounded_by_non_ascii_word_chars(self):
+ content = "(car), car."
+ links = [
+ {
+ "from_uri": "viking://user/Caroline/memories/profile.md",
+ "to_uri": "viking://user/Caroline/memories/entities/vehicles/car.md",
+ "weight": 1.0,
+ "match_text": "car",
+ }
+ ]
+ result = LinkRenderer.render_links(
+ content,
+ "viking://user/Caroline/memories/profile.md",
+ links,
+ )
+ assert result == "([car](entities/vehicles/car.md)), car."
+
+ def test_ascii_boundary_matches_next_to_cjk_text(self):
+ content = "她喜欢car,也喜欢旅行。"
+ links = [
+ {
+ "from_uri": "viking://user/Caroline/memories/profile.md",
+ "to_uri": "viking://user/Caroline/memories/entities/vehicles/car.md",
+ "weight": 1.0,
+ "match_text": "car",
+ }
+ ]
+ result = LinkRenderer.render_links(
+ content,
+ "viking://user/Caroline/memories/profile.md",
+ links,
+ )
+ assert result == "她喜欢[car](entities/vehicles/car.md),也喜欢旅行。"
+
+ def test_no_match_text_skipped(self):
+ content = "Some content here."
+ links = [
+ {
+ "from_uri": "viking://user/Caroline/memories/profile.md",
+ "to_uri": "viking://user/Caroline/memories/entities/foo.md",
+ "weight": 1.0,
+ "match_text": None,
+ }
+ ]
+ result = LinkRenderer.render_links(
+ content,
+ "viking://user/Caroline/memories/profile.md",
+ links,
+ )
+ assert result == "Some content here."
+
+ def test_self_link_skipped(self):
+ content = "This is my profile."
+ links = [
+ {
+ "from_uri": "viking://user/Caroline/memories/profile.md",
+ "to_uri": "viking://user/Caroline/memories/profile.md",
+ "weight": 1.0,
+ "match_text": "profile",
+ }
+ ]
+ result = LinkRenderer.render_links(
+ content,
+ "viking://user/Caroline/memories/profile.md",
+ links,
+ )
+ assert result == "This is my profile."
+
+ def test_backlink_not_rendered(self):
+ # Backlinks (where to_uri == source_uri) are not rendered
+ content = "The painting features nice colors."
+ links = [
+ {
+ "from_uri": "viking://user/Melanie/memories/entities/art/lake_sunrise.md",
+ "to_uri": "viking://user/Melanie/memories/preferences/creative.md",
+ "weight": 1.0,
+ "match_text": "painting",
+ }
+ ]
+ result = LinkRenderer.render_links(
+ content,
+ "viking://user/Melanie/memories/preferences/creative.md",
+ links,
+ )
+ # to_uri == source_uri, so this is a self-link, skipped
+ assert result == "The painting features nice colors."
+
+ def test_cross_scope_fallback_to_full_uri(self):
+ content = "The agent has a useful skill."
+ links = [
+ {
+ "from_uri": "viking://user/Caroline/memories/profile.md",
+ "to_uri": "viking://agent/Bot/memories/skills/research.md",
+ "weight": 1.0,
+ "match_text": "skill",
+ }
+ ]
+ result = LinkRenderer.render_links(
+ content,
+ "viking://user/Caroline/memories/profile.md",
+ links,
+ )
+ assert "viking://agent/Bot/memories/skills/research.md" in result
+
+ def test_weight_priority(self):
+ content = "She loves painting and painting is fun."
+ links = [
+ {
+ "from_uri": "viking://user/Melanie/memories/profile.md",
+ "to_uri": "viking://user/Melanie/memories/preferences/art.md",
+ "weight": 0.5,
+ "match_text": "painting",
+ },
+ {
+ "from_uri": "viking://user/Melanie/memories/profile.md",
+ "to_uri": "viking://user/Melanie/memories/entities/art/lake_sunrise.md",
+ "weight": 1.0,
+ "match_text": "painting",
+ },
+ ]
+ result = LinkRenderer.render_links(
+ content,
+ "viking://user/Melanie/memories/profile.md",
+ links,
+ )
+ # Higher weight wins, only first occurrence replaced
+ assert result == "She loves [painting](entities/art/lake_sunrise.md) and painting is fun."
+
+ def test_no_links_returns_unchanged(self):
+ content = "Plain text without links."
+ result = LinkRenderer.render_links(
+ content,
+ "viking://user/Caroline/memories/profile.md",
+ [],
+ )
+ assert result == content
+
+ def test_chinese_match_without_word_boundaries(self):
+ content = "她喜欢角色扮演游戏,也喜欢开放世界游戏。"
+ links = [
+ {
+ "from_uri": "viking://user/Caroline/memories/profile.md",
+ "to_uri": "viking://user/Caroline/memories/entities/games/rpg.md",
+ "weight": 1.0,
+ "match_text": "角色扮演游戏",
+ }
+ ]
+ result = LinkRenderer.render_links(
+ content,
+ "viking://user/Caroline/memories/profile.md",
+ links,
+ )
+ assert (
+ result
+ == "她喜欢[角色扮演游戏](entities/games/rpg.md),也喜欢开放世界游戏。"
+ )
+
+
+class TestStripLinks:
+ def test_strip_relative_link(self):
+ content = "See [support](../entities/groups/lgbtq_support_group.md) for details."
+ result = LinkRenderer.strip_links(content)
+ assert result == "See support for details."
+
+ def test_keep_absolute_link(self):
+ content = "Visit [docs](https://example.com/docs) for more."
+ result = LinkRenderer.strip_links(content)
+ assert result == content
+
+ def test_keep_viking_uri_link(self):
+ content = "Check [skill](viking://agent/Bot/memories/skills/research.md)."
+ result = LinkRenderer.strip_links(content)
+ assert result == content
+
+ def test_keep_viking_uri_link_when_target_uses_supported_scheme(self):
+ content = "Check [skill](viking://agent/Bot/memories/skills/research.md)."
+ result = LinkRenderer.strip_links(content)
+ assert result == content
+
+ def test_keep_anchor_link(self):
+ content = "Jump to [section](#intro)."
+ result = LinkRenderer.strip_links(content)
+ assert result == content
+
+ def test_keep_absolute_path_link(self):
+ content = "See [file](/absolute/path.md)."
+ result = LinkRenderer.strip_links(content)
+ assert result == content
+
+ def test_multiple_links(self):
+ content = "[support](../groups/support.md) and [art](../entities/art.md)"
+ result = LinkRenderer.strip_links(content)
+ assert result == "support and art"
+
+ def test_mixed_links(self):
+ content = "[local](../foo.md) and [web](https://example.com)"
+ result = LinkRenderer.strip_links(content)
+ assert result == "local and [web](https://example.com)"
+
+ def test_no_links(self):
+ content = "Just plain text."
+ result = LinkRenderer.strip_links(content)
+ assert result == content
+
+
+class TestRoundTrip:
+ def test_render_then_strip(self):
+ original = "Caroline attended a support group meeting."
+ links = [
+ {
+ "from_uri": "viking://user/Caroline/memories/profile.md",
+ "to_uri": "viking://user/Caroline/memories/entities/groups/lgbtq_support_group.md",
+ "weight": 1.0,
+ "match_text": "support",
+ }
+ ]
+ rendered = LinkRenderer.render_links(
+ original,
+ "viking://user/Caroline/memories/profile.md",
+ links,
+ )
+ stripped = LinkRenderer.strip_links(rendered)
+ assert stripped == original
+
+ def test_render_then_strip_multiple(self):
+ original = "She enjoys painting and swimming."
+ links = [
+ {
+ "from_uri": "viking://user/Melanie/memories/profile.md",
+ "to_uri": "viking://user/Melanie/memories/entities/art/lake_sunrise.md",
+ "weight": 1.0,
+ "match_text": "painting",
+ },
+ {
+ "from_uri": "viking://user/Melanie/memories/profile.md",
+ "to_uri": "viking://user/Melanie/memories/events/2023/08/swimming.md",
+ "weight": 0.8,
+ "match_text": "swimming",
+ },
+ ]
+ rendered = LinkRenderer.render_links(
+ original,
+ "viking://user/Melanie/memories/profile.md",
+ links,
+ )
+ stripped = LinkRenderer.strip_links(rendered)
+ assert stripped == original
+
+ def test_memory_file_plain_content_strips_markdown_links(self):
+ memory_file = MemoryFile(
+ uri="viking://user/Calvin/memories/events/2023/08/22/collab_with_frank_ocean.md",
+ content="Worked with [Frank Ocean](../../../../entities/personal/calvin.md).",
+ )
+
+ assert memory_file.plain_content() == "Worked with Frank Ocean."
+
+ def test_memory_file_utils_write_keeps_plain_text_body_and_preserves_links_metadata(self):
+ memory_file = MemoryFile(
+ uri="viking://user/Caroline/memories/profile.md",
+ content="她喜欢角色扮演游戏,也喜欢开放世界游戏。",
+ links=[
+ {
+ "from_uri": "viking://user/Caroline/memories/profile.md",
+ "to_uri": "viking://user/Caroline/memories/entities/games/rpg.md",
+ "weight": 1.0,
+ "match_text": "角色扮演游戏",
+ }
+ ],
+ extra_fields={"memory_type": "profile"},
+ )
+
+ written = MemoryFileUtils.write(memory_file)
+
+ assert "她喜欢角色扮演游戏,也喜欢开放世界游戏。" in written
+ assert "她喜欢[角色扮演游戏](entities/games/rpg.md),也喜欢开放世界游戏。" not in written
+ assert '"match_text": "角色扮演游戏"' in written
+
+ def test_repeated_memory_file_utils_write_does_not_persist_nested_links(self):
+ memory_file = MemoryFile(
+ uri="viking://user/Gina/memories/profile.md",
+ content="Gina",
+ links=[
+ {
+ "from_uri": "viking://user/Gina/memories/profile.md",
+ "to_uri": "viking://user/Gina/memories/events/2023/02/08/Gina与Jon的日常交流.md",
+ "weight": 1.0,
+ "match_text": "Gina",
+ }
+ ],
+ extra_fields={"memory_type": "profile"},
+ )
+
+ first_write = MemoryFileUtils.write(memory_file)
+ reparsed = MemoryFileUtils.read(first_write, uri=memory_file.uri)
+ second_write = MemoryFileUtils.write(reparsed)
+
+ assert "[Gina](events/2023/02/08/Gina与Jon的日常交流.md)" not in first_write
+ assert "[[Gina](events/2023/02/08/Gina与Jon的日常交流.md)](events/2023/02/08/Gina与Jon的日常交流.md)" not in second_write
+ assert "Gina" in second_write
diff --git a/tests/test_prompt_manager.py b/tests/test_prompt_manager.py
index 5b7bf456a..519491c79 100644
--- a/tests/test_prompt_manager.py
+++ b/tests/test_prompt_manager.py
@@ -5,6 +5,8 @@ import json
from pathlib import Path
from types import SimpleNamespace
+import yaml
+
from openviking.prompts.manager import PromptManager
from openviking.session.memory.memory_type_registry import MemoryTypeRegistry
from openviking.session.memory.session_extract_context_provider import (
@@ -67,7 +69,50 @@ def teardown_function() -> None:
OpenVikingConfigSingleton.reset_instance()
-def test_prompt_manager_prefers_environment_templates_dir(tmp_path, monkeypatch):
+def test_profile_memory_template_keeps_profile_minimal_and_migrates_preferences():
+ template_path = PromptManager._get_bundled_templates_dir() / "memory" / "profile.yaml"
+ schema = yaml.safe_load(template_path.read_text(encoding="utf-8"))
+ text = "\n".join(
+ [
+ schema["description"],
+ schema["fields"][0]["description"],
+ ]
+ )
+
+ assert "identity summary" in text
+ assert "5-8" in text
+ assert "Complete but minimal" in text
+ assert "Rewrite the full profile" in text
+ assert "Do not append" in text
+ assert "migrate" in text
+ assert "preferences" in text
+ assert "Do not keep concrete preference examples" in text
+ assert "patch" in text
+ assert "rewrite the whole profile" in text
+
+
+def test_preferences_memory_template_limits_topics_and_splits_when_too_large():
+ template_path = PromptManager._get_bundled_templates_dir() / "memory" / "preferences.yaml"
+ schema = yaml.safe_load(template_path.read_text(encoding="utf-8"))
+ text = "\n".join(
+ [
+ schema["description"],
+ schema["fields"][1]["description"],
+ schema["fields"][2]["description"],
+ ]
+ )
+
+ assert "Complete but minimal" in text
+ assert "3-8" in text
+ assert "800" in text
+ assert "split" in text
+ assert "semantic subtopics" in text
+ assert "evidenced by" in text
+ assert "as of" in text
+ assert "not become a second profile" in text
+
+
+def test_prompt_manager_prefers_env_templates_dir_over_config(tmp_path, monkeypatch):
env_dir = tmp_path / "env-prompts"
config_dir = tmp_path / "config-prompts"
config_path = tmp_path / "ov.conf"
@@ -242,6 +287,7 @@ def test_context_provider_schema_directories_use_prompt_manager_resolved_templat
eager_prefetch=False,
prefetch_search_topn=5,
enable_vaka_template=False,
+ link_enabled=True,
)
),
)
@@ -274,6 +320,7 @@ def test_context_provider_schema_directories_prefer_custom_memory_dir_over_promp
eager_prefetch=False,
prefetch_search_topn=5,
enable_vaka_template=False,
+ link_enabled=False,
)
),
)
@@ -336,6 +383,7 @@ def test_context_provider_includes_vaka_dir_when_enabled(monkeypatch):
eager_prefetch=False,
prefetch_search_topn=5,
enable_vaka_template=True,
+ link_enabled=False,
)
),
)
diff --git a/tests/transaction/test_lock_manager.py b/tests/transaction/test_lock_manager.py
index 06e38fcda..36285b2bf 100644
--- a/tests/transaction/test_lock_manager.py
+++ b/tests/transaction/test_lock_manager.py
@@ -92,6 +92,16 @@ class TestLockManagerBasic:
await lm.release(handle)
+ async def test_explicit_none_timeout_passes_through_as_infinite_wait(self, lm):
+ handle = lm.create_handle()
+ lm._path_lock = MagicMock()
+ lm._path_lock.acquire_tree = AsyncMock(return_value=True)
+
+ ok = await lm.acquire_tree(handle, "/local/test", timeout=None)
+
+ assert ok is True
+ lm._path_lock.acquire_tree.assert_awaited_once_with("/local/test", handle, timeout=None)
+
async def test_recover_pending_redo_preserves_cancelled_error(self, lm):
lm._redo_log = MagicMock()
lm._redo_log.list_pending.return_value = ["redo-task"]
diff --git a/tests/unit/session/memory/test_extract_loop_match_text.py b/tests/unit/session/memory/test_extract_loop_match_text.py
new file mode 100644
index 000000000..771d878fb
--- /dev/null
+++ b/tests/unit/session/memory/test_extract_loop_match_text.py
@@ -0,0 +1,353 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: AGPL-3.0
+
+from types import SimpleNamespace
+from unittest.mock import AsyncMock, Mock, patch
+
+import pytest
+
+from openviking.session.memory.dataclass import MemoryField, MemoryFile, MemoryTypeSchema, ResolvedOperation, WikiLink
+from openviking.session.memory.merge_op import FieldType, MergeOp
+from openviking.session.memory.page_id_map import PageIdMap
+from openviking.session.memory.extract_loop import ExtractLoop
+
+
+class AttrDict(dict):
+ __getattr__ = dict.get
+
+
+
+
+class TestResolveOperations:
+ @pytest.mark.asyncio
+ async def test_existing_page_id_keeps_existing_uri_and_identity_fields(self):
+ schema = MemoryTypeSchema(
+ memory_type="entities",
+ description="entity memory",
+ directory="viking://user/{{ user_space }}/memories/entities",
+ filename_template="{{ name }}.md",
+ fields=[
+ MemoryField(name="name", field_type=FieldType.STRING, merge_op=MergeOp.REPLACE),
+ MemoryField(name="content", field_type=FieldType.STRING, merge_op=MergeOp.PATCH),
+ ],
+ )
+ existing_uri = "viking://user/alice/memories/entities/Melanie.md"
+ old_file = MemoryFile(
+ uri=existing_uri,
+ content="old content",
+ memory_type="entities",
+ extra_fields={"name": "Melanie"},
+ )
+
+ context_provider = Mock()
+ context_provider.get_memory_schemas.return_value = [schema]
+ context_provider._get_registry.return_value = Mock(get=Mock(return_value=schema))
+ context_provider.read_file_contents = {existing_uri: old_file}
+
+ isolation_handler = Mock()
+ isolation_handler.get_read_scope.return_value = None
+ isolation_handler.fill_role_ids.side_effect = lambda item, role_scope=None: item
+
+ loop = ExtractLoop(
+ vlm=Mock(model="test-model"),
+ viking_fs=Mock(),
+ context_provider=context_provider,
+ isolation_handler=isolation_handler,
+ )
+ loop._extract_context = SimpleNamespace(
+ page_id_map=SimpleNamespace(resolve=lambda page_id: existing_uri)
+ )
+
+ operations, _ = await loop.resolve_operations(
+ AttrDict(
+ entities=[{"name": "WrongName", "content": "new content", "page_id": 7}],
+ delete_uris=[],
+ )
+ )
+
+ operation = operations.upsert_operations[0]
+ assert operation.uris == [existing_uri]
+ assert operation.old_memory_file_content is old_file
+ assert operation.memory_fields["name"] == "Melanie"
+ assert operation.memory_fields["content"] == "new content"
+ isolation_handler.calculate_memory_uris.assert_not_called()
+
+ def test_unresolved_page_ids_logs_at_info(self):
+ loop = ExtractLoop(vlm=Mock(model="test-model"), viking_fs=Mock(), context_provider=Mock())
+ loop._extract_context = Mock()
+ loop._extract_context.page_id_map = Mock()
+ loop._extract_context.page_id_map._id_to_uri = {
+ 100: "viking://agent/agent_sample_0/memories/trajectories/a.md"
+ }
+ loop._extract_context.page_id_map.resolve.side_effect = lambda page_id: {
+ 100: "viking://agent/agent_sample_0/memories/trajectories/a.md"
+ }.get(page_id)
+ loop._extract_context.page_id_map.register_new_page_id = Mock()
+
+ raw_links = [WikiLink(f=100, t=102, match_text="trip")]
+
+ with patch("openviking.session.memory.extract_loop.tracer.info") as mock_info, patch(
+ "openviking.session.memory.extract_loop.tracer.error"
+ ) as mock_error:
+ resolved = loop._resolve_links(raw_links, upsert_operations=[])
+
+ assert resolved == []
+ mock_error.assert_not_called()
+ mock_info.assert_any_call(
+ "Skipping link with unresolved page_ids: f=100, t=102, "
+ "from_uri=viking://agent/agent_sample_0/memories/trajectories/a.md, to_uri=None, "
+ "op_page_map_keys=[]"
+ )
+
+
+class TestResolveLinksMultiUri:
+ def test_shared_page_id_pairs_matching_user_uris_only(self):
+ loop = ExtractLoop(vlm=Mock(model="test-model"), viking_fs=Mock(), context_provider=Mock())
+ loop._extract_context = Mock()
+ loop._extract_context.page_id_map = Mock()
+ loop._extract_context.page_id_map._id_to_uri = {}
+ loop._extract_context.page_id_map.resolve.return_value = None
+ loop._extract_context.page_id_map.register_new_page_id = Mock()
+
+ raw_links = [WikiLink(f=100, t=101, match_text="trip")]
+ upsert_operations = [
+ ResolvedOperation(
+ memory_fields={},
+ memory_type="experiences",
+ uris=[
+ "viking://user/a/memories/experiences/source.md",
+ "viking://user/b/memories/experiences/source.md",
+ ],
+ page_id=100,
+ ),
+ ResolvedOperation(
+ memory_fields={},
+ memory_type="experiences",
+ uris=[
+ "viking://user/a/memories/experiences/target.md",
+ "viking://user/b/memories/experiences/target.md",
+ ],
+ page_id=101,
+ ),
+ ]
+
+ resolved = loop._resolve_links(raw_links, upsert_operations=upsert_operations)
+
+ assert {(link.from_uri, link.to_uri) for link in resolved} == {
+ (
+ "viking://user/a/memories/experiences/source.md",
+ "viking://user/a/memories/experiences/target.md",
+ ),
+ (
+ "viking://user/b/memories/experiences/source.md",
+ "viking://user/b/memories/experiences/target.md",
+ ),
+ }
+
+
+class TestPageIdInstruction:
+ @pytest.mark.asyncio
+ async def test_run_always_includes_page_id_rules_when_links_disabled(self):
+ context_provider = Mock()
+ context_provider.get_memory_schemas.return_value = [SimpleNamespace(memory_type="experiences")]
+ context_provider.get_output_language.return_value = "zh-CN"
+ context_provider.get_tools.return_value = []
+ extract_context = Mock()
+ extract_context.page_id_map = PageIdMap()
+ context_provider.get_extract_context.return_value = extract_context
+ context_provider.prefetch = AsyncMock(return_value=[])
+ context_provider.read_file_contents = {}
+ context_provider.instruction.return_value = "base instruction"
+ context_provider._get_registry.return_value = Mock()
+
+ isolation_handler = Mock()
+ isolation_handler.get_read_scope.return_value = None
+ isolation_handler.fill_role_ids.side_effect = lambda item, role_scope=None: item
+ isolation_handler.calculate_memory_uris.return_value = [
+ "viking://user/alice/memories/experiences/chat.md"
+ ]
+
+ loop = ExtractLoop(
+ vlm=Mock(model="test-model"),
+ viking_fs=Mock(),
+ context_provider=context_provider,
+ isolation_handler=isolation_handler,
+ )
+ loop._mark_cache_breakpoint = AsyncMock()
+ loop._call_llm = AsyncMock(
+ return_value=(
+ [],
+ AttrDict(
+ experiences=[{"experience_name": "chat", "content": "updated", "page_id": 100}]
+ ),
+ )
+ )
+ loop._check_unread_existing_files = AsyncMock(return_value=[])
+ loop.finalize_operations = AsyncMock()
+
+ captured_messages = []
+
+ def capture_messages(messages):
+ captured_messages.extend(messages)
+
+ with (
+ patch("openviking.session.memory.extract_loop.get_openviking_config") as mock_config,
+ patch("openviking.session.memory.extract_loop.pretty_print_messages", capture_messages),
+ patch(
+ "openviking.session.memory.extract_loop.SchemaModelGenerator.generate_all_models"
+ ),
+ patch(
+ "openviking.session.memory.extract_loop.SchemaModelGenerator.create_structured_operations_model"
+ ) as mock_create_model,
+ ):
+ mock_config.return_value = SimpleNamespace(memory=SimpleNamespace(link_enabled=False))
+ mock_create_model.return_value = SimpleNamespace(model_json_schema=lambda: {})
+
+ await loop.run()
+
+ system_content = captured_messages[0]["content"]
+ assert "## Page ID Rules" in system_content
+ assert "## Read Format Rules" in system_content
+ assert 'Every memory item you create or edit MUST include "page_id".' in system_content
+ assert "The read tool accepts `uri`, optional `offset` (0-indexed), and optional `limit`." in system_content
+ assert "each visible line is prefixed with `line_number<TAB>`" in system_content
+ assert "Never include the line-number prefix itself in `search` or `replace`." in system_content
+ assert "For existing items, use the page_id shown in read/search results." in system_content
+ assert "For new items, assign a unique page_id >= 100." in system_content
+ assert "When editing an existing item, reuse its existing page_id." in system_content
+ assert "Link fields" not in system_content
+
+ @pytest.mark.asyncio
+ async def test_run_includes_link_page_id_rule_when_links_enabled(self):
+ context_provider = Mock()
+ context_provider.get_memory_schemas.return_value = [SimpleNamespace(memory_type="experiences")]
+ context_provider.get_output_language.return_value = "zh-CN"
+ context_provider.get_tools.return_value = []
+ extract_context = Mock()
+ extract_context.page_id_map = PageIdMap()
+ context_provider.get_extract_context.return_value = extract_context
+ context_provider.prefetch = AsyncMock(return_value=[])
+ context_provider.read_file_contents = {}
+ context_provider.instruction.return_value = "base instruction"
+ context_provider._get_registry.return_value = Mock()
+
+ isolation_handler = Mock()
+ isolation_handler.get_read_scope.return_value = None
+ isolation_handler.fill_role_ids.side_effect = lambda item, role_scope=None: item
+ isolation_handler.calculate_memory_uris.return_value = [
+ "viking://user/alice/memories/experiences/chat.md"
+ ]
+
+ loop = ExtractLoop(
+ vlm=Mock(model="test-model"),
+ viking_fs=Mock(),
+ context_provider=context_provider,
+ isolation_handler=isolation_handler,
+ )
+ loop._mark_cache_breakpoint = AsyncMock()
+ loop._call_llm = AsyncMock(
+ return_value=(
+ [],
+ AttrDict(
+ experiences=[{"experience_name": "chat", "content": "updated", "page_id": 100}],
+ links=[],
+ ),
+ )
+ )
+ loop._check_unread_existing_files = AsyncMock(return_value=[])
+ loop.finalize_operations = AsyncMock()
+
+ captured_messages = []
+
+ def capture_messages(messages):
+ captured_messages.extend(messages)
+
+ with (
+ patch("openviking.session.memory.extract_loop.get_openviking_config") as mock_config,
+ patch("openviking.session.memory.extract_loop.pretty_print_messages", capture_messages),
+ patch(
+ "openviking.session.memory.extract_loop.SchemaModelGenerator.generate_all_models"
+ ),
+ patch(
+ "openviking.session.memory.extract_loop.SchemaModelGenerator.create_structured_operations_model"
+ ) as mock_create_model,
+ ):
+ mock_config.return_value = SimpleNamespace(memory=SimpleNamespace(link_enabled=True))
+ mock_create_model.return_value = SimpleNamespace(model_json_schema=lambda: {})
+
+ await loop.run()
+
+ system_content = captured_messages[0]["content"]
+ assert "## Page ID Rules" in system_content
+ assert "## Read Format Rules" in system_content
+ assert "## Link Rules" in system_content
+ assert "Link fields `f` and `t` must reference these page_id values." in system_content
+ assert "each visible line is prefixed with `line_number<TAB>`" in system_content
+ assert "Only create links when the relationship is meaningful" in system_content
+
+
+class TestFinalOperationsHydration:
+ @pytest.mark.asyncio
+ async def test_run_logs_final_operations_after_old_memory_file_is_hydrated(self):
+ old_file = MemoryFile(uri="viking://user/Caroline/memories/experiences/chat.md", content="old")
+
+ context_provider = Mock()
+ schema = SimpleNamespace(memory_type="experiences", fields=[])
+ context_provider.get_memory_schemas.return_value = [schema]
+ context_provider.get_output_language.return_value = "zh-CN"
+ context_provider.get_tools.return_value = []
+ extract_context = Mock()
+ extract_context.page_id_map = PageIdMap()
+ extract_context.page_id_map.get_page_id(old_file.uri)
+ context_provider.get_extract_context.return_value = extract_context
+ context_provider.prefetch = AsyncMock(return_value=[])
+ context_provider.read_file_contents = {old_file.uri: old_file}
+ context_provider.instruction.return_value = "test instruction"
+ context_provider._get_registry.return_value = Mock()
+
+ isolation_handler = Mock()
+ isolation_handler.get_read_scope.return_value = "user://Caroline"
+ isolation_handler.fill_role_ids.side_effect = lambda item, role_scope=None: item
+
+ loop = ExtractLoop(
+ vlm=Mock(model="test-model"),
+ viking_fs=Mock(),
+ context_provider=context_provider,
+ isolation_handler=isolation_handler,
+ )
+ loop._mark_cache_breakpoint = AsyncMock()
+ loop._call_llm = AsyncMock(
+ return_value=(
+ [],
+ AttrDict(
+ experiences=[{"experience_name": "chat", "content": "updated", "page_id": 1}]
+ ),
+ )
+ )
+ loop._check_unread_existing_files = AsyncMock(return_value=[])
+ loop.finalize_operations = AsyncMock()
+
+ with (
+ patch("openviking.session.memory.extract_loop.get_openviking_config") as mock_config,
+ patch(
+ "openviking.session.memory.extract_loop.SchemaModelGenerator.generate_all_models"
+ ),
+ patch(
+ "openviking.session.memory.extract_loop.SchemaModelGenerator.create_structured_operations_model"
+ ) as mock_create_model,
+ patch("openviking.session.memory.extract_loop.tracer.info") as mock_tracer_info,
+ ):
+ mock_config.return_value = SimpleNamespace(memory=SimpleNamespace(link_enabled=False))
+ mock_create_model.return_value = SimpleNamespace(model_json_schema=lambda: {})
+
+ final_operations, _ = await loop.run()
+
+ assert extract_context.page_id_map.resolve(1) == old_file.uri
+
+ op = final_operations.upsert_operations[0]
+ assert op.page_id == 1
+ assert op.old_memory_file_content is old_file
+ assert final_operations.resolved_links == []
+ logged_messages = [call.args[0] for call in mock_tracer_info.call_args_list]
+ final_log = next(message for message in logged_messages if message.startswith("final_operations="))
+ assert '"old_memory_file_content":null' not in final_log
diff --git a/tests/unit/session/memory/test_link_merge.py b/tests/unit/session/memory/test_link_merge.py
new file mode 100644
index 000000000..4a39af81f
--- /dev/null
+++ b/tests/unit/session/memory/test_link_merge.py
@@ -0,0 +1,84 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: AGPL-3.0
+
+import pytest
+
+from openviking.session.memory.merge_op.link_merge import (
+ _dedup_key,
+ merge_links,
+)
+
+
+class TestDedupKey:
+ def test_same_links_same_key(self):
+ link1 = {"from_uri": "a", "to_uri": "b", "match_text": "foo"}
+ link2 = {"from_uri": "a", "to_uri": "b", "match_text": "foo"}
+ assert _dedup_key(link1) == _dedup_key(link2)
+
+ def test_different_match_text_different_key(self):
+ link1 = {"from_uri": "a", "to_uri": "b", "match_text": "foo"}
+ link2 = {"from_uri": "a", "to_uri": "b", "match_text": "bar"}
+ assert _dedup_key(link1) != _dedup_key(link2)
+
+
+class TestMergeLinks:
+ def test_empty_inputs(self):
+ assert merge_links([], []) == []
+
+ def test_new_links_added(self):
+ existing = []
+ new = [{"from_uri": "a", "to_uri": "b", "link_type": "related_to", "weight": 0.8}]
+ result = merge_links(existing, new)
+ assert len(result) == 1
+ assert result[0]["weight"] == 0.8
+
+ def test_weight_conflict_takes_max(self):
+ existing = [
+ {
+ "from_uri": "a",
+ "to_uri": "b",
+ "match_text": "x",
+ "weight": 0.5,
+ "link_type": "related_to",
+ }
+ ]
+ new = [
+ {
+ "from_uri": "a",
+ "to_uri": "b",
+ "match_text": "x",
+ "weight": 0.9,
+ "link_type": "belongs_to",
+ }
+ ]
+ result = merge_links(existing, new)
+ assert len(result) == 1
+ assert result[0]["weight"] == 0.9
+ # link_type: latest wins
+ assert result[0]["link_type"] == "belongs_to"
+
+ def test_description_latest_wins(self):
+ existing = [
+ {
+ "from_uri": "a",
+ "to_uri": "b",
+ "match_text": "x",
+ "description": "old",
+ }
+ ]
+ new = [
+ {
+ "from_uri": "a",
+ "to_uri": "b",
+ "match_text": "x",
+ "description": "new",
+ }
+ ]
+ result = merge_links(existing, new)
+ assert result[0]["description"] == "new"
+
+ def test_different_match_text_not_deduped(self):
+ existing = [{"from_uri": "a", "to_uri": "b", "match_text": "foo"}]
+ new = [{"from_uri": "a", "to_uri": "b", "match_text": "bar"}]
+ result = merge_links(existing, new)
+ assert len(result) == 2
diff --git a/tests/unit/session/memory/test_link_models.py b/tests/unit/session/memory/test_link_models.py
new file mode 100644
index 000000000..382b4d1aa
--- /dev/null
+++ b/tests/unit/session/memory/test_link_models.py
@@ -0,0 +1,143 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: AGPL-3.0
+
+import pytest
+
+from openviking.session.memory.dataclass import (
+ LinkType,
+ MemoryTypeSchema,
+ ResolvedOperation,
+ ResolvedOperations,
+ StoredLink,
+ WikiLink,
+)
+
+
+class TestLinkType:
+ def test_default_value_defined(self):
+ assert LinkType.RELATED_TO == "related_to"
+
+
+class TestWikiLink:
+ def test_minimal_fields(self):
+ link = WikiLink(f=1, t=2, match_text=None)
+ assert link.f == 1
+ assert link.t == 2
+ assert link.link_type == "related_to"
+ assert link.weight == 0.5
+ assert link.match_text is None
+
+ def test_full_fields(self):
+ link = WikiLink(
+ f=1,
+ t=3,
+ link_type="belongs_to",
+ weight=0.9,
+ match_text="Caroline",
+ description="Preference belongs to Caroline",
+ )
+ assert link.link_type == "belongs_to"
+ assert link.match_text == "Caroline"
+ assert link.weight == 0.9
+
+ def test_weight_is_preserved_when_valid(self):
+ link = WikiLink(f=1, t=2, weight=0.8, match_text=None)
+ assert link.weight == 0.8
+
+ def test_weight_is_clamped_to_zero_when_negative(self):
+ link = WikiLink(f=1, t=2, weight=-0.2, match_text=None)
+ assert link.weight == 0.0
+
+ def test_weight_is_clamped_to_one_when_above_range(self):
+ link = WikiLink(f=1, t=2, weight=1.7, match_text=None)
+ assert link.weight == 1.0
+
+ def test_weight_defaults_to_mid_value_when_invalid(self):
+ link = WikiLink.model_validate({"f": 1, "t": 2, "weight": "not-a-number", "match_text": None})
+ assert link.weight == 0.5
+
+ def test_json_schema_requires_match_text_field(self):
+ schema = WikiLink.model_json_schema()
+
+ assert "match_text" in schema["required"]
+ assert any(option.get("type") == "string" for option in schema["properties"]["match_text"]["anyOf"])
+ assert any(option.get("type") == "null" for option in schema["properties"]["match_text"]["anyOf"])
+
+ def test_weight_schema_mentions_ranking_priority(self):
+ schema = WikiLink.model_json_schema()
+ description = schema["properties"]["weight"]["description"]
+ assert "ranking score" in description
+ assert "same anchor or attention" in description
+
+
+class TestStoredLink:
+ def test_link(self):
+ link = StoredLink(
+ from_uri="viking://a",
+ to_uri="viking://b",
+ link_type="belongs_to",
+ weight=0.9,
+ created_at="2026-05-09T10:00:00+00:00",
+ )
+ assert link.from_uri == "viking://a"
+ assert link.to_uri == "viking://b"
+ assert link.link_type == "belongs_to"
+
+ def test_model_dump(self):
+ link = StoredLink(
+ from_uri="viking://a",
+ to_uri="viking://b",
+ link_type="related_to",
+ created_at="2026-05-09T10:00:00+00:00",
+ )
+ d = link.model_dump()
+ assert d["from_uri"] == "viking://a"
+ assert d["to_uri"] == "viking://b"
+ assert d["link_type"] == "related_to"
+ assert "direction" not in d
+
+
+class TestResolvedOperationsLinks:
+ def test_default_empty_links(self):
+ ops = ResolvedOperations(
+ upsert_operations=[],
+ delete_file_contents=[],
+ errors=[],
+ )
+ assert ops.resolved_links == []
+
+ def test_with_resolved_links(self):
+ link = StoredLink(
+ from_uri="viking://a",
+ to_uri="viking://b",
+ link_type="related_to",
+ created_at="2026-05-09T10:00:00+00:00",
+ )
+ ops = ResolvedOperations(
+ upsert_operations=[],
+ delete_file_contents=[],
+ errors=[],
+ resolved_links=[link],
+ )
+ assert len(ops.resolved_links) == 1
+
+
+class TestResolvedOperationPageId:
+ def test_default_none(self):
+ op = ResolvedOperation(
+ old_memory_file_content=None,
+ memory_fields={},
+ memory_type="preferences",
+ uris=[],
+ )
+ assert op.page_id is None
+
+ def test_with_page_id(self):
+ op = ResolvedOperation(
+ old_memory_file_content=None,
+ memory_fields={},
+ memory_type="preferences",
+ uris=[],
+ page_id=100,
+ )
+ assert op.page_id == 100
diff --git a/tests/unit/session/memory/test_page_id_map.py b/tests/unit/session/memory/test_page_id_map.py
new file mode 100644
index 000000000..0f6459cc7
--- /dev/null
+++ b/tests/unit/session/memory/test_page_id_map.py
@@ -0,0 +1,77 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: AGPL-3.0
+
+from openviking.session.memory.page_id_map import PageIdMap
+
+
+class TestPageIdMap:
+ def test_get_page_id_assigns_incremental_ids_for_existing_pages(self):
+ pim = PageIdMap()
+
+ id1 = pim.get_page_id("viking://user/a/memories/profile.md")
+ id2 = pim.get_page_id("viking://user/a/memories/preferences/topic.md")
+
+ assert id1 == 1
+ assert id2 == 2
+
+ def test_get_page_id_returns_same_id_for_duplicate_uri(self):
+ pim = PageIdMap()
+
+ id1 = pim.get_page_id("viking://user/a/memories/profile.md")
+ id2 = pim.get_page_id("viking://user/a/memories/profile.md")
+
+ assert id1 == id2
+
+ def test_resolve_returns_uri_for_registered_existing_page(self):
+ pim = PageIdMap()
+
+ page_id = pim.get_page_id("viking://user/a/memories/profile.md")
+
+ assert pim.resolve(page_id) == "viking://user/a/memories/profile.md"
+
+ def test_resolve_returns_none_for_unknown_page_id(self):
+ pim = PageIdMap()
+
+ assert pim.resolve(999) is None
+
+ def test_register_new_page_id_resolves_uri_for_unseen_uri(self):
+ pim = PageIdMap()
+
+ pim.register_new_page_id("viking://new-item", 105)
+
+ assert pim.resolve(105) == "viking://new-item"
+
+ def test_get_page_id_returns_declared_page_id_for_unseen_registered_uri(self):
+ pim = PageIdMap()
+
+ pim.register_new_page_id("viking://new-item", 105)
+
+ assert pim.get_page_id("viking://new-item") == 105
+
+ def test_register_new_page_id_preserves_existing_primary_id_for_seen_uri(self):
+ pim = PageIdMap()
+
+ existing_id = pim.get_page_id("viking://profile.md")
+ pim.register_new_page_id("viking://profile.md", 100)
+
+ assert pim.get_page_id("viking://profile.md") == existing_id
+ assert pim.resolve(existing_id) == "viking://profile.md"
+ assert pim.resolve(100) == "viking://profile.md"
+
+ def test_has_links_enabled_after_existing_page_registration(self):
+ pim = PageIdMap()
+
+ assert not pim.has_links_enabled
+
+ pim.get_page_id("viking://test")
+
+ assert pim.has_links_enabled
+
+ def test_has_links_enabled_after_new_page_id_registration(self):
+ pim = PageIdMap()
+
+ assert not pim.has_links_enabled
+
+ pim.register_new_page_id("viking://new-item", 100)
+
+ assert pim.has_links_enabled
diff --git a/tests/unit/session/memory/test_searchable.py b/tests/unit/session/memory/test_searchable.py
new file mode 100644
index 000000000..59fd4abfd
--- /dev/null
+++ b/tests/unit/session/memory/test_searchable.py
@@ -0,0 +1,154 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: AGPL-3.0
+
+import pytest
+
+from openviking.session.memory.dataclass import MemoryField
+from openviking.session.memory.merge_op.base import FieldType
+from openviking.session.memory.memory_type_registry import MemoryTypeRegistry
+
+
+class TestMemoryFieldSearchable:
+ def test_default_is_false(self):
+ field = MemoryField(name="test", field_type=FieldType.STRING, description="test")
+ assert field.searchable is False
+
+ def test_explicit_true(self):
+ field = MemoryField(
+ name="content", field_type=FieldType.STRING, description="desc", searchable=True
+ )
+ assert field.searchable is True
+
+ def test_explicit_false(self):
+ field = MemoryField(
+ name="call_count", field_type=FieldType.INT64, description="count", searchable=False
+ )
+ assert field.searchable is False
+
+
+class TestSearchableYamlParsing:
+ @pytest.fixture(autouse=True)
+ def setup(self):
+ self.registry = MemoryTypeRegistry()
+
+ def test_events_searchable_fields(self):
+ schema = self.registry.get("events")
+ searchable = {f.name for f in schema.fields if f.searchable}
+ assert searchable == {"event_name", "goal", "summary"}
+
+ def test_tools_searchable_fields(self):
+ schema = self.registry.get("tools")
+ searchable = {f.name for f in schema.fields if f.searchable}
+ assert searchable == set() # all rendered in content_template
+
+ def test_entities_searchable_fields(self):
+ schema = self.registry.get("entities")
+ searchable = {f.name for f in schema.fields if f.searchable}
+ assert searchable == {"category", "name"}
+
+ def test_preferences_searchable_fields(self):
+ schema = self.registry.get("preferences")
+ searchable = {f.name for f in schema.fields if f.searchable}
+ assert searchable == {"user", "topic"}
+
+ def test_profile_searchable_fields(self):
+ schema = self.registry.get("profile")
+ searchable = {f.name for f in schema.fields if f.searchable}
+ assert searchable == set()
+
+ def test_soul_searchable_fields(self):
+ schema = self.registry.get("soul")
+ searchable = {f.name for f in schema.fields if f.searchable}
+ assert searchable == set() # all rendered in content_template
+
+ def test_skills_searchable_fields(self):
+ schema = self.registry.get("skills")
+ searchable = {f.name for f in schema.fields if f.searchable}
+ assert searchable == set() # all rendered in content_template
+
+
+class TestEmbeddingTextConstruction:
+ """Test that embedding text only includes searchable fields in JSON format."""
+
+ def test_searchable_fields_as_json(self):
+ parsed = {
+ "content": "Body content here",
+ "tool_name": "web_search",
+ "call_count": "42",
+ "when_to_use": "When you need web info",
+ }
+ abstract = parsed.get("content", "")
+ searchable_fields = {"when_to_use"}
+ embedding_parts = []
+ if abstract:
+ embedding_parts.append(abstract)
+ searchable_data = {}
+ for field_name in searchable_fields:
+ if field_name == "content":
+ continue
+ field_value = parsed.get(field_name)
+ if field_value is not None:
+ field_str = str(field_value) if not isinstance(field_value, str) else field_value
+ if field_str.strip():
+ searchable_data[field_name] = field_str.strip()
+ if searchable_data:
+ import json
+
+ embedding_parts.append(json.dumps(searchable_data, ensure_ascii=False))
+ embedding_text = "\n\n".join(embedding_parts)
+ assert "web_search" not in embedding_text
+ assert "42" not in embedding_text
+ assert '"when_to_use": "When you need web info"' in embedding_text
+ assert "Body content here" in embedding_text
+
+ def test_excludes_links_and_backlinks(self):
+ parsed = {
+ "content": "Body content",
+ "summary": "A summary",
+ "links": [{"from_uri": "a", "to_uri": "b"}],
+ "backlinks": [],
+ }
+ searchable_fields = {"summary"}
+ embedding_parts = []
+ abstract = parsed.get("content", "")
+ if abstract:
+ embedding_parts.append(abstract)
+ searchable_data = {}
+ for field_name in searchable_fields:
+ if field_name == "content":
+ continue
+ field_value = parsed.get(field_name)
+ if field_value is not None:
+ field_str = str(field_value) if not isinstance(field_value, str) else field_value
+ if field_str.strip():
+ searchable_data[field_name] = field_str.strip()
+ if searchable_data:
+ import json
+
+ embedding_parts.append(json.dumps(searchable_data, ensure_ascii=False))
+ embedding_text = "\n\n".join(embedding_parts)
+ assert "links" not in embedding_text
+ assert "from_uri" not in embedding_text
+
+ def test_no_searchable_data_no_json_appended(self):
+ parsed = {
+ "content": "Body content only",
+ "event_name": "road_trip",
+ "ranges": "0-5",
+ }
+ abstract = parsed.get("content", "")
+ searchable_fields = set() # no searchable fields
+ embedding_parts = []
+ if abstract:
+ embedding_parts.append(abstract)
+ searchable_data = {}
+ for field_name in searchable_fields:
+ if field_name == "content":
+ continue
+ if searchable_data:
+ import json
+
+ embedding_parts.append(json.dumps(searchable_data, ensure_ascii=False))
+ embedding_text = "\n\n".join(embedding_parts)
+ assert embedding_text == "Body content only"
+ assert "{" not in embedding_text
diff --git a/uv.lock b/uv.lock
index 9857cf5e2..58f2e6436 100644
--- a/uv.lock
+++ b/uv.lock
@@ -1182,6 +1182,15 @@ wheels = [
{ url = "https://files.pythonhosted.org/packages/8a/0e/97c33bf5009bdbac74fd2beace167cab3f978feb69cc36f1ef79360d6c4e/exceptiongroup-1.3.1-py3-none-any.whl", hash = "sha256:a7a39a3bd276781e98394987d3a5701d0c4edffb633bb7a5144577f82c773598", size = 16740, upload-time = "2025-11-21T23:01:53.443Z" },
]
+[[package]]
+name = "execnet"
+version = "2.1.2"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/bf/89/780e11f9588d9e7128a3f87788354c7946a9cbb1401ad38a48c4db9a4f07/execnet-2.1.2.tar.gz", hash = "sha256:63d83bfdd9a23e35b9c6a3261412324f964c2ec8dcd8d3c6916ee9373e0befcd", size = 166622, upload-time = "2025-11-12T09:56:37.75Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/ab/84/02fc1827e8cdded4aa65baef11296a9bbe595c474f0d6d758af082d849fd/execnet-2.1.2-py3-none-any.whl", hash = "sha256:67fba928dd5a544b783f6056f449e5e3931a5c378b128bc18501f7ea79e296ec", size = 40708, upload-time = "2025-11-12T09:56:36.333Z" },
+]
+
[[package]]
name = "fastapi"
version = "0.135.1"
@@ -3697,6 +3706,7 @@ test = [
{ name = "pytest" },
{ name = "pytest-asyncio" },
{ name = "pytest-cov" },
+ { name = "pytest-xdist" },
{ name = "ragas" },
]
@@ -3745,7 +3755,7 @@ requires-dist = [
{ name = "langgraph", marker = "extra == 'langgraph'", specifier = ">=1.0.0,<2.0.0" },
{ name = "lark-oapi", specifier = ">=1.5.3" },
{ name = "lark-oapi", marker = "extra == 'bot-feishu'", specifier = ">=1.0.0" },
- { name = "litellm", specifier = ">=1.83.7,<1.83.13" },
+ { name = "litellm", specifier = ">=1.83.7,<1.84.1" },
{ name = "llama-cpp-python", marker = "extra == 'local-embed'", specifier = ">=0.3.0" },
{ name = "loguru", specifier = ">=0.7.3" },
{ name = "markdownify", specifier = ">=0.11.0" },
@@ -3782,6 +3792,7 @@ requires-dist = [
{ name = "pytest", marker = "extra == 'test'", specifier = ">=7.0.0" },
{ name = "pytest-asyncio", marker = "extra == 'test'", specifier = ">=0.21.0" },
{ name = "pytest-cov", marker = "extra == 'test'", specifier = ">=4.0.0" },
+ { name = "pytest-xdist", marker = "extra == 'test'", specifier = ">=3.5.0" },
{ name = "python-docx", specifier = ">=1.0.0" },
{ name = "python-multipart", specifier = ">=0.0.27" },
{ name = "python-pptx", specifier = ">=1.0.0" },
@@ -4863,6 +4874,19 @@ wheels = [
{ url = "https://files.pythonhosted.org/packages/ee/49/1377b49de7d0c1ce41292161ea0f721913fa8722c19fb9c1e3aa0367eecb/pytest_cov-7.0.0-py3-none-any.whl", hash = "sha256:3b8e9558b16cc1479da72058bdecf8073661c7f57f7d3c5f22a1c23507f2d861", size = 22424, upload-time = "2025-09-09T10:57:00.695Z" },
]
+[[package]]
+name = "pytest-xdist"
+version = "3.8.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "execnet" },
+ { name = "pytest" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/78/b4/439b179d1ff526791eb921115fca8e44e596a13efeda518b9d845a619450/pytest_xdist-3.8.0.tar.gz", hash = "sha256:7e578125ec9bc6050861aa93f2d59f1d8d085595d6551c2c90b6f4fad8d3a9f1", size = 88069, upload-time = "2025-07-01T13:30:59.346Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/ca/31/d4e37e9e550c2b92a9cbc2e4d0b7420a27224968580b5a447f420847c975/pytest_xdist-3.8.0-py3-none-any.whl", hash = "sha256:202ca578cfeb7370784a8c33d6d05bc6e13b4f25b5053c30a152269fd10f0b88", size = 46396, upload-time = "2025-07-01T13:30:56.632Z" },
+]
+
[[package]]
name = "python-dateutil"
version = "2.9.0.post0"