memleaf 0.2.23__tar.gz → 0.2.24__tar.gz

{memleaf-0.2.23 → memleaf-0.2.24}/CHANGELOG.md

@@ -2,6 +2,15 @@
 
 All notable changes to memleaf are documented here.
 
+## 0.2.24 — 2026-09-04
+
+- Make Hermes MCP installation reliably persistent: write `mcp_servers.memleaf` through Hermes' canonical `config set` interface, disable the entry while command/arguments are updated, then read `config.yaml` back and require an exact command plus `--vault` match before reporting success.
+- Detect a same-Vault MCP entry that points at a different absolute memleaf runtime before changing Hermes. Add explicit `--mcp-runtime auto|current|existing` policies, prefer the current Python interpreter's scripts directory over `PATH`, and require an exact version check before retaining another environment.
+- Snapshot Hermes `config.yaml`, `memleaf.json`, and `plugins/memleaf` during installation; on a later failure, attempt every rollback target even when one restore fails, and report the failed paths together with the installation stage and recovery commands.
+- Improve human and JSON diagnostics for MCP persistence, runtime conflicts, lifecycle/test failures, and rollback results; document `memleaf-mcp --vault`, manual YAML, and the difference between Hermes connection discovery and final configuration persistence.
+- Make Windows CI fail immediately after every native command and keep POSIX command-rendering assertions platform-specific, preventing intermediate Windows test failures from being reported as green.
+- Leave memory extraction, CREATE/UPDATE/NO_CHANGE decisions, retrieval, injection, todo handling, and globally shared Vault visibility unchanged.
+
 ## 0.2.23 — 2026-09-03
 
 - Add a strict `scope_correction` transaction for explicit cross-project corrections without weakening ordinary UPDATE scope isolation: uniquely recover the wrong active target, reuse its `memory_id` when appropriate, or retire it to history with `invalidated_reason: scope_correction` and `superseded_by` when a correct active survivor already exists.

{memleaf-0.2.23/src/memleaf.egg-info → memleaf-0.2.24}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: memleaf
-Version: 0.2.23
+Version: 0.2.24
 Summary: A local-first Markdown memory core for AI agents
 Author: memleaf contributors
 License-Expression: MIT
