memorymaster 3.23.0__tar.gz → 3.25.0__tar.gz

{memorymaster-3.23.0/memorymaster.egg-info → memorymaster-3.25.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: memorymaster
-Version: 3.23.0
+Version: 3.25.0
 Summary: Production-grade memory reliability system for AI coding agents. Lifecycle-managed claims with citations, conflict detection, steward governance, and MCP integration.
 Author: wolverin0
 License: MIT
@@ -52,7 +52,7 @@ Lifecycle-managed claims with citations, conflict detection, steward governance,
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 [![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
-[![Tests](https://img.shields.io/badge/tests-2224-green.svg)]()
+[![Tests](https://img.shields.io/badge/tests-2232-green.svg)]()
 [![MCP Tools](https://img.shields.io/badge/MCP%20tools-24-purple.svg)]()
 [![CLI Commands](https://img.shields.io/badge/CLI%20commands-86-orange.svg)]()
 [![PyPI](https://img.shields.io/pypi/v/memorymaster.svg)](https://pypi.org/project/memorymaster/)

{memorymaster-3.23.0 → memorymaster-3.25.0}/README.md

@@ -6,7 +6,7 @@ Lifecycle-managed claims with citations, conflict detection, steward governance,
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 [![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
-[![Tests](https://img.shields.io/badge/tests-2224-green.svg)]()
+[![Tests](https://img.shields.io/badge/tests-2232-green.svg)]()
 [![MCP Tools](https://img.shields.io/badge/MCP%20tools-24-purple.svg)]()
 [![CLI Commands](https://img.shields.io/badge/CLI%20commands-86-orange.svg)]()
 [![PyPI](https://img.shields.io/pypi/v/memorymaster.svg)](https://pypi.org/project/memorymaster/)

{memorymaster-3.23.0 → memorymaster-3.25.0}/memorymaster/__init__.py

@@ -2,4 +2,4 @@
 
 __all__ = ["__version__"]
 
-__version__ = "3.23.0"
+__version__ = "3.25.0"

{memorymaster-3.23.0 → memorymaster-3.25.0}/memorymaster/config_templates/hooks/memorymaster-auto-ingest.py

@@ -10,9 +10,8 @@ import json
 import os
 import sys
 import re
-import sqlite3
 import hashlib
-from datetime import datetime, timezone
+from datetime import datetime
 from pathlib import Path
 
 PROJECT_ROOT = "__MEMORYMASTER_PROJECT_ROOT__"
@@ -139,43 +138,40 @@ Only: bug root causes, decisions, gotchas, constraints. Never: credentials, IPs,
             return
 
         scope = "project:" + os.path.basename(cwd).lower().replace(" ", "-") if cwd else "global"
-        now = datetime.now(timezone.utc).isoformat()
 
-        conn = sqlite3.connect(DB_PATH)
+        # Route through MemoryService.ingest instead of raw SQL so claims gain
+        # the canonical ingest path: sensitivity sanitize (defense-in-depth on
+        # top of the _is_sensitive_claim drop above), content-hash + idempotency
+        # dedup, entity resolution, auto-citation, observability, and webhook.
+        # Mirrors _run_rule_extraction, which already uses the service.
+        from memorymaster.service import MemoryService
+        from memorymaster.models import CitationInput
+
+        svc = MemoryService(DB_PATH, workspace_root=Path(cwd or PROJECT_ROOT))
+        ingested = 0
         for c in claims:
             text = c.get("text", "")
             if not text or len(text) < 10:
                 continue
-            # Duplicate check by content hash
             text_hash = hashlib.sha256(text.strip().lower().encode()).hexdigest()[:16]
-            idem = f"llm-stop-{text_hash}"
-            if conn.execute("SELECT id FROM claims WHERE idempotency_key = ?", (idem,)).fetchone():
-                continue
-            cur = conn.execute(
-                """INSERT INTO claims (text, idempotency_key, normalized_text, claim_type,
-                   subject, predicate, scope, status, confidence,
-                   source_agent, created_at, updated_at, tier, version, visibility,
-                   valid_from)
-                   VALUES (?, ?, ?, ?, ?, ?, ?, 'candidate', 0.6,
-                   'llm-stop-hook', ?, ?, 'working', 1, 'public', ?)""",
-                (text, idem, text.lower(), c.get("claim_type", "fact"),
-                 c.get("subject", "codebase"), c.get("predicate", "observation"),
-                 scope, now, now, now),
-            )
-            # Auto-citation: steward's min_citations>=1 gate requires at least one
-            # row per claim. Without this, every llm-stop-hook claim is born
-            # unpromotable. Source is the hook itself; locator = scope for
-            # traceability; excerpt preserves the first 200 chars of the claim.
-            conn.execute(
-                """INSERT INTO citations (claim_id, source, locator, excerpt, created_at)
-                   VALUES (?, 'llm-stop-hook', ?, ?, ?)""",
-                (cur.lastrowid, scope, text[:200], now),
-            )
-        conn.commit()
-        conn.close()
+            try:
+                svc.ingest(
+                    text=text,
+                    citations=[CitationInput(source="llm-stop-hook", locator=scope, excerpt=text[:200])],
+                    idempotency_key=f"llm-stop-{text_hash}",
+                    claim_type=c.get("claim_type", "fact"),
+                    subject=c.get("subject", "codebase"),
+                    predicate=c.get("predicate", "observation"),
+                    scope=scope,
+                    confidence=0.6,
+                    source_agent="llm-stop-hook",
+                )
+                ingested += 1
+            except Exception:
+                continue  # one bad claim must not abort the rest
 
         provider = os.environ.get("MEMORYMASTER_LLM_PROVIDER", "google")
-        sys.stderr.write(f"[MemoryMaster] {provider} extracted {len(claims)} learnings\n")
+        sys.stderr.write(f"[MemoryMaster] {provider} extracted {ingested} learnings\n")
     except Exception:
         pass
 

{memorymaster-3.23.0 → memorymaster-3.25.0}/memorymaster/contradiction_probe.py

@@ -357,7 +357,7 @@ def probe_for_claim(
     metrics: dict[str, Any] = {
         "pairs_checked": 0, "contradictions": 0,
         "cache_hits": 0, "llm_calls": 0, "errors": 0,
-        "timed_out": False, "duration_ms": 0.0,
+        "timed_out": False, "budget_exhausted": False, "duration_ms": 0.0,
     }
     reasons: list[dict[str, Any]] = []
 
@@ -426,7 +426,11 @@ def probe_for_claim(
                 try:
                     verdict = _judge_llm(claim, peer)
                 except llm_budget.LLMBudgetExceeded:
-                    metrics["timed_out"] = True
+                    # Budget exhaustion is an expected guardrail, NOT a probe
+                    # failure — the steward must not count it toward the circuit
+                    # breaker (which would disable the probe for the rest of the
+                    # cycle). Flag it distinctly from a genuine timeout.
+                    metrics["budget_exhausted"] = True
                     break
                 metrics["llm_calls"] += 1
                 if verdict is None:

{memorymaster-3.23.0 → memorymaster-3.25.0}/memorymaster/query_cache.py

@@ -84,11 +84,31 @@ def current_generation(conn: sqlite3.Connection) -> int:
     return int(row[0]) if row else 0
 
 
+def read_generation(db_path: str) -> int:
+    """Return the current corpus generation, or 0 on any error.
+
+    Callers capture this BEFORE reading the corpus they are about to compute a
+    result from, then pass it to ``write()`` — see the TOCTOU note there."""
+    try:
+        conn = _connect(db_path)
+    except sqlite3.Error as exc:
+        logger.warning("query_cache.read_generation connect failed: %s", exc)
+        return 0
+    try:
+        return current_generation(conn)
+    except (sqlite3.Error, ValueError) as exc:
+        logger.warning("query_cache.read_generation failed: %s", exc)
+        return 0
+    finally:
+        conn.close()
+
+
 def read(db_path: str, cache_key: str) -> list[dict] | None:
     """Return cached result stubs if present AND still fresh (generation match)."""
     try:
         conn = _connect(db_path)
-    except sqlite3.Error:
+    except sqlite3.Error as exc:
+        logger.warning("query_cache.read connect failed: %s", exc)
         return None
     try:
         gen = current_generation(conn)
@@ -99,20 +119,31 @@ def read(db_path: str, cache_key: str) -> list[dict] | None:
         if row is None or int(row["generation"]) != gen:
             return None
         return json.loads(row["result_json"])
-    except (sqlite3.Error, json.JSONDecodeError, ValueError):
+    except (sqlite3.Error, json.JSONDecodeError, ValueError) as exc:
+        logger.warning("query_cache.read failed (cache disabled for this query): %s", exc)
         return None
     finally:
         conn.close()
 
 
-def write(db_path: str, cache_key: str, stub_rows: list[dict]) -> None:
-    """Store result stubs tagged with the current generation. Best-effort."""
+def write(db_path: str, cache_key: str, stub_rows: list[dict], generation: int) -> None:
+    """Store result stubs tagged with ``generation``. Best-effort.
+
+    TOCTOU correctness: ``generation`` MUST be the corpus generation captured by
+    the caller BEFORE it read the candidates it computed ``stub_rows`` from. If
+    we re-read the generation here instead, a claim write that raced in between
+    the caller's corpus read and this write would have bumped the counter, and
+    we would tag a stale (generation-G) result as the new generation (G+1) — so
+    a subsequent read at G+1 would serve the stale ranking, defeating the
+    generation gate. Tagging with the compute-time generation guarantees any
+    racing write correctly invalidates this entry. (audit: qc-generation-toctou)
+    """
     try:
         conn = _connect(db_path)
-    except sqlite3.Error:
+    except sqlite3.Error as exc:
+        logger.warning("query_cache.write connect failed: %s", exc)
         return
     try:
-        gen = current_generation(conn)
         conn.execute(
             """INSERT INTO query_cache (cache_key, result_json, generation, created_at)
                VALUES (?, ?, ?, ?)
@@ -120,10 +151,10 @@ def write(db_path: str, cache_key: str, stub_rows: list[dict]) -> None:
                    result_json = excluded.result_json,
                    generation = excluded.generation,
                    created_at = excluded.created_at""",
-            (cache_key, json.dumps(stub_rows), gen, datetime.now(timezone.utc).isoformat()),
+            (cache_key, json.dumps(stub_rows), generation, datetime.now(timezone.utc).isoformat()),
         )
         conn.commit()
-    except (sqlite3.Error, TypeError, ValueError):
-        pass
+    except (sqlite3.Error, TypeError, ValueError) as exc:
+        logger.warning("query_cache.write failed (result not cached): %s", exc)
     finally:
         conn.close()

{memorymaster-3.23.0 → memorymaster-3.25.0}/memorymaster/rule_miner.py

@@ -158,12 +158,26 @@ def _build_window(assistant_content: str, user_content: str) -> str:
     return f"ASSISTANT: {asst}\nUSER: {user}"
 
 
+class TransientLLMError(RuntimeError):
+    """The LLM provider returned an empty response — almost always a transient
+    failure (outage, timeout, rate-limit returning ''), NOT a genuine "no
+    correction" verdict. Callers must distinguish the two: advancing the
+    watermark past a candidate that was never actually judged would permanently
+    skip real corrections during a provider outage. (audit:
+    mine-rules-silent-watermark-advance)"""
+
+
 def _extract_rule(window: str) -> dict[str, str] | None:
     """Ask the LLM to distill a rule. Returns ``{trigger, action, rationale}``
-    or ``None`` when there is no correction. May raise ``LLMBudgetExceeded``."""
+    or ``None`` when the model responded but found no correction.
+
+    Raises ``LLMBudgetExceeded`` if the per-cycle cap is hit, and
+    ``TransientLLMError`` if the provider returned nothing (so the caller can
+    avoid advancing the watermark). A non-empty response that simply doesn't
+    parse to a rule is a genuine "no correction" (``None``), not transient."""
     raw = llm_provider.call_llm(_CORRECTION_PROMPT, window)
     if not raw or not raw.strip():
-        return None
+        raise TransientLLMError("empty LLM response")
     for item in llm_provider.parse_json_response(raw):
         if not isinstance(item, dict):
             continue
@@ -300,6 +314,12 @@ def _process_candidate(
     except llm_budget.LLMBudgetExceeded as exc:
         stats["aborted_reason"] = exc.reason
         return "aborted"
+    except TransientLLMError:
+        # Provider returned empty (likely transient outage). Abort the run WITHOUT
+        # advancing the watermark past this row, so the candidate is retried next
+        # run instead of silently skipped. Stopping is safe: mining is a batch job.
+        stats["aborted_reason"] = "llm_transient_failure"
+        return "aborted"
 
     stats["llm_calls"] += 1
     if rule is None or _is_sensitive_rule(rule):
@@ -412,7 +432,10 @@ def mine_transcript_rules(
                 stats["windows"] += 1
                 try:
                     rule = _extract_rule(_build_window(asst_text, user_text))
-                except llm_budget.LLMBudgetExceeded:
+                except (llm_budget.LLMBudgetExceeded, TransientLLMError):
+                    # Budget hit or provider returned empty — stop this best-effort
+                    # Stop-hook pass. No watermark here, so nothing to skip; a
+                    # later session re-mines its own corrections.
                     break
                 stats["llm_calls"] += 1
                 if rule is None or _is_sensitive_rule(rule):

{memorymaster-3.23.0 → memorymaster-3.25.0}/memorymaster/security.py

@@ -157,6 +157,8 @@ class SanitizedClaimInput:
     is_sensitive: bool
     findings: list[str]
     encrypted_payload: str | None
+    subject: str | None = None
+    predicate: str | None = None
 
 
 def _as_bool(value: object, *, field: str) -> bool:
@@ -320,6 +322,8 @@ def sanitize_claim_input(
     text: str,
     object_value: str | None,
     citations: list[CitationInput],
+    subject: str | None = None,
+    predicate: str | None = None,
 ) -> SanitizedClaimInput:
     redacted_text, findings = _redact(text)
     redacted_object = object_value
@@ -328,6 +332,19 @@ def sanitize_claim_input(
         redacted_object, object_findings = _redact(object_value)
         findings.extend(object_findings)
 
+    # subject/predicate are structured-claim fields that reach the store
+    # alongside text/object_value. They are exposed MCP ingest parameters, so a
+    # secret placed there must be caught by the ingest filter — the last line of
+    # defense — not only at display time. (audit: ingest-subject-skips-filter)
+    redacted_subject = subject
+    if subject:
+        redacted_subject, subject_findings = _redact(subject)
+        findings.extend(subject_findings)
+    redacted_predicate = predicate
+    if predicate:
+        redacted_predicate, predicate_findings = _redact(predicate)
+        findings.extend(predicate_findings)
+
     sanitized_citations: list[CitationInput] = []
     citation_findings: list[str] = []
     for cite in citations:
@@ -344,6 +361,8 @@ def sanitize_claim_input(
         {
             "text": text,
             "object_value": object_value,
+            "subject": subject,
+            "predicate": predicate,
             "citations": [asdict(c) for c in citations],
         }
     ) if is_sensitive else None
@@ -355,6 +374,8 @@ def sanitize_claim_input(
         is_sensitive=is_sensitive,
         findings=dedup_findings,
         encrypted_payload=encrypted_payload,
+        subject=redacted_subject,
+        predicate=redacted_predicate,
     )
 
 

{memorymaster-3.23.0 → memorymaster-3.25.0}/memorymaster/service.py

@@ -251,9 +251,15 @@ class MemoryService:
             text=text.strip(),
             object_value=object_value,
             citations=citations,
+            subject=subject,
+            predicate=predicate,
         )
         if not sanitized.citations:
             raise ValueError("At least one citation is required.")
+        # Use the sanitized subject/predicate everywhere downstream so a secret
+        # placed in those fields is redacted at rest, not just at display time.
+        subject = sanitized.subject
+        predicate = sanitized.predicate
         # Resolve subject → canonical entity (GBrain-inspired entity registry)
         # and mine text for pattern-based entities (#127 Wave 3).
         entity_id = 0
@@ -667,6 +673,11 @@ class MemoryService:
                     rows = self._rehydrate_cached_rows(cached)
                     self._record_accesses(rows, query_text=query_text)
                     return rows
+        # Capture the corpus generation BEFORE reading candidates so the cache
+        # entry is tagged with the generation it was actually computed against,
+        # not whatever it is after ranking/LLM-rerank (which a concurrent claim
+        # write could have bumped). See query_cache.write TOCTOU note.
+        cache_generation = query_cache.read_generation(cache_path) if cache_path else 0
         candidate_limit = max(limit * 6, 60, 50 if use_llm_rerank else 0)
         candidates = self.store.list_claims(
             limit=candidate_limit,
@@ -733,7 +744,7 @@ class MemoryService:
                     "breakdown": r.get("breakdown"),
                 }
                 for r in results if r.get("claim") is not None
-            ])
+            ], cache_generation)
         return results
 
     def _rehydrate_cached_rows(self, stubs: list[dict[str, Any]]) -> list[dict[str, Any]]:

{memorymaster-3.23.0 → memorymaster-3.25.0}/memorymaster/steward.py

@@ -9,7 +9,7 @@ import subprocess
 import time
 from typing import Any, Literal
 
-from memorymaster import observability
+from memorymaster import llm_budget, observability
 from memorymaster.lifecycle import transition_claim
 from memorymaster.security import is_sensitive_claim
 from memorymaster.service import MemoryService
@@ -891,6 +891,14 @@ def _make_circuit_open_result(probe: ProbeSpec, probe_type: str, probe_failure_t
     )
 
 
+# Open ONE per-cycle LLM budget scope for the whole cycle so
+# MEMORYMASTER_MAX_LLM_CALLS_PER_CYCLE (and the token / provider-failure caps)
+# apply across every LLM-using probe this cycle — notably the contradiction
+# probe's judge. cycle_scope is a @contextmanager, so it doubles as a context
+# decorator and recreates a fresh scope per call. Without this the cap was a
+# no-op for the steward and probe_for_claim's LLMBudgetExceeded handler was dead
+# in production. (audit: probe-for-claim-budget-no-scope)
+@llm_budget.cycle_scope()
 def _run_cycle(
     service: MemoryService,
     *,