memleaf 0.2.9__tar.gz → 0.2.11__tar.gz

{memleaf-0.2.9 → memleaf-0.2.11}/CHANGELOG.md

@@ -2,6 +2,33 @@
 
 All notable changes to memleaf are documented here.
 
+## 0.2.11 — 2026-09-02
+
+- Document one complete macOS/Linux upgrade command that upgrades the core
+  package and refreshes the Hermes Provider together; report and verify both
+  versions after installation instead of silently accepting a stale copy.
+- Compare the copied Provider manifest with the MCP server version at Hermes
+  startup and emit the same actionable one-line upgrade command when they
+  differ or cannot be verified.
+- Normalize supported one-off Chinese and English relative dates
+  deterministically from their current evidence timestamps before strict
+  summary validation, including conflicting parenthesized numeric dates.
+- Keep ambiguous or unsupported relative-date candidates retryable without
+  guessing, while allowing valid sibling candidates from the same turn to
+  commit and preserving the source inbox.
+
+## 0.2.10 — 2026-09-01
+
+- Keep strict candidate-local project Scope grounding for the first two gate
+  attempts, then isolate a persistently invalid candidate instead of failing
+  the entire mailbox turn.
+- Correct a final-attempt model Scope only when the candidate text identifies
+  exactly one registered project name or alias; defer zero-match and
+  multi-project candidates as insufficient context without writing memory.
+- Preserve valid sibling candidates, new explicitly named project Scopes, and
+  the existing update-target relevance guard when Scope and target errors occur
+  together.
+
 ## 0.2.9 — 2026-09-01
 
 - Reject update and duplicate targets that are relevant only to another item

{memleaf-0.2.9/src/memleaf.egg-info → memleaf-0.2.11}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: memleaf
-Version: 0.2.9
+Version: 0.2.11
 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.9。**
-> 核心库、Vault、stdio MCP Server、初始化 CLI、模型路由、提炼流程、受控检索协议和宿主适配器已经实现。memleaf 0.2.9 通过 PyPI 分发。
+> **当前版本：0.2.11。**
+> 核心库、Vault、stdio MCP Server、初始化 CLI、模型路由、提炼流程、受控检索协议和宿主适配器已经实现。memleaf 0.2.11 通过 PyPI 分发。
 > **当前版本支持 Hermes 和 Codex。** Antigravity（反重力）不检测、不安装、不配置。
 
 ## 项目定位
@@ -132,7 +132,13 @@ python -m pip install -U memleaf && python -m memleaf install
 
 ### 更新 memleaf
 
-安装命令同时也是升级命令，不需要先卸载旧版本。Windows 用户重新执行上面的 PowerShell 一行命令；macOS / Linux 用户重新执行上面的 `pip install -U` 命令即可。
+安装命令同时也是升级命令，不需要先卸载旧版本。Windows 用户重新执行上面的 PowerShell 一行命令；macOS / Linux 用户升级时请重新执行下面这一行完整命令，它会同时升级核心包并刷新 Hermes Provider：
+
+```bash
+python -m pip install -U memleaf && python -m memleaf install
+```
+
+不要只执行 `pip install -U memleaf`；那只会升级核心包，不会刷新 `~/.hermes/plugins/memleaf` 中的 Provider。
 
 升级时不会迁移或删除现有记忆。Vault 选择顺序固定为：
 

{memleaf-0.2.9 → memleaf-0.2.11}/README.en.md

