memleaf 0.2.83__tar.gz → 0.2.84__tar.gz

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

@@ -4,6 +4,28 @@ All notable changes to memleaf are documented here.
 
 ## Unreleased
 
+## 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.84}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: memleaf
-Version: 0.2.83
+Version: 0.2.84
 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.84。**
 > 自动提炼和复核共用同一条“未来记忆价值”标准：模型综合未来复用、信息增量、再次读取时的直接可用性和忘记成本，只保留对未来理解、判断或行动有实质影响的最小核心；没有明确价值的信息不提炼，不按具体业务场景硬编码排除。
 > 提炼先比较旧事项中的编号、目标、进展、责任和期限；补全未知信息也应维护原事项，另建独立待办不能替代项目事实更新。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.84}/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.84.**
 > 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.84}/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.84。**
 > 自动提炼和复核共用同一条“未来记忆价值”标准：模型综合未来复用、信息增量、再次读取时的直接可用性和忘记成本，只保留对未来理解、判断或行动有实质影响的最小核心；没有明确价值的信息不提炼，不按具体业务场景硬编码排除。
 > 提炼先比较旧事项中的编号、目标、进展、责任和期限；补全未知信息也应维护原事项，另建独立待办不能替代项目事实更新。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.84/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.84/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.84}/pyproject.toml

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

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

@@ -1,6 +1,6 @@
 """Local-first Markdown memory core for AI agents."""
 
-__version__ = "0.2.83"
+__version__ = "0.2.84"
 
 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.84}/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)
 

{memleaf-0.2.83 → memleaf-0.2.84}/src/memleaf/hermes_provider/_provider.py

@@ -29,6 +29,118 @@ def _capture_assistant_text(value: str) -> str:
                   flags=re.IGNORECASE)
 
 
