"""记忆存储后端抽象。

低锁定设计:上层 MemoryStream 只依赖这个接口,换 mem0 / 本地 / 其他向量库
只改注入的实现,不动调用方(契合 mem0 低锁定特性,见调研)。
"""

from __future__ import annotations

from abc import ABC, abstractmethod
from dataclasses import dataclass

from genesis.memory.record import MemoryRecord


@dataclass
class SearchHit:
    record: MemoryRecord
    relevance: float  # 语义相关度 [0,1]


class MemoryStore(ABC):
    @abstractmethod
    def add(self, record: MemoryRecord) -> str:
        """写入一条记忆,返回其存储 id。"""

    @abstractmethod
    def search(self, query: str, agent_id: str, limit: int = 20) -> list[SearchHit]:
        """按语义相关度检索某 agent 的记忆候选(不含 recency/importance 加权)。"""

    @abstractmethod
    def all(self, agent_id: str) -> list[MemoryRecord]:
        """返回某 agent 的全部记忆。"""