feat: add optional mem0 cloud backend for memory index and update documentation

.env.example

@@ -55,5 +55,18 @@ DATABASE_URL=
 MEMORY_INDEX=
 MEMORY_INDEX_CONFIG=
 
+# Hosted mem0 platform backend (ADR-0020), opt-in. Set MEMORY_INDEX=cloud (or
+# MEMORY_INDEX_BACKEND=cloud) to use mem0's managed service instead of the local
+# embedder. NOTE: this sends ledger event text to mem0's servers — a deliberate
+# departure from the off-the-grid default; the local backend stays the default.
+#   MEMORY_INDEX=cloud
+#   MEM0_API_KEY=m0-...            # required for the hosted backend
+MEM0_API_KEY=
+# Optional hosted scoping:
+# MEM0_ORG_ID=
+# MEM0_PROJECT_ID=
+# MEM0_HOST=
+# MEMORY_INDEX_BACKEND=           # set to "cloud" to force the hosted backend
+
 # Gradio server port (auto-detects a free port in 7960-8059 if unset).
 GRADIO_SERVER_PORT=

.gitignore

@@ -8,4 +8,5 @@ __pycache__/
 scripts/
 runs/
 *.db
-CLAUDE.md
+CLAUDE.md
+ui/raw

docs/adr/0020-mem0-hosted-cloud-memory-index.md

