memorysync-cli 1.0.2__py3-none-any.whl

memorysync_cli/commands/memory.py

@@ -0,0 +1,629 @@
+"""The memory commands: add, search, list, get, update, delete, import, export.
+
+Each returns ``{"data": ..., "text": callable}`` - structured output plus a lazy
+human renderer - so ``main`` decides the format and these never print. That is
+what lets every command support every output format, which Mem0's do not.
+
+Mirrors ``sdk/cli/src/commands/memory.mjs``, including the two places where the
+API's silent degradation has to be turned back into something a terminal user can
+act on: over a plan limit ``add`` returns 200 having stored nothing and ``search``
+returns an empty list, on purpose, so an assistant never narrates billing state to
+an end user. From a shell that silence is unhelpful, so usage is checked and the
+result becomes a distinct exit code.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+import time
+from pathlib import Path
+from typing import Any
+
+from ..errors import quota_error, usage_error
+from ..http import ApiClient
+from ..output import render_table, style
+
+
+def _require_user(ctx: dict) -> str:
+    user = (ctx.get("settings") or {}).get("user")
+    if not user:
+        raise usage_error(
+            "This command needs an end user.",
+            "Pass --user <id>, or set a default with `memorysync init --user <id>`. "
+            "Memory is always scoped to a user, so there is no sensible default.",
+        )
+    return str(user)
+
+
+def _numeric_id(value: Any, label: str = "memory id") -> str:
+    """Accept ``m_123`` or ``123``; the API's numeric routes need the digits."""
+    text = str(value or "").strip()
+    body = text[2:] if text.startswith("m_") else text
+    if not body.isdigit():
+        raise usage_error(f'"{text}" is not a {label}.', "Expected something like m_60632.")
+    return body
+
+
+def _parse_json_flag(raw: Any, label: str) -> dict | None:
+    if raw is None or raw is False:
+        return None
+    try:
+        parsed = json.loads(raw)
+    except ValueError as error:
+        raise usage_error(f"--{label} is not valid JSON: {error}") from None
+    if not isinstance(parsed, dict):
+        raise usage_error(f"--{label} must be a JSON object.")
+    return parsed
+
+
+def _parse_limit(value: Any, fallback: int, maximum: int) -> int:
+    if value is None or value is False:
+        return fallback
+    try:
+        parsed = int(str(value))
+    except ValueError:
+        raise usage_error(f"--limit must be a whole number between 1 and {maximum}.") from None
+    if parsed < 1 or parsed > maximum:
+        raise usage_error(f"--limit must be a whole number between 1 and {maximum}.")
+    return parsed
+
+
+def _read_stdin() -> str | None:
+    """Text piped in, or None when stdin is a terminal.
+
+    Checked with isatty first: reading unconditionally would hang waiting for
+    input that is never coming, which is worse than a usage error.
+    """
+    if sys.stdin is None or sys.stdin.isatty():
+        return None
+    data = sys.stdin.read().strip()
+    return data or None
+
+
+def _normalize_memory(raw: Any) -> dict:
+    """One output shape regardless of which route served the record.
+
+    The API returns several shapes across routes; normalising here is what makes
+    ``-o json`` stable and comparable between the two CLIs.
+    """
+    if not isinstance(raw, dict):
+        return {"id": None, "text": None}
+
+    identifier = raw.get("memory_id")
+    if identifier is None and raw.get("id") is not None:
+        identifier = f"m_{raw['id']}"
+
+    return {
+        "id": identifier,
+        "text": raw.get("text") or raw.get("raw_text") or raw.get("content"),
+        "score": raw.get("score"),
+        "source": raw.get("source"),
+        "tags": raw.get("tags"),
+        "metadata": raw.get("metadata"),
+        "created_at": raw.get("created_at"),
+    }
+
+
+def _usage_used_up(api: ApiClient, metric: str) -> bool:
+    """Whether the named metric has no headroom left.
+
+    Called only when a response was empty, because it costs a request and an empty
+    result is usually just an empty result.
+    """
+    try:
+        usage = api.usage_summary()
+    except Exception:  # noqa: BLE001 - a failed usage read must not mask the result
+        return False
+    if not isinstance(usage, dict):
+        return False
+    for entry in usage.get("metrics") or []:
+        if not isinstance(entry, dict) or entry.get("metric") != metric:
+            continue
+        limit = entry.get("limit")
+        used = entry.get("used")
+        if isinstance(limit, (int, float)) and isinstance(used, (int, float)):
+            return limit > 0 and used >= limit
+    return False
+
+
+def _resolve_tenant(api: ApiClient) -> str:
+    """The tenant id, which the v1 list route needs in its path.
+
+    Derived from the project listing rather than asked for: a user should not have
+    to know their internal tenant id to list their own memories.
+    """
+    projects = api.projects()
+    first = projects[0] if isinstance(projects, list) and projects else None
+    if isinstance(projects, dict):
+        entries = projects.get("projects") or []
+        first = entries[0] if entries else None
+    if not isinstance(first, dict) or not first.get("tenant_id"):
+        from ..errors import not_found_error
+
+        raise not_found_error(
+            "Could not determine the tenant for this key.",
+            "Run `memorysync doctor` to check the credential.",
+        )
+    return str(first["tenant_id"])
+
+
+# ---------------------------------------------------------------------------
+# add
+# ---------------------------------------------------------------------------
+
+
+def add(ctx: dict) -> dict:
+    user = _require_user(ctx)
+    flags, positionals, api = ctx["flags"], ctx["positionals"], ctx["api"]
+
+    text = " ".join(positionals).strip() or None
+    if flags.get("file"):
+        try:
+            text = Path(flags["file"]).read_text(encoding="utf-8").strip()
+        except OSError as error:
+            raise usage_error(f"Could not read {flags['file']}: {error}") from None
+    if not text:
+        text = _read_stdin()
+    if not text:
+        raise usage_error(
+            "Nothing to store.",
+            "Give text as an argument, use --file, or pipe it in.",
+        )
+
+    metadata = _parse_json_flag(flags.get("metadata"), "metadata")
+    body: dict[str, Any] = {"text": text, "source": flags.get("source") or "cli"}
+    if metadata:
+        body["metadata"] = metadata
+    if flags.get("dedupe") is False:
+        body["deduplicate"] = False
+
+    if flags.get("dry_run"):
+        data = {
+            "would_store": text,
+            "source": body["source"],
+            "metadata": metadata,
+            "user": user,
+        }
+        return {
+            "data": data,
+            "text": lambda: "\n".join(
+                [
+                    style.yellow("Dry run. Nothing was stored."),
+                    f"{style.dim('user    ')} {user}",
+                    f"{style.dim('source  ')} {body['source']}",
+                    f"{style.dim('text    ')} {text}",
+                ]
+            ),
+        }
+
+    created = api.add_memory(body)
+    memory = _normalize_memory(created)
+
+    if not memory["id"] and _usage_used_up(api, "add_requests"):
+        raise quota_error("Your plan's add limit is used up, so nothing was stored.")
+
+    status = "created"
+    if flags.get("wait") and memory["id"]:
+        settled = _wait_for_searchable(api, memory["id"], ctx["settings"]["timeout"])
+        status = (
+            "searchable"
+            if settled.get("searchable")
+            else settled.get("processing_status") or "processing"
+        )
+
+    payload = {**memory, "status": status}
+    return {
+        "data": payload,
+        "text": lambda: "\n".join(
+            line
+            for line in [
+                f"{style.green('Stored')} {style.bold(memory['id'] or '(no id)')}",
+                f"{style.dim('extracted')} {memory['text']}" if memory["text"] else None,
+                f"{style.dim('state    ')} {status}" if flags.get("wait") else None,
+            ]
+            if line
+        ),
+    }
+
+
+def _wait_for_searchable(api: ApiClient, memory_id: str, timeout_ms: int) -> dict:
+    """Poll ingestion until the memory is searchable or time runs out.
+
+    Capped at two minutes regardless of --timeout, because a longer wait is almost
+    always a stuck job rather than a slow one.
+    """
+    deadline = time.monotonic() + min(timeout_ms, 120000) / 1000
+    last: dict = {}
+    while time.monotonic() < deadline:
+        try:
+            last = api.memory_status(_numeric_id(memory_id)) or {}
+        except Exception:  # noqa: BLE001 - keep polling through a transient failure
+            last = {}
+        if last.get("searchable"):
+            return last
+        if last.get("processing_status") == "failed":
+            return last
+        time.sleep(1.5)
+    return last or {"searchable": False, "processing_status": "timeout"}
+
+
+# ---------------------------------------------------------------------------
+# search
+# ---------------------------------------------------------------------------
+
+
+def search(ctx: dict) -> dict:
+    _require_user(ctx)
+    flags, positionals, api = ctx["flags"], ctx["positionals"], ctx["api"]
+
+    query = " ".join(positionals).strip()
+    if not query:
+        raise usage_error("Nothing to search for.", 'memorysync search "what to look for"')
+
+    limit = _parse_limit(flags.get("limit"), 5, 50)
+    body: dict[str, Any] = {"query": query, "k": limit}
+    if flags.get("rerank") is False:
+        body["rerank"] = False
+
+    response = api.query_memory(body) or {}
+    memories = [_normalize_memory(item) for item in (response.get("memories") or [])]
+
+    if not memories and _usage_used_up(api, "retrieval_requests"):
+        raise quota_error(
+            "Your plan's retrieval limit is used up, so no results were returned."
+        )
+
+    if flags.get("context"):
+        data: Any = {"context": response.get("context") or "", "count": len(memories)}
+    else:
+        data = memories
+
+    def render() -> str:
+        if flags.get("context"):
+            return response.get("context") or style.dim("(no context assembled)")
+        if not memories:
+            return style.dim(f'No memories matched "{query}".')
+        rows = [
+            [
+                item["id"] or "-",
+                "-" if item.get("score") is None else f"{float(item['score']):.3f}",
+                item.get("text") or "",
+            ]
+            for item in memories
+        ]
+        table = render_table(["id", "score", "memory"], rows, [14, 7, 78])
+        latency = response.get("latency_ms")
+        suffix = f" in {round(latency)}ms" if latency else ""
+        plural = "" if len(memories) == 1 else "s"
+        return f"{table}\n{style.dim(f'{len(memories)} result{plural}{suffix}')}"
+
+    return {"data": data, "text": render}
+
+
+# ---------------------------------------------------------------------------
+# list, get
+# ---------------------------------------------------------------------------
+
+
+def list_memories(ctx: dict) -> dict:
+    user = _require_user(ctx)
+    flags, api = ctx["flags"], ctx["api"]
+    limit = _parse_limit(flags.get("limit"), 20, 1000)
+
+    tenant = _resolve_tenant(api)
+    response = api.list_memories(tenant, user, limit) or {}
+    memories = [_normalize_memory(item) for item in (response.get("memories") or [])]
+
+    def render() -> str:
+        if not memories:
+            return style.dim(f"No memories stored for {user}.")
+        rows = [
+            [
+                item["id"] or "-",
+                (item.get("created_at") or "")[:10],
+                item.get("source") or "-",
+                item.get("text") or "",
+            ]
+            for item in memories
+        ]
+        table = render_table(["id", "created", "source", "memory"], rows, [14, 10, 12, 66])
+        total = response.get("total", len(memories))
+        return f"{table}\n{style.dim(f'{len(memories)} of {total}')}"
+
+    return {"data": memories, "text": render}
+
+
+def get(ctx: dict) -> dict:
+    _require_user(ctx)
+    positionals, api = ctx["positionals"], ctx["api"]
+    if not positionals:
+        raise usage_error("Which memory?", "memorysync get m_60632")
+
+    status = api.memory_status(_numeric_id(positionals[0])) or {}
+
+    def render() -> str:
+        return "\n".join(
+            f"{style.dim(key.ljust(24))} {'-' if value is None else value}"
+            for key, value in status.items()
+        )
+
+    return {"data": status, "text": render}
+
+
+# ---------------------------------------------------------------------------
+# delete
+# ---------------------------------------------------------------------------
+
+
+def delete_memories(ctx: dict) -> dict:
+    """Delete by id, or every memory for one end user with --all.
+
+    `--all` means every memory belonging to that one user, and nothing beyond it.
+    It resolves ids and deletes them through `forget`, the same memory-scoped route
+    the id form uses.
+
+    It must never call ``DELETE /memory/user/purge``. Despite living under
+    ``/memory/`` and reading as end-user scoped, that route ignores the end user
+    and erases the account behind the credential - password hash, every API key,
+    memberships, auth providers, MFA, and every end user underneath. The Node CLI
+    did call it, and it deleted a live account during a routine cleanup step. There
+    is no CLI feature that wants account erasure, so no client method reaches it.
+    """
+    user = _require_user(ctx)
+    flags, positionals, api = ctx["flags"], ctx["positionals"], ctx["api"]
+    ids = [value for value in positionals if value]
+
+    if not flags.get("all") and not ids:
+        raise usage_error("Nothing to delete.", "Give one or more memory ids, or pass --all.")
+    if flags.get("all") and ids:
+        raise usage_error(
+            "Pass either memory ids or --all, not both.",
+            "They mean different things and combining them is ambiguous.",
+        )
+
+    # Two-step by default, matching the MCP delete tools. Without --yes this shows
+    # what would go and stops, so an ambiguous command cannot clear a scope.
+    confirmed = bool(flags.get("yes")) and not flags.get("dry_run")
+
+    if flags.get("all"):
+        tenant = _resolve_tenant(api)
+        existing = api.list_memories(tenant, user, 0) or {}
+        all_ids = []
+        for item in existing.get("memories") or []:
+            raw = item.get("id") if isinstance(item, dict) else None
+            if raw is None and isinstance(item, dict):
+                raw = item.get("memory_id")
+            if raw in (None, ""):
+                continue
+            all_ids.append(int(_numeric_id(raw)))
+
+        if not confirmed:
+            plural = "y" if len(all_ids) == 1 else "ies"
+            return {
+                "data": {"would_delete": all_ids, "count": len(all_ids), "user": user, "confirmed": False},
+                "text": lambda: "\n".join(
+                    [
+                        style.yellow(f"Dry run. Would delete all {len(all_ids)} memor{plural} for {user}."),
+                        style.dim("Only this end user's memories. The account and its API keys are untouched."),
+                        style.dim("Nothing was deleted. Re-run with --yes to confirm."),
+                    ]
+                ),
+            }
+
+        if not all_ids:
+            return {
+                "data": {"deleted": [], "count": 0, "user": user},
+                "text": lambda: style.dim(f"No memories stored for {user}. Nothing to delete."),
+            }
+
+        purged = api.forget({"memory_ids": all_ids, "dry_run": False})
+        removed = purged if isinstance(purged, list) else (purged or {}).get("memory_ids") or all_ids
+        plural = "y" if len(removed) == 1 else "ies"
+        return {
+            "data": {"deleted": removed, "count": len(removed), "user": user},
+            "text": lambda: f"{style.green('Deleted')} all {len(removed)} memor{plural} for {user}",
+        }
+
+    memory_ids = [int(_numeric_id(value)) for value in ids]
+
+    if not confirmed:
+        preview = api.forget({"memory_ids": memory_ids, "dry_run": True})
+        would = preview if isinstance(preview, list) else (preview or {}).get("memory_ids") or []
+        plural = "y" if len(would) == 1 else "ies"
+        return {
+            "data": {"would_delete": would, "count": len(would), "user": user, "confirmed": False},
+            "text": lambda: "\n".join(
+                line
+                for line in [
+                    style.yellow(f"Dry run. Would delete {len(would)} memor{plural}."),
+                    style.dim("  " + ", ".join(f"m_{i}" for i in would)) if would else None,
+                    style.dim("Nothing was deleted. Re-run with --yes to confirm."),
+                ]
+                if line
+            ),
+        }
+
+    deleted = api.forget({"memory_ids": memory_ids, "dry_run": False})
+    removed = deleted if isinstance(deleted, list) else (deleted or {}).get("memory_ids") or []
+    plural = "y" if len(removed) == 1 else "ies"
+    return {
+        "data": {"deleted": removed, "count": len(removed), "user": user},
+        "text": lambda: f"{style.green('Deleted')} {len(removed)} memor{plural}",
+    }
+
+
+# ---------------------------------------------------------------------------
+# update, import, export
+# ---------------------------------------------------------------------------
+
+
+def update(ctx: dict) -> dict:
+    _require_user(ctx)
+    flags, positionals, api = ctx["flags"], ctx["positionals"], ctx["api"]
+    if not positionals:
+        raise usage_error("Which memory?", 'memorysync update m_60632 "new text"')
+
+    identifier = _numeric_id(positionals[0])
+    text = " ".join(positionals[1:]).strip() or None
+    metadata = _parse_json_flag(flags.get("metadata"), "metadata")
+
+    if not text and metadata is None:
+        raise usage_error(
+            "Nothing to change.",
+            "Give replacement text, or --metadata with a JSON object.",
+        )
+
+    body: dict[str, Any] = {}
+    if text:
+        body["text"] = text
+    if metadata is not None:
+        body["metadata"] = metadata
+
+    updated = api.request("PATCH", f"/memory/{identifier}", body=body) or {}
+    memory = _normalize_memory(updated)
+    return {
+        "data": memory,
+        "text": lambda: f"{style.green('Updated')} {style.bold(memory['id'] or f'm_{identifier}')}",
+    }
+
+
+def import_memories(ctx: dict) -> dict:
+    """Bulk load from JSON or JSONL, validating the whole file first.
+
+    Validation happens before anything is sent so a bad row on line 400 does not
+    leave 399 memories already stored, which is the difference between a retryable
+    failure and a partial import someone has to reconcile by hand.
+    """
+    flags, positionals, api = ctx["flags"], ctx["positionals"], ctx["api"]
+    user = _require_user(ctx)
+
+    source_path = flags.get("file") or (positionals[0] if positionals else None)
+    if not source_path:
+        raise usage_error("Which file?", "memorysync import memories.jsonl --user alice")
+
+    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
+
+    records: list[dict] = []
+    errors: list[str] = []
+
+    stripped = raw.strip()
+    if stripped.startswith("["):
+        try:
+            parsed = json.loads(stripped)
+        except ValueError as error:
+            raise usage_error(f"{source_path} is not valid JSON: {error}") from None
+        if not isinstance(parsed, list):
+            raise usage_error(f"{source_path} must contain a JSON array.")
+        candidates = list(enumerate(parsed, start=1))
+    else:
+        candidates = []
+        for number, line in enumerate(stripped.splitlines(), start=1):
+            if not line.strip():
+                continue
+            try:
+                candidates.append((number, json.loads(line)))
+            except ValueError as error:
+                errors.append(f"line {number}: {error}")
+
+    for number, entry in candidates:
+        if not isinstance(entry, dict):
+            errors.append(f"line {number}: expected an object")
+            continue
+        text = entry.get("text") or entry.get("memory") or entry.get("content")
+        if not text:
+            errors.append(f"line {number}: no text, memory or content field")
+            continue
+        record: dict[str, Any] = {"text": str(text), "source": entry.get("source") or "import"}
+        if isinstance(entry.get("metadata"), dict):
+            record["metadata"] = entry["metadata"]
+        records.append(record)
+
+    if errors:
+        raise usage_error(
+            f"{source_path} has {len(errors)} invalid row(s); nothing was imported.",
+            "; ".join(errors[:5]) + ("; ..." if len(errors) > 5 else ""),
+        )
+    if not records:
+        raise usage_error(f"{source_path} contained no records.")
+
+    if flags.get("dry_run"):
+        return {
+            "data": {"would_import": len(records), "user": user},
+            "text": lambda: style.yellow(
+                f"Dry run. {len(records)} record(s) validated. Nothing was imported."
+            ),
+        }
+
+    stored, skipped = [], 0
+    for record in records:
+        created = api.add_memory(record)
+        memory = _normalize_memory(created)
+        if memory["id"]:
+            stored.append(memory["id"])
+        else:
+            skipped += 1
+
+    return {
+        "data": {"imported": stored, "count": len(stored), "skipped": skipped, "user": user},
+        "text": lambda: "\n".join(
+            [
+                f"{style.green('Imported')} {len(stored)} of {len(records)}",
+                style.dim(f"  {skipped} skipped as duplicate or low value") if skipped else "",
+            ]
+        ).strip(),
+    }
+
+
+def export_memories(ctx: dict) -> dict:
+    user = _require_user(ctx)
+    flags, api = ctx["flags"], ctx["api"]
+
+    fmt = (flags.get("format") or "json").lower()
+    if fmt not in {"json", "jsonl", "csv"}:
+        raise usage_error(
+            f'Unknown export format "{fmt}".',
+            "One of: json, jsonl, csv.",
+        )
+
+    tenant = _resolve_tenant(api)
+    response = api.list_memories(tenant, user, 0) or {}
+    memories = [_normalize_memory(item) for item in (response.get("memories") or [])]
+
+    serialized = _serialize_export(memories, fmt)
+
+    if flags.get("out"):
+        Path(flags["out"]).write_text(serialized, encoding="utf-8")
+
+    def render() -> str:
+        if flags.get("out"):
+            plural = "y" if len(memories) == 1 else "ies"
+            return f"{style.green('Exported')} {len(memories)} memor{plural} to {flags['out']}"
+        return serialized
+
+    return {"data": memories, "text": render}
+
+
+def _serialize_export(memories: list[dict], fmt: str) -> str:
+    if fmt == "json":
+        return json.dumps(memories, indent=2) + "\n"
+    if fmt == "jsonl":
+        if not memories:
+            return ""
+        return "\n".join(json.dumps(item) for item in memories) + "\n"
+
+    # CSV, quoted by hand rather than through the csv module so the output is
+    # identical to the Node CLI's, which also writes it directly.
+    def escape(value: Any) -> str:
+        text = "" if value is None else str(value)
+        if any(character in text for character in [',', '"', "\n"]):
+            return '"' + text.replace('"', '""') + '"'
+        return text
+
+    headers = ["id", "text", "source", "created_at"]
+    lines = [",".join(headers)]
+    lines.extend(",".join(escape(item.get(header)) for header in headers) for item in memories)
+    return "\n".join(lines) + "\n"