portable-memory 0.1.2__py3-none-any.whl

portable_memory/__init__.py

@@ -0,0 +1,78 @@
+"""Portable Memory — an open, vendor-neutral format for AI memory portability.
+
+Python reference SDK. The on-disk format is defined by ``Spec/portable-memory-spec.md``
+and the language-neutral ``Schemas/``; this package is byte-for-byte interoperable with
+the Swift reference SDK (github.com/MacPaw/portable-memory-swift).
+"""
+from __future__ import annotations
+
+from ._codec import (
+    canonical_json,
+    format_timestamp,
+    from_wire,
+    parse_timestamp,
+    to_line,
+    to_wire,
+)
+from .format import (
+    IMPORT_ORDER,
+    BundlePath,
+    ConformanceLevel,
+    ExportMode,
+    MemFileEntry,
+    MemFormat,
+    MemKind,
+    MemLimits,
+    MemManifest,
+)
+from .hashing import embedding_cache_key, sha256_hex, sha256_hex_str
+from .interop import KNOWN_EPISODE_KEYS, extract_episode_ext, merge_episode_ext
+from .records import (
+    MemImportReport,
+    PortableCategory,
+    PortableChunk,
+    PortableCommunity,
+    PortableContext,
+    PortableCore,
+    PortableEdge,
+    PortableEntity,
+    PortableEpisode,
+    PortableEpisodeLink,
+    PortableFact,
+    PortableFactLink,
+    PortablePreference,
+    PortableProcedure,
+    PortableResource,
+    PortableSecretRef,
+)
+from .tombstone import DerivedRefs, PortableAuditRecord, Tombstone, TombstoneOp
+
+__version__ = "0.1.0"
+
+# Logic modules.
+from .store import PortableMemoryStore, StoreInfo  # noqa: E402
+from .signing import (  # noqa: E402
+    PortableSigning,
+    PortableSigningKey,
+    PortableVerifyingKey,
+)
+from .validator import BundleValidator, ValidationResult  # noqa: E402
+from .exporter import BundleExporter  # noqa: E402
+from .importer import BundleImporter, MemImportError  # noqa: E402
+
+__all__ = [
+    "canonical_json", "format_timestamp", "parse_timestamp", "to_wire", "from_wire", "to_line",
+    "MemFormat", "MemKind", "IMPORT_ORDER", "ExportMode", "ConformanceLevel",
+    "MemFileEntry", "MemManifest", "MemLimits", "BundlePath",
+    "sha256_hex", "sha256_hex_str", "embedding_cache_key",
+    "KNOWN_EPISODE_KEYS", "extract_episode_ext", "merge_episode_ext",
+    "PortableEpisode", "PortableEntity", "PortableEdge", "PortableFact", "PortableFactLink",
+    "PortableEpisodeLink", "PortableResource", "PortableChunk", "PortableCore",
+    "PortableProcedure", "PortableContext", "PortableCommunity", "PortableCategory",
+    "PortablePreference", "PortableSecretRef", "MemImportReport",
+    "DerivedRefs", "TombstoneOp", "Tombstone", "PortableAuditRecord",
+    "PortableMemoryStore", "StoreInfo",
+    "PortableSigning", "PortableSigningKey", "PortableVerifyingKey",
+    "BundleValidator", "ValidationResult",
+    "BundleExporter", "BundleImporter", "MemImportError",
+]

portable_memory/_codec.py

