memleaf 0.2.19__tar.gz → 0.2.20__tar.gz

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

@@ -2,6 +2,14 @@
 
 All notable changes to memleaf are documented here.
 
+## 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.
+- Remove the managed-turn 3-memory / 6000-character aggregate read block while retaining the 2000-character page limit and audit counters.
+- Add first-class `todo.due_date` (`YYYY-MM-DD`) with evidence-grounded date normalization, update/history/compaction propagation, and legacy Markdown compatibility.
+- Improve automatic extraction so concrete unfinished actions become atomic todos and durable rules remain project/fact memories; mixed rule/action candidates are split or safely deferred without blocking valid siblings.
+- Keep permanent `knowledge/` globally visible to all sessions and supported Agents sharing the same Vault; provenance fields never filter active memory visibility.
+
 ## 0.2.19 — 2026-09-03
 
 - Keep Hermes `<untrusted_tool_result>` search audit status synchronized with

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: memleaf
-Version: 0.2.19
+Version: 0.2.20
 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.19。**
-> 核心库、Vault、stdio MCP Server、初始化 CLI、模型路由、提炼流程、受控检索协议和宿主适配器已经实现。memleaf 0.2.19 通过 PyPI 分发。
+> **当前版本：0.2.20。**
+> 核心库、Vault、stdio MCP Server、初始化 CLI、模型路由、提炼流程、受控检索协议和宿主适配器已经实现。memleaf 0.2.20 通过 PyPI 分发。
 > **当前版本支持 Hermes 和 Codex。** Antigravity（反重力）不检测、不安装、不配置。
 
 ## 项目定位
@@ -69,12 +69,14 @@ memleaf 不会把整个 Vault 或整段历史对话自动塞进模型上下文
 4. 只有需要引用事实时，才使用同一轮返回的 `retrieval_id` 调用 `read`；
 5. 根据读取到的关键记忆回答，不把所有候选全部读完。
 
+当用户询问当前待办、所有未完成工作、紧急事项或某个日期范围内必须完成的事项时，使用 `list_todos`，默认覆盖所有 Scope；持续分页直到 `has_more=false`，再用同一个 `retrieval_id` 读取所有匹配待办正文。`source/session_id/turn_id` 只用于来源追踪，不参与永久 knowledge 可见性。
+
 当前限制：
 
 - Scope Map 最多 20 项、约 2000 字符；
 - search 候选单页最多 20 项、约 4000 字符；
 - read 单页正文最多 2000 字符；
-- 受管理轮次最多读取 3 个不同记忆、累计 6000 个正文字符；
+- 同一受管理轮次可继续读取所有与问题相关的记忆；`read_count`/`read_chars` 仅用于审计，不再作为阻断配额；
 - `retrieval_id` 必须属于当前轮次，且必须先有成功的 `search` 才能 `read`；
 - `found`、`no_match` 和工具错误是不同状态，错误不能被伪装成无匹配；
 - `context()` 和 Python `search(view="full")` 作为兼容接口保留，但不属于自动检索路径。
@@ -157,12 +159,12 @@ python -m pip install -U memleaf && python -m memleaf install
 4. 激活 `memory.provider=memleaf`；
 5. 通过 Hermes 官方 CLI 配置 memleaf MCP；
 6. 配置 MCP lazy/idle 生命周期；
-7. 验证 MCP Server 能发现 11 个工具；
+7. 验证 MCP Server 能发现 12 个工具；
 8. 写入本地 Agent 状态索引。
 
 完成后重启 Hermes。
 
-如果没有检测到 Hermes、无法取得完整模型路由、Provider 激活失败或 MCP 的 11 工具验证失败，安装会明确返回失败，不会把未完成的接入报告为成功。
+如果没有检测到 Hermes、无法取得完整模型路由、Provider 激活失败或 MCP 的 12 工具验证失败，安装会明确返回失败，不会把未完成的接入报告为成功。
 
 仓库中的 `install.sh` 保留给源码开发、离线源码安装和故障排查；普通 PyPI 用户不需要执行它。
 

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

