Surface mem0_notice for unclaimed Agent Mode keys + docs

CLI now consumes the unified mem0_notice surface that the platform side
emits for unclaimed Agent Mode keys. The notice is a directive to the
LLM agent reading the output, with a verbatim sentence to relay to the
human owner. Two presentation paths:

- Human/text output: yellow stderr banner after the primary output,
  once per command. Skipped in agent mode (the JSON envelope carries
  it instead, so no duplication).
- JSON/agent output (--json/--agent): folded into the envelope as
  "mem0_notice" so an agent parsing the output sees it without
  inspecting HTTP headers.

CLI changes (Python + Node, kept in lockstep):
- state.{ts,py}: captureNotice / takeNotice helpers — last-write-wins
  stash so multi-request commands fire the notice exactly once.
- backend/platform.{ts,py}: _request extracts notice from response
  bodies (top-level dict or list[0]) with header fallback, strips
  from downstream payload, captures for end-of-command surfacing.
- output.{ts,py}: JSON envelope formatters fold in any pending notice.
- index.ts / app.py: entrypoint surfaces notice on exit when not in
  agent mode.
- commands/agent-mode.{ts,py}: init success path prints the platform's
  notice verbatim (fallback to dim claim-command line if a stale
  backend doesn't return it).

Init-flag handling fix: the Python argv preprocessor was stripping
--agent from sys.argv unconditionally as the global JSON-output alias.
That swallowed `mem0 init --agent` (where --agent is a subcommand flag
for unattended bootstrap). Now preserved when "init" is in argv.

Parity tests: cli/python/tests/test_agent_mode.py and
cli/node/tests/agent-mode.test.ts — 7 tests each, kept in sync.

cli-spec.json updated: init now lists --agent and --source.

Docs:
- README.md: Agent Mode promo at top of Quickstart.
- docs/llms.txt: fast-path block for AI agents reading the docs.
- skills/mem0/SKILL.md, skills/mem0-cli/SKILL.md,
  skills/mem0-integrate/SKILL.md, mem0-plugin/skills/mem0/SKILL.md:
  autonomous-setup section + fallback hints.
- mem0-plugin/README.md, openclaw/README.md: "Quick path for agents"
  blocks above the human Quick Start.

cli/python/src/mem0_cli/app.py

@@ -856,7 +856,9 @@ def init(
         False, "--agent", help="Bootstrap an unattended Agent Mode account (no email required)."
     ),
     source: str | None = typer.Option(
-        None, "--source", help="Channel attribution for signup (e.g. github, hn, ph).",
+        None,
+        "--source",
+        help="Channel attribution for signup (e.g. github, hn, ph).",
     ),
 ) -> None:
     """Interactive setup wizard for mem0 CLI.
@@ -1215,11 +1217,28 @@ def main() -> None:
     import sys
 
     # Allow --json/--agent anywhere in the command line (not just before subcommand).
-    _json_flags = {"--json", "--agent"}
-    if any(a in _json_flags for a in sys.argv[1:]):
+    # Special case: `mem0 init --agent` is a subcommand flag (Agent Mode bootstrap)
+    # consumed by init_cmd, not a global JSON-output toggle — leave it in argv.
+    argv_rest = sys.argv[1:]
+    is_init = "init" in argv_rest
+    _global_flags = {"--json"} if is_init else {"--json", "--agent"}
+    if any(a in _global_flags for a in argv_rest):
         from mem0_cli.state import set_agent_mode
 
         set_agent_mode(True)
-        sys.argv = [sys.argv[0]] + [a for a in sys.argv[1:] if a not in _json_flags]
+        sys.argv = [sys.argv[0]] + [a for a in argv_rest if a not in _global_flags]
 
-    app()
+    try:
+        app()
+    finally:
+        # Surface any unclaimed Agent Mode notice once per command, after the
+        # primary output. In JSON/agent mode the notice is folded into the
+        # envelope by format_json_envelope, so skip the stderr banner there
+        # to avoid duplicate output.
+        from mem0_cli.state import is_agent_mode, take_notice
+
+        notice = take_notice()
+        if notice and not is_agent_mode():
+            from rich.console import Console
+
+            Console(stderr=True).print(f"\n[yellow]🔔 {notice}[/yellow]\n")

cli/python/src/mem0_cli/backend/platform.py

@@ -30,7 +30,7 @@ class PlatformBackend(Backend):
         )
 
     def _request(self, method: str, path: str, **kwargs: Any) -> Any:
-        from mem0_cli.state import is_agent_mode
+        from mem0_cli.state import capture_notice, is_agent_mode
 
         self._client.headers["X-Mem0-Caller-Type"] = "agent" if is_agent_mode() else "user"
         resp = self._client.request(method, path, **kwargs)
@@ -48,7 +48,26 @@ class PlatformBackend(Backend):
         resp.raise_for_status()
         if resp.status_code == 204:
             return {}
-        return resp.json()
+        data = resp.json()
+
+        # Pull the unclaimed-Agent-Mode notice out of the body (or the header
+        # fallback for endpoints that return non-dict / non-dict-leading
+        # payloads) and stash it for end-of-command surfacing.
+        notice = None
+        if isinstance(data, dict) and "mem0_notice" in data:
+            notice = data.pop("mem0_notice")
+        elif (
+            isinstance(data, list)
+            and data
+            and isinstance(data[0], dict)
+            and "mem0_notice" in data[0]
+        ):
+            notice = data[0].pop("mem0_notice")
+        if notice is None:
+            notice = resp.headers.get("X-Mem0-Notice-Message") or None
+        capture_notice(notice)
+
+        return data
 
     def add(
         self,

cli/python/src/mem0_cli/commands/agent_mode_cmd.py

@@ -15,7 +15,6 @@ from mem0_cli.branding import (
     BRAND_COLOR,
     DIM_COLOR,
     print_error,
-    print_info,
     print_success,
 )
 from mem0_cli.config import Mem0Config, save_config
@@ -81,7 +80,13 @@ def bootstrap_via_backend(
     save_config(config)
 
     print_success(console, f"Agent Mode active. Default user_id: {envelope['default_user_id']}")
-    console.print(f"  [{DIM_COLOR}]To claim this account later: {envelope.get('claim_command', 'mem0 init --email <your-email>')}[/]")
+    notice = envelope.get("mem0_notice")
+    if notice:
+        console.print(f"\n[yellow]🔔 {notice}[/yellow]\n")
+    else:
+        # Fallback if the backend hasn't deployed the unified notice yet.
+        claim_cmd = envelope.get("claim_command", "mem0 init --email <your-email>")
+        console.print(f"  [{DIM_COLOR}]To claim this account later: {claim_cmd}[/]")
 
 
 def claim_via_otp(config: Mem0Config, *, email: str, code: str | None = None) -> None:
@@ -161,7 +166,9 @@ def claim_via_otp(config: Mem0Config, *, email: str, code: str | None = None) ->
             code_str = ""
         print_error(err_console, f"Claim failed: {detail}")
         if code_str == "email_already_claimed":
-            console.print(f"  [{DIM_COLOR}]Tip: this email already has a Mem0 account. Sign in there and run `mem0 link <key>` to attach this agent.[/]")
+            console.print(
+                f"  [{DIM_COLOR}]Tip: this email already has a Mem0 account. Sign in there and run `mem0 link <key>` to attach this agent.[/]"
+            )
         raise typer.Exit(1)
 
     body = verify.json()

cli/python/src/mem0_cli/output.py

@@ -229,6 +229,16 @@ def format_json_envelope(
     if error:
         envelope["error"] = error
     envelope["data"] = data
+
+    # If the platform flagged this as an unclaimed Agent Mode account, surface
+    # the notice inside the JSON envelope so an agent consuming the output
+    # sees it without needing to inspect HTTP headers.
+    from mem0_cli.state import take_notice
+
+    notice = take_notice()
+    if notice:
+        envelope["mem0_notice"] = notice
+
     console.print_json(json.dumps(envelope, default=str))
 
 
@@ -323,6 +333,15 @@ def format_agent_envelope(
     if count is not None:
         envelope["count"] = count
     envelope["data"] = sanitize_agent_data(command, data)
+
+    # Surface the unclaimed-Agent-Mode notice (if any) in the envelope so an
+    # agent reading the JSON output sees it without inspecting HTTP headers.
+    from mem0_cli.state import take_notice
+
+    notice = take_notice()
+    if notice:
+        envelope["mem0_notice"] = notice
+
     console.print_json(json.dumps(envelope, default=str))
 
 

cli/python/src/mem0_cli/state.py

@@ -4,6 +4,7 @@ from __future__ import annotations
 
 _agent_mode: bool = False
 _current_command: str = ""
+_pending_notice: str = ""
 
 
 def is_agent_mode() -> bool:
@@ -22,3 +23,23 @@ def get_current_command() -> str:
 def set_current_command(name: str) -> None:
     global _current_command
     _current_command = name
+
+
+def capture_notice(notice: str | None) -> None:
+    """Stash a Mem0 backend notice for end-of-command surfacing.
+
+    Called from the platform backend after each response so the notice can
+    be printed once per command (regardless of how many sub-requests fired).
+    Last-write-wins is fine — the message text is identical across requests.
+    """
+    global _pending_notice
+    if notice:
+        _pending_notice = notice
+
+
+def take_notice() -> str:
+    """Return and clear the pending notice."""
+    global _pending_notice
+    msg = _pending_notice
+    _pending_notice = ""
+    return msg

cli/python/tests/test_agent_mode.py

@@ -0,0 +1,157 @@
+"""Parity tests for `mem0 init --agent` (Agent Mode bootstrap).
+
+Mirror of ``cli/node/tests/agent-mode.test.ts`` — both files MUST stay in
+sync so that the Python and Node CLIs expose an identical surface for the
+Agent Mode entrypoint. If you add a flag here, add the same assertion on
+the Node side (and vice versa).
+
+Network-bound bootstrap is covered by the platform-side E2E suite
+(``backend/tests/e2e/test_05_agent_mode.py``); these tests only verify
+the CLI surface that ships in the binary.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+import subprocess
+import sys
+
+import pytest
+
+_ANSI_RE = re.compile(r"\x1b\[[0-9;]*[mKJHABCDfsu]")
+
+
+def _strip_ansi(text: str) -> str:
+    return _ANSI_RE.sub("", text)
+
+
+def _run(args: list[str], home_dir: str | None = None) -> subprocess.CompletedProcess:
+    env = os.environ.copy()
+    for key in list(env.keys()):
+        if key.startswith("MEM0_"):
+            del env[key]
+    env.pop("FORCE_COLOR", None)
+    if home_dir:
+        env["HOME"] = home_dir
+    result = subprocess.run(
+        [sys.executable, "-m", "mem0_cli", *args],
+        capture_output=True,
+        text=True,
+        env=env,
+        timeout=15,
+    )
+    return subprocess.CompletedProcess(
+        args=result.args,
+        returncode=result.returncode,
+        stdout=_strip_ansi(result.stdout),
+        stderr=_strip_ansi(result.stderr),
+    )
+
+
+@pytest.fixture
+def clean_home(tmp_path):
+    return str(tmp_path)
+
+
+class TestInitFlagSurface:
+    """`mem0 init --help` must expose the Agent Mode flags."""
+
+    def test_init_help_lists_agent_flag(self):
+        result = _run(["init", "--help"])
+        assert result.returncode == 0
+        assert "--agent" in result.stdout
+
+    def test_init_help_describes_agent_mode(self):
+        result = _run(["init", "--help"])
+        assert result.returncode == 0
+        # Description must mention what --agent actually does so an agent
+        # reading the help can self-discover the bootstrap entrypoint.
+        assert "Agent Mode" in result.stdout or "unattended" in result.stdout.lower()
+
+    def test_init_help_lists_source_flag(self):
+        result = _run(["init", "--help"])
+        assert result.returncode == 0
+        assert "--source" in result.stdout
+
+    def test_init_help_lists_email_and_code(self):
+        # Claim flow flags must remain present alongside Agent Mode flags.
+        result = _run(["init", "--help"])
+        assert result.returncode == 0
+        assert "--email" in result.stdout
+        assert "--code" in result.stdout
+
+
+class TestArgvPreprocessing:
+    """`--agent` on `init` must reach init_cmd, not be eaten by the global preprocessor.
+
+    Regression for the bug where the top-level `--agent` JSON-alias was
+    stripped from ``sys.argv`` before Typer could bind it to the init
+    subcommand, making ``mem0 init --agent`` indistinguishable from a
+    plain ``mem0 init`` (interactive wizard).
+    """
+
+    def test_init_with_agent_reaches_subcommand(self, clean_home):
+        # We can't hit a real backend in unit tests, so we point the CLI at
+        # a guaranteed-dead URL and assert the failure is the bootstrap
+        # request failing — proving the --agent flag was honored and the
+        # bootstrap branch ran, not the interactive wizard.
+        result = subprocess.run(
+            [sys.executable, "-m", "mem0_cli", "init", "--agent"],
+            capture_output=True,
+            text=True,
+            env={
+                **{k: v for k, v in os.environ.items() if not k.startswith("MEM0_")},
+                "HOME": clean_home,
+                "MEM0_BASE_URL": "http://127.0.0.1:1",  # blackhole
+                "FORCE_COLOR": "0",
+            },
+            timeout=15,
+        )
+        combined = _strip_ansi(result.stdout + result.stderr).lower()
+        # Either we got a connection/network error from the bootstrap POST,
+        # or the CLI surfaced an Agent Mode-specific failure message.
+        assert (
+            "agent" in combined
+            or "connect" in combined
+            or "network" in combined
+            or "fetch" in combined
+            or "bootstrap" in combined
+        ), f"Expected bootstrap attempt, got: {combined!r}"
+
+
+class TestJsonEnvelopeParity:
+    """`mem0 init --agent --json` should produce a JSON envelope on success.
+
+    Without a live backend we can only assert the failure shape: when the
+    backend is unreachable, the CLI must still exit non-zero AND not crash
+    on a Python traceback (which would mean we leaked an exception past
+    the agent-mode handler).
+    """
+
+    def test_init_agent_json_no_traceback_on_network_failure(self, clean_home):
+        result = subprocess.run(
+            [sys.executable, "-m", "mem0_cli", "init", "--agent", "--json"],
+            capture_output=True,
+            text=True,
+            env={
+                **{k: v for k, v in os.environ.items() if not k.startswith("MEM0_")},
+                "HOME": clean_home,
+                "MEM0_BASE_URL": "http://127.0.0.1:1",
+                "FORCE_COLOR": "0",
+            },
+            timeout=15,
+        )
+        combined = _strip_ansi(result.stdout + result.stderr)
+        assert "Traceback (most recent call last)" not in combined
+        assert result.returncode != 0
+
+
+class TestInitInCommandList:
+    """`mem0 --help` must list `init` so agents walking the top-level help
+    can discover the Agent Mode entrypoint without prior knowledge."""
+
+    def test_top_level_help_lists_init(self):
+        result = _run(["--help"])
+        assert result.returncode == 0
+        assert "init" in result.stdout