memorysync-cli 1.0.3__tar.gz → 1.1.1__tar.gz

{memorysync_cli-1.0.3 → memorysync_cli-1.1.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: memorysync-cli
-Version: 1.0.3
+Version: 1.1.1
 Summary: MemorySync from your terminal. Zero dependencies.
 Project-URL: Documentation, https://docs.memorysync.io/cli
 Project-URL: Homepage, https://memorysync.io/cli

memorysync_cli-1.1.1/src/memorysync_cli/_version.py

@@ -0,0 +1 @@
+__version__ = "1.1.1"

{memorysync_cli-1.0.3 → memorysync_cli-1.1.1}/src/memorysync_cli/commands/admin.py

@@ -20,8 +20,18 @@ from .. import config as config_module
 from .. import credentials
 from .._version import __version__
 from ..errors import usage_error
+from ..evaluation import is_evaluation_key
 from ..output import render_table, style
 
+#: Keys ``config set`` / ``config unset`` accept. Identical to the Node CLI's
+#: ``SETTABLE``; ``output`` was previously missing here, so `config set output table`
+#: worked under one CLI and was refused by the other.
+#:
+#: ``api_key`` is deliberately absent. Keys go to the keychain through ``init``, and
+#: accepting one here would write a credential into a file people paste into bug
+#: reports.
+_SETTABLE = frozenset({"user", "project", "base_url", "output", "timeout"})
+
 
 def _percent(used: Any, limit: Any) -> str:
     if not isinstance(used, (int, float)) or not isinstance(limit, (int, float)) or limit <= 0:
@@ -29,6 +39,38 @@ def _percent(used: Any, limit: Any) -> str:
     return f"{min(100, round(used / limit * 100))}%"
 
 
+def _evaluation_usage_summary(api: Any) -> dict:
+    """Reshape ``/evaluation/usage`` into what ``quota`` already renders.
+
+    Same keys the billing summary returns, so the renderer and ``--json`` consumers
+    do not have to care which kind of key they are looking at. Mirrors the Node
+    CLI's ``evaluationQuota``.
+    """
+    usage = api.evaluation_usage() or {}
+    add = usage.get("add_requests") or {}
+    retrieval = usage.get("retrieval_requests") or {}
+    return {
+        "plan_id": usage.get("plan"),
+        "metrics": [
+            {
+                "metric": "add_requests",
+                "label": "Memories added",
+                "used": add.get("used"),
+                "limit": add.get("limit"),
+            },
+            {
+                "metric": "retrieval_requests",
+                "label": "Retrievals",
+                "used": retrieval.get("used"),
+                "limit": retrieval.get("limit"),
+            },
+        ],
+        "claimed": usage.get("claimed") is True,
+        "expires_at": usage.get("expires_at"),
+        "claim_command": usage.get("claim_command"),
+    }
+
+
 def quota(ctx: dict) -> dict:
     """Plan usage, with headroom made explicit.
 
@@ -36,7 +78,17 @@ def quota(ctx: dict) -> dict:
     Mem0, Supermemory or Zep expose this from their CLI.
     """
     api = ctx["api"]
-    summary = api.usage_summary() or {}
+
+    if is_evaluation_key(ctx.get("api_key")):
+        # ``/org/billing/usage-summary`` needs the ``billing.view`` capability and
+        # the ``billing:read`` scope, and an evaluation key is granted neither on
+        # purpose: ``billing:read`` also opens ``GET /org/billing/profit``, which
+        # returns cost and margin from our internal pricing model. The server
+        # exposes the same counters without the priced fields, so route there.
+        summary = _evaluation_usage_summary(api)
+    else:
+        summary = api.usage_summary() or {}
+
     metrics = [m for m in (summary.get("metrics") or []) if isinstance(m, dict)]
 
     rows = [
@@ -71,6 +123,15 @@ def quota(ctx: dict) -> dict:
                 for row in rows
             ],
         )
+        # An evaluation allowance does not reset on a cycle: the key stops working
+        # at expiry, so that is the date worth printing. Matches the Node CLI.
+        expiry_note = ""
+        if summary.get("expires_at") and not summary.get("claimed"):
+            expiry_note = "\n" + style.yellow(
+                "Unclaimed evaluation key, expires "
+                f"{str(summary['expires_at'])[:10]}."
+            )
+
         exhausted = [r["metric"] for r in rows if r["remaining"] == 0]
         if exhausted:
             warning = style.yellow(
@@ -80,8 +141,8 @@ def quota(ctx: dict) -> dict:
                 "Writes and reads return empty rather than failing, so check here "
                 "before assuming memory is missing."
             )
-            return f"{table}\n\n{warning}\n{note}"
-        return table
+            return f"{table}\n\n{warning}\n{note}{expiry_note}"
+        return f"{table}{expiry_note}"
 
     return {"data": rows, "text": render}
 
@@ -323,41 +384,123 @@ def config_command(ctx: dict) -> dict:
             ),
         }
 
