memleaf 0.2.26__tar.gz → 0.2.28__tar.gz

{memleaf-0.2.26 → memleaf-0.2.28}/CHANGELOG.md

@@ -2,6 +2,24 @@
 
 All notable changes to memleaf are documented here.
 
+## 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.
+- 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.

{memleaf-0.2.26/src/memleaf.egg-info → memleaf-0.2.28}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: memleaf
-Version: 0.2.26
+Version: 0.2.28
 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.26。**
-> 核心库、Vault、stdio MCP Server、初始化 CLI、模型路由、提炼流程、受控检索协议和宿主适配器已经实现。本版完成共享记忆核心重构；真实模型语义效果仍需结合本地模型和业务样本验收。
+> **版本：0.2.27。**
+> 核心库、Vault、stdio MCP Server、初始化 CLI、模型路由、提炼流程、受控检索协议和宿主适配器已经实现。本版收口长期运行治理：Core 语义判断保持 source-neutral，并为来源、关闭待办、历史版本和压缩身份增加有界生命周期。真实模型语义效果仍需结合本地模型和代表性样本验收。
 > **当前版本支持 Hermes 和 Codex。** Antigravity（反重力）不检测、不安装、不配置。
 
 ## 项目定位
@@ -417,6 +417,28 @@ $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、备份和模型调用凭证。
 
 ## 隐私与安全边界
@@ -457,7 +479,7 @@ python -m build --wheel --sdist
 - 没有模型路由时只能捕获和检索，不能完成自动提炼、显式记忆或压缩；
 - 真实宿主长期运行效果仍取决于本机 Agent 版本、配置、重启和模型可用性；
 - 不提供 Obsidian 插件、Web 管理界面、云同步或透明加密层；
-- `history/` 的批量清理不会被普通检索自动执行，删除操作需要明确调用维护接口。
+- 普通只读检索不会触发保留策略写入；历史淘汰和关闭待办退休只在正常处理/维护生命周期中执行。
 
 
 ## License
@@ -468,7 +490,7 @@ MIT，见 [LICENSE](LICENSE)。
 *Your memories, in files you own.*
 
 
-## 通用处理与只读验收（0.2.26）
+## 通用处理与只读验收（0.2.27）
 
 邮件、日历、工单、文件、浏览器与普通对话共用证据准入、覆盖检查和写入路径。
 自动摘要只能使用获准引用的原文；助手复述和旧记忆回读不能单独授权新增写入。

{memleaf-0.2.26 → memleaf-0.2.28}/README.en.md

@@ -4,8 +4,8 @@
 
 [中文](README.md) · [PyPI](https://pypi.org/project/memleaf/) · [GitHub](https://github.com/miffyblueboo/memleaf)
 
-> **Version: 0.2.26.**
-> The core library, Vault, stdio MCP server, initialization CLI, model routing, memory extraction, controlled retrieval protocol, and host adapters are implemented. This version completes the shared memory core refactor; real-model semantics still require local acceptance with the selected model and representative inputs.
+> **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,6 +400,28 @@ $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
@@ -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
@@ -452,7 +474,7 @@ MIT; see [LICENSE](LICENSE).
 *Your memories, in files you own.*
 
 
-## General processing and read-only inspection (0.2.26 candidate)
+## 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.

{memleaf-0.2.26 → memleaf-0.2.28}/README.md

@@ -4,8 +4,8 @@
 
 [English](README.en.md) · [PyPI](https://pypi.org/project/memleaf/) · [GitHub](https://github.com/miffyblueboo/memleaf)
 
-> **版本：0.2.26。**
-> 核心库、Vault、stdio MCP Server、初始化 CLI、模型路由、提炼流程、受控检索协议和宿主适配器已经实现。本版完成共享记忆核心重构；真实模型语义效果仍需结合本地模型和业务样本验收。
+> **版本：0.2.27。**
+> 核心库、Vault、stdio MCP Server、初始化 CLI、模型路由、提炼流程、受控检索协议和宿主适配器已经实现。本版收口长期运行治理：Core 语义判断保持 source-neutral，并为来源、关闭待办、历史版本和压缩身份增加有界生命周期。真实模型语义效果仍需结合本地模型和代表性样本验收。
 > **当前版本支持 Hermes 和 Codex。** Antigravity（反重力）不检测、不安装、不配置。
 
 ## 项目定位
@@ -398,6 +398,28 @@ $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、备份和模型调用凭证。
 
 ## 隐私与安全边界
@@ -438,7 +460,7 @@ python -m build --wheel --sdist
 - 没有模型路由时只能捕获和检索，不能完成自动提炼、显式记忆或压缩；
 - 真实宿主长期运行效果仍取决于本机 Agent 版本、配置、重启和模型可用性；
 - 不提供 Obsidian 插件、Web 管理界面、云同步或透明加密层；
-- `history/` 的批量清理不会被普通检索自动执行，删除操作需要明确调用维护接口。
+- 普通只读检索不会触发保留策略写入；历史淘汰和关闭待办退休只在正常处理/维护生命周期中执行。
 
 
 ## License
@@ -449,7 +471,7 @@ MIT，见 [LICENSE](LICENSE)。
 *Your memories, in files you own.*
 
 
-## 通用处理与只读验收（0.2.26）
+## 通用处理与只读验收（0.2.27）
 
 邮件、日历、工单、文件、浏览器与普通对话共用证据准入、覆盖检查和写入路径。
 自动摘要只能使用获准引用的原文；助手复述和旧记忆回读不能单独授权新增写入。

memleaf-0.2.28/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.26 → memleaf-0.2.28}/docs/general-processing.md

@@ -1,4 +1,4 @@
-# General processing reliability contract — 0.2.26 candidate
+# General processing reliability contract — 0.2.27
 
 This is source-neutral processing, not a mail extractor. Dialogue, documents,
 calendars, issue trackers and terminal/tool observations use the same admission

memleaf-0.2.28/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.26 → memleaf-0.2.28}/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.26 → memleaf-0.2.28}/pyproject.toml

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

{memleaf-0.2.26 → memleaf-0.2.28}/src/memleaf/__init__.py

@@ -1,6 +1,6 @@
 """Local-first Markdown memory core for AI agents."""
 
-__version__ = "0.2.26"
+__version__ = "0.2.28"
 
 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.26 → memleaf-0.2.28}/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.26 → memleaf-0.2.28}/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.26 → memleaf-0.2.28}/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.