memleaf 0.2.89__tar.gz → 0.2.91__tar.gz

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

@@ -4,6 +4,50 @@ All notable changes to memleaf are documented here.
 
 ## Unreleased
 
+## 0.2.91 — 2026-10-05
+
+### Preserve historical reads in incremental comparison
+
+- Accept successfully read historical versions as read-only comparison context
+  instead of blocking the whole turn with required_target_unavailable. Preserve
+  every required read identity and include its current head only through a
+  validated exact link; missing or conflicting links remain unknown.
+- Keep historical versions outside operation targets and source evidence. Their
+  scopes do not grant write authority, and current heads retain existing scope
+  boundaries. Ordinary turns continue to scan current knowledge only.
+- Protect historical content and lifecycle links in planning snapshots and
+  preserve them through partial recovery with stable current-target references.
+  Existing snapshots without historical context retain their original digest.
+- No new model stage, model output field or tool is added. Only required archive
+  versions enter model input; a short prompt clarification distinguishes them
+  from current records and new evidence.
+- Validation: 189 focused checks passed, including 19 new history-context
+  regressions, plus isolated replay of the original 19-read real turn. Six
+  existing legacy-suite failures reproduce on 0.2.90 and are recorded locally.
+  Replay used supplied responses with zero external model calls and left the
+  formal Vault unchanged; new live-model acceptance remains separate.
+
+## 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.91}/PKG-INFO

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

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

{memleaf-0.2.89 → memleaf-0.2.91}/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.91}/pyproject.toml

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

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

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

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

memleaf-0.2.91/src/memleaf/historical_context.py

@@ -0,0 +1,83 @@
+"""Read-only historical comparisons, separate from actionable memory targets."""
+from collections.abc import Mapping
+from copy import deepcopy
+from typing import Any
+
+from .models import Memory
+from .retrieval_lifecycle import project_lifecycle
+from .turn_plan import revision_digest
+from .vault import safe_component
+
+
+def freeze_history(value: Any, targets: Mapping[str, dict[str, Any]]) -> dict[str, Any]:
+    if value is None:
+        return {}
+    if not isinstance(value, Mapping):
+        raise ValueError("invalid_history_context")
+    current = {t["memory"]["memory_id"]: t for t in targets.values()}
+    identities = {identity.casefold() for identity in current}
+    result = {}
+    for identity, item in value.items():
+        if (not isinstance(identity, str) or not isinstance(item, Mapping)
+                or set(item) != {"memory", "lifecycle"}
+                or not isinstance(item["memory"], Memory)
+                or identity != item["memory"].memory_id):
+            raise ValueError("invalid_history_context")
+        safe_component(identity, "memory id")
+        if identity.casefold() in identities:
+            raise ValueError("duplicate_memory_id")
+        identities.add(identity.casefold())
+        life = project_lifecycle(item["lifecycle"])
+        if not life["historical"]:
+            raise ValueError("invalid_history_context")
+        head = current.get(life.get("active_memory_id"))
+        validity = head["memory"].get("validity", "valid") if head and "native" not in head else None
+        if life["current_validity"] != validity:
+            raise ValueError("invalid_history_context")
+        result[identity] = {"memory": item["memory"].to_dict(),
+                            "revision": revision_digest(item["memory"]), "lifecycle": life}
+    return result
+
+
+def thaw_history(value: Any) -> dict[str, Any] | None:
+    if value is None:
+        return None
+    if not isinstance(value, Mapping):
+        raise ValueError("invalid_history_context")
+    result = {}
+    for identity, item in value.items():
+        if (not isinstance(item, Mapping) or set(item) != {"memory", "revision", "lifecycle"}
+                or not isinstance(item["memory"], Mapping)):
+            raise ValueError("invalid_history_context")
+        memory = Memory.from_mapping(item["memory"])
+        if revision_digest(memory) != item["revision"]:
+            raise ValueError("invalid_history_context")
+        result[identity] = {"memory": memory, "lifecycle": item["lifecycle"]}
+    return result
+
+
+def history_signature(state: Mapping[str, Any]) -> dict[str, Any]:
+    # Current validity is derived from targets, whose changes (including this
+    # work's own writes) are already checked by partial recovery.
+    return {identity: {"revision": item["revision"],
+                       "lifecycle": {k: v for k, v in item["lifecycle"].items()
+                                     if k != "current_validity"}}
+            for identity, item in state.get("history_context", {}).items()}
+
+
+def project_history(state: Mapping[str, Any], scope_refs: Mapping[str, str]) -> list[dict[str, Any]]:
+    targets = {t["memory"]["memory_id"]: ref for ref, t in state["targets"].items()
+               if "native" not in t}
+    result = []
+    for item in state.get("history_context", {}).values():
+        memory = item["memory"]
+        row = {key: deepcopy(memory[key]) for key in (
+            "type", "title", "body", "status", "validity", "actionable", "assignee",
+            "due_date", "due_text", "due_status", "completed_at") if key in memory}
+        scopes = memory.get("scopes", ["global"])
+        row["scope"] = scope_refs.get(scopes[0], scopes[0]) if len(scopes) == 1 else scopes
+        life = dict(item["lifecycle"])
+        row["current_target"] = targets.get(life.pop("active_memory_id", None))
+        row["lifecycle"] = life
+        result.append(row)
+    return result

