memleaf 0.2.41__tar.gz → 0.2.42__tar.gz

{memleaf-0.2.41 → memleaf-0.2.42}/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 All notable changes to memleaf are documented here.
 
+## 0.2.42 — 2026-09-12
+
+- Rework ordinary automatic extraction around the unified `b3-single-pass-v1` planner. The current visible user/assistant turn is the only new-fact evidence; existing local/native memories remain comparison context. One structured model stage decides CREATE / UPDATE / NO_CHANGE / DEFERRED, with deterministic Core validation and at most one bounded format/structure repair.
+- Make the latency-critical `single_pass` stage non-thinking by default and use bounded structured output for supported OpenAI-compatible routes. Fixed safe API routes enforce a six-second primary request cap, an eight-second preparation-plus-model window, a ten-second total turn deadline, and rejection of late results before commit; no unmeasured P50/P95 claim is made.
+- Persist background extraction request/time budgets by process-job and turn identity so worker restarts cannot regain consumed attempts or wall time. Damaged budget/job state, invalid ownership/order, and wall-clock rollback fail closed instead of reopening a fresh extraction budget.
+- Commit automatic processing one complete turn at a time and re-read durable Markdown/journal state before planning the next turn. Frozen-turn recovery preserves already committed work without replaying model calls/history, while one process invocation drains at most four claimed turns and exposes the remaining backlog explicitly.
+- Move compaction/maintenance out of the `process()` / `remember()` extraction critical path, keep explicit no-write instructions as deterministic zero-model-call settlements, and retain structural-only model telemetry without prompt/response bodies or credentials.
+- Separate B3 protocol compatibility from strict transport deadline safety. Host/Python callbacks can use the same B3 semantic protocol without falsely claiming hard cancellation; mixed auto routes remain fail-closed, `single_pass` forbids hidden host-to-API fallback, and explicit `remember()` keeps its existing bounded validator retry semantics.
+- Preserve the product architecture: Markdown under `knowledge/` remains the active source of truth, `history/` remains historical state, permanent memory stays globally shared across agents using the same Vault, and no database, Redis, vector service, resident daemon, or local-model dependency is introduced. The release candidate passed Linux Python 3.11/3.12/3.13, Windows Python 3.11/3.12/3.13, macOS Python 3.11/3.13, native Codex Windows/macOS, wheel/sdist, installed-entry-point, and full unittest CI; real-model quality/latency acceptance remains a separate user-run step.
+
 ## 0.2.41 — 2026-09-11
 
 - Promote the B3 single-pass automatic memory planner for explicitly `single_pass_safe` API backends. Core prepares bounded local retrieval/context once, one semantic planner stage decides CREATE / UPDATE / NO_CHANGE / DEFERRED, deterministic validation remains authoritative, and model-output repair is bounded to at most one retry (`max_attempts=2`). Host/custom/host-backed providers keep the proven P3 fallback, while explicit `remember` retains its existing single-summary path.

{memleaf-0.2.41/src/memleaf.egg-info → memleaf-0.2.42}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: memleaf
-Version: 0.2.41
+Version: 0.2.42
 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.41。**
+> **版本：0.2.42。**
 > 记忆只从用户与 Agent 的可见对话提炼。Agent 已在回复中整理的事实、项目进展和明确待办可作为来源；邮件、附件、网页和终端等工具原文不进入记忆提炼。模型负责保留原话中的不确定性，现有记忆仅用于比较、去重和更新。Markdown 仍是唯一事实源。
 > **当前版本支持 Hermes 和 Codex。** Antigravity（反重力）不检测、不安装、不配置。
 

{memleaf-0.2.41 → memleaf-0.2.42}/README.en.md

@@ -4,7 +4,7 @@
 
 [中文](README.md) · [PyPI](https://pypi.org/project/memleaf/) · [GitHub](https://github.com/miffyblueboo/memleaf)
 
-> **Version: 0.2.41.**
+> **Version: 0.2.42.**
 > 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.41 → memleaf-0.2.42}/README.md

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

{memleaf-0.2.41 → memleaf-0.2.42}/pyproject.toml

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

{memleaf-0.2.41 → memleaf-0.2.42}/src/memleaf/__init__.py

@@ -1,6 +1,6 @@
 """Local-first Markdown memory core for AI agents."""
 
-__version__ = "0.2.41"
+__version__ = "0.2.42"
 
 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.41 → memleaf-0.2.42}/src/memleaf/config.py

@@ -19,9 +19,13 @@ MAX_REQUEST_TIMEOUT = 240
 DEFAULT_MODEL_CONCURRENCY = 3
 MIN_MODEL_CONCURRENCY = 1
 MAX_MODEL_CONCURRENCY = 8
