universal-memory 0.1.0__tar.gz → 0.1.2__tar.gz

{universal_memory-0.1.0 → universal_memory-0.1.2}/PKG-INFO

@@ -1,10 +1,19 @@
 Metadata-Version: 2.3
 Name: universal-memory
-Version: 0.1.0
+Version: 0.1.2
 Summary: Vendor-agnostic cognitive persistence layer for AI agents.
+Keywords: agent-memory,ai,ai-agents,agent-skills,claude-code,codex,context-engineering,developer-tools,llm,mcp,memory
 Author: Yan L. Amorelli
 Author-email: Yan L. Amorelli <dev@amorelliaoyan.com>
 License: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Utilities
 Requires-Dist: fastmcp>=0.1.0
 Requires-Dist: pydantic>=2.0
 Requires-Dist: rich>=15.0.0
@@ -15,11 +24,15 @@ Project-URL: Homepage, https://github.com/YanAmorelli/universal-memory
 Project-URL: Repository, https://github.com/YanAmorelli/universal-memory
 Description-Content-Type: text/markdown
 
+<p align="center">
+  <img src="assets/umem-logo.png" alt="Universal Memory logo" width="720">
+</p>
+
 # Universal Memory (umem)
 
 [![PyPI version](https://img.shields.io/pypi/v/universal-memory.svg)](https://pypi.org/project/universal-memory/)
-[![Python Version](https://img.shields.io/pypi/pyversions/universal-memory.svg)](https://img.shields.io/project/universal-memory/)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Python Version](https://img.shields.io/pypi/pyversions/universal-memory.svg)](https://pypi.org/project/universal-memory/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/YanAmorelli/universal-memory/blob/dev/LICENSE)
 
 A vendor-agnostic cognitive persistence layer for AI agents. Eliminate the "repetition tax" by transporting your context, preferences, guidelines, and history seamlessly across sessions, IDEs, and LLM models.
 
@@ -27,7 +40,7 @@ To see the core idea visually, check out the [Excalidraw design](https://excalid
 
 ![Universal Memory MVP Proposal](docs/UNIVERSAL-MEMORY-MVP-PROPOSAL.png)
 
-### Diagram Breakdown (English Translation)
+### Diagram Breakdown
 
 *   **Short-Term Memory (Ephemeral):** Project-specific (folder-level) memories. A simple summary of recent changes, pending tasks, and project or task-level constraints.
 *   **Agents Behaviours:** Comports the user's expected agent behaviors. Instead of requesting the same settings in every session, the agent understands the user by their traits, thoughts, and any context key to enhancing the overall experience. This encompasses:
@@ -72,12 +85,18 @@ Encapsulates complex, repetitive procedural instructions into formal Agent Skill
 
 Ensure you have Python 3.12+ installed. You can run or install `umem` using your preferred package manager.
 
-### Run instantly with `uv` (Recommended)
-You don't even need to install it permanently:
+### Try instantly with `uvx`
+You can run `umem` without installing it permanently:
 ```bash
-uvx umem --help
+uvx --from universal-memory umem --help
 ```
 
+> [!WARNING]
+> `uvx` is best for quick trials. For ongoing use, install Universal Memory as a persistent tool so `umem` is always available and can fully manage long-lived global memories and synced agent skills:
+> ```bash
+> uv tool install universal-memory
+> ```
+
 ### Install via PyPI
 ```bash
 pip install universal-memory

{universal_memory-0.1.0 → universal_memory-0.1.2}/README.md

@@ -1,8 +1,12 @@
+<p align="center">
+  <img src="assets/umem-logo.png" alt="Universal Memory logo" width="720">
+</p>
+
 # Universal Memory (umem)
 
 [![PyPI version](https://img.shields.io/pypi/v/universal-memory.svg)](https://pypi.org/project/universal-memory/)
-[![Python Version](https://img.shields.io/pypi/pyversions/universal-memory.svg)](https://img.shields.io/project/universal-memory/)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Python Version](https://img.shields.io/pypi/pyversions/universal-memory.svg)](https://pypi.org/project/universal-memory/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/YanAmorelli/universal-memory/blob/dev/LICENSE)
 
 A vendor-agnostic cognitive persistence layer for AI agents. Eliminate the "repetition tax" by transporting your context, preferences, guidelines, and history seamlessly across sessions, IDEs, and LLM models.
 
@@ -10,7 +14,7 @@ To see the core idea visually, check out the [Excalidraw design](https://excalid
 
 ![Universal Memory MVP Proposal](docs/UNIVERSAL-MEMORY-MVP-PROPOSAL.png)
 
-### Diagram Breakdown (English Translation)
+### Diagram Breakdown
 
 *   **Short-Term Memory (Ephemeral):** Project-specific (folder-level) memories. A simple summary of recent changes, pending tasks, and project or task-level constraints.
 *   **Agents Behaviours:** Comports the user's expected agent behaviors. Instead of requesting the same settings in every session, the agent understands the user by their traits, thoughts, and any context key to enhancing the overall experience. This encompasses:
@@ -55,12 +59,18 @@ Encapsulates complex, repetitive procedural instructions into formal Agent Skill
 
 Ensure you have Python 3.12+ installed. You can run or install `umem` using your preferred package manager.
 
-### Run instantly with `uv` (Recommended)
-You don't even need to install it permanently:
+### Try instantly with `uvx`
+You can run `umem` without installing it permanently:
 ```bash
-uvx umem --help
+uvx --from universal-memory umem --help
 ```
 
+> [!WARNING]
+> `uvx` is best for quick trials. For ongoing use, install Universal Memory as a persistent tool so `umem` is always available and can fully manage long-lived global memories and synced agent skills:
+> ```bash
+> uv tool install universal-memory
+> ```
+
 ### Install via PyPI
 ```bash
 pip install universal-memory

{universal_memory-0.1.0 → universal_memory-0.1.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "universal-memory"
-version = "0.1.0"
+version = "0.1.2"
 description = "Vendor-agnostic cognitive persistence layer for AI agents."
 readme = "README.md"
 license = { text = "MIT" }
@@ -8,6 +8,29 @@ authors = [
     { name = "Yan L. Amorelli", email = "dev@amorelliaoyan.com" }
 ]
 requires-python = ">=3.12"
+keywords = [
+    "agent-memory",
+    "ai",
+    "ai-agents",
+    "agent-skills",
+    "claude-code",
+    "codex",
+    "context-engineering",
+    "developer-tools",
+    "llm",
+    "mcp",
+    "memory",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: Utilities",
+]
 dependencies = [
     "fastmcp>=0.1.0",
     "pydantic>=2.0",
@@ -44,6 +67,18 @@ line-length = 100
 select = ["E", "F", "I", "N", "UP", "PL", "RUF", "B", "S"]
 
 [tool.ruff.lint.per-file-ignores]
+"scripts/alpha_tester.py" = [
+    "E501",
+    "F841",
+    "PLR0912",
+    "PLR0915",
+    "PLW1510",
+    "RUF005",
+    "RUF059",
+    "S101",
+    "S603",
+    "S607",
+]
 "tests/**/*.py" = ["S101"]
 "src/universal_memory/interfaces/cli/init_command.py" = ["E501"]
 

{universal_memory-0.1.0 → universal_memory-0.1.2}/src/universal_memory/__init__.py

@@ -5,4 +5,4 @@ from importlib.metadata import PackageNotFoundError, version
 try:
     __version__ = version("universal-memory")
 except PackageNotFoundError:
-    __version__ = "0.1.0"
+    __version__ = "0.1.2"

universal_memory-0.1.2/src/universal_memory/application/diagnostics/__init__.py

@@ -0,0 +1,15 @@
+from universal_memory.application.diagnostics.doctor_use_case import (
+    DoctorCheck,
+    DoctorCommand,
+    DoctorResult,
+    DoctorSummary,
+    DoctorUseCase,
+)
+
+__all__ = [
+    "DoctorCheck",
+    "DoctorCommand",
+    "DoctorResult",
+    "DoctorSummary",
+    "DoctorUseCase",
+]

universal_memory-0.1.2/src/universal_memory/application/diagnostics/doctor_use_case.py

@@ -0,0 +1,365 @@
+from __future__ import annotations
+
+import os
+import shutil
+import sys
+from collections.abc import Callable
+from dataclasses import dataclass
+from pathlib import Path
+
+from universal_memory.application.host import ConfigureHostCommand, ConfigureHostResult
+from universal_memory.infrastructure.config.project_layout import (
+    DIRECTORY_LAYOUT_PATHS,
+    PROJECT_LAYOUT_PATHS,
+)
+from universal_memory.infrastructure.config.toml_loader import load_config
+
+CheckStatus = str
+HostCheckCommand = Callable[[ConfigureHostCommand], ConfigureHostResult]
+WhichResolver = Callable[[str], str | None]
+CONFIG_LOAD_ERROR_PREFIX = "__config_load_error__:"
+
+
+@dataclass(frozen=True, slots=True)
+class DoctorCommand:
+    project_root: Path
+
+
+@dataclass(frozen=True, slots=True)
+class DoctorCheck:
+    name: str
+    status: CheckStatus
+    detail: str | None = None
+    error: str | None = None
+    recovery_hint: str | None = None
+
+    def to_payload(self) -> dict[str, str]:
+        payload = {"name": self.name, "status": self.status}
+        if self.detail is not None:
+            payload["detail"] = self.detail
+        if self.error is not None:
+            payload["error"] = self.error
+        if self.recovery_hint is not None:
+            payload["recovery_hint"] = self.recovery_hint
+        return payload
+
+
+@dataclass(frozen=True, slots=True)
+class DoctorSummary:
+    total_checks: int
+    passed: int
+    failed: int
+
+    def to_payload(self) -> dict[str, int]:
+        return {
+            "total_checks": self.total_checks,
+            "passed": self.passed,
+            "failed": self.failed,
+        }
+
+
+@dataclass(frozen=True, slots=True)
+class DoctorResult:
+    checks: list[DoctorCheck]
+
+    @property
+    def ok(self) -> bool:
+        return all(check.status == "success" for check in self.checks)
+
+    @property
+    def summary(self) -> DoctorSummary:
+        passed = sum(1 for check in self.checks if check.status == "success")
+        failed = len(self.checks) - passed
+        return DoctorSummary(total_checks=len(self.checks), passed=passed, failed=failed)
+
+    def to_payload(self) -> dict[str, object]:
+        return {
+            "checks": [check.to_payload() for check in self.checks],
+            "summary": self.summary.to_payload(),
+        }
+
+
+class DoctorUseCase:
+    def __init__(  # noqa: PLR0913
+        self,
+        *,
+        host_check_command: HostCheckCommand | None = None,
+        which: WhichResolver = shutil.which,
+        version_info: tuple[int, int, int] | None = None,
+        home: Path | None = None,
+        xdg_data_home: Path | None = None,
+        xdg_config_home: Path | None = None,
+    ) -> None:
+        self.host_check_command = host_check_command
+        self.which = which
+        self.version_info = version_info or (
+            sys.version_info.major,
+            sys.version_info.minor,
+            sys.version_info.micro,
+        )
+        self.home = home or Path.home()
+        self.xdg_data_home = xdg_data_home
+        self.xdg_config_home = xdg_config_home
+
+    def execute(self, command: DoctorCommand) -> DoctorResult:
+        project_root = command.project_root.resolve()
+        checks = [
+            self._python_version_check(),
+            self._path_permissions_check(project_root),
+            self._project_layout_check(project_root),
+            self._path_executables_check(),
+            self._hosts_integration_check(project_root),
+        ]
+        return DoctorResult(checks=checks)
+
+    def _python_version_check(self) -> DoctorCheck:
+        major, minor, micro = self.version_info
+        detail = f"Python {major}.{minor}.{micro}"
+        if (major, minor) >= (3, 12):
+            return DoctorCheck(name="python_version", status="success", detail=detail)
+        return DoctorCheck(
+            name="python_version",
+            status="failed",
+            detail=detail,
+            error="Python 3.12 or higher is required.",
+            recovery_hint="Configure a virtual environment with Python 3.12 or higher.",
+        )
+
+    def _path_permissions_check(self, project_root: Path) -> DoctorCheck:
+        paths = [
+            (self._global_data_root(), "directory"),
+            (self._global_config_path(), "file"),
+        ]
+        if (project_root / ".umem").exists():
+            paths.append((project_root / ".umem", "directory"))
+        else:
+            paths.append((project_root, "directory"))
+
+        failures: list[str] = []
+        for path, expected_kind in paths:
+            failure = self._permission_failure(path, expected_kind, project_root)
+            if failure is not None:
+                failures.append(failure)
+
+        if not failures:
+            return DoctorCheck(
+                name="filesystem_permissions",
+                status="success",
+                detail="Canonical local and global paths are writable.",
+            )
+        return DoctorCheck(
+            name="filesystem_permissions",
+            status="failed",
+            error="; ".join(failures),
+            recovery_hint="Fix filesystem permissions with chmod -R u+rw <path>.",
+        )
+
+    def _project_layout_check(self, project_root: Path) -> DoctorCheck:
+        umem_root = project_root / ".umem"
+        if not umem_root.exists():
+            return DoctorCheck(
+                name="project_layout",
+                status="failed",
+                error="Missing project layout: .umem",
+                recovery_hint="Run umem init --yes to create the project layout.",
+            )
+        if not umem_root.is_dir():
+            return DoctorCheck(
+                name="project_layout",
+                status="failed",
+                error="Project layout root .umem is not a directory.",
+                recovery_hint="Move the conflicting .umem file and run umem init --yes.",
+            )
+
+        failures: list[str] = []
+        for relative_path in PROJECT_LAYOUT_PATHS:
+            target = project_root / relative_path
+            expected = "directory" if relative_path in DIRECTORY_LAYOUT_PATHS else "file"
+            if not target.exists():
+                failures.append(f"Missing path: {relative_path}")
+            elif expected == "directory" and not target.is_dir():
+                failures.append(f"Wrong path kind: {relative_path} must be a directory")
+            elif expected == "file" and not target.is_file():
+                failures.append(f"Wrong path kind: {relative_path} must be a file")
+
+        if not failures:
+            return DoctorCheck(
+                name="project_layout",
+                status="success",
+                detail="Project layout is complete.",
+            )
+        return DoctorCheck(
+            name="project_layout",
+            status="failed",
+            error="; ".join(failures),
+            recovery_hint="Run umem init --yes to rebuild missing default paths.",
+        )
+
+    def _path_executables_check(self) -> DoctorCheck:
+        required = ["umem", "umem-mcp"]
+        missing = [name for name in required if self.which(name) is None]
+        if not missing:
+            return DoctorCheck(
+                name="path_executables",
+                status="success",
+                detail="umem and umem-mcp are available on PATH.",
+            )
+        return DoctorCheck(
+            name="path_executables",
+            status="failed",
+            error=f"Missing executables on PATH: {', '.join(missing)}",
+            recovery_hint="Activate the virtual environment or install with uv sync.",
+        )
+
+    def _hosts_integration_check(self, project_root: Path) -> DoctorCheck:
+        host_ids = self._configured_host_ids(project_root)
+        config_errors = [
+            host_id.removeprefix(CONFIG_LOAD_ERROR_PREFIX)
+            for host_id in host_ids
+            if host_id.startswith(CONFIG_LOAD_ERROR_PREFIX)
+        ]
+        if config_errors:
+            return DoctorCheck(
+                name="hosts_integration",
+                status="failed",
+                error="; ".join(config_errors),
+                recovery_hint="Fix .umem/config.toml and re-run umem doctor.",
+            )
+        if self.host_check_command is None:
+            return DoctorCheck(
+                name="hosts_integration",
+                status="success",
+                detail="Host integration check is not configured.",
+            )
+        if not host_ids:
+            return DoctorCheck(
+                name="hosts_integration",
+                status="success",
+                detail="No hosts configured.",
+            )
+
+        failures: list[str] = []
+        for host_id in host_ids:
+            try:
+                result = self.host_check_command(
+                    ConfigureHostCommand(
+                        host_id=host_id,
+                        apply=False,
+                        check=True,
+                        record_audit=False,
+                    )
+                )
+            except Exception as error:
+                failures.append(f"{host_id}: {error}")
+                continue
+            if result.validation_status != "success":
+                detail = ", ".join(result.warnings or result.manual_steps)
+                suffix = f" ({detail})" if detail else ""
+                failures.append(f"{host_id}: {result.validation_status}{suffix}")
+
+        if not failures:
+            return DoctorCheck(
+                name="hosts_integration",
+                status="success",
+                detail=f"Validated hosts: {', '.join(host_ids)}.",
+            )
+        return DoctorCheck(
+            name="hosts_integration",
+            status="failed",
+            error="; ".join(failures),
+            recovery_hint="Run umem host setup <host_id> --yes to repair host instructions.",
+        )
+
+    def _configured_host_ids(self, project_root: Path) -> list[str]:
+        try:
+            loaded = load_config(project_root)
+        except Exception as error:
+            return [f"{CONFIG_LOAD_ERROR_PREFIX}{error}"]
+
+        host_ids: list[str] = []
+        for section_name in ("runtimes", "hosts"):
+            section = loaded.merged.get(section_name)
+            if not isinstance(section, dict):
+                continue
+            enabled = section.get("enabled")
+            if isinstance(enabled, list):
+                host_ids.extend(str(item) for item in enabled)
+            for key, value in section.items():
+                if isinstance(value, dict) and value.get("enabled") is True:
+                    host_ids.append(str(key))
+
+        supported = {"codex", "claude_code"}
+        deduped: list[str] = []
+        for host_id in host_ids:
+            if host_id in supported and host_id not in deduped:
+                deduped.append(host_id)
+        return deduped
+
+    def _global_data_root(self) -> Path:
+        configured = self.xdg_data_home or _env_path("XDG_DATA_HOME")
+        return (configured if configured is not None else self.home / ".local" / "share") / "umem"
+
+    def _global_config_path(self) -> Path:
+        configured = self.xdg_config_home or _env_path("XDG_CONFIG_HOME")
+        root = configured if configured is not None else self.home / ".config"
+        return root / "umem" / "config.toml"
+
+    @staticmethod
+    def _relative_or_user_path(path: Path, project_root: Path) -> str:
+        try:
+            return path.resolve().relative_to(project_root.resolve()).as_posix()
+        except ValueError:
+            return path.expanduser().as_posix()
+
+    def _permission_failure(
+        self,
+        path: Path,
+        expected_kind: str,
+        project_root: Path,
+    ) -> str | None:
+        display_path = self._relative_or_user_path(path, project_root)
+        if path.exists():
+            return self._existing_path_permission_failure(path, expected_kind, display_path)
+
+        return self._missing_path_permission_failure(path, display_path)
+
+    @staticmethod
+    def _existing_path_permission_failure(
+        path: Path,
+        expected_kind: str,
+        display_path: str,
+    ) -> str | None:
+        if expected_kind == "directory":
+            if not path.is_dir():
+                return f"{display_path}: path must be a directory"
+            has_permissions = os.access(path, os.R_OK | os.W_OK | os.X_OK)
+            return (
+                None
+                if has_permissions
+                else f"{display_path}: directory is not readable, writable, and searchable"
+            )
+
+        if not path.is_file():
+            return f"{display_path}: path must be a file"
+
+        has_permissions = os.access(path, os.R_OK | os.W_OK)
+        return None if has_permissions else f"{display_path}: file is not readable and writable"
+
+    @staticmethod
+    def _missing_path_permission_failure(path: Path, display_path: str) -> str | None:
+        parent = path.parent
+        parent_has_permissions = (
+            parent.exists() and parent.is_dir() and os.access(parent, os.R_OK | os.W_OK | os.X_OK)
+        )
+        if parent_has_permissions:
+            return None
+        if not parent.exists():
+            return f"{display_path}: parent directory is missing"
+        return f"{display_path}: parent directory is not readable, writable, and searchable"
+
+
+def _env_path(name: str) -> Path | None:
+    value = os.environ.get(name)
+    if not value:
+        return None
+    return Path(value)

{universal_memory-0.1.0 → universal_memory-0.1.2}/src/universal_memory/application/host/setup_host_use_case.py

@@ -114,6 +114,7 @@ class ConfigureHostCommand:
     host_id: str
     apply: bool = False
     check: bool = False
+    record_audit: bool = True
     instruction_blocks: list[InstructionBlock] = field(default_factory=list)
     shared_manifest_available: bool | None = None
     max_managed_lines: int = DEFAULT_MAX_MANAGED_LINES
@@ -244,7 +245,11 @@ class ConfigureHostUseCase:
                 max_lines=command.max_managed_lines,
                 max_chars=command.max_managed_chars,
             )
-            audit_reference = self._record_host_validation(command, host, validation)
+            audit_reference = (
+                self._record_host_validation(command, host, validation)
+                if command.record_audit
+                else "not-recorded"
+            )
             return ConfigureHostResult(
                 host_id=host.name.value,
                 instruction_targets=[target.name.value],

{universal_memory-0.1.0 → universal_memory-0.1.2}/src/universal_memory/application/memory/get_memory_status_use_case.py

@@ -7,6 +7,7 @@ from dataclasses import dataclass
 from datetime import UTC, datetime
 from pathlib import Path
 
+from universal_memory import __version__
 from universal_memory.domain.entities import (
     AuditEventScope,
     FactScope,
@@ -40,6 +41,7 @@ class GetMemoryStatusResult:
     last_health_check: str | None
     host_validation: dict[str, dict[str, str | None]]
     recommended_action: str | None = None
+    installed_version: str = __version__
 
 
 class GetMemoryStatusUseCase:

{universal_memory-0.1.0 → universal_memory-0.1.2}/src/universal_memory/bootstrap/cli.py

@@ -2,6 +2,7 @@ from collections.abc import Sequence
 from datetime import UTC, datetime
 from pathlib import Path
 
+from universal_memory.application.diagnostics import DoctorUseCase
 from universal_memory.application.host import (
     ConfigureHostUseCase,
     SyncInstructionsUseCase,
@@ -176,6 +177,7 @@ def main(argv: Sequence[str] | None = None) -> int:
         safe_write_use_case=safe_write_use_case,
         fact_repository=fact_repository,
     )
+    doctor_use_case = DoctorUseCase(host_check_command=host_use_case.execute)
     host_sync_use_case = SyncInstructionsUseCase(
         project_root=project_root,
         safe_write_use_case=safe_write_use_case,
@@ -262,6 +264,7 @@ def main(argv: Sequence[str] | None = None) -> int:
         rollback_command=rollback_use_case.execute,
         rollback_preview_command=rollback_preview,
         status_command=status_use_case.execute,
+        doctor_command=doctor_use_case.execute,
         context_command=context_use_case.execute,
         remember_command=remember_use_case.execute,
         facts_list_command=facts_list_use_case.execute,

{universal_memory-0.1.0 → universal_memory-0.1.2}/src/universal_memory/bootstrap/mcp.py

@@ -4,6 +4,7 @@ from pathlib import Path
 
 from fastmcp import FastMCP
 
+from universal_memory.application.diagnostics import DoctorUseCase
 from universal_memory.application.host import (
     ConfigureHostUseCase,
     SyncInstructionsUseCase,
@@ -122,6 +123,7 @@ def build_server(project_root: Path | None = None) -> FastMCP:
         safe_write_use_case=safe_write_use_case,
         fact_repository=fact_repository,
     )
+    doctor_use_case = DoctorUseCase(host_check_command=host_use_case.execute)
     host_sync_use_case = SyncInstructionsUseCase(
         project_root=root,
         safe_write_use_case=safe_write_use_case,
@@ -182,6 +184,7 @@ def build_server(project_root: Path | None = None) -> FastMCP:
         MCPUseCases(
             initialize_project=initialize_project,
             status=status_use_case.execute,
+            doctor=doctor_use_case.execute,
             context=context_use_case.execute,
             remember=remember_use_case.execute,
             list_facts=facts_list_use_case.execute,

{universal_memory-0.1.0 → universal_memory-0.1.2}/src/universal_memory/interfaces/cli/init_command.py

@@ -16,6 +16,11 @@ from rich.panel import Panel
 from rich.table import Table
 from rich.text import Text
 
+from universal_memory import __version__
+from universal_memory.application.diagnostics import (
+    DoctorCommand,
+    DoctorResult,
+)
 from universal_memory.application.host import (
     ConfigureHostCommand,
     ConfigureHostResult,
@@ -146,6 +151,7 @@ ListSnapshotsCommandHandler = Callable[[ListSnapshotsCommand], ListSnapshotsResu
 RollbackCommandHandler = Callable[[RollbackCommand], RollbackResult]
 RollbackPreviewHandler = Callable[[SnapshotScope], Snapshot]
 StatusCommandHandler = Callable[[GetMemoryStatusCommand], GetMemoryStatusResult]
+DoctorCommandHandler = Callable[[DoctorCommand], DoctorResult]
 ContextCommandHandler = Callable[[AssembleContextSummaryCommand], AssembleContextSummaryResult]
 RememberFactCommandHandler = Callable[[RememberFactCommand], RememberFactResult]
 ListFactsCommandHandler = Callable[[ListFactsCommand], ListFactsResult]
@@ -199,6 +205,7 @@ def main(  # noqa: PLR0913
     rollback_command: RollbackCommandHandler | None = None,
     rollback_preview_command: RollbackPreviewHandler | None = None,
     status_command: StatusCommandHandler | None = None,
+    doctor_command: DoctorCommandHandler | None = None,
     context_command: ContextCommandHandler | None = None,
     remember_command: RememberFactCommandHandler | None = None,
     facts_list_command: ListFactsCommandHandler | None = None,
@@ -227,6 +234,7 @@ def main(  # noqa: PLR0913
         rollback_command=rollback_command,
         rollback_preview_command=rollback_preview_command,
         status_command=status_command,
+        doctor_command=doctor_command,
         context_command=context_command,
         remember_command=remember_command,
         facts_list_command=facts_list_command,
@@ -287,6 +295,12 @@ def main(  # noqa: PLR0913
     return 0
 
 
+def _version_callback(value: bool) -> None:
+    if value:
+        typer.echo(f"umem {__version__}")
+        raise typer.Exit()
+
+
 def create_typer_app(  # noqa: PLR0913, PLR0915
     *,
     setup_project_command: SetupProjectCommand | None = None,
@@ -295,6 +309,7 @@ def create_typer_app(  # noqa: PLR0913, PLR0915
     rollback_command: RollbackCommandHandler | None = None,
     rollback_preview_command: RollbackPreviewHandler | None = None,
     status_command: StatusCommandHandler | None = None,
+    doctor_command: DoctorCommandHandler | None = None,
     context_command: ContextCommandHandler | None = None,
     remember_command: RememberFactCommandHandler | None = None,
     facts_list_command: ListFactsCommandHandler | None = None,
@@ -332,6 +347,15 @@ def create_typer_app(  # noqa: PLR0913, PLR0915
     @app.callback()
     def callback(
         ctx: typer.Context,
+        version: Annotated[
+            bool,
+            typer.Option(
+                "--version",
+                help="Show installed version and exit.",
+                callback=_version_callback,
+                is_eager=True,
+            ),
+        ] = False,
         output_format: Annotated[
             str,
             typer.Option(
@@ -343,6 +367,7 @@ def create_typer_app(  # noqa: PLR0913, PLR0915
             ),
         ] = "human",
     ) -> None:
+        _ = version
         ctx.obj = {"output_format": output_format.lower()}
 
     @app.command("init")
@@ -384,6 +409,15 @@ def create_typer_app(  # noqa: PLR0913, PLR0915
             code=_run_status(status_command, output_format=_effective_format(ctx, output_format))
         )
 
+    @app.command("doctor")
+    def doctor(ctx: typer.Context, output_format: OutputFormatOption = None) -> None:
+        if doctor_command is None:
+            msg = "CLI doctor_command dependency was not configured."
+            raise RuntimeError(msg)
+        raise typer.Exit(
+            code=_run_doctor(doctor_command, output_format=_effective_format(ctx, output_format))
+        )
+
     @app.command("update")
     def update(  # noqa: PLR0913
         ctx: typer.Context,
@@ -950,6 +984,7 @@ def build_main(  # noqa: PLR0913
     rollback_command: RollbackCommandHandler,
     rollback_preview_command: RollbackPreviewHandler,
     status_command: StatusCommandHandler,
+    doctor_command: DoctorCommandHandler,
     context_command: ContextCommandHandler,
     remember_command: RememberFactCommandHandler,
     facts_list_command: ListFactsCommandHandler,
@@ -985,6 +1020,7 @@ def build_main(  # noqa: PLR0913
             rollback_command=rollback_command,
             rollback_preview_command=rollback_preview_command,
             status_command=status_command,
+            doctor_command=doctor_command,
             context_command=context_command,
             remember_command=remember_command,
             facts_list_command=facts_list_command,
@@ -1371,6 +1407,30 @@ def _run_status(command: StatusCommandHandler, *, output_format: str) -> int:
     return 0
 
 
+def _run_doctor(command: DoctorCommandHandler, *, output_format: str) -> int:
+    try:
+        result = command(DoctorCommand(project_root=Path.cwd()))
+    except OSError as error:
+        _print_expected_error(StorageError(str(error)), output_format=output_format)
+        return 1
+    except DOMAIN_ERROR_TYPES as error:
+        _print_expected_error(error, output_format=output_format)
+        return 1
+    except ValidationError as error:
+        _print_expected_error(ValidationFailedError(str(error)), output_format=output_format)
+        return 1
+    except Exception as error:
+        _print_unexpected_error(error, output_format=output_format)
+        return 1
+
+    if output_format == "json":
+        print(json.dumps(_doctor_success_envelope(result), sort_keys=True))
+    else:
+        _stdout_console().print(_format_human_doctor_output(result))
+
+    return 0 if result.ok else 1
+
+
 def _run_context(
     command: ContextCommandHandler,
     *,
@@ -2629,6 +2689,16 @@ def _status_success_envelope(result: GetMemoryStatusResult) -> dict[str, Any]:
     }
 
 
+def _doctor_success_envelope(result: DoctorResult) -> dict[str, Any]:
+    return {
+        "ok": result.ok,
+        "operation": "doctor",
+        "scope": "environment",
+        "data": result.to_payload(),
+        "warnings": [],
+    }
+
+
 def _skill_proposal_payload(result: ProposeSkillResult) -> dict[str, Any]:
     return {
         "skill_id": result.latent_skill.id,
@@ -2845,12 +2915,14 @@ def _status_payload(result: GetMemoryStatusResult) -> dict[str, Any]:
         return {
             "initialized": False,
             "project_path": result.project_path,
+            "installed_version": result.installed_version,
             "recommended_action": result.recommended_action,
         }
 
     return {
         "initialized": True,
         "project_path": result.project_path,
+        "installed_version": result.installed_version,
         "fact_counts": result.fact_counts,
         "active_rules_count": result.active_rules_count,
         "registered_skills_count": result.registered_skills_count,
@@ -2936,6 +3008,7 @@ def _format_human_status_output(result: GetMemoryStatusResult) -> str:
             [
                 "Local memory is not initialized.",
                 f"Project: {result.project_path}",
+                f"Installed version: {result.installed_version}",
                 f"Next action: {result.recommended_action}",
             ]
         )
@@ -2943,6 +3016,7 @@ def _format_human_status_output(result: GetMemoryStatusResult) -> str:
     lines = [
         "Local memory initialized.",
         f"Project: {result.project_path}",
+        f"Installed version: {result.installed_version}",
         f"Approximate size: {result.approximate_size_bytes} bytes",
         f"Last health check: {result.last_health_check}",
         f"Active rules: {result.active_rules_count}",
@@ -2967,6 +3041,36 @@ def _format_human_status_output(result: GetMemoryStatusResult) -> str:
     return "\n".join(lines)
 
 
+def _format_human_doctor_output(result: DoctorResult) -> str:
+    lines = [
+        "universal-memory Doctor - Health Report",
+        "========================================",
+        "",
+    ]
+    for check in result.checks:
+        marker = "[OK]" if check.status == "success" else "[FAIL]"
+        label = " ".join(check.name.split("_")).title()
+        detail = f" - {check.detail}" if check.detail else ""
+        lines.append(f"{marker} {label}{detail}")
+        if check.error:
+            lines.append(f"    Error: {check.error}")
+        if check.recovery_hint:
+            lines.append(f"    Recovery: {check.recovery_hint}")
+
+    summary = result.summary
+    lines.extend(
+        [
+            "",
+            (
+                "Final status: all checks passed."
+                if result.ok
+                else f"Final status: {summary.failed} failure(s) found."
+            ),
+        ]
+    )
+    return "\n".join(lines)
+
+
 def _format_human_context_output(result: AssembleContextSummaryResult) -> str:
     summary = result.context_summary
     lines = [

{universal_memory-0.1.0 → universal_memory-0.1.2}/src/universal_memory/interfaces/mcp/server.py

@@ -9,6 +9,10 @@ from typing import Any, Literal
 
 from fastmcp import FastMCP
 
+from universal_memory.application.diagnostics import (
+    DoctorCommand,
+    DoctorResult,
+)
 from universal_memory.application.host import (
     ConfigureHostCommand,
     ConfigureHostResult,
@@ -86,6 +90,7 @@ DEFAULT_CONTEXT_MAX_SIZE_CHARS = 4000
 TOKEN_ESTIMATE_CHARS = 4
 SetupProjectCommandHandler = Callable[[Path], SetupProjectResult]
 StatusCommandHandler = Callable[[GetMemoryStatusCommand], GetMemoryStatusResult]
+DoctorCommandHandler = Callable[[DoctorCommand], DoctorResult]
 ContextCommandHandler = Callable[[AssembleContextSummaryCommand], AssembleContextSummaryResult]
 RememberCommandHandler = Callable[[RememberFactCommand], RememberFactResult]
 ListFactsCommandHandler = Callable[[ListFactsCommand], ListFactsResult]
@@ -115,6 +120,7 @@ def _missing_use_case(_command: Any) -> Any:
 class MCPUseCases:
     status: StatusCommandHandler
     context: ContextCommandHandler
+    doctor: DoctorCommandHandler = _missing_use_case
     initialize_project: SetupProjectCommandHandler = _missing_use_case
     remember: RememberCommandHandler = _missing_use_case
     list_facts: ListFactsCommandHandler = _missing_use_case
@@ -184,6 +190,15 @@ def configure_server(  # noqa: PLR0915
         except Exception as error:
             return _mcp_tool_error(error, operation="status", scope="project")
 
+    @server.tool(name="doctor")
+    def doctor() -> ToolResponse:
+        """Run read-only environment diagnostics for Universal Memory."""
+        try:
+            result = use_cases.doctor(DoctorCommand(project_root=root))
+            return _doctor_success_envelope(result)
+        except Exception as error:
+            return _mcp_tool_error(error, operation="doctor", scope="environment")
+
     @server.tool(name="context")
     def context(
         scope: Literal["project", "global"] = "project",
@@ -669,12 +684,14 @@ def _status_payload(result: GetMemoryStatusResult) -> dict[str, Any]:
         return {
             "initialized": False,
             "project_path": result.project_path,
+            "installed_version": result.installed_version,
             "recommended_action": result.recommended_action,
         }
 
     return {
         "initialized": True,
         "project_path": result.project_path,
+        "installed_version": result.installed_version,
         "fact_counts": result.fact_counts,
         "active_rules_count": result.active_rules_count,
         "registered_skills_count": result.registered_skills_count,
@@ -684,6 +701,16 @@ def _status_payload(result: GetMemoryStatusResult) -> dict[str, Any]:
     }
 
 
+def _doctor_success_envelope(result: DoctorResult) -> dict[str, Any]:
+    return {
+        "ok": result.ok,
+        "operation": "doctor",
+        "scope": "environment",
+        "data": result.to_payload(),
+        "warnings": [],
+    }
+
+
 def _context_payload(
     result: AssembleContextSummaryResult,
     *,