surreal-memory 2.3.1__tar.gz → 2.3.2__tar.gz

{surreal_memory-2.3.1 → surreal_memory-2.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: surreal-memory
-Version: 2.3.1
+Version: 2.3.2
 Summary: Reflex-based memory system for AI agents with SurrealDB backend — retrieval through activation, not search
 Project-URL: Homepage, https://github.com/acidkill/surreal-memory
 Project-URL: Documentation, https://github.com/acidkill/surreal-memory/blob/main/docs/getting-started/quickstart.md

{surreal_memory-2.3.1 → surreal_memory-2.3.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "surreal-memory"
-version = "2.3.1"
+version = "2.3.2"
 description = "Reflex-based memory system for AI agents with SurrealDB backend — retrieval through activation, not search"
 readme = "README.md"
 license = "MIT"

{surreal_memory-2.3.1 → surreal_memory-2.3.2}/src/surreal_memory/__init__.py

@@ -16,7 +16,7 @@ from surreal_memory.engine.encoder import EncodingResult, MemoryEncoder
 from surreal_memory.engine.reflex_activation import CoActivation, ReflexActivation
 from surreal_memory.engine.retrieval import DepthLevel, ReflexPipeline, RetrievalResult
 
-__version__ = "2.3.1"
+__version__ = "2.3.2"
 
 __all__ = [
     "__version__",

{surreal_memory-2.3.1 → surreal_memory-2.3.2}/src/surreal_memory/cli/commands/tools.py

@@ -241,6 +241,7 @@ def init(
         setup_config,
         setup_hooks_claude,
         setup_mcp_claude,
+        setup_mcp_claude_desktop,
         setup_mcp_cursor,
         setup_skills,
     )
@@ -280,6 +281,15 @@ def init(
         }
         results["Cursor"] = cursor_labels.get(cursor_status, cursor_status)
 
+        desktop_status = setup_mcp_claude_desktop()
+        desktop_labels = {
+            "added": "claude_desktop_config.json (added MCP server)",
+            "exists": "claude_desktop_config.json (already configured)",
+            "not_found": "not detected (Claude Desktop not installed)",
+            "failed": "failed to write config",
+        }
+        results["Claude Desktop"] = desktop_labels.get(desktop_status, desktop_status)
+
     # 4. Hooks (Claude Code only)
     if not skip_mcp:
         hook_status = setup_hooks_claude()

{surreal_memory-2.3.1 → surreal_memory-2.3.2}/src/surreal_memory/cli/doctor.py

@@ -40,7 +40,9 @@ _CHECK_TIERS: dict[str, str] = {
     "Dependencies": TIER_CORE,
     "Schema version": TIER_CORE,
     "CLI tools": TIER_CORE,
+    "SurrealDB connection": TIER_CORE,
     "Embedding provider": TIER_RECOMMENDED,
+    "MCP env completeness": TIER_RECOMMENDED,
     "MCP configuration": TIER_RECOMMENDED,
     "MCP server": TIER_RECOMMENDED,
     "Hooks": TIER_RECOMMENDED,
@@ -86,6 +88,8 @@ def run_doctor(
     checks.append(_check_surface())
     checks.append(_check_config_freshness())
     checks.append(_check_cli_tools())
+    checks.append(_check_surrealdb_connection())
+    checks.append(_check_mcp_env_completeness())
     checks.append(_check_pro_plugin())
     if dev:
         checks.extend(_check_dev_environment())
@@ -328,6 +332,12 @@ def _check_brain() -> dict[str, Any]:
 
         config = get_config(reload=True)
         brain_name = config.current_brain
+        if config.storage_backend == "surrealdb":
+            return {
+                "name": "Brain database",
+                "status": SKIP,
+                "detail": "surrealdb backend — brain lives in SurrealDB, not a local .db file",
+            }
     except Exception:
         brain_name = "default"
 
@@ -441,6 +451,12 @@ def _check_schema_version() -> dict[str, Any]:
         from surreal_memory.unified_config import get_config, get_surrealmemory_dir
 
         config = get_config(reload=True)
+        if config.storage_backend == "surrealdb":
+            return {
+                "name": "Schema version",
+                "status": SKIP,
+                "detail": "surrealdb backend — schema managed by SurrealDB, not SQLite",
+            }
         brain_name = config.current_brain
         db_path = get_surrealmemory_dir() / "brains" / f"{brain_name}.db"
 
@@ -865,6 +881,8 @@ _FIX_HANDLERS: dict[str, Any] = {
     "Dedup": lambda: _fix_dedup(),
     "Embedding provider": lambda: _fix_embedding(),
     "Config freshness": lambda: _fix_config_freshness(),
+    "MCP env completeness": lambda: _fix_mcp_env(),
+    "SurrealDB connection": lambda: _fix_mcp_env(),
 }
 
 
@@ -958,6 +976,174 @@ def _fix_config_freshness() -> dict[str, Any]:
     }
 
 
+# ---------------------------------------------------------------------------
+# SurrealDB-specific checks
+# ---------------------------------------------------------------------------
+
+
+def _run_surrealdb_ping() -> None:
+    """Attempt a real SurrealDB connection with a short timeout.
+
+    Raises StorageAuthError on bad credentials, any other exception on
+    connectivity issues.  Returns None on success.
+    """
+    import asyncio
+
+    from surreal_memory.storage.surrealdb.connection import SurrealSettings
+    from surreal_memory.storage.surrealdb.store import SurrealDBStorage
+
+    async def _ping() -> None:
+        settings = SurrealSettings.from_env()
+        storage = SurrealDBStorage(
+            url=settings.url,
+            user=settings.user,
+            password=settings.password,
+            namespace=settings.namespace,
+            database=settings.database,
+        )
+        try:
+            await asyncio.wait_for(storage.initialize(), timeout=5)
+        finally:
+            await storage.close()
+
+    run_async(_ping())
+
+
+def _check_surrealdb_connection() -> dict[str, Any]:
+    """Check that the SurrealDB connection works (TIER_CORE for surrealdb backend).
+
+    Returns SKIP when storage backend is not surrealdb.
+    Returns FAIL with actionable hint when authentication fails.
+    Returns WARN when SurrealDB is unreachable (not running, wrong URL, etc.).
+    Returns OK on success.
+    """
+    import os
+
+    from surreal_memory.storage.surrealdb.connection import StorageAuthError
+
+    if os.environ.get("SURREAL_MEMORY_STORAGE") != "surrealdb":
+        try:
+            from surreal_memory.unified_config import get_config
+
+            config = get_config(reload=True)
+            if config.storage_backend != "surrealdb":
+                return {
+                    "name": "SurrealDB connection",
+                    "status": SKIP,
+                    "detail": "surrealdb backend not active",
+                }
+        except Exception as cfg_exc:
+            return {
+                "name": "SurrealDB connection",
+                "status": WARN,
+                "detail": f"could not load config to determine backend: {type(cfg_exc).__name__}",
+                "fix": "Check config.toml is valid; run: smem init",
+            }
+
+    try:
+        _run_surrealdb_ping()
+        return {
+            "name": "SurrealDB connection",
+            "status": OK,
+            "detail": "authenticated and connected",
+        }
+    except StorageAuthError:
+        return {
+            "name": "SurrealDB connection",
+            "status": FAIL,
+            "detail": "authentication failed (wrong password or user)",
+            "fix": "Set SURREALDB_PASS in your MCP client env or run: smem doctor --fix",
+            "fixable": True,
+        }
+    except Exception as exc:
+        return {
+            "name": "SurrealDB connection",
+            "status": WARN,
+            "detail": f"could not reach SurrealDB: {type(exc).__name__}",
+            "fix": "Ensure SurrealDB is running and SURREALDB_URL is correct",
+        }
+
+
+def _check_mcp_env_completeness() -> dict[str, Any]:
+    """Check that MCP entries contain the required env block (TIER_RECOMMENDED).
+
+    Reads ~/.claude.json (Claude Code) and claude_desktop_config.json to verify
+    that the surreal-memory entry has SURREALDB_PASS in its env block.
+    """
+    configs_to_check: list[tuple[str, Path]] = [
+        ("Claude Code (~/.claude.json)", Path.home() / ".claude.json"),
+    ]
+
+    # Also check Claude Desktop config
+    try:
+        from surreal_memory.cli.setup import _claude_desktop_config_path
+
+        desktop_path = _claude_desktop_config_path()
+        if desktop_path is not None:
+            configs_to_check.append(("Claude Desktop", desktop_path))
+    except Exception:
+        pass
+
+    missing_env: list[str] = []
+
+    for label, config_path in configs_to_check:
+        if not config_path.exists():
+            continue
+        try:
+            data = json.loads(config_path.read_text(encoding="utf-8"))
+            entry = data.get("mcpServers", {}).get("surreal-memory")
+            if entry is None:
+                continue
+            if not entry.get("env", {}).get("SURREALDB_PASS"):
+                missing_env.append(label)
+        except (json.JSONDecodeError, OSError):
+            continue
+
+    if not any(p.exists() for _, p in configs_to_check):
+        return {
+            "name": "MCP env completeness",
+            "status": SKIP,
+            "detail": "no MCP client config files found",
+        }
+
+    if missing_env:
+        return {
+            "name": "MCP env completeness",
+            "status": WARN,
+            "detail": f"surreal-memory entry missing env in: {', '.join(missing_env)}",
+            "fix": "Run: smem doctor --fix",
+            "fixable": True,
+        }
+
+    return {
+        "name": "MCP env completeness",
+        "status": OK,
+        "detail": "env block with SURREALDB_PASS present",
+    }
+
+
+def _fix_mcp_env() -> dict[str, Any]:
+    """Auto-fix: backfill env into MCP client configs."""
+    from surreal_memory.cli.setup import setup_mcp_claude, setup_mcp_claude_desktop
+
+    try:
+        setup_mcp_claude()
+        setup_mcp_claude_desktop()
+        return {
+            "name": "MCP env completeness",
+            "status": OK,
+            "detail": "auto-fixed: env backfilled in MCP client configs",
+        }
+    except Exception:
+        pass
+    return {
+        "name": "MCP env completeness",
+        "status": WARN,
+        "detail": "auto-fix failed",
+        "fix": "Run: smem init",
+    }
+
+
 def _render_results(result: dict[str, Any]) -> None:
     """Render diagnostic results to terminal."""
     typer.echo()

{surreal_memory-2.3.1 → surreal_memory-2.3.2}/src/surreal_memory/cli/full_setup.py

@@ -306,6 +306,7 @@ def run_full_setup(
         setup_config,
         setup_hooks_claude,
         setup_mcp_claude,
+        setup_mcp_claude_desktop,
         setup_mcp_cursor,
         setup_skills,
     )
@@ -347,6 +348,15 @@ def run_full_setup(
         }
         results["Cursor"] = cursor_labels.get(cursor_status, cursor_status)
 
+        desktop_status = setup_mcp_claude_desktop()
+        desktop_labels = {
+            "added": "MCP server configured",
+            "exists": "already configured",
+            "not_found": "not detected",
+            "failed": "failed",
+        }
+        results["Claude Desktop"] = desktop_labels.get(desktop_status, desktop_status)
+
     # 4. Hooks
     if not skip_mcp:
         hook_status = setup_hooks_claude()

{surreal_memory-2.3.1 → surreal_memory-2.3.2}/src/surreal_memory/cli/setup.py

@@ -22,16 +22,27 @@ def find_smem_command() -> dict[str, Any]:
     1. smem-mcp entry point (cleanest)
     2. smem CLI with mcp subcommand
     3. python -m fallback (uses absolute path, normalized for Windows)
+
+    Always includes an ``env`` block so MCP clients receive the full
+    SurrealDB connection config and do not start with an empty environment.
     """
+    from surreal_memory.storage.surrealdb.connection import build_mcp_env
+
+    env = build_mcp_env()
+
     smem_mcp = shutil.which("smem-mcp")
     if smem_mcp:
-        return {"command": "smem-mcp"}
+        return {"command": "smem-mcp", "env": env}
 
     smem = shutil.which("smem")
     if smem:
-        return {"command": "smem", "args": ["mcp"]}
+        return {"command": "smem", "args": ["mcp"], "env": env}
 
-    return {"command": _normalize_path(sys.executable), "args": ["-m", "surreal_memory.mcp"]}
+    return {
+        "command": _normalize_path(sys.executable),
+        "args": ["-m", "surreal_memory.mcp"],
+        "env": env,
+    }
 
 
 def setup_config(data_dir: Path, *, force: bool = False) -> bool:
@@ -149,9 +160,13 @@ def setup_mcp_claude() -> str:
     """Auto-configure MCP in Claude Code.
 
     Strategy:
-    1. Use ``claude mcp add --scope user`` CLI if available (official method).
-    2. Fallback: write directly to ``~/.claude.json`` > ``mcpServers``.
-    3. Clean up deprecated ``~/.claude/mcp_servers.json`` (Claude Code ignores it).
+    Always use direct JSON write (``~/.claude.json``) rather than the
+    ``claude mcp add`` CLI path, because the CLI does not support the ``env``
+    block required for SurrealDB credential injection. The JSON write is
+    idempotent and includes the full ``env`` dict.
+
+    If an entry already exists but lacks ``env``, the env block is backfilled
+    so upgraded installations receive the credential config.
 
     Returns status string: "added", "exists", "failed", or "not_found".
     """
@@ -160,23 +175,35 @@ def setup_mcp_claude() -> str:
         return "not_found"
 
     claude_json = claude_dir.parent / ".claude.json"
-
-    # Already registered?
-    if _claude_json_has_server(claude_json, "surreal-memory"):
-        _cleanup_stale_mcp_servers_json()
-        return "exists"
-
-    # Build the command to register
     mcp_entry = find_smem_command()
-    command_args: list[str] = [mcp_entry["command"]]
-    command_args.extend(mcp_entry.get("args", []))
 
-    # Try official CLI first
-    if _add_via_claude_cli("user", command_args):
-        _cleanup_stale_mcp_servers_json()
-        return "added"
+    # Check for existing entry
+    if claude_json.exists():
+        try:
+            raw = claude_json.read_text(encoding="utf-8").strip()
+            if raw:
+                data: dict[str, Any] = json.loads(raw)
+                servers = data.get("mcpServers", {})
+                if "surreal-memory" in servers:
+                    existing = servers["surreal-memory"]
+                    # If env already present and populated → exists
+                    if existing.get("env", {}).get("SURREALDB_PASS"):
+                        _cleanup_stale_mcp_servers_json()
+                        return "exists"
+                    # Backfill env for upgraded installations — backup first
+                    try:
+                        backup = claude_json.with_suffix(".json.bak")
+                        backup.write_bytes(claude_json.read_bytes())
+                    except OSError:
+                        pass
+                    existing["env"] = mcp_entry.get("env", {})
+                    claude_json.write_text(json.dumps(data, indent=2) + "\n", encoding="utf-8")
+                    _cleanup_stale_mcp_servers_json()
+                    return "added"
+        except (json.JSONDecodeError, OSError):
+            pass
 
-    # Fallback: direct JSON write
+    # Write full entry (includes env)
     if _add_via_claude_json(claude_json, mcp_entry):
         _cleanup_stale_mcp_servers_json()
         return "added"
@@ -221,6 +248,80 @@ def setup_mcp_cursor() -> str:
         return "failed"
 
 
+def _claude_desktop_config_path() -> Path | None:
+    """Return the Claude Desktop config file path for the current OS.
+
+    Returns None when the parent directory does not exist (Desktop not installed).
+    """
+    import os
+
+    if sys.platform == "darwin":
+        config_dir = Path.home() / "Library" / "Application Support" / "Claude"
+    elif sys.platform == "win32":
+        appdata = os.environ.get("APPDATA", "")
+        if not appdata:
+            return None
+        config_dir = Path(appdata) / "Claude"
+    else:
+        config_dir = Path.home() / ".config" / "Claude"
+
+    if not config_dir.exists():
+        return None
+    return config_dir / "claude_desktop_config.json"
+
+
+def setup_mcp_claude_desktop() -> str:
+    """Auto-configure MCP in Claude Desktop.
+
+    Writes or updates ``claude_desktop_config.json`` with a ``surreal-memory``
+    entry including the full ``env`` block so the Desktop app never starts the
+    MCP server with an empty environment.
+
+    Idempotent: if the entry already exists and has ``env.SURREALDB_PASS``,
+    returns ``"exists"``.  If the entry exists without ``env``, backfills it
+    and returns ``"added"``.  Creates a ``.bak`` backup before any write.
+
+    Returns status string: ``"added"``, ``"exists"``, ``"failed"``,
+    or ``"not_found"`` (Desktop not installed).
+    """
+    config_path = _claude_desktop_config_path()
+    if config_path is None:
+        return "not_found"
+
+    mcp_entry = find_smem_command()
+
+    existing: dict[str, Any] = {}
+    if config_path.exists():
+        try:
+            raw = config_path.read_text(encoding="utf-8").strip()
+            if raw:
+                existing = json.loads(raw)
+        except (json.JSONDecodeError, OSError):
+            existing = {}
+
+        servers = existing.get("mcpServers", {})
+        if "surreal-memory" in servers:
+            current = servers["surreal-memory"]
+            if current.get("env", {}).get("SURREALDB_PASS"):
+                return "exists"
+            # Backfill env for upgraded installations — fall through to write
+
+        # Backup before modifying
+        try:
+            backup = config_path.with_suffix(".json.bak")
+            backup.write_bytes(config_path.read_bytes())
+        except OSError:
+            pass
+
+    try:
+        servers = existing.setdefault("mcpServers", {})
+        servers["surreal-memory"] = mcp_entry
+        config_path.write_text(json.dumps(existing, indent=2) + "\n", encoding="utf-8")
+        return "added"
+    except OSError:
+        return "failed"
+
+
 def _normalize_path(path: str) -> str:
     """Normalize a filesystem path for use in shell commands.
 

{surreal_memory-2.3.1 → surreal_memory-2.3.2}/src/surreal_memory/cli/wizard.py

@@ -16,6 +16,7 @@ from surreal_memory.cli.setup import (
     setup_config,
     setup_hooks_claude,
     setup_mcp_claude,
+    setup_mcp_claude_desktop,
     setup_mcp_cursor,
     setup_skills,
 )
@@ -91,6 +92,9 @@ def run_wizard(*, force: bool = False) -> None:
     cursor_status = setup_mcp_cursor()
     _format_mcp_result(results, "Cursor", cursor_status)
 
+    desktop_status = setup_mcp_claude_desktop()
+    _format_mcp_result(results, "Claude Desktop", desktop_status)
+
     # Step 5: Hooks
     hook_status = setup_hooks_claude()
     hook_labels = {

{surreal_memory-2.3.1 → surreal_memory-2.3.2}/src/surreal_memory/mcp/server.py

@@ -55,6 +55,7 @@ from surreal_memory.mcp.train_handler import TrainHandler
 from surreal_memory.mcp.version_check_handler import VersionCheckHandler
 from surreal_memory.mcp.visualize_handler import VisualizeHandler
 from surreal_memory.mcp.watch_handler import WatchHandler
+from surreal_memory.storage.surrealdb.connection import StorageAuthError
 from surreal_memory.unified_config import get_config, get_shared_storage
 
 if TYPE_CHECKING:
@@ -492,6 +493,17 @@ async def handle_message(server: MCPServer, message: dict[str, Any]) -> dict[str
                     "message": f"Tool '{tool_name}' timed out after {_TOOL_CALL_TIMEOUT}s",
                 },
             }
+        except StorageAuthError as exc:
+            logger.error("Tool '%s' failed: SurrealDB auth error", tool_name)
+            try:
+                await _record_tool_event(server, tool_name, tool_args, t0, success=False)
+            except Exception:
+                logger.debug("Tool event recording failed", exc_info=True)
+            return {
+                "jsonrpc": "2.0",
+                "id": msg_id,
+                "error": {"code": -32001, "message": str(exc)},
+            }
         except Exception:
             logger.error("Tool '%s' raised an exception", tool_name, exc_info=True)
             try:

surreal_memory-2.3.2/src/surreal_memory/storage/surrealdb/connection.py

@@ -0,0 +1,120 @@
+"""SurrealDB connection settings and auth error types.
+
+Single source of truth for:
+- Default connection parameters (URL, user, password, namespace, database)
+- Credential-error detection (distinct from 401 token-expiry errors)
+- MCP env dict generation for client config backfill
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+
+DEFAULT_URL = "http://localhost:8001"
+DEFAULT_USER = "root"
+DEFAULT_PASS = "surrealmemory"  # noqa: S105
+
+AUTH_HINT = (
+    "The MCP server env is likely empty or missing SURREALDB_PASS, so it fell back to the "
+    "default password. Set SURREALDB_PASS (and SURREALDB_URL/USER) in your MCP client config "
+    "(Claude Code: ~/.claude.json; Claude Desktop: claude_desktop_config.json) or run "
+    "`smem doctor --fix`."
+)
+DEFAULT_NS = "surreal_memory"
+DEFAULT_DB = "default"
+
+
+@dataclass(frozen=True)
+class SurrealSettings:
+    """Immutable SurrealDB connection settings resolved from environment."""
+
+    url: str
+    user: str
+    password: str
+    namespace: str
+    database: str
+
+    @classmethod
+    def from_env(cls) -> SurrealSettings:
+        """Build settings from environment variables, falling back to defaults."""
+        return cls(
+            url=os.getenv("SURREALDB_URL", DEFAULT_URL),
+            user=os.getenv("SURREALDB_USER", DEFAULT_USER),
+            password=os.getenv("SURREALDB_PASS", DEFAULT_PASS),
+            namespace=os.getenv("SURREALDB_NS", DEFAULT_NS),
+            database=os.getenv("SURREALDB_DB", DEFAULT_DB),
+        )
+
+
+class StorageAuthError(Exception):
+    """Raised when SurrealDB rejects credentials (wrong password / user).
+
+    Distinct from token-expiry 401 errors handled by _is_auth_error in store.py.
+    Carries an actionable hint so MCP clients surface the root cause instead of
+    a generic -32000 failure.
+    """
+
+    def __init__(self, message: str, hint: str = "") -> None:
+        super().__init__(message)
+        self.hint = hint
+
+    def __str__(self) -> str:
+        base = super().__str__()
+        return f"{base} {self.hint}".strip()
+
+
+def is_credential_error(exc: Exception) -> bool:
+    """True if *exc* signals bad credentials (wrong password / user not allowed).
+
+    Distinct from _is_auth_error (token-expiry 401) in store.py — do NOT merge.
+    Detects NotAllowedError from surrealdb SDK by three means (in order):
+      1. isinstance check when the SDK is importable
+      2. class-name match (works when import is not available)
+      3. string content match as last resort
+
+    Returns False for 401 token-expiry errors so the reconnect loop is not
+    triggered on a bad password.
+    """
+    # Try real isinstance first — guard against MagicMock stubs in tests.
+    try:
+        from surrealdb.errors import NotAllowedError  # type: ignore[import-untyped,unused-ignore]
+
+        if isinstance(NotAllowedError, type) and isinstance(exc, NotAllowedError):
+            return True
+    except (ImportError, ModuleNotFoundError, TypeError):
+        pass
+
+    # Class-name fallback (SDK installed but import path changed)
+    if type(exc).__name__ == "NotAllowedError":
+        return True
+
+    # String-content fallback — match auth-specific phrases only.
+    # "not allowed" alone is too broad (SurrealDB reuses it for permission errors
+    # on tables/operations); require an auth-context indicator alongside it.
+    msg = str(exc).lower()
+    if "problem with authentication" in msg:
+        return True
+    if "not allowed" in msg and any(
+        kw in msg for kw in ("signin", "authenticate", "credentials", "login", "password")
+    ):
+        return True
+
+    return False
+
+
+def build_mcp_env() -> dict[str, str]:
+    """Return an env dict suitable for embedding in MCP client configs.
+
+    Reads actual env / .env values so a developer's local overrides are
+    preserved; falls back to defaults so clean installs get a working config.
+    """
+    s = SurrealSettings.from_env()
+    return {
+        "SURREAL_MEMORY_STORAGE": "surrealdb",
+        "SURREALDB_URL": s.url,
+        "SURREALDB_USER": s.user,
+        "SURREALDB_PASS": s.password,
+        "SURREALDB_NS": s.namespace,
+        "SURREALDB_DB": s.database,
+    }