memorymaster 3.13.0__tar.gz → 3.14.0__tar.gz

{memorymaster-3.13.0/memorymaster.egg-info → memorymaster-3.14.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: memorymaster
-Version: 3.13.0
+Version: 3.14.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
@@ -61,29 +61,23 @@ MemoryMaster prevents the #1 problem with agent memory: **drift, stale assumptio
 
 ## Architecture
 
+MemoryMaster is layered around MCP/CLI entry points, the `MemoryService` facade, SQLite/Postgres
+storage, optional Qdrant vector search, scheduled jobs, and the Obsidian wiki/vault layer. The
+canonical ingest path is:
+
+```text
+MCP/CLI -> sensitivity filter -> MemoryService.ingest -> store write -> FTS5 index
 ```
-┌─────────────────────────────────────────────────────────────────┐
-│                        Agent Runtime                            │
-│  (Claude Code / Codex / any MCP-compatible agent)               │
-└────────────┬────────────────────────────────┬───────────────────┘
-             │ MCP (24 tools)                 │ CLI (86 commands)
-             v                                v
-┌─────────────────────────────────────────────────────────────────┐
-│                      MemoryMaster Core                          │
-│  ┌──────────┐  ┌───────────┐  ┌──────────┐  ┌───────────────┐  │
-│  │ Ingestor │  │ Extractor │  │ Validator │  │ State Engine  │  │
-│  │ (events) │->│ (claims)  │->│ (probes)  │->│ (6-state FSM) │  │
-│  └──────────┘  └───────────┘  └──────────┘  └───────────────┘  │
-│  ┌──────────┐  ┌───────────┐  ┌──────────┐  ┌───────────────┐  │
-│  │ Retrieval│  │ Compactor │  │ Steward  │  │  Dashboard    │  │
-│  │ (hybrid) │  │ (archive) │  │ (govern) │  │  (HTML+SSE)   │  │
-│  └──────────┘  └───────────┘  └──────────┘  └───────────────┘  │
-└────────┬──────────────┬──────────────┬──────────┬───────────────┘
-         v              v              v          v
-   SQLite/Postgres   Qdrant      Ollama/CLI    Claude Code
-                    (vectors)   (LLM stack)   Auto Dream + Vault
+
+The query path is:
+
+```text
+query_memory -> MemoryService.query -> storage reads + optional Qdrant candidates -> ranked context
 ```
 
+See [docs/architecture.md](docs/architecture.md) for the current module map, data-flow details,
+recent PR status, and sensitivity-filter invariants.
+
 ## Key features
 
 - **6-state lifecycle**: `candidate` → `confirmed` → `stale` → `superseded` → `conflicted` → `archived`
@@ -104,18 +98,20 @@ Full feature index lives in [`docs/handbook.md`](docs/handbook.md).
 
 ## Prerequisites
 
-**Required**
+**Required (the package won't function without these)**
 
 - Python **3.10+** with `pip`
 - Claude Code, Codex, or any MCP-compatible agent
+- **An LLM provider** — pick one: Claude Code OAuth (free if you're a subscriber, set `MEMORYMASTER_LLM_PROVIDER=claude_cli`), a free Gemini API key from [aistudio.google.com](https://aistudio.google.com), OpenAI, Anthropic API, or local Ollama. The steward, auto-ingest, and wiki-absorb cycles all need an LLM — without one, claims pile up as `candidate` and never get validated, deduped, or compiled into the wiki.
+
+**Strongly recommended (you'll lose ~80% of the value without these)**
+
+- **Node.js 18+** for [graphify](https://github.com/wolverin0/graphify) and [GitNexus](https://github.com/wolverin0/gitnexus) — these are the cached intelligence layers that make MemoryMaster cheap to query. Without them, every "what does this codebase do?" question burns tokens cold-exploring files the graph already mapped. The `intelligence-first` workflow in `CLAUDE.md` assumes both are installed.
+- **Obsidian 1.6+** with the [Bases](https://help.obsidian.md/Plugins/Bases) core plugin — the wiki engine writes plain Markdown so any editor works, but Obsidian's backlinks, graph view, and Bases dashboards are how you actually navigate `wiki-absorb` output. Without Obsidian, the wiki is just a folder of files.
 
-**Optional**
+**Optional (nice to have)**
 
-- **Already a Claude Code subscriber?** No API key needed — set `MEMORYMASTER_LLM_PROVIDER=claude_cli` and the steward + auto-ingest hooks will use your existing OAuth via the local `claude --print` binary
-- A free Gemini API key from [aistudio.google.com](https://aistudio.google.com) — powers the auto-ingest hook at ~zero cost
-- **Node.js 18+** for graphify and GitNexus
-- **Obsidian 1.6+** with the Bases core plugin (for visual wiki browsing)
-- **Docker** for Qdrant (SQLite FTS5 is the default and works out of the box)
+- **Docker** for Qdrant — vector retrieval. SQLite FTS5 is the default and works out of the box; add Qdrant when you want semantic recall on top of keyword search.
 
 ## Quick start
 

{memorymaster-3.13.0 → memorymaster-3.14.0}/README.md

@@ -17,29 +17,23 @@ MemoryMaster prevents the #1 problem with agent memory: **drift, stale assumptio
 
 ## Architecture
 
+MemoryMaster is layered around MCP/CLI entry points, the `MemoryService` facade, SQLite/Postgres
+storage, optional Qdrant vector search, scheduled jobs, and the Obsidian wiki/vault layer. The
+canonical ingest path is:
+
+```text
+MCP/CLI -> sensitivity filter -> MemoryService.ingest -> store write -> FTS5 index
 ```
-┌─────────────────────────────────────────────────────────────────┐
-│                        Agent Runtime                            │
-│  (Claude Code / Codex / any MCP-compatible agent)               │
-└────────────┬────────────────────────────────┬───────────────────┘
-             │ MCP (24 tools)                 │ CLI (86 commands)
-             v                                v
-┌─────────────────────────────────────────────────────────────────┐
-│                      MemoryMaster Core                          │
-│  ┌──────────┐  ┌───────────┐  ┌──────────┐  ┌───────────────┐  │
-│  │ Ingestor │  │ Extractor │  │ Validator │  │ State Engine  │  │
-│  │ (events) │->│ (claims)  │->│ (probes)  │->│ (6-state FSM) │  │
-│  └──────────┘  └───────────┘  └──────────┘  └───────────────┘  │
-│  ┌──────────┐  ┌───────────┐  ┌──────────┐  ┌───────────────┐  │
-│  │ Retrieval│  │ Compactor │  │ Steward  │  │  Dashboard    │  │
-│  │ (hybrid) │  │ (archive) │  │ (govern) │  │  (HTML+SSE)   │  │
-│  └──────────┘  └───────────┘  └──────────┘  └───────────────┘  │
-└────────┬──────────────┬──────────────┬──────────┬───────────────┘
-         v              v              v          v
-   SQLite/Postgres   Qdrant      Ollama/CLI    Claude Code
-                    (vectors)   (LLM stack)   Auto Dream + Vault
+
+The query path is:
+
+```text
+query_memory -> MemoryService.query -> storage reads + optional Qdrant candidates -> ranked context
 ```
 
+See [docs/architecture.md](docs/architecture.md) for the current module map, data-flow details,
+recent PR status, and sensitivity-filter invariants.
+
 ## Key features
 
 - **6-state lifecycle**: `candidate` → `confirmed` → `stale` → `superseded` → `conflicted` → `archived`
@@ -60,18 +54,20 @@ Full feature index lives in [`docs/handbook.md`](docs/handbook.md).
 
 ## Prerequisites
 
-**Required**
+**Required (the package won't function without these)**
 
 - Python **3.10+** with `pip`
 - Claude Code, Codex, or any MCP-compatible agent
+- **An LLM provider** — pick one: Claude Code OAuth (free if you're a subscriber, set `MEMORYMASTER_LLM_PROVIDER=claude_cli`), a free Gemini API key from [aistudio.google.com](https://aistudio.google.com), OpenAI, Anthropic API, or local Ollama. The steward, auto-ingest, and wiki-absorb cycles all need an LLM — without one, claims pile up as `candidate` and never get validated, deduped, or compiled into the wiki.
+
+**Strongly recommended (you'll lose ~80% of the value without these)**
+
+- **Node.js 18+** for [graphify](https://github.com/wolverin0/graphify) and [GitNexus](https://github.com/wolverin0/gitnexus) — these are the cached intelligence layers that make MemoryMaster cheap to query. Without them, every "what does this codebase do?" question burns tokens cold-exploring files the graph already mapped. The `intelligence-first` workflow in `CLAUDE.md` assumes both are installed.
+- **Obsidian 1.6+** with the [Bases](https://help.obsidian.md/Plugins/Bases) core plugin — the wiki engine writes plain Markdown so any editor works, but Obsidian's backlinks, graph view, and Bases dashboards are how you actually navigate `wiki-absorb` output. Without Obsidian, the wiki is just a folder of files.
 
-**Optional**
+**Optional (nice to have)**
 
-- **Already a Claude Code subscriber?** No API key needed — set `MEMORYMASTER_LLM_PROVIDER=claude_cli` and the steward + auto-ingest hooks will use your existing OAuth via the local `claude --print` binary
-- A free Gemini API key from [aistudio.google.com](https://aistudio.google.com) — powers the auto-ingest hook at ~zero cost
-- **Node.js 18+** for graphify and GitNexus
-- **Obsidian 1.6+** with the Bases core plugin (for visual wiki browsing)
-- **Docker** for Qdrant (SQLite FTS5 is the default and works out of the box)
+- **Docker** for Qdrant — vector retrieval. SQLite FTS5 is the default and works out of the box; add Qdrant when you want semantic recall on top of keyword search.
 
 ## Quick start
 

{memorymaster-3.13.0 → memorymaster-3.14.0}/memorymaster/_storage_lifecycle.py

@@ -23,14 +23,14 @@ from memorymaster.models import (
     validate_transition_event_type,
 )
 
-logger = logging.getLogger(__name__)
-
 from memorymaster._storage_shared import (
     EVENT_HASH_ALGO,
     ConcurrentModificationError,
     utc_now,
 )
 
+logger = logging.getLogger(__name__)
+
 
 class _LifecycleMixin:
 
@@ -102,14 +102,64 @@ class _LifecycleMixin:
         old_claim = self.get_claim(old_claim_id, include_citations=False)
         if old_claim is None:
             return
-        self.apply_status_transition(
-            old_claim,
-            to_status="superseded",
-            reason=reason,
-            event_type="supersession",
-            replaced_by_claim_id=new_claim_id,
-        )
-        self.set_supersedes(new_claim_id, old_claim_id)
+        if old_claim.status == "superseded" or old_claim.replaced_by_claim_id is not None:
+            raise ConcurrentModificationError(
+                f"Claim {old_claim_id} was already superseded. Reload and retry."
+            )
+
+        now = utc_now()
+        with self.connect() as conn:
+            target = conn.execute(
+                "SELECT supersedes_claim_id FROM claims WHERE id = ?",
+                (new_claim_id,),
+            ).fetchone()
+            if target is None:
+                raise ValueError(f"Replacement claim {new_claim_id} does not exist.")
+            if target["supersedes_claim_id"] not in {None, old_claim_id}:
+                raise ConcurrentModificationError(
+                    f"Claim {new_claim_id} already supersedes another claim. Reload and retry."
+                )
+
+            cur = conn.execute(
+                """
+                UPDATE claims
+                SET status = 'superseded', updated_at = ?, replaced_by_claim_id = ?,
+                    version = version + 1, valid_until = COALESCE(?, valid_until)
+                WHERE id = ? AND version = ? AND status != 'superseded'
+                    AND replaced_by_claim_id IS NULL
+                """,
+                (now, new_claim_id, now, old_claim_id, old_claim.version),
+            )
+            if cur.rowcount == 0:
+                raise ConcurrentModificationError(
+                    f"Claim {old_claim_id} was modified by another writer. Reload and retry."
+                )
+
+            cur = conn.execute(
+                """
+                UPDATE claims
+                SET supersedes_claim_id = ?, updated_at = ?
+                WHERE id = ? AND (supersedes_claim_id IS NULL OR supersedes_claim_id = ?)
+                """,
+                (old_claim_id, now, new_claim_id, old_claim_id),
+            )
+            if cur.rowcount == 0:
+                conn.rollback()
+                raise ConcurrentModificationError(
+                    f"Claim {new_claim_id} was modified by another writer. Reload and retry."
+                )
+
+            self._insert_event_row(
+                conn,
+                claim_id=old_claim.id,
+                event_type="supersession",
+                from_status=old_claim.status,
+                to_status="superseded",
+                details=reason,
+                payload_json=json.dumps({"replaced_by_claim_id": new_claim_id}),
+                created_at=now,
+            )
+            conn.commit()
 
 
     def delete_old_events(self, retain_days: int) -> int:

{memorymaster-3.13.0 → memorymaster-3.14.0}/memorymaster/auto_resolver.py

@@ -3,27 +3,25 @@
 When two claims contradict (same subject/predicate, different object_value),
 asks an LLM to evaluate which one has stronger evidence and should be kept.
 
-Uses Ollama or any OpenAI-compatible endpoint. The loser gets superseded,
-not deleted — preserving full audit trail.
+Provider routing goes through `memorymaster.llm_provider.call_llm`, which
+honors `MEMORYMASTER_LLM_PROVIDER` (claude_cli / google / openai / anthropic
+/ ollama) instead of the previous hardcoded Ollama-only path. The loser
+gets superseded, not deleted — preserving full audit trail.
 """
 
 from __future__ import annotations
 
 import json
 import logging
-import os
-import urllib.error
-import urllib.request
 from typing import Any
 
+from memorymaster._storage_shared import ConcurrentModificationError
 from memorymaster.lifecycle import transition_claim
+from memorymaster.llm_provider import call_llm
 from memorymaster.models import Claim
 
 logger = logging.getLogger(__name__)
 
-DEFAULT_OLLAMA_URL = "http://localhost:11434"
-DEFAULT_MODEL = "deepseek-coder-v2:16b"
-
 RESOLUTION_PROMPT = """You are a memory quality evaluator. Two claims contradict each other.
 Decide which one should be KEPT based on:
 1. Recency (newer information is usually more accurate)
@@ -47,49 +45,34 @@ Return JSON only: {{"winner": "A" or "B", "reason": "brief explanation"}}"""
 
 
 def _llm_evaluate(prompt: str, model: str = "", base_url: str = "") -> dict:
-    """Call LLM and parse JSON response.
+    """Ask the configured LLM to pick the winner and parse its JSON response.
 
-    Returns empty dict {} if LLM returns invalid JSON or connection fails.
+    Returns empty dict {} if the LLM returns invalid JSON or the call fails.
+    The `model` and `base_url` kwargs are kept for backwards compatibility but
+    are no longer consulted — provider routing is centralized in llm_provider.
     """
-    url = (base_url or os.environ.get("OLLAMA_URL") or DEFAULT_OLLAMA_URL).rstrip("/")
-    mdl = model or os.environ.get("RESOLVER_LLM_MODEL") or DEFAULT_MODEL
-
-    body = json.dumps({
-        "model": mdl,
-        "messages": [{"role": "user", "content": prompt}],
-        "stream": False,
-        "options": {"temperature": 0.1, "num_predict": 200},
-    }).encode()
-
-    req = urllib.request.Request(
-        f"{url}/api/chat",
-        data=body,
-        headers={"Content-Type": "application/json"},
-        method="POST",
-    )
     try:
-        with urllib.request.urlopen(req, timeout=30) as resp:
-            result = json.loads(resp.read())
-            raw = result.get("message", {}).get("content", "")
-            # Parse JSON from response
-            text = raw.strip()
-            if text.startswith("```"):
-                lines = text.split("\n")
-                lines = [line for line in lines if not line.strip().startswith("```")]
-                text = "\n".join(lines)
-            try:
-                parsed = json.loads(text)
-                if not isinstance(parsed, dict):
-                    logger.warning("LLM returned non-dict JSON: %s", type(parsed))
-                    return {}
-                return parsed
-            except json.JSONDecodeError as exc:
-                logger.warning("LLM returned invalid JSON: %s (text: %s)", exc, text[:100])
-                return {}
+        raw = call_llm(prompt, "")
     except Exception as exc:
         logger.warning("LLM conflict evaluation failed: %s", exc)
         return {}
 
+    text = (raw or "").strip()
+    if text.startswith("```"):
+        lines = [line for line in text.split("\n") if not line.strip().startswith("```")]
+        text = "\n".join(lines)
+
+    try:
+        parsed = json.loads(text)
+    except json.JSONDecodeError as exc:
+        logger.warning("LLM returned invalid JSON: %s (text: %s)", exc, text[:100])
+        return {}
+
+    if not isinstance(parsed, dict):
+        logger.warning("LLM returned non-dict JSON: %s", type(parsed))
+        return {}
+    return parsed
+
 
 def _cite_summary(claim: Claim) -> str:
     """Summarize citations for LLM prompt."""
@@ -132,7 +115,7 @@ def resolve_conflict_pair(
     loser = claim_b if winner_letter == "A" else claim_a
 
     try:
-        transition_claim(
+        updated = transition_claim(
             store,
             claim_id=loser.id,
             to_status="superseded",
@@ -140,12 +123,35 @@ def resolve_conflict_pair(
             event_type="validator",
             replaced_by_claim_id=winner.id,
         )
+        current_replacement_id = getattr(updated, "replaced_by_claim_id", None)
+        if current_replacement_id != winner.id:
+            return {
+                "resolved": False,
+                "reason": "lost_race",
+                "winner_id": winner.id,
+                "loser_id": loser.id,
+                "current_replacement_id": current_replacement_id,
+            }
+        if hasattr(store, "set_supersedes"):
+            store.set_supersedes(winner.id, loser.id)
         return {
             "resolved": True,
             "winner_id": winner.id,
             "loser_id": loser.id,
             "reason": reason,
         }
+    except ConcurrentModificationError as exc:
+        current = store.get_claim(loser.id, include_citations=False)
+        if current is not None and current.status == "superseded":
+            return {
+                "resolved": False,
+                "reason": "lost_race",
+                "winner_id": winner.id,
+                "loser_id": loser.id,
+                "current_replacement_id": current.replaced_by_claim_id,
+            }
+        logger.warning("Failed to resolve conflict %d vs %d: %s", claim_a.id, claim_b.id, exc)
+        return {"resolved": False, "reason": str(exc)}
     except Exception as exc:
         logger.warning("Failed to resolve conflict %d vs %d: %s", claim_a.id, claim_b.id, exc)
         return {"resolved": False, "reason": str(exc)}

{memorymaster-3.13.0 → memorymaster-3.14.0}/memorymaster/claim_verifier.py

@@ -16,7 +16,6 @@ import os
 import re
 import sqlite3
 import subprocess
-from pathlib import Path
 from typing import Any
 
 logger = logging.getLogger(__name__)

{memorymaster-3.13.0 → memorymaster-3.14.0}/memorymaster/cli.py

@@ -13,13 +13,29 @@ from memorymaster.cli_helpers import (  # noqa: F401 — re-export for backward
     parse_citation,
     parse_scope_allowlist,
 )
-from memorymaster.context_optimizer import OUTPUT_FORMATS
+from memorymaster.context_optimizer import OUTPUT_FORMATS, PROVIDERS
 from memorymaster.models import CLAIM_LINK_TYPES, CLAIM_STATUSES, VOLATILITY_LEVELS
 from memorymaster.retrieval import RETRIEVAL_MODES
-from memorymaster.service import MemoryService
+from memorymaster.service import RETRIEVAL_PROFILES, MemoryService
 
 # Import dispatch table — this also triggers the late dispatch additions for daily/dream/ghost
 from memorymaster.cli_handlers_curation import COMMAND_HANDLERS
+from memorymaster.cli_handlers_basic import (
+    _handle_decay,
+    _handle_entity_graph_export,
+    _handle_recompute_confidence_priors,
+    _handle_wiki_suggest_links,
+    handle_mcp_usage_report,
+)
+
+
+COMMAND_HANDLERS["entity-graph-export"] = _handle_entity_graph_export
+COMMAND_HANDLERS["recompute-confidence-priors"] = _handle_recompute_confidence_priors
+COMMAND_HANDLERS["wiki-suggest-links"] = _handle_wiki_suggest_links
+COMMAND_HANDLERS["decay"] = _handle_decay
+COMMAND_HANDLERS["mcp-usage-report"] = (
+    lambda args, service, parser, effective_db: handle_mcp_usage_report(args, effective_db)
+)
 
 
 def build_parser() -> argparse.ArgumentParser:
@@ -147,6 +163,7 @@ def build_parser() -> argparse.ArgumentParser:
     query.add_argument("--exclude-conflicted", action="store_true", help="Only return confirmed/stale")
     query.add_argument("--include-candidates", action="store_true", help="Also search candidate (unverified) claims")
     query.add_argument("--retrieval-mode", choices=list(RETRIEVAL_MODES), default="legacy", help="Retrieval mode (legacy SQL ordering or hybrid lexical/confidence/freshness ranking)")
+    query.add_argument("--profile", choices=list(RETRIEVAL_PROFILES), default=None, help="Per-query hybrid retrieval profile")
     query.add_argument("--allow-sensitive", action="store_true", help="Include claims that look sensitive (default excludes them)")
     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")
@@ -156,11 +173,13 @@ def build_parser() -> argparse.ArgumentParser:
     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)")
     context.add_argument("--format", dest="output_format", choices=list(OUTPUT_FORMATS), default="text", help="Output format: text (human-readable), xml (system prompt), json (structured)")
+    context.add_argument("--provider", choices=list(PROVIDERS), default=None, help="Provider-aware packing strategy")
     context.add_argument("--limit", type=int, default=100, help="Max candidate claims to rank")
     context.add_argument("--exclude-stale", action="store_true", help="Exclude stale claims")
     context.add_argument("--exclude-conflicted", action="store_true", help="Exclude conflicted claims")
     context.add_argument("--include-candidates", action="store_true", help="Include candidate (unverified) claims")
     context.add_argument("--retrieval-mode", choices=list(RETRIEVAL_MODES), default="hybrid", help="Retrieval mode (default: hybrid)")
+    context.add_argument("--profile", choices=list(RETRIEVAL_PROFILES), default=None, help="Per-query hybrid retrieval profile")
     context.add_argument("--allow-sensitive", action="store_true", help="Include sensitive claims")
     context.add_argument("--scope-allowlist", default="", help="Comma-separated scopes to include")
 
@@ -180,6 +199,7 @@ def build_parser() -> argparse.ArgumentParser:
     compact = sub.add_parser("compact", help="Archive stale/superseded/conflicted claims and trim old events")
     compact.add_argument("--retain-days", type=int, default=30, help="Days before archiving stale/superseded/conflicted claims")
     compact.add_argument("--event-retain-days", type=int, default=60, help="Days to retain event history")
+    compact.add_argument("--dry-run", action="store_true", help="Preview compaction without archiving claims, deleting events, or writing artifacts")
 
     compact_sum = sub.add_parser("compact-summaries", help="Summarize groups of archived claims into higher-level summary claims using LLM")
     compact_sum.add_argument("--provider", default="gemini", choices=["gemini", "openai", "anthropic", "ollama", "custom"], help="LLM provider (default: gemini)")
@@ -197,10 +217,24 @@ def build_parser() -> argparse.ArgumentParser:
     dedup = sub.add_parser("dedup", help="Detect and merge duplicate claims using embedding similarity")
     dedup.add_argument("--threshold", type=float, default=0.92, help="Cosine similarity threshold for duplicate detection (default: 0.92)")
     dedup.add_argument("--min-text-overlap", type=float, default=0.3, help="Minimum word-level Jaccard overlap as secondary gate (default: 0.3)")
+    dedup.add_argument("--limit", type=int, default=None, help="Maximum claims to scan, oldest first")
+    dedup.add_argument("--scope", default=None, help="Only scan claims with this exact scope")
     dedup.add_argument("--dry-run", action="store_true", help="Preview duplicates without archiving")
 
+    decay_cmd = sub.add_parser("decay", help="Apply confidence decay and mark low-confidence claims stale")
+    decay_cmd.add_argument("--limit", type=int, default=200, help="Maximum confirmed claims to process")
+    decay_cmd.add_argument("--stale-threshold", type=float, default=None, help="Confidence threshold below which claims become stale")
+    decay_cmd.add_argument("--dry-run", action="store_true", help="Preview confidence decay and stale transitions without writing")
+
     sub.add_parser("recompute-tiers", help="Recompute memory tiers (core/working/peripheral) for all claims")
 
+    confidence_priors = sub.add_parser(
+        "recompute-confidence-priors",
+        help="Write recommended initial-confidence priors from recent validator events",
+    )
+    confidence_priors.add_argument("--window-days", type=int, default=90, help="Number of recent event days to read")
+    confidence_priors.add_argument("--output", required=True, help="JSON report path to write")
+
     list_claims = sub.add_parser("list-claims", help="List claims")
     list_claims.add_argument("--status", choices=list(CLAIM_STATUSES), help="Filter by claim status")
     list_claims.add_argument("--limit", type=int, default=50, help="Maximum rows")
@@ -221,6 +255,10 @@ def build_parser() -> argparse.ArgumentParser:
     export_metrics.add_argument("--out-prom", default="artifacts/metrics/metrics.prom", help="Output path for Prometheus text metrics")
     export_metrics.add_argument("--out-json", default="artifacts/metrics/metrics_snapshot.json", help="Output path for structured metrics JSON snapshot")
 
+    mcp_usage = sub.add_parser("mcp-usage-report", help="Export MCP tool usage for a time window")
+    mcp_usage.add_argument("--since", default="7d", help="Window start: 7d, 30d, 1d, or ISO date")
+    mcp_usage.add_argument("--format", default="csv", help="Output format (default: csv)")
+
     review_queue = sub.add_parser("review-queue", help="Build conflict/stale review queue")
     review_queue.add_argument("--limit", type=int, default=100, help="Maximum claims scanned for queue")
     review_queue.add_argument("--exclude-stale", action="store_true", help="Exclude stale claims from queue")
@@ -390,6 +428,12 @@ def build_parser() -> argparse.ArgumentParser:
     wiki_freshness.add_argument("--below", type=float, default=None, help="Only show articles with freshness_score below this threshold (0-1)")
     wiki_freshness.add_argument("--threshold-days", type=int, default=None, help="Only show articles older than N days since last absorb (alias for --below)")
 
+    wiki_suggest = sub.add_parser("wiki-suggest-links", help="Suggest wiki article links from paragraph entities")
+    wiki_suggest.add_argument("--text", required=True, help="Current paragraph text")
+    wiki_suggest.add_argument("--wiki-root", default="obsidian-vault/wiki", help="Wiki root to scan for article slugs")
+    wiki_suggest.add_argument("--limit", type=int, default=10, help="Maximum suggestions")
+    wiki_suggest.add_argument("--hops", type=int, default=2, help="Maximum entity graph hops")
+
     mine_cmd = sub.add_parser("mine-transcript", help="Parse Claude Code transcripts into claims")
     mine_cmd.add_argument("--input", required=True, help="JSONL transcript file or directory")
     mine_cmd.add_argument("--scope", default="project", help="Scope for ingested claims")
@@ -405,6 +449,11 @@ def build_parser() -> argparse.ArgumentParser:
 
     sub.add_parser("entity-stats", help="Show entity graph statistics")
 
+    entity_graph_export = sub.add_parser("entity-graph-export", help="Export entity graph relationships as DOT or GraphML")
+    entity_graph_export.add_argument("--format", choices=["dot", "graphml"], required=True, help="Graph output format")
+    entity_graph_export.add_argument("--output", required=True, help="Output file path")
+    entity_graph_export.add_argument("--scope", default=None, help="Only export graph data linked to this claim scope")
+
     sub.add_parser("feedback-stats", help="Show feedback tracking and quality score statistics")
 
     sub.add_parser("quality-scores", help="Recompute quality scores for all claims")
@@ -487,7 +536,7 @@ def build_parser() -> argparse.ArgumentParser:
     entity_aliases_cmd.add_argument("entity_id", type=int, help="Entity ID")
     entity_aliases_cmd.add_argument("--add", default="", help="Add this alias to the entity")
 
-    entity_backfill = sub.add_parser("entity-backfill", help="Backfill entity_id on claims with subject but no entity")
+    sub.add_parser("entity-backfill", help="Backfill entity_id on claims with subject but no entity")
 
     return parser
 
@@ -499,7 +548,7 @@ def main(argv: list[str] | None = None) -> int:
     effective_db = _resolve_db_path(args)
 
     # Commands that don't need MemoryService run first; service is lazy-created once for all others.
-    _NO_SERVICE_COMMANDS = {"stealth-status", "export-metrics", "wiki-freshness"}
+    _NO_SERVICE_COMMANDS = {"stealth-status", "export-metrics", "wiki-freshness", "mcp-usage-report"}
 
     try:
         handler = COMMAND_HANDLERS.get(args.command)