from abc import ABC, abstractmethod
from typing import Any, Dict, List, Optional


class BaseMemory(ABC):
    """Abstract base for all memory backends."""

    @abstractmethod
    async def store(self, key: str, value: Any, metadata: Optional[Dict] = None) -> None:
        """Persist a value under a key."""

    @abstractmethod
    async def retrieve(self, key: str) -> Optional[Any]:
        """Fetch a value by exact key."""

    @abstractmethod
    async def search(self, query: str, k: int = 5) -> List[Dict[str, Any]]:
        """Semantic or keyword search; return top-k results with scores."""

    @abstractmethod
    async def delete(self, key: str) -> None:
        """Remove a key from memory."""

    @abstractmethod
    async def clear(self, scope: Optional[str] = None) -> None:
        """Clear memory, optionally scoped to a job/session."""