cortexdbai 0.2.0__py3-none-any.whl

cortexdb/client.py

@@ -0,0 +1,962 @@
+"""Synchronous and asynchronous HTTP clients for the CortexDB API.
+
+Usage (sync)::
+
+    with Cortex() as client:
+        resp = client.remember("The deploy succeeded at 14:32 UTC.")
+        results = client.recall("What happened with the deploy?")
+
+Usage (async)::
+
+    async with AsyncCortex() as client:
+        resp = await client.remember("The deploy succeeded at 14:32 UTC.")
+        results = await client.recall("What happened with the deploy?")
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Any
+
+import httpx
+from tenacity import (
+    retry,
+    retry_if_exception,
+    stop_after_attempt,
+    wait_exponential,
+)
+
+from cortexdb.exceptions import (
+    CortexAPIError,
+    CortexAuthError,
+    CortexConnectionError,
+    CortexRateLimitError,
+    CortexTimeoutError,
+)
+from cortexdb.models import (
+    EntityResponse,
+    ForgetResponse,
+    HealthResponse,
+    IngestEpisodeRequest,
+    IngestEpisodeResponse,
+    LinkResponse,
+    ListEpisodesResponse,
+    MetricsResponse,
+    RecallResponse,
+    RememberResponse,
+    SearchResponse,
+)
+
+_DEFAULT_BASE_URL = "https://api.cortexdb.ai"
+_RETRYABLE_STATUS_CODES = {429, 502, 503, 504}
+
+
+def _is_retryable(exc: BaseException) -> bool:
+    """Return True if the exception warrants a retry."""
+    if isinstance(exc, CortexRateLimitError):
+        return True
+    if isinstance(exc, CortexAPIError) and exc.status_code in _RETRYABLE_STATUS_CODES:
+        return True
+    if isinstance(exc, CortexConnectionError):
+        return True
+    return False
+
+
+def _raise_for_status(response: httpx.Response) -> None:
+    """Translate an HTTP error response into the appropriate CortexDB exception."""
+    if response.is_success:
+        return
+
+    status = response.status_code
+    try:
+        body = response.json()
+    except Exception:
+        body = {}
+
+    message = body.get("message") or body.get("error") or response.reason_phrase or "Unknown error"
+    error_code = body.get("error_code") or body.get("code")
+
+    if status == 429:
+        retry_after_raw = response.headers.get("Retry-After")
+        retry_after: float | None = None
+        if retry_after_raw is not None:
+            try:
+                retry_after = float(retry_after_raw)
+            except (ValueError, TypeError):
+                pass
+        raise CortexRateLimitError(
+            message=message,
+            status_code=status,
+            error_code=error_code,
+            retry_after=retry_after,
+        )
+
+    if status in (401, 403):
+        raise CortexAuthError(message=message, status_code=status, error_code=error_code)
+
+    if status >= 400:
+        raise CortexAPIError(message=message, status_code=status, error_code=error_code)
+
+
+def _build_headers(api_key: str | None) -> dict[str, str]:
+    headers: dict[str, str] = {
+        "User-Agent": "cortexdb-python/0.2.0",
+        "Accept": "application/json",
+    }
+    if api_key:
+        headers["Authorization"] = f"Bearer {api_key}"
+    return headers
+
+
+# ---------------------------------------------------------------------------
+# Synchronous client
+# ---------------------------------------------------------------------------
+
+
+class Cortex:
+    """Synchronous client for the CortexDB HTTP API.
+
+    Args:
+        base_url: Root URL of the CortexDB server (default ``https://api.cortexdb.ai``).
+        api_key: Bearer token for authentication. Falls back to the
+            ``CORTEXDB_API_KEY`` environment variable when *None*.
+        timeout: Request timeout in seconds.
+        max_retries: Maximum number of retry attempts for transient failures.
+    """
+
+    def __init__(
+        self,
+        base_url: str = _DEFAULT_BASE_URL,
+        api_key: str | None = None,
+        timeout: float = 30.0,
+        max_retries: int = 3,
+    ) -> None:
+        self._base_url = base_url.rstrip("/")
+        self._api_key = api_key or os.environ.get("CORTEXDB_API_KEY")
+        self._max_retries = max_retries
+        self._client = httpx.Client(
+            base_url=self._base_url,
+            headers=_build_headers(self._api_key),
+            timeout=timeout,
+        )
+
+    # -- context manager -----------------------------------------------------
+
+    def __enter__(self) -> Cortex:
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()
+
+    def close(self) -> None:
+        """Close the underlying HTTP connection pool."""
+        self._client.close()
+
+    # -- public API ----------------------------------------------------------
+
+    def remember(
+        self,
+        content: str,
+        tenant_id: str = "default",
+        scope: str | None = None,
+        metadata: dict[str, Any] | None = None,
+    ) -> RememberResponse:
+        """Store a piece of information in CortexDB.
+
+        Args:
+            content: The text content to remember.
+            tenant_id: Tenant namespace.
+            scope: Optional scope qualifier.
+            metadata: Arbitrary key-value metadata to attach.
+
+        Returns:
+            A ``RememberResponse`` with the ID assigned by the server.
+        """
+        payload: dict[str, Any] = {"content": content, "tenant_id": tenant_id}
+        if scope is not None:
+            payload["scope"] = scope
+        if metadata is not None:
+            payload["metadata"] = metadata
+        data = self._request("POST", "/v1/remember", json=payload)
+        return RememberResponse.model_validate(data)
+
+    def recall(
+        self,
+        query: str,
+        tenant_id: str = "default",
+        max_tokens: int = 4096,
+        min_confidence: float = 0.0,
+    ) -> RecallResponse:
+        """Retrieve relevant memories matching a query.
+
+        Args:
+            query: Natural-language query.
+            tenant_id: Tenant namespace.
+            max_tokens: Maximum token budget for the response.
+            min_confidence: Minimum confidence threshold for matches.
+
+        Returns:
+            A ``RecallResponse`` containing ranked matches.
+        """
+        payload: dict[str, Any] = {
+            "query": query,
+            "tenant_id": tenant_id,
+        }
+        data = self._request("POST", "/v1/recall", json=payload)
+        return RecallResponse.model_validate(data)
+
+    def forget(
+        self,
+        query: str | None = None,
+        reason: str = "",
+        tenant_id: str = "default",
+    ) -> ForgetResponse:
+        """Delete memories matching a query.
+
+        Args:
+            query: Pattern or identifier of memories to delete. When *None*,
+                the server determines the scope.
+            reason: Human-readable justification for the deletion.
+            tenant_id: Tenant namespace.
+
+        Returns:
+            A ``ForgetResponse`` indicating how many records were deleted.
+        """
+        payload: dict[str, Any] = {"reason": reason, "tenant_id": tenant_id}
+        if query is not None:
+            payload["query"] = query
+        data = self._request("POST", "/v1/forget", json=payload)
+        return ForgetResponse.model_validate(data)
+
+    def ingest_episode(self, episode: IngestEpisodeRequest) -> IngestEpisodeResponse:
+        """Ingest a structured episode into CortexDB.
+
+        Args:
+            episode: The episode to ingest.
+
+        Returns:
+            An ``IngestEpisodeResponse`` with the episode ID and status.
+        """
+        payload = episode.model_dump(
+            by_alias=False, exclude_none=True, exclude={"tenant_id"}
+        )
+        data = self._request("POST", "/v1/episodes", json=payload)
+        return IngestEpisodeResponse.model_validate(data)
+
+    def list_episodes(
+        self,
+        tenant_id: str = "default",
+        offset: int = 0,
+        limit: int = 50,
+        **kwargs: Any,
+    ) -> ListEpisodesResponse:
+        """List episodes with optional filtering.
+
+        Args:
+            tenant_id: Tenant namespace.
+            offset: Pagination offset.
+            limit: Maximum number of episodes to return.
+            **kwargs: Additional query parameters forwarded to the API
+                (e.g. ``type``, ``actor_id``).
+
+        Returns:
+            A ``ListEpisodesResponse`` with the episode list and pagination info.
+        """
+        params: dict[str, Any] = {
+            "tenant_id": tenant_id,
+            "offset": offset,
+            "limit": limit,
+            **kwargs,
+        }
+        data = self._request("GET", "/v1/episodes", params=params)
+        return ListEpisodesResponse.model_validate(data)
+
+    def health(self) -> HealthResponse:
+        """Check server health.
+
+        Returns:
+            A ``HealthResponse`` with the server's status and version.
+        """
+        data = self._request("GET", "/v1/admin/health")
+        return HealthResponse.model_validate(data)
+
+    def metrics(self) -> MetricsResponse:
+        """Retrieve server metrics.
+
+        Returns:
+            A ``MetricsResponse`` with episode counts and storage usage.
+        """
+        data = self._request("GET", "/v1/admin/metrics")
+        return MetricsResponse.model_validate(data)
+
+    def entity(self, entity_id: str, tenant_id: str = "default") -> EntityResponse:
+        """Get detailed information about a specific entity.
+
+        Returns entity metadata, relationships, and recent episodes.
+
+        Args:
+            entity_id: The entity ID to look up.
+            tenant_id: Tenant namespace.
+
+        Returns:
+            An ``EntityResponse`` with entity details, relationships, and episodes.
+        """
+        data = self._request(
+            "GET",
+            f"/v1/entities/{entity_id}",
+            headers={"x-tenant-id": tenant_id},
+        )
+        return EntityResponse.model_validate(data)
+
+    def link(
+        self,
+        source_entity_id: str,
+        target_entity_id: str,
+        relationship: str,
+        fact: str = "",
+        confidence: float = 0.9,
+        tenant_id: str = "default",
+    ) -> LinkResponse:
+        """Create an explicit relationship between two entities.
+
+        Args:
+            source_entity_id: ID of the source entity.
+            target_entity_id: ID of the target entity.
+            relationship: Relationship type (e.g., ``"DEPENDS_ON"``, ``"OWNS"``).
+            fact: Human-readable description of the relationship.
+            confidence: Confidence score (0.0 to 1.0).
+            tenant_id: Tenant namespace.
+
+        Returns:
+            A ``LinkResponse`` with the created edge ID.
+        """
+        payload = {
+            "source_entity_id": source_entity_id,
+            "target_entity_id": target_entity_id,
+            "relationship": relationship,
+            "fact": fact,
+            "confidence": confidence,
+        }
+        data = self._request(
+            "POST",
+            "/v1/link",
+            json=payload,
+            headers={"x-tenant-id": tenant_id},
+        )
+        return LinkResponse.model_validate(data)
+
+    def search(
+        self,
+        query: str,
+        source: str | None = None,
+        episode_type: str | None = None,
+        time_range: str | None = None,
+        namespace: str | None = None,
+        limit: int = 20,
+        offset: int = 0,
+        tenant_id: str = "default",
+    ) -> SearchResponse:
+        """Search across memories and episodes with filters.
+
+        Unlike :meth:`recall`, this returns both context and matching episodes.
+
+        Args:
+            query: Natural-language search query.
+            source: Filter by source connector (e.g., ``"slack"``, ``"github"``).
+            episode_type: Filter by episode type (e.g., ``"message"``, ``"incident"``).
+            time_range: Time range filter (e.g., ``"1h"``, ``"24h"``, ``"7d"``, ``"30d"``).
+            namespace: Filter by namespace.
+            limit: Maximum results to return.
+            offset: Pagination offset.
+            tenant_id: Tenant namespace.
+
+        Returns:
+            A ``SearchResponse`` with context, episodes, and metadata.
+        """
+        payload: dict[str, Any] = {"query": query, "limit": limit, "offset": offset}
+        filters: dict[str, str] = {}
+        if source:
+            filters["source"] = source
+        if episode_type:
+            filters["episode_type"] = episode_type
+        if time_range:
+            filters["time_range"] = time_range
+        if namespace:
+            filters["namespace"] = namespace
+        if filters:
+            payload["filters"] = filters
+        data = self._request(
+            "POST",
+            "/v1/search",
+            json=payload,
+            headers={"x-tenant-id": tenant_id},
+        )
+        return SearchResponse.model_validate(data)
+
+    # -- GTM convenience methods ---------------------------------------------
+
+    def memory(
+        self,
+        query: str,
+        tenant_id: str = "default",
+        **kwargs: Any,
+    ) -> RecallResponse:
+        """Recall memories with a single natural-language query.
+
+        This is the GTM one-liner::
+
+            cortex.memory("why did checkout fail yesterday")
+
+        It is an alias for :meth:`recall` with the same parameter semantics.
+
+        Args:
+            query: Natural-language query.
+            tenant_id: Tenant namespace.
+            **kwargs: Additional keyword arguments forwarded to :meth:`recall`
+                (e.g. ``max_tokens``, ``min_confidence``).
+
+        Returns:
+            A ``RecallResponse`` containing ranked matches.
+        """
+        return self.recall(query=query, tenant_id=tenant_id, **kwargs)
+
+    def store(
+        self,
+        data: str | dict[str, Any],
+        tenant_id: str = "default",
+        **kwargs: Any,
+    ) -> RememberResponse | IngestEpisodeResponse:
+        """Smart store that accepts a string or a dict.
+
+        Usage::
+
+            cortex.store("The deploy succeeded at 14:32 UTC.")
+            cortex.store({"content": "deploy ok", "type": "event", "source": "ci"})
+
+        When *data* is a **string**, it delegates to :meth:`remember`.
+        When *data* is a **dict**, it converts it via
+        :meth:`IngestEpisodeRequest.from_dict` and delegates to
+        :meth:`ingest_episode`.
+
+        Args:
+            data: Either a plain string (stored via ``remember``) or a dict
+                describing a structured episode (stored via ``ingest_episode``).
+            tenant_id: Tenant namespace (used for both code paths).
+            **kwargs: Extra keyword arguments forwarded to ``remember`` when
+                *data* is a string.
+
+        Returns:
+            A ``RememberResponse`` (string path) or
+            ``IngestEpisodeResponse`` (dict path).
+
+        Raises:
+            TypeError: If *data* is neither a string nor a dict.
+        """
+        if isinstance(data, str):
+            return self.remember(content=data, tenant_id=tenant_id, **kwargs)
+
+        if isinstance(data, dict):
+            data.setdefault("tenant_id", tenant_id)
+            episode = IngestEpisodeRequest.from_dict(data)
+            return self.ingest_episode(episode)
+
+        raise TypeError(
+            f"store() expects a str or dict, got {type(data).__name__}"
+        )
+
+    def context(
+        self,
+        query: str,
+        agent_id: str = "default",
+        tenant_id: str = "default",
+        max_tokens: int = 8192,
+    ) -> RecallResponse:
+        """Retrieve enriched context for an LLM agent.
+
+        Designed for feeding context windows to autonomous agents. Uses a
+        higher default token budget than :meth:`recall`.
+
+        Usage::
+
+            cortex.context(agent_id="incident-bot", query="current status of payments")
+
+        Args:
+            query: Natural-language query describing what context is needed.
+            agent_id: Identifier of the requesting agent (reserved for
+                future per-agent retrieval policies).
+            tenant_id: Tenant namespace.
+            max_tokens: Maximum token budget for the response (default 8192).
+
+        Returns:
+            A ``RecallResponse`` containing ranked matches.
+        """
+        return self.recall(
+            query=query,
+            tenant_id=tenant_id,
+            max_tokens=max_tokens,
+        )
+
+    # -- internal ------------------------------------------------------------
+
+    def _request(self, method: str, path: str, **kwargs: Any) -> Any:
+        """Execute an HTTP request with retry logic.
+
+        Retries on 429, 502, 503, and 504 responses using exponential
+        backoff. On 429 responses the ``Retry-After`` header is respected.
+
+        Returns:
+            Decoded JSON response body.
+
+        Raises:
+            CortexAPIError: On non-retryable HTTP errors.
+            CortexConnectionError: When the server is unreachable.
+            CortexTimeoutError: When the request exceeds the configured timeout.
+        """
+
+        @retry(
+            retry=retry_if_exception(_is_retryable),
+            stop=stop_after_attempt(self._max_retries),
+            wait=wait_exponential(multiplier=0.5, min=0.5, max=10),
+            reraise=True,
+        )
+        def _do() -> Any:
+            try:
+                response = self._client.request(method, path, **kwargs)
+            except httpx.TimeoutException as exc:
+                raise CortexTimeoutError(str(exc)) from exc
+            except httpx.ConnectError as exc:
+                raise CortexConnectionError(str(exc)) from exc
+            except httpx.HTTPError as exc:
+                raise CortexConnectionError(str(exc)) from exc
+
+            _raise_for_status(response)
+
+            if response.status_code == 204:
+                return {}
+            return response.json()
+
+        return _do()
+
+
+# ---------------------------------------------------------------------------
+# Asynchronous client
+# ---------------------------------------------------------------------------
+
+
+class AsyncCortex:
+    """Asynchronous client for the CortexDB HTTP API.
+
+    Provides the same interface as :class:`Cortex` but all network methods are
+    coroutines suitable for use with ``asyncio``.
+
+    Args:
+        base_url: Root URL of the CortexDB server (default ``https://api.cortexdb.ai``).
+        api_key: Bearer token for authentication. Falls back to the
+            ``CORTEXDB_API_KEY`` environment variable when *None*.
+        timeout: Request timeout in seconds.
+        max_retries: Maximum number of retry attempts for transient failures.
+    """
+
+    def __init__(
+        self,
+        base_url: str = _DEFAULT_BASE_URL,
+        api_key: str | None = None,
+        timeout: float = 30.0,
+        max_retries: int = 3,
+    ) -> None:
+        self._base_url = base_url.rstrip("/")
+        self._api_key = api_key or os.environ.get("CORTEXDB_API_KEY")
+        self._max_retries = max_retries
+        self._client = httpx.AsyncClient(
+            base_url=self._base_url,
+            headers=_build_headers(self._api_key),
+            timeout=timeout,
+        )
+
+    # -- context manager -----------------------------------------------------
+
+    async def __aenter__(self) -> AsyncCortex:
+        return self
+
+    async def __aexit__(self, *exc: object) -> None:
+        await self.close()
+
+    async def close(self) -> None:
+        """Close the underlying HTTP connection pool."""
+        await self._client.aclose()
+
+    # -- public API ----------------------------------------------------------
+
+    async def remember(
+        self,
+        content: str,
+        tenant_id: str = "default",
+        scope: str | None = None,
+        metadata: dict[str, Any] | None = None,
+    ) -> RememberResponse:
+        """Store a piece of information in CortexDB.
+
+        Args:
+            content: The text content to remember.
+            tenant_id: Tenant namespace.
+            scope: Optional scope qualifier.
+            metadata: Arbitrary key-value metadata to attach.
+
+        Returns:
+            A ``RememberResponse`` with the ID assigned by the server.
+        """
+        payload: dict[str, Any] = {"content": content, "tenant_id": tenant_id}
+        if scope is not None:
+            payload["scope"] = scope
+        if metadata is not None:
+            payload["metadata"] = metadata
+        data = await self._request("POST", "/v1/remember", json=payload)
+        return RememberResponse.model_validate(data)
+
+    async def recall(
+        self,
+        query: str,
+        tenant_id: str = "default",
+    ) -> RecallResponse:
+        """Retrieve relevant memories matching a query.
+
+        Args:
+            query: Natural-language query.
+            tenant_id: Tenant namespace.
+
+        Returns:
+            A ``RecallResponse`` with context and confidence.
+        """
+        payload: dict[str, Any] = {
+            "query": query,
+            "tenant_id": tenant_id,
+        }
+        data = await self._request("POST", "/v1/recall", json=payload)
+        return RecallResponse.model_validate(data)
+
+    async def forget(
+        self,
+        query: str | None = None,
+        reason: str = "",
+        tenant_id: str = "default",
+    ) -> ForgetResponse:
+        """Delete memories matching a query.
+
+        Args:
+            query: Pattern or identifier of memories to delete.
+            reason: Human-readable justification for the deletion.
+            tenant_id: Tenant namespace.
+
+        Returns:
+            A ``ForgetResponse`` indicating how many records were forgotten.
+        """
+        payload: dict[str, Any] = {"reason": reason, "tenant_id": tenant_id}
+        if query is not None:
+            payload["query"] = query
+        data = await self._request("POST", "/v1/forget", json=payload)
+        return ForgetResponse.model_validate(data)
+
+    async def ingest_episode(self, episode: IngestEpisodeRequest) -> IngestEpisodeResponse:
+        """Ingest a structured episode into CortexDB.
+
+        Args:
+            episode: The episode to ingest.
+
+        Returns:
+            An ``IngestEpisodeResponse`` with the episode ID and status.
+        """
+        payload = episode.model_dump(
+            by_alias=False, exclude_none=True, exclude={"tenant_id"}
+        )
+        data = await self._request("POST", "/v1/episodes", json=payload)
+        return IngestEpisodeResponse.model_validate(data)
+
+    async def list_episodes(
+        self,
+        tenant_id: str = "default",
+        offset: int = 0,
+        limit: int = 50,
+        **kwargs: Any,
+    ) -> ListEpisodesResponse:
+        """List episodes with optional filtering.
+
+        Args:
+            tenant_id: Tenant namespace.
+            offset: Pagination offset.
+            limit: Maximum number of episodes to return.
+            **kwargs: Additional query parameters forwarded to the API.
+
+        Returns:
+            A ``ListEpisodesResponse`` with the episode list and pagination info.
+        """
+        params: dict[str, Any] = {
+            "tenant_id": tenant_id,
+            "offset": offset,
+            "limit": limit,
+            **kwargs,
+        }
+        data = await self._request("GET", "/v1/episodes", params=params)
+        return ListEpisodesResponse.model_validate(data)
+
+    async def health(self) -> HealthResponse:
+        """Check server health.
+
+        Returns:
+            A ``HealthResponse`` with the server's status and version.
+        """
+        data = await self._request("GET", "/v1/admin/health")
+        return HealthResponse.model_validate(data)
+
+    async def metrics(self) -> MetricsResponse:
+        """Retrieve server metrics.
+
+        Returns:
+            A ``MetricsResponse`` with episode counts and storage usage.
+        """
+        data = await self._request("GET", "/v1/admin/metrics")
+        return MetricsResponse.model_validate(data)
+
+    async def entity(self, entity_id: str, tenant_id: str = "default") -> EntityResponse:
+        """Get detailed information about a specific entity.
+
+        Returns entity metadata, relationships, and recent episodes.
+
+        Args:
+            entity_id: The entity ID to look up.
+            tenant_id: Tenant namespace.
+
+        Returns:
+            An ``EntityResponse`` with entity details, relationships, and episodes.
+        """
+        data = await self._request(
+            "GET",
+            f"/v1/entities/{entity_id}",
+            headers={"x-tenant-id": tenant_id},
+        )
+        return EntityResponse.model_validate(data)
+
+    async def link(
+        self,
+        source_entity_id: str,
+        target_entity_id: str,
+        relationship: str,
+        fact: str = "",
+        confidence: float = 0.9,
+        tenant_id: str = "default",
+    ) -> LinkResponse:
+        """Create an explicit relationship between two entities.
+
+        Args:
+            source_entity_id: ID of the source entity.
+            target_entity_id: ID of the target entity.
+            relationship: Relationship type (e.g., ``"DEPENDS_ON"``, ``"OWNS"``).
+            fact: Human-readable description of the relationship.
+            confidence: Confidence score (0.0 to 1.0).
+            tenant_id: Tenant namespace.
+
+        Returns:
+            A ``LinkResponse`` with the created edge ID.
+        """
+        payload = {
+            "source_entity_id": source_entity_id,
+            "target_entity_id": target_entity_id,
+            "relationship": relationship,
+            "fact": fact,
+            "confidence": confidence,
+        }
+        data = await self._request(
+            "POST",
+            "/v1/link",
+            json=payload,
+            headers={"x-tenant-id": tenant_id},
+        )
+        return LinkResponse.model_validate(data)
+
+    async def search(
+        self,
+        query: str,
+        source: str | None = None,
+        episode_type: str | None = None,
+        time_range: str | None = None,
+        namespace: str | None = None,
+        limit: int = 20,
+        offset: int = 0,
+        tenant_id: str = "default",
+    ) -> SearchResponse:
+        """Search across memories and episodes with filters.
+
+        Unlike :meth:`recall`, this returns both context and matching episodes.
+
+        Args:
+            query: Natural-language search query.
+            source: Filter by source connector (e.g., ``"slack"``, ``"github"``).
+            episode_type: Filter by episode type (e.g., ``"message"``, ``"incident"``).
+            time_range: Time range filter (e.g., ``"1h"``, ``"24h"``, ``"7d"``, ``"30d"``).
+            namespace: Filter by namespace.
+            limit: Maximum results to return.
+            offset: Pagination offset.
+            tenant_id: Tenant namespace.
+
+        Returns:
+            A ``SearchResponse`` with context, episodes, and metadata.
+        """
+        payload: dict[str, Any] = {"query": query, "limit": limit, "offset": offset}
+        filters: dict[str, str] = {}
+        if source:
+            filters["source"] = source
+        if episode_type:
+            filters["episode_type"] = episode_type
+        if time_range:
+            filters["time_range"] = time_range
+        if namespace:
+            filters["namespace"] = namespace
+        if filters:
+            payload["filters"] = filters
+        data = await self._request(
+            "POST",
+            "/v1/search",
+            json=payload,
+            headers={"x-tenant-id": tenant_id},
+        )
+        return SearchResponse.model_validate(data)
+
+    # -- GTM convenience methods ---------------------------------------------
+
+    async def memory(
+        self,
+        query: str,
+        tenant_id: str = "default",
+        **kwargs: Any,
+    ) -> RecallResponse:
+        """Recall memories with a single natural-language query.
+
+        This is the GTM one-liner::
+
+            await cortex.memory("why did checkout fail yesterday")
+
+        It is an alias for :meth:`recall` with the same parameter semantics.
+
+        Args:
+            query: Natural-language query.
+            tenant_id: Tenant namespace.
+            **kwargs: Additional keyword arguments forwarded to :meth:`recall`
+                (e.g. ``max_tokens``, ``min_confidence``).
+
+        Returns:
+            A ``RecallResponse`` containing ranked matches.
+        """
+        return await self.recall(query=query, tenant_id=tenant_id, **kwargs)
+
+    async def store(
+        self,
+        data: str | dict[str, Any],
+        tenant_id: str = "default",
+        **kwargs: Any,
+    ) -> RememberResponse | IngestEpisodeResponse:
+        """Smart store that accepts a string or a dict.
+
+        Usage::
+
+            await cortex.store("The deploy succeeded at 14:32 UTC.")
+            await cortex.store({"content": "deploy ok", "type": "event", "source": "ci"})
+
+        When *data* is a **string**, it delegates to :meth:`remember`.
+        When *data* is a **dict**, it converts it via
+        :meth:`IngestEpisodeRequest.from_dict` and delegates to
+        :meth:`ingest_episode`.
+
+        Args:
+            data: Either a plain string (stored via ``remember``) or a dict
+                describing a structured episode (stored via ``ingest_episode``).
+            tenant_id: Tenant namespace (used for both code paths).
+            **kwargs: Extra keyword arguments forwarded to ``remember`` when
+                *data* is a string.
+
+        Returns:
+            A ``RememberResponse`` (string path) or
+            ``IngestEpisodeResponse`` (dict path).
+
+        Raises:
+            TypeError: If *data* is neither a string nor a dict.
+        """
+        if isinstance(data, str):
+            return await self.remember(content=data, tenant_id=tenant_id, **kwargs)
+
+        if isinstance(data, dict):
+            data.setdefault("tenant_id", tenant_id)
+            episode = IngestEpisodeRequest.from_dict(data)
+            return await self.ingest_episode(episode)
+
+        raise TypeError(
+            f"store() expects a str or dict, got {type(data).__name__}"
+        )
+
+    async def context(
+        self,
+        query: str,
+        agent_id: str = "default",
+        tenant_id: str = "default",
+        max_tokens: int = 8192,
+    ) -> RecallResponse:
+        """Retrieve enriched context for an LLM agent.
+
+        Designed for feeding context windows to autonomous agents. Uses a
+        higher default token budget than :meth:`recall`.
+
+        Usage::
+
+            await cortex.context(agent_id="incident-bot", query="current status of payments")
+
+        Args:
+            query: Natural-language query describing what context is needed.
+            agent_id: Identifier of the requesting agent (reserved for
+                future per-agent retrieval policies).
+            tenant_id: Tenant namespace.
+            max_tokens: Maximum token budget for the response (default 8192).
+
+        Returns:
+            A ``RecallResponse`` containing ranked matches.
+        """
+        return await self.recall(
+            query=query,
+            tenant_id=tenant_id,
+            max_tokens=max_tokens,
+        )
+
+    # -- internal ------------------------------------------------------------
+
+    async def _request(self, method: str, path: str, **kwargs: Any) -> Any:
+        """Execute an async HTTP request with retry logic.
+
+        Returns:
+            Decoded JSON response body.
+
+        Raises:
+            CortexAPIError: On non-retryable HTTP errors.
+            CortexConnectionError: When the server is unreachable.
+            CortexTimeoutError: When the request exceeds the configured timeout.
+        """
+
+        @retry(
+            retry=retry_if_exception(_is_retryable),
+            stop=stop_after_attempt(self._max_retries),
+            wait=wait_exponential(multiplier=0.5, min=0.5, max=10),
+            reraise=True,
+        )
+        async def _do() -> Any:
+            try:
+                response = await self._client.request(method, path, **kwargs)
+            except httpx.TimeoutException as exc:
+                raise CortexTimeoutError(str(exc)) from exc
+            except httpx.ConnectError as exc:
+                raise CortexConnectionError(str(exc)) from exc
+            except httpx.HTTPError as exc:
+                raise CortexConnectionError(str(exc)) from exc
+
+            _raise_for_status(response)
+
+            if response.status_code == 204:
+                return {}
+            return response.json()
+
+        return await _do()