memorysync-cli 1.4.1__tar.gz → 1.5.0__tar.gz

{memorysync_cli-1.4.1 → memorysync_cli-1.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: memorysync-cli
-Version: 1.4.1
+Version: 1.5.0
 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.5.0/src/memorysync_cli/_version.py

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

memorysync_cli-1.5.0/src/memorysync_cli/commands/migrate.py

@@ -0,0 +1,748 @@
+"""``migrate`` — move an account from another memory provider into MemorySync.
+
+Separate from ``import`` on purpose. ``import`` takes a file already in our shape
+and sends it. ``migrate`` takes someone else's shape, understands its fields, maps
+them onto ours, splits the result across end-user scopes, and reports what it did
+per scope. Folding the two together would mean one command with two unrelated
+code paths and two sets of flags.
+
+This command writes customer data into scopes derived from another system's
+identifiers, so every ambiguity here is resolved by refusing rather than
+guessing. The three rules that follow from that:
+
+1. **A record whose scope cannot be determined stops the run.** Writing it into
+   a default or fallback scope would be a silent misfiling — the data is present,
+   retrievable by nobody, and there is no error to notice.
+
+2. **One API client per end-user group, never a per-item ``end_user_id``.** The
+   server resolves the end user as ``(header_val or body_end_user_id)``, so a
+   header set once wins over every per-item value. Varying the item field under a
+   fixed header would collapse an entire multi-user export into one scope and
+   return 207 success for all of it.
+
+3. **``client_ref`` is always sent, and there is no flag to turn it off.** A Mem0
+   record always carries an ``id``, so the reference is always available, and a
+   migration that is not safe to re-run is a migration that cannot be recovered
+   when it fails halfway.
+
+Mirrors ``sdk/cli/src/commands/migrate.mjs`` case for case. The two packages are
+documented as interchangeable, so a difference here is a defect in both.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import urllib.error
+import urllib.parse
+import urllib.request
+from pathlib import Path
+from typing import Any
+
+from ..errors import CliError, Exit, usage_error
+from ..output import style
+from .memory import _resolve_batch_size
+
+
+def _chunk_records(records: list, size: int) -> list[list]:
+    """Split into request-sized batches, mirroring the Node CLI's `chunkRecords`."""
+    return [records[i : i + size] for i in range(0, len(records), size)]
+
+#: Providers this command understands. Named so an unknown one lists the real set.
+PROVIDERS = ("mem0",)
+
+#: Mem0's paginated list endpoint. Entity ids go in ``filters``, not at the top level.
+MEM0_BASE = "https://api.mem0.ai"
+MEM0_PAGE_SIZE = 100
+
+#: Records held in memory at once before we insist on a file-based run.
+LIVE_PULL_CEILING = 50_000
+
+
+def migrate(ctx: dict) -> dict:
+    positionals = ctx.get("positionals") or []
+    provider = (positionals[0] if positionals else "").strip().lower()
+    if not provider:
+        raise usage_error(
+            "Which provider are you migrating from?",
+            f"Supported: {', '.join(PROVIDERS)}. Try "
+            "`memorysync migrate mem0 --file export.json --dry-run`.",
+        )
+    if provider not in PROVIDERS:
+        raise usage_error(
+            f'Cannot migrate from "{provider}".',
+            f"Supported providers: {', '.join(PROVIDERS)}.",
+        )
+    return _migrate_mem0(ctx)
+
+
+# ---------------------------------------------------------------------------
+# Mem0
+# ---------------------------------------------------------------------------
+
+
+def _migrate_mem0(ctx: dict) -> dict:
+    flags = ctx.get("flags") or {}
+    api = ctx.get("api")
+
+    source = _acquire_mem0_records(ctx)
+    groups, problems, total = _normalise_mem0(source["records"], source["scope_hint"])
+
+    if total == 0:
+        raise usage_error(
+            f"{source['label']} contained no memories.",
+            "Check that the export is not empty, and that it is the memories file "
+            "rather than a wrapper around one.",
+        )
+
+    # Unresolvable scope is fatal even under --continue-on-error, and it is
+    # checked before "nothing was usable" because its hint is the actionable one.
+    # Skipping such a record loses it silently; writing it to a fallback scope
+    # files it where nobody will look. Both are worse than refusing and naming
+    # the fix.
+    unscoped = [p for p in problems if "no user could be resolved" in p]
+    if unscoped:
+        raise CliError(
+            f"{len(unscoped)} record(s) carry no user id, so their scope cannot be determined.",
+            exit_code=Exit.USAGE,
+            code="unresolvable_scope",
+            hint=(
+                f"First: {unscoped[0]}. "
+                "Nothing was written. Pass --source-user <id> to state the scope for the "
+                "whole file, or re-export from Mem0 including user_id on every record. "
+                "A record written into a guessed scope would be unreachable by the user "
+                "it belongs to."
+            ),
+        )
+
+    usable = sum(len(records) for records in groups.values())
+    if usable == 0:
+        raise usage_error(
+            f"None of the {total} record(s) in {source['label']} are usable.",
+            f"First problem: {problems[0]}. Every record needs non-empty text and an id.",
+        )
+
+    batch_size = _resolve_batch_size(flags)
+
+    if flags.get("dry_run"):
+        return _dry_run_report(source, groups, problems, total, usable, batch_size)
+
+    if problems and not flags.get("continue_on_error"):
+        raise usage_error(
+            f"{len(problems)} record(s) in {source['label']} are not usable.",
+            f"First problem: {problems[0]}. Run with --dry-run to see them all, "
+            "or --continue-on-error to migrate the rest.",
+        )
+
+    return _run_mem0_migration(ctx, api, source, groups, problems, total, batch_size)
+
+
+# ---------------------------------------------------------------------------
+# Acquire
+# ---------------------------------------------------------------------------
+
+
+def _acquire_mem0_records(ctx: dict) -> dict:
+    """Get raw Mem0 records, from a file or from Mem0 itself.
+
+    ``scope_hint`` is the end user to attribute records to when the records
+    themselves do not say. It is only ever set from an explicit ``--source-user``,
+    never inferred, because an inferred scope is the failure mode this command
+    exists to avoid.
+    """
+    flags = ctx.get("flags") or {}
+    positionals = ctx.get("positionals") or []
+    file = flags.get("file") or (positionals[1] if len(positionals) > 1 else None)
+    explicit_user = (flags.get("source_user") or "").strip() or None
+
+    if file:
+        if flags.get("key"):
+            raise usage_error(
+                "Pass either --file or --key, not both.",
+                "A file is read from disk; a key pulls from Mem0. Two sources in one "
+                "run would be ambiguous.",
+            )
+        try:
+            raw = Path(file).read_text(encoding="utf-8")
+        except OSError as error:
+            raise usage_error(
+                f"Could not read {file}: {_describe_read_failure(error)}"
+            ) from None
+        return {
+            "label": str(file),
+            "origin": "file",
+            "records": _parse_mem0_file(raw, str(file)),
+            "scope_hint": explicit_user,
+        }
+
+    key = (flags.get("key") or os.environ.get("MEM0_API_KEY") or "").strip()
+    if not key:
+        raise usage_error(
+            "Nothing to migrate from.",
+            "Pass --file <path> for an export you already have, or --key <mem0-api-key> "
+            "(or set MEM0_API_KEY) to pull from Mem0 directly.",
+        )
+
+    records = _pull_from_mem0(key, explicit_user, flags)
+    return {
+        "label": f"Mem0 user {explicit_user}" if explicit_user else "your Mem0 account",
+        "origin": "api",
+        "records": records,
+        "scope_hint": explicit_user,
+    }
+
+
+def _parse_mem0_file(raw: str, file: str) -> list:
+    """Read a Mem0 export file.
+
+    Mem0 hands back a paginated envelope from the API and a wrapper object from
+    the dashboard, and people also save just the array. All three are accepted
+    because all three are things a user will actually have on disk; anything else
+    is refused with the shape we were looking for rather than a type error.
+    """
+    trimmed = raw.strip()
+    if not trimmed:
+        raise usage_error(f"{file} is empty.")
+
+    try:
+        parsed = json.loads(trimmed)
+    except ValueError as error:
+        raise usage_error(
+            f"{file} is not valid JSON: {error}",
+            "A Mem0 export is a JSON file. If you have JSONL in our own record shape, "
+            "use `memorysync import` instead.",
+        ) from None
+
+    if isinstance(parsed, list):
+        return parsed
+    if isinstance(parsed, dict):
+        for key in ("results", "memories", "data", "items"):
+            if isinstance(parsed.get(key), list):
+                return parsed[key]
+    raise usage_error(
+        f"{file} does not look like a Mem0 export.",
+        'Expected a JSON array of records, or an object with a "results" or '
+        '"memories" array.',
+    )
+
+
+def _pull_from_mem0(key: str, user: str | None, flags: dict) -> list:
+    """Page through Mem0's list endpoint.
+
+    ``filters`` is required and must name at least one entity, so a run without
+    ``--source-user`` uses the documented ``*`` wildcard. That returns every user's
+    memories in one stream, and the records must then carry ``user_id``
+    themselves for grouping to be possible — checked in ``_normalise_mem0``,
+    which refuses rather than pooling them.
+    """
+    filters = {"user_id": user} if user else {"user_id": "*"}
+    collected: list = []
+    page = 1
+
+    while True:
+        payload = _mem0_request(key, page, {"filters": filters}, flags.get("timeout"))
+
+        if isinstance(payload, dict) and isinstance(payload.get("results"), list):
+            batch = payload["results"]
+        elif isinstance(payload, list):
+            batch = payload
+        else:
+            raise CliError(
+                "Mem0 returned a response this version does not understand.",
+                exit_code=Exit.NETWORK,
+                code="mem0_unexpected_response",
+                hint=(
+                    'Expected a paginated object with a "results" array. Export from '
+                    "Mem0 and migrate the file with --file instead."
+                ),
+            )
+
+        collected.extend(batch)
+
+        if len(collected) > LIVE_PULL_CEILING:
+            raise CliError(
+                f"This account has more than {LIVE_PULL_CEILING:,} memories.",
+                exit_code=Exit.USAGE,
+                code="account_too_large_for_live_pull",
+                hint=(
+                    "Export from Mem0 to a file and run "
+                    "`memorysync migrate mem0 --file <path>`, which streams from disk "
+                    "instead of holding the account in memory."
+                ),
+            )
+
+        has_next = isinstance(payload, dict) and payload.get("next")
+        if not has_next or not batch:
+            break
+        page += 1
+
+    return collected
+
+
+def _mem0_request(key: str, page: int, body: dict, timeout: Any) -> Any:
+    """One page from Mem0, with its failures translated into our exit codes."""
+    query = urllib.parse.urlencode({"page": page, "page_size": MEM0_PAGE_SIZE})
+    url = f"{MEM0_BASE}/v3/memories/?{query}"
+    limit_ms = int(timeout) if timeout and int(timeout) > 0 else 60000
+
+    request = urllib.request.Request(
+        url,
+        data=json.dumps(body).encode("utf-8"),
+        method="POST",
+        headers={
+            # Mem0's own scheme. Not Bearer, and not our X-API-Key.
+            "Authorization": f"Token {key}",
+            "Content-Type": "application/json",
+            "Accept": "application/json",
+        },
+    )
+
+    try:
+        with urllib.request.urlopen(request, timeout=limit_ms / 1000) as response:
+            text = response.read().decode("utf-8", errors="replace")
+    except urllib.error.HTTPError as error:
+        status = error.code
+        if status in (401, 403):
+            raise CliError(
+                "Mem0 rejected that API key.",
+                exit_code=Exit.AUTH,
+                code="mem0_unauthorized",
+                hint="Check the key in your Mem0 dashboard. It is a Mem0 key, not your "
+                "MemorySync key.",
+            ) from None
+        if status == 429:
+            retry = error.headers.get("retry-after") if error.headers else None
+            raise CliError(
+                "Mem0 is rate limiting this account.",
+                exit_code=Exit.NETWORK,
+                code="mem0_rate_limited",
+                hint=(
+                    f"Retry in {retry}s, or export to a file and migrate that instead."
+                    if retry
+                    else "Wait a moment and try again, or export to a file and migrate "
+                    "that instead."
+                ),
+            ) from None
+        detail = ""
+        try:
+            detail = error.read().decode("utf-8", errors="replace")
+        except Exception:  # noqa: BLE001 — the body is a nicety, not required
+            detail = ""
+        raise CliError(
+            f"Mem0 answered {status} while listing memories.",
+            exit_code=Exit.NETWORK,
+            code="mem0_error",
+            hint=detail[:300] if detail else "Export to a file and migrate that instead.",
+        ) from None
+    except TimeoutError:
+        raise CliError(
+            f"Mem0 did not respond within {limit_ms}ms.",
+            exit_code=Exit.NETWORK,
+            code="mem0_timeout",
+            hint="Raise it with --timeout, or export to a file and migrate that.",
+        ) from None
+    except urllib.error.URLError as error:
+        reason = getattr(error, "reason", error)
+        if isinstance(reason, TimeoutError) or "timed out" in str(reason).lower():
+            raise CliError(
+                f"Mem0 did not respond within {limit_ms}ms.",
+                exit_code=Exit.NETWORK,
+                code="mem0_timeout",
+                hint="Raise it with --timeout, or export to a file and migrate that.",
+            ) from None
+        raise CliError(
+            f"Could not reach Mem0: {reason}",
+            exit_code=Exit.NETWORK,
+            code="mem0_unreachable",
+        ) from None
+
+    try:
+        return json.loads(text)
+    except ValueError:
+        raise CliError(
+            "Mem0 returned a body that is not JSON.",
+            exit_code=Exit.NETWORK,
+            code="mem0_bad_json",
+        ) from None
+
+
+def _describe_read_failure(error: OSError) -> str:
+    import errno
+
+    if error.errno == errno.ENOENT:
+        return "no such file or directory."
+    if error.errno in (errno.EACCES, errno.EPERM):
+        return "permission denied."
+    if error.errno in (errno.EISDIR, getattr(errno, "EISDIR", None)):
+        return "that is a directory, not a file."
+    return "could not be read."
+
+
+# ---------------------------------------------------------------------------
+# Normalise
+# ---------------------------------------------------------------------------
+
+
+def _normalise_mem0(raw_records: list, scope_hint: str | None) -> tuple[dict, list[str], int]:
+    """Map Mem0 records onto ours, grouped by the end user each belongs to.
+
+    Position is reported as ``record N`` counting from 1 across the whole source,
+    so a problem names something the user can find in their file whichever shape
+    it arrived in.
+    """
+    groups: dict[str, list[dict]] = {}
+    problems: list[str] = []
+    total = 0
+
+    for index, entry in enumerate(raw_records):
+        total += 1
+        at = f"record {index + 1}"
+
+        if not isinstance(entry, dict):
+            problems.append(f"{at}: expected an object")
+            continue
+
+        # ``memory`` is what the v3 API returns; ``content`` and ``text`` appear
+        # in older exports and in files people have already reshaped by hand.
+        text = entry.get("memory")
+        if text is None:
+            text = entry.get("content")
+        if text is None:
+            text = entry.get("text")
+        if not isinstance(text, str) or not text.strip():
+            problems.append(f"{at}: no memory, content or text field")
+            continue
+
+        # The reference that makes re-running safe. Mem0 ids are strings, but a
+        # reshaped export can carry a number, which is stringified rather than
+        # refused — an id is an identifier, not a measurement.
+        ref = _usable_ref(
+            entry.get("id") if entry.get("id") is not None
+            else entry.get("memory_id") if entry.get("memory_id") is not None
+            else entry.get("uuid")
+        )
+        if not ref:
+            problems.append(f"{at}: no id, so re-running this migration could not skip it")
+            continue
+
+        # Scope, in order of authority: the record's own user, then an explicit
+        # --source-user. Never a default. An ``agent_id`` is *not* accepted as a
+        # scope: it identifies which agent learned something, not whose memory it
+        # is, and treating it as an end user would create a scope no real user
+        # reads from.
+        record_user = _first_non_empty(
+            entry.get("user_id"), entry.get("userId"), entry.get("end_user_id")
+        )
+        user = record_user or scope_hint
+        if not user:
+            problems.append(f"{at}: no user could be resolved (id {ref})")
+            continue
+
+        metadata: dict[str, Any] = {}
+        if isinstance(entry.get("metadata"), dict):
+            metadata.update(entry["metadata"])
+        # Ours are written last so they are authoritative. A record whose own
+        # metadata happened to carry ``mem0_id`` would otherwise overwrite the
+        # reconciliation key with something that is not an id.
+        metadata["mem0_id"] = ref
+        created_at = entry.get("created_at")
+        if isinstance(created_at, str) and created_at.strip():
+            # Kept in metadata because our ``created_at`` is server-assigned and
+            # feeds the recency signal in ranking. Back-dating it would make every
+            # migrated memory look stale and rank below anything written after.
+            metadata["mem0_created_at"] = created_at.strip()
+        agent_id = _first_non_empty(entry.get("agent_id"), entry.get("agentId"))
+        if agent_id:
+            metadata["mem0_agent_id"] = agent_id
+        app_id = _first_non_empty(entry.get("app_id"), entry.get("appId"))
+        if app_id:
+            metadata["mem0_app_id"] = app_id
+        run_id = _first_non_empty(entry.get("run_id"), entry.get("runId"))
+        if run_id:
+            metadata["mem0_run_id"] = run_id
+
+        record: dict[str, Any] = {"text": text.strip(), "ref": ref, "metadata": metadata, "at": at}
+
+        # Mem0's ``categories`` is a list of labels, which is what our ``tags``
+        # is. Non-strings are dropped rather than coerced: a tag is matched
+        # exactly at query time, so a stringified object would be a tag nobody
+        # can ever match.
+        if isinstance(entry.get("categories"), list):
+            tags = [t.strip() for t in entry["categories"] if isinstance(t, str) and t.strip()]
+            if tags:
+                record["tags"] = tags
+
+        groups.setdefault(user, []).append(record)
+
+    return groups, problems, total
+
+
+def _usable_ref(value: Any) -> str | None:
+    """A reference we are willing to send as ``client_ref``.
+
+    Fractional numbers are refused because the two CLIs would render them
+    differently — Python's ``str(1.0)`` is ``'1.0'`` and JavaScript's
+    ``String(1.0)`` is ``'1'`` — so the same record would claim two different
+    references depending on which package ran the migration, and a re-run from
+    the other one would store it twice.
+    """
+    if isinstance(value, str):
+        return value.strip() or None
+    # ``bool`` is a subclass of ``int`` and True is not an identifier.
+    if isinstance(value, int) and not isinstance(value, bool):
+        return str(value)
+    return None
+
+
+def _first_non_empty(*values: Any) -> str | None:
+    for value in values:
+        if isinstance(value, str) and value.strip():
+            return value.strip()
+    return None
+
+
+# ---------------------------------------------------------------------------
+# Report
+# ---------------------------------------------------------------------------
+
+
+def _dry_run_report(
+    source: dict, groups: dict, problems: list[str], total: int, usable: int, batch_size: int
+) -> dict:
+    per_user = sorted(
+        ({"user": user, "records": len(records)} for user, records in groups.items()),
+        key=lambda g: (-g["records"], g["user"]),
+    )
+    requests = sum(-(-g["records"] // batch_size) for g in per_user)
+
+    def render() -> str:
+        lines: list[str | None] = [
+            style.yellow("Dry run. Nothing was written."),
+            f"{style.dim('source    ')} {source['label']}",
+            f"{style.dim('records   ')} {total}",
+            f"{style.dim('usable    ')} {usable}",
+            f"{style.dim('unusable  ')} {len(problems)}",
+            f"{style.dim('end users ')} {len(per_user)}",
+            f"{style.dim('requests  ')} {requests} at {batch_size} per request",
+            "",
+            style.dim("Would write:"),
+        ]
+        for group in per_user[:15]:
+            lines.append(f"  {group['user']:<24} {group['records']:>7}")
+        if len(per_user) > 15:
+            lines.append(style.dim(f"  ... and {len(per_user) - 15} more users"))
+        if problems:
+            lines.append("")
+            lines.append(style.dim("Problems:"))
+            for problem in problems[:10]:
+                lines.append(style.dim(f"  {problem}"))
+            if len(problems) > 10:
+                lines.append(style.dim(f"  ... and {len(problems) - 10} more"))
+            lines.append(
+                style.yellow(
+                    "A real run would refuse these. Pass --continue-on-error to "
+                    "migrate the rest."
+                )
+            )
+        return "\n".join(line for line in lines if line is not None)
+
+    return {
+        "data": {
+            "source": source["label"],
+            "origin": source["origin"],
+            "provider": "mem0",
+            "total": total,
+            "usable": usable,
+            "unusable": len(problems),
+            "users": len(per_user),
+            "per_user": per_user,
+            "requests": requests,
+            "batch_size": batch_size,
+            "problems": problems,
+            "dry_run": True,
+        },
+        "text": render,
+    }
+
+
+# ---------------------------------------------------------------------------
+# Run
+# ---------------------------------------------------------------------------
+
+
+def _run_mem0_migration(
+    ctx: dict,
+    api: Any,
+    source: dict,
+    groups: dict,
+    problems: list[str],
+    total: int,
+    batch_size: int,
+) -> dict:
+    flags = ctx.get("flags") or {}
+    results: dict[str, Any] = {
+        "source": source["label"],
+        "provider": "mem0",
+        "total": total,
+        "unusable": len(problems),
+        "users": len(groups),
+        "imported": 0,
+        "already_imported": 0,
+        "skipped": 0,
+        "unreported": 0,
+        "failed": 0,
+        "memory_ids": [],
+        "failures": [],
+        "per_user": [],
+        "batch_size": batch_size,
+    }
+
+    stopped = False
+
+    for user, records in groups.items():
+        # One client per group. See the note at the top of this module: the
+        # server trusts the header over any per-item value, so this is the only
+        # way to write more than one scope in a single run without silently
+        # pooling them.
+        scoped = api.with_user(user)
+        per_user = {
+            "user": user,
+            "records": len(records),
+            "imported": 0,
+            "already_imported": 0,
+            "skipped": 0,
+            "unreported": 0,
+            "failed": 0,
+        }
+
+        for batch in _chunk_records(records, batch_size):
+            items = []
+            for record in batch:
+                item: dict[str, Any] = {
+                    "text": record["text"],
+                    "source": "mem0-import",
+                    "metadata": record["metadata"],
+                    # Always sent. There is no flag to suppress it.
+                    "client_ref": record["ref"],
+                }
+                if record.get("tags"):
+                    item["tags"] = record["tags"]
+                items.append(item)
+
+            try:
+                response = scoped.bulk_add_memories({"items": items})
+            except CliError as error:
+                per_user["failed"] += len(batch)
+                results["failed"] += len(batch)
+                results["failures"].append(
+                    f"{user}: {batch[0]['at']}-{batch[-1]['at']}: {error.message}"
+                )
+                if not flags.get("continue_on_error"):
+                    stopped = True
+                    break
+                continue
+
+            per_item = response.get("results") if isinstance(response, dict) else None
+            if not isinstance(per_item, list):
+                # Over-quota returns a success envelope with no per-item detail
+                # and stores nothing. Counting these as imported would report a
+                # migration that did not happen, which is the one thing this must
+                # never do.
+                per_user["unreported"] += len(batch)
+                results["unreported"] += len(batch)
+                continue
+
+            for item in per_item:
+                index = item.get("index")
+                record = batch[index] if isinstance(index, int) and 0 <= index < len(batch) else None
+                where = f"{user}: {record['at']}" if record else f"{user}: item {index}"
+                status = item.get("status")
+                if status == "created":
+                    per_user["imported"] += 1
+                    results["imported"] += 1
+                    results["memory_ids"].extend(item.get("memory_ids") or [])
+                elif status == "skipped" and item.get("reason") == "already_ingested":
+                    per_user["already_imported"] += 1
+                    results["already_imported"] += 1
+                    results["memory_ids"].extend(item.get("memory_ids") or [])
+                elif status == "skipped":
+                    per_user["skipped"] += 1
+                    results["skipped"] += 1
+                else:
+                    per_user["failed"] += 1
+                    results["failed"] += 1
+                    results["failures"].append(f"{where}: {item.get('reason') or 'rejected'}")
+
+            if per_user["failed"] > 0 and not flags.get("continue_on_error"):
+                stopped = True
+                break
+
+        results["per_user"].append(per_user)
+        if stopped:
+            break
+
+    results["stopped_early"] = stopped
+    results["completed_users"] = len(results["per_user"])
+    return {"data": results, "text": lambda: _render_migration(results)}
+
+
+def _render_migration(results: dict) -> str:
+    lines = [
+        f"{style.green('Migrated')} {results['imported']} of {results['total']} record(s) "
+        f"across {results['completed_users']} end user(s)"
+    ]
+    if results["already_imported"]:
+        lines.append(
+            style.dim(f"  {results['already_imported']} already migrated on an earlier run")
+        )
+    if results["skipped"]:
+        lines.append(style.dim(f"  {results['skipped']} skipped as duplicate or low value"))
+    if results["unreported"]:
+        lines.append(
+            style.yellow(
+                f"  {results['unreported']} accepted without a per-record result — "
+                "likely over your plan limit"
+            )
+        )
+        lines.append(
+            style.dim(
+                "    Nothing was stored for those. Re-run this command when your cycle resets."
+            )
+        )
+    if results["unusable"]:
+        lines.append(style.dim(f"  {results['unusable']} unusable record(s) skipped"))
+    if results["failed"]:
+        lines.append(style.red(f"  {results['failed']} failed"))
+    for failure in results["failures"][:5]:
+        lines.append(style.dim(f"    {failure}"))
+    if len(results["failures"]) > 5:
+        lines.append(style.dim(f"    ... and {len(results['failures']) - 5} more"))
+
+    if len(results["per_user"]) > 1:
+        lines.append("")
+        lines.append(style.dim("Per end user:"))
+        for group in results["per_user"][:15]:
+            lines.append(
+                f"  {group['user']:<24} {group['imported']:>7} of {group['records']}"
+            )
+        if len(results["per_user"]) > 15:
+            lines.append(style.dim(f"  ... and {len(results['per_user']) - 15} more"))
+
+    if results["stopped_early"]:
+        lines.append("")
+        lines.append(style.yellow("Stopped at the first failure. Nothing after it was attempted."))
+        lines.append(
+            style.dim(
+                "Re-run the same command to continue: records already migrated are "
+                "recognised and not stored twice."
+            )
+        )
+    else:
+        lines.append("")
+        lines.append(
+            style.dim(
+                "Safe to re-run. Every record carries its Mem0 id, so nothing is stored twice."
+            )
+        )
+
+    return "\n".join(lines)

{memorysync_cli-1.4.1 → memorysync_cli-1.5.0}/src/memorysync_cli/http.py

@@ -108,6 +108,27 @@ class ApiClient:
         self.timeout = timeout
         self.verbose = verbose
 
+    def with_user(self, user: str | None) -> "ApiClient":
+        """The same client scoped to a different end user.
+
+        ``migrate`` needs this. One Mem0 export routinely carries memories for
+        many ``user_id`` values, and each group has to be written under its own
+        end-user scope. Doing that by varying ``end_user_id`` per bulk-add item
+        does not work and fails silently: the server resolves
+        ``(header_val or body_end_user_id)``, so a header set once wins over
+        every per-item value and the whole export collapses into one scope with
+        no error to say so. A separate client per group keeps the header
+        authoritative, which is the field the server trusts.
+        """
+        return ApiClient(
+            base_url=self.base_url,
+            api_key=self.api_key,
+            user=user,
+            project=self.project,
+            timeout=self.timeout,
+            verbose=self.verbose,
+        )
+
     def headers(self, extra: dict[str, str] | None = None) -> dict[str, str]:
         headers = {
             "Accept": "application/json",

{memorysync_cli-1.4.1 → memorysync_cli-1.5.0}/src/memorysync_cli/main.py

@@ -18,7 +18,14 @@ from typing import Any, Callable
 from . import config as config_module
 from . import registry
 from .args import parse_args, suggest
-from .commands import admin, init as init_command, memory, source as source_command, tooling
+from .commands import (
+    admin,
+    init as init_command,
+    memory,
+    migrate as migrate_command,
+    source as source_command,
+    tooling,
+)
 from .credentials import read_key
 from .errors import CliError, Exit, auth_error, usage_error
 from .evaluation import claim_reminder
@@ -63,6 +70,7 @@ _HANDLERS: dict[str, Handler] = {
     "update": memory.update,
     "delete": memory.delete_memories,
     "import": memory.import_memories,
+    "migrate": migrate_command.migrate,
     "import-status": memory.import_status,
     "export": memory.export_memories,
     "quota": admin.quota,

{memorysync_cli-1.4.1 → memorysync_cli-1.5.0}/src/memorysync_cli/registry.json

@@ -420,6 +420,49 @@
       "requires_auth": true,
       "consumes_quota": "add_requests"
     },
+    {
+      "name": "migrate",
+      "summary": "Move an account from another memory provider into MemorySync.",
+      "description": "Reads a Mem0 export from disk, or pulls the account from Mem0 directly with your Mem0 API key, maps every record onto a MemorySync memory, and writes each one into the end-user scope it belongs to. Mem0 ids become client references, so re-running the same migration recognises what already landed instead of storing it twice — a run interrupted halfway is finished by running it again. Categories become tags, and the original id, timestamp, agent, app and run ids are kept in metadata so the two systems stay reconcilable. Always start with --dry-run: it reports the per-user breakdown and every unusable record without writing anything.",
+      "usage": "memorysync migrate <provider> [--file <path> | --key <key>] [--dry-run]",
+      "flags": [
+        {
+          "name": "--file",
+          "value": "path",
+          "description": "A Mem0 export on disk. Use instead of --key."
+        },
+        {
+          "name": "--key",
+          "value": "key",
+          "description": "Mem0 API key, to pull the account directly. Falls back to MEM0_API_KEY."
+        },
+        {
+          "name": "--source-user",
+          "value": "id",
+          "description": "Migrate only this user from the source provider, and use it as the scope for records that name no user."
+        },
+        {
+          "name": "--batch-size",
+          "value": "n",
+          "description": "Records per request. Default 50."
+        },
+        {
+          "name": "--dry-run",
+          "description": "Report what would be written, and write nothing."
+        },
+        {
+          "name": "--continue-on-error",
+          "description": "Migrate the usable records instead of refusing the whole file."
+        }
+      ],
+      "examples": [
+        "memorysync migrate mem0 --file mem0_export.json --dry-run",
+        "memorysync migrate mem0 --file mem0_export.json",
+        "memorysync migrate mem0 --key m0-xxxx --source-user alice"
+      ],
+      "requires_auth": true,
+      "consumes_quota": "add_requests"
+    },
     {
       "name": "import-status",
       "summary": "Check a background import, or list recent ones.",

memorysync_cli-1.4.1/src/memorysync_cli/_version.py

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