+    if sub == "profiles":
+        cfg = config_module.load()
+        current = cfg.get("current_profile", "default")
+        profiles = cfg.get("profiles", {})
+        rows = [
+            [
+                style.green("*") if name == current else " ",
+                name,
+                entry.get("user") or "-",
+                entry.get("project") or "-",
+                entry.get("base_url") or "(default)",
+            ]
+            for name, entry in profiles.items()
+        ]
+
+        def render_profiles() -> str:
+            if not rows:
+                return style.dim("No profiles. Run `memorysync init`.")
+            return render_table([" ", "profile", "user", "project", "base url"], rows)
+
+        return {
+            "data": {"current": current, "profiles": profiles},
+            "text": render_profiles,
+        }
+
+    if sub == "use-profile":
+        if len(positionals) < 2:
+            raise usage_error("Which profile?")
+        name = positionals[1]
+        cfg = config_module.load()
+        if name not in cfg.get("profiles", {}):
+            raise usage_error(
+                f'No profile named "{name}".',
+                "Run `memorysync config profiles` to see what exists, or "
+                f"`memorysync init --profile {name}` to create it.",
+            )
+        cfg["current_profile"] = name
+        config_module.save(cfg)
+        return {
+            "data": {"current_profile": name},
+            "text": lambda: f"{style.green('Switched to')} {name}",
+        }
+
+    if sub == "delete-profile":
+        if len(positionals) < 2:
+            raise usage_error("Which profile?")
+        name = positionals[1]
+        cfg = config_module.load()
+        if name not in cfg.get("profiles", {}):
+            raise usage_error(f'No profile named "{name}".')
+        del cfg["profiles"][name]
+        if cfg.get("current_profile") == name:
+            remaining = list(cfg.get("profiles", {}))
+            cfg["current_profile"] = remaining[0] if remaining else "default"
+        config_module.save(cfg)
+        # The stored credential goes with the profile. Leaving it behind would keep
+        # a usable key in the keychain for a profile the user just removed.
+        credentials.delete_key(name)
+        return {
+            "data": {"deleted": name},
+            "text": lambda: f"{style.green('Deleted profile')} {name}",
+        }
+
     if sub == "get":
         if len(positionals) < 2:
             raise usage_error("Which key?", "memorysync config get user")
         key = positionals[1]
-        settings = config_module.resolve(ctx["flags"])
-        value = settings.get(key)
+        # Reads the stored profile, not the resolved value. Matches the Node CLI:
+        # `config get` answers "what is written down", so an environment variable
+        # does not make it look as though something was saved.
+        cfg = config_module.load()
+        entry = cfg.get("profiles", {}).get(cfg.get("current_profile", "default"), {})
+        value = entry.get(key)
         return {"data": {key: value}, "text": lambda: "" if value is None else str(value)}
 
-    if sub == "set":
-        if len(positionals) < 3:
-            raise usage_error("What to set?", "memorysync config set user alice")
-        key, value = positionals[1], positionals[2]
+    if sub in {"set", "unset"}:
+        if len(positionals) < 2:
+            raise usage_error(
+                "Which key?", f"Settable: {', '.join(sorted(_SETTABLE))}"
+            )
+        key = positionals[1]
         if key in {"api_key", "apikey", "key"}:
             raise usage_error(
                 "Keys are not stored in the config file.",
                 "Run `memorysync init --api-key <key>`; it goes to the OS keychain.",
             )
-        allowed = {"user", "project", "base_url", "timeout"}
-        if key not in allowed:
+        if key not in _SETTABLE:
             raise usage_error(
-                f'Cannot set "{key}".',
-                f"One of: {', '.join(sorted(allowed))}.",
+                f'"{key}" is not settable.',
+                f"Settable keys: {', '.join(sorted(_SETTABLE))}. The API key is "
+                "never stored here; use `memorysync init`.",
             )
-
-        profile_name = ctx["settings"]["profile_name"]
-        data = config_module.load()
-        data.setdefault("profiles", {}).setdefault(profile_name, {})[key] = value
-        path = config_module.save(data)
+        if sub == "set" and len(positionals) < 3:
+            raise usage_error(f"config set {key} <value>")
+        value = positionals[2] if sub == "set" else None
+
+        cfg = config_module.load()
+        name = cfg.get("current_profile", "default")
+        entry = dict(cfg.get("profiles", {}).get(name, {}))
+        if sub == "set":
+            entry[key] = value
+        else:
+            entry.pop(key, None)
+        cfg.setdefault("profiles", {})[name] = entry
+        config_module.save(cfg)
         return {
-            "data": {"profile": profile_name, key: value, "path": str(path)},
-            "text": lambda: f"{style.green('Set')} {key} = {value} in profile {profile_name}",
+            "data": {"profile": name, key: value},
+            "text": lambda: (
+                f"{style.green('Set' if sub == 'set' else 'Unset')} {key} "
+                f"on profile {name}"
+            ),
         }
 
     if sub == "path":
         path = str(config_module.config_path())
         return {"data": {"path": path}, "text": lambda: path}
 
