memleaf 0.2.89__tar.gz → 0.2.90__tar.gz

{memleaf-0.2.89 → memleaf-0.2.90}/CHANGELOG.md

@@ -4,6 +4,27 @@ All notable changes to memleaf are documented here.
 
 ## Unreleased
 
+## 0.2.90 — 2026-10-05
+
+### Expose withdrawal state in explicit historical retrieval
+
+- Include matching retracted current heads when historical retrieval is
+  explicitly requested. Ordinary retrieval continues to exclude them.
+- Project bounded lifecycle facts through search and paged MCP reads: the
+  historical snapshot flag, exact current identity link, invalidation reason,
+  and current validity from the same validated query scan. Keep missing,
+  unreadable, conflicting or ambiguous links unknown; support legacy links
+  without guessing from titles or content.
+- Preserve archived validity and distinguish past withdrawal from later
+  restoration. Associate successful lifecycle-only reads with the captured
+  turn's comparison context without fabricating body characters.
+- Reuse query scans and existing pagination, permissions and version checks.
+  No model stage, model call, tool or persistence format is added.
+- Validation: 97 affected checks passed, plus an isolated real-conversation
+  replay through a source MCP process. One legacy test still expects the
+  previously removed waiting_on field and fails identically on the prior
+  release. Replay used zero model calls and left the formal Vault unchanged.
+
 ## 0.2.89 — 2026-10-04
 
 ### Complete comparison context and bound tool continuation

{memleaf-0.2.89/src/memleaf.egg-info → memleaf-0.2.90}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: memleaf
-Version: 0.2.89
+Version: 0.2.90
 Summary: A local-first Markdown memory core for AI agents
 Author: memleaf contributors
 License-Expression: MIT
