@ngocsangairvds/vsaf 3.2.16 → 4.0.1

package/tools/vds-scripts/vds_memory_client/src/vds_memory_client/client.py

@@ -1,876 +0,0 @@
-"""Shared async HTTP client for VDS AI Memory API.
-
-Thin wrapper around httpx that handles:
-- Session auto-management (24h TTL, required for store, optional for search)
-- Atomic session state persistence (~/.vds/.memory-session.json)
-- JSON corruption recovery for the session cache file
-- Sync wrappers for non-async callers (search_sync, store_sync, health_sync)
-
-The base URL defaults to ``VDS_MEMORY_API_URL``. If unset, ``API_PORT`` is
-used (``http://localhost:${API_PORT}``), then falls back to
-``http://localhost:8000``.
-"""
-
-from __future__ import annotations
-
-import asyncio
-import contextlib
-import json
-import logging
-import os
-import sys
-import tempfile
-import warnings
-from collections.abc import AsyncIterator
-from pathlib import Path
-from urllib.parse import urlparse, urlunparse
-
-import httpx
-from websockets.asyncio.client import connect as ws_connect
-from websockets.exceptions import ConnectionClosedError, ConnectionClosedOK
-
-SESSION_STATE_FILE = Path.home() / ".vds" / ".memory-session.json"
-
-logger = logging.getLogger(__name__)
-
-
-def _is_machine_context() -> bool:
-    """Return True when running in a machine/CI/non-interactive context.
-
-    Checks: VDS_CLIENT_KIND=service, CI truthy, VDS_NON_INTERACTIVE truthy,
-    or stdin is not a tty. Pure function; no side effects.
-    """
-    return (
-        os.environ.get("VDS_CLIENT_KIND") == "service"
-        or bool(os.environ.get("CI"))
-        or bool(os.environ.get("VDS_NON_INTERACTIVE"))
-        or not sys.stdin.isatty()
-    )
-
-
-def _resolve_default_base_url() -> str:
-    explicit_url = os.environ.get("VDS_MEMORY_API_URL", "").strip()
-    if explicit_url:
-        return explicit_url
-
-    api_port = os.environ.get("API_PORT", "").strip()
-    if api_port:
-        return f"http://localhost:{api_port}"
-
-    return "http://localhost:8000"
-
-
-def _resolve_default_timeout() -> float:
-    """Resolve default HTTP timeout from env var with silent fallback."""
-    raw = os.environ.get("VDS_MEMORY_TIMEOUT_SECONDS", "").strip()
-    if raw:
-        try:
-            value = float(raw)
-            if value > 0:
-                return value
-        except ValueError:
-            pass
-    return 60.0
-
-
-class VDSMemoryClient:
-    """Shared async HTTP client for VDS AI Memory API.
-
-    This is the canonical client implementation used by both
-    ``memory_orchestrator`` (CLI) and ``multi_agent_orchestrator``.
-
-    Args:
-        base_url: API base URL. Defaults to ``VDS_MEMORY_API_URL`` env var
-            or ``http://localhost:8000``.
-        timeout: Request timeout in seconds. Defaults to
-            ``VDS_MEMORY_TIMEOUT_SECONDS`` env var, or 60.0 if unset.
-            Explicit kwarg always takes precedence.
-        default_user_id: Default user ID for API calls.
-    """
-
-    def __init__(
-        self,
-        base_url: str | None = None,
-        timeout: float | None = None,
-        default_user_id: str = "claude-agent",
-    ) -> None:
-        self._base_url = (base_url or _resolve_default_base_url()).rstrip("/")
-        self._timeout = timeout if timeout is not None else _resolve_default_timeout()
-        self._default_user_id = default_user_id
-        self._session_id: str | None = None
-
-    # ------------------------------------------------------------------
-    # Internal HTTP helper
-    # ------------------------------------------------------------------
-
-    async def _request(self, method: str, path: str, **kwargs: object) -> dict:
-        """Send an HTTP request and return the JSON response.
-
-        Token injection order (FR-220.M.2):
-          1. ``VDS_MEMORY_CLIENT_SERVICE_TOKEN`` — Phase 220.M machine-identity
-             env var (highest priority; preferred for all machine callers).
-          2. ``VDS_SCHEDULER_SERVICE_TOKEN`` — Phase 217 ADR-79 scheduler token
-             (backwards-compatible fallback).
-          3. No token injected — caller supplies an ``Authorization`` header
-             directly (e.g., analytics-stream acquires one via
-             ``acquire_jwt_token()`` when neither env var is set).
-
-        Args:
-            method: HTTP method (get, post, etc.).
-            path: API path (e.g., /api/v1/memories/search).
-            **kwargs: Additional arguments passed to httpx (json, params, etc.).
-
-        Returns:
-            Parsed JSON response as a dictionary.
-
-        Raises:
-            httpx.HTTPStatusError: On 4xx/5xx responses.
-            httpx.ConnectError: When the API is unreachable.
-        """
-        headers: dict = kwargs.pop("headers", {}) or {}  # type: ignore[assignment]
-
-        if _svc_token := os.environ.get("VDS_MEMORY_CLIENT_SERVICE_TOKEN"):
-            logger.debug("auth: using VDS_MEMORY_CLIENT_SERVICE_TOKEN")
-            headers.setdefault("Authorization", f"Bearer {_svc_token}")
-        elif _sched_token := os.environ.get("VDS_SCHEDULER_SERVICE_TOKEN"):
-            logger.debug("auth: using VDS_SCHEDULER_SERVICE_TOKEN")
-            headers.setdefault("Authorization", f"Bearer {_sched_token}")
-        else:
-            logger.debug("auth: no service token; caller must supply Authorization header directly")
-
-        if headers:
-            kwargs["headers"] = headers
-        async with httpx.AsyncClient(timeout=self._timeout) as client:
-            resp = await getattr(client, method)(f"{self._base_url}{path}", **kwargs)
-            resp.raise_for_status()
-            return resp.json()
-
-    # ------------------------------------------------------------------
-    # Session management
-    # ------------------------------------------------------------------
-
-    async def ensure_session(self, user_id: str | None = None) -> str:
-        """Auto-create or reuse a 24h session. Required by API for store operations.
-
-        Session resolution order:
-        1. In-memory cache (self._session_id)
-        2. File-persisted session (~/.vds/.memory-session.json) with validity check
-        3. Create new session via API (TTL capped at 24h)
-
-        Args:
-            user_id: User ID for session creation. Falls back to default_user_id.
-
-        Returns:
-            Active session_id string.
-        """
-        resolved_user_id = user_id or self._default_user_id
-
-        # Path 1: In-memory cache
-        if self._session_id:
-            return self._session_id
-
-        # Path 2: File-persisted session (with corruption recovery)
-        if SESSION_STATE_FILE.exists():
-            try:
-                state = json.loads(SESSION_STATE_FILE.read_text())
-            except (json.JSONDecodeError, OSError):
-                state = {}  # Treat corrupted file as expired
-
-            sid = state.get("session_id")
-            if sid:
-                # Verify session is still active via API
-                try:
-                    resp = await self._request("get", f"/api/v1/sessions/{sid}")
-                    if resp.get("status") == "active":
-                        self._session_id = sid
-                        return sid
-                except httpx.HTTPStatusError:
-                    pass  # Session expired or not found, create new
-
-        # Path 3: Create new session (TTL capped at 24h by API)
-        resp = await self._request(
-            "post",
-            "/api/v1/sessions",
-            json={
-                "user_id": resolved_user_id,
-                "project_domain": "PLATFORM",
-                "context": "VDS CLI memory session",
-                "ttl_hours": 24,
-            },
-        )
-        sid = resp["session_id"]
-        self._session_id = sid
-
-        # Atomic write (temp + os.replace) to prevent corruption from concurrent CLI calls
-        SESSION_STATE_FILE.parent.mkdir(parents=True, exist_ok=True)
-        fd, tmp_path = tempfile.mkstemp(
-            dir=str(SESSION_STATE_FILE.parent),
-            suffix=".tmp",
-        )
-        try:
-            with os.fdopen(fd, "w") as f:
-                json.dump({"session_id": sid, "user_id": resolved_user_id}, f)
-            os.replace(tmp_path, str(SESSION_STATE_FILE))
-        except OSError:
-            # Best-effort cleanup; session still works in-memory
-            with contextlib.suppress(OSError):
-                os.unlink(tmp_path)
-
-        return sid
-
-    # ------------------------------------------------------------------
-    # Async API methods
-    # ------------------------------------------------------------------
-
-    async def search(
-        self,
-        query: str,
-        category: str | None = None,
-        importance: str | None = None,
-        limit: int = 10,
-        user_id: str | None = None,
-        session_id: str | None = None,
-    ) -> dict:
-        """Semantic search across memories. Does NOT require a session.
-
-        Args:
-            query: Natural language search query.
-            category: Optional category filter.
-            importance: Optional importance filter.
-            limit: Maximum number of results.
-            user_id: User ID for the search. Falls back to default_user_id.
-            session_id: Optional session ID to restrict results to a single session.
-
-        Returns:
-            Search results dictionary with query, search_mode, total_count, results.
-        """
-        resolved_user_id = user_id or self._default_user_id
-        body: dict[str, object] = {
-            "query": query,
-            "user_id": resolved_user_id,
-            "limit": limit,
-        }
-        if category:
-            body["category"] = category
-        if importance:
-            body["importance"] = importance
-        if session_id:
-            body["session_id"] = session_id
-        return await self._request("post", "/api/v1/memories/search", json=body)
-
-    async def delete(self, memory_id: str) -> dict:
-        """Delete a single memory by ID (soft delete by default).
-
-        Args:
-            memory_id: The memory ID to delete.
-
-        Returns:
-            Response dictionary, e.g. {"message": "Memory deleted"}.
-        """
-        return await self._request("delete", f"/api/v1/memories/{memory_id}")
-
-    async def store(
-        self,
-        content: str,
-        category: str = "general",
-        importance: str = "medium",
-        tags: list[str] | None = None,
-        user_id: str | None = None,
-    ) -> dict:
-        """Store a new memory. Requires a session (auto-created if needed).
-
-        Args:
-            content: Memory content to store.
-            category: Memory category (e.g., general, code, decision).
-            importance: Memory importance (low, medium, high, critical).
-            tags: Optional tags (stored in metadata.tags because the API's
-                  create endpoint does not persist a top-level tags field).
-            user_id: User ID for the store. Falls back to default_user_id.
-
-        Returns:
-            Store response with memory_id, content, category, etc.
-        """
-        resolved_user_id = user_id or self._default_user_id
-        session_id = await self.ensure_session(resolved_user_id)
-        body: dict[str, object] = {
-            "content": content,
-            "user_id": resolved_user_id,
-            "session_id": session_id,
-            "category": category,
-            "importance": importance,
-        }
-        if tags:
-            # Tags go in metadata.tags -- top-level tags field is not persisted by API
-            body.setdefault("metadata", {})["tags"] = tags  # type: ignore[union-attr]
-        return await self._request("post", "/api/v1/memories", json=body)
-
-    async def get(self, memory_id: str) -> dict:
-        """Retrieve a single memory by ID.
-
-        Args:
-            memory_id: The memory ID to retrieve.
-
-        Returns:
-            Memory dictionary with id, content, category, importance, etc.
-        """
-        return await self._request("get", f"/api/v1/memories/{memory_id}")
-
-    async def list_sessions(self, user_id: str | None = None) -> dict:
-        """List sessions for a user.
-
-        Args:
-            user_id: User ID to list sessions for. Falls back to default_user_id.
-
-        Returns:
-            Sessions list response.
-        """
-        resolved_user_id = user_id or self._default_user_id
-        return await self._request("get", f"/api/v1/sessions/user/{resolved_user_id}")
-
-    async def health(self) -> dict:
-        """Check VDS AI Memory service health.
-
-        Returns:
-            Full health status dictionary including status.overall, mem0_sync
-            metrics, and timestamp. Uses the /api/v1/health/full endpoint to
-            include mem0 synchronisation statistics required by AC-5.2.
-        """
-        return await self._request("get", "/api/v1/health/full")
-
-    async def stats(self, include_internal: bool = False) -> dict:
-        """Get VDS AI Memory statistics.
-
-        Args:
-            include_internal: When True, include internal/_-prefixed user data.
-
-        Returns:
-            Statistics dictionary.
-        """
-        params: dict[str, str] = {"include_internal": "true"} if include_internal else {}
-        return await self._request("get", "/api/v1/stats", params=params)
-
-    async def warm_cache(self, user_id: str) -> dict:
-        """Warm the semantic cache for a user by pre-loading common queries.
-
-        Args:
-            user_id: The user ID to warm the cache for.
-
-        Returns:
-            Cache warming result dictionary.
-        """
-        return await self._request("post", "/api/v1/cache/warm", json={"user_id": user_id})
-
-    async def cleanup(
-        self,
-        remove_health_debris: bool = False,
-        remove_stale_sessions: bool = False,
-        stale_days: int = 90,
-        dry_run: bool = True,
-    ) -> dict:
-        """Clean up health-check debris and stale sessions.
-
-        Args:
-            remove_health_debris: Remove sessions/memories created by health probes.
-            remove_stale_sessions: Remove sessions inactive longer than stale_days.
-            stale_days: Days of inactivity before a session is considered stale.
-            dry_run: When True (default), report without deleting.
-
-        Returns:
-            Cleanup result dictionary.
-        """
-        return await self._request(
-            "post",
-            "/api/v1/cleanup",
-            json={
-                "remove_health_debris": remove_health_debris,
-                "remove_stale_sessions": remove_stale_sessions,
-                "stale_days": stale_days,
-                "dry_run": dry_run,
-            },
-        )
-
-    async def dedup_detect(self, threshold: float = 0.95) -> dict:
-        """Detect duplicate memories above a similarity threshold.
-
-        Args:
-            threshold: Cosine similarity threshold (0.0–1.0). Defaults to 0.95.
-
-        Returns:
-            Detection result with duplicate groups list.
-        """
-        # Phase 216 (ADR-79 W2): server's DuplicateDetectionRequest model uses
-        # field name `similarity_threshold` (default 0.7). The previous body
-        # `{"threshold": ...}` was silently dropped by Pydantic and the default
-        # 0.7 was used regardless of the operator-supplied --threshold flag.
-        # V1 validation observed `threshold_used: 0.7` for `--threshold 0.95`.
-        return await self._request(
-            "post",
-            "/api/v1/deduplication/detect",
-            json={"similarity_threshold": threshold},
-        )
-
-    async def dedup_resolve(self, group_id: str) -> dict:
-        """Resolve a duplicate group by merging/removing duplicates.
-
-        Args:
-            group_id: The duplicate group ID returned by dedup_detect.
-
-        Returns:
-            Resolution result dictionary.
-        """
-        return await self._request(
-            "post",
-            "/api/v1/deduplication/resolve",
-            json={"group_id": group_id},
-        )
-
-    async def dedup_auto_resolve(
-        self,
-        max_groups: int = 10,
-        cosine_min: float = 1.0,
-        strategy: str = "keep-newest",
-    ) -> dict:
-        """Run auto-resolution cycle on detected duplicate groups (FR-229.1).
-
-        Args:
-            max_groups: Cap on groups resolved per invocation.
-            cosine_min: Minimum cosine similarity threshold.
-            strategy: Keeper selection strategy (keep-newest, keep-most-imported, merge-content).
-
-        Returns:
-            AutoResolveResult as dict with groups_processed, memories_resolved,
-            memories_tombstoned, review_groups, strategy_used, cycle_timestamp.
-        """
-        return await self._request(
-            "post",
-            "/api/v1/maintenance/dedup-auto-resolve",
-            json={
-                "max_groups": max_groups,
-                "cosine_min": cosine_min,
-                "strategy": strategy,
-            },
-        )
-
-    async def restore_tombstone(self, original_memory_id: str) -> dict:
-        """Restore a tombstoned memory record (FR-229.5).
-
-        Looks up the original memory in memory_records_tombstones.
-        If within the 7-day retention window, re-inserts into memory_records
-        and removes the tombstone. Returns RestoreWindowExpired if expired.
-
-        Args:
-            original_memory_id: The original memory_id to restore.
-
-        Returns:
-            Result dict with status and restored memory details.
-        """
-        return await self._request(
-            "post",
-            "/api/v1/deduplication/restore",
-            json={"original_memory_id": original_memory_id},
-        )
-
-    async def reconcile(self, limit: int = 100, dry_run: bool = False) -> dict:
-        """Trigger memory reconciliation to repair inconsistencies.
-
-        Args:
-            limit: Maximum records to reconcile per run.
-            dry_run: When True, report without changing data.
-
-        Returns:
-            Reconciliation trigger result dictionary.
-        """
-        return await self._request(
-            "post",
-            "/api/v1/reconciliation/trigger",
-            json={"limit": limit, "dry_run": dry_run},
-        )
-
-    async def replay_dlq(self, limit: int = 25) -> dict:
-        """Synchronously drain the memory-evolution DLQ.
-
-        Operator escape hatch — same async helper Celery beat invokes every
-        15 minutes, but blocking so the caller gets a drain confirmation.
-
-        Args:
-            limit: Maximum DLQ events to replay this batch (1-1000, default 25).
-
-        Returns:
-            ``{status, replayed, skipped, source}`` — ``status`` is "replayed"
-            on work done or "empty" when the queue drained.
-        """
-        return await self._request(
-            "post",
-            "/api/v1/tasks/replay-dlq",
-            json={"limit": limit},
-        )
-
-    async def embedding_status(self) -> dict:
-        """Get current embedding provider, model, dimension, and counts."""
-        return await self._request("get", "/api/v1/embedding/status")
-
-    async def re_embed(self, batch_size: int = 32, dry_run: bool = True) -> dict:
-        """Trigger batch re-embedding of all memories with current provider.
-
-        Args:
-            batch_size: Number of memories per batch.
-            dry_run: When True, count and estimate only.
-
-        Returns:
-            Re-embedding result with counts and duration.
-        """
-        return await self._request(
-            "post",
-            "/api/v1/embedding/re-embed",
-            json={"batch_size": batch_size, "dry_run": dry_run},
-        )
-
-    # ------------------------------------------------------------------
-    # Phase 217 ADR-77/79 — scheduler-triggered maintenance endpoints
-    # ------------------------------------------------------------------
-
-    async def dispatch(self, limit: int = 25) -> dict:
-        """Dispatch memory evolution processing batch.
-
-        Phase 217 ADR-77: HTTP-route for scheduler-triggered dispatch op.
-        Corresponds to the ``memory.evolution.dispatch`` DBOS schedule.
-
-        Args:
-            limit: Maximum evolution events to dispatch per run (default 25).
-
-        Returns:
-            Dispatch result dictionary.
-        """
-        return await self._request(
-            "post",
-            "/api/v1/maintenance/dispatch",
-            json={"limit": limit},
-        )
-
-    async def sweep(self, window_hours: int = 24) -> dict:
-        """Sweep stale memory evolution events within a time window.
-
-        Phase 217 ADR-77: HTTP-route for scheduler-triggered sweep op.
-        Corresponds to the ``memory.evolution.sweep`` DBOS schedule.
-
-        Args:
-            window_hours: Time window in hours for the sweep (default 24).
-
-        Returns:
-            Sweep result dictionary.
-        """
-        return await self._request(
-            "post",
-            "/api/v1/maintenance/sweep",
-            json={"window_hours": window_hours},
-        )
-
-    async def replay_dlq_endpoint(self, limit: int = 25) -> dict:
-        """Replay dead-letter queue events via the maintenance HTTP route.
-
-        Phase 217 ADR-77: HTTP-route variant of the DLQ replay operation.
-        Name disambiguates from :meth:`replay_dlq`, which targets the legacy
-        ``/api/v1/tasks/replay-dlq`` endpoint (the ad-hoc operator escape
-        hatch). This method targets ``/api/v1/maintenance/replay-dlq``
-        (the scheduler-triggered maintenance route). Corresponds to the
-        ``memory.evolution.replay-dlq`` DBOS schedule.
-
-        Args:
-            limit: Maximum DLQ events to replay this batch (default 25).
-
-        Returns:
-            ``{status, replayed, skipped, source}`` replay result dictionary.
-        """
-        return await self._request(
-            "post",
-            "/api/v1/maintenance/replay-dlq",
-            json={"limit": limit},
-        )
-
-    async def resolve_pending_ids(self, limit: int = 50) -> dict:
-        """Resolve memories with pending mem0 IDs.
-
-        Phase 217 ADR-77: HTTP-route for scheduler-triggered resolve-pending-ids op.
-        Corresponds to the ``mem0.resolve-pending-ids`` DBOS schedule.
-
-        Args:
-            limit: Maximum records to process per run (default 50).
-
-        Returns:
-            Resolution result dictionary.
-        """
-        return await self._request(
-            "post",
-            "/api/v1/maintenance/resolve-pending-ids",
-            json={"limit": limit},
-        )
-
-    async def repush_stalled(self, limit: int = 100) -> dict:
-        """Repush stalled memory evolution records.
-
-        Phase 217 ADR-77: HTTP-route for scheduler-triggered repush-stalled op.
-        Corresponds to the ``mem0.repush-stalled`` DBOS schedule.
-
-        Args:
-            limit: Maximum records to repush per run (default 100).
-
-        Returns:
-            Repush result dictionary.
-        """
-        return await self._request(
-            "post",
-            "/api/v1/maintenance/repush-stalled",
-            json={"limit": limit},
-        )
-
-    async def repush_local_only(self, limit: int = 100) -> dict:
-        """Repush memories that exist locally but are not yet in mem0.
-
-        Phase 217 ADR-77: HTTP-route for scheduler-triggered repush-local-only op.
-        Corresponds to the ``mem0.repush-local-only`` DBOS schedule.
-
-        Args:
-            limit: Maximum records to repush per run (default 100).
-
-        Returns:
-            Repush result dictionary.
-        """
-        return await self._request(
-            "post",
-            "/api/v1/maintenance/repush-local-only",
-            json={"limit": limit},
-        )
-
-    # ------------------------------------------------------------------
-    # VAMI-030 — analytics-stream support: JWT acquisition + WebSocket stream
-    # ------------------------------------------------------------------
-
-    # Phase 219 FR-219.5 (ADR-80): module-level constants make the dev-only
-    # intent of these defaults explicit. In production-mode containers, the
-    # /auth/login endpoint refuses to mint JWTs (Phase 219 ADR-80 fail-closed
-    # gate); operators MUST provide a pre-minted token via VDS_MEMORY_JWT or
-    # --token (per ADR-50 acquisition order). Phase 220.M will deprecate this
-    # acquire_jwt_token path entirely and migrate machine identities to the
-    # service-account JWT pattern (mirrors VDS_SCHEDULER_SERVICE_TOKEN).
-    _DEFAULT_DEV_LOGIN_USER: str = "claude-agent"  # DEV-MODE-ONLY
-    _DEFAULT_DEV_LOGIN_PASS: str = "vds-cli"  # DEV-MODE-ONLY
-
-    async def acquire_jwt_token(
-        self,
-        username: str | None = None,
-        password: str | None = None,
-    ) -> str:
-        """POST /api/v1/auth/login and return the access_token (per ADR-50).
-
-        Phase 219 (ADR-80): dev-mode placeholder login. In production
-        deployments, this endpoint returns HTTP 501 (Auth backend not
-        configured for production). Callers in production MUST provide a
-        pre-minted JWT via the VDS_MEMORY_JWT env var or --token CLI flag.
-
-        Phase 220.M (FR-220.M.3): this method emits a ``DeprecationWarning``
-        when called from a machine context (CI / VDS_CLIENT_KIND=service /
-        VDS_NON_INTERACTIVE / non-tty stdin).  The call is NOT blocked —
-        backwards compatibility is preserved.  Use
-        ``VDS_MEMORY_CLIENT_SERVICE_TOKEN`` with a JWT minted via
-        ``python -m vds_memory_orchestrator.scripts.mint_memory_client_service_token``
-        for machine callers.
-        """
-        if _is_machine_context():
-            warnings.warn(
-                "acquire_jwt_token is deprecated for machine contexts; set "
-                "VDS_MEMORY_CLIENT_SERVICE_TOKEN with a service-account JWT minted via "
-                "`python -m vds_memory_orchestrator.scripts.mint_memory_client_service_token` "
-                "instead. Phase 219 dev-login will be removed in a future release.",
-                DeprecationWarning,
-                stacklevel=2,
-            )
-        username = username or self._DEFAULT_DEV_LOGIN_USER
-        password = password or self._DEFAULT_DEV_LOGIN_PASS
-        async with httpx.AsyncClient(timeout=self._timeout) as client:
-            resp = await client.post(
-                f"{self._base_url}/api/v1/auth/login",
-                json={"username": username, "password": password},
-            )
-            resp.raise_for_status()
-            return resp.json()["access_token"]
-
-    def _build_ws_url(self, *, token: str, interval: float) -> str:
-        """Convert http(s)://host:port → ws(s)://host:port + WS path + query."""
-        parsed = urlparse(self._base_url)
-        ws_scheme = "wss" if parsed.scheme == "https" else "ws"
-        return urlunparse(
-            (
-                ws_scheme,
-                parsed.netloc,
-                "/api/v1/analytics/ws/real-time",
-                "",
-                f"token={token}&interval={interval}",
-                "",
-            )
-        )
-
-    async def stream_real_time_metrics(
-        self,
-        *,
-        token: str,
-        interval: float = 2.0,
-        auto_reconnect: bool = True,
-        max_retries: int = 10,
-    ) -> AsyncIterator[dict]:
-        """Yield metrics envelopes from /api/v1/analytics/ws/real-time.
-
-        Per ADR-51: uses ``async for ws in connect(...)`` (websockets v16
-        canonical iterator) when ``auto_reconnect`` is True; reconnects
-        automatically on transient errors with library-managed exponential
-        backoff (capped ~30s with jitter). Does NOT reconnect on
-        ConnectionClosedError(1008) — auth failures are terminal and must
-        propagate to the caller.
-
-        Each yielded envelope is the parsed JSON dict from the server::
-
-            {"metrics": {...11 RealTimeMetrics fields...},
-             "timestamp": "<iso8601>"}
-
-        Args:
-            token: JWT for ?token=<jwt> query param. Use
-                :meth:`acquire_jwt_token` to mint via /auth/login.
-            interval: Server-side metric refresh interval (seconds).
-                Default 2.0; min 0.1.
-            auto_reconnect: If True (default), reconnect on transient errors
-                using the library iterator. If False, single-shot mode —
-                exits after first disconnect.
-            max_retries: Cap on auto-reconnect attempts (0 = unlimited).
-
-        Yields:
-            ``{"metrics": dict, "timestamp": str}`` envelope per server tick.
-
-        Raises:
-            ConnectionClosedError: On auth failure (close code 1008) — terminal,
-                NOT reconnected. Caller must surface as exit-1 with operator hint.
-            OSError / ConnectionRefusedError: When the API is unreachable AND
-                auto_reconnect is False (or max_retries exhausted).
-        """
-        url = self._build_ws_url(token=token, interval=interval)
-
-        if not auto_reconnect:
-            async with ws_connect(url, open_timeout=10) as ws:
-                async for raw in ws:
-                    yield json.loads(raw)
-            return
-
-        attempts = 0
-        async for ws in ws_connect(url, open_timeout=10):
-            try:
-                async for raw in ws:
-                    yield json.loads(raw)
-            except ConnectionClosedOK:
-                return  # Server-initiated normal close; do not reconnect.
-            except ConnectionClosedError as exc:
-                # 1008 = Policy Violation (auth fail) → terminal, propagate.
-                # Use .rcvd.code per websockets v13.1+ API (avoid deprecated .code).
-                code = getattr(getattr(exc, "rcvd", None), "code", None)
-                if code == 1008:
-                    raise
-                # Other close codes → let library reconnect via iterator.
-            attempts += 1
-            if max_retries and attempts >= max_retries:
-                return
-
-    # ------------------------------------------------------------------
-    # Sync wrappers (for non-async callers)
-    # ------------------------------------------------------------------
-
-    def search_sync(
-        self,
-        query: str,
-        category: str | None = None,
-        importance: str | None = None,
-        limit: int = 10,
-        user_id: str | None = None,
-    ) -> dict:
-        """Synchronous wrapper around :meth:`search`.
-
-        Uses ``asyncio.run()`` internally. Do NOT call from within an
-        already-running event loop -- use the async version instead.
-        """
-        return asyncio.run(self.search(query, category, importance, limit, user_id))
-
-    def store_sync(
-        self,
-        content: str,
-        category: str = "general",
-        importance: str = "medium",
-        tags: list[str] | None = None,
-        user_id: str | None = None,
-    ) -> dict:
-        """Synchronous wrapper around :meth:`store`.
-
-        Uses ``asyncio.run()`` internally. Do NOT call from within an
-        already-running event loop -- use the async version instead.
-        """
-        return asyncio.run(self.store(content, category, importance, tags, user_id))
-
-    def health_sync(self) -> dict:
-        """Synchronous wrapper around :meth:`health`.
-
-        Uses ``asyncio.run()`` internally. Do NOT call from within an
-        already-running event loop -- use the async version instead.
-        """
-        return asyncio.run(self.health())
-
-    # ------------------------------------------------------------------
-    # VAMI-017 Phase B — status polling (T-A5)
-    # ------------------------------------------------------------------
-
-    async def wait_for_mem0_id(
-        self,
-        memory_id: str,
-        poll_interval: float = 1.5,
-        max_wait: float = 60.0,
-    ) -> dict:
-        """Poll /memories/{id}/status until terminal state or timeout.
-
-        Supports the future 202-async store pattern: after receiving
-        ``{memory_id, status: "queued"}`` from POST /memories, call this to
-        wait for the mem0_id to be resolved. Also useful today to observe
-        mem0 backfill completion in sync-mode stores.
-
-        Args:
-            memory_id: The ``pg_<uuid>`` returned by store.
-            poll_interval: Seconds between polls (default 1.5 s).
-            max_wait: Maximum seconds to wait (default 60 s).
-
-        Returns:
-            The terminal status dict, e.g.
-            ``{memory_id, status: "complete", mem0_id}`` or
-            ``{memory_id, status: "failed", error}``.
-
-        Raises:
-            TimeoutError: If max_wait elapses without a terminal state.
-        """
-        import time
-
-        deadline = time.monotonic() + max_wait
-        while True:
-            result = await self._request("get", f"/api/v1/memories/{memory_id}/status")
-            state = result.get("status")
-            if state in ("complete", "failed"):
-                return result
-            if time.monotonic() >= deadline:
-                raise TimeoutError(
-                    f"wait_for_mem0_id: memory_id={memory_id} still {state!r} after {max_wait}s"
-                )
-            await asyncio.sleep(poll_interval)
-
-    def wait_for_mem0_id_sync(
-        self,
-        memory_id: str,
-        poll_interval: float = 1.5,
-        max_wait: float = 60.0,
-    ) -> dict:
-        """Synchronous wrapper around :meth:`wait_for_mem0_id`.
-
-        Uses ``asyncio.run()`` internally. Do NOT call from within an
-        already-running event loop -- use the async version instead.
-        """
-        return asyncio.run(self.wait_for_mem0_id(memory_id, poll_interval, max_wait))