memleaf 0.2.22__tar.gz → 0.2.23__tar.gz

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

@@ -2,6 +2,14 @@
 
 All notable changes to memleaf are documented here.
 
+## 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.
+- Deterministically split same-project `mixed_future_use` candidates after bounded model retries only when every clause is safely classifiable as durable project/fact state or an unfinished todo; ambiguous fragments remain deferred and valid siblings continue independently.
+- Add bounded mail-tool evidence capture limited to message ID, subject, sender and sender domain, plus private per-scope domain identifiers; a unique domain/scope conflict defers extraction instead of writing a wrongly attributed project memory, while full tool output remains excluded.
+- Preserve global `list_todos` pagination and unlimited aggregate managed reads from 0.2.20; no source/session ownership filter or aggregate read quota is reintroduced.
+- Hermes still uses its existing Soft Gate in this package release. Generic fail-closed pre-final retrieval enforcement requires a Hermes host lifecycle hook and is tracked upstream in NousResearch/hermes-agent#101973.
+
 ## 0.2.22 — 2026-09-03
 
 - Safely split valid multi-project `unscoped` aggregate candidates using only

{memleaf-0.2.22/src/memleaf.egg-info → memleaf-0.2.23}/PKG-INFO

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

{memleaf-0.2.22 → memleaf-0.2.23}/README.en.md

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

{memleaf-0.2.22 → memleaf-0.2.23}/README.md

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

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

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

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

@@ -1,6 +1,6 @@
 """Local-first Markdown memory core for AI agents."""
 
-__version__ = "0.2.22"
+__version__ = "0.2.23"
 
 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.22 → memleaf-0.2.23}/src/memleaf/capture.py

@@ -6,7 +6,7 @@ import json
 import re
 from datetime import datetime, timezone
 from pathlib import Path
