superlocalmemory 3.0.25 → 3.0.27

package/README.md

@@ -16,6 +16,8 @@
   <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-green?style=for-the-badge" alt="MIT License"/></a>
   <a href="#eu-ai-act-compliance"><img src="https://img.shields.io/badge/EU_AI_Act-Compliant-brightgreen?style=for-the-badge" alt="EU AI Act"/></a>
   <a href="https://superlocalmemory.com"><img src="https://img.shields.io/badge/Web-superlocalmemory.com-ff6b35?style=for-the-badge" alt="Website"/></a>
+  <a href="#dual-interface-mcp--cli"><img src="https://img.shields.io/badge/MCP-Native-blue?style=for-the-badge" alt="MCP Native"/></a>
+  <a href="#dual-interface-mcp--cli"><img src="https://img.shields.io/badge/CLI-Agent--Native-green?style=for-the-badge" alt="CLI Agent-Native"/></a>
 </p>
 
 ---
@@ -84,6 +86,32 @@ slm status
 
 24 MCP tools available. Works with Claude Code, Cursor, Windsurf, VS Code Copilot, Continue, Cody, ChatGPT Desktop, Gemini CLI, JetBrains, Zed, and 17+ AI tools.
 
+### Dual Interface: MCP + CLI
+
+SLM works everywhere -- from IDEs to CI pipelines to Docker containers. The only AI memory system with both MCP and agent-native CLI.
+
+| Need | Use | Example |
+|------|-----|---------|
+| IDE integration | MCP | Auto-configured for 17+ IDEs via `slm connect` |
+| Shell scripts | CLI + `--json` | `slm recall "auth" --json \| jq '.data.results[0]'` |
+| CI/CD pipelines | CLI + `--json` | `slm remember "deployed v2.1" --json` in GitHub Actions |
+| Agent frameworks | CLI + `--json` | OpenClaw, Codex, Goose, nanobot |
+| Human use | CLI | `slm recall "auth"` (readable text output) |
+
+**Agent-native JSON output** on every command:
+
+```bash
+# Human-readable (default)
+slm recall "database schema"
+#   1. [0.87] Database uses PostgreSQL 16 on port 5432...
+
+# Agent-native JSON
+slm recall "database schema" --json
+# {"success": true, "command": "recall", "version": "3.0.22", "data": {"results": [...]}}
+```
+
+All `--json` responses follow a consistent envelope with `success`, `command`, `version`, `data`, and `next_actions` for agent guidance.
+
 ---
 
 ## Three Operating Modes

package/docs/cli-reference.md

@@ -237,9 +237,60 @@ These options work with any command:
 | `--help` | Show help for a command |
 | `--version` | Show SLM version |
 | `--verbose` | Show detailed output |
-| `--json` | Output in JSON format (for scripting) |
+| `--json` | Output structured JSON with agent-native envelope (for AI agents, scripts, CI/CD) |
 | `--profile name` | Override the active profile for this command |
 