@@ -0,0 +1,100 @@
+# ADR-0020: Optional mem0 Hosted-Cloud Backend for the Memory Index
+
+## Status
+
+Accepted (extends [ADR-0018](0018-layered-semantic-memory-index.md); relates to
+[ADR-0019](0019-single-model-catalogue-no-cloud-path.md))
+
+## Context
+
+ADR-0018 added an optional **semantic memory index** as a *derived, rebuildable
+lens* over the append-only ledger, behind a two-method `MemoryIndex` protocol
+(`index(events)` / `search(query, k)`). ADR-0018 explicitly anticipated
+**alternative backends behind the same protocol**, and ADR-0019 set the default
+embedder to a **local sentence-transformers** model so an activated index stays
+*off the grid* — no API key, nothing leaves the machine.
+
+The local backend (`Mem0MemoryIndex`, wrapping the OSS `mem0.Memory`) is the right
+default, but some deployments want mem0's **managed platform** (api.mem0.ai)
+instead:
+
+- no local embedder or vector store to host (mem0 runs both);
+- memory that **persists across processes and runs** in one managed store, rather
+  than an in-process index rebuilt per boot;
+- access to mem0's hosted retrieval features and org/project scoping.
+
+The request is "can we use the mem0 hosted cloud version." The protocol already
+makes room for it; the only real design question is how to add it **without
+compromising the off-the-grid default** or the ledger-is-truth invariant.
+
+## Decision
+
+Add a second backend, **`Mem0CloudIndex`**, that wraps the mem0 platform client
+(`mem0.MemoryClient`) behind the *same* `MemoryIndex` protocol. It is **strictly
+opt-in and never the default**.
+
+**Shared base, two thin backends.** Factor the protocol surface — idempotent
+upsert keyed by `event.id`, verbatim storage (`infer=False`), and search-hit →
+`Event` reconstruction from metadata — into a private `_Mem0BackendBase`. The two
+backends differ only in three variation points: how the client is built
+(`Memory.from_config` vs `MemoryClient(...)`), how one event is stored, and how a
+query is run. The invariants from ADR-0018 (derived, rebuildable, ledger is truth,
+visibility filter unchanged) hold identically for both — only *where* the
+embedding and retrieval happen differs.
+
+**Same contract, verbatim storage.** The cloud backend stores each event as one
+chat-style user turn with `infer=False`, so mem0's generative LLM never rewrites
+or extracts — the ledger text is what is embedded, and the full event rides in
+`metadata` for reconstruction. Dedup is process-local by `event.id`, *before* the
+client is built, so re-indexing the same ledger slice never re-embeds and an
+already-indexed id needs no network call.
+
+**Selection by env, local stays default.** `memory_index_from_env()`:
+
+| `MEMORY_INDEX` | `MEMORY_INDEX_BACKEND` | Result |
+|---|---|---|
+| unset / falsey | — | `None` — offline keyword path (default; suite default) |
+| `1` / `true` / `local` / `mem0` / `on` | — | `Mem0MemoryIndex` (local, off the grid) |
+| `cloud` / `mem0-cloud` / `platform` / `hosted` | — | `Mem0CloudIndex` (hosted) |
+| any | `cloud` | `Mem0CloudIndex` (explicit backend wins) |
+
+The cloud backend reads `MEM0_API_KEY` (required), and optional `MEM0_ORG_ID` /
+`MEM0_PROJECT_ID` / `MEM0_HOST`, from the environment. `mem0` is lazy-imported
+inside the backend, so the offline path needs neither the package nor a key, and a
+missing key fails loudly on first use — not at import.
+
+**No new dependency.** `MemoryClient` ships in the same `mem0ai` package already
+declared by the optional `memory` extra; the cloud path does not need
+`sentence-transformers` (embeddings are server-side).
+
+## Off-the-grid reconciliation (ADR-0019)
+
+ADR-0019 made the engine off the grid *by default* — local embeddings, no cloud
+key path for inference or memory. This ADR does not reverse that: it adds an
+**opt-in** that is dormant unless explicitly selected. **Activating
+`Mem0CloudIndex` sends ledger event text to mem0's servers** — a deliberate,
+clearly-flagged departure from the default, documented in the backend docstring,
+`config` comments, and `memory-stack.md`. With the gate unset or set to a local
+spelling, behaviour is byte-for-byte what ADR-0019 specified.
+
+## Consequences
+
+- **Same protocol, no blast radius.** `SalienceMemory`, `ManifestAgent._recall`,
+  the registry wiring, and the agent contract are untouched — they still see a
+  `MemoryIndex`. Swapping local ↔ cloud is one env var.
+- **Tradeoffs the operator opts into.** Cloud means data egress (ledger text
+  leaves the machine), a network dependency on api.mem0.ai, and per-call latency
+  and cost on mem0's side. In exchange: managed embeddings + vector store, and
+  memory that persists across processes/runs rather than rebuilding in-process.
+- **Tests mirror the local tiers, all green offline.** Protocol conformance, env
+  selection (each cloud spelling + backend override + credential plumbing), and
+  idempotent dedup are exercised with `mem0` absent and no key. A real hosted
+  round-trip is guarded behind `MEM0_API_KEY` + `MEM0_CLOUD_E2E` and skipped
+  otherwise. The suite stays green with the extra uninstalled.
+- **Known follow-ups.** Surface the active backend (keyword / local / cloud) on the
+  stats panel; reconcile mem0's own platform memory-id with our `event.id` (we key
+  dedup and reconstruction on `event.id` in metadata, not mem0's id); consider
+  scoping cloud entries by `run_id` via mem0 filters for multi-run isolation
+  (mirrors the ADR-0014 single-store caveat); the `infer=False` + chat-message
+  `add` shape assumes a mem0 client version with platform `infer` support — pin it
+  in the `memory` extra if a future release changes the contract.

docs/architecture/memory-stack.md

@@ -155,6 +155,16 @@ Postgres+pgvector, ADR-0014) via `MEMORY_INDEX_CONFIG` (a JSON blob forwarded
 verbatim to the backend's `from_config`). Install the `memory` extra (`mem0ai` +
 `sentence-transformers`). See ADR-0019.
 