@@ -4,8 +4,8 @@
 
 [中文](README.md) · [PyPI](https://pypi.org/project/memleaf/) · [GitHub](https://github.com/miffyblueboo/memleaf)
 
-> **Version: 0.2.9.**
-> The core library, Vault, stdio MCP server, initialization CLI, model routing, memory extraction, controlled retrieval protocol, and host adapters are implemented. memleaf 0.2.9 is distributed through PyPI.
+> **Version: 0.2.11.**
+> The core library, Vault, stdio MCP server, initialization CLI, model routing, memory extraction, controlled retrieval protocol, and host adapters are implemented. memleaf 0.2.11 is distributed through PyPI.
 > **The current release supports Hermes and Codex.** Antigravity is not detected, installed, or configured.
 
 ## Project scope
@@ -113,7 +113,13 @@ python -m pip install -U memleaf && python -m memleaf install
 
 ### Updating memleaf
 
-The install command is also the upgrade command; an old version does not need to be uninstalled first. Windows users can rerun the PowerShell one-liner above, while macOS / Linux users can rerun the `pip install -U` command.
+The install command is also the upgrade command; an old version does not need to be uninstalled first. Windows users can rerun the PowerShell one-liner above. On macOS / Linux, run this complete one-line command to upgrade the core package and refresh the Hermes Provider together:
+
+```bash
+python -m pip install -U memleaf && python -m memleaf install
+```
+
+Do not run only `pip install -U memleaf`; that upgrades the core package but does not refresh the Provider under `~/.hermes/plugins/memleaf`.
 
 Upgrades do not migrate or delete existing memories. Vault selection has a fixed precedence:
 

{memleaf-0.2.9 → memleaf-0.2.11}/README.md

@@ -4,8 +4,8 @@
 
 [English](README.en.md) · [PyPI](https://pypi.org/project/memleaf/) · [GitHub](https://github.com/miffyblueboo/memleaf)
 
-> **当前版本：0.2.9。**
-> 核心库、Vault、stdio MCP Server、初始化 CLI、模型路由、提炼流程、受控检索协议和宿主适配器已经实现。memleaf 0.2.9 通过 PyPI 分发。
+> **当前版本：0.2.11。**
+> 核心库、Vault、stdio MCP Server、初始化 CLI、模型路由、提炼流程、受控检索协议和宿主适配器已经实现。memleaf 0.2.11 通过 PyPI 分发。
 > **当前版本支持 Hermes 和 Codex。** Antigravity（反重力）不检测、不安装、不配置。
 
 ## 项目定位
@@ -113,7 +113,13 @@ python -m pip install -U memleaf && python -m memleaf install
 
 ### 更新 memleaf
 
-安装命令同时也是升级命令，不需要先卸载旧版本。Windows 用户重新执行上面的 PowerShell 一行命令；macOS / Linux 用户重新执行上面的 `pip install -U` 命令即可。
+安装命令同时也是升级命令，不需要先卸载旧版本。Windows 用户重新执行上面的 PowerShell 一行命令；macOS / Linux 用户升级时请重新执行下面这一行完整命令，它会同时升级核心包并刷新 Hermes Provider：
+
+```bash
+python -m pip install -U memleaf && python -m memleaf install
+```
+
+不要只执行 `pip install -U memleaf`；那只会升级核心包，不会刷新 `~/.hermes/plugins/memleaf` 中的 Provider。
 
 升级时不会迁移或删除现有记忆。Vault 选择顺序固定为：
 

{memleaf-0.2.9 → memleaf-0.2.11}/pyproject.toml

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

{memleaf-0.2.9 → memleaf-0.2.11}/src/memleaf/__init__.py

@@ -1,6 +1,6 @@
 """Local-first Markdown memory core for AI agents."""
 
-__version__ = "0.2.9"
+__version__ = "0.2.11"
 
 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.9 → memleaf-0.2.11}/src/memleaf/cli.py

@@ -127,6 +127,15 @@ def main(argv: Sequence[str] | None = None) -> int:
             print(json.dumps(output, ensure_ascii=False, sort_keys=True))
         elif output.get("status") in {"configured", "already_configured"}:
             print(f"memleaf installed for {args.host}: {output['vault']}")
+            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'}"
+                )
             if output.get("vault_source") == "hermes_config":
                 print("Preserved the Vault from the existing Hermes memleaf configuration.")
             if args.host == "hermes":
@@ -136,6 +145,15 @@ def main(argv: Sequence[str] | None = None) -> int:
             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)
         return 0 if output.get("status") in {"configured", "already_configured"} else 2
     if args.json:

{memleaf-0.2.9 → memleaf-0.2.11}/src/memleaf/hermes_provider/__init__.py

