memleaf 0.2.23__tar.gz → 0.2.25__tar.gz

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

@@ -2,6 +2,26 @@
 
 All notable changes to memleaf are documented here.
 
+## 0.2.25 — 2026-09-04
+
+- Keep global todo questions and cross-session recaps strictly read-only,
+  without creating memories, appending sources, or producing history; an
+  explicit user assertion before a follow-up question remains write-eligible.
+- Recover project-grounded, explicitly counted repair items omitted from a
+  mailbox extraction gate, split concrete detail lines into independent todos,
+  and reuse an existing same-scope item when it is an update.
+- Record compact candidate-level `CREATE`, `UPDATE`, `NO_CHANGE`, and
+  `DEFERRED` dispositions in the processed-turn ledger for auditable coverage.
+
+## 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.25}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: memleaf
-Version: 0.2.23
+Version: 0.2.25
 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.25。**
+> 核心库、Vault、stdio MCP Server、初始化 CLI、模型路由、提炼流程、受控检索协议和宿主适配器已经实现。memleaf 0.2.25 通过 PyPI 分发。
 > **当前版本支持 Hermes 和 Codex。** Antigravity（反重力）不检测、不安装、不配置。
 
 ## 项目定位

{memleaf-0.2.23 → memleaf-0.2.25}/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.25.**
+> The core library, Vault, stdio MCP server, initialization CLI, model routing, memory extraction, controlled retrieval protocol, and host adapters are implemented. memleaf 0.2.25 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.25}/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.25。**
+> 核心库、Vault、stdio MCP Server、初始化 CLI、模型路由、提炼流程、受控检索协议和宿主适配器已经实现。memleaf 0.2.25 通过 PyPI 分发。
 > **当前版本支持 Hermes 和 Codex。** Antigravity（反重力）不检测、不安装、不配置。
 
 ## 项目定位

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

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

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

@@ -1,6 +1,6 @@
 """Local-first Markdown memory core for AI agents."""
 
-__version__ = "0.2.23"
+__version__ = "0.2.25"
 
 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.25}/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.25}/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.25}/src/memleaf/hermes_provider/plugin.yaml

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