memorymaster 3.26.0__tar.gz → 3.28.0__tar.gz

{memorymaster-3.26.0/memorymaster.egg-info → memorymaster-3.28.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: memorymaster
-Version: 3.26.0
+Version: 3.28.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-2514-green.svg)]()
+[![Tests](https://img.shields.io/badge/tests-2732-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.26.0 → memorymaster-3.28.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-2514-green.svg)]()
+[![Tests](https://img.shields.io/badge/tests-2732-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.26.0 → memorymaster-3.28.0}/memorymaster/__init__.py

@@ -2,4 +2,4 @@
 
 __all__ = ["__version__"]
 
-__version__ = "3.26.0"
+__version__ = "3.28.0"

{memorymaster-3.26.0 → memorymaster-3.28.0}/memorymaster/_storage_read.py

@@ -33,16 +33,23 @@ class _ReadMixin:
         normalized_key = (idempotency_key or "").strip() or None
         if normalized_key is None:
             return None
+        # Hydrate the full row from the already-open conn instead of paying
+        # a fresh get_claim() connection open on every duplicate re-ingest.
         existing_row = conn.execute(
-            "SELECT id FROM claims WHERE idempotency_key = ?",
+            "SELECT * FROM claims WHERE idempotency_key = ?",
             (normalized_key,),
         ).fetchone()
-        if existing_row is not None:
-            existing = self.get_claim(int(existing_row["id"]))
-            if existing is None:
-                raise RuntimeError("Idempotency key matched missing claim.")
-            return existing
-        return None
+        if existing_row is None:
+            return None
+        claim = self._row_to_claim(existing_row)
+        claim.citations = [
+            self._row_to_citation(cit_row)
+            for cit_row in conn.execute(
+                "SELECT * FROM citations WHERE claim_id = ? ORDER BY id ASC",
+                (claim.id,),
+            ).fetchall()
+        ]
+        return claim
 
 
     def get_claim(self, claim_id: int, include_citations: bool = True) -> Claim | None:
@@ -172,7 +179,13 @@ class _ReadMixin:
             clauses.append(f"status IN ({placeholders})")
             params.extend(status_in)
 
-        if not include_archived and status != "archived":
+        # Only apply the implicit archived-exclusion when the caller did not
+        # explicitly request archived claims via `status` or `status_in`.
+        # Otherwise list_claims(status_in=['archived']) would return zero rows.
+        explicitly_wants_archived = (
+            status == "archived" or (status is None and bool(status_in) and "archived" in status_in)
+        )
+        if not include_archived and not explicitly_wants_archived:
             clauses.append("status <> 'archived'")
 
         if scope_allowlist:
@@ -597,6 +610,45 @@ class _ReadMixin:
             ).fetchall()
         return [self._row_to_citation(row) for row in rows]
 
+    @staticmethod
+    def _batch_neighbors(
+        conn: sqlite3.Connection,
+        frontier_ids: list[int],
+        *,
+        direction: str,
+        link_types: list[str] | None,
+    ) -> dict[int, list[tuple[int, str]]]:
+        """Fetch all neighbors for a whole BFS frontier in one query per direction.
+
+        Returns a mapping ``{frontier_claim_id: [(neighbor_id, link_type), ...]}``.
+        Replaces the per-node N+1 pattern with one batched query per level.
+        """
+        if not frontier_ids:
+            return {}
+        result: dict[int, list[tuple[int, str]]] = {cid: [] for cid in frontier_ids}
+        placeholders = ",".join("?" for _ in frontier_ids)
+        if direction in ("outgoing", "both"):
+            sql = f"SELECT source_id, target_id, link_type FROM claim_links WHERE source_id IN ({placeholders})"
+            for row in conn.execute(sql, frontier_ids).fetchall():
+                if link_types is None or row["link_type"] in link_types:
+                    result[int(row["source_id"])].append((int(row["target_id"]), str(row["link_type"])))
+        if direction in ("incoming", "both"):
+            sql = f"SELECT source_id, target_id, link_type FROM claim_links WHERE target_id IN ({placeholders})"
+            for row in conn.execute(sql, frontier_ids).fetchall():
+                if link_types is None or row["link_type"] in link_types:
+                    result[int(row["target_id"])].append((int(row["source_id"]), str(row["link_type"])))
+        return result
+
+    def _hydrate_claims(self, conn: sqlite3.Connection, claim_ids: list[int]) -> dict[int, Claim]:
+        """Load a batch of claims (no citations) in a single SELECT from *conn*."""
+        if not claim_ids:
+            return {}
+        placeholders = ",".join("?" for _ in claim_ids)
+        rows = conn.execute(
+            f"SELECT * FROM claims WHERE id IN ({placeholders})", claim_ids
+        ).fetchall()
+        return {int(row["id"]): self._row_to_claim(row) for row in rows}
+
     def traverse_relationships(
         self,
         start_claim_id: int,
@@ -616,44 +668,34 @@ class _ReadMixin:
         """
         with self.connect() as conn:
             visited: set[int] = {start_claim_id}
-            queue: list[tuple[int, int, list[int], str]] = []  # (claim_id, depth, path, via_link_type)
-
-            # Seed with depth-0 neighbors
-            def _get_neighbors(claim_id: int) -> list[tuple[int, str]]:
-                neighbors: list[tuple[int, str]] = []
-                if direction in ("outgoing", "both"):
-                    q = "SELECT target_id, link_type FROM claim_links WHERE source_id = ?"
-                    for row in conn.execute(q, (claim_id,)).fetchall():
-                        if link_types is None or row[1] in link_types:
-                            neighbors.append((row[0], row[1]))
-                if direction in ("incoming", "both"):
-                    q = "SELECT source_id, link_type FROM claim_links WHERE target_id = ?"
-                    for row in conn.execute(q, (claim_id,)).fetchall():
-                        if link_types is None or row[1] in link_types:
-                            neighbors.append((row[0], row[1]))
-                return neighbors
-
-            for neighbor_id, link_type in _get_neighbors(start_claim_id):
+            # Frontier entries: (claim_id, depth, path, via_link_type)
+            frontier: list[tuple[int, int, list[int], str]] = []
+            seed = self._batch_neighbors(conn, [start_claim_id], direction=direction, link_types=link_types)
+            for neighbor_id, link_type in seed.get(start_claim_id, []):
                 if neighbor_id not in visited:
                     visited.add(neighbor_id)
-                    queue.append((neighbor_id, 1, [start_claim_id, neighbor_id], link_type))
+                    frontier.append((neighbor_id, 1, [start_claim_id, neighbor_id], link_type))
 
             results: list[dict] = []
-            while queue:
-                cid, depth, path, via_type = queue.pop(0)
-                claim = self.get_claim(cid, include_citations=False)
-                if claim:
-                    results.append({
-                        "claim": claim,
-                        "depth": depth,
-                        "path": path,
-                        "link_type": via_type,
-                    })
-                if depth < max_depth:
-                    for neighbor_id, link_type in _get_neighbors(cid):
+            while frontier:
+                level_ids = [cid for cid, _, _, _ in frontier]
+                claims = self._hydrate_claims(conn, level_ids)
+                next_frontier: list[tuple[int, int, list[int], str]] = []
+                depth = frontier[0][1] if frontier else 0
+                neighbor_map = (
+                    self._batch_neighbors(conn, level_ids, direction=direction, link_types=link_types)
+                    if depth < max_depth
+                    else {}
+                )
+                for cid, cdepth, path, via_type in frontier:
+                    claim = claims.get(cid)
+                    if claim:
+                        results.append({"claim": claim, "depth": cdepth, "path": path, "link_type": via_type})
+                    for neighbor_id, link_type in neighbor_map.get(cid, []):
                         if neighbor_id not in visited:
                             visited.add(neighbor_id)
-                            queue.append((neighbor_id, depth + 1, path + [neighbor_id], link_type))
+                            next_frontier.append((neighbor_id, cdepth + 1, path + [neighbor_id], link_type))
+                frontier = next_frontier
 
         return results
 

{memorymaster-3.26.0 → memorymaster-3.28.0}/memorymaster/_storage_schema.py

@@ -329,6 +329,10 @@ class _SchemaMixin:
         if not _SchemaMixin._fts5_available(conn):
             return
 
+        fts_existed = conn.execute(
+            "SELECT 1 FROM sqlite_master WHERE type='table' AND name='claims_fts'"
+        ).fetchone() is not None
+
         conn.execute(
             """
             CREATE VIRTUAL TABLE IF NOT EXISTS claims_fts USING fts5(
@@ -401,9 +405,19 @@ class _SchemaMixin:
             """
         )
 
-        # Backfill: rebuild FTS index from existing claims data.
-        # The 'rebuild' command re-reads all rows from the content table.
-        conn.execute("INSERT INTO claims_fts(claims_fts) VALUES ('rebuild')")
+        # Backfill: rebuild the FTS index from existing claims data only when
+        # necessary. A full 'rebuild' is O(n) over every claim and the sync
+        # triggers above already keep the index current, so on warm DBs an
+        # unconditional rebuild is pure waste (54k+ claims). Rebuild only when
+        # the FTS table was just created, or when a row-count mismatch between
+        # `claims` and `claims_fts` reveals the index drifted.
+        needs_rebuild = not fts_existed
+        if not needs_rebuild:
+            claims_count = conn.execute("SELECT COUNT(*) FROM claims").fetchone()[0]
+            fts_count = conn.execute("SELECT COUNT(*) FROM claims_fts").fetchone()[0]
+            needs_rebuild = claims_count != fts_count
+        if needs_rebuild:
+            conn.execute("INSERT INTO claims_fts(claims_fts) VALUES ('rebuild')")
 
 
     @staticmethod
@@ -486,12 +500,26 @@ class _SchemaMixin:
 
     @staticmethod
     def _backfill_human_ids(conn: sqlite3.Connection) -> int:
-        """Assign human_id to all claims that lack one."""
+        """Assign human_id to all claims that lack one.
+
+        Guard: only the claims with a NULL human_id are selected, so a warm DB
+        (all ids assigned) returns immediately. When there are zero
+        ``derived_from`` links the whole batch is top-level, so we skip the
+        per-row claim_links JOIN and generate ids in-memory + executemany.
+        """
         rows = conn.execute(
             "SELECT id, subject, text FROM claims WHERE human_id IS NULL ORDER BY id ASC"
         ).fetchall()
         if not rows:
             return 0
+
+        has_derived_links = conn.execute(
+            "SELECT 1 FROM claim_links WHERE link_type = 'derived_from' LIMIT 1"
+        ).fetchone() is not None
+
+        if not has_derived_links:
+            return _SchemaMixin._backfill_human_ids_top_level(conn, rows)
+
         updated = 0
         for row in rows:
             claim_id = int(row["id"])
@@ -505,6 +533,33 @@ class _SchemaMixin:
             updated += 1
         return updated
 
+    @staticmethod
+    def _backfill_human_ids_top_level(conn: sqlite3.Connection, rows: list) -> int:
+        """Batch-assign top-level human_ids (no derived_from parents present).
+
+        Collisions are resolved in-memory against ids already present in the DB
+        plus ids minted within this batch, then written via a single executemany.
+        """
+        taken: set[str] = {
+            str(r[0])
+            for r in conn.execute(
+                "SELECT human_id FROM claims WHERE human_id IS NOT NULL"
+            ).fetchall()
+        }
+        updates: list[tuple[str, int]] = []
+        for row in rows:
+            claim_id = int(row["id"])
+            candidate = generate_top_level_human_id(row["subject"], str(row["text"]))
+            final = candidate
+            suffix = 1
+            while final in taken:
+                suffix += 1
+                final = f"{candidate}~{suffix}"
+            taken.add(final)
+            updates.append((final, claim_id))
+        conn.executemany("UPDATE claims SET human_id = ? WHERE id = ?", updates)
+        return len(updates)
+
 
     @staticmethod
     def _allocate_human_id(
@@ -675,6 +730,20 @@ class _SchemaMixin:
 
     @staticmethod
     def _backfill_event_chain(conn: sqlite3.Connection, *, rebuild_all: bool = False) -> int:
+        # Fast path: when not rebuilding everything, skip the full-table scan
+        # entirely if every event already has an event_hash. The cheap probe
+        # uses idx_events_event_hash, so the common warm-DB init does no work.
+        if not rebuild_all:
+            pending = conn.execute(
+                "SELECT 1 FROM events WHERE event_hash IS NULL LIMIT 1"
+            ).fetchone()
+            if pending is None:
+                return 0
+
+        # Materialize the rows before issuing UPDATEs: SQLite forbids mutating
+        # a table while a read cursor over it is still being iterated, so we
+        # fetchall() here rather than streaming. The NULL-hash guard above
+        # already makes the warm-DB common case do zero work.
         rows = conn.execute(
             """
             SELECT id, claim_id, event_type, from_status, to_status, details, payload_json, created_at, event_hash, hash_algo

{memorymaster-3.26.0 → memorymaster-3.28.0}/memorymaster/_storage_sources.py

@@ -633,6 +633,16 @@ class _SourceItemsMixin:
             return []
         now = utc_now()
         with self.connect() as conn:
+            # BEGIN IMMEDIATE takes the write lock up front so the SELECT and
+            # the claiming UPDATE are one atomic read-modify-write. Without it,
+            # two concurrent fetchers can SELECT the same pending rows, both
+            # UPDATE (double-incrementing attempt_count, emitting duplicate
+            # events) and both receive the same media_key — breaking the
+            # single-claimer guarantee. The loser waits on busy_timeout instead
+            # of failing. The "AND status = 'pending'" on the UPDATE is the
+            # second guard: a row already moved out of 'pending' is never
+            # re-claimed even if a stale id slips through.
+            conn.execute("BEGIN IMMEDIATE")
             rows = conn.execute(
                 """
                 SELECT id FROM media_retry_queue
@@ -654,7 +664,8 @@ class _SourceItemsMixin:
                 SET status = 'retrying',
                     attempt_count = attempt_count + 1,
                     updated_at = ?
-                WHERE id IN ({placeholders})
+                WHERE status = 'pending'
+                  AND id IN ({placeholders})
                 """,
                 [now, *ids],
             )

{memorymaster-3.26.0 → memorymaster-3.28.0}/memorymaster/auto_resolver.py

@@ -158,21 +158,44 @@ def resolve_conflict_pair(
 
 
 def _resolve_group_pairs(store, claims: list[Claim], limit: int) -> tuple[int, int, int]:
-    """Resolve all pairs within a conflict group. Returns (evaluated, resolved, failed)."""
+    """Resolve a conflict group down to a single survivor. Returns (evaluated, resolved, failed).
+
+    MED audit fix: the previous loop only compared ADJACENT claims
+    (i vs i+1). In a 3+ group that left non-adjacent claims still
+    'conflicted' even though the whole group was reported resolved — a
+    claim that lost to its neighbour was never compared to the eventual
+    survivor. We instead carry a running winner and judge it against each
+    remaining conflicted claim, so every loser is superseded by the actual
+    group survivor and at most one 'conflicted' claim remains.
+    """
     evaluated = 0
     resolved = 0
     failed = 0
 
-    for i in range(len(claims) - 1):
+    # Running winner: the first still-conflicted claim, refreshed from store.
+    winner: Claim | None = None
+
+    for claim in claims:
         if evaluated >= limit:
             break
-        # Re-fetch to check if still conflicted (might have been resolved in earlier pair)
-        a = store.get_claim(claims[i].id, include_citations=True)
-        b = store.get_claim(claims[i + 1].id, include_citations=True)
-        if a is None or b is None or a.status != "conflicted" or b.status != "conflicted":
+
+        contender = store.get_claim(claim.id, include_citations=True)
+        if contender is None or contender.status != "conflicted":
+            continue
+
+        if winner is None:
+            winner = contender
+            continue
+
+        # Re-fetch the running winner: an earlier pair (or another writer)
+        # may have changed its status/version since we last saw it.
+        winner = store.get_claim(winner.id, include_citations=True)
+        if winner is None or winner.status != "conflicted":
+            # Running winner is gone; the current contender becomes the new winner.
+            winner = contender
             continue
 
-        result = resolve_conflict_pair(store, a, b)
+        result = resolve_conflict_pair(store, winner, contender)
         evaluated += 1
         if result.get("resolved"):
             resolved += 1
@@ -180,6 +203,10 @@ def _resolve_group_pairs(store, claims: list[Claim], limit: int) -> tuple[int, i
                 "Resolved conflict: winner=%d, loser=%d (%s)",
                 result["winner_id"], result["loser_id"], result["reason"],
             )
+            # The survivor (whichever side the LLM kept) carries forward.
+            survivor_id = result["winner_id"]
+            survivor = store.get_claim(survivor_id, include_citations=True)
+            winner = survivor if survivor is not None else contender
         else:
             failed += 1
 

{memorymaster-3.26.0 → memorymaster-3.28.0}/memorymaster/candidate_dedupe.py

@@ -90,6 +90,14 @@ def _has_fts5_table(conn: sqlite3.Connection) -> bool:
     return row is not None
 
 
+# Statuses a claim may have and still be a valid "canonical" target to dedupe
+# a fresh candidate against. A retired (archived), replaced (superseded), or
+# contested (conflicted) claim must NOT be treated as the canonical survivor —
+# archiving a newer candidate in favour of one of those drops live information
+# in favour of a dead/contested row.
+_CANONICAL_DEDUPE_STATUSES = ("confirmed", "candidate", "stale")
+
+
 def fts_candidates_in_scope(
     conn: sqlite3.Connection,
     *,
@@ -101,7 +109,11 @@ def fts_candidates_in_scope(
     """Return list of (id, text, status) candidate matches via FTS5 OR-query.
 
     Empty list if FTS5 isn't present, scope is empty, or there are no matches.
-    Excludes archived claims and the candidate itself.
+    Excludes the candidate itself and any claim whose status is not a valid
+    canonical-dedupe target (archived / superseded / conflicted) — MED audit
+    fix: a fresh candidate must never be archived as a duplicate of a retired,
+    replaced, or contested claim, which would drop the possibly-newer candidate
+    in favour of a dead one.
     """
     if not text or not text.strip() or not scope:
         return []
@@ -109,19 +121,20 @@ def fts_candidates_in_scope(
         return []
 
     fts_query = _escape_fts5_query(text)
+    status_placeholders = ", ".join("?" for _ in _CANONICAL_DEDUPE_STATUSES)
     rows = conn.execute(
-        """
+        f"""
         SELECT c.id, c.text, c.status
         FROM claims c
         JOIN claims_fts ON claims_fts.rowid = c.id
         WHERE claims_fts MATCH ?
           AND c.scope = ?
           AND c.id <> ?
-          AND c.status <> 'archived'
+          AND c.status IN ({status_placeholders})
         ORDER BY bm25(claims_fts) ASC
         LIMIT ?
         """,
-        (fts_query, scope, exclude_id, limit),
+        (fts_query, scope, exclude_id, *_CANONICAL_DEDUPE_STATUSES, limit),
     ).fetchall()
 
     return [(int(r[0]), r[1] or "", r[2] or "") for r in rows]

{memorymaster-3.26.0 → memorymaster-3.28.0}/memorymaster/cli.py

@@ -187,6 +187,19 @@ def build_parser() -> argparse.ArgumentParser:
     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")
 
+    recall_analysis = sub.add_parser(
+        "recall-analysis",
+        help="Explain WHY claims ranked where they did (per-component score breakdown)",
+    )
+    recall_analysis.add_argument("--query", required=True, help="Query text to analyze")
+    recall_analysis.add_argument("--mode", choices=list(RETRIEVAL_MODES), default="hybrid", help="Retrieval mode (legacy or hybrid)")
+    recall_analysis.add_argument("--limit", type=int, default=10, help="Maximum rows")
+    recall_analysis.add_argument("--profile", choices=list(RETRIEVAL_PROFILES), default=None, help="Per-query hybrid retrieval profile")
+    recall_analysis.add_argument("--include-candidates", action="store_true", help="Also analyze candidate (unverified) claims")
+    recall_analysis.add_argument("--allow-sensitive", action="store_true", help="Include claims that look sensitive")
+    recall_analysis.add_argument("--scope-allowlist", default="", help="Comma-separated scopes to include")
+    # JSON output uses the global --json/-j flag (dest=json_output).
+
     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")
     context.add_argument("--budget", type=int, default=4000, help="Maximum token budget (default: 4000)")
@@ -361,6 +374,14 @@ def build_parser() -> argparse.ArgumentParser:
     links_cmd.add_argument("claim_id", help="Claim numeric id or human_id")
     links_cmd.add_argument("--type", dest="link_type", choices=list(CLAIM_LINK_TYPES), default=None, help="Filter by link type")
 
+    paths_cmd = sub.add_parser("query-paths", help="BFS path query over claim links (provenance/conflict/impact)")
+    paths_cmd.add_argument("--claim-id", dest="claim_id", required=True, help="Start claim numeric id or human_id")
+    paths_cmd.add_argument("--edge-type", dest="edge_type", choices=list(CLAIM_LINK_TYPES), default=None, help="Filter traversal to one link type (default: all)")
+    paths_cmd.add_argument("--direction", choices=["in", "out", "both"], default="both", help="in=provenance, out=impact, both (default)")
+    paths_cmd.add_argument("--max-hops", dest="max_hops", type=int, default=2, help="BFS depth, clamped to 5 (default: 2)")
+    paths_cmd.add_argument("--include-stale", dest="include_stale", action="store_true", help="Include stale claims in results")
+    paths_cmd.add_argument("--include-conflicted", dest="include_conflicted", action="store_true", help="Include conflicted claims in results")
+
     resolve_conflicts_cmd = sub.add_parser("resolve-conflicts", help="Detect and auto-resolve conflicting claims (same subject+predicate, different object_value)")
     resolve_conflicts_cmd.add_argument("--dry-run", action="store_true", help="Detect conflicts but do not apply transitions")
     resolve_conflicts_cmd.add_argument("--limit", type=int, default=500, help="Maximum claims to scan for conflicts")
@@ -465,6 +486,12 @@ 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)")
 
+    export_rules_cmd = sub.add_parser("export-rules", help="Export mined rule-shaped claims as json/csv/markdown (v3.28)")
+    export_rules_cmd.add_argument("--format", choices=["json", "csv", "markdown"], default="json", help="Output format (default: json)")
+    export_rules_cmd.add_argument("--min-confidence", dest="min_confidence", type=float, default=0.0, help="Only export rules at/above this confidence (default: 0.0)")
+    export_rules_cmd.add_argument("--status", default=None, help="Only export rules with this claim status (default: all statuses)")
+    export_rules_cmd.add_argument("--limit", type=int, default=500, help="Max rules to export (default: 500)")
+
     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)")

{memorymaster-3.26.0 → memorymaster-3.28.0}/memorymaster/cli_handlers_basic.py

@@ -231,6 +231,34 @@ def _handle_link_commands(args: argparse.Namespace, service, parser: argparse.Ar
         return 0
 
 
+def _handle_query_paths(args: argparse.Namespace, service, parser: argparse.ArgumentParser, effective_db: str = "") -> int:
+    """Handle the query-paths subcommand: BFS path query over claim links."""
+    t0 = time.perf_counter()
+    rows = service.query_claim_paths(
+        args.claim_id,
+        edge_type=getattr(args, "edge_type", None),
+        direction=getattr(args, "direction", "both"),
+        max_hops=getattr(args, "max_hops", 2),
+        include_stale=getattr(args, "include_stale", False),
+        include_conflicted=getattr(args, "include_conflicted", False),
+    )
+    elapsed_ms = (time.perf_counter() - t0) * 1000
+    if args.json_output:
+        print(_json_envelope({"rows": len(rows), "paths": rows}, total=len(rows), query_ms=elapsed_ms))
+        return 0
+    if not rows:
+        print(f"No paths found from claim {args.claim_id}.")
+        return 0
+    print(f"claim {args.claim_id} ({getattr(args, 'direction', 'both')}, max {getattr(args, 'max_hops', 2)} hops)")
+    for row in rows:
+        claim = row["claim"]
+        chain = " > ".join(row.get("edge_chain", [])) or "?"
+        text = str(claim.get("text", ""))[:80]
+        print(f"{'  ' * row['depth']}|-[{chain}] #{claim.get('id')} "
+              f"(conf={row.get('path_confidence', 0.0):.2f}) {text}")
+    return 0
+
+
 def _handle_stealth_status(args: argparse.Namespace, service, parser: argparse.ArgumentParser, effective_db: str) -> int:
     t0 = time.perf_counter()
     stealth_path = Path.cwd() / STEALTH_DB_NAME
@@ -852,10 +880,19 @@ def _print_score_explanation(breakdown: dict | None) -> None:
 
 
 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")
+    allow_sensitive = resolve_allow_sensitive_access(
+        allow_sensitive=args.allow_sensitive, context="cli.query"
+    )
     if getattr(args, "as_of", ""):
         t0 = time.perf_counter()
         claims = service.store.query_as_of(args.as_of)
+        # Parity with the non-as-of path: never surface sensitive-visibility
+        # claims in plaintext unless allow_sensitive was actually granted.
+        if not allow_sensitive:
+            claims = [
+                c for c in claims
+                if (getattr(c, "visibility", "public") or "public").strip().lower() != "sensitive"
+            ]
         elapsed_ms = (time.perf_counter() - t0) * 1000
         if args.json_output:
             print(_json_envelope([_claim_to_dict(c) for c in claims], total=len(claims), query_ms=elapsed_ms))
@@ -901,6 +938,62 @@ def _handle_query(args: argparse.Namespace, service, parser: argparse.ArgumentPa
     return 0
 
 
+def _print_recall_analysis(analysis: dict) -> None:
+    """Render the recall-analysis breakdown for humans (non-JSON path)."""
+    w = analysis.get("weights", {})
+    rw = w.get("retrieval_weights", {})
+    print(f"query: {analysis.get('query', '')!r}  mode={analysis.get('mode')}  "
+          f"profile={analysis.get('profile')}  rows={analysis.get('rows', 0)}")
+    print(f"weights(l,c,f,v)=({rw.get('lexical')},{rw.get('confidence')},"
+          f"{rw.get('freshness')},{rw.get('vector')})  "
+          f"floor_ratio={w.get('boost_floor_ratio')}  pinned_bonus={w.get('pinned_bonus')}")
+    if w.get("profile_override"):
+        print(f"profile_override: {w['profile_override']}")
+    for rank, entry in enumerate(analysis.get("results", []), start=1):
+        bd = entry.get("breakdown") or {}
+        comp = bd.get("components", {})
+        contrib = bd.get("contributions", {})
+        gate = "GATED" if bd.get("floor_gated") else "applied"
+        print(f"#{rank} claim={entry.get('claim_id')} ({entry.get('human_id')}) "
+              f"score={entry.get('score', 0.0):.3f} tier={entry.get('tier')} "
+              f"pinned={int(entry.get('pinned', False))}")
+        print(f"    components: lex={comp.get('lexical', 0.0):.3f} "
+              f"conf={comp.get('confidence', 0.0):.3f} fresh={comp.get('freshness', 0.0):.3f} "
+              f"vec={comp.get('vector', 0.0):.3f}")
+        print(f"    contributions: lex={contrib.get('lexical', 0.0):+.3f} "
+              f"vec={contrib.get('vector', 0.0):+.3f} conf={contrib.get('confidence', 0.0):+.3f} "
+              f"fresh={contrib.get('freshness', 0.0):+.3f} "
+              f"tier={contrib.get('tier_bonus', 0.0):+.3f} pin={contrib.get('pinned_bonus', 0.0):+.3f}")
+        print(f"    relevance={bd.get('relevance_subtotal', 0.0):.3f} "
+              f"boosts={bd.get('boosts_subtotal', 0.0):+.3f} [{gate}] "
+              f"-> final={bd.get('final_score', 0.0):.3f}")
+    rankings = analysis.get("component_rankings", {})
+    if rankings:
+        print("component rankings (best-first claim ids):")
+        for comp_name, ids in rankings.items():
+            print(f"    {comp_name}: {ids}")
+
+
+def _handle_recall_analysis(args: argparse.Namespace, service, parser: argparse.ArgumentParser, effective_db: str) -> int:
+    resolve_allow_sensitive_access(allow_sensitive=args.allow_sensitive, context="cli.recall-analysis")
+    t0 = time.perf_counter()
+    analysis = service.recall_analysis(
+        query_text=args.query,
+        limit=args.limit,
+        retrieval_mode=args.mode,
+        include_candidates=getattr(args, "include_candidates", False),
+        retrieval_profile=getattr(args, "profile", None),
+        allow_sensitive=args.allow_sensitive,
+        scope_allowlist=parse_scope_allowlist(args.scope_allowlist),
+    )
+    elapsed_ms = (time.perf_counter() - t0) * 1000
+    if args.json_output:
+        print(_json_envelope(analysis, total=analysis.get("rows", 0), query_ms=elapsed_ms))
+    else:
+        _print_recall_analysis(analysis)
+    return 0
+
+
 def _handle_context(args: argparse.Namespace, service, parser: argparse.ArgumentParser, effective_db: str) -> int:
     resolve_allow_sensitive_access(allow_sensitive=args.allow_sensitive, context="cli.context")
     t0 = time.perf_counter()