mnemosyne-memory 2.1__tar.gz → 2.2__tar.gz

{mnemosyne_memory-2.1 → mnemosyne_memory-2.2}/CHANGELOG.md

@@ -5,6 +5,34 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Simple Versioning](https://github.com/AxDSan/mnemosyne) (MAJOR.MINOR).
 
+## [2.2] — 2026-05-02
+
+### Added
+
+**Cross-Provider Importers — migrate from any memory platform**
+- New `mnemosyne/core/importers/` module with 6 provider importers
+- **Mem0:** SDK pagination → REST → structured export fallback chain; preserves user/agent/app scoping
+- **Letta (MemGPT):** AgentFile `.af` format parsing (JSON/YAML/TOML); memory blocks → working_memory, messages → episodic
+- **Zep:** users → sessions → `memory.get()` per-session iteration; messages + summaries + facts extraction
+- **Cognee:** `get_graph_data()` nodes/edges extraction; nodes → episodic memories, edges → triples
+- **Honcho:** peers → sessions → `context()` + messages; peer identity preserved as author_id
+- **SuperMemory:** `documents.list()` + `search.execute()`; container tags mapped to channel_id
+- **Agentic importer:** generates ready-to-run Python migration scripts and AI agent instructions for all 6 providers
+
+**CLI: `hermes mnemosyne import` extended**
+- `--from <provider>` — import directly from Mem0, Letta, Zep, etc.
+- `--list-providers` — show all supported providers with docs links
+- `--generate-script` — generate a migration script for any provider
+- `--agentic` — output instructions to give your AI agent for extraction
+- `--dry-run` — validate and transform without writing
+
+**Plugin tool updated**
+- `mnemosyne_import` schema extended with `provider`, `api_key`, `user_id`, `agent_id`, `dry_run`, `channel_id` params
+
+### Changed
+
+- README: added "Migrate from other memory providers" section with examples
+
 ## [2.1] — 2026-05-02
 
 ### Added

{mnemosyne_memory-2.1 → mnemosyne_memory-2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mnemosyne-memory
-Version: 2.1
+Version: 2.2
 Summary: The Zero-Dependency, Sub-Millisecond AI Memory System
 Home-page: https://github.com/AxDSan/mnemosyne
 Author: Abdias J
@@ -50,7 +50,7 @@ Dynamic: requires-python
 > Native, zero-cloud memory for AI agents. SQLite-backed. Sub-millisecond. Fully private.
 
 [![Python](https://img.shields.io/badge/Python-3.9+-blue.svg)](https://python.org)
-[![PyPI](https://img.shields.io/pypi/v/mnemosyne-memory.svg?v=2.1)](https://pypi.org/project/mnemosyne-memory/)
+[![PyPI](https://img.shields.io/pypi/v/mnemosyne-memory.svg?v=2.2)](https://pypi.org/project/mnemosyne-memory/)
 [![SQLite](https://img.shields.io/badge/SQLite-3.35+-green.svg)](https://sqlite.org/codeofethics.html)
 [![License](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 [![CI](https://github.com/AxDSan/mnemosyne/actions/workflows/ci.yml/badge.svg)](https://github.com/AxDSan/mnemosyne/actions/workflows/ci.yml)
@@ -553,6 +553,34 @@ hermes mnemosyne export --output mnemosyne_backup.json
 hermes mnemosyne import --input mnemosyne_backup.json
 ```
 
+### Migrate from other memory providers
+
+Import directly from 6 supported providers into Mnemosyne:
+
+```bash
+# List all supported providers
+hermes mnemosyne import --list-providers
+
+# Mem0 → Mnemosyne
+hermes mnemosyne import --from mem0 --api-key sk-xxx
+
+# Letta → Mnemosyne (offline .af file)
+hermes mnemosyne import --from letta --agent-file-path ./agent.af
+
+# Zep → Mnemosyne
+hermes mnemosyne import --from zep --api-key sk-xxx --max-sessions 100
+
+# Generate a migration script for any provider
+hermes mnemosyne import --from mem0 --generate-script --output-script migrate.py
+
+# Use AI agent extraction (no SDK needed)
+hermes mnemosyne import --from zep --agentic
+```
+
+**Supported providers:** Mem0, Letta (MemGPT), Zep, Cognee, Honcho, SuperMemory
+
+All importers preserve metadata, timestamps, user/agent identity, and relationships (graph edges → triples). Use `--dry-run` to validate without writing.
+
 ---
 
 ## Environment Variables

{mnemosyne_memory-2.1 → mnemosyne_memory-2.2}/README.md

@@ -5,7 +5,7 @@
 > Native, zero-cloud memory for AI agents. SQLite-backed. Sub-millisecond. Fully private.
 
 [![Python](https://img.shields.io/badge/Python-3.9+-blue.svg)](https://python.org)
-[![PyPI](https://img.shields.io/pypi/v/mnemosyne-memory.svg?v=2.1)](https://pypi.org/project/mnemosyne-memory/)
+[![PyPI](https://img.shields.io/pypi/v/mnemosyne-memory.svg?v=2.2)](https://pypi.org/project/mnemosyne-memory/)
 [![SQLite](https://img.shields.io/badge/SQLite-3.35+-green.svg)](https://sqlite.org/codeofethics.html)
 [![License](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 [![CI](https://github.com/AxDSan/mnemosyne/actions/workflows/ci.yml/badge.svg)](https://github.com/AxDSan/mnemosyne/actions/workflows/ci.yml)
@@ -508,6 +508,34 @@ hermes mnemosyne export --output mnemosyne_backup.json
 hermes mnemosyne import --input mnemosyne_backup.json
 ```
 
+### Migrate from other memory providers
+
+Import directly from 6 supported providers into Mnemosyne:
+
+```bash
+# List all supported providers
+hermes mnemosyne import --list-providers
+
+# Mem0 → Mnemosyne
+hermes mnemosyne import --from mem0 --api-key sk-xxx
+
+# Letta → Mnemosyne (offline .af file)
+hermes mnemosyne import --from letta --agent-file-path ./agent.af
+
+# Zep → Mnemosyne
+hermes mnemosyne import --from zep --api-key sk-xxx --max-sessions 100
+
+# Generate a migration script for any provider
+hermes mnemosyne import --from mem0 --generate-script --output-script migrate.py
+
+# Use AI agent extraction (no SDK needed)
+hermes mnemosyne import --from zep --agentic
+```
+
+**Supported providers:** Mem0, Letta (MemGPT), Zep, Cognee, Honcho, SuperMemory
+
+All importers preserve metadata, timestamps, user/agent identity, and relationships (graph edges → triples). Use `--dry-run` to validate without writing.
+
 ---
 
 ## Environment Variables

mnemosyne_memory-2.2/hermes_memory_provider/cli.py

@@ -0,0 +1,260 @@
+"""CLI commands for Mnemosyne memory provider.
+
+Available via: hermes mnemosyne <subcommand>
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+
+_mnemosyne_root = Path(__file__).resolve().parent.parent
+if str(_mnemosyne_root) not in sys.path:
+    sys.path.insert(0, str(_mnemosyne_root))
+
+
+def register_cli(subparser):
+    """Register CLI subcommands for ``hermes mnemosyne``."""
+    mn_cmds = subparser.add_subparsers(dest="mnemosyne_cmd")
+
+    stats_cmd = mn_cmds.add_parser("stats", help="Show memory statistics")
+    stats_cmd.add_argument("--global", "-g", action="store_true", help="Show global stats across all sessions")
+
+    sleep_cmd = mn_cmds.add_parser("sleep", help="Run consolidation cycle")
+    sleep_cmd.add_argument("--all-sessions", action="store_true", help="Consolidate eligible old working memories across all sessions")
+    sleep_cmd.add_argument("--dry-run", action="store_true", help="Report what would be consolidated without writing changes")
+    mn_cmds.add_parser("version", help="Show Mnemosyne version")
+
+    inspect_cmd = mn_cmds.add_parser("inspect", help="Search memories")
+    inspect_cmd.add_argument("query", nargs="?", default="", help="Search query")
+    inspect_cmd.add_argument("--limit", type=int, default=10, help="Max results")
+
+    mn_cmds.add_parser("clear", help="Clear scratchpad")
+
+    export_cmd = mn_cmds.add_parser("export", help="Export all memories to a JSON file")
+    export_cmd.add_argument("--output", "-o", type=str, required=True, help="Output JSON file path")
+
+    import_cmd = mn_cmds.add_parser("import", help="Import memories from a JSON file or another provider")
+    import_cmd.add_argument("--input", "-i", type=str, help="Input JSON file path (for file imports)")
+    import_cmd.add_argument("--force", action="store_true", help="Overwrite existing records (file import)")
+    import_cmd.add_argument("--from", dest="from_provider", type=str, help="Provider to import from (e.g., 'mem0')")
+    import_cmd.add_argument("--api-key", type=str, help="Provider API key (or set env var)")
+    import_cmd.add_argument("--user-id", type=str, help="Filter by user ID (provider-specific)")
+    import_cmd.add_argument("--agent-id", type=str, help="Filter by agent ID (provider-specific)")
+    import_cmd.add_argument("--base-url", type=str, help="Provider base URL (for self-hosted)")
+    import_cmd.add_argument("--dry-run", action="store_true", help="Validate but don't import")
+    import_cmd.add_argument("--session-id", type=str, help="Override session for imported memories")
+    import_cmd.add_argument("--channel-id", type=str, help="Channel for imported memories")
+    import_cmd.add_argument("--list-providers", action="store_true", help="List supported import providers")
+    import_cmd.add_argument("--generate-script", action="store_true", help="Generate a migration script for the provider")
+    import_cmd.add_argument("--agentic", action="store_true", help="Generate agent migration instructions (prompt to give your AI agent)")
+    import_cmd.add_argument("--output-script", type=str, help="Save generated script to file")
+
+    subparser.set_defaults(func=mnemosyne_command)
+
+
+def mnemosyne_command(args):
+    """Dispatch ``hermes mnemosyne <subcommand>``."""
+    cmd = getattr(args, "mnemosyne_cmd", None)
+    if not cmd:
+        print("Usage: hermes mnemosyne {stats|sleep|inspect|clear}")
+        return 1
+
+    try:
+        from mnemosyne.core.beam import BeamMemory
+        beam = BeamMemory(session_id="hermes_default")
+    except Exception as e:
+        print(f"Error: Mnemosyne not available: {e}")
+        return 1
+
+    if cmd == "stats":
+        if getattr(args, "global", False):
+            working = beam.get_global_working_stats()
+        else:
+            working = beam.get_working_stats()
+        episodic = beam.get_episodic_stats()
+        print(json.dumps({"working": working, "episodic": episodic}, indent=2))
+
+    elif cmd == "version":
+        from mnemosyne import __version__, __author__
+        print(f"Mnemosyne {__version__} by {__author__}")
+
+    elif cmd == "sleep":
+        dry_run = bool(getattr(args, "dry_run", False))
+        if getattr(args, "all_sessions", False):
+            result = beam.sleep_all_sessions(dry_run=dry_run)
+        else:
+            result = beam.sleep(dry_run=dry_run)
+        print(json.dumps(result, indent=2))
+
+    elif cmd == "inspect":
+        query = getattr(args, "query", "") or ""
+        limit = getattr(args, "limit", 10)
+        if not query:
+            query = input("Search query: ")
+        results = beam.recall(query, top_k=limit)
+        print(f"Results for '{query}': {len(results)}")
+        for i, r in enumerate(results, 1):
+            content = r.get("content", "")[:120]
+            imp = r.get("importance", 0.0)
+            print(f"  {i}. [{imp:.2f}] {content}")
+
+    elif cmd == "clear":
+        confirm = input("Clear scratchpad? This cannot be undone. [y/N]: ")
+        if confirm.lower() in ("y", "yes"):
+            beam.scratchpad_clear()
+            print("Scratchpad cleared.")
+        else:
+            print("Cancelled.")
+
+    elif cmd == "export":
+        output_path = getattr(args, "output", None)
+        if not output_path:
+            print("Usage: hermes mnemosyne export --output <path>")
+            return 1
+        try:
+            from mnemosyne.core.memory import Mnemosyne
+            mem = Mnemosyne(session_id="hermes_default")
+            result = mem.export_to_file(output_path)
+            print(f"Exported {result['working_memory_count']} working, {result['episodic_memory_count']} episodic, {result['legacy_memories_count']} legacy, {result['triples_count']} triples to {output_path}")
+        except Exception as e:
+            print(f"Export failed: {e}")
+            return 1
+
+    elif cmd == "import":
+        # --list-providers
+        if getattr(args, "list_providers", False):
+            from mnemosyne.core.importers import PROVIDERS
+            print("Supported import providers:")
+            for name, info in PROVIDERS.items():
+                print(f"  {name}: {info['description']}")
+                print(f"         docs: {info['docs']}")
+                print(f"         env key: {info['env_key']}")
+                print(f"         pip: {info['pypi_package']}")
+            return 0
+
+        # --agentic: generate instructions for user's AI agent
+        generate_script_flag = getattr(args, "generate_script", False)
+        agentic_flag = getattr(args, "agentic", False)
+        from_provider = getattr(args, "from_provider", None)
+        output_script = getattr(args, "output_script", None)
+
+        if agentic_flag and from_provider:
+            from mnemosyne.core.importers.agentic import generate_agent_instructions
+            instructions = generate_agent_instructions(from_provider)
+            if output_script:
+                Path(output_script).write_text(instructions)
+                print(f"Agent instructions saved to {output_script}")
+            else:
+                print(instructions)
+            return 0
+
+        if generate_script_flag and from_provider:
+            from mnemosyne.core.importers.agentic import generate_migration_script
+            api_key = getattr(args, "api_key", None)
+            user_id = getattr(args, "user_id", None)
+            script = generate_migration_script(
+                from_provider,
+                api_key=api_key or "",
+                user_id=user_id or "",
+            )
+            if output_script:
+                Path(output_script).write_text(script)
+                print(f"Migration script saved to {output_script}")
+            else:
+                print(script)
+            return 0
+
+        cross_provider = from_provider
+        input_path = getattr(args, "input", None)
+        dry_run = getattr(args, "dry_run", False)
+        session_id = getattr(args, "session_id", None)
+        channel_id = getattr(args, "channel_id", None)
+
+        try:
+            from mnemosyne.core.memory import Mnemosyne
+            mem = Mnemosyne(session_id=session_id or "import_session",
+                            channel_id=channel_id)
+        except Exception as e:
+            print(f"Error: Mnemosyne not available: {e}")
+            return 1
+
+        # Cross-provider import
+        if cross_provider:
+            api_key = getattr(args, "api_key", None)
+            user_id = getattr(args, "user_id", None)
+            agent_id = getattr(args, "agent_id", None)
+            base_url = getattr(args, "base_url", None)
+
+            # Try env var fallback
+            import os
+            if not api_key:
+                info = __import__("mnemosyne.core.importers", fromlist=["PROVIDERS"]).PROVIDERS
+                pk = info.get(cross_provider, {}).get("env_key", "")
+                if pk:
+                    api_key = os.environ.get(pk)
+            if not api_key:
+                print(f"Error: --api-key required for {cross_provider} import. "
+                      f"Or set the {cross_provider.upper()}_API_KEY env var.")
+                return 1
+
+            print(f"Importing from {cross_provider}...")
+            if dry_run:
+                print("  (dry-run mode: no memories will be written)")
+
+            try:
+                from mnemosyne.core.importers import import_from_provider
+                result = import_from_provider(
+                    cross_provider, mem,
+                    api_key=api_key,
+                    user_id=user_id,
+                    agent_id=agent_id,
+                    base_url=base_url,
+                    dry_run=dry_run,
+                    session_id=session_id,
+                    channel_id=channel_id,
+                )
+                print(f"\nImport complete:")
+                print(f"  Total found: {result.total}")
+                print(f"  Imported:    {result.imported}")
+                print(f"  Skipped:     {result.skipped}")
+                print(f"  Failed:      {result.failed}")
+                if result.errors:
+                    print(f"  Errors:")
+                    for err in result.errors[:10]:
+                        print(f"    - {err}")
+                    if len(result.errors) > 10:
+                        print(f"    ... and {len(result.errors) - 10} more")
+                return 0 if result.failed == 0 else 1
+            except ValueError as e:
+                print(f"Error: {e}")
+                return 1
+            except Exception as e:
+                print(f"Import failed: {e}")
+                return 1
+
+        # File import
+        force = getattr(args, "force", False)
+        if not input_path:
+            print("Usage: hermes mnemosyne import --input <path> [--force]")
+            print("       hermes mnemosyne import --from <provider> --api-key <key> [--dry-run]")
+            print("       hermes mnemosyne import --list-providers")
+            return 1
+        try:
+            stats = mem.import_from_file(input_path, force=force)
+            beam_stats = stats.get("beam", {})
+            legacy_stats = stats.get("legacy", {})
+            triples_stats = stats.get("triples", {})
+            print(f"Import complete:")
+            print(f"  Working: +{beam_stats.get('working_memory', {}).get('inserted', 0)}")
+            print(f"  Episodic: +{beam_stats.get('episodic_memory', {}).get('inserted', 0)}")
+            print(f"  Legacy: +{legacy_stats.get('inserted', 0)}")
+            print(f"  Triples: +{triples_stats.get('inserted', 0)}")
+            if force:
+                print(f"  (force mode: overwrites applied)")
+        except Exception as e:
+            print(f"Import failed: {e}")
+            return 1
+
+    return 0

{mnemosyne_memory-2.1 → mnemosyne_memory-2.2}/hermes_plugin/tools.py

@@ -277,13 +277,42 @@ FORGET_SCHEMA = {
 
 IMPORT_SCHEMA = {
     "name": "mnemosyne_import",
-    "description": "Import Mnemosyne memories from a JSON file. Idempotent by default.",
+    "description": "Import Mnemosyne memories from a JSON file or another memory provider (Mem0, etc.). Idempotent by default.",
     "parameters": {
         "type": "object",
         "properties": {
             "input_path": {
                 "type": "string",
-                "description": "File path to read the export JSON from"
+                "description": "File path to read the export JSON from (for file imports)"
+            },
+            "provider": {
+                "type": "string",
+                "description": "Provider to import from: 'mem0'. Requires api_key. Use --list-providers to see supported providers."
+            },
+            "api_key": {
+                "type": "string",
+                "description": "API key for the source provider (can also be set via env var: MEM0_API_KEY)"
+            },
+            "user_id": {
+                "type": "string",
+                "description": "Filter imported memories by user ID (provider-specific)"
+            },
+            "agent_id": {
+                "type": "string",
+                "description": "Filter imported memories by agent ID (provider-specific)"
+            },
+            "base_url": {
+                "type": "string",
+                "description": "Base URL for self-hosted provider instances"
+            },
+            "dry_run": {
+                "type": "boolean",
+                "description": "If true, validate and transform but don't write any memories",
+                "default": False
+            },
+            "channel_id": {
+                "type": "string",
+                "description": "Channel to assign imported memories to"
             },
             "force": {
                 "type": "boolean",
@@ -291,7 +320,7 @@ IMPORT_SCHEMA = {
                 "default": False
             }
         },
-        "required": ["input_path"]
+        "required": []
     }
 }
 
@@ -538,14 +567,50 @@ def mnemosyne_forget(args: dict, **kwargs) -> str:
 
 
 def mnemosyne_import(args: dict, **kwargs) -> str:
-    """Import memories from a JSON file"""
+    """Import memories from a JSON file or another memory provider."""
     try:
+        provider = args.get("provider", "").strip().lower()
         input_path = args.get("input_path", "").strip()
+        dry_run = args.get("dry_run", False)
+        channel_id = args.get("channel_id")
         force = args.get("force", False)
-        if not input_path:
-            return json.dumps({"error": "input_path is required"})
 
         mem = _get_memory()
+
+        # Cross-provider import
+        if provider:
+            api_key = args.get("api_key", "").strip()
+            user_id = args.get("user_id", "").strip() or None
+            agent_id = args.get("agent_id", "").strip() or None
+            base_url = args.get("base_url", "").strip() or None
+
+            if not api_key:
+                import os
+                env_key = f"{provider.upper()}_API_KEY"
+                api_key = os.environ.get(env_key, "")
+            if not api_key:
+                return json.dumps({
+                    "error": f"api_key required for {provider} import. Set {provider.upper()}_API_KEY env var or pass api_key parameter."
+                })
+
+            from mnemosyne.core.importers import import_from_provider
+            result = import_from_provider(
+                provider, mem,
+                api_key=api_key,
+                user_id=user_id,
+                agent_id=agent_id,
+                base_url=base_url,
+                dry_run=dry_run,
+                channel_id=channel_id,
+            )
+            return json.dumps(result.to_dict())
+
+        # File import
+        if not input_path:
+            return json.dumps({
+                "error": "Either input_path (for file import) or provider (for cross-provider import) is required"
+            })
+
         stats = mem.import_from_file(input_path, force=force)
         return json.dumps({
             "status": "imported",

{mnemosyne_memory-2.1 → mnemosyne_memory-2.2}/mnemosyne/__init__.py

@@ -10,7 +10,7 @@ Example:
     >>> results = recall("user preferences")
 """
 
-__version__ = "2.1"
+__version__ = "2.2"
 __author__ = "Abdias J"
 __license__ = "MIT"
 

mnemosyne_memory-2.2/mnemosyne/core/importers/__init__.py

@@ -0,0 +1,152 @@
+"""
+Mnemosyne Cross-Provider Importers
+
+Import memories from other AI memory providers into Mnemosyne.
+
+Supported providers:
+    mem0        — Mem0 (cloud + self-hosted)
+    letta       — Letta (formerly MemGPT)
+    zep         — Zep enterprise memory
+    cognee      — Cognee graph memory
+    honcho      — Honcho entity memory
+    supermemory — SuperMemory cloud API
+
+CLI usage:
+    hermes mnemosyne import --from mem0 --api-key sk-xxx
+    hermes mnemosyne import --file export.json --dry-run
+    hermes mnemosyne import --list-providers
+    hermes mnemosyne import --from mem0 --generate-script
+
+Agentic migration:
+    hermes mnemosyne import --from zep --agentic
+"""
+
+from .base import BaseImporter, ImporterResult, import_from_file
+from .mem0 import Mem0Importer, import_from_mem0
+from .letta import LettaImporter
+from .zep import ZepImporter
+from .cognee import CogneeImporter
+from .honcho import HonchoImporter
+from .supermemory import SuperMemoryImporter
+from .agentic import (
+    AgenticImporter,
+    generate_migration_script,
+    generate_agent_instructions,
+    generate_docs_instructions,
+)
+
+
+# Registry of supported providers
+PROVIDERS = {
+    "mem0": {
+        "name": "Mem0",
+        "class": Mem0Importer,
+        "module": "mem0",
+        "docs": "https://docs.mem0.ai",
+        "env_key": "MEM0_API_KEY",
+        "pypi_package": "mem0ai",
+        "description": "Memory platform with 24 vector store backends. Supports user/agent/app scoping.",
+    },
+    "letta": {
+        "name": "Letta (MemGPT)",
+        "class": LettaImporter,
+        "module": "letta",
+        "docs": "https://docs.letta.com",
+        "env_key": "LETTA_API_KEY",
+        "pypi_package": "letta-client",
+        "description": "Agent OS with hierarchical memory blocks. Export via .af AgentFile format.",
+    },
+    "zep": {
+        "name": "Zep",
+        "class": ZepImporter,
+        "module": "zep",
+        "docs": "https://docs.getzep.com",
+        "env_key": "ZEP_API_KEY",
+        "pypi_package": "zep-cloud",
+        "description": "Enterprise temporal knowledge graph. Session-based with user/thread model.",
+    },
+    "cognee": {
+        "name": "Cognee",
+        "class": CogneeImporter,
+        "module": "cognee",
+        "docs": "https://docs.cognee.ai",
+        "env_key": None,
+        "pypi_package": "cognee",
+        "description": "Graph-based memory with Kùzu + LanceDB + SQLite. Nodes/edges map to episodic/triples.",
+    },
+    "honcho": {
+        "name": "Honcho",
+        "class": HonchoImporter,
+        "module": "honcho",
+        "docs": "https://docs.honcho.dev",
+        "env_key": None,
+        "pypi_package": "honcho-ai",
+        "description": "Entity-centric memory by Plastic Labs. Workspace → Peer → Session → Message model.",
+    },
+    "supermemory": {
+        "name": "SuperMemory",
+        "class": SuperMemoryImporter,
+        "module": "supermemory",
+        "docs": "https://supermemory.ai/docs",
+        "env_key": "SUPERMEMORY_API_KEY",
+        "pypi_package": "supermemory",
+        "description": "Cloud memory API with container tags and document management.",
+    },
+}
+
+
+def list_providers() -> list:
+    """Return list of supported provider names."""
+    return list(PROVIDERS.keys())
+
+
+def get_provider_info(name: str) -> dict:
+    """Get metadata for a supported provider."""
+    return PROVIDERS.get(name, {})
+
+
+def import_from_provider(provider: str, mnemosyne, dry_run: bool = False,
+                         session_id: str = None, channel_id: str = None,
+                         **kwargs) -> ImporterResult:
+    """Import memories from a supported provider into Mnemosyne.
+
+    Args:
+        provider: Provider name (e.g., 'mem0', 'letta').
+        mnemosyne: Mnemosyne instance to import into.
+        dry_run: If True, validate and transform but don't write.
+        session_id: Override session for imported memories.
+        channel_id: Channel to assign imported memories to.
+        **kwargs: Provider-specific arguments (api_key, user_id, etc.)
+
+    Returns:
+        ImporterResult with import statistics.
+
+    Raises:
+        ValueError: If provider is not supported.
+    """
+    provider_info = PROVIDERS.get(provider)
+    if not provider_info:
+        supported = ", ".join(PROVIDERS.keys())
+        raise ValueError(
+            f"Unsupported provider: '{provider}'. Supported: {supported}"
+        )
+
+    importer_cls = provider_info["class"]
+    importer = importer_cls(**kwargs)
+    return importer.run(
+        mnemosyne,
+        dry_run=dry_run,
+        session_id=session_id,
+        channel_id=channel_id,
+    )
+
+
+def generate_script(provider: str, **kwargs) -> str:
+    """Generate a migration script for the given provider."""
+    provider_info = PROVIDERS.get(provider)
+    if not provider_info:
+        supported = ", ".join(PROVIDERS.keys())
+        raise ValueError(
+            f"Unsupported provider: '{provider}'. Supported: {supported}"
+        )
+    return generate_migration_script(provider, **kwargs)