memleaf 0.2.96__tar.gz → 1.0.1__tar.gz

{memleaf-0.2.96 → memleaf-1.0.1}/CHANGELOG.md

@@ -5,6 +5,83 @@ All notable changes to memleaf are documented here.
 ## Unreleased
 
 
+## 1.0.1 — 2026-10-08
+
+### Optional host-model MCP workflow for Codex
+
+- Add an explicit `--profile host` route that lets Codex and other compatible
+  MCP hosts use their running model to propose memory changes. Memleaf performs
+  deterministic validation, persistence and recovery with no independent model
+  API key, model discovery, sampling or fallback model calls. The existing
+  `model` profile remains the default; native Hermes processing retains its
+  independent Model Route and shared five-request extraction/review budget.
+- Add seven host tools for capabilities, preparation, paged work inspection,
+  submission, recovery, cancellation and approved forgetting. Local Owner
+  commands bind credentials, permissions, scopes and acceptable source trust;
+  `host-grant` returns MCP configuration without modifying Codex defaults.
+  This route requires deliberate tool calls and does not automatically capture
+  or process every conversation turn.
+- Persist source-bound work, cumulative receipts and a default limit of three
+  accepted submits per work. Preserve successful items during partial repair,
+  request idempotency and target revisions during replay, and frozen operation
+  identities during interrupted I/O recovery. Changed connections or request IDs
+  do not reset source budgets; new processing budgets require exact Owner approval.
+- Support action tracking independently of content type, including projects;
+  distinguish `assignee` from `waiting_on` and retain unknown fields without
+  invented evidence. Include source-checked updates, retraction/restoration,
+  preserve-union MERGE and approved COMPACT/delete operations. Check permissions
+  on every work view, query page, replay and historical deletion target.
+- Render client input schemas without local references or object-union display
+  branches, with concise construction examples and safe field-level errors.
+  This display adaptation does not relax the original Core contract validation
+  or add runtime dependencies. Preserve existing public interfaces, default
+  entry points, Markdown memories and history; no formal Vault migration is required.
+
+### Validation and supported scope
+
+- All 152 added deterministic checks passed, covering contract shapes, real
+  stdio MCP, authorization, source evidence, CAS, recovery, retention and legacy
+  data compatibility. Existing affected regression checks were compared with
+  their prior baseline; this is not a claim that all historical tests passed.
+- Live macOS acceptance used Codex CLI 0.162.0-alpha.2 with GPT-6.1 Sol and
+  Hermes CLI 0.21.5 with DeepSeek v4.1 Flash. Both clients completed eight basic
+  behaviors, including independent-process search/read and distinct memories
+  with identical titles. Codex also verified preserve-union MERGE, reopening
+  and cancelling a project, whole-memory retraction/restoration with the same
+  ID, and precisely approved COMPACT: six advanced changes were saved, applied
+  and settled. Acceptance included corrective submits and Owner-approved new
+  processing budgets; it does not establish universal first-pass success.
+- Memleaf made zero independent model calls in these host runs. Host usage was
+  recorded separately: Codex model request counts were unavailable, while
+  Hermes reported actual request/token usage. MCP call counts are not model
+  request counts, and reusing the host model does not mean zero host usage.
+- These live results do not certify every model or MCP client, Windows/Linux
+  real-model behavior, or a formal production-Vault migration/rollback exercise.
+  Installed-artifact CI and real-model acceptance remain separate release gates.
+
+
+## 1.0.0 — 2026-10-06
+
+### Stable public interfaces and production-only distributions
+
+- Define the 1.x compatibility scope for documented Python exports, CLI entry
+  points, MCP tools, configuration and persisted memory formats. Preserve the
+  0.2.96 production runtime, prompts, existing storage/recovery contracts and
+  five-request budget; no model request or Vault migration is added.
+- Move the isolated acceptance harness, synthetic acceptance suite and query
+  benchmark into the ignored local development directory. Remove the former
+  `python -m memleaf.acceptance` developer entry point from public artifacts;
+  normal Python/CLI/MCP interfaces and usage/discovery examples remain.
+- Remove obsolete packaged-tool instructions and prevent developer/private files
+  from re-entering wheel or source distributions through the release CI. Keep
+  the existing five-cell native installation matrix and publish verified bytes.
+- The 0.2.96 installed Hermes acceptance remains evidence for the unchanged
+  production runtime: four successful turns, eight Memleaf requests and 42,518
+  observed tokens. The 1.0.0 release verifies interface compatibility, isolated
+  installed regressions and clean artifact payloads separately; a stable version
+  is not a guarantee of perfect future model responses.
+
+
 ## 0.2.96 — 2026-10-06
 
 ### Preserve existing information when replacing memory bodies

{memleaf-0.2.96 → memleaf-1.0.1}/MANIFEST.in

@@ -5,9 +5,8 @@ include install.ps1
 include README.md
 include README.en.md
 recursive-include examples *.md *.ndjson *.py
-recursive-exclude examples *_acceptance.py
+recursive-exclude examples *_acceptance.py query_benchmark.py incremental_acceptance.json
 prune tests