@@ -32,6 +32,7 @@ _DEFAULT_TIMEOUT = 5.0
 _MAX_TIMEOUT = 30.0
 _DEFAULT_PROCESS_TIMEOUT = 300.0
 _MAX_PROCESS_TIMEOUT = 900.0
+_UPDATE_COMMAND = "python -m pip install -U memleaf && python -m memleaf install"
 _MAX_SCOPE_ITEMS = 20
 _MAX_SCOPE_CHARS = 2000
 _SCOPE_MAP_INCOMPLETE = (
@@ -49,6 +50,7 @@ _MAX_SESSION_ALIASES = 128
 _MAX_LINEAGE_RETRIES = 2
 _MAX_DEFERRED_PROCESS_SESSIONS = 128
 _SAFE_COMPONENT_RE = re.compile(r"[^A-Za-z0-9_.-]+")
+_PROVIDER_VERSION_RE = re.compile(r"^version:\s*([^\s#]+)\s*(?:#.*)?$", re.MULTILINE)
 _ASCII_QUERY_TERM_RE = re.compile(r"[a-z0-9]+(?:[ ._-][a-z0-9]+)*")
 _DISABLED_PLATFORMS = frozenset({"cron"})
 _DISABLED_AGENT_CONTEXTS = frozenset({"cron", "flush", "subagent"})
@@ -704,6 +706,28 @@ def _config_path(hermes_home: str | Path) -> Path:
     return Path(hermes_home).expanduser() / "memleaf.json"
 
 
+def _version_value(value: Any) -> Optional[str]:
+    """Return a bounded, log-safe version string or ``None``."""
+
+    if not isinstance(value, str):
+        return None
+    value = value.strip()
+    if not value or len(value) > 64 or any(char.isspace() for char in value):
+        return None
+    return value
+
+
+def _provider_manifest_version() -> Optional[str]:
+    """Read the version from this copied provider's adjacent manifest."""
+
+    try:
+        text = Path(__file__).with_name("plugin.yaml").read_text(encoding="utf-8")
+    except (OSError, UnicodeError, RuntimeError):
+        return None
+    match = _PROVIDER_VERSION_RE.search(text)
+    return _version_value(match.group(1)) if match else None
+
+
 def _default_hermes_home() -> Path:
     configured = os.environ.get("HERMES_HOME")
     return Path(configured).expanduser() if configured else Path.home() / ".hermes"
@@ -863,6 +887,7 @@ class _MCPClient:
         self._stdout_thread: Optional[threading.Thread] = None
         self._next_id = 1
         self._lock = threading.RLock()
+        self.server_version: Optional[str] = None
 
     def _resolve_command(self) -> str:
         path = Path(self.command).expanduser()
@@ -921,7 +946,7 @@ class _MCPClient:
             bufsize=1,
         )
         self._start_stdout_reader_locked(self._process)
-        self._request_locked(
+        initialize_result = self._request_locked(
             "initialize",
             {
                 "protocolVersion": "2024-11-05",
@@ -929,6 +954,13 @@ class _MCPClient:
                 "clientInfo": {"name": "hermes-memleaf", "version": "0.1.0"},
             },
         )
+        server_info = (
+            initialize_result.get("serverInfo")
+            if isinstance(initialize_result, Mapping)
+            else None
+        )
+        if isinstance(server_info, Mapping):
+            self.server_version = _version_value(server_info.get("version"))
         self._send_locked({"jsonrpc": "2.0", "method": "notifications/initialized"})
 
     def _send_locked(self, message: Mapping[str, Any]) -> None:
@@ -983,6 +1015,7 @@ class _MCPClient:
         self._process = None
         self._stdout_queue = None
         self._stdout_thread = None
+        self.server_version = None
         if process is None:
             return
         if process.stdin is not None:
@@ -1091,6 +1124,7 @@ class MemleafMemoryProvider(MemoryProvider):
         self._gate_turn_ids: "OrderedDict[Tuple[str, int], str]" = OrderedDict()
         self._active_turn_numbers: "OrderedDict[str, int]" = OrderedDict()
         self._active_retrieval_ids: "OrderedDict[str, Optional[str]]" = OrderedDict()
+        self._version_warning_emitted = False
         # Hermes keeps one provider instance alive while compression rotates
         # the physical session id.  Keep only a bounded alias chain so a
         # callback already queued for the parent can still resolve to the
@@ -1506,6 +1540,48 @@ class MemleafMemoryProvider(MemoryProvider):
             _safe_component(turn_id, "none") if turn_id else "none",
         )
 