{memleaf-0.2.89 → memleaf-0.2.91}/src/memleaf/incremental_preview.py

@@ -155,6 +155,37 @@ def _prepare_incremental_unlocked(service: Any, *, source: str, session_id: str,
             read_ids.extend(identities)
     priority = list(dict.fromkeys(explicit_ids + read_ids + priority))
     priority += sorted(x for x in prior_ids if x.casefold() in records and x not in priority)
+    historical = {}
+    explicit_keys = {identity.casefold() for identity in explicit_ids}
+    if any(identity.casefold() not in records for identity in priority):
+        # Ordinary turns keep their knowledge-only scan. Read/caller-required
+        # identities that are absent there may be exact historical versions.
+        # Reuse the public scanner's duplicate, path and generation checks.
+        library = scan_memories(service.vault, include_history=True)
+        if library.ambiguous or native_keys.intersection(r.memory.memory_id.casefold() for r in library.records):
+            raise ValueError("duplicate_memory_id")
+        if library.issues:
+            raise ValueError("incomplete_library")
+        records = {r.memory.memory_id.casefold(): r.memory for r in library.area("knowledge")}
+        records.update({key.casefold(): memory for key, memory in native.memories.items()})
+        archives = {r.memory.memory_id.casefold(): r for r in library.area("history")}
+        from .retrieval_lifecycle import current_validities, lifecycle
+        current = current_validities(library)
+        current_priority = []
+        for identity in priority:
+            if identity.casefold() in records:
+                current_priority.append(identity)
+                continue
+            archive = archives.get(identity.casefold())
+            if archive is None or identity.casefold() in explicit_keys:
+                raise ValueError("required_target_unavailable")
+            life = lifecycle(archive, current)
+            historical[archive.memory.memory_id] = {"memory": archive.memory, "lifecycle": life}
+            # A stored unambiguous local link supplies comparison context, not
+            # new write authority; the existing scope boundary still applies.
+            if life["current_validity"] is not None:
+                current_priority.append(life["active_memory_id"])
+        priority = list(dict.fromkeys(current_priority))
     chosen = []
     for identity in priority:
         if identity.casefold() not in records:
@@ -202,6 +233,7 @@ def _prepare_incremental_unlocked(service: Any, *, source: str, session_id: str,
     return PlanningSnapshot.build(evidence=evidence, targets=targets, scopes=scope_refs,
                                   write_scopes=boundary, writable=writable,
                                   allow_new_scopes=allow_new_scopes, native_targets=native_targets,
+                                  history_context=historical,
                                   native_guard=native.guard if native.guard["sources"] else None,
                                   request_kind="explicit_remember" if selection else "automatic",
                                   retention_request=retention_request, scope_guard=scope_guard,

{memleaf-0.2.89 → memleaf-0.2.91}/src/memleaf/incremental_prompts.py

@@ -39,4 +39,5 @@ patch 只含 title/body/scope/status/actionable/assignee/deadline/validity；typ
 request_kind=explicit_remember：所选 new 有保留授权，仍按用户实际要求选择内容并整理去重，不得 NO_MEMORY；独立不被要求保留的内容不强行建项。
 仅 whole_host_turn=true 的宿主完整回合显式请求：遵守用户指定的保存/排除范围，同时按自动记忆标准处理整轮其余有价值的独立新信息；不要因已保存一项而跳过其他。助手建议仍不能变成用户义务。
 explicit_writes 是系统核验的已写目标关联，不是新证据或整轮已覆盖声明：先比较当前目标与 new，完整无变化 NO_CHANGE，同一事项新增 UPDATE，独立新事项仍 CREATE。不用旧回执覆盖较新目标。
+history_context 是已读历史版本，只供比较，不是新事实或操作 target；current_target 指向当前候选，current_validity=null 表示未知。历史正文及当时状态不覆盖当前候选。
 """

{memleaf-0.2.89 → memleaf-0.2.91}/src/memleaf/incremental_protocol.py

@@ -287,6 +287,7 @@ class PlanningSnapshot:
               allow_new_scopes: bool = False, context_complete: bool = True,
               native_targets: Mapping[str, dict[str, Any]] | None = None,
               native_guard: dict[str, Any] | None = None,
+              history_context: Mapping[str, Any] | None = None,
               retention_request: str | None = None, scope_guard: dict[str, Any] | None = None,
               scope_aliases: Mapping[str, list[str]] | None = None,
               basis_statuses: Mapping[str, str] | None = None,
@@ -371,6 +372,10 @@ class PlanningSnapshot:
         state = {"protocol_version": PROTOCOL_VERSION, "evidence": evidence, "targets": target_values,
                  "scopes": scopes, "write_scopes": write_scopes, "request_kind": request_kind,
                  "allow_new_scopes": allow_new_scopes, "context_complete": context_complete}
+        from .historical_context import freeze_history
+        historical = freeze_history(history_context, target_values)
+        if historical:
+            state["history_context"] = historical
         if extraction_contract is not None:
             state["extraction_contract"] = extraction_contract
         from .incremental_explicit import validate_links
@@ -415,6 +420,9 @@ class PlanningSnapshot:
         state["targets"] = {ref: {"revision": item["revision"], "writable": item["writable"],
                                   **({"native": item["native"]} if "native" in item else {})}
                             for ref, item in state["targets"].items()}
+        if "history_context" in state:
+            state["history_context"] = {identity: {"revision": item["revision"], "lifecycle": item["lifecycle"]}
+                                        for identity, item in state["history_context"].items()}
         return hashlib.sha256(_json(state).encode("utf-8")).hexdigest()
 
     def state(self) -> dict[str, Any]:
@@ -454,6 +462,7 @@ class PlanningSnapshot:
                 projection["calendar_hints"] = hints
             projected_evidence.append(projection)
         from .incremental_explicit import project_links
+        from .historical_context import project_history
         return {
             "protocol_version": PROTOCOL_VERSION, "request_kind": state["request_kind"],
             **({"extraction_contract": state["extraction_contract"]} if "extraction_contract" in state else {}),
@@ -463,6 +472,7 @@ class PlanningSnapshot:
                if state.get("scope_aliases") else {}),
             "allow_new_scopes": state["allow_new_scopes"], "context_complete": state["context_complete"],
             "evidence": projected_evidence, "memories": memories,
+            **({"history_context": project_history(state, reverse_scope)} if state.get("history_context") else {}),
             **({"explicit_writes": project_links(state["explicit_writes"], state["targets"])}
                if state.get("explicit_writes") else {}),
         }

{memleaf-0.2.89 → memleaf-0.2.91}/src/memleaf/incremental_recovery.py

@@ -12,6 +12,7 @@ from typing import Any
 from .incremental_protocol import PlanningSnapshot, MAX_ITEMS
 from .models import Memory
 from .validation import parse_strict_json
+from .historical_context import thaw_history, history_signature
 
 RECOVERY_SYSTEM = "\n本次仅重规划未结算的 new；settled 只读，不重出、不改写。新增前文和已有记忆仅帮助理解原事项，不据此新建无关事项。沿用 JSON 协议。\n"
 
@@ -36,6 +37,7 @@ def restore_snapshot(state: Any) -> PlanningSnapshot:
             vault_binding=state.get("vault_binding"),
             explicit_writes=state.get("explicit_writes"),
             extraction_contract=state.get("extraction_contract"),
+            history_context=thaw_history(state.get("history_context")),
         )
     except (KeyError, TypeError) as error:
         raise ValueError("invalid_partial_snapshot") from error
@@ -175,6 +177,7 @@ def context_changed(original: PlanningSnapshot, current: PlanningSnapshot, work:
     new_e = {e["event_key"]: {k: v for k, v in e.items() if k != "ref"} for e in new["evidence"]}
     from .incremental_scopes import guard_matches, applied_additions
     if (old_e != new_e or old.get("native_guard") != new.get("native_guard")
+            or history_signature(old) != history_signature(new)
             or not guard_matches(new.get("scope_guard"), old.get("scope_guard"), applied_additions(work))):
         return True
     expected = {t["memory"]["memory_id"]: t["revision"] for t in old["targets"].values()}
@@ -247,6 +250,8 @@ def recovery_snapshot(original: PlanningSnapshot, current: PlanningSnapshot, wor
             raise ValueError("repair_context_changed")
         if old.get("native_guard") != new.get("native_guard"):
             raise ValueError("repair_context_changed")
+        if history_signature(old) != history_signature(new):
+            raise ValueError("repair_context_changed")
         # A structural repair may not silently adapt any referenced target's
         # earlier business decision to a different complete target snapshot.
         for row in work.get("_repair_rows", []):
@@ -270,6 +275,7 @@ def recovery_snapshot(original: PlanningSnapshot, current: PlanningSnapshot, wor
                                   scope_guard=new.get("scope_guard"), scope_aliases=new.get("scope_aliases"),
                                   basis_statuses=statuses, vault_binding=new.get("vault_binding"),
                                   explicit_writes=explicit_links,
+                                  history_context=thaw_history(new.get("history_context")),
                                   extraction_contract=(old if mode == "repair" else new).get("extraction_contract"))
 
 

{memleaf-0.2.89 → memleaf-0.2.91}/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.91}/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.91/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.91}/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.91/src/memleaf.egg-info}/PKG-INFO

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

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

@@ -72,6 +72,7 @@ src/memleaf/extraction_capability.py
 src/memleaf/extraction_work_state.py
 src/memleaf/frontmatter.py
 src/memleaf/hermes_runtime.py
+src/memleaf/historical_context.py
 src/memleaf/host_events.py
 src/memleaf/host_retention.py
 src/memleaf/host_runtime.py
@@ -135,6 +136,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