@@ -0,0 +1,189 @@
+"""Canonical JSON + dataclass <-> wire-dict codec.
+
+The canonical form is byte-identical to the Swift reference SDK's ``MemCodec`` (spec
+§1.1): UTF-8, no BOM, object keys sorted recursively, no insignificant whitespace,
+``/`` unescaped, non-ASCII emitted raw (not ``\\u``), shortest round-tripping numbers,
+and whole-second UTC ``Z`` timestamps. That is what lets a bundle written by one
+implementation validate (matching checksums) in the other.
+"""
+from __future__ import annotations
+
+import json
+import types
+from dataclasses import fields, is_dataclass
+from datetime import datetime, timezone
+from enum import Enum
+from typing import Any, Union, get_args, get_origin, get_type_hints
+
+
+# Integral doubles below this bound serialize as plain integers ("1", not "1.0" —
+# spec §1.1); at/above it both reference encoders switch to exponent form ("1e+16"),
+# which Python's repr already produces. Probed against the Swift encoder: the two
+# agree byte-for-byte on either side of this boundary.
+_INTEGRAL_FLOAT_BOUND = 1e16
+
+
+def _canon_numbers(obj: Any) -> Any:
+    """Normalize floats to the canonical number form (spec §1.1) before dumping.
+
+    ``json.dumps`` renders ``1.0`` as ``"1.0"``, but Canonical JSON (ECMAScript /
+    JCS shortest-round-trip rule) requires integral values to emit with no decimal
+    point — ``"1"``. Convert integral floats (including ``-0.0`` → ``0``) to ``int``;
+    ``bool`` is untouched (it is an ``int`` subclass, never a ``float``).
+    """
+    if isinstance(obj, float):
+        if obj.is_integer() and abs(obj) < _INTEGRAL_FLOAT_BOUND:
+            return int(obj)
+        return obj
+    if isinstance(obj, dict):
+        return {k: _canon_numbers(v) for k, v in obj.items()}
+    if isinstance(obj, (list, tuple)):
+        return [_canon_numbers(v) for v in obj]
+    return obj
+
+
+def canonical_json(obj: Any) -> str:
+    """Serialize one value to a single canonical JSON line (no trailing newline)."""
+    # sort_keys -> sorted keys; separators -> no whitespace; ensure_ascii=False -> raw
+    # UTF-8 (and Python never escapes '/'); floats use repr = shortest round-trip;
+    # allow_nan=False -> NaN/Infinity raise instead of emitting invalid RFC 8259 JSON.
+    return json.dumps(_canon_numbers(obj), ensure_ascii=False, sort_keys=True,
+                      separators=(",", ":"), allow_nan=False)
+
+
+def format_timestamp(dt: datetime) -> str:
+    """Whole-second UTC RFC 3339 with a literal ``Z`` (canonical output, spec §1.1)."""
+    if dt.tzinfo is None:
+        dt = dt.replace(tzinfo=timezone.utc)
+    dt = dt.astimezone(timezone.utc).replace(microsecond=0)
+    return dt.strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+def parse_timestamp(s: str) -> datetime:
+    """Lenient RFC 3339 parse: accepts ``Z``, numeric offsets, and fractional seconds.
+
+    Canonical output is always whole-second UTC, but a foreign bundle may emit other
+    forms — a reader accepts them and re-emits canonically on the next export.
+    """
+    raw = s
+    if s[-1:] in ("Z", "z"):
+        s = s[:-1] + "+00:00"
+    try:
+        dt = datetime.fromisoformat(s)
+    except ValueError as exc:
+        raise ValueError(f"not a valid RFC 3339 timestamp: {raw}") from exc
+    if dt.tzinfo is None:
+        dt = dt.replace(tzinfo=timezone.utc)
+    return dt.astimezone(timezone.utc)
+
+
+def _json_key(field) -> str:
+    return field.metadata.get("json", field.name)
+
+
+def _unwrap_optional(hint: Any) -> Any:
+    """T from Optional[T] / T | None; hint unchanged otherwise."""
+    origin = get_origin(hint)
+    if origin is Union or origin is types.UnionType:
+        non_none = [a for a in get_args(hint) if a is not type(None)]
+        if len(non_none) == 1:
+            return non_none[0]
+    return hint
+
+
+def _encode_value(value: Any) -> Any:
+    if value is None:
+        return None
+    if isinstance(value, datetime):
+        return format_timestamp(value)
+    if isinstance(value, Enum):
+        return value.value
+    if is_dataclass(value):
+        return to_wire(value)
+    if isinstance(value, (list, tuple)):
+        return [_encode_value(v) for v in value]
+    if isinstance(value, dict):
+        return {k: _encode_value(v) for k, v in value.items()}
+    return value  # str / int / float / bool
+
+
+def to_wire(obj: Any) -> dict:
+    """Dataclass -> wire dict (camelCase keys; absent optionals omitted, never null)."""
+    out: dict[str, Any] = {}
+    for f in fields(obj):
+        val = getattr(obj, f.name)
+        if val is None:
+            continue
+        out[_json_key(f)] = _encode_value(val)
+    return out
+
+
+def _decode_value(value: Any, hint: Any) -> Any:
+    inner = _unwrap_optional(hint)
+    origin = get_origin(inner)
+    if inner is datetime:
+        if not isinstance(value, str):
+            raise TypeError(f"expected RFC 3339 string, got {type(value).__name__}")
+        return parse_timestamp(value)
+    if isinstance(inner, type) and issubclass(inner, Enum):
+        return inner(value)
+    if is_dataclass(inner):
+        return from_wire(inner, value)
+    if origin in (list, tuple):
+        if not isinstance(value, list):
+            raise TypeError(f"expected array, got {type(value).__name__}")
+        args = get_args(inner)
+        elem = args[0] if args else Any
+        return [_decode_value(v, elem) for v in value]
+    if origin is dict:
+        if not isinstance(value, dict):
+            raise TypeError(f"expected object, got {type(value).__name__}")
+        args = get_args(inner)
+        val_hint = args[1] if len(args) == 2 else Any
+        return {k: _decode_value(v, val_hint) for k, v in value.items()}
+    # Strict scalars — a wrong-typed field must fail the decode (as Swift's Codable
+    # does), not be silently absorbed and re-emitted through the canonical exporter.
+    if inner is str:
+        if not isinstance(value, str):
+            raise TypeError(f"expected string, got {type(value).__name__}")
+        return value
+    if inner is bool:
+        if not isinstance(value, bool):
+            raise TypeError(f"expected boolean, got {type(value).__name__}")
+        return value
+    if inner is int:
+        if isinstance(value, bool) or not isinstance(value, (int, float)):
+            raise TypeError(f"expected integer, got {type(value).__name__}")
+        # Integral floats are accepted for integer fields (Swift's decoder does the
+        # same): canonical form writes 2.0 as "2", so a reader must take "2.0" too.
+        if isinstance(value, float):
+            if not value.is_integer():
+                raise TypeError("expected integer, got non-integral number")
+            return int(value)
+        return value
+    if inner is float:
+        if isinstance(value, bool) or not isinstance(value, (int, float)):
+            raise TypeError(f"expected number, got {type(value).__name__}")
+        # Canonical form writes 1.0 as "1", so integer tokens must decode into
+        # float fields.
+        return float(value)
+    return value
+
+
+def from_wire(cls: type, data: dict) -> Any:
+    """Wire dict -> dataclass. Absent keys fall back to the field default."""
+    hints = get_type_hints(cls)
+    kwargs = {}
+    for f in fields(cls):
+        key = _json_key(f)
+        if key in data and data[key] is not None:
+            try:
+                kwargs[f.name] = _decode_value(data[key], hints[f.name])
+            except (TypeError, ValueError) as exc:
+                raise type(exc)(f"{cls.__name__}.{key}: {exc}") from exc
+    return cls(**kwargs)
+
+
+def to_line(obj: Any) -> str:
+    """Dataclass (or plain value) -> one canonical JSON line."""
+    return canonical_json(to_wire(obj) if is_dataclass(obj) else obj)