+def _assistant_source_matches(messages: Any, content: str) -> bool:
+    """Accept exact text or an exactly reconstructed native verifier footer.
+
+    No generic prefix/suffix matching. Tool receipts are used only to check
+    Hermes' display transformation, never as message times or memory facts.
+    Unsupported host formats fail closed.
+    """
+    if not isinstance(messages, list) or not messages:
+        return False
+    final = messages[-1]
+    if not isinstance(final, Mapping) or final.get("role") != "assistant" or final.get("tool_calls"):
+        return False
+    raw = final.get("content")
+    if raw == content:
+        return True
+    if not isinstance(raw, str) or not raw.strip():
+        return False
+    try:
+        from agent.turn_explainers import TurnExplainersMixin
+        from agent.tool_dispatch_helpers import _extract_error_preview, _extract_file_mutation_targets
+        from agent.tool_result_classification import file_mutation_result_landed
+        # The last real user bounds the supported single-message legacy turn.
+        anchor = max(i for i, row in enumerate(messages[:-1])
+                     if isinstance(row, Mapping) and row.get("role") == "user")
+        tail = messages[anchor:-1]
+        calls, results = _visible_tool_calls(tail), _visible_tool_results(tail)
+        failed = {}
+        for call in calls:
+            name, args = call.get("name"), call.get("arguments")
+            if name not in {"write_file", "patch"} or not isinstance(args, Mapping):
+                continue
+            matches = [row for row in results if call.get("call_id")
+                       and row.get("call_id") == call["call_id"]]
+            if not matches:
+                # Hermes' persisted transcript can omit tool_call_id. Accept
+                # only one call immediately followed by its named tool row.
+                for index, row in enumerate(tail[:-1]):
+                    row_calls = _visible_tool_calls([row])
+                    following = tail[index + 1]
+                    if (len(row_calls) == 1 and row_calls[0] == call
+                            and isinstance(following, Mapping) and following.get("role") == "tool"
+                            and not following.get("tool_call_id")
+                            and following.get("name", following.get("tool_name")) == name):
+                        matches.append({"payload": following.get("content")})
+            if len(matches) != 1:
+                return False
+            payload = matches[0]["payload"]
+            decoded = _decode_tool_value(payload)
+            if not isinstance(decoded, Mapping):
+                return False
+            targets = _extract_file_mutation_targets(name, dict(args))
+            if decoded.get("error") and not file_mutation_result_landed(name, payload):
+                for path in targets:
+                    failed.setdefault(path, {"tool": name, "error_preview": _extract_error_preview(payload)})
+            else:
+                for path in targets:
+                    failed.pop(path, None)
+        footer = TurnExplainersMixin._format_file_mutation_failure_footer(failed)
+        return bool(footer) and content == raw.rstrip() + "\n\n" + footer
+    except (ImportError, AttributeError, TypeError, ValueError, KeyError):
+        return False
+
+
+def _legacy_correction_users(messages: Any, merged: str) -> Optional[list[Mapping[str, Any]]]:
+    """Check the actual bounded correction rows against Hermes' merge format.
+
+    Never split user text by a delimiter. Admission rows and the native replay
+    scaffold identify corrections; full reconstruction must match uniquely.
+    """
+    if not isinstance(messages, list) or not messages:
+        return None
+    users = []
+    for row in reversed(messages[:-1]):
+        if not isinstance(row, Mapping) or row.get("role") != "user":
+            continue
+        if not isinstance(row.get("content"), str) or not row["content"].strip():
+            return None
+        users.append(row)
+        if len(users) > 63:
+            return None
+        api = row.get("api_content")
+        correction = (isinstance(api, str) and api.startswith(
+            "[Context from the interrupted assistant response]\n[This response was interrupted by a user correction.]")
+            and api.endswith("\n\n" + row["content"]))
+        if not correction:
+            break
+    if len(users) < 2:
+        return None
+    users.reverse()
+    reconstructed = users[0]["content"]
+    for row in users[1:]:
+        reconstructed += "\n\nUser correction during the turn: " + row["content"]
+    return users if reconstructed == merged else None
+
+
+def _sync_delivery_digest(messages: Any, users: Any, user_content: str, assistant_content: str) -> str:
+    """Disambiguate identical text deliveries using verified host source rows."""
+    identities = []
+    if _assistant_source_matches(messages, assistant_content):
+        for row in [*(users or []), messages[-1]]:
+            uid = row.get("message_uid") or row.get("message_id")
+            timestamp = _independent_assistant_time(row, "").get("assistant", {}).get("source_time")
+            if not uid and not timestamp:
+                identities = []
+                break
+            identities.append((uid, timestamp))
+    payload = f"{user_content}\x00{_capture_assistant_text(assistant_content)}"
+    if identities:
+        payload += "\x00" + json.dumps(identities, ensure_ascii=False, separators=(",", ":"))
+    return sha256(payload.encode()).hexdigest()[:16]
+
+
 def _sync_source_metadata(messages: Any, user_content: str, assistant_content: str) -> dict[str, dict[str, Any]]:
     """Read optional host metadata only from the exact visible tail pair.
 
@@ -43,8 +155,7 @@ def _sync_source_metadata(messages: Any, user_content: str, assistant_content: s
         logger.info("memleaf source-metadata reason=messages_missing")
         return {}
     assistant = messages[-1]
-    if (not isinstance(assistant, Mapping) or assistant.get("role") != "assistant"
-            or assistant.get("content") != assistant_content or assistant.get("tool_calls")):
+    if not _assistant_source_matches(messages, assistant_content):
         logger.info("memleaf source-metadata reason=assistant_mismatch")
         return {}
     # Tool rounds do not define a turn boundary. Stop at the nearest user,
@@ -149,7 +260,7 @@ def _host_visible_events(messages: Any, context: Any, session_id: str,
         return None
     final = messages[-1]
     if (not isinstance(final, Mapping) or final.get("role") != "assistant"
-            or final.get("content") != assistant_content or final.get("tool_calls")):
+            or not _assistant_source_matches(messages, assistant_content)):
         return None
     completed_uid = context.get("completed_assistant_message_id")
     completed = completed_uid is not None
@@ -195,7 +306,7 @@ def _host_visible_events(messages: Any, context: Any, session_id: str,
     final_metadata = {}
     for _, item in found:
         user = dict(item, message_id=item["message_uid"])
-        pair = _sync_source_metadata([user, assistant], user["content"], assistant_content)
+        pair = _sync_source_metadata([user, assistant], user["content"], assistant["content"])
         events.append({"role": "user", "content": user["content"], "metadata": pair.get("user", {})})
         final_metadata = pair.get("assistant", {})
     # Never manufacture a sequence by assuming a turn always has two events.
@@ -1040,8 +1151,9 @@ class MemleafMemoryProvider(MemoryProvider):
         turn_number: Optional[int],
         user_content: str,
         assistant_content: str,
+        delivery_digest: Optional[str] = None,
     ) -> str:
-        pair_digest = sha256(f"{user_content}\x00{assistant_content}".encode("utf-8")).hexdigest()[:16]
+        pair_digest = delivery_digest or sha256(f"{user_content}\x00{assistant_content}".encode("utf-8")).hexdigest()[:16]
         pair_key = (session_id, pair_digest)
         existing = self._turn_ids_by_pair.get(pair_key)
         if existing is not None and turn_number is None:
@@ -1481,6 +1593,8 @@ class MemleafMemoryProvider(MemoryProvider):
         source_sequence: int | None = None,
         final: bool | None = None,
         source_metadata: Mapping[str, Any] | None = None,
+        retrieval_id: str | None = None,
+        retrieval_turn_id: str | None = None,
     ) -> bool:
         metadata = {
             key: value for key, value in (source_metadata or {}).items()
@@ -1500,6 +1614,8 @@ class MemleafMemoryProvider(MemoryProvider):
                 **({"source_sequence": source_sequence} if source_sequence is not None else {}),
                 **({"final": final} if final is not None else {}),
                 **metadata,
+                **({"retrieval_id": retrieval_id, "retrieval_turn_id": retrieval_turn_id}
+                   if retrieval_id and retrieval_turn_id and role == "assistant" else {}),
                 "record": True,
                 "visible": True,
             },
@@ -1783,6 +1899,10 @@ class MemleafMemoryProvider(MemoryProvider):
             return
 
         effective_session = self._canonical_session_id(session_id or self._session_id)
+        # Snapshot the list at invocation; subsequent tool/turn appends cannot
+        # change which source rows this callback verifies.
+        import copy
+        messages = copy.deepcopy(messages)
         # Hermes serializes provider sync work, but this lock also protects
         # direct/plugin-level concurrent calls and makes process one-shot per
         # captured turn within this provider instance.
@@ -1798,30 +1918,60 @@ class MemleafMemoryProvider(MemoryProvider):
                 if turn_context is not None and host_events is None:
                     logger.info("memleaf source-metadata reason=host_event_mismatch")
                     return
+                correction_users = (_legacy_correction_users(messages, user_content)
+                                    if host_events is None else None)
+                queued_content = correction_users[0]["content"] if correction_users else user_content
+                source_users = correction_users
+                if source_users is None and isinstance(messages, list):
+                    nearest = next((row for row in reversed(messages[:-1])
+                                    if isinstance(row, Mapping) and row.get("role") == "user"), None)
+                    source_users = [nearest] if nearest and nearest.get("content") == user_content else None
+                delivery_digest = _sync_delivery_digest(messages, source_users, user_content, raw_assistant_content)
                 resolved_turn_number = turn_number
                 if bound_turn_id and type(turn_context.get("turn_number")) is int:
                     resolved_turn_number = turn_context["turn_number"]
                 if resolved_turn_number is None:
-                    resolved_turn_number = self._take_turn_number(effective_session, user_content)
+                    # Check this source delivery before consuming another same-text
+                    # admission. Old callbacks must not take the next turn's gate.
+                    import re
+                    cached = self._turn_ids_by_pair.get((effective_session, delivery_digest), "")
+                    if cached:
+                        numbers = [number for (session, number), identity in self._gate_turn_ids.items()
+                                   if session == effective_session and identity == cached]
+                        pair = sha256(f"{user_content}\x00{captured_assistant_content}".encode()).hexdigest()[:16]
+                        match = re.fullmatch(r"turn-([0-9]+)-" + pair, cached)
+                        if len(numbers) == 1:
+                            resolved_turn_number = numbers[0]
+                        elif match:
+                            resolved_turn_number = int(match[1])
+                    elif (messages is None or source_users and _assistant_source_matches(messages, raw_assistant_content)):
+                        resolved_turn_number = self._take_turn_number(effective_session, queued_content)
                 elif isinstance(resolved_turn_number, int) and not isinstance(resolved_turn_number, bool):
-                    queued_content = host_events[0]["content"] if host_events else user_content
+                    queued_content = host_events[0]["content"] if host_events else queued_content
                     self._discard_turn_number(effective_session, queued_content, resolved_turn_number)
                 turn_id = self._resolve_turn_id(
                     effective_session,
                     resolved_turn_number,
                     user_content,
                     captured_assistant_content,
+                    delivery_digest=delivery_digest,
                 )
-                source_metadata = ({} if host_events is not None else
+                source_metadata = ({} if host_events is not None or correction_users else
                                    _sync_source_metadata(messages, user_content, raw_assistant_content))
                 user_source_id = source_metadata.get("user", {}).get("message_id")
+                retrieval_id = self._gate_id_for_turn(effective_session, resolved_turn_number)
+                retrieval_turn_id = self._gate_turn_id(effective_session, resolved_turn_number)
                 if bound_turn_id:
                     turn_id = bound_turn_id
+                elif retrieval_id and retrieval_turn_id:
+                    # Reuse the identity frozen at on_turn_start. Comparison
+                    # reads and capture must refer to the identical host turn.
+                    turn_id = retrieval_turn_id
                 elif user_source_id:
                     # Stable host identity survives a revised body/final reply.
                     turn_id = "source-" + sha256(user_source_id.encode("utf-8")).hexdigest()[:24]
                     source_metadata["assistant"].setdefault("previous_message_id", user_source_id)
-                retrieval_id = self._gate_id_for_turn(effective_session, resolved_turn_number)
+                self._turn_ids_by_pair[(effective_session, delivery_digest)] = turn_id
                 # A background callback must never attach itself to a newer turn.
                 if self._gate_enabled:
                     audit_state: dict[str, Any] = {}
@@ -1850,6 +2000,21 @@ class MemleafMemoryProvider(MemoryProvider):
                                       for role, content in visible_events]
                     sequence_base = (resolved_turn_number * 2
                                      if not bound_turn_id and isinstance(resolved_turn_number, int) else None)
+                    if correction_users and resolved_turn_number is not None and _assistant_source_matches(messages, raw_assistant_content):
+                        # Capture each verified source row separately. A correction's
+                        # timestamp never becomes the timestamp of the merged text.
+                        capture_events = []
+                        for index, row in enumerate(correction_users):
+                            pair = _sync_source_metadata([row, messages[-1]], row["content"], messages[-1]["content"])
+                            metadata = pair.get("user", {})
+                            metadata["message_id"] = row.get("message_uid") or f"{turn_id}/user-{index}"
+                            capture_events.append({"role": "user", "content": row["content"], "metadata": metadata})
+                        assistant_metadata = pair.get("assistant", {})
+                        assistant_metadata["previous_message_id"] = capture_events[-1]["metadata"]["message_id"]
+                        capture_events.append({"role": "assistant", "content": captured_assistant_content,
+                                               "metadata": assistant_metadata})
+                        sequence_base = None
+                        logger.info("memleaf source-metadata contract=legacy-corrections user_events=%d", len(correction_users))
                 for offset, event in enumerate(capture_events):
                     role = event["role"]
                     if not self._capture_visible(
@@ -1858,6 +2023,8 @@ class MemleafMemoryProvider(MemoryProvider):
                         source_sequence=(sequence_base + offset if sequence_base is not None else None),
                         final=True if role == "assistant" else None,
                         source_metadata=event["metadata"],
+                        retrieval_id=retrieval_id if role == "assistant" else None,
+                        retrieval_turn_id=retrieval_turn_id if role == "assistant" else None,
                     ):
                         return
                 if not self._auto_process:

{memleaf-0.2.83 → memleaf-0.2.84}/src/memleaf/hermes_provider/plugin.yaml

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

{memleaf-0.2.83 → memleaf-0.2.84}/src/memleaf/inbox.py

@@ -62,6 +62,7 @@ class InboxEvent:
     tool_evidence: tuple[dict[str, str], ...] = ()
     legacy: bool = False
     explicit_input: dict[str, Any] | None = None
+    comparison_context: dict[str, Any] | None = None
 
     @property
     def processable(self) -> bool:
@@ -306,6 +307,8 @@ def parse_inbox_text(
                 timestamp=source_time if isinstance(source_time, str) and source_time else None,
                 tool_evidence=_bounded_tool_evidence(metadata.get("tool_evidence")),
                 explicit_input=explicit_input,
+                comparison_context=(metadata.get("comparison_context")
+                                    if isinstance(metadata.get("comparison_context"), dict) else None),
             )
         )