-from typing import Optional
+from typing import Any, Mapping, Optional
 
 from .index import (
     EVENT_CONTENT,
@@ -28,6 +28,45 @@ def _timestamp() -> str:
     return datetime.now(timezone.utc).isoformat(timespec="seconds").replace("+00:00", "Z")
 
 
+
+_MAIL_EVIDENCE_FIELDS = frozenset({"message_id", "subject", "sender", "domain"})
+_MAIL_DOMAIN_RE = re.compile(r"^(?=.{1,253}$)(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z]{2,63}$", re.IGNORECASE)
+_MAX_MAIL_EVIDENCE_ITEMS = 8
+_MAX_MAIL_EVIDENCE_TEXT = 320
+
+
+def _normalize_tool_evidence(value: Any) -> list[dict[str, str]]:
+    if value is None:
+        return []
+    if not isinstance(value, (list, tuple)):
+        raise ValueError("tool evidence must be a list")
+    result: list[dict[str, str]] = []
+    seen: set[tuple[tuple[str, str], ...]] = set()
+    for raw in list(value)[:_MAX_MAIL_EVIDENCE_ITEMS]:
+        if not isinstance(raw, Mapping) or set(raw) - _MAIL_EVIDENCE_FIELDS:
+            raise ValueError("invalid tool evidence record")
+        item: dict[str, str] = {}
+        for key in _MAIL_EVIDENCE_FIELDS:
+            field = raw.get(key)
+            if field is None:
+                continue
+            if not isinstance(field, str) or not field.strip() or any(ch in field for ch in "\x00\r\n"):
+                raise ValueError("invalid tool evidence field")
+            text = redact_text(field.strip())[:_MAX_MAIL_EVIDENCE_TEXT]
+            if key == "domain":
+                text = text.casefold().lstrip("@")
+                if not _MAIL_DOMAIN_RE.fullmatch(text):
+                    raise ValueError("invalid tool evidence domain")
+            item[key] = text
+        if not item:
+            continue
+        fingerprint = tuple(sorted(item.items()))
+        if fingerprint in seen:
+            continue
+        seen.add(fingerprint)
+        result.append(item)
+    return result
+
 def _event_id(source: str, session_id: str, turn_id: str, role: str, event_id: Optional[str]) -> str:
     if event_id is not None:
         if not isinstance(event_id, str) or not event_id or "\x00" in event_id or "\n" in event_id or "\r" in event_id:
@@ -149,6 +188,7 @@ def _append_event(
     event_digest: str,
     event_turn_key: str,
     turn_index: int,
+    tool_evidence: list[dict[str, str]] | None = None,
 ) -> str:
     timestamp = _timestamp()
     if not existing:
@@ -168,6 +208,8 @@ def _append_event(
         "turn_index": turn_index,
         "timestamp": timestamp,
     }
+    if tool_evidence:
+        metadata["tool_evidence"] = [dict(item) for item in tool_evidence]
     metadata_line = json.dumps(metadata, ensure_ascii=False, sort_keys=True, separators=(",", ":"))
     return (
         f"{updated}{EVENT_START}\n"
@@ -207,6 +249,7 @@ def capture_event(
     event_id: Optional[str] = None,
     record: bool = True,
     visible: bool = True,
+    tool_evidence: Any = None,
 ) -> CaptureResult:
     """Capture one visible event; all persisted text is redacted first."""
 
@@ -222,6 +265,7 @@ def capture_event(
     resolved_turn_key = turn_key(turn_id)
     persisted_turn_id = _safe_turn_id(turn_id)
     safe_content = escape_event_markers(redact_text(content))
+    safe_tool_evidence = _normalize_tool_evidence(tool_evidence)
     if not record or not visible or role not in ("user", "assistant"):
         return CaptureResult(resolved_event_id, stored=False, duplicate=False, content=safe_content)
 
@@ -266,6 +310,7 @@ def capture_event(
             resolved_event_key,
             resolved_turn_key,
             turn_index,
+            safe_tool_evidence,
         )
         atomic_write_text(path, updated)
 

{memleaf-0.2.22 → memleaf-0.2.23}/src/memleaf/hermes_provider/__init__.py

@@ -108,6 +108,11 @@ _UNTRUSTED_TOOL_RESULT_TAG = "<untrusted_tool_result"
 _UNTRUSTED_TOOL_RESULT_END = "</untrusted_tool_result>"
 
 
+_MAX_MAIL_EVIDENCE_ITEMS = 8
+_MAIL_ADDRESS_RE = re.compile(r"(?i)([A-Z0-9._%+-]+@([A-Z0-9.-]+\.[A-Z]{2,63}))")
+_MAIL_TOOL_RE = re.compile(r"(?:gmail|outlook|mail|email)", re.IGNORECASE)
+
+
 class _MCPToolError(RuntimeError):
     """Safe structured model error returned by the local MCP boundary."""
 
@@ -1152,6 +1157,83 @@ def _resolve_command(config: Mapping[str, Any]) -> Optional[str]:
     )
 
 
+def _bounded_mail_evidence(messages: Optional[List[Dict[str, Any]]]) -> list[dict[str, str]]:
+    """Extract only message id/subject/sender/domain from visible mail tool results."""
+
+    calls = _visible_tool_calls(messages)
+    results = _visible_tool_results(messages)
+    used: set[int] = set()
+    output: list[dict[str, str]] = []
+    seen: set[tuple[tuple[str, str], ...]] = set()
+
+    def add_record(mapping: Mapping[str, Any]) -> None:
+        if len(output) >= _MAX_MAIL_EVIDENCE_ITEMS:
+            return
+        lowered = {str(key).casefold(): value for key, value in mapping.items()}
+        message_id = next((lowered.get(key) for key in ("message_id", "messageid", "id") if isinstance(lowered.get(key), (str, int))), None)
+        subject = next((lowered.get(key) for key in ("subject", "title") if isinstance(lowered.get(key), str)), None)
+        sender = next((lowered.get(key) for key in ("sender", "from", "from_address", "from_email", "email") if isinstance(lowered.get(key), str)), None)
+        domain = next((lowered.get(key) for key in ("domain", "sender_domain") if isinstance(lowered.get(key), str)), None)
+        if isinstance(sender, str):
+            match = _MAIL_ADDRESS_RE.search(sender)
+            if match and not domain:
+                domain = match.group(2)
+        item: dict[str, str] = {}
+        for key, value, limit in (
+            ("message_id", message_id, 160),
+            ("subject", subject, 320),
+            ("sender", sender, 320),
+            ("domain", domain, 253),
+        ):
+            if value is None:
+                continue
+            text = str(value).strip()
+            if not text or any(ch in text for ch in "\x00\r\n"):
+                continue
+            if key == "domain":
+                text = text.casefold().lstrip("@")
+                if not re.fullmatch(r"(?=.{1,253}$)(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z]{2,63}", text):
+                    continue
+            item[key] = text[:limit]
+        if "domain" not in item:
+            return
+        fingerprint = tuple(sorted(item.items()))
+        if fingerprint not in seen:
+            seen.add(fingerprint)
+            output.append(item)
+
+    def visit(value: Any, depth: int = 0) -> None:
+        if depth > 4 or len(output) >= _MAX_MAIL_EVIDENCE_ITEMS:
+            return
+        decoded = _decode_hermes_tool_result(value)
+        if decoded is _MISSING_TOOL_RESULT:
+            return
+        if decoded is not value:
+            visit(decoded, depth + 1)
+            return
+        if isinstance(value, Mapping):
+            add_record(value)
+            for child in value.values():
+                if isinstance(child, (Mapping, list, tuple)):
+                    visit(child, depth + 1)
+        elif isinstance(value, (list, tuple)):
+            for child in value:
+                visit(child, depth + 1)
+
+    ordinal = 0
+    for call in calls:
+        name = call.get("name")
+        if not isinstance(name, str) or not _MAIL_TOOL_RE.search(name):
+            continue
+        ordinal += 1
+        payload = _tool_result_for_call(call, calls, results, used)
+        if payload is not _CALL_FAILED:
+            visit(payload)
+        if len(output) >= _MAX_MAIL_EVIDENCE_ITEMS:
+            break
+    return output
+
+
 class MemleafMemoryProvider(MemoryProvider):
     """Use the local memleaf vault as Hermes' single external provider."""
 
@@ -2115,7 +2197,15 @@ class MemleafMemoryProvider(MemoryProvider):
         )
         return result
 
-    def _capture_visible(self, *, session_id: str, turn_id: str, role: str, content: str) -> bool:
+    def _capture_visible(
+        self,
+        *,
+        session_id: str,
+        turn_id: str,
+        role: str,
+        content: str,
+        tool_evidence: Optional[List[Dict[str, str]]] = None,
+    ) -> bool:
         result = self._call(
             "capture",
             {
@@ -2126,6 +2216,7 @@ class MemleafMemoryProvider(MemoryProvider):
                 "content": content,
                 "record": True,
                 "visible": True,
+                **({"tool_evidence": tool_evidence} if tool_evidence else {}),
             },
             stage=f"capture_{role}",
             session_id=session_id,
@@ -2414,12 +2505,14 @@ class MemleafMemoryProvider(MemoryProvider):
                     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)
+                mail_evidence = _bounded_mail_evidence(messages)
                 for role, content in visible_events:
                     if not self._capture_visible(
                         session_id=effective_session,
                         turn_id=turn_id,
                         role=role,
                         content=content,
+                        tool_evidence=mail_evidence if role == "assistant" else None,
                     ):
                         return
                 if not self._auto_process:

{memleaf-0.2.22 → memleaf-0.2.23}/src/memleaf/hermes_provider/plugin.yaml

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

{memleaf-0.2.22 → memleaf-0.2.23}/src/memleaf/inbox.py

@@ -13,7 +13,7 @@ import json
 import re
 from dataclasses import dataclass
 from pathlib import Path
-from typing import Any, Iterable, Optional
+from typing import Any, Iterable, Mapping, Optional
 
 from .index import EVENT_V2_BLOCK, extract_event_metadata
 
@@ -32,6 +32,7 @@ class InboxEvent:
     content: str
     turn_id: Optional[str] = None
     timestamp: Optional[str] = None
+    tool_evidence: tuple[dict[str, str], ...] = ()
     legacy: bool = False
 
     @property
@@ -107,6 +108,30 @@ def _event_metadata(text: str) -> list[dict[str, Any]]:
     return result
 
 
+
+def _bounded_tool_evidence(value: Any) -> tuple[dict[str, str], ...]:
+    if not isinstance(value, list):
+        return ()
+    allowed = {"message_id", "subject", "sender", "domain"}
+    result: list[dict[str, str]] = []
+    for raw in value[:8]:
+        if not isinstance(raw, Mapping) or set(raw) - allowed:
+            continue
+        item = {
+            str(key): str(field)
+            for key, field in raw.items()
+            if key in allowed
+            and isinstance(field, str)
+            and field
+            and "\x00" not in field
+            and "\r" not in field
+            and "\n" not in field
+            and len(field) <= 320
+        }
+        if item:
+            result.append(item)
+    return tuple(result)
+
 def parse_inbox_text(
     text: str,
     *,
@@ -180,6 +205,7 @@ def parse_inbox_text(
                     content=str(metadata.get("content", "")),
                     turn_id=display_turn_id if isinstance(display_turn_id, str) else None,
                     timestamp=metadata.get("timestamp") if isinstance(metadata.get("timestamp"), str) else None,
+                    tool_evidence=_bounded_tool_evidence(metadata.get("tool_evidence")),
                     legacy=not groupable,
                 )
             )
@@ -195,6 +221,7 @@ def parse_inbox_text(
                 content=str(metadata.get("content", "")),
                 turn_id=display_turn_id,
                 timestamp=metadata.get("timestamp") if isinstance(metadata.get("timestamp"), str) else None,
+                tool_evidence=_bounded_tool_evidence(metadata.get("tool_evidence")),
             )
         )
 

