memleaf 0.2.17__tar.gz → 0.2.19__tar.gz

{memleaf-0.2.17 → memleaf-0.2.19}/CHANGELOG.md

@@ -2,6 +2,22 @@
 
 All notable changes to memleaf are documented here.
 
+## 0.2.19 — 2026-09-03
+
+- Keep Hermes `<untrusted_tool_result>` search audit status synchronized with
+  Core for `FOUND` and `NO_MATCH` results using bounded, strict decoding;
+  malformed and error envelopes remain audit errors.
+- After three `mixed_future_use` gate responses, defer only the affected
+  candidate so valid candidates from the same turn can continue processing;
+  mixed content is never persisted and unrelated schema violations still fail.
+
+## 0.2.18 — 2026-09-02
+
+- Register Hermes native `MEMORY.md` and `USER.md` as private, read-only native sources during supported install/upgrade flows while preserving custom native source configuration.
+- Harden cross-turn deduplication and UPDATE/NO_CHANGE decisions: split independent future-use clauses, reuse one unambiguous same-scope active target, treat exact active duplicates as deterministic no-ops, and keep crash replay idempotent.
+- Preserve the existing bounded Scope Map / metadata-directory retrieval flow without adding extra scope scans during automatic deduplication.
+- Distinguish Hermes controlled read audit states: record `FOUND_READ` only after a current-token successful read, and use `FOUND_NO_READ_UNDETERMINED` when a FOUND result has no provable controlled read instead of overstating Soft Gate guarantees.
+
 ## 0.2.17 — 2026-09-02
 
 - Preserve explicit user-confirmed completion or cancellation of one uniquely

{memleaf-0.2.17/src/memleaf.egg-info → memleaf-0.2.19}/PKG-INFO

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

{memleaf-0.2.17 → memleaf-0.2.19}/README.en.md

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

{memleaf-0.2.17 → memleaf-0.2.19}/README.md

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

{memleaf-0.2.17 → memleaf-0.2.19}/install.sh

@@ -347,6 +347,23 @@ PY
     die "Hermes memleaf MCP configuration/test failed"
   fi
 
+  # Register Hermes' own MEMORY.md and USER.md as private, read-only native
+  # sources only after both provider and MCP checks have succeeded. Missing
+  # files remain a valid indexed state and are never created by memleaf.
+  "$venv_path/bin/python" - "$vault_path" "$hermes_home" <<'PY'
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+from memleaf.native_registration import ensure_hermes_native_sources
+from memleaf.vault import Vault
+
+vault = Vault(Path(sys.argv[1]).expanduser().resolve())
+hermes_home = Path(sys.argv[2]).expanduser().resolve()
+ensure_hermes_native_sources(vault, hermes_home)
+PY
+
   # The MCP status is written only after its own official test succeeds.  This
   # merge changes no Provider or other host fields.
   "$venv_path/bin/python" - "$vault_path" <<'PY'

{memleaf-0.2.17 → memleaf-0.2.19}/pyproject.toml

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

{memleaf-0.2.17 → memleaf-0.2.19}/src/memleaf/__init__.py

@@ -1,6 +1,6 @@
 """Local-first Markdown memory core for AI agents."""
 
-__version__ = "0.2.17"
+__version__ = "0.2.19"
 
 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.17 → memleaf-0.2.19}/src/memleaf/hermes_provider/__init__.py

