memleaf 0.2.45__tar.gz → 0.2.47__tar.gz

{memleaf-0.2.45 → memleaf-0.2.47}/CHANGELOG.md

@@ -2,6 +2,23 @@
 
 All notable changes to memleaf are documented here.
 
+## 0.2.47 — 2026-09-12
+
+- Fix two satisfiability deadlocks in the public candidate filter that made every compound query carrying a punctuation-rich identifier return no_match. Word splitting turns `vX.Y.Z` into `vX` / `Y` / `Z`; those one-character fragments were collected as *required* ASCII components while the matching rule refused to treat anything shorter than three characters as a strong match, so the requirement could never be met. A fixed three-character bar had the same effect on a two-character CJK component whenever an ASCII component was present. A component that cannot reach its own bar no longer creates a requirement, and a CJK component's bar never exceeds its own length. Identifier strictness is unchanged: a short fragment still cannot stand in for a longer topic.
+- State the `sources` entry shape in the summarize contract instead of leaving the model to infer it, and generate that sentence from the validator's own field list so the instruction and the enforced shape cannot drift apart. Production `remember` calls writing a todo failed four times with `schema_violation` / `source_shape`: the prompt required `sources` and mentioned event keys but never described the object the validator accepts. A bare admitted event key is now additionally normalized to `{"event_key": ...}` losslessly, and `source_shape` gained a targeted repair instruction so the bounded retry corrects the shape instead of re-deriving the whole summary.
+- Make failed automatic extraction visible. `_state/processed.json` already recorded which sessions failed, at which stage and with which code, but nothing surfaced it: a Vault whose every turn failed extraction still looked idle from outside. `process_status` now accepts an omitted `job_id` and reports Vault-level extraction health — failed and running sessions, failure code and stage, and retryable turn counts. The report is strictly read-only and opens the Vault without creating it.
+- Report an incompatible model route instead of a misleading `ready`. The installer answered `processing_status: ready` for any configured route, including one whose adapter cannot speak the single-pass protocol. `install --host hermes` now distinguishes `ready`, `model_route_required` and `model_route_incompatible`. Capability is resolved through the same `ModelRouter` the extraction path uses, so the adapter decides and no rule is restated; no request is sent and no service is probed.
+- Document that the Claude and Gemini adapters implement no verified structured-output boundary, so the single-pass protocol stays fail-closed for them by design: a Vault routed through `llm.protocol: claude` cannot run automatic extraction, while capture, retrieval and explicit `remember`/`forget` are unaffected. Automatic extraction therefore requires an OpenAI-compatible route. No tool was added, removed or renamed; the public MCP surface remains the same 13 tools.
+
+Verification for this release used synthetic memories, temporary Vaults, synthetic routes and no model call: 51 focused tests cover the retrieval deadlocks and the strictness they preserve, the `sources` contract and its consistency with the validator, the targeted repair selection, the route capability decision across Claude, OpenAI/DeepSeek and unknown OpenAI-compatible routes, and the read-only processing-health report. Real-model first-pass success rate, repair success rate, reasoning reduction and latency improvement remain unmeasured, and the two reported production sessions were not replayed.
+
+## 0.2.46 — 2026-09-12
+
+- Restore the host protocol literals that v0.2.45 dropped from the API-route protocol table. `anthropic_messages`, `chat_completions`, `chat`, `google` and `generate_content` resolve again. v0.2.45 replaced the previous tolerant mapping with an exact table that omitted every canonical Hermes `api_mode` value, so a Hermes custom provider that used to resolve to a protocol began resolving to none and was reported as `missing provider, base URL, protocol, or model`. Substring and model-name matching stay removed: only exact host-contract literals are accepted, and an unknown protocol still fails closed.
+- Stop `memleaf install --host hermes` from aborting when model-route discovery finds nothing. Installation now continues and reports `processing_status: model_route_required` with an explicit user action, matching the Codex installer policy. Previously the install returned `stage: model_route` before touching the provider, which left the core package upgraded while the Hermes provider stayed on its previous version. The provider and MCP surface do not need a model route for capture or retrieval, so a missing route is a deferred configuration step rather than an installation failure.
+- Add `install --no-model-discovery` so an upgrade can skip host model discovery while still preserving an existing memleaf route, matching the `init` flag that already existed. Discovery remains enabled by default, so an installation that already succeeds is unaffected.
+- Verification for this release used synthetic Hermes-shaped routes, a temporary Vault and mocked host calls only: 18 focused tests cover the restored protocol literals, rejection of still-unknown protocols, discovery of a Hermes-shaped custom provider, the degraded-install decision, the new CLI flag, and an end-to-end assertion that `install_hermes` walks past a failed model route. No real provider call was made and no production Vault, Hermes configuration or session was read or written. A real Windows Hermes install and a real macOS Hermes install remain unverified by this release, and the manual model-route configuration step is still required on a host whose credentials the host CLI only reports masked.
+
 ## 0.2.45 — 2026-09-12
 
 - Repair the `b3-single-pass-v1` automatic extraction contract so model output is constrained by the same CREATE / UPDATE / NO_CHANGE / DEFERRED fields, evidence shapes, no-memory/defer reasons, target rules and lookup-completeness checks that Core validates. Pure ASCII decision-case differences are normalized locally; unknown decisions and missing semantic fields still fail closed.