+**Hosted backend (opt-in, ADR-0020)**: set `MEMORY_INDEX=cloud` (or
+`MEMORY_INDEX_BACKEND=cloud`) to use mem0's managed platform (`MemoryClient`,
+api.mem0.ai) instead of the local embedder. `Mem0CloudIndex` satisfies the *same*
+`MemoryIndex` protocol — derived, idempotent by `event.id`, ledger-is-truth,
+verbatim `infer=False` storage — so nothing downstream changes; only *where* the
+embedding and retrieval run differs. It needs `MEM0_API_KEY` (plus optional
+`MEM0_ORG_ID` / `MEM0_PROJECT_ID` / `MEM0_HOST`). **Caveat:** activating it sends
+ledger event text to mem0's servers — a deliberate departure from the
+off-the-grid default, which is why the local backend remains the default.
+
 **Alternative backends**: the two-method protocol can wrap any retrieval store —
 a stateful agent-memory service (e.g. a Letta-style memory server) could be a
 `MemoryIndex` too, as long as it stays derived from and rebuildable from the

src/core/memory_index.py

@@ -14,15 +14,22 @@ Two pieces:
     events back. Any backend that satisfies this protocol can supply semantic
     relevance — a vector service, a local embedding store, or a fake in tests.
 
-  * :class:`Mem0MemoryIndex` — a concrete backend. It is **lazy-imported and
-    env-gated**: with the backend not installed or not configured, nothing here
-    is imported and :class:`~src.core.memory.SalienceMemory` falls back to its
-    keyword-Jaccard relevance exactly as before. The backend activates only when
-    :func:`memory_index_from_env` finds it configured.
-
-Because the index is derived, ``index()`` upserts each event under its
-``event.id`` so re-indexing the same events is a no-op (no duplicates) — this is
-what makes the index rebuildable rather than authoritative.
+  * Two concrete backends behind that protocol, both **lazy-imported and
+    env-gated** so nothing is imported and :class:`~src.core.memory.SalienceMemory`
+    stays on its keyword-Jaccard relevance unless an index is configured:
+
+      - :class:`Mem0MemoryIndex` — the default, **off the grid**. Wraps the
+        ``mem0`` OSS ``Memory`` with a local sentence-transformers embedder; no
+        API key, nothing leaves the machine (ADR-0019).
+      - :class:`Mem0CloudIndex` — opt-in hosted backend. Wraps the ``mem0``
+        platform ``MemoryClient`` (api.mem0.ai). **Activating it sends ledger
+        event text to mem0's servers** and needs ``MEM0_API_KEY`` — a deliberate
+        departure from the off-the-grid default, so it is never the default
+        (ADR-0020).
+
+Because the index is derived, both backends upsert each event under its
+``event.id`` (process-local dedup) so re-indexing the same events is a no-op (no
+duplicates) — this is what makes the index rebuildable rather than authoritative.
 """
 
 from __future__ import annotations
@@ -33,14 +40,22 @@ from typing import TYPE_CHECKING, Protocol, runtime_checkable
 from src.core.events import Event
 
 if TYPE_CHECKING:  # pragma: no cover - typing only
-    from mem0 import Memory
+    from mem0 import Memory, MemoryClient
 
-#: Env gate. Set to a truthy value to activate the semantic index; unset (the
+#: Env gate. Set to a truthy value to activate the local semantic index, or to a
+#: cloud spelling (see :data:`_CLOUD_VALUES`) for the hosted backend; unset (the
 #: default) keeps memory on the offline keyword path with nothing imported.
 INDEX_ENV = "MEMORY_INDEX"
 
-#: Truthy spellings accepted for the gate and boolean sub-options.
-_TRUTHY: frozenset[str] = frozenset({"1", "true", "yes", "on", "mem0"})
+#: Optional explicit backend selector (``local`` | ``cloud``). Takes precedence
+#: over the spelling of ``MEMORY_INDEX`` when set.
+BACKEND_ENV = "MEMORY_INDEX_BACKEND"
+
+#: Truthy spellings accepted for the gate and boolean sub-options (→ local backend).
+_TRUTHY: frozenset[str] = frozenset({"1", "true", "yes", "on", "mem0", "local"})
+
+#: Spellings of ``MEMORY_INDEX`` that select the hosted mem0 platform backend.
+_CLOUD_VALUES: frozenset[str] = frozenset({"cloud", "mem0-cloud", "platform", "hosted"})
 
 #: Default mem0 config when ``MEMORY_INDEX_CONFIG`` is unset: embed LOCALLY with
 #: sentence-transformers (no API key; fully offline once the model is cached), so
@@ -79,7 +94,7 @@ class MemoryIndex(Protocol):
         ...
 
 
-# ── mem0 backend ────────────────────────────────────────────────────────────
+# ── shared event ⇄ entry helpers ──────────────────────────────────────────────
 
 
 def _event_text(event: Event) -> str:
@@ -87,77 +102,60 @@ def _event_text(event: Event) -> str:
     return str(event.payload.get("text") or event.payload.get("summary") or event.payload)
 
 
-class Mem0MemoryIndex:
-    """Semantic :class:`MemoryIndex` backed by the ``mem0`` vector memory.
+# ── shared mem0 backend base ──────────────────────────────────────────────────
 