portable_memory/adapters/__init__.py

@@ -0,0 +1,15 @@
+"""Vendor ingest adapters (cross-provider import).
+
+Each adapter maps a foreign export onto portable episodes; whatever it doesn't model is
+preserved in ``metadata`` (namespaced) so a later ``.mem`` export stays lossless. Every
+adapter exposes ``parse_episodes(...)`` (input shape varies by source) returning
+``list[PortableEpisode]``.
+"""
+from __future__ import annotations
+
+from .claude import ClaudeAdapter
+from .mem0 import Mem0Adapter
+from .mem0 import parse_episodes  # back-compat: the bare name is the original mem0 adapter
+from .openai import OpenAIAdapter
+
+__all__ = ["Mem0Adapter", "OpenAIAdapter", "ClaudeAdapter", "parse_episodes"]

portable_memory/adapters/claude.py

@@ -0,0 +1,162 @@
+"""Anthropic / Claude memory ingest adapter.
+
+Claude's memory is a *directory of files* — a ``MEMORY.md`` entrypoint plus topic files
+(markdown, commonly with YAML frontmatter), as used by the Claude Code auto-memory and the
+API memory tool. This adapter maps each memory file onto one portable episode: the file
+body becomes the episode text, and the frontmatter (``name``, ``description``,
+``metadata.type``) plus the file path are preserved into ``metadata`` (namespaced
+``claude_*``) so a later ``.mem`` export stays lossless.
+
+Input is the memory files themselves (not JSON), since Claude leaves the storage format to
+the host. Accepted shapes (tolerant):
+  * ``list`` of ``{"path": str, "content": str}`` (``name``/``text``/``body`` also accepted);
+  * ``list`` of ``(path, content)`` tuples;
+  * ``dict`` mapping ``path -> content``.
+
+Adapters are pure: files in, ``list[PortableEpisode]`` out. No host, store, or I/O.
+"""
+from __future__ import annotations
+
+import os
+import uuid
+from datetime import datetime, timezone
+from typing import Any
+
+from ..records import PortableEpisode
+
+__all__ = ["ClaudeAdapter", "parse_episodes"]
+
+_INDEX_FILES = {"MEMORY.md", "CLAUDE.md"}
+
+
+class ClaudeAdapter:
+    """Maps a set of Claude memory files onto portable episodes."""
+
+    @staticmethod
+    def parse_episodes(files: Any) -> list[PortableEpisode]:
+        episodes: list[PortableEpisode] = []
+        for path, content in _iter_files(files):
+            ep = _map_file(path, content)
+            if ep is not None:
+                episodes.append(ep)
+        return episodes
+
+
+def _iter_files(files: Any):
+    """Yield (path, content) from any accepted input shape."""
+    if isinstance(files, dict):
+        for path, content in files.items():
+            if isinstance(path, str) and isinstance(content, str):
+                yield path, content
+        return
+    if isinstance(files, (list, tuple)):
+        for f in files:
+            if isinstance(f, dict):
+                path = _first_str(f.get("path"), f.get("name")) or ""
+                content = _first_str(f.get("content"), f.get("text"), f.get("body"))
+                if content is not None:
+                    yield path, content
+            elif isinstance(f, (list, tuple)) and len(f) == 2 and isinstance(f[1], str):
+                yield (f[0] if isinstance(f[0], str) else ""), f[1]
+
+
+def _map_file(path: str, content: str) -> PortableEpisode | None:
+    frontmatter, body = _split_frontmatter(content)
+    text = (body or content).strip()
+    if not text:
+        return None
+
+    base = os.path.basename(path) if path else ""
+    name = frontmatter.get("name") or (base[:-3] if base.endswith(".md") else base) or None
+    description = frontmatter.get("description")
+    ctype = frontmatter.get("metadata.type") or frontmatter.get("type")
+
+    # Summary: the description, else the first non-empty line, else the name.
+    first_line = next((ln.strip() for ln in text.splitlines() if ln.strip()), "")
+    summary = (description or first_line or name or "")[:120]
+
+    meta: dict[str, str] = {}
+    _put(meta, "claude_path", path or None)
+    _put(meta, "claude_name", name)
+    _put(meta, "claude_type", ctype)
+    _put(meta, "claude_description", description)
+    if base in _INDEX_FILES:
+        meta["claude_role"] = "index"
+
+    now = datetime.now(timezone.utc)
+    return PortableEpisode(
+        id=name or (base[:-3] if base.endswith(".md") else base) or ("ep_" + uuid.uuid4().hex[:16]),
+        event_time=now,
+        mention_time=now,
+        ingestion_time=now,
+        source_type="note",
+        source_id=path or None,
+        actors=[],
+        summary=summary,
+        details=text,
+        sensitivity="low",
+        deleted_at=None,
+        metadata=meta,
+        context_id=None,
+        categories=[ctype] if ctype else [],
+        importance=0.5,
+        confidence=0.7,
+        lifecycle_state="HOT",
+        extraction_state="done",
+        last_accessed=None,
+        access_count=0,
+        pinned=False,
+        expiration_date=None,
+        vault_refs=[],
+        speaker=None,
+    )
+
+
+def _split_frontmatter(content: str) -> tuple[dict[str, str], str]:
+    """Parse a leading ``---`` YAML frontmatter block into a flat dict (nested keys as
+    ``parent.child``) + the remaining body. Returns ({}, content) when there is none.
+
+    A minimal, stdlib-only parser for the ``key: value`` subset the memory format uses
+    (Claude leaves the format to the host; the core stays dependency-free). Anything it
+    can't parse is left in the body, never dropped.
+    """
+    lines = content.splitlines()
+    if not lines or lines[0].strip() != "---":
+        return {}, content
+    end = next((i for i in range(1, len(lines)) if lines[i].strip() == "---"), None)
+    if end is None:
+        return {}, content
+
+    fm: dict[str, str] = {}
+    parent: str | None = None
+    for raw in lines[1:end]:
+        if not raw.strip() or raw.lstrip().startswith("#"):
+            continue
+        indented = raw[:1] in (" ", "\t")
+        key, sep, val = raw.strip().partition(":")
+        if not sep:
+            continue
+        key, val = key.strip(), val.strip()
+        if indented and parent is not None:
+            fm[f"{parent}.{key}"] = val
+        elif val == "":
+            parent = key  # a nested block follows
+        else:
+            fm[key] = val
+            parent = None
+    return fm, "\n".join(lines[end + 1:])
+
+
+def _first_str(*values: Any) -> str | None:
+    for v in values:
+        if isinstance(v, str):
+            return v
+    return None
+
+
+def _put(meta: dict[str, str], key: str, value: str | None) -> None:
+    if value:
+        meta[key] = value
+
+
+parse_episodes = ClaudeAdapter.parse_episodes