@@ -23,8 +23,8 @@ Dynamic: license-file
 
 [English](README.en.md) · [PyPI](https://pypi.org/project/memleaf/) · [GitHub](https://github.com/miffyblueboo/memleaf)
 
-> **当前版本：0.2.23。**
-> 核心库、Vault、stdio MCP Server、初始化 CLI、模型路由、提炼流程、受控检索协议和宿主适配器已经实现。memleaf 0.2.23 通过 PyPI 分发。
+> **当前版本：0.2.24。**
+> 核心库、Vault、stdio MCP Server、初始化 CLI、模型路由、提炼流程、受控检索协议和宿主适配器已经实现。memleaf 0.2.24 通过 PyPI 分发。
 > **当前版本支持 Hermes 和 Codex。** Antigravity（反重力）不检测、不安装、不配置。
 
 ## 项目定位

{memleaf-0.2.23 → memleaf-0.2.24}/README.en.md

@@ -4,8 +4,8 @@
 
 [中文](README.md) · [PyPI](https://pypi.org/project/memleaf/) · [GitHub](https://github.com/miffyblueboo/memleaf)
 
-> **Version: 0.2.23.**
-> The core library, Vault, stdio MCP server, initialization CLI, model routing, memory extraction, controlled retrieval protocol, and host adapters are implemented. memleaf 0.2.23 is distributed through PyPI.
+> **Version: 0.2.24.**
+> The core library, Vault, stdio MCP server, initialization CLI, model routing, memory extraction, controlled retrieval protocol, and host adapters are implemented. memleaf 0.2.24 is distributed through PyPI.
 > **The current release supports Hermes and Codex.** Antigravity is not detected, installed, or configured.
 
 ## Project scope

{memleaf-0.2.23 → memleaf-0.2.24}/README.md

@@ -4,8 +4,8 @@
 
 [English](README.en.md) · [PyPI](https://pypi.org/project/memleaf/) · [GitHub](https://github.com/miffyblueboo/memleaf)
 
-> **当前版本：0.2.23。**
-> 核心库、Vault、stdio MCP Server、初始化 CLI、模型路由、提炼流程、受控检索协议和宿主适配器已经实现。memleaf 0.2.23 通过 PyPI 分发。
+> **当前版本：0.2.24。**
+> 核心库、Vault、stdio MCP Server、初始化 CLI、模型路由、提炼流程、受控检索协议和宿主适配器已经实现。memleaf 0.2.24 通过 PyPI 分发。
 > **当前版本支持 Hermes 和 Codex。** Antigravity（反重力）不检测、不安装、不配置。
 
 ## 项目定位

{memleaf-0.2.23 → memleaf-0.2.24}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "memleaf"
-version = "0.2.23"
+version = "0.2.24"
 description = "A local-first Markdown memory core for AI agents"
 readme = "README.md"
 requires-python = ">=3.11"

{memleaf-0.2.23 → memleaf-0.2.24}/src/memleaf/__init__.py

@@ -1,6 +1,6 @@
 """Local-first Markdown memory core for AI agents."""
 
-__version__ = "0.2.23"
+__version__ = "0.2.24"
 
 from .config import DEFAULT_CONFIG, default_config, load_config, save_config
 from .frontmatter import FrontmatterError, dump_frontmatter, dump_yaml, load_yaml, parse_frontmatter

{memleaf-0.2.23 → memleaf-0.2.24}/src/memleaf/cli.py

@@ -6,6 +6,8 @@ import argparse
 import getpass
 import json
 import os
+import shlex
+import subprocess
 import sys
 from pathlib import Path
 from typing import Sequence
@@ -65,6 +67,15 @@ def build_parser() -> argparse.ArgumentParser:
         help="host to configure (default: hermes)",
     )
     install.add_argument("--vault", type=Path, default=None, help="vault directory")
+    install.add_argument(
+        "--mcp-runtime",
+        choices=("auto", "current", "existing"),
+        default="auto",
+        help=(
+            "Hermes only: fail on a second memleaf runtime (auto), migrate to "
+            "this installation (current), or retain a version-matched configured runtime (existing)"
+        ),
+    )
     install.add_argument("--json", action="store_true", help="emit one JSON result")
     host_event = commands.add_parser(
         "host-event",
@@ -87,6 +98,96 @@ def _configure_stdio_utf8() -> None:
             continue
 
 
+def _format_command(command: Sequence[object]) -> str:
+    values = [str(item) for item in command]
+    return subprocess.list2cmdline(values) if os.name == "nt" else shlex.join(values)
+
+
+def _print_install_failure(output: dict, *, host: str) -> None:
+    print(
+        f"memleaf install failed: {output.get('reason', 'unknown error')}",
+        file=sys.stderr,
+    )
+    stage = output.get("stage")
+    if isinstance(stage, str) and stage:
+        print(f"failed stage: {stage}", file=sys.stderr)
+
+    if host == "hermes" and output.get("core_version") is not None:
+        provider_version = output.get("provider_version")
+        if output.get("provider_updated"):
+            provider_text = provider_version or "unknown"
+        elif provider_version:
+            provider_text = f"not changed (rejected candidate {provider_version})"
+        else:
+            provider_text = "not changed"
+        print(
+            "memleaf versions: "
+            f"core={output.get('core_version') or 'unknown'}, "
+            f"Hermes provider={provider_text}",
+            file=sys.stderr,
+        )
+
+    runtime = output.get("mcp_runtime")
+    if isinstance(runtime, dict):
+        config_path = runtime.get("config_path")
+        configured = runtime.get("configured_command")
+        current = runtime.get("current_command") or runtime.get("expected_command")
+        existing_version = runtime.get("existing_version")
+        if config_path:
+            print(f"Hermes config: {config_path}", file=sys.stderr)
+        if configured:
+            print(f"configured MCP runtime: {configured}", file=sys.stderr)
+        if current:
+            print(f"current memleaf runtime: {current}", file=sys.stderr)
+        if existing_version:
+            print(f"configured MCP version: {existing_version}", file=sys.stderr)
+
+    mcp = output.get("mcp")
+    if isinstance(mcp, dict):
+        mcp_reason = mcp.get("reason")
+        if isinstance(mcp_reason, str) and mcp_reason and mcp_reason != output.get("reason"):
+            print(f"MCP detail: {mcp_reason}", file=sys.stderr)
+        config_path = mcp.get("config_path")
+        if config_path and not (
+            isinstance(runtime, dict) and config_path == runtime.get("config_path")
+        ):
+            print(f"Hermes config: {config_path}", file=sys.stderr)
+        backup_path = mcp.get("backup_path")
+        if backup_path:
+            print(f"config backup: {backup_path}", file=sys.stderr)
+
+    rollback = output.get("rollback_status")
+    if rollback == "completed":
+        print("Hermes configuration was restored to its pre-install state.", file=sys.stderr)
+    elif rollback == "failed":
+        print(
+            "WARNING: automatic rollback failed; inspect the reported Hermes paths before restarting.",
+            file=sys.stderr,
+        )
+
+    user_action = output.get("user_action")
+    if output.get("user_action_required") and isinstance(user_action, str) and user_action:
+        print(f"action required: {user_action}", file=sys.stderr)
+
+    commands = output.get("recovery_commands")
+    if isinstance(commands, list) and commands:
+        print("recovery commands:", file=sys.stderr)
+        for command in commands:
+            if isinstance(command, list) and command:
+                print(f"  {_format_command(command)}", file=sys.stderr)
+
+    diagnostic = ["python", "-m", "memleaf", "install", "--host", host]
+    if host == "hermes" and isinstance(runtime, dict):
+        policy = runtime.get("policy")
+        if policy in {"current", "existing"}:
+            diagnostic.extend(["--mcp-runtime", policy])
+    diagnostic.append("--json")
+    print(
+        f"Run `{_format_command(diagnostic)}` for the complete diagnostic result.",
+        file=sys.stderr,
+    )
+
+
 def main(argv: Sequence[str] | None = None) -> int:
     _configure_stdio_utf8()
     parser = build_parser()
@@ -96,8 +197,22 @@ def main(argv: Sequence[str] | None = None) -> int:
             output = _init(args)
         elif args.command == "install":
             from .installer import install_codex, install_hermes
-            installer = install_codex if args.host == "codex" else install_hermes
-            output = installer(vault_path=args.vault)
+
+            if args.host == "codex":
+                if args.mcp_runtime != "auto":
+                    output = {
+                        "status": "failure",
+                        "stage": "arguments",
+                        "reason": "--mcp-runtime applies only to Hermes installations",
+                        "vault": str(args.vault) if args.vault is not None else None,
+                    }
+                else:
+                    output = install_codex(vault_path=args.vault)
+            else:
+                install_kwargs = {"vault_path": args.vault}
+                if args.mcp_runtime != "auto":
+                    install_kwargs["mcp_runtime"] = args.mcp_runtime
+                output = install_hermes(**install_kwargs)
         elif args.command == "host-event":
             output = _host_event(args)
         else:  # pragma: no cover - argparse requires a known subcommand.
@@ -116,7 +231,8 @@ def main(argv: Sequence[str] | None = None) -> int:
         if getattr(args, "json", False):
             print(json.dumps({"error": "initialization failed"}, ensure_ascii=False))
         else:
-            print("memleaf init failed", file=sys.stderr)
+            action = getattr(args, "command", "init")
+            print(f"memleaf {action} failed unexpectedly", file=sys.stderr)
         return 1
 
     if args.command == "host-event":
@@ -139,22 +255,16 @@ def main(argv: Sequence[str] | None = None) -> int:
             if output.get("vault_source") == "hermes_config":
                 print("Preserved the Vault from the existing Hermes memleaf configuration.")
             if args.host == "hermes":
+                runtime = output.get("mcp_runtime")
+                if isinstance(runtime, dict) and runtime.get("selected_command"):
+                    print(f"Hermes MCP runtime: {runtime['selected_command']}")
                 print("Restart Hermes to use memleaf.")
             elif output.get("user_action_required"):
                 print(f"Codex action required: {output.get('user_action')}")
             if output.get("model", {}).get("status") == "not_configured":
                 print("Configure a memleaf model route before using automatic processing.")
         else:
-            if args.host == "hermes" and (
-                output.get("core_version") is not None
-                or output.get("provider_version") is not None
-            ):
-                print(
-                    "memleaf versions: "
-                    f"core={output.get('core_version') or 'unknown'}, "
-                    f"Hermes provider={output.get('provider_version') or 'unknown'}"
-                )
-            print(f"memleaf install failed: {output.get('reason', 'unknown error')}", file=sys.stderr)
+            _print_install_failure(output, host=args.host)
         return 0 if output.get("status") in {"configured", "already_configured"} else 2
     if args.json:
         print(json.dumps(output, ensure_ascii=False, sort_keys=True))
@@ -309,7 +419,7 @@ def _prepare_model_route(
     candidate = discovery.selected
     diagnostics = list(discovery.diagnostics)
     if candidate is None:
-        # An existing direct route is a safe idempotency fallback.  It is not
+        # An existing direct route is a safe idempotency fallback. It is not
         # reported as a host discovery result and never appears with its key.
         candidate = _existing_memleaf_route(requested_vault / "config.yaml")
     if candidate is None and not dry_run and not non_interactive and sys.stdin.isatty():

{memleaf-0.2.23 → memleaf-0.2.24}/src/memleaf/hermes_provider/README.md

@@ -1,8 +1,8 @@
 # Memleaf memory provider for Hermes
 
 This is a Hermes user-level memory-provider plugin for the local memleaf vault.
-It is separate from the `memleaf-mcp` MCP server, but uses the same
-`~/.memleaf` directory and executable.
+It is separate from the `memleaf-mcp` MCP server, but uses the same Vault and
+must use a version-compatible memleaf runtime.
 
 The native provider supplies a bounded Scope Map (no memory titles or bodies),
 captures visible Hermes turns, and automatically processes complete turns.
@@ -28,12 +28,36 @@ The optional provider config is `~/.hermes/memleaf.json`:
 ```json
 {
   "vault": "~/.memleaf",
-  "command": "memleaf-mcp",
+  "command": "/absolute/path/to/memleaf-mcp",
   "timeout": 5,
-  "process_timeout": 300
+  "process_timeout": 300,
+  "auto_process": true
 }
 ```
 
+The separate persisted MCP entry uses the same executable and Vault:
+
+```yaml
+mcp_servers:
+  memleaf:
+    command: /absolute/path/to/memleaf-mcp
+    args:
+      - --vault
+      - /absolute/path/to/vault
+    enabled: true
+    lazy: true
+    idle_timeout_seconds: 60
+```
+
+Use `python -m memleaf install` to configure both entries. The installer writes
+the MCP entry through `hermes config set`, reads `config.yaml` back, and tests
+that all 12 tools are discoverable before it reports success. When two memleaf
+virtual environments are present, use `--mcp-runtime current` to migrate to the
+runtime executing the installer or `--mcp-runtime existing` to retain an
+already configured executable after an exact version check. See the
+[Hermes MCP runtime guide](https://github.com/miffyblueboo/memleaf/blob/main/docs/hermes-mcp-runtime.md)
+for the full multi-environment and manual-recovery procedure.
+
 Capture, stats, and context calls use the short `timeout`; model-backed
 processing uses `process_timeout` so a slow local model does not get mistaken
 for a dead MCP worker. A failed or timed-out request closes the MCP process;

{memleaf-0.2.23 → memleaf-0.2.24}/src/memleaf/hermes_provider/plugin.yaml

@@ -1,5 +1,5 @@
 name: memleaf
-version: 0.2.23
+version: 0.2.24
 description: "Hermes-native external MemoryProvider for local-first Markdown memory shared with the memleaf MCP server."
 hooks:
   - prefetch

memleaf-0.2.24/src/memleaf/hermes_runtime.py

@@ -0,0 +1,349 @@
+"""Read-only inspection of Hermes' persisted memleaf MCP runtime.
+
+The installer uses this module before mutating Hermes so an existing MCP entry
+that points at a different virtual environment cannot be silently combined with
+a newly installed MemoryProvider. The parser deliberately reuses the adapter's
+small JSON/YAML reader and never executes a command discovered in user config.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+import json
+import ntpath
+import os
+from pathlib import Path
+from typing import Any, Mapping, Sequence
+
+from .adapters.hermes import _parse_json_or_yaml_mcp
+
+
+_MEMLEAF_COMMAND_NAMES = frozenset({"memleaf-mcp", "memleaf-mcp.exe"})
+_TRUE_VALUES = frozenset({"true", "1", "yes", "on"})
+_FALSE_VALUES = frozenset({"false", "0", "no", "off"})
+
+
+@dataclass(frozen=True)
+class HermesMcpInspection:
+    """Safe, serializable description of one Hermes memleaf MCP entry."""
+
+    status: str
+    reason: str
+    config_path: str
+    expected_command: str
+    configured_command: str | None = None
+    configured_vault: str | None = None
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "status": self.status,
+            "reason": self.reason,
+            "config_path": self.config_path,
+            "expected_command": self.expected_command,
+            "configured_command": self.configured_command,
+            "configured_vault": self.configured_vault,
+        }
+
+
+def _platform_name(platform: str | None) -> str:
+    return os.name if platform is None else platform
+
+
+def _path_text(value: Path | str) -> str:
+    return os.path.expandvars(os.path.expanduser(str(value).strip()))
+
+
+def _host_path_key(value: Path | str, *, platform: str | None = None) -> str:
+    """Normalize a host path without pretending a foreign path is local."""
+
+    text = _path_text(value)
+    if _platform_name(platform) == "nt":
+        return ntpath.normcase(ntpath.normpath(text.replace("/", "\\")))
+    return os.path.normcase(str(Path(text).expanduser().resolve(strict=False)))
+
+
+def host_paths_equivalent(
+    left: Path | str,
+    right: Path | str,
+    *,
+    platform: str | None = None,
+) -> bool:
+    """Return whether two paths identify the same location on the host."""
+
+    effective_platform = _platform_name(platform)
+    if effective_platform == os.name:
+        try:
+            left_path = Path(left).expanduser()
+            right_path = Path(right).expanduser()
+            if left_path.exists() and right_path.exists():
+                return os.path.samefile(left_path, right_path)
+        except (OSError, TypeError, ValueError):
+            pass
+    try:
+        return _host_path_key(left, platform=effective_platform) == _host_path_key(
+            right, platform=effective_platform
+        )
+    except (OSError, TypeError, ValueError):
+        return False
+
+
+def _command_basename(command: str, *, platform: str | None = None) -> str:
+    text = command.strip()
+    if _platform_name(platform) == "nt":
+        return ntpath.basename(text.replace("/", "\\")).casefold()
+    return Path(text).name.casefold()
+
+
+def is_absolute_memleaf_command(
+    command: str,
+    *,
+    platform: str | None = None,
+) -> bool:
+    """Return whether ``command`` is an absolute memleaf-mcp executable path."""
+
+    if not isinstance(command, str) or not command.strip():
+        return False
+    text = _path_text(command)
+    if _command_basename(text, platform=platform) not in _MEMLEAF_COMMAND_NAMES:
+        return False
+    if _platform_name(platform) == "nt":
+        return ntpath.isabs(text.replace("/", "\\"))
+    return Path(text).is_absolute()
+
+
+def _is_bare_memleaf_command(command: str, *, platform: str | None = None) -> bool:
+    text = command.strip()
+    return (
+        _command_basename(text, platform=platform) in _MEMLEAF_COMMAND_NAMES
+        and not is_absolute_memleaf_command(text, platform=platform)
+        and "/" not in text
+        and "\\" not in text
+    )
+
+
+def _boolish_enabled(value: Any) -> bool | None:
+    if value is None:
+        return True
+    if isinstance(value, bool):
+        return value
+    if isinstance(value, str):
+        normalized = value.strip().casefold()
+        if normalized in _TRUE_VALUES:
+            return True
+        if normalized in _FALSE_VALUES:
+            return False
+    return None
+
+
+def _vault_from_args(args: Any) -> str | None:
+    if not isinstance(args, Sequence) or isinstance(args, (str, bytes, bytearray)):
+        return None
+    values = [str(item) for item in args]
+    if len(values) == 2 and values[0] == "--vault" and values[1].strip():
+        return values[1].strip()
+    if len(values) == 1 and values[0].startswith("--vault="):
+        value = values[0].split("=", 1)[1].strip()
+        return value or None
+    return None
+
+
+def _result(
+    status: str,
+    reason: str,
+    *,
+    config_path: Path,
+    expected_command: Path | str,
+    configured_command: str | None = None,
+    configured_vault: str | None = None,
+) -> HermesMcpInspection:
+    return HermesMcpInspection(
+        status=status,
+        reason=reason,
+        config_path=str(config_path),
+        expected_command=str(expected_command),
+        configured_command=configured_command,
+        configured_vault=configured_vault,
+    )
+
+
+def inspect_hermes_mcp(
+    config_path: Path | str,
+    vault: Path | str,
+    expected_command: Path | str,
+    *,
+    platform: str | None = None,
+) -> HermesMcpInspection:
+    """Inspect ``mcp_servers.memleaf`` without executing configured commands.
+
+    Status values are:
+
+    ``absent``
+        No memleaf entry exists.
+    ``correct``
+        The entry uses the requested Vault and the same executable.
+    ``legacy``
+        The entry uses the requested Vault and a bare ``memleaf-mcp`` command;
+        it is safe for the installer to canonicalize to an absolute path.
+    ``runtime_conflict``
+        The Vault matches, but an absolute memleaf executable from a different
+        environment is configured. The installer must require an explicit
+        runtime policy before changing either side.
+    ``conflict``
+        The entry is disabled, points at another Vault, has invalid arguments,
+        or names a non-memleaf command.
+    ``unknown``
+        The configuration cannot be read safely.
+    """
+
+    path = Path(config_path)
+    if path.is_symlink():
+        return _result(
+            "unknown",
+            "Hermes config is a symlink; refusing automatic access",
+            config_path=path,
+            expected_command=expected_command,
+        )
+    if path.exists() and not path.is_file():
+        return _result(
+            "unknown",
+            "Hermes config is not a regular file",
+            config_path=path,
+            expected_command=expected_command,
+        )
+    if not path.exists():
+        return _result(
+            "absent",
+            "no persisted memleaf MCP entry was found",
+            config_path=path,
+            expected_command=expected_command,
+        )
+
+    try:
+        text = path.read_text(encoding="utf-8")
+    except (OSError, UnicodeError):
+        text = ""
+        parsed = None
+    else:
+        parsed = _parse_json_or_yaml_mcp(text)
+        # The adapter's compact parser historically returns None for a valid
+        # JSON object that simply has no mcp_servers key. Treat that shape as
+        # an absent entry, while retaining fail-closed behavior for malformed
+        # or type-invalid configuration.
+        if parsed is None:
+            try:
+                root = json.loads(text)
+            except (TypeError, ValueError):
+                root = None
+            if isinstance(root, Mapping) and root.get("mcp_servers") in (None, {}):
+                parsed = {}
+    if parsed is None:
+        return _result(
+            "unknown",
+            "Hermes config could not be parsed safely",
+            config_path=path,
+            expected_command=expected_command,
+        )
+
+    entry = parsed.get("memleaf")
+    if entry is None:
+        return _result(
+            "absent",
+            "no persisted memleaf MCP entry was found",
+            config_path=path,
+            expected_command=expected_command,
+        )
+    if not isinstance(entry, Mapping):
+        return _result(
+            "conflict",
+            "mcp_servers.memleaf is not an object",
+            config_path=path,
+            expected_command=expected_command,
+        )
+
+    enabled = _boolish_enabled(entry.get("enabled"))
+    command_value = entry.get("command")
+    command = command_value.strip() if isinstance(command_value, str) else None
+    configured_vault = _vault_from_args(entry.get("args"))
+
+    if enabled is not True:
+        reason = (
+            "the existing memleaf MCP entry is disabled"
+            if enabled is False
+            else "the existing memleaf MCP enabled value is invalid"
+        )
+        return _result(
+            "conflict",
+            reason,
+            config_path=path,
+            expected_command=expected_command,
+            configured_command=command,
+            configured_vault=configured_vault,
+        )
+    if not command:
+        return _result(
+            "conflict",
+            "the existing memleaf MCP command is missing or invalid",
+            config_path=path,
+            expected_command=expected_command,
+            configured_vault=configured_vault,
+        )
+    if configured_vault is None:
+        return _result(
+            "conflict",
+            "the existing memleaf MCP args must contain exactly one --vault path",
+            config_path=path,
+            expected_command=expected_command,
+            configured_command=command,
+        )
+    if not host_paths_equivalent(configured_vault, vault, platform=platform):
+        return _result(
+            "conflict",
+            "the existing memleaf MCP entry points at a different Vault",
+            config_path=path,
+            expected_command=expected_command,
+            configured_command=command,
+            configured_vault=configured_vault,
+        )
+    if host_paths_equivalent(command, expected_command, platform=platform):
+        return _result(
+            "correct",
+            "the existing memleaf MCP entry uses this runtime and Vault",
+            config_path=path,
+            expected_command=expected_command,
+            configured_command=command,
+            configured_vault=configured_vault,
+        )
+    if _is_bare_memleaf_command(command, platform=platform):
+        return _result(
+            "legacy",
+            "the existing entry uses a PATH-dependent memleaf-mcp command",
+            config_path=path,
+            expected_command=expected_command,
+            configured_command=command,
+            configured_vault=configured_vault,
+        )
+    if is_absolute_memleaf_command(command, platform=platform):
+        return _result(
+            "runtime_conflict",
+            "the existing MCP entry uses the same Vault but a different memleaf runtime",
+            config_path=path,
+            expected_command=expected_command,
+            configured_command=command,
+            configured_vault=configured_vault,
+        )
+    return _result(
+        "conflict",
+        "the existing MCP command is not a recognized memleaf-mcp executable",
+        config_path=path,
+        expected_command=expected_command,
+        configured_command=command,
+        configured_vault=configured_vault,
+    )
+
+
+__all__ = [
+    "HermesMcpInspection",
+    "host_paths_equivalent",
+    "inspect_hermes_mcp",
+    "is_absolute_memleaf_command",
+]