memleaf 0.2.90__tar.gz → 0.2.91__tar.gz

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

@@ -4,6 +4,29 @@ 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

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

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

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

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

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

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

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

@@ -1,5 +1,5 @@
 name: memleaf
-version: 0.2.90
+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.90 → 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.90 → 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.90 → 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.90 → 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.90 → memleaf-0.2.91/src/memleaf.egg-info}/PKG-INFO

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

{memleaf-0.2.90 → 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