+    def _check_version_sync(self) -> None:
+        """Warn when the copied provider and MCP core came from different releases."""
+
+        client = self._client
+        if client is None:
+            return
+        # Test doubles and older host integrations may not expose the MCP
+        # initialize metadata.  The real client always does, so only suppress
+        # this check for a double that has no version attribute at all.
+        client_type = _MCPClient
+        is_real_client = isinstance(client_type, type) and isinstance(client, client_type)
+        client_fields = getattr(client, "__dict__", {})
+        if not is_real_client and not (
+            isinstance(client_fields, Mapping) and "server_version" in client_fields
+        ):
+            return
+        provider_version = _provider_manifest_version()
+        core_version = _version_value(getattr(client, "server_version", None))
+        if provider_version is None or core_version is None:
+            if not self._version_warning_emitted:
+                logger.warning(
+                    "memleaf provider/core version check unavailable "
+                    "(provider=%s core=%s); do not assume they are synchronized. "
+                    "Run: %s",
+                    provider_version or "unknown",
+                    core_version or "unknown",
+                    _UPDATE_COMMAND,
+                )
+                self._version_warning_emitted = True
+            return
+        if provider_version == core_version:
+            return
+        if not self._version_warning_emitted:
+            logger.warning(
+                "memleaf provider/core version mismatch (provider=%s core=%s). "
+                "Run: %s",
+                provider_version,
+                core_version,
+                _UPDATE_COMMAND,
+            )
+            self._version_warning_emitted = True
+
     def _queue_turn_number(self, turn_number: Any, message: Any) -> None:
         if isinstance(turn_number, bool) or not isinstance(turn_number, int) or turn_number <= 0:
             return
@@ -1753,6 +1829,7 @@ class MemleafMemoryProvider(MemoryProvider):
         self._pending_lineage.clear()
         self._deferred_process_sessions.clear()
         self._last_retrieval_observation = "unknown"
+        self._version_warning_emitted = False
         if self._client is not None:
             self._client.close()
             self._client = None
@@ -1795,6 +1872,7 @@ class MemleafMemoryProvider(MemoryProvider):
             session_id=self._session_id,
         )
         self._call("stats", {}, stage="stats", session_id=self._session_id)
+        self._check_version_sync()
 
     def system_prompt_block(self) -> str:
         if not self._write_enabled:

{memleaf-0.2.9 → memleaf-0.2.11}/src/memleaf/hermes_provider/plugin.yaml

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

{memleaf-0.2.9 → memleaf-0.2.11}/src/memleaf/installer.py

@@ -6,6 +6,7 @@ import json
 import os
 from importlib import resources
 from pathlib import Path
+import re
 import shutil
 import site
 import stat
@@ -15,6 +16,7 @@ import sysconfig
 import tempfile
 from typing import Any
 
+from . import __version__
 from .adapters.base import update_agents_index
 from .adapters.codex import CodexAdapter
 from .adapters.hermes import HermesAdapter, hermes_home_for_platform
@@ -24,6 +26,7 @@ from .vault import Vault
 
 
 _EXPECTED_TOOLS = 11