-    Derived, not authoritative. Each ledger event is upserted as one raw memory
-    (``infer=False`` — text is stored verbatim, **no model extraction**, so
-    indexing is deterministic and the ledger stays the source of truth) carrying
-    the full event in ``metadata`` so a search hit reconstructs the original
-    :class:`Event` without a second lookup. The entry id is the ``event.id``, so
-    re-indexing the same event updates in place rather than duplicating — the
-    index is rebuildable from the ledger.
 
-    Configuration (env, read by :func:`memory_index_from_env`):
+class _Mem0BackendBase:
+    """Shared :class:`MemoryIndex` machinery for the mem0-backed indexes.
 
-      * ``MEMORY_INDEX`` — gate; truthy activates the index, unset disables it.
-      * Embeddings — run LOCALLY by default via sentence-transformers (no API
-        key, fully offline once the model is cached); see :data:`_LOCAL_INDEX_CONFIG`.
-        Install the backend with ``uv sync --extra memory``.
-      * ``MEMORY_INDEX_CONFIG`` — optional JSON config forwarded verbatim to
-        ``mem0.Memory.from_config``, replacing the local default. Use it to pick a
-        different embedder or to persist vectors in the project's own
-        Postgres/pgvector (the durable store from ADR-0014) instead of the default
-        in-process vector store, so the index lives beside the ledger it derives
-        from.
-
-    ``mem0`` is imported lazily inside :meth:`_memory` so ``import src.*`` and
-    ``import app`` work with the package not installed.
+    Subclasses supply the three variation points — how the client is built and
+    how a single event is stored / queried — while this base owns the protocol
+    surface that keeps the index *derived*: idempotent upsert keyed by
+    ``event.id`` and search-hit → :class:`Event` reconstruction from metadata.
     """
 
-    #: mem0 scopes memories to a session id; the index is engine-wide, so a fixed
+    #: mem0 scopes memories to an id; the index is engine-wide, so a fixed
     #: namespace keeps every event in one searchable space.
     _NAMESPACE = "ledger"
 
-    def __init__(self, config: dict | None = None) -> None:
-        self._config = config
-        self._mem: "Memory | None" = None
+    def __init__(self) -> None:
+        self._mem: object | None = None
         self._indexed: set[str] = set()
 
-    # ── lazy construction ─────────────────────────────────────────────────────
+    # ── variation points (subclass) ───────────────────────────────────────────
 
