Skip to content

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

Refactor memory extract (#916)

chenjw277176529851
diff --git a/.gitignore b/.gitignore
index e050e2c83..a3f187325 100644
--- a/.gitignore
+++ b/.gitignore
@@ -67,6 +67,7 @@ venv.bak/
# IDE
.vscode/
.idea/
+.obsidian/
*.swp
*.swo
*~
diff --git a/bot/scripts/test_restart_openviking_server.sh b/bot/scripts/test_restart_openviking_server.sh
new file mode 100755
index 000000000..be473ae07
--- /dev/null
+++ b/bot/scripts/test_restart_openviking_server.sh
@@ -0,0 +1,175 @@
+#!/bin/bash
+
+# Restart OpenViking Server with Test Config (~/.openviking_test/ov.conf)
+# Usage: ./test_restart_openviking_server.sh [--port PORT] [--bot-url URL]
+
+set -e
+
+# Default values
+PORT="1933"
+BOT_URL="http://localhost:18790"
+TEST_CONFIG="$HOME/.openviking_test/ov.conf"
+TEST_DATA_DIR="$HOME/.openviking_test/data"
+
+# Parse arguments
+while [[ $# -gt 0 ]]; do
+ case $1 in
+ --port)
+ PORT="$2"
+ shift 2
+ ;;
+ --bot-url)
+ BOT_URL="$2"
+ shift 2
+ ;;
+ *)
+ echo "Unknown option: $1"
+ echo "Usage: $0 [--port PORT] [--bot-url URL]"
+ exit 1
+ ;;
+ esac
+done
+
+# Parse Bot URL to extract port
+BOT_PORT=$(echo "$BOT_URL" | sed -n 's/.*:\([0-9]*\).*/\1/p')
+if [ -z "$BOT_PORT" ]; then
+ BOT_PORT="18790"
+fi
+
+echo "=========================================="
+echo "Restarting OpenViking Server (TEST MODE)"
+echo "=========================================="
+echo "OpenViking Server Port: $PORT"
+echo "Bot URL: $BOT_URL"
+echo "Bot Port: $BOT_PORT"
+echo "Config File: $TEST_CONFIG"
+echo "Data Dir: $TEST_DATA_DIR"
+echo ""
+
+# Step 0: Clean up test data directory
+echo "Step 0: Cleaning up test data directory..."
+if [ -d "$TEST_DATA_DIR" ]; then
+ rm -rf "$TEST_DATA_DIR"
+ echo " ✓ Removed $TEST_DATA_DIR"
+fi
+mkdir -p "$TEST_DATA_DIR"
+echo " ✓ Created clean $TEST_DATA_DIR"
+
+# Step 1: Kill existing vikingbot processes
+echo ""
+echo "Step 1: Stopping existing vikingbot processes..."
+if pgrep -f "vikingbot.*openapi" > /dev/null 2>&1 || pgrep -f "vikingbot.*gateway" > /dev/null 2>&1; then
+ pkill -f "vikingbot.*openapi" 2>/dev/null || true
+ pkill -f "vikingbot.*gateway" 2>/dev/null || true
+ sleep 2
+ echo " ✓ Stopped existing vikingbot processes"
+else
+ echo " ✓ No existing vikingbot processes found"
+fi
+
+# Step 2: Kill existing openviking-server processes
+echo ""
+echo "Step 2: Stopping existing openviking-server processes..."
+if pgrep -f "openviking-server" > /dev/null 2>&1; then
+ pkill -f "openviking-server" 2>/dev/null || true
+ sleep 2
+ # Force kill if still running
+ if pgrep -f "openviking-server" > /dev/null 2>&1; then
+ echo " Force killing remaining processes..."
+ pkill -9 -f "openviking-server" 2>/dev/null || true
+ sleep 1
+ fi
+ echo " ✓ Stopped existing processes"
+else
+ echo " ✓ No existing processes found"
+fi
+
+# Step 3: Wait for port to be released
+echo ""
+echo "Step 3: Waiting for port $PORT to be released..."
+for i in {1..10}; do
+ if ! lsof -i :"$PORT" > /dev/null 2>&1; then
+ echo " ✓ Port $PORT is free"
+ break
+ fi
+ sleep 1
+done
+
+# Step 4: Verify test config exists
+echo ""
+echo "Step 4: Checking test config..."
+if [ ! -f "$TEST_CONFIG" ]; then
+ echo " ✗ Config file not found: $TEST_CONFIG"
+ echo ""
+ echo "Please create $TEST_CONFIG with:"
+ echo " - storage.workspace = $TEST_DATA_DIR"
+ echo " - memory.version = \"v2\" (optional)"
+ echo ""
+ exit 1
+fi
+echo " ✓ Using config: $TEST_CONFIG"
+
+# Step 5: Start openviking-server with test config
+echo ""
+echo "Step 5: Starting openviking-server with TEST config..."
+echo " Config: $TEST_CONFIG"
+echo " Command: OPENVIKING_CONFIG_FILE=$TEST_CONFIG openviking-server --with-bot --port $PORT --bot-url $BOT_URL"
+echo ""
+
+# Set environment variable to use test config
+export OPENVIKING_CONFIG_FILE="$TEST_CONFIG"
+
+# Start server
+openviking-server \
+ --with-bot \
+ --port "$PORT" \
+ --bot-url "$BOT_URL"
+
+SERVER_PID=$!
+echo " Server PID: $SERVER_PID"
+
+# Step 6: Wait for server to start
+echo ""
+echo "Step 6: Waiting for server to be ready..."
+sleep 3
+
+# First check if server is responding at all
+for i in {1..10}; do
+ if curl -s http://localhost:"$PORT"/api/v1/bot/health > /dev/null 2>&1; then
+ echo ""
+ echo "=========================================="
+ echo "✓ OpenViking Server started successfully! (TEST MODE)"
+ echo "=========================================="
+ echo ""
+ echo "Server URL: http://localhost:$PORT"
+ echo "Config File: $TEST_CONFIG"
+ echo "Data Dir: $TEST_DATA_DIR"
+ echo "Health Check: http://localhost:$PORT/api/v1/bot/health"
+ echo ""
+ exit 0
+ fi
+ # Check actual health response
+ health_response=$(curl -s http://localhost:"$PORT"/api/v1/bot/health 2>/dev/null)
+ if echo "$health_response" | grep -q "Vikingbot"; then
+ echo " ✓ Vikingbot is healthy"
+ elif echo "$health_response" | grep -q "Bot service unavailable"; then
+ echo " ⏳ Waiting for Vikingbot to start (attempt $i/10)..."
+ fi
+ sleep 2
+done
+
+# If we reach here, server failed to start
+echo ""
+echo "=========================================="
+echo "✗ Failed to start OpenViking Server (TEST MODE)"
+echo "=========================================="
+echo ""
+echo "Config used: $TEST_CONFIG"
+echo "Data dir: $TEST_DATA_DIR"
+echo ""
+echo "Troubleshooting:"
+echo " 1. Check if port $PORT is in use: lsof -i :$PORT"
+echo " 2. Check Vikingbot is running on $BOT_URL"
+echo " 3. Verify config file exists: $TEST_CONFIG"
+echo ""
+exit 1
diff --git a/docs/design/memory-extractor-optimization.md b/docs/design/memory-extractor-optimization.md
new file mode 100644
index 000000000..2abdae6de
--- /dev/null
+++ b/docs/design/memory-extractor-optimization.md
@@ -0,0 +1,1057 @@
+# Memory Extractor Templating and Update Mechanism Optimization / 记忆抽取模版与更新机制优化
+
+## Context / 上下文
+
+### Problem Background / 问题背景
+
+- [#578](https://github.com/volcengine/OpenViking/issues/578) "[Feature]: 允许提示词模板自定义添加和指定" - Current OpenViking memory_extractor uses 8 fixed memory categories (profile, preferences, entities, events, cases, patterns, tools, skills), adding new memory types requires modifying multiple core code files, prompt templates and merge logic are hard-coded. This design implements the custom template capability requested in #578. / [#578](https://github.com/volcengine/OpenViking/issues/578) "[Feature]: 允许提示词模板自定义添加和指定" - 当前 OpenViking 的 memory_extractor 使用 8 个固定的记忆类别(profile, preferences, entities, events, cases, patterns, tools, skills),新增记忆类型需要修改多处核心代码,提示模板和合并逻辑都是硬编码的。本设计实现了 #578 中要求的自定义模板能力。
+- User memory filenames use random ID encoding, not semantic, wasting the navigation value of filenames / 用户记忆文件名采用随机 ID 编码,没有语义化,浪费了文件名的导航价值
+- After extraction, merging is still required, involving multiple LLM calls, low efficiency / 抽取之后还需要做合并,涉及多次 LLM 调用,效率较低
+
+### Goals / 目标
+
+Implement a memory templating system based on OpenViking storage, such that: / 实现基于 OpenViking 存储的记忆模版化系统,使得:
+1. Design memory templating mechanism, can add new memory types without modifying core code / 设计记忆模版机制,无需修改核心代码即可添加新的记忆类型
+2. Maintain backward compatibility (existing 8 categories continue to work) / 保持向后兼容(现有 8 个类别继续工作)
+3. Adopt ReAct (Reasoning + Action) pattern for memory updates, update all memories in one ReAct-based LLM call / 采用 ReAct (Reasoning + Action) 模式进行记忆更新,一次基于 ReAct 的 LLM 调用更新所有记忆
+4. Adopt semantic filenames, fully utilize the navigation value of filenames / 采用语义化文件名,充分利用文件名的导航价值
+5. Learn from commercial memory library implementations, adopt patch incremental update mechanism (including abstract and overview), reduce LLM call count / 借鉴商业化记忆库的实现,采用 patch 增量更新机制(包括abstract和overview),减少 LLM 调用次数
+
+### Reference Design / 参考设计
+
+This design references the following core ideas from the `../memory` project: / 本设计参考了 `../memory` 项目的以下核心思想:
+- Memory templating (OpenViking's memory template is a subset of the commercial version, preserving the possibility of future upgrade to commercial version) / 记忆模版化(openviking的记忆模版是商业化版本的一个子集,保留未来升级到商业化版本的可能性)
+- Three-operation Schema (write/edit/delete) / 三种操作 Schema(write/edit/delete)
+- RoocodePatch patch protocol (patch + replace) / RoocodePatch patch协议(patch + replace)
+
+---
+
+## Two Memory Modes / 两种记忆模式
+
+The system provides two memory modes, distinguished by whether `content_template` exists. / 系统提供两种记忆模式,用是否有 `content_template` 来区分。
+
+### Simple Mode (without content_template) / 模式一:简单模式(无 content_template)
+
+**Use Cases**: profile, preferences, entities, events, cases, patterns / 适用场景:profile、preferences、entities、events、cases、patterns
+
+**Characteristics**: / 特点:
+- Only `name`, `content` two fields (or a few simple fields) / 只有 `name`、`content` 两个字段(或简单的几个字段)
+- `content` is Markdown content, no rendering needed / `content` 就是 Markdown 内容,不需要渲染
+- No `MEMORY_FIELDS` comment needed / 不需要 `MEMORY_FIELDS` 注释
+- Directly use patch to incrementally update content during updates / 更新时直接用 patch 增量更新 content
+
+**Config Examples** / **配置示例**:
+
+**profile.yaml**
+```yaml
+name: profile
+description: |
+ 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.
+ Do NOT include transient conversation content or temporary mood states.
+directory: "viking://user/{user_space}/memories"
+filename_template: "profile.md"
+
+fields:
+ - name: content
+ type: string
+ description: |
+ User profile content describing "who the user is".
+ Includes relatively stable personal attributes: profession, experience, tech stack, communication style, etc.
+ Example: "User is an AI development engineer with 3 years of LLM application development experience, mainly using Python and LangChain tech stack. Communication style is concise and direct, prefers efficient code implementation."
+ merge_op: patch
+```
+
+**preferences.yaml**
+```yaml
+name: preferences
+description: |
+ User preference memory - captures "what the user likes/dislikes or is accustomed to".
+ Extract specific preferences the user has expressed across conversations.
+ 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.
+directory: "viking://user/{user_space}/memories/preferences"
+filename_template: "{topic}.md"
+
+fields:
+ - name: topic
+ type: string
+ description: |
+ 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.
+ merge_op: immutable
+
+ - name: content
+ type: string
+ description: |
+ Specific preference content describing "what the user prefers/is accustomed to".
+ 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
+```
+
+**entities.yaml**
+```yaml
+name: entities
+description: |
+ Entity memory - captures "what this named thing is, what properties it has".
+ Extract information about specific entities mentioned in conversation.
+ Entity types include: projects, people, organizations, systems, technologies, concepts, products, etc.
+ Each entity is a named thing that has attributes worth remembering for future conversations.
+ Store each entity as a separate memory file, keyed by entity name.
+directory: "viking://user/{user_space}/memories/entities"
+filename_template: "{entity_name}.md"
+
+fields:
+ - name: entity_name
+ type: string
+ description: |
+ Entity name used to uniquely identify this entity memory.
+ Should be the specific name of the entity such as "OpenViking project", "Alice (colleague)", "Redis", etc.
+ merge_op: immutable
+
+ - name: entity_type
+ type: string
+ description: |
+ Entity type describing what type of entity this is.
+ Possible values: project, person, organization, system, technology, concept, etc.
+
+ - name: content
+ type: string
+ description: |
+ Detailed entity content describing "what this named thing is, what properties it has".
+ Includes: basic information, core attributes, status, etc.
+ Example: "OpenViking is an AI Agent long-term memory management system the user is developing. The project uses Python and AGFS tech stack, core features include memory extraction, deduplication, and retrieval. Currently in active development, goal is to build Claude-like long-term memory capabilities."
+ merge_op: patch
+```
+
+**events.yaml**
+```yaml
+name: events
+description: |
+ Event memory - captures "what happened, what decision was made, and why".
+ Extract notable events, decisions, milestones, and turning points from the conversation.
+ Events should be things worth remembering for future context: decisions made, agreements reached, milestones achieved, problems solved, etc.
+ Each event should include: what happened, why it happened, what the outcome was, and any relevant context/timeline.
+ Use absolute dates for event_time, not relative time like "today" or "recently".
+directory: "viking://user/{user_space}/memories/events"
+filename_template: "{event_time}_{event_name}.md"
+
+fields:
+ - name: event_name
+ type: string
+ description: |
+ Event name used to uniquely identify this event memory.
+ Should be a specific event description such as "Decided to refactor memory system", "Started OpenViking project", "Completed Q3 review", etc.
+ Example: "[Action]: [Description]"
+ merge_op: immutable
+
+ - name: event_time
+ type: string
+ description: |
+ Time when the event occurred, use absolute time format, do not use relative time (such as "today", "recently").
+ Can be empty if time is unknown.
+ Example: "2026-03-17"
+ merge_op: immutable
+
+ - name: content
+ type: string
+ description: |
+ Detailed event content describing "what happened".
+ Includes: decision content, reasons, results, background, timeline, etc.
+ Example: "During memory system design discussion, found that the original 6 categories had blurry boundaries. Especially states, lessons, insights often overlapped and were hard to distinguish. Decided to refactor to 5 categories, removing these three to make classification boundaries clearer."
+ merge_op: patch
+```
+
+**cases.yaml**
+```yaml
+name: cases
+description: |
+ Case memory - captures "what problem was encountered and how it was solved".
+ Extract specific problem-solution pairs from the conversation that are worth remembering for future reference.
+ Cases should be about specific problems that have clear solutions.
+ Each case should include: what the problem was (symptoms, error messages, context), what the solution was (steps taken, principles used), and why it worked.
+ Case names should be in "Problem → Solution" format to make them easily searchable.
+directory: "viking://agent/{agent_space}/memories/cases"
+filename_template: "{case_name}.md"
+
+fields:
+ - name: case_name
+ type: string
+ description: |
+ Case name used to uniquely identify this case memory.
+ Should be in "Problem → Solution" format such as "Band not recognized → Request member/album/style details", "Memory merge timeout → Split into smaller chunks", etc.
+ Example: "[Problem] → [Solution]"
+ merge_op: immutable
+
+ - name: problem
+ type: string
+ description: |
+ Problem description specifically detailing what problem was encountered.
+ Includes: error messages, symptoms, context, and other specific details.
+ Example: "User feedback that a band cannot be recognized by system."
+ merge_op: patch
+
+ - name: solution
+ type: string
+ description: |
+ Solution description detailing how to solve this problem.
+ Includes: solution method, steps, principles, etc.
+ Example: "Request user to provide more identification details: band member names, representative album names, music style, etc. This information can improve recognition accuracy."
+ merge_op: patch
+
+ - name: content
+ type: string
+ description: |
+ Complete case content including full narrative of problem and solution.
+ Example: "User feedback mentioned a band that the system could not recognize. Solution is to request user to provide more identification details: band member names, representative album names, music style, etc. This information can improve recognition accuracy."
+ merge_op: patch
+```
+
+**patterns.yaml**
+```yaml
+name: patterns
+description: |
+ Pattern memory - captures "under what circumstances to follow what process".
+ Extract reusable workflows, processes, and methods that the agent should follow in similar future situations.
+ Patterns should be about: how to approach certain types of tasks, what steps to follow, what considerations to keep in mind.
+ Each pattern should include: trigger conditions (when to use this pattern), process steps (what to do), and considerations (what to watch out for).
+ Pattern names should be in "Process name: Step description" format.
+directory: "viking://agent/{agent_space}/memories/patterns"
+filename_template: "{pattern_name}.md"
+
+fields:
+ - name: pattern_name
+ type: string
+ description: |
+ Pattern name used to uniquely identify this pattern memory.
+ Should be in "Process name: Step description" format such as "Teaching topic handling: Outline→Plan→Generate PPT", "Code refactoring: Understand→Test→Refactor→Verify", etc.
+ Example: "[Pattern name]: [Step sequence]"
+ merge_op: immutable
+
+ - name: pattern_type
+ type: string
+ description: |
+ Pattern type describing what type of pattern this is.
+ Possible values: workflow, method, process, etc.
+
+ - name: content
+ type: string
+ description: |
+ Detailed pattern content describing "under what circumstances to follow what process".
+ Includes: trigger conditions, process steps, considerations, etc.
+ Example: "When user requests teaching content for a topic, use a four-step process: first list the topic outline to understand overall structure; then create a detailed learning plan; next generate PPT framework; finally refine specific content for each section. This process ensures content is systematic and complete."
+ merge_op: patch
+```
+
+**Memory File Storage Format Example** / **记忆文件存储格式示例**:
+```markdown
+# User Profile
+
+User is an AI development engineer with 3 years of experience...
+```
+
+---
+
+### Template Mode (with content_template) / 模式二:模板模式(有 content_template)
+
+**Use Cases**: tools, skills / 适用场景:tools、skills
+
+**Characteristics**: / 特点:
+- Has multiple structured fields (including statistical fields like usage count, success rate, etc.) / 有多个结构化字段(包括统计字段如使用次数、成功率等)
+- `content` is rendered from fields via `content_template` / `content` 是通过 `content_template` 从字段渲染出来的
+- `MEMORY_FIELDS` JSON comment is always placed at the end of the file / `MEMORY_FIELDS` JSON 注释永远放在文件最后
+- Update workflow: / 更新流程:
+ 1. Parse JSON fields from `<!-- MEMORY_FIELDS -->` comment at the end of Markdown file / 从 Markdown 文件最后的 `<!-- MEMORY_FIELDS -->` 注释中解析 JSON 字段
+ 2. Perform memory updates according to field's `merge_op` / 根据字段的 `merge_op` 做记忆更新
+ 3. Re-render Markdown content via `content_template` after update / 更新后通过 `content_template` 重新渲染 Markdown 内容
+ 4. Write updated `MEMORY_FIELDS` back to end of file / 把更新后的 `MEMORY_FIELDS` 写回文件最后
+
+**Config Examples** / **配置示例**:
+
+**tools.yaml**
+```yaml
+name: tools
+description: |
+ Tool usage memory - captures "how this tool is used, what works well, and what doesn't".
+ Extract tool usage patterns, statistics, and learnings from [ToolCall] records and conversation context.
+ For each tool, track: how many times it's been called, success rate, average time/tokens, what it's best for, optimal parameters, common failure modes, and actionable recommendations.
+ Also accumulate complete guidelines with "Good Cases" and "Bad Cases" examples.
+ Tool memories help the agent learn from experience and use tools more effectively over time.
+directory: "viking://agent/{agent_space}/memories/tools"
+filename_template: "{tool_name}.md"
+
+content_template: |
+ Tool: {tool_name}
+
+ Static Description:
+ "{static_desc}"
+
+ Tool Memory Context:
+ Based on {total_calls} historical calls:
+ - Success rate: {success_rate}% ({success_count} successful, {fail_count} failed)
+ - Avg time: {avg_time}, Avg tokens: {avg_tokens}
+ - Best for: {best_for}
+ - Optimal params: {optimal_params}
+ - Common failures: {common_failures}
+ - Recommendation: {recommendation}
+
+ {guidelines}
+
+fields:
+ - name: tool_name
+ type: string
+ description: |
+ Tool name, copied exactly from [ToolCall] records without modification.
+ Used to uniquely identify this tool memory.
+ Examples: "web_search", "read_file", "execute_code"
+ merge_op: immutable
+
+ - name: static_desc
+ type: string
+ description: |
+ Static description of the tool, basic functionality description.
+ Examples: "Searches the web for information", "Reads files from the file system"
+
+ - name: total_calls
+ type: int64
+ description: |
+ Total number of tool calls, accumulated from historical statistics.
+ Used to calculate success rate and average duration.
+ merge_op: sum
+
+ - name: success_count
+ type: int64
+ description: |
+ Number of successful tool calls, accumulated from historical statistics.
+ Counts calls with status "completed".
+ merge_op: sum
+
+ - name: fail_count
+ type: int64
+ description: |
+ Number of failed tool calls, accumulated from historical statistics.
+ Counts calls with status not "completed".
+ merge_op: sum
+
+ - name: total_time_ms
+ type: int64
+ description: |
+ Total tool call duration in milliseconds, accumulated from historical statistics.
+ Used to calculate average duration.
+ merge_op: sum
+
+ - name: total_tokens
+ type: int64
+ description: |
+ Total tokens used by tool calls (prompt tokens + completion tokens), accumulated from historical statistics.
+ Used to calculate average token consumption.
+ merge_op: sum
+
+ - name: best_for
+ type: string
+ description: |
+ Best use cases for the tool, describing in what scenarios this tool works best.
+ Examples: "Technical documentation, tutorials, API references"
+ merge_op: patch
+
+ - name: optimal_params
+ type: string
+ description: |
+ Optimal parameter range/best practices for the tool, describing general parameter optimization suggestions.
+ Should describe general best practices (such as "max_results=5-20", "timeout>30s for large files"),
+ do not describe specific case values (such as "command: 'echo hello'").
+ Examples: "max_results: 5-20 (larger values may timeout); language: 'en' for better results; query: specific multi-word phrases with qualifiers"
+ merge_op: patch
+
+ - name: common_failures
+ type: string
+ description: |
+ Common failure modes of the tool, describing problems and error patterns this tool frequently encounters.
+ Examples: "Single-word queries return irrelevant results; max_results>50 causes timeout; non-English queries have lower quality"
+ merge_op: patch
+
+ - name: recommendation
+ type: string
+ description: |
+ Actionable recommendations for tool usage, short actionable recommendations.
+ Examples: "Use specific multi-word queries like 'Python asyncio tutorial'; add qualifiers like 'guide', 'docs', 'example'"
+ merge_op: patch
+
+ - name: guidelines
+ type: string
+ description: |
+ Tool usage guidelines, complete usage guide content.
+ Must include exact English headings:
+ - "## Guidelines" - best practices
+ - "### Good Cases" - successful usage examples
+ - "### Bad Cases" - failed usage examples
+ Headings must be in English, content can be in target language.
+ merge_op: patch
+```
+
+**skills.yaml**
+```yaml
+name: skills
+description: |
+ Skill execution memory - captures "how this skill is executed, what works well, and what doesn't".
+ Extract skill execution patterns, statistics, and learnings from skill usage in conversation.
+ For each skill, track: how many times it's been executed, success rate, what it's best for, recommended execution flow, key dependencies, common failure modes, and actionable recommendations.
+ Also accumulate complete guidelines with "Good Cases" and "Bad Cases" examples.
+ Skill memories help the agent learn from experience and execute skills more effectively over time.
+directory: "viking://agent/{agent_space}/memories/skills"
+filename_template: "{skill_name}.md"
+
+content_template: |
+ Skill: {skill_name}
+
+ Skill Memory Context:
+ Based on {total_executions} historical executions:
+ - Success rate: {success_rate}% ({success_count} successful, {fail_count} failed)
+ - Best for: {best_for}
+ - Recommended flow: {recommended_flow}
+ - Key dependencies: {key_dependencies}
+ - Common failures: {common_failures}
+ - Recommendation: {recommendation}
+
+ {guidelines}
+
+fields:
+ - name: skill_name
+ type: string
+ description: |
+ Skill name, copied exactly from [ToolCall] if skill_name is present, otherwise inferred from conversation context.
+ Used to uniquely identify this skill memory.
+ Examples: "create_presentation", "analyze_code", "write_document"
+ merge_op: immutable
+
+ - name: total_executions
+ type: int64
+ description: |
+ Total number of skill executions, accumulated from historical statistics.
+ Used to calculate success rate.
+ merge_op: sum
+
+ - name: success_count
+ type: int64
+ description: |
+ Number of successful skill executions, accumulated from historical statistics.
+ Counts successful executions.
+ merge_op: sum
+
+ - name: fail_count
+ type: int64
+ description: |
+ Number of failed skill executions, accumulated from historical statistics.
+ Counts failed executions.
+ merge_op: sum
+
+ - name: best_for
+ type: string
+ description: |
+ Best use cases for the skill, describing in what scenarios this skill works best.
+ Examples: "Slide creation tasks with clear topic and target audience"
+ merge_op: patch
+
+ - name: recommended_flow
+ type: string
+ description: |
+ Recommended execution flow for the skill, describing the best steps to execute this skill.
+ Examples: "1. Confirm topic and audience → 2. Collect reference materials → 3. Generate outline → 4. Create slides → 5. Refine content"
+ merge_op: patch
+
+ - name: key_dependencies
+ type: string
+ description: |
+ Key dependencies/prerequisites for the skill, describing what prerequisites and inputs are needed to execute this skill.
+ Examples: "Clear topic (e.g., 'Q3 project update', 'Python tutorial'); Target audience (e.g., 'executives', 'beginners'); Reference materials (optional but recommended)"
+ merge_op: patch
+
+ - name: common_failures
+ type: string
+ description: |
+ Common failure modes of the skill, describing problems and error patterns this skill frequently encounters.
+ Examples: "Vague topic like 'make a PPT' leads to multiple rework cycles; Missing audience info causes style mismatch; No reference materials results in generic content"
+ merge_op: patch
+
+ - name: recommendation
+ type: string
+ description: |
+ Actionable recommendations for skill usage, short actionable recommendations.
+ Examples: "Always confirm topic and audience before starting; Collect 2-3 reference materials for better quality"
+ merge_op: patch
+
+ - name: guidelines
+ type: string
+ description: |
+ Skill usage guidelines, complete usage guide content.
+ Must include exact English headings:
+ - "## Guidelines" - best practices
+ - "### Good Cases" - successful usage examples
+ - "### Bad Cases" - failed usage examples
+ Headings must be in English, content can be in target language.
+ merge_op: patch
+```
+
+**Memory File Storage Format Example** / **记忆文件存储格式示例**:
+```markdown
+Tool: web_search
+
+Static Description:
+"Searches the web for information"
+
+Tool Memory Context:
+Based on 100 historical calls:
+- Success rate: 92.0% (92 successful, 8 failed)
+- Avg time: 1.2s, Avg tokens: 1500
+- Best for: Technical documentation, tutorials, API references
+- Optimal params: max_results=5-20, timeout>30s
+- Common failures: Single-word queries return irrelevant results
+- Recommendation: Use specific multi-word queries
+
+## Guidelines
+...
+
+### Good Cases
+...
+
+### Bad Cases
+...
+
+<!-- MEMORY_FIELDS
+{
+ "tool_name": "web_search",
+ "static_desc": "Searches the web for information",
+ "total_calls": 100,
+ "success_count": 92,
+ "fail_count": 8,
+ "total_time_ms": 120000,
+ "total_tokens": 150000,
+ "best_for": "Technical documentation, tutorials, API references",
+ "optimal_params": "max_results=5-20, timeout>30s",
+ "common_failures": "Single-word queries return irrelevant results",
+ "recommendation": "Use specific multi-word queries",
+ "guidelines": "## Guidelines\n...\n\n### Good Cases\n...\n\n### Bad Cases\n..."
+}
+-->
+```
+
+---
+
+## Overall Architecture / 整体架构
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│ Phase 0: Pre-fetch (System) │
+│ ┌───────────────────────────────────────────────────────────┐ │
+│ │ System automatically executes before LLM reasoning: │ │
+│ │ 1. ls: Get all memory directory structures │ │
+│ │ 2. read: Read all .abstract.md (L0) and .overview.md (L1)│ │
+│ │ 3. search: Perform one semantic search in all directories│ │
+│ │ Output: Pre-fetched Context (dir + L0/L1 + search results)│ │
+│ └───────────────────────────────────────────────────────────┘ │
+└─────────────────────────────────────────────────────────────────┘
+ ↓
+┌─────────────────────────────────────────────────────────────────┐
+│ Phase 1: Reasoning + Action (LLM + Optional Reads) │
+│ ┌───────────────────────────────────────────────────────────┐ │
+│ │ LLM: Analyze conversation + Pre-fetched Context │ │
+│ │ Output: Reasoning + Actions (optional additional reads) │ │
+│ │ - Reasoning: What memories need to change │ │
+│ │ - Actions: Additional read operations (only if needed) │ │
+│ └───────────────────────────────────────────────────────────┘ │
+└─────────────────────────────────────────────────────────────────┘
+ ↓
+┌─────────────────────────────────────────────────────────────────┐
+│ Phase 2: Generate Operations (Final Output) │
+│ ┌───────────────────────────────────────────────────────────┐ │
+│ │ LLM: Generate final operations based on existing memories │ │
+│ │ Output: MemoryOperations │ │
+│ │ - WriteOp: New memory data (create or full replace) │ │
+│ │ - EditOp: patch (SEARCH/REPLACE) incremental update │ │
+│ │ - DeleteOp: URI to delete │ │
+│ │ [Note] This is model's final output, directly executed │ │
+│ └───────────────────────────────────────────────────────────┘ │
+└─────────────────────────────────────────────────────────────────┘
+ ↓
+┌─────────────────────────────────────────────────────────────────┐
+│ Phase 3: System Execute │
+│ ┌───────────────────────────────────────────────────────────┐ │
+│ │ MemoryUpdater: Directly execute MemoryOperations │ │
+│ │ - Write to OpenViking Storage (L0/L1/L2) │ │
+│ │ - Update VikingDB vector index │ │
+│ └───────────────────────────────────────────────────────────┘ │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Core Components Design / 核心组件设计
+
+### 1. Memory Data Structures / 记忆数据结构
+
+#### 1.1 MemoryField (Memory Field Definition / 记忆字段定义)
+
+Field properties / 字段属性:
+- name: Field name / 字段名称
+- field_type: Field type (string/int64/float32/bool) / 字段类型(string/int64/float32/bool)
+- description
+- merge_op: Merge operation (patch/sum/avg/immutable), default patch / 合并操作(patch/sum/avg/immutable),默认 patch
+ - patch: Default, SEARCH/REPLACE incremental update / 默认,SEARCH/REPLACE 增量更新
+ - sum: Sum (numeric fields like total_calls, success_count) / 累加(数字字段,如 total_calls、success_count)
+ - avg: Average (calculated from sum fields, non-storage field) / 平均值(从 sum 字段计算,非存储字段)
+ - immutable: Immutable after initial generation (for filename-related fields) / 初次生成后不可变(用于文件名相关字段)
+
+**Special fields** / **特殊字段**:
+- `content`: Default Markdown content field, only this field is used in simple mode / 默认的 Markdown 内容字段,简单模式下只用这个字段
+- `abstract`: L0 summary field (one-sentence summary for indexing) / L0 摘要字段(用于索引的一句话摘要)
+- `overview`: L1 overview field (structured Markdown summary) / L1 概览字段(结构化 Markdown 摘要)
+
+#### 1.2 MemoryType (Memory Type Definition / 记忆类型定义)
+
+Type properties / 类型属性:
+- name: Type name, e.g., "preferences", "tools" / 类型名称,如 "preferences", "tools"
+- description
+- directory: Full URI for memory data storage, e.g., "viking://user/{user_space}/memories/preferences" / 记忆数据存放的完整 URI,如 "viking://user/{user_space}/memories/preferences"
+- fields: MemoryField list / MemoryField 列表
+- filename_template: Filename generation template, e.g., "{name}_{topic}.md" / 文件名生成模板,如 "{name}_{topic}.md"
+- content_template: Content rendering template (supports field placeholders), used to render Markdown content from fields / 内容渲染模板(支持字段占位符),用于从 fields 渲染 Markdown 内容
+
+**content_template example** (for tools type) / **content_template 示例**(用于 tools 类型):
+```yaml
+content_template: |
+ # Tool: {tool_name}
+
+ Tool Memory Context:
+ Based on {total_calls} historical calls:
+ - Success rate: {success_rate}% ({success_count} successful, {fail_count} failed)
+ - Best for: {best_for}
+ - Common failures: {common_failures}
+ - Recommendation: {recommendation}
+
+ {content}
+```
+
+#### 1.3 MemoryData (Dynamic Memory Data / 动态记忆数据)
+
+Data properties / 数据属性:
+- memory_type: Memory type name / 记忆类型名称
+- uri: Memory URI (provided during update) / 记忆 URI(更新时提供)
+- fields: Dynamic field data (Dict) / 动态字段数据(Dict)
+- abstract/overview/content: L0/L1/L2 content / L0/L1/L2 内容
+- name/tags/created_at/updated_at: Metadata / 元数据
+
+### 2. ReAct Flow Data Structures / ReAct 流程数据结构
+
+#### 2.1 Reasoning + Action (Phase 1: Reasoning Output / 阶段 1: 推理输出)
+
+```
+ReasoningAction:
+ - reasoning: str # LLM's thinking string (natural language description)
+ - memory_changes: List[MemoryChange] # Memories that need changes
+ - actions: List[ReadAction] # Read operations to execute
+
+MemoryChange:
+ - change_type: write/edit/delete
+ - memory_type: Memory type
+ - uri: Memory URI (if known)
+ - reason: Reason for change
+
+ReadAction:
+ - action_type: read/find/ls
+ - params: Dict # Call parameters
+```
+
+**Available Tools** (consistent with OpenViking VikingFS API) / **可使用的工具**(与 OpenViking VikingFS API 保持一致):
+
+**read**
+- Parameters / 参数: `uri: str, offset: int = 0, limit: int = -1`
+- Returns / 返回: Memory file content (str) / 记忆文件内容(str)
+- Description / 说明: Read single file, offset is start line number (0-indexed), limit is number of lines to read, -1 means read to end / 读取单个文件,offset 为起始行号(0-indexed),limit 为读取行数,-1 表示读取到末尾
+
+**find**
+- Parameters / 参数: `query: str, target_uri: str = "", limit: int = 10, score_threshold: Optional[float] = None, filter: Optional[Dict] = None`
+- Returns / 返回: FindResult (includes memories, resources, skills) / FindResult(包含 memories, resources, skills)
+- Description / 说明: Semantic search, target_uri is target directory URI / 语义搜索,target_uri 为目标目录 URI
+
+**ls**
+- Parameters / 参数: `uri: str, output: str = "agent", abs_limit: int = 256, show_all_hidden: bool = False, node_limit: int = 1000`
+- Returns / 返回: List[Dict] (directory entry list) / List[Dict](目录条目列表)
+- Description / 说明: List directory content, includes abstract field when output="agent" / 列出目录内容,output="agent" 时包含 abstract 字段
+
+**tree**
+- Parameters / 参数: `uri: str = "viking://", output: str = "agent", abs_limit: int = 256, show_all_hidden: bool = False, node_limit: int = 1000, level_limit: int = 3`
+- Returns / 返回: List[Dict] (recursive directory tree) / List[Dict](递归目录树)
+- Description / 说明: Recursively list all content, includes abstract field when output="agent", level_limit controls traversal depth / 递归列出所有内容,output="agent" 时包含 abstract 字段,level_limit 控制遍历深度
+
+**Important** / **重要**: No function calls like add_memory/update_memory/delete_memory, add/edit/delete operations are model's final output as MemoryOperations, directly executed by system / 没有 add_memory/update_memory/delete_memory 这样的 function call,增删改操作通过模型最终输出 MemoryOperations,由系统直接执行
+
+#### 2.2 MemoryOperations (Phase 2: Final Output / 阶段 2: 最终输出)
+
+```
+MemoryOperations:
+ - write_operations: List[WriteOp]
+ - edit_operations: List[EditOp]
+ - delete_operations: List[DeleteOp]
+
+WriteOp:
+ - uri: Target memory URI / 目标记忆的 URI
+ - memory_data: MemoryData
+
+EditOp:
+ - uri: Target memory URI / 目标记忆的 URI
+ - patches: Field-level updates / 字段级更新
+
+DeleteOp:
+ - uri: Memory URI to delete / 要删除的记忆 URI
+```
+
+### 3. Patch Handler / Patch 处理器
+
+#### 3.1 Content-level Patch (SEARCH/REPLACE) / 内容级 Patch (SEARCH/REPLACE)
+
+```
+Patch format / Patch 格式:
+<<<<<<< SEARCH
+:start_line:10
+-------
+Original content / 原始内容
+=======
+New content / 新内容
+>>>>>>> REPLACE
+```
+
+#### 3.2 Field-level Patch / 字段级 Patch
+
+Handle according to field's merge_op / 根据字段的 merge_op 处理:
+- patch: Default, SEARCH/REPLACE incremental update / 默认,SEARCH/REPLACE 增量更新
+- sum: Sum (numeric fields like total_calls, success_count) / 累加(数字字段,如 total_calls、success_count)
+- avg: Average (calculated from sum fields, non-storage field) / 平均值(从 sum 字段计算,非存储字段)
+
+### 4. MemoryTypeRegistry (Type Registry / 类型注册表)
+
+Features / 功能:
+- register(memory_type): Register memory type / 注册记忆类型
+- get(name): Get memory type / 获取记忆类型
+- list_all(): List all types / 列出所有类型
+- load_from_dir(dir_path): Load all MemoryType YAML files from directory (one type per file) / 从目录加载所有 MemoryType YAML 文件(每个文件一个类型)
+ - Default load built-in types from `openviking/session/memory/schemas/` / 默认从 `openviking/session/memory/schemas/` 加载内置类型
+
+### 5. MemoryReActOrchestrator (ReAct Orchestrator / ReAct 编排器)
+
+#### Workflow / 工作流:
+
+**Optimization Strategy** / **优化策略**: To avoid excessive time from multiple ReAct rounds, system automatically performs pre-fetch before LLM reasoning / 为避免多次 ReAct 导致耗时过长,系统在 LLM 推理前自动执行前置读取:
+
+**Phase 0: Pre-fetch (system executes, before LLM reasoning)** / **阶段 0: Pre-fetch(系统执行,LLM 推理前)**:
+1. **ls**: Get all memory directory structures / 获取所有记忆目录结构
+ - `viking://user/{user_space}/memories/` and subdirectories / 及子目录
+ - `viking://agent/{agent_space}/memories/` and subdirectories / 及子目录
+2. **read**: Read all `.abstract.md` (L0) and `.overview.md` (L1) / 读取所有 `.abstract.md` (L0) 和 `.overview.md` (L1)
+ - These summary files provide memory overview with small size / 这些摘要文件提供记忆的概览信息,体积小
+3. **search**: Perform one semantic search in all directories / 在所有目录执行一次语义搜索
+ - Use current conversation as query / 使用当前对话作为查询
+ - Return list of relevant memory URIs / 返回相关的记忆 URI 列表
+
+**Phase 1: Reasoning + Action**: LLM analyzes conversation + Pre-fetched Context, outputs ReasoningAction / LLM 分析对话 + Pre-fetched Context,输出 ReasoningAction
+ - reasoning: LLM's thinking string (natural language description) / LLM 的 thinking 字符串(自然语言描述)
+ - memory_changes: Memories that need changes (write/edit/delete) / 需要变更的记忆(write/edit/delete)
+ - actions: Additional read operations (only execute when needed, e.g., read specific L2 content) / 额外的读取操作(仅在需要时执行,如读取具体 L2 内容)
+ - System executes additional read operations (if needed) / 系统执行额外读取操作(如需要)
+
+**Phase 2: Generate Operations**: LLM generates MemoryOperations based on existing memories (final output) / LLM 基于现有记忆生成 MemoryOperations(最终输出)
+
+**Phase 3: System Execute**: System directly executes MemoryOperations / 系统直接执行 MemoryOperations
+
+### 6. MemoryUpdater (Patch Applier - System Execution / Patch 应用器 - 系统执行)
+
+Features / 功能:
+- apply_operations(operations, user): Apply memory operations, return list of changed URIs / 应用记忆操作,返回变更的 URI 列表
+- Directly execute MemoryOperations from model output, no function call / 直接执行模型输出的 MemoryOperations,不经过 function call
+
+### 7. Structured Output Implementation / 结构化输出实现
+
+Based on the implementation from ../memory project, the following tech stack is used / 基于 ../memory 项目的实现方案,采用以下技术栈:
+
+#### 7.1 Core Components / 核心组件
+
+**Pydantic BaseModel**: Used to define all data structures / 用于定义所有数据结构
+- MemoryField, MemoryType, MemoryData
+- ReasoningAction, MemoryChange, ReadAction
+- MemoryOperations, WriteOp, EditOp, DeleteOp
+
+**json_repair**: Fault-tolerant LLM output parsing / 容错解析 LLM 输出
+- Auto-repair incomplete JSON / 自动修复不完整的 JSON
+- Handle trailing content (e.g., safety warnings) / 处理尾随内容(如安全警告)
+- Compatible with non-standard formats / 兼容非标准格式
+
+**Pydantic TypeAdapter**: Type validation and conversion / 类型验证和转换
+- validate_python(value, strict=False) - non-strict mode validation / 非严格模式验证
+- Automatic type conversion / 自动类型转换
+- Fault-tolerant filtering for list types / 列表类型容错过滤
+
+**BaseModelCompat**: Compatibility base class (refer to ../memory) / 兼容性基类(参考 ../memory)
+- Extract base type from Optional/Union / 从 Optional/Union 提取基础类型
+- Convert 'None' string to None / 'None' 字符串转 None
+- Automatic string conversion (array→comma-separated string, dict→JSON) / 字符串自动转换(数组→逗号分隔字符串,dict→JSON)
+- Numeric fault tolerance (string→int/float) / 数字容错(字符串→int/float)
+- List fault tolerance (string→[string], dict→[dict]) / 列表容错(字符串→[string],dict→[dict])
+
+#### 7.2 JSONAdapter Flow / JSONAdapter 流程
+
+```
+1. format() - Build prompt / 构建提示
+ - prepare_instructions(): Generate input/output field descriptions / 生成输入输出字段说明
+ - format_turn(): Format user/assistant messages / 格式化用户/助手消息
+ - format_fields(): Format field values / 格式化字段值
+
+2. llm_request() - Call LLM / 调用 LLM
+ - Check if json_schema is supported / 检查是否支持 json_schema
+ - If supported: generate response_format (type: json_schema) / 如果支持:生成 response_format (type: json_schema)
+ - If not supported: use json_object or no format / 如果不支持:使用 json_object 或无格式
+ - Call LM with static_messages + dynamic_messages / 调用 LM,传入 static_messages + dynamic_messages
+
+3. parse() - Parse output / 解析输出
+ - remove_trailing_content(): Remove content after JSON ends / 去除 JSON 结束后的内容
+ - json_repair.loads(): Fault-tolerant parsing / 容错解析
+ - parse_value(): Type conversion + fault tolerance / 类型转换 + 容错
+ - List type: filter invalid items / 列表类型:过滤无效项目
+ - Other types: use TypeAdapter validation / 其他类型:使用 TypeAdapter 验证
+```
+
+#### 7.3 Fault Tolerance Strategy / 容错策略
+
+**JSON Parsing Fault Tolerance** / **JSON 解析容错**:
+- Remove trailing content after JSON ends (e.g., safety warnings) / 去除 JSON 结束后的尾随内容(如安全警告)
+- json_repair auto-repairs incomplete JSON / json_repair 自动修复不完整 JSON
+- Compatible with array output (take first element) / 兼容数组输出(取第一个元素)
+
+**Type Validation Fault Tolerance** / **类型验证容错**:
+- List type: validate items one by one, skip invalid items / 列表类型:逐个验证元素,跳过无效项
+- Non-strict mode (strict=False) validation / 非严格模式 (strict=False) 验证
+- BaseModelCompat preprocessor handles common format issues / BaseModelCompat 预处理器处理常见格式问题
+
+**Field Fault Tolerance** / **字段容错**:
+- Missing fields: use default values / 缺失字段:使用默认值
+- Extra fields: automatically ignore / 多余字段:自动忽略
+- Type mismatch: attempt automatic conversion / 类型不匹配:尝试自动转换
+
+---
+
+## Existing Design Analysis / 现有设计分析
+
+### Current Architecture / 当前架构
+
+### Storage / 存储方式
+
+- **File Storage**: L0/L1/L2 three-level structure / L0/L1/L2 三层结构
+ - L0: `.abstract.md` - summary / 摘要
+ - L1: `.overview.md` - overview / 概览
+ - L2: content file / 内容文件
+
+- **URI Structure**:
+ - User: `viking://user/{space}/memories/{category}/`
+ - Agent: `viking://agent/{space}/memories/{category}/`
+
+- **Vector Index**: stored in context collection of VikingDB / 存储在 VikingDB 的 context 集合中
+
+### Key Files / 关键文件
+
+| File / 文件 | Purpose / 作用 |
+| ----------------------------------------------------------------- | ------------------------------------------------------------- |
+| `openviking/session/memory_extractor.py` | Memory extraction main logic (~1200 lines) / 记忆提取主逻辑 (~1200行) |
+| `openviking/session/memory_deduplicator.py` | Deduplication decision (~395 lines) / 去重决策 (~395行) |
+| `openviking/session/compressor.py` | Session compressor (~447 lines) / 会话压缩器 (~447行) |
+| `openviking/prompts/templates/compression/memory_extraction.yaml` | Extraction prompt template (~400 lines) / 提取提示模板 (~400行) |
+
+---
+
+## Implementation Steps / 实施步骤
+
+### Phase 1: Core Data Structures / 核心数据结构
+
+1. Create `openviking/session/memory/memory_data.py` / 创建 `openviking/session/memory/memory_data.py`
+ - Field type, merge operation Enum / 字段类型、合并策略 Enum
+ - MemoryField, MemoryType, MemoryData definitions / MemoryField、MemoryType、MemoryData 定义
+
+2. Create `openviking/session/memory/memory_operations.py` / 创建 `openviking/session/memory/memory_operations.py`
+ - WriteOp, EditOp, DeleteOp
+ - MemoryOperations (LLM final output format) / MemoryOperations(LLM 最终输出格式)
+
+3. Create `openviking/session/memory/memory_react.py` / 创建 `openviking/session/memory/memory_react.py`
+ - Standard LLM ReAct implementation / 标准的 LLM ReAct 实现
+
+4. Create `openviking/session/memory/memory_functions.py` / 创建 `openviking/session/memory/memory_functions.py`
+ - ReadArgs/ReadResult
+ - FindArgs/FindResult
+ - LsArgs/LsResult
+ - READ_TOOL, FIND_TOOL, LS_TOOL definitions / READ_TOOL、FIND_TOOL、LS_TOOL 定义
+
+### Phase 2: Patch Handling / Patch 处理
+
+5. Create `openviking/session/memory/memory_patch.py` / 创建 `openviking/session/memory/memory_patch.py`
+ - MemoryPatchHandler class / MemoryPatchHandler 类
+ - apply_content_patch() - SEARCH/REPLACE format / SEARCH/REPLACE 格式
+ - apply_field_patches() - Field-level updates / 字段级更新
+
+### Phase 3: Type Registration / 类型注册
+
+6. Create `openviking/session/memory/memory_types.py` / 创建 `openviking/session/memory/memory_types.py`
+ - MemoryTypeRegistry class / MemoryTypeRegistry 类
+ - YAML loading functionality / YAML 加载功能
+ - Built-in type registration / 内置类型注册
+
+7. Create YAML config files / 创建 YAML 配置文件
+ - Place in `openviking/session/memory/schemas/` directory / 放在 `openviking/session/memory/schemas/` 目录
+ - preferences.yaml, entities.yaml, tools.yaml, etc. / preferences.yaml、entities.yaml、tools.yaml 等
+
+### Phase 4: MemoryUpdater
+
+8. Create `openviking/session/memory/memory_updater.py` / 创建 `openviking/session/memory/memory_updater.py`
+ - MemoryUpdater class / MemoryUpdater 类
+ - apply_operations() method - system direct execution / apply_operations() 方法 - 系统直接执行
+ - Integration with OpenViking Storage / 与 OpenViking Storage 集成
+
+### Phase 5: ReAct Orchestrator / ReAct 编排器
+
+9. Complete `openviking/session/memory/memory_react.py` / 完善 `openviking/session/memory/memory_react.py`
+ - Standard LLM ReAct orchestrator implementation / 标准的 LLM ReAct 编排器实现
+
+### Phase 6: Prompt Templates / 提示模板
+
+10. Create LLM prompt templates / 创建 LLM 提示模板
+ - Reasoning prompt (output MemoryChangePlan format) / 推理提示(输出 MemoryChangePlan 格式)
+ - Operation generation prompt (output MemoryOperations format) / 操作生成提示(输出 MemoryOperations 格式)
+ - L0/L1 summary generation prompt / L0/L1 摘要生成提示
+
+11. Create new memory_extractor_v2.py / 创建新的 memory_extractor_v2.py
+ - Implement new memory extractor entry point / 实现新的记忆提取器入口
+ - Preserve existing memory_extractor.py without modification / 保留现有 memory_extractor.py 不修改
+ - Can switch via config later / 后续可通过配置切换
+
+### Phase 7: Testing and Verification / 测试与验证
+
+12. Unit tests / 单元测试
+ - MemoryPatchHandler tests / MemoryPatchHandler 测试
+ - MemoryUpdater tests / MemoryUpdater 测试
+ - MemoryReActOrchestrator tests / MemoryReActOrchestrator 测试
+
+13. Integration tests / 集成测试
+ - End-to-end ReAct flow tests / 端到端 ReAct 流程测试
+ - Backward compatibility tests / 向后兼容测试
+
+---
+
+## File List / 文件清单
+
+### New Files / 新增文件
+
+```
+openviking/session/
+├── memory_extractor_v2.py # New memory extractor (replaces existing) / 新的记忆提取器(替换现有)
+
+openviking/session/memory/
+├── memory_data.py # Core data structures / 核心数据结构
+├── memory_operations.py # Three operation definitions (LLM final output) / 三种操作定义(模型最终输出)
+├── memory_react.py # ReAct orchestrator / ReAct 编排器
+├── memory_functions.py # Function call definitions (read/find/ls) / Function call 定义(read/find/ls)
+├── memory_patch.py # Patch handler / Patch 处理器
+├── memory_types.py # Type registry / 类型注册表
+├── memory_updater.py # Patch applier (system execution) / Patch 应用器(系统执行)
+└── schemas/ # Config directory / 配置目录
+ ├── profile.yaml # directory: viking://user/{user_space}/memories
+ ├── preferences.yaml # directory: viking://user/{user_space}/memories/preferences
+ ├── entities.yaml # directory: viking://user/{user_space}/memories/entities
+ ├── events.yaml # directory: viking://user/{user_space}/memories/events
+ ├── cases.yaml # directory: viking://agent/{agent_space}/memories/cases
+ ├── patterns.yaml # directory: viking://agent/{agent_space}/memories/patterns
+ ├── tools.yaml # directory: viking://agent/{agent_space}/memories/tools
+ └── skills.yaml # directory: viking://agent/{agent_space}/memories/skills
+
+tests/session/memory/
+├── test_memory_data.py
+├── test_memory_operations.py
+├── test_memory_react.py
+├── test_memory_patch.py
+├── test_memory_types.py
+└── test_memory_updater.py
+```
+
+### Preserved Files / 保留文件
+
+```
+openviking/session/memory_extractor.py # Preserve existing version, do not modify / 保留现有版本,不修改
+```
+
+---
+
+## ReAct Flow Details / ReAct 流程详细说明
+
+### Phase 0: Pre-fetch (Pre-fetch - System Execution / 前置读取 - 系统执行)
+
+**Purpose** / **目的**: Avoid excessive time from multiple ReAct rounds / 避免多次 ReAct 导致耗时过长
+
+**System automatically executes** / **系统自动执行**:
+1. **ls**: Get all memory directory structures / 获取所有记忆目录结构
+ - `viking://user/{user_space}/memories/` and subdirectories / 及子目录
+ - `viking://agent/{agent_space}/memories/` and subdirectories / 及子目录
+2. **read**: Read all `.abstract.md` (L0) and `.overview.md` (L1) / 读取所有 `.abstract.md` (L0) 和 `.overview.md` (L1)
+3. **search**: Perform one semantic search in all directories (using current conversation as query) / 在所有目录执行一次语义搜索(使用当前对话作为查询)
+
+**Output** / **输出**: Pre-fetched Context (directory structure + L0/L1 summaries + search results) / Pre-fetched Context(目录结构 + L0/L1 摘要 + 搜索结果)
+
+### Phase 1: Reasoning + Action (Reasoning + Action / 推理 + 行动)
+
+**Input** / **输入**: Conversation history + Pre-fetched Context / 对话历史 + Pre-fetched Context
+
+**LLM Task** / **LLM 任务**: Analyze conversation + Pre-fetched Context, identify memories that need changes + decide if additional reads are needed / 分析对话 + Pre-fetched Context,识别需要变更的记忆 + 决定是否需要额外读取
+
+**Output** / **输出**: ReasoningAction (reasoning + optional additional actions) / ReasoningAction(reasoning + 可选的额外 actions)
+- reasoning: List of memories that need changes (write/edit/delete) / 需要变更的记忆列表(write/edit/delete)
+- actions: List of additional read operations (only execute when needed, e.g., read specific L2 content) / 额外的读取操作列表(仅在需要时执行,如读取具体 L2 内容)
+
+**System Execution** / **系统执行**: Execute additional read operations in actions (if needed) / 执行 actions 中的额外读取操作(如需要)
+
+### Phase 2: Generate Operations (Generate Final Operations / 生成最终操作)
+
+**Input** / **输入**: Conversation history + Reasoning + read existing memories / 对话历史 + Reasoning + 读取的现有记忆
+
+**LLM Task** / **LLM 任务**: Generate specific operations based on existing memories / 基于现有记忆生成具体的操作
+
+**Output** / **输出**: MemoryOperations (model final output) / MemoryOperations(模型最终输出)
+
+**Important** / **重要**: This is the model's final output, directly executed by system, no more function calls / 这是模型的最后输出,直接由系统执行,不再通过 function call
+
+### Phase 3: System Execute (System Execution / 系统执行)
+
+**Input** / **输入**: MemoryOperations
+
+**Execution** / **执行**: MemoryUpdater.apply_operations() directly applies patch, writes to OpenViking Storage / MemoryUpdater.apply_operations() 直接应用 patch,写入 OpenViking Storage
+
+---
+
+## Summary / 总结
+
+This design is based on practices from ../memory project, uses ReAct pattern: / 本设计基于 ../memory 项目的实践,采用 ReAct 模式:
+- ✅ Removed aggregation operators (not considered for now) / 移除了聚合算子(先不考虑)
+- ✅ Adopt write/edit/delete three-operation Schema / 采用 write/edit/delete 三种操作 Schema
+- ✅ Adopt RoocodePatch style dual-mode Patch (replace + patch) / 采用 RoocodePatch 风格的双模式 Patch(replace + patch)
+- ✅ **Dual-mode design** / **双模式设计**:
+ - Simple mode: no content_template, only name + content fields / 简单模式:无 content_template,只有 name + content 字段
+ - Template mode: with content_template, supports multiple structured fields + MEMORY_FIELDS comment / 模板模式:有 content_template,支持多个结构化字段 + MEMORY_FIELDS 注释
+- ✅ **Pre-fetch Optimization** / **前置读取优化**:
+ - Phase 0: System automatically executes before LLM reasoning / 阶段 0: 系统在 LLM 推理前自动执行
+ - ls: Get all memory directory structures / ls: 获取所有记忆目录结构
+ - read: Read all .abstract.md (L0) and .overview.md (L1) / read: 读取所有 .abstract.md (L0) 和 .overview.md (L1)
+ - search: Perform one semantic search in all directories / search: 在所有目录执行一次语义搜索
+ - Purpose: Avoid excessive time from multiple ReAct rounds / 目的:避免多次 ReAct 导致耗时过长
+- ✅ **ReAct (Reasoning + Action) 3+1 phase flow** / **ReAct (Reasoning + Action) 3+1 阶段流程**:
+ 0. Pre-fetch: System automatically pre-fetches directories, L0/L1, search results / Pre-fetch: 系统自动前置读取目录、L0/L1、搜索结果
+ 1. Reasoning + Action: LLM outputs reasoning (memories that need changes) and actions (optional additional reads) based on pre-fetched context / LLM 基于 pre-fetched context 输出 reasoning(需要变更的记忆)和 actions(可选的额外读取)
+ 2. Generate Operations: Generate final MemoryOperations based on existing memories / 基于现有记忆生成最终的 MemoryOperations
+ 3. System Execute: System directly executes MemoryOperations (no more function calls) / 系统直接执行 MemoryOperations(不再通过 function call)
+- ✅ Adopt semantic filenames, fully utilize navigation value of filenames / 采用语义化文件名,充分利用文件名的导航价值
+- ✅ Learn from commercial memory library implementations, adopt patch incremental update mechanism, reduce LLM call count / 借鉴商业化记忆库的实现,采用 patch 增量更新机制,减少 LLM 调用次数
+- ✅ Fully compatible with OpenViking existing storage structure / 完全兼容 OpenViking 现有存储结构
diff --git a/docs/design/openclaw-integration.md b/docs/design/openclaw-integration.md
index 9725f7ee7..a77892633 100644
--- a/docs/design/openclaw-integration.md
+++ b/docs/design/openclaw-integration.md
@@ -32,6 +32,47 @@ This proposal discusses the extension mechanism for integrating OpenClaw Context
Compact is typically triggered by /new or when messages reach a certain length. Messages that don't reach the length threshold won't trigger memory extraction. A timeout-based extraction mechanism can be added in the future (not needed currently).
+### Two-Threshold Compact Upload Mechanism / 双阈值 Compact 上报机制
+
+为了平衡记忆同步的实时性和用户体验,采用双阈值的非阻塞上报机制:
+
+**Threshold 1: Early Upload (e.g., 50% of context window) / 阈值 1:提前上报(如上下文窗口的 50%)**
+- **Trigger Condition / 触发条件**: When session reaches ~50% of context window limit / 当会话达到上下文窗口限制的约 50% 时
+- **Action / 行为**:
+ - Trigger memory upload to OpenViking in background / 后台触发记忆上报到 OpenViking
+ - **DO NOT block the main flow / 不阻塞主流程**
+ - **DO NOT clear session messages / 不清空会话消息**
+ - Record the range of messages being uploaded (start_index, end_index) / 记录正在上报的消息范围(start_index, end_index)
+ - Store upload state (upload_id, status, message_range) in session metadata / 在会话元数据中存储上报状态(upload_id, status, message_range)
+
+**Threshold 2: Force Cleanup (e.g., 70% of context window) / 阈值 2:强制清理(如上下文窗口的 70%)**
+- **Trigger Condition / 触发条件**: When session reaches ~70% of context window limit / 当会话达到上下文窗口限制的约 70% 时
+- **Action / 行为**:
+ - **Always clear the messages marked for upload** / 总是清理标记为待上报的消息
+ - The upload will continue in background, messages are already in memory buffer / 上报将在后台继续,消息已在内存缓冲区中
+ - Keep the newer messages that arrived after upload started / 保留上报开始后到达的新消息
+
+**Cleanup After Upload Completion (Before Threshold 2) / 上报完成后的清理(阈值 2 前)**
+- **Trigger Condition / 触发条件**: Upload to OpenViking has completed and session hasn't reached Threshold 2 / 上报到 OpenViking 已完成且会话未达到阈值 2
+- **Action / 行为**:
+ - Clear only the messages that were uploaded (from message_range) / 只清理已上报的消息(从 message_range)
+ - Keep the newer messages that arrived after upload started / 保留上报开始后到达的新消息
+
+**Compact Hook Integration / Compact Hook 集成**
+- In each compact hook (before message processing) / 在每次 compact hook 中(消息处理前):
+ 1. Check session size against thresholds / 检查会话大小是否达到阈值
+ 2. If Threshold 1 reached and no ongoing upload: trigger background upload / 如果达到阈值 1 且无正在进行的上报:触发后台上报
+ 3. If Threshold 2 reached: force cleanup marked messages / 如果达到阈值 2:强制清理标记的消息
+ 4. If any upload has completed and below Threshold 2: cleanup those messages / 如果有上报完成且在阈值 2 以下:清理那些消息
+
+
+**Benefits / 优势**:
+- Non-blocking: User never waits for memory extraction / 非阻塞:用户永远不需要等待记忆提取
+- Progressive: Memory is uploaded early, reduces final compact work / 渐进式:记忆提前上报,减少最终 compact 的工作量
+- Safe: Messages only cleared after upload confirmation when possible / 安全:尽可能在上报确认后清理消息
+- Guaranteed: At Threshold 2, messages are cleared even if upload not complete / 保证:在阈值 2 时,即使上报未完成也清理消息
+- Backward compatible: Works with existing compact flow / 向后兼容:与现有 compact 流程兼容
+
---
### Active Memory (Tool-based) / 主动记忆(基于工具)(可选)
diff --git a/examples/ov.conf.example b/examples/ov.conf.example
index 5b837b8db..f9c18010c 100644
--- a/examples/ov.conf.example
+++ b/examples/ov.conf.example
@@ -86,6 +86,9 @@
"default_search_limit": 3,
"enable_memory_decay": true,
"memory_decay_check_interval": 3600,
+ "memory": {
+ "version": "v1"
+ },
"log": {
"level": "INFO",
"format": "%(asctime)s - %(name)s - %(levelname)s - %(message)s",
diff --git a/openviking/models/vlm/backends/litellm_vlm.py b/openviking/models/vlm/backends/litellm_vlm.py
index 90230987b..f868b8626 100644
--- a/openviking/models/vlm/backends/litellm_vlm.py
+++ b/openviking/models/vlm/backends/litellm_vlm.py
@@ -2,6 +2,7 @@
# SPDX-License-Identifier: Apache-2.0
"""LiteLLM VLM Provider implementation with multi-provider support."""
+import json
import logging
import os
@@ -11,12 +12,12 @@ import asyncio
import base64
import time
from pathlib import Path
-from typing import Any, Dict, List, Union
+from typing import Any, Dict, List, Optional, Union
import litellm
from litellm import acompletion, completion
-from ..base import VLMBase
+from ..base import VLMBase, VLMResponse, ToolCall
logger = logging.getLogger(__name__)
@@ -195,7 +196,7 @@ class LiteLLMVLMProvider(VLMBase):
else:
return {"type": "image_url", "image_url": {"url": image}}
- def _build_kwargs(self, model: str, messages: list) -> dict[str, Any]:
+ def _build_kwargs(self, model: str, messages: list, tools: Optional[List[Dict[str, Any]]] = None, tool_choice: Optional[str] = None) -> dict[str, Any]:
"""Build kwargs for LiteLLM call."""
kwargs: dict[str, Any] = {
"model": model,
@@ -218,28 +219,94 @@ class LiteLLMVLMProvider(VLMBase):
kwargs["api_base"] = self.api_base
if self._extra_headers:
kwargs["extra_headers"] = self._extra_headers
+ if tools:
+ kwargs["tools"] = tools
+ kwargs["tool_choice"] = tool_choice or "auto"
return kwargs
- def get_completion(self, prompt: str, thinking: bool = False) -> str:
+ def _parse_tool_calls(self, message) -> List[ToolCall]:
+ """Parse tool calls from LiteLLM response message."""
+ tool_calls = []
+ if hasattr(message, "tool_calls") and message.tool_calls:
+ for tc in message.tool_calls:
+ args = tc.function.arguments
+ if isinstance(args, str):
+ try:
+ args = json.loads(args)
+ except json.JSONDecodeError:
+ args = {"raw": args}
+ tool_calls.append(ToolCall(
+ id=tc.id,
+ name=tc.function.name,
+ arguments=args
+ ))
+ return tool_calls
+
+ def _build_vlm_response(self, response, has_tools: bool) -> Union[str, VLMResponse]:
+ """Build response from LiteLLM response. Returns str or VLMResponse based on has_tools."""
+ choice = response.choices[0]
+ message = choice.message
+
+ if has_tools:
+ usage = {}
+ if hasattr(response, "usage") and response.usage:
+ usage = {
+ "prompt_tokens": response.usage.prompt_tokens,
+ "completion_tokens": response.usage.completion_tokens,
+ "total_tokens": response.usage.total_tokens,
+ "prompt_tokens_details": getattr(response.usage, "prompt_tokens_details", None),
+ }
+
+ return VLMResponse(
+ content=message.content,
+ tool_calls=self._parse_tool_calls(message),
+ finish_reason=choice.finish_reason or "stop",
+ usage=usage,
+ )
+ else:
+ return message.content or ""
+
+ def get_completion(
+ self,
+ prompt: str = "",
+ thinking: bool = False,
+ 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 synchronously."""
model = self._resolve_model(self.model or "gpt-4o-mini")
- messages = [{"role": "user", "content": prompt}]
- kwargs = self._build_kwargs(model, messages)
+ if messages:
+ kwargs_messages = messages
+ else:
+ kwargs_messages = [{"role": "user", "content": prompt}]
+
+ kwargs = self._build_kwargs(model, kwargs_messages, tools, tool_choice)
t0 = time.perf_counter()
response = completion(**kwargs)
elapsed = time.perf_counter() - t0
self._update_token_usage_from_response(response, duration_seconds=elapsed)
- return self._clean_response(self._extract_content_from_response(response))
+ return self._build_vlm_response(response, has_tools=bool(tools))
async def get_completion_async(
- self, prompt: str, thinking: bool = False, max_retries: int = 0
- ) -> str:
+ self,
+ prompt: str = "",
+ thinking: bool = False,
+ max_retries: int = 0,
+ 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."""
model = self._resolve_model(self.model or "gpt-4o-mini")
- messages = [{"role": "user", "content": prompt}]
- kwargs = self._build_kwargs(model, messages)
+ if messages:
+ kwargs_messages = messages
+ else:
+ kwargs_messages = [{"role": "user", "content": prompt}]
+
+ kwargs = self._build_kwargs(model, kwargs_messages, tools, tool_choice)
last_error = None
for attempt in range(max_retries + 1):
@@ -250,7 +317,7 @@ class LiteLLMVLMProvider(VLMBase):
self._update_token_usage_from_response(
response, duration_seconds=elapsed,
)
- return self._clean_response(self._extract_content_from_response(response))
+ return self._build_vlm_response(response, has_tools=bool(tools))
except Exception as e:
last_error = e
if attempt < max_retries:
@@ -262,49 +329,63 @@ class LiteLLMVLMProvider(VLMBase):
def get_vision_completion(
self,
- prompt: str,
- images: List[Union[str, Path, bytes]],
+ prompt: str = "",
+ images: Optional[List[Union[str, Path, bytes]]] = None,
thinking: bool = False,
- ) -> str:
+ tools: Optional[List[Dict[str, Any]]] = None,
+ messages: Optional[List[Dict[str, Any]]] = None,
+ ) -> Union[str, VLMResponse]:
"""Get vision completion synchronously."""
model = self._resolve_model(self.model or "gpt-4o-mini")
- content = []
- for img in images:
- content.append(self._prepare_image(img))
- content.append({"type": "text", "text": prompt})
+ if messages:
+ kwargs_messages = messages
+ else:
+ content = []
+ if images:
+ for img in images:
+ content.append(self._prepare_image(img))
+ if prompt:
+ content.append({"type": "text", "text": prompt})
+ kwargs_messages = [{"role": "user", "content": content}]
- messages = [{"role": "user", "content": content}]
- kwargs = self._build_kwargs(model, messages)
+ kwargs = self._build_kwargs(model, kwargs_messages, tools)
t0 = time.perf_counter()
response = completion(**kwargs)
elapsed = time.perf_counter() - t0
self._update_token_usage_from_response(response, duration_seconds=elapsed)
- return self._clean_response(self._extract_content_from_response(response))
+ return self._build_vlm_response(response, has_tools=bool(tools))
async def get_vision_completion_async(
self,
- prompt: str,
- images: List[Union[str, Path, bytes]],
+ prompt: str = "",
+ images: Optional[List[Union[str, Path, bytes]]] = None,
thinking: bool = False,
- ) -> str:
+ tools: Optional[List[Dict[str, Any]]] = None,
+ messages: Optional[List[Dict[str, Any]]] = None,
+ ) -> Union[str, VLMResponse]:
"""Get vision completion asynchronously."""
model = self._resolve_model(self.model or "gpt-4o-mini")
- content = []
- for img in images:
- content.append(self._prepare_image(img))
- content.append({"type": "text", "text": prompt})
+ if messages:
+ kwargs_messages = messages
+ else:
+ content = []
+ if images:
+ for img in images:
+ content.append(self._prepare_image(img))
+ if prompt:
+ content.append({"type": "text", "text": prompt})
+ kwargs_messages = [{"role": "user", "content": content}]
- messages = [{"role": "user", "content": content}]
- kwargs = self._build_kwargs(model, messages)
+ kwargs = self._build_kwargs(model, kwargs_messages, tools)
t0 = time.perf_counter()
response = await acompletion(**kwargs)
elapsed = time.perf_counter() - t0
self._update_token_usage_from_response(response, duration_seconds=elapsed)
- return self._clean_response(self._extract_content_from_response(response))
+ return self._build_vlm_response(response, has_tools=bool(tools))
def _update_token_usage_from_response(
self, response, duration_seconds: float = 0.0,
diff --git a/openviking/models/vlm/backends/openai_vlm.py b/openviking/models/vlm/backends/openai_vlm.py
index 16d6948fa..fdf35f025 100644
--- a/openviking/models/vlm/backends/openai_vlm.py
+++ b/openviking/models/vlm/backends/openai_vlm.py
@@ -4,12 +4,13 @@
import asyncio
import base64
+import json
import logging
import time
from pathlib import Path
-from typing import Any, Dict, List, Union
+from typing import Any, Dict, List, Optional, Union
-from ..base import VLMBase
+from ..base import VLMBase, VLMResponse, ToolCall
from ..registry import DEFAULT_AZURE_API_VERSION
logger = logging.getLogger(__name__)
@@ -96,6 +97,48 @@ class OpenAIVLM(VLMBase):
)
return
+ def _parse_tool_calls(self, message) -> List[ToolCall]:
+ """Parse tool calls from OpenAI response message."""
+ tool_calls = []
+ if hasattr(message, "tool_calls") and message.tool_calls:
+ for tc in message.tool_calls:
+ args = tc.function.arguments
+ if isinstance(args, str):
+ try:
+ args = json.loads(args)
+ except json.JSONDecodeError:
+ args = {"raw": args}
+ tool_calls.append(ToolCall(
+ id=tc.id,
+ name=tc.function.name,
+ arguments=args
+ ))
+ return tool_calls
+
+ def _build_vlm_response(self, response, has_tools: bool) -> Union[str, VLMResponse]:
+ """Build response from OpenAI response. Returns str or VLMResponse based on has_tools."""
+ choice = response.choices[0]
+ message = choice.message
+
+ if has_tools:
+ usage = {}
+ if hasattr(response, "usage") and response.usage:
+ usage = {
+ "prompt_tokens": response.usage.prompt_tokens,
+ "completion_tokens": response.usage.completion_tokens,
+ "total_tokens": response.usage.total_tokens,
+ "prompt_tokens_details": getattr(response.usage, "prompt_tokens_details", None),
+ }
+
+ return VLMResponse(
+ content=message.content,
+ tool_calls=self._parse_tool_calls(message),
+ finish_reason=choice.finish_reason or "stop",
+ usage=usage,
+ )
+ else:
+ return message.content or ""
+
def _extract_from_chunk(self, chunk):
"""Extract content and usage from a single chunk.
@@ -183,22 +226,42 @@ class OpenAIVLM(VLMBase):
return "".join(content_parts)
- def get_completion(self, prompt: str, thinking: bool = False) -> str:
+ def get_completion(
+ self,
+ prompt: str = "",
+ thinking: bool = False,
+ 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"""
client = self.get_client()
+ if messages:
+ kwargs_messages = messages
+ else:
+ kwargs_messages = [{"role": "user", "content": prompt}]
+
kwargs = {
"model": self.model or "gpt-4o-mini",
- "messages": [{"role": "user", "content": prompt}],
+ "messages": kwargs_messages,
"temperature": self.temperature,
"stream": self.stream,
}
if self.max_tokens is not None:
kwargs["max_tokens"] = self.max_tokens
+ if tools:
+ kwargs["tools"] = tools
+ kwargs["tool_choice"] = tool_choice or "auto"
+
t0 = time.perf_counter()
response = client.chat.completions.create(**kwargs)
elapsed = time.perf_counter() - t0
+ if tools:
+ self._update_token_usage_from_response(response)
+ return self._build_vlm_response(response, has_tools=bool(tools))
+
if self.stream:
content = self._process_streaming_response(response)
else:
@@ -208,19 +271,34 @@ class OpenAIVLM(VLMBase):
return self._clean_response(content)
async def get_completion_async(
- self, prompt: str, thinking: bool = False, max_retries: int = 0
- ) -> str:
+ self,
+ prompt: str = "",
+ thinking: bool = False,
+ max_retries: int = 0,
+ 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"""
client = self.get_async_client()
+ if messages:
+ kwargs_messages = messages
+ else:
+ kwargs_messages = [{"role": "user", "content": prompt}]
+
kwargs = {
"model": self.model or "gpt-4o-mini",
- "messages": [{"role": "user", "content": prompt}],
+ "messages": kwargs_messages,
"temperature": self.temperature,
"stream": self.stream,
}
if self.max_tokens is not None:
kwargs["max_tokens"] = self.max_tokens
+ if tools:
+ kwargs["tools"] = tools
+ kwargs["tool_choice"] = tool_choice or "auto"
+
last_error = None
for attempt in range(max_retries + 1):
try:
@@ -228,6 +306,10 @@ class OpenAIVLM(VLMBase):
response = await client.chat.completions.create(**kwargs)
elapsed = time.perf_counter() - t0
+ if tools:
+ self._update_token_usage_from_response(response)
+ return self._build_vlm_response(response, has_tools=bool(tools))
+
if self.stream:
content = await self._process_streaming_response_async(response)
else:
@@ -301,31 +383,47 @@ class OpenAIVLM(VLMBase):
def get_vision_completion(
self,
- prompt: str,
- images: List[Union[str, Path, bytes]],
+ prompt: str = "",
+ images: Optional[List[Union[str, Path, bytes]]] = None,
thinking: bool = False,
- ) -> str:
+ tools: Optional[List[Dict[str, Any]]] = None,
+ messages: Optional[List[Dict[str, Any]]] = None,
+ ) -> Union[str, VLMResponse]:
"""Get vision completion"""
client = self.get_client()
- content = []
- for img in images:
- content.append(self._prepare_image(img))
- content.append({"type": "text", "text": prompt})
+ if messages:
+ kwargs_messages = messages
+ else:
+ content = []
+ if images:
+ for img in images:
+ content.append(self._prepare_image(img))
+ if prompt:
+ content.append({"type": "text", "text": prompt})
+ kwargs_messages = [{"role": "user", "content": content}]
kwargs = {
"model": self.model or "gpt-4o-mini",
- "messages": [{"role": "user", "content": content}],
+ "messages": kwargs_messages,
"temperature": self.temperature,
"stream": self.stream,
}
if self.max_tokens is not None:
kwargs["max_tokens"] = self.max_tokens
+ if tools:
+ kwargs["tools"] = tools
+ kwargs["tool_choice"] = "auto"
+
t0 = time.perf_counter()
response = client.chat.completions.create(**kwargs)
elapsed = time.perf_counter() - t0
+ if tools:
+ self._update_token_usage_from_response(response)
+ return self._build_vlm_response(response, has_tools=bool(tools))
+
if self.stream:
content = self._process_streaming_response(response)
else:
@@ -336,35 +434,51 @@ class OpenAIVLM(VLMBase):
async def get_vision_completion_async(
self,
- prompt: str,
- images: List[Union[str, Path, bytes]],
+ prompt: str = "",
+ images: Optional[List[Union[str, Path, bytes]]] = None,
thinking: bool = False,
- ) -> str:
+ tools: Optional[List[Dict[str, Any]]] = None,
+ messages: Optional[List[Dict[str, Any]]] = None,
+ ) -> Union[str, VLMResponse]:
"""Get vision completion asynchronously"""
client = self.get_async_client()
- content = []
- for img in images:
- content.append(self._prepare_image(img))
- content.append({"type": "text", "text": prompt})
+ if messages:
+ kwargs_messages = messages
+ else:
+ content = []
+ if images:
+ for img in images:
+ content.append(self._prepare_image(img))
+ if prompt:
+ content.append({"type": "text", "text": prompt})
+ kwargs_messages = [{"role": "user", "content": content}]
kwargs = {
"model": self.model or "gpt-4o-mini",
- "messages": [{"role": "user", "content": content}],
+ "messages": kwargs_messages,
"temperature": self.temperature,
"stream": self.stream,
}
if self.max_tokens is not None:
kwargs["max_tokens"] = self.max_tokens
+ if tools:
+ kwargs["tools"] = tools
+ kwargs["tool_choice"] = "auto"
+
t0 = time.perf_counter()
response = await client.chat.completions.create(**kwargs)
elapsed = time.perf_counter() - t0
+ if tools:
+ self._update_token_usage_from_response(response)
+ return self._build_vlm_response(response, has_tools=bool(tools))
+
if self.stream:
content = await self._process_streaming_response_async(response)
else:
self._update_token_usage_from_response(response, duration_seconds=elapsed)
content = self._extract_content_from_response(response)
- return self._clean_response(content)
+ return self._clean_response(content)
\ No newline at end of file
diff --git a/openviking/models/vlm/backends/volcengine_vlm.py b/openviking/models/vlm/backends/volcengine_vlm.py
index 0c9c558ae..63c8abfc5 100644
--- a/openviking/models/vlm/backends/volcengine_vlm.py
+++ b/openviking/models/vlm/backends/volcengine_vlm.py
@@ -4,12 +4,14 @@
import asyncio
import base64
+import json
import logging
import time
from pathlib import Path
-from typing import Any, Dict, List, Union
+from typing import Any, Dict, List, Optional, Union
from .openai_vlm import OpenAIVLM
+from ..base import VLMResponse, ToolCall
logger = logging.getLogger(__name__)
@@ -60,38 +62,111 @@ class VolcEngineVLM(OpenAIVLM):
)
return self._async_client
- def get_completion(self, prompt: str, thinking: bool = False) -> str:
+ def _parse_tool_calls(self, message) -> List[ToolCall]:
+ """Parse tool calls from VolcEngine response message."""
+ tool_calls = []
+ if hasattr(message, "tool_calls") and message.tool_calls:
+ for tc in message.tool_calls:
+ args = tc.function.arguments
+ if isinstance(args, str):
+ try:
+ args = json.loads(args)
+ except json.JSONDecodeError:
+ args = {"raw": args}
+ tool_calls.append(ToolCall(
+ id=tc.id,
+ name=tc.function.name,
+ arguments=args
+ ))
+ return tool_calls
+
+ def _build_vlm_response(self, response, has_tools: bool) -> Union[str, VLMResponse]:
+ """Build response from VolcEngine response. Returns str or VLMResponse based on has_tools."""
+ choice = response.choices[0]
+ message = choice.message
+
+ if has_tools:
+ usage = {}
+ if hasattr(response, "usage") and response.usage:
+ usage = {
+ "prompt_tokens": response.usage.prompt_tokens,
+ "completion_tokens": response.usage.completion_tokens,
+ "total_tokens": response.usage.total_tokens,
+ "prompt_tokens_details": getattr(response.usage, "prompt_tokens_details", None),
+ }
+
+ return VLMResponse(
+ content=message.content,
+ tool_calls=self._parse_tool_calls(message),
+ finish_reason=choice.finish_reason or "stop",
+ usage=usage,
+ )
+ else:
+ return message.content or ""
+
+ def get_completion(
+ self,
+ prompt: str = "",
+ thinking: bool = False,
+ 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"""
client = self.get_client()
+ if messages:
+ kwargs_messages = messages
+ else:
+ kwargs_messages = [{"role": "user", "content": prompt}]
+
kwargs = {
"model": self.model or "doubao-seed-2-0-pro-260215",
- "messages": [{"role": "user", "content": prompt}],
+ "messages": kwargs_messages,
"temperature": self.temperature,
"thinking": {"type": "disabled" if not thinking else "enabled"},
}
if self.max_tokens is not None:
kwargs["max_tokens"] = self.max_tokens
+ if tools:
+ kwargs["tools"] = tools
+ kwargs["tool_choice"] = tool_choice or "auto"
+
t0 = time.perf_counter()
response = client.chat.completions.create(**kwargs)
elapsed = time.perf_counter() - t0
self._update_token_usage_from_response(response, duration_seconds=elapsed)
- return self._clean_response(self._extract_content_from_response(response))
+ return self._build_vlm_response(response, has_tools=bool(tools))
async def get_completion_async(
- self, prompt: str, thinking: bool = False, max_retries: int = 0
- ) -> str:
+ self,
+ prompt: str = "",
+ thinking: bool = False,
+ max_retries: int = 0,
+ 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"""
client = self.get_async_client()
+ if messages:
+ kwargs_messages = messages
+ else:
+ kwargs_messages = [{"role": "user", "content": prompt}]
+
kwargs = {
"model": self.model or "doubao-seed-2-0-pro-260215",
- "messages": [{"role": "user", "content": prompt}],
+ "messages": kwargs_messages,
"temperature": self.temperature,
"thinking": {"type": "disabled" if not thinking else "enabled"},
}
if self.max_tokens is not None:
kwargs["max_tokens"] = self.max_tokens
+ if tools:
+ kwargs["tools"] = tools
+ kwargs["tool_choice"] = tool_choice or "auto"
+
last_error = None
for attempt in range(max_retries + 1):
try:
@@ -101,7 +176,7 @@ class VolcEngineVLM(OpenAIVLM):
self._update_token_usage_from_response(
response, duration_seconds=elapsed,
)
- return self._clean_response(self._extract_content_from_response(response))
+ return self._build_vlm_response(response, has_tools=bool(tools))
except Exception as e:
last_error = e
if attempt < max_retries:
@@ -228,58 +303,82 @@ class VolcEngineVLM(OpenAIVLM):
def get_vision_completion(
self,
- prompt: str,
- images: List[Union[str, Path, bytes]],
+ prompt: str = "",
+ images: Optional[List[Union[str, Path, bytes]]] = None,
thinking: bool = False,
- ) -> str:
+ tools: Optional[List[Dict[str, Any]]] = None,
+ messages: Optional[List[Dict[str, Any]]] = None,
+ ) -> Union[str, VLMResponse]:
"""Get vision completion"""
client = self.get_client()
- content = []
- for img in images:
- content.append(self._prepare_image(img))
- content.append({"type": "text", "text": prompt})
+ if messages:
+ kwargs_messages = messages
+ else:
+ content = []
+ if images:
+ for img in images:
+ content.append(self._prepare_image(img))
+ if prompt:
+ content.append({"type": "text", "text": prompt})
+ kwargs_messages = [{"role": "user", "content": content}]
kwargs = {
"model": self.model or "doubao-seed-2-0-pro-260215",
- "messages": [{"role": "user", "content": content}],
+ "messages": kwargs_messages,
"temperature": self.temperature,
"thinking": {"type": "disabled" if not thinking else "enabled"},
}
if self.max_tokens is not None:
kwargs["max_tokens"] = self.max_tokens
+ if tools:
+ kwargs["tools"] = tools
+ kwargs["tool_choice"] = "auto"
+
t0 = time.perf_counter()
response = client.chat.completions.create(**kwargs)
elapsed = time.perf_counter() - t0
self._update_token_usage_from_response(response, duration_seconds=elapsed)
- return self._clean_response(self._extract_content_from_response(response))
+ return self._build_vlm_response(response, has_tools=bool(tools))
async def get_vision_completion_async(
self,
- prompt: str,
- images: List[Union[str, Path, bytes]],
+ prompt: str = "",
+ images: Optional[List[Union[str, Path, bytes]]] = None,
thinking: bool = False,
- ) -> str:
+ tools: Optional[List[Dict[str, Any]]] = None,
+ messages: Optional[List[Dict[str, Any]]] = None,
+ ) -> Union[str, VLMResponse]:
"""Get vision completion asynchronously"""
client = self.get_async_client()
- content = []
- for img in images:
- content.append(self._prepare_image(img))
- content.append({"type": "text", "text": prompt})
+ if messages:
+ kwargs_messages = messages
+ else:
+ content = []
+ if images:
+ for img in images:
+ content.append(self._prepare_image(img))
+ if prompt:
+ content.append({"type": "text", "text": prompt})
+ kwargs_messages = [{"role": "user", "content": content}]
kwargs = {
"model": self.model or "doubao-seed-2-0-pro-260215",
- "messages": [{"role": "user", "content": content}],
+ "messages": kwargs_messages,
"temperature": self.temperature,
"thinking": {"type": "disabled" if not thinking else "enabled"},
}
if self.max_tokens is not None:
kwargs["max_tokens"] = self.max_tokens
+ if tools:
+ kwargs["tools"] = tools
+ kwargs["tool_choice"] = "auto"
+
t0 = time.perf_counter()
response = await client.chat.completions.create(**kwargs)
elapsed = time.perf_counter() - t0
self._update_token_usage_from_response(response, duration_seconds=elapsed)
- return self._clean_response(self._extract_content_from_response(response))
+ return self._build_vlm_response(response, has_tools=bool(tools))
diff --git a/openviking/models/vlm/base.py b/openviking/models/vlm/base.py
index fd8f939c1..ca237decf 100644
--- a/openviking/models/vlm/base.py
+++ b/openviking/models/vlm/base.py
@@ -4,8 +4,9 @@
import re
from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
from pathlib import Path
-from typing import Any, Dict, List, Union
+from typing import Any, Dict, List, Optional, Union
from openviking.utils.time_utils import format_iso8601
@@ -14,6 +15,35 @@ from .token_usage import TokenUsageTracker
_THINK_TAG_RE = re.compile(r"<think>[\s\S]*?</think>")
+@dataclass
+class ToolCall:
+ """Single tool call from LLM."""
+
+ id: str
+ name: str
+ arguments: Dict[str, Any]
+
+
+@dataclass
+class VLMResponse:
+ """VLM response that supports both text content and tool calls."""
+
+ content: Optional[str] = None
+ tool_calls: List[ToolCall] = field(default_factory=list)
+ finish_reason: str = "stop" # stop, tool_calls, length, error
+ usage: Dict[str, int] = field(default_factory=dict) # prompt_tokens, completion_tokens, total_tokens
+ reasoning_content: Optional[str] = None # For thinking process (doubao thinking, deepseek r1, etc.)
+
+ @property
+ def has_tool_calls(self) -> bool:
+ """Check if response contains tool calls."""
+ return len(self.tool_calls) > 0
+
+ def __str__(self) -> str:
+ """String representation for backward compatibility - returns content."""
+ return self.content or ""
+
+
class VLMBase(ABC):
"""VLM base abstract class"""
@@ -33,35 +63,101 @@ class VLMBase(ABC):
self._token_tracker = TokenUsageTracker()
@abstractmethod
- def get_completion(self, prompt: str, thinking: bool = False) -> str:
- """Get text completion"""
+ def get_completion(
+ self,
+ prompt: str = "",
+ thinking: bool = False,
+ 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
+
+ Args:
+ prompt: Text prompt (used if messages not provided)
+ thinking: Whether to enable thinking mode
+ tools: Optional list of tool definitions in OpenAI function format
+ tool_choice: Optional tool choice mode ("auto", "none", or specific tool name)
+ messages: Optional list of message dicts (takes precedence over prompt)
+
+ Returns:
+ str if no tools provided, VLMResponse if tools provided
+ """
pass
@abstractmethod
async def get_completion_async(
- self, prompt: str, thinking: bool = False, max_retries: int = 0
- ) -> str:
- """Get text completion asynchronously"""
+ self,
+ prompt: str = "",
+ thinking: bool = False,
+ max_retries: int = 0,
+ 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
+
+ Args:
+ prompt: Text prompt (used if messages not provided)
+ thinking: Whether to enable thinking mode
+ max_retries: Maximum number of retries
+ tools: Optional list of tool definitions in OpenAI function format
+ tool_choice: Optional tool choice mode ("auto", "none", or specific tool name)
+ messages: Optional list of message dicts (takes precedence over prompt)
+
+ Returns:
+ str if no tools provided, VLMResponse if tools provided
+ """
pass
@abstractmethod
def get_vision_completion(
self,
- prompt: str,
- images: List[Union[str, Path, bytes]],
+ prompt: str = "",
+ images: Optional[List[Union[str, Path, bytes]]] = None,
thinking: bool = False,
- ) -> str:
- """Get vision completion"""
+ 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
+
+ Args:
+ prompt: Text prompt (used if messages not provided)
+ images: List of images (used if messages not provided)
+ thinking: Whether to enable thinking mode
+ tools: Optional list of tool definitions in OpenAI function format
+ tool_choice: Optional tool choice mode ("auto", "none", or specific tool name)
+ messages: Optional list of message dicts (takes precedence over prompt/images)
+
+ Returns:
+ str if no tools provided, VLMResponse if tools provided
+ """
pass
@abstractmethod
async def get_vision_completion_async(
self,
- prompt: str,
- images: List[Union[str, Path, bytes]],
+ prompt: str = "",
+ images: Optional[List[Union[str, Path, bytes]]] = None,
thinking: bool = False,
- ) -> str:
- """Get vision completion asynchronously"""
+ 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
+
+ Args:
+ prompt: Text prompt (used if messages not provided)
+ images: List of images (used if messages not provided)
+ thinking: Whether to enable thinking mode
+ tools: Optional list of tool definitions in OpenAI function format
+ tool_choice: Optional tool choice mode ("auto", "none", or specific tool name)
+ messages: Optional list of message dicts (takes precedence over prompt/images)
+
+ Returns:
+ str if no tools provided, VLMResponse if tools provided
+ """
pass
def _clean_response(self, content: str) -> str:
diff --git a/openviking/models/vlm/llm.py b/openviking/models/vlm/llm.py
index 6c8b9c569..f2fc70dd4 100644
--- a/openviking/models/vlm/llm.py
+++ b/openviking/models/vlm/llm.py
@@ -8,7 +8,7 @@ Provides unified structured output handling with response_format support.
import json
import re
-from typing import Any, Dict, Optional, Type, TypeVar
+from typing import Any, Dict, List, Optional, Type, TypeVar, Union
import json_repair
from pydantic import BaseModel
@@ -20,18 +20,25 @@ logger = get_logger(__name__)
T = TypeVar("T", bound=BaseModel)
-def parse_json_from_response(response: str) -> Optional[Any]:
+def parse_json_from_response(response: Union[str, Any]) -> Optional[Any]:
"""
Parse JSON object from LLM text response.
Handles code blocks and plain JSON strings, including fixing common format issues.
Args:
- response (str): LLM text response or JSON string
+ response: LLM text response, JSON string, or VLMResponse object
Returns:
Optional[Any]: Parsed JSON object, None if parsing fails
"""
+ # Handle VLMResponse - extract content
+ if hasattr(response, 'content'):
+ response = response.content
+
+ if response is None:
+ return None
+
if not isinstance(response, str):
return None
@@ -166,29 +173,33 @@ class StructuredVLM:
def complete_json(
self,
- prompt: str,
+ prompt: str = "",
schema: Optional[Dict[str, Any]] = None,
thinking: bool = False,
+ tools: Optional[List[Dict[str, Any]]] = None,
+ messages: Optional[List[Dict[str, Any]]] = None,
) -> Optional[Dict[str, Any]]:
"""Get JSON completion from VLM."""
- if schema:
+ if schema and not messages:
prompt = f"{prompt}\n\n{get_json_schema_prompt(schema)}"
- response = self._get_vlm().get_completion(prompt, thinking)
+ response = self._get_vlm().get_completion(prompt, thinking, tools, messages)
return parse_json_from_response(response)
async def complete_json_async(
self,
- prompt: str,
+ prompt: str = "",
schema: Optional[Dict[str, Any]] = None,
thinking: bool = False,
max_retries: int = 0,
+ tools: Optional[List[Dict[str, Any]]] = None,
+ messages: Optional[List[Dict[str, Any]]] = None,
) -> Optional[Dict[str, Any]]:
"""Async version of complete_json."""
- if schema:
+ if schema and not messages:
prompt = f"{prompt}\n\n{get_json_schema_prompt(schema)}"
- response = await self._get_vlm().get_completion_async(prompt, thinking, max_retries)
+ response = await self._get_vlm().get_completion_async(prompt, thinking, max_retries, tools, messages)
return parse_json_from_response(response)
def complete_model(
@@ -232,18 +243,22 @@ class StructuredVLM:
def get_vision_completion(
self,
- prompt: str,
- images: list,
+ prompt: str = "",
+ images: Optional[list] = None,
thinking: bool = False,
- ) -> str:
+ tools: Optional[List[Dict[str, Any]]] = None,
+ messages: Optional[List[Dict[str, Any]]] = None,
+ ) -> Union[str, Any]:
"""Get vision completion."""
- return self._get_vlm().get_vision_completion(prompt, images, thinking)
+ return self._get_vlm().get_vision_completion(prompt, images, thinking, tools, messages)
async def get_vision_completion_async(
self,
- prompt: str,
- images: list,
+ prompt: str = "",
+ images: Optional[list] = None,
thinking: bool = False,
- ) -> str:
+ tools: Optional[List[Dict[str, Any]]] = None,
+ messages: Optional[List[Dict[str, Any]]] = None,
+ ) -> Union[str, Any]:
"""Async vision completion."""
- return await self._get_vlm().get_vision_completion_async(prompt, images, thinking)
+ return await self._get_vlm().get_vision_completion_async(prompt, images, thinking, tools, messages)
diff --git a/openviking/prompts/templates/memory/cases.yaml b/openviking/prompts/templates/memory/cases.yaml
new file mode 100644
index 000000000..2831da6b0
--- /dev/null
+++ b/openviking/prompts/templates/memory/cases.yaml
@@ -0,0 +1,41 @@
+memory_type: cases
+description: |
+ Case memory - captures "what problem was encountered and how it was solved".
+ Extract specific problem-solution pairs from the conversation that are worth remembering for future reference.
+ Cases should be about specific problems that have clear solutions.
+ Each case should include: what the problem was (symptoms, error messages, context), what the solution was (steps taken, principles used), and why it worked.
+ Case names should be in "Problem → Solution" format to make them easily searchable.
+directory: "viking://agent/{agent_space}/memories/cases"
+filename_template: "{case_name}.md"
+enabled: true
+fields:
+ - name: case_name
+ type: string
+ description: |
+ Case name used to uniquely identify this case memory.
+ Should be in "Problem → Solution" format such as "Band not recognized → Request member/album/style details", "Memory merge timeout → Split into smaller chunks", etc.
+ Example: "[Problem] → [Solution]"
+ merge_op: immutable
+
+ - name: problem
+ type: string
+ description: |
+ Problem description specifically detailing what problem was encountered.
+ Includes: error messages, symptoms, context, and other specific details.
+ Example: "User feedback that a band cannot be recognized by system."
+ merge_op: patch
+
+ - name: solution
+ type: string
+ description: |
+ Solution description detailing how to solve this problem.
+ Includes: solution method, steps, principles, etc.
+ Example: "Request user to provide more identification details: band member names, representative album names, music style, etc. This information can improve recognition accuracy."
+ merge_op: patch
+
+ - name: content
+ type: string
+ description: |
+ Complete case content including full narrative of problem and solution.
+ Example: "User feedback mentioned a band that the system could not recognize. Solution is to request user to provide more identification details: band member names, representative album names, music style, etc. This information can improve recognition accuracy."
+ merge_op: patch
diff --git a/openviking/prompts/templates/memory/entities.yaml b/openviking/prompts/templates/memory/entities.yaml
new file mode 100644
index 000000000..7065c5459
--- /dev/null
+++ b/openviking/prompts/templates/memory/entities.yaml
@@ -0,0 +1,44 @@
+memory_type: entities
+description: |
+ Entity memory - manages knowledge using Zettelkasten method.
+ Each card represents an entity with relative path links to other cards.
+ Relative path format: ../entities/entity_name.md
+ - Example: [skin_itching](../entities/skin_itching.md) → see dermatologist
+ - Cards should be rich and distributed - avoid putting all info in one card.
+directory: "viking://user/{user_space}/memories/entities"
+filename_template: "{name}.md"
+enabled: true
+
+fields:
+ - name: name
+ type: string
+ description: |
+ # Content
+ - Entity card name in English, lowercase with underscores, max 3 words
+
+ # Format Requirements
+ ## Entity Cards
+ - In triage scenarios, each card represents a department or symptom
+ - Entities should be as granular as possible - split combined symptoms into individual entities
+
+ ### Good Examples
+ emergency_department
+ cough_symptom
+ daily_20260110
+
+ ### Bad Examples
+ progressive_memory_loss_with_personality_change // Too long, max 3 words
+ merge_op: immutable
+
+ - name: content
+ type: string
+ description: |
+ # Content
+ - Detailed Zettelkasten card content in markdown format
+ - Use standard markdown links to connect cards:
+ [emergency_department](../entities/{name})
+ [fever](../entities/{name})
+
+ - One card per topic, link to related cards; if content is too long, create new cards
+ - If retrieved content is related to current card, update content to establish connections
+ merge_op: patch
diff --git a/openviking/prompts/templates/memory/events.yaml b/openviking/prompts/templates/memory/events.yaml
new file mode 100644
index 000000000..8e1b04c9f
--- /dev/null
+++ b/openviking/prompts/templates/memory/events.yaml
@@ -0,0 +1,30 @@
+memory_type: events
+description: |
+ Event memory - captures "what happened, what decision was made, and why".
+ Extract notable events, decisions, milestones, and turning points from the conversation.
+ Events should be things worth remembering for future context: decisions made, agreements reached, milestones achieved, problems solved, etc.
+ Each event should include: what happened, why it happened, what the outcome was, and any relevant context/timeline.
+ Use absolute dates for event_time, not relative time like "today" or "recently".
+directory: "viking://user/{user_space}/memories/events"
+filename_template: "{event_time}_{event_name}.md"
+enabled: true
+fields:
+ - name: event_name
+ type: string
+ description: |
+ Event name in Chinese or English. If English, use lowercase with underscores, max 3 words.
+ merge_op: immutable
+
+ - name: event_time
+ type: string
+ description: |
+ Time when the event occurred, format “2026-03-17”. If unknown, use current time.
+ merge_op: immutable
+
+ - name: content
+ type: string
+ description: |
+ Event content in Markdown format, describing “what happened”.
+ Includes: decision content, reasons, outcomes, context, timeline, etc.
+ Example: “In memory system design discussion, found original 6 category boundaries were unclear. Especially status, lessons learned, and insights often overlapped, making them difficult to distinguish. Decided to refactor to 5 categories, removing these three to make boundaries clearer.”
+ merge_op: patch
diff --git a/openviking/prompts/templates/memory/patterns.yaml b/openviking/prompts/templates/memory/patterns.yaml
new file mode 100644
index 000000000..0232f1ae2
--- /dev/null
+++ b/openviking/prompts/templates/memory/patterns.yaml
@@ -0,0 +1,32 @@
+memory_type: patterns
+description: |
+ Pattern memory - captures "under what circumstances to follow what process".
+ Extract reusable workflows, processes, and methods that the agent should follow in similar future situations.
+ Patterns should be about: how to approach certain types of tasks, what steps to follow, what considerations to keep in mind.
+ Each pattern should include: trigger conditions (when to use this pattern), process steps (what to do), and considerations (what to watch out for).
+ Pattern names should be in "Process name: Step description" format.
+directory: "viking://agent/{agent_space}/memories/patterns"
+filename_template: "{pattern_name}.md"
+enabled: true
+fields:
+ - name: pattern_name
+ type: string
+ description: |
+ Pattern name used to uniquely identify this pattern memory.
+ Should be in "Process name: Step description" format such as "Teaching topic handling: Outline→Plan→Generate PPT", "Code refactoring: Understand→Test→Refactor→Verify", etc.
+ Example: "[Pattern name]: [Step sequence]"
+ merge_op: immutable
+
+ - name: pattern_type
+ type: string
+ description: |
+ Pattern type describing what type of pattern this is.
+ Possible values: workflow, method, process, etc.
+
+ - name: content
+ type: string
+ description: |
+ Detailed pattern content describing "under what circumstances to follow what process".
+ Includes: trigger conditions, process steps, considerations, etc.
+ Example: "When user requests teaching content for a topic, use a four-step process: first list the topic outline to understand overall structure; then create a detailed learning plan; next generate PPT framework; finally refine specific content for each section. This process ensures content is systematic and complete."
+ merge_op: patch
diff --git a/openviking/prompts/templates/memory/preferences.yaml b/openviking/prompts/templates/memory/preferences.yaml
new file mode 100644
index 000000000..15b10a7fa
--- /dev/null
+++ b/openviking/prompts/templates/memory/preferences.yaml
@@ -0,0 +1,26 @@
+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.
+ 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.
+directory: "viking://user/{user_space}/memories/preferences"
+filename_template: "{topic}.md"
+enabled: true
+fields:
+ - name: topic
+ type: string
+ description: |
+ Preference topic in Chinese or English. If English, use lowercase with underscores, max 3 words.
+ 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.
+ merge_op: immutable
+
+ - name: content
+ type: string
+ description: |
+ Preference content in Markdown format describing "what the user prefers/is accustomed to".
+ 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
new file mode 100644
index 000000000..9bc8dcc09
--- /dev/null
+++ b/openviking/prompts/templates/memory/profile.yaml
@@ -0,0 +1,17 @@
+memory_type: profile
+description: |
+ 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.
+ Do NOT include transient conversation content or temporary mood states.
+directory: "viking://user/{user_space}/memories"
+filename_template: "profile.md"
+enabled: true
+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.
+ Example: "User is an AI development engineer with 3 years of LLM application development experience, mainly using Python and LangChain tech stack. Communication style is concise and direct, prefers efficient code implementation."
+ merge_op: patch
diff --git a/openviking/prompts/templates/memory/skills.yaml b/openviking/prompts/templates/memory/skills.yaml
new file mode 100644
index 000000000..5a286a332
--- /dev/null
+++ b/openviking/prompts/templates/memory/skills.yaml
@@ -0,0 +1,100 @@
+memory_type: skills
+description: |
+ Skill execution memory - captures "how this skill is executed, what works well, and what doesn't".
+ Extract skill execution patterns, statistics, and learnings from skill usage in conversation.
+ For each skill, track: how many times it's been executed, success rate, what it's best for, recommended execution flow, key dependencies, common failure modes, and actionable recommendations.
+ Also accumulate complete guidelines with "Good Cases" and "Bad Cases" examples.
+ Skill memories help the agent learn from experience and execute skills more effectively over time.
+directory: "viking://agent/{agent_space}/memories/skills"
+filename_template: "{skill_name}.md"
+
+content_template: |
+ Skill: {skill_name}
+
+ Skill Memory Context:
+ Based on {total_executions} historical executions:
+ - Success rate: {success_rate}% ({success_count} successful, {fail_count} failed)
+ - Best for: {best_for}
+ - Recommended flow: {recommended_flow}
+ - Key dependencies: {key_dependencies}
+ - Common failures: {common_failures}
+ - Recommendation: {recommendation}
+
+ {guidelines}
+
+enabled: true
+fields:
+ - name: skill_name
+ type: string
+ description: |
+ Skill name, copied exactly from [ToolCall] if skill_name is present, otherwise inferred from conversation context.
+ Used to uniquely identify this skill memory.
+ Examples: "create_presentation", "analyze_code", "write_document"
+ merge_op: immutable
+
+ - name: total_executions
+ type: int64
+ description: |
+ Total number of skill executions, accumulated from historical statistics.
+ Used to calculate success rate.
+ merge_op: sum
+
+ - name: success_count
+ type: int64
+ description: |
+ Number of successful skill executions, accumulated from historical statistics.
+ Counts successful executions.
+ merge_op: sum
+
+ - name: fail_count
+ type: int64
+ description: |
+ Number of failed skill executions, accumulated from historical statistics.
+ Counts failed executions.
+ merge_op: sum
+
+ - name: best_for
+ type: string
+ description: |
+ Best use cases for the skill, describing in what scenarios this skill works best.
+ Examples: "Slide creation tasks with clear topic and target audience"
+ merge_op: patch
+
+ - name: recommended_flow
+ type: string
+ description: |
+ Recommended execution flow for the skill, describing the best steps to execute this skill.
+ Examples: "1. Confirm topic and audience → 2. Collect reference materials → 3. Generate outline → 4. Create slides → 5. Refine content"
+ merge_op: patch
+
+ - name: key_dependencies
+ type: string
+ description: |
+ Key dependencies/prerequisites for the skill, describing what prerequisites and inputs are needed to execute this skill.
+ Examples: "Clear topic (e.g., 'Q3 project update', 'Python tutorial'); Target audience (e.g., 'executives', 'beginners'); Reference materials (optional but recommended)"
+ merge_op: patch
+
+ - name: common_failures
+ type: string
+ description: |
+ Common failure modes of the skill, describing problems and error patterns this skill frequently encounters.
+ Examples: "Vague topic like 'make a PPT' leads to multiple rework cycles; Missing audience info causes style mismatch; No reference materials results in generic content"
+ merge_op: patch
+
+ - name: recommendation
+ type: string
+ description: |
+ Actionable recommendations for skill usage, short actionable recommendations.
+ Examples: "Always confirm topic and audience before starting; Collect 2-3 reference materials for better quality"
+ merge_op: patch
+
+ - name: guidelines
+ type: string
+ description: |
+ Skill usage guidelines, complete usage guide content.
+ Must include exact English headings:
+ - "## Guidelines" - best practices
+ - "### Good Cases" - successful usage examples
+ - "### Bad Cases" - failed usage examples
+ Headings must be in English, content can be in target language.
+ merge_op: patch
diff --git a/openviking/prompts/templates/memory/tools.yaml b/openviking/prompts/templates/memory/tools.yaml
new file mode 100644
index 000000000..eeec88d2c
--- /dev/null
+++ b/openviking/prompts/templates/memory/tools.yaml
@@ -0,0 +1,117 @@
+memory_type: tools
+description: |
+ Tool usage memory - captures "how this tool is used, what works well, and what doesn't".
+ Extract tool usage patterns, statistics, and learnings from [ToolCall] records and conversation context.
+ For each tool, track: how many times it's been called, success rate, average time/tokens, what it's best for, optimal parameters, common failure modes, and actionable recommendations.
+ Also accumulate complete guidelines with "Good Cases" and "Bad Cases" examples.
+ Tool memories help the agent learn from experience and use tools more effectively over time.
+directory: "viking://agent/{agent_space}/memories/tools"
+filename_template: "{tool_name}.md"
+enabled: true
+content_template: |
+ Tool: {tool_name}
+
+ Static Description:
+ "{static_desc}"
+
+ Tool Memory Context:
+ Based on {total_calls} historical calls:
+ - Success rate: {success_rate}% ({success_count} successful, {fail_count} failed)
+ - Avg time: {total_time_ms/total_calls}, Avg tokens: {total_tokens/total_calls}
+ - Best for: {best_for}
+ - Optimal params: {optimal_params}
+ - Common failures: {common_failures}
+ - Recommendation: {recommendation}
+
+ {guidelines}
+
+fields:
+ - name: tool_name
+ type: string
+ description: |
+ Tool name, copied exactly from [ToolCall] records without modification.
+ Used to uniquely identify this tool memory.
+ Examples: "web_search", "read_file", "execute_code"
+ merge_op: immutable
+
+ - name: static_desc
+ type: string
+ description: |
+ Static description of the tool, basic functionality description.
+ Examples: "Searches the web for information", "Reads files from the file system"
+
+ - name: total_calls
+ type: int64
+ description: |
+ Total number of tool calls, accumulated from historical statistics.
+ Used to calculate success rate and average duration.
+ merge_op: sum
+
+ - name: success_count
+ type: int64
+ description: |
+ Number of successful tool calls, accumulated from historical statistics.
+ Counts calls with status "completed".
+ merge_op: sum
+
+ - name: fail_count
+ type: int64
+ description: |
+ Number of failed tool calls, accumulated from historical statistics.
+ Counts calls with status not "completed".
+ merge_op: sum
+
+ - name: total_time_ms
+ type: int64
+ description: |
+ Total tool call duration in milliseconds, accumulated from historical statistics.
+ Used to calculate average duration.
+ merge_op: sum
+
+ - name: total_tokens
+ type: int64
+ description: |
+ Total tokens used by tool calls (prompt tokens + completion tokens), accumulated from historical statistics.
+ Used to calculate average token consumption.
+ merge_op: sum
+
+ - name: best_for
+ type: string
+ description: |
+ Best use cases for the tool, describing in what scenarios this tool works best.
+ Examples: "Technical documentation, tutorials, API references"
+ merge_op: patch
+
+ - name: optimal_params
+ type: string
+ description: |
+ Optimal parameter range/best practices for the tool, describing general parameter optimization suggestions.
+ Should describe general best practices (such as "max_results=5-20", "timeout>30s for large files"),
+ do not describe specific case values (such as "command: 'echo hello'").
+ Examples: "max_results: 5-20 (larger values may timeout); language: 'en' for better results; query: specific multi-word phrases with qualifiers"
+ merge_op: patch
+
+ - name: common_failures
+ type: string
+ description: |
+ Common failure modes of the tool, describing problems and error patterns this tool frequently encounters.
+ Examples: "Single-word queries return irrelevant results; max_results>50 causes timeout; non-English queries have lower quality"
+ merge_op: patch
+
+ - name: recommendation
+ type: string
+ description: |
+ Actionable recommendations for tool usage, short actionable recommendations.
+ Examples: "Use specific multi-word queries like 'Python asyncio tutorial'; add qualifiers like 'guide', 'docs', 'example'"
+ merge_op: patch
+
+ - name: guidelines
+ type: string
+ description: |
+ Tool usage guidelines, complete usage guide content.
+ Must include exact English headings:
+ - "## Guidelines" - best practices
+ - "### Good Cases" - successful usage examples
+ - "### Bad Cases" - failed usage examples
+ Headings must be in English, content can be in target language.
+ merge_op: patch
diff --git a/openviking/server/identity.py b/openviking/server/identity.py
index 5dcf932a8..74a95e904 100644
--- a/openviking/server/identity.py
+++ b/openviking/server/identity.py
@@ -2,9 +2,9 @@
# SPDX-License-Identifier: Apache-2.0
"""Identity and role types for OpenViking multi-tenant HTTP Server."""
-from dataclasses import dataclass
+from dataclasses import dataclass, field
from enum import Enum
-from typing import Optional
+from typing import List, Optional
from openviking_cli.session.user_id import UserIdentifier
@@ -31,6 +31,7 @@ class RequestContext:
user: UserIdentifier
role: Role
+ default_search_uris: List[str] = field(default_factory=list)
@property
def account_id(self) -> str:
diff --git a/openviking/service/core.py b/openviking/service/core.py
index 4f58cd5f4..f5e6905a9 100644
--- a/openviking/service/core.py
+++ b/openviking/service/core.py
@@ -21,7 +21,7 @@ from openviking.service.relation_service import RelationService
from openviking.service.resource_service import ResourceService
from openviking.service.search_service import SearchService
from openviking.service.session_service import SessionService
-from openviking.session.compressor import SessionCompressor
+from openviking.session import create_session_compressor, SessionCompressor
from openviking.storage import VikingDBManager
from openviking.storage.collection_schemas import init_context_collection
from openviking.storage.queuefs.queue_manager import QueueManager, init_queue_manager
@@ -307,7 +307,7 @@ class OpenVikingService:
vikingdb=self._vikingdb_manager,
)
self._skill_processor = SkillProcessor(vikingdb=self._vikingdb_manager)
- self._session_compressor = SessionCompressor(vikingdb=self._vikingdb_manager)
+ self._session_compressor = create_session_compressor(vikingdb=self._vikingdb_manager)
# Start LockManager if initialized
if self._lock_manager:
diff --git a/openviking/session/__init__.py b/openviking/session/__init__.py
index d9a8d9d3a..4dad7c2e2 100644
--- a/openviking/session/__init__.py
+++ b/openviking/session/__init__.py
@@ -2,6 +2,12 @@
# SPDX-License-Identifier: Apache-2.0
"""Session management module."""
+from typing import Optional
+
+from openviking.storage import VikingDBManager
+from openviking_cli.utils import get_logger
+from openviking_cli.utils.config import get_openviking_config
+
from openviking.session.compressor import ExtractionStats, SessionCompressor
from openviking.session.memory_archiver import (
ArchivalCandidate,
@@ -23,6 +29,47 @@ from openviking.session.memory_extractor import (
)
from openviking.session.session import Session, SessionCompression, SessionStats
+logger = get_logger(__name__)
+
+
+def create_session_compressor(
+ vikingdb: VikingDBManager,
+ memory_version: Optional[str] = None,
+) -> SessionCompressor:
+ """
+ Create a SessionCompressor instance based on configuration.
+
+ Args:
+ vikingdb: VikingDBManager instance
+ memory_version: Optional memory version override ("v1" or "v2").
+ If not provided, uses the version from config.
+
+ Returns:
+ SessionCompressor instance (v1 or v2 implementation)
+ """
+ # Determine which version to use
+ if memory_version is None:
+ try:
+ config = get_openviking_config()
+ memory_version = config.memory.version
+ except Exception as e:
+ logger.warning(f"Failed to get memory version from config, defaulting to v1: {e}")
+ memory_version = "v1"
+
+ if memory_version == "v2":
+ logger.info("Using v2 memory compressor (templating system)")
+ try:
+ from openviking.session.compressor_v2 import SessionCompressorV2
+ return SessionCompressorV2(vikingdb=vikingdb)
+ except Exception as e:
+ logger.warning(f"Failed to load v2 compressor, falling back to v1: {e}")
+ return SessionCompressor(vikingdb=vikingdb)
+
+ # Default to v1
+ logger.info("Using v1 memory compressor (legacy)")
+ return SessionCompressor(vikingdb=vikingdb)
+
+
__all__ = [
# Session
"Session",
@@ -31,6 +78,7 @@ __all__ = [
# Compressor
"SessionCompressor",
"ExtractionStats",
+ "create_session_compressor",
# Memory Archiver
"MemoryArchiver",
"ArchivalCandidate",
diff --git a/openviking/session/compressor_v2.py b/openviking/session/compressor_v2.py
new file mode 100644
index 000000000..074ad48be
--- /dev/null
+++ b/openviking/session/compressor_v2.py
@@ -0,0 +1,149 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: Apache-2.0
+"""
+Session Compressor V2 for OpenViking.
+
+Uses the new Memory Templating System with ReAct orchestrator.
+Maintains the same interface as compressor.py for backward compatibility.
+"""
+
+from dataclasses import dataclass
+import os
+from typing import Dict, List, Optional
+
+from openviking.core.context import Context
+from openviking.message import Message
+from openviking.server.identity import RequestContext
+from openviking.storage import VikingDBManager
+from openviking.storage.viking_fs import get_viking_fs
+from openviking_cli.session.user_id import UserIdentifier
+from openviking_cli.utils import get_logger
+from openviking_cli.utils.config import get_openviking_config
+
+from openviking.session.memory import MemoryReAct, MemoryUpdater, MemoryTypeRegistry
+
+logger = get_logger(__name__)
+
+
+@dataclass
+class ExtractionStats:
+ """Statistics for memory extraction."""
+
+ created: int = 0
+ merged: int = 0
+ deleted: int = 0
+ skipped: int = 0
+
+
+class SessionCompressorV2:
+ """Session memory extractor with v2 templating system."""
+
+ def __init__(
+ self,
+ vikingdb: VikingDBManager,
+ ):
+ """Initialize session compressor."""
+ self.vikingdb = vikingdb
+ # Initialize registry once - used by both MemoryReAct and MemoryUpdater
+ self._registry = MemoryTypeRegistry()
+ schemas_dir = os.path.join(os.path.dirname(__file__), "..", "prompts", "templates", "memory")
+ self._registry.load_from_directory(schemas_dir)
+ # Lazy initialize MemoryReAct - we need vlm and ctx
+ self._react_orchestrator: Optional[MemoryReAct] = None
+ self._memory_updater: Optional[MemoryUpdater] = None
+
+ def _get_or_create_react(
+ self, ctx: Optional[RequestContext] = None
+ ) -> MemoryReAct:
+ """Create new MemoryReAct instance with current ctx.
+
+ Note: Always create new instance to avoid cross-session isolation issues.
+ The ctx contains request-scoped state that must not be shared across requests.
+ """
+ config = get_openviking_config()
+ vlm = config.vlm.get_vlm_instance()
+ viking_fs = get_viking_fs()
+
+ return MemoryReAct(
+ vlm=vlm,
+ viking_fs=viking_fs,
+ ctx=ctx,
+ registry=self._registry,
+ )
+
+ def _get_or_create_updater(self) -> MemoryUpdater:
+ """Get or create MemoryUpdater instance."""
+ if self._memory_updater is not None:
+ return self._memory_updater
+
+ self._memory_updater = MemoryUpdater(registry=self._registry)
+ return self._memory_updater
+
+ async def extract_long_term_memories(
+ self,
+ messages: List[Message],
+ user: Optional["UserIdentifier"] = None,
+ session_id: Optional[str] = None,
+ ctx: Optional[RequestContext] = None,
+ strict_extract_errors: bool = False,
+ ) -> List[Context]:
+ """Extract long-term memories from messages using v2 templating system.
+
+ Note: Returns empty List[Context] because v2 directly writes to storage.
+ The list length is used for stats in session.py.
+ """
+ if not messages:
+ return []
+
+ if not ctx:
+ logger.warning("No RequestContext provided, skipping memory extraction")
+ return []
+
+ # Format conversation as string
+ conversation_str = "\n".join([f"[{msg.role}]: {msg.content}" for msg in messages])
+
+ logger.info("Starting v2 memory extraction from conversation")
+
+ try:
+ # Initialize orchestrator
+ orchestrator = self._get_or_create_react(ctx=ctx)
+ updater = self._get_or_create_updater()
+
+ # Run ReAct orchestrator
+ operations, tools_used = await orchestrator.run(conversation=conversation_str)
+
+ if operations is None:
+ logger.info("No memory operations generated")
+ return []
+
+ logger.info(
+ f"Generated memory operations: write={len(operations.write_uris)}, "
+ f"edit={len(operations.edit_uris)}, edit_overview={len(operations.edit_overview_uris)}, "
+ f"delete={len(operations.delete_uris)}"
+ )
+
+ # Apply operations
+ result = await updater.apply_operations(
+ operations, ctx, registry=orchestrator.registry
+ )
+
+ logger.info(
+ f"Applied memory operations: written={len(result.written_uris)}, "
+ f"edited={len(result.edited_uris)}, deleted={len(result.deleted_uris)}, "
+ f"errors={len(result.errors)}"
+ )
+
+ # Return list with dummy values to preserve count for stats in session.py
+ # v2 directly writes to storage, so we return None objects to maintain len() accuracy
+ total_changes = (
+ len(result.written_uris)
+ + len(result.edited_uris)
+ + len(result.deleted_uris)
+ )
+ return [None] * total_changes
+
+ except Exception as e:
+ logger.error(f"Failed to extract memories with v2: {e}", exc_info=True)
+ if strict_extract_errors:
+ raise
+ return []
diff --git a/openviking/session/memory/__init__.py b/openviking/session/memory/__init__.py
new file mode 100644
index 000000000..11866f3c3
--- /dev/null
+++ b/openviking/session/memory/__init__.py
@@ -0,0 +1,95 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: Apache-2.0
+"""
+Memory Templating System for OpenViking.
+
+This module provides a YAML-configurable memory templating system with
+ReAct (Reasoning + Action) pattern for memory updates.
+"""
+
+from openviking.session.memory.utils import (
+ detect_language_from_conversation,
+ generate_uri,
+ is_uri_allowed,
+ is_uri_allowed_for_schema,
+ pretty_print_messages,
+ resolve_all_operations,
+ validate_uri_template,
+)
+from openviking.session.memory.dataclass import (
+ MemoryData,
+ MemoryField,
+ MemoryOperations,
+ MemoryTypeSchema,
+ StructuredMemoryOperations,
+)
+from openviking.session.memory.merge_op import MergeOp, FieldType, MemoryPatchHandler
+from openviking.session.memory.memory_react import (
+ MemoryReAct,
+)
+from openviking.session.memory.memory_type_registry import MemoryTypeRegistry
+from openviking.session.memory.memory_updater import MemoryUpdater, MemoryUpdateResult
+from openviking.session.memory.schema_model_generator import (
+ SchemaModelGenerator,
+ SchemaPromptGenerator,
+)
+from openviking.session.memory.tools import (
+ MemorySearchTool,
+ MemoryLsTool,
+ MemoryReadTool,
+ MemoryTool,
+ add_tool_call_items_to_messages,
+ add_tool_call_pair_to_messages,
+ create_tool_call_message,
+ create_tool_result_message,
+ get_tool,
+ get_tool_schemas,
+ list_tools,
+ register_tool,
+)
+
+__all__ = [
+ # Data structures
+ "FieldType",
+ "MergeOp",
+ "MemoryField",
+ "MemoryTypeSchema",
+ "MemoryData",
+ # Operations
+ "MemoryOperations",
+ "StructuredMemoryOperations",
+ # Registry
+ "MemoryTypeRegistry",
+ # Schema models
+ "SchemaModelGenerator",
+ "SchemaPromptGenerator",
+ # Patch
+ "MemoryPatchHandler",
+ # Updater
+ "MemoryUpdater",
+ "MemoryUpdateResult",
+ # ReAct
+ "MemoryReAct",
+ # Tools (Tool implementations)
+ "MemoryTool",
+ "MemoryReadTool",
+ "MemorySearchTool",
+ "MemoryLsTool",
+ "register_tool",
+ "get_tool",
+ "list_tools",
+ "get_tool_schemas",
+ "create_tool_call_message",
+ "create_tool_result_message",
+ "add_tool_call_pair_to_messages",
+ "add_tool_call_items_to_messages",
+ # Language utilities and helpers
+ "detect_language_from_conversation",
+ "pretty_print_messages",
+ # URI utilities
+ "generate_uri",
+ "validate_uri_template",
+ "resolve_all_operations",
+ "is_uri_allowed",
+ "is_uri_allowed_for_schema",
+]
diff --git a/openviking/session/memory/dataclass.py b/openviking/session/memory/dataclass.py
new file mode 100644
index 000000000..4ce2c03a8
--- /dev/null
+++ b/openviking/session/memory/dataclass.py
@@ -0,0 +1,135 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: Apache-2.0
+"""
+Core domain data classes for memory system.
+"""
+
+from datetime import datetime
+from typing import Any, List, Optional, Protocol, TypeVar
+
+from pydantic import BaseModel, Field
+
+from openviking.session.memory.merge_op.base import (
+ FieldType,
+ MergeOp,
+ SearchReplaceBlock,
+ StrPatch,
+ get_python_type_for_field,
+)
+
+
+T = TypeVar('T')
+
+
+# ============================================================================
+# Memory Field and Schema Definitions
+# ============================================================================
+
+
+class MemoryField(BaseModel):
+ """Memory field definition."""
+
+ name: str = Field(..., description="Field name")
+ field_type: FieldType = Field(..., description="Field type")
+ description: str = Field("", description="Field description")
+ merge_op: MergeOp = Field(MergeOp.PATCH, description="Merge strategy")
+
+
+class MemoryTypeSchema(BaseModel):
+ """Memory type schema definition."""
+
+ memory_type: str = Field(..., description="Memory type name")
+ description: str = Field("", description="Type description")
+ fields: List[MemoryField] = Field(default_factory=list, description="Field definitions")
+ filename_template: str = Field("", description="Filename template")
+ content_template: Optional[str] = Field(None, description="Content template (for template mode)")
+ directory: str = Field("", description="Directory path")
+ enabled: bool = Field(True, description="Whether this memory type is enabled")
+
+
+class MemoryData(BaseModel):
+ """Dynamic memory data."""
+
+ memory_type: str = Field(..., description="Memory type name")
+ uri: Optional[str] = Field(None, description="Memory URI (for updates)")
+ fields: dict[str, Any] = Field(default_factory=dict, description="Dynamic field data")
+ abstract: Optional[str] = Field(None, description="L0 abstract")
+ overview: Optional[str] = Field(None, description="L1 overview")
+ content: Optional[str] = Field(None, description="L2 content")
+ name: Optional[str] = Field(None, description="Memory name")
+ tags: List[str] = Field(default_factory=list, description="Tags")
+ created_at: Optional[datetime] = Field(None, description="Created time")
+ updated_at: Optional[datetime] = Field(None, description="Updated time")
+
+ def get_field(self, field_name: str) -> Any:
+ """Get field value."""
+ return self.fields.get(field_name)
+
+ def set_field(self, field_name: str, value: Any) -> None:
+ """Set field value."""
+ self.fields[field_name] = value
+
+
+
+
+# ============================================================================
+# Memory Operations
+# ============================================================================
+
+
+class MemoryOperationsProtocol(Protocol):
+ """Protocol for memory operations (for type checking)."""
+
+ reasoning: str
+ write_uris: List[Any]
+ edit_uris: List[Any]
+ edit_overview_uris: List[Any]
+ delete_uris: List[str]
+
+ def is_empty(self) -> bool: ...
+
+
+class StructuredMemoryOperations(BaseModel):
+ """
+ DEPRECATED: Placeholder only. The actual model is dynamically generated.
+
+ Use SchemaModelGenerator.create_structured_operations_model() to get
+ the actual type-safe implementation with proper union types for write_uris
+ and edit_uris.
+ """
+
+ reasoning: str = Field(
+ '',
+ description="reasoning",
+ )
+ write_uris: List[Any] = Field(
+ default_factory=list,
+ description="Write operations with flat data format",
+ )
+ edit_uris: List[Any] = Field(
+ default_factory=list,
+ description="Edit operations with flat data format",
+ )
+ edit_overview_uris: List[Any] = Field(
+ default_factory=list,
+ description="Edit operations for .overview.md files using memory_type",
+ )
+ delete_uris: List[str] = Field(
+ default_factory=list,
+ description="Delete operations as URI strings",
+ )
+
+ def is_empty(self) -> bool:
+ """Check if there are any operations."""
+ return (
+ len(self.write_uris) == 0
+ and len(self.edit_uris) == 0
+ and len(self.edit_overview_uris) == 0
+ and len(self.delete_uris) == 0
+ )
+
+ model_config = {'extra': 'ignore'}
+
+
+# Backward compatibility alias
+MemoryOperations = StructuredMemoryOperations
diff --git a/openviking/session/memory/memory_react.py b/openviking/session/memory/memory_react.py
new file mode 100644
index 000000000..bc427a30d
--- /dev/null
+++ b/openviking/session/memory/memory_react.py
@@ -0,0 +1,637 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: Apache-2.0
+"""
+Simplified ReAct orchestrator for memory updates - single LLM call with tool use.
+
+Reference: bot/vikingbot/agent/loop.py AgentLoop structure
+"""
+
+import asyncio
+import json
+from enum import Enum
+from typing import Any, Dict, List, Optional, Set, Tuple
+
+from pydantic import BaseModel, Field
+
+from openviking.models.vlm.base import VLMBase, VLMResponse
+from openviking.server.identity import RequestContext
+from openviking.session.memory.utils import (
+ collect_allowed_directories,
+ detect_language_from_conversation,
+ extract_json_from_markdown,
+ parse_json_with_stability,
+ parse_memory_file_with_fields,
+ pretty_print_messages,
+ validate_operations_uris,
+)
+from openviking.session.memory.dataclass import MemoryOperations
+from openviking.session.memory.memory_type_registry import MemoryTypeRegistry
+from openviking.session.memory.schema_model_generator import (
+ SchemaModelGenerator,
+ SchemaPromptGenerator,
+)
+from openviking.session.memory.tools import (
+ get_tool,
+ get_tool_schemas,
+ add_tool_call_pair_to_messages,
+)
+from openviking.storage.viking_fs import VikingFS, get_viking_fs
+from openviking_cli.utils import get_logger
+from openviking_cli.utils.config import get_openviking_config
+
+logger = get_logger(__name__)
+
+
+
+class MemoryReAct:
+ """
+ Simplified ReAct orchestrator for memory updates.
+
+ Workflow:
+ 0. Pre-fetch: System performs ls + read .overview.md + search
+ 1. LLM call with tools: Model decides to either use tools OR output final operations
+ 2. If tools used: Execute and continue loop
+ 3. If operations output: Return and finish
+ """
+
+ def __init__(
+ self,
+ vlm: VLMBase,
+ viking_fs: Optional[VikingFS] = None,
+ model: Optional[str] = None,
+ max_iterations: int = 5,
+ ctx: Optional[RequestContext] = None,
+ registry: Optional[MemoryTypeRegistry] = None,
+ ):
+ """
+ Initialize the MemoryReAct.
+
+ Args:
+ vlm: VLM instance (from openviking.models.vlm.base)
+ viking_fs: VikingFS instance for storage operations
+ model: Model name to use
+ max_iterations: Maximum number of ReAct iterations (default: 5)
+ ctx: Request context
+ registry: Optional MemoryTypeRegistry - if not provided, will be created
+ """
+ self.vlm = vlm
+ self.viking_fs = viking_fs or get_viking_fs()
+ self.model = model or self.vlm.model
+ self.max_iterations = max_iterations
+ self.ctx = ctx
+
+ # Initialize schema registry and generators
+ if registry is not None:
+ self.registry = registry
+ else:
+ import os
+ schemas_dir = os.path.join(os.path.dirname(__file__), "..", "..", "prompts", "templates", "memory")
+ self.registry = MemoryTypeRegistry()
+ self.registry.load_from_directory(schemas_dir)
+ self.schema_model_generator = SchemaModelGenerator(self.registry)
+ self.schema_prompt_generator = SchemaPromptGenerator(self.registry)
+
+ # Pre-generate models and JSON schema
+ self.schema_model_generator.generate_all_models()
+ self._json_schema = self.schema_model_generator.get_llm_json_schema()
+
+ # Track files read during ReAct for refetch detection
+ self._read_files: Set[str] = set()
+ self._output_language: str = "en"
+
+ async def _pre_fetch_context(self, conversation: str) -> Dict[str, Any]:
+ """
+ Pre-fetch context based on activated schemas.
+
+ Optimized logic:
+ - For multi-file schemas (filename_template has variables): ls the directory
+ - For single-file schemas (filename_template no variables): directly read the file
+ - No longer ls the root memories directory
+
+ Args:
+ conversation: Conversation history for search query
+
+ Returns:
+ Pre-fetched context with directories, summaries, and search_results
+ """
+ from openviking.session.memory.tools import get_tool
+ messages = []
+
+ # Step 1: Separate schemas into multi-file (ls) and single-file (direct read)
+ ls_dirs = set() # directories to ls (for multi-file schemas)
+ read_files = set() # files to read directly (for single-file schemas)
+
+ for schema in self.registry.list_all(include_disabled=False):
+ if not schema.directory:
+ continue
+
+ # Replace variables in directory path with actual user/agent space
+ user_space = self.ctx.user.user_space_name() if self.ctx and self.ctx.user else "default"
+ agent_space = self.ctx.user.agent_space_name() if self.ctx and self.ctx.user else "default"
+ dir_path = schema.directory.replace("{user_space}", user_space).replace("{agent_space}", agent_space)
+
+ # Check if filename_template has variables (contains {xxx})
+ has_variables = False
+ if schema.filename_template:
+ has_variables = "{" in schema.filename_template and "}" in schema.filename_template
+
+ if has_variables or not schema.filename_template:
+ # Multi-file schema or no filename template: ls the directory
+ ls_dirs.add(dir_path)
+ else:
+ # Single-file schema: directly read the specific file
+ file_uri = f"{dir_path}/{schema.filename_template}"
+ read_files.add(file_uri)
+
+ call_id_seq = 0
+ # Step 2: Execute ls for multi-file schema directories in parallel
+ ls_tool = get_tool("ls")
+ read_tool = get_tool("read")
+ if ls_tool and self.viking_fs and ls_dirs:
+ for dir_uri in ls_dirs:
+ try:
+ result_str = await ls_tool.execute(self.viking_fs, self.ctx, uri=dir_uri)
+ add_tool_call_pair_to_messages(
+ messages=messages,
+ call_id=call_id_seq,
+ tool_name='ls',
+ params={
+ "uri": dir_uri
+ },
+ result=result_str
+ )
+ call_id_seq += 1
+
+ result_str = await read_tool.execute(self.viking_fs, self.ctx, uri=f'{dir_uri}/.overview.md')
+
+ add_tool_call_pair_to_messages(
+ messages=messages,
+ call_id=call_id_seq,
+ tool_name='read',
+ params={
+ "uri": f'{dir_uri}/.overview.md'
+ },
+ result=result_str
+ )
+ call_id_seq += 1
+
+ except Exception as e:
+ logger.warning(f"Failed to ls {dir_uri}: {e}")
+
+ # Step 3: Search for relevant memories based on user messages in conversation
+ search_tool = get_tool("search")
+ if search_tool and self.viking_fs and self.ctx:
+ try:
+ # Extract only user messages from conversation
+ user_messages = []
+ for line in conversation.split("\n"):
+ if line.startswith("[user]:"):
+ user_messages.append(line[len("[user]:"):].strip())
+ user_query = " ".join(user_messages)
+
+ if user_query:
+ search_result = await search_tool.execute(
+ viking_fs=self.viking_fs,
+ ctx=self.ctx,
+ query=user_query,
+ )
+ if search_result and not search_result.get("error"):
+ add_tool_call_pair_to_messages(
+ messages=messages,
+ call_id=call_id_seq,
+ tool_name='search',
+ params={"query": user_query},
+ result=str(search_result)
+ )
+ call_id_seq += 1
+ except Exception as e:
+ logger.warning(f"Pre-fetch search failed: {e}")
+
+ return messages
+
+
+ async def run(
+ self,
+ conversation: str,
+ ) -> Tuple[Optional[MemoryOperations], List[Dict[str, Any]]]:
+ """
+ Run the simplified ReAct loop for memory updates.
+
+ Args:
+ conversation: Conversation history
+
+ Returns:
+ Tuple of (final MemoryOperations, tools_used list)
+ """
+ iteration = 0
+ final_operations = None
+ tools_used: List[Dict[str, Any]] = []
+
+ # Detect output language from conversation
+ config = get_openviking_config()
+ fallback_language = (config.language_fallback or "en").strip() or "en"
+ self._output_language = detect_language_from_conversation(
+ conversation, fallback_language=fallback_language
+ )
+ logger.info(f"Detected output language for memory ReAct: {self._output_language}")
+
+ # Pre-fetch context internally
+ tool_call_messages = await self._pre_fetch_context(conversation)
+
+ # Reset read files tracking for this run
+ self._read_files.clear()
+
+ messages = self._build_initial_messages(conversation, tool_call_messages, self._output_language)
+
+ while iteration < self.max_iterations:
+ iteration += 1
+ logger.debug(f"ReAct iteration {iteration}/{self.max_iterations}")
+
+ # Check if this is the last iteration - force final result
+ is_last_iteration = iteration >= self.max_iterations
+
+ # If last iteration, add a message telling the model to return result directly
+ if is_last_iteration:
+ messages.append({
+ "role": "user",
+ "content": "You have reached the maximum number of tool call iterations. Do not call any more tools - return your final result directly now."
+ })
+
+ # Call LLM with tools - model decides: tool calls OR final operations
+ tool_calls, operations = await self._call_llm(messages, force_final=is_last_iteration)
+
+ # If model returned final operations, check if refetch is needed
+ if operations is not None:
+ # Check if any write_uris target existing files that weren't read
+ refetch_uris = await self._check_unread_existing_files(operations)
+ if refetch_uris:
+ logger.info(f"Found unread existing files: {refetch_uris}, refetching...")
+ # Add refetch results to messages and continue loop
+ await self._add_refetch_results_to_messages(messages, refetch_uris)
+ # Clear operations to force another iteration
+ operations = None
+ # Continue to next iteration
+ continue
+
+ final_operations = operations
+ break
+
+ # If no tool calls either, continue to next iteration (don't break!)
+ if not tool_calls:
+ logger.warning(f"LLM returned neither tool calls nor operations (iteration {iteration}/{self.max_iterations})")
+ # If it's the last iteration, use empty operations
+ if is_last_iteration:
+ final_operations = MemoryOperations()
+ break
+ # Otherwise continue and try again
+ continue
+
+ # Execute all tool calls in parallel
+ async def execute_single_tool_call(idx: int, tool_call):
+ """Execute a single tool call."""
+ result = await self._execute_tool(tool_call)
+ return idx, tool_call, result
+
+ action_tasks = [
+ execute_single_tool_call(idx, tool_call)
+ for idx, tool_call in enumerate(tool_calls)
+ ]
+ results = await self._execute_in_parallel(action_tasks)
+
+ # Process results and add to messages
+ for _idx, tool_call, result in results:
+ tools_used.append({
+ "tool_name": tool_call.name,
+ "params": tool_call.arguments,
+ "result": result,
+ })
+
+ # Track read tool calls for refetch detection
+ if tool_call.name == "read" and tool_call.arguments.get("uri"):
+ self._read_files.add(tool_call.arguments["uri"])
+
+ add_tool_call_pair_to_messages(
+ messages,
+ call_id=tool_call.id,
+ tool_name=tool_call.name,
+ params=tool_call.arguments,
+ result=result,
+ )
+ # Print updated messages with tool results
+ pretty_print_messages(messages)
+ if final_operations is None:
+ if iteration >= self.max_iterations:
+ raise RuntimeError(f"Reached {self.max_iterations} iterations without completion")
+ else:
+ raise RuntimeError("ReAct loop completed but no operations generated")
+
+ logger.info(f'final_operations={final_operations.model_dump_json(indent=4)}')
+
+ return final_operations, tools_used
+
+ def _build_initial_messages(
+ self,
+ conversation: str,
+ tool_call_messages: List,
+ output_language: str,
+ ) -> List[Dict[str, Any]]:
+ """Build initial messages from conversation and pre-fetched context."""
+ system_prompt = self._get_system_prompt(output_language)
+ messages = [
+ {
+ "role": "system",
+ "content": system_prompt,
+ }
+ ]
+
+ # Add pre-fetched context as tool calls
+ messages.extend(tool_call_messages)
+ messages.append({
+ "role": "user",
+ "content": f"""## Conversation History
+{conversation}
+
+After exploring, analyze the conversation and output ALL memory write/edit/delete operations in a single response. Do not output operations one at a time - gather all changes first, then return them together.""",
+ })
+ # Print messages in a readable format
+ pretty_print_messages(messages)
+
+ return messages
+
+
+ def _get_allowed_directories_list(self) -> str:
+ """Get a formatted list of allowed directories for the system prompt."""
+ user_space = self.ctx.user.user_space_name() if self.ctx and self.ctx.user else "default"
+ agent_space = self.ctx.user.agent_space_name() if self.ctx and self.ctx.user else "default"
+ allowed_dirs = collect_allowed_directories(
+ self.registry.list_all(include_disabled=False),
+ user_space=user_space,
+ agent_space=agent_space,
+ )
+ if not allowed_dirs:
+ return "No directories configured (this is an error)."
+ return "\n".join(f"- {dir_path}" for dir_path in sorted(allowed_dirs))
+
+ def _get_system_prompt(self, output_language: str) -> str:
+ """Get the simplified system prompt."""
+ import json
+ schema_str = json.dumps(self._json_schema, ensure_ascii=False)
+ allowed_dirs_list = self._get_allowed_directories_list()
+
+ return f"""You are a memory extraction agent. Your task is to analyze conversations and update memories.
+
+## Workflow
+1. Analyze the conversation and pre-fetched context
+2. If you need more information, use the available tools (read/search)
+3. When you have enough information, output ONLY a JSON object (no extra text before or after)
+
+## CRITICAL: Available Tools
+- ONLY read and search tools are available
+- DO NOT use write tool - just output the JSON result, the system will handle writing
+- ls tool is NOT available
+
+## Critical: Read Before Edit
+IMPORTANT: Before you edit or update ANY existing memory file, you MUST first use the read tool to read its complete content.
+
+- The pre-fetched .overview.md files are only partial information - they are NOT the complete memory content
+- You MUST use the read tool to get the actual content of any file you want to edit
+- Without reading the actual file first, your edit operations will fail because the search string won't match
+
+## Target Output Language
+All memory content (abstract, overview, content fields) MUST be written in {output_language}.
+
+## URI Handling (Automatic)
+IMPORTANT: You do NOT need to construct URIs manually. The system will automatically generate URIs based on:
+- For write_uris: Using memory_type and fields
+- For edit_uris: Using memory_type and fields to identify the target
+- For edit_overview_uris: Using memory_type to identify the directory, then updates the .overview.md file in that directory
+- For delete_uris: Using memory_type and fields to identify the target
+
+Just provide the correct memory_type and fields, and the system will handle the rest.
+
+## Edit Overview Files (IMPORTANT - Don't Forget!)
+You MUST use edit_overview_uris to update the .overview.md file whenever you write new memories.
+
+This is a REQUIRED step after writing memories:
+1. After adding new entries via write_uris, ALWAYS also update the corresponding .overview.md
+2. The .overview.md provides a high-level summary for that memory type directory
+3. Without updating overview, new memories won't be visible in high-level summaries
+
+Example workflow:
+- write_uris: Add new skill "Python async programming" → writes to skills/python_async.md
+- edit_overview_uris: {{"memory_type": "skills", "overview": "Python async programming, Go concurrency, System design..."}}
+
+How to use edit_overview_uris:
+- Provide memory_type to identify which directory's overview to update
+- Provide overview field with the new content (string or patch format)
+- Example: {{"memory_type": "profile", "overview": "User profile overview..."}}
+
+## Final Output Format
+Outputs will be a complete JSON object with the following fields (Don't have '```json' appear and do not use '//' to omit content)
+
+JSON schema:
+```json
+{schema_str}
+```
+
+## Important Notes
+- DO NOT use write tool - the system will write memories based on your JSON output
+- Only read and search tools are available for you to use
+- Output ONLY the JSON object - no extra text before or after
+- Put your thinking and reasoning in the `reasonning` field of the JSON
+"""
+
+ def _validate_operations(self, operations: MemoryOperations) -> None:
+ """
+ Validate that all operations have allowed URIs.
+
+ Args:
+ operations: The MemoryOperations to validate
+
+ Raises:
+ ValueError: If any operation has a disallowed URI
+ """
+ is_valid, errors = validate_operations_uris(
+ operations,
+ self.registry.list_all(include_disabled=False),
+ self.registry,
+ user_space="default",
+ agent_space="default",
+ )
+ if not is_valid:
+ error_msg = "Invalid memory operations:\n" + "\n".join(f" - {err}" for err in errors)
+ logger.error(error_msg)
+ raise ValueError(error_msg)
+
+ async def _call_llm(
+ self,
+ messages: List[Dict[str, Any]],
+ force_final: bool = False,
+ ) -> Tuple[Optional[List], Optional[MemoryOperations]]:
+ """
+ Call LLM with tools. Returns either tool calls OR final operations.
+
+ Args:
+ messages: Message list
+ force_final: If True, force model to return final result (not tool calls)
+
+ Returns:
+ Tuple of (tool_calls, operations) - one will be None, the other set
+ """
+ # Call LLM with tools
+ tool_choice = "none" if force_final else None
+ response = await self.vlm.get_completion_async(
+ messages=messages,
+ tools=get_tool_schemas(),
+ tool_choice=tool_choice,
+ max_retries=self.vlm.max_retries,
+ )
+
+ # Log cache hit info
+ if hasattr(response, 'usage') and response.usage:
+ usage = response.usage
+ prompt_tokens = usage.get('prompt_tokens', 0)
+ cached_tokens = usage.get('prompt_tokens_details', {}).get('cached_tokens', 0) if isinstance(usage.get('prompt_tokens_details'), dict) else 0
+ if prompt_tokens > 0:
+ cache_hit_rate = (cached_tokens / prompt_tokens) * 100
+ logger.info(f"[KVCache] prompt_tokens={prompt_tokens}, cached_tokens={cached_tokens}, cache_hit_rate={cache_hit_rate:.1f}%")
+ else:
+ logger.info(f"[KVCache] prompt_tokens={prompt_tokens}, cached_tokens={cached_tokens}")
+
+ # Case 1: LLM returned tool calls
+ if response.has_tool_calls:
+ # Format tool calls nicely for debug logging
+ for tc in response.tool_calls:
+ logger.info(f"[assistant tool_call] (id={tc.id}, name={tc.name})")
+ logger.info(f" {json.dumps(tc.arguments, indent=2, ensure_ascii=False)}")
+ return (response.tool_calls, None)
+
+ # Case 2: Try to parse MemoryOperations from content with stability
+ content = response.content or ""
+ if content:
+ try:
+ logger.debug(f"[assistant]\n{content}")
+ # Get the dynamically generated operations model for better type safety
+ operations_model = self.schema_model_generator.create_structured_operations_model()
+
+ # Use five-layer stable JSON parsing
+ operations, error = parse_json_with_stability(
+ content=content,
+ model_class=operations_model,
+ expected_fields=['reasoning', 'write_uris', 'edit_uris', 'edit_overview_uris', 'delete_uris'],
+ )
+
+ if error is not None:
+ logger.warning(f"Failed to parse memory operations (stable parse): {error}")
+ # Fallback: try with base MemoryOperations
+ content_no_md = extract_json_from_markdown(content)
+ operations, error_fallback = parse_json_with_stability(
+ content=content_no_md,
+ model_class=MemoryOperations,
+ expected_fields=['reasoning', 'write_uris', 'edit_uris', 'edit_overview_uris', 'delete_uris'],
+ )
+ if error_fallback is not None:
+ logger.warning(f"Fallback parse also failed: {error_fallback}")
+ return (None, None)
+
+ # Validate that all URIs are allowed
+ self._validate_operations(operations)
+ return (None, operations)
+ except Exception as e:
+ logger.warning(f"Unexpected error parsing memory operations: {e}")
+
+ # Case 3: No tool calls and no parsable operations
+ return (None, None)
+
+ async def _execute_tool(
+ self,
+ tool_call,
+ ) -> Any:
+ """Execute a single read action (read/search/ls/tree)."""
+ if not self.viking_fs:
+ return {"error": "VikingFS not available"}
+
+ tool = get_tool(tool_call.name)
+ if not tool:
+ return {"error": f"Unknown tool: {tool_call.name}"}
+
+ try:
+ result = await tool.execute(self.viking_fs, self.ctx, **tool_call.arguments)
+ return result
+ except Exception as e:
+ logger.error(f"Failed to execute {tool_call.name}: {e}")
+ return {"error": str(e)}
+
+ async def _execute_in_parallel(
+ self,
+ tasks: List[Any],
+ ) -> List[Any]:
+ """Execute tasks in parallel, similar to AgentLoop."""
+ return await asyncio.gather(*tasks)
+
+ async def _check_unread_existing_files(
+ self,
+ operations: MemoryOperations,
+ ) -> List[str]:
+ """Check if write_uris target existing files that weren't read during ReAct."""
+ if not operations.write_uris:
+ return []
+
+ from openviking.session.memory.utils.uri import resolve_flat_model_uri
+
+ refetch_uris = []
+ for op in operations.write_uris:
+ # Resolve the flat model to URI
+ try:
+ uri = resolve_flat_model_uri(op, self.registry, "default", "default")
+ except Exception as e:
+ logger.warning(f"Failed to resolve URI for {op}: {e}")
+ continue
+
+ # Skip if already read
+ if uri in self._read_files:
+ continue
+ # Check if file exists
+ try:
+ await self.viking_fs.read_file(uri, ctx=self.ctx)
+ # File exists and wasn't read - need refetch
+ refetch_uris.append(uri)
+ except Exception:
+ # File doesn't exist, no need to refetch
+ pass
+ return refetch_uris
+
+ async def _add_refetch_results_to_messages(
+ self,
+ messages: List[Dict[str, Any]],
+ refetch_uris: List[str],
+ ) -> None:
+ """Add existing file content as read tool results to messages."""
+ # 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 in refetch_uris:
+ try:
+ content = await self.viking_fs.read_file(uri, ctx=self.ctx)
+ parsed = parse_memory_file_with_fields(content)
+
+ # Add as read tool call + result
+ add_tool_call_pair_to_messages(
+ messages=messages,
+ call_id=call_id_seq,
+ tool_name="read",
+ params={"uri": uri},
+ result=parsed,
+ )
+ call_id_seq += 1
+
+ # Mark as read
+ self._read_files.add(uri)
+ except Exception as e:
+ logger.warning(f"Failed to refetch {uri}: {e}")
+
+ # Add reminder message for the model
+ messages.append({
+ "role": "user",
+ "content": "Note: The files above were automatically read because they exist and you didn't read them before deciding to write. Please consider the existing content when making write decisions. You can now output updated operations."
+ })
diff --git a/openviking/session/memory/memory_type_registry.py b/openviking/session/memory/memory_type_registry.py
new file mode 100644
index 000000000..77f17c869
--- /dev/null
+++ b/openviking/session/memory/memory_type_registry.py
@@ -0,0 +1,165 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: Apache-2.0
+"""
+Memory type registry - loads YAML configurations.
+"""
+
+from pathlib import Path
+from typing import Dict, List, Optional
+
+import yaml
+
+from openviking.session.memory.dataclass import MemoryField, MemoryTypeSchema
+from openviking.session.memory.merge_op import MergeOp
+from openviking.session.memory.merge_op.base import FieldType
+from openviking_cli.utils import get_logger
+
+logger = get_logger(__name__)
+
+
+class MemoryTypeRegistry:
+ """
+ Registry for memory types.
+
+ Loads memory type definitions from YAML files and provides
+ access to memory type configurations.
+ """
+
+ def __init__(self):
+ self._types: Dict[str, MemoryTypeSchema] = {}
+
+ def register(self, memory_type: MemoryTypeSchema) -> None:
+ """Register a memory type."""
+ self._types[memory_type.memory_type] = memory_type
+ logger.debug(f"Registered memory type: {memory_type.memory_type}")
+
+ def get(self, name: str) -> Optional[MemoryTypeSchema]:
+ """Get a memory type by name."""
+ return self._types.get(name)
+
+ def list_all(self, include_disabled: bool = False) -> List[MemoryTypeSchema]:
+ """List all registered memory types.
+
+ Args:
+ include_disabled: If True, include disabled memory types
+
+ Returns:
+ List of memory type schemas
+ """
+ if include_disabled:
+ return list(self._types.values())
+ return [mt for mt in self._types.values() if mt.enabled]
+
+ def list_names(self, include_disabled: bool = False) -> List[str]:
+ """List all registered memory type names.
+
+ Args:
+ include_disabled: If True, include disabled memory types
+
+ Returns:
+ List of memory type names
+ """
+ if include_disabled:
+ return list(self._types.keys())
+ return [mt.memory_type for mt in self._types.values() if mt.enabled]
+
+ def load_from_yaml(self, yaml_path: str) -> None:
+ """
+ Load memory type from a YAML file.
+
+ Args:
+ yaml_path: Path to YAML file
+ """
+ with open(yaml_path, "r", encoding="utf-8") as f:
+ data = yaml.safe_load(f)
+
+ memory_type = self._parse_memory_type(data)
+ self.register(memory_type)
+
+ def load_from_directory(self, dir_path: str) -> int:
+ """
+ Load all YAML files from a directory.
+
+ Args:
+ dir_path: Directory path
+
+ Returns:
+ Number of types loaded
+ """
+ count = 0
+ dir_path_obj = Path(dir_path)
+
+ if not dir_path_obj.exists():
+ logger.warning(f"Directory not found: {dir_path}")
+ return 0
+
+ for yaml_file in dir_path_obj.glob("*.yaml"):
+ try:
+ self.load_from_yaml(str(yaml_file))
+ count += 1
+ except Exception as e:
+ logger.error(f"Failed to load {yaml_file}: {e}")
+
+ for yaml_file in dir_path_obj.glob("*.yml"):
+ try:
+ self.load_from_yaml(str(yaml_file))
+ count += 1
+ except Exception as e:
+ logger.error(f"Failed to load {yaml_file}: {e}")
+
+ return count
+
+ def _parse_memory_type(self, data: dict) -> MemoryTypeSchema:
+ """Parse memory type from YAML data."""
+ fields_data = data.get("fields", [])
+ fields = []
+
+ for field_data in fields_data:
+ field = MemoryField(
+ name=field_data.get("name", ""),
+ field_type=FieldType(field_data.get("type", "string")),
+ description=field_data.get("description", ""),
+ merge_op=MergeOp(field_data.get("merge_op", "patch")),
+ )
+ fields.append(field)
+
+ return MemoryTypeSchema(
+ memory_type=data.get("memory_type", data.get("name", "")),
+ description=data.get("description", ""),
+ fields=fields,
+ filename_template=data.get("filename_template", ""),
+ content_template=data.get("content_template"),
+ directory=data.get("directory", ""),
+ enabled=data.get("enabled", data.get("enable", True)),
+ )
+
+
+
+def create_default_registry(schemas_dir: Optional[str] = None) -> MemoryTypeRegistry:
+ """
+ Create a registry with built-in memory types.
+
+ Args:
+ schemas_dir: Optional directory to load schemas from
+
+ Returns:
+ MemoryTypeRegistry with built-in types
+ """
+ registry = MemoryTypeRegistry()
+
+ # Register built-in types
+ # These can also be loaded from YAML files
+ _register_builtin_types(registry)
+
+ # Load from schemas directory if provided
+ if schemas_dir:
+ registry.load_from_directory(schemas_dir)
+
+ return registry
+
+
+def _register_builtin_types(registry: MemoryTypeRegistry) -> None:
+ """Register built-in memory types."""
+ # Note: In production, these should be loaded from YAML files
+ # This is just a placeholder for reference
+ pass
diff --git a/openviking/session/memory/memory_updater.py b/openviking/session/memory/memory_updater.py
new file mode 100644
index 000000000..b038b2ae6
--- /dev/null
+++ b/openviking/session/memory/memory_updater.py
@@ -0,0 +1,398 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: Apache-2.0
+"""
+Memory updater - applies MemoryOperations directly.
+
+This is the system executor that applies LLM's final output (MemoryOperations)
+to the storage system.
+"""
+
+from datetime import datetime
+from typing import Any, Dict, List, Optional, Tuple
+
+from openviking.server.identity import RequestContext
+from openviking.session.memory.utils import (
+ deserialize_full,
+ serialize_with_metadata,
+ resolve_all_operations,
+ flat_model_to_dict,
+)
+from openviking.session.memory.dataclass import MemoryField
+from openviking.session.memory.merge_op import MergeOpFactory, PatchOp
+from openviking.session.memory.merge_op.base import FieldType, SearchReplaceBlock, StrPatch
+from openviking.session.memory.memory_type_registry import MemoryTypeRegistry
+from openviking.storage.viking_fs import get_viking_fs
+from openviking_cli.exceptions import NotFoundError
+from openviking_cli.utils import get_logger
+
+logger = get_logger(__name__)
+
+
+class MemoryUpdateResult:
+ """Result of memory update operation."""
+
+ def __init__(self):
+ self.written_uris: List[str] = []
+ self.edited_uris: List[str] = []
+ self.deleted_uris: List[str] = []
+ self.errors: List[Tuple[str, Exception]] = []
+
+ def add_written(self, uri: str) -> None:
+ self.written_uris.append(uri)
+
+ def add_edited(self, uri: str) -> None:
+ self.edited_uris.append(uri)
+
+ def add_deleted(self, uri: str) -> None:
+ self.deleted_uris.append(uri)
+
+ def add_error(self, uri: str, error: Exception) -> None:
+ self.errors.append((uri, error))
+
+ def has_changes(self) -> bool:
+ return (
+ len(self.written_uris) > 0
+ or len(self.edited_uris) > 0
+ or len(self.deleted_uris) > 0
+ )
+
+ def summary(self) -> str:
+ return (
+ f"Written: {len(self.written_uris)}, "
+ f"Edited: {len(self.edited_uris)}, "
+ f"Deleted: {len(self.deleted_uris)}, "
+ f"Errors: {len(self.errors)}"
+ )
+
+
+
+
+class MemoryUpdater:
+ """
+ Applies MemoryOperations to storage.
+
+ This is the system executor that directly applies the LLM's final output.
+ No function calls are used for write/edit/delete - these are executed directly.
+ """
+
+ def __init__(self, registry: Optional[MemoryTypeRegistry] = None):
+ self._viking_fs = None
+ self._registry = registry
+
+ def set_registry(self, registry: MemoryTypeRegistry) -> None:
+ """Set the memory type registry for URI resolution."""
+ self._registry = registry
+
+ def _get_viking_fs(self):
+ """Get or create VikingFS instance."""
+ if self._viking_fs is None:
+ self._viking_fs = get_viking_fs()
+ return self._viking_fs
+
+ async def apply_operations(
+ self,
+ operations: Any,
+ ctx: RequestContext,
+ registry: Optional[MemoryTypeRegistry] = None,
+ ) -> MemoryUpdateResult:
+ """
+ Apply MemoryOperations directly using the flat model format.
+
+ This is the system executor - no LLM involved at this stage.
+
+ Args:
+ operations: StructuredMemoryOperations from LLM (final output) with flat models
+ ctx: Request context
+ registry: Optional MemoryTypeRegistry for URI resolution
+
+ Returns:
+ MemoryUpdateResult with changes made
+ """
+ result = MemoryUpdateResult()
+ viking_fs = self._get_viking_fs()
+
+ if not viking_fs:
+ logger.warning("VikingFS not available, skipping memory operations")
+ return result
+
+ # Use provided registry or internal registry
+ resolved_registry = registry or self._registry
+ if not resolved_registry:
+ raise ValueError("MemoryTypeRegistry is required for URI resolution")
+
+ # Get actual user/agent space from ctx
+ user_space = ctx.user.user_space_name() if ctx and ctx.user else "default"
+ agent_space = ctx.user.agent_space_name() if ctx and ctx.user else "default"
+
+ # Resolve all URIs first
+ resolved_ops = resolve_all_operations(
+ operations,
+ resolved_registry,
+ user_space=user_space,
+ agent_space=agent_space,
+ )
+
+ if resolved_ops.has_errors():
+ for error in resolved_ops.errors:
+ result.add_error("unknown", ValueError(error))
+ return result
+
+ # Apply write operations
+ for op, uri in resolved_ops.write_operations:
+ try:
+ await self._apply_write(op, uri, ctx)
+ result.add_written(uri)
+ except Exception as e:
+ logger.error(f"Failed to write memory: {e}")
+ result.add_error(uri, e)
+
+ # Apply edit operations
+ for op, uri in resolved_ops.edit_operations:
+ try:
+ await self._apply_edit(op, uri, ctx)
+ result.add_edited(uri)
+ except Exception as e:
+ logger.error(f"Failed to edit memory {uri}: {e}")
+ result.add_error(uri, e)
+
+ # Apply edit_overview operations
+ for op, uri in resolved_ops.edit_overview_operations:
+ try:
+ await self._apply_edit_overview(op, uri, ctx)
+ result.add_edited(uri)
+ except Exception as e:
+ logger.error(f"Failed to edit overview {uri}: {e}")
+ result.add_error(uri, e)
+
+ # Apply delete operations
+ for _uri_str, uri in resolved_ops.delete_operations:
+ try:
+ await self._apply_delete(uri, ctx)
+ result.add_deleted(uri)
+ except Exception as e:
+ logger.error(f"Failed to delete memory {uri}: {e}")
+ result.add_error(uri, e)
+
+ logger.info(f"Memory operations applied: {result.summary()}")
+ return result
+
+ async def _apply_write(self, flat_model: Any, uri: str, ctx: RequestContext) -> None:
+ """Apply write operation from a flat model."""
+ viking_fs = self._get_viking_fs()
+
+ # Convert model to dict
+ model_dict = flat_model_to_dict(flat_model)
+
+ # Set timestamps if not provided
+ now = datetime.utcnow()
+ created_at = model_dict.get("created_at", now)
+ updated_at = model_dict.get("updated_at", now)
+
+ # Extract content - priority: model_dict["content"]
+ content = model_dict.pop("content", None) or ""
+
+ # Get memory type schema to know which fields are business fields vs metadata
+ memory_type_str = model_dict.get("memory_type")
+ field_schema_map: Dict[str, MemoryField] = {}
+ business_fields: Dict[str, Any] = {}
+
+ if self._registry and memory_type_str:
+ schema = self._registry.get(memory_type_str)
+ if schema:
+ field_schema_map = {f.name: f for f in schema.fields}
+ # Extract business fields (those defined in the schema)
+ for field_name in field_schema_map:
+ if field_name in model_dict:
+ business_fields[field_name] = model_dict[field_name]
+
+ # Collect metadata - only include business fields (from schema, except content)
+ metadata = business_fields.copy()
+
+ # Serialize content with metadata
+ full_content = serialize_with_metadata(content, metadata)
+
+ # Write content to VikingFS
+ # VikingFS automatically handles L0/L1/L2 and vector index updates
+ await viking_fs.write_file(uri, full_content, ctx=ctx)
+ logger.debug(f"Written memory: {uri}")
+
+ async def _apply_edit(self, flat_model: Any, uri: str, ctx: RequestContext) -> None:
+ """Apply edit operation from a flat model."""
+ viking_fs = self._get_viking_fs()
+
+ # Read current memory
+ try:
+ current_full_content = await viking_fs.read_file(uri, ctx=ctx) or ""
+ except NotFoundError:
+ logger.warning(f"Memory not found for edit: {uri}")
+ return
+
+ # Deserialize content and metadata
+ current_plain_content, current_metadata = deserialize_full(current_full_content)
+
+ # Convert flat model to dict
+ model_dict = flat_model_to_dict(flat_model)
+
+ # Get memory type schema
+ memory_type_str = model_dict.get("memory_type") or current_metadata.get("memory_type")
+ field_schema_map: Dict[str, MemoryField] = {}
+
+ if self._registry and memory_type_str:
+ schema = self._registry.get(memory_type_str)
+ if schema:
+ field_schema_map = {f.name: f for f in schema.fields}
+
+ # Apply all fields (including content) through MergeOp
+ new_plain_content = current_plain_content
+ metadata = current_metadata or {}
+
+ # Handle schema-defined fields first
+ for field_name, field_schema in field_schema_map.items():
+ if field_name in model_dict:
+ patch_value = model_dict[field_name]
+
+ # Get current value
+ if field_name == "content":
+ current_value = current_plain_content
+ else:
+ current_value = metadata.get(field_name)
+
+ # Create MergeOp and apply
+ merge_op = MergeOpFactory.from_field(field_schema)
+ new_value = merge_op.apply(current_value, patch_value)
+
+ # Update the field
+ if field_name == "content":
+ new_plain_content = new_value
+ else:
+ metadata[field_name] = new_value
+
+ # Special case: handle content field even without schema (for backward compatibility/testing)
+ if "content" in model_dict and "content" not in field_schema_map:
+ from openviking.session.memory.merge_op import PatchOp
+ from openviking.session.memory.merge_op.base import FieldType
+ patch_value = model_dict["content"]
+ merge_op = PatchOp(FieldType.STRING)
+ new_plain_content = merge_op.apply(current_plain_content, patch_value)
+
+ # Re-serialize with updated content and metadata
+ new_full_content = serialize_with_metadata(new_plain_content, metadata)
+
+ # Print diff of the edit
+ self._print_diff(uri, current_plain_content, new_plain_content)
+
+ await viking_fs.write_file(uri, new_full_content, ctx=ctx)
+ logger.debug(f"Edited memory: {uri}")
+
+ async def _apply_delete(self, uri: str, ctx: RequestContext) -> None:
+ """Apply delete operation (uri is already a string)."""
+ viking_fs = self._get_viking_fs()
+
+ # Delete from VikingFS
+ # VikingFS automatically handles vector index cleanup
+ try:
+ await viking_fs.rm(uri, recursive=False, ctx=ctx)
+ logger.debug(f"Deleted memory: {uri}")
+ except NotFoundError:
+ logger.warning(f"Memory not found for delete: {uri}")
+ # Idempotent - deleting non-existent file succeeds
+
+ async def _apply_edit_overview(self, overview_model: Any, uri: str, ctx: RequestContext) -> None:
+ """
+ Apply edit operation for .overview.md file.
+
+ Args:
+ overview_model: Overview edit model with memory_type and overview fields
+ uri: URI of the .overview.md file
+ ctx: Request context
+ """
+ viking_fs = self._get_viking_fs()
+
+ # Get overview value from model
+ if hasattr(overview_model, 'overview'):
+ overview_value = overview_model.overview
+ elif isinstance(overview_model, dict):
+ overview_value = overview_model.get('overview')
+ else:
+ raise ValueError("overview_model must have overview field")
+
+ # Read current overview if exists
+ current_overview = ""
+ try:
+ current_overview = await viking_fs.read_file(uri, ctx=ctx) or ""
+ except NotFoundError:
+ # File doesn't exist yet, start with empty content
+ logger.debug(f"Overview file does not exist yet: {uri}")
+
+ # Apply patch or replace based on overview_value type
+ new_overview = current_overview
+ if overview_value is None:
+ # No overview provided, nothing to do
+ logger.debug(f"No overview value provided, skipping edit")
+ return
+ elif isinstance(overview_value, str):
+ # Direct string - replace
+ new_overview = overview_value
+ elif isinstance(overview_value, dict):
+ # Dict format - convert to StrPatch if needed
+ if 'blocks' in overview_value:
+ # Already in StrPatch format
+ blocks = [SearchReplaceBlock(**block) for block in overview_value['blocks']]
+ str_patch = StrPatch(blocks=blocks)
+ else:
+ # Unexpected format
+ raise ValueError(f"Invalid overview patch format: {overview_value}")
+
+ # Apply patch
+ patch_op = PatchOp(FieldType.STRING)
+ new_overview = patch_op.apply(current_overview, str_patch)
+ else:
+ # StrPatch object
+ patch_op = PatchOp(FieldType.STRING)
+ new_overview = patch_op.apply(current_overview, overview_value)
+
+ # Print diff of the edit
+ self._print_diff(uri, current_overview, new_overview)
+
+ # Write new overview
+ await viking_fs.write_file(uri, new_overview, ctx=ctx)
+ logger.debug(f"Edited overview: {uri}")
+
+ def _print_diff(self, uri: str, old_content: str, new_content: str) -> None:
+ """Print a diff of the memory edit using diff_match_patch."""
+ try:
+ from diff_match_patch import diff_match_patch
+ dmp = diff_match_patch()
+
+ # Compute character-level diff
+ diffs = dmp.diff_main(old_content, new_content)
+ dmp.diff_cleanupSemantic(diffs)
+
+ # Build formatted output
+ lines = []
+ lines.append(f"\n{'=' * 60}")
+ lines.append(f"MEMORY EDIT: {uri}")
+ lines.append(f"{'=' * 60}")
+
+ # ANSI styles
+ STYLE_DELETE = "\033[9m\033[31m" # 删除线 + 红色
+ STYLE_INSERT = "\033[32m" # 绿色
+ STYLE_RESET = "\033[0m"
+
+ for op, text in diffs:
+ if op == 0: # Equal - 正常显示
+ lines.append(text)
+ elif op == -1: # Delete - 红色删除线
+ lines.append(f"{STYLE_DELETE}{text}{STYLE_RESET}")
+ elif op == 1: # Insert - 绿色高亮
+ lines.append(f"{STYLE_INSERT}{text}{STYLE_RESET}")
+
+ lines.append(f"{'=' * 60}\n")
+
+ # Print directly
+ print("\n".join(lines))
+ except ImportError:
+ # Fallback: just show file name
+ logger.debug(f"diff_match_patch not available, skipping diff for {uri}")
+ except Exception as e:
+ logger.debug(f"Failed to print diff for {uri}: {e}")
diff --git a/openviking/session/memory/merge_op/__init__.py b/openviking/session/memory/merge_op/__init__.py
new file mode 100644
index 000000000..e590d05b3
--- /dev/null
+++ b/openviking/session/memory/merge_op/__init__.py
@@ -0,0 +1,37 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: Apache-2.0
+"""
+Merge operation implementations.
+"""
+
+from openviking.session.memory.merge_op.base import (
+ MergeOp,
+ MergeOpBase,
+ FieldType,
+ SearchReplaceBlock,
+ StrPatch,
+)
+from openviking.session.memory.merge_op.patch import PatchOp
+from openviking.session.memory.merge_op.sum import SumOp
+from openviking.session.memory.merge_op.immutable import ImmutableOp
+from openviking.session.memory.merge_op.factory import MergeOpFactory
+from openviking.session.memory.merge_op.patch_handler import (
+ MemoryPatchHandler,
+ PatchParseError,
+ apply_str_patch,
+)
+
+__all__ = [
+ "MergeOp",
+ "MergeOpBase",
+ "FieldType",
+ "SearchReplaceBlock",
+ "StrPatch",
+ "PatchOp",
+ "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
new file mode 100644
index 000000000..35c29c90b
--- /dev/null
+++ b/openviking/session/memory/merge_op/base.py
@@ -0,0 +1,121 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: Apache-2.0
+"""
+Merge operation base classes and registry.
+"""
+
+from abc import ABC, abstractmethod
+from enum import Enum
+from typing import Any, Dict, List, Optional, Type
+
+from pydantic import BaseModel, Field
+
+
+class FieldType(str, Enum):
+ """Field type enumeration."""
+
+ STRING = "string"
+ INT64 = "int64"
+ FLOAT32 = "float32"
+ BOOL = "bool"
+
+
+# ============================================================================
+# Field Type Mapping (shared across all merge operations)
+# ============================================================================
+
+_FIELD_TYPE_TO_PYTHON: Dict[FieldType, Type[Any]] = {
+ FieldType.STRING: str,
+ FieldType.INT64: int,
+ FieldType.FLOAT32: float,
+ FieldType.BOOL: bool,
+}
+
+
+def get_python_type_for_field(field_type: FieldType, default: Type[Any] = str) -> Type[Any]:
+ """Map FieldType to corresponding Python type.
+
+ Args:
+ field_type: The FieldType enum value
+ default: Default type if field_type is not recognized
+
+ Returns:
+ Corresponding Python type (str, int, float, or bool)
+ """
+ return _FIELD_TYPE_TO_PYTHON.get(field_type, default)
+
+
+# ============================================================================
+# Structured Patch Models
+# ============================================================================
+
+
+class SearchReplaceBlock(BaseModel):
+ """Single SEARCH/REPLACE block for string patches."""
+
+ search: str = Field(..., description="Content to search for")
+ replace: str = Field(..., description="Content to replace with")
+ start_line: Optional[int] = Field(None, description="Starting line number hint")
+
+
+class StrPatch(BaseModel):
+ """String patch containing multiple SEARCH/REPLACE blocks.
+
+ All string fields with merge_op=patch use this structure.
+ """
+
+ blocks: List[SearchReplaceBlock] = Field(
+ default_factory=list,
+ description="List of SEARCH/REPLACE blocks to apply"
+ )
+
+
+class MergeOp(str, Enum):
+ """Merge operation enumeration."""
+
+ PATCH = "patch"
+ SUM = "sum"
+ IMMUTABLE = "immutable"
+
+
+class MergeOpBase(ABC):
+ """Abstract base class for merge operations."""
+
+ op_type: MergeOp
+
+ @abstractmethod
+ def get_output_schema_type(self, field_type: FieldType) -> Type[Any]:
+ """Get the Python type for this merge operation's output schema.
+
+ Args:
+ field_type: The underlying field type
+
+ Returns:
+ Python type to use in the Pydantic schema
+ """
+ pass
+
+ @abstractmethod
+ def get_output_schema_description(self, field_description: str) -> str:
+ """Get the description for this merge operation's output schema.
+
+ Args:
+ field_description: The original field description
+
+ Returns:
+ Description string to use in the Pydantic schema
+ """
+ pass
+
+ @abstractmethod
+ def apply(self, current_value: Any, patch_value: Any) -> Any:
+ """Apply this merge operation.
+
+ Args:
+ current_value: Current field value
+ patch_value: Patch value from the operation
+
+ Returns:
+ New field value after applying the merge
+ """
+ pass
diff --git a/openviking/session/memory/merge_op/factory.py b/openviking/session/memory/merge_op/factory.py
new file mode 100644
index 000000000..0d048bece
--- /dev/null
+++ b/openviking/session/memory/merge_op/factory.py
@@ -0,0 +1,52 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: Apache-2.0
+"""
+Factory for creating MergeOp instances.
+"""
+
+from typing import TYPE_CHECKING
+
+from openviking.session.memory.merge_op.base import MergeOp, MergeOpBase, FieldType
+from openviking.session.memory.merge_op.patch import PatchOp
+from openviking.session.memory.merge_op.sum import SumOp
+from openviking.session.memory.merge_op.immutable import ImmutableOp
+
+if TYPE_CHECKING:
+ from openviking.session.memory.dataclass import MemoryField
+
+
+class MergeOpFactory:
+ """Factory for creating MergeOp instances."""
+
+ @staticmethod
+ def create(merge_op: MergeOp, field_type: FieldType) -> MergeOpBase:
+ """Create a MergeOp instance from a MergeOp enum.
+
+ Args:
+ merge_op: The merge operation type
+ field_type: The underlying field type
+
+ Returns:
+ MergeOpBase implementation
+ """
+ if merge_op == MergeOp.PATCH:
+ return PatchOp(field_type)
+ elif merge_op == MergeOp.SUM:
+ return SumOp()
+ elif merge_op == MergeOp.IMMUTABLE:
+ return ImmutableOp()
+ else:
+ # Default to PatchOp
+ return PatchOp(field_type)
+
+ @staticmethod
+ def from_field(field: 'MemoryField') -> MergeOpBase:
+ """Create a MergeOp instance from a MemoryField.
+
+ Args:
+ field: The memory field definition
+
+ Returns:
+ MergeOpBase implementation
+ """
+ return MergeOpFactory.create(field.merge_op, field.field_type)
diff --git a/openviking/session/memory/merge_op/immutable.py b/openviking/session/memory/merge_op/immutable.py
new file mode 100644
index 000000000..67c24844a
--- /dev/null
+++ b/openviking/session/memory/merge_op/immutable.py
@@ -0,0 +1,32 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: Apache-2.0
+"""
+Immutable merge operation - field cannot be changed once set.
+"""
+
+from typing import Any, Type
+
+from openviking.session.memory.merge_op.base import (
+ MergeOp,
+ MergeOpBase,
+ FieldType,
+ get_python_type_for_field,
+)
+
+
+class ImmutableOp(MergeOpBase):
+ """Immutable merge operation - field cannot be changed once set."""
+
+ op_type = MergeOp.IMMUTABLE
+
+ def get_output_schema_type(self, field_type: FieldType) -> Type[Any]:
+ return get_python_type_for_field(field_type)
+
+ def get_output_schema_description(self, field_description: str) -> str:
+ return f"Immutable field '{field_description}' - can only be set once, cannot be modified"
+
+ def apply(self, current_value: Any, patch_value: Any) -> Any:
+ if current_value is None:
+ return patch_value
+ # Keep current value if already set
+ return current_value
diff --git a/openviking/session/memory/merge_op/patch.py b/openviking/session/memory/merge_op/patch.py
new file mode 100644
index 000000000..35827f60d
--- /dev/null
+++ b/openviking/session/memory/merge_op/patch.py
@@ -0,0 +1,96 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: Apache-2.0
+"""
+Patch merge operation - SEARCH/REPLACE for strings, direct replace for others.
+"""
+
+from typing import Any, Type, TYPE_CHECKING
+
+from openviking.session.memory.merge_op.base import (
+ MergeOp,
+ MergeOpBase,
+ FieldType,
+ StrPatch,
+ SearchReplaceBlock,
+ 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."""
+
+ op_type = MergeOp.PATCH
+
+ 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:
+ return StrPatch
+ return get_python_type_for_field(field_type)
+
+ 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."
+ return f"Replace value for '{field_description}'"
+
+ def apply(self, current_value: Any, patch_value: Any) -> Any:
+ """
+ Apply patch operation.
+
+ For string fields (content):
+ - StrPatch: use apply_str_patch()
+ - str with "<<<<<<< SEARCH": use MemoryPatchHandler
+ - other str: full replacement
+
+ For non-string fields:
+ - Just replace with patch_value
+ """
+ # For non-string fields, just replace
+ if self._field_type != FieldType.STRING:
+ return patch_value
+
+ # For string fields, handle various patch formats
+ from openviking.session.memory.merge_op.patch_handler import (
+ MemoryPatchHandler,
+ apply_str_patch,
+ )
+
+ current_str = current_value or ""
+
+ # Case 1: StrPatch object
+ if isinstance(patch_value, StrPatch):
+ return apply_str_patch(current_str, patch_value)
+
+ # Case 2: dict form of StrPatch (from JSON parsing)
+ if isinstance(patch_value, dict):
+ try:
+ if "blocks" in patch_value:
+ blocks = []
+ for block_dict in patch_value["blocks"]:
+ if isinstance(block_dict, dict):
+ blocks.append(SearchReplaceBlock(**block_dict))
+ else:
+ blocks.append(block_dict)
+ patch_value = StrPatch(blocks=blocks)
+ return apply_str_patch(current_str, patch_value)
+ except Exception:
+ # If conversion fails, treat as simple replacement
+ return str(patch_value) if patch_value is not None else ""
+
+ # Case 3: string with SEARCH/REPLACE markers
+ if isinstance(patch_value, str):
+ if "<<<<<<< SEARCH" in patch_value:
+ if self._patch_handler is None:
+ self._patch_handler = MemoryPatchHandler()
+ return self._patch_handler.apply_content_patch(current_str, patch_value)
+ else:
+ # Simple full replacement
+ return patch_value
+
+ # Fallback: just return patch_value as-is
+ return patch_value
diff --git a/openviking/session/memory/merge_op/patch_handler.py b/openviking/session/memory/merge_op/patch_handler.py
new file mode 100644
index 000000000..aa5d44a7e
--- /dev/null
+++ b/openviking/session/memory/merge_op/patch_handler.py
@@ -0,0 +1,1087 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: Apache-2.0
+"""
+Patch handler for memory updates.
+
+Supports two modes:
+1. Content patch: SEARCH/REPLACE format (enhanced with RooCode's multi-search-replace strategy)
+2. Field patch: Field-level updates based on merge_op
+
+Enhanced features from RooCode:
+- Support for multiple SEARCH/REPLACE blocks
+- Fuzzy matching (fuzzy matching)
+- Line number handling (add, strip, detect)
+- Marker escaping support
+- Aggressive line number stripping fallback
+- Detailed validation and error messages
+- Indentation preservation
+- Levenshtein distance similarity calculation
+"""
+
+import re
+from dataclasses import dataclass
+from enum import Enum
+from typing import Any, Dict, List, Optional, Tuple, TYPE_CHECKING
+
+from openviking.session.memory.merge_op.base import SearchReplaceBlock, StrPatch
+from openviking.session.memory.merge_op.factory import MergeOpFactory
+from openviking_cli.utils import get_logger
+
+if TYPE_CHECKING:
+ from openviking.session.memory.dataclass import MemoryField
+
+logger = get_logger(__name__)
+
+
+class PatchParseError(Exception):
+ """Error parsing patch content."""
+ pass
+
+
+# ============================================================================
+# Core Algorithm Functions (from RooCode)
+# ============================================================================
+
+
+def levenshtein_distance(s1: str, s2: str) -> int:
+ """Calculate Levenshtein distance between two strings."""
+ if len(s1) < len(s2):
+ return levenshtein_distance(s2, s1)
+
+ if len(s2) == 0:
+ return len(s1)
+
+ previous_row = list(range(len(s2) + 1))
+ for i, c1 in enumerate(s1):
+ current_row = [i + 1]
+ for j, c2 in enumerate(s2):
+ insertions = previous_row[j + 1] + 1
+ deletions = current_row[j] + 1
+ substitutions = previous_row[j] + (c1 != c2)
+ current_row.append(min(insertions, deletions, substitutions))
+ previous_row = current_row
+
+ return previous_row[-1]
+
+
+def normalize_string(text: str) -> str:
+ """Normalize string by handling smart quotes and special characters."""
+ replacements = {
+ '\u2018': "'",
+ '\u2019': "'",
+ '\u201c': '"',
+ '\u201d': '"',
+ '\u00a0': ' ',
+ '\u200b': '',
+ '\u200c': '',
+ '\u200d': '',
+ '\u200e': '',
+ '\u200f': '',
+ '\ufeff': '',
+ }
+ for old, new in replacements.items():
+ text = text.replace(old, new)
+ return text
+
+
+def get_similarity(original: str, search: str) -> float:
+ """Calculate similarity ratio between two strings (0 to 1)."""
+ if search == "":
+ return 0.0
+
+ normalized_original = normalize_string(original)
+ normalized_search = normalize_string(search)
+
+ if normalized_original == normalized_search:
+ return 1.0
+
+ dist = levenshtein_distance(normalized_original, normalized_search)
+ max_length = max(len(normalized_original), len(normalized_search))
+
+ return 1.0 - (dist / max_length) if max_length > 0 else 1.0
+
+
+def fuzzy_search(
+ lines: List[str],
+ search_chunk: str,
+ start_index: int,
+ end_index: int
+) -> Dict[str, Any]:
+ """
+ Perform a "middle-out" search to find the slice most similar to search_chunk.
+
+ Returns dict with bestScore, bestMatchIndex, bestMatchContent
+ """
+ best_score = 0.0
+ best_match_index = -1
+ best_match_content = ""
+ search_lines = search_chunk.split('\n')
+ search_len = len(search_lines)
+
+ mid_point = (start_index + end_index) // 2
+ left_index = mid_point
+ right_index = mid_point + 1
+
+ while left_index >= start_index or right_index <= end_index - search_len:
+ if left_index >= start_index:
+ original_chunk = '\n'.join(lines[left_index:left_index + search_len])
+ similarity = get_similarity(original_chunk, search_chunk)
+ if similarity > best_score:
+ best_score = similarity
+ best_match_index = left_index
+ best_match_content = original_chunk
+ left_index -= 1
+
+ if right_index <= end_index - search_len:
+ original_chunk = '\n'.join(lines[right_index:right_index + search_len])
+ similarity = get_similarity(original_chunk, search_chunk)
+ if similarity > best_score:
+ best_score = similarity
+ best_match_index = right_index
+ best_match_content = original_chunk
+ right_index += 1
+
+ return {
+ 'bestScore': best_score,
+ 'bestMatchIndex': best_match_index,
+ 'bestMatchContent': best_match_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)
+# ============================================================================
+
+
+def unescape_markers(content: str) -> str:
+ """Unescape escaped markers in content."""
+ return (content
+ .replace(r'\<<<<<<<', '<<<<<<<')
+ .replace(r'\=======', '=======')
+ .replace(r'\>>>>>>>', '>>>>>>>')
+ .replace(r'\-------', '-------')
+ .replace(r'\:end_line:', ':end_line:')
+ .replace(r'\:start_line:', ':start_line:'))
+
+
+# ============================================================================
+# Validation (from RooCode)
+# ============================================================================
+
+
+class State(Enum):
+ START = 1
+ AFTER_SEARCH = 2
+ AFTER_SEPARATOR = 3
+
+
+def validate_marker_sequencing(diff_content: str) -> Dict[str, Any]:
+ """Validate the marker sequencing in diff content."""
+ state = {'current': State.START, 'line': 0}
+
+ SEARCH_PATTERN = r'^<<<<<<< SEARCH>?$'
+ SEP = "======="
+ REPLACE = ">>>>>>> REPLACE"
+ SEARCH_PREFIX = "<<<<<<<"
+ REPLACE_PREFIX = ">>>>>>>"
+
+ def report_merge_conflict_error(found: str, _expected: str) -> Dict[str, Any]:
+ return {
+ 'success': False,
+ 'error': (
+ f"ERROR: Special marker '{found}' found in your diff content at line {state['line']}:\n"
+ "\n"
+ f"When removing merge conflict markers like '{found}' from files, you MUST escape them\n"
+ "in your SEARCH section by prepending a backslash (\\) at the beginning of the line:\n"
+ "\n"
+ "CORRECT FORMAT:\n\n"
+ "<<<<<<< SEARCH\n"
+ "content before\n"
+ f"\\{found} <-- Note the backslash here in this example\n"
+ "content after\n"
+ "=======\n"
+ "replacement content\n"
+ ">>>>>>> REPLACE\n"
+ "\n"
+ "Without escaping, the system confuses your content with diff syntax markers.\n"
+ "You may use multiple diff blocks in a single diff request, but ANY of ONLY the following "
+ "separators that occur within SEARCH or REPLACE content must be escaped, as follows:\n"
+ f"\\{SEARCH_PREFIX}\n"
+ f"\\{SEP}\n"
+ f"\\{REPLACE}\n"
+ )
+ }
+
+ def report_invalid_diff_error(found: str, expected: str) -> Dict[str, Any]:
+ return {
+ 'success': False,
+ 'error': (
+ f"ERROR: Diff block is malformed: marker '{found}' found in your diff content at line {state['line']}. "
+ f"Expected: {expected}\n"
+ "\n"
+ "CORRECT FORMAT:\n\n"
+ "<<<<<<< SEARCH\n"
+ ":start_line: (required) The line number of original content where the search block starts.\n"
+ "-------\n"
+ "[exact content to find including whitespace]\n"
+ "=======\n"
+ "[new content to replace with]\n"
+ ">>>>>>> REPLACE\n"
+ )
+ }
+
+ def report_line_marker_in_replace_error(marker: str) -> Dict[str, Any]:
+ return {
+ 'success': False,
+ 'error': (
+ f"ERROR: Invalid line marker '{marker}' found in REPLACE section at line {state['line']}\n"
+ "\n"
+ "Line markers (:start_line: and :end_line:) are only allowed in SEARCH sections.\n"
+ "\n"
+ "CORRECT FORMAT:\n"
+ "<<<<<<< SEARCH\n"
+ ":start_line:5\n"
+ "content to find\n"
+ "=======\n"
+ "replacement content\n"
+ ">>>>>>> REPLACE\n"
+ "\n"
+ "INCORRECT FORMAT:\n"
+ "<<<<<<< SEARCH\n"
+ "content to find\n"
+ "=======\n"
+ ":start_line:5 <-- Invalid location\n"
+ "replacement content\n"
+ ">>>>>>> REPLACE\n"
+ )
+ }
+
+ lines = diff_content.split('\n')
+ search_count = sum(1 for l in lines if re.match(SEARCH_PATTERN, l.strip()))
+ sep_count = sum(1 for l in lines if l.strip() == SEP)
+ replace_count = sum(1 for l in lines if l.strip() == REPLACE)
+
+ likely_bad_structure = search_count != replace_count or sep_count < search_count
+
+ for line in diff_content.split('\n'):
+ state['line'] += 1
+ marker = line.strip()
+
+ # Check for line markers in REPLACE sections (but allow escaped ones)
+ if state['current'] == State.AFTER_SEPARATOR:
+ if marker.startswith(":start_line:") and not line.strip().startswith(r"\:start_line:"):
+ return report_line_marker_in_replace_error(":start_line:")
+ if marker.startswith(":end_line:") and not line.strip().startswith(r"\:end_line:"):
+ return report_line_marker_in_replace_error(":end_line:")
+
+ if state['current'] == State.START:
+ if marker == SEP:
+ return (report_invalid_diff_error(SEP, "SEARCH")
+ if likely_bad_structure
+ else report_merge_conflict_error(SEP, "SEARCH"))
+ if marker == REPLACE:
+ return report_invalid_diff_error(REPLACE, "SEARCH")
+ if marker.startswith(REPLACE_PREFIX):
+ return report_merge_conflict_error(marker, "SEARCH")
+ if re.match(SEARCH_PATTERN, marker):
+ state['current'] = State.AFTER_SEARCH
+ elif marker.startswith(SEARCH_PREFIX):
+ return report_merge_conflict_error(marker, "SEARCH")
+
+ elif state['current'] == State.AFTER_SEARCH:
+ if re.match(SEARCH_PATTERN, marker):
+ return report_invalid_diff_error("SEARCH", SEP)
+ if marker.startswith(SEARCH_PREFIX):
+ return report_merge_conflict_error(marker, "SEARCH")
+ if marker == REPLACE:
+ return report_invalid_diff_error(REPLACE, SEP)
+ if marker.startswith(REPLACE_PREFIX):
+ return report_merge_conflict_error(marker, "SEARCH")
+ if marker == SEP:
+ state['current'] = State.AFTER_SEPARATOR
+
+ elif state['current'] == State.AFTER_SEPARATOR:
+ if re.match(SEARCH_PATTERN, marker):
+ return report_invalid_diff_error("SEARCH", REPLACE)
+ if marker.startswith(SEARCH_PREFIX):
+ return report_merge_conflict_error(marker, REPLACE)
+ if marker == SEP:
+ return (report_invalid_diff_error(SEP, REPLACE)
+ if likely_bad_structure
+ else report_merge_conflict_error(SEP, REPLACE))
+ if marker == REPLACE:
+ state['current'] = State.START
+ elif marker.startswith(REPLACE_PREFIX):
+ return report_merge_conflict_error(marker, REPLACE)
+
+ if state['current'] == State.START:
+ return {'success': True}
+ else:
+ expected = "=======" if state['current'] == State.AFTER_SEARCH else ">>>>>>> REPLACE"
+ return {
+ 'success': False,
+ 'error': f"ERROR: Unexpected end of sequence: Expected '{expected}' was not found."
+ }
+
+
+# ============================================================================
+# Result Classes (from RooCode)
+# ============================================================================
+
+
+@dataclass
+class DiffResult:
+ """Result of applying a diff."""
+ success: bool
+ content: Optional[str] = None
+ error: Optional[str] = None
+ fail_parts: Optional[List[Dict]] = None
+
+
+# ============================================================================
+# Main Strategy Class (from RooCode)
+# ============================================================================
+
+
+class MultiSearchReplaceDiffStrategy:
+ """Multi-Search-Replace diff strategy implementation."""
+
+ def __init__(self, fuzzy_threshold: float = 1.0, buffer_lines: int = 40):
+ """
+ Initialize the strategy.
+
+ Args:
+ fuzzy_threshold: Similarity threshold for fuzzy matching (0.0 to 1.0)
+ buffer_lines: Number of extra context lines to search around target
+ """
+ self.fuzzy_threshold = fuzzy_threshold
+ self.buffer_lines = buffer_lines
+
+ def apply_diff(
+ self,
+ original_content: str,
+ diff_content: str,
+ _param_start_line: Optional[int] = None,
+ _param_end_line: Optional[int] = None,
+ ) -> DiffResult:
+ """
+ Apply a multi-search-replace diff to the original content.
+
+ Args:
+ original_content: The original file content
+ diff_content: The multi-search-replace diff content
+ _param_start_line: (unused) Reserved for future use
+ _param_end_line: (unused) Reserved for future use
+
+ Returns:
+ DiffResult with success status and modified content
+ """
+ # Validate marker sequencing
+ valid_seq = validate_marker_sequencing(diff_content)
+ if not valid_seq['success']:
+ return DiffResult(success=False, error=valid_seq['error'])
+
+ # Parse diff blocks
+ matches = self._parse_diff_blocks(diff_content)
+ if not matches:
+ return DiffResult(
+ success=True,
+ content=original_content
+ )
+
+ # Detect line ending from original content
+ line_ending = '\r\n' if '\r\n' in original_content else '\n'
+ result_lines = re.split(r'\r?\n', original_content)
+ delta = 0
+ diff_results = []
+ applied_count = 0
+
+ # Sort replacements by start_line
+ replacements = [
+ {
+ 'startLine': int(match.get('startLine', 0)),
+ 'searchContent': match.get('searchContent', ''),
+ 'replaceContent': match.get('replaceContent', '')
+ }
+ for match in matches
+ ]
+ replacements.sort(key=lambda x: x['startLine'])
+
+ for replacement in replacements:
+ search_content = replacement['searchContent']
+ replace_content = replacement['replaceContent']
+ start_line = replacement['startLine'] + (replacement['startLine'] if replacement['startLine'] != 0 else 0)
+
+ # Unescape markers
+ search_content = unescape_markers(search_content)
+ replace_content = unescape_markers(replace_content)
+
+ # Strip line numbers if present
+ has_all_line_numbers = (
+ (every_line_has_line_numbers(search_content) and every_line_has_line_numbers(replace_content)) 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())
+
+ if has_all_line_numbers:
+ search_content = strip_line_numbers(search_content)
+ replace_content = strip_line_numbers(replace_content)
+
+ # If search and replace are identical, treat as success (no changes needed)
+ if search_content == replace_content:
+ diff_results.append({
+ 'success': True,
+ 'message': 'Search and replace content are identical - no changes needed'
+ })
+ continue
+
+ # Split content into lines
+ search_lines = [] if search_content == "" else search_content.split('\n')
+ replace_lines = [] if replace_content == "" else replace_content.split('\n')
+
+ # Validate search content is not empty
+ if len(search_lines) == 0:
+ diff_results.append({
+ 'success': False,
+ 'error': (
+ "Empty search content is not allowed\n\n"
+ "Debug Info:\n"
+ "- Search content cannot be empty\n"
+ "- For insertions, provide a specific line using :start_line: "
+ "and include content to search for\n"
+ "- For example, match a single line to insert before/after it"
+ )
+ })
+ continue
+
+ end_line = replacement['startLine'] + len(search_lines) - 1
+
+ # Initialize search variables
+ match_index = -1
+ best_match_score = 0.0
+ best_match_content = ""
+ search_chunk = '\n'.join(search_lines)
+
+ # Determine search bounds
+ search_start_index = 0
+ search_end_index = len(result_lines)
+
+ # Validate and handle line range if provided
+ if start_line:
+ exact_start_index = start_line - 1
+ search_len = len(search_lines)
+ exact_end_index = exact_start_index + search_len - 1
+
+ # Try exact match first
+ original_chunk = '\n'.join(result_lines[exact_start_index:exact_end_index + 1])
+ similarity = get_similarity(original_chunk, search_chunk)
+ if similarity >= self.fuzzy_threshold:
+ match_index = exact_start_index
+ best_match_score = similarity
+ best_match_content = original_chunk
+ else:
+ # Set bounds for buffered search
+ search_start_index = max(0, start_line - (self.buffer_lines + 1))
+ search_end_index = min(len(result_lines), start_line + len(search_lines) + self.buffer_lines)
+
+ # If no match found yet, try middle-out search within bounds
+ if match_index == -1:
+ fuzzy_result = fuzzy_search(result_lines, search_chunk, search_start_index, search_end_index)
+ match_index = fuzzy_result['bestMatchIndex']
+ best_match_score = fuzzy_result['bestScore']
+ best_match_content = fuzzy_result['bestMatchContent']
+
+ # Try aggressive line number stripping as a fallback
+ if match_index == -1 or best_match_score < self.fuzzy_threshold:
+ aggressive_search_content = strip_line_numbers(search_content, aggressive=True)
+ aggressive_replace_content = strip_line_numbers(replace_content, aggressive=True)
+
+ aggressive_search_lines = [] if aggressive_search_content == "" else aggressive_search_content.split('\n')
+ aggressive_search_chunk = '\n'.join(aggressive_search_lines)
+
+ # Try middle-out search again with aggressive stripped content
+ fuzzy_result = fuzzy_search(result_lines, aggressive_search_chunk, search_start_index, search_end_index)
+ if fuzzy_result['bestMatchIndex'] != -1 and fuzzy_result['bestScore'] >= self.fuzzy_threshold:
+ match_index = fuzzy_result['bestMatchIndex']
+ best_match_score = fuzzy_result['bestScore']
+ best_match_content = fuzzy_result['bestMatchContent']
+ # Replace with stripped versions
+ search_content = aggressive_search_content
+ replace_content = aggressive_replace_content
+ search_lines = aggressive_search_lines
+ replace_lines = [] if replace_content == "" else replace_content.split('\n')
+ else:
+ # No match found with either method
+ if start_line and end_line:
+ original_section = '\n\nOriginal Content:\n' + add_line_numbers(
+ '\n'.join(result_lines[
+ max(0, start_line - 1 - self.buffer_lines):
+ min(len(result_lines), end_line + self.buffer_lines)
+ ]),
+ max(1, start_line - self.buffer_lines)
+ )
+ else:
+ original_section = '\n\nOriginal Content:\n' + add_line_numbers('\n'.join(result_lines))
+
+ best_match_section = (
+ '\n\nBest Match Found:\n' + add_line_numbers(best_match_content, match_index + 1)
+ if best_match_content
+ else '\n\nBest Match Found:\n(no match)'
+ )
+
+ line_range = f" at line: {start_line}" if start_line else ""
+
+ diff_results.append({
+ 'success': False,
+ 'error': (
+ f"No sufficiently similar match found{line_range} "
+ f"({int(best_match_score * 100)}% similar, "
+ f"needs {int(self.fuzzy_threshold * 100)}%)\n\n"
+ "Debug Info:\n"
+ f"- Similarity Score: {int(best_match_score * 100)}%\n"
+ f"- Required Threshold: {int(self.fuzzy_threshold * 100)}%\n"
+ f"- Search Range: {f'starting at line {start_line}' if start_line else 'start to end'}\n"
+ "- Tried both standard and aggressive line number stripping\n"
+ "- Tip: Use read_file tool to get the latest content of the file before "
+ "attempting to use apply_diff tool again, as file content may have changed\n\n"
+ f"Search Content:\n{search_chunk}"
+ f"{best_match_section}"
+ f"{original_section}"
+ )
+ })
+ continue
+
+ # Get matched lines from original content
+ matched_lines = result_lines[match_index:match_index + len(search_lines)]
+
+ # Get exact indentation of each line
+ original_indents = []
+ for line in matched_lines:
+ match = re.match(r'^[\t ]*', line)
+ original_indents.append(match.group(0) if match else "")
+
+ search_indents = []
+ for line in search_lines:
+ match = re.match(r'^[\t ]*', line)
+ search_indents.append(match.group(0) if match else "")
+
+ # Apply replacement while preserving exact indentation
+ # For each replace line, use the corresponding original matched line's indent
+ indented_replace_lines = []
+ for i, line in enumerate(replace_lines):
+ # Get indent from corresponding original matched line
+ if i < len(original_indents):
+ matched_indent = original_indents[i]
+ else:
+ matched_indent = original_indents[0] if original_indents else ""
+
+ # Get indent from corresponding search line
+ if i < len(search_indents):
+ search_indent = search_indents[i]
+ else:
+ search_indent = search_indents[0] if search_indents else ""
+
+ # Get indent from current replace line
+ current_replace_match = re.match(r'^[\t ]*', line)
+ current_replace_indent = current_replace_match.group(0) if current_replace_match else ""
+
+ # Calculate relative indent level (how much deeper/shallower this line is compared to search)
+ relative_level = len(current_replace_indent) - len(search_indent)
+
+ # Apply same relative level to matched indent
+ if relative_level >= 0:
+ final_indent = matched_indent + current_replace_indent[len(search_indent):]
+ else:
+ final_indent = matched_indent[:max(0, len(matched_indent) + relative_level)]
+
+ # For empty lines, keep original indent with no content
+ if line.strip() == "":
+ indented_replace_lines.append(matched_indent)
+ else:
+ # Add line content (without its original indent, preserving internal whitespace)
+ line_content = line.lstrip(' \t')
+ indented_replace_lines.append(final_indent + line_content)
+
+ # Construct final content
+ before_match = result_lines[:match_index]
+ after_match = result_lines[match_index + len(search_lines):]
+ result_lines = before_match + indented_replace_lines + after_match
+ delta = delta - len(matched_lines) + len(replace_lines)
+ applied_count += 1
+
+ final_content = line_ending.join(result_lines)
+
+ # Check if all results are successful (including no-change cases)
+ all_successful = all(result.get('success', False) for result in diff_results)
+ has_failures = any(not result.get('success', False) for result in diff_results)
+
+ if applied_count == 0 and has_failures:
+ return DiffResult(success=False, fail_parts=diff_results)
+
+ # If no changes were applied but all results are successful (e.g., search==replace),
+ # return success with original content
+ if applied_count == 0 and all_successful:
+ return DiffResult(success=True, content=original_content, fail_parts=diff_results)
+
+ return DiffResult(
+ success=True,
+ content=final_content,
+ fail_parts=diff_results if diff_results else None
+ )
+
+ def _parse_diff_blocks(self, diff_content: str) -> List[Dict[str, Any]]:
+ """
+ Parse diff blocks from diff content.
+
+ Supports two formats:
+ 1. v1 format (with :start_line: and)-------
+ 2. v2 format (without :start_line: and)-------
+
+ Returns list of dicts with keys: startLine, searchContent, replaceContent
+ """
+ matches = []
+ blocks = diff_content.split('<<<<<<< SEARCH')
+
+ for block in blocks[1:]:
+ if '=======' not in block or '>>>>>>> REPLACE' not in block:
+ continue
+
+ # Split by =======
+ sep_parts = block.split('=======')
+ if len(sep_parts) < 2:
+ continue
+
+ before_sep = sep_parts[0]
+ after_sep = sep_parts[1]
+
+ # Split before_sep by -------
+ dash_parts = before_sep.split('-------')
+
+ if len(dash_parts) >= 2:
+ # v1 format: has -------
+ header = dash_parts[0]
+ search_content = dash_parts[1].lstrip('\n').rstrip('\n') if len(dash_parts) > 1 else ''
+ else:
+ # v2 format: no -------, entire before_sep is header + search content
+ # Extract :start_line: if present
+ header = ''
+ search_content = before_sep.lstrip('\n').rstrip('\n')
+
+ # Check if first line is :start_line:
+ lines = search_content.split('\n')
+ if lines and lines[0].startswith(':start_line:'):
+ header = lines[0]
+ search_content = '\n'.join(lines[1:])
+
+ replace_content = after_sep.split('>>>>>>> REPLACE')[0].lstrip('\n').rstrip('\n')
+
+ # Extract start_line from header
+ start_line = 0
+ for line in header.split('\n'):
+ if line.startswith(':start_line:'):
+ try:
+ start_line = int(line.split(':')[1].strip())
+ except:
+ pass
+
+ matches.append({
+ 'startLine': start_line,
+ 'searchContent': search_content,
+ 'replaceContent': replace_content
+ })
+
+ return matches
+
+
+# ============================================================================
+# MemoryPatchHandler
+# ============================================================================
+
+
+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:
+ # If failed but patch was valid (e.g., search content not found), fall back to appending
+ error_msg = result.error or "Unknown error"
+ logger.warning(f"Patch application failed, falling back to append: {error_msg}")
+ return original_content + "\n" + self._extract_replace_content(patch)
+
+ 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.
+
+ Args:
+ original_content: Original string content
+ patch: StrPatch model to apply
+
+ Returns:
+ Updated content after applying the patch
+ """
+ if not patch.blocks:
+ return original_content
+
+ # Directly convert StrPatch to internal format, skip string conversion
+ strategy = MultiSearchReplaceDiffStrategy()
+
+ # Convert StrPatch blocks to internal match format
+ matches = []
+ for block in patch.blocks:
+ matches.append({
+ 'startLine': block.start_line or 0,
+ 'searchContent': block.search,
+ 'replaceContent': block.replace
+ })
+
+ if not matches:
+ return original_content
+
+ # Apply using the same logic as apply_diff, but with pre-parsed matches
+ # Detect line ending from original content
+ line_ending = '\r\n' if '\r\n' in original_content else '\n'
+ result_lines = re.split(r'\r?\n', original_content)
+ diff_results = []
+ applied_count = 0
+
+ # Sort replacements by start_line
+ replacements = [
+ {
+ 'startLine': int(match.get('startLine', 0)),
+ 'searchContent': match.get('searchContent', ''),
+ 'replaceContent': match.get('replaceContent', '')
+ }
+ for match in matches
+ ]
+ replacements.sort(key=lambda x: x['startLine'])
+
+ for replacement in replacements:
+ search_content = replacement['searchContent']
+ replace_content = replacement['replaceContent']
+ start_line = replacement['startLine'] + (replacement['startLine'] if replacement['startLine'] != 0 else 0)
+
+ # Unescape markers
+ search_content = unescape_markers(search_content)
+ replace_content = unescape_markers(replace_content)
+
+ # Strip line numbers if present
+ has_all_line_numbers = (
+ (every_line_has_line_numbers(search_content) and every_line_has_line_numbers(replace_content)) 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())
+
+ if has_all_line_numbers:
+ search_content = strip_line_numbers(search_content)
+ replace_content = strip_line_numbers(replace_content)
+
+ # If search and replace are identical, treat as success (no changes needed)
+ if search_content == replace_content:
+ diff_results.append({
+ 'success': True,
+ 'message': 'Search and replace content are identical - no changes needed'
+ })
+ continue
+
+ # Split content into lines
+ search_lines = [] if search_content == "" else search_content.split('\n')
+ replace_lines = [] if replace_content == "" else replace_content.split('\n')
+
+ # Validate search content is not empty
+ if len(search_lines) == 0:
+ diff_results.append({
+ 'success': False,
+ 'error': (
+ "Empty search content is not allowed\n\n"
+ "Debug Info:\n"
+ "- Search content cannot be empty\n"
+ "- For insertions, provide a specific line using :start_line: "
+ "and include content to search for\n"
+ "- For example, match a single line to insert before/after it"
+ )
+ })
+ continue
+
+ # Initialize search variables
+ match_index = -1
+ best_match_score = 0.0
+ best_match_content = ""
+ search_chunk = '\n'.join(search_lines)
+
+ # Determine search bounds
+ search_start_index = 0
+ search_end_index = len(result_lines)
+
+ # Validate and handle line range if provided
+ if start_line:
+ exact_start_index = start_line - 1
+ search_len = len(search_lines)
+ exact_end_index = exact_start_index + search_len - 1
+
+ # Try exact match first
+ original_chunk = '\n'.join(result_lines[exact_start_index:exact_end_index + 1])
+ similarity = get_similarity(original_chunk, search_chunk)
+ if similarity >= strategy.fuzzy_threshold:
+ match_index = exact_start_index
+ best_match_score = similarity
+ best_match_content = original_chunk
+ else:
+ # Set bounds for buffered search
+ search_start_index = max(0, start_line - (strategy.buffer_lines + 1))
+ search_end_index = min(len(result_lines), start_line + len(search_lines) + strategy.buffer_lines)
+
+ # If no match found yet, try middle-out search within bounds
+ if match_index == -1:
+ fuzzy_result = fuzzy_search(result_lines, search_chunk, search_start_index, search_end_index)
+ match_index = fuzzy_result['bestMatchIndex']
+ best_match_score = fuzzy_result['bestScore']
+ best_match_content = fuzzy_result['bestMatchContent']
+
+ # Try aggressive line number stripping as a fallback
+ if match_index == -1 or best_match_score < strategy.fuzzy_threshold:
+ aggressive_search_content = strip_line_numbers(search_content, aggressive=True)
+ aggressive_replace_content = strip_line_numbers(replace_content, aggressive=True)
+
+ aggressive_search_lines = [] if aggressive_search_content == "" else aggressive_search_content.split('\n')
+ aggressive_search_chunk = '\n'.join(aggressive_search_lines)
+
+ # Try middle-out search again with aggressive stripped content
+ fuzzy_result = fuzzy_search(result_lines, aggressive_search_chunk, search_start_index, search_end_index)
+ if fuzzy_result['bestMatchIndex'] != -1 and fuzzy_result['bestScore'] >= strategy.fuzzy_threshold:
+ match_index = fuzzy_result['bestMatchIndex']
+ best_match_score = fuzzy_result['bestScore']
+ best_match_content = fuzzy_result['bestMatchContent']
+ # Replace with stripped versions
+ search_content = aggressive_search_content
+ replace_content = aggressive_replace_content
+ search_lines = aggressive_search_lines
+ replace_lines = [] if replace_content == "" else replace_content.split('\n')
+ else:
+ # No match found with either method
+ if start_line:
+ end_line = start_line + len(search_lines) - 1
+ original_section = '\n\nOriginal Content:\n' + add_line_numbers(
+ '\n'.join(result_lines[
+ max(0, start_line - 1 - strategy.buffer_lines):
+ min(len(result_lines), end_line + strategy.buffer_lines)
+ ]),
+ max(1, start_line - strategy.buffer_lines)
+ )
+ else:
+ original_section = '\n\nOriginal Content:\n' + add_line_numbers('\n'.join(result_lines))
+
+ best_match_section = (
+ '\n\nBest Match Found:\n' + add_line_numbers(best_match_content, match_index + 1)
+ if best_match_content
+ else '\n\nBest Match Found:\n(no match)'
+ )
+
+ line_range = f" at line: {start_line}" if start_line else ""
+
+ diff_results.append({
+ 'success': False,
+ 'error': (
+ f"No sufficiently similar match found{line_range} "
+ f"({int(best_match_score * 100)}% similar, "
+ f"needs {int(strategy.fuzzy_threshold * 100)}%)\n\n"
+ "Debug Info:\n"
+ f"- Similarity Score: {int(best_match_score * 100)}%\n"
+ f"- Required Threshold: {int(strategy.fuzzy_threshold * 100)}%\n"
+ f"- Search Range: {f'starting at line {start_line}' if start_line else 'start to end'}\n"
+ "- Tried both standard and aggressive line number stripping\n"
+ "- Tip: Use read_file tool to get the latest content of the file before "
+ "attempting to use apply_diff tool again, as file content may have changed\n\n"
+ f"Search Content:\n{search_chunk}"
+ f"{best_match_section}"
+ f"{original_section}"
+ )
+ })
+ continue
+
+ # Get matched lines from original content
+ matched_lines = result_lines[match_index:match_index + len(search_lines)]
+
+ # Get exact indentation of each line
+ original_indents = []
+ for line in matched_lines:
+ match = re.match(r'^[\t ]*', line)
+ original_indents.append(match.group(0) if match else "")
+
+ search_indents = []
+ for line in search_lines:
+ match = re.match(r'^[\t ]*', line)
+ search_indents.append(match.group(0) if match else "")
+
+ # Apply replacement while preserving exact indentation
+ # For each replace line, use the corresponding original matched line's indent
+ indented_replace_lines = []
+ for i, line in enumerate(replace_lines):
+ # Get indent from corresponding original matched line
+ if i < len(original_indents):
+ matched_indent = original_indents[i]
+ else:
+ matched_indent = original_indents[0] if original_indents else ""
+
+ # Get indent from corresponding search line
+ if i < len(search_indents):
+ search_indent = search_indents[i]
+ else:
+ search_indent = search_indents[0] if search_indents else ""
+
+ # Get indent from current replace line
+ current_replace_match = re.match(r'^[\t ]*', line)
+ current_replace_indent = current_replace_match.group(0) if current_replace_match else ""
+
+ # Calculate relative indent level (how much deeper/shallower this line is compared to search)
+ relative_level = len(current_replace_indent) - len(search_indent)
+
+ # Apply same relative level to matched indent
+ if relative_level >= 0:
+ final_indent = matched_indent + current_replace_indent[len(search_indent):]
+ else:
+ final_indent = matched_indent[:max(0, len(matched_indent) + relative_level)]
+
+ # For empty lines, keep original indent with no content
+ if line.strip() == "":
+ indented_replace_lines.append(matched_indent)
+ else:
+ # Add line content (without its original indent, preserving internal whitespace)
+ line_content = line.lstrip(' \t')
+ indented_replace_lines.append(final_indent + line_content)
+
+ # Construct final content
+ before_match = result_lines[:match_index]
+ after_match = result_lines[match_index + len(search_lines):]
+ result_lines = before_match + indented_replace_lines + after_match
+ applied_count += 1
+
+ final_content = line_ending.join(result_lines)
+
+ # Check if all results are successful (including no-change cases)
+ all_successful = all(result.get('success', False) for result in diff_results)
+ has_failures = any(not result.get('success', False) for result in diff_results)
+
+ if applied_count == 0 and has_failures:
+ # If failed, fall back to appending last replace content
+ logger.warning(f"Patch application failed, falling back to append")
+ last_replace = matches[-1].get('replaceContent', '') if matches else ''
+ return original_content + "\n" + last_replace
+
+ return final_content
+
+
+# Import MergeOp here to avoid circular import
+from openviking.session.memory.merge_op.base import MergeOp
diff --git a/openviking/session/memory/merge_op/sum.py b/openviking/session/memory/merge_op/sum.py
new file mode 100644
index 000000000..f6a38caf6
--- /dev/null
+++ b/openviking/session/memory/merge_op/sum.py
@@ -0,0 +1,36 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: Apache-2.0
+"""
+Sum merge operation - numeric addition.
+"""
+
+from typing import Any, Type
+
+from openviking.session.memory.merge_op.base import (
+ MergeOp,
+ MergeOpBase,
+ FieldType,
+ get_python_type_for_field,
+)
+
+
+class SumOp(MergeOpBase):
+ """Sum merge operation - numeric addition."""
+
+ op_type = MergeOp.SUM
+
+ def get_output_schema_type(self, field_type: FieldType) -> Type[Any]:
+ return get_python_type_for_field(field_type, default=int)
+
+ def get_output_schema_description(self, field_description: str) -> str:
+ return f"add for '{field_description}'"
+
+ def apply(self, current_value: Any, patch_value: Any) -> Any:
+ if current_value is None:
+ return patch_value
+ try:
+ if isinstance(current_value, float) or isinstance(patch_value, float):
+ return float(current_value) + float(patch_value)
+ return int(current_value) + int(patch_value)
+ except (ValueError, TypeError):
+ return patch_value
diff --git a/openviking/session/memory/schema_model_generator.py b/openviking/session/memory/schema_model_generator.py
new file mode 100644
index 000000000..cc7c742ef
--- /dev/null
+++ b/openviking/session/memory/schema_model_generator.py
@@ -0,0 +1,404 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: Apache-2.0
+"""
+Dynamic Pydantic model generator based on YAML schemas.
+
+Generates type-safe Pydantic models at runtime from MemoryTypeSchema
+definitions, with discriminator support for polymorphic fields.
+"""
+
+import re
+from datetime import datetime
+from typing import Any, Dict, List, Optional, Tuple, Type, Union
+
+from pydantic import BaseModel, Field, create_model
+from pydantic.config import ConfigDict
+from typing_extensions import Annotated, Literal
+
+from openviking.session.memory.dataclass import MemoryTypeSchema
+from openviking.session.memory.merge_op import MergeOp, MergeOpFactory
+from openviking.session.memory.merge_op.base import FieldType, StrPatch, get_python_type_for_field
+from openviking.session.memory.memory_type_registry import MemoryTypeRegistry
+from openviking_cli.utils import get_logger
+
+logger = get_logger(__name__)
+
+
+def to_pascal_case(s: str) -> str:
+ """Convert snake_case or kebab-case to PascalCase."""
+ # Replace non-alphanumeric with spaces
+ s = re.sub(r"[^a-zA-Z0-9]+", " ", s)
+ # Split and capitalize
+ words = s.strip().split()
+ return "".join(word.title() for word in words)
+
+
+class SchemaModelGenerator:
+ """
+ Dynamic Pydantic model generator from memory type schemas.
+
+ Creates type-safe models at runtime with discriminator support
+ for polymorphic memory data.
+ """
+
+ # Generic overview edit model shared by all memory types
+ _generic_overview_edit_model: Optional[Type[BaseModel]] = None
+
+ def __init__(self, registry: MemoryTypeRegistry):
+ self.registry = registry
+ self._model_cache: Dict[str, Type[BaseModel]] = {}
+ self._flat_data_models: Dict[str, Type[BaseModel]] = {}
+ self._overview_edit_models: Dict[str, Type[BaseModel]] = {}
+ self._union_model: Optional[Type[BaseModel]] = None
+ self._operations_model: Optional[Type[BaseModel]] = None
+
+ 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)
+
+ def create_flat_data_model(self, memory_type: MemoryTypeSchema) -> Type[BaseModel]:
+ """
+ Create a fully flat Pydantic model for a specific memory type.
+
+ The model includes:
+ - memory_type (literal discriminator)
+ - All business fields (with Union[base_type, patch_type] for mutable fields)
+ - Standard metadata fields (uri, name, abstract, overview, content, tags, created_at, updated_at)
+
+ Args:
+ memory_type: The memory type schema
+
+ Returns:
+ Dynamically created flat Pydantic model class
+ """
+ cache_key = memory_type.memory_type
+
+ if cache_key in self._flat_data_models:
+ return self._flat_data_models[cache_key]
+
+ model_name = f"{to_pascal_case(memory_type.memory_type)}Data"
+
+ # Build field definitions
+ field_definitions: Dict[str, Tuple[Type[Any], Any]] = {}
+
+ # Add memory_type as literal discriminator
+ field_definitions["memory_type"] = (
+ Literal[memory_type.memory_type], # type: ignore
+ Field(..., description=f"Memory type: {memory_type.memory_type}"),
+ )
+
+ # Add business fields from schema
+ for field in memory_type.fields:
+ base_type = self._map_field_type(field.field_type)
+ if field.merge_op == MergeOp.IMMUTABLE:
+ # Immutable fields: only base type, required
+ field_definitions[field.name] = (
+ base_type,
+ Field(..., 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)
+ field_definitions[field.name] = (
+ Optional[union_type],
+ Field(None, description=desc),
+ )
+ # Create the model
+ model = create_model(
+ model_name,
+ __config__=ConfigDict(extra="forbid"),
+ **field_definitions,
+ )
+
+ # Store in cache
+ self._flat_data_models[cache_key] = model
+ return model
+
+ def generate_all_models(self, include_disabled: bool = True) -> Dict[str, Type[BaseModel]]:
+ """
+ Generate flat data models for all registered memory types.
+
+ Args:
+ include_disabled: If True, include disabled memory types
+
+ Returns:
+ Dictionary mapping memory_type to generated model class
+ """
+ models: Dict[str, Type[BaseModel]] = {}
+ for memory_type in self.registry.list_all(include_disabled=include_disabled):
+ models[memory_type.memory_type] = self.create_flat_data_model(memory_type)
+ return models
+
+ def create_overview_edit_model(self, memory_type: MemoryTypeSchema) -> Type[BaseModel]:
+ """
+ Create a simplified model for editing .overview.md files.
+
+ The model includes:
+ - memory_type (literal discriminator)
+ - overview (Union[str, StrPatch])
+
+ Args:
+ memory_type: The memory type schema
+
+ Returns:
+ Dynamically created overview edit model class
+ """
+ # Use cached generic model
+ if SchemaModelGenerator._generic_overview_edit_model is not None:
+ return SchemaModelGenerator._generic_overview_edit_model
+
+ # Create generic model with string memory_type (not Literal)
+ model = create_model(
+ "GenericOverviewEdit",
+ __config__=ConfigDict(extra="forbid"),
+ memory_type=(
+ str,
+ Field(..., description="Memory type to edit (e.g., 'profile', 'skills')"),
+ ),
+ overview=(
+ Optional[Union[str, StrPatch]],
+ Field(
+ None,
+ description="Overview content (L1). Use Markdown with internal links: [filename](filename.md), e.g., [python](python.md), [go](go.md). Supports direct string or patch format.",
+ ),
+ ),
+ )
+
+ SchemaModelGenerator._generic_overview_edit_model = model
+ return model
+
+ def create_discriminated_union_model(self) -> Type[BaseModel]:
+ """
+ Create a unified MemoryData model with discriminator support.
+
+ The model uses 'memory_type' as the discriminator field to
+ determine which fields model to use.
+
+ Returns:
+ Unified Pydantic model with discriminator (a wrapper model containing the union)
+ """
+ if self._union_model is not None:
+ return self._union_model
+
+ # Generate all flat data models first (including disabled for completeness)
+ self.generate_all_models(include_disabled=True)
+
+ # Build the annotated union with discriminator - only use enabled types
+ memory_types = self.registry.list_all(include_disabled=False)
+ if not memory_types:
+ raise ValueError("No memory types registered in registry")
+
+ # Create union of flat data models
+ enabled_memory_types = self.registry.list_all(include_disabled=False)
+ flat_model_union_types = tuple(
+ self._flat_data_models[mt.memory_type]
+ for mt in enabled_memory_types
+ )
+
+ if flat_model_union_types:
+ FlatDataUnion = Union[tuple(flat_model_union_types)] # type: ignore
+ else:
+ # Fallback if no types are enabled
+ class GenericMemoryData(BaseModel):
+ """Generic memory data (fallback)."""
+ memory_type: str = Field(..., description="Memory type identifier")
+ FlatDataUnion = GenericMemoryData # type: ignore
+
+ # Wrap the union in a BaseModel for JSON schema generation
+ class MemoryDataWrapper(BaseModel):
+ """Wrapper model for memory data union."""
+ data: FlatDataUnion = Field(..., description="Memory data") # type: ignore
+
+ model_config = ConfigDict(extra="forbid")
+
+ self._union_model = MemoryDataWrapper
+ return self._union_model
+
+ def create_structured_operations_model(self) -> Type[BaseModel]:
+ """
+ Create a structured MemoryOperations model with type-safe write operations.
+
+ This uses fully flat models for write_uris and edit_uris,
+ and simple string URIs for delete_uris.
+
+ Returns:
+ Pydantic model for structured operations
+ """
+ if self._operations_model is not None:
+ return self._operations_model
+
+ # Generate all flat data models
+ self.generate_all_models(include_disabled=True)
+
+ # Get enabled memory types
+ enabled_memory_types = self.registry.list_all(include_disabled=False)
+
+ # Create union type for flat data models (used for both write and edit)
+ flat_models: List[Type[BaseModel]] = []
+ for mt in enabled_memory_types:
+ flat_model = self.create_flat_data_model(mt)
+ flat_models.append(flat_model)
+
+ FlatDataUnion = Union[tuple(flat_models)] # type: ignore
+
+ # Use single generic model for overview edit (same for all memory types)
+ generic_overview_edit = self.create_overview_edit_model(enabled_memory_types[0] if enabled_memory_types else None)
+
+ # Create structured operations
+ class StructuredMemoryOperations(BaseModel):
+ """Final memory operations output from LLM with type safety."""
+
+ reasoning: str = Field(
+ '',
+ description="reasoning",
+ )
+ write_uris: List[FlatDataUnion] = Field( # type: ignore
+ default_factory=list,
+ description="Write operations with flat data format",
+ )
+ edit_uris: List[FlatDataUnion] = Field( # type: ignore
+ default_factory=list,
+ description="Edit operations with flat data format",
+ )
+ edit_overview_uris: List[generic_overview_edit] = Field( # type: ignore
+ default_factory=list,
+ description="Edit operations for .overview.md files using memory_type",
+ )
+ delete_uris: List[str] = Field(
+ default_factory=list,
+ description="Delete operations as URI strings",
+ )
+
+ def is_empty(self) -> bool:
+ """Check if there are any operations."""
+ return (
+ len(self.write_uris) == 0
+ and len(self.edit_uris) == 0
+ and len(self.edit_overview_uris) == 0
+ and len(self.delete_uris) == 0
+ )
+
+ model_config = ConfigDict(extra='ignore')
+
+ self._operations_model = StructuredMemoryOperations
+ return self._operations_model
+
+ def get_llm_json_schema(self) -> Dict[str, Any]:
+ """
+ Get the JSON schema for LLM structured output.
+
+ Returns:
+ JSON schema dictionary suitable for LLM API
+ """
+ operations_model = self.create_structured_operations_model()
+ return operations_model.model_json_schema()
+
+ def get_memory_data_json_schema(self) -> Dict[str, Any]:
+ """
+ Get the JSON schema just for the flat memory data union.
+
+ Returns:
+ JSON schema for MemoryData
+ """
+ memory_model = self.create_discriminated_union_model()
+ return memory_model.model_json_schema()
+
+
+class SchemaPromptGenerator:
+ """
+ Prompt generator that incorporates schema information into LLM prompts.
+
+ Generates descriptive text about memory types and their fields
+ based on the YAML schema definitions.
+ """
+
+ def __init__(self, registry: MemoryTypeRegistry):
+ self.registry = registry
+
+ def generate_type_descriptions(self) -> str:
+ """
+ Generate descriptions of all memory types.
+
+ Returns:
+ Formatted string with all memory type descriptions
+ """
+ lines = ["## Available Memory Types"]
+
+ for mt in self.registry.list_all():
+ lines.append(f"\n### {mt.memory_type}")
+ lines.append(f"{mt.description}")
+
+ # Add URI format information
+ if mt.directory or mt.filename_template:
+ lines.append("\n**URI Format:**")
+ if mt.directory and mt.filename_template:
+ lines.append(f"- URI: `{mt.directory}/{mt.filename_template}`")
+ elif mt.directory:
+ lines.append(f"- Directory: `{mt.directory}`")
+ elif mt.filename_template:
+ lines.append(f"- Filename: `{mt.filename_template}`")
+
+ # Add variable substitution info
+ lines.append("\n**Variable Substitution:**")
+ lines.append("- `{user_space}` → 'default'")
+ lines.append("- `{agent_space}` → 'default'")
+ if mt.fields:
+ for field in mt.fields:
+ lines.append(f"- `{field.name}` → use value from fields")
+
+ if mt.fields:
+ lines.append("\n**Fields:**")
+ for field in mt.fields:
+ lines.append(f"- `{field.name}` ({field.field_type.value}): {field.description}")
+
+ return "\n".join(lines)
+
+ def generate_field_descriptions(self, memory_type: str) -> Optional[str]:
+ """
+ Generate descriptions for a specific memory type's fields.
+
+ Args:
+ memory_type: The memory type to describe
+
+ Returns:
+ Formatted string with field descriptions, or None if not found
+ """
+ mt = self.registry.get(memory_type)
+ if not mt:
+ return None
+
+ lines = [f"### {mt.memory_type} Fields"]
+ for field in mt.fields:
+ lines.append(f"- `{field.name}`: {field.description}")
+
+ return "\n".join(lines)
+
+ def get_full_prompt_context(self) -> Dict[str, Any]:
+ """
+ Get the full prompt context including all schema information.
+
+ Returns:
+ Dictionary with all prompt context components
+ """
+ return {
+ "type_descriptions": self.generate_type_descriptions(),
+ "memory_types": [
+ {
+ "memory_type": mt.memory_type,
+ "description": mt.description,
+ "fields": [
+ {
+ "name": f.name,
+ "type": f.field_type.value,
+ "description": f.description,
+ "merge_op": f.merge_op.value,
+ }
+ for f in mt.fields
+ ],
+ }
+ for mt in self.registry.list_all()
+ ],
+ }
diff --git a/openviking/session/memory/tools.py b/openviking/session/memory/tools.py
new file mode 100644
index 000000000..4a3074b93
--- /dev/null
+++ b/openviking/session/memory/tools.py
@@ -0,0 +1,391 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: Apache-2.0
+"""
+Memory tools - encapsulate VikingFS read operations for ReAct loop.
+
+Reference: bot/vikingbot/agent/tools/base.py design pattern
+"""
+
+import json
+from abc import ABC, abstractmethod
+from typing import Any, Dict, List, Optional, Tuple, Union
+
+from openviking.server.identity import RequestContext
+from openviking.session.memory.utils import parse_memory_file_with_fields
+from openviking.storage.viking_fs import VikingFS
+from openviking_cli.utils import get_logger
+
+logger = get_logger(__name__)
+
+
+def create_tool_call_message(
+ call_id: Union[str, int],
+ tool_name: str,
+ params: Dict[str, Any],
+) -> Dict[str, Any]:
+ """
+ Create an assistant role message with tool_calls.
+
+ Args:
+ call_id: Unique identifier for the tool call
+ tool_name: Name of the tool being called
+ params: Parameters for the tool call
+
+ Returns:
+ Assistant message with tool_calls field
+ """
+ return {
+ "role": "assistant",
+ "content": None,
+ "tool_calls": [{
+ "id": str(call_id),
+ "type": "function",
+ "function": {
+ "name": tool_name,
+ "arguments": json.dumps(params),
+ },
+ }],
+ }
+
+
+def create_tool_result_message(
+ call_id: Union[str, int],
+ result: Any,
+) -> Dict[str, Any]:
+ """
+ Create a tool role message with the tool execution result.
+
+ Args:
+ call_id: Unique identifier matching the tool call
+ result: Result from the tool execution
+
+ Returns:
+ Tool message with result content
+ """
+ return {
+ "role": "tool",
+ "tool_call_id": str(call_id),
+ "content": json.dumps(result, ensure_ascii=False),
+ }
+
+
+def add_tool_call_pair_to_messages(
+ messages: List[Dict[str, Any]],
+ call_id: Union[str, int],
+ tool_name: str,
+ params: Dict[str, Any],
+ result: Any,
+) -> None:
+ """
+ Add a pair of tool call + tool result messages to the messages list.
+
+ Args:
+ messages: List to append messages to
+ call_id: Unique identifier for the tool call
+ tool_name: Name of the tool being called
+ params: Parameters for the tool call
+ result: Result from the tool execution
+ """
+ messages.append(create_tool_call_message(call_id, tool_name, params))
+ messages.append(create_tool_result_message(call_id, result))
+
+
+def add_tool_call_items_to_messages(
+ messages: List[Dict[str, Any]],
+ tool_call_items: List[Tuple[Union[str, int], str, Dict[str, Any], Any]],
+) -> None:
+ """
+ Add multiple tool call pairs to the messages list.
+
+ Args:
+ messages: List to append messages to
+ tool_call_items: List of tuples (call_id, tool_name, params, result)
+ """
+ for call_id, tool_name, params, result in tool_call_items:
+
+ add_tool_call_pair_to_messages(messages, call_id, tool_name, params, result)
+
+
+class MemoryTool(ABC):
+ """
+ Abstract base class for memory tools.
+
+ Similar to bot/vikingbot/agent/tools/base.py Tool,
+ but simplified for memory module's internal use.
+ """
+
+ @property
+ @abstractmethod
+ def name(self) -> str:
+ """Tool name used in function calls."""
+ pass
+
+ @property
+ @abstractmethod
+ def description(self) -> str:
+ """Description of what the tool does."""
+ pass
+
+ @property
+ @abstractmethod
+ def parameters(self) -> Dict[str, Any]:
+ """JSON Schema for tool parameters."""
+ pass
+
+ @abstractmethod
+ async def execute(
+ self,
+ viking_fs: VikingFS,
+ ctx: Optional[RequestContext],
+ **kwargs: Any,
+ ) -> Any:
+ """
+ Execute the tool with given parameters.
+
+ Args:
+ viking_fs: VikingFS instance
+ ctx: Request context
+ **kwargs: Tool-specific parameters
+
+ Returns:
+ Result of the tool execution (can be dict, list, string, etc.)
+ """
+ pass
+
+ def to_schema(self) -> Dict[str, Any]:
+ """Convert tool to OpenAI function schema format."""
+ return {
+ "type": "function",
+ "function": {
+ "name": self.name,
+ "description": self.description,
+ "parameters": self.parameters,
+ },
+ }
+
+
+class MemoryReadTool(MemoryTool):
+ """Tool to read single memory file."""
+
+ @property
+ def name(self) -> str:
+ return "read"
+
+ @property
+ def description(self) -> str:
+ return "Read single file, offset is start line number (0-indexed), limit is number of lines to read, -1 means read to end"
+
+ @property
+ def parameters(self) -> Dict[str, Any]:
+ return {
+ "type": "object",
+ "properties": {
+ "uri": {
+ "type": "string",
+ "description": "Memory URI to read, e.g., 'viking://user/user123/memories/profile.md'",
+ },
+ },
+ "required": ["uri"],
+ }
+
+ async def execute(
+ self,
+ viking_fs: VikingFS,
+ ctx: Optional[RequestContext],
+ **kwargs: Any,
+ ) -> Any:
+ try:
+ uri = kwargs.get("uri", "")
+ content = await viking_fs.read_file(
+ uri,
+ ctx=ctx,
+ )
+ # Parse MEMORY_FIELDS from comment and return dict directly
+ parsed = parse_memory_file_with_fields(content)
+ return parsed
+ except Exception as e:
+ logger.error(f"Failed to execute read: {e}")
+ return {"error": str(e)}
+
+
+class MemorySearchTool(MemoryTool):
+ """Tool to perform semantic search."""
+
+ @property
+ def name(self) -> str:
+ return "search"
+
+ @property
+ def description(self) -> str:
+ return "Semantic search with session context, target_uri is target directory URI"
+
+ @property
+ def parameters(self) -> Dict[str, Any]:
+ return {
+ "type": "object",
+ "properties": {
+ "query": {
+ "type": "string",
+ "description": "Search query text",
+ },
+ "target_uri": {
+ "type": "string",
+ "description": "Target directory URI, default empty means search all",
+ "default": "",
+ },
+ "session_info": {
+ "type": "object",
+ "description": "Session information with summaries and recent_messages, optional",
+ },
+ "limit": {
+ "type": "integer",
+ "description": "Maximum results to return, default 10",
+ "default": 10,
+ },
+ "score_threshold": {
+ "type": "number",
+ "description": "Score threshold, optional",
+ },
+ "filter": {
+ "type": "object",
+ "description": "Filter conditions, optional",
+ },
+ },
+ "required": ["query"],
+ }
+
+ async def execute(
+ self,
+ viking_fs: VikingFS,
+ ctx: Optional[RequestContext],
+ **kwargs: Any,
+ ) -> Any:
+ try:
+ query = kwargs.get("query", "")
+ target_uri = kwargs.get("target_uri", "")
+ # If target_uri is empty, use default from ctx
+ if not target_uri and ctx and hasattr(ctx, 'default_search_uris') and ctx.default_search_uris:
+ target_uri = ctx.default_search_uris
+ session_info = kwargs.get("session_info")
+ limit = kwargs.get("limit", 10)
+ score_threshold = kwargs.get("score_threshold")
+ filter = kwargs.get("filter")
+ search_result = await viking_fs.search(
+ query,
+ target_uri=target_uri,
+ session_info=session_info,
+ limit=limit,
+ score_threshold=score_threshold,
+ filter=filter,
+ ctx=ctx,
+ )
+ return search_result.to_dict()
+ except Exception as e:
+ logger.error(f"Failed to execute search: {e}")
+ return {"error": str(e)}
+
+
+def _format_size(size_bytes: int) -> str:
+ """Format size in bytes to human readable format."""
+ if size_bytes >= 1024 * 1024:
+ return f"{size_bytes / (1024 * 1024):.1f}M"
+ elif size_bytes >= 1024:
+ return f"{size_bytes / 1024:.1f}K"
+ else:
+ return f"{size_bytes}B"
+
+
+class MemoryLsTool(MemoryTool):
+ """Tool to list directory contents."""
+
+ @property
+ def name(self) -> str:
+ return "ls"
+
+ @property
+ def description(self) -> str:
+ return "List directory content, includes abstract field when output='agent'"
+
+ @property
+ def parameters(self) -> Dict[str, Any]:
+ return {
+ "type": "object",
+ "properties": {
+ "uri": {
+ "type": "string",
+ "description": "Directory URI to list, e.g., 'viking://user/user123/memories'",
+ },
+ },
+ "required": ["uri"],
+ }
+
+ async def execute(
+ self,
+ viking_fs: VikingFS,
+ ctx: Optional[RequestContext],
+ **kwargs: Any,
+ ) -> Any:
+ try:
+ uri = kwargs.get("uri", "")
+ entries = await viking_fs.ls(
+ uri,
+ output="agent",
+ abs_limit=256,
+ show_all_hidden=False,
+ node_limit=1000,
+ ctx=ctx,
+ )
+ # Format: filename size (e.g., "file.md 1.2K")
+ result_lines = []
+ for e in entries:
+ if not e.get("isDir", False):
+ # Extract name from entry or fallback to uri
+ name = e.get("name", "")
+ if not name:
+ uri = e.get("uri", "")
+ name = uri.rsplit("/", 1)[-1] if "/" in uri else uri
+ size = e.get("size", 0)
+ result_lines.append(f"{name} {_format_size(size)}")
+ if not result_lines:
+ return f"Directory is empty. You can write new files to create memory content."
+ return '\n'.join(result_lines)
+ except Exception as e:
+ logger.error(f"Failed to execute ls: {e}")
+ return {"error": str(e)}
+
+
+
+
+# Tool registry
+MEMORY_TOOLS_REGISTRY: Dict[str, MemoryTool] = {}
+
+
+def register_tool(tool: MemoryTool) -> None:
+ """Register a memory tool."""
+ MEMORY_TOOLS_REGISTRY[tool.name] = tool
+ logger.debug(f"Registered memory tool: {tool.name}")
+
+
+def get_tool(name: str) -> Optional[MemoryTool]:
+ """Get a memory tool by name."""
+ return MEMORY_TOOLS_REGISTRY.get(name)
+
+
+def list_tools() -> Dict[str, MemoryTool]:
+ """List all registered memory tools."""
+ return MEMORY_TOOLS_REGISTRY.copy()
+
+
+# Tools exposed to LLM (not all registered tools are exposed)
+LLM_TOOLS = ["read", "search"]
+
+
+def get_tool_schemas() -> List[Dict[str, Any]]:
+ """Get tools exposed to LLM in OpenAI function schema format."""
+ return [tool.to_schema() for tool in MEMORY_TOOLS_REGISTRY.values() if tool.name in LLM_TOOLS]
+
+
+# Register default tools
+register_tool(MemoryReadTool())
+register_tool(MemorySearchTool())
+register_tool(MemoryLsTool())
diff --git a/openviking/session/memory/utils/__init__.py b/openviking/session/memory/utils/__init__.py
new file mode 100644
index 000000000..a516fd0bd
--- /dev/null
+++ b/openviking/session/memory/utils/__init__.py
@@ -0,0 +1,85 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: Apache-2.0
+"""
+Memory utilities package.
+"""
+
+from openviking.session.memory.utils.content import (
+ deserialize_content,
+ deserialize_full,
+ deserialize_metadata,
+ serialize_with_metadata,
+)
+from openviking.session.memory.utils.language import (
+ detect_language_from_conversation,
+)
+from openviking.session.memory.utils.messages import (
+ parse_memory_file_with_fields,
+ pretty_print_messages,
+)
+from openviking.session.memory.utils.uri import (
+ ResolvedOperations,
+ collect_allowed_directories,
+ collect_allowed_path_patterns,
+ extract_uri_fields_from_flat_model,
+ generate_uri,
+ is_uri_allowed,
+ is_uri_allowed_for_schema,
+ resolve_all_operations,
+ resolve_flat_model_uri,
+ validate_operations_uris,
+ validate_uri_template,
+)
+from openviking.session.memory.utils.json_parser import (
+ _any_to_str,
+ _get_arg_type,
+ _get_origin_type,
+ extract_json_content,
+ extract_json_from_markdown,
+ parse_json_with_stability,
+ parse_value_with_tolerance,
+ remove_json_trailing_content,
+ value_fault_tolerance,
+)
+from openviking.session.memory.utils.model import (
+ model_to_dict,
+ flat_model_to_dict,
+)
+
+__all__ = [
+ # Content serialization
+ "serialize_with_metadata",
+ "deserialize_content",
+ "deserialize_metadata",
+ "deserialize_full",
+ # Language
+ "detect_language_from_conversation",
+ # Messages
+ "pretty_print_messages",
+ "parse_memory_file_with_fields",
+ # URI
+ "generate_uri",
+ "validate_uri_template",
+ "collect_allowed_directories",
+ "collect_allowed_path_patterns",
+ "is_uri_allowed",
+ "is_uri_allowed_for_schema",
+ "extract_uri_fields_from_flat_model",
+ "resolve_flat_model_uri",
+ "ResolvedOperations",
+ "resolve_all_operations",
+ "validate_operations_uris",
+ # JSON Parser
+ "extract_json_content",
+ "remove_json_trailing_content",
+ "parse_json_with_stability",
+ "extract_json_from_markdown",
+ "value_fault_tolerance",
+ "parse_value_with_tolerance",
+ "_get_origin_type",
+ "_get_arg_type",
+ "_any_to_str",
+ # Model
+ "model_to_dict",
+ "flat_model_to_dict",
+]
diff --git a/openviking/session/memory/utils/content.py b/openviking/session/memory/utils/content.py
new file mode 100644
index 000000000..3a8a12998
--- /dev/null
+++ b/openviking/session/memory/utils/content.py
@@ -0,0 +1,159 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: Apache-2.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
+
+
+# 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] = datetime.fromisoformat(result[key])
+ except (ValueError, TypeError):
+ # Keep as string if parsing fails
+ pass
+ return result
+
+
+def serialize_with_metadata(content: str, metadata: Dict[str, Any]) -> str:
+ """
+ Serialize content and metadata into a single string.
+
+ The metadata is stored in an HTML comment at the end of the content.
+
+ Args:
+ content: The main memory content (Markdown)
+ metadata: Dictionary containing metadata fields:
+ - memory_type: Type of memory (NOT included in output)
+ - fields: Structured fields (for template mode)
+ - name: Memory name
+ - tags: List of tags
+ - created_at: Creation datetime
+ - updated_at: Update datetime
+ - abstract: L0 abstract
+ - overview: L1 overview
+
+ Returns:
+ Combined string with content followed by metadata in HTML comment
+ """
+ # 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) -> Tuple[str, Optional[Dict[str, Any]]]:
+ """
+ Extract both content and metadata from a serialized string.
+
+ Args:
+ full_content: Complete content including metadata comment
+
+ Returns:
+ Tuple of (content, metadata) where metadata may be None
+ """
+ content = deserialize_content(full_content)
+ metadata = deserialize_metadata(full_content)
+ return content, metadata
diff --git a/openviking/session/memory/utils/json_parser.py b/openviking/session/memory/utils/json_parser.py
new file mode 100644
index 000000000..08bbb4012
--- /dev/null
+++ b/openviking/session/memory/utils/json_parser.py
@@ -0,0 +1,430 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: Apache-2.0
+"""
+JSON stable parsing - Five-Layer Fault Tolerance Architecture.
+
+Layer 1: JSON Cleanup - extract_json_content()
+Layer 2: JSON Repair - json_repair.loads()
+Layer 3: Structure Tolerance - list→object conversion + field filtering
+Layer 4: Value Tolerance - value_fault_tolerance()
+Layer 5: Validation Tolerance - TypeAdapter(strict=False) + list item filtering
+"""
+
+import json
+import re
+from types import UnionType
+from typing import Any, Dict, List, Optional, Tuple, Type, get_type_hints, get_origin, get_args, Union
+
+import json_repair
+from pydantic import TypeAdapter
+
+from openviking_cli.utils import get_logger
+
+logger = get_logger(__name__)
+
+
+# Exported for testing
+__all__ = [
+ "extract_json_content",
+ "remove_json_trailing_content",
+ "parse_json_with_stability",
+ "extract_json_from_markdown",
+ "value_fault_tolerance",
+ "parse_value_with_tolerance",
+ "_get_origin_type",
+ "_get_arg_type",
+ "_any_to_str",
+]
+
+
+def extract_json_content(s: str) -> str:
+ """
+ Layer 1: Extract JSON content from LLM response, removing both leading and trailing non-JSON content.
+
+ Models often add thinking process, safety warnings, or explanations before or after the JSON.
+ This function extracts only the valid JSON part from first {/[ to last }/].
+
+ Args:
+ s: Raw LLM response string
+
+ Returns:
+ String with only the JSON part (from first {/[ to last }/])
+ """
+ if not s:
+ return s
+
+ original_stripped = s.strip()
+ if not original_stripped:
+ return s
+
+ temp_s = s
+
+ # Find first { or [
+ first_brace = temp_s.find('{')
+ first_bracket = temp_s.find('[')
+
+ start_idx = 0
+ if first_brace != -1 and first_bracket != -1:
+ start_idx = min(first_brace, first_bracket)
+ elif first_brace != -1:
+ start_idx = first_brace
+ elif first_bracket != -1:
+ start_idx = first_bracket
+ else:
+ # No JSON markers found, return original
+ return s
+
+ if start_idx > 0:
+ temp_s = temp_s[start_idx:]
+
+ # Find last } or ]
+ last_brace = temp_s.rfind('}')
+ last_bracket = temp_s.rfind(']')
+
+ end_idx = len(temp_s)
+ if last_brace != -1 and last_bracket != -1:
+ end_idx = max(last_brace, last_bracket) + 1
+ elif last_brace != -1:
+ end_idx = last_brace + 1
+ elif last_bracket != -1:
+ end_idx = last_bracket + 1
+
+ if end_idx < len(temp_s):
+ temp_s = temp_s[:end_idx]
+
+ result = temp_s.strip()
+
+ # If we stripped everything, return original
+ if not result:
+ return s
+
+ return result
+
+
+def remove_json_trailing_content(s: str) -> str:
+ """
+ Layer 1: Remove extra content after JSON closing brace.
+
+ DEPRECATED: Use extract_json_content() instead which handles both leading and trailing content.
+
+ Args:
+ s: Raw LLM response string
+
+ Returns:
+ String with only the JSON part
+ """
+ return extract_json_content(s)
+
+
+def _get_origin_type(annotation) -> Type:
+ """
+ Extract base type from Optional or Union types.
+
+ Similar to BaseModelCompat.get_origin_type().
+
+ Args:
+ annotation: Type annotation (could be Union, Optional, List, etc.)
+
+ Returns:
+ The underlying origin type
+ """
+ origin = get_origin(annotation)
+ if origin is Union or origin is UnionType:
+ args = get_args(annotation)
+ # Handle Optional[T] which is Union[T, None]
+ if len(args) == 2 and args[1] == type(None):
+ return _get_origin_type(args[0])
+ elif origin is list:
+ return list
+ return annotation
+
+
+def _get_arg_type(annotation) -> Optional[Type]:
+ """
+ Extract item type from List annotations.
+
+ Similar to BaseModelCompat.get_arg_type().
+
+ Args:
+ annotation: Type annotation
+
+ Returns:
+ The list item type if annotation is List[T], else None
+ """
+ origin = get_origin(annotation)
+ if origin is Union or origin is UnionType:
+ args = get_args(annotation)
+ if len(args) == 2 and args[1] == type(None):
+ return _get_arg_type(args[0])
+ elif origin is list:
+ args = get_args(annotation)
+ if args:
+ return args[0]
+ return None
+
+
+def _any_to_str(value) -> str:
+ """
+ Convert any value to string, with special handling for containers.
+
+ Similar to BaseModelCompat.any_to_str().
+
+ Args:
+ value: Any value
+
+ Returns:
+ String representation
+ """
+ if value is None:
+ return ""
+ if isinstance(value, list):
+ return ",".join(map(str, value))
+ elif isinstance(value, dict):
+ return json.dumps(value, ensure_ascii=False)
+ elif isinstance(value, (int, bool, float)):
+ return f'{value}'
+ return str(value)
+
+
+def value_fault_tolerance(field_type, value):
+ """
+ Layer 4: Value-level fault tolerance - automatic type conversion.
+
+ Similar to BaseModelCompat.value_fault_tolerance().
+
+ Handles common type mismatches:
+ - 'None' → None (for non-str types)
+ - list/dict/number → str (when target type is str)
+ - str → int/float (when target type is number)
+ - str/dict → list (when target type is list)
+
+ Args:
+ field_type: Target type annotation
+ value: Raw value from JSON
+
+ Returns:
+ Converted value
+ """
+ origin_type = _get_origin_type(field_type)
+
+ # Handle json_repair converting None to 'None'
+ if value == 'None':
+ if origin_type is not str:
+ return None
+
+ if origin_type is str:
+ # Convert any type to string
+ return _any_to_str(value)
+ elif origin_type is int:
+ if isinstance(value, str):
+ if value is None or value == 'None':
+ return 0
+ try:
+ return int(value)
+ except (ValueError, TypeError):
+ pass
+ elif origin_type is float:
+ if isinstance(value, str):
+ if value is None or value == 'None':
+ return 0.0
+ try:
+ return float(value)
+ except (ValueError, TypeError):
+ pass
+ elif origin_type is list:
+ if isinstance(value, str):
+ # Wrap single string in list
+ return [value]
+ elif isinstance(value, dict):
+ # Wrap single dict in list
+ return [value]
+
+ return value
+
+
+def parse_value_with_tolerance(value, annotation):
+ """
+ Layer 4 & 5: Parse value with tolerance and validation.
+
+ Similar to json_adapter.parse_value().
+
+ Args:
+ value: Raw value
+ annotation: Target type annotation
+
+ Returns:
+ Parsed and validated value
+
+ Raises:
+ Exception: If parsing fails even after tolerance attempts
+ """
+ # Handle None string from json_repair
+ if annotation is str or annotation is Optional[str]:
+ if value is None:
+ return None
+ if isinstance(value, str):
+ return value
+ else:
+ return json.dumps(value, ensure_ascii=False) if isinstance(value, (dict, list)) else str(value)
+
+ if value == 'None':
+ return None
+
+ parsed_value = value
+
+ # Apply value fault tolerance first
+ parsed_value = value_fault_tolerance(annotation, parsed_value)
+
+ # Try validation with TypeAdapter
+ try:
+ return TypeAdapter(annotation).validate_python(parsed_value, strict=False)
+ except Exception as e:
+ logger.warning(f'TypeAdapter validation failed: {e}')
+
+ # For list types, try filtering invalid items
+ if (get_origin(annotation) is list and
+ isinstance(parsed_value, list)):
+ filtered_items = []
+ item_type = _get_arg_type(annotation)
+ if item_type is not None:
+ for item in parsed_value:
+ try:
+ 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}")
+ continue
+
+ if filtered_items:
+ return filtered_items
+ else:
+ logger.warning("All list items were filtered out, returning empty list")
+ return []
+
+ # Re-raise for non-list types
+ raise e
+
+
+def parse_json_with_stability(
+ content: str,
+ model_class: Optional[Type] = None,
+ expected_fields: Optional[List[str]] = None,
+) -> Tuple[Optional[Any], Optional[str]]:
+ """
+ Five-layer JSON parsing with maximum stability.
+
+ Layer 1: Extract JSON content (remove both leading and trailing non-JSON)
+ Layer 2: Repair JSON with json_repair
+ Layer 3: Structure tolerance (list→object, extra fields filtering)
+ Layer 4: Value fault tolerance (type conversion)
+ Layer 5: Validation tolerance (strict=False + list item filtering)
+
+ Args:
+ content: Raw LLM response string
+ model_class: Optional Pydantic model class to validate against
+ expected_fields: Optional list of field names to keep (filter out extra fields)
+
+ Returns:
+ Tuple of (parsed_data, error_message). error_message is None on success.
+ """
+ if not content:
+ return None, "Empty content"
+
+ # Layer 1: Extract JSON content (both leading and trailing)
+ try:
+ cleaned_content = extract_json_content(content)
+ if not cleaned_content:
+ return None, "No JSON content found after cleanup"
+ except Exception as e:
+ logger.warning(f"Layer 1 cleanup failed: {e}")
+ cleaned_content = content
+
+ # Layer 2: Parse with json_repair
+ parsed_data = None
+ try:
+ parsed_data = json_repair.loads(cleaned_content)
+ except Exception as e:
+ logger.warning(f"Layer 2 json_repair failed: {e}")
+ # Fallback: try regular json.loads
+ try:
+ parsed_data = json.loads(cleaned_content)
+ except Exception as e2:
+ return None, f"JSON parsing failed: {e} (fallback also failed: {e2})"
+
+ # Layer 3: Structure tolerance
+ # 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")
+
+ if not isinstance(parsed_data, dict):
+ return None, f"Expected dict after parsing, got {type(parsed_data)}"
+
+ # Filter to only expected fields if provided
+ if expected_fields:
+ filtered_data = {}
+ for k, v in parsed_data.items():
+ if k in expected_fields:
+ filtered_data[k] = v
+ parsed_data = filtered_data
+
+ # If no model class, return the raw dict
+ if model_class is None:
+ return parsed_data, None
+
+ # Layer 4 & 5: Validate with model
+ try:
+ # First try direct model validation
+ return model_class.model_validate(parsed_data), None
+ except Exception as e:
+ logger.warning(f"Direct model validation failed, trying parse_value_with_tolerance: {e}")
+
+ # Fallback: Apply value fault tolerance to each field individually
+ try:
+ field_types = get_type_hints(model_class)
+ tolerant_data = {}
+ for field_name, field_value in parsed_data.items():
+ if field_name in field_types:
+ try:
+ tolerant_data[field_name] = parse_value_with_tolerance(
+ field_value,
+ field_types[field_name]
+ )
+ except Exception as field_e:
+ logger.warning(f"Field {field_name} parsing failed: {field_e}")
+ # Skip this field rather than failing the whole parse
+ continue
+
+ # Now try validating with the tolerant data
+ return model_class.model_validate(tolerant_data), None
+ except Exception as e2:
+ return None, f"Model validation failed even after tolerance: {e} (fallback: {e2})"
+
+
+def extract_json_from_markdown(content: str) -> str:
+ """
+ Extract JSON from markdown code blocks.
+
+ Handles:
+ - ```json { ... } ```
+ - ``` { ... } ```
+ - Plain JSON without markdown
+
+ Args:
+ content: Content possibly containing markdown code blocks
+
+ Returns:
+ Extracted JSON string
+ """
+ if not content:
+ return content
+
+ content = content.strip()
+
+ # Try to find ```json ... ```
+ match = re.search(r"```(?:json)?\s*([\s\S]*?)\s*```", content, re.DOTALL)
+ if match:
+ return match.group(1).strip()
+
+ # If no code block, return as-is
+ return content
diff --git a/openviking/session/memory/utils/language.py b/openviking/session/memory/utils/language.py
new file mode 100644
index 000000000..b87f855e7
--- /dev/null
+++ b/openviking/session/memory/utils/language.py
@@ -0,0 +1,73 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: Apache-2.0
+"""
+Language detection utilities.
+"""
+
+import re
+from typing import Optional
+
+from openviking_cli.utils import get_logger
+
+logger = get_logger(__name__)
+
+
+def _detect_language_from_text(user_text: str, fallback_language: str) -> str:
+ """Internal shared helper to detect dominant language from text."""
+ fallback = (fallback_language or "en").strip() or "en"
+
+ if not user_text:
+ return fallback
+
+ # Detect scripts that are largely language-unique first.
+ counts = {
+ "ko": len(re.findall(r"[\uac00-\ud7af]", user_text)),
+ "ru": len(re.findall(r"[\u0400-\u04ff]", user_text)),
+ "ar": len(re.findall(r"[\u0600-\u06ff]", user_text)),
+ }
+
+ detected, score = max(counts.items(), key=lambda item: item[1])
+ if score > 0:
+ return detected
+
+ # CJK disambiguation:
+ # - Japanese often includes Han characters too, so Han-count alone can
+ # misclassify Japanese as Chinese.
+ # - If any Kana is present, prioritize Japanese.
+ kana_count = len(re.findall(r"[\u3040-\u30ff\u31f0-\u31ff\uff66-\uff9f]", user_text))
+ han_count = len(re.findall(r"[\u4e00-\u9fff]", user_text))
+
+ if kana_count > 0:
+ return "ja"
+ if han_count > 0:
+ return "zh-CN"
+
+ return fallback
+
+
+def detect_language_from_conversation(conversation: str, fallback_language: str = "en") -> str:
+ """Detect dominant language from user messages in conversation.
+
+ We intentionally scope detection to user role content so assistant/system
+ text does not bias the target output language for stored memories.
+ """
+ fallback = (fallback_language or "en").strip() or "en"
+
+ # Try to extract user messages from conversation string
+ # Look for patterns like "[user]: ..." or "User: ..."
+ user_lines = []
+ for line in conversation.split("\n"):
+ line_lower = line.strip().lower()
+ if line_lower.startswith("[user]:") or line_lower.startswith("user:"):
+ # Extract content after the role marker
+ content = line.split(":", 1)[1].strip() if ":" in line else line.strip()
+ if content:
+ user_lines.append(content)
+
+ user_text = "\n".join(user_lines)
+
+ # If no user messages found, use the whole conversation as fallback
+ if not user_text:
+ user_text = conversation
+
+ return _detect_language_from_text(user_text, fallback)
diff --git a/openviking/session/memory/utils/messages.py b/openviking/session/memory/utils/messages.py
new file mode 100644
index 000000000..8ac895d57
--- /dev/null
+++ b/openviking/session/memory/utils/messages.py
@@ -0,0 +1,126 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: Apache-2.0
+"""
+Message formatting and memory file parsing utilities.
+"""
+
+import json
+import re
+from typing import Any, Dict, List
+
+import json_repair
+
+from openviking_cli.utils import get_logger
+
+logger = get_logger(__name__)
+
+
+def pretty_print_messages(messages: List[Dict[str, Any]]) -> None:
+ """
+ Print messages in a human-readable format.
+
+ Formats messages with [role] headers and indented content for readability.
+ Tool calls and results are printed in a way that shows their correspondence.
+
+ Args:
+ messages: List of message dictionaries with 'role', 'content', and optional 'tool_calls'
+ """
+ def _format_tool_call(tc: Dict[str, Any]) -> Dict[str, Any]:
+ """Format a single tool call, pretty-printing arguments if it's JSON."""
+ tc_copy = dict(tc)
+ if "function" in tc_copy and "arguments" in tc_copy["function"]:
+ args_str = tc_copy["function"]["arguments"]
+ if isinstance(args_str, str):
+ try:
+ # Try to parse and pretty-print the arguments
+ args_json = json.loads(args_str)
+ tc_copy["function"] = dict(tc_copy["function"])
+ tc_copy["function"]["arguments"] = args_json
+ except (json.JSONDecodeError, TypeError):
+ # If it's not valid JSON, leave it as is
+ pass
+ return tc_copy
+
+ print("=== Messages ===")
+ for msg in messages:
+ role = msg.get("role", "unknown")
+ content = msg.get("content", "")
+
+ if role == "tool":
+ # Tool result - show correspondence with tool_call_id
+ tool_call_id = msg.get("tool_call_id", "")
+ print(f"\n[{role}] (id={tool_call_id})")
+ if content:
+ # Try to pretty-print tool result if it's JSON
+ try:
+ result_json = json.loads(content)
+ print(json.dumps(result_json, indent=2, ensure_ascii=False))
+ except (json.JSONDecodeError, TypeError):
+ # If it's not valid JSON, print as is
+ print(content)
+ else:
+ if content:
+ print(f"\n[{role}]")
+ print(content)
+
+ if "tool_calls" in msg and msg["tool_calls"]:
+ tool_calls = msg["tool_calls"]
+ if len(tool_calls) == 1:
+ # Single tool call - show its id
+ tc = tool_calls[0]
+ tc_id = tc.get("id", "")
+ tc_name = tc.get("function", {}).get("name", "")
+ print(f"\n[{role} tool_call] (id={tc_id}, name={tc_name})")
+ formatted_tc = _format_tool_call(tc)
+ print(json.dumps(formatted_tc, indent=2, ensure_ascii=False))
+ else:
+ # Multiple tool calls
+ print(f"\n[{role} tool_calls]")
+ formatted_tcs = [_format_tool_call(tc) for tc in tool_calls]
+ print(json.dumps(formatted_tcs, indent=2, ensure_ascii=False))
+
+ print("\n=== End Messages ===")
+
+
+def parse_memory_file_with_fields(content: str) -> Dict[str, Any]:
+ """
+ Parse memory file content with optional MEMORY_FIELDS HTML comment.
+
+ Extracts fields from <!-- MEMORY_FIELDS { ... } --> comment and returns
+ the fields merged at top level with the content.
+
+ Args:
+ content: Raw file content string
+
+ Returns:
+ Dict with {field1: value1, field2: value2, ..., "content": str}
+ """
+ if not content:
+ return {"content": ""}
+
+ # Pattern to match: <!-- MEMORY_FIELDS ... -->
+ # Matches multi-line JSON inside the comment
+ pattern = r"<!--\s*MEMORY_FIELDS\s*([\s\S]*?)\s*-->"
+
+ match = re.search(pattern, content)
+
+ result = {}
+
+ if match:
+ fields_json_str = match.group(1).strip()
+ if fields_json_str:
+ try:
+ fields = json_repair.loads(fields_json_str)
+ # If it's a list, take the first item (just in case)
+ if isinstance(fields, list) and len(fields) > 0:
+ fields = fields[0]
+ if isinstance(fields, dict):
+ result.update(fields)
+ except Exception as e:
+ logger.warning(f"Failed to parse MEMORY_FIELDS JSON: {e}")
+
+ # Remove the comment from content
+ content_without_comment = re.sub(pattern, "", content).strip()
+ result["content"] = content_without_comment
+
+ return result
diff --git a/openviking/session/memory/utils/model.py b/openviking/session/memory/utils/model.py
new file mode 100644
index 000000000..e0134cc3b
--- /dev/null
+++ b/openviking/session/memory/utils/model.py
@@ -0,0 +1,34 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: Apache-2.0
+"""
+Model utilities - shared model conversion functions.
+"""
+
+from typing import Any, Dict
+
+
+def model_to_dict(model: Any, exclude_none: bool = True) -> Dict[str, Any]:
+ """Convert a model to a dictionary, handling both Pydantic models and raw dicts.
+
+ Args:
+ model: Pydantic model or dict to convert
+ exclude_none: Whether to exclude None values (default: True)
+
+ Returns:
+ Dictionary representation of the model
+ """
+ if hasattr(model, 'model_dump'):
+ if exclude_none:
+ return model.model_dump(exclude_none=True)
+ return model.model_dump()
+ elif hasattr(model, 'dict'):
+ # For backward compatibility with older Pydantic
+ if exclude_none:
+ return model.dict(exclude_none=True)
+ return model.dict()
+ else:
+ return dict(model) if model else {}
+
+
+# Backward compatibility alias
+flat_model_to_dict = model_to_dict
diff --git a/openviking/session/memory/utils/uri.py b/openviking/session/memory/utils/uri.py
new file mode 100644
index 000000000..f47d9d545
--- /dev/null
+++ b/openviking/session/memory/utils/uri.py
@@ -0,0 +1,481 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: Apache-2.0
+"""
+URI generation and validation utilities.
+"""
+
+import re
+from typing import Any, Dict, List, Optional, Set, Tuple, Type
+
+from openviking.session.memory.dataclass import MemoryTypeSchema
+from openviking.session.memory.memory_type_registry import MemoryTypeRegistry
+from openviking_cli.utils import get_logger
+
+logger = get_logger(__name__)
+
+
+def generate_uri(
+ memory_type: MemoryTypeSchema,
+ fields: Dict[str, Any],
+ user_space: str = "default",
+ agent_space: str = "default",
+) -> str:
+ """
+ Generate a full URI from memory type schema and field values.
+
+ Args:
+ memory_type: The memory type schema with directory and filename_template
+ fields: The field values to use for template replacement
+ user_space: The user space to substitute for {user_space}
+ agent_space: The agent space to substitute for {agent_space}
+
+ Returns:
+ The fully generated URI
+
+ Raises:
+ ValueError: If required template variables are missing from fields
+ """
+ # Build the URI template from directory and filename_template
+ uri_template = ""
+ if memory_type.directory:
+ uri_template = memory_type.directory
+ if memory_type.filename_template:
+ if uri_template:
+ uri_template = f"{uri_template}/{memory_type.filename_template}"
+ else:
+ uri_template = memory_type.filename_template
+
+ if not uri_template:
+ raise ValueError("Memory type has neither directory nor filename_template")
+
+ # Build the replacement dictionary
+ replacements = {
+ "user_space": user_space,
+ "agent_space": agent_space,
+ }
+
+ # Add all fields to replacements
+ replacements.update(fields)
+
+ # Replace all template variables
+ def replace_var(match: re.Match) -> str:
+ var_name = match.group(1)
+ if var_name not in replacements:
+ raise ValueError(f"Missing template variable '{var_name}' in fields")
+ value = replacements[var_name]
+ if value is None:
+ raise ValueError(f"Template variable '{var_name}' has None value")
+ return str(value)
+
+ # Replace {variable} patterns
+ uri = re.sub(r"\{([^}]+)\}", replace_var, uri_template)
+
+ return uri
+
+
+def validate_uri_template(memory_type: MemoryTypeSchema) -> bool:
+ """
+ Validate that a memory type's URI template is well-formed.
+
+ Args:
+ memory_type: The memory type schema to validate
+
+ Returns:
+ True if the template is valid, False otherwise
+ """
+ if not memory_type.directory and not memory_type.filename_template:
+ return False
+
+ # Check that all variables in filename_template exist in fields
+ if memory_type.filename_template:
+ field_names = {f.name for f in memory_type.fields}
+ template_vars = set(re.findall(r"\{([^}]+)\}", memory_type.filename_template))
+
+ # {user_space} and {agent_space} are built-in, not from fields
+ built_in_vars = {"user_space", "agent_space"}
+ required_field_vars = template_vars - built_in_vars
+
+ for var in required_field_vars:
+ if var not in field_names:
+ return False
+
+ return True
+
+
+def collect_allowed_directories(
+ schemas: List[MemoryTypeSchema],
+ user_space: str = "default",
+ agent_space: str = "default",
+) -> Set[str]:
+ """
+ Collect all allowed directories from activated schemas.
+
+ Args:
+ schemas: List of activated memory type schemas
+ user_space: User space to substitute for {user_space}
+ agent_space: Agent space to substitute for {agent_space}
+
+ Returns:
+ Set of allowed directory paths with variables replaced
+ """
+ allowed_dirs = set()
+ for schema in schemas:
+ if schema.directory:
+ dir_path = schema.directory.replace("{user_space}", user_space).replace("{agent_space}", agent_space)
+ allowed_dirs.add(dir_path)
+ return allowed_dirs
+
+
+def collect_allowed_path_patterns(
+ schemas: List[MemoryTypeSchema],
+ user_space: str = "default",
+ agent_space: str = "default",
+) -> Set[str]:
+ """
+ Collect all allowed full path patterns from activated schemas.
+
+ Args:
+ schemas: List of activated memory type schemas
+ user_space: User space to substitute for {user_space}
+ agent_space: Agent space to substitute for {agent_space}
+
+ Returns:
+ Set of allowed path patterns with {user_space} and {agent_space} replaced
+ (other variables like {topic}, {tool_name}, etc. remain as patterns)
+ """
+ allowed_patterns = set()
+ for schema in schemas:
+ if not schema.directory and not schema.filename_template:
+ continue
+ pattern_parts = []
+ if schema.directory:
+ pattern_parts.append(schema.directory)
+ if schema.filename_template:
+ pattern_parts.append(schema.filename_template)
+ if pattern_parts:
+ pattern = "/".join(pattern_parts)
+ pattern = pattern.replace("{user_space}", user_space).replace("{agent_space}", agent_space)
+ allowed_patterns.add(pattern)
+ return allowed_patterns
+
+
+def _pattern_matches_uri(pattern: str, uri: str) -> bool:
+ """
+ Check if a URI matches a pattern with variables like {topic}, {tool_name}, etc.
+
+ The pattern matching is flexible:
+ - {variable} matches any sequence of characters except '/'
+ - * matches any sequence of characters except '/' (shell-style)
+ - ** matches any sequence of characters including '/' (shell-style)
+
+ Args:
+ pattern: The pattern to match against (may contain {variables} or * wildcards)
+ uri: The URI to check
+
+ Returns:
+ True if the URI matches the pattern
+ """
+ import re
+
+ # First, convert the pattern to a regex
+ # Escape regex special chars except {, }, *, /
+ pattern = re.escape(pattern)
+ # Unescape {, }, * that we need to handle specially
+ pattern = pattern.replace(r"\{", "{").replace(r"\}", "}").replace(r"\*", "*")
+ # Convert {variable} to [^/]+
+ pattern = re.sub(r"\{[^}]+\}", r"[^/]+", pattern)
+ # Convert ** to .* and * to [^/]*
+ pattern = pattern.replace("**", ".*")
+ pattern = pattern.replace("*", "[^/]*")
+ # Anchor the pattern
+ pattern = "^" + pattern + "$"
+
+ return bool(re.match(pattern, uri))
+
+
+def is_uri_allowed(
+ uri: str,
+ allowed_directories: Set[str],
+ allowed_patterns: Set[str],
+) -> bool:
+ """
+ Check if a URI is allowed based on allowed directories and patterns.
+
+ Args:
+ uri: The URI to check
+ allowed_directories: Set of allowed directory paths
+ allowed_patterns: Set of allowed path patterns
+
+ Returns:
+ True if the URI is allowed
+ """
+ # Check if URI starts with any allowed directory
+ for dir_path in allowed_directories:
+ if uri == dir_path or uri.startswith(dir_path + "/"):
+ return True
+ # Check if URI matches any allowed pattern
+ for pattern in allowed_patterns:
+ if _pattern_matches_uri(pattern, uri):
+ return True
+ return False
+
+
+def is_uri_allowed_for_schema(
+ uri: str,
+ schemas: List[MemoryTypeSchema],
+ user_space: str = "default",
+ agent_space: str = "default",
+) -> bool:
+ """
+ Check if a URI is allowed for the given activated schemas.
+
+ Args:
+ uri: The URI to check
+ schemas: List of activated memory type schemas
+ user_space: User space to substitute for {user_space}
+ agent_space: Agent space to substitute for {agent_space}
+
+ Returns:
+ True if the URI is allowed
+ """
+ allowed_dirs = collect_allowed_directories(schemas, user_space, agent_space)
+ allowed_patterns = collect_allowed_path_patterns(schemas, user_space, agent_space)
+ return is_uri_allowed(uri, allowed_dirs, allowed_patterns)
+
+
+from openviking.session.memory.utils.model import model_to_dict
+
+
+def extract_uri_fields_from_flat_model(model: Any, schema: MemoryTypeSchema) -> Dict[str, Any]:
+ """
+ Extract URI-friendly fields from a flat model, ignoring patch objects.
+
+ Args:
+ model: Flat model instance (Pydantic model or dict)
+ schema: Memory type schema to know which fields are part of the schema
+
+ Returns:
+ Dict with only primitive type values suitable for URI generation
+ """
+ # Convert model to dict if it's a Pydantic model
+ model_dict = model_to_dict(model)
+
+ uri_fields = {}
+ # Only include fields that are in the schema
+ schema_field_names = {f.name for f in schema.fields}
+ for name, value in model_dict.items():
+ if name in schema_field_names and isinstance(value, (str, int, float, bool)):
+ uri_fields[name] = value
+ return uri_fields
+
+
+def resolve_flat_model_uri(
+ flat_model: Any,
+ registry: MemoryTypeRegistry,
+ user_space: str = "default",
+ agent_space: str = "default",
+) -> str:
+ """
+ Resolve URI for a flat model (used for both write and edit operations).
+
+ Args:
+ flat_model: Flat model instance with memory_type and business fields
+ registry: MemoryTypeRegistry to get schema
+ user_space: User space for substitution
+ agent_space: Agent space for substitution
+
+ Returns:
+ Resolved URI
+
+ Raises:
+ ValueError: If memory_type not found or URI generation fails
+ """
+ # Get memory_type from the model
+ if hasattr(flat_model, 'memory_type'):
+ memory_type_str = flat_model.memory_type
+ elif isinstance(flat_model, dict) and 'memory_type' in flat_model:
+ memory_type_str = flat_model['memory_type']
+ else:
+ raise ValueError("Flat model missing 'memory_type' field")
+
+ schema = registry.get(memory_type_str)
+ if not schema:
+ raise ValueError(f"Unknown memory type: {memory_type_str}")
+
+ # Check if model already has a uri field
+ if hasattr(flat_model, 'uri') and flat_model.uri is not None:
+ return flat_model.uri
+ elif isinstance(flat_model, dict) and 'uri' in flat_model and flat_model['uri'] is not None:
+ return flat_model['uri']
+
+ # Extract URI fields and generate URI
+ uri_fields = extract_uri_fields_from_flat_model(flat_model, schema)
+ return generate_uri(schema, uri_fields, user_space, agent_space)
+
+
+def resolve_overview_edit_uri(
+ overview_model: Any,
+ registry: MemoryTypeRegistry,
+ user_space: str = "default",
+ agent_space: str = "default",
+) -> str:
+ """
+ Resolve URI for an overview edit operation.
+
+ Args:
+ overview_model: Overview edit model with memory_type and overview fields
+ registry: MemoryTypeRegistry to get schema
+ user_space: User space for substitution
+ agent_space: Agent space for substitution
+
+ Returns:
+ Resolved URI for .overview.md file (e.g., viking://user/default/memories/.overview.md)
+
+ Raises:
+ ValueError: If memory_type not found or directory not found
+ """
+ # Get memory_type from model
+ if hasattr(overview_model, 'memory_type'):
+ memory_type_str = overview_model.memory_type
+ elif isinstance(overview_model, dict):
+ memory_type_str = overview_model.get('memory_type')
+ else:
+ raise ValueError("overview_model must have memory_type field")
+
+ # Get schema from registry
+ schema = registry.get(memory_type_str)
+ if not schema:
+ raise ValueError(f"Unknown memory type: {memory_type_str}")
+
+ if not schema.directory:
+ raise ValueError(f"Memory type {memory_type_str} has no directory configured")
+
+ # Substitute user_space and agent_space in directory
+ directory = schema.directory.replace("{user_space}", user_space).replace("{agent_space}", agent_space)
+
+ # Return the .overview.md URI
+ return f"{directory}/.overview.md"
+
+
+class ResolvedOperations:
+ """Operations with resolved URIs."""
+
+ def __init__(self):
+ self.write_operations: List[Tuple[Any, str]] = [] # (flat_model, resolved_uri)
+ self.edit_operations: List[Tuple[Any, str]] = [] # (flat_model, resolved_uri)
+ self.edit_overview_operations: List[Tuple[Any, str]] = [] # (overview_edit_model, overview_uri)
+ self.delete_operations: List[Tuple[str, str]] = [] # (uri_str, uri_str) - just the uri
+ self.errors: List[str] = []
+
+ def has_errors(self) -> bool:
+ return len(self.errors) > 0
+
+
+def resolve_all_operations(
+ operations: Any,
+ registry: MemoryTypeRegistry,
+ user_space: str = "default",
+ agent_space: str = "default",
+) -> ResolvedOperations:
+ """
+ Resolve URIs for all operations using the new flat model format.
+
+ Args:
+ operations: StructuredMemoryOperations with write_uris, edit_uris, delete_uris
+ registry: MemoryTypeRegistry to get schemas
+ user_space: User space for substitution
+ agent_space: Agent space for substitution
+
+ Returns:
+ ResolvedOperations with all URIs resolved
+ """
+ resolved = ResolvedOperations()
+
+ # Resolve write operations (flat models)
+ if hasattr(operations, 'write_uris'):
+ for op in operations.write_uris:
+ try:
+ uri = resolve_flat_model_uri(op, registry, user_space, agent_space)
+ resolved.write_operations.append((op, uri))
+ except Exception as e:
+ resolved.errors.append(f"Failed to resolve write operation: {e}")
+
+ # Resolve edit operations (flat models)
+ if hasattr(operations, 'edit_uris'):
+ for op in operations.edit_uris:
+ try:
+ uri = resolve_flat_model_uri(op, registry, user_space, agent_space)
+ resolved.edit_operations.append((op, uri))
+ except Exception as e:
+ resolved.errors.append(f"Failed to resolve edit operation: {e}")
+
+ # Resolve edit_overview operations (overview edit models)
+ if hasattr(operations, 'edit_overview_uris'):
+ for op in operations.edit_overview_uris:
+ try:
+ uri = resolve_overview_edit_uri(op, registry, user_space, agent_space)
+ resolved.edit_overview_operations.append((op, uri))
+ except Exception as e:
+ resolved.errors.append(f"Failed to resolve edit_overview operation: {e}")
+
+ # Resolve delete operations (already URI strings)
+ if hasattr(operations, 'delete_uris'):
+ for uri in operations.delete_uris:
+ try:
+ # Delete operations are already URIs, just pass them through
+ resolved.delete_operations.append((uri, uri))
+ except Exception as e:
+ resolved.errors.append(f"Failed to resolve delete operation: {e}")
+
+ return resolved
+
+
+def validate_operations_uris(
+ operations: Any,
+ schemas: List[MemoryTypeSchema],
+ registry: MemoryTypeRegistry,
+ user_space: str = "default",
+ agent_space: str = "default",
+) -> Tuple[bool, List[str]]:
+ """
+ Validate that all URIs in StructuredMemoryOperations are allowed.
+
+ Args:
+ operations: The StructuredMemoryOperations to validate
+ schemas: List of activated memory type schemas
+ registry: MemoryTypeRegistry for URI resolution
+ user_space: User space to substitute for {user_space}
+ agent_space: Agent space to substitute for {agent_space}
+
+ Returns:
+ Tuple of (is_valid, list of error messages)
+ """
+ allowed_dirs = collect_allowed_directories(schemas, user_space, agent_space)
+ allowed_patterns = collect_allowed_path_patterns(schemas, user_space, agent_space)
+
+ errors = []
+
+ # First resolve all URIs
+ resolved = resolve_all_operations(operations, registry, user_space, agent_space)
+
+ if resolved.has_errors():
+ errors.extend(resolved.errors)
+ else:
+ # Validate resolved URIs
+ for _op, uri in resolved.write_operations:
+ if not is_uri_allowed(uri, allowed_dirs, allowed_patterns):
+ errors.append(f"Write operation URI not allowed: {uri}")
+
+ for _op, uri in resolved.edit_operations:
+ if not is_uri_allowed(uri, allowed_dirs, allowed_patterns):
+ errors.append(f"Edit operation URI not allowed: {uri}")
+
+ for _op, uri in resolved.edit_overview_operations:
+ if not is_uri_allowed(uri, allowed_dirs, allowed_patterns):
+ errors.append(f"Edit overview operation URI not allowed: {uri}")
+
+ for _uri_str, uri in resolved.delete_operations:
+ if not is_uri_allowed(uri, allowed_dirs, allowed_patterns):
+ errors.append(f"Delete operation URI not allowed: {uri}")
+
+ return len(errors) == 0, errors
diff --git a/openviking/storage/viking_fs.py b/openviking/storage/viking_fs.py
index 744271dce..4e96e14c4 100644
--- a/openviking/storage/viking_fs.py
+++ b/openviking/storage/viking_fs.py
@@ -931,7 +931,7 @@ class VikingFS:
async def search(
self,
query: str,
- target_uri: str = "",
+ target_uri: Union[str, List[str]] = "",
session_info: Optional[Dict] = None,
limit: int = 10,
score_threshold: Optional[float] = None,
@@ -942,7 +942,7 @@ class VikingFS:
Args:
query: Search query
- target_uri: Target directory URI
+ target_uri: Target directory URI(s), supports str or List[str]
session_info: Session information
limit: Return count
filter: Metadata filter
@@ -960,6 +960,11 @@ class VikingFS:
TypedQuery,
)
+ # Normalize target_uri to list
+ target_uri_list = [target_uri] if isinstance(target_uri, str) else (target_uri or [])
+ # Use first URI for context inference and access check
+ primary_target_uri = target_uri_list[0] if target_uri_list else ""
+
summary_list = session_info.get("summaries") if session_info else None
if isinstance(summary_list, list):
session_summary = "\n\n".join(str(item) for item in summary_list if item)
@@ -968,16 +973,16 @@ class VikingFS:
recent_messages = session_info.get("recent_messages") if session_info else None
query_plan: Optional[QueryPlan] = None
- if target_uri and target_uri not in {"/", "viking://"}:
- self._ensure_access(target_uri, ctx)
+ if primary_target_uri and primary_target_uri not in {"/", "viking://"}:
+ self._ensure_access(primary_target_uri, ctx)
# When target_uri exists: read abstract, infer context_type
target_context_type: Optional[ContextType] = None
target_abstract = ""
- if target_uri:
- target_context_type = self._infer_context_type(target_uri)
+ if primary_target_uri:
+ target_context_type = self._infer_context_type(primary_target_uri)
try:
- target_abstract = await self.abstract(target_uri, ctx=ctx)
+ target_abstract = await self.abstract(primary_target_uri, ctx=ctx)
except Exception:
target_abstract = ""
@@ -993,9 +998,9 @@ class VikingFS:
)
typed_queries = query_plan.queries
# Set target_directories
- if target_uri:
+ if target_uri_list:
for tq in typed_queries:
- tq.target_directories = [target_uri]
+ tq.target_directories = target_uri_list
else:
# No session context: create query directly
if target_context_type:
@@ -1006,7 +1011,7 @@ class VikingFS:
context_type=target_context_type,
intent="",
priority=1,
- target_directories=[target_uri] if target_uri else [],
+ target_directories=target_uri_list,
)
]
else:
@@ -1017,7 +1022,7 @@ class VikingFS:
context_type=ctx_type,
intent="",
priority=1,
- target_directories=[target_uri] if target_uri else [],
+ target_directories=target_uri_list,
)
for ctx_type in [ContextType.MEMORY, ContextType.RESOURCE, ContextType.SKILL]
]
diff --git a/openviking_cli/client/http.py b/openviking_cli/client/http.py
index ac091c43b..9383f085f 100644
--- a/openviking_cli/client/http.py
+++ b/openviking_cli/client/http.py
@@ -127,6 +127,7 @@ class AsyncHTTPClient(BaseClient):
self,
url: Optional[str] = None,
api_key: Optional[str] = None,
+ user_id: Optional[str] = None,
agent_id: Optional[str] = None,
account: Optional[str] = None,
user: Optional[str] = None,
@@ -137,6 +138,7 @@ class AsyncHTTPClient(BaseClient):
Args:
url: OpenViking Server URL. If not provided, reads from ovcli.conf.
api_key: API key for authentication. If not provided, reads from ovcli.conf.
+ user_id: User identifier. If not provided, defaults to "default".
agent_id: Agent identifier. If not provided, reads from ovcli.conf.
account: Account identifier for multi-tenant auth. Required when using root key
to access tenant-scoped APIs. If not provided, reads from ovcli.conf.
diff --git a/openviking_cli/utils/config/memory_config.py b/openviking_cli/utils/config/memory_config.py
new file mode 100644
index 000000000..ffcd0adc0
--- /dev/null
+++ b/openviking_cli/utils/config/memory_config.py
@@ -0,0 +1,25 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: Apache-2.0
+from typing import Any, Dict
+
+from pydantic import BaseModel, Field
+
+
+class MemoryConfig(BaseModel):
+ """Memory configuration for OpenViking."""
+
+ version: str = Field(
+ default="v1",
+ description="Memory implementation version: 'v1' (legacy) or 'v2' (new templating system)",
+ )
+
+ model_config = {"extra": "forbid"}
+
+ @classmethod
+ def from_dict(cls, config: Dict[str, Any]) -> "MemoryConfig":
+ """Create configuration from dictionary."""
+ return cls(**config)
+
+ def to_dict(self) -> Dict[str, Any]:
+ """Convert configuration to dictionary."""
+ return self.model_dump()
diff --git a/openviking_cli/utils/config/open_viking_config.py b/openviking_cli/utils/config/open_viking_config.py
index 78ff81f54..4aeb9898a 100644
--- a/openviking_cli/utils/config/open_viking_config.py
+++ b/openviking_cli/utils/config/open_viking_config.py
@@ -37,6 +37,7 @@ from .parser_config import (
from .rerank_config import RerankConfig
from .storage_config import StorageConfig
from .vlm_config import VLMConfig
+from .memory_config import MemoryConfig
class OpenVikingConfig(BaseModel):
@@ -145,6 +146,10 @@ class OpenVikingConfig(BaseModel):
log: LogConfig = Field(default_factory=lambda: LogConfig(), description="Logging configuration")
+ memory: MemoryConfig = Field(
+ default_factory=lambda: MemoryConfig(), description="Memory configuration"
+ )
+
model_config = {"arbitrary_types_allowed": True, "extra": "forbid"}
@classmethod
@@ -192,16 +197,27 @@ class OpenVikingConfig(BaseModel):
for parser_type in parser_types:
if parser_type in config_copy:
parser_configs[parser_type] = config_copy.pop(parser_type)
+
# Handle log configuration from nested "log" section
log_config_data = None
if "log" in config_copy:
log_config_data = config_copy.pop("log")
+ # Handle memory configuration from nested "memory" section
+ memory_config_data = None
+ if "memory" in config_copy:
+ memory_config_data = config_copy.pop("memory")
+
instance = cls(**config_copy)
+
# Apply log configuration
if log_config_data is not None:
instance.log = LogConfig.from_dict(log_config_data)
+ # Apply memory configuration
+ if memory_config_data is not None:
+ instance.memory = MemoryConfig.from_dict(memory_config_data)
+
# Apply parser configurations
for parser_type, parser_data in parser_configs.items():
if hasattr(instance, parser_type):
diff --git a/openviking_cli/utils/config/vlm_config.py b/openviking_cli/utils/config/vlm_config.py
index a8c7da078..9e8260d29 100644
--- a/openviking_cli/utils/config/vlm_config.py
+++ b/openviking_cli/utils/config/vlm_config.py
@@ -1,6 +1,6 @@
# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
# SPDX-License-Identifier: Apache-2.0
-from typing import Any, Dict, Optional
+from typing import Any, Dict, List, Optional, Union
from pydantic import BaseModel, Field, model_validator
@@ -173,17 +173,26 @@ class VLMConfig(BaseModel):
return result
- def get_completion(self, prompt: str, thinking: bool = False) -> str:
+ def get_completion(
+ self,
+ prompt: str = "",
+ thinking: bool = False,
+ tools: Optional[List[Dict[str, Any]]] = None,
+ messages: Optional[List[Dict[str, Any]]] = None,
+ ) -> Union[str, Any]:
"""Get LLM completion."""
- return self.get_vlm_instance().get_completion(prompt, thinking)
+ return self.get_vlm_instance().get_completion(prompt, thinking, tools, messages)
async def get_completion_async(
- self, prompt: str, thinking: bool = False, max_retries: int | None = None
- ) -> str:
- """Get LLM completion asynchronously. Uses self.max_retries if not specified."""
- if max_retries is None:
- max_retries = self.max_retries
- return await self.get_vlm_instance().get_completion_async(prompt, thinking, max_retries)
+ self,
+ prompt: str = "",
+ thinking: bool = False,
+ max_retries: int = 0,
+ tools: Optional[List[Dict[str, Any]]] = None,
+ messages: Optional[List[Dict[str, Any]]] = None,
+ ) -> Union[str, Any]:
+ """Get LLM completion asynchronously, max_retries=0 means no retry."""
+ return await self.get_vlm_instance().get_completion_async(prompt, thinking, max_retries, tools, messages)
def is_available(self) -> bool:
"""Check if LLM is configured."""
@@ -191,18 +200,22 @@ class VLMConfig(BaseModel):
def get_vision_completion(
self,
- prompt: str,
- images: list,
+ prompt: str = "",
+ images: Optional[list] = None,
thinking: bool = False,
- ) -> str:
+ tools: Optional[List[Dict[str, Any]]] = None,
+ messages: Optional[List[Dict[str, Any]]] = None,
+ ) -> Union[str, Any]:
"""Get LLM completion with images."""
- return self.get_vlm_instance().get_vision_completion(prompt, images, thinking)
+ return self.get_vlm_instance().get_vision_completion(prompt, images, thinking, tools, messages)
async def get_vision_completion_async(
self,
- prompt: str,
- images: list,
+ prompt: str = "",
+ images: Optional[list] = None,
thinking: bool = False,
- ) -> str:
+ tools: Optional[List[Dict[str, Any]]] = None,
+ messages: Optional[List[Dict[str, Any]]] = None,
+ ) -> Union[str, Any]:
"""Get LLM completion with images asynchronously."""
- return await self.get_vlm_instance().get_vision_completion_async(prompt, images, thinking)
+ return await self.get_vlm_instance().get_vision_completion_async(prompt, images, thinking, tools, messages)
diff --git a/pyproject.toml b/pyproject.toml
index a57085a46..9234d7602 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -85,6 +85,7 @@ test = [
"ragas>=0.1.0",
"datasets>=2.0.0",
"pandas>=2.0.0",
+ "diff-match-patch>=20200713",
"hvac>=2.0.0",
]
dev = [
diff --git a/tests/integration/test_compressor_v2_e2e.py b/tests/integration/test_compressor_v2_e2e.py
new file mode 100644
index 000000000..d085ff0c2
--- /dev/null
+++ b/tests/integration/test_compressor_v2_e2e.py
@@ -0,0 +1,204 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: Apache-2.0
+
+"""
+End-to-end test for SessionCompressorV2 (memory v2 templating system).
+
+Uses AsyncHTTPClient to connect to local openviking-server at 127.0.0.1:1933.
+No need to worry about ov.conf - server uses its own config.
+"""
+
+from dataclasses import asdict
+import pytest
+import pytest_asyncio
+
+from openviking.message import TextPart
+from openviking_cli.client.http import AsyncHTTPClient
+from openviking_cli.utils import get_logger
+
+logger = get_logger(__name__)
+
+# Server URL - user starts openviking-server separately
+SERVER_URL = "http://127.0.0.1:1933"
+
+
+def create_test_conversation_messages():
+ """Create a conversation that should trigger memory extraction (Chinese with various memory types)"""
+ return [
+ # ===== 个人信息(画像) =====
+ ("user", "你好,我叫李明,是一名软件工程师,在北京工作。"),
+ ("assistant", "你好李明!很高兴认识你。能介绍一下你自己吗?"),
+ ("user", "好的,我今年28岁,浙江杭州人,现在在网易工作,主要做后端开发。"),
+ ("assistant", "很厉害!你在网易做什么项目?"),
+
+ # ===== 个人偏好 =====
+ ("user", "我负责推荐系统相关的开发。对了,我喜欢喝咖啡,每天早上都要喝一杯美式咖啡,不加糖。"),
+ ("assistant", "喝咖啡是个好习惯!你对咖啡有什么特别的偏好吗?"),
+ ("user", "是的,我只喝浅烘焙的咖啡豆,而且必须是来自埃塞俄比亚的耶加雪菲,酸度要高一些的。"),
+ ("assistant", "很讲究啊!除了咖啡,你还有什么其他爱好吗?"),
+
+ # ===== 兴趣爱好 =====
+ ("user", "我周末喜欢去爬山,北京周边的山我基本都爬过了,最喜欢的是香山,秋天的红叶特别美。"),
+ ("assistant", "爬山很锻炼身体!你一般和谁一起去?"),
+ ("user", "通常和我的女朋友张小红一起去,她也很喜欢户外运动,我们还一起加入了一个登山俱乐部。"),
+
+ # ===== 关系记忆 =====
+ ("assistant", "真好!你们在一起多久了?"),
+ ("user", "我们在一起三年了,是2023年的5月20日确定的关系,那天我们在西湖边散步,我向她表白的。"),
+ ("assistant", "很浪漫的日子!你们有计划结婚吗?"),
+
+ # ===== 事件/计划 =====
+ ("user", "有的,我们打算明年春天结婚,婚礼地点初步定在杭州,具体时间还没定,大概是4月份。"),
+ ("assistant", "恭喜恭喜!杭州是个美丽的城市。"),
+ ("user", "是的,我老家就是杭州的,所以想在那里办婚礼。我们还打算去云南度蜜月,想去大理和丽江。"),
+
+ # ===== Agent/项目相关记忆 =====
+ ("assistant", "听起来很棒!对了,你们现在在做什么项目?"),
+ ("user", "我们团队正在做OpenViking项目,这是一个Agent原生的上下文数据库。"),
+ ("assistant", "听起来很有意思!能详细说说吗?"),
+ ("user", "好的,这个项目主要是帮助Agent更好地管理和记忆上下文信息,支持长期记忆的提取和存储。有两种主要的记忆类型:卡片(cards)用于知识笔记,采用Zettelkasten笔记法;事件(events)用于记录重要的决策和时间线。"),
+ ("assistant", "明白了!那技术架构是怎样的?"),
+
+ # ===== 技术知识/卡片 =====
+ ("user", "技术上,我们使用MemoryReAct模式结合LLM来分析对话和生成记忆操作。v2版本使用了YAML配置的模板系统,比v1的8个固定类别更灵活。"),
+ ("assistant", "很有技术含量!你们团队有多少人?"),
+
+ # ===== 团队/组织信息 =====
+ ("user", "我们团队现在有8个人,包括3个前端、4个后端,还有1个产品经理。产品经理叫王芳,她特别擅长用户体验设计。"),
+ ("assistant", "团队配置很齐全!你们平时怎么协作?"),
+
+ # ===== 工作习惯 =====
+ ("user", "我们用敏捷开发,每周一上午开站会,周三进行技术评审,周五下午做代码回顾。我一般早上10点到公司,晚上8点左右下班。"),
+ ("assistant", "很规律的工作节奏!"),
+ ]
+
+
+@pytest_asyncio.fixture(scope="function")
+async def http_client():
+ """Create AsyncHTTPClient connected to local server"""
+ client = AsyncHTTPClient(url=SERVER_URL)
+ await client.initialize()
+
+ yield client
+
+ await client.close()
+
+
+class TestCompressorV2EndToEnd:
+ """End-to-end tests for SessionCompressorV2 via HTTP"""
+
+ @pytest.mark.integration
+ @pytest.mark.asyncio
+ async def test_memory_v2_extraction_e2e(
+ self, http_client: AsyncHTTPClient
+ ):
+ """
+ Test full end-to-end flow:
+ 1. Create session with conversation
+ 2. Commit session (triggers memory extraction)
+ 3. Wait for processing
+ 4. Verify memories were created in storage
+ """
+ client = http_client
+
+ print("=" * 80)
+ print("SessionCompressorV2 END-TO-END TEST (HTTP)")
+ print(f"Server: {SERVER_URL}")
+ print("=" * 80)
+
+ # 1. Create session
+ result = await client.create_session()
+ assert "session_id" in result
+ session_id = result["session_id"]
+ print(f"\nCreated session: {session_id}")
+
+ # 2. Add conversation messages
+ conversation = create_test_conversation_messages()
+ for role, content in conversation:
+ parts = [TextPart(content)]
+ parts_dicts = [asdict(p) for p in parts]
+ await client.add_message(session_id, role, parts=parts_dicts)
+ print(f"[{role}]: {content[:60]}...")
+
+ # 3. Commit session (this should trigger memory extraction)
+ print("\nCommitting session...")
+ commit_result = await client.commit_session(session_id)
+ assert commit_result["status"] == "committed"
+ print(f"Commit result: {commit_result}")
+
+ # 4. Wait for memory extraction to complete
+ print("\nWaiting for processing...")
+ await client.wait_processed()
+ print("Processing complete!")
+
+ # 5. Try to find memories via search
+ print("\nSearching for memories...")
+ find_result = await client.find(query="OpenViking memory cards events")
+ print(f"Find result: total={find_result.total}")
+ print(f" Memories found: {len(getattr(find_result, 'memories', []))}")
+ print(f" Resources found: {len(getattr(find_result, 'resources', []))}")
+
+ # 6. List the memories directory structure and read memory contents
+ print("\nChecking memories directories...")
+
+ # Helper function to read and print memory files
+ async def print_memory_files(uri_prefix: str, memories_list: list):
+ """Read and print memory file contents"""
+ for entry in memories_list:
+ if not entry.get("isDir", False) and entry.get("name", "").endswith(".md"):
+ uri = entry.get("uri", "")
+ if uri:
+ try:
+ content = await client.read(uri)
+ print(f"\n--- {entry['name']} ---")
+ print(content)
+ print("-" * 60)
+ except Exception as e:
+ print(f" Failed to read {uri}: {e}")
+
+ user_space = client._user.user_space_name()
+ agent_space = client._user.agent_space_name()
+
+ try:
+ # Try to list agent memories
+ agent_memories = await client.ls(f"viking://agent/{agent_space}/memories", recursive=True)
+ print(f"Agent memories entries: {len(agent_memories)}")
+ for entry in agent_memories[:20]: # Show first 20
+ print(f" - {entry['name']} ({'dir' if entry['isDir'] else 'file'})")
+ # Read and print memory files
+ await print_memory_files(f"viking://agent/{agent_space}/memories", agent_memories)
+ except Exception as e:
+ print(f"Could not list agent memories: {e}")
+
+ try:
+ # Try to list user memories
+ user_memories = await client.ls(f"viking://user/{user_space}/memories", recursive=True)
+ print(f"\nUser memories entries: {len(user_memories)}")
+ for entry in user_memories[:20]: # Show first 20
+ print(f" - {entry['name']} ({'dir' if entry['isDir'] else 'file'})")
+ # Read and print memory files
+ await print_memory_files(f"viking://user/{user_space}/memories", user_memories)
+ except Exception as e:
+ print(f"Could not list user memories: {e}")
+
+ print("\n" + "=" * 80)
+ print("Test completed!")
+ print("=" * 80)
+ print(f"\nConnected to server: {SERVER_URL}")
+ print(f"Session ID: {session_id}")
+ print("Server uses its own ov.conf configuration")
+ print("Note: Data cleanup is handled by test_restart_openviking_server.sh")
+
+ # The test passes if it doesn't throw an exception
+ # Memory extraction happens in background, v2 writes directly to storage
+ assert True
+
+ @pytest.mark.integration
+ @pytest.mark.asyncio
+ async def test_server_health(
+ self, http_client: AsyncHTTPClient
+ ):
+ """Verify server is healthy"""
+ result = await http_client.health()
+ assert result is True
+ print(f"Server at {SERVER_URL} is healthy")
diff --git a/tests/integration/test_compressor_v2_xiaomei.py b/tests/integration/test_compressor_v2_xiaomei.py
new file mode 100644
index 000000000..a83fa7d54
--- /dev/null
+++ b/tests/integration/test_compressor_v2_xiaomei.py
@@ -0,0 +1,254 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: Apache-2.0
+
+"""
+OpenViking Memory Demo Test - User: 小美 (Xiaomei)
+
+Integration test using the demo conversation from the user.
+Tests memory extraction and recall for a realistic conversation.
+"""
+
+from dataclasses import asdict
+import pytest
+import pytest_asyncio
+
+from openviking.message import TextPart
+from openviking_cli.client.http import AsyncHTTPClient
+from openviking_cli.utils import get_logger
+
+logger = get_logger(__name__)
+
+# Server URL - user starts openviking-server separately
+SERVER_URL = "http://127.0.0.1:1933"
+DISPLAY_NAME = "小美"
+
+
+# ── Conversation data (10 turns user + assistant) ─────────────────────────
+CONVERSATION = [
+ {
+ "user": "嗨!我是小美,刚毕业不久,现在在一家互联网公司做运营。我想找个能帮我记录日常生活的小助手,比如记一下每天发生的事情、我的想法、还有想做的事情。你能帮帮我吗?",
+ "assistant": "你好小美!当然可以,我很乐意当你的生活小助手。你可以随时跟我聊天,我会帮你记住重要的事情。",
+ },
+ {
+ "user": "今天心情还不错!早上在地铁上看到了一个超级可爱的小猫咪,它主人带着它坐车,只露出个小脑袋,太萌了!对了,今天部门开会说下个月要做 618 大促,我负责写活动文案,有点紧张,这是我第一次独立负责这么重要的项目。",
+ "assistant": "看到可爱的猫咪真的很治愈!618 大促是个很好的锻炼机会,第一次独立负责确实会紧张,但这说明领导信任你。你可以先列个文案大纲,慢慢来。",
+ },
+ {
+ "user": "说到吃,中午我跟同事小丽一起去吃了楼下那家麻辣烫,超级好吃!我喜欢多放醋和麻酱,不太能吃辣。不过最近在减肥,不敢吃太多主食。你有没有什么好吃又不胖的推荐呀?",
+ "assistant": "麻辣烫多放醋和麻酱是很经典的搭配。减肥期间可以试试轻食沙拉,或者选麻辣烫里多加蔬菜和豆腐,少放粉丝和面条。",
+ },
+ {
+ "user": "对了,我办了一张健身卡,就在我家小区旁边。上周去了一次,跑了 30 分钟步,还练了会儿瑜伽。结果第二天腿酸得不行,下楼都费劲。教练说让我每周去三次,我怕坚持不下来...",
+ "assistant": "刚开始运动肌肉酸痛是正常的。不用一下子每周三次,先从每周两次开始适应,跑步和瑜伽交替练习,慢慢增加频率。",
+ },
+ {
+ "user": "这个周末你有什么建议吗?我想跟我男朋友一起出去。我们之前想过去看樱花,但好像花期快过了。要不看电影?最近有什么好看的电影吗?或者去探店?我知道有一家咖啡馆好像很不错。",
+ "assistant": "花期快过了的话可以抓紧最后的机会去看。也可以先去那家咖啡馆探店,下午再看场电影,安排一个轻松的约会日。",
+ },
+ {
+ "user": "说起来,我平时喜欢追剧,尤其是那种甜宠剧,最近在看《归路》,太甜了!我还喜欢画画,虽然画得不太好,但挺解压的。偶尔也会看看书,最近在看《被讨厌的勇气》,挺有启发的。",
+ "assistant": "甜宠剧确实很解压。画画也是个很好的放松方式,不用在意画得好不好。《被讨厌的勇气》是本好书,里面关于课题分离的理念很有用。",
+ },
+ {
+ "user": "哎呀,我差点忘了提醒你!我对芒果过敏,吃了会起疹子。上次在公司同事给了我一个芒果蛋糕,我不知道,吃了一口就进医院了,还好不严重。还有,我每天晚上睡觉前都要喝一杯热牛奶,不然会失眠。",
+ "assistant": "芒果过敏一定要注意,我记住了,以后推荐食物会避开芒果相关的。睡前喝热牛奶是个好习惯,有助于睡眠。",
+ },
+ {
+ "user": "最近我种草了一个拍立得,就是富士的 mini12,粉色那款,颜值超级高!但有点贵,要 700 多块钱,还在犹豫要不要买。对了,我还想买一个投影仪,这样周末可以在家看电影。",
+ "assistant": "富士 mini12 粉色确实很好看,适合记录生活。700 多块不算特别贵,可以等促销入手。投影仪也很实用,在家看电影很有氛围。",
+ },
+ {
+ "user": "说到同事,小丽人超好,她说会帮我一起想 618 的文案点子。还有,我闺蜜下周要结婚了!她是我们宿舍第一个结婚的,真为她开心。我还在想送什么礼物好呢,红包肯定要包,但想再加点特别的。",
+ "assistant": "小丽是个好搭档。闺蜜结婚的话,除了红包可以送一本定制相册,把你们大学的照片整理进去,很有纪念意义。",
+ },
+ {
+ "user": "好的,谢谢你听我说了这么多!以后跟我聊天的时候,轻松一点就好,像朋友一样。如果我不开心了,多安慰安慰我;如果我开心,就跟我一起开心。对了,多给我推荐好吃的好玩的,谢谢啦!",
+ "assistant": "没问题小美!以后就当朋友一样聊天,我会记住你的喜好和习惯。有什么开心的或不开心的都可以找我聊。",
+ },
+]
+
+# ── Verification queries ──────────────────────────────────────────────────
+VERIFY_QUERIES = [
+ {
+ "query": "小美的工作情况",
+ "expected_keywords": ["618", "文案", "运营", "小丽"],
+ },
+ {
+ "query": "小美的饮食偏好和注意事项",
+ "expected_keywords": ["芒果过敏", "麻辣烫", "减肥"],
+ },
+ {
+ "query": "小美的爱好",
+ "expected_keywords": ["追剧", "画画", "看书"],
+ },
+ {
+ "query": "小美想买什么",
+ "expected_keywords": ["拍立得", "投影仪"],
+ },
+ {
+ "query": "小美的运动计划",
+ "expected_keywords": ["健身", "瑜伽", "跑步"],
+ },
+]
+
+
+@pytest_asyncio.fixture(scope="function")
+async def http_client():
+ """Create AsyncHTTPClient connected to local server"""
+ client = AsyncHTTPClient(url=SERVER_URL)
+ await client.initialize()
+
+ yield client
+
+ await client.close()
+
+
+class TestXiaomeiMemoryDemo:
+ """Integration test for Xiaomei memory demo"""
+
+ @pytest.mark.integration
+ @pytest.mark.asyncio
+ async def test_xiaomei_memory_extraction_and_recall(
+ self, http_client: AsyncHTTPClient
+ ):
+ """
+ Test full flow:
+ 1. Create session and add conversation messages
+ 2. Commit session (triggers memory extraction)
+ 3. Wait for processing
+ 4. Verify memory recall with queries
+ """
+ client = http_client
+
+ print("\n" + "=" * 80)
+ print(f"OpenViking Memory Demo Test — {DISPLAY_NAME}")
+ print(f"Server: {SERVER_URL}")
+ print("=" * 80)
+
+ # Get user/agent space names
+ user_space = client._user.user_space_name()
+ agent_space = client._user.agent_space_name()
+ print(f"\nUser space: {user_space}")
+ print(f"Agent space: {agent_space}")
+
+ # Phase 1: Create session and add messages
+ print("\n" + "-" * 40)
+ print(f"Phase 1: Ingest conversation ({len(CONVERSATION)} turns)")
+ print("-" * 40)
+
+ result = await client.create_session()
+ assert "session_id" in result
+ session_id = result["session_id"]
+ print(f"\nCreated session: {session_id}")
+
+ # Add conversation messages
+ total = len(CONVERSATION)
+ for i, turn in enumerate(CONVERSATION, 1):
+ print(f" [{i}/{total}] Adding user + assistant message...")
+ # Add user message
+ parts = [TextPart(turn["user"])]
+ parts_dicts = [asdict(p) for p in parts]
+ await client.add_message(session_id, "user", parts=parts_dicts)
+ # Add assistant message
+ parts = [TextPart(turn["assistant"])]
+ parts_dicts = [asdict(p) for p in parts]
+ await client.add_message(session_id, "assistant", parts=parts_dicts)
+
+ print(f"\n Added {total * 2} messages")
+
+ # Commit session
+ print("\n Committing session...")
+ commit_result = await client.commit_session(session_id)
+ assert commit_result["status"] == "committed"
+ print(f" Commit result: {commit_result}")
+
+ # Wait for processing
+ print("\n Waiting for processing...")
+ await client.wait_processed()
+ print(" Processing complete!")
+
+ # Phase 2: Verify memory recall
+ print("\n" + "-" * 40)
+ print(f"Phase 2: Verify memory recall ({len(VERIFY_QUERIES)} queries)")
+ print("-" * 40)
+
+ total_hits = 0
+ total_queries = len(VERIFY_QUERIES)
+
+ for i, item in enumerate(VERIFY_QUERIES, 1):
+ query = item["query"]
+ expected = item["expected_keywords"]
+
+ print(f"\n [{i}/{total_queries}] Query: {query}")
+ print(f" Expected keywords: {', '.join(expected)}")
+
+ try:
+ results = await client.find(query, limit=5)
+
+ # Collect all recall texts
+ 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)
+ recall_texts.append(text)
+ uri = getattr(m, "uri", "")
+ score = getattr(m, "score", 0)
+ print(f" Memory: {uri} (score: {score:.4f})")
+ print(f" {text[:100]}..." if len(text) > 100 else f" {text}")
+ 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)
+ recall_texts.append(text)
+ print(f" Resource: {r.uri} (score: {r.score:.4f})")
+ count += len(results.resources)
+
+ # Check keyword hits
+ all_text = " ".join(recall_texts)
+ hits = [kw for kw in expected if kw in all_text]
+ hit_str = ", ".join(hits) if hits else "None"
+
+ print(f" Recalled: {count}, Hits: {hit_str}")
+ total_hits += len(hits)
+
+ except Exception as e:
+ print(f" ERROR: {e}")
+
+ # List memory files
+ print("\n" + "-" * 40)
+ print("Memory files created:")
+ print("-" * 40)
+
+ try:
+ user_memories = await client.ls(f"viking://user/{user_space}/memories", recursive=True)
+ print(f"\nUser memories ({len(user_memories)} entries):")
+ for entry in user_memories[:20]:
+ print(f" - {entry['name']} ({'dir' if entry['isDir'] else 'file'})")
+ except Exception as e:
+ print(f"Could not list user memories: {e}")
+
+ try:
+ agent_memories = await client.ls(f"viking://agent/{agent_space}/memories", recursive=True)
+ print(f"\nAgent memories ({len(agent_memories)} entries):")
+ for entry in agent_memories[:20]:
+ print(f" - {entry['name']} ({'dir' if entry['isDir'] else 'file'})")
+ except Exception as e:
+ print(f"Could not list agent memories: {e}")
+
+ print("\n" + "=" * 80)
+ print(f"Test completed! Total keyword hits: {total_hits}/{total_queries * len(VERIFY_QUERIES[0]['expected_keywords'])}")
+ print("=" * 80)
+
+ # Test passes if no exception is thrown
+ assert True
+
+ @pytest.mark.integration
+ @pytest.mark.asyncio
+ async def test_server_health(self, http_client: AsyncHTTPClient):
+ """Verify server is healthy"""
+ result = await http_client.health()
+ assert result is True
+ print(f"Server at {SERVER_URL} is healthy")
\ No newline at end of file
diff --git a/tests/session/memory/test_compressor_v2.py b/tests/session/memory/test_compressor_v2.py
new file mode 100644
index 000000000..bd6d14846
--- /dev/null
+++ b/tests/session/memory/test_compressor_v2.py
@@ -0,0 +1,369 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: Apache-2.0
+"""
+Test for SessionCompressorV2.
+
+Uses MockVikingFS and real VLM (from config).
+"""
+
+from unittest.mock import patch
+from typing import Any, Dict, List
+
+import logging
+import pytest
+
+from openviking.message import Message, TextPart
+from openviking.server.identity import RequestContext, Role
+from openviking.session.compressor_v2 import SessionCompressorV2
+from openviking_cli.session.user_id import UserIdentifier
+from openviking_cli.utils.config import get_openviking_config, initialize_openviking_config
+
+# Let openviking logger propagate to pytest
+for logger_name in ["openviking", "openviking.session.memory"]:
+ logger = logging.getLogger(logger_name)
+ logger.propagate = True
+ logger.setLevel(logging.DEBUG)
+
+logger = logging.getLogger(__name__)
+
+
+class MockVikingFS:
+ """Mock VikingFS for testing with unified memory storage."""
+
+ def __init__(self):
+ # Unified storage: key is URI, value is dict with type and content/children
+ self._store: Dict[str, Dict[str, Any]] = {}
+ self._snapshot: Dict[str, str] = {}
+
+ def _get_parent_uri(self, uri: str) -> str:
+ """Get parent directory URI."""
+ # Handle URIs like "viking://agent/default/memories/cards/file.md"
+ parts = uri.split("/")
+ if len(parts) <= 3:
+ return uri # Root or protocol level
+ return "/".join(parts[:-1])
+
+ def _get_name_from_uri(self, uri: str) -> str:
+ """Get file/directory name from URI."""
+ parts = uri.split("/")
+ return parts[-1] if parts else ""
+
+ async def read_file(self, uri: str, **kwargs) -> str:
+ """Mock read_file."""
+ entry = self._store.get(uri)
+ if entry and entry.get("type") == "file":
+ return entry.get("content", "")
+ return ""
+
+ async def write_file(self, uri: str, content: str, **kwargs) -> None:
+ """Mock write_file - automatically updates parent directory entries."""
+ # Create parent directories if they don't exist
+ parent_uri = self._get_parent_uri(uri)
+ if parent_uri and parent_uri != uri:
+ await self.mkdir(parent_uri)
+
+ # Write the file
+ self._store[uri] = {
+ "type": "file",
+ "content": content
+ }
+
+ # Update parent directory's entries
+ if parent_uri and parent_uri in self._store:
+ name = self._get_name_from_uri(uri)
+ # Create entry for this file in parent's children
+ file_entry = {
+ "name": name,
+ "isDir": False,
+ "uri": uri,
+ "abstract": content[:100] if content else ""
+ }
+ # Update or add to parent's children
+ parent = self._store[parent_uri]
+ if "children" not in parent:
+ parent["children"] = []
+ # Remove existing entry if present
+ parent["children"] = [
+ c for c in parent["children"]
+ if c.get("name") != name
+ ]
+ parent["children"].append(file_entry)
+
+ async def ls(self, uri: str, **kwargs) -> List[Dict[str, Any]]:
+ """Mock ls - returns entries from unified storage."""
+ entry = self._store.get(uri)
+ if entry and entry.get("type") == "dir":
+ return entry.get("children", [])
+ return []
+
+ async def mkdir(self, uri: str, **kwargs) -> None:
+ """Mock mkdir - recursively creates parent directories."""
+ if uri in self._store:
+ return # Already exists
+
+ # Create parent directories first
+ parent_uri = self._get_parent_uri(uri)
+ if parent_uri and parent_uri != uri:
+ await self.mkdir(parent_uri)
+
+ # Create this directory
+ self._store[uri] = {
+ "type": "dir",
+ "children": []
+ }
+
+ # Update parent directory's entries
+ if parent_uri and parent_uri in self._store:
+ name = self._get_name_from_uri(uri)
+ dir_entry = {
+ "name": name,
+ "isDir": True,
+ "uri": uri
+ }
+ parent = self._store[parent_uri]
+ # Remove existing entry if present
+ parent["children"] = [
+ c for c in parent.get("children", [])
+ if c.get("name") != name
+ ]
+ parent["children"].append(dir_entry)
+
+ async def rm(self, uri: str, **kwargs) -> None:
+ """Mock rm - removes file and updates parent directory."""
+ if uri not in self._store:
+ return
+
+ # Remove from parent's children
+ parent_uri = self._get_parent_uri(uri)
+ name = self._get_name_from_uri(uri)
+ if parent_uri and parent_uri in self._store:
+ parent = self._store[parent_uri]
+ parent["children"] = [
+ c for c in parent.get("children", [])
+ if c.get("name") != name
+ ]
+
+ # Remove the file/directory
+ del self._store[uri]
+
+ async def stat(self, uri: str, **kwargs) -> Dict[str, Any]:
+ """Mock stat."""
+ entry = self._store.get(uri)
+ if entry:
+ return {"type": entry["type"], "uri": uri}
+ raise FileNotFoundError(f"Not found: {uri}")
+
+ async def find(self, query: str, **kwargs) -> Dict[str, Any]:
+ """Mock find - searches file names and content."""
+ memories = []
+ query_lower = query.lower()
+
+ for uri, entry in self._store.items():
+ if entry.get("type") == "file":
+ name = self._get_name_from_uri(uri)
+ content = entry.get("content", "")
+ if (query_lower in name.lower() or
+ query_lower in content.lower()):
+ memories.append({
+ "uri": uri,
+ "name": name,
+ "abstract": content[:200] if content else ""
+ })
+
+ return {
+ "memories": memories,
+ "resources": [],
+ "skills": [],
+ }
+
+ async def tree(self, uri: str, **kwargs) -> Dict[str, Any]:
+ """Mock tree."""
+ return {"uri": uri, "tree": []}
+
+ def snapshot(self) -> None:
+ """Save a snapshot of the current file state."""
+ self._snapshot = {}
+ for uri, entry in self._store.items():
+ if entry.get("type") == "file":
+ self._snapshot[uri] = entry.get("content", "")
+
+ def diff_since_snapshot(self) -> Dict[str, Dict[str, Any]]:
+ """
+ Compute diff since last snapshot.
+
+ Returns:
+ Dict with keys 'added', 'modified', 'deleted', each mapping URIs to content.
+ """
+ added = {}
+ modified = {}
+ deleted = {}
+
+ # Get current files
+ current_files = {}
+ for uri, entry in self._store.items():
+ if entry.get("type") == "file":
+ current_files[uri] = entry.get("content", "")
+
+ # Check for added/modified files
+ for uri, content in current_files.items():
+ if uri not in self._snapshot:
+ added[uri] = content
+ elif content != self._snapshot[uri]:
+ modified[uri] = {
+ "old": self._snapshot[uri],
+ "new": content
+ }
+
+ # Check for deleted files
+ for uri in self._snapshot:
+ if uri not in current_files:
+ deleted[uri] = self._snapshot[uri]
+
+ return {
+ "added": added,
+ "modified": modified,
+ "deleted": deleted
+ }
+
+
+def create_test_conversation() -> List[Message]:
+ """Create a test conversation focused on cards and events."""
+ messages = []
+
+ # Message 1: User starts talking about a project
+ msg1 = Message(
+ id="msg1",
+ role="user",
+ parts=[TextPart("We're starting the memory extraction feature for the OpenViking project today. This project is an Agent-native context database.")],
+ )
+ messages.append(msg1)
+
+ # Message 2: Assistant responds
+ msg2 = Message(
+ id="msg2",
+ role="assistant",
+ parts=[TextPart("Great! The memory extraction feature is important. What technical approach are we planning to use?")],
+ )
+ messages.append(msg2)
+
+ # Message 3: User talks about architecture decisions
+ msg3 = Message(
+ id="msg3",
+ role="user",
+ parts=[TextPart(
+ "We've decided to use the MemoryReAct pattern, combined with LLMs to analyze conversations and generate memory operations. "
+ "There are two main memory types: cards for knowledge cards (Zettelkasten note-taking method), and events for recording important events and decisions."
+ )],
+ )
+ messages.append(msg3)
+
+ # Message 4: Assistant asks about schemas
+ msg4 = Message(
+ id="msg4",
+ role="assistant",
+ parts=[TextPart("Got it! What's the specific structure of these two schemas?")],
+ )
+ messages.append(msg4)
+
+ # Message 5: User explains schemas
+ msg5 = Message(
+ id="msg5",
+ role="user",
+ parts=[TextPart(
+ "Cards are stored in viking://agent/{agent_space}/memories/cards, each card has name and content fields. "
+ "Events are stored in viking://user/{user_space}/memories/events, each event has event_name, event_time, and content fields."
+ )],
+ )
+ messages.append(msg5)
+
+ return messages
+
+
+class TestCompressorV2:
+ """Tests for SessionCompressorV2."""
+
+ @pytest.mark.integration
+ @pytest.mark.asyncio
+ async def test_extract_long_term_memories(self):
+ """
+ Test SessionCompressorV2.extract_long_term_memories().
+
+ Uses:
+ - MockVikingFS
+ - REAL VLM (from config)
+ """
+ # Initialize config
+ initialize_openviking_config()
+ config = get_openviking_config()
+ logger.info(f"Using config with memory.version = {config.memory.version}")
+
+ # Get real VLM instance
+ vlm = config.vlm.get_vlm_instance()
+ logger.info(f"Using VLM: {vlm}")
+
+ # Create user and context
+ user = UserIdentifier.the_default_user()
+ ctx = RequestContext(user=user, role=Role.ROOT)
+
+ # Create mock VikingFS
+ viking_fs = MockVikingFS()
+
+ # Note: SessionCompressorV2 doesn't actually use vikingdb parameter
+ vikingdb = None
+
+ # Create test conversation
+ messages = create_test_conversation()
+
+ # Format conversation for display
+ conversation_str = "\n".join([f"[{msg.role}]: {msg.content}" for msg in messages])
+
+ print("=" * 80)
+ print("SessionCompressorV2 TEST")
+ print("=" * 80)
+ print(f"\nConversation ({len(messages)} messages):")
+ print("-" * 80)
+ print(conversation_str[:1000] + "..." if len(conversation_str) > 1000 else conversation_str)
+ print("-" * 80)
+
+ # Create SessionCompressorV2
+ compressor = SessionCompressorV2(vikingdb=vikingdb)
+
+ # Take snapshot before running
+ viking_fs.snapshot()
+
+ # Patch get_viking_fs() to return our mock
+ # Need to patch it in all the places it's used
+ with patch('openviking.session.memory.memory_react.get_viking_fs', return_value=viking_fs):
+ with patch('openviking.session.memory.memory_updater.get_viking_fs', return_value=viking_fs):
+ with patch('openviking.session.compressor_v2.get_viking_fs', return_value=viking_fs):
+ # Actually call extract_long_term_memories()
+ logger.info("Calling SessionCompressorV2.extract_long_term_memories()...")
+ memories = await compressor.extract_long_term_memories(
+ messages=messages,
+ user=user,
+ session_id="test-session-v2",
+ ctx=ctx,
+ strict_extract_errors=True,
+ )
+
+ # Verify results
+ print("\n" + "=" * 80)
+ print("TEST RESULTS")
+ print("=" * 80)
+ print(f"Returned memories list length: {len(memories)}")
+ print(f"Note: v2 returns empty list because it writes directly to storage")
+ print("=" * 80)
+
+ # Check what changed
+ diff = viking_fs.diff_since_snapshot()
+ print(f"\nChanges detected:")
+ print(f" Added: {len(diff['added'])} files")
+ print(f" Modified: {len(diff['modified'])} files")
+ print(f" Deleted: {len(diff['deleted'])} files")
+
+ # The list can be empty - v2 writes directly to storage
+ # The important thing is that it didn't throw an exception
+ assert memories is not None
+ assert isinstance(memories, list)
+
+ logger.info("Test completed successfully!")
diff --git a/tests/session/memory/test_json_stability.py b/tests/session/memory/test_json_stability.py
new file mode 100644
index 000000000..37ed2aca0
--- /dev/null
+++ b/tests/session/memory/test_json_stability.py
@@ -0,0 +1,362 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: Apache-2.0
+"""
+Tests for JSON stable parsing utilities.
+"""
+
+import json
+from typing import List, Optional
+
+import pytest
+from pydantic import BaseModel, Field
+
+from openviking.session.memory.utils import (
+ remove_json_trailing_content,
+ extract_json_content,
+ extract_json_from_markdown,
+ parse_memory_file_with_fields,
+ value_fault_tolerance,
+ parse_value_with_tolerance,
+ parse_json_with_stability,
+ _get_origin_type,
+ _get_arg_type,
+ _any_to_str,
+)
+
+
+class TestExtractJsonContent:
+ """Tests for Layer 1: JSON extraction (both leading and trailing)."""
+
+ def test_removes_trailing_content_after_closing_brace(self):
+ """Test that content after the last } is removed."""
+ content = '''{"reasonning": "test", "write_uris": []}
+
+Note: This is a safety warning from the model.'''
+ result = extract_json_content(content)
+ assert result == '{"reasonning": "test", "write_uris": []}'
+
+ def test_removes_trailing_content_after_closing_bracket(self):
+ """Test that content after the last ] is removed."""
+ content = '''[{"reasonning": "test"}]
+
+Extra content after.'''
+ result = extract_json_content(content)
+ assert result == '[{"reasonning": "test"}]'
+
+ def test_handles_leading_content_before_json(self):
+ """Test that content before the first { is removed."""
+ content = '''Here's the JSON:
+{"reasonning": "test", "write_uris": []}'''
+ result = extract_json_content(content)
+ assert result == '{"reasonning": "test", "write_uris": []}'
+
+ def test_handles_both_leading_and_trailing_content(self):
+ """Test that both content before { and after } are removed."""
+ content = '''Alright, let me analyze this.
+
+First, I need to create some memory entries.
+{"reasonning": "test", "write_uris": [{"memory_type": "cards", "name": "test"}]}
+
+That's all for now.'''
+ result = extract_json_content(content)
+ parsed = json.loads(result)
+ assert parsed['reasonning'] == 'test'
+ assert len(parsed['write_uris']) == 1
+
+ def test_preserves_nested_structures(self):
+ """Test that nested structures are preserved correctly."""
+ content = '''{"reasonning": "test", "write_uris": [{"memory_type": "preferences", "topic": "test"}]}
+
+Trailing content.'''
+ result = extract_json_content(content)
+ assert 'Trailing' not in result
+ parsed = json.loads(result)
+ assert parsed['reasonning'] == 'test'
+ assert len(parsed['write_uris']) == 1
+
+ def test_empty_string_returns_empty(self):
+ """Test empty string input returns empty string."""
+ assert extract_json_content('') == ''
+ assert extract_json_content(' ') == ' '
+
+
+class TestRemoveJsonTrailingContent:
+ """Tests for deprecated remove_json_trailing_content (alias for extract_json_content)."""
+
+ def test_alias_works(self):
+ """Test that remove_json_trailing_content is an alias for extract_json_content."""
+ content = '''Alright, let's see.
+{"reasonning": "test"}
+And then some.'''
+ result1 = extract_json_content(content)
+ result2 = remove_json_trailing_content(content)
+ assert result1 == result2
+
+
+class TestExtractJsonFromMarkdown:
+ """Tests for markdown extraction."""
+
+ def test_extracts_json_from_json_code_block(self):
+ """Test JSON wrapped in ```json ... ```."""
+ content = '''```json
+{"reasonning": "test", "write_uris": []}
+```'''
+ result = extract_json_from_markdown(content)
+ assert result == '{"reasonning": "test", "write_uris": []}'
+
+ def test_extracts_json_from_generic_code_block(self):
+ """Test JSON wrapped in ``` ... ``` without json specifier."""
+ content = '''```
+{"reasonning": "test"}
+```'''
+ result = extract_json_from_markdown(content)
+ assert result == '{"reasonning": "test"}'
+
+ def test_returns_plain_json_when_no_markdown(self):
+ """Test plain JSON without markdown is returned as-is."""
+ content = '{"reasonning": "test"}'
+ result = extract_json_from_markdown(content)
+ assert result == content
+
+
+class TestValueFaultTolerance:
+ """Tests for Layer 4: Value-level fault tolerance."""
+
+ def test_none_string_converts_to_none(self):
+ """Test 'None' string converts to None for non-str types."""
+ assert value_fault_tolerance(int, 'None') is None
+ assert value_fault_tolerance(List[str], 'None') is None
+
+ def test_none_string_remains_string_for_str_type(self):
+ """Test 'None' remains as string when target type is str."""
+ assert value_fault_tolerance(str, 'None') == 'None'
+
+ def test_list_converts_to_string(self):
+ """Test list converts to comma-separated string for str type."""
+ assert value_fault_tolerance(str, ['a', 'b', 'c']) == 'a,b,c'
+
+ def test_dict_converts_to_json_string(self):
+ """Test dict converts to JSON string for str type."""
+ result = value_fault_tolerance(str, {'key': 'value'})
+ assert 'key' in result
+ assert 'value' in result
+
+ def test_number_converts_to_string(self):
+ """Test numbers convert to string for str type."""
+ assert value_fault_tolerance(str, 42) == '42'
+ assert value_fault_tolerance(str, 3.14) == '3.14'
+ assert value_fault_tolerance(str, True) == 'True'
+
+ def test_string_converts_to_int(self):
+ """Test string converts to int for int type."""
+ assert value_fault_tolerance(int, '42') == 42
+
+ def test_string_converts_to_float(self):
+ """Test string converts to float for float type."""
+ assert value_fault_tolerance(float, '3.14') == 3.14
+
+ def test_string_wraps_to_list(self):
+ """Test string wraps in list for list type."""
+ assert value_fault_tolerance(List[str], 'test') == ['test']
+
+ def test_dict_wraps_to_list(self):
+ """Test dict wraps in list for list type."""
+ result = value_fault_tolerance(List[dict], {'key': 'value'})
+ assert result == [{'key': 'value'}]
+
+
+class TestTypeHelpers:
+ """Tests for _get_origin_type and _get_arg_type."""
+
+ def test_get_origin_type_from_optional(self):
+ """Test extracts type from Optional[T]."""
+ assert _get_origin_type(Optional[str]) == str
+ assert _get_origin_type(Optional[int]) == int
+
+ def test_get_origin_type_from_list(self):
+ """Test returns list for List[T]."""
+ assert _get_origin_type(List[str]) == list
+
+ def test_get_arg_type_from_list(self):
+ """Test extracts item type from List[T]."""
+ assert _get_arg_type(List[str]) == str
+ assert _get_arg_type(List[int]) == int
+
+
+class TestParseJsonWithStability:
+ """Tests for full five-layer stable JSON parsing."""
+
+ class TestModel(BaseModel):
+ reasonning: str = ''
+ count: Optional[int] = None
+ tags: List[str] = Field(default_factory=list)
+
+ def test_parses_valid_json(self):
+ """Test valid JSON parses successfully."""
+ content = '{"reasonning": "test", "count": 42, "tags": ["a", "b"]}'
+ data, error = parse_json_with_stability(content, model_class=self.TestModel)
+ assert error is None
+ assert data.reasonning == 'test'
+ assert data.count == 42
+ assert data.tags == ['a', 'b']
+
+ def test_handles_list_wrapped_response(self):
+ """Test [{"..."}] is handled correctly."""
+ content = '[{"reasonning": "test", "count": 42}]'
+ data, error = parse_json_with_stability(content, model_class=self.TestModel)
+ assert error is None
+ assert data.reasonning == 'test'
+
+ def test_filters_extra_fields(self):
+ """Test extra fields are filtered when expected_fields is provided."""
+ content = '{"reasonning": "test", "extra_field": "should be filtered", "count": 42}'
+ data, error = parse_json_with_stability(
+ content,
+ model_class=self.TestModel,
+ expected_fields=['reasonning', 'count', 'tags'],
+ )
+ assert error is None
+ assert data.reasonning == 'test'
+ assert data.count == 42
+
+ def test_returns_raw_dict_when_no_model_class(self):
+ """Test returns dict when no model_class is provided."""
+ content = '{"reasonning": "test"}'
+ data, error = parse_json_with_stability(content)
+ assert error is None
+ assert isinstance(data, dict)
+ assert data['reasonning'] == 'test'
+
+ def test_handles_trailing_content(self):
+ """Test JSON with trailing content parses."""
+ content = '''{"reasonning": "test"}
+
+Note: This is a safety warning.
+Please be careful with the output.'''
+ data, error = parse_json_with_stability(content, model_class=self.TestModel)
+ assert error is None
+ assert data.reasonning == 'test'
+
+ def test_handles_markdown_code_blocks(self):
+ """Test JSON wrapped in markdown parses."""
+ content = '''```json
+{"reasonning": "test", "count": 42}
+```'''
+ data, error = parse_json_with_stability(content, model_class=self.TestModel)
+ assert error is None
+ assert data.reasonning == 'test'
+
+ def test_returns_error_for_completely_invalid_content(self):
+ """Test completely invalid content returns error."""
+ content = 'This is not JSON at all'
+ data, error = parse_json_with_stability(content)
+ assert data is None
+ assert error is not None
+
+
+class TestMemoryOperationsIntegration:
+ """Integration tests with MemoryOperations-like models."""
+
+ class SimpleWriteOperation(BaseModel):
+ memory_type: str
+ topic: str
+
+ class SimpleOperations(BaseModel):
+ reasonning: str = ''
+ write_uris: List['TestMemoryOperationsIntegration.SimpleWriteOperation'] = Field(default_factory=list)
+ delete_uris: List[str] = Field(default_factory=list)
+
+ def test_parses_nested_write_operations(self):
+ """Test nested write operations parse correctly."""
+ content = '''{
+ "reasonning": "Added user preferences",
+ "write_uris": [
+ {"memory_type": "preferences", "topic": "theme"},
+ {"memory_type": "preferences", "topic": "notifications"}
+ ]
+ }'''
+ data, error = parse_json_with_stability(content, model_class=self.SimpleOperations)
+ assert error is None
+ assert data.reasonning == 'Added user preferences'
+ assert len(data.write_uris) == 2
+ assert data.write_uris[0].topic == 'theme'
+
+ def test_handles_string_instead_of_list_for_delete(self):
+ """Test single string for delete_uris wraps to list via tolerance."""
+ # Note: This would need field-level tolerance applied
+ content = '''{
+ "reasonning": "Removed old memory",
+ "delete_uris": "viking://user/default/memories/old.md"
+ }'''
+ # First parse as raw dict
+ data, error = parse_json_with_stability(content)
+ assert error is None
+ assert data['delete_uris'] == 'viking://user/default/memories/old.md'
+
+
+class TestParseMemoryFileWithFields:
+ """Tests for parse_memory_file_with_fields function."""
+
+ def test_parses_memory_fields_comment(self):
+ """Test parsing MEMORY_FIELDS HTML comment."""
+ content = '''<!-- MEMORY_FIELDS
+{
+ "tool_name": "web_search",
+ "static_desc": "Searches the web for information",
+ "total_calls": 100,
+ "success_count": 92
+}
+-->
+Here is the actual file content.
+It has multiple lines.'''
+ result = parse_memory_file_with_fields(content)
+ assert result["tool_name"] == "web_search"
+ assert result["static_desc"] == "Searches the web for information"
+ assert result["total_calls"] == 100
+ assert result["success_count"] == 92
+ assert "Here is the actual file content" in result["content"]
+ assert "<!-- MEMORY_FIELDS" not in result["content"]
+
+ def test_returns_only_content_when_no_comment(self):
+ """Test returns only content when no MEMORY_FIELDS comment."""
+ content = "Just plain file content\nwithout any special comments"
+ result = parse_memory_file_with_fields(content)
+ assert list(result.keys()) == ["content"]
+ assert result["content"] == content
+
+ def test_handles_empty_content(self):
+ """Test handles empty string input."""
+ result = parse_memory_file_with_fields("")
+ assert result["content"] == ""
+
+ def test_handles_invalid_json_in_comment(self):
+ """Test handles invalid JSON in MEMORY_FIELDS comment gracefully."""
+ # Use truly invalid JSON that even json_repair can't parse
+ content = '''<!-- MEMORY_FIELDS
+not json at all, just random text
+-->
+File content'''
+ result = parse_memory_file_with_fields(content)
+ assert "File content" in result["content"]
+ # No extra fields added
+ assert "not" not in result
+
+ def test_removes_comment_from_content(self):
+ """Test that the comment is completely removed from content."""
+ content = '''Before comment
+<!-- MEMORY_FIELDS {"test": "value"} -->
+After comment'''
+ result = parse_memory_file_with_fields(content)
+ assert "<!-- MEMORY_FIELDS" not in result["content"]
+ assert "Before comment" in result["content"]
+ assert "After comment" in result["content"]
+ assert result["test"] == "value"
+
+ def test_fields_on_same_line(self):
+ """Test MEMORY_FIELDS on single line."""
+ content = '''<!-- MEMORY_FIELDS {"tool_name": "test", "value": 42} -->
+Content'''
+ result = parse_memory_file_with_fields(content)
+ assert result["tool_name"] == "test"
+ assert result["value"] == 42
+ assert result["content"] == "Content"
diff --git a/tests/session/memory/test_memory_extractor_flow.py b/tests/session/memory/test_memory_extractor_flow.py
new file mode 100644
index 000000000..7f8611f97
--- /dev/null
+++ b/tests/session/memory/test_memory_extractor_flow.py
@@ -0,0 +1,732 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: Apache-2.0
+"""
+Test memory extraction flow with memory module components.
+
+This test simulates the complete memory extraction workflow:
+1. Setup conversation messages
+2. Pre-fetch memory directory structure
+3. Call ReAct orchestrator to analyze and determine memory changes
+4. Generate memory operations
+5. Apply operations via MemoryUpdater
+"""
+
+from unittest.mock import AsyncMock, MagicMock, patch
+from typing import Any, Dict, List, Optional, Tuple
+from dataclasses import dataclass
+
+import logging
+import pytest
+
+# 让 openviking logger 的日志 propagate 到 pytest
+for logger_name in ["openviking", "openviking.session.memory"]:
+ logger = logging.getLogger(logger_name)
+ logger.propagate = True
+ logger.setLevel(logging.DEBUG)
+
+# Module logger for this test
+logger = logging.getLogger(__name__)
+
+from openviking.message import Message, TextPart
+from openviking.server.identity import RequestContext, Role
+from openviking.session.memory import (
+ MemoryOperations,
+ MemoryReAct,
+ MemoryUpdater,
+ MemoryUpdateResult,
+)
+from openviking_cli.session.user_id import UserIdentifier
+from openviking_cli.utils.config import get_openviking_config, initialize_openviking_config
+
+
+class MockVikingFS:
+ """Mock VikingFS for testing with unified memory storage."""
+
+ def __init__(self):
+ # Unified storage: key is URI, value is dict with type and content/children
+ self._store: Dict[str, Dict[str, Any]] = {}
+ self._snapshot: Dict[str, str] = {}
+
+ def _get_parent_uri(self, uri: str) -> str:
+ """Get parent directory URI."""
+ # Handle URIs like "viking://agent/default/memories/cards/file.md"
+ parts = uri.split("/")
+ if len(parts) <= 3:
+ return uri # Root or protocol level
+ return "/".join(parts[:-1])
+
+ def _get_name_from_uri(self, uri: str) -> str:
+ """Get file/directory name from URI."""
+ parts = uri.split("/")
+ return parts[-1] if parts else ""
+
+ async def read_file(self, uri: str, **kwargs) -> str:
+ """Mock read_file."""
+ entry = self._store.get(uri)
+ if entry and entry.get("type") == "file":
+ return entry.get("content", "")
+ return ""
+
+ async def write_file(self, uri: str, content: str, **kwargs) -> None:
+ """Mock write_file - automatically updates parent directory entries."""
+ # Create parent directories if they don't exist
+ parent_uri = self._get_parent_uri(uri)
+ if parent_uri and parent_uri != uri:
+ await self.mkdir(parent_uri)
+
+ # Write the file
+ self._store[uri] = {
+ "type": "file",
+ "content": content
+ }
+
+ # Update parent directory's entries
+ if parent_uri and parent_uri in self._store:
+ name = self._get_name_from_uri(uri)
+ # Create entry for this file in parent's children
+ file_entry = {
+ "name": name,
+ "isDir": False,
+ "uri": uri,
+ "abstract": content[:100] if content else ""
+ }
+ # Update or add to parent's children
+ parent = self._store[parent_uri]
+ if "children" not in parent:
+ parent["children"] = []
+ # Remove existing entry if present
+ parent["children"] = [
+ c for c in parent["children"]
+ if c.get("name") != name
+ ]
+ parent["children"].append(file_entry)
+
+ async def ls(self, uri: str, **kwargs) -> List[Dict[str, Any]]:
+ """Mock ls - returns entries from unified storage."""
+ entry = self._store.get(uri)
+ if entry and entry.get("type") == "dir":
+ return entry.get("children", [])
+ return []
+
+ async def mkdir(self, uri: str, **kwargs) -> None:
+ """Mock mkdir - recursively creates parent directories."""
+ if uri in self._store:
+ return # Already exists
+
+ # Create parent directories first
+ parent_uri = self._get_parent_uri(uri)
+ if parent_uri and parent_uri != uri:
+ await self.mkdir(parent_uri)
+
+ # Create this directory
+ self._store[uri] = {
+ "type": "dir",
+ "children": []
+ }
+
+ # Update parent directory's entries
+ if parent_uri and parent_uri in self._store:
+ name = self._get_name_from_uri(uri)
+ dir_entry = {
+ "name": name,
+ "isDir": True,
+ "uri": uri
+ }
+ parent = self._store[parent_uri]
+ # Remove existing entry if present
+ parent["children"] = [
+ c for c in parent["children"]
+ if c.get("name") != name
+ ]
+ parent["children"].append(dir_entry)
+
+ async def rm(self, uri: str, **kwargs) -> None:
+ """Mock rm - removes file and updates parent directory."""
+ if uri not in self._store:
+ return
+
+ # Remove from parent's children
+ parent_uri = self._get_parent_uri(uri)
+ name = self._get_name_from_uri(uri)
+ if parent_uri and parent_uri in self._store:
+ parent = self._store[parent_uri]
+ parent["children"] = [
+ c for c in parent.get("children", [])
+ if c.get("name") != name
+ ]
+
+ # Remove the file/directory
+ del self._store[uri]
+
+ async def stat(self, uri: str, **kwargs) -> Dict[str, Any]:
+ """Mock stat."""
+ entry = self._store.get(uri)
+ if entry:
+ return {"type": entry["type"], "uri": uri}
+ raise FileNotFoundError(f"Not found: {uri}")
+
+ async def find(self, query: str, **kwargs) -> Dict[str, Any]:
+ """Mock find - searches file names and content."""
+ memories = []
+ query_lower = query.lower()
+
+ for uri, entry in self._store.items():
+ if entry.get("type") == "file":
+ name = self._get_name_from_uri(uri)
+ content = entry.get("content", "")
+ if (query_lower in name.lower() or
+ query_lower in content.lower()):
+ memories.append({
+ "uri": uri,
+ "name": name,
+ "abstract": content[:200] if content else ""
+ })
+
+ return {
+ "memories": memories,
+ "resources": [],
+ "skills": [],
+ }
+
+ async def tree(self, uri: str, **kwargs) -> Dict[str, Any]:
+ """Mock tree."""
+ return {"uri": uri, "tree": []}
+
+ def snapshot(self) -> None:
+ """Save a snapshot of the current file state."""
+ self._snapshot = {}
+ for uri, entry in self._store.items():
+ if entry.get("type") == "file":
+ self._snapshot[uri] = entry.get("content", "")
+
+ def diff_since_snapshot(self) -> Dict[str, Dict[str, Any]]:
+ """
+ Compute diff since last snapshot.
+
+ Returns:
+ Dict with keys 'added', 'modified', 'deleted', each mapping URIs to content.
+ """
+ added = {}
+ modified = {}
+ deleted = {}
+
+ # Get current files
+ current_files = {}
+ for uri, entry in self._store.items():
+ if entry.get("type") == "file":
+ current_files[uri] = entry.get("content", "")
+
+ # Check for added/modified files
+ for uri, content in current_files.items():
+ if uri not in self._snapshot:
+ added[uri] = content
+ elif content != self._snapshot[uri]:
+ modified[uri] = {
+ "old": self._snapshot[uri],
+ "new": content
+ }
+
+ # Check for deleted files
+ for uri in self._snapshot:
+ if uri not in current_files:
+ deleted[uri] = self._snapshot[uri]
+
+ return {
+ "added": added,
+ "modified": modified,
+ "deleted": deleted
+ }
+
+
+def print_diff(diff: Dict[str, Dict[str, str]]) -> None:
+ """
+ Print diff in a readable format using diff-match-patch with colors.
+ Uses inline color codes to show character-level changes on the same line.
+ """
+ # ANSI color codes - 9m=删除线,31m=红色字体,32m=绿色
+ STYLE_DELETE = "\033[9m\033[31m"
+ STYLE_INSERT = "\033[32m"
+ STYLE_RESET = "\033[0m"
+ YELLOW = "\033[33m"
+ GREEN = "\033[32m"
+ RED = "\033[31m"
+
+ try:
+ from diff_match_patch import diff_match_patch
+ has_dmp = True
+ except ImportError:
+ has_dmp = False
+
+ print("\n" + "=" * 80)
+ print(f"{YELLOW}MEMORY CHANGES DIFF (Character-level){STYLE_RESET}")
+ print("=" * 80)
+
+ # Added files
+ if diff["added"]:
+ print(f"\n{GREEN}[ADDED] {len(diff['added'])} file(s):{STYLE_RESET}")
+ for uri, content in diff["added"].items():
+ print(f"\n {uri}")
+ print(" " + "-" * 76)
+ for line in content.split("\n"):
+ print(f"{GREEN} + {line}{STYLE_RESET}")
+
+ # Modified files
+ if diff["modified"]:
+ print(f"\n[MODIFIED] {len(diff['modified'])} file(s):")
+ for uri, changes in diff["modified"].items():
+ print(f"\n {uri}")
+ print(" " + "-" * 76)
+
+ old_text = changes["old"] or ""
+ new_text = changes["new"] or ""
+
+ if has_dmp and old_text and new_text:
+ try:
+ dmp = diff_match_patch()
+ # Compute character-level diff and clean up
+ diffs = dmp.diff_main(old_text, new_text)
+ dmp.diff_cleanupSemantic(diffs) # 优化diff结果,减少冗余
+
+ # Format output with inline colors - character-level on same line
+ _print_inline_diff(diffs, STYLE_DELETE, STYLE_INSERT, STYLE_RESET)
+ except Exception as e:
+ # Fallback to simple line-by-line comparison
+ logger.exception("diff_match_patch fail",e)
+ else:
+ logger.exception("has_dmp= False")
+
+ # Deleted files
+ if diff["deleted"]:
+ print(f"\n{RED}[DELETED] {len(diff['deleted'])} file(s):{STYLE_RESET}")
+ for uri, content in diff["deleted"].items():
+ print(f"\n {uri}")
+ print(" " + "-" * 76)
+ for line in content.split("\n"):
+ print(f"{RED} - {line}{STYLE_RESET}")
+
+ if not any(diff.values()):
+ print("\n No changes detected.")
+
+ print("\n" + "=" * 80 + "\n")
+
+
+def _print_inline_diff(diffs: List[Tuple[int, str]], style_delete: str, style_insert: str, style_reset: str) -> None:
+ """
+ Print character-level diff with inline colors.
+
+ Shows deletions in red strikethrough and insertions in green,
+ all in the same line flow for easy reading.
+ """
+ output = []
+
+ for op, text in diffs:
+ if op == 0: # 文本无差异:正常显示
+ output.append(f"{text}")
+ elif op == -1: # 文本删除:红色删除线
+ output.append('\n'.join([f'{style_delete}{t}{style_reset}' for t in text.split('\n')]))
+ elif op == 1: # 文本新增:绿色
+ output.append('\n'.join([f'{style_insert}{t}{style_reset}' for t in text.split('\n')]))
+
+ # 合并并打印最终结果,添加行号
+ formatted_text = "".join(output)
+ for idx, line in enumerate(formatted_text.split('\n')):
+ print(f" {idx+1}: {line}")
+
+
+def create_test_conversation() -> List[Message]:
+ """Create a test conversation focused on cards and events."""
+ user = UserIdentifier.the_default_user()
+ ctx = RequestContext(user=user, role=Role.ROOT)
+
+ messages = []
+
+ # Message 1: User starts talking about a project
+ msg1 = Message(
+ id="msg1",
+ role="user",
+ parts=[TextPart("We're starting the memory extraction feature for the OpenViking project today. This project is an Agent-native context database.")],
+ )
+ messages.append(msg1)
+
+ # Message 2: Assistant responds
+ msg2 = Message(
+ id="msg2",
+ role="assistant",
+ parts=[TextPart("Great! The memory extraction feature is important. What technical approach are we planning to use?")],
+ )
+ messages.append(msg2)
+
+ # Message 3: User talks about architecture decisions
+ msg3 = Message(
+ id="msg3",
+ role="user",
+ parts=[TextPart(
+ "We've decided to use the MemoryReAct pattern, combined with LLMs to analyze conversations and generate memory operations. "
+ "There are two main memory types: cards for knowledge cards (Zettelkasten note-taking method), and events for recording important events and decisions."
+ )],
+ )
+ messages.append(msg3)
+
+ # Message 4: Assistant asks about schemas
+ msg4 = Message(
+ id="msg4",
+ role="assistant",
+ parts=[TextPart("Got it! What's the specific structure of these two schemas?")],
+ )
+ messages.append(msg4)
+
+ # Message 5: User explains schemas
+ msg5 = Message(
+ id="msg5",
+ role="user",
+ parts=[TextPart(
+ "Cards are stored in viking://agent/{agent_space}/memories/cards, each card has name and content fields. "
+ "Events are stored in viking://user/{user_space}/memories/events, each event has event_name, event_time, and content fields. "
+ "Just now, we also decided to add diff-match-patch to print memory modification differences."
+ )],
+ )
+ messages.append(msg5)
+
+ return messages
+
+
+def create_existing_memories_content() -> Dict[str, str]:
+ """Create existing memory content for update test with cards and events."""
+ return {
+ "viking://agent/default/memories/cards/openviking_project.md": """# OpenViking Project
+
+## Overview
+OpenViking is an Agent-native context database.
+
+## Technical Approach
+- Uses MemoryReAct pattern
+- Combines LLM to analyze conversations and generate memory operations
+
+
+<!-- MEMORY_FIELDS
+{
+ "name": "openviking_project"
+}
+-->""",
+ "viking://agent/default/memories/cards/memory_react.md": """# MemoryReAct Pattern
+
+## Overview
+MemoryReAct is an orchestrator pattern for memory extraction.
+
+## Features
+- Analyze conversation content
+- Generate memory operations
+
+
+<!-- MEMORY_FIELDS
+{
+ "name": "memory_react"
+}
+-->""",
+ "viking://user/default/memories/events/2026-03-20_Started_memory_extraction_feature_development.md": """# Event: Started memory extraction feature development
+
+## Event Name
+Started memory extraction feature development
+
+## Event Time
+2026-03-20
+
+## Content
+Today we started working on the memory extraction feature for the OpenViking project. Decided to use the MemoryReAct pattern.
+
+
+<!-- MEMORY_FIELDS
+{
+ "event_name": "Started_memory_extraction_feature_development",
+ "event_time": "2026-03-20"
+}
+-->""",
+ }
+
+
+def create_update_conversation() -> List[Message]:
+ """Create a conversation for updating existing cards and events."""
+ user = UserIdentifier.the_default_user()
+ ctx = RequestContext(user=user, role=Role.ROOT)
+
+ messages = []
+
+ # Message 1: User corrects and adds details to existing OpenViking project card
+ msg1 = Message(
+ id="msg1",
+ role="user",
+ parts=[TextPart(
+ "I just looked at our OpenViking project card and need to correct it: "
+ "OpenViking is not just a context database, it's an Agent-native memory system, "
+ "supporting multi-level memory (L0/L1/L2) and incremental updates. "
+ "Also, in the technical approach section, we not only use the MemoryReAct pattern, "
+ "but also need to support schema-driven memory extraction."
+ )],
+ )
+ messages.append(msg1)
+
+ # Message 2: Assistant responds
+ msg2 = Message(
+ id="msg2",
+ role="assistant",
+ parts=[TextPart("Okay, I'll update the project card! Does the MemoryReAct pattern description need adjustment too?")],
+ )
+ messages.append(msg2)
+
+ # Message 3: User updates MemoryReAct card and adds to event
+ msg3 = Message(
+ id="msg3",
+ role="user",
+ parts=[TextPart(
+ "Yes, the MemoryReAct card also needs updating: MemoryReAct is not just about analyzing conversations and generating operations, "
+ "it's a complete orchestrator responsible for tool calling, LLM reasoning, and memory operation integration. "
+ "Also, the event card that mentions 'Decided to use MemoryReAct pattern' "
+ "needs to add the reason: because the MemoryReAct pattern can handle uncertainty well, "
+ "verifying the correctness of memory operations through the ReAct flow."
+ )],
+ )
+ messages.append(msg3)
+
+ return messages
+
+
+class TestMemoryExtractorFlow:
+ """Test the complete memory extraction flow."""
+
+
+ @pytest.mark.integration
+ @pytest.mark.asyncio
+ async def test_full_flow_with_real_llm(self):
+
+
+ # Only mock VikingFS, everything else is real!
+ viking_fs = MockVikingFS()
+ initialize_openviking_config()
+ config = get_openviking_config()
+ vlm = config.vlm.get_vlm_instance()
+ print(f'vlm={vlm}')
+ user = UserIdentifier.the_default_user()
+ ctx = RequestContext(user=user, role=Role.ROOT)
+
+ # Create test conversation
+ messages = create_test_conversation()
+
+ # Format conversation as string
+ conversation_str = "\n".join([
+ f"[{msg.role}]: {msg.content}"
+ for msg in messages
+ ])
+
+ print("-" * 60)
+ print("使用真实 LLM 测试完整流程(cards & events)...")
+ print("对话内容:")
+ print(conversation_str[:800] + "..." if len(conversation_str) > 800 else conversation_str)
+ print("-" * 60)
+
+ # Initialize orchestrator with real VLM!
+ orchestrator = MemoryReAct(
+ vlm=vlm,
+ viking_fs=viking_fs,
+ ctx=ctx,
+ )
+
+ # Take snapshot BEFORE running orchestrator to capture all changes
+ viking_fs.snapshot()
+
+ # Actually run the orchestrator with real LLM calls!
+ operations, tools_used = await orchestrator.run(
+ conversation=conversation_str,
+ )
+
+ # Verify results
+ assert operations is not None
+ assert tools_used is not None
+
+ print("-" * 60)
+ print(f"生成的操作:")
+ print(f" 写入:{len(operations.write_uris)}")
+ print(f" 编辑:{len(operations.edit_uris)}")
+ print(f" 删除:{len(operations.delete_uris)}")
+ print(f" 使用的工具:{len(tools_used)}")
+ print("-" * 60)
+
+ # Now test MemoryUpdater with the operations, mock get_viking_fs
+ with patch('openviking.session.memory.memory_updater.get_viking_fs', return_value=viking_fs):
+ updater = MemoryUpdater()
+ # Pass the registry from orchestrator
+ result = await updater.apply_operations(operations, ctx, registry=orchestrator.registry)
+
+ assert isinstance(result, MemoryUpdateResult)
+
+ print(f"已应用的操作:")
+ print(f" 已写入:{len(result.written_uris)}")
+ print(f" 已编辑:{len(result.edited_uris)}")
+ print(f" 已删除:{len(result.deleted_uris)}")
+ print(f" 错误:{len(result.errors)}")
+ print("-" * 60)
+
+ # Print diff since snapshot
+ diff = viking_fs.diff_since_snapshot()
+ print_diff(diff)
+
+ # Check that at least something happened (could be write/edit/delete depending on LLM)
+ total_changes = (len(operations.write_uris) +
+ len(operations.edit_uris) +
+ len(operations.delete_uris))
+ print(f"LLM 建议的总变更数:{total_changes}")
+
+ @pytest.mark.integration
+ @pytest.mark.asyncio
+ async def test_update_existing_memories_with_real_llm(self):
+ """Test updating existing cards and events with real LLM (only VikingFS is mocked)."""
+ # Check if VLM is available
+ initialize_openviking_config()
+ config = get_openviking_config()
+ vlm = config.vlm.get_vlm_instance()
+ print(f'vlm={vlm}')
+
+ # Only mock VikingFS, everything else is real!
+ viking_fs = MockVikingFS()
+ user = UserIdentifier.the_default_user()
+ ctx = RequestContext(user=user, role=Role.ROOT)
+
+ existing_memories = create_existing_memories_content()
+ for uri, content in existing_memories.items():
+ await viking_fs.write_file(uri, content)
+
+ # Create test conversation for updating
+ messages = create_update_conversation()
+
+ # Format conversation as string
+ conversation_str = "\n".join([
+ f"[{msg.role}]: {msg.content}"
+ for msg in messages
+ ])
+
+ print("=" * 60)
+ print("测试更新已有 cards 和 events...")
+ print("-" * 60)
+ print("已有记忆内容:")
+ for uri, content in existing_memories.items():
+ print(f"\n--- {uri} ---")
+ print(content[:300] + "..." if len(content) > 300 else content)
+ print("-" * 60)
+ print("新对话内容:")
+ print(conversation_str)
+ print("=" * 60)
+
+ # Initialize orchestrator with real VLM!
+ orchestrator = MemoryReAct(
+ vlm=vlm,
+ viking_fs=viking_fs,
+ ctx=ctx,
+ )
+
+ # Take snapshot BEFORE running orchestrator to capture all changes
+ viking_fs.snapshot()
+
+ # Actually run the orchestrator with real LLM calls!
+ operations, tools_used = await orchestrator.run(
+ conversation=conversation_str,
+ )
+
+ # Verify results
+ assert operations is not None
+ assert tools_used is not None
+ print(f'operations={operations.model_dump_json(indent=4)}')
+ print("=" * 60)
+ print(f"生成的操作:")
+ print(f" 写入:{len(operations.write_uris)}")
+ print(f" 编辑:{len(operations.edit_uris)}")
+ print(f" 删除:{len(operations.delete_uris)}")
+ print(f" 使用的工具:{len(tools_used)}")
+
+ if operations.edit_uris:
+ print("\n编辑操作详情:")
+ for op in operations.edit_uris:
+ # Handle both dict and model objects
+ if isinstance(op, dict):
+ print(f" - memory_type: {op.get('memory_type', 'unknown')}")
+ if 'fields' in op:
+ print(f" - fields: {op['fields']}")
+ if 'patches' in op:
+ print(f" 补丁:{list(op['patches'].keys())}")
+ if 'content' in op:
+ print(f" - content: {str(op['content'])[:100]}...")
+ else:
+ # Try to access as model attributes
+ memory_type = getattr(op, 'memory_type', 'unknown')
+ print(f" - memory_type: {memory_type}")
+ fields = getattr(op, 'fields', None)
+ if fields:
+ print(f" - fields: {fields}")
+ patches = getattr(op, 'patches', None)
+ if patches:
+ print(f" 补丁:{list(patches.keys())}")
+ content = getattr(op, 'content', None)
+ if content:
+ print(f" - content: {str(content)[:100]}...")
+
+ print("=" * 60)
+
+ # Now test MemoryUpdater with the operations, mock get_viking_fs
+ with patch('openviking.session.memory.memory_updater.get_viking_fs', return_value=viking_fs):
+ updater = MemoryUpdater()
+ # Pass the registry from orchestrator
+ result = await updater.apply_operations(operations, ctx, registry=orchestrator.registry)
+
+ assert isinstance(result, MemoryUpdateResult)
+
+ print(f"已应用的操作:")
+ print(f" 已写入:{len(result.written_uris)}")
+ print(f" 已编辑:{len(result.edited_uris)}")
+ print(f" 已删除:{len(result.deleted_uris)}")
+ print(f" 错误:{len(result.errors)}")
+ print("=" * 60)
+
+ # Print diff since snapshot
+ diff = viking_fs.diff_since_snapshot()
+ print_diff(diff)
+
+ # Check updated content
+ print("\n更新后的记忆内容:")
+ for uri in existing_memories.keys():
+ new_content = await viking_fs.read_file(uri)
+ if new_content != existing_memories.get(uri, ""):
+ print(f"\n--- {uri} (已更新) ---")
+ print(new_content[:500] + "..." if len(new_content) > 500 else new_content)
+ else:
+ print(f"\n--- {uri} (未变化) ---")
+ # Also check if new cards/events were created
+ print("\n--- cards 目录内容 ---")
+ try:
+ card_files = await viking_fs.ls("viking://agent/default/memories/cards")
+ for f in card_files:
+ print(f" - {f.get('name', 'unknown')}")
+ except Exception as e:
+ print(f" 无法列出目录: {e}")
+ print("\n--- events 目录内容 ---")
+ try:
+ event_files = await viking_fs.ls("viking://user/default/memories/events")
+ for f in event_files:
+ print(f" - {f.get('name', 'unknown')}")
+ except Exception as e:
+ print(f" 无法列出目录: {e}")
+ print("=" * 60)
+
+ # Check that at least something happened (could be write/edit/delete depending on LLM)
+ total_changes = (len(operations.write_uris) +
+ len(operations.edit_uris) +
+ len(operations.delete_uris))
+ print(f"LLM 建议的总变更数:{total_changes}")
+
+ def test_message_formatting(self):
+ """Test that messages can be formatted correctly."""
+ messages = create_test_conversation()
+
+ assert len(messages) == 5
+ assert messages[0].role == "user"
+ assert "OpenViking" in messages[0].content
+ assert "memory extraction" in messages[0].content
+
+
diff --git a/tests/session/memory/test_memory_patch.py b/tests/session/memory/test_memory_patch.py
new file mode 100644
index 000000000..904ee9028
--- /dev/null
+++ b/tests/session/memory/test_memory_patch.py
@@ -0,0 +1,156 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: Apache-2.0
+"""
+Tests for MemoryPatchHandler.
+"""
+
+import pytest
+
+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_fallback_append(self):
+ """Test that search not found falls back to append."""
+ original = "Original content"
+ patch = """<<<<<<< SEARCH
+Non-existent content
+=======
+New content
+>>>>>>> REPLACE
+"""
+
+ result = self.handler.apply_content_patch(original, patch)
+ assert result.startswith(original)
+ assert "New content" in result
+
+ 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
diff --git a/tests/session/memory/test_memory_react.py b/tests/session/memory/test_memory_react.py
new file mode 100644
index 000000000..d05fdacd9
--- /dev/null
+++ b/tests/session/memory/test_memory_react.py
@@ -0,0 +1,201 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: Apache-2.0
+"""
+Tests for memory ReAct orchestrator.
+"""
+
+import json
+from unittest.mock import AsyncMock, MagicMock, patch
+
+import pytest
+
+from openviking.session.memory.memory_react import (
+ MemoryReAct,
+)
+from openviking.session.memory.dataclass import (
+ MemoryTypeSchema,
+ MemoryField,
+)
+from openviking.session.memory.merge_op.base import FieldType, MergeOp
+
+
+class TestPreFetchFileFiltering:
+ """Tests for the file filtering logic in pre-fetch."""
+
+ def test_only_abstract_and_overview_are_read_when_both_exist(self):
+ """Test that from a directory listing, only .abstract.md and .overview.md are selected when both exist."""
+ # Mock directory entries - both .abstract.md and .overview.md exist
+ test_entries = [
+ {"name": ".abstract.md", "isDir": False},
+ {"name": ".overview.md", "isDir": False},
+ {"name": "regular-file.md", "isDir": False},
+ {"name": "another-file.md", "isDir": False},
+ {"name": "subdir", "isDir": True},
+ {"name": ".gitkeep", "isDir": False},
+ {"name": "data.json", "isDir": False},
+ ]
+
+ dir_uri = "viking://user/default/memories/preferences"
+ single_file_schemas = set()
+
+ # Apply the filtering logic manually (replicate what _pre_fetch_context does)
+ md_files = list(single_file_schemas)
+
+ for entry in test_entries:
+ name = entry.get("name", "")
+ if not entry.get("isDir", False):
+ # Only read .abstract.md and .overview.md from multi-file schema directories
+ # (only if they actually exist in the directory listing)
+ if name == ".abstract.md" or name == ".overview.md":
+ file_uri = f"{dir_uri}/{name}"
+ if file_uri not in md_files:
+ md_files.append(file_uri)
+
+ # Verify only the two special files are included
+ assert len(md_files) == 2
+ assert f"{dir_uri}/.abstract.md" in md_files
+ assert f"{dir_uri}/.overview.md" in md_files
+
+ # Verify regular .md files are NOT included
+ assert f"{dir_uri}/regular-file.md" not in md_files
+ assert f"{dir_uri}/another-file.md" not in md_files
+
+ def test_only_read_existing_files(self):
+ """Test that only existing files are read - when only one exists or none exist."""
+ dir_uri = "viking://user/default/memories/preferences"
+ single_file_schemas = set()
+
+ # Case 1: Only .abstract.md exists
+ test_entries1 = [
+ {"name": ".abstract.md", "isDir": False},
+ {"name": "regular-file.md", "isDir": False},
+ ]
+ md_files1 = list(single_file_schemas)
+ for entry in test_entries1:
+ name = entry.get("name", "")
+ if not entry.get("isDir", False):
+ if name == ".abstract.md" or name == ".overview.md":
+ file_uri = f"{dir_uri}/{name}"
+ if file_uri not in md_files1:
+ md_files1.append(file_uri)
+ assert len(md_files1) == 1
+ assert f"{dir_uri}/.abstract.md" in md_files1
+ assert f"{dir_uri}/.overview.md" not in md_files1
+
+ # Case 2: Only .overview.md exists
+ test_entries2 = [
+ {"name": ".overview.md", "isDir": False},
+ {"name": "regular-file.md", "isDir": False},
+ ]
+ md_files2 = list(single_file_schemas)
+ for entry in test_entries2:
+ name = entry.get("name", "")
+ if not entry.get("isDir", False):
+ if name == ".abstract.md" or name == ".overview.md":
+ file_uri = f"{dir_uri}/{name}"
+ if file_uri not in md_files2:
+ md_files2.append(file_uri)
+ assert len(md_files2) == 1
+ assert f"{dir_uri}/.overview.md" in md_files2
+ assert f"{dir_uri}/.abstract.md" not in md_files2
+
+ # Case 3: Neither exists
+ test_entries3 = [
+ {"name": "regular-file.md", "isDir": False},
+ ]
+ md_files3 = list(single_file_schemas)
+ for entry in test_entries3:
+ name = entry.get("name", "")
+ if not entry.get("isDir", False):
+ if name == ".abstract.md" or name == ".overview.md":
+ file_uri = f"{dir_uri}/{name}"
+ if file_uri not in md_files3:
+ md_files3.append(file_uri)
+ assert len(md_files3) == 0
+
+ def test_schema_type_detection_logic(self):
+ """Test the logic for determining if a schema is multi-file or single-file."""
+ # Test cases: (filename_template, expected_has_variables)
+ test_cases = [
+ ("{topic}.md", True),
+ ("static.md", False),
+ ("{tool_name}.md", True),
+ ("profile.md", False),
+ ("", False), # empty template
+ ("{entity_name}-details.md", True),
+ ("fixed-filename.md", False),
+ ("{a}/{b}.md", True),
+ ]
+
+ for filename_template, expected_has_variables in test_cases:
+ # Replicate the logic from _pre_fetch_context
+ has_variables = False
+ if filename_template:
+ has_variables = "{" in filename_template and "}" in filename_template
+
+ assert has_variables == expected_has_variables, \
+ f"Template '{filename_template}': expected has_variables={expected_has_variables}"
+
+
+class TestAllowedDirectoriesList:
+ """Tests for _get_allowed_directories_list method."""
+
+ @pytest.fixture
+ def mock_vlm(self):
+ """Create a mock VLM."""
+ vlm = MagicMock()
+ vlm.model = "test-model"
+ vlm.max_retries = 2
+ vlm.get_completion_async = AsyncMock()
+ return vlm
+
+ @pytest.fixture
+ def mock_viking_fs(self):
+ """Create a mock VikingFS."""
+ return MagicMock()
+
+ def test_get_allowed_directories_list(self, mock_vlm, mock_viking_fs):
+ """Test that allowed directories list is properly formatted."""
+ # Patch the registry loading so we can inject our own schemas
+ with patch('openviking.session.memory.memory_react.MemoryTypeRegistry') as mock_registry_cls:
+ mock_registry = MagicMock()
+
+ # Create test schemas
+ schema1 = MemoryTypeSchema(
+ memory_type="preferences",
+ description="Preferences",
+ directory="viking://user/{user_space}/memories/preferences",
+ filename_template="{topic}.md",
+ fields=[],
+ )
+ schema2 = MemoryTypeSchema(
+ memory_type="tools",
+ description="Tools",
+ directory="viking://agent/{agent_space}/memories/tools",
+ filename_template="{tool_name}.md",
+ fields=[],
+ )
+
+ mock_registry.list_all.return_value = [schema1, schema2]
+ mock_registry_cls.return_value = mock_registry
+
+ # Also patch schema_model_generator and schema_prompt_generator
+ with patch('openviking.session.memory.memory_react.SchemaModelGenerator') as mock_smg, \
+ patch('openviking.session.memory.memory_react.SchemaPromptGenerator') as mock_spg:
+
+ mock_smg_instance = MagicMock()
+ mock_smg_instance.generate_all_models = MagicMock()
+ mock_smg_instance.get_llm_json_schema = MagicMock(return_value={})
+ mock_smg.return_value = mock_smg_instance
+
+ mock_spg.return_value = MagicMock()
+
+ # Create MemoryReAct
+ react = MemoryReAct(mock_vlm, mock_viking_fs)
+
+ # Call the method
+ result = react._get_allowed_directories_list()
+
+ # Verify the result contains the expected directories with variables replaced
+ assert "viking://user/default/memories/preferences" in result
+ assert "viking://agent/default/memories/tools" in result
diff --git a/tests/session/memory/test_memory_react_system_prompt.py b/tests/session/memory/test_memory_react_system_prompt.py
new file mode 100644
index 000000000..4f2f1ce1e
--- /dev/null
+++ b/tests/session/memory/test_memory_react_system_prompt.py
@@ -0,0 +1,103 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: Apache-2.0
+"""
+Test that MemoryReAct system prompt correctly instructs LLM to read before edit.
+"""
+
+import json
+import pytest
+from unittest.mock import MagicMock, AsyncMock, patch
+
+from openviking.session.memory import MemoryReAct
+
+
+class TestMemoryReActSystemPrompt:
+ """Test the system prompt contains correct instructions about reading before edit."""
+
+ @pytest.fixture
+ def mock_viking_fs(self):
+ """Mock VikingFS."""
+ mock = MagicMock()
+ mock.read_file = AsyncMock(return_value="")
+ mock.write_file = AsyncMock()
+ mock.ls = AsyncMock(return_value=[])
+ mock.mkdir = AsyncMock()
+ mock.rm = AsyncMock()
+ mock.stat = AsyncMock(return_value={"type": "dir"})
+ mock.find = AsyncMock(return_value={"memories": [], "resources": [], "skills": []})
+ mock.tree = AsyncMock(return_value={"uri": "", "tree": []})
+ return mock
+
+ @patch('openviking.session.memory.memory_react.get_viking_fs')
+ def test_system_prompt_contains_read_before_edit_instructions(self, mock_get_viking_fs, mock_viking_fs):
+ """Test that system prompt explicitly tells LLM to read files before editing."""
+ mock_get_viking_fs.return_value = mock_viking_fs
+
+ # Create MemoryReAct with mock dependencies
+ mock_llm = MagicMock()
+ mock_llm.get_default_model.return_value = "test-model"
+
+ react = MemoryReAct(llm_provider=mock_llm, viking_fs=mock_viking_fs)
+
+ # Get system prompt
+ system_prompt = react._get_system_prompt("zh")
+
+ # Check for critical instructions
+ assert "Critical: Read Before Edit" in system_prompt
+ assert "Before you edit or update ANY existing memory file, you MUST first use the read tool" in system_prompt
+ assert "The ls tool only shows you what files exist - it does NOT show you the file content" in system_prompt
+ assert "You MUST use the read tool to get the actual content of any file you want to edit" in system_prompt
+ assert "Without reading the actual file first, your edit operations will fail" in system_prompt
+
+ @patch('openviking.session.memory.memory_react.get_viking_fs')
+ def test_system_prompt_contains_note_in_important_notes(self, mock_get_viking_fs, mock_viking_fs):
+ """Test that important notes section also reminds to read before edit."""
+ mock_get_viking_fs.return_value = mock_viking_fs
+
+ mock_llm = MagicMock()
+ mock_llm.get_default_model.return_value = "test-model"
+
+ react = MemoryReAct(llm_provider=mock_llm, viking_fs=mock_viking_fs)
+ system_prompt = react._get_system_prompt("zh")
+
+ assert "Always read a file before editing it - ls and summaries are not enough" in system_prompt
+
+ @patch('openviking.session.memory.memory_react.get_viking_fs')
+ def test_ls_result_has_note_about_reading_files(self, mock_get_viking_fs, mock_viking_fs):
+ """Test that pre-fetched ls results include a note about needing to read files."""
+ mock_get_viking_fs.return_value = mock_viking_fs
+
+ mock_llm = MagicMock()
+ mock_llm.get_default_model.return_value = "test-model"
+
+ react = MemoryReAct(llm_provider=mock_llm, viking_fs=mock_viking_fs)
+
+ # Test with a pre-fetched context that has directories
+ pre_fetched = {
+ "directories": {
+ "viking://test/memories": [
+ {"name": "test.md", "isDir": False}
+ ]
+ },
+ "summaries": {},
+ "search_results": []
+ }
+
+ messages = react._format_pre_fetched_as_tool_calls(pre_fetched)
+
+ # Check that we have messages (ls call + result, find call + result)
+ assert len(messages) >= 2
+
+ # Find the ls tool result message
+ ls_result_msg = None
+ for msg in messages:
+ if msg.get("role") == "tool" and "prefetch_ls" in msg.get("tool_call_id", ""):
+ ls_result_msg = msg
+ break
+
+ assert ls_result_msg is not None, "Could not find ls tool result message"
+
+ # The tool result message should contain our note
+ content = json.loads(ls_result_msg["content"])
+ assert "_note" in content
+ assert "This ls result only shows file names. Use read tool to get actual file content before editing any file." in content["_note"]
diff --git a/tests/session/memory/test_memory_tools.py b/tests/session/memory/test_memory_tools.py
new file mode 100644
index 000000000..beda7d8bd
--- /dev/null
+++ b/tests/session/memory/test_memory_tools.py
@@ -0,0 +1,76 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: Apache-2.0
+"""
+Tests for memory tools.
+"""
+
+
+from openviking.session.memory.tools import (
+ MemorySearchTool,
+ MemoryLsTool,
+ MemoryReadTool,
+ get_tool,
+ get_tool_schemas,
+ list_tools,
+)
+
+
+class TestMemoryTools:
+ """Tests for memory tools."""
+
+ def test_read_tool_properties(self):
+ """Test MemoryReadTool properties."""
+ tool = MemoryReadTool()
+
+ assert tool.name == "read"
+ assert "Read single file" in tool.description
+ assert "uri" in tool.parameters["properties"]
+ assert "required" in tool.parameters
+
+ def test_search_tool_properties(self):
+ """Test MemorySearchTool properties."""
+ tool = MemorySearchTool()
+
+ assert tool.name == "search"
+ assert "Semantic search" in tool.description
+ assert "query" in tool.parameters["properties"]
+ assert "session_info" in tool.parameters["properties"]
+
+ def test_ls_tool_properties(self):
+ """Test MemoryLsTool properties."""
+ tool = MemoryLsTool()
+
+ assert tool.name == "ls"
+ assert "List directory" in tool.description
+ assert "uri" in tool.parameters["properties"]
+
+ def test_to_schema(self):
+ """Test tool to_schema method."""
+ tool = MemoryReadTool()
+ schema = tool.to_schema()
+
+ assert schema["type"] == "function"
+ assert schema["function"]["name"] == "read"
+ assert "description" in schema["function"]
+ assert "parameters" in schema["function"]
+
+ 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
+
+ # Check get_tool
+ read_tool = get_tool("read")
+ assert read_tool is not None
+ assert isinstance(read_tool, MemoryReadTool)
+
+ # Check get_tool_schemas
+ schemas = get_tool_schemas()
+ assert len(schemas) == 3
+ schema_names = [s["function"]["name"] for s in schemas]
+ assert "read" in schema_names
+ assert "search" in schema_names
+ assert "ls" in schema_names
diff --git a/tests/session/memory/test_memory_updater.py b/tests/session/memory/test_memory_updater.py
new file mode 100644
index 000000000..0bd27faa2
--- /dev/null
+++ b/tests/session/memory/test_memory_updater.py
@@ -0,0 +1,309 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: Apache-2.0
+"""
+Tests for MemoryUpdater.
+"""
+from datetime import datetime
+from unittest.mock import AsyncMock, MagicMock, patch
+
+import pytest
+
+from openviking.session.memory.memory_updater import (
+ MemoryUpdateResult,
+ MemoryUpdater,
+)
+from openviking.session.memory.memory_type_registry import MemoryTypeRegistry
+from openviking.session.memory.dataclass import (
+ MemoryTypeSchema,
+ MemoryField,
+)
+from openviking.session.memory.merge_op import (
+ SearchReplaceBlock,
+ StrPatch,
+)
+from openviking.session.memory.merge_op.base import FieldType
+from openviking.session.memory.utils import deserialize_full, serialize_with_metadata
+
+
+class TestMemoryUpdateResult:
+ """Tests for MemoryUpdateResult."""
+
+ def test_create_empty(self):
+ """Test creating an empty result."""
+ result = MemoryUpdateResult()
+
+ assert len(result.written_uris) == 0
+ assert len(result.edited_uris) == 0
+ assert len(result.deleted_uris) == 0
+ assert len(result.errors) == 0
+ assert result.has_changes() is False
+
+ def test_add_written(self):
+ """Test adding written URI."""
+ result = MemoryUpdateResult()
+ result.add_written("viking://user/test/memories/profile.md")
+
+ assert len(result.written_uris) == 1
+ assert result.has_changes() is True
+
+ def test_add_edited(self):
+ """Test adding edited URI."""
+ result = MemoryUpdateResult()
+ result.add_edited("viking://user/test/memories/profile.md")
+
+ assert len(result.edited_uris) == 1
+ assert result.has_changes() is True
+
+ def test_add_deleted(self):
+ """Test adding deleted URI."""
+ result = MemoryUpdateResult()
+ result.add_deleted("viking://user/test/memories/to_delete.md")
+
+ assert len(result.deleted_uris) == 1
+ assert result.has_changes() is True
+
+ def test_summary(self):
+ """Test summary generation."""
+ result = MemoryUpdateResult()
+ result.add_written("uri1")
+ result.add_edited("uri2")
+ result.add_deleted("uri3")
+
+ summary = result.summary()
+ assert "Written: 1" in summary
+ assert "Edited: 1" in summary
+ assert "Deleted: 1" in summary
+ assert "Errors: 0" in summary
+
+
+class TestMemoryUpdater:
+ """Tests for MemoryUpdater."""
+
+ def test_create(self):
+ """Test creating a MemoryUpdater."""
+ updater = MemoryUpdater()
+
+ assert updater is not None
+ assert updater._viking_fs is None
+ assert updater._registry is None
+
+ def test_create_with_registry(self):
+ """Test creating a MemoryUpdater with registry."""
+ registry = MemoryTypeRegistry()
+ updater = MemoryUpdater(registry)
+
+ assert updater._registry == registry
+
+ def test_set_registry(self):
+ """Test setting registry after creation."""
+ updater = MemoryUpdater()
+ registry = MemoryTypeRegistry()
+
+ updater.set_registry(registry)
+
+ assert updater._registry == registry
+
+
+# The TestApplyWriteWithContentInFields tests are outdated because WriteOp no longer exists
+# The _apply_write method now accepts any flat model (dict or Pydantic model) that
+# can be converted with flat_model_to_dict(). Since the main issue we're fixing is
+# the StrPatch handling in _apply_edit, we'll keep the focus on that.
+
+
+class TestApplyEditWithSearchReplacePatch:
+ """Tests for _apply_edit with SEARCH/REPLACE patches."""
+
+ @pytest.mark.asyncio
+ async def test_apply_edit_with_str_patch_instance(self):
+ """Test _apply_edit with StrPatch instance."""
+ updater = MemoryUpdater()
+
+ # Original content
+ original_content = """Line 1
+Line 2
+Line 3
+Line 4"""
+ original_metadata = {"name": "test"}
+ original_full_content = serialize_with_metadata(original_content, original_metadata)
+
+ # Mock VikingFS
+ mock_viking_fs = MagicMock()
+ mock_viking_fs.read_file = AsyncMock(return_value=original_full_content)
+ written_content = None
+
+ async def mock_write_file(uri, content, **kwargs):
+ nonlocal written_content
+ written_content = content
+
+ mock_viking_fs.write_file = mock_write_file
+ updater._get_viking_fs = MagicMock(return_value=mock_viking_fs)
+
+ # Create StrPatch
+ patch = StrPatch(blocks=[
+ SearchReplaceBlock(
+ search="Line 2\nLine 3",
+ replace="Line 2 modified\nLine 3 modified",
+ start_line=2
+ )
+ ])
+
+ # Mock request context
+ mock_ctx = MagicMock()
+
+ # Apply edit
+ await updater._apply_edit(
+ {"content": patch},
+ "viking://test/test.md",
+ mock_ctx
+ )
+
+ # Verify
+ assert written_content is not None
+ body_content, metadata = deserialize_full(written_content)
+ assert "Line 1" in body_content
+ assert "Line 2 modified" in body_content
+ assert "Line 3 modified" in body_content
+ assert "Line 4" in body_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()
+
+ # Original content
+ original_content = """Hello world
+This is a test
+Goodbye"""
+ original_metadata = {"name": "test"}
+ original_full_content = serialize_with_metadata(original_content, original_metadata)
+
+ # Mock VikingFS
+ mock_viking_fs = MagicMock()
+ mock_viking_fs.read_file = AsyncMock(return_value=original_full_content)
+ written_content = None
+
+ async def mock_write_file(uri, content, **kwargs):
+ nonlocal written_content
+ written_content = content
+
+ mock_viking_fs.write_file = mock_write_file
+ updater._get_viking_fs = MagicMock(return_value=mock_viking_fs)
+
+ # StrPatch as dict (this is what JSON parsing gives us)
+ patch_dict = {
+ "blocks": [
+ {
+ "search": "This is a test",
+ "replace": "This has been modified",
+ "start_line": 2
+ }
+ ]
+ }
+
+ # Mock request context
+ mock_ctx = MagicMock()
+
+ # Apply edit
+ await updater._apply_edit(
+ {"content": patch_dict},
+ "viking://test/test.md",
+ mock_ctx
+ )
+
+ # Verify
+ assert written_content is not None
+ body_content, metadata = deserialize_full(written_content)
+ assert "Hello world" in body_content
+ assert "This has been modified" in body_content
+ assert "Goodbye" in body_content
+
+ @pytest.mark.asyncio
+ async def test_apply_edit_with_string_patch(self):
+ """Test _apply_edit with string patch containing <<<<<<< SEARCH."""
+ updater = MemoryUpdater()
+
+ # Original content
+ original_content = """First line
+Second line
+Third line"""
+ original_metadata = {"name": "test"}
+ original_full_content = serialize_with_metadata(original_content, original_metadata)
+
+ # Mock VikingFS
+ mock_viking_fs = MagicMock()
+ mock_viking_fs.read_file = AsyncMock(return_value=original_full_content)
+ written_content = None
+
+ async def mock_write_file(uri, content, **kwargs):
+ nonlocal written_content
+ written_content = content
+
+ mock_viking_fs.write_file = mock_write_file
+ updater._get_viking_fs = MagicMock(return_value=mock_viking_fs)
+
+ # String patch with SEARCH/REPLACE markers
+ patch_str = """<<<<<<< SEARCH
+:start_line:2
+-------
+Second line
+=======
+Second line (updated)
+>>>>>>> REPLACE
+"""
+
+ # Mock request context
+ mock_ctx = MagicMock()
+
+ # Apply edit
+ await updater._apply_edit(
+ {"content": patch_str},
+ "viking://test/test.md",
+ mock_ctx
+ )
+
+ # Verify
+ assert written_content is not None
+ body_content, metadata = deserialize_full(written_content)
+ assert "First line" in body_content
+ assert "Second line (updated)" in body_content
+ assert "Third line" in body_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_full_content = serialize_with_metadata(original_content, original_metadata)
+
+ # Mock VikingFS
+ mock_viking_fs = MagicMock()
+ mock_viking_fs.read_file = AsyncMock(return_value=original_full_content)
+ written_content = None
+
+ async def mock_write_file(uri, content, **kwargs):
+ nonlocal written_content
+ written_content = content
+
+ 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"
+
+ # Mock request context
+ mock_ctx = MagicMock()
+
+ # Apply edit
+ await updater._apply_edit(
+ {"content": new_content},
+ "viking://test/test.md",
+ mock_ctx
+ )
+
+ # Verify
+ assert written_content is not None
+ body_content, metadata = deserialize_full(written_content)
+ assert body_content == new_content
diff --git a/tests/session/memory/test_memory_utils.py b/tests/session/memory/test_memory_utils.py
new file mode 100644
index 000000000..f247b74fc
--- /dev/null
+++ b/tests/session/memory/test_memory_utils.py
@@ -0,0 +1,534 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: Apache-2.0
+"""
+Tests for memory utilities - URI generation, etc.
+"""
+
+import pytest
+
+from openviking.session.memory.dataclass import (
+ MemoryField,
+ MemoryTypeSchema,
+ MemoryOperations,
+)
+from openviking.session.memory.merge_op.base import FieldType, MergeOp
+from openviking.session.memory.utils import (
+ collect_allowed_directories,
+ collect_allowed_path_patterns,
+ generate_uri,
+ is_uri_allowed,
+ is_uri_allowed_for_schema,
+ parse_memory_file_with_fields,
+ resolve_all_operations,
+ validate_uri_template,
+)
+from openviking.session.memory.memory_type_registry import MemoryTypeRegistry
+
+
+class TestUriGeneration:
+ """Tests for URI generation."""
+
+ def test_generate_uri_preferences(self):
+ """Test generating URI for preferences memory type."""
+ memory_type = MemoryTypeSchema(
+ memory_type="preferences",
+ description="User preference memory",
+ directory="viking://user/{user_space}/memories/preferences",
+ filename_template="{topic}.md",
+ fields=[
+ MemoryField(
+ name="topic",
+ field_type=FieldType.STRING,
+ description="Preference topic",
+ merge_op=MergeOp.IMMUTABLE,
+ ),
+ MemoryField(
+ name="content",
+ field_type=FieldType.STRING,
+ description="Preference content",
+ merge_op=MergeOp.PATCH,
+ ),
+ ],
+ )
+
+ uri = generate_uri(
+ memory_type,
+ {"topic": "Python code style", "content": "..."},
+ user_space="default",
+ )
+
+ assert uri == "viking://user/default/memories/preferences/Python code style.md"
+
+ def test_generate_uri_tools(self):
+ """Test generating URI for tools memory type."""
+ memory_type = MemoryTypeSchema(
+ memory_type="tools",
+ description="Tool usage memory",
+ directory="viking://agent/{agent_space}/memories/tools",
+ filename_template="{tool_name}.md",
+ fields=[
+ MemoryField(
+ name="tool_name",
+ field_type=FieldType.STRING,
+ description="Tool name",
+ merge_op=MergeOp.IMMUTABLE,
+ ),
+ ],
+ )
+
+ uri = generate_uri(
+ memory_type,
+ {"tool_name": "web_search"},
+ agent_space="default",
+ )
+
+ assert uri == "viking://agent/default/memories/tools/web_search.md"
+
+ def test_generate_uri_only_directory(self):
+ """Test generating URI with only directory."""
+ memory_type = MemoryTypeSchema(
+ memory_type="test",
+ description="Test memory",
+ directory="viking://user/{user_space}/memories/test",
+ filename_template="",
+ fields=[],
+ )
+
+ uri = generate_uri(memory_type, {}, user_space="alice")
+
+ assert uri == "viking://user/alice/memories/test"
+
+ def test_generate_uri_only_filename(self):
+ """Test generating URI with only filename template."""
+ memory_type = MemoryTypeSchema(
+ memory_type="test",
+ description="Test memory",
+ directory="",
+ filename_template="{name}.md",
+ fields=[
+ MemoryField(
+ name="name",
+ field_type=FieldType.STRING,
+ description="Name",
+ merge_op=MergeOp.IMMUTABLE,
+ ),
+ ],
+ )
+
+ uri = generate_uri(memory_type, {"name": "test-file"})
+
+ assert uri == "test-file.md"
+
+ def test_generate_uri_missing_variable(self):
+ """Test error when required variable is missing."""
+ memory_type = MemoryTypeSchema(
+ memory_type="preferences",
+ description="User preference memory",
+ directory="viking://user/{user_space}/memories/preferences",
+ filename_template="{topic}.md",
+ fields=[],
+ )
+
+ with pytest.raises(ValueError, match="Missing template variable"):
+ generate_uri(memory_type, {})
+
+ def test_generate_uri_none_value(self):
+ """Test error when variable has None value."""
+ memory_type = MemoryTypeSchema(
+ memory_type="preferences",
+ description="User preference memory",
+ directory="viking://user/{user_space}/memories/preferences",
+ filename_template="{topic}.md",
+ fields=[],
+ )
+
+ with pytest.raises(ValueError, match="has None value"):
+ generate_uri(memory_type, {"topic": None})
+
+ def test_validate_uri_template_valid(self):
+ """Test validating a valid URI template."""
+ memory_type = MemoryTypeSchema(
+ memory_type="preferences",
+ description="User preference memory",
+ directory="viking://user/{user_space}/memories/preferences",
+ filename_template="{topic}.md",
+ fields=[
+ MemoryField(
+ name="topic",
+ field_type=FieldType.STRING,
+ description="Preference topic",
+ merge_op=MergeOp.IMMUTABLE,
+ ),
+ ],
+ )
+
+ assert validate_uri_template(memory_type) is True
+
+ def test_validate_uri_template_missing_field(self):
+ """Test validating a template with missing field."""
+ memory_type = MemoryTypeSchema(
+ memory_type="preferences",
+ description="User preference memory",
+ directory="viking://user/{user_space}/memories/preferences",
+ filename_template="{missing_field}.md",
+ fields=[
+ MemoryField(
+ name="topic",
+ field_type=FieldType.STRING,
+ description="Preference topic",
+ merge_op=MergeOp.IMMUTABLE,
+ ),
+ ],
+ )
+
+ assert validate_uri_template(memory_type) is False
+
+ def test_validate_uri_template_no_directory_or_filename(self):
+ """Test validating with neither directory nor filename."""
+ memory_type = MemoryTypeSchema(
+ memory_type="test",
+ description="Test memory",
+ directory="",
+ filename_template="",
+ fields=[],
+ )
+
+ assert validate_uri_template(memory_type) is False
+
+
+class TestUriValidation:
+ """Tests for URI validation."""
+
+ def test_collect_allowed_directories(self):
+ """Test collecting allowed directories from schemas."""
+ schemas = [
+ MemoryTypeSchema(
+ memory_type="preferences",
+ description="Preferences",
+ directory="viking://user/{user_space}/memories/preferences",
+ filename_template="{topic}.md",
+ fields=[],
+ ),
+ MemoryTypeSchema(
+ memory_type="tools",
+ description="Tools",
+ directory="viking://agent/{agent_space}/memories/tools",
+ filename_template="{tool_name}.md",
+ fields=[],
+ ),
+ MemoryTypeSchema(
+ memory_type="disabled",
+ description="Disabled",
+ directory="viking://user/default/memories/disabled",
+ filename_template="",
+ fields=[],
+ enabled=False,
+ ),
+ ]
+
+ dirs = collect_allowed_directories([s for s in schemas if s.enabled], user_space="default", agent_space="default")
+
+ assert dirs == {
+ "viking://user/default/memories/preferences",
+ "viking://agent/default/memories/tools",
+ }
+
+ def test_collect_allowed_path_patterns(self):
+ """Test collecting allowed path patterns from schemas."""
+ schemas = [
+ MemoryTypeSchema(
+ memory_type="preferences",
+ description="Preferences",
+ directory="viking://user/{user_space}/memories/preferences",
+ filename_template="{topic}.md",
+ fields=[],
+ ),
+ ]
+
+ patterns = collect_allowed_path_patterns(schemas, user_space="default", agent_space="default")
+
+ assert patterns == {
+ "viking://user/default/memories/preferences/{topic}.md",
+ }
+
+ def test_is_uri_allowed_by_directory(self):
+ """Test URI allowed by matching directory prefix."""
+ allowed_dirs = {
+ "viking://user/default/memories/preferences",
+ "viking://agent/default/memories/tools",
+ }
+ allowed_patterns = set()
+
+ assert is_uri_allowed(
+ "viking://user/default/memories/preferences/test.md",
+ allowed_dirs,
+ allowed_patterns,
+ ) is True
+
+ assert is_uri_allowed(
+ "viking://user/default/memories/preferences",
+ allowed_dirs,
+ allowed_patterns,
+ ) is True
+
+ assert is_uri_allowed(
+ "viking://user/default/memories/preferences/subdir/test.md",
+ allowed_dirs,
+ allowed_patterns,
+ ) is True
+
+ def test_is_uri_allowed_by_pattern(self):
+ """Test URI allowed by matching pattern."""
+ allowed_dirs = set()
+ allowed_patterns = {
+ "viking://user/default/memories/preferences/{topic}.md",
+ }
+
+ assert is_uri_allowed(
+ "viking://user/default/memories/preferences/Python code style.md",
+ allowed_dirs,
+ allowed_patterns,
+ ) is True
+
+ def test_is_uri_disallowed(self):
+ """Test URI not allowed."""
+ allowed_dirs = {
+ "viking://user/default/memories/preferences",
+ }
+ allowed_patterns = set()
+
+ assert is_uri_allowed(
+ "viking://user/default/memories/other/test.md",
+ allowed_dirs,
+ allowed_patterns,
+ ) is False
+
+ assert is_uri_allowed(
+ "viking://user/other/memories/preferences/test.md",
+ allowed_dirs,
+ allowed_patterns,
+ ) is False
+
+ def test_is_uri_allowed_for_schema(self):
+ """Test checking URI against schemas."""
+ schemas = [
+ MemoryTypeSchema(
+ memory_type="preferences",
+ description="Preferences",
+ directory="viking://user/{user_space}/memories/preferences",
+ filename_template="{topic}.md",
+ fields=[],
+ ),
+ ]
+
+ assert is_uri_allowed_for_schema(
+ "viking://user/default/memories/preferences/test.md",
+ schemas,
+ ) is True
+
+ assert is_uri_allowed_for_schema(
+ "viking://user/default/memories/other/test.md",
+ schemas,
+ ) is False
+
+
+class TestUriResolution:
+ """Tests for URI resolution methods."""
+
+ @pytest.fixture
+ def test_registry(self):
+ """Create a test registry with sample schemas."""
+ registry = MemoryTypeRegistry()
+
+ # Add preferences schema
+ registry.register(MemoryTypeSchema(
+ memory_type="preferences",
+ description="User preferences",
+ directory="viking://user/{user_space}/memories/preferences",
+ filename_template="{topic}.md",
+ fields=[
+ MemoryField(name="topic", field_type=FieldType.STRING, description="Topic"),
+ ],
+ ))
+
+ # Add tools schema
+ registry.register(MemoryTypeSchema(
+ memory_type="tools",
+ description="Tool memories",
+ directory="viking://agent/{agent_space}/memories/tools",
+ filename_template="{tool_name}.md",
+ fields=[
+ MemoryField(name="tool_name", field_type=FieldType.STRING, description="Tool name"),
+ ],
+ ))
+
+ return registry
+
+ def test_resolve_write_uri(self, test_registry):
+ """Test resolving URI for WriteOp."""
+ write_op = WriteOp(
+ memory_type="preferences",
+ fields={"topic": "Python code style"},
+ content="Test content",
+ )
+
+ uri = resolve_write_uri(write_op, test_registry)
+
+ assert uri == "viking://user/default/memories/preferences/Python code style.md"
+
+ def test_resolve_write_uri_unknown_type(self, test_registry):
+ """Test resolving WriteOp with unknown memory type."""
+ write_op = WriteOp(
+ memory_type="unknown_type",
+ fields={},
+ )
+
+ with pytest.raises(ValueError, match="Unknown memory type"):
+ resolve_write_uri(write_op, test_registry)
+
+ def test_resolve_edit_target(self, test_registry):
+ """Test resolving target URI for EditOp."""
+ uri = resolve_edit_target(
+ "tools",
+ {"tool_name": "web_search"},
+ test_registry,
+ )
+
+ assert uri == "viking://agent/default/memories/tools/web_search.md"
+
+ def test_resolve_delete_target(self, test_registry):
+ """Test resolving target URI for DeleteOp."""
+ uri = resolve_delete_target(
+ "preferences",
+ {"topic": "Test topic"},
+ test_registry,
+ )
+
+ assert uri == "viking://user/default/memories/preferences/Test topic.md"
+
+ def test_resolve_all_operations(self, test_registry):
+ """Test resolving all operations at once."""
+ operations = MemoryOperations(
+ write_uris=[
+ WriteOp(
+ memory_type="preferences",
+ fields={"topic": "Write test"},
+ content="Write content",
+ ),
+ ],
+ edit_uris=[
+ EditOp(
+ memory_type="tools",
+ fields={"tool_name": "edit_tool"},
+ patches={"content": "Updated"},
+ ),
+ ],
+ delete_uris=[
+ DeleteOp(
+ memory_type="preferences",
+ fields={"topic": "Delete me"},
+ ),
+ ],
+ )
+
+ resolved = resolve_all_operations(operations, test_registry)
+
+ assert resolved.has_errors() is False
+ assert len(resolved.write_operations) == 1
+ assert len(resolved.edit_operations) == 1
+ assert len(resolved.delete_operations) == 1
+
+ # Verify resolved URIs
+ assert resolved.write_operations[0][1] == "viking://user/default/memories/preferences/Write test.md"
+ assert resolved.edit_operations[0][1] == "viking://agent/default/memories/tools/edit_tool.md"
+ assert resolved.delete_operations[0][1] == "viking://user/default/memories/preferences/Delete me.md"
+
+ def test_resolve_all_operations_with_errors(self, test_registry):
+ """Test resolving operations with errors."""
+ operations = MemoryOperations(
+ write_uris=[
+ WriteOp(
+ memory_type="unknown",
+ fields={},
+ ),
+ ],
+ )
+
+ resolved = resolve_all_operations(operations, test_registry)
+
+ assert resolved.has_errors() is True
+ assert len(resolved.errors) == 1
+ assert "Failed to resolve write operation" in resolved.errors[0]
+
+
+class TestParseMemoryFileWithFields:
+ """Tests for parse_memory_file_with_fields function."""
+
+ def test_parses_memory_fields_comment(self):
+ """Test parsing MEMORY_FIELDS HTML comment."""
+ content = '''<!-- MEMORY_FIELDS
+{
+ "tool_name": "web_search",
+ "static_desc": "Searches the web for information",
+ "total_calls": 100,
+ "success_count": 92
+}
+-->
+Here is the actual file content.
+It has multiple lines.'''
+ result = parse_memory_file_with_fields(content)
+ assert result["fields"] is not None
+ assert result["fields"]["tool_name"] == "web_search"
+ assert result["fields"]["static_desc"] == "Searches the web for information"
+ assert result["fields"]["total_calls"] == 100
+ assert result["fields"]["success_count"] == 92
+ assert "Here is the actual file content" in result["content"]
+ assert "<!-- MEMORY_FIELDS" not in result["content"]
+
+ def test_returns_null_fields_when_no_comment(self):
+ """Test returns null fields when no MEMORY_FIELDS comment."""
+ content = "Just plain file content\nwithout any special comments"
+ result = parse_memory_file_with_fields(content)
+ assert result["fields"] is None
+ assert result["content"] == content
+
+ def test_handles_empty_content(self):
+ """Test handles empty string input."""
+ result = parse_memory_file_with_fields("")
+ assert result["fields"] is None
+ assert result["content"] == ""
+
+ def test_handles_invalid_json_in_comment(self):
+ """Test handles invalid JSON in MEMORY_FIELDS comment gracefully."""
+ content = '''<!-- MEMORY_FIELDS
+{
+ "tool_name": "web_search",
+ invalid json here
+}
+-->
+File content'''
+ result = parse_memory_file_with_fields(content)
+ assert result["fields"] is None
+ assert "File content" in result["content"]
+
+ def test_removes_comment_from_content(self):
+ """Test that the comment is completely removed from content."""
+ content = '''Before comment
+<!-- MEMORY_FIELDS {"test": "value"} -->
+After comment'''
+ result = parse_memory_file_with_fields(content)
+ assert "<!-- MEMORY_FIELDS" not in result["content"]
+ assert "Before comment" in result["content"]
+ assert "After comment" in result["content"]
+ # The comment should be removed, leaving the surrounding content
+ assert "Before comment" in result["content"]
+ assert "After comment" in result["content"]
+
+ def test_fields_on_same_line(self):
+ """Test MEMORY_FIELDS on single line."""
+ content = '''<!-- MEMORY_FIELDS {"tool_name": "test", "value": 42} -->
+Content'''
+ result = parse_memory_file_with_fields(content)
+ assert result["fields"] is not None
+ assert result["fields"]["tool_name"] == "test"
+ assert result["fields"]["value"] == 42
diff --git a/tests/session/memory/test_merge_ops.py b/tests/session/memory/test_merge_ops.py
new file mode 100644
index 000000000..fea9678cf
--- /dev/null
+++ b/tests/session/memory/test_merge_ops.py
@@ -0,0 +1,265 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: Apache-2.0
+"""
+Tests for MergeOp architecture - type-safe merge operations.
+"""
+
+import tempfile
+from pathlib import Path
+
+import pytest
+import yaml
+
+from openviking.session.memory.dataclass import (
+ MemoryField,
+ MemoryTypeSchema,
+)
+from openviking.session.memory.merge_op import (
+ MergeOp,
+ MergeOpBase,
+ MergeOpFactory,
+ PatchOp,
+ SumOp,
+ ImmutableOp,
+ SearchReplaceBlock,
+ StrPatch,
+ apply_str_patch,
+)
+from openviking.session.memory.merge_op.base import FieldType
+from openviking.session.memory.schema_model_generator import (
+ SchemaModelGenerator,
+ SchemaPromptGenerator,
+ to_pascal_case,
+)
+from openviking.session.memory.memory_type_registry import (
+ MemoryTypeRegistry,
+ create_default_registry,
+)
+
+
+# ============================================================================
+# Test MergeOp Base Classes
+# ============================================================================
+
+
+class TestPatchOp:
+ """Tests for PatchOp."""
+
+ def test_get_output_schema_type_string(self):
+ """String field with patch should return StrPatch."""
+ op = PatchOp(FieldType.STRING)
+ assert op.get_output_schema_type(FieldType.STRING) == StrPatch
+
+ def test_get_output_schema_type_int(self):
+ """Int field with patch should return int."""
+ op = PatchOp(FieldType.INT64)
+ assert op.get_output_schema_type(FieldType.INT64) == int
+
+ def test_get_output_schema_type_float(self):
+ """Float field with patch should return float."""
+ op = PatchOp(FieldType.FLOAT32)
+ assert op.get_output_schema_type(FieldType.FLOAT32) == float
+
+ def test_get_output_schema_type_bool(self):
+ """Bool field with patch should return bool."""
+ op = PatchOp(FieldType.BOOL)
+ assert op.get_output_schema_type(FieldType.BOOL) == bool
+
+ def test_get_output_schema_description_string(self):
+ """String field description should mention PATCH."""
+ op = PatchOp(FieldType.STRING)
+ desc = op.get_output_schema_description("test content")
+ assert "PATCH" in desc
+ assert "test content" in desc
+
+ def test_get_output_schema_description_other(self):
+ """Non-string field description should mention replace."""
+ op = PatchOp(FieldType.INT64)
+ desc = op.get_output_schema_description("score")
+ assert "Replace" in desc
+ assert "score" in desc
+
+ def test_apply(self):
+ """PatchOp apply should just return the patch value."""
+ op_str = PatchOp(FieldType.STRING)
+ assert op_str.apply("old", "new") == "new"
+
+ op_int = PatchOp(FieldType.INT64)
+ assert op_int.apply(100, 200) == 200
+
+
+class TestSumOp:
+ """Tests for SumOp."""
+
+ def test_get_output_schema_type(self):
+ """SumOp should return appropriate numeric types."""
+ op = SumOp()
+ assert op.get_output_schema_type(FieldType.INT64) == int
+ assert op.get_output_schema_type(FieldType.FLOAT32) == float
+
+ def test_get_output_schema_description(self):
+ """Description should have 'add for' format."""
+ op = SumOp()
+ desc = op.get_output_schema_description("打分合")
+ assert desc == "add for '打分合'"
+
+ def test_apply_both_int(self):
+ """Sum of two ints."""
+ op = SumOp()
+ assert op.apply(10, 5) == 15
+
+ def test_apply_both_float(self):
+ """Sum of two floats."""
+ op = SumOp()
+ assert op.apply(10.5, 3.5) == 14.0
+
+ def test_apply_mixed(self):
+ """Sum of int and float."""
+ op = SumOp()
+ assert op.apply(10, 3.5) == 13.5
+
+ def test_apply_current_none(self):
+ """Current is None should return patch."""
+ op = SumOp()
+ assert op.apply(None, 10) == 10
+
+ def test_apply_invalid_values(self):
+ """Invalid values should fall back to patch."""
+ op = SumOp()
+ assert op.apply("not a number", 10) == 10
+
+
+class TestImmutableOp:
+ """Tests for ImmutableOp."""
+
+ def test_get_output_schema_type(self):
+ """ImmutableOp should return base types."""
+ op = ImmutableOp()
+ assert op.get_output_schema_type(FieldType.STRING) == str
+ assert op.get_output_schema_type(FieldType.INT64) == int
+
+ def test_get_output_schema_description(self):
+ """Description should mention immutable."""
+ op = ImmutableOp()
+ desc = op.get_output_schema_description("name")
+ assert "Immutable" in desc
+ assert "name" in desc
+ assert "can only be set once" in desc
+
+ def test_apply_current_none(self):
+ """Current is None should set to patch."""
+ op = ImmutableOp()
+ assert op.apply(None, "new value") == "new value"
+
+ def test_apply_current_exists(self):
+ """Current exists should keep current."""
+ op = ImmutableOp()
+ assert op.apply("existing", "new value") == "existing"
+
+
+class TestMergeOpFactory:
+ """Tests for MergeOpFactory."""
+
+ def test_create_patch(self):
+ """Factory should create PatchOp for PATCH."""
+ op = MergeOpFactory.create(MergeOp.PATCH, FieldType.STRING)
+ assert isinstance(op, PatchOp)
+
+ def test_create_sum(self):
+ """Factory should create SumOp for SUM."""
+ op = MergeOpFactory.create(MergeOp.SUM, FieldType.INT64)
+ assert isinstance(op, SumOp)
+
+ def test_create_immutable(self):
+ """Factory should create ImmutableOp for IMMUTABLE."""
+ op = MergeOpFactory.create(MergeOp.IMMUTABLE, FieldType.STRING)
+ assert isinstance(op, ImmutableOp)
+
+ def test_from_field(self):
+ """Factory should create from MemoryField."""
+ field = MemoryField(
+ name="test",
+ field_type=FieldType.STRING,
+ merge_op=MergeOp.SUM,
+ )
+ op = MergeOpFactory.from_field(field)
+ assert isinstance(op, SumOp)
+
+
+# ============================================================================
+# Test Structured Patch Models
+# ============================================================================
+
+
+class TestSearchReplaceBlock:
+ """Tests for SearchReplaceBlock."""
+
+ def test_create_basic(self):
+ """Create a basic SearchReplaceBlock."""
+ block = SearchReplaceBlock(
+ search="old content",
+ replace="new content",
+ )
+ assert block.search == "old content"
+ assert block.replace == "new content"
+ assert block.start_line is None
+
+ def test_create_with_start_line(self):
+ """Create with start line."""
+ block = SearchReplaceBlock(
+ search="old",
+ replace="new",
+ start_line=10,
+ )
+ assert block.start_line == 10
+
+
+class TestStrPatch:
+ """Tests for StrPatch."""
+
+ def test_create_empty(self):
+ """Create empty StrPatch."""
+ patch = StrPatch()
+ assert len(patch.blocks) == 0
+
+ def test_create_with_blocks(self):
+ """Create with blocks."""
+ block1 = SearchReplaceBlock(search="a", replace="b")
+ block2 = SearchReplaceBlock(search="c", replace="d")
+ patch = StrPatch(blocks=[block1, block2])
+ assert len(patch.blocks) == 2
+
+
+# ============================================================================
+# Test StrPatch Conversion
+# ============================================================================
+
+
+class TestApplyStrPatch:
+ """Tests for apply_str_patch."""
+
+ def test_empty_patch(self):
+ """Empty patch returns original."""
+ original = "line1\nline2\nline3"
+ patch = StrPatch()
+ result = apply_str_patch(original, patch)
+ assert result == original
+
+ def test_simple_replace(self):
+ """Simple replace."""
+ original = "hello world"
+ patch = StrPatch(blocks=[
+ SearchReplaceBlock(
+ search="hello world",
+ replace="hello there",
+ start_line=1
+ )
+ ])
+ result = apply_str_patch(original, patch)
+ # Directly test apply_str_patch
+ assert result == "hello there"
+
+
+# ============================================================================
+# 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
new file mode 100644
index 000000000..9d0250f27
--- /dev/null
+++ b/tests/session/memory/test_schema_models.py
@@ -0,0 +1,308 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: Apache-2.0
+"""Tests for schema_models.py - dynamic Pydantic model generation."""
+
+import tempfile
+from pathlib import Path
+from typing import Union
+
+import pytest
+import yaml
+
+from openviking.session.memory.dataclass import (
+ MemoryField,
+ MemoryTypeSchema,
+)
+from openviking.session.memory.merge_op.base import FieldType, MergeOp
+from openviking.session.memory.memory_type_registry import (
+ MemoryTypeRegistry,
+ create_default_registry,
+)
+from openviking.session.memory.schema_model_generator import (
+ SchemaModelGenerator,
+ SchemaPromptGenerator,
+ to_pascal_case,
+)
+
+
+class TestToPascalCase:
+ """Tests for to_pascal_case helper function."""
+
+ def test_snake_case(self):
+ """Test converting snake_case to PascalCase."""
+ assert to_pascal_case("profile_memory") == "ProfileMemory"
+
+ def test_kebab_case(self):
+ """Test converting kebab-case to PascalCase."""
+ assert to_pascal_case("memory-type") == "MemoryType"
+
+ def test_spaces(self):
+ """Test converting space-separated to PascalCase."""
+ assert to_pascal_case("user preferences") == "UserPreferences"
+
+ def test_mixed(self):
+ """Test mixed separators."""
+ assert to_pascal_case("test-case_with spaces") == "TestCaseWithSpaces"
+
+
+class TestSchemaModelGenerator:
+ """Tests for SchemaModelGenerator."""
+
+ @pytest.fixture
+ def sample_memory_type(self):
+ """Create a sample MemoryTypeSchema for testing."""
+ return MemoryTypeSchema(
+ memory_type="test_type",
+ description="Test memory type",
+ fields=[
+ MemoryField(
+ name="field1",
+ field_type=FieldType.STRING,
+ description="First test field",
+ merge_op=MergeOp.PATCH,
+ ),
+ MemoryField(
+ name="field2",
+ field_type=FieldType.INT64,
+ description="Second test field",
+ merge_op=MergeOp.SUM,
+ ),
+ ],
+ filename_template="test.md",
+ directory="test://dir",
+ )
+
+ @pytest.fixture
+ def registry_with_sample(self, sample_memory_type):
+ """Create a registry with a sample memory type."""
+ registry = MemoryTypeRegistry()
+ registry.register(sample_memory_type)
+ return registry
+
+ @pytest.fixture
+ def real_registry(self):
+ """Create a registry with real schemas."""
+ schemas_dir = Path(__file__).parent.parent.parent.parent / "openviking" / "prompts" / "templates" / "memory"
+ return create_default_registry(str(schemas_dir))
+
+ 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)
+ model = generator.create_flat_data_model(sample_memory_type)
+
+ # Check model name
+ assert model.__name__ == "TestTypeData"
+
+ # Check model has the memory_type field
+ assert "memory_type" in model.model_fields
+ # memory_type is a required field with literal type
+
+ # Check business fields
+ assert "field1" in model.model_fields
+ assert "field2" in model.model_fields
+
+ # Check metadata fields are present
+ assert "uri" in model.model_fields
+ assert "name" in model.model_fields
+ assert "abstract" in model.model_fields
+ assert "overview" in model.model_fields
+ assert "content" in model.model_fields
+ assert "tags" in model.model_fields
+ assert "created_at" in model.model_fields
+ assert "updated_at" in model.model_fields
+
+ def test_generate_all_models(self, real_registry):
+ """Test generating models for all real schemas."""
+ generator = SchemaModelGenerator(real_registry)
+ # Generate all models including disabled ones
+ models = generator.generate_all_models(include_disabled=True)
+
+ # Check we have models for all registered types (including disabled)
+ assert len(models) == len(real_registry.list_all(include_disabled=True))
+
+ # Check specific types exist
+ assert "profile" in models
+ assert "preferences" in models
+
+ # Check profile model has 'content' field
+ profile_model = models["profile"]
+ assert "content" in profile_model.model_fields
+
+ def test_create_discriminated_union_model(self, real_registry):
+ """Test creating the union model wrapper."""
+ generator = SchemaModelGenerator(real_registry)
+ union_model = generator.create_discriminated_union_model()
+
+ # The union model is a wrapper BaseModel
+ assert hasattr(union_model, "model_fields")
+ assert "data" in union_model.model_fields
+
+ def test_get_llm_json_schema(self, real_registry):
+ """Test getting the LLM JSON schema."""
+ generator = SchemaModelGenerator(real_registry)
+ json_schema = generator.get_llm_json_schema()
+
+ # Check it's a valid JSON schema
+ assert "$defs" in json_schema or "definitions" in json_schema
+ assert "properties" in json_schema
+
+ # Check it includes operations
+ assert "write_uris" in json_schema["properties"]
+ assert "edit_uris" in json_schema["properties"]
+ assert "delete_uris" in json_schema["properties"]
+
+ # Check delete_uris is an array of strings
+ delete_props = json_schema["properties"]["delete_uris"]
+ assert delete_props.get("items", {}).get("type") == "string"
+
+ def test_get_memory_data_json_schema(self, real_registry):
+ """Test getting just the MemoryData JSON schema."""
+ generator = SchemaModelGenerator(real_registry)
+ json_schema = generator.get_memory_data_json_schema()
+
+ # Check it's a valid JSON schema
+ assert "$defs" in json_schema or "definitions" in json_schema
+ assert "properties" in json_schema
+
+ def test_model_caching(self, registry_with_sample, sample_memory_type):
+ """Test that models are cached."""
+ generator = SchemaModelGenerator(registry_with_sample)
+
+ # Create model twice
+ model1 = generator.create_flat_data_model(sample_memory_type)
+ model2 = generator.create_flat_data_model(sample_memory_type)
+
+ # Should be the same object
+ assert model1 is model2
+
+ def test_dynamic_new_schema(self):
+ """Test that adding a new schema at runtime works without code changes."""
+ # Create a temporary YAML file for a new memory type
+ with tempfile.TemporaryDirectory() as tmpdir:
+ tmp_path = Path(tmpdir)
+ new_schema_path = tmp_path / "new_type.yaml"
+
+ # Write a new schema
+ new_schema = {
+ "memory_type": "new_custom_type",
+ "description": "A dynamically added custom type",
+ "directory": "test://new",
+ "filename_template": "custom_{name}.md",
+ "fields": [
+ {
+ "name": "custom_field",
+ "type": "string",
+ "description": "Custom field description",
+ "merge_op": "patch",
+ }
+ ],
+ }
+
+ with open(new_schema_path, "w", encoding="utf-8") as f:
+ yaml.dump(new_schema, f)
+
+ # Load it
+ registry = MemoryTypeRegistry()
+ registry.load_from_yaml(str(new_schema_path))
+
+ # Verify it's loaded
+ assert registry.get("new_custom_type") is not None
+
+ # Generate model
+ generator = SchemaModelGenerator(registry)
+ model = generator.create_flat_data_model(registry.get("new_custom_type"))
+
+ # Verify the model has the custom field
+ assert "custom_field" in model.model_fields
+ assert "memory_type" in model.model_fields
+ assert "uri" in model.model_fields
+
+
+class TestSchemaPromptGenerator:
+ """Tests for SchemaPromptGenerator."""
+
+ @pytest.fixture
+ def real_registry(self):
+ """Create a registry with real schemas."""
+ schemas_dir = Path(__file__).parent.parent.parent.parent / "openviking" / "prompts" / "templates" / "memory"
+ return create_default_registry(str(schemas_dir))
+
+ def test_generate_type_descriptions(self, real_registry):
+ """Test generating type descriptions."""
+ generator = SchemaPromptGenerator(real_registry)
+ descriptions = generator.generate_type_descriptions()
+
+ # Check it's not empty
+ assert len(descriptions) > 0
+
+ # Check it contains the structure header
+ assert "## Available Memory Types" in descriptions
+
+ # Check for memory types that should always be enabled
+ # (profile and preferences might be disabled, check for events or cards instead)
+ assert "### events" in descriptions or "### cards" in descriptions
+
+ def test_generate_field_descriptions(self, real_registry):
+ """Test generating field descriptions for a specific type."""
+ generator = SchemaPromptGenerator(real_registry)
+
+ # Get profile fields
+ profile_fields = generator.generate_field_descriptions("profile")
+ assert profile_fields is not None
+ assert "### profile Fields" in profile_fields
+ assert "content" in profile_fields
+
+ # Get preferences fields
+ pref_fields = generator.generate_field_descriptions("preferences")
+ assert pref_fields is not None
+ assert "topic" in pref_fields
+ assert "content" in pref_fields
+
+ # Non-existent type returns None
+ assert generator.generate_field_descriptions("non_existent") is None
+
+ def test_get_full_prompt_context(self, real_registry):
+ """Test getting the full prompt context."""
+ generator = SchemaPromptGenerator(real_registry)
+ context = generator.get_full_prompt_context()
+
+ # Check structure
+ assert "type_descriptions" in context
+ assert "memory_types" in context
+
+ # Check memory_types entries - should only include enabled types
+ memory_types = context["memory_types"]
+ assert len(memory_types) == len(real_registry.list_all())
+
+ # Check each entry has expected fields
+ for mt in memory_types:
+ assert "memory_type" in mt
+ assert "description" in mt
+ assert "fields" in mt
+ for field in mt["fields"]:
+ assert "name" in field
+ assert "type" in field
+ assert "description" in field
+
+
+class TestIntegration:
+ """Integration tests for the complete schema system."""
+
+ def test_end_to_end_model_generation_and_validation(self):
+ """Test end-to-end: load schemas, generate models, validate data."""
+ schemas_dir = Path(__file__).parent.parent.parent.parent / "openviking" / "prompts" / "templates" / "memory"
+ registry = create_default_registry(str(schemas_dir))
+
+ # Create generator
+ generator = SchemaModelGenerator(registry)
+
+ # Get the operations model
+ operations_model = generator.create_structured_operations_model()
+
+ # Get JSON schema
+ json_schema = generator.get_llm_json_schema()
+
+ # Verify the schema includes descriptions from YAML
+ # Check that $defs has entries
+ defs = json_schema.get("$defs", {})
+ assert len(defs) > 0, "No definitions found in JSON schema"
diff --git a/uv.lock b/uv.lock
index 8b51bfe30..6e9437f6a 100644
--- a/uv.lock
+++ b/uv.lock
@@ -1041,6 +1041,15 @@ wheels = [
{ url = "https://files.pythonhosted.org/packages/4e/8c/f3147f5c4b73e7550fe5f9352eaa956ae838d5c51eb58e7a25b9f3e2643b/decorator-5.2.1-py3-none-any.whl", hash = "sha256:d316bb415a2d9e2d2b3abcc4084c6502fc09240e292cd76a76afc106a1c8e04a", size = 9190, upload-time = "2025-02-24T04:41:32.565Z" },
]
+[[package]]
+name = "diff-match-patch"
+version = "20241021"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/0e/ad/32e1777dd57d8e85fa31e3a243af66c538245b8d64b7265bec9a61f2ca33/diff_match_patch-20241021.tar.gz", hash = "sha256:beae57a99fa48084532935ee2968b8661db861862ec82c6f21f4acdd6d835073", size = 39962, upload-time = "2024-10-21T19:41:21.094Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/f7/bb/2aa9b46a01197398b901e458974c20ed107935c26e44e37ad5b0e5511e44/diff_match_patch-20241021-py3-none-any.whl", hash = "sha256:93cea333fb8b2bc0d181b0de5e16df50dd344ce64828226bda07728818936782", size = 43252, upload-time = "2024-10-21T19:41:19.914Z" },
+]
+
[[package]]
name = "dill"
version = "0.4.0"
@@ -3498,6 +3507,7 @@ gemini-async = [
test = [
{ name = "boto3" },
{ name = "datasets" },
+ { name = "diff-match-patch" },
{ name = "hvac" },
{ name = "pandas", version = "2.3.3", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.11'" },
{ name = "pandas", version = "3.0.1", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version >= '3.11'" },
@@ -3527,6 +3537,7 @@ requires-dist = [
{ name = "datasets", marker = "extra == 'eval'", specifier = ">=2.0.0" },
{ name = "datasets", marker = "extra == 'test'", specifier = ">=2.0.0" },
{ name = "ddgs", marker = "extra == 'bot'", specifier = ">=9.0.0" },
+ { name = "diff-match-patch", marker = "extra == 'test'", specifier = ">=20200713" },
{ name = "dingtalk-stream", marker = "extra == 'bot-dingtalk'", specifier = ">=0.4.0" },
{ name = "ebooklib", specifier = ">=0.18.0" },
{ name = "fastapi", specifier = ">=0.128.0" },