Skip to content
Python
30.4 KB
Raw Blame
"""
Agent Memory V2 - VectorStore 抽象基类

定义向量存储层的统一接口(Provider 模式),允许切换不同的向量数据库后端。

当前支持:
- Chroma   (嵌入式, 默认, 零外部依赖)
- Qdrant   (嵌入式 / 远程)
- FAISS    (嵌入式, CPU)

存储的 payload 结构:
  - node_id: str
  - isolation_key: str (user_id::agent_id::session_id)
  - user_id / agent_id / session_id: str
  - layer: str
  - content: str                  (核心语义,embed 只用此字段)
  - status: str
  - confidence: float
  - memory_at / temporal_anchor / gmt_created / gmt_modified: str (ISO) | None
  - valid_from / valid_until: str (ISO) | None
  - supersedes: List[str] | None  (取代的旧节点 ID 列表)
  - superseded_by: List[str] | None (被哪些新节点取代)
  - is_latest: bool               (是否链条末端,默认 True,加 payload index)
  - speculate: str | None         (推断注解,不参与 embed)
  - source_raw_memory_id: str | None (L3_SUMMARY 锚点)
  - emotional_valence / emotional_arousal: float
  - meta_tags: List[str]
  - source_session_id: str
"""

from abc import ABC, abstractmethod
import asyncio
from typing import Optional, List, Dict, Any
import logging
import uuid

from ..models.memory import (
    MemoryNode, MemoryLayer, MemoryStatus,
    MetaCognitionTag,
)
from ..config import MemoryConfig


# ================================================================
# 时间过滤:事件时间(memory_at)优先,缺失时回退写入时间(gmt_created)
# ================================================================
#
# `created_after` 的语义是**记忆描述的事件发生在该时间之后**,因此必须按
# `memory_at`(事件时间,调用方可指定)过滤,而不是 `gmt_created`(落库时间)。
#
# 早期实现按 gmt_created 过滤,在批量灌入场景下等于没有过滤 —— 一次导入进来的
# 全部记忆 gmt_created 几乎同一时刻,无论 memory_at 跨越多长时间跨度都会一起命中。
#
# 回退规则:`memory_at` 为空时回退 `gmt_created`。writer 两个入口都保证
# memory_at 有值,但 L0_BASIC_INFO(`agent/tools/basic_profile.py`)等旁路写入
# 以及 owner 字段引入前的历史数据可能为空;回退保证这些节点的行为与改动前一致,
# 不会因为换了字段而被静默过滤掉。

def node_effective_time(payload: Dict[str, Any]) -> Optional[float]:
    """取 payload 的有效时间戳:memory_at 优先,回退 gmt_created;都没有返回 None。

    兼容 Chroma —— 它不支持 None,`_payload_to_chroma_metadata` 把空值写成 `""`。
    """
    for key in ("memory_at", "gmt_created"):
        v = payload.get(key)
        if v is None or v == "":
            continue
        try:
            return float(v)
        except (TypeError, ValueError):
            continue
    return None


def passes_created_after(
    payload: Dict[str, Any], created_after: Optional[float]
) -> bool:
    """post-filter 版时间过滤(Chroma / FAISS 用,它们的过滤 DSL 表达不了 null 判断)。

    两个时间字段都缺失时返回 True —— 宁可多召回,也不因为缺字段丢数据。
    """
    if not created_after:
        return True
    t = node_effective_time(payload)
    if t is None:
        return True
    return t >= float(created_after)

logger = logging.getLogger(__name__)


def physical_collection_name(base_name: Optional[str], dims: Optional[int]) -> str:
    """The collection name a store opens for ``base_name`` at ``dims``.

    The dims suffix keeps two embedding widths from sharing one collection.
    `hy_memory.reembed.vector_space_names` uses this too, so callers never
    re-derive the rule.
    """
    base = base_name or "agent_memories"
    return f"{base}_{dims}" if dims else base