-    def _memory(self) -> "Memory":
-        """Construct (once) and return the underlying ``mem0`` memory.
+    def _build_memory(self) -> object:
+        """Construct the underlying mem0 client (lazy-imported by the subclass)."""
+        raise NotImplementedError
 
-        With no explicit config, the local sentence-transformers default
-        (:data:`_LOCAL_INDEX_CONFIG`) is used — never mem0's cloud-keyed default —
-        so an activated index stays fully offline.
-        """
-        if self._mem is None:
-            from mem0 import Memory  # lazy: offline import must not require mem0
+    def _store(self, mem: object, event: Event) -> None:
+        """Upsert one event verbatim into *mem* (``infer=False``; ledger is truth)."""
+        raise NotImplementedError
+
+    def _query(self, mem: object, query: str, k: int) -> list[dict]:
+        """Run semantic search on *mem*; return raw hit dicts (carrying metadata)."""
+        raise NotImplementedError
 
-            self._mem = Memory.from_config(self._config or _LOCAL_INDEX_CONFIG)
+    # ── lazy construction ─────────────────────────────────────────────────────
+
+    def _memory(self) -> object:
+        if self._mem is None:
+            self._mem = self._build_memory()
         return self._mem
 
     # ── MemoryIndex protocol ──────────────────────────────────────────────────
 
     def index(self, events: tuple[Event, ...]) -> None:
-        """Upsert *events* into the vector store, keyed by ``event.id``.
+        """Upsert *events*, keyed by ``event.id`` — idempotent within the process.
 
-        Idempotent: an ``event.id`` already indexed in this process is skipped, so
-        re-indexing the same ledger slice each turn does not duplicate entries.
-        """
+        Dedup happens *before* the client is built, so re-indexing the same
+        ledger slice each turn never re-embeds and never forces a mem0 import."""
         fresh = [e for e in events if e.id not in self._indexed]
         if not fresh:
             return
         mem = self._memory()
         for event in fresh:
-            mem.add(
-                _event_text(event),
-                user_id=self._NAMESPACE,
-                metadata=_event_metadata(event),
-                infer=False,  # store verbatim; the ledger, not a model, is truth
-            )
+            self._store(mem, event)
             self._indexed.add(event.id)
 
     def search(self, query: str, k: int) -> list[Event]:
@@ -165,15 +163,133 @@ class Mem0MemoryIndex:
         if not query or k <= 0:
             return []
         mem = self._memory()
-        hits = mem.search(query, top_k=k, filters={"user_id": self._NAMESPACE})
         events: list[Event] = []
-        for hit in _result_items(hits):
+        for hit in self._query(mem, query, k):
             event = _event_from_metadata(hit.get("metadata"))
             if event is not None:
                 events.append(event)
         return events
 
 