@@ -23,7 +23,7 @@ Dynamic: license-file
 
 [English](README.en.md) · [PyPI](https://pypi.org/project/memleaf/) · [GitHub](https://github.com/miffyblueboo/memleaf)
 
-> **版本：0.2.89。**
+> **版本：0.2.90。**
 > 自动提炼和复核共用同一条“未来记忆价值”标准：模型综合未来复用、信息增量、再次读取时的直接可用性和忘记成本，只保留对未来理解、判断或行动有实质影响的最小核心；没有明确价值的信息不提炼，不按具体业务场景硬编码排除。
 > 提炼先比较旧事项中的编号、目标、进展、责任和期限；补全未知信息也应维护原事项，另建独立待办不能替代项目事实更新。确认重复的记忆在现有处理请求中合并，保留历史与来源；项目和独立任务保持各自生命周期，Core 不按标题强行合并。
 > 新请求兼容等价的字段表示；未知执行人保持 `null`，新增或变更负责人和期限需要真实来源；等待条件在正文维护，不再提炼 `waiting_on`。行动及相关字段经过有界语义复核，提炼与复核共用每份工作的最多五次模型请求额度，成功即停止；复核失败不写入。来源时间用于解析相对日期，不补造事实日期。

{memleaf-0.2.89 → memleaf-0.2.90}/README.en.md

@@ -4,7 +4,7 @@
 
 [中文](README.md) · [PyPI](https://pypi.org/project/memleaf/) · [GitHub](https://github.com/miffyblueboo/memleaf)
 
-> **Version: 0.2.89.**
+> **Version: 0.2.90.**
 > Automatic extraction and review share one future-value standard: the model weighs likely reuse, information gain, direct usability when read again, and the cost of forgetting. It keeps only the smallest core that can materially help future understanding, decisions, or actions; information without clear value is not extracted, and no business-specific exclusion rule is hard-coded.
 > Extraction compares existing identifiers, objectives, progress, responsibility and deadlines first. Filling an unknown also maintains the original item; a separate task does not replace updating shared project facts. Confirmed duplicates can be merged in the existing processing requests with their sources and history preserved. Independent project and task lifecycles remain separate; Core does not merge matching titles.
 > New requests accept equivalent field representations. Unknown executors remain `null`; new or changed responsibility and deadlines require actual source evidence. Dependencies belong in the body; `waiting_on` is no longer extracted. Proposed actions and related fields undergo bounded semantic verification within a shared five-request limit per work item, stopping on success; failed verification blocks writes. Source time resolves relative dates without inventing factual dates.

{memleaf-0.2.89 → memleaf-0.2.90}/README.md

@@ -4,7 +4,7 @@
 
 [English](README.en.md) · [PyPI](https://pypi.org/project/memleaf/) · [GitHub](https://github.com/miffyblueboo/memleaf)
 
-> **版本：0.2.89。**
+> **版本：0.2.90。**
 > 自动提炼和复核共用同一条“未来记忆价值”标准：模型综合未来复用、信息增量、再次读取时的直接可用性和忘记成本，只保留对未来理解、判断或行动有实质影响的最小核心；没有明确价值的信息不提炼，不按具体业务场景硬编码排除。
 > 提炼先比较旧事项中的编号、目标、进展、责任和期限；补全未知信息也应维护原事项，另建独立待办不能替代项目事实更新。确认重复的记忆在现有处理请求中合并，保留历史与来源；项目和独立任务保持各自生命周期，Core 不按标题强行合并。
 > 新请求兼容等价的字段表示；未知执行人保持 `null`，新增或变更负责人和期限需要真实来源；等待条件在正文维护，不再提炼 `waiting_on`。行动及相关字段经过有界语义复核，提炼与复核共用每份工作的最多五次模型请求额度，成功即停止；复核失败不写入。来源时间用于解析相对日期，不补造事实日期。

{memleaf-0.2.89 → memleaf-0.2.90}/docs/memory-state-contract.md

@@ -83,6 +83,26 @@ Ordinary `read`, `read_page`, `search`, `context`, and `list_todos` exclude retr
 
 The derived active index excludes retracted heads. History indexing remains available only through APIs that explicitly include history. Closed todos remain in `knowledge/`; status filtering, rather than age-based deletion, controls their normal presentation.
 
+For explicit historical questions, `search_candidates(include_history=True)` and
+MCP `search` also expose matching retracted current heads. Candidate entries and
+`read_page`/MCP `read` with `include_history=True` carry a bounded `lifecycle`:
+
+- `historical` distinguishes an archived snapshot from a current head.
+- `active_memory_id`, when present, is the stored exact current-identity link.
+- `invalidated_reason`, when present, describes why that snapshot was archived.
+- `current_validity` comes from the validated current head in the same query
+  observation. It is `null` when the linked head is missing, unreadable or
+  ambiguous; conflicting or missing legacy links are not inferred from titles.
+
+An archived snapshot's own `validity=valid` describes its past assertion. A past
+`invalidated_reason=retracted` does not establish current withdrawal after a
+later restoration. Use `lifecycle.current_validity` for that distinction. The
+projection contains no current body and grants no edit authority. Ordinary
+retrieval remains unchanged and excludes retracted assertions. Historical body
+pages retain their existing explicit history permission and version checks.
+Successful lifecycle-only reads also associate the exact ID with the captured
+turn's comparison context; an empty assertion does not fabricate body characters.
+
 ## Compatibility boundary
 
 `closed_todo_retention_days` remains accepted so existing config files continue to load, but it no longer retires the stable current identity. Optional structured fields stored in frontmatter participate in the protected revision. The incremental model protocol supports UPDATE.patch.validity and an explicit restore with current content. The legacy planner still excludes retracted heads; its older protocol is not silently extended. Deterministic Python retraction and explicit update use the same current identity and protected revision semantics.

{memleaf-0.2.89 → memleaf-0.2.90}/pyproject.toml

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

{memleaf-0.2.89 → memleaf-0.2.90}/src/memleaf/__init__.py

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

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

{memleaf-0.2.89 → memleaf-0.2.90}/src/memleaf/mcp_server.py

@@ -244,6 +244,8 @@ _TOOLS: tuple[dict[str, Any], ...] = (
             "MCP client may omit it only on the first page; memleaf returns a short-lived retrieval_id "
             "for pagination/read. Errors are failures, never no_match. Managed MCP search is "
             "directory-only; view=full is rejected. "
+            "For explicit history/withdrawal questions use include_history=true. Results include lifecycle: "
+            "historical snapshot, linked current ID/validity and invalidation reason; null current validity is unknown. "
             "Python search(view='full') remains the compatibility interface."
         ),
         "inputSchema": _object_schema(
@@ -303,9 +305,10 @@ _TOOLS: tuple[dict[str, Any], ...] = (
         "name": "read",
         "description": (
             "Read one memory by exact memory_id in pages. Each page is capped at 2000 body "
-            "characters and contains only identifiers, scopes, body, and paging/version fields; "
+            "characters with bounded content, state, and paging/version fields; "
             "retrieval_id is required, and the retrieval turn must have a current FOUND search; "
             "NO_MATCH, ERROR, and DEGRADED turns are rejected. "
+            "Read historical or retracted records with include_history=true; lifecycle distinguishes past invalidation from current validity. "
             "Prefer returned body_continuation: pass only continue=true and retrieval_id to read the next unfinished body, with its ID/version/offset held by the server. "
             "On memory_version_changed, add restart=true to that continuation to restart the same bound memory at offset 0 with its new version. "
             "continue with next_offset only when has_more is true, passing the returned version "
@@ -693,6 +696,9 @@ def _read_page_result(value: Any) -> dict[str, Any] | None:
             result[name] = field
     if "due_anchor" in value:
         result["due_anchor"] = _jsonable(value.get("due_anchor"))
+    if "lifecycle" in value:
+        from .retrieval_lifecycle import project_lifecycle
+        result["lifecycle"] = project_lifecycle(value["lifecycle"])
     result.update(_query_metadata(value))
     if "read_accounting" in value:
         if not isinstance(value["read_accounting"], str) or value["read_accounting"] not in {"counted", "not_counted", "unavailable"}:
@@ -734,7 +740,7 @@ def _search_result(value: Any) -> dict[str, Any]:
     entries = value.get("results")
     if not isinstance(entries, list):
         raise ValueError("invalid search results")
-    results: list[dict[str, str]] = []
+    results: list[dict[str, Any]] = []
     for entry in entries:
         if not isinstance(entry, Mapping):
             raise ValueError("invalid search entry")
@@ -744,7 +750,11 @@ def _search_result(value: Any) -> dict[str, Any]:
             raise ValueError("invalid search identifiers")
         # Search is intentionally narrower than the legacy directory helper:
         # do not leak per-memory scope/tags/aliases/keywords into candidates.
-        results.append({"memory_id": memory_id, "title": title})
+        row = {"memory_id": memory_id, "title": title}
+        if "lifecycle" in entry:
+            from .retrieval_lifecycle import project_lifecycle
+            row["lifecycle"] = project_lifecycle(entry["lifecycle"])
+        results.append(row)
     if bool(results) != (value["status"] == "found"):
         raise ValueError("inconsistent search results")
     paging = _paging_fields(value)

{memleaf-0.2.89 → memleaf-0.2.90}/src/memleaf/retrieval_gate.py

@@ -762,7 +762,9 @@ def guarded_read(
             elif prior is not None:
                 pending.pop(prior)
             entry["body_continuations"] = pending
-        if body:
+        # A verified empty tombstone still supplies lifecycle facts and must
+        # remain available to the captured turn's comparison context.
+        if body or isinstance(result.get("lifecycle"), Mapping):
             if memory_id not in read_ids:
                 read_ids.append(memory_id)
             entry["read_ids"] = read_ids

memleaf-0.2.90/src/memleaf/retrieval_lifecycle.py

@@ -0,0 +1,60 @@
+"""Bounded lifecycle facts for explicitly requested historical retrieval."""
+from collections.abc import Mapping
+from typing import Any
+
+from .query_scan import QueryScan, ScanRecord
+from .vault import safe_component
+
+
+def current_validities(snapshot: QueryScan) -> dict[str, str]:
+    # Only validated, unambiguous current records can establish current state.
+    unavailable = snapshot.ambiguous | {i.identity.casefold() for i in snapshot.issues if i.identity}
+    return {r.memory.memory_id: r.memory.validity
+            for r in snapshot.area("knowledge")
+            if r.memory.memory_id.casefold() not in unavailable}
+
+
+def lifecycle(record: ScanRecord, current: Mapping[str, str]) -> dict[str, Any]:
+    historical = record.area == "history"
+    result = {"historical": historical,
+              "current_validity": None if historical else record.memory.validity}
+    if not historical:
+        return result
+    extra = record.memory.extra
+    links = [extra[k] for k in ("active_memory_id", "original_memory_id") if k in extra]
+    if links and all(isinstance(v, str) and len(v) <= 800 and v == links[0] for v in links):
+        try:
+            identity = safe_component(links[0], "active memory id")
+        except ValueError:
+            pass
+        else:
+            result.update(active_memory_id=identity, current_validity=current.get(identity))
+    reason = extra.get("invalidated_reason")
+    if isinstance(reason, str) and 0 < len(reason) <= 120:
+        result["invalidated_reason"] = reason
+    return result
+
+
+def project_lifecycle(value: Any) -> dict[str, Any]:
+    """Do not pass arbitrary archive extras through the MCP boundary."""
+    if (not isinstance(value, Mapping)
+            or not {"historical", "current_validity"} <= set(value)
+            or set(value) - {"historical", "current_validity", "active_memory_id", "invalidated_reason"}
+            or type(value["historical"]) is not bool
+            or value["current_validity"] not in (None, "valid", "retracted")):
+        raise ValueError("invalid retrieval lifecycle")
+    result = dict(value)
+    if not value["historical"] and (value["current_validity"] is None
+                                   or set(value) != {"historical", "current_validity"}):
+        raise ValueError("invalid current lifecycle")
+    if value["historical"] and value["current_validity"] is not None and "active_memory_id" not in value:
+        raise ValueError("current validity requires an exact archive link")
+    if "active_memory_id" in value:
+        if not isinstance(value["active_memory_id"], str) or len(value["active_memory_id"]) > 800:
+            raise ValueError("invalid active memory id")
+        safe_component(value["active_memory_id"], "active memory id")
+    if "invalidated_reason" in value:
+        reason = value["invalidated_reason"]
+        if not isinstance(reason, str) or not 0 < len(reason) <= 120:
+            raise ValueError("invalid invalidation reason")
+    return result

{memleaf-0.2.89 → memleaf-0.2.90}/src/memleaf/service.py

@@ -58,6 +58,7 @@ from .scope_state import (
 )
 from .vault import Vault, safe_component
 from .query_scan import QueryScan, ScanRecord, scan_memories, ensure_scan_current
+from .retrieval_lifecycle import current_validities, lifecycle
 from .query_progress import observe_progress
 
 
@@ -989,7 +990,9 @@ class Memleaf:
                     revision=revision_digest(memory),
                     structured_fields=memory.extra,
                     record=record,
-                ), **self._query_envelope(snapshot, scope=memory.scopes)}
+                ), **({"lifecycle": lifecycle(record, current_validities(snapshot))}
+                      if include_history else {}),
+                    **self._query_envelope(snapshot, scope=memory.scopes)}
 
             from .native_index import NativeIndexer
 
@@ -1157,8 +1160,8 @@ class Memleaf:
 
     @staticmethod
     def _candidate_directory(record: _Record) -> dict[str, Any]:
-        # The finalized retrieval contract deliberately keeps candidate
-        # entries to memory_id + title. Scope selection already happened
+        # Ordinary candidate entries remain memory_id + title. Explicit
+        # historical queries add lifecycle separately. Scope selection happened
         # before search via the bounded Scope Map and search input.
         display = directory_entry(record.memory)
         return {
@@ -1259,6 +1262,8 @@ class Memleaf:
     ) -> dict[str, Any]:
         """Search and return only a bounded directory of candidate memories."""
 
+        if type(include_history) is not bool:
+            raise ValueError("include_history must be a boolean")
         page_limit = self._page_limit(
             limit,
             MAX_SEARCH_CANDIDATE_ITEMS,
@@ -1289,6 +1294,7 @@ class Memleaf:
                 limit=None,
                 stable=True,
                 strict_candidates=True,
+                include_retracted=include_history,
                 query_snapshot=snapshot,
             )
             records = [
@@ -1296,7 +1302,10 @@ class Memleaf:
                 for record in records
                 if candidate_matches_query(record.memory, query_value)
             ]
-            candidates = [self._candidate_directory(record) for record in records]
+            current = current_validities(snapshot) if include_history else {}
+            candidates = [{**self._candidate_directory(record),
+                           **({"lifecycle": lifecycle(record, current)} if include_history else {})}
+                          for record in records]
             fingerprint = self._search_fingerprint(
                 records,
                 query=query_value,

{memleaf-0.2.89 → memleaf-0.2.90/src/memleaf.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: memleaf
-Version: 0.2.89
+Version: 0.2.90
 Summary: A local-first Markdown memory core for AI agents
 Author: memleaf contributors
 License-Expression: MIT
@@ -23,7 +23,7 @@ Dynamic: license-file
 
 [English](README.en.md) · [PyPI](https://pypi.org/project/memleaf/) · [GitHub](https://github.com/miffyblueboo/memleaf)
 
-> **版本：0.2.89。**
+> **版本：0.2.90。**
 > 自动提炼和复核共用同一条“未来记忆价值”标准：模型综合未来复用、信息增量、再次读取时的直接可用性和忘记成本，只保留对未来理解、判断或行动有实质影响的最小核心；没有明确价值的信息不提炼，不按具体业务场景硬编码排除。
 > 提炼先比较旧事项中的编号、目标、进展、责任和期限；补全未知信息也应维护原事项，另建独立待办不能替代项目事实更新。确认重复的记忆在现有处理请求中合并，保留历史与来源；项目和独立任务保持各自生命周期，Core 不按标题强行合并。
 > 新请求兼容等价的字段表示；未知执行人保持 `null`，新增或变更负责人和期限需要真实来源；等待条件在正文维护，不再提炼 `waiting_on`。行动及相关字段经过有界语义复核，提炼与复核共用每份工作的最多五次模型请求额度，成功即停止；复核失败不写入。来源时间用于解析相对日期，不补造事实日期。

{memleaf-0.2.89 → memleaf-0.2.90}/src/memleaf.egg-info/SOURCES.txt

@@ -135,6 +135,7 @@ src/memleaf/remember_route.py
 src/memleaf/retention.py
 src/memleaf/retrieval.py
 src/memleaf/retrieval_gate.py
+src/memleaf/retrieval_lifecycle.py
 src/memleaf/runtime_retention.py
 src/memleaf/scope_maintenance.py
 src/memleaf/scope_state.py