foodforthought-cli 0.2.8__py3-none-any.whl → 0.3.0__py3-none-any.whl

ate/commands/memory.py

@@ -0,0 +1,907 @@
+"""
+Memory management commands for FoodforThought CLI.
+
+Commands:
+- ate memory init    - Create a new .mv2 memory file
+- ate memory add     - Add content (single text or bulk JSONL)
+- ate memory search  - Search memory by query
+- ate memory info    - Show memory store statistics
+- ate memory export  - Export all content to JSONL
+- ate memory merge   - Merge multiple .mv2 files
+"""
+
+import json
+import os
+import sys
+from dataclasses import asdict
+from pathlib import Path
+
+from ate.memory import MemoryStore, merge_memories, EmbeddingConfig, EmbeddingManager
+from ate.memory.cloud import CloudClient, CloudAuthError, CloudError, CloudNotFoundError
+from ate.auth.token_store import TokenStore
+
+
+# ---------------------------------------------------------------------------
+# Arg-parser registration
+# ---------------------------------------------------------------------------
+
+def register_parser(subparsers):
+    """Register memory commands with argparse."""
+    mem_parser = subparsers.add_parser("memory", help="Memory file management (.mv2)")
+    mem_subs = mem_parser.add_subparsers(dest="memory_action", help="Memory action")
+
+    # --- init ---
+    p_init = mem_subs.add_parser("init", help="Create a new .mv2 memory file")
+    p_init.add_argument("path", help="Path for the new .mv2 file")
+    p_init.add_argument("--embedding-provider", dest="embedding_provider", default=None,
+                        choices=["openai", "cohere", "voyage", "ollama", "none"],
+                        help="Embedding provider to use")
+    p_init.add_argument("--embedding-model", dest="embedding_model", default=None,
+                        help="Embedding model override")
+    p_init.add_argument("--format", dest="format", default=None,
+                        choices=["json"], help="Output format (default: human-readable)")
+
+    # --- add ---
+    p_add = mem_subs.add_parser("add", help="Add content to a memory file")
+    p_add.add_argument("path", help="Path to the .mv2 file")
+    p_add.add_argument("--text", default=None, help="Text content to add")
+    p_add.add_argument("--file", default=None, help="JSONL file for bulk add")
+    p_add.add_argument("--tags", default=None, help="Comma-separated tags")
+    p_add.add_argument("--title", default=None, help="Title for the entry")
+    p_add.add_argument("--metadata", default=None, help="JSON metadata string")
+    p_add.add_argument("--embed", action="store_true", default=False,
+                        help="Force embedding even if not default")
+    p_add.add_argument("--format", dest="format", default=None,
+                        choices=["json"], help="Output format")
+
+    # --- search ---
+    p_search = mem_subs.add_parser("search", help="Search memory")
+    p_search.add_argument("path", help="Path to the .mv2 file")
+    p_search.add_argument("query", help="Search query")
+    p_search.add_argument("--top-k", type=int, default=5, help="Max results (default 5)")
+    p_search.add_argument("--engine", dest="engine", default=None,
+                          choices=["auto", "vec", "lex", "hybrid", "rerank"],
+                          help="Search engine to use (default: auto)")
+    p_search.add_argument("--rerank-provider", dest="rerank_provider", default=None,
+                          choices=["anthropic", "openai", "google", "ollama"],
+                          help="LLM provider for reranking")
+    p_search.add_argument("--rerank-model", dest="rerank_model", default=None,
+                          help="LLM model for reranking")
+    p_search.add_argument("--format", dest="format", default=None,
+                          choices=["json"], help="Output format")
+
+    # --- info ---
+    p_info = mem_subs.add_parser("info", help="Show memory store statistics")
+    p_info.add_argument("path", help="Path to the .mv2 file")
+    p_info.add_argument("--format", dest="format", default=None,
+                        choices=["json"], help="Output format")
+
+    # --- export ---
+    p_export = mem_subs.add_parser("export", help="Export memory content")
+    p_export.add_argument("path", help="Path to the .mv2 file")
+    p_export.add_argument("--output", required=True, help="Output JSONL file path")
+    p_export.add_argument("--format", dest="format", default=None,
+                          choices=["json", "jsonl"], help="Output format")
+
+    # --- merge ---
+    p_merge = mem_subs.add_parser("merge", help="Merge multiple .mv2 files")
+    p_merge.add_argument("paths", nargs="+", help="Source .mv2 file paths")
+    p_merge.add_argument("--output", required=True, help="Output .mv2 file path")
+    p_merge.add_argument("--no-dedup", action="store_true", default=False,
+                         help="Disable deduplication")
+    p_merge.add_argument("--format", dest="format", default=None,
+                         choices=["json"], help="Output format")
+
+    # --- think (context-aware) ---
+    p_think = mem_subs.add_parser("think", help="Add a thought to active memory")
+    p_think.add_argument("text", help="Text content to add")
+    p_think.add_argument("--memory", default=None, help="Override active memory")
+    p_think.add_argument("--tags", default=None, help="Comma-separated tags")
+    p_think.add_argument("--title", default=None, help="Title for the entry")
+    p_think.add_argument("--metadata", default=None, help="JSON metadata string")
+    p_think.add_argument("--embed", action="store_true", default=False,
+                        help="Force embedding even if not default")
+    p_think.add_argument("--format", dest="format", default=None,
+                        choices=["json"], help="Output format")
+
+    # --- recall (context-aware) ---
+    p_recall = mem_subs.add_parser("recall", help="Search active memory")
+    p_recall.add_argument("query", help="Search query")
+    p_recall.add_argument("--memory", default=None, help="Override active memory")
+    p_recall.add_argument("--top-k", type=int, default=5, help="Max results (default 5)")
+    p_recall.add_argument("--engine", dest="engine", default=None,
+                          choices=["auto", "vec", "lex", "hybrid", "rerank"],
+                          help="Search engine to use (default: auto)")
+    p_recall.add_argument("--all-trains", action="store_true", default=False,
+                          help="Search across all trains in current memory")
+    p_recall.add_argument("--format", dest="format", default=None,
+                          choices=["json"], help="Output format")
+
+    # --- train (context switching) ---
+    p_train = mem_subs.add_parser("train", help="Manage trains of thought")
+    p_train.add_argument("name", nargs="?", help="Train name to switch to")
+    p_train.add_argument("--delete", default=None, help="Delete a train")
+    p_train.add_argument("--rename", nargs=2, metavar=("OLD", "NEW"), 
+                        help="Rename a train")
+    p_train.add_argument("--format", dest="format", default=None,
+                        choices=["json"], help="Output format")
+
+    # --- status (context info) ---
+    p_status = mem_subs.add_parser("status", help="Show current memory context")
+    p_status.add_argument("--format", dest="format", default=None,
+                         choices=["json"], help="Output format")
+
+    # --- new (memory creation) ---
+    p_new = mem_subs.add_parser("new", help="Create a new memory")
+    p_new.add_argument("name", help="Memory name")
+    p_new.add_argument("--description", default="", help="Memory description")
+    p_new.add_argument("--format", dest="format", default=None,
+                      choices=["json"], help="Output format")
+
+    # --- use (memory switching) ---
+    p_use = mem_subs.add_parser("use", help="Switch to a different memory")
+    p_use.add_argument("name", help="Memory name")
+    p_use.add_argument("--format", dest="format", default=None,
+                      choices=["json"], help="Output format")
+
+    # --- list-memories (local memories) ---
+    p_list_memories = mem_subs.add_parser("list-memories", help="List all local memories")
+    p_list_memories.add_argument("--format", dest="format", default=None,
+                                choices=["json"], help="Output format")
+
+    # --- push (cloud) ---
+    p_push = mem_subs.add_parser("push", help="Upload .mv2 file to cloud")
+    p_push.add_argument("path", help="Path to the .mv2 file to upload")
+    p_push.add_argument("--project", required=True, help="Project identifier (e.g. kindly/memories)")
+    p_push.add_argument("--name", default=None, help="Name override (defaults to filename)")
+    p_push.add_argument("--format", dest="format", default=None,
+                        choices=["json"], help="Output format")
+
+    # --- pull (cloud) ---
+    p_pull = mem_subs.add_parser("pull", help="Download .mv2 file from cloud")
+    p_pull.add_argument("ref", help="Project/name reference (e.g. kindly/memories/test.mv2)")
+    p_pull.add_argument("--output", required=True, help="Output file path")
+    p_pull.add_argument("--format", dest="format", default=None,
+                        choices=["json"], help="Output format")
+
+    # --- list (cloud) ---
+    p_list = mem_subs.add_parser("list", help="List memory files in a cloud project")
+    p_list.add_argument("--project", required=True, help="Project identifier")
+    p_list.add_argument("--format", dest="format", default=None,
+                        choices=["json"], help="Output format")
+
+    # --- delete (cloud) ---
+    p_delete = mem_subs.add_parser("delete", help="Delete a memory file from cloud")
+    p_delete.add_argument("ref", help="Project/name reference (e.g. kindly/memories/old.mv2)")
+    p_delete.add_argument("--format", dest="format", default=None,
+                          choices=["json"], help="Output format")
+
+    # --- providers ---
+    p_providers = mem_subs.add_parser("providers", help="List detected embedding providers")
+    p_providers.add_argument("--format", dest="format", default=None,
+                            choices=["json"], help="Output format")
+
+
+# ---------------------------------------------------------------------------
+# Dispatcher
+# ---------------------------------------------------------------------------
+
+def handle(client, args):
+    """Handle memory commands."""
+    action = getattr(args, "memory_action", None)
+    if action == "init":
+        _handle_init(args)
+    elif action == "add":
+        _handle_add(args)
+    elif action == "search":
+        _handle_search(args)
+    elif action == "info":
+        _handle_info(args)
+    elif action == "export":
+        _handle_export(args)
+    elif action == "merge":
+        _handle_merge(args)
+    elif action == "think":
+        _handle_think(args)
+    elif action == "recall":
+        _handle_recall(args)
+    elif action == "train":
+        _handle_train(args)
+    elif action == "status":
+        _handle_status(args)
+    elif action == "new":
+        _handle_new(args)
+    elif action == "use":
+        _handle_use(args)
+    elif action == "list-memories":
+        _handle_list_memories(args)
+    elif action == "push":
+        _handle_push(args)
+    elif action == "pull":
+        _handle_pull(args)
+    elif action == "list":
+        _handle_list(args)
+    elif action == "delete":
+        _handle_delete(args)
+    elif action == "providers":
+        _handle_providers(args)
+    else:
+        print("Usage: ate memory {init|add|search|info|export|merge|think|recall|train|status|new|use|list-memories|push|pull|list|delete|providers}", file=sys.stderr)
+        sys.exit(1)
+
+
+# ---------------------------------------------------------------------------
+# Individual handlers
+# ---------------------------------------------------------------------------
+
+def _handle_init(args):
+    """Create a new .mv2 memory file."""
+    path = args.path
+    
+    # Handle embedding configuration
+    embedding_config = None
+    if args.embedding_provider:
+        embedding_config = EmbeddingConfig(
+            provider=args.embedding_provider,
+            model=args.embedding_model
+        )
+    
+    try:
+        store = MemoryStore.create(path, embedding_config=embedding_config)
+        store.close()
+    except Exception as e:
+        print(f"Error: Failed to create memory file: {e}", file=sys.stderr)
+        sys.exit(2)
+
+    if args.format == "json":
+        print(json.dumps({"path": path, "created": True}))
+    else:
+        print(f"✅ Created memory file: {path}")
+
+
+def _handle_add(args):
+    """Add content to a memory file."""
+    path = args.path
+    text = args.text
+    file_path = args.file
+
+    if not text and not file_path:
+        print("Error: Provide --text or --file", file=sys.stderr)
+        sys.exit(1)
+
+    if text is not None and text.strip() == "":
+        print("Error: Text cannot be empty", file=sys.stderr)
+        sys.exit(1)
+
+    try:
+        with MemoryStore.open(path) as store:
+            if file_path:
+                # Bulk add from JSONL
+                items = []
+                with open(file_path, "r", encoding="utf-8") as f:
+                    for line in f:
+                        line = line.strip()
+                        if line:
+                            items.append(json.loads(line))
+                frame_ids = store.add_batch(items)
+
+                if args.format == "json":
+                    print(json.dumps({"count": len(frame_ids), "frame_ids": frame_ids}))
+                else:
+                    print(f"✅ Added {len(frame_ids)} entries from {file_path}")
+            else:
+                # Single add
+                tags = [t.strip() for t in args.tags.split(",")] if args.tags else None
+                metadata = json.loads(args.metadata) if args.metadata else None
+                title = args.title
+                enable_embedding = True if args.embed else None
+
+                frame_id = store.add(text=text, tags=tags, metadata=metadata, 
+                                   title=title, enable_embedding=enable_embedding)
+
+                if args.format == "json":
+                    print(json.dumps({"frame_id": frame_id}))
+                else:
+                    print(f"✅ Added entry {frame_id}")
+    except FileNotFoundError as e:
+        print(f"Error: {e}", file=sys.stderr)
+        sys.exit(1)
+    except Exception as e:
+        print(f"Error: {e}", file=sys.stderr)
+        sys.exit(2)
+
+
+def _handle_search(args):
+    """Search memory."""
+    path = args.path
+    query = args.query
+    top_k = args.top_k
+    engine = args.engine
+
+    if not query.strip():
+        print("Error: Query cannot be empty", file=sys.stderr)
+        sys.exit(1)
+
+    try:
+        with MemoryStore.open(path) as store:
+            results = store.search(query, top_k=top_k, engine=engine)
+
+            if args.format == "json":
+                out = {
+                    "query": query,
+                    "results": [
+                        {
+                            "frame_id": r.frame_id,
+                            "text": r.text,
+                            "title": r.title,
+                            "score": r.score,
+                            "tags": r.tags,
+                            "metadata": r.metadata,
+                            "engine": r.engine,
+                        }
+                        for r in results
+                    ],
+                }
+                print(json.dumps(out))
+            else:
+                if not results:
+                    print("No results found.")
+                else:
+                    print(f"🔍 {len(results)} result(s) for \"{query}\":\n")
+                    for i, r in enumerate(results, 1):
+                        title_str = f" — {r.title}" if r.title else ""
+                        print(f"  {i}. [{r.score:.2f}] {r.text}{title_str}")
+                        if r.tags:
+                            print(f"     Tags: {', '.join(r.tags)}")
+    except FileNotFoundError as e:
+        print(f"Error: {e}", file=sys.stderr)
+        sys.exit(1)
+    except Exception as e:
+        print(f"Error: {e}", file=sys.stderr)
+        sys.exit(2)
+
+
+def _handle_info(args):
+    """Show memory store statistics."""
+    path = args.path
+    try:
+        with MemoryStore.open(path) as store:
+            info = store.info()
+
+            if args.format == "json":
+                print(json.dumps({
+                    "path": info.path,
+                    "frame_count": info.frame_count,
+                    "size_bytes": info.size_bytes,
+                    "has_lex_index": info.has_lex_index,
+                    "has_vec_index": info.has_vec_index,
+                    "has_time_index": info.has_time_index,
+                    "created_at": getattr(info, "created_at", None),
+                }))
+            else:
+                size_kb = info.size_bytes / 1024
+                print(f"📦 Memory: {info.path}")
+                print(f"   Frames:     {info.frame_count}")
+                print(f"   Size:       {size_kb:.1f} KB")
+                print(f"   Lex index:  {'✅' if info.has_lex_index else '❌'}")
+                print(f"   Vec index:  {'✅' if info.has_vec_index else '❌'}")
+                print(f"   Time index: {'✅' if info.has_time_index else '❌'}")
+    except FileNotFoundError as e:
+        print(f"Error: {e}", file=sys.stderr)
+        sys.exit(1)
+    except Exception as e:
+        print(f"Error: {e}", file=sys.stderr)
+        sys.exit(2)
+
+
+def _handle_export(args):
+    """Export memory content to JSONL."""
+    path = args.path
+    output = args.output
+    try:
+        with MemoryStore.open(path) as store:
+            count = store.export_jsonl(output)
+
+            if args.format == "json":
+                print(json.dumps({"output": output, "count": count}))
+            else:
+                print(f"✅ Exported {count} entries to {output}")
+    except FileNotFoundError as e:
+        print(f"Error: {e}", file=sys.stderr)
+        sys.exit(1)
+    except Exception as e:
+        print(f"Error: {e}", file=sys.stderr)
+        sys.exit(2)
+
+
+def _handle_merge(args):
+    """Merge multiple .mv2 files."""
+    source_paths = args.paths
+    output = args.output
+    dedup = not args.no_dedup
+
+    try:
+        info = merge_memories(source_paths, output, dedup=dedup)
+
+        if args.format == "json":
+            print(json.dumps({
+                "output": info.path,
+                "frame_count": info.frame_count,
+                "size_bytes": info.size_bytes,
+                "dedup": dedup,
+            }))
+        else:
+            print(f"✅ Merged {len(source_paths)} files → {info.path}")
+            print(f"   Frames: {info.frame_count}")
+            print(f"   Size:   {info.size_bytes / 1024:.1f} KB")
+            if dedup:
+                print(f"   Dedup:  enabled")
+    except FileNotFoundError as e:
+        print(f"Error: {e}", file=sys.stderr)
+        sys.exit(1)
+    except Exception as e:
+        print(f"Error: {e}", file=sys.stderr)
+        sys.exit(2)
+
+
+# ---------------------------------------------------------------------------
+# Context-aware handlers (think / recall / train / status / new / use / list-memories)
+# ---------------------------------------------------------------------------
+
+def _handle_think(args):
+    """Add a thought to active memory."""
+    text = args.text
+    memory_path = getattr(args, 'memory', None)
+    
+    if not text.strip():
+        print("Error: Text cannot be empty", file=sys.stderr)
+        sys.exit(1)
+
+    try:
+        with MemoryStore.from_context_or_path(memory_path) as store:
+            tags = [t.strip() for t in args.tags.split(",")] if args.tags else None
+            metadata = json.loads(args.metadata) if args.metadata else None
+            title = args.title
+            enable_embedding = True if args.embed else None
+
+            frame_id = store.add(text=text, tags=tags, metadata=metadata, 
+                               title=title, enable_embedding=enable_embedding)
+
+            if args.format == "json":
+                # Get current context for output
+                from ate.memory.context import ContextManager
+                context = ContextManager.get_context()
+                print(json.dumps({
+                    "frame_id": frame_id, 
+                    "memory": context.active_memory,
+                    "train": context.active_train
+                }))
+            else:
+                print(f"💭 Stored thought (frame {frame_id})")
+    except Exception as e:
+        print(f"Error: {e}", file=sys.stderr)
+        sys.exit(2)
+
+
+def _handle_recall(args):
+    """Search active memory."""
+    query = args.query
+    memory_path = getattr(args, 'memory', None)
+    top_k = args.top_k
+    engine = args.engine
+
+    if not query.strip():
+        print("Error: Query cannot be empty", file=sys.stderr)
+        sys.exit(1)
+
+    try:
+        # TODO: Implement --all-trains functionality
+        if getattr(args, 'all_trains', False):
+            print("Error: --all-trains not yet implemented", file=sys.stderr)
+            sys.exit(1)
+
+        with MemoryStore.from_context_or_path(memory_path) as store:
+            results = store.search(query, top_k=top_k, engine=engine)
+
+            if args.format == "json":
+                # Get current context for output
+                from ate.memory.context import ContextManager
+                context = ContextManager.get_context()
+                out = {
+                    "query": query,
+                    "memory": context.active_memory,
+                    "train": context.active_train,
+                    "results": [
+                        {
+                            "frame_id": r.frame_id,
+                            "text": r.text,
+                            "title": r.title,
+                            "score": r.score,
+                            "tags": r.tags,
+                            "metadata": r.metadata,
+                            "engine": r.engine,
+                        }
+                        for r in results
+                    ],
+                }
+                print(json.dumps(out))
+            else:
+                if not results:
+                    print("🔍 No results found.")
+                else:
+                    print(f"🔍 {len(results)} result(s) for \"{query}\":\n")
+                    for i, r in enumerate(results, 1):
+                        title_str = f" — {r.title}" if r.title else ""
+                        print(f"  {i}. [{r.score:.2f}] {r.text}{title_str}")
+                        if r.tags:
+                            print(f"     Tags: {', '.join(r.tags)}")
+    except Exception as e:
+        print(f"Error: {e}", file=sys.stderr)
+        sys.exit(2)
+
+
+def _handle_train(args):
+    """Manage trains of thought."""
+    from ate.memory.context import ContextManager
+    
+    try:
+        # List trains if no name provided
+        if not args.name:
+            context = ContextManager.get_context()
+            trains = ContextManager.list_trains(context.active_memory)
+            
+            if args.format == "json":
+                print(json.dumps({
+                    "memory": context.active_memory,
+                    "trains": trains,
+                    "active": context.active_train
+                }))
+            else:
+                print(f"🚂 Trains of thought in \"{context.active_memory}\":")
+                for train in trains:
+                    marker = " ← active" if train == context.active_train else ""
+                    print(f"  {'→' if train == context.active_train else ' '} {train}{marker}")
+            return
+
+        # Handle delete
+        if args.delete:
+            print("Error: --delete not yet implemented", file=sys.stderr)
+            sys.exit(1)
+
+        # Handle rename
+        if args.rename:
+            print("Error: --rename not yet implemented", file=sys.stderr)
+            sys.exit(1)
+
+        # Switch to train
+        context = ContextManager.get_context()
+        new_context = ContextManager.set_context(context.active_memory, args.name)
+        
+        if args.format == "json":
+            print(json.dumps({
+                "memory": new_context.active_memory,
+                "train": new_context.active_train,
+                "path": new_context.path
+            }))
+        else:
+            print(f"🚂 Switched to train \"{args.name}\"")
+            
+    except Exception as e:
+        print(f"Error: {e}", file=sys.stderr)
+        sys.exit(2)
+
+
+def _handle_status(args):
+    """Show current memory context."""
+    from ate.memory.context import ContextManager
+    
+    try:
+        context = ContextManager.get_context()
+        
+        # Get memory info
+        with MemoryStore.open(context.path) as store:
+            info = store.info()
+
+        if args.format == "json":
+            print(json.dumps({
+                "memory": context.active_memory,
+                "train": context.active_train,
+                "frames": info.frame_count,
+                "size_bytes": info.size_bytes,
+                "has_vec_index": info.has_vec_index,
+                "has_lex_index": info.has_lex_index,
+                "has_time_index": info.has_time_index,
+                "path": context.path,
+                "visibility": "private"  # Default for now
+            }))
+        else:
+            size_kb = info.size_bytes / 1024
+            print(f"🧠 Memory: {context.active_memory} (private)")
+            print(f"🚂 Train:  {context.active_train}")
+            print(f"📦 Frames: {info.frame_count} ({size_kb:.1f} KB)")
+            print(f"🔍 Search: {'lex' if info.has_lex_index else ''}" + 
+                  f"{' + vec' if info.has_vec_index else ''}")
+            print(f"📁 Path:   {context.path}")
+            
+    except Exception as e:
+        print(f"Error: {e}", file=sys.stderr)
+        sys.exit(2)
+
+
+def _handle_new(args):
+    """Create a new memory."""
+    from ate.memory.context import ContextManager
+    
+    try:
+        path = ContextManager.ensure_memory(args.name)
+        
+        # Update memory.json with description if provided
+        if args.description:
+            memory_dir = os.path.dirname(path)
+            memory_json_path = os.path.join(memory_dir, "memory.json")
+            
+            with open(memory_json_path, 'r') as f:
+                data = json.load(f)
+            data["description"] = args.description
+            with open(memory_json_path, 'w') as f:
+                json.dump(data, f, indent=2)
+        
+        if args.format == "json":
+            print(json.dumps({
+                "name": args.name,
+                "path": path,
+                "description": args.description,
+                "created": True
+            }))
+        else:
+            print(f"✅ Created memory \"{args.name}\"")
+            if args.description:
+                print(f"   Description: {args.description}")
+                
+    except Exception as e:
+        print(f"Error: {e}", file=sys.stderr)
+        sys.exit(2)
+
+
+def _handle_use(args):
+    """Switch to a different memory."""
+    from ate.memory.context import ContextManager
+    
+    try:
+        # Verify memory exists
+        memories = ContextManager.list_memories()
+        memory_names = [m.name for m in memories]
+        
+        if args.name not in memory_names:
+            print(f"Error: Memory '{args.name}' does not exist. Use 'ate memory list-memories' to see available memories.", file=sys.stderr)
+            sys.exit(1)
+        
+        # Find the default train for this memory
+        memory_metadata = next(m for m in memories if m.name == args.name)
+        default_train = memory_metadata.default_train
+        
+        context = ContextManager.set_context(args.name, default_train)
+        
+        if args.format == "json":
+            print(json.dumps({
+                "memory": context.active_memory,
+                "train": context.active_train,
+                "path": context.path
+            }))
+        else:
+            print(f"🧠 Switched to memory \"{args.name}\"")
+            
+    except Exception as e:
+        print(f"Error: {e}", file=sys.stderr)
+        sys.exit(2)
+
+
+def _handle_list_memories(args):
+    """List all local memories."""
+    from ate.memory.context import ContextManager
+    
+    try:
+        memories = ContextManager.list_memories()
+        
+        if args.format == "json":
+            print(json.dumps({
+                "memories": [
+                    {
+                        "name": m.name,
+                        "visibility": m.visibility,
+                        "trains": m.trains,
+                        "default_train": m.default_train,
+                        "description": m.description,
+                        "created_at": m.created_at,
+                        "remote": m.remote
+                    }
+                    for m in memories
+                ]
+            }))
+        else:
+            if not memories:
+                print("No local memories found.")
+                print("Create one with: ate memory new <name>")
+            else:
+                print(f"🧠 {len(memories)} local memor{'y' if len(memories) == 1 else 'ies'}:")
+                for memory in memories:
+                    trains_str = f"{len(memory.trains)} train{'s' if len(memory.trains) != 1 else ''}"
+                    desc_str = f" — {memory.description}" if memory.description else ""
+                    print(f"  • {memory.name} ({trains_str}){desc_str}")
+                    
+    except Exception as e:
+        print(f"Error: {e}", file=sys.stderr)
+        sys.exit(2)
+
+
+# ---------------------------------------------------------------------------
+# Cloud handlers (push / pull / list / delete)
+# ---------------------------------------------------------------------------
+
+def _get_cloud_client(args=None):
+    """Create a CloudClient with token from TokenStore.
+
+    Exits with code 1 if no valid token is found.
+    """
+    store = TokenStore()
+    token_resp = store.load()
+    if token_resp is None:
+        print("Error: Not authenticated. Run: ate device-login", file=sys.stderr)
+        sys.exit(1)
+    return CloudClient(token=token_resp.access_token)
+
+
+def _parse_ref(ref: str):
+    """Parse a 'project/name' reference like 'kindly/memories/test.mv2'.
+
+    The last path component is the name; everything before is the project.
+    Returns (project, name).
+    """
+    parts = ref.rsplit("/", 1)
+    if len(parts) != 2 or not parts[0] or not parts[1]:
+        print(f"Error: Invalid reference '{ref}'. Expected format: project/name", file=sys.stderr)
+        sys.exit(1)
+    return parts[0], parts[1]
+
+
+def _handle_push(args):
+    """Upload .mv2 file to cloud."""
+    client = _get_cloud_client(args)
+    try:
+        result = client.push(args.path, args.project, name=args.name)
+
+        if args.format == "json":
+            print(json.dumps(asdict(result)))
+        else:
+            print(f"✅ Pushed {result.name} to {result.project}")
+            print(f"   URL:  {result.url}")
+            print(f"   Size: {result.size_bytes} bytes")
+    except CloudAuthError as e:
+        print(f"Error: {e}", file=sys.stderr)
+        sys.exit(1)
+    except CloudError as e:
+        print(f"Error: {e}", file=sys.stderr)
+        sys.exit(2)
+    except Exception as e:
+        print(f"Error: {e}", file=sys.stderr)
+        sys.exit(2)
+
+
+def _handle_pull(args):
+    """Download .mv2 file from cloud."""
+    client = _get_cloud_client(args)
+    project, name = _parse_ref(args.ref)
+    try:
+        result = client.pull(project, name, args.output)
+
+        if args.format == "json":
+            print(json.dumps(asdict(result)))
+        else:
+            print(f"✅ Pulled {result.name} from {result.project}")
+            print(f"   Saved: {result.path}")
+            print(f"   Size:  {result.size_bytes} bytes")
+    except CloudNotFoundError as e:
+        print(f"Error: {e}", file=sys.stderr)
+        sys.exit(1)
+    except CloudAuthError as e:
+        print(f"Error: {e}", file=sys.stderr)
+        sys.exit(1)
+    except CloudError as e:
+        print(f"Error: {e}", file=sys.stderr)
+        sys.exit(2)
+    except Exception as e:
+        print(f"Error: {e}", file=sys.stderr)
+        sys.exit(2)
+
+
+def _handle_list(args):
+    """List memory files in a cloud project."""
+    client = _get_cloud_client(args)
+    try:
+        items = client.list(args.project)
+
+        if args.format == "json":
+            print(json.dumps({
+                "project": args.project,
+                "items": [asdict(item) for item in items],
+            }))
+        else:
+            if not items:
+                print(f"No memory files in project '{args.project}'.")
+            else:
+                print(f"📦 {len(items)} file(s) in {args.project}:\n")
+                for item in items:
+                    size_kb = item.size_bytes / 1024
+                    print(f"  • {item.name}  ({size_kb:.1f} KB)  {item.updated_at}")
+    except CloudAuthError as e:
+        print(f"Error: {e}", file=sys.stderr)
+        sys.exit(1)
+    except CloudError as e:
+        print(f"Error: {e}", file=sys.stderr)
+        sys.exit(2)
+    except Exception as e:
+        print(f"Error: {e}", file=sys.stderr)
+        sys.exit(2)
+
+
+def _handle_delete(args):
+    """Delete a memory file from cloud."""
+    client = _get_cloud_client(args)
+    project, name = _parse_ref(args.ref)
+    try:
+        client.delete(project, name)
+
+        if args.format == "json":
+            print(json.dumps({"project": project, "name": name, "deleted": True}))
+        else:
+            print(f"✅ Deleted {name} from {project}")
+    except CloudNotFoundError as e:
+        print(f"Error: {e}", file=sys.stderr)
+        sys.exit(1)
+    except CloudAuthError as e:
+        print(f"Error: {e}", file=sys.stderr)
+        sys.exit(1)
+    except CloudError as e:
+        print(f"Error: {e}", file=sys.stderr)
+        sys.exit(2)
+    except Exception as e:
+        print(f"Error: {e}", file=sys.stderr)
+        sys.exit(2)
+
+
+def _handle_providers(args):
+    """List detected embedding providers."""
+    try:
+        providers = EmbeddingManager.available_providers()
+        
+        # Determine active provider
+        active_config = EmbeddingManager.detect()
+        active = active_config.provider if active_config.provider != "none" else None
+        
+        if args.format == "json":
+            print(json.dumps({
+                "providers": providers,
+                "active": active
+            }))
+        else:
+            print("🤖 Embedding Providers:\n")
+            for provider in providers:
+                status = "✅" if provider["available"] else "❌"
+                name = provider["name"]
+                
+                if provider["available"]:
+                    model = provider.get("model", "default")
+                    source = provider.get("source", "unknown")
+                    print(f"  {status} {name} ({model}) - {source}")
+                else:
+                    reason = provider.get("reason", "unknown")
+                    print(f"  {status} {name} - {reason}")
+            
+            if active:
+                print(f"\n🎯 Active provider: {active}")
+            else:
+                print(f"\n⚠️ No embedding providers available - using BM25 lexical search only")
+                
+    except Exception as e:
+        print(f"Error: {e}", file=sys.stderr)
+        sys.exit(2)