memleaf 0.2.27__tar.gz → 0.2.29__tar.gz

{memleaf-0.2.27 → memleaf-0.2.29}/CHANGELOG.md

@@ -2,6 +2,21 @@
 
 All notable changes to memleaf are documented here.
 
+## 0.2.29 — 2026-09-07
+
+- Clarify the source-neutral Gate contract for tool records retained as `metadata`: they are not evidence units, cannot be bound by metadata identifiers, and cannot authorize CREATE or UPDATE.
+- Normalize coverage dispositions from their declared reasons so `query_only`, `assistant_restatement`, and other known no-write reasons close as `NO_CHANGE`, while unresolved evidence, ownership, target, or Scope ambiguity remains `DEFERRED`.
+- Add a bounded `invalid_evidence` correction path and regressions for metadata-only one-off operations, failed watermark recovery, cleanup eligibility, idempotent retry, and protection against knowledge/history pollution. Keep Markdown as the sole source of truth without adding SQLite, FTS, or other runtime services.
+
+## 0.2.28 — 2026-09-06
+
+- Separate rebuildable derived data in `_index/` from correctness/runtime state in `_state/`. Existing Vaults migrate processed-event, agent activation, host-ingest, retrieval-gate and compaction state crash-safely and idempotently; conflicting or corrupt legacy/current state fails closed, and `rebuild-index` never rewrites runtime state.
+- Normalize supported legacy configuration into current names, including `capture.include_tool_output` to `capture.tool_evidence_mode`, reject conflicting legacy/current settings, preserve historical safe defaults, and document 0.2.x compatibility/deprecation behavior in `docs/config-migrations.md`.
+- Move host activation bookkeeping to `_state/agents.json`, update installation/status paths accordingly, and keep Hermes/Codex shared-Vault behavior, permanent-memory global visibility, provenance-only session/source metadata, and native Hermes memory coexistence unchanged.
+- Remove the remaining Core urgency-word classifier for unscheduled todos so ordering stays source-neutral; model-owned business semantics remain outside deterministic Core validation.
+- Add reproducible 1k/10k/50k long-run benchmarking across retrieval, writes, lifecycle, locks, RSS and disk. The 50k-active dataset is explicitly an extreme stress boundary rather than a normal steady-state assumption; normal retrieval remains `Scope Map -> scope-constrained search -> read`, while UPDATE/NO_CHANGE, todo retirement, bounded history and compaction control active-memory growth.
+- Do not introduce SQLite/FTS, vector storage, external databases, daemons or new runtime dependencies. Markdown remains the sole source of truth and `_index/` remains fully deletable/rebuildable.
+
 ## 0.2.27 — 2026-09-05
 
 - Remove application-, document-, tool- and business-specific semantic classifiers from the Core admission/target path. The model owns future-use and atomicity judgments; Core retains source-neutral evidence, Scope, type, target, date, revision and conflict validation.

{memleaf-0.2.27/src/memleaf.egg-info → memleaf-0.2.29}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: memleaf
-Version: 0.2.27
+Version: 0.2.29
 Summary: A local-first Markdown memory core for AI agents
 Author: memleaf contributors
 License-Expression: MIT