@@ -4,8 +4,8 @@
 
 [中文](README.md) · [PyPI](https://pypi.org/project/memleaf/) · [GitHub](https://github.com/miffyblueboo/memleaf)
 
-> **Version: 0.2.19.**
-> The core library, Vault, stdio MCP server, initialization CLI, model routing, memory extraction, controlled retrieval protocol, and host adapters are implemented. memleaf 0.2.19 is distributed through PyPI.
+> **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.
 > **The current release supports Hermes and Codex.** Antigravity is not detected, installed, or configured.
 
 ## Project scope
@@ -80,6 +80,9 @@ Additional rules:
 - Model, parsing, write, or index failures keep the inbox and processing watermark retryable.
 - Automatic cleanup has a 24-hour safety period; a failed processing attempt does not delete the original capture.
 
+
+For current todos, all unfinished work, urgent items, or work due in a date range, use `list_todos`. It covers all scopes by default; continue until `has_more=false`, then read every matching todo body with the same `retrieval_id`. Provenance fields such as `source`, `session_id`, and `turn_id` never filter permanent knowledge visibility.
+
 ## 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.

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

@@ -4,8 +4,8 @@
 
 [English](README.en.md) · [PyPI](https://pypi.org/project/memleaf/) · [GitHub](https://github.com/miffyblueboo/memleaf)
 
-> **当前版本：0.2.19。**
-> 核心库、Vault、stdio MCP Server、初始化 CLI、模型路由、提炼流程、受控检索协议和宿主适配器已经实现。memleaf 0.2.19 通过 PyPI 分发。
+> **当前版本：0.2.20。**
+> 核心库、Vault、stdio MCP Server、初始化 CLI、模型路由、提炼流程、受控检索协议和宿主适配器已经实现。memleaf 0.2.20 通过 PyPI 分发。
 > **当前版本支持 Hermes 和 Codex。** Antigravity（反重力）不检测、不安装、不配置。
 
 ## 项目定位
@@ -50,12 +50,14 @@ memleaf 不会把整个 Vault 或整段历史对话自动塞进模型上下文
 4. 只有需要引用事实时，才使用同一轮返回的 `retrieval_id` 调用 `read`；
 5. 根据读取到的关键记忆回答，不把所有候选全部读完。
 
+当用户询问当前待办、所有未完成工作、紧急事项或某个日期范围内必须完成的事项时，使用 `list_todos`，默认覆盖所有 Scope；持续分页直到 `has_more=false`，再用同一个 `retrieval_id` 读取所有匹配待办正文。`source/session_id/turn_id` 只用于来源追踪，不参与永久 knowledge 可见性。
+
 当前限制：
 
 - Scope Map 最多 20 项、约 2000 字符；
 - search 候选单页最多 20 项、约 4000 字符；
 - read 单页正文最多 2000 字符；
-- 受管理轮次最多读取 3 个不同记忆、累计 6000 个正文字符；
+- 同一受管理轮次可继续读取所有与问题相关的记忆；`read_count`/`read_chars` 仅用于审计，不再作为阻断配额；
 - `retrieval_id` 必须属于当前轮次，且必须先有成功的 `search` 才能 `read`；
 - `found`、`no_match` 和工具错误是不同状态，错误不能被伪装成无匹配；
 - `context()` 和 Python `search(view="full")` 作为兼容接口保留，但不属于自动检索路径。
@@ -138,12 +140,12 @@ python -m pip install -U memleaf && python -m memleaf install
 4. 激活 `memory.provider=memleaf`；
 5. 通过 Hermes 官方 CLI 配置 memleaf MCP；
 6. 配置 MCP lazy/idle 生命周期；
-7. 验证 MCP Server 能发现 11 个工具；
+7. 验证 MCP Server 能发现 12 个工具；
 8. 写入本地 Agent 状态索引。
 
 完成后重启 Hermes。
 
-如果没有检测到 Hermes、无法取得完整模型路由、Provider 激活失败或 MCP 的 11 工具验证失败，安装会明确返回失败，不会把未完成的接入报告为成功。
+如果没有检测到 Hermes、无法取得完整模型路由、Provider 激活失败或 MCP 的 12 工具验证失败，安装会明确返回失败，不会把未完成的接入报告为成功。
 
 仓库中的 `install.sh` 保留给源码开发、离线源码安装和故障排查；普通 PyPI 用户不需要执行它。
 

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

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

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

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

@@ -24,7 +24,7 @@ from .base import (
 
 
 _MCP_IDLE_TIMEOUT_SECONDS = 60
-_MCP_EXPECTED_TOOL_COUNT = 11
+_MCP_EXPECTED_TOOL_COUNT = 12
 
 
 def hermes_home_for_platform(

{memleaf-0.2.19 → memleaf-0.2.20}/src/memleaf/compaction.py

@@ -40,6 +40,7 @@ def _content_mapping(value: Memory | Mapping[str, Any]) -> dict[str, Any]:
             "keywords": list(value.keywords),
             "status": value.status,
             "completed_at": value.completed_at,
+            "due_date": value.due_date,
         }
     if not isinstance(value, Mapping):
         raise ValueError("memory content must be a memory or mapping")
@@ -54,6 +55,7 @@ def _content_mapping(value: Memory | Mapping[str, Any]) -> dict[str, Any]:
         "keywords": list(value.get("keywords", [])),
         "status": value.get("status"),
         "completed_at": value.get("completed_at"),
+        "due_date": value.get("due_date"),
     }
 
 
@@ -423,6 +425,7 @@ class Compactor:
                     "keywords",
                     "status",
                     "completed_at",
+                    "due_date",
                 )
             },
         }
