memleaf 0.2.84__tar.gz → 0.2.86__tar.gz

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

@@ -4,6 +4,54 @@ All notable changes to memleaf are documented here.
 
 ## Unreleased
 
+## 0.2.86 — 2026-10-04
+
+### Source-bound Hermes retention and general extraction compatibility
+
+- Queue Hermes explicit retention against a stable host turn, then use the
+  actual captured user messages, IDs, timestamps and order. Register the native
+  `memleaf_remember` tool before Provider initialization and configure Hermes to
+  exclude the unbound standalone MCP `remember` tool without changing the public
+  MCP tool list. Queued retention is not reported as a completed save.
+- Preserve bound intent identity across a unique declared compression lineage.
+  Atomically admit one run per intent and check recording authorization across
+  the whole lineage before model dispatch, commit and frozen-work recovery.
+  Unrelated sessions, stale live tokens and ambiguous lineage remain rejected.
+- Normalize equivalent flat/nested field representations with the same compiler
+  and review rules; reject conflicts, retain unknown fields as unknown, and store
+  retraction explanations separately from the empty retracted body.
+- Add a bounded semantic veto for proposed actions, responsibility and deadlines.
+  It can only reject unsupported proposals or remove unverified fields, never
+  invent facts or authorization. Extraction and verification share the existing
+  two-request limit; malformed verification blocks writes.
+- Rank existing comparison candidates using generic normalized terms and their
+  rarity. Keep scope, revision and candidate bounds; explicit write receipts
+  prioritize comparison without skipping independent new information or forcing
+  similar-title merges.
+- Maintain proven completed runtime records before admitting new work, using
+  existing lossless compaction under the writer lock. Preserve unresolved runs
+  and spent allowances. Return specific capacity errors and explicit partial or
+  stale-query guidance instead of implying all work completed.
+- Fix history source statistics double counting while retaining exact legacy
+  recovery compatibility. No historical memory or failed-run migration occurs.
+- Validation: 587 affected checks, 32 checks in the actual Hermes interpreter,
+  64 isolated real-model turns and 58 developer semantic checks passed. Native
+  Hermes MemoryManager/stdio MCP tests covered source times, compression,
+  cross-midnight updates and repeated callbacks. Full Desktop acceptance still
+  requires installation and a Hermes restart.
+
+## 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

{memleaf-0.2.84/src/memleaf.egg-info → memleaf-0.2.86}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: memleaf
-Version: 0.2.84
+Version: 0.2.86
 Summary: A local-first Markdown memory core for AI agents
 Author: memleaf contributors
 License-Expression: MIT