@@ -23,8 +23,8 @@ Dynamic: license-file
 
 [English](README.en.md) · [PyPI](https://pypi.org/project/memleaf/) · [GitHub](https://github.com/miffyblueboo/memleaf)
 
-> **版本：0.2.27。**
-> 核心库、Vault、stdio MCP Server、初始化 CLI、模型路由、提炼流程、受控检索协议和宿主适配器已经实现。本版收口长期运行治理：Core 语义判断保持 source-neutral，并为来源、关闭待办、历史版本和压缩身份增加有界生命周期。真实模型语义效果仍需结合本地模型和代表性样本验收。
+> **版本：0.2.29。**
+> 核心库、Vault、stdio MCP Server、初始化 CLI、模型路由、提炼流程、受控检索协议和宿主适配器已经实现。本版补齐 metadata 工具证据的 Gate 覆盖协议，修复查询和助手复述误标 DEFERRED 的收口问题，同时保持 source-neutral 语义、Markdown 唯一事实源和无 SQLite 运行时依赖。真实模型语义效果仍需结合本地模型和代表性样本验收。
 > **当前版本支持 Hermes 和 Codex。** Antigravity（反重力）不检测、不安装、不配置。
 
 ## 项目定位
@@ -490,7 +490,7 @@ MIT，见 [LICENSE](LICENSE)。
 *Your memories, in files you own.*
 
 
-## 通用处理与只读验收（0.2.27）
+## 通用处理与只读验收（0.2.29）
 
 邮件、日历、工单、文件、浏览器与普通对话共用证据准入、覆盖检查和写入路径。
 自动摘要只能使用获准引用的原文；助手复述和旧记忆回读不能单独授权新增写入。

{memleaf-0.2.27 → memleaf-0.2.29}/README.en.md

@@ -4,8 +4,8 @@
 
 [中文](README.md) · [PyPI](https://pypi.org/project/memleaf/) · [GitHub](https://github.com/miffyblueboo/memleaf)
 
-> **Version: 0.2.27.**
-> The core library, Vault, stdio MCP server, initialization CLI, model routing, memory extraction, controlled retrieval protocol, and host adapters are implemented. This release closes long-run lifecycle gaps: Core semantic decisions remain source-neutral, while provenance, closed todos, history versions, and compaction identity are bounded. Real-model semantics still require local acceptance with the selected model and representative inputs.
+> **Version: 0.2.29.**
+> The core library, Vault, stdio MCP server, initialization CLI, model routing, memory extraction, controlled retrieval protocol, and host adapters are implemented. This release completes the metadata-only tool evidence Gate contract and prevents query or assistant restatement coverage from remaining DEFERRED, while preserving source-neutral semantics, Markdown as the sole source of truth, and zero SQLite runtime dependencies. Real-model semantics still require local acceptance with the selected model and representative inputs.
 > **The current release supports Hermes and Codex.** Antigravity is not detected, installed, or configured.
 
 ## Project scope
@@ -474,7 +474,7 @@ MIT; see [LICENSE](LICENSE).
 *Your memories, in files you own.*
 
 
-## General processing and read-only inspection (0.2.27)
+## General processing and read-only inspection (0.2.29)
 
 Dialogue, calendars, tickets, files, web results and other tools share the evidence, coverage and write path.
 Models interpret semantics; Core validates physical provenance and exact original quotations.

{memleaf-0.2.27 → memleaf-0.2.29}/README.md

@@ -4,8 +4,8 @@
 
 [English](README.en.md) · [PyPI](https://pypi.org/project/memleaf/) · [GitHub](https://github.com/miffyblueboo/memleaf)
 
-> **版本：0.2.27。**
-> 核心库、Vault、stdio MCP Server、初始化 CLI、模型路由、提炼流程、受控检索协议和宿主适配器已经实现。本版收口长期运行治理：Core 语义判断保持 source-neutral，并为来源、关闭待办、历史版本和压缩身份增加有界生命周期。真实模型语义效果仍需结合本地模型和代表性样本验收。
+> **版本：0.2.29。**
+> 核心库、Vault、stdio MCP Server、初始化 CLI、模型路由、提炼流程、受控检索协议和宿主适配器已经实现。本版补齐 metadata 工具证据的 Gate 覆盖协议，修复查询和助手复述误标 DEFERRED 的收口问题，同时保持 source-neutral 语义、Markdown 唯一事实源和无 SQLite 运行时依赖。真实模型语义效果仍需结合本地模型和代表性样本验收。
 > **当前版本支持 Hermes 和 Codex。** Antigravity（反重力）不检测、不安装、不配置。
 
 ## 项目定位
@@ -471,7 +471,7 @@ MIT，见 [LICENSE](LICENSE)。
 *Your memories, in files you own.*
 
 
-## 通用处理与只读验收（0.2.27）
+## 通用处理与只读验收（0.2.29）
 
 邮件、日历、工单、文件、浏览器与普通对话共用证据准入、覆盖检查和写入路径。
 自动摘要只能使用获准引用的原文；助手复述和旧记忆回读不能单独授权新增写入。

memleaf-0.2.29/docs/config-migrations.md

@@ -0,0 +1,37 @@
+# Configuration migrations
+
+This document describes the configuration and Vault-layout compatibility boundary starting with memleaf v0.2.28.
+
+## Current configuration
+
+The current persisted top-level sections are `vault`, `agents`, `scopes`, `native_sources`, `process`, `history`, `capture`, and `llm`. Retrieval remains Scope Map -> search -> read; there is no configurable legacy injection mode.
+
+`capture.tool_evidence_mode` is the current tool-evidence retention setting and accepts `bounded`, `metadata`, or `off`. `capture.include_attachments` is independent and defaults to `false`.
+
+## Deprecated fields
+
+- Top-level `inject` (`mode`, `abnormal_guard`) belonged to the pre-Scope-Map injection path. v0.2.28 reads and discards this section; it is not written again.
+- `capture.include_tool_output` is replaced by `capture.tool_evidence_mode`.
+- The old internal `processed_index_path` / `agents_index_path` names are removed in v0.2.28; runtime code uses explicit `_state/` properties.
+
+## CLI compatibility sunset
+
+`memleaf init --no-codex` and `memleaf init --no-antigravity` are retained only as deprecated no-op argument compatibility for existing 0.2.x setup scripts. They do not select runtime behavior and are scheduled for removal in v0.3. The legacy `init --json` host result slots are likewise retained through 0.2.x so automation does not break during this maintenance release. New integrations must use `memleaf install --host ...` and the current host-state fields.
+memleaf's own current installers no longer pass the two deprecated no-op flags; only external 0.2.x callers retain that compatibility surface.
+
+## Automatic migration
+
+When reading an older configuration, `capture.include_tool_output: true` becomes `tool_evidence_mode: bounded`; `false` becomes `metadata`. Saving the normalized configuration writes only the current field. If both legacy and current fields are present but disagree, loading fails closed instead of guessing.
+A persisted older config with no `capture` section, or with a partial capture section that has neither evidence field, normalizes to `tool_evidence_mode: metadata`, preserving the previous safe metadata-only behavior. New Vaults still write an explicit `bounded` mode.
+
+The obsolete `inject` section is removed during normalization. No current runtime component consumes it.
+
+On first v0.2.28 Vault use, runtime correctness state is migrated from `_index/` to `_state/` by one centralized layout owner. Existing v0.2.27 Vault/retrieval lock files are acquired during migration so an already-running old worker cannot mutate the copied state concurrently. The new copy is atomically written and verified before a durable `_state/layout.json` completion marker is written; legacy files are removed only after that marker. Before the marker, old/new coexistence must be equivalent or startup fails closed. After the marker, `_state/` is authoritative and stale `_index/` state is cleanup debris, never merged or replayed.
+
+## Incompatible cases
+
+Migration fails closed for malformed runtime JSON, unsafe symlinks, divergent pre-marker old/new state, an invalid layout marker, or an old process still holding a legacy lock strongly enough to prevent cleanup. Stop older memleaf/Hermes/Codex processes and retry; do not delete `_state/` to force an upgrade.
+
+## User action
+
+Normal users do not need to edit their Vault or configuration. For a live upgrade, stop older processes that are using the Vault before starting v0.2.28. Backups remain recommended for any software upgrade. `_index/` is disposable and rebuildable; `_state/` is not.

{memleaf-0.2.27 → memleaf-0.2.29}/docs/general-processing.md

@@ -1,4 +1,4 @@
-# General processing reliability contract — 0.2.27
+# General processing reliability contract — 0.2.29
 
 This is source-neutral processing, not a mail extractor. Dialogue, documents,
 calendars, issue trackers and terminal/tool observations use the same admission
@@ -40,6 +40,13 @@ A Gate may map multiple facts in one evidence unit to several candidates, or
 one candidate to several units. Coverage is checked against real supplied IDs.
 One source-neutral correction can classify missing units; its candidates pass
 the same validator/deduplication path, never a post-Gate business-pattern writer.
+Tool records retained as `metadata` may remain visible in the event envelope for
+diagnostics, but they are not evidence units and cannot be bound by call ID,
+digest, tool name or other metadata. They therefore require no coverage row and
+cannot authorize CREATE/UPDATE. Coverage reasons are normalized at the boundary:
+`query_only`, `assistant_restatement`, `retrieved_memory_only`, `no_future_value`,
+duplicate/example and completed/negated reasons resolve to `NO_CHANGE`; unresolved
+coverage, ownership, target or Scope reasons remain `DEFERRED`.
 Already valid siblings survive a malformed correction. Work that remains
 ambiguous is retained and explicitly reported, not guessed into a global scope.
 

memleaf-0.2.29/docs/performance.md

@@ -0,0 +1,99 @@
+# Performance and long-run scale
+
+This benchmark measures memleaf's local Markdown Vault and derived indexes. It does not call an LLM, so model/provider latency is intentionally excluded.
+
+## Methodology
+
+Datasets contain global plus 24 project scopes, tags, aliases, keywords, wikilinks, active todos, historical versions, bounded high-frequency provenance, Chinese and English text, and mixed short/long bodies. CREATE/UPDATE/NO_CHANGE use `MemoryWriter` plus the real derived-index rebuild boundary; lifecycle measurements use the real retention and compaction primitives.
+
+The hosted benchmark reports a process-cold first search and warm repeated searches. It does **not** claim a true OS cold-cache measurement because hosted CI cannot safely or reproducibly drop the kernel page cache.
+
+The 50,000-active-memory dataset is deliberately an extreme stress boundary. It is not an assumption that a healthy Vault should normally retain 50,000 useful active memories. The dataset has 20% global memories and spreads the rest across 24 project scopes, so even one project scope contains roughly 1.6k-1.7k active records at 50k total.
+
+Normal product retrieval remains `Scope Map -> scope-constrained search -> read`; full-vault full-text search is a fallback/special case rather than the primary injection path.
+
+Platform: `Linux-6.17.0-1022-azure-x86_64-with-glibc2.39`
+Python: `3.13.15`
+Run UTC: `2026-09-06T03:49:07Z`
+
+## Latency results
+
+All latency values are milliseconds.
+
+| Active memories | Metric | median | p95 | max | samples |
+|---:|---|---:|---:|---:|---:|
+| 1,000 | `vault_initialization` | 0.667 | 0.799 | 0.799 | 3 |
+| 1,000 | `rebuild_index` | 390.421 | 398.467 | 398.467 | 3 |
+| 1,000 | `search_candidate_process_cold` | 388.067 | 388.067 | 388.067 | 1 |
+| 1,000 | `search_candidate_warm` | 386.328 | 388.011 | 388.011 | 3 |
+| 1,000 | `exact_memory_id_lookup` | 385.124 | 386.845 | 386.845 | 3 |
+| 1,000 | `fulltext_search` | 385.229 | 389.206 | 389.206 | 3 |
+| 1,000 | `scope_filtered_search` | 369.218 | 370.537 | 370.537 | 3 |
+| 1,000 | `list_todos` | 337.284 | 363.616 | 363.616 | 3 |
+| 1,000 | `read` | 337.300 | 338.413 | 338.413 | 3 |
+| 1,000 | `create` | 1149.732 | 1218.470 | 1218.470 | 3 |
+| 1,000 | `update` | 1068.737 | 1132.795 | 1132.795 | 3 |
+| 1,000 | `no_change` | 1109.159 | 1185.680 | 1185.680 | 3 |
+| 1,000 | `history_write` | 3.047 | 3.392 | 3.392 | 3 |
+| 1,000 | `closed_todo_retirement` | 835.599 | 843.429 | 843.429 | 3 |
+| 1,000 | `history_pruning` | 572.614 | 578.825 | 578.825 | 3 |
+| 1,000 | `compaction_snapshot` | 356.001 | 370.681 | 370.681 | 3 |
+| 1,000 | `vault_lock_hold_search` | 381.196 | 381.196 | 381.196 | 1 |
+| 10,000 | `vault_initialization` | 0.710 | 0.835 | 0.835 | 3 |
+| 10,000 | `rebuild_index` | 4058.684 | 4157.842 | 4157.842 | 3 |
+| 10,000 | `search_candidate_process_cold` | 3809.702 | 3809.702 | 3809.702 | 1 |
+| 10,000 | `search_candidate_warm` | 3700.780 | 3752.602 | 3752.602 | 3 |
+| 10,000 | `exact_memory_id_lookup` | 3925.242 | 3934.726 | 3934.726 | 3 |
+| 10,000 | `fulltext_search` | 3726.453 | 3854.321 | 3854.321 | 3 |
+| 10,000 | `scope_filtered_search` | 3643.267 | 3805.982 | 3805.982 | 3 |
+| 10,000 | `list_todos` | 3480.108 | 3481.024 | 3481.024 | 3 |
+| 10,000 | `read` | 3419.434 | 3502.751 | 3502.751 | 3 |
+| 10,000 | `create` | 10926.382 | 11013.296 | 11013.296 | 3 |
+| 10,000 | `update` | 10950.698 | 11030.074 | 11030.074 | 3 |
+| 10,000 | `no_change` | 10976.892 | 11187.753 | 11187.753 | 3 |
+| 10,000 | `history_write` | 14.652 | 40.393 | 40.393 | 3 |
+| 10,000 | `closed_todo_retirement` | 7271.686 | 7683.019 | 7683.019 | 3 |
+| 10,000 | `history_pruning` | 4214.574 | 5079.721 | 5079.721 | 3 |
+| 10,000 | `compaction_snapshot` | 3625.947 | 3808.937 | 3808.937 | 3 |
+| 10,000 | `vault_lock_hold_search` | 3721.875 | 3721.875 | 3721.875 | 1 |
+| 50,000 | `vault_initialization` | 0.600 | 0.759 | 0.759 | 3 |
+| 50,000 | `rebuild_index` | 20435.382 | 20560.472 | 20560.472 | 2 |
+| 50,000 | `search_candidate_process_cold` | 19243.749 | 19243.749 | 19243.749 | 1 |
+| 50,000 | `search_candidate_warm` | 19148.126 | 19553.817 | 19553.817 | 3 |
+| 50,000 | `exact_memory_id_lookup` | 19556.986 | 19834.327 | 19834.327 | 3 |
+| 50,000 | `fulltext_search` | 19855.403 | 20002.997 | 20002.997 | 3 |
+| 50,000 | `scope_filtered_search` | 18576.396 | 18639.123 | 18639.123 | 3 |
+| 50,000 | `list_todos` | 18160.793 | 18328.362 | 18328.362 | 3 |
+| 50,000 | `read` | 17648.840 | 18197.055 | 18197.055 | 3 |
+| 50,000 | `create` | 56061.953 | 56745.539 | 56745.539 | 3 |
+| 50,000 | `update` | 55893.789 | 56715.012 | 56715.012 | 3 |
+| 50,000 | `no_change` | 55934.604 | 56323.055 | 56323.055 | 3 |
+| 50,000 | `history_write` | 5.971 | 70.687 | 70.687 | 3 |
+| 50,000 | `closed_todo_retirement` | 37710.833 | 37795.840 | 37795.840 | 3 |
+| 50,000 | `history_pruning` | 21802.002 | 21843.263 | 21843.263 | 3 |
+| 50,000 | `compaction_snapshot` | 19330.915 | 19619.114 | 19619.114 | 3 |
+| 50,000 | `vault_lock_hold_search` | 19650.941 | 19650.941 | 19650.941 | 1 |
+
+## Resource footprint
+
+| Active memories | Peak RSS MiB | Vault MiB | `_index/` MiB | `_state/` MiB |
+|---:|---:|---:|---:|---:|
+| 1,000 | 50.871 | 2.174 | 0.170 | 0.000 |
+| 10,000 | 259.891 | 21.156 | 1.458 | 0.000 |
+| 50,000 | 1186.762 | 105.841 | 7.157 | 0.000 |
+
+## Scale interpretation
+
+The 2,000 ms search, 120 s rebuild, and 1,024 MiB RSS values are retained as stress references only. A miss at 50,000 active memories is capacity evidence, not a release blocker and not a reason to introduce a new database/search backend.
+
+**Architecture change required from the 50k stress result: no.** 50k active memories is retained as an extreme stress boundary, not a normal steady-state assumption. The normal retrieval path is Scope Map -> scope-constrained search -> read, while UPDATE/NO_CHANGE, todo retirement, bounded history, and compaction are expected to control active-memory growth. Stress misses are recorded for capacity visibility and do not justify adding another storage/search backend.
+
+If a real Vault grows into the tens of thousands of active memories, first audit CREATE-vs-UPDATE/NO_CHANGE behavior, todo retirement, history retention, duplicate control, and compaction. The product remains Markdown-only in v0.2.28.
+
+## Active-memory lifecycle health
+
+Active memory count is a health signal, not an archival counter. Repeated facts should update existing canonical memories, unchanged observations should be NO_CHANGE, completed/cancelled todos retire from active memory, historical versions are bounded, and compaction reduces redundant active material. A real Vault approaching the 50k stress dataset should therefore trigger lifecycle/quality investigation before search-backend expansion.
+
+## Runtime state growth audit
+
+The retrieval ledger is already TTL- and count-bounded, and per-session pending tool evidence/injection bookkeeping is bounded. The processed-turn/session ledger retains replay/idempotency evidence and is therefore intentionally not destructively pruned in v0.2.28: deleting it without a new durable replay checkpoint would risk duplicate replay. Future state compaction must first define a verified checkpoint that proves older replay evidence is no longer needed.

{memleaf-0.2.27 → memleaf-0.2.29}/install.sh

@@ -171,9 +171,7 @@ done
 export PATH="$venv_path/bin:$user_bin:$PATH"
 "$venv_path/bin/memleaf" init \
   --vault "$vault_path" \
-  --no-codex \
-  --no-hermes \
-  --no-antigravity
+  --no-hermes
 
 hermes_bin=""
 candidate_hermes=$(command -v hermes 2>/dev/null || true)
@@ -265,7 +263,7 @@ from __future__ import annotations
 import sys
 from pathlib import Path
 
-from memleaf.adapters.base import update_agents_index
+from memleaf.adapters.base import update_agents_state
 
 vault_path = Path(sys.argv[1]).expanduser()
 hermes_executable = str(Path(sys.argv[2]).expanduser().resolve())
@@ -283,8 +281,8 @@ updates = {
         "user_action_required": False,
     }
 }
-if not update_agents_index(vault_path / "_index" / "agents.json", updates):
-    raise SystemExit("could not update Hermes provider status in agents index")
+if not update_agents_state(vault_path / "_state" / "agents.json", updates):
+    raise SystemExit("could not update Hermes provider status in agents state")
 PY
 
   # Configure the active MCP entry through Hermes' official CLI.  Keep this
@@ -332,17 +330,17 @@ from __future__ import annotations
 import sys
 from pathlib import Path
 
-from memleaf.adapters.base import update_agents_index
+from memleaf.adapters.base import update_agents_state
 
 vault_path = Path(sys.argv[1]).expanduser()
-if not update_agents_index(
-    vault_path / "_index" / "agents.json",
+if not update_agents_state(
+    vault_path / "_state" / "agents.json",
     {"hermes": {"mcp_status": "failed", "mcp_availability": "unavailable"}},
 ):
-    raise SystemExit("could not record Hermes MCP failure in agents index")
+    raise SystemExit("could not record Hermes MCP failure in agents state")
 PY
     then
-      die "could not record Hermes MCP failure in agents index"
+      die "could not record Hermes MCP failure in agents state"
     fi
     die "Hermes memleaf MCP configuration/test failed"
   fi
@@ -372,14 +370,14 @@ from __future__ import annotations
 import sys
 from pathlib import Path
 
-from memleaf.adapters.base import update_agents_index
+from memleaf.adapters.base import update_agents_state
 
 vault_path = Path(sys.argv[1]).expanduser()
-if not update_agents_index(
-    vault_path / "_index" / "agents.json",
+if not update_agents_state(
+    vault_path / "_state" / "agents.json",
     {"hermes": {"mcp_status": "active", "mcp_availability": "available"}},
 ):
-    raise SystemExit("could not update Hermes MCP status in agents index")
+    raise SystemExit("could not update Hermes MCP status in agents state")
 PY
   printf 'Hermes memory provider: verified active\n'
 fi

{memleaf-0.2.27 → memleaf-0.2.29}/pyproject.toml

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

{memleaf-0.2.27 → memleaf-0.2.29}/src/memleaf/__init__.py

@@ -1,6 +1,6 @@
 """Local-first Markdown memory core for AI agents."""
 
-__version__ = "0.2.27"
+__version__ = "0.2.29"
 
 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.27 → memleaf-0.2.29}/src/memleaf/adapters/base.py

@@ -209,11 +209,11 @@ def hook_definition_fingerprint(definition: Mapping[str, Any]) -> str:
     return hashlib.sha256(payload).hexdigest()
 
 
-def agent_index_path(vault: Path | str) -> Path:
-    """Return the agents index path without creating or changing the vault."""
+def agent_state_path(vault: Path | str) -> Path:
+    """Return the host activation state path without creating or changing the vault."""
 
     root = vault if isinstance(vault, (str, os.PathLike)) else getattr(vault, "root", vault)
-    return Path(root).expanduser().resolve() / "_index" / "agents.json"
+    return Path(root).expanduser().resolve() / "_state" / "agents.json"
 
 
 def _read_agents_index(path: Path) -> dict[str, Any] | None:
@@ -245,7 +245,7 @@ def hook_activation_status(
 ) -> str:
     """Keep ``active`` only when it belongs to the current hook definition."""
 
-    index = _read_agents_index(agent_index_path(vault))
+    index = _read_agents_index(agent_state_path(vault))
     if index is None:
         return pending_status
     entry = index["agents"].get(agent)
@@ -259,7 +259,7 @@ def hook_activation_status(
     return pending_status
 
 
-def update_agents_index(
+def update_agents_state(
     path: Path | str,
     updates: Mapping[str, Mapping[str, Any]],
 ) -> bool:
@@ -301,7 +301,7 @@ def update_agents_index(
 def mark_hook_active(vault: Path | str, agent: str) -> bool:
     """Record a successful real hook invocation without touching hook trust."""
 
-    target = agent_index_path(vault)
+    target = agent_state_path(vault)
     if target.is_symlink() or target.parent.is_symlink():
         return False
     lock_path = target.parent / "vault.lock"

{memleaf-0.2.27 → memleaf-0.2.29}/src/memleaf/admission.py

@@ -293,6 +293,19 @@ COVERAGE_REASONS = frozenset({"query_only", "assistant_restatement", "retrieved_
     "no_future_value", "exact_duplicate", "quoted_or_example", "negated", "already_completed",
     "scope_ambiguous", "scope_conflict", "ownership_ambiguous", "target_ambiguous", "coverage_unresolved"})
 
+# Coverage is a semantic accounting ledger, not a second candidate decision.
+# Keep the disposition implied by the reason so a model cannot leave known
+# read-only/irrelevant evidence retryable, or mark unresolved evidence clean.
+_NO_CHANGE_COVERAGE_REASONS = frozenset({
+    "query_only", "assistant_restatement", "retrieved_memory_only",
+    "no_future_value", "exact_duplicate", "quoted_or_example", "negated",
+    "already_completed",
+})
+_DEFERRED_COVERAGE_REASONS = frozenset({
+    "scope_ambiguous", "scope_conflict", "ownership_ambiguous",
+    "target_ambiguous", "coverage_unresolved",
+})
+
 
 def parse_coverage(value: Any, units: Iterable[EvidenceUnit], candidates: Iterable[Mapping[str, Any]], *, require_complete: bool = True) -> dict[str, dict[str, Any]]:
     """Validate accounting without trusting the model's evidence identities."""
@@ -317,12 +330,22 @@ def parse_coverage(value: Any, units: Iterable[EvidenceUnit], candidates: Iterab
             if any(units[uid].event_key not in candidates[i]["evidence_event_ids"] for i in ids):
                 raise ModelOutputError("coverage event mismatch", validation_detail="invalid_evidence")
         elif decision in {"NO_CHANGE", "DEFERRED"}:
-            if (row.get("candidate_ids") or not isinstance(row.get("reason"), str)
-                or row.get("reason") not in COVERAGE_REASONS):
+            reason = row.get("reason")
+            if (row.get("candidate_ids") or not isinstance(reason, str)
+                or reason not in COVERAGE_REASONS):
                 raise ModelOutputError("invalid coverage decision", validation_detail="invalid_evidence")
+            # Normalize only the model's declared reason. This keeps the
+            # protocol source-neutral: no local topic or business heuristic
+            # decides whether a fragment is retryable.
+            if reason in _NO_CHANGE_COVERAGE_REASONS:
+                decision = "NO_CHANGE"
+            elif reason in _DEFERRED_COVERAGE_REASONS:
+                decision = "DEFERRED"
         else:
             raise ModelOutputError("unknown coverage decision", validation_detail="invalid_evidence")
-        result[uid] = dict(row)
+        normalized = dict(row)
+        normalized["decision"] = decision
+        result[uid] = normalized
     if require_complete and set(result) != set(units):
         raise ModelOutputError("incomplete evidence coverage", validation_detail="invalid_evidence")
     return result
@@ -376,6 +399,10 @@ def evidence_prompt(units: Iterable[EvidenceUnit]) -> str:
         '{"unit_id":"supplied id","decision":"CANDIDATE","candidate_ids":["id"]} or '
         '{"unit_id":"supplied id","decision":"NO_CHANGE or DEFERRED","reason":"reason"}. '
         'Allowed reasons: ' + ', '.join(sorted(COVERAGE_REASONS)) + '. '
+        'Use NO_CHANGE only with reasons: ' + ', '.join(sorted(_NO_CHANGE_COVERAGE_REASONS)) + '. '
+        'Use DEFERRED only with reasons: ' + ', '.join(sorted(_DEFERRED_COVERAGE_REASONS)) + '. '
+        'Tool records retained with retention=metadata may appear in the event envelope but are not evidence units: '
+        'do not invent a unit ID for them or bind their call ID, digest, tool name, or other metadata. '
         'Only actual user assertions or complete external observations can support writes. User origin labels are hints. Questions, examples, '
         'retrieved memories and assistant synthesis cannot. Account for missing or ambiguous facts '
         'as DEFERRED; do not invent a candidate to satisfy coverage. Interpret mixed assertions '

{memleaf-0.2.27 → memleaf-0.2.29}/src/memleaf/capture.py

@@ -29,11 +29,6 @@ def _timestamp() -> str:
 
 
 
-_MAIL_EVIDENCE_FIELDS = frozenset({"message_id", "subject", "sender", "domain"})
-_MAIL_DOMAIN_RE = re.compile(r"^(?=.{1,253}$)(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z]{2,63}$", re.IGNORECASE)
-_MAX_MAIL_EVIDENCE_ITEMS = 8
-_MAX_MAIL_EVIDENCE_TEXT = 320
-
 
 def _normalize_tool_evidence(value: Any) -> list[dict[str, str]]:
     from .provenance import normalize_tool_evidence
@@ -241,19 +236,19 @@ def capture_event(
         return CaptureResult(resolved_event_id, stored=False, duplicate=False, content=safe_content)
 
     with vault.lock():
-        processed = _read_processed(vault.processed_index_path)
+        processed = _read_processed(vault.processed_state_path)
         from .recording_policy import apply_control
         allowed, changed = apply_control(processed, source=source, session_id=session_id,
             turn_key=resolved_turn_key, event_key=resolved_event_key, role=role, content=content, record=record)
         if not allowed:
             if changed:
-                atomic_write_json(vault.processed_index_path, processed)
+                atomic_write_json(vault.processed_state_path, processed)
             return CaptureResult(resolved_event_id, stored=False, duplicate=False, suppressed=True)
         # Only permitted data reaches normalization or any persistence path.
         from .evidence_policy import retain_tool_evidence
         safe_tool_evidence = retain_tool_evidence(tool_evidence, vault.config())
         if changed:
-            atomic_write_json(vault.processed_index_path, processed)
+            atomic_write_json(vault.processed_state_path, processed)
         known_keys = _known_event_keys(vault, processed)
         if resolved_event_key in known_keys:
             path = vault.session_path(source, session_id)
@@ -328,7 +323,7 @@ def capture_event(
             new_state["processing"] = old_state["processing"]
         sessions[session_key] = new_state
         atomic_write_json(
-            vault.processed_index_path,
+            vault.processed_state_path,
             {
                 **processed,
                 "version": 1,

{memleaf-0.2.27 → memleaf-0.2.29}/src/memleaf/cli.py

@@ -17,7 +17,7 @@ from .adapters.base import (
     ConfigureResult,
     Detection,
     result_from_detection,
-    update_agents_index,
+    update_agents_state,
 )
 from .adapters.hermes import HermesAdapter
 from .credentials import credential_text
@@ -43,13 +43,13 @@ def build_parser() -> argparse.ArgumentParser:
     init.add_argument(
         "--no-codex",
         action="store_true",
-        help="compatibility no-op; use install --host codex for explicit Codex setup",
+        help="deprecated compatibility no-op through 0.2.x; use install --host codex (removal planned for 0.3)",
     )
     init.add_argument("--no-hermes", action="store_true", help="disable Hermes setup")
     init.add_argument(
         "--no-antigravity",
         action="store_true",
-        help="accepted for compatibility; Antigravity is currently unsupported",
+        help="deprecated compatibility no-op through 0.2.x; Antigravity is unsupported (removal planned for 0.3)",
     )
     init.add_argument(
         "--no-model-discovery",
@@ -366,7 +366,7 @@ def _init(args: argparse.Namespace) -> dict:
 
     # Retain legacy init result slots without implicitly configuring hosts.
     # Codex is supported only through the explicit install command; Antigravity
-    # remains unsupported. Clear stale activation claims in our own index only.
+    # remains unsupported. Clear stale activation claims in our own state only.
     legacy_slots = (
         (
             "codex",
@@ -396,15 +396,15 @@ def _init(args: argparse.Namespace) -> dict:
         )
 
     agents = {name: result.to_dict() for name, result in results.items()}
-    agents_index_written = False
+    agents_state_written = False
     if not args.dry_run:
-        agents_index_written = update_agents_index(vault.agents_index_path, agents)
+        agents_state_written = update_agents_state(vault.agents_state_path, agents)
 
     return {
         "version": 1,
         "vault": str(vault.root),
-        "agents_index_path": str(vault.agents_index_path),
-        "agents_index_written": agents_index_written,
+        "agents_state_path": str(vault.agents_state_path),
+        "agents_state_written": agents_state_written,
         "dry_run": bool(args.dry_run),
         "agents": agents,
         "model": model_result,
@@ -565,9 +565,9 @@ def _print_human_result(output: dict) -> None:
         else:
             print(f"model: {model.get('status')}")
     if output["dry_run"]:
-        print(f"agents index not written: {output['agents_index_path']}")
+        print(f"agents state not written: {output['agents_state_path']}")
     else:
-        print(f"agents index: {output['agents_index_path']}")
+        print(f"agents state: {output['agents_state_path']}")
 
 
 if __name__ == "__main__":  # pragma: no cover - exercised by subprocess smoke tests.

{memleaf-0.2.27 → memleaf-0.2.29}/src/memleaf/compaction.py

@@ -1,4 +1,4 @@
-"""Local, deterministic active-memory compaction for stage B3a."""
+"""Local, deterministic active-memory compaction."""
 
 from __future__ import annotations