memleaf 0.1.7__tar.gz → 0.2.0__tar.gz

{memleaf-0.1.7 → memleaf-0.2.0}/CHANGELOG.md

@@ -2,6 +2,22 @@
 
 All notable changes to memleaf are documented here.
 
+## 0.2.0 — 2026-08-31
+
+- Hardened the supported Codex integration against the official Codex CLI 0.151.0 on Windows and macOS, including `CODEX_HOME`, npm `codex.cmd` discovery, UTF-8 CLI output, idempotent `mcp add/get`, and quote-free Windows lifecycle commands carried through a UTF-16LE PowerShell `EncodedCommand` payload.
+- Aligned Codex `PreToolUse` argument rewriting with the current hook contract by returning `permissionDecision=allow` together with `updatedInput`, preserving the current-turn `retrieval_id` binding.
+- Restored the finalized automatic retrieval contract: the bounded Scope Map exposes only Scope metadata, `search` candidates expose only `memory_id + title`, and selected memory bodies enter context only through bounded `read` calls under the existing retrieval gate and budgets.
+- Added durable shared-Vault acceptance for Codex → Codex, Hermes → Codex, and Codex → Hermes so cross-session and cross-host memory reuse is verified without duplicating CREATE/UPDATE/NO_CHANGE, history, deduplication, or processing semantics outside the Core.
+- Kept Codex installation explicitly opt-in and fail-closed: existing Codex model/provider, profiles, sandbox/approval settings, MCP entries, hooks, and custom providers remain untouched; conflicting host Vaults are rejected rather than guessed.
+- Decoupled the Codex host from the extraction model. Automatic processing uses an independent memleaf Model Route, reports `processing_status=model_route_required` when no complete route exists, and never copies Codex credentials or silently consumes the active Codex session model.
+- Promoted native Codex Windows/macOS acceptance, cross-host memory roundtrips, Linux/Windows/macOS host tests, and packaging checks into release-blocking CI gates.
+
+## 0.1.8 — 2026-08-31
+
+- Fixed Windows UTF-8 stdio handling across the MCP server, Hermes MemoryProvider, and Codex host-event entry point so Chinese and other non-ASCII memory content can be captured, searched, read, and injected without depending on the system code page.
+- Added native Windows coverage for Codex executable discovery and Hermes MCP subprocess execution, including Unicode paths and payloads.
+- Strengthened Windows and macOS release gates to exercise Hermes and Codex installation, host lifecycle, bounded Scope Map injection, controlled `search` → `read`, retrieval budgets, memory extraction/update semantics, and session-lineage behavior before release.
+
 ## 0.1.7 — 2026-08-31
 
 - Added supported Codex integration through the explicit

