memorymaster 3.21.0__tar.gz → 3.23.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: memorymaster
-Version: 3.21.0
+Version: 3.23.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-2194-green.svg)]()
+[![Tests](https://img.shields.io/badge/tests-2224-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/)
@@ -90,6 +90,9 @@ recent PR status, and sensitivity-filter invariants.
 - **Rule-shaped claims** (new in v3.21.0): prescriptive `when <trigger>, do <action> because <rationale>` claims (`ingest_rule` / `query_rules`) — the shape an agent needs to actually change behaviour next time, not just recall a fact
 - **Correction mining** (new in v3.21.0): `mine-rules` scans the verbatim transcript archive for user corrections and distills them into rule claims; the Stop hook also mines each session's latest correction automatically
 - **Versioned schema migrations** (new in v3.20.0): `migrate` applies SQLite/Postgres migrations with sha256 drift detection; incremental `export-delta` ships small claim deltas for cheap cross-machine sync
+- **Retrieval quality** (new in v3.22.0): floor-ratio boost gate (`MEMORYMASTER_BOOST_FLOOR_RATIO`) stops fresh-but-wrong claims outranking the true match; `query --explain` shows per-stage score attribution; an opt-in correctness-safe query cache (`MEMORYMASTER_QUERY_CACHE`) with a generation gate
+- **Semantic contradiction probe** (new in v3.22.0, wired as a steward phase in v3.23.0): `detect-contradictions` finds claims that genuinely contradict each other (beyond the deterministic same-subject conflict check) via an LLM judge with a Wilson-CI rate and verdict cache; in v3.23 the same probe runs inside `run-steward` and emits paste-ready `conflicted` proposals
+- **Verbatim archive cleanup** (new in v3.23.0): `verbatim-cleanup` dedups the raw-transcript table and optionally purges pre-#128 junk rows, with a dry-run default and FTS5 mirror sync
 - **Steward governance**: multi-probe validators (filesystem, format, citation, semantic, tool) with proposal review
 - **Conflict resolution**: 5-tier auto (confidence > freshness > citations > LLM > manual)
 - **Auto-redaction** at ingest: JWT, GitHub tokens, Bearer, AWS keys, SSH keys, custom patterns

{memorymaster-3.21.0 → memorymaster-3.23.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-2194-green.svg)]()
+[![Tests](https://img.shields.io/badge/tests-2224-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/)
@@ -44,6 +44,9 @@ recent PR status, and sensitivity-filter invariants.
 - **Rule-shaped claims** (new in v3.21.0): prescriptive `when <trigger>, do <action> because <rationale>` claims (`ingest_rule` / `query_rules`) — the shape an agent needs to actually change behaviour next time, not just recall a fact
 - **Correction mining** (new in v3.21.0): `mine-rules` scans the verbatim transcript archive for user corrections and distills them into rule claims; the Stop hook also mines each session's latest correction automatically
 - **Versioned schema migrations** (new in v3.20.0): `migrate` applies SQLite/Postgres migrations with sha256 drift detection; incremental `export-delta` ships small claim deltas for cheap cross-machine sync
+- **Retrieval quality** (new in v3.22.0): floor-ratio boost gate (`MEMORYMASTER_BOOST_FLOOR_RATIO`) stops fresh-but-wrong claims outranking the true match; `query --explain` shows per-stage score attribution; an opt-in correctness-safe query cache (`MEMORYMASTER_QUERY_CACHE`) with a generation gate
+- **Semantic contradiction probe** (new in v3.22.0, wired as a steward phase in v3.23.0): `detect-contradictions` finds claims that genuinely contradict each other (beyond the deterministic same-subject conflict check) via an LLM judge with a Wilson-CI rate and verdict cache; in v3.23 the same probe runs inside `run-steward` and emits paste-ready `conflicted` proposals
+- **Verbatim archive cleanup** (new in v3.23.0): `verbatim-cleanup` dedups the raw-transcript table and optionally purges pre-#128 junk rows, with a dry-run default and FTS5 mirror sync
 - **Steward governance**: multi-probe validators (filesystem, format, citation, semantic, tool) with proposal review
 - **Conflict resolution**: 5-tier auto (confidence > freshness > citations > LLM > manual)
 - **Auto-redaction** at ingest: JWT, GitHub tokens, Bearer, AWS keys, SSH keys, custom patterns

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

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

{memorymaster-3.21.0 → memorymaster-3.23.0}/memorymaster/cli.py

@@ -185,6 +185,7 @@ def build_parser() -> argparse.ArgumentParser:
     query.add_argument("--scope-allowlist", default="", help="Comma-separated scopes to include (e.g. project,team_x)")
     query.add_argument("--as-of", default="", help="Temporal query: show claims valid at this ISO timestamp")
     query.add_argument("--auto-classify", action="store_true", help="Auto-classify query type and use optimal retrieval mode")
+    query.add_argument("--explain", action="store_true", help="Show per-stage score attribution (relevance vs. boosts, floor-gate status) for each result")
 
     context = sub.add_parser("context", help="Pack relevant claims into a token-budgeted context block for AI agents")
     context.add_argument("text", help="Query text describing what context is needed")
@@ -331,6 +332,7 @@ def build_parser() -> argparse.ArgumentParser:
     steward.add_argument("--probe-failure-threshold", type=int, default=3, help="Open circuit breaker for a probe type after this many timeout/error failures")
     steward.add_argument("--disable-semantic-probe", action="store_true", help="Disable semantic retrieval probe in steward planner")
     steward.add_argument("--disable-tool-probe", action="store_true", help="Disable tool/storage probe in steward planner")
+    steward.add_argument("--disable-contradiction-probe", action="store_true", help="Disable semantic contradiction probe in steward planner (v3.23)")
     steward.add_argument("--allow-sensitive", action="store_true", help="Include sensitive claims in stewardship scan")
     steward.add_argument("--apply", action="store_true", help="Apply proposed status transitions")
     steward.add_argument("--artifact-json", default="artifacts/steward/steward_report.json", help="Path to steward JSON report artifact")
@@ -463,6 +465,19 @@ def build_parser() -> argparse.ArgumentParser:
     mine_rules_cmd.add_argument("--provider", default="claude_cli", help="LLM provider for this run (default: claude_cli)")
     mine_rules_cmd.add_argument("--reset", action="store_true", help="Clear the stored watermark before running (re-scan from the start)")
 
+    verbatim_clean = sub.add_parser("verbatim-cleanup", help="Dedup the verbatim archive + optionally purge pre-#128 capture-bug junk (v3.23)")
+    verbatim_clean.add_argument("--analyze-only", dest="analyze_only", action="store_true", help="Report composition only; do not delete")
+    verbatim_clean.add_argument("--apply", action="store_true", help="Actually delete (default is dry-run)")
+    verbatim_clean.add_argument("--no-dedup", dest="no_dedup", action="store_true", help="Skip the (session_id, content) exact-dup pass")
+    verbatim_clean.add_argument("--purge-junk", dest="purge_junk", action="store_true", help="Also delete rows matching known pre-#128 junk prefixes (wiki-absorb prompt, etc.)")
+
+    detect_contra = sub.add_parser("detect-contradictions", help="Find semantic contradictions between topically-similar claims via an LLM judge (v3.22)")
+    detect_contra.add_argument("--limit", type=int, default=200, help="Max claims to load for pair sampling")
+    detect_contra.add_argument("--sample", type=int, default=50, help="Max candidate pairs to judge this run (caps LLM calls)")
+    detect_contra.add_argument("--sim-low", dest="sim_low", type=float, default=0.60, help="Lower similarity-band bound (below = unrelated)")
+    detect_contra.add_argument("--sim-high", dest="sim_high", type=float, default=0.92, help="Upper similarity-band bound (at/above = near-duplicates, dedup's job)")
+    detect_contra.add_argument("--apply", action="store_true", help="Flag the lower-confidence claim of each contradicting pair as conflicted (reversible)")
+
     verify_cmd = sub.add_parser("verify-claims", help="Cross-check claims against current codebase")
     verify_cmd.add_argument("--scope", default="", help="Scope filter")
     verify_cmd.add_argument("--limit", type=int, default=200, help="Max claims to check")

{memorymaster-3.21.0 → memorymaster-3.23.0}/memorymaster/cli_handlers_basic.py

@@ -832,6 +832,25 @@ def _handle_run_cycle(args: argparse.Namespace, service, parser: argparse.Argume
     return 0
 
 
+def _print_score_explanation(breakdown: dict | None) -> None:
+    """Render per-stage score attribution for `query --explain`.
+
+    Shows query-relevance vs. the metadata boost terms and whether the
+    floor-ratio gate suppressed the boosts for this result.
+    """
+    if not breakdown:
+        print("    explain: (no breakdown — legacy retrieval mode)")
+        return
+    terms = breakdown.get("boost_terms", {})
+    w = breakdown.get("weights", (0, 0, 0, 0))
+    applied = breakdown.get("boosts_applied", True)
+    gate = "applied" if applied else f"GATED (relevance < floor={breakdown.get('floor', 0.0):.3f})"
+    term_str = " ".join(f"{k}={v:+.3f}" for k, v in terms.items())
+    print(f"    explain: relevance={breakdown.get('relevance', 0.0):.3f} "
+          f"boosts={breakdown.get('boosts_total', 0.0):+.3f} [{gate}] -> final={breakdown.get('final', 0.0):.3f}")
+    print(f"             weights(l,c,f,v)={tuple(round(x, 2) for x in w)}  boost_terms: {term_str}")
+
+
 def _handle_query(args: argparse.Namespace, service, parser: argparse.ArgumentParser, effective_db: str) -> int:
     resolve_allow_sensitive_access(allow_sensitive=args.allow_sensitive, context="cli.query")
     if getattr(args, "as_of", ""):
@@ -876,6 +895,8 @@ def _handle_query(args: argparse.Namespace, service, parser: argparse.ArgumentPa
                   f"vec={sc['vector_score']:.3f} "
                   f"active={int(bool(ann.get('active')))} stale={int(bool(ann.get('stale')))} "
                   f"conflicted={int(bool(ann.get('conflicted')))} pinned={int(bool(ann.get('pinned')))}")
+            if getattr(args, "explain", False):
+                _print_score_explanation(row.get("breakdown"))
         print(f"rows={len(rows_data)}")
     return 0
 
@@ -1207,6 +1228,7 @@ def _handle_run_steward(args: argparse.Namespace, service, parser: argparse.Argu
         probe_failure_threshold=args.probe_failure_threshold,
         enable_semantic_probe=not args.disable_semantic_probe,
         enable_tool_probe=not args.disable_tool_probe,
+        enable_contradiction_probe=not getattr(args, "disable_contradiction_probe", False),
         artifact_path=Path(args.artifact_json),
     )
     elapsed_ms = (time.perf_counter() - t0) * 1000

{memorymaster-3.21.0 → memorymaster-3.23.0}/memorymaster/cli_handlers_curation.py

@@ -368,6 +368,71 @@ def _handle_mine_rules(args: argparse.Namespace, service, parser: argparse.Argum
     return 0
 
 
+def _handle_detect_contradictions(args: argparse.Namespace, service, parser: argparse.ArgumentParser, effective_db: str) -> int:
+    from memorymaster.contradiction_probe import run_probe
+    t0 = time.perf_counter()
+    result = run_probe(
+        effective_db, service,
+        limit=getattr(args, "limit", 200),
+        sample=getattr(args, "sample", 50),
+        sim_low=getattr(args, "sim_low", 0.60),
+        sim_high=getattr(args, "sim_high", 0.92),
+        apply=getattr(args, "apply", False),
+    )
+    elapsed_ms = (time.perf_counter() - t0) * 1000
+    if args.json_output:
+        print(_json_envelope(result, query_ms=elapsed_ms))
+    else:
+        ci = result["rate_ci"]
+        abort = f", ABORTED ({result['aborted_reason']})" if result.get("aborted_reason") else ""
+        print(
+            f"Contradictions: {result['contradictions']}/{result['judged']} judged "
+            f"(rate={result['rate']:.2f} CI95=[{ci[0]:.2f},{ci[1]:.2f}]) from "
+            f"{result['candidate_pairs']} candidate pairs; cache_hits={result['cache_hits']}, "
+            f"errors={result['judge_errors']}, flagged={result['flagged_conflicted']}{abort} ({elapsed_ms:.0f}ms)"
+        )
+        for f in result["found"][:20]:
+            print(f"  [{f['severity']}] claims {f['claim_a_id']} <> {f['claim_b_id']} "
+                  f"(sim={f['similarity']}): {f['reason']}")
+    return 0
+
+
+def _handle_verbatim_cleanup(args: argparse.Namespace, service, parser: argparse.ArgumentParser, effective_db: str) -> int:
+    from memorymaster.verbatim_cleanup import analyze, cleanup
+    t0 = time.perf_counter()
+    if getattr(args, "analyze_only", False):
+        result = analyze(effective_db)
+    else:
+        result = cleanup(
+            effective_db,
+            dedup=not getattr(args, "no_dedup", False),
+            purge_junk=getattr(args, "purge_junk", False),
+            dry_run=not getattr(args, "apply", False),
+        )
+    elapsed_ms = (time.perf_counter() - t0) * 1000
+    if args.json_output:
+        print(_json_envelope(result, query_ms=elapsed_ms))
+    else:
+        if not result.get("verbatim_present", True):
+            print("verbatim-cleanup: verbatim_memories table not present; nothing to do")
+        elif "before_total" in result:  # cleanup result
+            tag = "(dry-run)" if result["dry_run"] else "(applied)"
+            print(
+                f"verbatim-cleanup {tag}: dedup_deleted={result['dedup_deleted']}, "
+                f"junk_deleted={result['junk_deleted']}, "
+                f"before={result['before_total']} -> after={result['after_total']} "
+                f"({elapsed_ms:.0f}ms)"
+            )
+        else:  # analyze result
+            print(
+                f"verbatim analyze: total={result['total']}, distinct={result['distinct_content']}, "
+                f"duplicate_extras={result['duplicate_extras']}, "
+                f"empty_role={result['empty_role_rows']}, junk_prefix={result['junk_prefix_rows']} "
+                f"({elapsed_ms:.0f}ms)"
+            )
+    return 0
+
+
 def _handle_wiki_breakdown(args: argparse.Namespace, service, parser: argparse.ArgumentParser, effective_db: str) -> int:
     from memorymaster.wiki_engine import breakdown
     t0 = time.perf_counter()
@@ -729,6 +794,8 @@ COMMAND_HANDLERS: dict[str, object] = {
     "bases-generate": _handle_bases_generate,
     "mine-transcript": _handle_mine_transcript,
     "mine-rules": _handle_mine_rules,
+    "detect-contradictions": _handle_detect_contradictions,
+    "verbatim-cleanup": _handle_verbatim_cleanup,
     "verify-claims": _handle_verify_claims,
     "extract-entities": _handle_extract_entities,
     "entity-stats": _handle_entity_stats,

{memorymaster-3.21.0 → memorymaster-3.23.0}/memorymaster/config.py

@@ -222,6 +222,11 @@ class Config:
     llm_rerank: bool = False
     rrf_tiebreaker_enabled: bool = False
     rrf_tiebreaker_threshold: float = 0.01
+    # Floor-ratio gate (gbrain v0.35.6 "hybrid.floor_ratio"): metadata boosts
+    # (confidence/freshness/tier/pinned) only apply to candidates whose
+    # query-relevance (lexical+vector) is >= boost_floor_ratio * top relevance.
+    # 0.0 = disabled (boosts always apply) — preserves pre-v3.22 behaviour.
+    boost_floor_ratio: float = 0.0
 
     # --- Initial confidence priors calibrated from validator outcomes ---
     default_initial_confidence: float = DEFAULT_INITIAL_CONFIDENCE
@@ -397,6 +402,7 @@ def load_config(config_path: str | Path | None = None) -> Config:
     _apply_env_bool(overrides, "MEMORYMASTER_LLM_RERANK", "llm_rerank")
     _apply_env_bool(overrides, "MEMORYMASTER_RRF_TIEBREAKER", "rrf_tiebreaker_enabled")
     _apply_env_float(overrides, "MEMORYMASTER_RRF_TIEBREAKER_THRESHOLD", "rrf_tiebreaker_threshold")
+    _apply_env_float(overrides, "MEMORYMASTER_BOOST_FLOOR_RATIO", "boost_floor_ratio")
     _apply_env_retrieval_profiles(overrides)
 
     # Filter to only valid Config fields