-THINKING_PURPOSES = ("gate", "summarize", "compact")
+THINKING_PURPOSES = ("gate", "summarize", "compact", "single_pass")
 THINKING_MODES = frozenset({"default", "disabled", "low", "high", "max"})
 DEFAULT_THINKING = {purpose: "low" for purpose in THINKING_PURPOSES}
+# Unified extraction is latency-sensitive and keeps deterministic validation in
+# Core.  Make the single-pass path non-thinking by default without changing
+# the established policy for maintenance/legacy stages.
+DEFAULT_THINKING["single_pass"] = "disabled"
 
 
 def _normalize_request_timeout(value: Any) -> int | float:

memleaf-0.2.42/src/memleaf/extraction_budget.py

@@ -0,0 +1,280 @@
+"""Latency and outbound-request budget for unified memory extraction.
+
+The budget is deliberately attached to one logical single-pass turn instead
+of to an HTTP adapter.  That keeps the product invariants (at most two actual
+model requests and a bounded end-to-end turn) independent from provider-
+specific prompt/transport details.
+"""
+from __future__ import annotations
+
+import math
+import time
+from collections.abc import Callable
+from typing import Any, Mapping
+
+from .llm import ModelError
+
+
+MAX_MODEL_REQUESTS = 2
+TARGET_TOTAL_SECONDS = 10.0
+MODEL_TIME_BUDGET_SECONDS = 8.0
+PRIMARY_REQUEST_MAX_SECONDS = 6.0
+
+
+class SinglePassBudgetBackend:
+    """Wrap one safe backend with the extraction request/time budget.
+
+    ``single_pass_safe`` routes are already constrained so one ``complete()``
+    maps to one provider request (no host->API fallback).  The wrapper
+    therefore makes the two-call limit a true outbound-request limit for the
+    production B3 route, not merely a parser-attempt count.
+
+    ``deadline`` is absolute in the supplied monotonic clock.  Supplying it is
+    what lets preparation time consume the same turn budget instead of
+    starting a fresh eight-second clock only when the HTTP call begins.
+
+    ``reserve_request`` optionally persists the request ordinal before the
+    outbound call.  Background workers use it so a process restart cannot
+    reopen attempts already consumed by the same durable work item.
+    """
+
+    single_pass_safe = True
+
+    def __init__(
+        self,
+        backend: Any,
+        *,
+        clock: Any = time.monotonic,
+        deadline: float | None = None,
+        reserve_request: Callable[[], int | None] | None = None,
+    ):
+        if not hasattr(backend, "complete"):
+            raise TypeError("single-pass backend must expose complete()")
+        if reserve_request is not None and not callable(reserve_request):
+            raise TypeError("reserve_request must be callable")
+        self._backend = backend
+        self._clock = clock
+        self._started = float(clock())
+        self._deadline = (
+            self._started + MODEL_TIME_BUDGET_SECONDS
+            if deadline is None
+            else float(deadline)
+        )
+        self._requests = 0
+        self._reserve_request = reserve_request
+
+    @property
+    def provider(self) -> str:
+        return str(getattr(self._backend, "provider", "unknown"))
+
+    @property
+    def model(self) -> str:
+        return str(getattr(self._backend, "model", "unknown"))
+
+    @property
+    def parallel_safe(self) -> bool:
+        return getattr(self._backend, "parallel_safe", False) is True
+
+    @property
+    def structured_batch_safe(self) -> bool:
+        return getattr(self._backend, "structured_batch_safe", False) is True
+
+    @property
+    def request_count(self) -> int:
+        return self._requests
+
+    def _remaining(self) -> float:
+        return self._deadline - float(self._clock())
+
+    def _request_ordinal(self, *, purpose: str) -> int:
+        if self._requests >= MAX_MODEL_REQUESTS:
+            raise ModelError(
+                "single-pass extraction budget exhausted",
+                code="model_timeout",
+                stage=purpose or "single_pass",
+            )
+        if self._reserve_request is None:
+            return self._requests + 1
+        try:
+            ordinal = self._reserve_request()
+        except Exception as error:
+            raise ModelError(
+                "single-pass extraction request budget cannot be reserved",
+                code="model_timeout",
+                stage=purpose or "single_pass",
+            ) from error
+        if type(ordinal) is not int or not 1 <= ordinal <= MAX_MODEL_REQUESTS:
+            raise ModelError(
+                "single-pass extraction budget exhausted",
+                code="model_timeout",
+                stage=purpose or "single_pass",
+            )
+        return ordinal
+
+    def complete(
+        self,
+        prompt: str,
+        *,
+        system: str = "",
+        purpose: str = "",
+        temperature: float = 0.0,
+    ) -> str:
+        remaining = self._remaining()
+        if remaining <= 0:
+            raise ModelError(
+                "single-pass extraction budget exhausted",
+                code="model_timeout",
+                stage=purpose or "single_pass",
+            )
+        ordinal = self._request_ordinal(purpose=purpose)
+        cap = min(
+            PRIMARY_REQUEST_MAX_SECONDS if ordinal == 1 else remaining,
+            remaining,
+        )
+        if cap <= 0:
+            raise ModelError(
+                "single-pass extraction budget exhausted",
+                code="model_timeout",
+                stage=purpose or "single_pass",
+            )
+        # Count locally only after the durable reservation succeeded. A kill
+        # after this point still leaves the persistent ordinal consumed.
+        self._requests += 1
+
+        set_timeout = getattr(self._backend, "set_call_timeout", None)
+        clear_timeout = getattr(self._backend, "clear_call_timeout", None)
+        if callable(set_timeout):
+            set_timeout(cap)
+        try:
+            value = self._backend.complete(
+                prompt,
+                system=system,
+                purpose=purpose,
+                temperature=temperature,
+            )
+        finally:
+            if callable(clear_timeout):
+                try:
+                    clear_timeout()
+                except Exception:
+                    pass
+
+        # A callback/custom transport may ignore the timeout hook. Such a late
+        # result must never become writable merely because it eventually returned.
+        if self._remaining() < 0:
+            raise ModelError(
+                "single-pass extraction result arrived after deadline",
+                code="model_timeout",
+                stage=purpose or "single_pass",
+            )
+        return value
+
+    def consume_call_metrics(self) -> dict[str, Any]:
+        consume = getattr(self._backend, "consume_call_metrics", None)
+        if not callable(consume):
+            return {}
+        try:
+            value = consume()
+        except Exception:
+            return {}
+        return dict(value) if isinstance(value, Mapping) else {}
+
+
+class ExtractionWorkBudget:
+    """One monotonic budget beginning before preparation for a visible turn.
+
+    The first eight seconds are available to preparation plus model work. The
+    remaining two seconds are reserved for deterministic validation/commit.
+    If the ten-second total deadline has already elapsed, the turn is not
+    allowed to enter the mutation boundary.
+
+    ``elapsed_seconds`` restores wall time already consumed by the same durable
+    background work item before a worker restart. The persisted ledger uses a
+    wall clock only to derive that cross-process elapsed interval; after this
+    object is constructed, every new deadline check uses the supplied monotonic
+    clock in the current process.
+    """
+
+    def __init__(
+        self,
+        *,
+        clock: Any = time.monotonic,
+        elapsed_seconds: float = 0.0,
+    ):
+        if (
+            isinstance(elapsed_seconds, bool)
+            or not isinstance(elapsed_seconds, (int, float))
+            or not math.isfinite(float(elapsed_seconds))
+            or float(elapsed_seconds) < 0
+        ):
+            raise ValueError("elapsed_seconds must be a finite non-negative number")
+        self._clock = clock
+        current = float(clock())
+        elapsed = float(elapsed_seconds)
+        self._started = current - elapsed
+        self._model_deadline = current + (MODEL_TIME_BUDGET_SECONDS - elapsed)
+        self._total_deadline = current + (TARGET_TOTAL_SECONDS - elapsed)
+
+    @property
+    def started(self) -> float:
+        return self._started
+
+    @property
+    def model_deadline(self) -> float:
+        return self._model_deadline
+
+    @property
+    def total_deadline(self) -> float:
+        return self._total_deadline
+
+    def remaining_total(self) -> float:
+        return self._total_deadline - float(self._clock())
+
+    def wrap_backend(
+        self,
+        backend: Any,
+        *,
+        reserve_request: Callable[[], int | None] | None = None,
+    ) -> SinglePassBudgetBackend:
+        return budget_single_pass_backend(
+            backend,
+            clock=self._clock,
+            deadline=self._model_deadline,
+            reserve_request=reserve_request,
+        )
+
+    def ensure_before_commit(self) -> None:
+        if self.remaining_total() <= 0:
+            raise ModelError(
+                "single-pass extraction exceeded total deadline before commit",
+                code="model_timeout",
+                stage="single_pass",
+            )
+
+
+def budget_single_pass_backend(
+    backend: Any,
+    *,
+    clock: Any = time.monotonic,
+    deadline: float | None = None,
+    reserve_request: Callable[[], int | None] | None = None,
+) -> SinglePassBudgetBackend:
+    if isinstance(backend, SinglePassBudgetBackend):
+        return backend
+    return SinglePassBudgetBackend(
+        backend,
+        clock=clock,
+        deadline=deadline,
+        reserve_request=reserve_request,
+    )
+
+
+__all__ = [
+    "MAX_MODEL_REQUESTS",
+    "MODEL_TIME_BUDGET_SECONDS",
+    "PRIMARY_REQUEST_MAX_SECONDS",
+    "TARGET_TOTAL_SECONDS",
+    "ExtractionWorkBudget",
+    "SinglePassBudgetBackend",
+    "budget_single_pass_backend",
+]

