memorysync-cli 1.2.0__tar.gz → 1.3.0__tar.gz

{memorysync_cli-1.2.0 → memorysync_cli-1.3.0}/PKG-INFO

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

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

{memorysync_cli-1.2.0 → memorysync_cli-1.3.0}/src/memorysync_cli/commands/memory.py

@@ -505,11 +505,15 @@ def import_memories(ctx: dict) -> dict:
     try:
         raw = Path(source_path).read_text(encoding="utf-8")
     except OSError as error:
-        raise usage_error(f"Could not read {source_path}: {error}") from None
+        raise usage_error(
+            f"Could not read {source_path}: {_describe_read_failure(error)}"
+        ) from None
 
     records: list[dict] = []
     errors: list[str] = []
 
+    ref_field = flags.get("ref_field") or None
+
     def _validate(number: int, entry: Any) -> None:
         """Record one candidate as either usable or an error, in line order."""
         if not isinstance(entry, dict):
@@ -526,6 +530,7 @@ def import_memories(ctx: dict) -> dict:
             "text": text.strip(),
             "source": entry.get("source") or "cli-import",
             "line": number,
+            "ref": _pick_ref(entry, ref_field),
         }
         if isinstance(entry.get("metadata"), dict):
             record["metadata"] = entry["metadata"]
@@ -562,12 +567,14 @@ def import_memories(ctx: dict) -> dict:
     if flags.get("dry_run"):
         preview = list(errors[:10])
         trailer = len(errors) - len(preview)