+_PROVIDER_VERSION_RE = re.compile(r"^version:\s*([^\s#]+)\s*(?:#.*)?$", re.MULTILINE)
 
 
 def _hermes_home(
@@ -232,6 +235,17 @@ def _copy_provider(hermes_home: Path) -> Path:
     return target
 
 
+def _provider_manifest_version(provider_path: Path) -> str | None:
+    """Read the copied Hermes provider version without requiring a YAML parser."""
+
+    try:
+        text = (provider_path / "plugin.yaml").read_text(encoding="utf-8")
+    except (OSError, UnicodeError):
+        return None
+    match = _PROVIDER_VERSION_RE.search(text)
+    return match.group(1) if match else None
+
+
 def _write_provider_config(path: Path, command: Path, vault: Path) -> None:
     if path.is_symlink():
         raise RuntimeError(f"refusing to write symlinked Hermes config: {path}")
@@ -289,6 +303,7 @@ def _verify_provider(hermes: str) -> bool:
 def install_hermes(*, vault_path: Path | None = None) -> dict[str, Any]:
     """Install and configure memleaf for Hermes from the PyPI package."""
 
+    core_version = __version__
     home = _home_from_environment()
     hermes_home = _hermes_home(home)
     selected_vault, vault_source = _select_vault_path(
@@ -308,6 +323,8 @@ def install_hermes(*, vault_path: Path | None = None) -> dict[str, Any]:
         return {
             "status": "failure",
             "reason": "model route is not configured",
+            "core_version": core_version,
+            "provider_version": None,
             "vault": str(vault.root),
             "model": model,
         }
@@ -318,12 +335,28 @@ def install_hermes(*, vault_path: Path | None = None) -> dict[str, Any]:
         return {
             "status": "failure",
             "reason": "Hermes executable was not found",
+            "core_version": core_version,
+            "provider_version": None,
             "vault": str(vault.root),
             "model": model,
         }
 
     command = _memleaf_mcp_command()
     provider_path = _copy_provider(hermes_home)
+    provider_version = _provider_manifest_version(provider_path)
+    if provider_version != core_version:
+        return {
+            "status": "failure",
+            "reason": (
+                "Hermes provider version mismatch after copy: "
+                f"core={core_version}, provider={provider_version or 'unknown'}"
+            ),
+            "core_version": core_version,
+            "provider_version": provider_version,
+            "vault": str(vault.root),
+            "provider": str(provider_path),
+            "model": model,
+        }
     _write_provider_config(hermes_home / "memleaf.json", command, vault.root)
 
     activated = _run([detection.executable, "config", "set", "memory.provider", "memleaf"])
@@ -331,6 +364,8 @@ def install_hermes(*, vault_path: Path | None = None) -> dict[str, Any]:
         return {
             "status": "failure",
             "reason": "Hermes MemoryProvider could not be activated",
+            "core_version": core_version,
+            "provider_version": provider_version,
             "vault": str(vault.root),
             "provider": str(provider_path),
             "model": model,
@@ -348,6 +383,8 @@ def install_hermes(*, vault_path: Path | None = None) -> dict[str, Any]:
         return {
             "status": "failure",
             "reason": "Hermes MCP entry could not be configured",
+            "core_version": core_version,
+            "provider_version": provider_version,
             "vault": str(vault.root),
             "provider": str(provider_path),
             "model": model,
@@ -357,6 +394,8 @@ def install_hermes(*, vault_path: Path | None = None) -> dict[str, Any]:
         return {
             "status": "failure",
             "reason": "Hermes MCP lifecycle could not be configured",
+            "core_version": core_version,
+            "provider_version": provider_version,
             "vault": str(vault.root),
             "provider": str(provider_path),
             "model": model,
@@ -369,6 +408,8 @@ def install_hermes(*, vault_path: Path | None = None) -> dict[str, Any]:
         return {
             "status": "failure",
             "reason": "Hermes MCP test did not confirm 11 tools",
+            "core_version": core_version,
+            "provider_version": provider_version,
             "vault": str(vault.root),
             "provider": str(provider_path),
             "model": model,
@@ -395,6 +436,8 @@ def install_hermes(*, vault_path: Path | None = None) -> dict[str, Any]:
     return {
         "status": "configured",
         "reason": "memleaf is fully configured for Hermes",
+        "core_version": core_version,
+        "provider_version": provider_version,
         "vault": str(vault.root),
         "vault_source": vault_source,
         "provider": str(provider_path),