{memleaf-0.2.22 → memleaf-0.2.23}/src/memleaf/mcp_server.py

@@ -138,6 +138,17 @@ _TOOLS: tuple[dict[str, Any], ...] = (
                 "event_id": {"type": "string"},
                 "record": {"type": "boolean"},
                 "visible": {"type": "boolean"},
+                "tool_evidence": {
+                    "type": "array",
+                    "items": _object_schema(
+                        {
+                            "message_id": {"type": "string"},
+                            "subject": {"type": "string"},
+                            "sender": {"type": "string"},
+                            "domain": {"type": "string"},
+                        }
+                    ),
+                },
             },
             required=["source", "session_id", "turn_id", "role", "content"],
         ),

{memleaf-0.2.22 → memleaf-0.2.23}/src/memleaf/memory_writer.py

@@ -160,6 +160,26 @@ class MemoryWriter:
         duplicate_ids: set[str] = set()
         memory_ids: set[str] = set()
         for request in requests:
+            correction = request.get("scope_correction")
+            if isinstance(correction, Mapping) and correction.get("survivor_memory_id"):
+                target_id = correction.get("target_memory_id")
+                survivor_id = correction.get("survivor_memory_id")
+                if not isinstance(target_id, str) or not isinstance(survivor_id, str) or target_id == survivor_id:
+                    raise self._preflight_error("invalid scope correction targets")
+                target_record = active.get(target_id)
+                survivor_record = active.get(survivor_id)
+                if target_record is None or survivor_record is None:
+                    raise self._preflight_error("scope correction target is not active")
+                target_memory = getattr(target_record, "memory", target_record)
+                survivor_memory = getattr(survivor_record, "memory", survivor_record)
+                if not isinstance(target_memory, Memory) or not isinstance(survivor_memory, Memory):
+                    raise self._preflight_error("scope correction memory is invalid")
+                if target_memory.type != survivor_memory.type or survivor_memory.type != request["summary"].get("type"):
+                    raise self._preflight_error("scope correction type mismatch")
+                if request.get("memory_id") != survivor_id:
+                    raise self._preflight_error("scope correction survivor id mismatch")
+                active.pop(target_id, None)
+                continue
             summary = request["summary"]
             duplicate_id = request.get("duplicate_memory_id")
             if duplicate_id is not None:
@@ -338,7 +358,14 @@ class MemoryWriter:
             values = [scope for scope in values if scope != "unscoped"]
         return values or ["global"]
 
-    def _write_history(self, old: Memory, *, superseded_by: str, archived_at: str) -> str:
+    def _write_history(
+        self,
+        old: Memory,
+        *,
+        superseded_by: str,
+        archived_at: str,
+        invalidated_reason: str | None = None,
+    ) -> str:
         history_id = self._history_id(old)
         extra = dict(old.extra)
         extra.update(
@@ -348,6 +375,8 @@ class MemoryWriter:
                 "archived_at": archived_at,
             }
         )
+        if invalidated_reason is not None:
+            extra["invalidated_reason"] = invalidated_reason
         historical = Memory(
             memory_id=history_id,
             title=old.title,
@@ -390,6 +419,32 @@ class MemoryWriter:
         active_records: Mapping[str, Any] | None = None,
     ) -> Memory:
         active = active_records if active_records is not None else self._active_records()
+        correction = request.get("scope_correction")
+        if isinstance(correction, Mapping) and correction.get("survivor_memory_id"):
+            target_id = correction.get("target_memory_id")
+            survivor_id = correction.get("survivor_memory_id")
+            target_record = active.get(target_id)
+            survivor_record = active.get(survivor_id)
+            if target_record is None or survivor_record is None:
+                raise ModelOutputError("scope correction target is not active")
+            target = getattr(target_record, "memory", target_record)
+            survivor = getattr(survivor_record, "memory", survivor_record)
+            if not isinstance(target, Memory) or not isinstance(survivor, Memory):
+                raise ModelOutputError("scope correction memory is invalid")
+            self._write_history(
+                target,
+                superseded_by=survivor.memory_id,
+                archived_at=now,
+                invalidated_reason="scope_correction",
+            )
+            path = self.service.vault.memory_path(target.memory_id, "knowledge")
+            if path.is_symlink():
+                raise ModelOutputError("unsafe knowledge path")
+            if path.exists():
+                path.unlink()
+            if isinstance(active, dict):
+                active.pop(target.memory_id, None)
+            return survivor
         duplicate_id = request.get("duplicate_memory_id")
         if duplicate_id is not None:
             existing_record = active.get(duplicate_id)
@@ -448,7 +503,14 @@ class MemoryWriter:
             self.last_noop_memory_ids.add(request["memory_id"])
             return existing
         if existing is not None:
-            self._write_history(existing, superseded_by=desired.memory_id, archived_at=now)
+            correction = request.get("scope_correction")
+            invalidated_reason = "scope_correction" if isinstance(correction, Mapping) else None
+            self._write_history(
+                existing,
+                superseded_by=desired.memory_id,
+                archived_at=now,
+                invalidated_reason=invalidated_reason,
+            )
         path = self.service.vault.memory_path(desired.memory_id, "knowledge")
         if path.is_symlink():
             raise ModelOutputError("unsafe knowledge path")