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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: surreal-memory
-Version: 2.3.0
+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.0 → surreal_memory-2.3.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "surreal-memory"
-version = "2.3.0"
+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.0 → 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.0"
+__version__ = "2.3.2"
 
 __all__ = [
     "__version__",

{surreal_memory-2.3.0 → 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.0 → 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.0 → 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.0 → 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.0 → 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.0 → surreal_memory-2.3.2}/src/surreal_memory/engine/diagnostics.py

@@ -299,6 +299,16 @@ class DiagnosticsEngine:
         Returns:
             BrainHealthReport with scores, warnings, and recommendations
         """
+        # Pin storage to the analyzed brain before any brain-scoped reads.
+        # The SurrealDB backend uses a single shared storage singleton with a
+        # mutable current-brain pointer; without this, a concurrent multi-brain
+        # dashboard call (e.g. /stats analyzing both brains) leaves the pointer
+        # on a different brain, and get_all_synapses()/get_fibers() then return
+        # the WRONG brain's data — producing a false orphan rate. Harmless on
+        # backends that scope storage per brain (e.g. SQLite per-file).
+        if hasattr(self._storage, "set_brain"):
+            self._storage.set_brain(brain_id)
+
         # Gather base data
         enhanced = await self._storage.get_enhanced_stats(brain_id)
         neuron_count: int = enhanced.get("neuron_count", 0)

{surreal_memory-2.3.0 → 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.0 → surreal_memory-2.3.2}/src/surreal_memory/server/routes/dashboard_api.py

@@ -2,7 +2,6 @@
 
 from __future__ import annotations
 
-import asyncio
 import logging
 from pathlib import Path
 from typing import Annotated, Any
@@ -130,7 +129,12 @@ async def get_stats() -> DashboardStats:
             logger.warning("Brain analysis failed for %s", name, exc_info=True)
             return BrainSummary(id=name, name=name, is_active=name == active_name)
 
-    brains = list(await asyncio.gather(*[_analyze_brain(name) for name in brain_names]))
+    # Analyze brains sequentially, NOT via asyncio.gather: the SurrealDB backend
+    # shares one storage singleton with a mutable current-brain pointer, so
+    # concurrent per-brain analysis races and corrupts orphan/synapse reads
+    # (each _analyze_brain repins the shared pointer). Sequential keeps each
+    # brain's reads consistent. Brain count is tiny, so latency is negligible.
+    brains = [await _analyze_brain(name) for name in brain_names]
 
     total_n = sum(b.neuron_count for b in brains)
     total_s = sum(b.synapse_count for b in brains)
@@ -192,7 +196,15 @@ async def get_tier_stats(
     summary="List all brains",
 )
 async def list_brains_api() -> list[BrainSummary]:
-    """List all available brains with summary stats."""
+    """List all available brains with summary stats, including health grade.
+
+    Previously this endpoint left grade/purity at their model defaults (F / 0.0)
+    because it never ran diagnostics, so the dashboard's Brains table showed
+    every brain as grade F while the stats cards (which DO run diagnostics)
+    showed the real grade — the F-vs-D mismatch. Run diagnostics per brain here
+    too, sequentially (the SurrealDB backend shares one storage singleton with a
+    mutable brain pointer, so concurrent analysis would race).
+    """
     from surreal_memory.unified_config import (
         get_config,
         get_shared_storage,
@@ -208,6 +220,16 @@ async def list_brains_api() -> list[BrainSummary]:
         try:
             brain_storage = await get_shared_storage(brain_name=name)
             stats = await brain_storage.get_stats(name)
+            grade = "F"
+            purity = 0.0
+            try:
+                from surreal_memory.engine.diagnostics import DiagnosticsEngine
+
+                report = await DiagnosticsEngine(brain_storage).analyze(name)
+                grade = report.grade
+                purity = report.purity_score
+            except Exception:
+                logger.debug("Diagnostics failed for brain %s", name, exc_info=True)
             results.append(
                 BrainSummary(
                     id=name,
@@ -215,11 +237,13 @@ async def list_brains_api() -> list[BrainSummary]:
                     neuron_count=stats.get("neuron_count", 0),
                     synapse_count=stats.get("synapse_count", 0),
                     fiber_count=stats.get("fiber_count", 0),
+                    grade=grade,
+                    purity_score=purity,
                     is_active=name == active_name,
                 )
             )
         except Exception:
-            logger.debug("Failed to get stats for brain %s", name, exc_info=True)
+            logger.warning("Brain summary failed for %s", name, exc_info=True)
             results.append(BrainSummary(id=name, name=name, is_active=name == active_name))
 
     return results