memleaf 0.2.83__tar.gz → 0.2.85__tar.gz

{memleaf-0.2.83 → memleaf-0.2.85}/CHANGELOG.md

@@ -4,6 +4,40 @@ All notable changes to memleaf are documented here.
 
 ## Unreleased
 
+## 0.2.85 — 2026-10-03
+
+### Incremental field protocol
+
+- Stop requiring redundant model `deadline_decision` assertions; absent UPDATE
+  deadline fields preserve the current deadline. Older assertions remain checked
+  for contradictions, and selected/cancelled deadlines still require source quotes.
+- Allow CREATE to omit an unknown assignee and store null without inventing a
+  responsibility observation. Non-null responsibility changes still require proof.
+- Consolidate the model field instructions and examples without extra model calls;
+  advance the semantic protocol to `incremental-turn-v12` for cached-run guards.
+
+## 0.2.84 — 2026-09-30
+
+### Task lifecycle, Hermes source times and read-linked comparison
+
+- Expose revision-bound MCP `update_memory` for completion, cancellation and
+  reopening; retain the memory body, other fields and version history. Both MCP
+  permanent-forgetting tools now require strict `confirm_delete=true`.
+- Verify Hermes' native file-mutation footer as an exact display transformation
+  instead of losing both message times. Verify legacy correction rows against
+  their native scaffold and full merge format; capture each source event with
+  its own timestamp. Unknown inputs remain unknown.
+- Recognize a repeated source delivery before consuming another same-text turn;
+  copy messages at callback invocation and retain the queued retrieval identity.
+- Freeze successful current-turn read IDs in assistant capture metadata and
+  immutable receipts. Prioritize those targets for automatic extraction; reject
+  mismatched source/session/turn context and block missing or over-budget targets.
+  Recover captured context after Inbox/receipt interruption even if the gate expires.
+- Require structured deadline maintenance before NO_CHANGE when current evidence
+  verifies an existing textual deadline whose date is absent or unresolved.
+  Advance semantic protocol to v11 without changing legacy snapshot field contracts.
+- No production memory migration or automatic retry of historical runs is performed.
+
 ## 0.2.83 — 2026-09-30
 
 ### Reviewed extraction fields and existing-item maintenance

{memleaf-0.2.83/src/memleaf.egg-info → memleaf-0.2.85}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: memleaf
-Version: 0.2.83
+Version: 0.2.85
 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.83。**
+> **版本：0.2.85。**
 > 自动提炼和复核共用同一条“未来记忆价值”标准：模型综合未来复用、信息增量、再次读取时的直接可用性和忘记成本，只保留对未来理解、判断或行动有实质影响的最小核心；没有明确价值的信息不提炼，不按具体业务场景硬编码排除。
 > 提炼先比较旧事项中的编号、目标、进展、责任和期限；补全未知信息也应维护原事项，另建独立待办不能替代项目事实更新。Core 不按标题强行合并。
 > 新请求使用 `field-reviewed-v1`：CREATE/UPDATE 显式判断结构化期限；未知执行人填 `null`，新增或变更非空负责人必须引用来源原文。Core 校验字段和来源，模型判断业务含义；非法行进入现有 partial 处理。来源时间用于解析相对日期，不补造事实日期。
@@ -283,11 +283,14 @@ python -m memleaf.mcp_server --vault "$HOME/.memleaf"
 | `process_status` | 只读查询异步处理 job 状态 |
 | `recover_failed_run` | 预览并显式恢复终态传输失败，保留原请求预算 |
 | `remember` | 用户明确要求时创建或更新记忆 |
-| `forget_memory` | 按精确 ID 删除一条记忆 |
-| `forget_about` | 忘记明确主题；有歧义时只返回候选 |
+| `update_memory` | 携带当前 revision 办结、取消或重新激活任务，保留正文与历史 |
+| `forget_memory` | 用户明确要求遗忘时，携带 `confirm_delete=true` 按精确 ID 永久删除 |
+| `forget_about` | 携带 `confirm_delete=true` 遗忘明确主题；有歧义时只返回候选 |
 | `rebuild_index` | 重建可重建的本地派生索引 |
 | `stats` | 返回 Vault 计数和诊断统计 |
 