+prune tests_public
 
 include docs/*.md
-
-include examples/incremental_acceptance.json

{memleaf-0.2.96/src/memleaf.egg-info → memleaf-1.0.1}/PKG-INFO

@@ -1,10 +1,11 @@
 Metadata-Version: 2.4
 Name: memleaf
-Version: 0.2.96
+Version: 1.0.1
 Summary: A local-first Markdown memory core for AI agents
 Author: memleaf contributors
 License-Expression: MIT
 Keywords: ai-agents,local-first,markdown,memory
+Classifier: Development Status :: 5 - Production/Stable
 Classifier: Intended Audience :: Developers
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3 :: Only
@@ -23,12 +24,10 @@ Dynamic: license-file
 
 [English](README.en.md) · [PyPI](https://pypi.org/project/memleaf/) · [GitHub](https://github.com/miffyblueboo/memleaf)
 
-> **版本：0.2.96。**
-> 自动提炼和复核共用同一条“未来记忆价值”标准：模型综合未来复用、信息增量、再次读取时的直接可用性和忘记成本，只保留对未来理解、判断或行动有实质影响的最小核心；没有明确价值的信息不提炼，不按具体业务场景硬编码排除。
-> 提炼先比较旧事项中的编号、目标、进展、责任和期限；补全未知信息也应维护原事项，另建独立待办不能替代项目事实更新。确认重复的记忆在现有处理请求中合并，保留历史与来源；项目和独立任务保持各自生命周期，Core 不按标题强行合并。
-> 新请求兼容等价的字段表示；未知执行人保持 `null`，新增或变更负责人和期限需要真实来源；等待条件在正文维护，不再提炼 `waiting_on`。行动及相关字段经过有界语义复核，提炼与复核共用每份工作的最多五次模型请求额度，成功即停止；复核失败不写入。来源时间用于解析相对日期，不补造事实日期。
-> 待办 `due_date` 只表示待办动作本身明确声明的截止日；属于待办主题或预期结果的日期不会被误作截止日。项目归属由模型按语义判断，不要求项目名在证据里逐字出现。复核阶段会保留首轮已选定的更新目标，避免“状态变更”被降级成新增记忆。Markdown 仍是唯一事实源。
-> **当前版本支持 Hermes 和 Codex。** Antigravity（反重力）不检测、不安装、不配置。
+> **稳定版：1.0.1。** 支持 Hermes 和 Codex；版本与兼容范围见[稳定性约定](docs/stability.md)。
+> **Codex 可通过 `--profile host` 使用当前宿主模型完成记忆闭环，无需另配 Memleaf 模型 API Key。** 本地 Owner 仍需配置客户端身份、读写权限及来源信任；客户端主动调用工具，不代表每轮自动记忆。
+> host profile 支持独立于内容类型的 `actionable` 和结构化 `waiting_on`，每份 work 默认最多三次被接受的 submit；Memleaf 负责确定性校验、落盘与恢复。
+> 默认 `model` profile 和 Hermes 原生接入继续使用独立 Model Route，提炼与语义复核共用每份工作的最多五次模型请求。旧接口、现有记忆和默认入口保留，升级无需正式 Vault 迁移。Antigravity（反重力）当前不支持。
 
 ## 项目定位
 
@@ -45,6 +44,8 @@ memleaf 不会把整个 Vault 或整段历史对话自动塞进模型上下文
 
 ## 当前工作流
 
+原有 `model` profile / Hermes 原生工作流：
+
 ```text
 可见的 user/assistant 对话
         │
@@ -89,6 +90,16 @@ Hermes 使用原生 MemoryProvider 维护生命周期，并通过 MCP 获取 Sco
 
 ## 记忆提炼规则
 
+以下规则适用于原有 `model` profile / Hermes 原生自动提炼；host profile 的动作、字段与预算见下文 [Codex host 接入](#codex)。
+
+自动提炼和复核共用同一条“未来记忆价值”标准：模型综合未来复用、信息增量、再次读取时的直接可用性和忘记成本，只保留对未来理解、判断或行动有实质影响的最小核心；没有明确价值的信息不提炼，不按具体业务场景硬编码排除。
+
+提炼先比较旧事项中的编号、目标、进展、责任和期限；补全未知信息也应维护原事项，另建独立待办不能替代项目事实更新。确认重复的记忆在现有处理请求中合并，保留历史与来源；项目和独立任务保持各自生命周期，Core 不按标题强行合并。
+
+新请求兼容等价的字段表示；未知执行人保持 `null`，新增或变更负责人和期限需要真实来源；等待条件在正文维护，不再提炼 `waiting_on`。行动及相关字段经过有界语义复核，提炼与复核共用每份工作的最多五次模型请求额度，成功即停止；复核失败不写入。来源时间用于解析相对日期，不补造事实日期。
+
+待办 `due_date` 只表示待办动作本身明确声明的截止日；属于待办主题或预期结果的日期不会被误作截止日。项目归属由模型按语义判断，不要求项目名在证据里逐字出现。复核阶段会保留首轮已选定的更新目标，避免“状态变更”被降级成新增记忆。Markdown 仍是唯一事实源。
+
 **10 秒是自动提炼的性能目标，不是失败阈值。** HTTP 请求遵循 `llm.request_timeout`（默认 120 秒）；正常返回且通过 Core 校验的结果不会仅因超过 10 秒而丢弃。模型单次请求、有限修复和逐轮提交保留，耗时与是否完成分别统计。详见 [提炼耗时与超时](docs/extraction-latency.md)。
 
 memleaf 不把每句话都保存为记忆。处理一轮完整的 user + assistant 可见文本时，模型先判断是否存在明确的未来复用价值：
@@ -111,7 +122,7 @@ memleaf 不把每句话都保存为记忆。处理一轮完整的 user + assista
 
 ## 安装
 
-要求 Python 3.11+；当前版本支持 Hermes 和 Codex。Hermes 是默认安装目标，Codex 使用明确的独立安装命令。
+要求 Python 3.11+。Hermes 是默认安装目标；Codex 可明确选择下述 host MCP 接入，或保留原有 model profile 自动提炼接入。
 
 ### Windows
 
@@ -180,6 +191,35 @@ Hermes 显式保存使用 MCP `save_turn`：先绑定本轮并排队，轮次完
 
 ### Codex
 
+#### 复用 Codex 当前模型：host profile
+
+安装包后，由本地 Owner 为客户端创建授权：
+
+```bash
+python -m pip install -U memleaf
+python -m memleaf host-grant --vault /path/to/vault --principal codex --accept-caller-asserted --json
+```
+
+`host-grant` 输出 `mcpServers` 的 `command`/`args` 和本地凭据文件路径，不会自动修改 Codex 配置。凭据用于本地授权，是以 `0600` 创建的文件，不是模型 Key；默认路径为 `<vault>/_state/host_credentials/codex.token`，也可通过 `--credential-file` 指定新路径。已有凭据文件不会被覆盖。
+
+默认读写范围为 `global`；需要其他范围时，在创建授权的命令上重复传入 `--read-scope` 和 `--write-scope`。`--accept-caller-asserted` 表示 Owner 信任该客户端如实提交可见对话，不代表 Memleaf 独立验证了用户决定。省略该选项时，应先通过 Owner 确认来源或使用可靠绑定的来源。维护、永久删除等能力需要各自权限和精确审批，详见 [host-v2 合同](docs/host-v2-contract.md)。
+
+将输出中的实际 Python、Vault 和凭据绝对路径显式注册到 Codex，例如：
+
+```bash
+codex mcp add memleaf-host -- /absolute/path/to/python -m memleaf.mcp_server --vault /path/to/vault --profile host --token-file /path/to/credential.token
+```
+
+注册后重启或重新连接 Codex MCP。`memleaf-host` 是示例服务名；已有接入应先核对其 profile，避免同时配置两条处理同一来源的路线。Memleaf 不读取或复制 Codex 的模型 Key；推理使用正在运行的宿主模型，并计入该宿主自身的用量。
+
+客户端先调用 `memory_capabilities`，再以 `prepare_memory → memory_work（按需分页 sources/targets）→ submit_memory` 完成保存，仅在保存项的 receipt 中 `applied=true` 且 `settled=true` 时确认已保存。部分成功后只在同一 work 内修正未完成项；I/O 中断用 `resume_memory` 恢复。后续会话使用 `search → read` 读取正式 Markdown。host profile 允许项目等非 `todo` 内容携带行动属性，`assignee` 与 `waiting_on` 分别表示执行人和依赖方；未知事实保持未知，变化字段需来源依据。
+
+每份 work 默认最多三次被接受的 submit，错误提案也可能消耗预算；这不是三次模型 API 请求额度。换 request ID、连接或重交同一来源不会重置预算。host profile 提供七个 v2 工具、`capture` 和查询工具；客户端需要主动执行闭环，旧 Model Route Hook 不会自动替它处理每轮记忆。
+
+#### 原有自动提炼接入：model profile
+
+以下安装与 Hook 流程继续使用独立 Memleaf Model Route：
+
 先安装或升级 memleaf，再明确选择 Codex：
 
 ```bash
@@ -190,7 +230,7 @@ python -m pip install -U memleaf && python -m memleaf install --host codex
 
 安装后打开 Codex，运行 `/hooks`，审核并信任 memleaf Hook。完成授权前，MCP 可用不等于自动捕获、检索门控和提炼已经激活；安装结果会明确显示 `pending_user_review`，不会把待审核状态报告为已启用。
 
-Codex 只作为宿主，不作为 memleaf 的提炼模型来源。已有的独立 memleaf Model Route 会继续复用；如果当前 Vault 还没有完整 Model Route，Codex 安装仍可完成 MCP/Hook 配置，但结果会明确返回 `processing_status=model_route_required`，在配置模型前不能把“自动记忆提炼”视为已就绪。memleaf 不读取、不复制也不修改 Codex 的 `model`、`model_provider`、`base_url` 或认证信息，也不会为了提炼偷偷消耗 Codex 会话额度。Codex-only 用户可针对同一个 Vault 运行：
+在这条原有 model 路线中，Codex 只作为宿主，不作为 memleaf 的提炼模型来源。已有的独立 memleaf Model Route 会继续复用；如果当前 Vault 还没有完整 Model Route，Codex 安装仍可完成 MCP/Hook 配置，但结果会明确返回 `processing_status=model_route_required`，在配置模型前不能把“自动记忆提炼”视为已就绪。memleaf 不读取、不复制也不修改 Codex 的 `model`、`model_provider`、`base_url` 或认证信息，也不会为了提炼偷偷消耗 Codex 会话额度。Codex-only 用户可针对同一个 Vault 运行：
 
 ```bash
 python -m memleaf init --no-hermes --vault /path/to/the/same/vault
@@ -223,9 +263,9 @@ memleaf init --no-model-discovery
 memleaf init --json
 ```
 
-`init` 下的 `--no-codex` 和 `--no-antigravity` 为兼容保留的无操作参数；Codex 必须通过 `install --host codex` 明确安装。宿主配置只会在检测证据可靠、结构可识别且没有冲突时修改；修改前会创建备份，未知或冲突配置保持不变。
+`init` 下的 `--no-codex` 和 `--no-antigravity` 为兼容保留的无操作参数；原有 model profile 的 Codex 接入使用 `install --host codex`；host profile 使用上面的显式 MCP 注册。宿主配置只会在检测证据可靠、结构可识别且没有冲突时修改；修改前会创建备份，未知或冲突配置保持不变。
 
-## Codex 使用方式
+## Codex 原有 model profile 使用方式
 
 - `UserPromptSubmit` 只注入有界 Scope Map 和当前轮次的检索协议，不注入记忆标题或正文；
 - `PreToolUse` / `PostToolUse` 将 memleaf `search` 和 `read` 绑定到当前 `retrieval_id`，记录真实检索结果与读取预算；
@@ -235,7 +275,7 @@ memleaf init --json
 
 Codex Hook 必须经过用户审核和信任。若 Hook 未激活、被禁用或 Codex 版本不支持对应生命周期事件，自动捕获和自动提炼不会生效；MCP 主动工具与 Hook 生命周期是两个独立状态。
 
-## Hermes 使用方式
+## Hermes 原生接入使用方式
 
 Hermes 的原生 Provider 和 MCP Server 是两个不同入口，但共用同一个 `$HOME/.memleaf`：
 
@@ -271,7 +311,7 @@ python -m memleaf.mcp_server --vault "$HOME/.memleaf"
 
 不传 `--vault` 时默认使用 `~/.memleaf`；也可以设置 `MEMLEAF_VAULT`。正常情况下不需要手工常驻，Hermes 或 Codex 会按需启动它。stdout 只输出 JSON-RPC，日志不会污染协议通道。
 
-当前提供以下工具：
+未传 `--profile` 时使用兼容保留的 `model` profile，其工具如下；host profile 的工具和授权流程见上文。
 
 | 工具 | 用途 |
 | --- | --- |
@@ -357,7 +397,7 @@ python -m memleaf.mcp_server --vault /path/to/your/vault \
   < examples/mcp_stdio.ndjson
 ```
 
-## 模型路由
+## 原有 model profile 的模型路由
 
 捕获、索引、目录检索和读取可离线运行；`process()`、`remember()` 和 `compact()` 需要可用的模型能力。
 
@@ -491,12 +531,12 @@ python -m build --wheel --sdist
 
 以下内容不应被 README 或安装结果误解为已交付能力：
 
-- Windows、macOS 和 Linux 都提供 Hermes 安装入口；Codex 通过 `memleaf install --host codex` 明确接入；源码 `install.sh` 仅保留给开发、离线源码安装和故障排查；
+- Windows、macOS 和 Linux 都提供 Hermes 安装入口；Codex 明确选择 host MCP 或 `memleaf install --host codex` 原有 model 接入；源码 `install.sh` 仅保留给开发、离线源码安装和故障排查；
 - 当前支持 Hermes 和 Codex；Antigravity（反重力）不检测、不安装、不配置；
 - Codex 生命周期 Hook 需要用户在 `/hooks` 中审核并信任，安装程序不能代替用户完成授权；
 - Hermes 的检索门控是 Soft Gate，不保证阻止所有未检索回答；
-- 没有模型路由时只能捕获和检索，不能完成自动提炼、显式记忆或压缩；
-- 真实宿主长期运行效果仍取决于本机 Agent 版本、配置、重启和模型可用性；
+- 原有 model profile / Hermes 原生处理需要 Model Route；host profile 无需独立模型 Key，但仍需 Owner 授权和可接受来源，并由宿主主动执行记忆闭环；
+- 1.0.1 在 macOS 实机验证了 Codex CLI 与 Hermes CLI 的基础 host 行为，以及 Codex 的高级维护行为；该证据不代表所有模型、所有 MCP 客户端或 Windows 真实模型验收；真实宿主长期效果仍取决于本机版本、配置和模型可用性；
 - 不提供 Obsidian 插件、Web 管理界面、云同步或透明加密层；
 - 普通只读检索不会触发保留策略写入；历史淘汰和关闭待办退休只在正常处理/维护生命周期中执行。
 

{memleaf-0.2.96 → memleaf-1.0.1}/README.en.md

@@ -4,12 +4,10 @@
 
 [中文](README.md) · [PyPI](https://pypi.org/project/memleaf/) · [GitHub](https://github.com/miffyblueboo/memleaf)
 
-> **Version: 0.2.96.**
-> Automatic extraction and review share one future-value standard: the model weighs likely reuse, information gain, direct usability when read again, and the cost of forgetting. It keeps only the smallest core that can materially help future understanding, decisions, or actions; information without clear value is not extracted, and no business-specific exclusion rule is hard-coded.
-> Extraction compares existing identifiers, objectives, progress, responsibility and deadlines first. Filling an unknown also maintains the original item; a separate task does not replace updating shared project facts. Confirmed duplicates can be merged in the existing processing requests with their sources and history preserved. Independent project and task lifecycles remain separate; Core does not merge matching titles.
-> New requests accept equivalent field representations. Unknown executors remain `null`; new or changed responsibility and deadlines require actual source evidence. Dependencies belong in the body; `waiting_on` is no longer extracted. Proposed actions and related fields undergo bounded semantic verification within a shared five-request limit per work item, stopping on success; failed verification blocks writes. Source time resolves relative dates without inventing factual dates.
-> A todo's `due_date` means only the explicit deadline of the todo action; dates describing its subject or desired outcome are not deadlines. Project ownership remains the model's semantic judgement and needs no literal name match. The review stage now keeps the update target chosen by the first pass, so a state change is no longer downgraded into a new memory. Markdown remains the sole source of truth.
-> **The current release supports Hermes and Codex.** Antigravity is not detected, installed, or configured.
+> **Stable release: 1.0.1.** Hermes and Codex are supported; see the [stability policy](docs/stability.md) for compatibility scope.
+> **Codex can complete the memory workflow with its current host model through `--profile host`, without a separate Memleaf model API key.** A local Owner still configures client identity, permissions and source trust. Clients invoke the tools deliberately; this does not enable automatic memory on every turn.
+> The host profile supports `actionable` independently of content type and structured `waiting_on`, with at most three accepted submits per work by default. Memleaf validates, persists and recovers deterministically.
+> The default `model` profile and native Hermes integration retain their independent Model Route and shared five-request extraction/review budget. Existing interfaces, memories and default entry points remain; no formal Vault migration is required. Antigravity is not supported.
 
 ## Project scope
 
@@ -26,6 +24,8 @@ memleaf does not automatically put the entire Vault or a whole conversation hist
 
 ## Current workflow
 
+Original `model` profile / native Hermes workflow:
+
 ```text
 Visible user/assistant conversation
         │
@@ -67,6 +67,16 @@ Hermes uses a native MemoryProvider for lifecycle handling and obtains the Scope
 
 ## Memory admission and maintenance
 
+The following rules apply to the original `model` profile and native Hermes automatic processing. See [Codex host setup](#codex) below for host actions, fields and budgets.
+
+Automatic extraction and review share one future-value standard: the model weighs likely reuse, information gain, direct usability when read again, and the cost of forgetting. It keeps only the smallest core that can materially help future understanding, decisions, or actions; information without clear value is not extracted, and no business-specific exclusion rule is hard-coded.
+
+Extraction compares existing identifiers, objectives, progress, responsibility and deadlines first. Filling an unknown also maintains the original item; a separate task does not replace updating shared project facts. Confirmed duplicates can be merged in the existing processing requests with their sources and history preserved. Independent project and task lifecycles remain separate; Core does not merge matching titles.
+
+New requests accept equivalent field representations. Unknown executors remain `null`; new or changed responsibility and deadlines require actual source evidence. Dependencies belong in the body; `waiting_on` is no longer extracted. Proposed actions and related fields undergo bounded semantic verification within a shared five-request limit per work item, stopping on success; failed verification blocks writes. Source time resolves relative dates without inventing factual dates.
+
+A todo's `due_date` means only the explicit deadline of the todo action; dates describing its subject or desired outcome are not deadlines. Project ownership remains the model's semantic judgement and needs no literal name match. The review stage now keeps the update target chosen by the first pass, so a state change is no longer downgraded into a new memory. Markdown remains the sole source of truth.
+
 **Ten seconds is an extraction performance target, not a failure deadline.** HTTP requests honor `llm.request_timeout` (120 seconds by default). A valid, Core-checked response is not discarded just because processing exceeds ten seconds. Single-pass planning, bounded repair and per-turn commits remain; completion and latency are measured separately. See [extraction latency and timeouts](docs/extraction-latency.md).
 
 memleaf does not save every sentence. When a complete visible user + assistant turn is processed, the model first evaluates whether it has concrete future reuse value:
@@ -92,7 +102,7 @@ For current todos, all unfinished work, urgent items, or work due in a date rang
 
 ## Installation
 
-Python 3.11+ is required. The current release supports Hermes and Codex. Hermes is the default install target; Codex uses an explicit, separate install command.
+Python 3.11+ is required. Hermes is the default install target. For Codex, explicitly select the host MCP setup below or retain the original model profile with automatic processing.
 
 ### Windows
 
@@ -161,6 +171,35 @@ The repository `install.sh` remains for source development, offline source insta
 
 ### Codex
 
+#### Reuse the current Codex model: host profile
+
+Install the package, then have the local Owner authorize the client:
+
+```bash
+python -m pip install -U memleaf
+python -m memleaf host-grant --vault /path/to/vault --principal codex --accept-caller-asserted --json
+```
+
+`host-grant` returns the `mcpServers` command/arguments and a local credential file path; it does not automatically change Codex configuration. The credential binds local authorization, is created with mode `0600`, and is not a model key. Its default path is `<vault>/_state/host_credentials/codex.token`; `--credential-file` can select a new path. Existing credential files are preserved.
+
+Read/write scopes default to `global`. Repeat `--read-scope` and `--write-scope` in the grant command for other scopes. `--accept-caller-asserted` means the Owner trusts the client to report visible conversation accurately; it does not independently verify a user decision. Without that option, use Owner-confirmed or reliably bound sources. Maintenance and permanent deletion require their respective permissions and exact approvals; see the [host-v2 contract](docs/host-v2-contract.md).
+
+Explicitly register the actual Python, Vault and credential absolute paths from the output with Codex, for example:
+
+```bash
+codex mcp add memleaf-host -- /absolute/path/to/python -m memleaf.mcp_server --vault /path/to/vault --profile host --token-file /path/to/credential.token
+```
+
+Restart or reconnect Codex MCP after registration. `memleaf-host` is an example server name; check the profile of any existing connection before configuring two routes to process the same sources. Memleaf does not read or copy Codex model keys. Reasoning uses the running host model and counts toward that host's usage.
+
+Call `memory_capabilities`, then run `prepare_memory → memory_work` (page sources/targets as needed) `→ submit_memory`. Confirm a save only when its receipt has `applied=true` and `settled=true`. Repair only unresolved items in the same work after partial success; use `resume_memory` for interrupted I/O. Later sessions retrieve the committed Markdown with `search → read`. Non-`todo` content, including projects, can carry action fields; `assignee` identifies the executor and `waiting_on` the dependency. Unknown facts remain unknown and field changes require source evidence.
+
+Each work permits at most three accepted submits by default; invalid proposals can consume an attempt. This is not a three-call model API budget. Changing the request ID or connection, or replaying the same sources, does not reset it. The host profile exposes seven v2 tools, `capture` and query tools. Clients invoke the workflow deliberately; existing Model Route hooks do not automatically process every turn through this profile.
+
+#### Original automatic processing: model profile
+
+The following installer and hook flow retains the independent Memleaf Model Route:
+
 Install or upgrade memleaf, then explicitly select Codex:
 
 ```bash
@@ -171,7 +210,7 @@ This command reuses the one Vault already configured for Hermes or Codex, or cre
 
 After installation, open Codex, run `/hooks`, and review and trust the memleaf hooks. Until that approval is complete, an available MCP server does not mean that automatic capture, retrieval gating, and processing are active. The installer reports `pending_user_review` instead of claiming that unreviewed hooks are enabled.
 
-Codex is a host, not memleaf's extraction-model source. An existing independent memleaf Model Route is reused. If the selected Vault has no complete Model Route yet, Codex MCP/hooks can still be configured, but installation explicitly returns `processing_status=model_route_required`; automatic memory extraction is not ready until that route is configured. memleaf does not read, copy, or modify Codex `model`, `model_provider`, `base_url`, or credentials, and it does not silently spend Codex session quota for extraction. A Codex-only user can configure the same Vault with:
+In this original model route, Codex is a host, not memleaf's extraction-model source. An existing independent memleaf Model Route is reused. If the selected Vault has no complete Model Route yet, Codex MCP/hooks can still be configured, but installation explicitly returns `processing_status=model_route_required`; automatic memory extraction is not ready until that route is configured. memleaf does not read, copy, or modify Codex `model`, `model_provider`, `base_url`, or credentials, and it does not silently spend Codex session quota for extraction. A Codex-only user can configure the same Vault with:
 
 ```bash
 python -m memleaf init --no-hermes --vault /path/to/the/same/vault
@@ -204,9 +243,9 @@ memleaf init --no-model-discovery
 memleaf init --json
 ```
 
-Under `init`, `--no-codex` and `--no-antigravity` remain compatibility no-ops; Codex must be installed explicitly with `install --host codex`. Host configuration is changed only when detection evidence is reliable, the structure is understood, and there is no conflict. Backups are created before changes; unknown or conflicting configuration is left unchanged.
+Under `init`, `--no-codex` and `--no-antigravity` remain compatibility no-ops. The original model profile uses `install --host codex`; the host profile uses the explicit MCP registration above. Host configuration is changed only when detection evidence is reliable, the structure is understood, and there is no conflict. Backups are created before changes; unknown or conflicting configuration is left unchanged.
 
-## Codex integration
+## Original Codex model profile integration
 
 - `UserPromptSubmit` injects only a bounded Scope Map and the current-turn retrieval protocol, never memory titles or bodies.
 - `PreToolUse` / `PostToolUse` bind memleaf `search` and `read` to the current `retrieval_id` and record the real search result and read budget.
@@ -216,7 +255,7 @@ Under `init`, `--no-codex` and `--no-antigravity` remain compatibility no-ops; C
 
 Codex hooks require user review and trust. If the hooks are pending, disabled, or unsupported by the installed Codex version, automatic capture and processing are inactive; MCP tool availability and hook lifecycle activation are separate states.
 
-## Hermes integration
+## Native Hermes integration
 
 Hermes' native Provider and the MCP server are separate entry points, but they share the same `$HOME/.memleaf` Vault:
 
@@ -252,7 +291,7 @@ python -m memleaf.mcp_server --vault "$HOME/.memleaf"
 
 Without `--vault`, the server uses `~/.memleaf`; `MEMLEAF_VAULT` can also specify the Vault. In normal use the server does not need to be kept running manually: Hermes or Codex starts it on demand. stdout contains only JSON-RPC messages so logs do not corrupt the protocol stream.
 
-The server exposes the following tools:
+Without `--profile`, the server retains the original `model` profile and the tools below. See the host setup above for its tools and authorization flow.
 
 | Tool | Purpose |
 | --- | --- |
@@ -339,7 +378,7 @@ python -m memleaf.mcp_server --vault /path/to/your/vault \
   < examples/mcp_stdio.ndjson
 ```
 
-## Model routing
+## Original model profile routing
 
 Capture, indexing, directory retrieval, and reading work offline. `process()`, `remember()`, and `compact()` require a usable model route.
 
@@ -471,12 +510,12 @@ python -m build --wheel --sdist
 
 The following should not be interpreted as delivered capabilities:
 
-- Windows, macOS, and Linux provide a Hermes installation entry point; Codex is explicitly configured with `memleaf install --host codex`. The source `install.sh` remains only for development, offline source installation, and troubleshooting.
+- Windows, macOS, and Linux provide a Hermes installation entry point; Codex explicitly selects host MCP or the original model setup with `memleaf install --host codex`. The source `install.sh` remains only for development, offline source installation, and troubleshooting.
 - The current release supports Hermes and Codex. Antigravity is not detected, installed, or configured.
 - Codex lifecycle hooks require user review and trust through `/hooks`; the installer cannot approve them on the user's behalf.
 - Hermes retrieval gating is a Soft Gate and does not guarantee that every answer performed retrieval.
-- 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.
+- The original model profile and native Hermes processing require a Model Route. The host profile requires no independent model key, but still needs Owner authorization, acceptable sources and deliberate execution by the host.
+- On macOS, 1.0.1 has live Codex CLI and Hermes CLI evidence for basic host behavior, plus advanced Codex maintenance behavior. This does not establish support for every model or MCP client, or live Windows model acceptance. Long-running behavior still depends on local versions, configuration and model availability.
 - There is no Obsidian plugin, web management UI, cloud sync, or transparent encryption layer.
 - Routine read-only retrieval never performs retention writes; history pruning and closed-todo retirement run only during normal processing/maintenance lifecycle calls.
 

{memleaf-0.2.96 → memleaf-1.0.1}/README.md

@@ -4,12 +4,10 @@
 
 [English](README.en.md) · [PyPI](https://pypi.org/project/memleaf/) · [GitHub](https://github.com/miffyblueboo/memleaf)
 
-> **版本：0.2.96。**
-> 自动提炼和复核共用同一条“未来记忆价值”标准：模型综合未来复用、信息增量、再次读取时的直接可用性和忘记成本，只保留对未来理解、判断或行动有实质影响的最小核心；没有明确价值的信息不提炼，不按具体业务场景硬编码排除。
-> 提炼先比较旧事项中的编号、目标、进展、责任和期限；补全未知信息也应维护原事项，另建独立待办不能替代项目事实更新。确认重复的记忆在现有处理请求中合并，保留历史与来源；项目和独立任务保持各自生命周期，Core 不按标题强行合并。
-> 新请求兼容等价的字段表示；未知执行人保持 `null`，新增或变更负责人和期限需要真实来源；等待条件在正文维护，不再提炼 `waiting_on`。行动及相关字段经过有界语义复核，提炼与复核共用每份工作的最多五次模型请求额度，成功即停止；复核失败不写入。来源时间用于解析相对日期，不补造事实日期。
-> 待办 `due_date` 只表示待办动作本身明确声明的截止日；属于待办主题或预期结果的日期不会被误作截止日。项目归属由模型按语义判断，不要求项目名在证据里逐字出现。复核阶段会保留首轮已选定的更新目标，避免“状态变更”被降级成新增记忆。Markdown 仍是唯一事实源。
-> **当前版本支持 Hermes 和 Codex。** Antigravity（反重力）不检测、不安装、不配置。
+> **稳定版：1.0.1。** 支持 Hermes 和 Codex；版本与兼容范围见[稳定性约定](docs/stability.md)。
+> **Codex 可通过 `--profile host` 使用当前宿主模型完成记忆闭环，无需另配 Memleaf 模型 API Key。** 本地 Owner 仍需配置客户端身份、读写权限及来源信任；客户端主动调用工具，不代表每轮自动记忆。
+> host profile 支持独立于内容类型的 `actionable` 和结构化 `waiting_on`，每份 work 默认最多三次被接受的 submit；Memleaf 负责确定性校验、落盘与恢复。
+> 默认 `model` profile 和 Hermes 原生接入继续使用独立 Model Route，提炼与语义复核共用每份工作的最多五次模型请求。旧接口、现有记忆和默认入口保留，升级无需正式 Vault 迁移。Antigravity（反重力）当前不支持。
 
 ## 项目定位
 
@@ -26,6 +24,8 @@ memleaf 不会把整个 Vault 或整段历史对话自动塞进模型上下文
 
 ## 当前工作流
 
+原有 `model` profile / Hermes 原生工作流：
+
 ```text
 可见的 user/assistant 对话
         │
@@ -70,6 +70,16 @@ Hermes 使用原生 MemoryProvider 维护生命周期，并通过 MCP 获取 Sco
 
 ## 记忆提炼规则
 
+以下规则适用于原有 `model` profile / Hermes 原生自动提炼；host profile 的动作、字段与预算见下文 [Codex host 接入](#codex)。
+
+自动提炼和复核共用同一条“未来记忆价值”标准：模型综合未来复用、信息增量、再次读取时的直接可用性和忘记成本，只保留对未来理解、判断或行动有实质影响的最小核心；没有明确价值的信息不提炼，不按具体业务场景硬编码排除。
+
+提炼先比较旧事项中的编号、目标、进展、责任和期限；补全未知信息也应维护原事项，另建独立待办不能替代项目事实更新。确认重复的记忆在现有处理请求中合并，保留历史与来源；项目和独立任务保持各自生命周期，Core 不按标题强行合并。
+
+新请求兼容等价的字段表示；未知执行人保持 `null`，新增或变更负责人和期限需要真实来源；等待条件在正文维护，不再提炼 `waiting_on`。行动及相关字段经过有界语义复核，提炼与复核共用每份工作的最多五次模型请求额度，成功即停止；复核失败不写入。来源时间用于解析相对日期，不补造事实日期。
+
+待办 `due_date` 只表示待办动作本身明确声明的截止日；属于待办主题或预期结果的日期不会被误作截止日。项目归属由模型按语义判断，不要求项目名在证据里逐字出现。复核阶段会保留首轮已选定的更新目标，避免“状态变更”被降级成新增记忆。Markdown 仍是唯一事实源。
+
 **10 秒是自动提炼的性能目标，不是失败阈值。** HTTP 请求遵循 `llm.request_timeout`（默认 120 秒）；正常返回且通过 Core 校验的结果不会仅因超过 10 秒而丢弃。模型单次请求、有限修复和逐轮提交保留，耗时与是否完成分别统计。详见 [提炼耗时与超时](docs/extraction-latency.md)。
 
 memleaf 不把每句话都保存为记忆。处理一轮完整的 user + assistant 可见文本时，模型先判断是否存在明确的未来复用价值：
@@ -92,7 +102,7 @@ memleaf 不把每句话都保存为记忆。处理一轮完整的 user + assista
 
 ## 安装
 
-要求 Python 3.11+；当前版本支持 Hermes 和 Codex。Hermes 是默认安装目标，Codex 使用明确的独立安装命令。
+要求 Python 3.11+。Hermes 是默认安装目标；Codex 可明确选择下述 host MCP 接入，或保留原有 model profile 自动提炼接入。
 
 ### Windows
 
@@ -161,6 +171,35 @@ Hermes 显式保存使用 MCP `save_turn`：先绑定本轮并排队，轮次完
 
 ### Codex
 
+#### 复用 Codex 当前模型：host profile
+
+安装包后，由本地 Owner 为客户端创建授权：
+
+```bash
+python -m pip install -U memleaf
+python -m memleaf host-grant --vault /path/to/vault --principal codex --accept-caller-asserted --json
+```
+
+`host-grant` 输出 `mcpServers` 的 `command`/`args` 和本地凭据文件路径，不会自动修改 Codex 配置。凭据用于本地授权，是以 `0600` 创建的文件，不是模型 Key；默认路径为 `<vault>/_state/host_credentials/codex.token`，也可通过 `--credential-file` 指定新路径。已有凭据文件不会被覆盖。
+
+默认读写范围为 `global`；需要其他范围时，在创建授权的命令上重复传入 `--read-scope` 和 `--write-scope`。`--accept-caller-asserted` 表示 Owner 信任该客户端如实提交可见对话，不代表 Memleaf 独立验证了用户决定。省略该选项时，应先通过 Owner 确认来源或使用可靠绑定的来源。维护、永久删除等能力需要各自权限和精确审批，详见 [host-v2 合同](docs/host-v2-contract.md)。
+
+将输出中的实际 Python、Vault 和凭据绝对路径显式注册到 Codex，例如：
+
+```bash
+codex mcp add memleaf-host -- /absolute/path/to/python -m memleaf.mcp_server --vault /path/to/vault --profile host --token-file /path/to/credential.token
+```
+
+注册后重启或重新连接 Codex MCP。`memleaf-host` 是示例服务名；已有接入应先核对其 profile，避免同时配置两条处理同一来源的路线。Memleaf 不读取或复制 Codex 的模型 Key；推理使用正在运行的宿主模型，并计入该宿主自身的用量。
+
+客户端先调用 `memory_capabilities`，再以 `prepare_memory → memory_work（按需分页 sources/targets）→ submit_memory` 完成保存，仅在保存项的 receipt 中 `applied=true` 且 `settled=true` 时确认已保存。部分成功后只在同一 work 内修正未完成项；I/O 中断用 `resume_memory` 恢复。后续会话使用 `search → read` 读取正式 Markdown。host profile 允许项目等非 `todo` 内容携带行动属性，`assignee` 与 `waiting_on` 分别表示执行人和依赖方；未知事实保持未知，变化字段需来源依据。
+
+每份 work 默认最多三次被接受的 submit，错误提案也可能消耗预算；这不是三次模型 API 请求额度。换 request ID、连接或重交同一来源不会重置预算。host profile 提供七个 v2 工具、`capture` 和查询工具；客户端需要主动执行闭环，旧 Model Route Hook 不会自动替它处理每轮记忆。
+
+#### 原有自动提炼接入：model profile
+
+以下安装与 Hook 流程继续使用独立 Memleaf Model Route：
+
 先安装或升级 memleaf，再明确选择 Codex：
 
 ```bash
@@ -171,7 +210,7 @@ python -m pip install -U memleaf && python -m memleaf install --host codex
 
 安装后打开 Codex，运行 `/hooks`，审核并信任 memleaf Hook。完成授权前，MCP 可用不等于自动捕获、检索门控和提炼已经激活；安装结果会明确显示 `pending_user_review`，不会把待审核状态报告为已启用。
 
-Codex 只作为宿主，不作为 memleaf 的提炼模型来源。已有的独立 memleaf Model Route 会继续复用；如果当前 Vault 还没有完整 Model Route，Codex 安装仍可完成 MCP/Hook 配置，但结果会明确返回 `processing_status=model_route_required`，在配置模型前不能把“自动记忆提炼”视为已就绪。memleaf 不读取、不复制也不修改 Codex 的 `model`、`model_provider`、`base_url` 或认证信息，也不会为了提炼偷偷消耗 Codex 会话额度。Codex-only 用户可针对同一个 Vault 运行：
+在这条原有 model 路线中，Codex 只作为宿主，不作为 memleaf 的提炼模型来源。已有的独立 memleaf Model Route 会继续复用；如果当前 Vault 还没有完整 Model Route，Codex 安装仍可完成 MCP/Hook 配置，但结果会明确返回 `processing_status=model_route_required`，在配置模型前不能把“自动记忆提炼”视为已就绪。memleaf 不读取、不复制也不修改 Codex 的 `model`、`model_provider`、`base_url` 或认证信息，也不会为了提炼偷偷消耗 Codex 会话额度。Codex-only 用户可针对同一个 Vault 运行：
 
 ```bash
 python -m memleaf init --no-hermes --vault /path/to/the/same/vault
@@ -204,9 +243,9 @@ memleaf init --no-model-discovery
 memleaf init --json
 ```
 
-`init` 下的 `--no-codex` 和 `--no-antigravity` 为兼容保留的无操作参数；Codex 必须通过 `install --host codex` 明确安装。宿主配置只会在检测证据可靠、结构可识别且没有冲突时修改；修改前会创建备份，未知或冲突配置保持不变。
+`init` 下的 `--no-codex` 和 `--no-antigravity` 为兼容保留的无操作参数；原有 model profile 的 Codex 接入使用 `install --host codex`；host profile 使用上面的显式 MCP 注册。宿主配置只会在检测证据可靠、结构可识别且没有冲突时修改；修改前会创建备份，未知或冲突配置保持不变。
 
-## Codex 使用方式
+## Codex 原有 model profile 使用方式
 
 - `UserPromptSubmit` 只注入有界 Scope Map 和当前轮次的检索协议，不注入记忆标题或正文；
 - `PreToolUse` / `PostToolUse` 将 memleaf `search` 和 `read` 绑定到当前 `retrieval_id`，记录真实检索结果与读取预算；
@@ -216,7 +255,7 @@ memleaf init --json
 
 Codex Hook 必须经过用户审核和信任。若 Hook 未激活、被禁用或 Codex 版本不支持对应生命周期事件，自动捕获和自动提炼不会生效；MCP 主动工具与 Hook 生命周期是两个独立状态。
 
-## Hermes 使用方式
+## Hermes 原生接入使用方式
 
 Hermes 的原生 Provider 和 MCP Server 是两个不同入口，但共用同一个 `$HOME/.memleaf`：
 
@@ -252,7 +291,7 @@ python -m memleaf.mcp_server --vault "$HOME/.memleaf"
 
 不传 `--vault` 时默认使用 `~/.memleaf`；也可以设置 `MEMLEAF_VAULT`。正常情况下不需要手工常驻，Hermes 或 Codex 会按需启动它。stdout 只输出 JSON-RPC，日志不会污染协议通道。
 
-当前提供以下工具：
+未传 `--profile` 时使用兼容保留的 `model` profile，其工具如下；host profile 的工具和授权流程见上文。
 
 | 工具 | 用途 |
 | --- | --- |
@@ -338,7 +377,7 @@ python -m memleaf.mcp_server --vault /path/to/your/vault \
   < examples/mcp_stdio.ndjson
 ```
 
-## 模型路由
+## 原有 model profile 的模型路由
 
 捕获、索引、目录检索和读取可离线运行；`process()`、`remember()` 和 `compact()` 需要可用的模型能力。
 
@@ -472,12 +511,12 @@ python -m build --wheel --sdist
 
 以下内容不应被 README 或安装结果误解为已交付能力：
 
-- Windows、macOS 和 Linux 都提供 Hermes 安装入口；Codex 通过 `memleaf install --host codex` 明确接入；源码 `install.sh` 仅保留给开发、离线源码安装和故障排查；
+- Windows、macOS 和 Linux 都提供 Hermes 安装入口；Codex 明确选择 host MCP 或 `memleaf install --host codex` 原有 model 接入；源码 `install.sh` 仅保留给开发、离线源码安装和故障排查；
 - 当前支持 Hermes 和 Codex；Antigravity（反重力）不检测、不安装、不配置；
 - Codex 生命周期 Hook 需要用户在 `/hooks` 中审核并信任，安装程序不能代替用户完成授权；
 - Hermes 的检索门控是 Soft Gate，不保证阻止所有未检索回答；
-- 没有模型路由时只能捕获和检索，不能完成自动提炼、显式记忆或压缩；
-- 真实宿主长期运行效果仍取决于本机 Agent 版本、配置、重启和模型可用性；
+- 原有 model profile / Hermes 原生处理需要 Model Route；host profile 无需独立模型 Key，但仍需 Owner 授权和可接受来源，并由宿主主动执行记忆闭环；
+- 1.0.1 在 macOS 实机验证了 Codex CLI 与 Hermes CLI 的基础 host 行为，以及 Codex 的高级维护行为；该证据不代表所有模型、所有 MCP 客户端或 Windows 真实模型验收；真实宿主长期效果仍取决于本机版本、配置和模型可用性；
 - 不提供 Obsidian 插件、Web 管理界面、云同步或透明加密层；
 - 普通只读检索不会触发保留策略写入；历史淘汰和关闭待办退休只在正常处理/维护生命周期中执行。