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

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

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

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

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

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

# User Profile

User is an AI development engineer with 3 years of experience...

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

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

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..."
}
-->

┌─────────────────────────────────────────────────────────────────┐
│              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                             │  │
│  └───────────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────────┘

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}

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

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

Patch format / Patch 格式:
<<<<<<< SEARCH
:start_line:10
-------
Original content / 原始内容
=======
New content / 新内容
>>>>>>> REPLACE

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 验证

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

openviking/session/memory_extractor.py  # Preserve existing version, do not modify / 保留现有版本，不修改