+# ── local (off-the-grid) backend ─────���────────────────────────────────────────
+
+
+class Mem0MemoryIndex(_Mem0BackendBase):
+    """Local semantic :class:`MemoryIndex` backed by the ``mem0`` OSS ``Memory``.
+
+    Derived, not authoritative, and **off the grid**: each ledger event is
+    upserted as one raw memory (``infer=False`` — text stored verbatim, **no
+    model extraction**) carrying the full event in ``metadata`` so a search hit
+    reconstructs the :class:`Event` without a second lookup. Embeddings run
+    locally via sentence-transformers by default (:data:`_LOCAL_INDEX_CONFIG`).
+
+    Configuration (env, read by :func:`memory_index_from_env`):
+
+      * ``MEMORY_INDEX`` — gate; truthy (``1``/``true``/``local``/…) activates this
+        backend, unset disables it.
+      * ``MEMORY_INDEX_CONFIG`` — optional JSON config forwarded verbatim to
+        ``mem0.Memory.from_config``, replacing the local default (pick a different
+        embedder, or persist vectors in the project's Postgres/pgvector, ADR-0014).
+
+    ``mem0`` is imported lazily inside :meth:`_build_memory` so ``import src.*`` and
+    ``import app`` work with the package not installed.
+    """
+
+    def __init__(self, config: dict | None = None) -> None:
+        super().__init__()
+        self._config = config
+
+    def _build_memory(self) -> "Memory":
+        from mem0 import Memory  # lazy: offline import must not require mem0
+
+        return Memory.from_config(self._config or _LOCAL_INDEX_CONFIG)
+
+    def _store(self, mem: object, event: Event) -> None:
+        mem.add(  # type: ignore[attr-defined]
+            _event_text(event),
+            user_id=self._NAMESPACE,
+            metadata=_event_metadata(event),
+            infer=False,  # store verbatim; the ledger, not a model, is truth
+        )
+
+    def _query(self, mem: object, query: str, k: int) -> list[dict]:
+        return _result_items(mem.search(query, top_k=k, filters={"user_id": self._NAMESPACE}))  # type: ignore[attr-defined]
+
+
+# ── hosted (opt-in) backend ────────────────────────────────────────────────────
+
+
+class Mem0CloudIndex(_Mem0BackendBase):
+    """Hosted semantic :class:`MemoryIndex` backed by the ``mem0`` platform.
+
+    Wraps ``mem0.MemoryClient`` (api.mem0.ai): embeddings, the vector store, and
+    retrieval all live in mem0's managed service. The :class:`MemoryIndex`
+    contract is identical to the local backend — derived, idempotent, ledger is
+    truth — and events are still stored verbatim (``infer=False``) with the full
+    event in ``metadata`` for reconstruction. The only difference is *where* the
+    work happens.
+
+    **Off-the-grid caveat (ADR-0019/0020).** Activating this backend sends ledger
+    event text to mem0's servers and requires a ``MEM0_API_KEY``. It is therefore
+    strictly opt-in and never the default; the local backend remains the engine's
+    off-the-grid default.
+
+    Configuration (env, read by :func:`memory_index_from_env`):
+
+      * ``MEMORY_INDEX=cloud`` (or ``MEMORY_INDEX_BACKEND=cloud``) — selects this
+        backend.
+      * ``MEM0_API_KEY`` — required platform key (falls back to the client's own
+        ``MEM0_API_KEY`` env read if not passed explicitly).
+      * ``MEM0_ORG_ID`` / ``MEM0_PROJECT_ID`` / ``MEM0_HOST`` — optional scoping.
+
+    ``mem0`` is imported lazily inside :meth:`_build_memory`, so the offline path
+    needs neither the package nor a key.
+    """
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        org_id: str | None = None,
+        project_id: str | None = None,
+        host: str | None = None,
+    ) -> None:
+        super().__init__()
+        self._api_key = api_key
+        self._org_id = org_id
+        self._project_id = project_id
+        self._host = host
+
+    def _build_memory(self) -> "MemoryClient":
+        from mem0 import MemoryClient  # lazy: offline import must not require mem0
+
+        # Pass only what is set; MemoryClient falls back to MEM0_API_KEY from the
+        # environment and raises loudly here (not at import) if no key is found.
+        kwargs = {
+            k: v
+            for k, v in {
+                "api_key": self._api_key,
+                "org_id": self._org_id,
+                "project_id": self._project_id,
+                "host": self._host,
+            }.items()
+            if v
+        }
+        return MemoryClient(**kwargs)
+
+    def _store(self, mem: object, event: Event) -> None:
+        # The platform `add` takes chat-style messages; one verbatim user turn per
+        # event, inference disabled so nothing but the ledger text is stored.
+        mem.add(  # type: ignore[attr-defined]
+            [{"role": "user", "content": _event_text(event)}],
+            user_id=self._NAMESPACE,
+            metadata=_event_metadata(event),
+            infer=False,
+        )
+
+    def _query(self, mem: object, query: str, k: int) -> list[dict]:
+        return _result_items(mem.search(query, user_id=self._NAMESPACE, top_k=k))  # type: ignore[attr-defined]
+
+
 # ── metadata round-trip (event ⇄ vector entry) ────────────────────────────────
 
 