-    raise usage_error(f'Unknown subcommand "{sub}".', "Try show, get, set or path.")
+    raise usage_error(
+        f'Unknown subcommand "{sub}".', "Try `memorysync config show`."
+    )

memorysync_cli-1.1.1/src/memorysync_cli/commands/init.py

@@ -0,0 +1,333 @@
+"""init: store a credential and pick defaults.
+
+The key is verified against the API before it is written. Storing an unverified key
+means the next command fails with something that looks like a network problem, and
+the person has no reason to suspect the thing they just typed.
+
+It is never written to the config file in plain text. It goes to the OS keychain
+where one is reachable, and otherwise to an owner-only encrypted file, and `init`
+says which of the two happened rather than implying a keychain that was never
+there.
+"""
+
+from __future__ import annotations
+
+import getpass
+import os
+import sys
+
+from .. import config as config_module
+from .. import credentials
+from ..errors import auth_error, usage_error
+from ..evaluation import CLAIM_HINT
+from ..http import ApiClient
+from ..output import style
+
+
+def _init_as_agent(ctx: dict, profile_name: str) -> dict:
+    """``init --agent`` — mint an evaluation key with no signup.
+
+    Stores the key exactly the way the interactive path does, so every later
+    command works with no further setup, and keeps the server's generated
+    end-user id as the profile default: an agent forced to invent one will invent
+    a different one next run and then wonder where its memories went.
+    """
+    flags, settings = ctx["flags"], ctx["settings"]
+
+    # No credential yet, by definition.
+    client = ApiClient(
+        base_url=settings["base_url"], api_key=None, timeout=settings["timeout"]
+    )
+    body = {}
+    if flags.get("agent_caller"):
+        body["agent_caller"] = flags["agent_caller"]
+    minted = client.mint_evaluation_key(body) or {}
+
+    api_key = minted.get("api_key")
+    if not api_key:
+        raise auth_error(
+            "The server did not return an evaluation key.",
+            'Try again, or run "memorysync init" with a key from https://memorysync.io.',
+        )
+
+    tier = credentials.write_key(api_key, profile_name)
+
+    data = config_module.load()
+    entry = data.setdefault("profiles", {}).setdefault(profile_name, {})
+    user = flags.get("user") or minted.get("default_user_id")
+    if user:
+        entry["user"] = user
+    if minted.get("project_id"):
+        entry["project"] = minted["project_id"]
+    if settings["base_url"] != config_module.DEFAULT_BASE_URL:
+        entry["base_url"] = settings["base_url"]
+    path = config_module.save(data)
+
+    payload = {
+        "profile": profile_name,
+        "mode": "agent",
+        "api_key": api_key,
+        "default_user_id": minted.get("default_user_id"),
+        "project_id": minted.get("project_id"),
+        "plan": minted.get("plan"),
+        "claimed": False,
+        "expires_at": minted.get("expires_at"),
+        "claim_command": minted.get("claim_command") or CLAIM_HINT,
+        "limits": minted.get("limits"),
+        "mcp_url": minted.get("mcp_url"),
+        "stored_in": tier,
+        "config": str(path),
+    }
+
+    def render() -> str:
+        where = (
+            "the OS keychain" if tier == "keychain" else "an owner-only encrypted file"
+        )
+        return "\n".join(
+            [
+                style.green("Agent mode active."),
+                f"{style.dim('default user')} {payload['default_user_id'] or '-'}",
+                f"{style.dim('plan        ')} {payload['plan'] or '-'}",
+                f"{style.dim('expires     ')} {payload['expires_at'] or '-'}",
+                f"{style.dim('key stored  ')} in {where}",
+                "",
+                style.dim('Try: memorysync add "I prefer TypeScript"'),
+                "",
+                style.yellow(
+                    "Nobody owns this account yet. To keep it and everything in it:"
+                ),
+                f"  {payload['claim_command']}",
+            ]
+        )
+
+    return {"data": payload, "text": render}
+
+
+def _init_by_claiming(ctx: dict, profile_name: str) -> dict:
+    """``init --email`` — claim the evaluation account behind the stored key.
+
+    Two steps in one command, chosen by whether ``--code`` is present, because
+    that is how a person experiences it: run it, read the email, run it again with
+    the code.
+    """
+    flags, settings = ctx["flags"], ctx["settings"]
+    email = str(flags.get("email") or "").strip()
+
+    if flags.get("code"):
+        # Completing needs no credential, so this works on a machine that never
+        # held the key.
+        client = ApiClient(
+            base_url=settings["base_url"], api_key=None, timeout=settings["timeout"]
+        )
+        body = {"email": email, "code": str(flags["code"]).strip()}
+        if flags.get("password"):
+            body["password"] = str(flags["password"])
+        claimed = client.complete_evaluation_claim(body) or {}
+
+        # Recorded locally so the per-command reminder stops. The key keeps its
+        # ``ms_eval_`` prefix after claiming, so the prefix alone cannot tell us.
+        data = config_module.load()
+        entry = data.setdefault("profiles", {}).setdefault(profile_name, {})
+        entry["claimed"] = True
+        config_module.save(data)
+
+        payload = {**claimed, "profile": profile_name, "mode": "claim-complete"}
+
+        def render_complete() -> str:
+            return "\n".join(
+                [
+                    style.green("Account claimed."),
+                    f"{style.dim('email  ')} {claimed.get('email') or email}",
+                    f"{style.dim('plan   ')} {claimed.get('plan') or '-'}",
+                    "",
+                    style.dim(
+                        "Your existing key keeps working and no longer expires. "
+                        "Everything stored during the evaluation is still there."
+                    ),
+                ]
+            )
+
+        return {"data": payload, "text": render_complete}
+
+    # The value ``main`` already resolved from --api-key, the environment, then the
+    # stored profile. Resolving it again here would be a second precedence order
+    # for the Node CLI to disagree with.
+    api_key = ctx.get("api_key")
+    if not api_key:
+        raise usage_error(
+            "No stored key, so there is no evaluation account to claim.",
+            'Run "memorysync init --agent" first, or pass --code to finish a claim '
+            "you already started.",
+        )
+
+    client = ApiClient(
+        base_url=settings["base_url"], api_key=api_key, timeout=settings["timeout"]
+    )
+    started = client.start_evaluation_claim({"email": email}) or {}
+    payload = {**started, "profile": profile_name, "mode": "claim-start"}
+
+    def render_start() -> str:
+        target = started.get("email") or email
+        return "\n".join(
+            [
+                style.green("Claim code sent."),
+                f"{style.dim('email  ')} {target}",
+                f"{style.dim('expires')} {started.get('expires_in_minutes') or '-'} minutes",
+                "",
+                style.dim("Check your email, then run:"),
+                f"  memorysync init --email {target} --code <CODE>",
+            ]
+        )
+
+    return {"data": payload, "text": render_start}
+
+
+def identify(ctx: dict) -> dict:
+    """``identify <name>`` — replace the profile's default end-user id.
+
+    Purely local. Renaming the default cannot rename memories already stored under
+    the old id, and pretending otherwise would be worse than saying so: the output
+    names the previous id so it can still be read back with ``--user``.
+    """
+    positionals = ctx.get("positionals") or []
+    name = (positionals[0] if positionals else "").strip()
+    if not name:
+        raise usage_error("No name given.", "Try: memorysync identify alice")
+
+    profile_name = ctx["settings"]["profile_name"]
+    data = config_module.load()
+    entry = data.setdefault("profiles", {}).setdefault(profile_name, {})
+    previous = entry.get("user")
+    entry["user"] = name
+    # Also make it current, matching the Node CLI. Without this, `identify` under
+    # one CLI set a default that the other did not switch to, which is exactly the
+    # kind of near-miss the two-CLI contract exists to prevent.
+    data["current_profile"] = profile_name
+    config_module.save(data)
+
+    payload = {
+        "profile": profile_name,
+        "end_user": name,
+        "previous_end_user": previous,
+    }
+
+    def render() -> str:
+        lines = [style.green(f"Default end user is now {name}.")]
+        if previous and previous != name:
+            lines.append(
+                style.dim(
+                    f'Memories stored as "{previous}" keep that id - '
+                    f"read them with --user {previous}."
+                )
+            )
+        else:
+            lines.append(style.dim("Nothing was stored under a different id."))
+        return "\n".join(lines)
+
+    return {"data": payload, "text": render}
+
+
+def init(ctx: dict) -> dict:
+    flags, settings = ctx["flags"], ctx["settings"]
+    profile_name = settings["profile_name"]
+
+    # Claiming acts on the account behind an existing key rather than creating a
+    # profile, so it runs before the overwrite guard.
+    if flags.get("email"):
+        if flags.get("agent"):
+            raise usage_error(
+                "--agent mints a new account and --email claims the current one.",
+                'Run "memorysync init --agent" first, then '
+                '"memorysync init --email <address>".',
+            )
+        return _init_by_claiming(ctx, profile_name)
+
+    if flags.get("agent") and flags.get("api_key"):
+        raise usage_error(
+            "--agent mints a key, so there is nothing to pass with --api-key.",
+            "Drop one of the two.",
+        )
+
+    existing = config_module.profile(profile_name)
+    if existing and not flags.get("force"):
+        stored = credentials.read_key(profile_name)
+        if stored:
+            raise usage_error(
+                f'Profile "{profile_name}" already has a key.',
+                "Pass --force to replace it, or --profile <name> to add another.",
+            )
+
+    if flags.get("agent"):
+        return _init_as_agent(ctx, profile_name)
+
+    api_key = flags.get("api_key") or os.environ.get("MEMORYSYNC_API_KEY")
+    if not api_key:
+        if not sys.stdin.isatty():
+            raise usage_error(
+                "No API key given and no terminal to prompt from.",
+                "Pass --api-key, or set MEMORYSYNC_API_KEY.",
+            )
+        # getpass, so the key is not echoed into the terminal or the scrollback.
+        api_key = getpass.getpass("MemorySync API key: ").strip()
+
+    if not api_key:
+        raise usage_error("No API key given.")
+
+    # Verified before storing. A key that cannot read its own plan is not usable,
+    # and finding that out now is far cheaper than on the next command.
+    probe = ApiClient(
+        base_url=settings["base_url"],
+        api_key=api_key,
+        timeout=settings["timeout"],
+    )
+    try:
+        plan = probe.current_plan() or {}
+    except Exception as error:  # noqa: BLE001 - re-raised as an auth failure below
+        raise auth_error(
+            f"That key was refused: {error}",
+            "Check it in the dashboard, or pass --base-url if you are not on production.",
+        ) from None
+
+    tier = credentials.write_key(api_key, profile_name)
+
+    data = config_module.load()
+    entry = data.setdefault("profiles", {}).setdefault(profile_name, {})
+    if flags.get("user"):
+        entry["user"] = flags["user"]
+    if flags.get("project"):
+        entry["project"] = flags["project"]
+    if settings["base_url"] != config_module.DEFAULT_BASE_URL:
+        entry["base_url"] = settings["base_url"]
+    path = config_module.save(data)
+
+    payload = {
+        "profile": profile_name,
+        "stored_in": tier,
+        "config": str(path),
+        "user": entry.get("user"),
+        "project": entry.get("project"),
+        "plan": plan.get("plan") or plan.get("name"),
+    }
+
+    def render() -> str:
+        where = (
+            "the OS keychain"
+            if tier == "keychain"
+            else "an owner-only encrypted file"
+        )
+        lines = [
+            f"{style.green('Ready.')} Profile {style.bold(profile_name)} is set up.",
+            f"{style.dim('key      ')} stored in {where}",
+            f"{style.dim('config   ')} {path}",
+        ]
+        if entry.get("user"):
+            lines.append(f"{style.dim('user     ')} {entry['user']}")
+        else:
+            lines.append(
+                style.dim("no default user; pass --user on each call or re-run with --user")
+            )
+        if payload["plan"]:
+            lines.append(f"{style.dim('plan     ')} {payload['plan']}")
+        return "\n".join(lines)
+
+    return {"data": payload, "text": render}