{memleaf-0.2.45/src/memleaf.egg-info → memleaf-0.2.47}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: memleaf
-Version: 0.2.45
+Version: 0.2.47
 Summary: A local-first Markdown memory core for AI agents
 Author: memleaf contributors
 License-Expression: MIT
@@ -23,7 +23,7 @@ Dynamic: license-file
 
 [English](README.en.md) · [PyPI](https://pypi.org/project/memleaf/) · [GitHub](https://github.com/miffyblueboo/memleaf)
 
-> **版本：0.2.45。**
+> **版本：0.2.47。**
 > 记忆只从用户与 Agent 的可见对话提炼。Agent 已在回复中整理的事实、项目进展和明确待办可作为来源；邮件、附件、网页和终端等工具原文不进入记忆提炼。模型负责保留原话中的不确定性，现有记忆仅用于比较、去重和更新。Markdown 仍是唯一事实源。
 > **当前版本支持 Hermes 和 Codex。** Antigravity（反重力）不检测、不安装、不配置。
 

{memleaf-0.2.45 → memleaf-0.2.47}/README.en.md

@@ -4,7 +4,7 @@
 
 [中文](README.md) · [PyPI](https://pypi.org/project/memleaf/) · [GitHub](https://github.com/miffyblueboo/memleaf)
 
-> **Version: 0.2.45.**
+> **Version: 0.2.47.**
 > Automatic extraction now uses only the current turn's visible user input and final assistant reply. Raw tool output, attachments, web/file/terminal payloads and legacy tool-evidence bodies are not new source evidence; existing or retrieved memory remains comparison context rather than source authority. Background processing is persisted as a local job and can be checked through the read-only `process_status` MCP tool; failed work remains retryable and fail closed. The release also tightens source/date grounding, target reconciliation, duplicate/no-op handling and semantic review before writes. Markdown remains the sole source of truth with no SQLite runtime dependency. Acceptance covers deterministic regression suites and synthetic inputs; it does not claim real-mail or customer-business acceptance.
 > **The current release supports Hermes and Codex.** Antigravity is not detected, installed, or configured.
 

{memleaf-0.2.45 → memleaf-0.2.47}/README.md

@@ -4,7 +4,7 @@
 
 [English](README.en.md) · [PyPI](https://pypi.org/project/memleaf/) · [GitHub](https://github.com/miffyblueboo/memleaf)
 
-> **版本：0.2.45。**
+> **版本：0.2.47。**
 > 记忆只从用户与 Agent 的可见对话提炼。Agent 已在回复中整理的事实、项目进展和明确待办可作为来源；邮件、附件、网页和终端等工具原文不进入记忆提炼。模型负责保留原话中的不确定性，现有记忆仅用于比较、去重和更新。Markdown 仍是唯一事实源。
 > **当前版本支持 Hermes 和 Codex。** Antigravity（反重力）不检测、不安装、不配置。
 

{memleaf-0.2.45 → memleaf-0.2.47}/pyproject.toml

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

{memleaf-0.2.45 → memleaf-0.2.47}/src/memleaf/__init__.py

@@ -1,6 +1,6 @@
 """Local-first Markdown memory core for AI agents."""
 
-__version__ = "0.2.45"
+__version__ = "0.2.47"
 
 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.45 → memleaf-0.2.47}/src/memleaf/cli.py

@@ -77,6 +77,14 @@ def build_parser() -> argparse.ArgumentParser:
             "this installation (current), or retain a version-matched configured runtime (existing)"
         ),
     )