+任务办结与永久遗忘的接口和兼容性见 [生命周期工具](docs/memory-lifecycle-tools.md)；来源时间及本轮比较目标的捕获边界见 [Hermes 来源与比较上下文](docs/hermes-source-comparison-context.md)。
+
 `search` 的候选只是线索，标题不能单独作为事实依据。受管理检索必须使用同一条检索链的 `retrieval_id` 完成 `search → read`。Hermes/Codex Hook 可直接提供该 token；只有 MCP 的客户端可在第一条 `search` / `list_todos` 省略 token，并使用返回值继续分页和读取。带 cursor 的后续页以及所有 `read` 都不能省略 `retrieval_id`。工具错误、Scope 冲突或读取失败都应如实处理。
 
 ## Python API

{memleaf-0.2.83 → memleaf-0.2.85}/README.en.md

@@ -4,7 +4,7 @@
 
 [中文](README.md) · [PyPI](https://pypi.org/project/memleaf/) · [GitHub](https://github.com/miffyblueboo/memleaf)
 
-> **Version: 0.2.83.**
+> **Version: 0.2.85.**
 > 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. Core does not merge matching titles.
 > New requests use `field-reviewed-v1`: CREATE/UPDATE explicitly decide structural deadlines; unknown executors use `null`, and new or changed non-null responsibility requires a source quote. Core validates fields and provenance while the model judges business meaning; invalid rows use existing partial handling. Source time resolves relative dates without inventing factual dates.
@@ -264,11 +264,14 @@ The server exposes the following tools:
 | `process_status` | Read the status of a background processing job |
 | `recover_failed_run` | Preview and explicitly recover terminal transport failures within the original request budget |
 | `remember` | Create or update memory after an explicit request |
-| `forget_memory` | Delete one memory by exact ID |
-| `forget_about` | Forget an unambiguous topic; return candidates when ambiguous |
+| `update_memory` | Complete, cancel or reopen a task using its current revision; retain body and history |
+| `forget_memory` | Permanently delete an exact ID after explicit user forgetting, with `confirm_delete=true` |
+| `forget_about` | Forget an unambiguous topic with `confirm_delete=true`; return candidates when ambiguous |
 | `rebuild_index` | Rebuild local derived indexes |
 | `stats` | Return Vault counts and diagnostic statistics |
 
+See [Lifecycle tools](docs/memory-lifecycle-tools.md) and [Hermes source and comparison context](docs/hermes-source-comparison-context.md) for operation and capture boundaries.
+
 Search results are clues; a title alone is not a business fact. Managed retrieval must use the same `retrieval_id` for `search → read`. Tool errors, Scope conflicts, retrieval-turn violations, and read page/version errors must be handled as such.
 
 ## Python API

{memleaf-0.2.83 → memleaf-0.2.85}/README.md

@@ -4,7 +4,7 @@
 
 [English](README.en.md) · [PyPI](https://pypi.org/project/memleaf/) · [GitHub](https://github.com/miffyblueboo/memleaf)
 
-> **版本：0.2.83。**
+> **版本：0.2.85。**
 > 自动提炼和复核共用同一条“未来记忆价值”标准：模型综合未来复用、信息增量、再次读取时的直接可用性和忘记成本，只保留对未来理解、判断或行动有实质影响的最小核心；没有明确价值的信息不提炼，不按具体业务场景硬编码排除。
 > 提炼先比较旧事项中的编号、目标、进展、责任和期限；补全未知信息也应维护原事项，另建独立待办不能替代项目事实更新。Core 不按标题强行合并。
 > 新请求使用 `field-reviewed-v1`：CREATE/UPDATE 显式判断结构化期限；未知执行人填 `null`，新增或变更非空负责人必须引用来源原文。Core 校验字段和来源，模型判断业务含义；非法行进入现有 partial 处理。来源时间用于解析相对日期，不补造事实日期。
@@ -264,11 +264,14 @@ python -m memleaf.mcp_server --vault "$HOME/.memleaf"
 | `process_status` | 只读查询异步处理 job 状态 |
 | `recover_failed_run` | 预览并显式恢复终态传输失败，保留原请求预算 |
 | `remember` | 用户明确要求时创建或更新记忆 |
-| `forget_memory` | 按精确 ID 删除一条记忆 |
-| `forget_about` | 忘记明确主题；有歧义时只返回候选 |
+| `update_memory` | 携带当前 revision 办结、取消或重新激活任务，保留正文与历史 |
+| `forget_memory` | 用户明确要求遗忘时，携带 `confirm_delete=true` 按精确 ID 永久删除 |
+| `forget_about` | 携带 `confirm_delete=true` 遗忘明确主题；有歧义时只返回候选 |
 | `rebuild_index` | 重建可重建的本地派生索引 |
 | `stats` | 返回 Vault 计数和诊断统计 |
 
+任务办结与永久遗忘的接口和兼容性见 [生命周期工具](docs/memory-lifecycle-tools.md)；来源时间及本轮比较目标的捕获边界见 [Hermes 来源与比较上下文](docs/hermes-source-comparison-context.md)。
+
 `search` 的候选只是线索，标题不能单独作为事实依据。受管理检索必须使用同一条检索链的 `retrieval_id` 完成 `search → read`。Hermes/Codex Hook 可直接提供该 token；只有 MCP 的客户端可在第一条 `search` / `list_todos` 省略 token，并使用返回值继续分页和读取。带 cursor 的后续页以及所有 `read` 都不能省略 `retrieval_id`。工具错误、Scope 冲突或读取失败都应如实处理。
 
 ## Python API

memleaf-0.2.85/docs/hermes-source-comparison-context.md

@@ -0,0 +1,60 @@
+# Hermes source and comparison context
+
+## Message times
+
+`source_time` comes from the corresponding message's `source_time` or
+`timestamp`. Missing or invalid values stay unknown. Capturing or processing
+an event does not create a source time.
+
+The legacy callback checks the final assistant and the nearest user. It has no
+32-message lookback limit. It does not borrow a matching user from an older turn.
+
+Some Hermes versions persist a reply before adding their file-mutation verifier
+footer. The Provider accepts that display transformation only when the installed
+Hermes formatter reconstructs the entire footer from uniquely associated,
+current-turn file-tool receipts and the full resulting reply matches. Arbitrary
+prefixes, suffixes, unsupported formatters and ambiguous receipts remain unknown.
+Tool receipts supply no times or memory facts. The displayed reply remains the
+captured assistant content.
+
+For legacy corrections, the Provider verifies the real user rows, native replay
+scaffold and the exact full merged callback string. It never splits arbitrary
+user text by a separator. A bounded chain must have a queued original admission;
+then each source row is captured separately with its own time. It does not assign
+the final correction's time to the combined user text. A repeated source delivery
+is recognized before consuming another same-text admission. Host-v1 admission
+snapshots remain the preferred interface for compaction and transformations that
+legacy callbacks cannot verify. The list is copied at callback invocation; this
+cannot recover a host snapshot already lost before the callback arrives.
+
+## Successful reads as comparison targets
+
+Hermes uses the retrieval identity frozen at `on_turn_start` for final capture.
+The assistant capture includes `retrieval_id` and `retrieval_turn_id`; the latter
+must equal its `turn_id`. Core checks that the existing gate belongs to exactly
+the declared source, session and turn. It never resolves a session's latest gate
+on behalf of an older callback. Live search and read still reject stale tokens.
+
+Core freezes only successfully read memory IDs into `comparison_context` on the
+assistant event, including the immutable capture receipt and payload digest.
+It accepts no caller-supplied list of IDs through this interface. The capsule is
+comparison metadata, not factual evidence, and its token is not projected into
+the model request. Automatic preparation gives these required targets priority
+alongside explicit-write receipts before filling the bounded candidate budget.
+A missing target or insufficient budget blocks preparation instead of silently
+replacing or dropping the required target. No model call is added to capture.
+
+A delayed callback can use its own unexpired gate even after a later turn starts.
+Once the capsule is captured, gate expiry cannot erase it or break a duplicate
+capture. If Inbox was saved but receipt persistence failed, retries first recover
+the capsule from Inbox before consulting a live gate. An uncaptured, expired or
+mismatched gate cannot supply comparison context.
+
+The extraction prompt also requires structured deadline maintenance before
+NO_CHANGE when current evidence makes an existing unstructured deadline
+verifiable. Unchanged wording does not mean a missing due_date is complete.
+This rule advances the semantic protocol to v11.
+
+This supplies the model with the old targets. It does not force semantic UPDATE,
+merge similar titles, or automatically alter historical memories. Recovery of
+existing production runs and deleted records is a separate operation.

{memleaf-0.2.83 → memleaf-0.2.85}/docs/incremental-planner-preview.md

@@ -61,12 +61,15 @@ The version is `incremental-items-v1`; only `{"items": [...]}` is accepted.
 
 New prepared requests also carry `extraction_contract=field-reviewed-v1`:
 
-- Every CREATE/UPDATE includes row-level `deadline_decision`. Use `selected`
-  with `memory.deadline` for CREATE or `patch.deadline` for UPDATE; use `none`
-  for CREATE without an established deadline, or `unchanged` for UPDATE without
-  a deadline change. A deadline mentioned only in prose is insufficient.
-- CREATE explicitly supplies `memory.assignee`, using null when the executor
-  is unknown. New or changed non-null `assignee`/`waiting_on` requires row-level
+- CREATE supplies `memory.deadline` only for an established deadline. UPDATE
+  supplies `patch.deadline` for a change or explicit cancellation; omission
+  preserves the current deadline. The model does not need `deadline_decision`.
+  Older outputs may retain it, but contradictions with the actual fields are
+  still rejected. A deadline mentioned only in prose is insufficient; Core
+  does not infer a deadline from the body or detect every semantic omission.
+- CREATE may omit `memory.assignee` when the executor is unknown; Core stores
+  null. UPDATE omission preserves the current executor. New or changed non-null
+  `assignee`/`waiting_on` requires row-level
   `responsibility_basis`, keyed by that field, with `{ref, text}` citing an exact
   source quote in the row's evidence. An unchanged inherited owner needs no new
   quote. Field provenance uses the selected source rather than the generic row

memleaf-0.2.85/docs/memory-lifecycle-tools.md

@@ -0,0 +1,26 @@
+# 任务办结与永久遗忘
+
+MCP `update_memory` 用于完成、取消或重新打开现有事项。它调用 Core 的 revision-bound 更新接口，保留原正文、未修改字段及历史版本，不调用模型。任务办结不等于删除记忆。
+
+先通过 `search` / `list_todos` 和 `read` 确认目标。使用 `read` 返回的 `revision`，而不是分页用的 `version`：
+
+```json
+{
+  "memory_id": "mem-example",
+  "expected_revision": "<read 返回的 revision>",
+  "patch": {"status": "completed"}
+}
+```
+
+- 已完成或关闭的事项使用 `completed`，放弃的事项使用 `cancelled`。
+- 本 MCP 接口仅接受 `patch.status`，不修改正文、类型或范围。
+- 重新打开事项使用 `patch.status=active` 和 `reopen=true`，应有用户明确重新打开的要求。
+- 只有明确知道事项的完成事件时间时才传 `source_time`（带时区的 ISO 时间）；完成时会保存为 `completed_at`。未知时省略，不使用当前执行时间补造完成时间。
+- 相同请求可以安全重试，不重复创建历史。旧 revision 的不同修改会被拒绝，应重新读取目标。
+- 混合了项目事实和待办的记忆，办结只改变状态，仍保留项目事实。
+
+`forget_memory` 与 `forget_about` 永久删除选中的记忆及其历史，没有“删除后收档”的历史副本。两个 MCP 工具均要求 `confirm_delete=true`，缺失或不是布尔值 `true` 时服务器拒绝执行。
+
+这个参数只能表示调用方确认用户明确要求永久遗忘。完成、关闭、取消或归档任务不能作为设置它的理由。布尔参数本身不是用户自然语言授权的证明，也不能保证模型永远正确选择工具。需要撤销任务完成状态时，应通过 `update_memory` 重新打开；已永久删除的内容不能用此接口恢复。
+
+这是 MCP 删除接口的兼容性变更：旧客户端应只在已有明确永久遗忘要求时补传 `confirm_delete=true`。Python Core 的 `forget_memory` / `forget_about` 原有删除语义及参数保持不变。

{memleaf-0.2.83 → memleaf-0.2.85}/pyproject.toml

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

{memleaf-0.2.83 → memleaf-0.2.85}/src/memleaf/__init__.py

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

@@ -199,6 +199,7 @@ def _append_event(
     final: bool | None,
     tool_evidence: list[dict[str, str]] | None = None,
     explicit_input: dict[str, Any] | None = None,
+    comparison_context: dict[str, Any] | None = None,
 ) -> str:
     if not existing:
         existing = _new_session_text(source, session_id, captured_at)
@@ -232,6 +233,8 @@ def _append_event(
         metadata["final"] = final
     if explicit_input is not None:
         metadata["explicit_input"] = explicit_input
+    if comparison_context is not None:
+        metadata["comparison_context"] = comparison_context
     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=(",", ":"))
@@ -359,6 +362,8 @@ def _payload_digest(metadata: Mapping[str, Any], content: str) -> str:
     if metadata.get("explicit_input") is not None:
         from .explicit_text_source import validate_origin
         value["explicit_input"] = validate_origin(metadata["explicit_input"])
+    if metadata.get("comparison_context") is not None:
+        value["comparison_context"] = metadata["comparison_context"]
     value["content"] = content.rstrip("\n")
     return hashlib.sha256(json.dumps(value, ensure_ascii=False, sort_keys=True,
                                     separators=(",", ":")).encode("utf-8")).hexdigest()
@@ -414,7 +419,7 @@ def recover_capture_receipts_unlocked(vault: Vault, processed: dict, path: Path)
             turn_key_value=metadata["turn_key"], turn_index=metadata["turn_index"],
             message_id=metadata["message_id"], message_revision=metadata["message_revision"],
         )
-        entry = {field: metadata[field] for field in (*_IMMUTABLE_EVENT_FIELDS, "turn_id", "turn_index", "captured_at", "explicit_input")
+        entry = {field: metadata[field] for field in (*_IMMUTABLE_EVENT_FIELDS, "turn_id", "turn_index", "captured_at", "explicit_input", "comparison_context")
                  if field in metadata}
         entry.update(event_key=key, payload_digest=digest)
         events[key] = entry
@@ -447,6 +452,8 @@ def capture_event(
     previous_message_id: Optional[str] = None,
     final: Optional[bool] = None,
     _explicit_input: dict[str, Any] | None = None,
+    retrieval_id: Optional[str] = None,
+    retrieval_turn_id: Optional[str] = None,
 ) -> CaptureResult:
     """Capture one visible event; all persisted text is redacted first."""
 
@@ -478,6 +485,9 @@ def capture_event(
         # Opting into source envelopes does not implicitly certify completion.
         # Old callers with no source metadata retain their legacy boundary.
         final = False
+    if (retrieval_id is None) != (retrieval_turn_id is None) or (
+            retrieval_id is not None and (role != "assistant" or retrieval_turn_id != turn_id)):
+        raise ValueError("invalid_comparison_binding")
     resolved_event_id, resolved_message_id, resolved_event_key = _event_identity(
         source, session_id, turn_id, role, event_id, message_id, message_revision
     )
@@ -488,6 +498,31 @@ def capture_event(
     if not visible or role not in ("user", "assistant"):
         return CaptureResult(resolved_event_id, stored=False, duplicate=False, content=safe_content)
 
+    comparison_context = None
+    if retrieval_id is not None:
+        # Never hold the vault lock while acquiring the retrieval lock: gated
+        # reads acquire them in the opposite order. Durable retries reuse their
+        # immutable receipt even after the short-lived gate has expired.
+        with vault.lock():
+            recovered = _read_processed(vault.processed_state_path)
+            from .recording_policy import recording_allowed
+            comparison_permitted = record and recording_allowed(recovered, source, session_id, resolved_turn_key)
+            if comparison_permitted:
+                path = vault.session_path(source, session_id)
+                if path.is_symlink():
+                    raise ValueError("unsafe inbox session path")
+                if recover_capture_receipts_unlocked(vault, recovered, path):
+                    atomic_write_json(vault.processed_state_path, recovered)
+            receipt = recovered.get("events", {}).get(resolved_event_key, {})
+            saved = receipt.get("comparison_context") if isinstance(receipt, Mapping) else None
+        if (isinstance(saved, dict) and saved.get("retrieval_id") == retrieval_id
+                and saved.get("turn_id") == retrieval_turn_id):
+            comparison_context = saved
+        elif comparison_permitted:
+            from .retrieval_gate import snapshot_read_context
+            comparison_context = snapshot_read_context(vault, retrieval_id,
+                source=source, session_id=session_id, turn_id=retrieval_turn_id)
+
     with vault.lock():
         processed = _read_processed(vault.processed_state_path)
         if _explicit_input is not None:
@@ -526,6 +561,8 @@ def capture_event(
             "previous_message_revision": previous_message_revision, "source_sequence": source_sequence,
             "previous_message_id": previous_message_id, "source_time": source_time, "final": final,
         }
+        if retrieval_id is not None:
+            incoming["comparison_context"] = comparison_context
         if _explicit_input is not None:
             incoming["explicit_input"] = _explicit_input
         digest = _payload_digest(incoming, safe_content)
@@ -584,6 +621,7 @@ def capture_event(
             final=final,
             tool_evidence=safe_tool_evidence,
             explicit_input=_explicit_input,
+            comparison_context=comparison_context,
         )
         atomic_write_text(path, updated)