memleaf-0.2.42/src/memleaf/extraction_capability.py

@@ -0,0 +1,114 @@
+"""Capability checks for unified automatic extraction.
+
+Protocol compatibility and hard latency safety are intentionally separate.
+A backend may understand the B3 single-pass contract without being able to
+honor transport-level cancellation/deadlines. Automatic extraction can use
+one semantic protocol in both cases, while Processor applies the strict
+8/10-second budget only to ``single_pass_safe`` transports.
+"""
+from __future__ import annotations
+
+from typing import Any
+
+from .llm import CallableBackend, ModelRouter
+
+
+def _callable_protocol_override(backend: CallableBackend) -> bool | None:
+    """Return a caller-declared protocol override for callback adapters.
+
+    Raw callbacks default to the unified B3 contract. A callback may set
+    ``single_pass_protocol = False`` when it intentionally implements the
+    legacy staged test/compatibility protocol. Product code never needs this
+    for ordinary host callbacks; the escape hatch prevents capability
+    inference from rewriting explicitly versioned compatibility fixtures.
+    """
+
+    callback = getattr(backend, "callback", None)
+    value = getattr(callback, "single_pass_protocol", None)
+    return value if isinstance(value, bool) else None
+
+
+def _direct_protocol_capable(backend: Any) -> bool:
+    """Return whether one concrete backend can speak the B3 output contract."""
+
+    if backend is None:
+        return False
+    if getattr(backend, "single_pass_safe", False) is True:
+        return True
+    declared = getattr(backend, "single_pass_protocol", None)
+    if isinstance(declared, bool):
+        return declared
+    if isinstance(backend, CallableBackend):
+        override = _callable_protocol_override(backend)
+        if override is not None:
+            return override
+        # Raw Python callbacks are adapted by ModelExecutor into
+        # CallableBackend. They can consume memleaf's B3 prompt, but are not
+        # strict-deadline safe because caller-owned code may ignore
+        # timeout/cancellation entirely.
+        return True
+    return False
+
+
+def supports_single_pass_protocol(backend: Any) -> bool:
+    """Return B3 protocol capability without claiming strict transport SLA."""
+
+    if _direct_protocol_capable(backend):
+        return True
+    if not isinstance(backend, ModelRouter):
+        return False
+
+    if backend.mode == "api":
+        return _direct_protocol_capable(backend.api)
+    if backend.mode == "host":
+        return _direct_protocol_capable(backend.host)
+
+    # Auto mode can expose both routes over its lifetime. Even though the
+    # single-pass call itself is pinned against hidden host->API fallback, B3
+    # capability remains fail-closed unless every configured reachable route
+    # speaks the same protocol. This prevents a later routing-policy change or
+    # route selection from silently changing the output contract.
+    if backend.host is not None:
+        if not _direct_protocol_capable(backend.host):
+            return False
+        return backend.api is None or _direct_protocol_capable(backend.api)
+    return _direct_protocol_capable(backend.api)
+
+
+def _direct_requires_inline_system(backend: Any) -> bool:
+    """Return whether a concrete callback may receive only the prompt value.
+
+    CallableBackend intentionally supports legacy ``callback(prompt)``
+    signatures. In that mode its ``system`` argument cannot reach the caller,
+    so B3 must inline the system contract into the prompt rather than silently
+    dropping the planner rules. This says nothing about latency safety.
+    """
+
+    return isinstance(backend, CallableBackend)
+
+
+def requires_inline_single_pass_system(backend: Any) -> bool:
+    """Keep B3 instructions visible across prompt-only callback routes."""
+
+    if _direct_requires_inline_system(backend):
+        return True
+    if not isinstance(backend, ModelRouter):
+        return False
+    if backend.mode == "api":
+        return _direct_requires_inline_system(backend.api)
+    if backend.mode == "host":
+        return _direct_requires_inline_system(backend.host)
+
+    # Keep the prompt self-contained whenever either configured auto route is
+    # a prompt-only callback. Capability gating above ensures both routes speak
+    # B3 before automatic extraction chooses this protocol.
+    return (
+        _direct_requires_inline_system(backend.host)
+        or _direct_requires_inline_system(backend.api)
+    )
+
+
+__all__ = [
+    "requires_inline_single_pass_system",
+    "supports_single_pass_protocol",
+]