class VectorStoreBase(ABC):
    """
    向量存储抽象基类

    所有向量数据库后端必须实现此接口。
    """

    def __init__(self, config: MemoryConfig):
        self.config = config
        # 自动拼接维度后缀,避免不同 embedding 模型写入同一 collection 导致维度冲突
        self._collection_name = physical_collection_name(
            config.vector_store.collection_name, config.vector_store.embedding_dims,
        )

    _supports_retrieval_clauses: bool = False
    _supports_narrow_episode_queries: bool = False

    # ================================================================
    # 生命周期
    # ================================================================

    @abstractmethod
    async def initialize(self) -> None:
        """初始化向量数据库连接,确保集合/索引存在"""
        ...

    @abstractmethod
    async def close(self) -> None:
        """关闭连接,释放资源"""
        ...

    # ================================================================
    # 写入
    # ================================================================

    @abstractmethod
    async def upsert(self, node: MemoryNode) -> str:
        """
        写入或更新一个 MemoryNode 的向量和 payload。

        Args:
            node: 需要有 node.embedding 已赋值

        Returns:
            node_id (str)
        """
        ...

    @abstractmethod
    async def upsert_batch(self, nodes: List[MemoryNode]) -> List[str]:
        """批量写入"""
        ...

    @abstractmethod
    async def update_embedding(self, node_id: str, embedding: List[float]) -> bool:
        """仅更新向量(payload 不变)"""
        ...

    @abstractmethod
    async def update_payload(self, node_id: str, updates: Dict[str, Any]) -> bool:
        """
        仅更新 payload 字段(向量不变)
        
        Args:
            node_id: 节点 ID
            updates: 要更新的字段和值,如 {"status": "shadow"}
            
        Returns:
            是否成功
        """
        ...

    # ================================================================
    # 检索
    # ================================================================

    @abstractmethod
    async def search(
        self,
        query_embedding: List[float],
        isolation_key: str = "",
        isolation_keys: Optional[List[str]] = None,
        user_id: Optional[str] = None,
        user_ids: Optional[List[str]] = None,
        agent_ids: Optional[List[str]] = None,
        include_sources: Optional[List[str]] = None,
        exclude_sources: Optional[List[str]] = None,
        layers: Optional[List[MemoryLayer]] = None,
        limit: int = 10,
        score_threshold: float = 0.0,
        status_filter: Optional[List[MemoryStatus]] = None,
        only_latest: bool = True,
        tags_match_any: Optional[List[str]] = None,
        created_after: Optional[float] = None,
    ) -> List[Dict[str, Any]]:
        """
        语义检索

        支持三种过滤模式(优先级从高到低):
        1. 精确 keys: isolation_keys 非空 → IN 过滤
        2. 单 key: isolation_key 非空 → 精确匹配(向后兼容)
        3. user 级 / agent 级: user_ids/user_id + 可选 agent_ids → 字段组合过滤

        Args:
            query_embedding: 查询向量
            isolation_key: 单个隔离键(向后兼容)
            isolation_keys: 多个隔离键(精确匹配模式)
            user_id: 单个用户 ID(向后兼容)
            user_ids: 多个用户 ID(跨用户搜索)
            agent_ids: Agent ID 列表(与 user_id/user_ids 配合使用)
            include_sources: 调用来源白名单,在底层 top-k 前过滤
            exclude_sources: 调用来源黑名单,在底层 top-k 前过滤;优先级更高
            layers: 可选,限定搜索层级
            created_after: 可选,Unix timestamp (float),只返回 gmt_created >= 此值的记忆
            limit: 返回数量
            score_threshold: 最低分数阈值
            status_filter: 可选,状态过滤 (默认只返回 ACTIVE)
            tags_match_any: 可选,仅返回 tags 字段与该列表有交集的记忆
                            (兼容底层存储能力,reader 可不使用)

        Returns:
            [{"node_id": ..., "score": ..., "node": MemoryNode}, ...]
        """
        ...

    @abstractmethod
    async def get_by_id(self, node_id: str) -> Optional[MemoryNode]:
        """按 ID 获取"""
        ...

    async def search_batch(
        self, requests: List[Dict[str, Any]],
    ) -> List[List[Dict[str, Any]]]:
        """Execute independent semantic searches as one logical batch.

        Backends with a native batch endpoint should override this method.  The
        fallback deliberately preserves each request's exact arguments and
        ordering, so callers can adopt batching without changing retrieval
        semantics on older or non-Qdrant stores.
        """
        if not requests:
            return []
        return list(await asyncio.gather(
            *(self.search(**dict(request)) for request in requests),
        ))

    async def get_by_ids(self, node_ids: List[str]) -> List[MemoryNode]:
        """
        批量按 ID 获取(默认实现:串行调用 get_by_id)。
        后端可覆盖此方法以使用批量 API 提升效率。
        """
        results = []
        for node_id in node_ids:
            node = await self.get_by_id(node_id)
            if node is not None:
                results.append(node)
        return results

    async def list_by_episode(
        self,
        episode_ids: List[str],
        *,
        user_id: Optional[str] = None,
        agent_id: Optional[str] = None,
        layers: Optional[List[MemoryLayer]] = None,
        limit: int = 200,
        include_sources: Optional[List[str]] = None,
        exclude_sources: Optional[List[str]] = None,
    ) -> List[MemoryNode]:
        """按 episode_id 框出同一次讨论的记忆。

        Episode 是 SDK 内部按写入时间间隔切出的"一次讨论"(见 `MemoryNode.episode_id`)。
        读侧用它把同一件事的记忆一次性框成候选,比建 O(n²) 时间边便宜得多。

        默认实现:`list_by_user` + 本地过滤。后端可 override 成下推过滤
        (Qdrant / Chroma / FAISS 的 payload 是动态的,加过滤条件零迁移)。
        """
        wanted = {e for e in (episode_ids or []) if e}
        if not wanted:
            return []
        nodes = await self.list_by_user(
            user_id=user_id, agent_id=agent_id, layers=layers,
            limit=max(limit * 10, 1000), with_vectors=False,
            include_sources=include_sources,
            exclude_sources=exclude_sources,
        )
        out = [
            n for n in (nodes or [])
            if (getattr(n, "episode_id", "") or "") in wanted
        ]
        return out[:limit]

    async def list_by_session(
        self,
        *,
        user_id: str,
        agent_id: Optional[str],
        session_id: str,
        limit: int = 10000,
        status_filter: Optional[List] = None,
        layers: Optional[List[MemoryLayer]] = None,
        only_latest: bool = False,
        with_vectors: bool = False,
        allow_raw_layer: bool = False,
    ) -> List[MemoryNode]:
        """List one session; remote stores should override with pushed filters."""
        nodes = await self.list_by_user(
            user_id=user_id,
            agent_id=agent_id,
            limit=limit,
            status_filter=status_filter,
            layers=layers,
            only_latest=only_latest,
            with_vectors=with_vectors,
            allow_raw_layer=allow_raw_layer,
        )
        wanted = session_id or "default_session"
        return [
            node for node in nodes
            if (getattr(node, "session_id", "") or "default_session") == wanted
        ][:limit]

    async def list_by_source_raw_ids(
        self,
        source_raw_ids: List[str],
        *,
        user_id: str,
        agent_id: Optional[str],
        limit: int = 10000,
        status_filter: Optional[List] = None,
        layers: Optional[List[MemoryLayer]] = None,
        only_latest: bool = False,
        with_vectors: bool = False,
    ) -> List[MemoryNode]:
        """List nodes whose direct or accumulated provenance references raw IDs."""
        wanted = {str(value) for value in source_raw_ids if value}
        if not wanted:
            return []
        nodes = await self.list_by_user(
            user_id=user_id,
            agent_id=agent_id,
            limit=limit,
            status_filter=status_filter,
            layers=layers,
            only_latest=only_latest,
            with_vectors=with_vectors,
        )
        out = []
        for node in nodes:
            direct = getattr(node, "source_raw_memory_id", "") or ""
            accumulated = (getattr(node, "custom", None) or {}).get(
                "source_raw_memory_ids", []
            )
            if direct in wanted or wanted.intersection(str(v) for v in accumulated or []):
                out.append(node)
        return out[:limit]

    async def get_embeddings(self, node_ids: List[str]) -> Dict[str, List[float]]:
        """
        批量取节点向量(用于去重时本地算 pairwise cosine,不调 embedding API)。

        默认实现复用 get_by_ids 并读 node.embedding;后端若 get_by_id 默认不返回
        向量(如 qdrant 批量版、tencent),必须 override 以确保拿到向量。

        Returns:
            {node_id: embedding},取不到向量的 node_id 不出现在返回里。
        """
        out: Dict[str, List[float]] = {}
        nodes = await self.get_by_ids(node_ids)
        for n in nodes:
            emb = getattr(n, "embedding", None)
            if emb:
                out[n.node_id] = list(emb)
        return out

    # ================================================================
    # 删除
    # ================================================================

    @abstractmethod
    async def delete(self, node_id: str) -> bool:
        """删除单个向量点"""
        ...

    @abstractmethod
    async def delete_by_isolation_key(self, isolation_key: str) -> int:
        """删除某隔离键下的所有向量"""
        ...

    @abstractmethod
    async def delete_by_metadata(
        self,
        user_id: str,
        agent_id: Optional[str] = None,
        session_id: Optional[str] = None,
    ) -> int:
        """
        按 metadata 字段组合删除向量(与 search 同一过滤思路)。

        粒度:
        - 仅 user_id          → 删除该用户所有记忆
        - user_id + agent_id   → 删除该用户指定 agent 下所有记忆
        - user_id + agent_id + session_id → 删除精确 session 的记忆

        Returns:
            删除的向量数量(后端不支持精确计数时返回 -1)
        """
        ...

    # ================================================================
    # 枚举
    # ================================================================

    @abstractmethod
    async def list_by_user(
        self,
        user_id: Optional[str] = None,
        agent_id: Optional[str] = None,
        limit: int = 10000,
        status_filter: Optional[List] = None,
        layers: Optional[List[MemoryLayer]] = None,
        user_ids: Optional[List[str]] = None,
        agent_ids: Optional[List[str]] = None,
        include_sources: Optional[List[str]] = None,
        exclude_sources: Optional[List[str]] = None,
        only_latest: bool = False,
        with_vectors: bool = True,
        allow_raw_layer: bool = False,
    ) -> List[MemoryNode]:
        """
        枚举用户的记忆节点。

        Args:
            user_id: 用户 ID(单值)。与 user_ids 互斥,二者必须提供其一
            agent_id: 可选,限定某个 agent(单值)
            limit: 最大返回数量
            status_filter: 可选,只返回指定状态的节点(如 [MemoryStatus.ACTIVE])。
                不传则**不限定状态**,返回含 SUPERSEDED / SHADOW 在内的全部节点
            layers: 可选,只返回指定层级的节点(如 [MemoryLayer.L2_FACT])
            user_ids: 可选,多用户批量枚举。提供时优先于 user_id
            agent_ids: 可选,多 agent 批量枚举。提供时优先于 agent_id
            only_latest: 是否只返回演化链末端(is_latest=True)。
                **默认 False**,即返回链上全部版本。clone 等全量复制场景依赖该默认值,
                改动前务必确认调用方不需要历史版本
            with_vectors: 是否返回 embedding。只需要 payload/tags 时应传 False,避免拉取大向量。
            allow_raw_layer: 是否允许返回 L1_RAW 原始对话层。**默认 False**:
                对外读路径一律不返回原始对话。仅内部管线(writer 拼多轮对话历史)
                需要时显式置 True。
        """
        ...

    # ================================================================
    # 统计
    # ================================================================

    @abstractmethod
    async def get_stats(self) -> Dict[str, Any]:
        """获取集合统计"""
        ...

    @abstractmethod
    async def count(self, isolation_key: str) -> int:
        """统计某隔离键下的向量数量"""
        ...

    # ================================================================
    # Tag Index (per-user tag embedding) —— 供 reader_hybrid_tag 路 B 使用
    # ================================================================
    #
    # 设计:
    #   - 独立 collection(命名由 `_retrieval.config.tag_index_collection_name`
    #     负责),与主 memories collection 隔离
    #   - point_id 由 uuid5(user_id + ":" + tag) 生成,保证幂等 upsert
    #   - payload: {user_id, tag}
    #   - 只有 Qdrant 后端首版实现;其他后端继承默认实现(抛 NotImplementedError)
    #     reader_hybrid_tag 在 init 时探测能力,不支持则自动降级到 hybrid 行为
    #
    # 非必需的后端可以:
    #   - 不实现(默认抛 NotImplementedError)
    #   - 或覆盖 `_supports_tag_index = True` 并提供全部 5 个方法

    _supports_tag_index: bool = False

    async def upsert_tag_embedding(
        self, user_id: str, tag: str, embedding: List[float]
    ) -> None:
        """写入 (user_id, tag) 的 embedding。幂等:同 (user_id, tag) 永远落同一 point。"""
        raise NotImplementedError("tag_index not supported by this backend")

    async def has_tag_embedding(self, user_id: str, tag: str) -> bool:
        """判断 (user_id, tag) 是否已在 tag_index 中。"""
        raise NotImplementedError("tag_index not supported by this backend")

    async def delete_tag_embedding(self, user_id: str, tag: str) -> None:
        """删除 (user_id, tag) 的 embedding。不存在是幂等的 no-op。"""
        raise NotImplementedError("tag_index not supported by this backend")

    async def search_tag_embeddings(
        self,
        user_id: str,
        query_embedding: List[float],
        topk: int = 5,
        min_score: float = 0.5,
    ) -> List[Dict[str, Any]]:
        """
        在指定 user 的 tag_index 中做向量检索,返回 [{"tag": ..., "score": ...}, ...]。
        按 score 降序。分数低于 min_score 的被过滤。
        """
        raise NotImplementedError("tag_index not supported by this backend")

    async def replace_retrieval_clauses(
        self, parent: MemoryNode, clauses: List[str], embeddings: List[List[float]],
    ) -> int:
        """Replace hidden search aliases for one visible parent memory."""
        return 0

    async def delete_retrieval_clauses(self, parent_id: str) -> int:
        """Delete all hidden search aliases belonging to one parent memory."""
        return 0

    async def delete_retrieval_clauses_by_metadata(
        self,
        *,
        user_id: str,
        agent_id: Optional[str] = None,
        session_id: Optional[str] = None,
    ) -> int:
        """Delete hidden aliases for the same scope as delete_all()."""
        return 0

    async def search_retrieval_clauses(
        self,
        *,
        query_embedding: List[float],
        user_id: str,
        agent_ids: Optional[List[str]] = None,
        top_k: int = 20,
        min_score: float = 0.0,
    ) -> List[Dict[str, Any]]:
        """Search hidden aliases, returning parent_id/score pairs."""
        return []

    async def count_memories_with_tag(
        self, user_id: str, tag: str, isolation_key: str = ""
    ) -> int:
        """
        统计主 memories collection 中 tags 字段含指定 tag 且属于该 user(可选
        带 isolation_key)的记忆数量。用于删除 memory 时判断 tag 是否还可保留。
        """
        raise NotImplementedError("tag_index not supported by this backend")

    # ================================================================
    # Entity Store(对齐 mem0 的 {collection}_entities 独立 collection)
    #   - entity 节点 payload: {data, entity_type, linked_memory_ids, user_id, agent_id}
    #   - upsert: 同 user 下 entity 文本向量相似度 >= 0.95 视为同一 entity,
    #     合并 linked_memory_ids;否则新建。
    #   - 默认 NotImplementedError;目前仅 chroma 实现(实验用)。
    # ================================================================

    async def upsert_entity(
        self,
        *,
        entity_text: str,
        entity_type: str,
        embedding: List[float],
        memory_id: str,
        user_id: str,
        agent_id: str = "",
        merge_threshold: float = 0.95,
    ) -> str:
        """把一个 entity 写入 entity store 并关联到 memory_id。

        若同 user 下已存在相似 entity(cosine >= merge_threshold),把 memory_id
        并入其 linked_memory_ids;否则新建一条 entity 记录。返回 entity_id。
        """
        raise NotImplementedError("entity store not supported by this backend")

    async def search_entities(
        self,
        *,
        query_embedding: List[float],
        user_id: str,
        agent_ids: Optional[List[str]] = None,
        top_k: int = 500,
        min_score: float = 0.0,
    ) -> List[Dict[str, Any]]:
        """在指定 user 的 entity store 中做向量检索。

        返回 [{"entity_id", "data", "entity_type", "linked_memory_ids", "score"}, ...],
        按 score 降序。
        """
        raise NotImplementedError("entity store not supported by this backend")

    async def list_entities(
        self, *, user_id: str, agent_ids: Optional[List[str]] = None, top_k: int = 10000
    ) -> List[Dict[str, Any]]:
        """列出指定 user 的全部 entity 记录(用于迁移/清理/统计)。"""
        raise NotImplementedError("entity store not supported by this backend")

    async def delete_entities_for_memory(
        self, *, memory_id: str, user_id: str, agent_ids: Optional[List[str]] = None
    ) -> int:
        """从所有 entity 的 linked_memory_ids 中剔除 memory_id;空链则删除该 entity。

        返回受影响的 entity 数。memory 删除时调用。
        """
        raise NotImplementedError("entity store not supported by this backend")

    # ================================================================
    # Keyword Search (Full-text / BM25)
    # ================================================================

    # keyword_search 返回的 score 是否已是 [0,1] 归一化的相关性分。
    #   - True:reader 直接使用,不再过 normalize_bm25 sigmoid
    #     (tencent sparse IP 分 ~0.x、qdrant/未来 binary 命中分 1.0 等,
    #      本身已在 [0,1],再套为"经典 BM25 原始分 0~20"标定的 sigmoid 会被压成 ~0)
    #   - False(默认):返回的是经典 BM25 原始分(量级 0~20+),reader 端用
    #     normalize_bm25(midpoint, steepness) 做 sigmoid 归一化
    _keyword_score_normalized: bool = False

    @property
    def keyword_score_normalized(self) -> bool:
        return self._keyword_score_normalized

    async def keyword_search(
        self,
        query: str,
        top_k: int = 10,
        user_id: Optional[str] = None,
        agent_ids: Optional[List[str]] = None,
        layers: Optional[List[MemoryLayer]] = None,
        status_filter: Optional[List[MemoryStatus]] = None,
        only_latest: bool = True,
        isolation_key: str = "",
        isolation_keys: Optional[List[str]] = None,
        include_sources: Optional[List[str]] = None,
        exclude_sources: Optional[List[str]] = None,
    ) -> List[Dict[str, Any]]:
        """
        Full-text keyword search via payload text index.

        Returns results in the same format as search():
            [{"node_id": ..., "score": ..., "node": MemoryNode}, ...]

        Backend implementations should use their native full-text search
        capabilities. Default implementation returns empty (no-op fallback).
        """
        return []

    async def keyword_search_batch(
        self, requests: List[Dict[str, Any]],
    ) -> List[List[Dict[str, Any]]]:
        """Execute independent keyword searches as one logical batch.

        The default is behaviorally identical to calling ``keyword_search``
        for every request.  Native backends may collapse the transport calls.
        """
        if not requests:
            return []
        return list(await asyncio.gather(
            *(self.keyword_search(**dict(request)) for request in requests),
        ))

    # ================================================================
    # 通用工具方法(所有后端共用)
    # ================================================================

    @staticmethod
    def _node_id_to_point_id(node_id: str) -> str:
        """
        将 node_id 转换为确定性的 UUID 格式 point_id。

        如果 node_id 本身是 UUID 格式则直接使用,否则生成确定性 UUID。
        """
        try:
            uuid.UUID(node_id)
            return node_id
        except ValueError:
            return str(uuid.uuid5(uuid.NAMESPACE_URL, node_id))

    @staticmethod
    def _tag_point_id(user_id: str, tag: str) -> str:
        """
        tag_index 专用的确定性 point_id。
        同 (user_id, tag) 永远生成同一 UUID,upsert 天然幂等。
        """
        return str(uuid.uuid5(uuid.NAMESPACE_URL, f"tag_index::{user_id}::{tag}"))

    @staticmethod
    def _build_search_text(content: Any, tags: Any = None) -> str:
        """Build the canonical lexical-index text for a memory payload.

        Keep this in one place so an in-place payload UPDATE can rebuild the
        same text that an UPSERT would have produced.  Otherwise ``content``
        and ``tags`` can change while Qdrant's text/sparse indexes continue to
        describe the old memory.
        """
        # search_text: content + tags 拼接,过 lemmatize_for_bm25 (jieba 中文 + spaCy 英文)
        # 后再写入。配合 Qdrant whitespace tokenizer,让查询/索引两侧统一用 jieba 分词,
        # 修复中文 keyword search 全零问题。
        # 注意:lemmatize 只作用于 search_text(倒排索引专用),content 字段保持原文不动,
        # 用户搜索返回的 memory.content 不受影响。
        from ..pipelines._retrieval.lemmatize import lemmatize_for_bm25
        if isinstance(tags, str):
            tag_values = [tags]
        else:
            tag_values = list(tags or [])
        tags_text = " ".join(str(tag) for tag in tag_values if tag)
        content_text = str(content or "")
        raw_search_text = (
            f"{content_text} {tags_text}".strip()
            if tags_text else content_text
        )
        return lemmatize_for_bm25(raw_search_text) if raw_search_text else ""

    @staticmethod
    def _node_to_payload(node: MemoryNode) -> Dict[str, Any]:
        """将 MemoryNode 转换为通用 payload 字典(所有后端共用相同结构)"""
        search_text = VectorStoreBase._build_search_text(node.content, node.tags)

        return {
            "node_id": node.node_id,
            "isolation_key": node.get_isolation_key(),
            "user_id": node.user_id,
            "agent_id": node.agent_id,
            "session_id": node.session_id,
            "source": node.source,
            # Episode(内部会话):读侧用它框出同一次讨论的候选。payload 是动态的,
            # Qdrant / Chroma / FAISS 加字段零迁移。
            "episode_id": getattr(node, "episode_id", "") or "",
            "owner": node.owner,
            "layer": node.layer.value,
            "content": node.content,
            "search_text": search_text,
            "status": node.status.value,
            "confidence": node.confidence,
            "source_type": node.source_type.value,
            "emotional_valence": node.emotional_valence,
            "emotional_arousal": node.emotional_arousal,
            "specificity_score": node.specificity_score,
            "rarity_score": node.rarity_score,
            "longtail_flag": node.longtail_flag,
            "meta_tags": [t.value for t in node.meta_tags],
            "source_session_id": node.source_session_id,
            "memory_at": int(node.memory_at.timestamp()) if node.memory_at else None,
            "temporal_anchor": node.temporal_anchor,
            "gmt_created": int(node.gmt_created.timestamp()) if node.gmt_created else None,
            "gmt_modified": int(node.gmt_modified.timestamp()) if node.gmt_modified else None,
            "valid_from": int(node.valid_from.timestamp()) if node.valid_from else None,
            "valid_until": int(node.valid_until.timestamp()) if node.valid_until else None,
            "access_count": node.access_count,
            "last_accessed_at": int(node.last_accessed_at.timestamp()) if node.last_accessed_at else None,
            # 演化图谱
            "supersedes": node.supersedes,
            "superseded_by": node.superseded_by,
            "is_latest": node.is_latest,
            # 推断注解(payload-only,不参与 embed)
            "speculate": node.speculate,
            # 主题标签(payload-only,reconcile 用作软提示)
            "tags": list(node.tags or []),
            # 与 tags 等长的 NER label;主题词为空串
            "tag_ners": list(getattr(node, "tag_ners", None) or []),
            # Summary 锚点
            "source_raw_memory_id": node.source_raw_memory_id,
            # 自定义扩展字段(tool 用此字段存结构化 KV,例如 basic_info_kv)
            "custom": dict(node.custom or {}),
        }

    @staticmethod
    def _payload_to_node(payload: Dict[str, Any]) -> MemoryNode:
        """从 payload 字典重建 MemoryNode"""
        return MemoryNode.from_dict(payload)