+        with_ref = sum(1 for record in records if record.get("ref"))
         return {
             "data": {
                 "file": source_path,
                 "valid": len(records),
                 "invalid": len(errors),
                 "errors": errors,
+                "identified": with_ref,
             },
             "text": lambda: "\n".join(
                 line
@@ -575,6 +582,10 @@ def import_memories(ctx: dict) -> dict:
                     style.yellow("Dry run. Nothing was sent."),
                     f"{style.dim('valid   ')} {len(records)}",
                     f"{style.dim('invalid ')} {len(errors)}",
+                    # Shown always, not only under --resume, because knowing the
+                    # file has usable ids is what tells someone --resume is
+                    # available to them.
+                    f"{style.dim('with id ')} {with_ref}",
                     *[style.dim(f"  {message}") for message in preview],
                     style.dim(f"  ... and {trailer} more") if trailer > 0 else "",
                     style.yellow(
@@ -597,6 +608,25 @@ def import_memories(ctx: dict) -> dict:
     if not records:
         raise usage_error(f"{source_path} contained no records.")
 
+    # --resume is only honest if every record has a stable identity. Falling back
+    # to the line number would break the moment the file is re-exported in a
+    # different order, and falling back to a hash of the text would make two
+    # genuinely identical records collide, so the second would be reported as
+    # already stored and silently dropped. Refusing names the problem instead.
+    if flags.get("resume"):
+        missing = [record for record in records if not record.get("ref")]
+        if missing:
+            shown = ", ".join(f"line {record['line']}" for record in missing[:5])
+            looked_for = f'"{ref_field}"' if ref_field else "id, _id, uuid"
+            extra = "" if ref_field else " and metadata.mem0_id"
+            raise usage_error(
+                f"--resume needs an id on every record, and {len(missing)} "
+                f"{'has' if len(missing) == 1 else 'have'} none.",
+                f"First: {shown}. Looked for {looked_for}{extra}. "
+                "Pass --ref-field <name> to use a different field, or run without "
+                "--resume.",
+            )
+
     batch_size = _resolve_batch_size(flags)
     batches = [records[i : i + batch_size] for i in range(0, len(records), batch_size)]
     totals = {
@@ -604,23 +634,31 @@ def import_memories(ctx: dict) -> dict:
         "imported": 0,
         "memory_ids": [],
         "skipped": 0,
+        # Rows the server had already stored under the same identifier. Counted
+        # apart from ``skipped`` because they mean something different to whoever
+        # is resuming: nothing was lost, this row is simply already in.
+        "already_imported": 0,
         "failed": 0,
         "unreported": 0,
         "failures": [],
         "batches": len(batches),
         "batch_size": batch_size,
+        "resume": bool(flags.get("resume")),
     }
 
+    resume = bool(flags.get("resume"))
     for batch in batches:
         before = totals["failed"]
-        items = [
-            {
+        items = []
+        for record in batch:
+            item = {
                 key: value
                 for key, value in record.items()
                 if key in {"text", "source", "metadata"}
             }
-            for record in batch
-        ]
+            if resume and record.get("ref"):
+                item["client_ref"] = record["ref"]
+            items.append(item)
         try:
             response = api.bulk_add_memories({"items": items}) or {}
         except Exception as error:  # noqa: BLE001 — reported, not raised
@@ -651,6 +689,11 @@ def import_memories(ctx: dict) -> dict:
             if status == "created":
                 totals["imported"] += 1
                 totals["memory_ids"].extend(item.get("memory_ids") or [])
+            elif status == "skipped" and item.get("reason") == "already_ingested":
+                totals["already_imported"] += 1
+                # The ids the first run produced, so a resumed import still ends
+                # up knowing every memory its file corresponds to.
+                totals["memory_ids"].extend(item.get("memory_ids") or [])
             elif status == "skipped":
                 totals["skipped"] += 1
             else:
@@ -666,6 +709,11 @@ def import_memories(ctx: dict) -> dict:
             line
             for line in [
                 f"{style.green('Imported')} {totals['imported']} of {totals['total']}",
+                style.dim(
+                    f"  {totals['already_imported']} already imported on an earlier run"
+                )
+                if totals["already_imported"]
+                else "",
                 style.dim(f"  {totals['skipped']} skipped as duplicate or low value")
                 if totals["skipped"]
                 else "",
@@ -691,6 +739,57 @@ def import_memories(ctx: dict) -> dict:
 SERVER_BULK_MAX = 50
 
 
+def _pick_ref(entry: dict, ref_field: str | None) -> str | None:
+    """The record's own id, for ``--resume``.
+
+    Checked in the order an export is likely to carry one. ``metadata.mem0_id``
+    is included because the Mem0 migration guide tells people to put it there, so
+    a file built by following our own documentation resumes without extra flags.
+    Numbers are accepted and stringified; a caller-supplied id is frequently an
+    integer and refusing it would be pedantry.
+    """
+    metadata = entry.get("metadata") if isinstance(entry.get("metadata"), dict) else {}
+    if ref_field:
+        candidates = [entry.get(ref_field), metadata.get(ref_field)]
+    else:
+        candidates = [
+            entry.get("id"),
+            entry.get("_id"),
+            entry.get("uuid"),
+            metadata.get("mem0_id"),
+        ]
+    for value in candidates:
+        if isinstance(value, str) and value.strip():
+            return value.strip()
+        # bool is an int subclass and is never a usable identifier.
+        if isinstance(value, int) and not isinstance(value, bool):
+            return str(value)
+        if isinstance(value, float) and value == int(value):
+            return str(int(value))
+    return None
+
+
+def _describe_read_failure(error: OSError) -> str:
+    """Why a file could not be read, worded identically to the Node CLI.
+
+    ``str(error)`` cannot be used directly: Python says
+    ``[Errno 2] No such file or directory: 'relative'`` and Node says
+    ``ENOENT: no such file or directory, open 'C:\\abs\\path'`` — different
+    wording, different casing, and Node leaks an absolute path the user did not
+    type. The two packages are published as interchangeable, so the common cases
+    are named here and the rest fall back to a sentence neither runtime supplies.
+    """
+    import errno
+
+    if isinstance(error, IsADirectoryError) or error.errno == errno.EISDIR:
+        return "that is a directory, not a file."
+    if isinstance(error, PermissionError) or error.errno in {errno.EACCES, errno.EPERM}:
+        return "permission denied."
+    if isinstance(error, FileNotFoundError) or error.errno == errno.ENOENT:
+        return "no such file or directory."
+    return "the file could not be opened."
+
+
 def _resolve_batch_size(flags: dict) -> int:
     """Effective batch size for this run.
 
@@ -708,9 +807,12 @@ def _resolve_batch_size(flags: dict) -> int:
     except (TypeError, ValueError):
         value = 0
     if value < 1:
+        # Quoted by hand rather than with ``!r``. ``repr`` gives single quotes and
+        # the Node CLI's idiom gives double ones, and the two are published as
+        # interchangeable.
         raise usage_error(
             "--batch-size must be a whole number of at least 1.",
-            f"Got {requested!r}. The server accepts at most "
+            f'Got "{requested}". The server accepts at most '
             f"{SERVER_BULK_MAX} records per request.",
         )
     return min(value, SERVER_BULK_MAX)

{memorysync_cli-1.2.0 → memorysync_cli-1.3.0}/src/memorysync_cli/registry.json

@@ -372,8 +372,8 @@
     {
       "name": "import",
       "summary": "Bulk load memories from a JSON or JSONL file.",
-      "description": "Each record needs a text field, and may carry its own user and metadata. Validates the whole file before sending anything, and reports per-row errors with line numbers rather than failing on the first bad row.",
-      "usage": "memorysync import <file> [--user <id>] [--batch-size <n>]",
+      "description": "Each record needs a text field, and may carry its own user and metadata. Validates the whole file before sending anything, and reports per-row errors with line numbers rather than failing on the first bad row. Pass --resume to make re-running the same file safe: each record is sent with an identifier the server remembers, so rows that already landed are reported as skipped instead of being stored a second time.",
+      "usage": "memorysync import <file> [--user <id>] [--batch-size <n>] [--resume]",
       "flags": [
         {
           "name": "--user",
@@ -386,6 +386,15 @@
           "value": "n",
           "description": "Records per request. Default 50."
         },
+        {
+          "name": "--resume",
+          "description": "Send a per-record identifier so re-running the same file skips rows already stored."
+        },
+        {
+          "name": "--ref-field",
+          "value": "name",
+          "description": "Field holding each record’s own id, used by --resume. Default: id, then _id, then uuid."
+        },
         {
           "name": "--continue-on-error",
           "description": "Keep going after a failed batch."
@@ -396,7 +405,8 @@
         }
       ],
       "examples": [
-        "memorysync import memories.jsonl --user alice --dry-run"
+        "memorysync import memories.jsonl --user alice --dry-run",
+        "memorysync import memories.jsonl --user alice --resume"
       ],
       "requires_auth": true,
       "consumes_quota": "add_requests"

memorysync_cli-1.2.0/src/memorysync_cli/_version.py

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