memleaf 0.2.16__tar.gz → 0.2.18__tar.gz

{memleaf-0.2.16 → memleaf-0.2.18}/CHANGELOG.md

@@ -2,6 +2,23 @@
 
 All notable changes to memleaf are documented here.
 
+## 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
+  related active todo as an in-place state update, even when the gate omits the
+  candidate or the same message asks what remains.
+- Keep todo-state recovery deterministic and bounded: reuse the existing
+  memory ID, anchor `completed_at` to the user event, archive the old version,
+  and reject queries, negation, future intent, uncertainty, assistant-only
+  claims, and ambiguous targets.
+
 ## 0.2.16 — 2026-09-02
 
 - Keep read-only operational queries, derived overdue counters, and one-time

{memleaf-0.2.16/src/memleaf.egg-info → memleaf-0.2.18}/PKG-INFO

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

{memleaf-0.2.16 → memleaf-0.2.18}/README.en.md

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

{memleaf-0.2.16 → memleaf-0.2.18}/README.md

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

{memleaf-0.2.16 → memleaf-0.2.18}/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.16 → memleaf-0.2.18}/pyproject.toml

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

{memleaf-0.2.16 → memleaf-0.2.18}/src/memleaf/__init__.py

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

@@ -1181,6 +1181,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 +1874,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 +2119,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 +2155,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 +2179,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 +2208,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 +2368,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 +2376,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.16 → memleaf-0.2.18}/src/memleaf/hermes_provider/plugin.yaml

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

{memleaf-0.2.16 → memleaf-0.2.18}/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.18/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"]