@@ -511,6 +514,7 @@ class Compactor:
             last_hit_at=self._last_hit(source_memories),
             status=status,
             completed_at=summary.get("completed_at"),
+            due_date=summary.get("due_date"),
             extra=extra,
         )
         raw = memory.to_markdown()
@@ -540,6 +544,7 @@ class Compactor:
             and left.sources == right.sources
             and left.status == right.status
             and left.completed_at == right.completed_at
+            and left.due_date == right.due_date
             and left_extra == right_extra
         )
 
@@ -591,6 +596,8 @@ class Compactor:
         replacements: list[_Replacement] = []
         for summary in output["memories"]:
             source_ids = tuple(summary["source_memory_ids"])
+            if summary.get("type") == "todo" and len(source_ids) != 1:
+                raise CompactionError("independent todos cannot be merged by compaction")
             try:
                 source_candidates = [by_id[source_id.casefold()] for source_id in source_ids]
             except KeyError as error:
@@ -638,6 +645,7 @@ class Compactor:
             last_hit_at=source.memory.last_hit_at,
             status=source.memory.status,
             completed_at=source.memory.completed_at,
+            due_date=source.memory.due_date,
             extra=extra,
         )
         return history_id, historical, historical.to_markdown()

{memleaf-0.2.19 → memleaf-0.2.20}/src/memleaf/hermes_provider/__init__.py

