Skip to content

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

52.1 KB
Raw Blame
"""Memory system for persistent agent memory."""

import asyncio
import json
import re
import time
from pathlib import Path
from typing import TYPE_CHECKING, Any

from loguru import logger

from vikingbot.config.loader import load_config
from vikingbot.openviking_mount.ov_server import VikingClient
from vikingbot.utils.helpers import ensure_dir

if TYPE_CHECKING:
    from vikingbot.config.schema import Config

_LEGACY_MEMORY_RECALL_LIMIT = 30
_TYPE_QUOTA_MEMORY_TYPES = ("events", "entities", "preferences")
_TYPE_QUOTA_EVENT_CHAR_RATIO = 0.75
_TYPE_QUOTA_PREFERENCE_FULL_LIMIT = 1
_MEMORY_TYPE_DESCRIPTIONS = {
    "events": ("Event memories. The URI path includes the event date."),
    "entities": (
        "Entity and topic memories. Use them for stable facts, attributes, "
        "relationships, and background about people, hobbies, places, or concepts."
    ),
    "preferences": (
        "Preference memories. Use them for likes, dislikes, habits, recurring choices, "
        "and long-term personal tendencies."
    ),
    "cases": (
        "Structured training case memories. Use them as scenario/rubric context and "
        "follow direct deterministic links to experiences when available."
    ),
    "experiences": (
        "Reusable agent experiences distilled from prior tasks. Apply them only when their "
        "Situation and policy gates match the current task."
    ),
    "trajectories": (
        "Diagnostic trajectory memories from evaluated rollouts. Use them as read-only "
        "failure/success deltas for similar tasks."
    ),
}