{memorysync_cli-1.0.3 → memorysync_cli-1.1.1}/src/memorysync_cli/config.py

@@ -55,7 +55,7 @@ def config_path() -> Path:
 
 
 def _empty() -> dict[str, Any]:
-    return {"version": CONFIG_VERSION, "profiles": {}}
+    return {"version": CONFIG_VERSION, "profiles": {}, "current_profile": "default"}
 
 
 def load() -> dict[str, Any]:
@@ -78,6 +78,18 @@ def load() -> dict[str, Any]:
     return {
         "version": parsed.get("version", CONFIG_VERSION),
         "profiles": parsed.get("profiles") if isinstance(parsed.get("profiles"), dict) else {},
+        # Preserved, not dropped. This key was being discarded on read, so the
+        # Python CLI had no concept of an active profile at all: `config
+        # use-profile work` wrote it and every later command still used "default",
+        # and a profile switched under the Node CLI was ignored here. The two are
+        # documented as interchangeable and share ~/.memorysync, so that was a real
+        # divergence rather than a missing nicety.
+        "current_profile": (
+            parsed.get("current_profile")
+            if isinstance(parsed.get("current_profile"), str)
+            and parsed.get("current_profile")
+            else "default"
+        ),
     }
 
 
@@ -105,10 +117,18 @@ def resolve(flags: dict[str, Any]) -> dict[str, Any]:
     Values are read once here so every command sees the same view, rather than
     each one reaching for the environment at a different moment.
     """
+    # Same precedence as the Node CLI's ``resolveSettings``: an explicit flag, then
+    # the environment, then the profile the user selected with
+    # ``config use-profile``, then "default". The stored selection was missing here,
+    # which is why a switch made under either CLI had no effect on this one.
+    config = load()
     profile_name = (
-        flags.get("profile") or os.environ.get("MEMORYSYNC_PROFILE") or "default"
+        flags.get("profile")
+        or os.environ.get("MEMORYSYNC_PROFILE")
+        or config.get("current_profile")
+        or "default"
     )
-    stored = profile(profile_name)
+    stored = config.get("profiles", {}).get(profile_name, {})
 
     def pick(
         flag_key: str,
@@ -151,6 +171,15 @@ def resolve(flags: dict[str, Any]) -> dict[str, Any]:
         # `-o table` saved into a profile worked under one CLI only.
         "output": pick("output", "MEMORYSYNC_OUTPUT", "output"),
         "timeout": timeout,
+        # Whether the evaluation account behind this profile has been claimed.
+        # Recorded locally by ``init --email ... --code ...`` because a claimed
+        # key keeps its ``ms_eval_`` prefix, so the prefix alone cannot tell us
+        # and the per-command reminder would never stop.
+        #
+        # Deliberately read straight off the profile rather than through ``pick``:
+        # it is a fact about the account, not a preference, so a flag or an
+        # environment variable must not be able to silence the reminder.
+        "claimed": stored.get("claimed") is True,
     }
 
 

memorysync_cli-1.1.1/src/memorysync_cli/evaluation.py

@@ -0,0 +1,54 @@
+"""Evaluation-key awareness shared by every command.
+
+Mirrors ``sdk/cli/src/evaluation.mjs`` exactly. The two CLIs are documented as
+interchangeable, so a reminder that appears in one and not the other is a parity
+bug, not a cosmetic difference.
+
+An evaluation key is minted by an agent and expires in seven days unless a human
+claims it. The most expensive outcome is somebody building on one, never noticing
+it is temporary, and losing the account on day eight — so every command running
+on an unclaimed key ends with one line saying so, on stderr.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Mapping, Optional
+
+#: Prefix the server puts on anonymously minted keys.
+EVALUATION_KEY_PREFIX = "ms_eval_"
+
+#: The command a human runs to keep the account.
+CLAIM_HINT = "memorysync init --email you@example.com"
+
+
+def is_evaluation_key(key: Optional[str]) -> bool:
+    """True when *key* was minted anonymously."""
+    return isinstance(key, str) and key.startswith(EVALUATION_KEY_PREFIX)
+
+
+def claim_reminder(
+    api_key: Optional[str] = None,
+    profile: Optional[Mapping[str, Any]] = None,
+) -> Optional[str]:
+    """The reminder line for this invocation, or ``None``.
+
+    Reads ``claimed`` from the local profile rather than asking the API. Checking
+    on every command would add a round-trip to ``memorysync --help``, and the
+    claim path already knows the answer the moment it succeeds, so it records it.
+    """
+    if not is_evaluation_key(api_key):
+        return None
+    if profile and profile.get("claimed") is True:
+        return None
+    return (
+        "This is an unclaimed evaluation key and expires. "
+        f"Keep it: {CLAIM_HINT}"
+    )
+
+
+__all__ = [
+    "EVALUATION_KEY_PREFIX",
+    "CLAIM_HINT",
+    "is_evaluation_key",
+    "claim_reminder",
+]