+## Agent-Native JSON Output
+
+All data-returning commands support `--json` for structured output. The envelope follows the 2026 agent-native CLI standard:
+
+```json
+{
+  "success": true,
+  "command": "recall",
+  "version": "3.0.22",
+  "data": {
+    "results": [
+      {"fact_id": "abc123", "score": 0.87, "content": "Database uses PostgreSQL 16"}
+    ],
+    "count": 1,
+    "query_type": "semantic"
+  },
+  "next_actions": [
+    {"command": "slm list --json", "description": "List recent memories"}
+  ]
+}
+```
+
+### Supported Commands
+
+`recall`, `remember`, `list`, `status`, `health`, `trace`, `forget`, `delete`, `update`, `mode`, `profile`, `connect`
+
+### Usage with jq
+
+```bash
+# Get first result content
+slm recall "auth" --json | jq '.data.results[0].content'
+
+# Get all fact IDs
+slm list --json | jq '.data.results[].fact_id'
+
+# Check current mode
+slm status --json | jq '.data.mode'
+```
+
+### In CI/CD (GitHub Actions)
+
+```yaml
+- name: Store deployment info
+  run: slm remember "Deployed ${{ github.sha }} to production" --json
+
+- name: Check memory health
+  run: slm status --json | jq -e '.success'
+```
+
+---
+
 ## Examples
 
 ### Daily workflow

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "superlocalmemory",
-  "version": "3.0.25",
+  "version": "3.0.27",
   "description": "Information-geometric agent memory with mathematical guarantees. 4-channel retrieval, Fisher-Rao similarity, zero-LLM mode, EU AI Act compliant. Works with Claude, Cursor, Windsurf, and 17+ AI tools.",
   "keywords": [
     "ai-memory",

package/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "superlocalmemory"
-version = "3.0.25"
+version = "3.0.27"
 description = "Information-geometric agent memory with mathematical guarantees"
 readme = "README.md"
 license = {text = "MIT"}

package/src/superlocalmemory/cli/commands.py

@@ -5,6 +5,7 @@
 """CLI command implementations.
 
 Each function handles one CLI command. Dispatch routes by name.
+All data-returning commands support --json for agent-native output.
 
 Part of Qualixar | Author: Varun Pratap Bhardwaj
 """
@@ -45,6 +46,9 @@ def dispatch(args: Namespace) -> None:
         sys.exit(1)
 
 
+# -- Setup & Config (no --json — interactive commands) ---------------------
+
+
 def cmd_setup(_args: Namespace) -> None:
     """Run the interactive setup wizard."""
     from superlocalmemory.cli.setup_wizard import run_wizard
@@ -59,6 +63,31 @@ def cmd_mode(args: Namespace) -> None:
 
     config = SLMConfig.load()
 
+    if getattr(args, 'json', False):
+        from superlocalmemory.cli.json_output import json_print
+        if args.value:
+            old_mode = config.mode.value.upper()
+            updated = SLMConfig.for_mode(
+                Mode(args.value),
+                llm_provider=config.llm.provider,
+                llm_model=config.llm.model,
+                llm_api_key=config.llm.api_key,
+                llm_api_base=config.llm.api_base,
+            )
+            updated.save()
+            json_print("mode", data={
+                "previous_mode": old_mode, "current_mode": args.value.upper(),
+            }, next_actions=[
+                {"command": "slm status --json", "description": "Check system status"},
+            ])
+        else:
+            json_print("mode", data={"current_mode": config.mode.value.upper()},
+                       next_actions=[
+                           {"command": "slm mode a --json", "description": "Switch to zero-cloud mode"},
+                           {"command": "slm mode c --json", "description": "Switch to full-power mode"},
+                       ])
+        return
+
     if args.value:
         updated = SLMConfig.for_mode(
             Mode(args.value),
@@ -94,6 +123,24 @@ def cmd_connect(args: Namespace) -> None:
     from superlocalmemory.hooks.ide_connector import IDEConnector
 
     connector = IDEConnector()
+
+    if getattr(args, 'json', False):
+        from superlocalmemory.cli.json_output import json_print
+        if getattr(args, "list", False):
+            json_print("connect", data={"ides": connector.get_status()},
+                       next_actions=[
+                           {"command": "slm connect --json", "description": "Auto-configure all IDEs"},
+                       ])
+        elif getattr(args, "ide", None):
+            success = connector.connect(args.ide)
+            json_print("connect", data={"ide": args.ide, "connected": success})
+        else:
+            json_print("connect", data={"results": connector.connect_all()},
+                       next_actions=[
+                           {"command": "slm status --json", "description": "Check system status"},
+                       ])
+        return
+
     if getattr(args, "list", False):
         status = connector.get_status()
         for s in status:
@@ -116,20 +163,47 @@ def cmd_migrate(args: Namespace) -> None:
     _migrate(args)
 
 
+# -- Memory Operations (all support --json) --------------------------------
+
+
 def cmd_list(args: Namespace) -> None:
     """List recent memories chronologically."""
     from superlocalmemory.core.config import SLMConfig
     from superlocalmemory.core.engine import MemoryEngine
 
-    config = SLMConfig.load()
-    engine = MemoryEngine(config)
-    engine.initialize()
-
-    limit = getattr(args, "limit", 20)
-    facts = engine._db.get_all_facts(engine.profile_id)
-    # Sort by created_at descending, take limit
-    facts.sort(key=lambda f: f.created_at or "", reverse=True)
-    facts = facts[:limit]
+    use_json = getattr(args, 'json', False)
+    try:
+        config = SLMConfig.load()
+        engine = MemoryEngine(config)
+        engine.initialize()
+
+        limit = getattr(args, "limit", 20)
+        facts = engine._db.get_all_facts(engine.profile_id)
+        facts.sort(key=lambda f: f.created_at or "", reverse=True)
+        facts = facts[:limit]
+    except Exception as exc:
+        if use_json:
+            from superlocalmemory.cli.json_output import json_print
+            json_print("list", error={"code": "ENGINE_ERROR", "message": str(exc)})
+            sys.exit(1)
+        raise
+
+    if use_json:
+        from superlocalmemory.cli.json_output import json_print
+        items = []
+        for f in facts:
+            ftype_raw = getattr(f, "fact_type", "")
+            ftype = ftype_raw.value if hasattr(ftype_raw, "value") else str(ftype_raw)
+            items.append({
+                "fact_id": f.fact_id, "content": f.content,
+                "fact_type": ftype, "created_at": (f.created_at or "")[:19],
+            })
+        json_print("list", data={"results": items, "count": len(items)},
+                   next_actions=[
+                       {"command": "slm recall '<query>' --json", "description": "Search memories"},
+                       {"command": "slm delete <fact_id> --json --yes", "description": "Delete a memory"},
+                   ])
+        return
 
     if not facts:
         print("No memories stored yet.")
@@ -149,12 +223,30 @@ def cmd_remember(args: Namespace) -> None:
     from superlocalmemory.core.config import SLMConfig
     from superlocalmemory.core.engine import MemoryEngine
 
-    config = SLMConfig.load()
-    engine = MemoryEngine(config)
-    engine.initialize()
+    use_json = getattr(args, 'json', False)
+    try:
+        config = SLMConfig.load()
+        engine = MemoryEngine(config)
+        engine.initialize()
+
+        metadata = {"tags": args.tags} if args.tags else {}
+        fact_ids = engine.store(args.content, metadata=metadata)
+    except Exception as exc:
+        if use_json:
+            from superlocalmemory.cli.json_output import json_print
+            json_print("remember", error={"code": "STORE_ERROR", "message": str(exc)})
+            sys.exit(1)
+        raise
+
+    if use_json:
+        from superlocalmemory.cli.json_output import json_print
+        json_print("remember", data={"fact_ids": fact_ids, "count": len(fact_ids)},
+                   next_actions=[
+                       {"command": "slm recall '<query>' --json", "description": "Search your memories"},
+                       {"command": "slm list --json -n 5", "description": "See recent memories"},
+                   ])
+        return
 
-    metadata = {"tags": args.tags} if args.tags else {}
-    fact_ids = engine.store(args.content, metadata=metadata)
     print(f"Stored {len(fact_ids)} facts.")
 
 
@@ -163,11 +255,39 @@ def cmd_recall(args: Namespace) -> None:
     from superlocalmemory.core.config import SLMConfig
     from superlocalmemory.core.engine import MemoryEngine
 
-    config = SLMConfig.load()
-    engine = MemoryEngine(config)
-    engine.initialize()
+    use_json = getattr(args, 'json', False)
+    try:
+        config = SLMConfig.load()
+        engine = MemoryEngine(config)
+        engine.initialize()
+
+        response = engine.recall(args.query, limit=args.limit)
+    except Exception as exc:
+        if use_json:
+            from superlocalmemory.cli.json_output import json_print
+            json_print("recall", error={"code": "RECALL_ERROR", "message": str(exc)})
+            sys.exit(1)
+        raise
+
+    if use_json:
+        from superlocalmemory.cli.json_output import json_print
+        items = []
+        for r in response.results:
+            item = {
+                "fact_id": r.fact.fact_id, "content": r.fact.content,
+                "score": round(r.score, 3),
+            }
+            if hasattr(r, "channel_scores") and r.channel_scores:
+                item["channel_scores"] = {k: round(v, 3) for k, v in r.channel_scores.items()}
+            items.append(item)
+        json_print("recall", data={
+            "results": items, "count": len(items),
+            "query_type": getattr(response, "query_type", "unknown"),
+        }, next_actions=[
+            {"command": "slm list --json", "description": "List recent memories"},
+        ])
+        return
 
-    response = engine.recall(args.query, limit=args.limit)
     if not response.results:
         print("No memories found.")
         return
@@ -180,18 +300,57 @@ def cmd_forget(args: Namespace) -> None:
     from superlocalmemory.core.engine import MemoryEngine
     from superlocalmemory.core.config import SLMConfig
 
-    config = SLMConfig.load()
-    engine = MemoryEngine(config)
-    engine.initialize()
-    facts = engine._db.get_all_facts(engine.profile_id)
-    query_lower = args.query.lower()
-    matches = [f for f in facts if query_lower in f.content.lower()]
+    use_json = getattr(args, 'json', False)
+    try:
+        config = SLMConfig.load()
+        engine = MemoryEngine(config)
+        engine.initialize()
+        facts = engine._db.get_all_facts(engine.profile_id)
+        query_lower = args.query.lower()
+        matches = [f for f in facts if query_lower in f.content.lower()]
+    except Exception as exc:
+        if use_json:
+            from superlocalmemory.cli.json_output import json_print
+            json_print("forget", error={"code": "ENGINE_ERROR", "message": str(exc)})
+            sys.exit(1)
+        raise
+
+    if use_json:
+        from superlocalmemory.cli.json_output import json_print
+        if not matches:
+            json_print("forget", data={"matched_count": 0, "deleted_count": 0, "matches": []})
+            return
+        match_items = [{"fact_id": f.fact_id, "content": f.content[:120]} for f in matches[:20]]
+        if getattr(args, 'yes', False):
+            for f in matches:
+                engine._db.delete_fact(f.fact_id)
+            json_print("forget", data={
+                "matched_count": len(matches), "deleted_count": len(matches),
+                "deleted": [f.fact_id for f in matches],
+            }, next_actions=[
+                {"command": "slm list --json", "description": "Verify remaining memories"},
+            ])
+        else:
+            json_print("forget", data={
+                "matched_count": len(matches), "deleted_count": 0,
+                "matches": match_items,
+                "hint": "Add --yes to confirm deletion",
+            }, next_actions=[
+                {"command": f"slm forget '{args.query}' --json --yes", "description": "Confirm deletion"},
+            ])
+        return
+
     if not matches:
         print(f"No memories matching '{args.query}'")
         return
     print(f"Found {len(matches)} matching memories:")
     for f in matches[:10]:
         print(f"  - {f.fact_id[:8]}... {f.content[:80]}")
+    if getattr(args, 'yes', False):
+        for f in matches:
+            engine._db.delete_fact(f.fact_id)
+        print(f"Deleted {len(matches)} memories.")
+        return
     confirm = input(f"Delete {len(matches)} memories? [y/N] ").strip().lower()
     if confirm in ("y", "yes"):
         for f in matches:
@@ -206,16 +365,47 @@ def cmd_delete(args: Namespace) -> None:
     from superlocalmemory.core.config import SLMConfig
     from superlocalmemory.core.engine import MemoryEngine
 
-    config = SLMConfig.load()
-    engine = MemoryEngine(config)
-    engine.initialize()
+    use_json = getattr(args, 'json', False)
+    try:
+        config = SLMConfig.load()
+        engine = MemoryEngine(config)
+        engine.initialize()
+
+        fact_id = args.fact_id.strip()
+        rows = engine._db.execute(
+            "SELECT content FROM atomic_facts WHERE fact_id = ? AND profile_id = ?",
+            (fact_id, engine.profile_id),
+        )
+    except Exception as exc:
+        if use_json:
+            from superlocalmemory.cli.json_output import json_print
+            json_print("delete", error={"code": "ENGINE_ERROR", "message": str(exc)})
+            sys.exit(1)
+        raise
+
+    if use_json:
+        from superlocalmemory.cli.json_output import json_print
+        if not rows:
+            json_print("delete", error={
+                "code": "NOT_FOUND", "message": f"Memory not found: {fact_id}",
+            })
+            sys.exit(1)
+        content = dict(rows[0]).get("content", "")
+        if getattr(args, "yes", False):
+            engine._db.delete_fact(fact_id)
+            json_print("delete", data={"deleted": fact_id, "content": content[:120]},
+                       next_actions=[
+                           {"command": "slm list --json", "description": "Verify remaining memories"},
+                       ])
+        else:
+            json_print("delete", data={
+                "fact_id": fact_id, "content": content[:120], "deleted": False,
+                "hint": "Add --yes to confirm deletion",
+            }, next_actions=[
+                {"command": f"slm delete {fact_id} --json --yes", "description": "Confirm deletion"},
+            ])
+        return
 
-    fact_id = args.fact_id.strip()
-    # Look up the memory first so user can confirm
-    rows = engine._db.execute(
-        "SELECT content FROM atomic_facts WHERE fact_id = ? AND profile_id = ?",
-        (fact_id, engine.profile_id),
-    )
     if not rows:
         print(f"Memory not found: {fact_id}")
         return
@@ -238,40 +428,91 @@ def cmd_update(args: Namespace) -> None:
     from superlocalmemory.core.config import SLMConfig
     from superlocalmemory.core.engine import MemoryEngine
 
-    config = SLMConfig.load()
-    engine = MemoryEngine(config)
-    engine.initialize()
-
+    use_json = getattr(args, 'json', False)
     fact_id = args.fact_id.strip()
     new_content = args.content.strip()
+
     if not new_content:
+        if use_json:
+            from superlocalmemory.cli.json_output import json_print
+            json_print("update", error={"code": "INVALID_INPUT", "message": "content cannot be empty"})
+            sys.exit(1)
         print("Error: content cannot be empty")
         return
 
-    rows = engine._db.execute(
-        "SELECT content FROM atomic_facts WHERE fact_id = ? AND profile_id = ?",
-        (fact_id, engine.profile_id),
-    )
+    try:
+        config = SLMConfig.load()
+        engine = MemoryEngine(config)
+        engine.initialize()
+
+        rows = engine._db.execute(
+            "SELECT content FROM atomic_facts WHERE fact_id = ? AND profile_id = ?",
+            (fact_id, engine.profile_id),
+        )
+    except Exception as exc:
+        if use_json:
+            from superlocalmemory.cli.json_output import json_print
+            json_print("update", error={"code": "ENGINE_ERROR", "message": str(exc)})
+            sys.exit(1)
+        raise
+
     if not rows:
+        if use_json:
+            from superlocalmemory.cli.json_output import json_print
+            json_print("update", error={
+                "code": "NOT_FOUND", "message": f"Memory not found: {fact_id}",
+            })
+            sys.exit(1)
         print(f"Memory not found: {fact_id}")
         return
 
     old_content = dict(rows[0]).get("content", "")
-    print(f"Old: {old_content[:100]}")
-    print(f"New: {new_content[:100]}")
-
     engine._db.execute(
         "UPDATE atomic_facts SET content = ? WHERE fact_id = ?",
         (new_content, fact_id),
     )
+
+    if use_json:
+        from superlocalmemory.cli.json_output import json_print
+        json_print("update", data={
+            "fact_id": fact_id,
+            "old_content": old_content[:120],
+            "new_content": new_content[:120],
+        }, next_actions=[
+            {"command": "slm list --json", "description": "List recent memories"},
+        ])
+        return
+
+    print(f"Old: {old_content[:100]}")
+    print(f"New: {new_content[:100]}")
     print(f"Updated: {fact_id}")
 
 
-def cmd_status(_args: Namespace) -> None:
+# -- Diagnostics (all support --json) -------------------------------------
+
+
+def cmd_status(args: Namespace) -> None:
     """Show system status."""
     from superlocalmemory.core.config import SLMConfig
 
     config = SLMConfig.load()
+
+    if getattr(args, 'json', False):
+        from superlocalmemory.cli.json_output import json_print
+        data = {
+            "mode": config.mode.value.upper(),
+            "provider": config.llm.provider or "none",
+            "base_dir": str(config.base_dir),
+            "db_path": str(config.db_path),
+        }
+        if config.db_path.exists():
+            data["db_size_mb"] = round(config.db_path.stat().st_size / 1024 / 1024, 2)
+        json_print("status", data=data, next_actions=[
+            {"command": "slm health --json", "description": "Check math layer health"},
+            {"command": "slm list --json", "description": "List recent memories"},
+        ])
+        return
+
     print("SuperLocalMemory V3")
     print(f"  Mode: {config.mode.value.upper()}")
     print(f"  Provider: {config.llm.provider or 'none'}")
@@ -282,17 +523,39 @@ def cmd_status(_args: Namespace) -> None:
         print(f"  DB size: {size_mb} MB")
 
 
-def cmd_health(_args: Namespace) -> None:
+def cmd_health(args: Namespace) -> None:
     """Show math layer health status."""
     from superlocalmemory.core.engine import MemoryEngine
     from superlocalmemory.core.config import SLMConfig
 
-    config = SLMConfig.load()
-    engine = MemoryEngine(config)
-    engine.initialize()
-    facts = engine._db.get_all_facts(engine.profile_id)
-    fisher_count = sum(1 for f in facts if f.fisher_mean is not None)
-    langevin_count = sum(1 for f in facts if f.langevin_position is not None)
+    use_json = getattr(args, 'json', False)
+    try:
+        config = SLMConfig.load()
+        engine = MemoryEngine(config)
+        engine.initialize()
+        facts = engine._db.get_all_facts(engine.profile_id)
+        fisher_count = sum(1 for f in facts if f.fisher_mean is not None)
+        langevin_count = sum(1 for f in facts if f.langevin_position is not None)
+    except Exception as exc:
+        if use_json:
+            from superlocalmemory.cli.json_output import json_print
+            json_print("health", error={"code": "ENGINE_ERROR", "message": str(exc)})
+            sys.exit(1)
+        raise
+
+    if use_json:
+        from superlocalmemory.cli.json_output import json_print
+        json_print("health", data={
+            "total_facts": len(facts),
+            "similarity_indexed": fisher_count,
+            "lifecycle_positioned": langevin_count,
+            "mode": config.mode.value.upper(),
+        }, next_actions=[
+            {"command": "slm status --json", "description": "Check system status"},
+            {"command": "slm recall '<query>' --json", "description": "Test retrieval"},
+        ])
+        return
+
     print("Math Layer Health:")
     print(f"  Total facts: {len(facts)}")
     print(f"  Fisher-Rao indexed: {fisher_count}/{len(facts)}")
@@ -305,9 +568,41 @@ def cmd_trace(args: Namespace) -> None:
     from superlocalmemory.core.engine import MemoryEngine
     from superlocalmemory.core.config import SLMConfig
 
-    config = SLMConfig.load()
-    engine = MemoryEngine(config)
-    response = engine.recall(args.query, limit=5)
+    use_json = getattr(args, 'json', False)
+    try:
+        config = SLMConfig.load()
+        engine = MemoryEngine(config)
+        response = engine.recall(args.query, limit=5)
+    except Exception as exc:
+        if use_json:
+            from superlocalmemory.cli.json_output import json_print
+            json_print("trace", error={"code": "ENGINE_ERROR", "message": str(exc)})
+            sys.exit(1)
+        raise
+
+    if use_json:
+        from superlocalmemory.cli.json_output import json_print
+        items = []
+        for r in response.results:
+            item = {
+                "fact_id": r.fact.fact_id, "content": r.fact.content[:200],
+                "score": round(r.score, 3),
+            }
+            if hasattr(r, "channel_scores") and r.channel_scores:
+                item["channel_scores"] = {
+                    k: round(v, 3) for k, v in r.channel_scores.items()
+                }
+            items.append(item)
+        json_print("trace", data={
+            "query": args.query,
+            "query_type": getattr(response, "query_type", "unknown"),
+            "retrieval_time_ms": round(getattr(response, "retrieval_time_ms", 0), 1),
+            "results": items, "count": len(items),
+        }, next_actions=[
+            {"command": "slm recall '<query>' --json", "description": "Standard recall"},
+        ])
+        return
+
     print(f"Query: {args.query}")
     print(f"Type: {response.query_type} | Time: {response.retrieval_time_ms:.0f}ms")
     print(f"Results: {len(response.results)}")
@@ -318,6 +613,9 @@ def cmd_trace(args: Namespace) -> None:
                 print(f"       {ch}: {sc:.3f}")
 
 
+# -- Services (no --json — these start long-running processes) -------------
+
+
 def cmd_mcp(_args: Namespace) -> None:
     """Start the V3 MCP server (stdio transport for IDE integration)."""
     from superlocalmemory.mcp.server import server
@@ -397,6 +695,9 @@ def cmd_dashboard(args: Namespace) -> None:
     uvicorn.run(app, host="127.0.0.1", port=ui_port, log_level="info")
 
 
+# -- Profiles (supports --json) -------------------------------------------
+
+
 def cmd_profile(args: Namespace) -> None:
     """Profile management (list, switch, create)."""
     from superlocalmemory.core.config import SLMConfig
@@ -407,6 +708,34 @@ def cmd_profile(args: Namespace) -> None:
     db = DatabaseManager(config.db_path)
     db.initialize(schema)
 
+    if getattr(args, 'json', False):
+        from superlocalmemory.cli.json_output import json_print
+        if args.action == "list":
+            rows = db.execute("SELECT profile_id, name FROM profiles")
+            profiles = [
+                {"profile_id": dict(r)["profile_id"], "name": dict(r).get("name", "")}
+                for r in rows
+            ]
+            json_print("profile", data={"profiles": profiles, "count": len(profiles)},
+                       next_actions=[
+                           {"command": "slm profile switch <name> --json", "description": "Switch profile"},
+                       ])
+        elif args.action == "switch":
+            config.active_profile = args.name
+            config.save()
+            json_print("profile", data={"action": "switched", "profile": args.name})
+        elif args.action == "create":
+            db.execute(
+                "INSERT OR IGNORE INTO profiles (profile_id, name) VALUES (?, ?)",
+                (args.name, args.name),
+            )
+            json_print("profile", data={"action": "created", "profile": args.name},
+                       next_actions=[
+                           {"command": f"slm profile switch {args.name} --json",
+                            "description": "Switch to new profile"},
+                       ])
+        return
+
     if args.action == "list":
         rows = db.execute("SELECT profile_id, name FROM profiles")
         print("Profiles:")

package/src/superlocalmemory/cli/json_output.py

@@ -0,0 +1,58 @@
+# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
+# Licensed under the MIT License - see LICENSE file
+# Part of SuperLocalMemory V3 | https://qualixar.com | https://varunpratap.com
+
+"""Shared JSON envelope for agent-native CLI output.
+
+Follows the 2026 agent-native CLI standard:
+- Consistent envelope: success, command, version, data/error
+- HATEOAS next_actions for agent guidance
+- Metadata for execution context
+
+Part of Qualixar | Author: Varun Pratap Bhardwaj
+"""
+
+from __future__ import annotations
+
+import json
+
+
+def _get_version() -> str:
+    """Get installed package version."""
+    try:
+        from importlib.metadata import version
+        return version("superlocalmemory")
+    except Exception:
+        return "unknown"
+
+
+def json_print(
+    command: str,
+    *,
+    data: dict | None = None,
+    error: dict | None = None,
+    next_actions: list[dict] | None = None,
+    metadata: dict | None = None,
+) -> None:
+    """Print a standard JSON envelope to stdout.
+
+    Success envelope:
+        {"success": true, "command": "...", "version": "...", "data": {...}}
+
+    Error envelope:
+        {"success": false, "command": "...", "version": "...", "error": {...}}
+    """
+    envelope: dict = {
+        "success": error is None,
+        "command": command,
+        "version": _get_version(),
+    }
+    if error is not None:
+        envelope["error"] = error
+    else:
+        envelope["data"] = data if data is not None else {}
+    if metadata:
+        envelope["metadata"] = metadata
+    if next_actions:
+        envelope["next_actions"] = next_actions
+    print(json.dumps(envelope, indent=2, default=str))

package/src/superlocalmemory/cli/main.py

@@ -59,6 +59,7 @@ examples:
   slm trace "auth flow"       Recall with per-channel score breakdown
   slm health                  Check math layer status
   slm dashboard --port 9000   Dashboard on custom port
+  slm recall "query" --json   Agent-native JSON output (for scripts, CI/CD)
 
 documentation:
   Website:    https://superlocalmemory.com
@@ -93,6 +94,7 @@ def main() -> None:
     mode_p.add_argument(
         "value", nargs="?", choices=["a", "b", "c"], help="Mode to set",
     )
+    mode_p.add_argument("--json", action="store_true", help="Output structured JSON (agent-native)")
 
     provider_p = sub.add_parser("provider", help="Get or set LLM provider for Mode B/C")
     provider_p.add_argument(
@@ -104,6 +106,7 @@ def main() -> None:
     connect_p.add_argument(
         "--list", action="store_true", help="List all supported IDEs",
     )
+    connect_p.add_argument("--json", action="store_true", help="Output structured JSON (agent-native)")
 
     migrate_p = sub.add_parser("migrate", help="Migrate data from V2 to V3 schema")
     migrate_p.add_argument(
@@ -114,33 +117,44 @@ def main() -> None:
     remember_p = sub.add_parser("remember", help="Store a memory (extracts facts, builds graph)")
     remember_p.add_argument("content", help="Content to remember")
     remember_p.add_argument("--tags", default="", help="Comma-separated tags")
+    remember_p.add_argument("--json", action="store_true", help="Output structured JSON (agent-native)")
 
     recall_p = sub.add_parser("recall", help="Semantic search with 4-channel retrieval")
     recall_p.add_argument("query", help="Search query")
     recall_p.add_argument("--limit", type=int, default=10, help="Max results (default 10)")
+    recall_p.add_argument("--json", action="store_true", help="Output structured JSON (agent-native)")
 
     forget_p = sub.add_parser("forget", help="Delete memories matching a query (fuzzy)")
     forget_p.add_argument("query", help="Query to match for deletion")
+    forget_p.add_argument("--yes", "-y", action="store_true", help="Skip confirmation prompt")
+    forget_p.add_argument("--json", action="store_true", help="Output structured JSON (agent-native)")
 
     delete_p = sub.add_parser("delete", help="Delete a specific memory by ID (precise)")
     delete_p.add_argument("fact_id", help="Exact fact ID to delete")
     delete_p.add_argument("--yes", "-y", action="store_true", help="Skip confirmation")
+    delete_p.add_argument("--json", action="store_true", help="Output structured JSON (agent-native)")
 
     update_p = sub.add_parser("update", help="Edit the content of a specific memory by ID")
     update_p.add_argument("fact_id", help="Exact fact ID to update")
     update_p.add_argument("content", help="New content for the memory")
+    update_p.add_argument("--json", action="store_true", help="Output structured JSON (agent-native)")
 
     list_p = sub.add_parser("list", help="List recent memories chronologically (shows IDs for delete/update)")
     list_p.add_argument(
         "--limit", "-n", type=int, default=20, help="Number of entries (default 20)",
     )
+    list_p.add_argument("--json", action="store_true", help="Output structured JSON (agent-native)")
 
     # -- Diagnostics ---------------------------------------------------
-    sub.add_parser("status", help="System status (mode, profile, DB size)")
-    sub.add_parser("health", help="Math layer health (Fisher-Rao, Sheaf, Langevin)")
+    status_p = sub.add_parser("status", help="System status (mode, profile, DB size)")
+    status_p.add_argument("--json", action="store_true", help="Output structured JSON (agent-native)")
+
+    health_p = sub.add_parser("health", help="Math layer health (Fisher-Rao, Sheaf, Langevin)")
+    health_p.add_argument("--json", action="store_true", help="Output structured JSON (agent-native)")
 
     trace_p = sub.add_parser("trace", help="Recall with per-channel score breakdown")
     trace_p.add_argument("query", help="Search query")
+    trace_p.add_argument("--json", action="store_true", help="Output structured JSON (agent-native)")
 
     # -- Services ------------------------------------------------------
     sub.add_parser("mcp", help="Start MCP server (stdio transport for IDE integration)")
@@ -157,6 +171,7 @@ def main() -> None:
         "action", choices=["list", "switch", "create"], help="Action",
     )
     profile_p.add_argument("name", nargs="?", help="Profile name")
+    profile_p.add_argument("--json", action="store_true", help="Output structured JSON (agent-native)")
 
     args = parser.parse_args()
 

package/src/superlocalmemory/server/ui.py

@@ -26,24 +26,20 @@ logger = logging.getLogger(__name__)
 
 
 def _get_version() -> str:
-    """Read version from package metadata, package.json, or pyproject.toml."""
+    """Read version from package.json (npm), pyproject.toml, or metadata."""
     import json as _json
-    # 1. Try importlib.metadata (works when pip-installed)
-    try:
-        from importlib.metadata import version
-        return version("superlocalmemory")
-    except Exception:
-        pass
-    # 2. Try package.json (works when npm-installed)
     pkg_root = Path(__file__).resolve().parent.parent.parent.parent
+    # 1. Try package.json FIRST (source of truth for npm installs)
     try:
         pkg_json = pkg_root / "package.json"
         if pkg_json.exists():
             with open(pkg_json) as f:
-                return _json.load(f).get("version", "")
+                v = _json.load(f).get("version", "")
+                if v:
+                    return v
     except Exception:
         pass
-    # 3. Try pyproject.toml
+    # 2. Try pyproject.toml (source of truth for pip installs)
     try:
         import tomllib
         toml_path = pkg_root / "pyproject.toml"
@@ -52,6 +48,12 @@ def _get_version() -> str:
                 return tomllib.load(f)["project"]["version"]
     except Exception:
         pass
+    # 3. Fallback to importlib.metadata
+    try:
+        from importlib.metadata import version
+        return version("superlocalmemory")
+    except Exception:
+        pass
     return "unknown"