memleaf 0.2.68__tar.gz → 0.2.69__tar.gz

{memleaf-0.2.68 → memleaf-0.2.69}/CHANGELOG.md

@@ -4,6 +4,14 @@ All notable changes to memleaf are documented here.
 
 ## Unreleased
 
+## 0.2.69 — 2026-09-21
+
+### Incremental protocol compatibility hardening
+
+- Advance the incremental semantic protocol to `incremental-turn-v5` and expose precise field-shape details for fail-closed rows.
+- Normalize only unambiguous model serialization variants: null placeholders from other branches, a null CREATE wrapper, a single-item `scopes` alias, default `validity`, and flattened CREATE fields. Ambiguous aliases and unknown fields remain rejected.
+- Keep the new normalization behavior covered by the public protocol and provider-compatibility tests.
+
 ## 0.2.68 — 2026-09-20
 
 ### Hermes live-path hardening

{memleaf-0.2.68/src/memleaf.egg-info → memleaf-0.2.69}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: memleaf
-Version: 0.2.68
+Version: 0.2.69
 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.65。**
+> **版本：0.2.69。**
 > 自动提炼和复核共用同一条“未来记忆价值”标准：模型综合未来复用、信息增量、再次读取时的直接可用性和忘记成本，只保留对未来理解、判断或行动有实质影响的最小核心；没有明确价值的信息不提炼，不按具体业务场景硬编码排除。
 > 提炼契约现在只有一份中文语义契约（旧版英文 B3 提示词已删除），首轮、主题选择、候选修复和 `semantic_maintenance` 使用同一套保留价值判断；同一件事只写一次。
 > Core 不再因为归属、日期、任务依据或跨项目而丢弃整条候选：归属缺失会归一到证据里唯一被点名的项目、否则落 `global`；日期只接受能在本候选证据里找到出处、且能锚定成 ISO 的写法（`明天`、`周五`、`月底` 都会被解析），无法解析时只丢掉日期字段，记忆照常写入；未获授权的改归属沿用目标原归属。

{memleaf-0.2.68 → memleaf-0.2.69}/README.en.md