portable_memory/adapters/mem0.py

@@ -0,0 +1,247 @@
+"""mem0 (https://github.com/mem0ai/mem0) ingest adapter.
+
+Mirrors the Swift ``Mem0Adapter`` (Sources/PortableMemory/Adapters/Mem0Adapter.swift):
+maps a mem0 export — a bare JSON array, or ``{"results":[...]}`` / ``{"memories":[...]}``
+/ ``{"data":[...]}`` (the platform's paginated envelope also wraps ``results``) — onto
+portable episodes. The format is a superset container, so whatever mem0 models that the
+portable schema doesn't is preserved in ``metadata`` (namespaced ``mem0_*``) rather than
+dropped; a later ``.mem`` export stays lossless. That includes a generic sweep of any
+top-level key the mapping doesn't recognize (``score``, ``immutable``, ``memory_type``,
+future platform fields, …).
+
+mem0's promoted per-memory keys (OSS ``promoted_payload_keys``) are ``user_id``,
+``agent_id``, ``run_id``, ``actor_id``, ``role``, ``attributed_to``, and
+``expiration_date`` — all read here; ``expiration_date`` (normalized ``YYYY-MM-DD``)
+additionally maps onto the episode's own ``expiration_date``. Graph ``relations``
+(returned alongside ``results`` when graph memory is enabled) are NOT mapped in v1 —
+adapters return episodes only; entity/edge promotion is a possible follow-up.
+
+Adapters are pure: they take foreign bytes/JSON and return ``list[PortableEpisode]``
+that a host then imports. There is no host, store, or I/O here.
+"""
+from __future__ import annotations
+
+import json
+import uuid
+from datetime import datetime, timezone
+from typing import Any, Callable
+
+from .._codec import canonical_json, parse_timestamp
+from ..records import PortableEpisode
+
+__all__ = ["Mem0Adapter", "parse_episodes"]
+
+
+class Mem0Adapter:
+    """Maps a mem0 export onto portable episodes.
+
+    Missing/extra fields are handled gracefully; the original ``id``, ``hash``, role,
+    and the various actor ids are preserved into episode ``metadata``.
+    """
+
+    @staticmethod
+    def parse_episodes(data: bytes | str | dict) -> list[PortableEpisode]:
+        """Parse a mem0 export into portable episodes.
+
+        Accepts the already-decoded ``dict`` (or ``list``) as well as raw ``bytes`` /
+        ``str`` JSON — the Swift API takes ``Data`` only, but Python callers routinely
+        hold a parsed object, so we accept both without changing the mapping.
+        """
+        if isinstance(data, (bytes, bytearray, str)):
+            root: Any = json.loads(data)
+        else:
+            root = data
+
+        # A bare array, or one of the known envelope keys wrapping the array. Anything
+        # else (or a missing/mistyped envelope) yields no items rather than raising —
+        # mirrors the Swift adapter's tolerant shape handling.
+        if isinstance(root, list):
+            items = root
+        elif isinstance(root, dict):
+            items = (
+                _as_object_list(root.get("results"))
+                or _as_object_list(root.get("memories"))
+                or _as_object_list(root.get("data"))
+            )
+        else:
+            items = []
+
+        # Swift builds the ISO-8601 parsers once per call for large exports; the
+        # foundation's ``parse_timestamp`` is cheap, so we just wrap it in a lenient
+        # closure that returns ``None`` for missing/unparseable input (Swift returns nil
+        # from the failed-both-formatters path, which the call sites already tolerate).
+        def parse(s: Any) -> datetime | None:
+            if not isinstance(s, str) or not s:
+                return None
+            try:
+                return parse_timestamp(s)
+            except ValueError:
+                return None
+
+        episodes: list[PortableEpisode] = []
+        for item in items:
+            if not isinstance(item, dict):
+                continue  # compactMap drops non-object entries
+            ep = _map_one(item, parse)
+            if ep is not None:
+                episodes.append(ep)
+        return episodes
+
+
+def _as_object_list(value: Any) -> list[dict]:
+    """Return ``value`` when it's a list of dicts, else ``[]`` (mirrors the Swift
+    ``as? [[String: Any]]`` casts, which fail-to-nil on a mistyped envelope)."""
+    if isinstance(value, list) and all(isinstance(e, dict) for e in value):
+        return value
+    return []
+
+
+#: Top-level mem0 keys the mapping reads explicitly. Anything else is swept into
+#: ``mem0_<key>`` metadata so no field a mem0 version emits is ever dropped.
+_HANDLED_KEYS = frozenset({
+    "memory", "text", "data", "role", "user_id", "agent_id", "actor_id", "run_id",
+    "created_at", "updated_at", "metadata", "categories", "id", "hash",
+    "attributed_to", "expiration_date",
+})
+
+
+def _map_one(
+    o: dict,
+    parse: Callable[[Any], "datetime | None"],
+) -> PortableEpisode | None:
+    """Map one mem0 record onto a portable episode, or ``None`` when it carries no text."""
+    text = _first_str(o.get("memory"), o.get("text"), o.get("data")) or ""
+    if not text.strip():
+        return None  # nothing to remember
+
+    role = _opt_str(o.get("role"))
+    user_id = _opt_str(o.get("user_id"))
+    agent_id = _opt_str(o.get("agent_id"))
+    actor_id = _opt_str(o.get("actor_id"))
+    run_id = _opt_str(o.get("run_id"))
+
+    created = parse(o.get("created_at")) or datetime.now(timezone.utc)
+    updated = parse(o.get("updated_at"))
+    # mem0 normalizes expiration_date to date-only "YYYY-MM-DD"; the lenient parser
+    # accepts it (midnight UTC). The raw string is also preserved in metadata below.
+    expiration = parse(o.get("expiration_date"))
+
+    # Actors in mem0's own precedence: user, then agent, then explicit actor. Only
+    # non-empty ids are carried.
+    actors = [a for a in (user_id, agent_id, actor_id) if a]
+
+    # Foreign metadata first (stringified), then mem0 provenance overlaid. Provenance
+    # keys only land when the value is a non-empty string, matching Swift.
+    meta: dict[str, str] = {}
+    raw_meta = o.get("metadata")
+    if isinstance(raw_meta, dict):
+        for k, v in raw_meta.items():
+            meta[k] = _stringify(v)
+    provenance = {
+        "mem0_id": o.get("id"),
+        "mem0_hash": o.get("hash"),
+        "mem0_role": role,
+        "mem0_user_id": user_id,
+        "mem0_agent_id": agent_id,
+        "mem0_actor_id": actor_id,
+        "mem0_run_id": run_id,
+        "mem0_created_at": o.get("created_at"),
+        "mem0_updated_at": o.get("updated_at"),
+        "mem0_attributed_to": o.get("attributed_to"),
+        "mem0_expiration_date": o.get("expiration_date"),
+    }
+    for k, v in provenance.items():
+        if isinstance(v, str) and v:
+            meta[k] = v
+    # Lossless sweep: any top-level key the mapping doesn't recognize (score, immutable,
+    # memory_type, future platform fields, ...) is preserved as mem0_<key>. Nulls are
+    # skipped — mem0 emits e.g. "expiration_date": null. setdefault so user metadata or
+    # provenance that already claimed a key is never overwritten.
+    for k, v in o.items():
+        if k not in _HANDLED_KEYS and v is not None:
+            meta.setdefault(f"mem0_{k}", _stringify(v))
+
+    # Mirror Swift's `as? [String]`: a non-list (e.g. a bare string — which Python
+    # would happily iterate char-by-char) or a list with non-string members maps to [].
+    raw_categories = o.get("categories", [])
+    categories = (
+        raw_categories
+        if isinstance(raw_categories, list) and all(isinstance(c, str) for c in raw_categories)
+        else []
+    )
+
+    raw_id = _opt_str(o.get("id"))
+    episode_id = raw_id or ("ep_" + uuid.uuid4().hex[:16])
+
+    return PortableEpisode(
+        id=episode_id,
+        event_time=created,
+        mention_time=updated or created,
+        ingestion_time=created,
+        # A message with a role came from a conversation; anything else is free text.
+        source_type="chat" if role is not None else "text",
+        source_id=raw_id,
+        actors=actors,
+        summary=text[:120],
+        details=text,
+        sensitivity="low",
+        deleted_at=None,
+        metadata=meta,
+        context_id=run_id or None,
+        categories=categories,
+        importance=0.5,
+        confidence=0.7,
+        lifecycle_state="HOT",
+        extraction_state="done",
+        last_accessed=None,
+        access_count=0,
+        pinned=False,
+        expiration_date=expiration,
+        vault_refs=[],
+        # Only chat-shaped roles map to a speaker; a bare "role" like "system" does not.
+        speaker=role if role in ("user", "assistant") else None,
+    )
+
+
+def _first_str(*values: Any) -> str | None:
+    """First value that is a ``str`` (mirrors Swift's ``as? String`` cast chain)."""
+    for v in values:
+        if isinstance(v, str):
+            return v
+    return None
+
+
+def _opt_str(value: Any) -> str | None:
+    """A ``str`` value, or ``None`` (Swift ``o[k] as? String``)."""
+    return value if isinstance(value, str) else None
+
+
+def _stringify(v: Any) -> str:
+    """Render a metadata value as a string, mirroring Swift's ``stringify``.
+
+    - ``str`` passes through.
+    - ``bool`` becomes ``"1"``/``"0"`` — ``JSONSerialization`` decodes JSON booleans to
+      ``NSNumber``, whose ``stringValue`` is ``"1"``/``"0"``. Checked before ``int``
+      because ``bool`` is an ``int`` subclass in Python.
+    - other numbers use their string form (``NSNumber.stringValue``).
+    - containers use canonical JSON (Swift uses ``JSONSerialization`` with sorted keys;
+      the foundation's ``canonical_json`` is the byte-compatible equivalent).
+    """
+    if isinstance(v, str):
+        return v
+    if isinstance(v, bool):
+        return "1" if v else "0"
+    if isinstance(v, int):
+        return str(v)
+    if isinstance(v, float):
+        # ``canonical_json`` yields the shortest round-tripping form, matching Swift's
+        # ``NSNumber.stringValue`` for the numeric cases mem0 produces.
+        return canonical_json(v)
+    if isinstance(v, (dict, list)):
+        return canonical_json(v)
+    return str(v)
+
+
+#: Module-level alias so callers can ``from portable_memory.adapters.mem0 import
+#: parse_episodes`` without going through the class.
+parse_episodes = Mem0Adapter.parse_episodes