@@ -210,10 +326,11 @@ def _event_from_metadata(metadata: dict | None) -> Event | None:
 
 
 def _result_items(hits: object) -> list[dict]:
-    """Normalise ``mem0.search`` output to a list of hit dicts.
+    """Normalise mem0 ``search`` output to a list of hit dicts.
 
-    ``mem0`` returns either ``{"results": [...]}`` (v1.1+) or a bare list,
-    depending on version/config; accept both so the backend is version-tolerant.
+    Both the OSS ``Memory`` and the platform ``MemoryClient`` return either
+    ``{"results": [...]}`` or a bare list depending on version/config; accept both
+    so the backends are version-tolerant.
     """
     if isinstance(hits, dict):
         results = hits.get("results", [])
@@ -230,16 +347,34 @@ def _is_truthy(value: str | None) -> bool:
 
 
 def memory_index_from_env(env: dict[str, str] | None = None) -> MemoryIndex | None:
-    """Build a :class:`Mem0MemoryIndex` from the env gate, or ``None`` if unset.
+    """Build a mem0-backed :class:`MemoryIndex` from the env, or ``None`` if unset.
+
+    Selection (``mem0`` is only imported later, on first use):
 
-    Returns ``None`` (the offline default the suite exercises) unless
-    ``MEMORY_INDEX`` is truthy. ``mem0`` is only imported later, on first use, so
-    a truthy gate without the package installed still imports cleanly and fails
-    loudly only when the index is actually exercised.
+      * gate unset / falsey → ``None`` (the offline keyword path the suite exercises).
+      * ``MEMORY_INDEX`` truthy (``1``/``true``/``local``/…) → :class:`Mem0MemoryIndex`
+        (local sentence-transformers; off the grid).
+      * ``MEMORY_INDEX`` ∈ {cloud, mem0-cloud, platform, hosted}, or
+        ``MEMORY_INDEX_BACKEND=cloud`` → :class:`Mem0CloudIndex` (hosted; sends
+        ledger text to mem0). An explicit ``MEMORY_INDEX_BACKEND`` wins over the
+        ``MEMORY_INDEX`` spelling.
     """
     source = os.environ if env is None else env
-    if not _is_truthy(source.get(INDEX_ENV)):
+    gate = (source.get(INDEX_ENV) or "").strip().lower()
+    backend = (source.get(BACKEND_ENV) or "").strip().lower()
+
+    is_cloud = backend == "cloud" or gate in _CLOUD_VALUES
+    if not (is_cloud or _is_truthy(gate)):
         return None
+
+    if is_cloud:
+        return Mem0CloudIndex(
+            api_key=source.get("MEM0_API_KEY") or None,
+            org_id=source.get("MEM0_ORG_ID") or None,
+            project_id=source.get("MEM0_PROJECT_ID") or None,
+            host=source.get("MEM0_HOST") or None,
+        )
+
     raw_config = (source.get("MEMORY_INDEX_CONFIG") or "").strip()
     config: dict | None = None
     if raw_config:

tests/test_memory_index.py