@@ -4,7 +4,7 @@
 
 [中文](README.md) · [PyPI](https://pypi.org/project/memleaf/) · [GitHub](https://github.com/miffyblueboo/memleaf)
 
-> **Version: 0.2.65.**
+> **Version: 0.2.69.**
 > 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.
 > A single Chinese semantic contract is sent for extraction, topic selection, candidate repair, and `semantic_maintenance`; the older English B3 prompt has been deleted and B3 remains only as a compatibility read format. One topic is written once.
 > Core no longer discards a whole candidate over ownership, dates, task basis or cross-project wording. A missing owner normalizes to the single project named by that candidate's own evidence, otherwise `global`. A deadline is accepted only when it appears in the candidate's own evidence and can be anchored to ISO (`明天`, `周五`, `月底` all resolve); when it cannot, only the date field is dropped and the memory is still written. An unauthorized ownership change keeps the target's existing scope.

{memleaf-0.2.68 → memleaf-0.2.69}/README.md

@@ -4,7 +4,7 @@
 
 [English](README.en.md) · [PyPI](https://pypi.org/project/memleaf/) · [GitHub](https://github.com/miffyblueboo/memleaf)
 
-> **版本：0.2.65。**
+> **版本：0.2.69。**
 > 自动提炼和复核共用同一条“未来记忆价值”标准：模型综合未来复用、信息增量、再次读取时的直接可用性和忘记成本，只保留对未来理解、判断或行动有实质影响的最小核心；没有明确价值的信息不提炼，不按具体业务场景硬编码排除。
 > 提炼契约现在只有一份中文语义契约（旧版英文 B3 提示词已删除），首轮、主题选择、候选修复和 `semantic_maintenance` 使用同一套保留价值判断；同一件事只写一次。
 > Core 不再因为归属、日期、任务依据或跨项目而丢弃整条候选：归属缺失会归一到证据里唯一被点名的项目、否则落 `global`；日期只接受能在本候选证据里找到出处、且能锚定成 ISO 的写法（`明天`、`周五`、`月底` 都会被解析），无法解析时只丢掉日期字段，记忆照常写入；未获授权的改归属沿用目标原归属。

{memleaf-0.2.68 → memleaf-0.2.69}/pyproject.toml

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

{memleaf-0.2.68 → memleaf-0.2.69}/src/memleaf/__init__.py

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

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

{memleaf-0.2.68 → memleaf-0.2.69}/src/memleaf/incremental_protocol.py

@@ -22,7 +22,7 @@ from .turn_plan import revision_digest
 from .validation import ModelOutputError, parse_strict_json
 
 PROTOCOL_VERSION = "incremental-items-v1"
-SEMANTIC_PROTOCOL = "incremental-turn-v4"
+SEMANTIC_PROTOCOL = "incremental-turn-v5"
 MAX_BYTES = 128 * 1024
 MAX_ITEMS = 64
 _TYPES = frozenset(("fact", "todo", "preference", "project", "event", "identity", "other"))
@@ -38,6 +38,64 @@ _BRANCHES = {
 }
 
 _CREATE_ROW_META = frozenset(("action", "evidence", "at", "effective"))
+_ROW_FIELDS = frozenset(
+    {"action", "evidence"}.union(*(required | optional for required, optional in _BRANCHES.values()))
+)
+
+
+class _FieldShapeError(ValueError):
+    def __init__(self, detail: str):
+        super().__init__("invalid_fields")
+        self.detail = detail
+
+
+def _normalize_create_fields(fields: Any) -> tuple[Any, list[str]]:
+    """Normalize model serialization aliases that preserve one exact meaning."""
+    if not isinstance(fields, dict):
+        return fields, []
+    normalized = deepcopy(fields)
+    warnings = []
+    if "scope" not in normalized and isinstance(normalized.get("scopes"), list):
+        scopes = normalized["scopes"]
+        if len(scopes) == 1 and isinstance(scopes[0], str):
+            normalized["scope"] = scopes[0]
+            normalized.pop("scopes")
+            warnings.append("create_single_scope_alias_normalized")
+    if normalized.get("validity") == "valid":
+        normalized.pop("validity")
+        warnings.append("create_default_validity_normalized")
+    return normalized, warnings
+
+
+def _normalize_model_row(row: Any) -> tuple[Any, list[str]]:
+    """Remove only semantically empty branch placeholders and normalize CREATE aliases."""
+    if not isinstance(row, dict) or not isinstance(row.get("action"), str):
+        return row, []
+    action = row["action"].strip().upper()
+    if action not in _BRANCHES:
+        return row, []
+    normalized = deepcopy(row)
+    warnings = []
+    required, optional = _BRANCHES[action]
+    allowed = {"action", "evidence"} | required | optional
+    for key in sorted(_ROW_FIELDS - allowed):
+        if key in normalized and normalized[key] is None:
+            normalized.pop(key)
+            warnings.append("null_branch_placeholder_normalized")
+    if action == "CREATE":
+        if "memory" in normalized and normalized["memory"] is None:
+            normalized.pop("memory")
+            warnings.append("null_memory_wrapper_normalized")
+        if "memory" in normalized:
+            normalized["memory"], field_warnings = _normalize_create_fields(normalized["memory"])
+            warnings.extend(field_warnings)
+        else:
+            normalized, field_warnings = _normalize_create_fields(normalized)
+            warnings.extend(field_warnings)
+        normalized, flattened = _normalize_flat_create_row(normalized)
+        if flattened:
+            warnings.append("create_memory_wrapper_normalized")
+    return normalized, list(dict.fromkeys(warnings))
 
 
 def _normalize_flat_create_row(row: Any) -> tuple[Any, bool]:
@@ -55,8 +113,6 @@ def _normalize_flat_create_row(row: Any) -> tuple[Any, bool]:
     required = {"type", "scope", "title", "body"}
     if not required <= memory_keys:
         return row, False
-    if set(row) - (_CREATE_ROW_META | set(_CREATE)):
-        return row, False
     normalized = {key: deepcopy(value) for key, value in row.items() if key not in _CREATE}
     normalized["memory"] = {key: deepcopy(row[key]) for key in row if key in _CREATE}
     return normalized, True
@@ -75,9 +131,18 @@ def _text(value: Any, maximum: int = 16384, *, empty: bool = False) -> str:
     return value
 
 
-def _keys(value: Any, required: set[str], allowed: set[str] | frozenset[str]) -> None:
-    if not isinstance(value, dict) or not required <= value.keys() or value.keys() - allowed:
-        raise ValueError("invalid_fields")
+def _keys(value: Any, required: set[str], allowed: set[str] | frozenset[str], *, path: str) -> None:
+    if not isinstance(value, dict):
+        raise _FieldShapeError(f"{path}:not_object")
+    missing = sorted(required - value.keys())
+    unexpected = sorted(value.keys() - allowed)
+    if missing or unexpected:
+        parts = []
+        if missing:
+            parts.append("missing=" + ",".join(missing))
+        if unexpected:
+            parts.append("unexpected=" + ",".join(unexpected))
+        raise _FieldShapeError(path + ":" + ";".join(parts))
 
 
 def _ref(value: Any, table: Mapping[str, Any]) -> str:
@@ -305,7 +370,7 @@ def _selected(value: Any, evidence: Mapping[str, Any], refs: list[str], *, clear
         if ref not in refs or evidence[ref]["use"] != "new":
             raise ValueError("invalid_reference")
         return {"clear": True, "anchor": source_basis(evidence[ref])}
-    _keys(value, {"ref", "text"}, {"ref", "text"})
+    _keys(value, {"ref", "text"}, {"ref", "text"}, path="selected_time")
     ref = _ref(value["ref"], evidence)
     if ref not in refs:
         raise ValueError("invalid_reference")
@@ -369,7 +434,7 @@ def _parse_row(row: Any, state: Mapping[str, Any]) -> dict[str, Any]:
     required_keys = {"action"} | required
     if action != "NO_MEMORY":
         required_keys.add("evidence")
-    _keys(row, required_keys, {"action", "evidence"} | optional)
+    _keys(row, required_keys, {"action", "evidence"} | optional, path="row")
     evidence = {e["ref"]: e for e in state["evidence"]}
     if action == "NO_MEMORY" and state["request_kind"] == "explicit_remember":
         raise ValueError("explicit_retention_required")
@@ -412,7 +477,8 @@ def _parse_row(row: Any, state: Mapping[str, Any]) -> dict[str, Any]:
     if action in {"CREATE", "UPDATE"}:
         fields = deepcopy(row["memory"] if action == "CREATE" else row["patch"])
         _keys(fields, {"type", "scope", "title", "body"} if action == "CREATE" else set(),
-              _CREATE if action == "CREATE" else _PATCH)
+              _CREATE if action == "CREATE" else _PATCH,
+              path="memory" if action == "CREATE" else "patch")
         if not fields:
             raise ValueError("empty_patch")
         if action == "CREATE":
@@ -564,26 +630,30 @@ def compile_incremental(raw: str, snapshot: PlanningSnapshot) -> dict[str, Any]:
         value = parse_strict_json(raw)
     except (ModelOutputError, RecursionError) as error:
         raise ValueError("invalid_json") from error
-    _keys(value, {"items"}, {"items"})
+    _keys(value, {"items"}, {"items"}, path="root")
     if not isinstance(value["items"], list) or len(value["items"]) > MAX_ITEMS:
         raise ValueError("invalid_items")
     state = snapshot.state()
     known = {e["ref"] for e in state["evidence"]}
     new = {e["ref"] for e in state["evidence"] if e["use"] == "new"}
     parsed, issues, poisoned = [], [], set()
-    def problem(index: int | None, code: str, row: Any) -> None:
+    def problem(index: int | None, code: str, row: Any, detail: str | None = None) -> None:
         refs = row.get("evidence", []) if isinstance(row, dict) else []
         refs = [r.strip() for r in refs if isinstance(r, str) and r.strip() in known] if isinstance(refs, list) else []
-        issues.append({"row": index, "code": code, "evidence": list(dict.fromkeys(refs))})
+        issue = {"row": index, "code": code, "evidence": list(dict.fromkeys(refs))}
+        if detail:
+            issue["detail"] = detail
+        issues.append(issue)
     for index, row in enumerate(value["items"]):
         try:
-            normalized_row, normalized = _normalize_flat_create_row(row)
+            normalized_row, warnings = _normalize_model_row(row)
             parsed_row = _parse_row(normalized_row, state)
-            if normalized:
-                parsed_row.setdefault("warnings", []).append("create_memory_wrapper_normalized")
+            if warnings:
+                parsed_row.setdefault("warnings", []).extend(warnings)
             parsed.append((index, parsed_row))
         except (ValueError, TypeError) as error:
-            problem(index, str(error) if isinstance(error, ValueError) else "invalid_fields", row)
+            problem(index, str(error) if isinstance(error, ValueError) else "invalid_fields", row,
+                    getattr(error, "detail", None))
             if isinstance(row, dict) and isinstance(row.get("target"), str) and row["target"].strip() in state["targets"]:
                 poisoned.add(row["target"].strip())
     groups: dict[str, list[tuple[int, dict[str, Any]]]] = defaultdict(list)

{memleaf-0.2.68 → memleaf-0.2.69/src/memleaf.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: memleaf
-Version: 0.2.68
+Version: 0.2.69
 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.65。**
+> **版本：0.2.69。**
 > 自动提炼和复核共用同一条“未来记忆价值”标准：模型综合未来复用、信息增量、再次读取时的直接可用性和忘记成本，只保留对未来理解、判断或行动有实质影响的最小核心；没有明确价值的信息不提炼，不按具体业务场景硬编码排除。
 > 提炼契约现在只有一份中文语义契约（旧版英文 B3 提示词已删除），首轮、主题选择、候选修复和 `semantic_maintenance` 使用同一套保留价值判断；同一件事只写一次。
 > Core 不再因为归属、日期、任务依据或跨项目而丢弃整条候选：归属缺失会归一到证据里唯一被点名的项目、否则落 `global`；日期只接受能在本候选证据里找到出处、且能锚定成 ISO 的写法（`明天`、`周五`、`月底` 都会被解析），无法解析时只丢掉日期字段，记忆照常写入；未获授权的改归属沿用目标原归属。

{memleaf-0.2.68 → memleaf-0.2.69}/tests_public/test_incremental_protocol.py

@@ -141,6 +141,47 @@ class IncrementalProtocolTests(unittest.TestCase):
         out = self.run_rows(row)
         self.assertFalse(out["operations"])
         self.assertEqual(out["issues"][0]["code"], "invalid_fields")
+        self.assertEqual(out["issues"][0]["detail"], "row:unexpected=unexpected")
+
+    def test_null_fields_from_other_branches_are_ignored(self):
+        row = self.create()
+        row.update(target=None, patch=None, reason=None, need=None, reopen=None)
+        out = self.run_rows(row)
+        self.assertFalse(out["issues"])
+        self.assertEqual(len(out["operations"]), 1)
+        self.assertIn("null_branch_placeholder_normalized", out["operations"][0]["warnings"])
+
+    def test_flattened_create_with_null_memory_wrapper_is_normalized(self):
+        row = {
+            "action": "CREATE", "evidence": ["e1"], "memory": None,
+            "type": "fact", "scope": "s1",
+            "title": "Known requirement", "body": "Keep this requirement.",
+        }
+        out = self.run_rows(row)
+        self.assertFalse(out["issues"])
+        warnings = out["operations"][0]["warnings"]
+        self.assertIn("null_memory_wrapper_normalized", warnings)
+        self.assertIn("create_memory_wrapper_normalized", warnings)
+
+    def test_single_scopes_alias_and_default_validity_are_normalized(self):
+        row = self.create()
+        row["memory"].pop("scope")
+        row["memory"].update(scopes=["s1"], validity="valid")
+        out = self.run_rows(row)
+        self.assertFalse(out["issues"])
+        op = out["operations"][0]
+        self.assertEqual(op["memory"]["scopes"], ["project:Atlas"])
+        self.assertIn("create_single_scope_alias_normalized", op["warnings"])
+        self.assertIn("create_default_validity_normalized", op["warnings"])
+
+    def test_ambiguous_scopes_alias_stays_rejected_with_detail(self):
+        row = self.create()
+        row["memory"].pop("scope")
+        row["memory"]["scopes"] = ["s1", "s2"]
+        out = self.run_rows(row)
+        self.assertFalse(out["operations"])
+        self.assertEqual(out["issues"][0]["code"], "invalid_fields")
+        self.assertEqual(out["issues"][0]["detail"], "memory:missing=scope;unexpected=scopes")
 
     def test_flattened_create_missing_required_field_stays_rejected(self):
         row = {

{memleaf-0.2.68 → memleaf-0.2.69}/tests_public/test_provider_compatibility.py

@@ -283,7 +283,7 @@ class ServerCompatibilityTests(unittest.TestCase):
         with patch.object(self.service,'stats',side_effect=AssertionError('must not scan')):
             result=self.hello(self.good)['result']
         self.assertEqual(result['_meta'][BUILD_META],self.good)
-        self.assertEqual(result['serverInfo']['version'],'0.2.68')
+        self.assertEqual(result['serverInfo']['version'],'0.2.69')
 
     def test_compatible_bridge_dispatches_capture(self):
         self.hello(self.good)