@@ -268,8 +268,9 @@ def _scope_context(
         "<memleaf-scope-map>\n"
         "Available memleaf memory scopes. For every visible user turn, call "
         "memleaf MCP search at least once using the current conversation and "
-        "this map. Search returns a directory; read only the selected memory "
-        "when needed. A no-match result is valid.\n"
+        "this map. Use list_todos instead of relevance search for global current-todo questions. "
+        "Search/list_todos return directories; read only the selected memory when needed for ordinary "
+        "relevance queries; for global todo queries, read every matching todo item. A no-match result is valid.\n"
     )
     if isinstance(retrieval_id, str) and retrieval_id:
         prefix = (
@@ -421,11 +422,12 @@ def _hermes_search_status(value: Any) -> str:
                 return "error"
             valid_results = all(
                 isinstance(item, Mapping)
-                and set(item) == {"memory_id", "title"}
+                and set(item) in ({"memory_id", "title"}, {"memory_id", "title", "due_date"})
                 and isinstance(item.get("memory_id"), str)
                 and bool(item.get("memory_id"))
                 and isinstance(item.get("title"), str)
                 and bool(item.get("title"))
+                and ("due_date" not in item or item.get("due_date") is None or isinstance(item.get("due_date"), str))
                 for item in results
             )
             if not valid_results:
@@ -1953,8 +1955,12 @@ class MemleafMemoryProvider(MemoryProvider):
             "read(memory_id, retrieval_id) when its body is needed, carrying the "
             "current turn's retrieval_id exactly as supplied; a missing or mismatched "
             "token is a read failure, never a reason to fall back to a file tool. "
-            "Read more only if needed, and do not read all entries to filter unrelated "
-            "items. Hermes has a soft "
+            "Read more only if needed; for ordinary relevance queries, do not read all entries to filter unrelated items. "
+            "When the user asks for current "
+            "todos, all unfinished work, urgent work, or work due in a time range, call memleaf MCP "
+            "list_todos instead of relevance search; omit scope for a global query, follow every "
+            "next_cursor until has_more=false, and read every matching todo body with the same retrieval_id. "
+            "Never exclude a todo because another Hermes session or another Agent created it. Hermes has a soft "
             "observer only: do not claim a search happened unless the visible tool "
             "messages show it. Visible Hermes "
             "turns are durably captured into the local memleaf inbox. Automatic "
@@ -2155,7 +2161,7 @@ class MemleafMemoryProvider(MemoryProvider):
         search_results_used: set[int] = set()
         search_ordinal = 0
         for call in calls:
-            if call.get("name") != "mcp__memleaf__search":
+            if call.get("name") not in {"mcp__memleaf__search", "mcp__memleaf__list_todos"}:
                 continue
             search_ordinal += 1
             arguments = call.get("arguments")

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

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

{memleaf-0.2.19 → memleaf-0.2.20}/src/memleaf/host_events.py

@@ -32,6 +32,7 @@ from .retrieval_gate import (
     find_pending_continuation,
     mark_degraded,
     observe_search,
+    todo_filter_key,
     request_gate_retry,
     validate_turn,
 )
@@ -306,7 +307,11 @@ def _handle_codex_pre_tool(
     turn_id: str | None,
 ) -> dict[str, Any]:
     tool_name = _field(event, "tool_name", "toolName")
-    if not (_codex_memleaf_tool(tool_name, "search") or _codex_memleaf_tool(tool_name, "read")):
+    if not (
+        _codex_memleaf_tool(tool_name, "search")
+        or _codex_memleaf_tool(tool_name, "list_todos")
+        or _codex_memleaf_tool(tool_name, "read")
+    ):
         return {}
     if session_id is None or turn_id is None:
         return {}
@@ -385,26 +390,70 @@ def _codex_search_status(value: Any) -> str:
     return "error"
 
 
+
+def _codex_todo_result(value: Any) -> tuple[str, bool, str | None]:
+    result = _json_tool_result(value)
+    if not isinstance(result, Mapping) or result.get("isError") is True or "error" in result:
+        return "error", False, None
+    status = result.get("status")
+    items = result.get("results")
+    has_more = result.get("has_more")
+    next_cursor = result.get("next_cursor")
+    if status not in {"found", "no_match"} or not isinstance(items, list) or not isinstance(has_more, bool):
+        return "error", False, None
+    if not all(
+        isinstance(item, Mapping)
+        and set(item) == {"memory_id", "title", "due_date"}
+        and isinstance(item.get("memory_id"), str) and bool(item.get("memory_id"))
+        and isinstance(item.get("title"), str) and bool(item.get("title"))
+        and (item.get("due_date") is None or isinstance(item.get("due_date"), str))
+        for item in items
+    ):
+        return "error", False, None
+    if (has_more and not isinstance(next_cursor, str)) or (not has_more and next_cursor is not None):
+        return "error", False, None
+    if status == "found" and not items:
+        return "error", False, None
+    if status == "no_match" and items:
+        return "error", False, None
+    return status, has_more, next_cursor if isinstance(next_cursor, str) else None
+
+
 def _handle_codex_post_tool(
     runtime: HostRuntime,
     event: Mapping[str, Any],
     session_id: str | None,
     turn_id: str | None,
 ) -> dict[str, Any]:
-    if not _codex_memleaf_tool(_field(event, "tool_name", "toolName"), "search"):
-        return {}
-    if session_id is None or turn_id is None:
+    tool_name = _field(event, "tool_name", "toolName")
+    is_search = _codex_memleaf_tool(tool_name, "search")
+    is_todos = _codex_memleaf_tool(tool_name, "list_todos")
+    if not (is_search or is_todos) or session_id is None or turn_id is None:
         return {}
     tool_input = _field(event, "tool_input", "toolInput")
     call_id = _field(event, "tool_use_id", "toolUseId")
     if not isinstance(tool_input, Mapping) or not isinstance(call_id, str):
         return {}
-    runtime.observe_search(
+    if is_search:
+        runtime.observe_search(
+            session_id=session_id,
+            turn_id=turn_id,
+            status=_codex_search_status(_field(event, "tool_response", "toolResponse")),
+            call_id=call_id,
+            supplied_retrieval_id=tool_input.get("retrieval_id"),
+        )
+        return {}
+    status, has_more, next_cursor = _codex_todo_result(_field(event, "tool_response", "toolResponse"))
+    runtime.observe_todo_list(
         session_id=session_id,
         turn_id=turn_id,
-        status=_codex_search_status(_field(event, "tool_response", "toolResponse")),
+        status=status,
         call_id=call_id,
         supplied_retrieval_id=tool_input.get("retrieval_id"),
+        filter_key=todo_filter_key(tool_input),
+        cursor=tool_input.get("cursor") if isinstance(tool_input.get("cursor"), str) else None,
+        has_more=has_more,
+        next_cursor=next_cursor,
     )
     return {}
 

{memleaf-0.2.19 → memleaf-0.2.20}/src/memleaf/host_runtime.py

@@ -28,6 +28,7 @@ from .retrieval_gate import (
     find_turn,
     mark_degraded,
     observe_search,
+    observe_todo_list,
     request_gate_retry,
     validate_turn,
 )
@@ -40,9 +41,13 @@ _GATE_RETRY_REASON = (
     "a no-match result is acceptable."
 )
 _GATE_ERROR_REASON = (
-    "The memleaf search did not complete. Retry the memleaf search once before "
+    "The memleaf retrieval did not complete. Retry the memleaf memory tool once before "
     "answering; do not treat this error as no match."
 )
+_TODO_PAGINATION_REASON = (
+    "The global todo directory is incomplete. Continue memleaf list_todos with the returned "
+    "next_cursor until has_more=false before answering."
+)
 
 
 @dataclass(frozen=True)
@@ -250,6 +255,38 @@ class HostRuntime:
             return False
         return True
 
+    def observe_todo_list(
+        self,
+        *,
+        session_id: str,
+        turn_id: str,
+        status: str,
+        call_id: str,
+        supplied_retrieval_id: Any,
+        filter_key: str,
+        cursor: str | None,
+        has_more: bool,
+        next_cursor: str | None,
+    ) -> bool:
+        retrieval_id = self._retrieval_id(session_id, turn_id)
+        if retrieval_id is None or supplied_retrieval_id != retrieval_id or not isinstance(call_id, str) or not call_id:
+            return False
+        try:
+            observe_todo_list(
+                self.vault,
+                retrieval_id,
+                status,
+                call_id,
+                filter_key=filter_key,
+                cursor=cursor,
+                has_more=has_more,
+                next_cursor=next_cursor,
+                current_source=self.host,
+            )
+        except RetrievalGateError:
+            return False
+        return True
+
     def complete_turn(
         self,
         *,
@@ -277,7 +314,8 @@ class HostRuntime:
                 if gate_state.get("status") == "DEGRADED":
                     degraded = True
 
-            if gate_state is not None and gate_state.get("status") in {"NOT_SEARCHED", "ERROR"}:
+            todo_pending = gate_state is not None and gate_state.get("todo_list_pending") is True
+            if gate_state is not None and (gate_state.get("status") in {"NOT_SEARCHED", "ERROR"} or todo_pending):
                 retries = int(gate_state.get("gate_retries", 0) or 0)
                 if retries < MAX_GATE_RETRIES:
                     try:
@@ -286,7 +324,9 @@ class HostRuntime:
                         pass
                     else:
                         reason = (
-                            _GATE_ERROR_REASON
+                            _TODO_PAGINATION_REASON
+                            if todo_pending
+                            else _GATE_ERROR_REASON
                             if gate_state.get("status") == "ERROR"
                             else _GATE_RETRY_REASON
                         )

{memleaf-0.2.19 → memleaf-0.2.20}/src/memleaf/mcp_server.py

@@ -28,6 +28,8 @@ from .retrieval_gate import (
     begin_turn,
     guarded_read,
     observe_search,
+    observe_todo_list,
+    todo_filter_key,
     validate_current_turn,
     validate_turn,
 )
@@ -60,10 +62,11 @@ INSTRUCTIONS = (
     "Use read(memory_id) on the best matching entry before relying on a past fact. Read more only "
     "when needed, not every entry to filter unrelated items. You may refine the query/scope and "
     "search again. Pass the host-provided retrieval_id to search and read; never invent or replace "
-    "it to reset a budget. Managed turns permit at most 3 distinct memory IDs and 6000 returned body "
-    "characters. MCP read requires retrieval_id and a current FOUND search; NO_MATCH, ERROR, "
-    "and DEGRADED turns cannot read. A budget error requires stopping further reads in this turn, "
-    "not a different tool. "
+    "it. Managed reads have no aggregate ID/character quota; read every relevant memory needed for "
+    "the user's question while keeping each read page at 2000 characters. MCP read requires retrieval_id "
+    "and a current FOUND search or list_todos result; NO_MATCH, ERROR, and DEGRADED turns cannot read. "
+    "For global current-todo questions use list_todos rather than relevance search, omit scope to cover "
+    "all scopes, follow next_cursor until has_more=false, then read every matching todo body. "
     "Legacy context is an explicit compatibility interface, not an alternative to this "
     "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; "
@@ -205,6 +208,28 @@ _TOOLS: tuple[dict[str, Any], ...] = (
             required=["query", "retrieval_id"],
         ),
     },
+    {
+        "name": "list_todos",
+        "description": (
+            "Enumerate current memleaf todo memories by status/date across all scopes by default. "
+            "This is not relevance search. Continue with next_cursor until has_more=false, then read "
+            "the matching todo bodies with the same retrieval_id."
+        ),
+        "inputSchema": _object_schema(
+            {
+                "status": {"type": "string", "enum": ["active", "completed", "cancelled", "all"]},
+                "scope": _text_or_texts_schema(),
+                "due_from": {"type": "string"},
+                "due_to": {"type": "string"},
+                "include_overdue": {"type": "boolean"},
+                "include_unscheduled": {"type": "boolean"},
+                "cursor": {"type": "string"},
+                "limit": {"type": "integer", "minimum": 1},
+                "retrieval_id": {"type": "string"},
+            },
+            required=["retrieval_id"],
+        ),
+    },
     {
         "name": "read",
         "description": (
@@ -439,7 +464,23 @@ def _read_page_result(value: Any) -> dict[str, Any] | None:
             raise ValueError("invalid read continuation")
     elif value["next_offset"] is not None or end != value["total_chars"]:
         raise ValueError("invalid read final page")
-    return {name: _jsonable(value[name]) for name in fields if name in value}
+    result = {name: _jsonable(value[name]) for name in fields if name in value}
+    memory_type = value.get("type")
+    status = value.get("status")
+    due_date = value.get("due_date")
+    if memory_type is not None and not isinstance(memory_type, str):
+        raise ValueError("invalid read memory type")
+    if status is not None and not isinstance(status, str):
+        raise ValueError("invalid read todo status")
+    if due_date is not None and not isinstance(due_date, str):
+        raise ValueError("invalid read todo due date")
+    if "type" in value:
+        result["type"] = memory_type
+    if "status" in value:
+        result["status"] = status
+    if "due_date" in value:
+        result["due_date"] = due_date
+    return result
 
 
 def _catalog_result(value: Any) -> dict[str, Any]:
@@ -703,6 +744,34 @@ def _observe_mcp_search(
     )
 
 
+
+def _observe_mcp_todos(
+    service: Memleaf,
+    state: Mapping[str, Any] | None,
+    value: Mapping[str, Any] | None,
+    request_id: Any,
+    arguments: Mapping[str, Any],
+) -> None:
+    if state is None:
+        return
+    status = value.get("status") if isinstance(value, Mapping) else "error"
+    if status not in {"found", "no_match"}:
+        status = "error"
+    has_more = value.get("has_more") if isinstance(value, Mapping) else False
+    next_cursor = value.get("next_cursor") if isinstance(value, Mapping) else None
+    observe_todo_list(
+        service.vault,
+        state["retrieval_id"],
+        status,
+        _mcp_search_call_id(request_id),
+        filter_key=todo_filter_key(arguments),
+        cursor=arguments.get("cursor") if isinstance(arguments.get("cursor"), str) else None,
+        has_more=has_more if isinstance(has_more, bool) else False,
+        next_cursor=next_cursor if isinstance(next_cursor, str) else None,
+        current_source="hermes",
+    )
+
+
 def _invoke_tool(
     service: Memleaf,
     name: str,
@@ -712,7 +781,7 @@ def _invoke_tool(
 ) -> dict[str, Any]:
     if name not in _TOOL_BY_NAME:
         raise _InvalidParams
-    if name in {"read", "search"} and (
+    if name in {"read", "search", "list_todos"} and (
         not isinstance(arguments, dict) or "retrieval_id" not in arguments
     ):
         return _tool_error(RetrievalGateError("retrieval_id_required"))
@@ -773,6 +842,22 @@ def _invoke_tool(
             except Exception as error:
                 # A managed result is not successful until the gate records it.
                 return _tool_error(error)
+        elif name == "list_todos":
+            retrieval_id = args.pop("retrieval_id", None)
+            managed_state = _managed_search_state(service, retrieval_id)
+            observed_args = dict(args)
+            try:
+                value = service.list_todos(**args)
+            except Exception as error:
+                try:
+                    _observe_mcp_todos(service, managed_state, None, request_id, observed_args)
+                except Exception as observe_error:
+                    return _tool_error(observe_error)
+                return _tool_error(error)
+            try:
+                _observe_mcp_todos(service, managed_state, value, request_id, observed_args)
+            except Exception as error:
+                return _tool_error(error)
         elif name == "read":
             # Keep the protocol boundary hard-capped even if a caller sends a
             # larger value.  Core read_page performs the same authoritative

{memleaf-0.2.19 → memleaf-0.2.20}/src/memleaf/memory_writer.py

@@ -82,6 +82,7 @@ class MemoryWriter:
             and (ignore_sources or left.sources == right.sources)
             and left.status == right.status
             and left.completed_at == right.completed_at
+            and left.due_date == right.due_date
             and left_extra == right_extra
         )
 
@@ -263,9 +264,15 @@ class MemoryWriter:
         summary = request["summary"]
         memory_id = existing.memory_id if existing is not None else request["memory_id"]
         created = existing.created if existing is not None else now
-        status = summary.get("status")
+        status = summary.get("status") if "status" in summary else (existing.status if existing is not None else None)
         if summary["type"] == "todo" and status is None:
             status = "active"
+        due_date = summary.get("due_date") if "due_date" in summary else (existing.due_date if existing is not None else None)
+        completed_at = (
+            summary.get("completed_at")
+            if "completed_at" in summary
+            else existing.completed_at if existing is not None and status == "completed" else None
+        )
         extra = dict(existing.extra) if existing is not None else {}
         extra["source"] = request["turn"].source
         if request.get("explicit_remember") is True:
@@ -287,7 +294,8 @@ class MemoryWriter:
             hit_count=existing.hit_count if existing is not None else 0,
             last_hit_at=existing.last_hit_at if existing is not None else None,
             status=status,
-            completed_at=summary.get("completed_at"),
+            completed_at=completed_at,
+            due_date=due_date,
             extra=extra,
         )
 
@@ -315,6 +323,7 @@ class MemoryWriter:
             last_hit_at=existing.last_hit_at,
             status=existing.status,
             completed_at=existing.completed_at,
+            due_date=existing.due_date,
             extra=dict(existing.extra),
         )
 
@@ -356,6 +365,7 @@ class MemoryWriter:
             last_hit_at=old.last_hit_at,
             status=old.status,
             completed_at=old.completed_at,
+            due_date=old.due_date,
             extra=extra,
         )
         path = self.service.vault.memory_path(history_id, "history")