memleaf 0.2.25__tar.gz → 0.2.27__tar.gz

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

@@ -2,6 +2,27 @@
 
 All notable changes to memleaf are documented here.
 
+## 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.
+- Bound per-memory provenance to 16 retained source rows while preserving cumulative source count/digest metadata, preventing repeated UPDATEs and copied history versions from growing `sources` without limit.
+- Retire completed/cancelled todos from active `knowledge/` after a configurable grace period (30 days by default) while keeping them queryable through historical todo enumeration.
+- Add bounded history retention (`3650` days and `32` complete versions per stable identity by default) with an explicit `keep_all` opt-out for audit-oriented Vaults.
+- Preserve an existing canonical memory identity during compaction instead of generating `mem-compact-*` IDs; rollback remains journaled and crash-safe.
+- Keep Markdown as the source of truth, retain zero runtime dependencies and no daemon, and preserve Hermes/Codex shared-Vault retrieval and write contracts.
+
+## 0.2.26 — 2026-09-05
+
+- Refactor automatic processing into explicit model execution, planning, update coordination, commit, journal and audit owners while preserving Markdown Vaults, memory IDs, Hermes MemoryProvider and cross-Agent retrieval contracts. No runtime dependency or independent service is added.
+- Remove post-Gate completion/rework generation, forced status/type/Scope rewrites, local last-retry candidate splitting, wrong-target UPDATE-to-CREATE conversion and automatic old/new body concatenation. Invalid proposals receive bounded model correction, then explicit candidate-local deferral; valid siblings proceed.
+- Add source-neutral exact evidence bindings and one bounded coverage correction. Assistant synthesis, recalled memory and truncated observations do not independently authorize new facts; evidence and candidate outcomes are accounted separately.
+- Reconcile compatible same-target updates into one model-owned write/history operation with all contributing receipts. Preserve actual outcomes on replay and reject stale target revisions under the shared Vault lock.
+- Freeze complete change payloads; explicit forget cancels matching pending operations before deletion. Explicit remember enforces selected Scope and target revisions. Automatic/explicit writes, forget, raw-library writes and compaction share the lock/recovery entry boundary without conflating their authorization.
+- Honor leading recording controls and record=False before persistence, consume only safely captured tool caches, and retry unresolved coverage at most once through natural lifecycle triggers. Keep unresolved source evidence after exhaustion.
+- Unify bounded/metadata/off tool-evidence retention across direct capture, Hermes, Codex and planning. Preserve legacy disabled settings and document-source exclusions; configuration changes do not fabricate missing source content.
+- Add read-only audit, isolated dry-run, Windows native process-liveness and cross-process file-lock safeguards. Run complete regression suites on Linux, Windows and macOS plus wheel/sdist installation checks.
+- Deterministic contract tests do not establish real-model semantic quality. The maintainer selected local live-model acceptance rather than repository model credentials; no real-model result is claimed by this release.
+
 ## 0.2.25 — 2026-09-04
 
 - Keep global todo questions and cross-session recaps strictly read-only,

{memleaf-0.2.25 → memleaf-0.2.27}/MANIFEST.in

@@ -8,3 +8,5 @@ include RELEASE_CHECKLIST.md
 include IMPLEMENTATION_PLAN.md
 recursive-include tests *.py
 recursive-include examples *.md *.ndjson *.py