+    install.add_argument(
+        "--no-model-discovery",
+        action="store_true",
+        help=(
+            "Hermes only: skip host model discovery; an existing memleaf route is "
+            "still preserved and the install continues either way"
+        ),
+    )
     install.add_argument("--json", action="store_true", help="emit one JSON result")
     audit = commands.add_parser("audit", help="inspect an existing Vault without changing it")
     audit.add_argument("--vault", type=Path, default=None)
@@ -232,6 +240,8 @@ def main(argv: Sequence[str] | None = None) -> int:
                 install_kwargs = {"vault_path": args.vault}
                 if args.mcp_runtime != "auto":
                     install_kwargs["mcp_runtime"] = args.mcp_runtime
+                if args.no_model_discovery:
+                    install_kwargs["skip_model_discovery"] = True
                 output = install_hermes(**install_kwargs)
         elif args.command in {"audit", "process"}:
             from .inspection import audit_vault, existing_root, preview_process
@@ -302,8 +312,17 @@ def main(argv: Sequence[str] | None = None) -> int:
                 print("Restart Hermes to use memleaf.")
             elif output.get("user_action_required"):
                 print(f"Codex action required: {output.get('user_action')}")
-            if output.get("model", {}).get("status") == "not_configured":
-                print("Configure a memleaf model route before using automatic processing.")
+            processing = output.get("processing_status")
+            if processing == "model_route_required":
+                print(
+                    "Automatic memory extraction needs a memleaf model route before it can run. "
+                    "Set llm.provider/family/protocol/base_url/model/key in the Vault config.yaml, "
+                    "or rerun `memleaf init` from an interactive terminal."
+                )
+            elif processing == "model_route_incompatible":
+                print("Automatic memory extraction cannot run on this route.")
+                if output.get("user_action"):
+                    print(f"  {output['user_action']}")
         else:
             _print_install_failure(output, host=args.host)
         return 0 if output.get("status") in {"configured", "already_configured"} else 2

{memleaf-0.2.45 → memleaf-0.2.47}/src/memleaf/hermes_provider/plugin.yaml

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

{memleaf-0.2.45 → memleaf-0.2.47}/src/memleaf/installer.py

@@ -15,7 +15,7 @@ import subprocess
 import sys
 import sysconfig
 import tempfile