{memorysync_cli-1.0.3 → memorysync_cli-1.1.1}/src/memorysync_cli/http.py

@@ -64,12 +64,22 @@ class ApiClient:
 
     def headers(self, extra: dict[str, str] | None = None) -> dict[str, str]:
         headers = {
-            "X-API-Key": self.api_key,
             "Accept": "application/json",
             # From the package version, never a literal. The Node CLI shipped
             # 1.0.1 announcing itself as 1.0.0 because this was hardcoded.
             "User-Agent": f"memorysync-cli-py/{__version__}",
         }
+        # Omitted rather than sent empty when there is no key.
+        #
+        # Two endpoints are deliberately keyless: minting an evaluation key, and
+        # redeeming a claim code. Setting the header to ``None`` made urllib raise
+        # ``TypeError: expected string or bytes-like object`` inside ``putheader``,
+        # before the request was sent -- so `init --agent` and `init --email --code`
+        # could never work in this package at all. The Node CLI survived the same
+        # bug only because ``fetch`` coerces null to the string "null", which the
+        # server then ignores on an unauthenticated route.
+        if self.api_key:
+            headers["X-API-Key"] = self.api_key
         # The API rejects key-authenticated memory calls without this, because
         # memory is always scoped to (tenant, project, user) and storing
         # everything under the key owner is not allowed. Commands validate it up