{memleaf-0.1.7 → memleaf-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: memleaf
-Version: 0.1.7
+Version: 0.2.0
 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.1.7。**
-> 核心库、Vault、stdio MCP Server、初始化 CLI、模型路由、提炼流程、受控检索协议和宿主适配器已经实现。memleaf 0.1.7 通过 PyPI 分发。
+> **当前版本：0.2.0。**
+> 核心库、Vault、stdio MCP Server、初始化 CLI、模型路由、提炼流程、受控检索协议和宿主适配器已经实现。memleaf 0.2.0 通过 PyPI 分发。
 > **当前版本支持 Hermes 和 Codex。** Antigravity（反重力）不检测、不安装、不配置。
 
 ## 项目定位
@@ -65,7 +65,7 @@ memleaf 不会把整个 Vault 或整段历史对话自动塞进模型上下文
 
 1. Agent 使用当前完整会话和 Scope Map 选择检索范围与查询词；
 2. 至少调用一次 `search`；
-3. `search` 只返回候选的 `memory_id`、标题和 Scope，不直接返回正文；
+3. `search` 候选默认只返回 `memory_id` 和标题；Scope 已由 Scope Map 与本次搜索参数确定，不随每条候选重复返回，也不直接返回正文；
 4. 只有需要引用事实时，才使用同一轮返回的 `retrieval_id` 调用 `read`；
 5. 根据读取到的关键记忆回答，不把所有候选全部读完。
 
@@ -172,6 +172,14 @@ 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 运行：
+
+```bash
+python -m memleaf init --no-hermes --vault /path/to/the/same/vault
+```
+
+完成独立 Model Route 配置后，再使用 Codex 自动提炼。DeepSeek、OpenRouter 或其他自定义 Codex provider 因此保持原样。
+
 Antigravity（反重力）当前不支持，安装流程不会检测、安装或修改其配置。
 
 ### 高级初始化命令（可选）

{memleaf-0.1.7 → memleaf-0.2.0}/README.en.md

@@ -4,8 +4,8 @@
 
 [中文](README.md) · [PyPI](https://pypi.org/project/memleaf/) · [GitHub](https://github.com/miffyblueboo/memleaf)
 
-> **Version: 0.1.7.**
-> The core library, Vault, stdio MCP server, initialization CLI, model routing, memory extraction, controlled retrieval protocol, and host adapters are implemented. memleaf 0.1.7 is distributed through PyPI.
+> **Version: 0.2.0.**
+> The core library, Vault, stdio MCP server, initialization CLI, model routing, memory extraction, controlled retrieval protocol, and host adapters are implemented. memleaf 0.2.0 is distributed through PyPI.
 > **The current release supports Hermes and Codex.** Antigravity is not detected, installed, or configured.
 
 ## Project scope
@@ -46,7 +46,7 @@ For a normal user message, the intended flow is:
 
 1. The Agent uses the full current conversation and the Scope Map to choose a scope and query.
 2. It calls `search` at least once.
-3. `search` returns only candidate `memory_id`, title, and Scope metadata; it does not return the body.
+3. `search` candidates return only `memory_id` and title by default. Scope is already selected through the Scope Map and the search input, so it is not repeated per candidate; bodies are never returned by search.
 4. If a business fact is needed, the Agent calls `read` with the `retrieval_id` from the same turn.
 5. The Agent answers from the selected bodies instead of reading every candidate.
 
@@ -153,6 +153,14 @@ 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:
+
+```bash
+python -m memleaf init --no-hermes --vault /path/to/the/same/vault
+```
+
+After the independent Model Route is ready, Codex automatic extraction can use it. DeepSeek, OpenRouter, and other custom Codex providers therefore remain untouched.
+
 Antigravity is not currently supported; the installer does not detect, install, or modify its configuration.
 
 ### Advanced initialization commands (optional)

{memleaf-0.1.7 → memleaf-0.2.0}/README.md

@@ -4,8 +4,8 @@
 
 [English](README.en.md) · [PyPI](https://pypi.org/project/memleaf/) · [GitHub](https://github.com/miffyblueboo/memleaf)
 
-> **当前版本：0.1.7。**
-> 核心库、Vault、stdio MCP Server、初始化 CLI、模型路由、提炼流程、受控检索协议和宿主适配器已经实现。memleaf 0.1.7 通过 PyPI 分发。
+> **当前版本：0.2.0。**
+> 核心库、Vault、stdio MCP Server、初始化 CLI、模型路由、提炼流程、受控检索协议和宿主适配器已经实现。memleaf 0.2.0 通过 PyPI 分发。
 > **当前版本支持 Hermes 和 Codex。** Antigravity（反重力）不检测、不安装、不配置。
 
 ## 项目定位
@@ -46,7 +46,7 @@ memleaf 不会把整个 Vault 或整段历史对话自动塞进模型上下文
 
 1. Agent 使用当前完整会话和 Scope Map 选择检索范围与查询词；
 2. 至少调用一次 `search`；
-3. `search` 只返回候选的 `memory_id`、标题和 Scope，不直接返回正文；
+3. `search` 候选默认只返回 `memory_id` 和标题；Scope 已由 Scope Map 与本次搜索参数确定，不随每条候选重复返回，也不直接返回正文；
 4. 只有需要引用事实时，才使用同一轮返回的 `retrieval_id` 调用 `read`；
 5. 根据读取到的关键记忆回答，不把所有候选全部读完。
 
@@ -153,6 +153,14 @@ 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 运行：
+
+```bash
+python -m memleaf init --no-hermes --vault /path/to/the/same/vault
+```
+
+完成独立 Model Route 配置后，再使用 Codex 自动提炼。DeepSeek、OpenRouter 或其他自定义 Codex provider 因此保持原样。
+
 Antigravity（反重力）当前不支持，安装流程不会检测、安装或修改其配置。
 
 ### 高级初始化命令（可选）

{memleaf-0.1.7 → memleaf-0.2.0}/RELEASE_CHECKLIST.md

@@ -21,8 +21,20 @@
 
 - [ ] Linux Python 3.11 / 3.12 / 3.13 完整 unittest 通过。
 - [ ] Windows Python 3.11 / 3.12 / 3.13 安装与集成验收通过。
+- [ ] macOS Python 3.11 / 3.13 Hermes/Codex 宿主与记忆语义验收通过。
 - [ ] Windows 真实 Provider → `memleaf-mcp` stdio 回归通过：
   `stats`、`scope_catalog`、user/assistant capture、inbox 落盘。
+- [ ] Windows 与 macOS 使用当前受支持 Codex CLI 做真实 `codex mcp add/get` 验收，
+  Unicode/空格路径正常，重复安装为 `already_configured` 且 `changed=false`。
+- [ ] Codex `PreToolUse` 参数重写符合当前 Hook 合同：
+  `permissionDecision=allow` 与 `updatedInput` 同时存在，当前轮 `retrieval_id` 不丢失。
+- [ ] Windows `commandWindows` 不含会触发 Codex 当前 cmd 外层引号缺陷的内嵌双引号；
+  Python/Vault 含空格和中文时，quote-free 命令在原生 `cmd.exe` 执行回归通过。
+- [ ] Codex → Codex、Hermes → Codex、Codex → Hermes 三条共享 Vault 持久记忆闭环全部通过。
+- [ ] Scope Map 仍只注入 Scope/alias/检索协议；`search` 候选严格只返回
+  `memory_id + title`，`read` 才读取选中正文，检索预算与 retrieval gate 保持。
+- [ ] CREATE / UPDATE / NO_CHANGE、history、去重、process 继续由 Core 统一实现，
+  Codex/Hermes Adapter 不复制记忆语义。
 - [ ] wheel 与 sdist 构建通过。
 - [ ] 从 wheel 安装后 `memleaf` / `memleaf-mcp` 入口正常。
 - [ ] 从 sdist 解包后的测试通过。
@@ -48,6 +60,13 @@
 - [ ] Windows 路径仍支持 `%LOCALAPPDATA%\hermes` 及官方 launcher 布局。
 - [ ] 从旧版本升级时保留已有 Hermes `memleaf.json` 中的自定义 Vault，不静默切换到默认 Vault。
 - [ ] Provider 的 Windows stdio 实现不重新引入 `select.select(pipe)`。
+- [ ] 普通升级/`memleaf install` 不自动配置 Codex；只有显式
+  `memleaf install --host codex` 才修改 Codex memleaf 接入。
+- [ ] Codex 安装前后的 model/model_provider/base_url、sandbox、approval、
+  profiles、已有 MCP 与已有 Hooks 保持；DeepSeek/OpenRouter/自定义 provider 不被改写。
+- [ ] Hermes/Codex 已有 Vault 唯一一致时复用；冲突时 `vault_conflict` fail closed。
+- [ ] Codex 自动提炼只使用独立 memleaf Model Route；没有 Route 时明确返回
+  `processing_status=model_route_required`，不复制 Codex credential、不隐式消耗 Codex 会话模型。
 - [ ] shell、Python 与 PowerShell 安装路径都使用
   `src/memleaf/hermes_provider` 这一份权威 Provider 源码。
 

{memleaf-0.1.7 → memleaf-0.2.0}/pyproject.toml

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

{memleaf-0.1.7 → memleaf-0.2.0}/src/memleaf/__init__.py

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

@@ -7,6 +7,7 @@ contents and possible secrets cannot accidentally end up in ``agents.json``.
 
 from __future__ import annotations
 
+import base64
 import datetime as _datetime
 import hashlib
 import inspect
@@ -355,10 +356,28 @@ def host_event_command(
         absolute_vault(vault),
     )
     if (os.name if platform is None else platform) == "nt":
-        return subprocess.list2cmdline(args)
+        # Codex currently wraps commandWindows in an outer cmd.exe /C quoted
+        # string. Embedded quotes can break that wrapper. Put the real argv in
+        # a UTF-16LE PowerShell EncodedCommand payload instead: commandWindows
+        # itself stays quote-free while paths with spaces/Unicode remain exact.
+        script = "& " + " ".join(_powershell_single_quoted(argument) for argument in args)
+        script += "; exit $LASTEXITCODE"
+        payload = base64.b64encode(script.encode("utf-16le")).decode("ascii")
+        return (
+            "powershell.exe -NoLogo -NoProfile -NonInteractive "
+            "-ExecutionPolicy Bypass -EncodedCommand " + payload
+        )
     return " ".join(shlex.quote(argument) for argument in args)
 
 
+def _powershell_single_quoted(value: str) -> str:
+    """Return one literal PowerShell string for an encoded Windows hook."""
+
+    if not isinstance(value, str) or not value or any(char in value for char in "\r\n\x00"):
+        raise ValueError("invalid Windows command argument")
+    return "'" + value.replace("'", "''") + "'"
+
+
 def run_argv(
     runner: CommandRunner | None,
     argv: Sequence[str],
@@ -427,6 +446,11 @@ def _subprocess_runner(
         "check": False,
         "capture_output": True,
         "text": True,
+        # Codex and the supported host CLIs emit UTF-8.  Relying on the
+        # Windows process default code page corrupts non-ASCII JSON paths
+        # before adapters can validate them.
+        "encoding": "utf-8",
+        "errors": "strict",
         "env": dict(env),
     }
     if input_text is not None:

{memleaf-0.1.7 → memleaf-0.2.0}/src/memleaf/adapters/codex.py

@@ -68,6 +68,12 @@ class CodexAdapter:
         self.env = adapter_environment(env)
         effective_home = home if home is not None else self.env.get("HOME")
         self.home = adapter_home(effective_home)
+        codex_home_value = self.env.get("CODEX_HOME")
+        self.codex_home = (
+            Path(codex_home_value).expanduser().resolve()
+            if isinstance(codex_home_value, str) and codex_home_value.strip()
+            else self.home / ".codex"
+        )
         self.platform = os.name if platform is None else platform
         self.interpreter = interpreter if interpreter is not None else sys.executable
         if known_paths is None:
@@ -101,11 +107,11 @@ class CodexAdapter:
 
     @property
     def config_path(self) -> Path:
-        return self.home / ".codex" / "config.toml"
+        return self.codex_home / "config.toml"
 
     @property
     def hooks_path(self) -> Path:
-        return self.home / ".codex" / "hooks.json"
+        return self.codex_home / "hooks.json"
 
     def detect(self) -> Detection:
         config = self.config_path
@@ -124,11 +130,20 @@ class CodexAdapter:
                     status="diagnostic",
                 )
         if executable is None:
-            executable = resolve_executable(
-                "codex.exe" if self.platform == "nt" else "codex",
-                env=self.env,
-                known_paths=self.known_paths,
-            )
+            # Native Windows installs commonly expose codex.exe, while the
+            # official npm package exposes codex.cmd on PATH.  Accept both
+            # before falling back to documented bundled/runtime locations.
+            path_names = ("codex.exe", "codex.cmd", "codex") if self.platform == "nt" else ("codex",)
+            for name in path_names:
+                executable = resolve_executable(name, env=self.env)
+                if executable is not None:
+                    break
+            if executable is None:
+                executable = resolve_executable(
+                    "codex.exe" if self.platform == "nt" else "codex",
+                    env={**self.env, "PATH": ""},
+                    known_paths=self.known_paths,
+                )
         config_value = str(config)
         if executable is not None:
             return Detection(
@@ -584,6 +599,22 @@ def _entry_vault(entry: Mapping[str, Any]) -> Path | None:
     return Path(raw_vault).expanduser().resolve()
 
 
+def _path_equivalent(left: str, right: str) -> bool:
+    """Compare host paths without weakening the expected command structure."""
+
+    try:
+        if Path(left).exists() and Path(right).exists():
+            return os.path.samefile(left, right)
+    except OSError:
+        pass
+    try:
+        left_value = os.path.normcase(str(Path(left).expanduser().resolve()))
+        right_value = os.path.normcase(str(Path(right).expanduser().resolve()))
+    except (OSError, RuntimeError):
+        return False
+    return left_value == right_value
+
+
 def _entry_matches(
     entry: Mapping[str, Any],
     vault: Path | str,
@@ -593,8 +624,17 @@ def _entry_matches(
     candidate = _entry_candidate(entry)
     if candidate is None:
         return False
+    command = candidate.get("command")
+    args = candidate.get("args")
+    if not isinstance(command, str) or not isinstance(args, list) or len(args) != 4:
+        return False
+    if args[:3] != ["-m", "memleaf.mcp_server", "--vault"]:
+        return False
+    raw_vault = args[3]
+    if not isinstance(raw_vault, str) or not raw_vault:
+        return False
     expected = mcp_command(vault, interpreter=interpreter)
-    return candidate.get("command") == expected[0] and candidate.get("args") == expected[1:]
+    return _path_equivalent(command, expected[0]) and _path_equivalent(raw_vault, expected[4])
 
 
 def _inline_hooks_diagnostic(path: Path) -> str | None:

{memleaf-0.1.7 → memleaf-0.2.0}/src/memleaf/cli.py

@@ -47,7 +47,7 @@ def build_parser() -> argparse.ArgumentParser:
     init.add_argument(
         "--no-antigravity",
         action="store_true",
-        help="accepted for compatibility; Antigravity is disabled in v0.1",
+        help="accepted for compatibility; Antigravity is currently unsupported",
     )
     init.add_argument(
         "--no-model-discovery",
@@ -76,7 +76,19 @@ def build_parser() -> argparse.ArgumentParser:
     return parser
 
 
+def _configure_stdio_utf8() -> None:
+    for stream in (sys.stdin, sys.stdout, sys.stderr):
+        reconfigure = getattr(stream, "reconfigure", None)
+        if not callable(reconfigure):
+            continue
+        try:
+            reconfigure(encoding="utf-8", errors="strict")
+        except (OSError, ValueError):
+            continue
+
+
 def main(argv: Sequence[str] | None = None) -> int:
+    _configure_stdio_utf8()
     parser = build_parser()
     args = parser.parse_args(argv)
     try:
@@ -200,13 +212,22 @@ def _init(args: argparse.Namespace) -> dict:
             attempt=args.all,
         )
 
-    # Retain legacy APIs, but never inspect or configure unsupported hosts.
-    # Clear stale activation claims in our own index, not the user's hosts.
-    for name, config_path in (
-        ("codex", home / ".codex" / "config.toml"),
-        ("antigravity", home / ".gemini" / "config" / "mcp_config.json"),
-    ):
-        reason = f"{name} is disabled in v0.1; no detection or configuration performed"
+    # 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.
+    legacy_slots = (
+        (
+            "codex",
+            home / ".codex" / "config.toml",
+            "Codex is not configured by init; use install --host codex",
+        ),
+        (
+            "antigravity",
+            home / ".gemini" / "config" / "mcp_config.json",
+            "Antigravity is currently unsupported; no detection or configuration performed",
+        ),
+    )
+    for name, config_path, reason in legacy_slots:
         results[name] = result_from_detection(
             Detection(
                 agent=name, detected=False, confidence="none", reason=reason,

{memleaf-0.1.7 → memleaf-0.2.0}/src/memleaf/hermes_provider/__init__.py

@@ -911,6 +911,8 @@ class _MCPClient:
             stdout=subprocess.PIPE,
             stderr=subprocess.DEVNULL,
             text=True,
+            encoding="utf-8",
+            errors="strict",
             bufsize=1,
         )
         self._start_stdout_reader_locked(self._process)

{memleaf-0.1.7 → memleaf-0.2.0}/src/memleaf/hermes_provider/plugin.yaml

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

{memleaf-0.1.7 → memleaf-0.2.0}/src/memleaf/host_events.py

@@ -326,6 +326,10 @@ def _handle_codex_pre_tool(
     return {
         "hookSpecificOutput": {
             "hookEventName": "PreToolUse",
+            # Codex only applies updatedInput when the hook explicitly allows
+            # the call.  Omitting this field makes the rewrite invalid and
+            # would drop memleaf's current-turn retrieval_id binding.
+            "permissionDecision": "allow",
             "updatedInput": prepared.arguments,
         }
     }

{memleaf-0.1.7 → memleaf-0.2.0}/src/memleaf/installer.py

@@ -442,15 +442,26 @@ def install_codex(*, vault_path: Path | None = None) -> dict[str, Any]:
             "model": model,
             "codex": configured.to_dict(),
         }
+    model_ready = model.get("status") in {"configured", "already_configured"}
+    actions: list[str] = []
+    if configured.user_action_required and configured.user_action:
+        actions.append(configured.user_action)
+    if not model_ready:
+        actions.append(
+            "Configure an independent memleaf Model Route for this Vault before "
+            "relying on automatic memory extraction. Codex model/provider settings "
+            "are intentionally not used or modified."
+        )
     return {
         "status": configured.status,
         "reason": configured.reason,
         "vault": str(vault.root),
         "vault_source": vault_source,
         "model": model,
+        "processing_status": "ready" if model_ready else "model_route_required",
         "codex": configured.to_dict(),
-        "user_action_required": configured.user_action_required,
-        "user_action": configured.user_action,
+        "user_action_required": bool(actions),
+        "user_action": " ".join(actions) if actions else None,
     }
 
 

{memleaf-0.1.7 → memleaf-0.2.0}/src/memleaf/mcp_server.py

@@ -53,7 +53,7 @@ INSTRUCTIONS = (
     "user turn, including greetings, call memleaf search at least once before answering. Use your "
     "complete conversation context to select scope and query; do not add a needs-memory gate. "
     "Fetch further scope_catalog pages when the map has_more; never assume an omitted scope is absent. "
-    "Search returns status=found or no_match and lightweight results (memory_id, title, scopes), "
+    "Search returns status=found or no_match and lightweight results (memory_id, title), "
     "not bodies. Errors are not no_match: correct scope_mismatch or retry a failed search at most "
     "twice, then honestly report degraded retrieval; do not claim memory was checked successfully. "
     "Treat directory entries as leads, never as verified facts; do not infer facts from a title. "
@@ -68,7 +68,7 @@ INSTRUCTIONS = (
     "scope/search/read flow. Managed MCP search is directory-only and rejects view=full; "
     "Python full-result search remains compatible. Without host integration, tools remain an explicit fallback only; "
     "do not claim automatic recall, recording or final-answer enforcement succeeded. "
-    "Hermes is the only supported host in v0.1 and uses a Soft Gate, not a hard guarantee. "
+    "Hermes and Codex are supported hosts; Hermes uses a Soft Gate, not a hard guarantee. "
     "When explicitly calling legacy context, pass source and session_id together and avoid "
     "duplicating native memory that the target host already loads. "
     "Capture only user-visible and assistant-visible text. Never capture system or developer "
@@ -183,7 +183,7 @@ _TOOLS: tuple[dict[str, Any], ...] = (
         "name": "search",
         "description": (
             "Search once per ordinary user turn. Return found/no_match and paged lightweight "
-            "results (memory_id, title, scopes), at most 20/4000 characters, without changing hits. "
+            "results (memory_id, title), at most 20/4000 characters, without changing hits. "
             "retrieval_id is required and must be the host-provided current-turn token. Errors are "
             "failures, never no_match. Managed MCP search is directory-only; view=full is rejected. "
             "Python search(view='full') remains the compatibility interface."
@@ -475,16 +475,18 @@ def _search_result(value: Any) -> dict[str, Any]:
     entries = value.get("results")
     if not isinstance(entries, list):
         raise ValueError("invalid search results")
+    results: list[dict[str, str]] = []
     for entry in entries:
         if not isinstance(entry, Mapping):
             raise ValueError("invalid search entry")
-        if any(not isinstance(entry.get(name), str) or not entry[name] for name in ("memory_id", "title")):
+        memory_id = entry.get("memory_id")
+        title = entry.get("title")
+        if not isinstance(memory_id, str) or not memory_id or not isinstance(title, str) or not title:
             raise ValueError("invalid search identifiers")
-        scopes = entry.get("scopes")
-        if not isinstance(scopes, list) or not scopes or not all(isinstance(scope, str) and scope for scope in scopes):
-            raise ValueError("invalid search scopes")
-    results = [_directory_item(entry) for entry in entries]
-    if any(entry is None for entry in results) or bool(results) != (value["status"] == "found"):
+        # Search is intentionally narrower than the legacy directory helper:
+        # do not leak per-memory scope/tags/aliases/keywords into candidates.
+        results.append({"memory_id": memory_id, "title": title})
+    if bool(results) != (value["status"] == "found"):
         raise ValueError("inconsistent search results")
     paging = _paging_fields(value)
     if not results and paging["has_more"]:
@@ -953,11 +955,24 @@ def _write_message(output: TextIO, message: Mapping[str, Any]) -> bool:
     try:
         output.write(_json_text(message) + "\n")
         output.flush()
-    except (BrokenPipeError, OSError):
+    except (BrokenPipeError, OSError, UnicodeError):
         return False
     return True
 
 
+def _configure_stdio_utf8() -> None:
+    """Force the stdio protocol channel to UTF-8 on every supported platform."""
+
+    for stream in (sys.stdout, sys.stderr):
+        reconfigure = getattr(stream, "reconfigure", None)
+        if not callable(reconfigure):
+            continue
+        try:
+            reconfigure(encoding="utf-8", errors="strict")
+        except (OSError, ValueError):
+            continue
+
+
 def serve(service: Memleaf, *, input_stream: Any = None, output_stream: TextIO = sys.stdout) -> int:
     """Serve newline-delimited JSON-RPC messages until EOF or a broken pipe."""
 
@@ -992,6 +1007,7 @@ def _parser() -> argparse.ArgumentParser:
 
 
 def main(argv: list[str] | None = None) -> int:
+    _configure_stdio_utf8()
     args = _parser().parse_args(argv)
     vault = args.vault if args.vault is not None else os.environ.get("MEMLEAF_VAULT") or None
     try:

{memleaf-0.1.7 → memleaf-0.2.0}/src/memleaf/service.py

@@ -830,13 +830,13 @@ class Memleaf:
 
     @staticmethod
     def _candidate_directory(record: _Record) -> dict[str, Any]:
-        # Keep the exact memory id and scope IDs usable by the next search;
-        # only the human-facing title is shortened for a directory response.
+        # The finalized retrieval contract deliberately keeps candidate
+        # entries to memory_id + title. Scope selection already happened
+        # before search via the bounded Scope Map and search input.
         display = directory_entry(record.memory)
         return {
             "memory_id": record.memory.memory_id,
             "title": display.title,
-            "scopes": list(record.memory.scopes),
         }
 
     @staticmethod

{memleaf-0.1.7 → memleaf-0.2.0}/src/memleaf.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: memleaf
-Version: 0.1.7
+Version: 0.2.0
 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.1.7。**
-> 核心库、Vault、stdio MCP Server、初始化 CLI、模型路由、提炼流程、受控检索协议和宿主适配器已经实现。memleaf 0.1.7 通过 PyPI 分发。
+> **当前版本：0.2.0。**
+> 核心库、Vault、stdio MCP Server、初始化 CLI、模型路由、提炼流程、受控检索协议和宿主适配器已经实现。memleaf 0.2.0 通过 PyPI 分发。
 > **当前版本支持 Hermes 和 Codex。** Antigravity（反重力）不检测、不安装、不配置。
 
 ## 项目定位
@@ -65,7 +65,7 @@ memleaf 不会把整个 Vault 或整段历史对话自动塞进模型上下文
 
 1. Agent 使用当前完整会话和 Scope Map 选择检索范围与查询词；
 2. 至少调用一次 `search`；
-3. `search` 只返回候选的 `memory_id`、标题和 Scope，不直接返回正文；
+3. `search` 候选默认只返回 `memory_id` 和标题；Scope 已由 Scope Map 与本次搜索参数确定，不随每条候选重复返回，也不直接返回正文；
 4. 只有需要引用事实时，才使用同一轮返回的 `retrieval_id` 调用 `read`；
 5. 根据读取到的关键记忆回答，不把所有候选全部读完。
 
@@ -172,6 +172,14 @@ 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 运行：
+
+```bash
+python -m memleaf init --no-hermes --vault /path/to/the/same/vault
+```
+
+完成独立 Model Route 配置后，再使用 Codex 自动提炼。DeepSeek、OpenRouter 或其他自定义 Codex provider 因此保持原样。
+
 Antigravity（反重力）当前不支持，安装流程不会检测、安装或修改其配置。
 
 ### 高级初始化命令（可选）

{memleaf-0.1.7 → memleaf-0.2.0}/src/memleaf.egg-info/SOURCES.txt

@@ -63,8 +63,10 @@ src/memleaf/llm/router.py
 tests/__init__.py
 tests/test_admission_noise.py
 tests/test_codex_install.py
+tests/test_codex_native_cli.py
 tests/test_context_budget.py
 tests/test_credential_safety.py
+tests/test_cross_host_acceptance.py
 tests/test_hermes_provider.py
 tests/test_hermes_stdio_transport.py
 tests/test_host_events.py