memleaf 0.2.20__tar.gz → 0.2.21__tar.gz

{memleaf-0.2.20 → memleaf-0.2.21}/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 All notable changes to memleaf are documented here.
 
+## 0.2.21 — 2026-09-03
+
+- Fix `memleaf install` for Hermes after the 12th MCP tool was added: the installer now uses the adapter's canonical tool-count constant instead of a stale private `11`.
+- Add a regression invariant that compares the Hermes installer count with the actual public MCP tool tuple, preventing future tool additions from silently breaking installation self-checks.
+- Correct the English README's stale 11-tool and 3-memory/6000-character descriptions so the published documentation matches the v0.2 retrieval contract.
+
 ## 0.2.20 — 2026-09-03
 
 - Add `list_todos` for complete active todo retrieval across all scopes with stable pagination, date/status filtering, and current-turn retrieval gating.

{memleaf-0.2.20/src/memleaf.egg-info → memleaf-0.2.21}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: memleaf
-Version: 0.2.20
+Version: 0.2.21
 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.20。**
-> 核心库、Vault、stdio MCP Server、初始化 CLI、模型路由、提炼流程、受控检索协议和宿主适配器已经实现。memleaf 0.2.20 通过 PyPI 分发。
+> **当前版本：0.2.21。**
+> 核心库、Vault、stdio MCP Server、初始化 CLI、模型路由、提炼流程、受控检索协议和宿主适配器已经实现。memleaf 0.2.21 通过 PyPI 分发。
 > **当前版本支持 Hermes 和 Codex。** Antigravity（反重力）不检测、不安装、不配置。
 
 ## 项目定位

{memleaf-0.2.20 → memleaf-0.2.21}/README.en.md