@@ -387,47 +387,66 @@ def _scope_context(
 def _hermes_search_status(value: Any) -> str:
     """Classify an observed MCP search result without retaining its content."""
 
-    decoded: Any = value
-    if isinstance(decoded, list):
-        for item in decoded:
-            if isinstance(item, Mapping) and item.get("type") == "text":
-                decoded = item.get("text")
-                break
-    if isinstance(decoded, str):
-        try:
-            decoded = json.loads(decoded)
-        except (TypeError, ValueError):
-            return "error"
-    if not isinstance(decoded, Mapping):
-        return "error"
-    if decoded.get("isError") is True:
-        return "error"
-    nested = decoded.get("structuredContent")
-    if isinstance(nested, Mapping):
-        decoded = nested.get("result") if isinstance(nested.get("result"), Mapping) else nested
-    elif isinstance(decoded.get("content"), list):
-        return _hermes_search_status(decoded["content"])
-    if not isinstance(decoded, Mapping) or "error" in decoded:
-        return "error"
-    status = decoded.get("status")
-    results = decoded.get("results")
-    if status not in {"found", "no_match"} or not isinstance(results, list):
-        return "error"
-    valid_results = all(
-        isinstance(item, Mapping)
-        and set(item) == {"memory_id", "title"}
-        and isinstance(item.get("memory_id"), str)
-        and bool(item.get("memory_id"))
-        and isinstance(item.get("title"), str)
-        and bool(item.get("title"))
-        for item in results
-    )
-    if not valid_results:
+    if value is _CALL_FAILED or value is None:
         return "error"
-    if status == "found" and results:
-        return "found"
-    if status == "no_match" and not results:
-        return "no_match"
+    decoded: Any = _decode_hermes_tool_result(value)
+    for _ in range(_MAX_TOOL_RESULT_LAYERS):
+        if decoded is _MISSING_TOOL_RESULT:
+            return "error"
+        if isinstance(decoded, str):
+            decoded = _decode_hermes_tool_result(decoded)
+            continue
+        if isinstance(decoded, list):
+            text_item = next(
+                (
+                    item
+                    for item in decoded
+                    if isinstance(item, Mapping) and item.get("type") == "text"
+                ),
+                None,
+            )
+            if text_item is None:
+                return "error"
+            decoded = _decode_hermes_tool_result(text_item.get("text"))
+            continue
+        if not isinstance(decoded, Mapping):
+            return "error"
+        if decoded.get("isError") is True or decoded.get("error") is not None:
+            return "error"
+
+        status = decoded.get("status")
+        results = decoded.get("results")
+        if status is not None or results is not None:
+            if status not in {"found", "no_match"} or not isinstance(results, list):
+                return "error"
+            valid_results = all(
+                isinstance(item, Mapping)
+                and set(item) == {"memory_id", "title"}
+                and isinstance(item.get("memory_id"), str)
+                and bool(item.get("memory_id"))
+                and isinstance(item.get("title"), str)
+                and bool(item.get("title"))
+                for item in results
+            )
+            if not valid_results:
+                return "error"
+            if status == "found" and results:
+                return "found"
+            if status == "no_match" and not results:
+                return "no_match"
+            return "error"
+
+        nested = next(
+            (
+                decoded[key]
+                for key in ("structuredContent", "result", "content")
+                if isinstance(decoded.get(key), (Mapping, list, str))
+            ),
+            _MISSING_TOOL_RESULT,
+        )
+        if nested is _MISSING_TOOL_RESULT:
+            return "error"
+        decoded = _decode_hermes_tool_result(nested)
     return "error"
 
 
@@ -1181,6 +1200,7 @@ class MemleafMemoryProvider(MemoryProvider):
         # under the original session id after the chain is restored.
         self._deferred_process_sessions: "OrderedDict[str, None]" = OrderedDict()
         self._last_retrieval_observation = "unknown"
+        self._last_retrieval_audit = "SEARCH_UNKNOWN"
 
     @property
     def name(self) -> str:
@@ -1873,6 +1893,7 @@ class MemleafMemoryProvider(MemoryProvider):
         self._pending_lineage.clear()
         self._deferred_process_sessions.clear()
         self._last_retrieval_observation = "unknown"
+        self._last_retrieval_audit = "SEARCH_UNKNOWN"
         self._version_warning_emitted = False
         if self._client is not None:
             self._client.close()
@@ -2117,6 +2138,7 @@ class MemleafMemoryProvider(MemoryProvider):
         turn_id: str = "",
         vault_root: Optional[Path] = None,
         seen_call_keys: Any = None,
+        audit_state: Optional[dict[str, Any]] = None,
     ) -> str:
         """Observe explicit host MCP calls in public messages.
 
@@ -2152,6 +2174,7 @@ class MemleafMemoryProvider(MemoryProvider):
 
         read_results_used: set[int] = set()
         read_sequence = 0
+        controlled_reads = 0
         read_ordinal = 0
         for call in calls:
             if call.get("name") != "mcp__memleaf__read":
@@ -2175,6 +2198,8 @@ class MemleafMemoryProvider(MemoryProvider):
             if not _record_tool_observation(seen_call_keys, observation_key):
                 continue
             read_sequence += 1
+            if result_status == "ok" and retrieval_match:
+                controlled_reads += 1
             logger.info(
                 "memleaf retrieval-read source=hermes session=%s turn=%s read_seq=%d retrieval_present=%s retrieval_match=%s result=%s",
                 _safe_component(session_id, "none") if session_id else "none",
@@ -2202,12 +2227,39 @@ class MemleafMemoryProvider(MemoryProvider):
                 "detected" if bypass else "not_detected",
             )
         if not statuses:
-            return "unknown"
-        if "found" in statuses:
-            return "found"
-        if "no_match" in statuses:
-            return "no_match"
-        return "error"
+            search_status = "unknown"
+            audit_status = "SEARCH_UNKNOWN"
+        elif "found" in statuses:
+            search_status = "found"
+            # Hermes exposes no public pre-final hook and no reliable signal
+            # that proves whether an answer used historical memory when no
+            # controlled read occurred. Do not fabricate FOUND_NOT_USED or
+            # FOUND_REQUIRED_READ_MISSING; record the uncertainty explicitly.
+            audit_status = "FOUND_READ" if controlled_reads else "FOUND_NO_READ_UNDETERMINED"
+        elif "no_match" in statuses:
+            search_status = "no_match"
+            audit_status = "NO_MATCH"
+        else:
+            search_status = "error"
+            audit_status = "ERROR"
+        if isinstance(audit_state, dict):
+            audit_state.clear()
+            audit_state.update(
+                {
+                    "status": audit_status,
+                    "search_status": search_status,
+                    "controlled_reads": controlled_reads,
+                }
+            )
+        logger.info(
+            "memleaf retrieval-audit source=hermes session=%s turn=%s status=%s search=%s controlled_reads=%d",
+            _safe_component(session_id, "none") if session_id else "none",
+            _safe_component(turn_id, "none") if turn_id else "none",
+            audit_status,
+            search_status,
+            controlled_reads,
+        )
+        return search_status
 
     @staticmethod
     def _catalog_retrieval_id(value: Any) -> Optional[str]:
@@ -2335,6 +2387,7 @@ class MemleafMemoryProvider(MemoryProvider):
                 if retrieval_id is None and resolved_turn_number is None:
                     retrieval_id = self._current_gate_id(effective_session)
                 if self._gate_enabled:
+                    audit_state: dict[str, Any] = {}
                     observation = self._observe_search_messages(
                         messages,
                         retrieval_id,
@@ -2342,10 +2395,12 @@ class MemleafMemoryProvider(MemoryProvider):
                         turn_id=turn_id,
                         vault_root=_resolve_vault(self._config()),
                         seen_call_keys=self._observed_tool_call_keys,
+                        audit_state=audit_state,
                     )
                     while len(self._observed_tool_call_keys) > _MAX_OBSERVED_TOOL_CALL_KEYS:
                         self._observed_tool_call_keys.popitem(last=False)
                     self._last_retrieval_observation = observation
+                    self._last_retrieval_audit = str(audit_state.get("status") or "SEARCH_UNKNOWN")
                 lineage_ready = self._retry_pending_lineage(effective_session)
                 for role, content in visible_events:
                     if not self._capture_visible(

{memleaf-0.2.17 → memleaf-0.2.19}/src/memleaf/hermes_provider/plugin.yaml

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

{memleaf-0.2.17 → memleaf-0.2.19}/src/memleaf/installer.py

@@ -22,6 +22,7 @@ from .adapters.codex import CodexAdapter
 from .adapters.hermes import HermesAdapter, hermes_home_for_platform
 from .cli import _home_from_environment, _prepare_model_route
 from .locking import atomic_write_json
+from .native_registration import ensure_hermes_native_sources
 from .vault import Vault
 
 
@@ -415,6 +416,19 @@ def install_hermes(*, vault_path: Path | None = None) -> dict[str, Any]:
             "model": model,
         }
 
+    try:
+        native_registration = ensure_hermes_native_sources(vault, hermes_home)
+    except Exception:
+        return {
+            "status": "failure",
+            "reason": "Hermes native memory sources could not be registered safely",
+            "core_version": core_version,
+            "provider_version": provider_version,
+            "vault": str(vault.root),
+            "provider": str(provider_path),
+            "model": model,
+        }
+
     update_agents_index(
         vault.agents_index_path,
         {
@@ -443,6 +457,7 @@ def install_hermes(*, vault_path: Path | None = None) -> dict[str, Any]:
         "provider": str(provider_path),
         "mcp_command": str(command),
         "model": model,
+        "native_sources": native_registration,
     }
 
 

memleaf-0.2.19/src/memleaf/native_registration.py

@@ -0,0 +1,123 @@
+"""Host-native source registration helpers.
+
+This module owns only configuration of read-only native sources.  It never
+creates, writes, renames, or removes a host's native memory files.
+"""
+
+from __future__ import annotations
+
+from copy import deepcopy
+from pathlib import Path
+from typing import Any, Mapping
+
+from .config import save_config
+from .native_index import NativeIndexer, validate_native_sources
+
+
+_HERMES_SOURCES = (
+    ("hermes_memory", "hermes_memory_builtin", "MEMORY.md"),
+    ("hermes_user", "hermes_user_builtin", "USER.md"),
+)
+
+
+def _same_path(left: str | Path, right: str | Path) -> bool:
+    try:
+        return Path(left).expanduser().resolve(strict=False) == Path(right).expanduser().resolve(strict=False)
+    except (OSError, RuntimeError, ValueError):
+        return False
+
+
+def _desired(path: Path) -> dict[str, Any]:
+    return {
+        "agent": "hermes",
+        "path": str(path.expanduser().resolve(strict=False)),
+        "share": False,
+        "format": "markdown",
+    }
+
+
+def _safe_existing_for_hermes(source: Mapping[str, Any], path: Path) -> bool:
+    return (
+        source.get("agent") == "hermes"
+        and source.get("share") is False
+        and source.get("format", "markdown") == "markdown"
+        and _same_path(str(source.get("path", "")), path)
+    )
+
+
+def ensure_hermes_native_sources(vault: Any, hermes_home: Path | str) -> dict[str, Any]:
+    """Idempotently register Hermes MEMORY.md and USER.md as private sources.
+
+    Existing user-defined native sources are preserved.  A semantic conflict
+    fails closed instead of silently changing the user's source or exposing a
+    private Hermes file to another agent.
+    """
+
+    home = Path(hermes_home).expanduser().resolve(strict=False)
+    targets = [(canonical, fallback, home / "memories" / filename) for canonical, fallback, filename in _HERMES_SOURCES]
+
+    with vault.lock():
+        config = vault.config()
+        existing_value = config.get("native_sources", {})
+        if not isinstance(existing_value, Mapping):
+            raise RuntimeError("invalid native_sources configuration")
+        sources: dict[str, dict[str, Any]] = {
+            str(source_id): deepcopy(dict(source))
+            for source_id, source in existing_value.items()
+            if isinstance(source_id, str) and isinstance(source, Mapping)
+        }
+        # Validate before touching anything.  This also catches duplicate paths
+        # already present in a manually edited configuration.
+        validate_native_sources(sources, base_dir=vault.root)
+        changed = False
+        registered: dict[str, str] = {}
+
+        for canonical, fallback, path in targets:
+            desired = _desired(path)
+            path_owner = next(
+                (
+                    source_id
+                    for source_id, source in sources.items()
+                    if _same_path(str(source.get("path", "")), path)
+                ),
+                None,
+            )
+            if path_owner is not None:
+                current = sources[path_owner]
+                if not _safe_existing_for_hermes(current, path):
+                    raise RuntimeError(f"unsafe Hermes native source conflict: {path_owner}")
+                registered[canonical] = path_owner
+                continue
+
+            target_id = canonical
+            if target_id in sources:
+                if _safe_existing_for_hermes(sources[target_id], path):
+                    registered[canonical] = target_id
+                    continue
+                target_id = fallback
+                if target_id in sources and not _safe_existing_for_hermes(sources[target_id], path):
+                    raise RuntimeError(f"Hermes native source id conflict: {canonical}")
+
+            if target_id not in sources:
+                sources[target_id] = desired
+                changed = True
+            registered[canonical] = target_id
+
+        if changed:
+            updated = deepcopy(dict(config))
+            updated["native_sources"] = sources
+            save_config(vault.config_path, updated)
+
+        # Refresh the derived index under the same vault lock. Missing native
+        # files are a valid state and are represented as unavailable entries;
+        # this function never creates them.
+        index_summary = NativeIndexer(vault).refresh_unlocked()
+
+    return {
+        "changed": changed,
+        "sources": registered,
+        "index": index_summary,
+    }
+
+
+__all__ = ["ensure_hermes_native_sources"]