-from typing import Any
+from typing import Any, Mapping
 
 from . import __version__
 from .adapters.base import (
@@ -754,10 +754,72 @@ def _failure_result(
     return result
 
 
+_MODEL_ROUTE_REQUIRED_ACTION = (
+    "Configure an independent memleaf Model Route for this Vault before relying on "
+    "automatic memory extraction. Host model/provider settings are intentionally "
+    "not used or modified."
+)
+
+_MODEL_ROUTE_INCOMPATIBLE_ACTION = (
+    "This Vault's model route cannot run automatic memory extraction. The Claude and "
+    "Gemini adapters implement no verified structured-output boundary, so the "
+    "single-pass protocol stays fail-closed for them; v0.2.x automatic extraction "
+    "requires an OpenAI-compatible route (set llm.protocol to openai). Capture, "
+    "retrieval, and explicit remember/forget keep working unchanged."
+)
+
+
+def _route_can_extract(vault: Any) -> bool:
+    """Ask the production router whether this Vault's route can speak B3.
+
+    This deliberately reuses the same decision the extraction path makes instead
+    of restating the capability rules: the installer must never advertise
+    ``ready`` for a route whose adapter leaves ``single_pass_protocol`` False.
+    No request is sent and no service is probed.
+    """
+
+    try:
+        from .extraction_capability import supports_single_pass_protocol
+        from .llm import ModelRouter
+
+        router = ModelRouter.from_config(vault.config())
+    except Exception:
+        return False
+    try:
+        return bool(supports_single_pass_protocol(router))
+    except Exception:
+        return False
+
+
+def _model_route_outcome(
+    model: Any, *, can_extract: bool | None = None
+) -> tuple[bool, str, str | None]:
+    """Decide how one host installation reports its model route.
+
+    A missing model route must never block installing the host integration.
+    The provider/MCP surface still serves capture and retrieval without one,
+    so installation continues and reports ``model_route_required`` until a
+    route is configured.  This is the documented Codex policy, and applying it
+    to Hermes keeps the two hosts consistent instead of aborting the install
+    and leaving core and provider versions out of step.
+
+    ``can_extract`` carries the resolved capability of a *configured* route.  A
+    route can be present and still be unable to run automatic extraction, so
+    reporting plain ``ready`` for it would be a false promise.
+    """
+
+    if not (isinstance(model, Mapping) and model.get("status") in {"configured", "already_configured"}):
+        return False, "model_route_required", _MODEL_ROUTE_REQUIRED_ACTION
+    if can_extract is False:
+        return False, "model_route_incompatible", _MODEL_ROUTE_INCOMPATIBLE_ACTION
+    return True, "ready", None
+
+
 def install_hermes(
     *,
     vault_path: Path | None = None,
     mcp_runtime: str = "auto",
+    skip_model_discovery: bool = False,
 ) -> dict[str, Any]:
     """Install memleaf for Hermes with runtime preflight and host rollback.
 
@@ -870,18 +932,18 @@ def install_hermes(
         home=home,
         dry_run=False,
         non_interactive=not sys.stdin.isatty(),
-        skip_discovery=False,
+        skip_discovery=skip_model_discovery,
     )
-    if model.get("status") == "failure":
-        return _failure_result(
-            stage="model_route",
-            reason="model route is not configured",
-            core_version=core_version,
-            vault=vault.root,
-            vault_source=vault_source,
-            model=model,
-            mcp_runtime=runtime_details,
-        )
+    # A missing route degrades the installation instead of aborting it: the
+    # Hermes provider and MCP surface do not need a model route, and stopping
+    # here used to leave core and provider versions out of step.  A *present*
+    # route that cannot speak B3 is reported separately, because advertising
+    # ``ready`` for it would promise extraction that can never run.
+    model_ready, processing_status, model_action = _model_route_outcome(
+        model, can_extract=_route_can_extract(vault)
+    )
+    # ``model_ready`` is reported through ``processing_status`` below; the host
+    # integration itself is configured either way.
 
     provider_target = hermes_home / "plugins" / "memleaf"
     provider_config = hermes_home / "memleaf.json"
@@ -1079,6 +1141,9 @@ def install_hermes(
         "model": model,
         "native_sources": native_registration,
         "capture": capture_policy_status(vault.config()),
+        "processing_status": processing_status,
+        "user_action_required": bool(model_action),
+        "user_action": model_action,
     }
 
 

{memleaf-0.2.45 → memleaf-0.2.47}/src/memleaf/mcp_server.py

@@ -286,8 +286,14 @@ _TOOLS: tuple[dict[str, Any], ...] = (
     },
     {
         "name": "process_status",
-        "description": "Read the status of an accepted background process job.",
-        "inputSchema": _object_schema({"job_id": {"type": "string"}}, required=["job_id"]),
+        "description": (
+            "Read the status of an accepted background process job, or, when job_id is "
+            "omitted, the Vault's automatic-extraction health: failed and running "
+            "sessions, the failure code and stage, and whether the work is still "
+            "retryable. Failed extraction is never silent; check this when expected "
+            "memories do not appear."
+        ),
+        "inputSchema": _object_schema({"job_id": {"type": "string"}}),
     },
     {
         "name": "remember",
@@ -930,9 +936,15 @@ def _invoke_tool(
                 else:
                     value = service.process(**args)
         elif name == "process_status":
-            from .process_jobs import status
+            job_id = args.get("job_id")
+            if isinstance(job_id, str) and job_id:
+                from .process_jobs import status
+
+                value = status(service.vault.root, job_id=job_id)
+            else:
+                from .process_journal import processing_health
 
-            value = status(service.vault.root, job_id=args.get("job_id", ""))
+                value = processing_health(service.vault.root)
         elif name == "remember":
             value = service.remember(**args)
         elif name == "forget_memory":

{memleaf-0.2.45 → memleaf-0.2.47}/src/memleaf/model_capabilities.py

@@ -36,13 +36,23 @@ _LEGACY_PROVIDER_PROTOCOL = {
     "google": "gemini",
 }
 
+# Exact protocol identities, including the canonical ``api_mode`` literals a
+# Hermes configuration actually stores (``chat_completions`` and
+# ``anthropic_messages``).  These are host-contract literals, not fuzzy
+# guesses: substring and model-name matching stay removed so a custom alias can
+# never authorize a protocol it does not name.
 _PROTOCOL_ALIASES = {
     "openai": "openai",
     "openai-compatible": "openai",
     "openai_compatible": "openai",
+    "chat_completions": "openai",
+    "chat": "openai",
     "claude": "claude",
     "anthropic": "claude",
+    "anthropic_messages": "claude",
     "gemini": "gemini",
+    "google": "gemini",
+    "generate_content": "gemini",
 }
 
 

{memleaf-0.2.45 → memleaf-0.2.47}/src/memleaf/model_execution.py

@@ -9,7 +9,7 @@ from typing import Any, Callable, Mapping, Optional
 from .config import DEFAULT_MODEL_CONCURRENCY, MAX_MODEL_CONCURRENCY, MIN_MODEL_CONCURRENCY
 from .llm import MODEL_VALIDATION_REASONS, CallableBackend, ModelError, ModelUnavailable, ModelRouter
 from .models import utc_now
-from .prompts import COVERAGE_ALREADY_COMPLETED_CORRECTION, COVERAGE_CANDIDATE_CORRECTION, COVERAGE_CORRECTION, COVERAGE_SHAPE_CORRECTION, DUPLICATE_TARGET_CORRECTION, EVIDENCE_EVENT_MAPPING_CORRECTION, EVIDENCE_SPAN_CORRECTION, GATE_STRUCTURE_REPAIR_SYSTEM, GATE_TYPE_CORRECTION, JSON_CORRECTION, MIXED_FUTURE_USE_CORRECTION, MIXED_PROJECT_SCOPES_CORRECTION, RELATIVE_TIME_CORRECTION, SCOPE_GROUNDING_CORRECTION, SUMMARY_SCOPE_CORRECTION, SUMMARY_TARGET_CORRECTION, SUMMARY_TYPE_CORRECTION, TARGET_RELEVANCE_CORRECTION, UPDATE_TARGET_TYPE_CORRECTION, gate_structure_repair_prompt
+from .prompts import COVERAGE_ALREADY_COMPLETED_CORRECTION, COVERAGE_CANDIDATE_CORRECTION, COVERAGE_CORRECTION, COVERAGE_SHAPE_CORRECTION, DUPLICATE_TARGET_CORRECTION, EVIDENCE_EVENT_MAPPING_CORRECTION, EVIDENCE_SPAN_CORRECTION, GATE_STRUCTURE_REPAIR_SYSTEM, GATE_TYPE_CORRECTION, JSON_CORRECTION, MIXED_FUTURE_USE_CORRECTION, MIXED_PROJECT_SCOPES_CORRECTION, RELATIVE_TIME_CORRECTION, SCOPE_GROUNDING_CORRECTION, SOURCES_SHAPE_CORRECTION, SUMMARY_SCOPE_CORRECTION, SUMMARY_TARGET_CORRECTION, SUMMARY_TYPE_CORRECTION, TARGET_RELEVANCE_CORRECTION, UPDATE_TARGET_TYPE_CORRECTION, gate_structure_repair_prompt
 from .validation import MODEL_VALIDATION_DETAILS, ModelOutputError, parse_strict_json
 from .process_common import _DIAGNOSTIC_FILENAME, _DIAGNOSTIC_MAX_BYTES, _failure_metadata, _model_output_statistics, _safe_evidence_check, _safe_evidence_diagnostics
 
@@ -686,6 +686,8 @@ class ModelExecutor:
                 return COVERAGE_ALREADY_COMPLETED_CORRECTION
             context = ModelExecutor._evidence_correction_context(error)
             return COVERAGE_CORRECTION if context is None else COVERAGE_CORRECTION + "\n" + context
+        if stage == "summarize" and hint == "source_shape":
+            return SOURCES_SHAPE_CORRECTION
         if stage == "summarize" and hint == "scope_drift":
             return SUMMARY_SCOPE_CORRECTION
         if hint in {"relative_time", "due_date_not_grounded"}:

{memleaf-0.2.45 → memleaf-0.2.47}/src/memleaf/process_journal.py

@@ -16,14 +16,70 @@ from .inbox import InboxEvent, InboxTurn, parse_inbox
 from .locking import atomic_write_json, atomic_write_text
 from .turn_plan import turn_identity_key
 from .redaction import redact_text
-from .vault import safe_component
+from .vault import Vault, safe_component
 from .process_common import ProcessingError, _FAILED_STATUS, _LEGACY_PROCESSING_GRACE_SECONDS, _MAX_SESSION_LINEAGE_DEPTH, _PROCESSING_LEASE_SECONDS, _PROCESSING_STATUS, _Snapshot, _as_int, _event_payload, _failure_metadata, _now_value, _parse_time, _read_processed, _safe_evidence_check, _safe_evidence_diagnostics, _safe_scope_background, _session_key
 
 
+def processing_health(vault_path: Path | str) -> dict[str, Any]:
+    """Report whether automatic extraction is keeping up, and why not.
+
+    Strictly read-only: the Vault is opened without ``create`` and nothing is
+    written.  Failures were previously visible only inside
+    ``_state/processed.json``, so a Vault whose every turn failed extraction
+    still looked idle from the outside and the user had no way to notice.
+    """
+
+    vault = Vault(vault_path, create=False)
+    processed = _read_processed(vault.processed_state_path)
+    sessions = processed.get("sessions")
+    failures: list[dict[str, Any]] = []
+    running = 0
+    idle = 0
+    failed_turns = 0
+    last_processed: str | None = None
+    if isinstance(sessions, Mapping):
+        for key, state in sessions.items():
+            if not isinstance(state, Mapping):
+                continue
+            marker = state.get("processing")
+            marker = marker if isinstance(marker, Mapping) else {}
+            observed = marker.get("last_processed_at")
+            if isinstance(observed, str) and (last_processed is None or observed > last_processed):
+                last_processed = observed
+            status = marker.get("status")
+            if status == _FAILED_STATUS:
+                turn_indices = marker.get("turn_indices")
+                count = len(turn_indices) if isinstance(turn_indices, list) else 0
+                failed_turns += count
+                failures.append(
+                    {
+                        "session_id": key,
+                        "failure_code": marker.get("failure_code"),
+                        "failure_stage": marker.get("failure_stage"),
+                        "attempt_count": marker.get("attempt_count"),
+                        "turn_count": count,
+                    }
+                )
+            elif status == _PROCESSING_STATUS:
+                running += 1
+            else:
+                idle += 1
+    failures.sort(key=lambda item: str(item.get("session_id")))
+    return {
+        "status": "failed" if failures else ("running" if running else "idle"),
+        "failed_sessions": len(failures),
+        "failed_turns": failed_turns,
+        "running_sessions": running,
+        "idle_sessions": idle,
+        "last_processed_at": last_processed,
+        "retryable": bool(failures or running),
+        "failures": failures,
+    }
+
+
 class ProcessJournal:
     def __init__(self, service: Any):
         self.service = service
-
     def _write_processed_unlocked(self, processed: Mapping[str, Any]) -> None:
         atomic_write_json(self.service.vault.processed_state_path, dict(processed))
 

{memleaf-0.2.45 → memleaf-0.2.47}/src/memleaf/prompts.py

@@ -2,6 +2,27 @@
 
 from __future__ import annotations
 
+from .validation import SOURCE_FIELDS
+
+_SOURCE_FIELDS_TEXT = ", ".join(SOURCE_FIELDS)
+
+# The model is never asked to guess the ``sources`` entry shape: this sentence
+# is generated from the validator's own field list, so the instruction and the
+# enforced contract stay in step.
+_SOURCES_CONTRACT = (
+    "sources is a non-empty array of objects, never an array of bare strings. Each "
+    f"object may contain only these keys: {_SOURCE_FIELDS_TEXT}. Every value is a "
+    "string, except evidence_event_ids, which is a non-empty array of strings. Write "
+    '[{"event_key":"<admitted event key>"}], not ["<admitted event key>"]. Use only '
+    "event keys admitted for the current turn."
+)
+
+SOURCES_SHAPE_CORRECTION = (
+    "Previous output violated: source_shape. "
+    + _SOURCES_CONTRACT
+    + " Keep every other field of the summary unchanged."
+)
+
 
 GATE_SYSTEM = """You are memleaf's strict, source-neutral memory admission Gate. Return exactly one strict JSON object with top-level fields candidates, coverage, and evidence_bindings.
 
@@ -73,6 +94,9 @@ Semantic completeness is required: keep the smallest complete confirmed content
 OUTPUT CONTRACT
 A normal summary requires title, body, tags, type, scopes, and sources. Optional existing-schema fields are memory_id, update_memory_id, aliases, keywords, scope_source, evidence_event_ids, shadow_native_ids, scope_operations, status, completed_at, and due_date. Use only admitted current event keys in sources/evidence references. Copy the Gate candidate's type and scopes exactly; if scope_source is present, it must match the Gate value.
 
+SOURCES SHAPE
+""" + _SOURCES_CONTRACT + """
+
 TODO AND DATES
 Evidence events may include an ISO-8601 UTC timestamp. For a new todo, include status and due_date; use due_date=null when no deadline is established. For an updated todo, include current status. completed requires completed_at grounded in the admitted event timestamp. Do not invent dates. Preserve only date meaning supported by admitted Evidence; an admitted visible-message timestamp may anchor a supported relative date. Core normalizes supported relative calendar dates to YYYY-MM-DD and validates grounding; recurring schedules may remain recurring.
 

{memleaf-0.2.45 → memleaf-0.2.47}/src/memleaf/retrieval.py

@@ -26,6 +26,19 @@ def _is_cjk_char(value: str) -> bool:
     )
 
 
+def _cjk_span_bar(part: str) -> int:
+    """Return the contiguous-span bar for one CJK component.
+
+    The bar is a fraction of the component but never longer than the component
+    itself.  A two-character term could otherwise never reach it, which turned
+    every compound query carrying a short CJK word plus an ASCII token into an
+    unsatisfiable one: the compound branch requires a strong CJK match as soon
+    as an ASCII component is present.
+    """
+
+    return min(len(part), max(3, (len(part) * 35 + 99) // 100))
+
+
 def _query_parts(query: str | Iterable[str]) -> tuple[str, list[str], set[str]]:
     """Return the normalized query and its lexical components.
 
@@ -45,6 +58,13 @@ def _query_parts(query: str | Iterable[str]) -> tuple[str, list[str], set[str]]:
     for raw_part, part in zip(raw_parts, normalized_raw_parts):
         if any(_is_cjk_char(char) for char in part):
             continue
+        # Only a component that can satisfy the strong-match bar used below may
+        # become a *requirement*.  Splitting a punctuated identifier such as
+        # ``vX.Y.Z`` yields the one-character fragments ``Y`` and ``Z``; making
+        # those mandatory would demand a match that the same bar refuses to
+        # grant, so the compound query could never match anything at all.
+        if len(part) < 3 and not any(char.isdigit() for char in raw_part):
+            continue
         if any(char.isdigit() for char in raw_part) or raw_part.isalpha() and raw_part.isupper():
             explicit.add(part)
     # A trailing hyphen component is a common identifier form even when a
@@ -123,7 +143,7 @@ def candidate_matches_query(memory: Memory, query: str | Iterable[str]) -> bool:
             return True
         if not any(_is_cjk_char(char) for char in part):
             return False
-        minimum = max(3, (len(part) * 35 + 99) // 100)
+        minimum = _cjk_span_bar(part)
         return max((_longest_common_substring(part, value) for value in values), default=0) >= minimum
 
     has_cjk_part = any(any(_is_cjk_char(char) for char in part) for part in parts)
@@ -142,7 +162,7 @@ def candidate_matches_query(memory: Memory, query: str | Iterable[str]) -> bool:
     for part in parts:
         if any(_is_cjk_char(char) for char in part):
             longest = max((_longest_common_substring(part, value) for value in values), default=0)
-            minimum = max(3, (len(part) * 35 + 99) // 100)
+            minimum = _cjk_span_bar(part)
             if longest >= minimum:
                 strong_match = True
                 strong_cjk_match = True

{memleaf-0.2.45 → memleaf-0.2.47}/src/memleaf/validation.py

@@ -410,7 +410,11 @@ _RELATIVE_DAY_OFFSETS = {
     "昨天": -1,
     "昨日": -1,
 }
-_SOURCE_FIELDS = frozenset(("event_key", "session_id", "turn_id", "conversation_title", "evidence_event_ids"))
+# The single authority for the ``sources`` entry shape.  ``prompts.py`` builds
+# its output contract from this tuple, so the instruction the model receives and
+# the shape this validator enforces cannot drift apart the way the B3 protocol
+# string once did.
+SOURCE_FIELDS = ("event_key", "session_id", "turn_id", "conversation_title", "evidence_event_ids")
 _COMPACT_FIELDS = frozenset(
     (
         "title",
@@ -1274,9 +1278,22 @@ def _source_items(value: Any) -> list[dict[str, Any]]:
         raise ModelOutputError("sources must be a non-empty list", validation_detail="source_shape")
     result: list[dict[str, Any]] = []
     for source in value:
+        if isinstance(source, str):
+            # A bare admitted event key is unambiguous: under this contract a
+            # bare string cannot denote any other field.  Normalize it to the
+            # object form instead of failing the whole summary; the event-key
+            # authority check below still applies unchanged.
+            result.append(
+                {
+                    "event_key": _string(
+                        source, "source event_key", validation_detail="source_shape"
+                    )
+                }
+            )
+            continue
         if not isinstance(source, Mapping):
             raise ModelOutputError("each source must be an object", validation_detail="source_shape")
-        if set(source) - set(_SOURCE_FIELDS):
+        if set(source) - set(SOURCE_FIELDS):
             raise ModelOutputError("source contains unknown fields", validation_detail="unknown_fields")
         item = {}
         for key, child in source.items():

{memleaf-0.2.45 → memleaf-0.2.47/src/memleaf.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: memleaf
-Version: 0.2.45
+Version: 0.2.47
 Summary: A local-first Markdown memory core for AI agents
 Author: memleaf contributors
 License-Expression: MIT
@@ -23,7 +23,7 @@ Dynamic: license-file
 
 [English](README.en.md) · [PyPI](https://pypi.org/project/memleaf/) · [GitHub](https://github.com/miffyblueboo/memleaf)
 
-> **版本：0.2.45。**
+> **版本：0.2.47。**
 > 记忆只从用户与 Agent 的可见对话提炼。Agent 已在回复中整理的事实、项目进展和明确待办可作为来源；邮件、附件、网页和终端等工具原文不进入记忆提炼。模型负责保留原话中的不确定性，现有记忆仅用于比较、去重和更新。Markdown 仍是唯一事实源。
 > **当前版本支持 Hermes 和 Codex。** Antigravity（反重力）不检测、不安装、不配置。