@@ -22,6 +22,7 @@ from src.core.events import Event
 from src.core.manifest import AgentManifest, MemoryConfig
 from src.core.memory import SalienceMemory
 from src.core.memory_index import (
+    Mem0CloudIndex,
     Mem0MemoryIndex,
     MemoryIndex,
     memory_index_from_env,
@@ -72,6 +73,10 @@ class TestProtocol:
         # No mem0 import needed: the backend is constructed lazily.
         assert isinstance(Mem0MemoryIndex(), MemoryIndex)
 
+    def test_cloud_backend_is_memory_index(self):
+        # No mem0 import needed: the platform client is constructed lazily.
+        assert isinstance(Mem0CloudIndex(), MemoryIndex)
+
 
 # ── layering: index drives the relevance term, recency/importance intact ────────
 
@@ -155,6 +160,13 @@ class TestIdempotentIndexing:
         # raise (mem0 may be absent), so reaching it on a dup would surface here.
         backend.index((_event("world.observed", eid="e1"),))  # no-op, no import
 
+    def test_cloud_backend_skips_already_indexed_ids(self):
+        """Cloud dedup is identical and happens before the client is built — so a
+        repeat id is a no-op with mem0 absent and no MEM0_API_KEY set."""
+        backend = Mem0CloudIndex()
+        backend._indexed.add("e1")
+        backend.index((_event("world.observed", eid="e1"),))  # no-op, no import/key
+
 
 # ── env gate (no mem0 required) ──────────────────────────────────────────────────
 
@@ -175,6 +187,31 @@ class TestEnvGate:
         assert isinstance(idx, Mem0MemoryIndex)
         assert idx._config == {"version": "v1.1"}
 
+    def test_truthy_gate_selects_local_not_cloud(self):
+        assert isinstance(memory_index_from_env({"MEMORY_INDEX": "1"}), Mem0MemoryIndex)
+
+    def test_cloud_spelling_selects_hosted_backend(self):
+        for spelling in ("cloud", "mem0-cloud", "platform", "hosted"):
+            idx = memory_index_from_env({"MEMORY_INDEX": spelling})
+            assert isinstance(idx, Mem0CloudIndex), spelling
+
+    def test_backend_env_overrides_local_gate(self):
+        # Explicit MEMORY_INDEX_BACKEND=cloud wins even when the gate spells local.
+        idx = memory_index_from_env({"MEMORY_INDEX": "1", "MEMORY_INDEX_BACKEND": "cloud"})
+        assert isinstance(idx, Mem0CloudIndex)
+
+    def test_cloud_reads_credentials_from_env(self):
+        idx = memory_index_from_env(
+            {
+                "MEMORY_INDEX": "cloud",
+                "MEM0_API_KEY": "k-123",
+                "MEM0_ORG_ID": "org-1",
+                "MEM0_PROJECT_ID": "proj-1",
+            }
+        )
+        assert isinstance(idx, Mem0CloudIndex)
+        assert (idx._api_key, idx._org_id, idx._project_id) == ("k-123", "org-1", "proj-1")
+
 
 # ── agent wiring: _recall threads the index into salience ────────────────────────
 
@@ -237,3 +274,28 @@ class TestMem0RoundTrip:
         hit = next(h for h in hits if h.id == "rt1")
         assert hit.kind == "world.observed"
         assert hit.payload.get("text", "").startswith("golden spores")
+
+
+# ── guarded real-mem0-CLOUD round-trip (requires mem0 + MEM0_API_KEY) ────────────
+
+
+class TestMem0CloudRoundTrip:
+    def test_index_then_search_recovers_event(self):
+        pytest.importorskip("mem0")
+        # Opt-in: this hits the hosted mem0 platform and sends text off-machine, so
+        # it only runs when explicitly enabled with a real key.
+        if not (os.getenv("MEM0_API_KEY") and os.getenv("MEM0_CLOUD_E2E")):
+            pytest.skip("set MEM0_API_KEY and MEM0_CLOUD_E2E=1 to run the hosted round-trip")
+
+        backend = Mem0CloudIndex()  # reads MEM0_API_KEY from the environment
+        ev = _event("world.observed", turn=1, text="golden spores drift over the glass forest", eid="rtc1")
+        try:
+            backend.index((ev,))
+            hits = backend.search("golden spores", k=5)
+        except Exception as exc:  # pragma: no cover - environment dependent
+            pytest.skip(f"mem0 cloud unavailable: {exc}")
+
+        assert any(h.id == "rtc1" for h in hits)
+        hit = next(h for h in hits if h.id == "rtc1")
+        assert hit.kind == "world.observed"
+        assert hit.payload.get("text", "").startswith("golden spores")