@@ -194,6 +204,37 @@ class ApiClient:
     # Named endpoints, so commands never carry raw paths
     # -----------------------------------------------------------------------
 
+    def mint_evaluation_key(self, body: dict) -> Any:
+        """Mint an evaluation key. The only endpoint here needing no credential.
+
+        Rate limited server-side per IP and per /24, failing closed, so a 429 is a
+        real answer rather than a transient error — it carries
+        ``retry_after_seconds`` pointing at the next UTC day.
+        """
+        return self.request("POST", "/evaluation/keys", body=body)
+
+    def start_evaluation_claim(self, body: dict) -> Any:
+        """Ask for a claim code by email. Needs the evaluation key."""
+        return self.request("POST", "/evaluation/claim/start", body=body)
+
+    def complete_evaluation_claim(self, body: dict) -> Any:
+        """Redeem a claim code.
+
+        Deliberately does not require the key: the code is the proof, so a claim
+        started on one machine can be finished on another — which is what happens
+        whenever somebody reads the code off their phone.
+        """
+        return self.request("POST", "/evaluation/claim/complete", body=body)
+
+    def evaluation_usage(self) -> Any:
+        """Remaining allowance for an evaluation key.
+
+        Evaluation keys are not granted ``billing:read``, so
+        ``/org/billing/usage`` is closed to them. This reports the same counters
+        without the pricing fields.
+        """
+        return self.request("GET", "/evaluation/usage")
+
     def add_memory(self, body: dict) -> Any:
         return self.request("POST", "/memory/add", body=body)
 