+
+include docs/*.md

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: memleaf
-Version: 0.2.25
+Version: 0.2.27
 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.25。**
-> 核心库、Vault、stdio MCP Server、初始化 CLI、模型路由、提炼流程、受控检索协议和宿主适配器已经实现。memleaf 0.2.25 通过 PyPI 分发。
+> **版本：0.2.27。**
+> 核心库、Vault、stdio MCP Server、初始化 CLI、模型路由、提炼流程、受控检索协议和宿主适配器已经实现。本版收口长期运行治理：Core 语义判断保持 source-neutral，并为来源、关闭待办、历史版本和压缩身份增加有界生命周期。真实模型语义效果仍需结合本地模型和代表性样本验收。
 > **当前版本支持 Hermes 和 Codex。** Antigravity（反重力）不检测、不安装、不配置。
 
 ## 项目定位
@@ -417,11 +417,33 @@ $HOME/.memleaf/
 
 `knowledge/` 和 `history/` 是可读数据；`_index/` 主要是派生索引或运行状态。删除或直接修改 `_index/` 可能丢失处理水位、Hook 游标或当前检索账本；需要重建时优先使用 `rebuild_index()`。
 
+### 长期运行与保留策略
+
+默认配置对长期增长做三层治理，而不引入后台服务：
+
+```yaml
+process:
+  memory_compact_threshold_tokens: 100000
+  memory_compact_candidate_ratio: 0.30
+  inbox_cleanup_hours: 24
+  closed_todo_retention_days: 30
+history:
+  policy: bounded
+  retention_days: 3650
+  max_versions_per_memory: 32
+```
+
+- active Markdown 每条最多保留 16 个来源明细，同时记录累计 `source_count`、`source_digest` 和省略数量，避免 UPDATE 让 `sources` 无限膨胀；
+- 已完成/已取消 todo 默认在 30 天后退出 `knowledge/` 并进入 `history/`；`list_todos(status=completed|cancelled|all)` 仍可枚举这些历史待办；
+- `history.policy: bounded` 默认每个稳定记忆身份最多保留 32 个完整历史版本，且超过 3650 天的版本可被维护流程淘汰；需要永久审计时可显式设置 `history.policy: keep_all`；
+- compaction 会保留一个既有 canonical `memory_id`，不会再为整理结果创建新的 `mem-compact-*` 身份；单条精简保持原 ID，多条合并选择一个稳定 survivor。
+- 这些维护动作在正常 `process()` / `remember()` / `compact()` 生命周期中执行，不需要 daemon；普通只读检索本身不触发维护写入。
+
 默认目录尽量使用 `0700`，文件默认明文保存。memleaf 没有内置加密层，请自行保护 Vault、备份和模型调用凭证。
 
 ## 隐私与安全边界
 
-- 捕获默认只接收调用方明确传入的 user/assistant 可见文本；不捕获 system prompt、developer prompt、隐藏推理、原始工具输出或附件全文；
+- 对话捕获只接收 user/assistant 可见文本，不捕获 system/developer 指令或隐藏推理。匹配到当前轮工具调用的证据另由 `capture.tool_evidence_mode` 控制；新建 Vault 默认 `bounded`（脱敏、有界正文），文件/附件正文默认不留存。旧配置显式关闭工具输出时不自动升级为保留正文；
 - 捕获落盘前尽力脱敏常见 API key、Bearer token、Cookie、JWT 和私钥，但脱敏不是加密，也不能保证识别所有敏感信息；
 - 路径校验、符号链接检查、Vault 锁、同目录临时文件、fsync 和原子替换用于保护本地写入；
 - memleaf 不主动上传整个 Vault，也没有托管后台、遥测或账号系统；
@@ -457,7 +479,7 @@ python -m build --wheel --sdist
 - 没有模型路由时只能捕获和检索，不能完成自动提炼、显式记忆或压缩；
 - 真实宿主长期运行效果仍取决于本机 Agent 版本、配置、重启和模型可用性；
 - 不提供 Obsidian 插件、Web 管理界面、云同步或透明加密层；
-- `history/` 的批量清理不会被普通检索自动执行，删除操作需要明确调用维护接口。
+- 普通只读检索不会触发保留策略写入；历史淘汰和关闭待办退休只在正常处理/维护生命周期中执行。
 
 
 ## License
@@ -466,3 +488,46 @@ MIT，见 [LICENSE](LICENSE)。
 
 **memleaf**
 *Your memories, in files you own.*
+
+
+## 通用处理与只读验收（0.2.27）
+
+邮件、日历、工单、文件、浏览器与普通对话共用证据准入、覆盖检查和写入路径。
+自动摘要只能使用获准引用的原文；助手复述和旧记忆回读不能单独授权新增写入。
+模型负责语义判断，代码验证来源和原文引用。通过引用校验并不保证模型的语义判断一定正确。
+
+```bash
+memleaf audit --vault /path/to/existing/vault --json
+memleaf process --vault /path/to/existing/vault --source hermes --session-id SESSION --dry-run --json
+```
+
+`audit` 完全本地、只读，不调用模型，不推断旧记忆由哪个版本创建，也不自动清理。
+`--dry-run` 在私有临时副本运行正常处理，可能调用配置的独立 Model Route；不会改写原 Vault。
+检测到原 Vault 并发变化时会拒绝输出可用预览。没有一键应用预览的功能。
+
+工具执行状态与证据完整性分别记录；超限、丢失或不完整内容不会被模型的 NO_CHANGE 升级为完整。
+执行成功但尚有未解决项时，结果显示 `coverage_status=partial`，并保留来源以供有界重试或补充证据。
+行为、限制、测试协议变更见 [通用处理说明](docs/general-processing.md)。
+
+### 工具证据留存配置
+
+```yaml
+capture:
+  tool_evidence_mode: bounded  # bounded | metadata | off
+  include_attachments: false
+```
+
+`bounded` 允许当前轮真实工具观察保留有界、脱敏的正文；小结果可能完整保留，
+不是承诺只保存模型总结。`metadata` 仅留工具调用标识等元数据（仍可能包含标题），
+不保留证据正文，也不把主动排除误报成提炼漏项。`off` 不保存工具证据记录。
+三种模式均不允许把助手复述或旧记忆回读变成独立的新事实。
+
+现有配置未提供新字段时，旧 `include_tool_output: false` 或未设置该开关均按
+`metadata` 处理，旧 `true` 按 `bounded` 处理。显式新字段优先；新建 Vault 只写
+新字段，不再同时写含义冲突的旧开关。`include_attachments: true` 仍受上述总模式限制。
+宿主通过结构化文件路径、文件/附件标识识别文档；不承诺识别任意 Shell 命令或不透明工具
+隐藏读取的文件。用户粘贴的可见文档和显式 `remember` 内容不属于自动附件抓取。
+
+策略在待捕获缓存、inbox 写入和新模型提炼输入处共同执行。配置收紧不会自动删除已提交
+记忆或改写已捕获 inbox；失败前已经冻结的提交计划也不作为新的模型调用重新提炼。
+已捕获工具原文的清理仍遵守原有安全期，明确忘记使用 `forget_memory/forget_about`。

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

@@ -4,8 +4,8 @@
 
 [中文](README.md) · [PyPI](https://pypi.org/project/memleaf/) · [GitHub](https://github.com/miffyblueboo/memleaf)
 
-> **Version: 0.2.25.**
-> The core library, Vault, stdio MCP server, initialization CLI, model routing, memory extraction, controlled retrieval protocol, and host adapters are implemented. memleaf 0.2.25 is distributed through PyPI.
+> **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.
 > **The current release supports Hermes and Codex.** Antigravity is not detected, installed, or configured.
 
 ## Project scope
@@ -400,11 +400,33 @@ $HOME/.memleaf/
 
 `knowledge/` and `history/` are human-readable data. `_index/` contains derived indexes and runtime state. Deleting or editing it directly can lose processing watermarks, host cursors, or the current retrieval ledger; use `rebuild_index()` when a rebuild is needed.
 
+### Long-run retention
+
+The default configuration bounds long-run growth without adding a background service:
+
+```yaml
+process:
+  memory_compact_threshold_tokens: 100000
+  memory_compact_candidate_ratio: 0.30
+  inbox_cleanup_hours: 24
+  closed_todo_retention_days: 30
+history:
+  policy: bounded
+  retention_days: 3650
+  max_versions_per_memory: 32
+```
+
+- Each active Markdown memory retains at most 16 detailed provenance rows while tracking cumulative `source_count`, `source_digest`, and omitted rows, so repeated UPDATEs cannot grow `sources` without bound.
+- Completed/cancelled todos leave `knowledge/` after 30 days by default and move to `history/`; `list_todos(status=completed|cancelled|all)` can still enumerate retired todos.
+- With `history.policy: bounded`, each stable memory identity keeps at most 32 full historical versions, and versions older than 3650 days are eligible for pruning. Set `history.policy: keep_all` explicitly when permanent audit retention is required.
+- Compaction preserves an existing canonical `memory_id` instead of creating a new `mem-compact-*` identity; a single-memory rewrite keeps its ID and a multi-memory merge chooses one stable survivor.
+- Maintenance runs through normal `process()` / `remember()` / `compact()` lifecycle calls and requires no daemon. Ordinary read-only retrieval does not trigger maintenance writes.
+
 Directories are normally created with mode `0700`, and files are stored as plaintext by default. memleaf has no built-in encryption layer; protect the Vault, backups, and model credentials yourself.
 
 ## Privacy and security boundaries
 
-- By default, capture accepts only explicitly supplied visible user/assistant text; it excludes system prompts, developer prompts, hidden reasoning, raw tool output, and full attachment bodies.
+- Conversation capture accepts visible user/assistant text, never system/developer instructions or hidden reasoning. Matched current-turn tool evidence is controlled separately by `capture.tool_evidence_mode`: new Vaults use bounded/redacted observations; document/attachment bodies are excluded by default. Legacy configurations disabling tool output are not silently opted into body retention.
 - Common API keys, Bearer tokens, cookies, JWTs, and private keys are redacted on a best-effort basis before capture is written. Redaction is not encryption and cannot detect every secret.
 - Path validation, symlink checks, Vault locks, same-directory temporary files, fsync, and atomic replacement protect local writes.
 - memleaf does not upload the entire Vault and has no hosted backend, telemetry, or account system.
@@ -440,7 +462,7 @@ The following should not be interpreted as delivered capabilities:
 - Without a model route, memleaf can capture and retrieve but cannot perform automatic extraction, explicit model-backed memory, or compaction.
 - Long-running real-host behavior still depends on the local Agent version, configuration, restart, and model availability.
 - There is no Obsidian plugin, web management UI, cloud sync, or transparent encryption layer.
-- Routine retrieval never performs batch history cleanup; deletion requires an explicit maintenance operation.
+- Routine read-only retrieval never performs retention writes; history pruning and closed-todo retirement run only during normal processing/maintenance lifecycle calls.
 
 
 ## License
@@ -450,3 +472,48 @@ MIT; see [LICENSE](LICENSE).
 **memleaf**
 
 *Your memories, in files you own.*
+
+
+## General processing and read-only inspection (0.2.27)
+
+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.
+A valid quotation establishes provenance, not the truth or entailment of a generated claim.
+
+```bash
+memleaf audit --vault /path/to/existing/vault --json
+memleaf process --vault /path/to/existing/vault --source hermes --session-id SESSION --dry-run --json
+```
+
+Audit is local/read-only, never calls a model, never infers producing versions and never repairs automatically.
+Dry-run executes the normal processor on a private temporary copy and may call the configured Model Route.
+It does not modify the source Vault; concurrent source changes invalidate the preview. There is no apply-preview mode.
+Execution success is separate from evidence completeness: `coverage_status=partial` reports unresolved work.
+See [general processing](docs/general-processing.md) for the protocol, limits and verification boundaries.
+
+### Tool-evidence retention
+
+```yaml
+capture:
+  tool_evidence_mode: bounded  # bounded | metadata | off
+  include_attachments: false
+```
+
+`bounded` keeps bounded, redacted current-turn observations; small tool results may be
+retained in full, not just as model summaries. `metadata` keeps identifiers and permitted
+metadata (which may include titles), not bodies; intentional exclusions are not reported
+as unresolved extraction. `off` retains no tool-evidence records. None of these modes makes
+assistant synthesis or retrieved old memory independent evidence of new facts.
+
+For an existing file without the new mode, legacy `include_tool_output: false` or an
+absent boolean means `metadata`; true means `bounded`. An explicit new mode takes
+precedence. New Vaults write only the new mode. Attachment opt-in remains subject to the
+mode. Adapters classify structural file paths, file IDs and attachment handles, not
+arbitrary opaque shell commands. Pasted visible documents and explicit remember text
+are not automatic attachment capture.
+
+The policy applies to pending cache, inbox writes, and new model-planning inputs.
+Tightening it is not a retroactive rewrite of committed memories or captured inbox files.
+Previously frozen operations are recovered as existing plans, not new model calls.
+Captured evidence retains its existing cleanup grace period; use explicit forget for
+memory deletion. See `docs/evidence-retention.md` for limits and scope.

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

@@ -4,8 +4,8 @@
 
 [English](README.en.md) · [PyPI](https://pypi.org/project/memleaf/) · [GitHub](https://github.com/miffyblueboo/memleaf)
 
-> **当前版本：0.2.25。**
-> 核心库、Vault、stdio MCP Server、初始化 CLI、模型路由、提炼流程、受控检索协议和宿主适配器已经实现。memleaf 0.2.25 通过 PyPI 分发。
+> **版本：0.2.27。**
+> 核心库、Vault、stdio MCP Server、初始化 CLI、模型路由、提炼流程、受控检索协议和宿主适配器已经实现。本版收口长期运行治理：Core 语义判断保持 source-neutral，并为来源、关闭待办、历史版本和压缩身份增加有界生命周期。真实模型语义效果仍需结合本地模型和代表性样本验收。
 > **当前版本支持 Hermes 和 Codex。** Antigravity（反重力）不检测、不安装、不配置。
 
 ## 项目定位
@@ -398,11 +398,33 @@ $HOME/.memleaf/
 
 `knowledge/` 和 `history/` 是可读数据；`_index/` 主要是派生索引或运行状态。删除或直接修改 `_index/` 可能丢失处理水位、Hook 游标或当前检索账本；需要重建时优先使用 `rebuild_index()`。
 
+### 长期运行与保留策略
+
+默认配置对长期增长做三层治理，而不引入后台服务：
+
+```yaml
+process:
+  memory_compact_threshold_tokens: 100000
+  memory_compact_candidate_ratio: 0.30
+  inbox_cleanup_hours: 24
+  closed_todo_retention_days: 30
+history:
+  policy: bounded
+  retention_days: 3650
+  max_versions_per_memory: 32
+```
+
+- active Markdown 每条最多保留 16 个来源明细，同时记录累计 `source_count`、`source_digest` 和省略数量，避免 UPDATE 让 `sources` 无限膨胀；
+- 已完成/已取消 todo 默认在 30 天后退出 `knowledge/` 并进入 `history/`；`list_todos(status=completed|cancelled|all)` 仍可枚举这些历史待办；
+- `history.policy: bounded` 默认每个稳定记忆身份最多保留 32 个完整历史版本，且超过 3650 天的版本可被维护流程淘汰；需要永久审计时可显式设置 `history.policy: keep_all`；
+- compaction 会保留一个既有 canonical `memory_id`，不会再为整理结果创建新的 `mem-compact-*` 身份；单条精简保持原 ID，多条合并选择一个稳定 survivor。
+- 这些维护动作在正常 `process()` / `remember()` / `compact()` 生命周期中执行，不需要 daemon；普通只读检索本身不触发维护写入。
+
 默认目录尽量使用 `0700`，文件默认明文保存。memleaf 没有内置加密层，请自行保护 Vault、备份和模型调用凭证。
 
 ## 隐私与安全边界
 
-- 捕获默认只接收调用方明确传入的 user/assistant 可见文本；不捕获 system prompt、developer prompt、隐藏推理、原始工具输出或附件全文；
+- 对话捕获只接收 user/assistant 可见文本，不捕获 system/developer 指令或隐藏推理。匹配到当前轮工具调用的证据另由 `capture.tool_evidence_mode` 控制；新建 Vault 默认 `bounded`（脱敏、有界正文），文件/附件正文默认不留存。旧配置显式关闭工具输出时不自动升级为保留正文；
 - 捕获落盘前尽力脱敏常见 API key、Bearer token、Cookie、JWT 和私钥，但脱敏不是加密，也不能保证识别所有敏感信息；
 - 路径校验、符号链接检查、Vault 锁、同目录临时文件、fsync 和原子替换用于保护本地写入；
 - memleaf 不主动上传整个 Vault，也没有托管后台、遥测或账号系统；
@@ -438,7 +460,7 @@ python -m build --wheel --sdist
 - 没有模型路由时只能捕获和检索，不能完成自动提炼、显式记忆或压缩；
 - 真实宿主长期运行效果仍取决于本机 Agent 版本、配置、重启和模型可用性；
 - 不提供 Obsidian 插件、Web 管理界面、云同步或透明加密层；
-- `history/` 的批量清理不会被普通检索自动执行，删除操作需要明确调用维护接口。
+- 普通只读检索不会触发保留策略写入；历史淘汰和关闭待办退休只在正常处理/维护生命周期中执行。
 
 
 ## License
@@ -447,3 +469,46 @@ MIT，见 [LICENSE](LICENSE)。
 
 **memleaf**
 *Your memories, in files you own.*
+
+
+## 通用处理与只读验收（0.2.27）
+
+邮件、日历、工单、文件、浏览器与普通对话共用证据准入、覆盖检查和写入路径。
+自动摘要只能使用获准引用的原文；助手复述和旧记忆回读不能单独授权新增写入。
+模型负责语义判断，代码验证来源和原文引用。通过引用校验并不保证模型的语义判断一定正确。
+
+```bash
+memleaf audit --vault /path/to/existing/vault --json
+memleaf process --vault /path/to/existing/vault --source hermes --session-id SESSION --dry-run --json
+```
+
+`audit` 完全本地、只读，不调用模型，不推断旧记忆由哪个版本创建，也不自动清理。
+`--dry-run` 在私有临时副本运行正常处理，可能调用配置的独立 Model Route；不会改写原 Vault。
+检测到原 Vault 并发变化时会拒绝输出可用预览。没有一键应用预览的功能。
+
+工具执行状态与证据完整性分别记录；超限、丢失或不完整内容不会被模型的 NO_CHANGE 升级为完整。
+执行成功但尚有未解决项时，结果显示 `coverage_status=partial`，并保留来源以供有界重试或补充证据。
+行为、限制、测试协议变更见 [通用处理说明](docs/general-processing.md)。
+
+### 工具证据留存配置
+
+```yaml
+capture:
+  tool_evidence_mode: bounded  # bounded | metadata | off
+  include_attachments: false
+```
+
+`bounded` 允许当前轮真实工具观察保留有界、脱敏的正文；小结果可能完整保留，
+不是承诺只保存模型总结。`metadata` 仅留工具调用标识等元数据（仍可能包含标题），
+不保留证据正文，也不把主动排除误报成提炼漏项。`off` 不保存工具证据记录。
+三种模式均不允许把助手复述或旧记忆回读变成独立的新事实。
+
+现有配置未提供新字段时，旧 `include_tool_output: false` 或未设置该开关均按
+`metadata` 处理，旧 `true` 按 `bounded` 处理。显式新字段优先；新建 Vault 只写
+新字段，不再同时写含义冲突的旧开关。`include_attachments: true` 仍受上述总模式限制。
+宿主通过结构化文件路径、文件/附件标识识别文档；不承诺识别任意 Shell 命令或不透明工具
+隐藏读取的文件。用户粘贴的可见文档和显式 `remember` 内容不属于自动附件抓取。
+
+策略在待捕获缓存、inbox 写入和新模型提炼输入处共同执行。配置收紧不会自动删除已提交
+记忆或改写已捕获 inbox；失败前已经冻结的提交计划也不作为新的模型调用重新提炼。
+已捕获工具原文的清理仍遵守原有安全期，明确忘记使用 `forget_memory/forget_about`。

memleaf-0.2.27/docs/core-refactor.md

@@ -0,0 +1,129 @@
+# Shared memory core — controlled refactor
+
+Baseline: `bc7622e0f4c5c7b6658336c4deb71fce6a370f11` (the unreleased 0.2.26
+candidate). This document describes the completed four-increment design, not
+an assertion that arbitrary model outputs are correct. The maintainer chose to
+perform live-model acceptance locally; scripted fixtures are contract tests.
+
+## Product boundaries
+
+Markdown in `knowledge/` and `history/` remains the permanent source of truth.
+Existing Vaults, paths, frontmatter, memory IDs and public tools remain compatible.
+No database, vector engine, model weights, queue service, daemon, telemetry or
+third-party runtime dependency is introduced. The existing host-managed stdio
+MCP subprocess remains supported; no separate service needs deployment.
+
+Hermes still registers `MemleafMemoryProvider` with the official plugin API.
+Native MEMORY.md / USER.md stay read-only cooperating sources. Hermes and Codex
+use the same Core and selected Vault. Source/session identifiers describe
+provenance and lifecycle, never permanent-memory visibility. Scope Map -> search
+-> selected read, retrieval enforcement levels, budget, global todo paging,
+installation and the independent Model Route remain intact.
+
+## Ownership
+
+| Component | Responsibility |
+| --- | --- |
+| Processor | Orchestrate process/remember, compose components explicitly |
+| ModelExecutor | Existing Model Route, bounded correction, diagnostics |
+| PlanningContext | Read related memories, Scope evidence and target context |
+| MemoryPlanner | Validate model proposals and construct change requests |
+| UpdateCoordinator | One bounded reconciliation for an exceptional same-target group |
+| MemoryCommitter | Validate revisions, freeze/execute writes, coordinate forget cancellation |
+| ProcessJournal | Claims, progress, temporary evidence cleanup and retained retry state |
+| TurnAudit | Per-candidate/evidence outcomes and uncommitted lookup overlay |
+| recording_policy | Pre-capture permission controls, no business extraction |
+| evidence_policy | One retention rule for capture, host caches and new planning |
+
+There is one automatic pipeline, not parallel old/new writers, mixin inheritance
+or a dynamic attribute proxy. `Memleaf._mutation_boundary()` is the common Vault
+lock plus interrupted-compaction recovery boundary for automatic/explicit
+commits, raw-library writes, forget and compaction snapshot/commit. Each operation
+retains its own authorization, revision checks and journal. Models execute outside
+this critical section. Pending automatic writes are NOT replayed by entering the
+boundary: forget must be able to cancel them first.
+
+## Semantic ownership
+
+The model selects type, Scope, target and content. Deterministic code validates
+identity, allowed source spans, schema, explicit constraints and local conflicts.
+It can reject a proposal, but must not silently change its business meaning.
+
+Removed paths include completion/rework post-Gate candidate factories, forced
+summary status/timestamp insertion, keyword-based fact/project/todo conversion,
+last-retry Scope reassignment, local splitting of rejected candidates, formal-plan
+preference that changes type, and old/new body concatenation. A persistent wrong
+UPDATE target is DEFERRED, not converted into CREATE. Valid sibling candidates
+continue. The model may correct its proposal during bounded retries.
+
+`NO_CHANGE` remains a valid no-write decision. Missing required todo-update state
+is returned for model correction, not guessed locally. A model-declared ambiguous
+target can be represented as coverage DEFERRED / target_ambiguous. An exact title
+lookup with more than one target cannot select one. Source-local rejection and
+retrieval heuristics remain conservative checks, not a guarantee of semantic
+entailment. Only exact full-statement matching is used for legacy unbound outputs.
+
+For an UPDATE, the model must return the complete intended current state, retaining
+still-valid facts and omitting retired facts. Code no longer appends old paragraphs
+to an incomplete summary. The prior complete version is preserved in history.
+Real-model quality still needs local evaluation, including preservation of old
+facts and recognition of new assertions mixed with questions.
+
+Multiple admitted updates to one target are reconciled using the existing Model
+Route and original target revision. One compatible summary produces one write and
+one history record with all contributing receipts. True conflicts defer the group;
+unrelated targets proceed. Single updates incur no group call. Oversized groups
+are retained, not split into competing writes. Scope-retirement/native-shadowing
+authorizations are not silently combined.
+
+## Lifecycle and privacy
+
+Capture preserves process-owned root journal fields. Frozen requests keep complete
+payloads and checksums; recovery uses the saved payload without another model call.
+Revision checks under lock refuse stale overwrites. Replay preserves the actual
+CREATE/UPDATE outcome for each contributing candidate. This is forward recovery,
+not a database-style atomic transaction across every file in a Vault.
+
+Explicit forget cancels matching frozen operations before deleting files. Unrelated
+siblings survive, stale cancelled owners cannot commit, and a new explicitly
+authorized remember event can store the fact again. No permanent topic blacklist
+is added. Explicit remember skips value classification, not its supplied Scope or
+target-revision constraints.
+
+Successfully captured tool cache records are consumed only after their presence in
+inbox is confirmed. Failed capture retains evidence; historical loss cannot taint
+unrelated future turns. Retention modes and old-config compatibility are specified
+in `evidence-retention.md`. Historical abandoned cache entries are not globally
+purged as part of upgrade; no destructive migration is performed.
+
+Leading recording controls and `record=False` suppress user/assistant/tool content
+before persistence. Session off/resume state survives rebuild/restart, and late
+callbacks for private turns remain private. Examples and quoted controls cannot
+change permission. The command vocabulary is intentionally bounded (for example
+`这段不要记录`, `接下来不要记录`, `恢复记录`, `Don't record this`, `stop recording this session`);
+this is not arbitrary-language privacy inference. Integrations may use record=False.
+Permission state stores only booleans and hashed identifiers, never private text.
+
+Coverage-unresolved evidence receives at most one subsequent natural retry, capped
+to four old turns per process call alongside new complete work. Missing-source,
+Scope/target and ownership ambiguities wait for relevant new information or explicit
+retry instead of spending model budget forever. Exhaustion retains unresolved input.
+
+## Validation and test-contract migration
+
+The existing suite is retained. Renamed tests distinguish a MODEL correcting its
+Scope/type/target from the removed local repair. Public outcomes remain checked:
+stable ID, complete new content, one prior history version, no wrong-Scope write,
+retained inbox and independent sibling progress. Prior tests that expected invalid
+proposals to be rewritten now assert bounded model correction or explicit DEFERRED.
+
+A test that required creation of a fact absent from its input and attached to an
+unrelated target now requires zero writes; the valid duplicate sibling remains
+unchanged. Ambiguity fixtures explicitly return evidence-level DEFERRED and assert
+retention, rather than relying on plan-title keywords. Dedicated raw-response tests
+cover malformed evidence and illegal targets without the fixture binding adapter.
+
+Final-source testing must include the full Linux, Windows and macOS matrix, wheel
+entry points and the matching sdist suite. Native CLI registration is not live
+semantic acceptance. Test results are tied to exact commits/artifacts, not to a
+mutable local worktree or a percentage-complete estimate.

memleaf-0.2.27/docs/evidence-retention.md

@@ -0,0 +1,58 @@
+# Shared tool-evidence retention — refactor phase 3
+
+One deterministic policy governs direct capture, HostRuntime hooks and the copied
+Hermes MemoryProvider. It grants no semantic write permission and adds no service,
+runtime dependency, storage engine or model call.
+
+## Modes and compatibility
+
+| Effective setting | Bodies | Observation metadata |
+| --- | --- | --- |
+| bounded | Redacted, bounded | Retained |
+| metadata | Excluded | Retained |
+| off | Excluded | Excluded |
+
+New Vaults explicitly choose bounded; existing files without a mode preserve the
+legacy boolean (false/absent -> metadata, true -> bounded). An explicit new mode
+wins over the legacy boolean. Invalid strings and non-boolean flags fail closed.
+Loading config does not rewrite it. Normal saves make the effective mode explicit.
+
+The inherited limits remain eight records, 2,000 characters per body, and 320 per
+metadata field. Oversized eligible evidence remains incomplete; its prefix is
+never promoted into a complete fact. Policy-excluded observations are marked
+retention=metadata, have no content, and are not retried as missing evidence.
+No later relaxation recreates discarded original content.
+
+Document/attachment bodies require include_attachments=true and bounded mode.
+HostRuntime and the standalone Hermes adapter classify structural file arguments
+using the same tested contract (path/file_path/file_id/attachment_id/file URI,
+including bounded nesting). This is not a claim to identify every file hidden
+behind arbitrary terminal commands or undocumented remote tools. Direct callers
+must truthfully identify document evidence with source_type=document.
+
+## Lifecycle
+
+- Pre-capture recording permission takes precedence over every retention mode.
+- New host observations and pending-cache reads obey the effective mode.
+- Core capture validates and reapplies it before inbox persistence.
+- New planning calls filter evidence from already captured inbox events too,
+  without mutating the original event identity or frozen-plan input checksum.
+- Successful capture consumes only evidence verified in inbox under the same
+  policy; failed capture does not discard eligible observations.
+- No retrospective deletion of knowledge/history/inbox is implied. Frozen plans
+  already prepared before a policy change recover via their existing contract.
+  Explicit forget coordinates cancellation; a retention toggle is not forget.
+- Old abandoned host sessions are not scanned by a daemon or globally purged.
+  Current sessions consume their caches through the normal lifecycle.
+
+Metadata is not anonymization: identifiers/titles may remain sensitive. Redaction
+is best effort and local plaintext backups remain the user's responsibility.
+
+## Verification
+
+Contract tests cover legacy/no-capture config compatibility, round trips, explicit
+precedence, denied documents, shared Hermes/core classification, bounded redaction,
+cache-policy changes, direct and MCP fields, no model input after tightening,
+no false coverage/retry from deliberate exclusion, and no reconstruction on opt-in.
+Existing general evidence, native memory, lifecycle, retrieval and packaging tests
+remain part of the full suite; no live model credentials are required here.