@@ -4,8 +4,8 @@
 
 [中文](README.md) · [PyPI](https://pypi.org/project/memleaf/) · [GitHub](https://github.com/miffyblueboo/memleaf)
 
-> **Version: 0.2.20.**
-> The core library, Vault, stdio MCP server, initialization CLI, model routing, memory extraction, controlled retrieval protocol, and host adapters are implemented. memleaf 0.2.20 is distributed through PyPI.
+> **Version: 0.2.21.**
+> The core library, Vault, stdio MCP server, initialization CLI, model routing, memory extraction, controlled retrieval protocol, and host adapters are implemented. memleaf 0.2.21 is distributed through PyPI.
 > **The current release supports Hermes and Codex.** Antigravity is not detected, installed, or configured.
 
 ## Project scope
@@ -55,7 +55,7 @@ Current limits:
 - Scope Map: at most 20 items and approximately 2,000 characters per page;
 - search candidates: at most 20 items and approximately 4,000 characters per page;
 - one read page: at most 2,000 body characters;
-- managed turn: at most 3 distinct memory IDs and 6,000 body characters in total;
+- managed turn: all relevant memories may be read; `read_count` and `read_chars` are audit-only and do not block valid reads;
 - `retrieval_id` must belong to the current turn, and a successful `search` is required before `read`;
 - `found`, `no_match`, and tool errors are distinct states; an error must not be reported as no match;
 - `context()` and Python `search(view="full")` remain available for compatibility, but are not part of the automatic retrieval path.
@@ -141,12 +141,12 @@ Both installation paths automatically:
 4. Activate `memory.provider=memleaf`.
 5. Configure the memleaf MCP entry through Hermes' official CLI.
 6. Configure MCP lazy/idle lifecycle settings.
-7. Verify that the MCP server exposes all 11 tools.
+7. Verify that the MCP server exposes all 12 tools.
 8. Record the local Agent integration status.
 
 Restart Hermes after installation.
 
-If Hermes cannot be detected, no complete model route can be configured, Provider activation fails, or the 11-tool MCP verification fails, the installer returns an explicit failure rather than reporting an incomplete integration as successful.
+If Hermes cannot be detected, no complete model route can be configured, Provider activation fails, or the 12-tool MCP verification fails, the installer returns an explicit failure rather than reporting an incomplete integration as successful.
 
 The repository `install.sh` remains for source development, offline source installation, and troubleshooting. Normal PyPI users do not need to run it.
 
@@ -243,7 +243,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 currently exposes 11 tools:
+The server currently exposes 12 tools:
 
 | Tool | Purpose |
 | --- | --- |
@@ -251,6 +251,7 @@ The server currently exposes 11 tools:
 | `context` | Compatibility directory; not used by the automatic retrieval path |
 | `scope_catalog` | Return Scopes, parents, and aliases without memory bodies |
 | `search` | Return a bounded candidate directory and `found`/`no_match` status |
+| `list_todos` | Enumerate current todo memories across scopes with status/date filters and pagination |
 | `read` | Read a selected memory body in pages using the current `retrieval_id` |
 | `process` | Process complete inbox turns under the admission rules |
 | `remember` | Create or update memory after an explicit request |
@@ -259,7 +260,7 @@ The server currently exposes 11 tools:
 | `rebuild_index` | Rebuild local derived indexes |
 | `stats` | Return Vault counts and diagnostic statistics |
 
-Search results are clues; a title alone is not a business fact. Managed retrieval must use the same `retrieval_id` for `search → read`. Tool errors, Scope conflicts, and exhausted read budgets must be handled as such.
+Search results are clues; a title alone is not a business fact. Managed retrieval must use the same `retrieval_id` for `search → read`. Tool errors, Scope conflicts, retrieval-turn violations, and read page/version errors must be handled as such.
 
 ## Python API
 

{memleaf-0.2.20 → memleaf-0.2.21}/README.md

@@ -4,8 +4,8 @@
 
 [English](README.en.md) · [PyPI](https://pypi.org/project/memleaf/) · [GitHub](https://github.com/miffyblueboo/memleaf)
 
-> **当前版本：0.2.20。**
-> 核心库、Vault、stdio MCP Server、初始化 CLI、模型路由、提炼流程、受控检索协议和宿主适配器已经实现。memleaf 0.2.20 通过 PyPI 分发。
+> **当前版本：0.2.21。**
+> 核心库、Vault、stdio MCP Server、初始化 CLI、模型路由、提炼流程、受控检索协议和宿主适配器已经实现。memleaf 0.2.21 通过 PyPI 分发。
 > **当前版本支持 Hermes 和 Codex。** Antigravity（反重力）不检测、不安装、不配置。
 
 ## 项目定位

{memleaf-0.2.20 → memleaf-0.2.21}/pyproject.toml

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

{memleaf-0.2.20 → memleaf-0.2.21}/src/memleaf/__init__.py

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

@@ -24,7 +24,8 @@ from .base import (
 
 
 _MCP_IDLE_TIMEOUT_SECONDS = 60
-_MCP_EXPECTED_TOOL_COUNT = 12
+MCP_EXPECTED_TOOL_COUNT = 12
+_MCP_EXPECTED_TOOL_COUNT = MCP_EXPECTED_TOOL_COUNT
 
 
 def hermes_home_for_platform(
@@ -417,7 +418,7 @@ class HermesAdapter:
         self,
         detection: Detection | None = None,
         *,
-        expected_tools: int = _MCP_EXPECTED_TOOL_COUNT,
+        expected_tools: int = MCP_EXPECTED_TOOL_COUNT,
     ) -> bool:
         """Run the official MCP test and require the expected tool count."""
 

{memleaf-0.2.20 → memleaf-0.2.21}/src/memleaf/hermes_provider/plugin.yaml

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

{memleaf-0.2.20 → memleaf-0.2.21}/src/memleaf/installer.py

@@ -19,14 +19,17 @@ from typing import Any
 from . import __version__
 from .adapters.base import update_agents_index
 from .adapters.codex import CodexAdapter
-from .adapters.hermes import HermesAdapter, hermes_home_for_platform
+from .adapters.hermes import (
+    HermesAdapter,
+    MCP_EXPECTED_TOOL_COUNT,
+    hermes_home_for_platform,
+)
 from .cli import _home_from_environment, _prepare_model_route
 from .locking import atomic_write_json
 from .native_registration import ensure_hermes_native_sources
 from .vault import Vault
 
 
-_EXPECTED_TOOLS = 11
 _PROVIDER_VERSION_RE = re.compile(r"^version:\s*([^\s#]+)\s*(?:#.*)?$", re.MULTILINE)
 
 
@@ -401,14 +404,14 @@ def install_hermes(*, vault_path: Path | None = None) -> dict[str, Any]:
             "provider": str(provider_path),
             "model": model,
         }
-    if not adapter.test_mcp(detection, expected_tools=_EXPECTED_TOOLS):
+    if not adapter.test_mcp(detection, expected_tools=MCP_EXPECTED_TOOL_COUNT):
         update_agents_index(
             vault.agents_index_path,
             {"hermes": {"mcp_status": "failed", "mcp_availability": "unavailable"}},
         )
         return {
             "status": "failure",
-            "reason": "Hermes MCP test did not confirm 11 tools",
+            "reason": f"Hermes MCP test did not confirm {MCP_EXPECTED_TOOL_COUNT} tools",
             "core_version": core_version,
             "provider_version": provider_version,
             "vault": str(vault.root),

{memleaf-0.2.20 → memleaf-0.2.21/src/memleaf.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: memleaf
-Version: 0.2.20
+Version: 0.2.21
 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.20。**
-> 核心库、Vault、stdio MCP Server、初始化 CLI、模型路由、提炼流程、受控检索协议和宿主适配器已经实现。memleaf 0.2.20 通过 PyPI 分发。
+> **当前版本：0.2.21。**
+> 核心库、Vault、stdio MCP Server、初始化 CLI、模型路由、提炼流程、受控检索协议和宿主适配器已经实现。memleaf 0.2.21 通过 PyPI 分发。
 > **当前版本支持 Hermes 和 Codex。** Antigravity（反重力）不检测、不安装、不配置。
 
 ## 项目定位

{memleaf-0.2.20 → memleaf-0.2.21}/tests/test_pypi_install.py

@@ -8,7 +8,8 @@ import unittest
 from unittest import mock
 
 from memleaf import __version__, cli
-from memleaf.adapters.hermes import HermesAdapter
+from memleaf.adapters.hermes import HermesAdapter, MCP_EXPECTED_TOOL_COUNT
+from memleaf.mcp_server import _TOOLS
 from memleaf.installer import (
     _copy_provider,
     _hermes_home,
@@ -21,6 +22,12 @@ from memleaf.installer import (
 
 
 class PyPIInstallTests(unittest.TestCase):
+    def test_hermes_installer_tool_count_matches_public_mcp_contract(self) -> None:
+        from memleaf import installer
+
+        self.assertEqual(MCP_EXPECTED_TOOL_COUNT, len(_TOOLS))
+        self.assertEqual(installer.MCP_EXPECTED_TOOL_COUNT, len(_TOOLS))
+
     def test_packaged_provider_can_be_copied_without_importing_hermes(self) -> None:
         with tempfile.TemporaryDirectory(prefix="memleaf-pypi-provider-") as temporary:
             hermes_home = Path(temporary) / ".hermes"
@@ -81,7 +88,7 @@ class PyPIInstallTests(unittest.TestCase):
 
             self.assertTrue(target.is_dir())
             self.assertFalse(target.is_symlink())
-            self.assertIn("version: 0.2.20", (target / "plugin.yaml").read_text(encoding="utf-8"))
+            self.assertIn("version: 0.2.21", (target / "plugin.yaml").read_text(encoding="utf-8"))
 
     def test_windows_hermes_paths_follow_official_native_layout(self) -> None:
         with tempfile.TemporaryDirectory(prefix="memleaf-win-paths-") as temporary:

{memleaf-0.2.20 → memleaf-0.2.21}/tests/test_stage_c1_mcp.py

@@ -104,7 +104,7 @@ class StageC1MCPTest(unittest.TestCase):
         testcase.assertEqual(result["resultType"], "complete")
         testcase.assertEqual(
             result["_meta"]["io.modelcontextprotocol/serverInfo"],
-            {"name": "memleaf", "version": "0.2.20"},
+            {"name": "memleaf", "version": "0.2.21"},
         )
         return result
 

{memleaf-0.2.20 → memleaf-0.2.21}/tests/test_stage_c3_packaging.py

@@ -24,7 +24,7 @@ class StageC3PackagingTests(unittest.TestCase):
 
     def test_project_metadata_and_version_export(self) -> None:
         self.assertEqual(self.project["name"], "memleaf")
-        self.assertEqual(self.project["version"], "0.2.20")
+        self.assertEqual(self.project["version"], "0.2.21")
         self.assertEqual(self.project["requires-python"], ">=3.11")
         self.assertEqual(self.project["dependencies"], [])
         self.assertEqual(self.project["license"], "MIT")