{memorysync_cli-1.0.3 → memorysync_cli-1.1.1}/src/memorysync_cli/main.py

@@ -21,6 +21,7 @@ from .args import parse_args, suggest
 from .commands import admin, init as init_command, memory, source as source_command, tooling
 from .credentials import read_key
 from .errors import CliError, Exit, auth_error, usage_error
+from .evaluation import claim_reminder
 from .http import ApiClient
 from .output import (
     emit,
@@ -37,8 +38,23 @@ Handler = Callable[[dict], dict]
 # which is the same reason the Node CLI keeps its HANDLERS map next to its own. A
 # name in the registry with no entry here fails as "not available" rather than
 # "unknown command", so `help --json` stays honest about what exists.
+def _note_unclaimed_key(api_key: str | None, settings: dict) -> None:
+    """Tell the user their evaluation key is temporary, once per command.
+
+    On stderr so stdout stays machine-parseable — an agent piping ``--json``
+    somewhere sees nothing extra, and a person sees the line. Silent for a claimed
+    key or a normal one. Matches the Node CLI line for line.
+    """
+    reminder = claim_reminder(
+        api_key, {"claimed": bool((settings or {}).get("claimed"))}
+    )
+    if reminder:
+        print(reminder, file=sys.stderr)
+
+
 _HANDLERS: dict[str, Handler] = {
     "init": init_command.init,
+    "identify": init_command.identify,
     "add": memory.add,
     "search": memory.search,
     "list": memory.list_memories,
@@ -260,6 +276,7 @@ def dispatch(argv: list[str]) -> int:
         # command list.
         if command_name == "help" and (agent_mode or fmt == "json"):
             write(json.dumps(result["data"], indent=2))
+            _note_unclaimed_key(api_key, settings)
             return Exit.OK
 
         if agent_mode:
@@ -274,6 +291,7 @@ def dispatch(argv: list[str]) -> int:
                     indent=2,
                 )
             )
+            _note_unclaimed_key(api_key, settings)
             return result.get("exit_code", Exit.OK)
 
         # `completion` and `mcp` emit text that must not be decorated or reshaped.
@@ -281,9 +299,13 @@ def dispatch(argv: list[str]) -> int:
             text = result["text"]()
             if text:
                 write(text)
+            # No reminder here: `completion` and `mcp` emit text that gets pasted
+            # into a shell profile or a config file, and a stray line would be
+            # pasted too.
             return result.get("exit_code", Exit.OK)
 
         emit(fmt=fmt, data=result["data"], text=result["text"])
+        _note_unclaimed_key(api_key, settings)
         return result.get("exit_code", Exit.OK)
 
     except CliError as error:

{memorysync_cli-1.0.3 → memorysync_cli-1.1.1}/src/memorysync_cli/registry.json

