Skip to content

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

26.9 KB
Raw Blame
# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
# SPDX-License-Identifier: AGPL-3.0
"""
Session Extract Context Provider - 会话提取 Provider 实现

从会话消息中提取记忆的实现。
"""

import re
from typing import TYPE_CHECKING, Any, Dict, List, Optional

from openviking.message.part import TextPart, ToolPart
from openviking.server.identity import RequestContext, ToolContext
from openviking.session.memory.core import ExtractContextProvider
from openviking.session.memory.dataclass import MemoryFile
from openviking.session.memory.memory_isolation_handler import (
    MemoryIsolationHandler,
    RoleScope,
    peer_user_space,
)
from openviking.session.memory.memory_type_registry import (
    MemoryTypeRegistry,
    get_default_registry,
)
from openviking.session.memory.merge_policy import MEMORY_MERGE_POLICY
from openviking.session.memory.tools import (
    add_tool_call_pair_to_messages,
    get_tool,
)
from openviking.session.memory.utils.resource_refs import contains_resource_uri
from openviking.session.memory.utils.uri import render_template
from openviking.session.memory.vision_message_normalizer import (
    replace_image_parts_with_descriptions,
)
from openviking.storage.viking_fs import VikingFS
from openviking.telemetry import tracer
from openviking.utils.time_utils import parse_iso_datetime
from openviking_cli.utils import get_logger
from openviking_cli.utils.config import get_openviking_config

if TYPE_CHECKING:
    from openviking.config.vlm import VLMHandle
    from openviking.session.memory.memory_updater import ExtractContext

logger = get_logger(__name__)

_PREFETCH_SEARCH_QUERY_MAX_CHARS = 5000
_PREFETCH_SEARCH_TEXT_PART_MAX_CHARS = 1000
_PREFETCH_SEARCH_ASSISTANT_TEXT_PART_MAX_CHARS = 500
_PREFETCH_SEARCH_TOOL_FIELD_MAX_CHARS = 500
_RESOURCE_REASON_LANGUAGE_RE = re.compile(
    r"(?im)^\s*(?:User reason|用户说明|用户原因|用户理由)[::]\s*(.+?)\s*$"
)