class MemoryStore:
    """Two-layer memory: MEMORY.md (long-term facts) + HISTORY.md (grep-searchable log)."""

    def __init__(self, workspace: Path, config: "Config | None" = None):
        self.memory_dir = ensure_dir(workspace / "memory")
        self.memory_file = self.memory_dir / "MEMORY.md"
        self.history_file = self.memory_dir / "HISTORY.md"
        self._config = config

    def _get_config(self) -> "Config":
        if self._config is None:
            self._config = load_config()
        return self._config

    @staticmethod
    def _get_score(memory: Any) -> float:
        raw_score = (
            memory.get("score", 0) if isinstance(memory, dict) else getattr(memory, "score", 0.0)
        )
        try:
            return float(raw_score)
        except (TypeError, ValueError):
            return 0.0

    @staticmethod
    def _get_uri(memory: Any) -> str:
        return memory.get("uri", "") if isinstance(memory, dict) else getattr(memory, "uri", "")

    @staticmethod
    def _filename_from_uri(uri: str) -> str:
        """Extract the filename (basename) from a memory URI."""
        stripped = uri.rstrip("/")
        if not stripped:
            return ""
        return stripped.rsplit("/", 1)[-1]

    @staticmethod
    def _get_abstract(memory: Any) -> str:
        return (
            memory.get("abstract", "")
            if isinstance(memory, dict)
            else getattr(memory, "abstract", "")
        )

    @staticmethod
    def _get_recall_type(memory: Any) -> str:
        return (
            memory.get("_recall_type", "")
            if isinstance(memory, dict)
            else getattr(memory, "_recall_type", "")
        )

    @classmethod
    def _infer_memory_type(cls, memory: Any) -> str:
        recall_type = cls._get_recall_type(memory)
        if recall_type:
            return recall_type

        uri = cls._get_uri(memory).strip("/")
        parts = [part for part in uri.split("/") if part]
        for idx, part in enumerate(parts):
            if part == "memories" and idx + 1 < len(parts):
                return parts[idx + 1]
        return ""

    @classmethod
    def _with_recall_metadata(cls, memory: Any, memory_type: str, rank: int) -> dict[str, Any]:
        if isinstance(memory, dict):
            item = dict(memory)
        else:
            item = {
                "uri": cls._get_uri(memory),
                "score": cls._get_score(memory),
                "abstract": cls._get_abstract(memory),
            }
        item["_recall_type"] = memory_type
        item["_recall_rank"] = rank
        return item

    @classmethod
    def _limit_memories(cls, result: list[Any], limit: int) -> list[Any]:
        return sorted(result, key=cls._get_score, reverse=True)[:limit]

    @staticmethod
    def _extract_memories(result: Any) -> list[Any]:
        if not result:
            return []
        if isinstance(result, list):
            return result
        if isinstance(result, dict):
            memories = result.get("memories")
            return memories if isinstance(memories, list) else []
        memories = getattr(result, "memories", None)
        return memories if isinstance(memories, list) else []

    @classmethod
    def _dedupe_memories(cls, memories: list[Any]) -> list[Any]:
        deduped: list[Any] = []
        seen_uris: set[str] = set()
        for memory in memories:
            uri = cls._get_uri(memory)
            if not uri or uri in seen_uris:
                continue
            seen_uris.add(uri)
            deduped.append(memory)
        return deduped

    @staticmethod
    def _memory_type_target(base_uri: str, memory_type: str) -> str:
        return f"{base_uri.rstrip('/')}/{memory_type.strip('/')}/"

    @staticmethod
    def _peer_id_from_memory_uri(uri: str) -> str | None:
        parts = [part for part in uri.strip("/").split("/") if part]
        for idx, part in enumerate(parts):
            if part == "peers" and idx + 1 < len(parts):
                return parts[idx + 1]
        return None

    @classmethod
    def _order_type_quota_memories(
        cls,
        memories: list[Any],
    ) -> list[Any]:
        groups: dict[str, list[Any]] = {}
        others: list[Any] = []
        for memory in memories:
            memory_type = cls._infer_memory_type(memory)
            if memory_type:
                groups.setdefault(memory_type, []).append(memory)
            else:
                others.append(memory)

        for group in groups.values():
            group.sort(key=cls._get_score, reverse=True)
        others.sort(key=cls._get_score, reverse=True)

        ordered: list[Any] = []
        for memory_type in _TYPE_QUOTA_MEMORY_TYPES:
            ordered.extend(groups.get(memory_type, []))
        ordered.extend(others)
        return cls._dedupe_memories(ordered)

    @classmethod
    def _select_type_quota_memories(
        cls,
        memories: list[Any],
        quotas: dict[str, int],
    ) -> list[Any]:
        memories = sorted(cls._dedupe_memories(memories), key=cls._get_score, reverse=True)
        selected: list[Any] = []
        for memory_type in _TYPE_QUOTA_MEMORY_TYPES:
            quota = max(0, int(quotas.get(memory_type, 0) or 0))
            if quota <= 0:
                continue
            type_memories = [
                memory for memory in memories if cls._infer_memory_type(memory) == memory_type
            ][:quota]
            selected.extend(
                cls._with_recall_metadata(memory, memory_type, rank)
                for rank, memory in enumerate(type_memories, start=1)
            )
        return cls._dedupe_memories(selected)

    @staticmethod
    def _type_quota_char_budgets(max_chars: int) -> dict[str, int]:
        max_chars = max(0, int(max_chars))
        event_budget = int(max_chars * _TYPE_QUOTA_EVENT_CHAR_RATIO)
        return {
            "events": event_budget,
            "entities": max_chars - event_budget,
        }

    @staticmethod
    def _format_memory_group(memory_type: str, memories: list[str]) -> str:
        description = _MEMORY_TYPE_DESCRIPTIONS.get(
            memory_type,
            "Other retrieved memories. Use them when relevant and inspect URI entries if needed.",
        )
        body = "\n".join(memories)
        return (
            f'<memory_group type="{memory_type}">\n'
            f"  <group_hint>{description}</group_hint>\n"
            f"{body}\n"
            f"</memory_group>"
        )

    @staticmethod
    def _format_full_memory(idx: int, uri: str, score: float, content: str) -> str:
        filename = MemoryStore._filename_from_uri(uri)
        return (
            f'<memory index="{idx}" type="full">\n'
            f"  <uri>{uri}</uri>\n"
            f"  <filename>{filename}</filename>\n"
            f"  <score>{score}</score>\n"
            f"  <content>{content}</content>\n"
            f"</memory>"
        )

    @staticmethod
    def _format_summary_memory(idx: int, uri: str, score: float, summary: str) -> str:
        filename = MemoryStore._filename_from_uri(uri)
        return (
            f'<memory index="{idx}" type="summary">\n'
            f"  <uri>{uri}</uri>\n"
            f"  <filename>{filename}</filename>\n"
            f"  <score>{score}</score>\n"
            f"  <summary>{summary}</summary>\n"
            f"</memory>"
        )

    @staticmethod
    def _format_uri_memory(idx: int, uri: str, score: float) -> str:
        filename = MemoryStore._filename_from_uri(uri)
        return (
            f'<memory index="{idx}" type="uri">\n'
            f"  <uri>{uri}</uri>\n"
            f"  <filename>{filename}</filename>\n"
            f"  <score>{score}</score>\n"
            f"</memory>"
        )

    @staticmethod
    def _extract_event_summary(content: str, fallback: str = "") -> str:
        if content:
            match = re.search(
                r"(?is)^\s*Summary:\s*(.*?)(?:\n\s*\d{4}-\d{2}-\d{2}"
                r"(?:\s*\([^)]+\))?\s*ChatLog:|\n\s*ChatLog:|\n\s*<!--\s*MEMORY_FIELDS|$)",
                content,
            )
            if match:
                return re.sub(r"\s+", " ", match.group(1)).strip()
        return fallback.strip()

    def read_long_term(self) -> str:
        if self.memory_file.exists():
            return self.memory_file.read_text(encoding="utf-8")
        return ""

    async def _parse_viking_memory(
        self,
        result: Any,
        client: Any,
        min_score: float = 0.3,
        max_chars: int = 4000,
        full_limit: int | None = None,
        type_char_budgets: dict[str, int] | None = None,
        preference_full_limit: int = 0,
        include_uri_entries: bool = True,
        read_content: Any | None = None,
    ) -> str:
        """Parse viking memory with score filtering and character limit.
        Automatically reads full content for memories that fit the relevant budget;
        memories beyond budget are kept as URI-only entries when include_uri_entries is true.

        Args:
            result: Memory search results
            client: VikingClient instance to read content
            min_score: Minimum score threshold (default: 0.4)
            max_chars: Maximum character limit for full memories in global mode
            full_limit: Number of top memories allowed to use full content in global mode
            type_char_budgets: Per-memory-type character budgets for type_quota recall
            preference_full_limit: Number of preference memories forced full in type_quota mode
            include_uri_entries: Whether to keep URI-only candidates after content budgets are exhausted

        Returns:
            Formatted memory string within character limit
        """
        if not result or len(result) == 0:
            return ""

        filtered_memories = [memory for memory in result if self._get_score(memory) >= min_score]
        use_type_budgets = bool(type_char_budgets) and any(
            self._infer_memory_type(memory) for memory in filtered_memories
        )
        if use_type_budgets:
            filtered_memories = self._order_type_quota_memories(filtered_memories)
        else:
            filtered_memories.sort(key=self._get_score, reverse=True)

        grouped_memories: dict[str, list[str]] = {}
        total_chars = 0
        type_chars = dict.fromkeys(_TYPE_QUOTA_MEMORY_TYPES, 0)
        preference_full_count = 0
        seen_content_hashes = set()
        full_limit = len(filtered_memories) if full_limit is None else max(0, full_limit)
        type_char_budgets = type_char_budgets or {}

        for idx, memory in enumerate(filtered_memories, start=1):
            uri = self._get_uri(memory)
            abstract = self._get_abstract(memory)
            score = self._get_score(memory)
            memory_type = self._infer_memory_type(memory) or "other"
            should_try_full = idx <= full_limit
            if use_type_budgets:
                should_try_full = (memory_type in type_char_budgets) or (
                    memory_type == "preferences"
                    and preference_full_count < max(0, preference_full_limit)
                )

            content = ""
            try:
                if read_content:
                    content = await read_content(uri, level="read")
                else:
                    content = await client.read_content(uri, level="read")
            except Exception as e:
                logger.warning(f"Failed to read content from {uri}: {e}")

            # Deduplicate by content hash (use content or abstract as key)
            content_to_hash = content or abstract or uri
            content_hash = hash(content_to_hash)
            if content_to_hash and content_hash in seen_content_hashes:
                continue
            if content_to_hash:
                seen_content_hashes.add(content_hash)

            if should_try_full and content:
                full_memory_str = self._format_full_memory(idx, uri, score, content)
                full_chars = len(full_memory_str)
                if any(grouped_memories.values()):
                    full_chars += 1

                if use_type_budgets and memory_type in type_char_budgets:
                    budget = max(0, int(type_char_budgets[memory_type]))
                    if (
                        type_chars[memory_type] + full_chars <= budget
                        and total_chars + full_chars <= max_chars
                    ):
                        grouped_memories.setdefault(memory_type, []).append(full_memory_str)
                        type_chars[memory_type] += full_chars
                        total_chars += full_chars
                        continue
                elif use_type_budgets and memory_type == "preferences":
                    preference_full_count += 1
                    if total_chars + full_chars <= max_chars:
                        grouped_memories.setdefault(memory_type, []).append(full_memory_str)
                        total_chars += full_chars
                        continue
                elif total_chars + full_chars <= max_chars:
                    grouped_memories.setdefault(memory_type, []).append(full_memory_str)
                    total_chars += full_chars
                    continue

            if use_type_budgets and memory_type == "events" and content:
                summary = self._extract_event_summary(content, fallback=abstract)
                if summary:
                    summary_memory_str = self._format_summary_memory(idx, uri, score, summary)
                    summary_chars = len(summary_memory_str) + bool(any(grouped_memories.values()))
                    if (
                        type_chars[memory_type] + summary_chars
                        <= max(0, int(type_char_budgets.get(memory_type, 0)))
                        and total_chars + summary_chars <= max_chars
                    ):
                        grouped_memories.setdefault(memory_type, []).append(summary_memory_str)
                        type_chars[memory_type] += summary_chars
                        total_chars += summary_chars
                        continue

            if include_uri_entries:
                grouped_memories.setdefault(memory_type, []).append(
                    self._format_uri_memory(idx, uri, score)
                )

        ordered_groups: list[str] = []
        for memory_type in (*_TYPE_QUOTA_MEMORY_TYPES, "other"):
            memories = grouped_memories.get(memory_type)
            if memories:
                ordered_groups.append(self._format_memory_group(memory_type, memories))
        for memory_type, memories in grouped_memories.items():
            if memory_type not in (*_TYPE_QUOTA_MEMORY_TYPES, "other") and memories:
                ordered_groups.append(self._format_memory_group(memory_type, memories))

        return "\n".join(ordered_groups)

    def write_long_term(self, content: str) -> None:
        self.memory_file.write_text(content, encoding="utf-8")

    def append_history(self, entry: str) -> None:
        with open(self.history_file, "a", encoding="utf-8") as f:
            f.write(entry.rstrip() + "\n\n")

    def get_memory_context(self) -> str:
        long_term = self.read_long_term()
        return f"## Long-term Memory\n{long_term}" if long_term else ""

    async def _search_viking_memory_by_type_quota(
        self,
        client: VikingClient,
        query: str,
        peer_ids: list[str] | None,
        quotas: dict[str, int],
    ) -> list[Any]:
        if getattr(client, "actor_peer_id", None):
            try:
                base_targets = [client._current_peer_memory_target_uri(client.actor_peer_id)]
            except ValueError:
                base_targets = []
        else:
            base_targets = client.build_current_memory_target_uris(
                peer_ids=peer_ids,
                include_self=not bool(peer_ids),
            )
        if not base_targets:
            return []

        all_memories: list[Any] = []
        for memory_type, quota in quotas.items():
            if quota <= 0:
                continue
            type_memories: list[Any] = []
            for base_target in base_targets:
                target_uri = self._memory_type_target(base_target, memory_type)
                try:
                    find_kwargs = {
                        "query": query,
                        "target_uri": target_uri,
                        "limit": quota,
                    }
                    if getattr(client, "actor_peer_id", None):
                        find_kwargs["context_type"] = "memory"
                    result = await client.find(**find_kwargs)
                except Exception as e:
                    logger.warning(f"Failed to search {target_uri}: {e}")
                    continue
                type_memories.extend(self._extract_memories(result))
            type_memories = self._limit_memories(self._dedupe_memories(type_memories), quota)
            all_memories.extend(
                self._with_recall_metadata(memory, memory_type, rank)
                for rank, memory in enumerate(type_memories, start=1)
            )

        return self._dedupe_memories(all_memories)

    async def _search_actor_peer_memories_by_type_quota(
        self,
        query: str,
        workspace_id: str,
        openviking_connection: dict[str, Any] | None,
        base_client: VikingClient,
        peer_ids: list[str],
        quotas: dict[str, int],
    ) -> list[Any]:
        current_actor_peer_id = getattr(base_client, "actor_peer_id", None)
        normalized_peer_ids = VikingClient._dedupe_strings(
            [
                normalized_peer_id
                for normalized_peer_id in (VikingClient._peer_id(peer_id) for peer_id in peer_ids)
                if normalized_peer_id
            ]
        )

        async def search_peer(normalized_peer_id: str) -> list[Any]:
            peer_client = base_client
            should_close = False
            if normalized_peer_id != current_actor_peer_id:
                peer_client = await VikingClient.create(
                    agent_id=workspace_id,
                    connection=openviking_connection,
                    actor_peer_id=normalized_peer_id,
                    config=self._get_config(),
                )
                should_close = True

            try:
                return await self._search_viking_memory_by_type_quota(
                    client=peer_client,
                    query=query,
                    peer_ids=[normalized_peer_id],
                    quotas=quotas,
                )
            finally:
                if should_close:
                    try:
                        await peer_client.close()
                    except Exception as e:
                        logger.warning(f"Error closing VikingClient: {e}")

        results = await asyncio.gather(
            *(search_peer(peer_id) for peer_id in normalized_peer_ids),
            return_exceptions=True,
        )
        all_memories: list[Any] = []
        for result in results:
            if isinstance(result, Exception):
                logger.warning(f"Failed to search actor peer memories: {result}")
                continue
            all_memories.extend(result)

        return self._select_type_quota_memories(all_memories, quotas)

    async def get_viking_memory_context(
        self,
        current_message: str,
        workspace_id: str,
        sender_id: str,
        peer_ids: list[str] | None = None,
        user_ids: list[str] | None = None,
        openviking_connection: dict[str, Any] | None = None,
    ) -> str:
        client = None
        read_clients: dict[str, VikingClient] = {}
        try:
            config = self._get_config()
            ov_cfg = config.ov_server
            admin_user_id = (
                str(openviking_connection.get("user_id"))
                if isinstance(openviking_connection, dict) and openviking_connection.get("user_id")
                else ov_cfg.admin_user_id
            )
            logger.info(f"workspace_id={workspace_id}")
            logger.info(f"sender_id={sender_id}")
            logger.info(f"peer_ids={peer_ids}")
            logger.info(f"user_ids={user_ids}")
            logger.info(f"admin_user_id={admin_user_id}")

            client = await VikingClient.create(
                agent_id=workspace_id,
                connection=openviking_connection,
                actor_peer_id=sender_id,
                config=config,
            )
            if sender_id:
                search_peer_ids = [sender_id, *(peer_ids or [])]
            else:
                search_peer_ids = peer_ids or None
            type_quotas = {
                "events": max(0, int(getattr(ov_cfg, "memory_recall_events_limit", 10))),
                "entities": max(0, int(getattr(ov_cfg, "memory_recall_entities_limit", 10))),
                "preferences": max(0, int(getattr(ov_cfg, "memory_recall_preferences_limit", 3))),
            }
            recall_max_chars = max(1, int(getattr(ov_cfg, "memory_recall_max_chars", 6500)))
            use_type_quota = not user_ids
            if use_type_quota:
                if getattr(client, "actor_peer_id", None):
                    result = await self._search_actor_peer_memories_by_type_quota(
                        query=current_message,
                        workspace_id=workspace_id,
                        openviking_connection=openviking_connection,
                        base_client=client,
                        peer_ids=search_peer_ids or [],
                        quotas=type_quotas,
                    )
                else:
                    result = await self._search_viking_memory_by_type_quota(
                        client=client,
                        query=current_message,
                        peer_ids=search_peer_ids,
                        quotas=type_quotas,
                    )
            else:
                result = await client.search_memory(
                    query=current_message,
                    user_ids=user_ids,
                    peer_ids=search_peer_ids,
                    limit=_LEGACY_MEMORY_RECALL_LIMIT + 5,
                )
            if not result:
                return ""
            result = [
                memory
                for memory in result
                if not self._get_uri(memory).rstrip("/").endswith("/profile.md")
            ]
            if not result:
                return ""
            if not use_type_quota:
                result = self._limit_memories(result, limit=_LEGACY_MEMORY_RECALL_LIMIT)

            async def read_memory_content(uri: str, level: str = "read") -> str:
                actor_peer_id = getattr(client, "actor_peer_id", None)
                memory_peer_id = self._peer_id_from_memory_uri(uri)
                if actor_peer_id and memory_peer_id and memory_peer_id != actor_peer_id:
                    peer_client = read_clients.get(memory_peer_id)
                    if not peer_client:
                        peer_client = await VikingClient.create(
                            agent_id=workspace_id,
                            connection=openviking_connection,
                            actor_peer_id=memory_peer_id,
                            config=config,
                        )
                        read_clients[memory_peer_id] = peer_client
                    return await peer_client.read_content(uri, level=level)
                return await client.read_content(uri, level=level)

            # Log raw search results for debugging
            recall_strategy = "type_quota" if use_type_quota else "global"
            memory_list = []
            memory_list.append(f"user_memory[{len(result)}],strategy={recall_strategy}:")

            for i, mem in enumerate(result):
                uri = self._get_uri(mem)
                score = self._get_score(mem)
                memory_list.append(f"{i},{uri},{score}")
            raw_memories_log = "\n".join(memory_list)
            logger.info(f"[RAW_MEMORIES]\n{raw_memories_log}")
            user_memory = await self._parse_viking_memory(
                result,
                client,
                min_score=0.1,
                max_chars=recall_max_chars,
                full_limit=0 if use_type_quota else None,
                type_char_budgets=(
                    self._type_quota_char_budgets(recall_max_chars) if use_type_quota else None
                ),
                preference_full_limit=(_TYPE_QUOTA_PREFERENCE_FULL_LIMIT if use_type_quota else 0),
                include_uri_entries=True,
                read_content=read_memory_content,
            )
            return f"### user memories:\n{user_memory}"
        except Exception as e:
            logger.error(f"[READ_USER_MEMORY]: search error. {e}")
            return ""
        finally:
            for read_client in read_clients.values():
                try:
                    await read_client.close()
                except Exception as e:
                    logger.warning(f"Error closing VikingClient: {e}")
            if client:
                try:
                    await client.close()
                except Exception as e:
                    logger.warning(f"Error closing VikingClient: {e}")

    async def get_viking_experience_context(
        self,
        query: str,
        workspace_id: str,
        openviking_connection: dict[str, Any] | None = None,
        case_lookup: dict[str, Any] | None = None,
    ) -> str:
        """用当前任务 query 检索 experience 记忆,注入到 system prompt。"""
        content, _ = await self.get_viking_experience_reminder(
            query=query,
            workspace_id=workspace_id,
            exclude_uris=None,
            openviking_connection=openviking_connection,
            case_lookup=case_lookup,
        )
        return content

    async def get_viking_experience_reminder(
        self,
        query: str,
        workspace_id: str,
        exclude_uris: list[str] | None = None,
        openviking_connection: dict[str, Any] | None = None,
        case_lookup: dict[str, Any] | None = None,
    ) -> tuple[str, list[str]]:
        """检索 experience 记忆并排除已召回过的 URI。

        Returns:
            (formatted_content, recalled_uris) — 格式化后的记忆块和实际命中的 URI 列表。
            无命中时返回 ("", [])。
        """
        if case_lookup:
            return await self._get_linked_case_experience_content(
                query=query,
                workspace_id=workspace_id,
                case_lookup=case_lookup,
                openviking_connection=openviking_connection,
                exclude_uris=exclude_uris,
            )
        client = None
        try:
            config = self._get_config()
            ov_cfg = config.ov_server
            client = await VikingClient.create(
                agent_id=workspace_id,
                connection=openviking_connection,
                config=config,
            )
            case_limit = max(0, int(getattr(ov_cfg, "case_recall_limit", 0) or 0))
            if case_lookup:
                cases = await self._find_cases_by_lookup(
                    client,
                    case_lookup,
                    limit=max(case_limit, 1),
                    fallback_query=query,
                )
                logger.info(
                    f"[READ_CASE_MEMORY]: exact lookup found {len(cases)} cases, "
                    f"lookup={case_lookup}, query={query[:50]}"
                )
            else:
                cases = await self._search_memory_type(
                    client,
                    query,
                    memory_type="cases",
                    limit=case_limit,
                )
                logger.info(f"[READ_CASE_MEMORY]: found {len(cases)} cases, query={query[:50]}")
            top_case = cases[:1]
            linked_experiences = await self._linked_experiences_from_cases(
                top_case,
                client,
                limit=0,
            )
            experiences = self._dedupe_memories(linked_experiences)
            logger.info(
                f"[READ_EXPERIENCE_MEMORY]: found {len(linked_experiences)} linked experiences "
                f"from top1 case, query={query[:50]}"
            )
            for i, case in enumerate(cases):
                uri = case.get("uri", "") if isinstance(case, dict) else getattr(case, "uri", "")
                score = (
                    case.get("score", 0) if isinstance(case, dict) else getattr(case, "score", 0)
                )
                logger.info(f"  case {i},{uri},{score}")
            for i, exp in enumerate(experiences):
                uri = exp.get("uri", "") if isinstance(exp, dict) else getattr(exp, "uri", "")
                score = exp.get("score", 0) if isinstance(exp, dict) else getattr(exp, "score", 0)
                logger.info(f"  {i},{uri},{score}")
            if not experiences:
                return "", []

            # 过滤掉已召回过的 URI。case 只作为路由入口,不注入上下文。
            if exclude_uris:
                exclude_set = set(exclude_uris)
                experiences = [exp for exp in experiences if self._get_uri(exp) not in exclude_set]
                logger.info(
                    f"[READ_EXPERIENCE_MEMORY]: after exclude {len(exclude_set)} uris, "
                    f"{len(experiences)} experiences remaining"
                )
                if not experiences:
                    return "", []

            recall_max_chars = max(1, int(ov_cfg.exp_recall_max_chars))
            content = await self._parse_viking_memory(
                experiences,
                client,
                min_score=0.0,
                max_chars=recall_max_chars,
                full_limit=len(experiences),
                include_uri_entries=False,
            )

            recalled_uris = [
                self._get_uri(exp) for exp in experiences if self._get_score(exp) >= 0.0
            ]

            return content, recalled_uris
        except Exception as e:
            logger.error(f"[READ_EXPERIENCE_MEMORY]: error. {e}")
            return "", []
        finally:
            if client:
                try:
                    await client.close()
                except Exception:
                    pass

    async def _get_linked_case_experience_content(
        self,
        *,
        query: str,
        workspace_id: str,
        case_lookup: dict[str, Any],
        openviking_connection: dict[str, Any] | None = None,
        exclude_uris: list[str] | None = None,
    ) -> tuple[str, list[str]]:
        client = None
        try:
            config = self._get_config()
            ov_cfg = config.ov_server
            client = await VikingClient.create(
                agent_id=workspace_id,
                connection=openviking_connection,
                config=config,
            )
            case_limit = max(1, int(getattr(ov_cfg, "case_recall_limit", 0) or 1))
            cases = await self._find_cases_by_lookup(
                client,
                case_lookup,
                limit=case_limit,
                fallback_query=query,
            )
            logger.info(
                f"[READ_TASK_CASE_EXP]: found {len(cases)} exact cases, "
                f"lookup={case_lookup}, query={query[:50]}"
            )
            linked_experiences = await self._linked_experiences_from_cases(
                cases[:1],
                client,
                limit=0,
            )
            experiences = self._dedupe_memories(linked_experiences)
            if exclude_uris:
                exclude_set = set(exclude_uris)
                experiences = [exp for exp in experiences if self._get_uri(exp) not in exclude_set]
            if not experiences:
                return "", []
            recall_max_chars = max(1, int(getattr(ov_cfg, "exp_recall_max_chars", 10000)))
            content = await self._parse_viking_memory(
                experiences,
                client,
                min_score=0.0,
                max_chars=recall_max_chars,
                full_limit=len(experiences),
                include_uri_entries=False,
            )
            recalled_uris = [
                self._get_uri(exp) for exp in experiences if self._get_score(exp) >= 0.0
            ]
            return content, recalled_uris
        except Exception as e:
            logger.error(f"[READ_TASK_CASE_EXP]: error. {e}")
            return "", []
        finally:
            if client:
                try:
                    await client.close()
                except Exception:
                    pass

    async def _find_cases_by_lookup(
        self,
        client: Any,
        case_lookup: dict[str, Any],
        *,
        limit: int,
        fallback_query: str,
    ) -> list[Any]:
        """Find the current task's case by exact structured identity.

        Tau2 passes task identity (domain/split/task_id/task_no) from the runner.
        We may use search only to enumerate candidates, but every returned case
        must pass an exact MEMORY_FIELDS/input match before its links are used.
        """
        lookup = self._normalize_case_lookup(case_lookup)
        if not lookup:
            return []

        target_uri = f"viking://user/{client.admin_user_id}/memories/cases/"
        matched = await self._read_exact_case_uri_candidates(
            client,
            lookup,
            base_uri=target_uri,
            limit=limit,
        )
        if matched:
            return matched
        if lookup.get("strict"):
            # Strict exact lookup is for benchmark/eval or other controlled
            # tasks where injecting a semantically similar but different case
            # is worse than recalling nothing.
            return []

        candidates: list[Any] = []
        seen: set[str] = set()
        for query_value in self._case_lookup_queries(lookup, fallback_query=fallback_query):
            remaining = max(1, int(limit or 1) * 5)
            try:
                result = await client.search(
                    query=query_value,
                    target_uri=target_uri,
                    limit=remaining,
                )
            except Exception as exc:
                logger.warning(f"[READ_CASE_MEMORY]: exact lookup candidate search error. {exc}")
                continue
            for memory in self._extract_memories(result):
                uri = self._get_uri(memory)
                if not uri or uri in seen:
                    continue
                seen.add(uri)
                candidates.append(memory)

        matched = []
        for case in candidates:
            uri = self._get_uri(case)
            if not uri:
                continue
            try:
                content = await client.read_content(uri, level="read")
            except Exception as exc:
                logger.warning(f"Failed to read case content from {uri}: {exc}")
                continue
            if not self._case_matches_lookup(content, lookup, uri=uri):
                continue
            matched.append(self._with_recall_metadata(case, "cases", len(matched) + 1))
            if len(matched) >= max(1, int(limit or 1)):
                break
        return matched

    async def _read_exact_case_uri_candidates(
        self,
        client: Any,
        lookup: dict[str, str],
        *,
        base_uri: str,
        limit: int,
    ) -> list[Any]:
        matched: list[Any] = []
        for uri in self._case_uri_candidates(base_uri, lookup):
            try:
                content = await client.read_content(uri, level="read")
            except Exception as exc:
                logger.warning(f"Failed to read exact case content from {uri}: {exc}")
                continue
            if not content or not self._case_matches_lookup(content, lookup, uri=uri):
                continue
            matched.append(
                {
                    "uri": uri,
                    "score": 1.0,
                    "abstract": "",
                    "_recall_type": "cases",
                    "_recall_rank": len(matched) + 1,
                    "_matched_by": "exact_case_uri",
                }
            )
            if len(matched) >= max(1, int(limit or 1)):
                break
        return matched

    @classmethod
    def _case_uri_candidates(cls, base_uri: str, lookup: dict[str, Any]) -> list[str]:
        names: list[str] = []
        for value in lookup.get("case_names") or []:
            if value:
                names.append(str(value))
        for key in ("case_name", "original_case_name"):
            value = lookup.get(key)
            if value:
                names.append(str(value))
        data_split = lookup.get("data_split")
        task_no = lookup.get("task_no")
        if data_split and task_no:
            names.append(f"tau2_{data_split}_{task_no}")
        uris: list[str] = []
        for name in names:
            filename = cls._safe_case_filename(name)
            if not filename:
                continue
            uri = f"{base_uri.rstrip('/')}/{filename}"
            if uri not in uris:
                uris.append(uri)
        return uris

    @staticmethod
    def _safe_case_filename(name: str) -> str:
        value = str(name or "").strip().strip("/")
        if not value or "/" in value or "\\" in value:
            return ""
        return value if value.endswith(".md") else f"{value}.md"

    @staticmethod
    def _normalize_case_lookup(case_lookup: dict[str, Any] | None) -> dict[str, Any]:
        if not isinstance(case_lookup, dict):
            return {}
        normalized: dict[str, Any] = {}
        for key in (
            "benchmark",
            "domain",
            "split",
            "data_split",
            "task_id",
            "task_no",
            "case_name",
            "task_signature",
            "original_case_name",
        ):
            value = case_lookup.get(key)
            if value is None:
                continue
            value_str = str(value).strip()
            if value_str:
                normalized[key] = value_str

        case_names = case_lookup.get("case_names")
        if isinstance(case_names, (list, tuple)):
            normalized["case_names"] = [
                str(value).strip()
                for value in case_names
                if value is not None and str(value).strip()
            ]

        expected_fields = case_lookup.get("expected_fields")
        if isinstance(expected_fields, dict):
            normalized["expected_fields"] = {
                str(key).strip(): str(value).strip()
                for key, value in expected_fields.items()
                if str(key).strip() and value is not None
            }

        if "strict" in case_lookup:
            normalized["strict"] = bool(case_lookup.get("strict"))
        elif "allow_query_fallback" in case_lookup:
            normalized["strict"] = not bool(case_lookup.get("allow_query_fallback"))
        else:
            normalized["strict"] = False
        return normalized

    @classmethod
    def _case_lookup_queries(cls, lookup: dict[str, Any], *, fallback_query: str) -> list[str]:
        queries: list[str] = []
        for value in lookup.get("case_names") or []:
            if value:
                queries.append(str(value))
        for key in ("case_name", "original_case_name", "task_signature"):
            value = lookup.get(key)
            if value:
                queries.append(str(value))
        domain = lookup.get("domain")
        split = lookup.get("split")
        task_id = lookup.get("task_id")
        task_no = lookup.get("task_no")
        data_split = lookup.get("data_split") or (f"{domain}_{split}" if domain and split else "")
        if domain and split and task_id:
            queries.append(f"{domain}:{split}:{task_id}")
        if data_split and task_no:
            queries.append(f"{data_split}_{task_no}")
        if data_split and task_id:
            queries.append(f"{data_split} task_id {task_id}")
        if fallback_query:
            queries.append(fallback_query)

        deduped: list[str] = []
        for query in queries:
            query = str(query or "").strip()
            if query and query not in deduped:
                deduped.append(query)
        return deduped

    @classmethod
    def _case_matches_lookup(
        cls, raw_content: str, lookup: dict[str, Any], *, uri: str = ""
    ) -> bool:
        try:
            from openviking.session.memory.utils.memory_file_utils import MemoryFileUtils

            memory_file = MemoryFileUtils.read(raw_content or "", uri=uri or None)
        except Exception:
            return False

        fields = dict(memory_file.extra_fields or {})
        if not fields:
            fields = cls._case_fields_from_markdown(memory_file.content or raw_content, uri=uri)
        case_input = cls._parse_json_object(fields.get("input"))
        case_name = str(fields.get("case_name") or cls._filename_from_uri(uri).removesuffix(".md"))
        task_signature = str(fields.get("task_signature") or "")

        accepted_names = [str(value) for value in lookup.get("case_names") or [] if value]
        if lookup.get("case_name"):
            accepted_names.append(str(lookup["case_name"]))
        if lookup.get("original_case_name"):
            accepted_names.append(str(lookup["original_case_name"]))
        case_names = {case_name, cls._filename_from_uri(uri).removesuffix(".md")}
        if accepted_names and not case_names.intersection(accepted_names):
            return False
        if lookup.get("task_signature") and str(lookup["task_signature"]) != task_signature:
            return False

        expected_fields = dict(lookup.get("expected_fields") or {})
        if not expected_fields:
            for key in ("domain", "task_id", "split", "data_split", "task_no"):
                expected = lookup.get(key)
                if expected:
                    expected_fields[f"input.{key}"] = expected

        document = {"fields": fields, "input": case_input}
        for path, expected in expected_fields.items():
            actual = cls._get_dotted_value(document, str(path))
            if str(actual if actual is not None else "").strip() != str(expected).strip():
                return False
        return True

    @staticmethod
    def _get_dotted_value(document: dict[str, Any], path: str) -> Any:
        current: Any = document
        for part in str(path or "").split("."):
            if not part:
                continue
            if isinstance(current, dict) and part in current:
                current = current[part]
            else:
                return None
        return current

    @staticmethod
    def _parse_json_object(value: Any) -> dict[str, Any]:
        if isinstance(value, dict):
            return value
        if not isinstance(value, str) or not value.strip():
            return {}
        try:
            parsed = json.loads(value)
        except Exception:
            return {}
        return parsed if isinstance(parsed, dict) else {}

    async def _linked_experiences_from_cases(
        self,
        cases: list[Any],
        client: Any,
        *,
        limit: int,
    ) -> list[Any]:
        """Read direct case -> experience links from the visible case markdown."""
        if not cases:
            return []
        max_links = int(limit or 0)

        linked: list[Any] = []
        seen: set[str] = set()
        for case in cases:
            case_uri = self._get_uri(case)
            if not case_uri:
                continue
            try:
                content = await client.read_content(case_uri, level="read")
            except Exception as exc:
                logger.warning(f"Failed to read case content from {case_uri}: {exc}")
                continue
            for exp_uri in self._extract_linked_experience_uris(content, source_uri=case_uri):
                if exp_uri in seen:
                    continue
                seen.add(exp_uri)
                linked.append(
                    {
                        "uri": exp_uri,
                        "score": self._get_score(case),
                        "abstract": "",
                        "_recall_type": "experiences",
                        "_recall_rank": len(linked) + 1,
                        "_linked_from_case_uri": case_uri,
                    }
                )
                if max_links > 0 and len(linked) >= max_links:
                    return linked
        return linked

    @classmethod
    def _case_fields_from_markdown(cls, content: str, *, uri: str = "") -> dict[str, str]:
        fields = {"case_name": cls._filename_from_uri(uri).removesuffix(".md")}
        title = re.search(r"(?m)^#\s+(.+?)\s*$", content or "")
        if title:
            fields["case_name"] = title.group(1).strip()
        for field, heading in (
            ("task_signature", "Task Signature"),
            ("input", "Input"),
            ("rubric", "Rubric"),
            ("evidence", "Evidence"),
        ):
            value = cls._markdown_section(content, heading)
            if value:
                fields[field] = value
        return fields

    @staticmethod
    def _markdown_section(content: str, heading: str) -> str:
        match = re.search(
            rf"(?ims)^##\s+{re.escape(heading)}\s*\n(.*?)(?=^##\s+|\Z)",
            content or "",
        )
        return match.group(1).strip() if match else ""

    @classmethod
    def _extract_linked_experience_uris(cls, content: str, *, source_uri: str = "") -> list[str]:
        section = cls._markdown_section(content, "Linked Experiences")
        if not section:
            return []

        targets = re.findall(r"\[[^\]]+\]\(([^)\s]+)\)", section)
        if not targets:
            targets = [
                line.lstrip("- ").strip()
                for line in section.splitlines()
                if line.strip().startswith("- ")
            ]

        uris: list[str] = []
        for target in targets:
            uri = cls._resolve_case_link_uri(target, source_uri=source_uri)
            if "/memories/experiences/" in uri and uri not in uris:
                uris.append(uri)
        return uris

    @staticmethod
    def _resolve_case_link_uri(target: str, *, source_uri: str) -> str:
        import posixpath

        target = str(target or "").strip()
        if not target:
            return ""
        if "://" in target:
            return target
        if "/" not in target:
            target = f"../experiences/{target.removesuffix('.md')}.md"
        if not source_uri.startswith("viking://"):
            return target
        source_dir = source_uri.removeprefix("viking://").rsplit("/", 1)[0]
        return "viking://" + posixpath.normpath(f"{source_dir}/{target}")

    async def _search_memory_type(
        self,
        client: Any,
        query: str,
        *,
        memory_type: str,
        limit: int,
    ) -> list[Any]:
        if limit <= 0:
            return []
        try:
            target_uri = f"viking://user/{client.admin_user_id}/memories/{memory_type}/"
            result = await client.search(query=query, target_uri=target_uri, limit=limit)
        except Exception as e:
            logger.warning(f"[READ_{memory_type.upper()}_MEMORY]: error. {e}")
            return []
        memories = result.get("memories", []) if isinstance(result, dict) else []
        return [
            self._with_recall_metadata(memory, memory_type, rank)
            for rank, memory in enumerate(memories, start=1)
        ]

    async def get_viking_peer_profile(
        self,
        workspace_id: str,
        peer_id: str | None,
        openviking_connection: dict[str, Any] | None = None,
        actor_peer_id: str | None = None,
    ) -> str:
        if not peer_id:
            return ""

        client = None
        try:
            client = await VikingClient.create(
                agent_id=workspace_id,
                connection=openviking_connection,
                actor_peer_id=actor_peer_id or peer_id,
                config=self._get_config(),
            )
            result = await client.read_peer_profile(peer_id)
            return result or ""
        except Exception as e:
            logger.error(f"[READ_PEER_PROFILE]: peer_id={peer_id}, error. {e}")
            return ""
        finally:
            if client:
                try:
                    await client.close()
                except Exception as e:
                    logger.warning(f"Error closing VikingClient: {e}")

    async def get_viking_peer_profiles(
        self,
        workspace_id: str,
        peer_ids: list[str],
        openviking_connection: dict[str, Any] | None = None,
        use_peer_actor_scope: bool = False,
    ) -> str:
        if not peer_ids:
            return ""

        client = None
        try:
            if not use_peer_actor_scope:
                client = await VikingClient.create(
                    agent_id=workspace_id,
                    connection=openviking_connection,
                    config=self._get_config(),
                )

            async def fetch_profile(peer_id: str) -> tuple[str, str]:
                peer_client = client
                should_close = False
                try:
                    if use_peer_actor_scope:
                        peer_client = await VikingClient.create(
                            agent_id=workspace_id,
                            connection=openviking_connection,
                            actor_peer_id=peer_id,
                            config=self._get_config(),
                        )
                        should_close = True
                    start_time = time.time()
                    profile = await peer_client.read_peer_profile(peer_id)
                    cost = round(time.time() - start_time, 2)
                    logger.info(
                        f"[READ_PEER_PROFILE]: peer_id={peer_id}, cost {cost}s, "
                        f"profile={profile[:50] if profile else 'None'}"
                    )
                    return (peer_id, profile or "")
                except Exception as e:
                    logger.error(f"[READ_PEER_PROFILE]: peer_id={peer_id}, error. {e}")
                    return (peer_id, "")
                finally:
                    if should_close and peer_client:
                        try:
                            await peer_client.close()
                        except Exception as e:
                            logger.warning(f"Error closing VikingClient: {e}")

            tasks = [fetch_profile(peer_id) for peer_id in peer_ids]
            results = await asyncio.gather(*tasks, return_exceptions=True)

            parts = []
            for result in results:
                if isinstance(result, Exception):
                    continue
                peer_id, profile = result
                if profile:
                    parts.append(f"## Peer profile for {peer_id}: \n{profile}")

            return "\n\n".join(parts) if parts else ""
        except Exception as e:
            logger.error(f"[READ_PEER_PROFILES]: error. {e}")
            return ""
        finally:
            if client:
                try:
                    await client.close()
                except Exception as e:
                    logger.warning(f"Error closing VikingClient: {e}")