@@ -92,14 +92,38 @@
     {
       "name": "init",
       "summary": "Store a credential and pick a default user and project.",
-      "description": "Prompts for an API key, verifies it against the API, then writes a profile. The key is never written to the config file in plain text: it goes to the OS keychain where one is reachable, and otherwise to an encrypted file readable only by you.",
-      "usage": "memorysync init [--api-key <key>] [--user <id>] [--project <id>] [--force]",
+      "description": "Prompts for an API key, verifies it against the API, then writes a profile. The key is never written to the config file in plain text: it goes to the OS keychain where one is reachable, and otherwise to an encrypted file readable only by you.\n\nWith --agent it mints an evaluation key instead of asking for one, so a coding agent can get working memory with no email, no verification code and no human. That key expires after seven days and nobody owns it until somebody claims it with --email.",
+      "usage": "memorysync init [--api-key <key> | --agent | --email <address>] [--user <id>] [--project <id>] [--force]",
       "flags": [
         {
           "name": "--api-key",
           "value": "key",
           "description": "Skip the prompt and use this key."
         },
+        {
+          "name": "--agent",
+          "description": "Mint an evaluation key with no signup. Expires in 7 days unless claimed."
+        },
+        {
+          "name": "--agent-caller",
+          "value": "name",
+          "description": "Which tool is minting the key, e.g. claude-code. Attribution only."
+        },
+        {
+          "name": "--email",
+          "value": "address",
+          "description": "Claim the current evaluation account. Sends a code, then pass it with --code."
+        },
+        {
+          "name": "--code",
+          "value": "code",
+          "description": "The claim code from the email."
+        },
+        {
+          "name": "--password",
+          "value": "password",
+          "description": "Set a dashboard password while claiming. Optional."
+        },
         {
           "name": "--user",
           "short": "-u",
@@ -124,7 +148,29 @@
       ],
       "examples": [
         "memorysync init",
-        "memorysync init --api-key ms_live_xxx --user alice --force"
+        "memorysync init --api-key ms_live_xxx --user alice --force",
+        "memorysync init --agent --agent-caller claude-code",
+        "memorysync init --email you@example.com",
+        "memorysync init --email you@example.com --code K7MP-3XQR"
+      ],
+      "requires_auth": false
+    },
+    {
+      "name": "identify",
+      "summary": "Name the end user that later commands default to.",
+      "description": "An evaluation key starts with a generated end-user id like swift-otter-4821, because a key minted by an agent has nobody to name it after. This replaces it with something meaningful.\n\nOnly changes the local default: memories already stored under the old id keep that id, so pass --user explicitly to read them back.",
+      "usage": "memorysync identify <name> [--profile <name>]",
+      "flags": [
+        {
+          "name": "--profile",
+          "short": "-p",
+          "value": "name",
+          "description": "Profile to change. Default \"default\"."
+        }
+      ],
+      "examples": [
+        "memorysync identify alice",
+        "memorysync identify alice@example.com"
       ],
       "requires_auth": false
     },

memorysync_cli-1.0.3/src/memorysync_cli/_version.py

@@ -1 +0,0 @@
-__version__ = "1.0.3"

memorysync_cli-1.0.3/src/memorysync_cli/commands/init.py

@@ -1,109 +0,0 @@
-"""init: store a credential and pick defaults.
-
-The key is verified against the API before it is written. Storing an unverified key
-means the next command fails with something that looks like a network problem, and
-the person has no reason to suspect the thing they just typed.
-
-It is never written to the config file in plain text. It goes to the OS keychain
-where one is reachable, and otherwise to an owner-only encrypted file, and `init`
-says which of the two happened rather than implying a keychain that was never
-there.
-"""
-
-from __future__ import annotations
-
-import getpass
-import os
-import sys
-
-from .. import config as config_module
-from .. import credentials
-from ..errors import auth_error, usage_error
-from ..http import ApiClient
-from ..output import style
-
-
-def init(ctx: dict) -> dict:
-    flags, settings = ctx["flags"], ctx["settings"]
-    profile_name = settings["profile_name"]
-
-    existing = config_module.profile(profile_name)
-    if existing and not flags.get("force"):
-        stored = credentials.read_key(profile_name)
-        if stored:
-            raise usage_error(
-                f'Profile "{profile_name}" already has a key.',
-                "Pass --force to replace it, or --profile <name> to add another.",
-            )
-
-    api_key = flags.get("api_key") or os.environ.get("MEMORYSYNC_API_KEY")
-    if not api_key:
-        if not sys.stdin.isatty():
-            raise usage_error(
-                "No API key given and no terminal to prompt from.",
-                "Pass --api-key, or set MEMORYSYNC_API_KEY.",
-            )
-        # getpass, so the key is not echoed into the terminal or the scrollback.
-        api_key = getpass.getpass("MemorySync API key: ").strip()
-
-    if not api_key:
-        raise usage_error("No API key given.")
-
-    # Verified before storing. A key that cannot read its own plan is not usable,
-    # and finding that out now is far cheaper than on the next command.
-    probe = ApiClient(
-        base_url=settings["base_url"],
-        api_key=api_key,
-        timeout=settings["timeout"],
-    )
-    try:
-        plan = probe.current_plan() or {}
-    except Exception as error:  # noqa: BLE001 - re-raised as an auth failure below
-        raise auth_error(
-            f"That key was refused: {error}",
-            "Check it in the dashboard, or pass --base-url if you are not on production.",
-        ) from None
-
-    tier = credentials.write_key(api_key, profile_name)
-
-    data = config_module.load()
-    entry = data.setdefault("profiles", {}).setdefault(profile_name, {})
-    if flags.get("user"):
-        entry["user"] = flags["user"]
-    if flags.get("project"):
-        entry["project"] = flags["project"]
-    if settings["base_url"] != config_module.DEFAULT_BASE_URL:
-        entry["base_url"] = settings["base_url"]
-    path = config_module.save(data)
-
-    payload = {
-        "profile": profile_name,
-        "stored_in": tier,
-        "config": str(path),
-        "user": entry.get("user"),
-        "project": entry.get("project"),
-        "plan": plan.get("plan") or plan.get("name"),
-    }
-
-    def render() -> str:
-        where = (
-            "the OS keychain"
-            if tier == "keychain"
-            else "an owner-only encrypted file"
-        )
-        lines = [
-            f"{style.green('Ready.')} Profile {style.bold(profile_name)} is set up.",
-            f"{style.dim('key      ')} stored in {where}",
-            f"{style.dim('config   ')} {path}",
-        ]
-        if entry.get("user"):
-            lines.append(f"{style.dim('user     ')} {entry['user']}")
-        else:
-            lines.append(
-                style.dim("no default user; pass --user on each call or re-run with --user")
-            )
-        if payload["plan"]:
-            lines.append(f"{style.dim('plan     ')} {payload['plan']}")
-        return "\n".join(lines)
-
-    return {"data": payload, "text": render}