class SessionExtractContextProvider(ExtractContextProvider):
    """会话提取 Provider - 从会话消息中提取记忆"""

    include_tool_parts_in_conversation: bool = False
    split_long_text_messages_for_extraction: bool = True

    def __init__(
        self,
        messages: Any,
        latest_archive_overview: str = "",
        isolation_handler: MemoryIsolationHandler = None,
        ctx: RequestContext = None,
        viking_fs: VikingFS = None,
        transaction_handle=None,
        memory_registry: MemoryTypeRegistry | None = None,
        vlm_config: Optional["VLMHandle"] = None,
        *,
        source_archive_uri: str = "",
        extraction_scope: str = "",
    ):
        self.messages = list(messages) if isinstance(messages, list) else messages
        self.latest_archive_overview = latest_archive_overview
        self._source_archive_uri = source_archive_uri
        self._extraction_scope = extraction_scope
        self._output_language = self._detect_language()
        self._registry = memory_registry  # Lazy defaults if no account snapshot was supplied.
        self._schema_directories = None
        self._extract_context = None  # 缓存 ExtractContext 实例
        self._isolation_handler = isolation_handler
        self._read_file_contents: Dict[str, MemoryFile] = {}
        # 读取 eager_prefetch 配置
        config = get_openviking_config()
        self._eager_prefetch = config.memory.eager_prefetch if config.memory else False
        self._prefetch_search_topn = config.memory.prefetch_search_topn if config.memory else 5
        self._ctx = ctx
        self._viking_fs = viking_fs
        self._transaction_handle = transaction_handle
        self._vlm_config = vlm_config
        self._link_enabled = config.memory.link_enabled if config.memory else False
        self._vision_messages_prepared = False
        self._vision_vlm = None

    @property
    def read_file_contents(self) -> Dict[str, MemoryFile]:
        return self._read_file_contents

    def get_conversation_text(self) -> str:
        """Get the full conversation text for match_text validation."""
        text_parts = []
        for message in self.messages or []:
            for part in getattr(message, "parts", []):
                if isinstance(part, TextPart) and part.text:
                    text_parts.append(part.text)
        return "\n".join(text_parts)

    def set_transaction_handle(self, handle):
        """Set transaction handle after lock is acquired."""
        self._transaction_handle = handle

    def get_extract_context(self) -> "ExtractContext":
        """获取或创建 ExtractContext 实例(缓存)"""
        from openviking.session.memory.memory_updater import ExtractContext

        if self._extract_context is None:
            self._extract_context = ExtractContext(
                self.messages if isinstance(self.messages, list) else [],
                split_long_text_messages=self.split_long_text_messages_for_extraction,
                source_archive_uri=self._source_archive_uri,
                extraction_scope=self._extraction_scope,
            )
        return self._extract_context

    async def prepare_extraction_messages(self) -> None:
        """Prepare extraction-only messages before ranges and prompts are built."""
        if self._vision_messages_prepared:
            return
        if isinstance(self.messages, list):
            self.messages = await replace_image_parts_with_descriptions(
                self.messages,
                get_vlm=self._get_vision_vlm,
                logger=logger,
            )
            self._extract_context = None
            self._output_language = self._detect_language()
        self._vision_messages_prepared = True

    def _get_vision_vlm(self):
        if self._vision_vlm is not None:
            return self._vision_vlm
        vlm_config = self._vlm_config
        if vlm_config is None:
            raise RuntimeError(
                "SessionExtractContextProvider requires an explicitly resolved "
                "VLM for vision processing"
            )
        if not (vlm_config and vlm_config.is_available()):
            return None
        self._vision_vlm = vlm_config
        return self._vision_vlm

    def _detect_language(self) -> str:
        """检测输出语言"""
        from openviking.session.memory.utils import (
            resolve_output_language,
            strip_language_detection_noise,
        )

        user_text_parts = []
        all_text_parts = []
        for message in self.messages or []:
            for part in getattr(message, "parts", []):
                if isinstance(part, TextPart) and part.text:
                    text = self._language_signal_text(
                        part.text,
                        strip_language_detection_noise=strip_language_detection_noise,
                    )
                    all_text_parts.append(text)
                    if getattr(message, "role", "") == "user":
                        user_text_parts.append(text)

        text_parts = user_text_parts or all_text_parts
        return resolve_output_language("\n".join(text_parts))

    @staticmethod
    def _language_signal_text(text: str, *, strip_language_detection_noise) -> str:
        """Keep user-authored language signal and drop machine-oriented URI noise."""
        reason_lines = [
            match.group(1).strip()
            for match in _RESOURCE_REASON_LANGUAGE_RE.finditer(text or "")
            if match.group(1).strip()
        ]
        if reason_lines:
            return "\n".join(reason_lines)
        return strip_language_detection_noise(text)

    def get_output_language(self) -> str:
        return self._output_language

    def _conversation_contains_resource_uri(self) -> bool:
        for message in self.messages or []:
            content = getattr(message, "content", None)
            if content and contains_resource_uri(content):
                return True
            for part in getattr(message, "parts", []) or []:
                text = getattr(part, "text", None)
                if text and contains_resource_uri(text):
                    return True
        return False

    def instruction(self) -> str:
        output_language = self._output_language
        contains_resource_uri = self._conversation_contains_resource_uri()
        resource_uri_handling = (
            """

## Resource URI Handling
- If the conversation contains a resource URI (`viking://resources/...`, `viking://user/{user_id}/resources/...`, or `viking://user/{user_id}/peers/{peer_id}/resources/...`) and the user says a durable fact, judgment, preference, or event about it, extract that memory into whichever enabled memory type its schema best fits.
- Preserve resource references as markdown links in visible memory content when useful. Example: user said "The user saved a Ryoma Echizen photo viking://resources/images/ryoma" -> write "The user saved a [Ryoma Echizen photo](viking://resources/images/ryoma)".
- For `## Resource Addition` blocks, use `User reason` as the user's intent and `Resource abstract` only as optional context. Do not copy raw fields such as `Resource URI`, `Added at`, `Resource abstract`, or `User reason` into visible memory content.
- For `## Resource Deletion` blocks, update existing mutable memories that mention or depend on the deleted resource. Do not create a new event solely for this maintenance action.
- Use descriptive link text such as `[Ryoma Echizen photo](viking://resources/...)`; avoid visible wording like `resource URI is` or `Resource URI`.
- If the user already wrote a markdown link to a resource URI, keep the same resource link intent.
- Do NOT claim you inspected, summarized, OCRed, or opened the resource file unless the conversation explicitly provides that fact.
"""
            if contains_resource_uri
            else ""
        )
        resource_deletion_read_source = (
            ", or listed under the system-generated `## Resource Deletion` block's `Affected memory URIs`"
            if contains_resource_uri
            else ""
        )
        goal = f"""You are a memory extraction and maintenance agent. Analyze the conversation together with the pre-fetched existing memories, then produce a single atomic plan to create, update, delete, or reorganize memories so that the final memory collection conforms to all enabled memory schemas.

## 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
- ONLY read and search tools are available - DO NOT use write tool
- Before editing ANY existing memory file, you MUST first read its complete content
- ONLY read URIs that are explicitly listed in ls/search tool results, returned by previous tool calls{resource_deletion_read_source}

## Target Output Language
All memory content MUST be written in {output_language}.

## URI Handling
The system automatically generates URIs based on memory_type and fields. Just provide correct memory_type and fields.
{resource_uri_handling}

## Self and Peer Memory
When a memory item describes the current user, omit peer_id.
When a memory item describes a peer, set peer_id to one of the peer_id values allowed by
the output schema. Do not invent peer_id values.
For memory items that carry a message-range field, the system derives self/peer targets from that range.
Message role is authoritative for newly extracted facts: attribute each fact to the speaker whose
message states it, and follow each enabled memory type's own schema rules for which role its content
comes from. Do not infer ownership from neighboring messages.
Facts already stored in pre-fetched or explicitly read memories remain valid sources for
maintenance and may be preserved, normalized, merged, split, or moved between enabled memory
types when required by their schemas.

{MEMORY_MERGE_POLICY}
"""

        return goal

    def _build_conversation_message(self) -> Dict[str, Any]:
        """构建包含 Conversation History 的 user message"""
        from datetime import datetime

        if self.messages:
            first_msg_time = getattr(self.messages[0], "created_at", None)
            last_msg_time = getattr(self.messages[-1], "created_at", None)
        else:
            first_msg_time = None
            last_msg_time = None

        if first_msg_time:
            session_time = parse_iso_datetime(first_msg_time)
        else:
            session_time = datetime.now()

        session_time_str = session_time.strftime("%Y-%m-%d %H:%M")
        day_of_week = session_time.strftime("%A")

        # 检查是否需要显示范围
        if last_msg_time and last_msg_time != first_msg_time:
            last_time = parse_iso_datetime(last_msg_time)
            time_display = f"{session_time_str} - {last_time.strftime('%Y-%m-%d %H:%M')}"
        else:
            time_display = session_time_str

        extract_context = self.get_extract_context()
        conversation = self._assemble_conversation(extract_context.messages)

        return {
            "role": "user",
            "content": f"""## Conversation History
**Session Time:** {time_display} ({day_of_week})
Relative times (e.g., 'last week', 'next month') are based on Session Time, not today.

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

    def _assemble_conversation(self, messages: Any) -> str:
        """Assemble conversation string from messages.

        Args:
            messages: List of Message objects
            latest_archive_overview: Optional overview from previous archive for context

        Returns:
            Formatted conversation string
        """
        from openviking.message import Message

        conversation_sections: List[str] = []

        def format_message_with_parts(msg: Message) -> str:
            """Format message parts for extraction.

            By default this provider extracts user/session memories, so tool
            calls/results are omitted: they are execution evidence rather than
            user utterances and can leak environment/database state into user
            memories. Agent-scope providers enable tool evidence explicitly.
            """

            parts = getattr(msg, "parts", [])
            formatted_parts: List[str] = []
            for part in parts:
                if hasattr(part, "text") and part.text:
                    formatted_parts.append(part.text)
                elif self.include_tool_parts_in_conversation and isinstance(part, ToolPart):
                    fields = [f"tool_name={part.tool_name}"]
                    if part.tool_status:
                        fields.append(f"status={part.tool_status}")
                    if part.tool_input:
                        fields.append(f"input={part.tool_input}")
                    if part.tool_output:
                        fields.append(f"output={part.tool_output[:500]}")
                    if part.duration_ms is not None:
                        fields.append(f"duration_ms={part.duration_ms}")
                    if part.skill_uri:
                        fields.append(f"skill={part.skill_uri.rstrip('/').split('/')[-1]}")
                    formatted_parts.append("ToolCall: " + "; ".join(fields))
            return "\n".join(formatted_parts)

        def format_message_header(msg: Message, idx: int) -> str | None:
            """Format message header with role and stable interaction peer when present."""
            body = format_message_with_parts(msg)
            if not body.strip():
                return None
            speaker = msg.peer_id or msg.role
            return f"[{idx}][{msg.role}][{speaker}]: {body}"

        formatted_messages = [
            formatted
            for idx, msg in enumerate(messages)
            if (formatted := format_message_header(msg, idx)) is not None
        ]
        conversation_sections.append("\n".join(formatted_messages))

        return "\n\n".join(section for section in conversation_sections if section)

    def _truncate_prefetch_query_text(self, text: Any, max_chars: int) -> str:
        normalized = " ".join(str(text or "").split())
        if len(normalized) <= max_chars:
            return normalized
        return normalized[: max_chars - 3].rstrip() + "..."

    def _build_prefetch_search_query(self) -> str:
        """Build a compact semantic query from raw conversation messages.

        The LLM already receives the full conversation via pre_fetch_messages.
        Search only needs topical recall signals, so use the raw message content
        instead of the prompt-wrapped conversation.
        """
        if not isinstance(self.messages, list):
            return ""

        primary_sections: List[str] = []
        supporting_sections: List[str] = []

        for msg in self.messages:
            role = getattr(msg, "role", "")
            speaker = getattr(msg, "peer_id", "") or role
            parts = getattr(msg, "parts", [])

            text_parts: List[str] = []

            for part in parts:
                if hasattr(part, "text") and part.text:
                    limit = (
                        _PREFETCH_SEARCH_TEXT_PART_MAX_CHARS
                        if role == "user"
                        else _PREFETCH_SEARCH_ASSISTANT_TEXT_PART_MAX_CHARS
                    )
                    text_parts.append(self._truncate_prefetch_query_text(part.text, limit))
            if text_parts:
                section = f"{speaker}: " + "\n".join(text_parts)
                if role == "user":
                    primary_sections.append(section)
                else:
                    supporting_sections.append(section)

        query = "\n\n".join(primary_sections + supporting_sections)
        if not query.strip():
            query = self._assemble_conversation(self.messages)

        return self._truncate_prefetch_query_text(query, _PREFETCH_SEARCH_QUERY_MAX_CHARS)

    def create_tool_context(self, default_search_uris=[]):
        extract_context = self.get_extract_context()
        tool_ctx = ToolContext(
            viking_fs=self._viking_fs,
            request_ctx=self._ctx,
            transaction_handle=self._transaction_handle,
            default_search_uris=default_search_uris,
            read_file_contents=self._read_file_contents,
            page_id_map=extract_context.page_id_map,
        )
        return tool_ctx

    @staticmethod
    def _is_expected_read_not_found(error: Any) -> bool:
        if not error:
            return False
        error_text = str(error)
        return error_text == "not_found" or error_text.startswith("File not found")

    async def read_file(self, uri: str) -> Optional[Dict]:
        """Read a file via MemoryReadTool (auto-registers page_id, fills read_file_contents)."""
        read_tool = get_tool("read")
        if not read_tool:
            return None
        try:
            result = await read_tool.execute(self.create_tool_context(), uri=uri)
            if isinstance(result, dict) and "error" in result:
                if not self._is_expected_read_not_found(result["error"]):
                    tracer.info(f"Failed to read {uri}: {result['error']}")
                return None
            return result
        except Exception as e:
            if not self._is_expected_read_not_found(e):
                tracer.error(f"Failed to read {uri}: {e}")
            return None

    async def search_files(
        self, query: str, search_uris: List[str] = None, limit: int = 5
    ) -> List[str]:
        """Search via MemorySearchTool, returns list of URIs."""
        search_tool = get_tool("search")
        if not search_tool:
            return []
        try:
            result = await search_tool.execute(
                viking_fs=self._viking_fs,
                ctx=self.create_tool_context(search_uris or []),
                query=query,
                limit=limit,
            )
            if isinstance(result, list):
                return [m.get("uri", "") for m in result if m.get("uri")]
            elif isinstance(result, dict) and "memories" in result:
                return [m.get("uri", "") for m in result.get("memories", []) if m.get("uri")]
            return []
        except Exception as e:
            tracer.error(f"Failed to search: {e}")
            return []

    async def _append_structured_read_result(
        self,
        messages: List[Dict[str, Any]],
        call_id: int,
        file_uri: str,
    ) -> int:
        result = await self.read_file(file_uri)
        if result is not None:
            add_tool_call_pair_to_messages(
                messages=messages,
                call_id=call_id,
                tool_name="read",
                params={"uri": file_uri},
                result=result,
            )
            return call_id + 1
        return call_id

    async def prefetch(self) -> List[Dict]:
        """
        执行 prefetch - 从会话消息中提取相关记忆上下文

        Returns:
            预取的消息列表,第一个元素是 Conversation History user message,后续是 tool call messages
        """
        messages = self.messages

        if not isinstance(messages, list):
            tracer.error(f"Expected List[Message], got {type(messages)}")
            return []

        # 先构建 Conversation History user message
        pre_fetch_messages = []
        pre_fetch_messages.append(self._build_conversation_message())

        # 触发 registry 加载,过滤掉 agent stage 的 schema(trajectory/experience 由执行提取处理)
        schemas = [
            s
            for s in self._get_registry().list_all(include_disabled=False)
            if getattr(s, "stage", "user") == "user"
        ]
        if self._isolation_handler:
            schemas = [s for s in schemas if self._isolation_handler.allows_schema(s)]

        # 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)

        rolescope: RoleScope = self._isolation_handler.get_read_scope()

        for schema in schemas:
            if not schema.directory:
                continue

            # 根据 operation_mode 决定是否需要 ls 和读取其他文件
            if schema.operation_mode == "add_only":
                continue

            schema_dirs = set()
            if self._isolation_handler:
                schema_dirs.update(self._isolation_handler.render_schema_directories(schema))
            else:
                for user_id in rolescope.user_ids:
                    dir_path = render_template(
                        schema.directory,
                        {"user_space": user_id},
                    )
                    schema_dirs.add(dir_path)
                    for peer_id in rolescope.peer_ids:
                        dir_path = render_template(
                            schema.directory,
                            {"user_space": peer_user_space(user_id, peer_id)},
                        )
                        schema_dirs.add(dir_path)
            if schema.filename_has_variables():
                for dir_path in schema_dirs:
                    ls_dirs.add(dir_path)
            else:
                for dir_path in schema_dirs:
                    file_uri = f"{dir_path}/{schema.filename_template}"
                    read_files.add(file_uri)

        call_id_seq = 0
        # Step 2: Execute search for each ls directory (instead of ls)

        # 首先读取所有 .overview.md 文件(截断以避免窗口过大)
        # 为 overview 读取创建一个基本的 tool_ctx

        # 在每个之前 ls 的目录内执行 search(替换原来的 ls操作)
        files_to_read_from_search = []  # 收集需要读取的文件(eager_prefetch 模式)

        # 批量 search:所有目录一次搜索
        if ls_dirs:
            dir_list = list(ls_dirs)
            search_query = self._build_prefetch_search_query()
            if not search_query:
                search_query = "conversation"
            search_uris = await self.search_files(
                query=search_query,
                search_uris=dir_list,
            )
            result_value = search_uris
            if self._eager_prefetch:
                files_to_read_from_search.extend(search_uris)

            add_tool_call_pair_to_messages(
                messages=pre_fetch_messages,
                call_id=call_id_seq,
                tool_name="search",
                params={"query": "[Keywords]", "search_uri": dir_list},
                result=result_value,
            )
            call_id_seq += 1

        # 读取单文件 schema 的文件(只对非 add_only 模式)
        for file_uri in read_files:
            call_id_seq = await self._append_structured_read_result(
                messages=pre_fetch_messages,
                call_id=call_id_seq,
                file_uri=file_uri,
            )

        # eager_prefetch 模式:读取搜索结果 top-N
        if self._eager_prefetch:
            topn_files = files_to_read_from_search[: self._prefetch_search_topn]
            for file_uri in topn_files:
                if not file_uri:
                    continue
                call_id_seq = await self._append_structured_read_result(
                    messages=pre_fetch_messages,
                    call_id=call_id_seq,
                    file_uri=file_uri,
                )

        return pre_fetch_messages

    async def execute_tool(
        self,
        tool_call,
    ) -> Any:
        tool = get_tool(tool_call.name)
        if not tool:
            return {"error": f"Unknown tool: {tool_call.name}"}
        result = await tool.execute(self.create_tool_context(), **tool_call.arguments)
        is_expected_read_not_found = (
            tool_call.name == "read"
            and isinstance(result, dict)
            and result.get("error")
            and self._is_expected_read_not_found(result["error"])
        )
        if not is_expected_read_not_found:
            tracer.info(f"tool_call.arguments={tool_call.arguments}")
        return result

    def get_tools(self) -> List[str]:
        """获取可用的工具列表"""
        if self._eager_prefetch:
            # eager_prefetch 模式下不提供工具,所有内容已在 prefetch 中加载
            return []
        return ["read"]

    def get_memory_schemas(self, ctx: RequestContext) -> List[Any]:
        """获取需要参与的 memory schemas(内部自动加载)"""
        schemas = [
            s
            for s in self._get_registry().list_all(include_disabled=False)
            if getattr(s, "stage", "user") == "user"
        ]
        if self._isolation_handler:
            schemas = [s for s in schemas if self._isolation_handler.allows_schema(s)]
        return schemas

    def _get_registry(self) -> MemoryTypeRegistry:
        """获取共享的默认记忆 registry。"""
        if self._registry is None:
            self._registry = get_default_registry()
        return self._registry