@@ -23,10 +23,10 @@ Dynamic: license-file
 
 [English](README.en.md) · [PyPI](https://pypi.org/project/memleaf/) · [GitHub](https://github.com/miffyblueboo/memleaf)
 
-> **版本：0.2.84。**
+> **版本：0.2.86。**
 > 自动提炼和复核共用同一条“未来记忆价值”标准：模型综合未来复用、信息增量、再次读取时的直接可用性和忘记成本，只保留对未来理解、判断或行动有实质影响的最小核心；没有明确价值的信息不提炼，不按具体业务场景硬编码排除。
 > 提炼先比较旧事项中的编号、目标、进展、责任和期限；补全未知信息也应维护原事项，另建独立待办不能替代项目事实更新。Core 不按标题强行合并。
-> 新请求使用 `field-reviewed-v1`：CREATE/UPDATE 显式判断结构化期限；未知执行人填 `null`，新增或变更非空负责人必须引用来源原文。Core 校验字段和来源，模型判断业务含义；非法行进入现有 partial 处理。来源时间用于解析相对日期，不补造事实日期。
+> 新请求兼容等价的字段表示；未知执行人保持 `null`，新增或变更负责人、等待方和期限需要真实来源。行动及相关字段经过有界语义复核，提炼与复核共用每份工作的最多两次模型请求额度；复核失败不写入。来源时间用于解析相对日期，不补造事实日期。
 > 待办 `due_date` 只表示待办动作本身明确声明的截止日；属于待办主题或预期结果的日期不会被误作截止日。项目归属由模型按语义判断，不要求项目名在证据里逐字出现。复核阶段会保留首轮已选定的更新目标，避免“状态变更”被降级成新增记忆。Markdown 仍是唯一事实源。
 > **当前版本支持 Hermes 和 Codex。** Antigravity（反重力）不检测、不安装、不配置。
 
@@ -166,12 +166,14 @@ python -m pip install -U memleaf && python -m memleaf install
 3. 发现并保存可用的聊天模型路由；Hermes CLI 返回的脱敏凭证不会被当成真实 API key，而会继续尝试环境变量和 Hermes `.env`；已有有效 memleaf 路由会保留；
 4. 激活 `memory.provider=memleaf`；
 5. 通过 Hermes 官方 CLI 配置 memleaf MCP；
-6. 配置 MCP lazy/idle 生命周期；
+6. 配置 MCP lazy/idle 生命周期，以及绑定真实用户消息的 Hermes 原生保存工具；
 7. 验证 MCP Server 能发现当前版本声明的全部工具；
 8. 写入本地 Agent 状态索引。
 
 完成后重启 Hermes。
 
+Hermes 显式保存使用原生 `memleaf_remember`：先绑定本轮并排队，轮次完成后再以真实用户消息提炼，排队不表示已保存。安装器会在 Hermes 中屏蔽独立 MCP `remember`，保留其他工具选择；Core/Python API 和其他客户端的 `remember` 继续可用。仅升级 pip 包不足以更新 Provider 和这项工具配置。
+
 如果没有检测到 Hermes、无法取得完整模型路由、Provider 激活失败或 MCP 工具发现验证失败，安装会明确返回失败，不会把未完成的接入报告为成功。
 
 仓库中的 `install.sh` 保留给源码开发、离线源码安装和故障排查；普通 PyPI 用户不需要执行它。
@@ -359,6 +361,8 @@ python -m memleaf.mcp_server --vault /path/to/your/vault \
 
 捕获、索引、目录检索和读取可离线运行；`process()`、`remember()` 和 `compact()` 需要可用的模型能力。
 
+包含行动或责任、期限变更的增量候选通常会追加一次语义复核；每份增量工作最多两次请求，格式修复也计入同一额度。
+
 `llm.mode` 支持：
 
 - `auto`：优先使用显式注入的 host backend，失败后回退到完整 API 路由；

{memleaf-0.2.84 → memleaf-0.2.86}/README.en.md

@@ -4,10 +4,10 @@
 
 [中文](README.md) · [PyPI](https://pypi.org/project/memleaf/) · [GitHub](https://github.com/miffyblueboo/memleaf)
 
-> **Version: 0.2.84.**
+> **Version: 0.2.86.**
 > 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.
+> New requests accept equivalent field representations. Unknown executors remain `null`; new or changed responsibility, dependencies and deadlines require actual source evidence. Proposed actions and related fields undergo bounded semantic verification within the existing two-request limit per work item; failed verification blocks writes. Source time resolves relative dates without inventing factual dates.
 > A todo's `due_date` means only the explicit deadline of the todo action; dates describing its subject or desired outcome are not deadlines. Project ownership remains the model's semantic judgement and needs no literal name match. The review stage now keeps the update target chosen by the first pass, so a state change is no longer downgraded into a new memory. Markdown remains the sole source of truth.
 > **The current release supports Hermes and Codex.** Antigravity is not detected, installed, or configured.
 
@@ -147,12 +147,14 @@ Both installation paths automatically:
 3. Discover and save a callable chat-model route. Redacted credentials returned by the Hermes CLI are never treated as real API keys; discovery falls through to environment variables and Hermes `.env`, while preserving an existing valid memleaf route.
 4. Activate `memory.provider=memleaf`.
 5. Configure the memleaf MCP entry through Hermes' official CLI.
-6. Configure MCP lazy/idle lifecycle settings.
+6. Configure MCP lazy/idle lifecycle settings and the source-bound native Hermes retention tool.
 7. Verify that the MCP server exposes all tools declared by the installed version.
 8. Record the local Agent integration status.
 
 Restart Hermes after installation.
 
+Hermes uses native `memleaf_remember` to queue a request bound to the current turn, then retain the actual user messages after the turn completes. Queued does not mean saved. The installer excludes standalone MCP `remember` in Hermes while preserving other tool choices; the Core/Python API and other clients keep `remember`. Upgrading only the pip package does not refresh the Provider or this tool configuration.
+
 If Hermes cannot be detected, no complete model route can be configured, Provider activation fails, or MCP tool-discovery verification fails, the installer returns an explicit failure rather than reporting an incomplete integration as successful.
 
 The repository `install.sh` remains for source development, offline source installation, and troubleshooting. Normal PyPI users do not need to run it.

{memleaf-0.2.84 → memleaf-0.2.86}/README.md

@@ -4,10 +4,10 @@
 
 [English](README.en.md) · [PyPI](https://pypi.org/project/memleaf/) · [GitHub](https://github.com/miffyblueboo/memleaf)
 
-> **版本：0.2.84。**
+> **版本：0.2.86。**
 > 自动提炼和复核共用同一条“未来记忆价值”标准：模型综合未来复用、信息增量、再次读取时的直接可用性和忘记成本，只保留对未来理解、判断或行动有实质影响的最小核心；没有明确价值的信息不提炼，不按具体业务场景硬编码排除。
 > 提炼先比较旧事项中的编号、目标、进展、责任和期限；补全未知信息也应维护原事项，另建独立待办不能替代项目事实更新。Core 不按标题强行合并。
-> 新请求使用 `field-reviewed-v1`：CREATE/UPDATE 显式判断结构化期限；未知执行人填 `null`，新增或变更非空负责人必须引用来源原文。Core 校验字段和来源，模型判断业务含义；非法行进入现有 partial 处理。来源时间用于解析相对日期，不补造事实日期。
+> 新请求兼容等价的字段表示；未知执行人保持 `null`，新增或变更负责人、等待方和期限需要真实来源。行动及相关字段经过有界语义复核，提炼与复核共用每份工作的最多两次模型请求额度；复核失败不写入。来源时间用于解析相对日期，不补造事实日期。
 > 待办 `due_date` 只表示待办动作本身明确声明的截止日；属于待办主题或预期结果的日期不会被误作截止日。项目归属由模型按语义判断，不要求项目名在证据里逐字出现。复核阶段会保留首轮已选定的更新目标，避免“状态变更”被降级成新增记忆。Markdown 仍是唯一事实源。
 > **当前版本支持 Hermes 和 Codex。** Antigravity（反重力）不检测、不安装、不配置。
 
@@ -147,12 +147,14 @@ python -m pip install -U memleaf && python -m memleaf install
 3. 发现并保存可用的聊天模型路由；Hermes CLI 返回的脱敏凭证不会被当成真实 API key，而会继续尝试环境变量和 Hermes `.env`；已有有效 memleaf 路由会保留；
 4. 激活 `memory.provider=memleaf`；
 5. 通过 Hermes 官方 CLI 配置 memleaf MCP；
-6. 配置 MCP lazy/idle 生命周期；
+6. 配置 MCP lazy/idle 生命周期，以及绑定真实用户消息的 Hermes 原生保存工具；
 7. 验证 MCP Server 能发现当前版本声明的全部工具；
 8. 写入本地 Agent 状态索引。
 
 完成后重启 Hermes。
 
+Hermes 显式保存使用原生 `memleaf_remember`：先绑定本轮并排队，轮次完成后再以真实用户消息提炼，排队不表示已保存。安装器会在 Hermes 中屏蔽独立 MCP `remember`，保留其他工具选择；Core/Python API 和其他客户端的 `remember` 继续可用。仅升级 pip 包不足以更新 Provider 和这项工具配置。
+
 如果没有检测到 Hermes、无法取得完整模型路由、Provider 激活失败或 MCP 工具发现验证失败，安装会明确返回失败，不会把未完成的接入报告为成功。
 
 仓库中的 `install.sh` 保留给源码开发、离线源码安装和故障排查；普通 PyPI 用户不需要执行它。
@@ -340,6 +342,8 @@ python -m memleaf.mcp_server --vault /path/to/your/vault \
 
 捕获、索引、目录检索和读取可离线运行；`process()`、`remember()` 和 `compact()` 需要可用的模型能力。
 
+包含行动或责任、期限变更的增量候选通常会追加一次语义复核；每份增量工作最多两次请求，格式修复也计入同一额度。
+
 `llm.mode` 支持：
 
 - `auto`：优先使用显式注入的 host backend，失败后回退到完整 API 路由；

{memleaf-0.2.84 → memleaf-0.2.86}/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.84 → memleaf-0.2.86}/pyproject.toml

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

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

@@ -1,6 +1,6 @@
 """Local-first Markdown memory core for AI agents."""
 
-__version__ = "0.2.84"
+__version__ = "0.2.86"
 
 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.84 → memleaf-0.2.86}/src/memleaf/acceptance.py

@@ -196,7 +196,7 @@ def plan_suite(suite: dict, *, repeats: int = 5) -> dict:
     turns = sum(len(c["turns"]) for c in suite["cases"])
     return {"version": VERSION, "suite_id": suite["suite_id"], "suite_sha256": _hash(_canonical(suite)),
             "cases": len(suite["cases"]), "turns_per_repeat": turns, "repeats": repeats,
-            "normal_request_upper_bound": turns * repeats,
+            "normal_request_upper_bound": turns * repeats * 2,
             "recovery_request_upper_bound": turns * repeats * 2,
             "model_calls": 0, "mode": "plan", "semantic_status": "not_run",
             "switch_authorized": False, "prompt_sha256": _hash(INCREMENTAL_SYSTEM.encode("utf-8")),

{memleaf-0.2.84 → memleaf-0.2.86}/src/memleaf/adapters/hermes.py

@@ -420,6 +420,58 @@ class HermesAdapter:
                 return False
         return True
 
+    def configure_retention_tools(self, detection=None):
+        """Keep one host-bound retention entry, preserving unrelated tool choices."""
+        import fnmatch
+        detection = detection or self.detect()
+        if detection.confidence != "high" or not detection.executable:
+            return False
+        key = "mcp_servers.memleaf.tools"
+        command = [detection.executable, "config", "get", key, "--json"]
+        try:
+            result = run_argv(self.runner, command, env=self.env)
+            if result.returncode == 0:
+                filters = json.loads(result.stdout)
+                if not isinstance(filters, dict):
+                    return False
+            elif "Config key not set: " + key in result.stdout + result.stderr:
+                filters = {}
+            else:
+                return False
+            updated = dict(filters)
+            from ..mcp_server import _TOOLS
+            def patterns(value):
+                if isinstance(value, str):
+                    return [value]
+                if isinstance(value, list) and all(isinstance(x, str) for x in value):
+                    return value
+                raise ValueError("invalid tool filter")
+            if "include" in updated:
+                selected = patterns(updated["include"])
+                managed = updated.pop("memleaf_bound_retention", None)
+                if (isinstance(managed, dict) and set(managed) == {"patterns", "applied"}
+                        and managed["applied"] == selected):
+                    selected = patterns(managed["patterns"])
+                known = [tool["name"] for tool in _TOOLS if tool["name"] != "remember"
+                    and any(fnmatch.fnmatchcase(tool["name"], pattern) for pattern in selected)]
+                # Retain explicit future names and original wildcard intent so
+                # reinstalling a newer declaration set does not freeze it.
+                literal = [name for name in selected if name != "remember" and not any(c in name for c in "*?[")]
+                updated["include"] = list(dict.fromkeys([*known, *literal]))
+                updated["memleaf_bound_retention"] = {"patterns": selected, "applied": updated["include"]}
+            else:
+                updated["exclude"] = list(dict.fromkeys([*patterns(updated.get("exclude", [])), "remember"]))
+            if updated == filters:
+                return True
+            written = run_argv(self.runner, [detection.executable, "config", "set", key,
+                json.dumps(updated, ensure_ascii=False)], env=self.env)
+            if written.returncode != 0:
+                return False
+            confirmed = run_argv(self.runner, command, env=self.env)
+            return confirmed.returncode == 0 and json.loads(confirmed.stdout) == updated
+        except (OSError, ValueError, TypeError):
+            return False
+
     def test_mcp(
         self,
         detection: Detection | None = None,

{memleaf-0.2.84 → memleaf-0.2.86}/src/memleaf/hermes_provider/README.md

@@ -10,7 +10,11 @@ Automatic capture and processing use only the visible user and assistant text.
 Tool calls and results, email or attachment bodies, and other hidden payloads are
 not automatic memory input.
 Hermes uses MCP `search` and `read` with the current `retrieval_id` for recall.
-MCP also supports explicit `remember`, `forget`, and maintenance operations.
+The native `memleaf_remember` tool queues explicit retention bound to the current
+turn; the completed capture supplies the original user messages and source times.
+A queued response is not a saved memory. The installer excludes standalone MCP
+`remember` in Hermes while preserving other configured tool choices. MCP still
+supports `remember` for other clients, plus `forget` and maintenance operations.
 This is a Soft Gate, not a guarantee that every answer has performed retrieval.
 
 Hermes discovers this directory when it is installed as:

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

@@ -1380,6 +1380,7 @@ class MemleafMemoryProvider(MemoryProvider):
             "current turn's retrieval_id exactly as supplied; a missing or mismatched "
             "token is a read failure, never a reason to fall back to a file tool. "
             "Read more only if needed; for ordinary relevance queries, do not read all entries to filter unrelated items. "
+            "When pipeline_status is pending/unknown, memory can lag recent conversation: qualify current-state claims. For partial or completed_with_unresolved writes, report only the individually committed changes, and say which remain unresolved; never claim the entire request succeeded. "
             "When the user asks for current "
             "todos, all unfinished work, urgent work, or work due in a time range, call memleaf MCP "
             "list_todos instead of relevance search; omit scope for a global query, follow every "
@@ -1390,7 +1391,7 @@ class MemleafMemoryProvider(MemoryProvider):
             "turns are durably captured into the local memleaf inbox. Automatic "
             "capture → process runs after your final answer and is authoritative: "
             "a capture only proves that the inbox received the turn. Until a "
-            "successful explicit remember or update tool result is visible, never "
+            "explicit tool result proves execution_status=completed and complete coverage, never "
             "say that the turn was saved to permanent memory, persisted, or "
             "记好了/已落库. For automatic handling, say only that you will process "
             "it through the workflow or that it is recorded in the current "
@@ -1402,7 +1403,8 @@ class MemleafMemoryProvider(MemoryProvider):
             "file writes to simulate success, and do not infer automatic success merely because "
             "active or history files exist. Automatic recall is a directory of "
             "scope identifiers, hierarchy, and aliases only; it never contains "
-            "memory IDs, titles, or bodies. Use deliberate remember/forget tools "
+            "memory IDs, titles, or bodies. For explicit retention use memleaf_remember with the current retrieval_id; it retains verified user messages after the complete turn is captured. Pending means not yet saved. Do not submit assistant-written facts through legacy MCP remember. "
+            "Use deliberate remember/forget tools "
             "only when the user explicitly asks for that operation. Automatic "
             "capture and processing use only visible user and assistant text; "
             "tool calls/results, email or attachment bodies, and other hidden "
@@ -2027,6 +2029,10 @@ class MemleafMemoryProvider(MemoryProvider):
                         retrieval_turn_id=retrieval_turn_id if role == "assistant" else None,
                     ):
                         return
+                if self._gate_enabled:
+                    self._call("remember_turn", {"phase": "complete", "source": "hermes",
+                        "session_id": effective_session, "turn_id": turn_id},
+                        stage="remember_turn", session_id=effective_session, turn_id=turn_id)
                 if not self._auto_process:
                     return
                 if not lineage_ready:
@@ -2072,9 +2078,9 @@ class MemleafMemoryProvider(MemoryProvider):
             bound.update(source="hermes", session_id=session, turn_id=turn_id,
                          intent_id="host-op-" + sha256((turn_id + "/" + tool_call_id + "/" + name).encode()).hexdigest())
             bound.pop("event_id", None)
-            # No source timestamp is assigned to an assistant-written composite
-            # explicit request; only the submitted text itself is its evidence.
-            bound.pop("source_time", None)
+            # New hosts route retention to the source-bound lifecycle tool.
+            # Never authorize the model's rewritten text as user evidence.
+            raise ValueError("memory_host_retention_requires_bound_tool")
         elif name == "scope_catalog":
             bound.update(source="hermes", session_id=session, turn_id=turn_id)
         else:
@@ -2092,10 +2098,25 @@ class MemleafMemoryProvider(MemoryProvider):
         return bound
 
     def get_tool_schemas(self) -> List[Dict[str, Any]]:
-        # memleaf-mcp remains configured separately for deliberate search,
-        # remember, and forget operations. The native provider owns automatic
-        # recall/capture only, avoiding duplicate tool names in Hermes.
-        return []
+        # Hermes registers schemas before initialize_all. Execution remains
+        # gated by the initialized host identity and write policy.
+        if not self._write_enabled:
+            return []
+        return [{"name": "memleaf_remember", "description": "Use only for an explicit user request to remember. Bind the actual complete user turn; never submit rewritten facts or scopes. Returns pending until the turn is captured and processed.",
+                 "parameters": {"type": "object", "properties": {"retrieval_id": {"type": "string"}},
+                                "required": ["retrieval_id"], "additionalProperties": False}}]
+
+    def handle_tool_call(self, tool_name: str, args: Dict[str, Any], **kwargs: Any) -> str:
+        if (tool_name != "memleaf_remember" or not self._write_enabled or not self._gate_enabled
+                or not isinstance(args, dict) or set(args) != {"retrieval_id"}):
+            return json.dumps({"error": {"code": "invalid_host_retention_request"}})
+        session = self._canonical_session_id(self._session_id)
+        if not isinstance(args["retrieval_id"], str) or args["retrieval_id"] != self._current_gate_id(session):
+            return json.dumps({"error": {"code": "host_retention_turn_mismatch"}, "saved": False})
+        result = self._call("remember_turn", {"phase": "queue", "retrieval_id": args["retrieval_id"]}, stage="remember_turn")
+        if result is _CALL_FAILED:
+            return json.dumps({"error": {"code": "host_retention_not_queued"}, "saved": False})
+        return json.dumps(result, ensure_ascii=False)
 
     def shutdown(self) -> None:
         with self._sync_lock:

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

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

memleaf-0.2.86/src/memleaf/host_retention.py

@@ -0,0 +1,167 @@
+"""Durable retention intent bound to a host turn, never model-written facts."""
+from __future__ import annotations
+
+from .incremental_journal import digest
+from .incremental_selection import explicit_run_id, bind_selection
+from .incremental_run_state import load_run, public_result
+from .process_common import _read_processed
+from .locking import atomic_write_json
+from .retrieval_gate import validate_turn, validate_current_turn
+
+KEY = "host_retention_intents"
+MAX_PENDING = 128
+INTENT_PREFIX = "host-retain-"
+
+
+def pending_intents(processed):
+    pending = processed.get(KEY, {})
+    if not isinstance(pending, dict) or len(pending) > MAX_PENDING:
+        raise ValueError("invalid_host_retention_intents")
+    for identity, row in pending.items():
+        if (not isinstance(row, dict) or set(row) != {"source", "session_id", "turn_id", "intent_id"}
+                or row["source"] != "hermes"
+                or any(not isinstance(row[k], str) or not row[k] for k in ("session_id", "turn_id"))
+                or identity != digest([row["source"], row["session_id"], row["turn_id"]])
+                or row["intent_id"] != "host-retain-" + identity):
+            raise ValueError("invalid_host_retention_intents")
+    return pending
+
+
+def _bound_intent(processed, source, session_id, *, turn_id=None, captured_key=None):
+    """Follow only declared ancestry for the SAME turn, never a latest session."""
+    from .index import turn_key
+    from .host_turn_identity import ancestors, continuation_path
+    lineage = ancestors(processed, source, session_id)
+    key = captured_key if captured_key is not None else turn_key(turn_id)
+    matches = [(identity, row) for identity, row in pending_intents(processed).items()
+               if row["source"] == source and row["session_id"] in lineage
+               and turn_key(row["turn_id"]) == key]
+    if len(matches) > 1:
+        raise ValueError("ambiguous_host_retention_intent")
+    if not matches:
+        return None
+    identity, row = matches[0]
+    # A fork is not proof that this branch owns the original queued request.
+    continuation_path(processed, source, session_id, row["session_id"])
+    return identity, row
+
+
+def check_run_authority(processed, run):
+    """Recheck the whole frozen authority path before dispatch and commit."""
+    origin = run.get("host_retention_origin")
+    if origin is None:
+        return
+    from .host_turn_identity import continuation_path
+    from .recording_policy import recording_allowed
+    path = continuation_path(processed, run["source"], run["session_id"], origin["session_id"])
+    if path is None or any(not recording_allowed(processed, run["source"], session, run["turn_key"])
+                           for session in path):
+        raise ValueError("source_recording_revoked")
+
+
+def validate_origin(origin, *, source, turn_key, intent_id):
+    if origin is None:
+        return
+    from .index import turn_key as key
+    if not isinstance(origin, dict):
+        raise ValueError("invalid_host_retention_origin")
+    pending_intents({KEY: {digest([origin.get(k) for k in ("source", "session_id", "turn_id")]): origin}})
+    if (origin["source"] != source or origin["intent_id"] != intent_id or key(origin["turn_id"]) != turn_key):
+        raise ValueError("invalid_host_retention_origin")
+
+
+def admit_unlocked(processed, *, source, session_id, turn_key, intent_id, run_id):
+    """Bind a reserved host authorization in the SAME lock as run creation."""
+    if not intent_id.startswith(INTENT_PREFIX):
+        return None  # Existing caller-defined explicit intent namespaces remain scoped.
+    from .incremental_run_state import KEY as RUNS
+    for identity in processed.get(RUNS, {}):
+        prior = load_run(processed, identity)
+        if prior.get("authorization_intent") == intent_id and identity != run_id:
+            raise ValueError("host_retention_source_binding_changed")
+    bound = _bound_intent(processed, source, session_id, captured_key=turn_key)
+    if bound is None or bound[1]["intent_id"] != intent_id:
+        raise ValueError("host_retention_intent_not_pending")
+    origin = dict(bound[1])
+    check_run_authority(processed, {"host_retention_origin": origin, "source": source,
+                                   "session_id": session_id, "turn_key": turn_key})
+    return origin
+
+
+def remember_turn(service, *, phase, retrieval_id=None, source=None, session_id=None, turn_id=None, model=None, router=None):
+    if phase == "queue":
+        state = validate_turn(service.vault, retrieval_id)
+        source, session_id, turn_id = (state.get(k) for k in ("source", "session_id", "turn_id"))
+        if source != "hermes":
+            raise ValueError("host_retention_identity_required")
+        validate_current_turn(service.vault, retrieval_id, source)
+    elif phase != "complete" or source != "hermes" or not all(isinstance(v, str) and v for v in (session_id, turn_id)):
+        raise ValueError("invalid_host_retention_phase")
+    identity = digest([source, session_id, turn_id])
+    intent = "host-retain-" + identity
+    with service.vault.lock():
+        processed = _read_processed(service.vault.processed_state_path)
+        pending = pending_intents(processed)
+        bound = _bound_intent(processed, source, session_id, turn_id=turn_id)
+        if bound is not None:
+            identity, expected = bound
+            intent = expected["intent_id"]
+        from .index import turn_key
+        from .recording_policy import recording_allowed
+        if (not recording_allowed(processed, source, session_id, turn_key(turn_id))
+                or bound is not None and not recording_allowed(processed, source, expected["session_id"], turn_key(turn_id))):
+            raise ValueError("source_recording_revoked")
+        if bound is not None:
+            check_run_authority(processed, {"host_retention_origin": expected, "source": source,
+                                           "session_id": session_id, "turn_key": turn_key(turn_id)})
+        if phase == "queue":
+            if identity not in pending and len(pending) >= MAX_PENDING:
+                raise ValueError("host_retention_intents_full")
+            if bound is None:
+                pending[identity] = {"source": source, "session_id": session_id, "turn_id": turn_id, "intent_id": intent}
+            processed[KEY] = pending
+            atomic_write_json(service.vault.processed_state_path, processed)
+            return {"execution_status": "queued", "saved": False,
+                    "guidance": "The actual user messages will be retained after this turn finishes. Do not claim permanent memory was saved yet."}
+        if bound is None:
+            return {"execution_status": "not_requested", "saved": False, "model_calls": 0}
+        # A started intent already owns its source and allowance. Compression
+        # cannot turn it into a fresh authorization with a fresh budget.
+        from .incremental_run_state import KEY as RUNS
+        for run_id in processed.get(RUNS, {}):
+            prior = load_run(processed, run_id)
+            if (prior.get("authorization_intent") == intent
+                    and (prior["source"], prior["session_id"]) != (source, session_id)):
+                raise ValueError("host_retention_source_binding_changed")
+        from .incremental_commit import _window
+        from .index import turn_key
+        turn, _ = _window(service, source, session_id, turn_key(turn_id))
+        users = [event for event in turn.events if event.role == "user"]
+        request = "\n\n".join(event.content for event in users)
+        refs = [event.event_key for event in users]
+        selection, request = bind_selection(intent, refs, request)
+        run = load_run(processed, explicit_run_id(source, session_id, selection))
+    if run is not None and run["status"] in {"completed", "completed_with_unresolved", "blocked", "failed", "cancelled"}:
+        result = public_result(run)
+    else:
+        result = service.remember_incremental(source=source, session_id=session_id, turn_id=turn_id,
+            intent_id=intent, selected_source_refs=refs, retention_request=request, model=model, router=router)
+    if result["execution_status"] == "completed":
+        with service.vault.lock():
+            processed = _read_processed(service.vault.processed_state_path)
+            if processed.get(KEY, {}).get(identity) == expected:
+                processed[KEY].pop(identity)
+                atomic_write_json(service.vault.processed_state_path, processed)
+    return result
+
+
+def complete_for_captured_turn(service, turn, *, model=None, router=None):
+    """Resume durable queued intent after host restart, without borrowing a newer turn."""
+    with service.vault.lock():
+        processed = _read_processed(service.vault.processed_state_path)
+        bound = _bound_intent(processed, turn.source, turn.session_id, captured_key=turn.turn_key)
+    if bound is None:
+        return None
+    _, row = bound
+    return remember_turn(service, phase="complete", source=turn.source, session_id=turn.session_id,
+                         turn_id=row["turn_id"], model=model, router=router)

memleaf-0.2.86/src/memleaf/host_turn_identity.py

@@ -0,0 +1,33 @@
+"""Declared, unambiguous continuation of a host session; no latest-turn lookup."""
+from __future__ import annotations
+
+from .vault import safe_component
+
+
+def ancestors(processed, source, session_id):
+    sessions = processed.get("sessions", {})
+    path = [session_id]
+    while True:
+        state = sessions.get(f"{source}/{path[-1]}", {})
+        parent = state.get("lineage_parent_session_id")
+        if parent is None:
+            return path
+        parent = safe_component(parent, "parent session id")
+        if parent in path or len(path) >= 16:
+            raise ValueError("invalid_host_retention_lineage")
+        path.append(parent)
+
+
+def continuation_path(processed, source, session_id, origin_session_id):
+    path = ancestors(processed, source, session_id)
+    if origin_session_id not in path:
+        return None
+    path = path[:path.index(origin_session_id) + 1]
+    sessions = processed.get("sessions", {})
+    for parent in path[1:]:
+        children = [name for name, state in sessions.items()
+                    if name.startswith(source + "/")
+                    and state.get("lineage_parent_session_id") == parent]
+        if len(children) != 1:
+            raise ValueError("ambiguous_host_retention_lineage")
+    return path