memorymaster 3.14.0__tar.gz → 3.15.1__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: memorymaster
-Version: 3.14.0
+Version: 3.15.1
 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
@@ -17,6 +17,8 @@ Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
+Requires-Dist: requests>=2.31
+Requires-Dist: tenacity>=8.2
 Provides-Extra: postgres
 Requires-Dist: psycopg[binary]>=3.2; extra == "postgres"
 Provides-Extra: security
@@ -96,6 +98,20 @@ recent PR status, and sensitivity-filter invariants.
 
 Full feature index lives in [`docs/handbook.md`](docs/handbook.md).
 
+## Benchmarks
+
+**LongMemEval-S (N=500, retrieval-only)** — v3.15.0 now leads the publicly-reported numbers from [agentmemory](https://github.com/rohitg00/agentmemory) on R@5 and MRR, after wiring `sentence-transformers/all-MiniLM-L6-v2` into the bench harness (the v3.14 baseline was unintentionally BM25-only).
+
+![LongMemEval-S benchmark](docs/benchmark-longmemeval.svg)
+
+| Metric | v3.14.0 | **v3.15.0** | agentmemory | Δ vs agentmemory |
+|---|---|---|---|---|
+| Recall@5 | 0.894 | **0.966** | 0.952 | **+0.014** ★ |
+| Recall@10 | 0.942 | **0.984** | 0.986 | -0.002 |
+| MRR | 0.799 | **0.902** | 0.882 | **+0.020** ★ |
+
+Reproduce: `python tests/bench_longmemeval.py --retrieval-only`. Full methodology, experiment-by-experiment deltas (1 KEEP, 2 REVERT, 3 NULL), and the architectural findings that surfaced along the way live in [`docs/longmemeval-results.md`](docs/longmemeval-results.md) and [`docs/v315-experiments/`](docs/v315-experiments/). QA-accuracy pass (with judge) is deferred until provider quotas allow.
+
 ## Prerequisites
 
 **Required (the package won't function without these)**

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

@@ -52,6 +52,20 @@ recent PR status, and sensitivity-filter invariants.
 
 Full feature index lives in [`docs/handbook.md`](docs/handbook.md).
 
+## Benchmarks
+
+**LongMemEval-S (N=500, retrieval-only)** — v3.15.0 now leads the publicly-reported numbers from [agentmemory](https://github.com/rohitg00/agentmemory) on R@5 and MRR, after wiring `sentence-transformers/all-MiniLM-L6-v2` into the bench harness (the v3.14 baseline was unintentionally BM25-only).
+
+![LongMemEval-S benchmark](docs/benchmark-longmemeval.svg)
+
+| Metric | v3.14.0 | **v3.15.0** | agentmemory | Δ vs agentmemory |
+|---|---|---|---|---|
+| Recall@5 | 0.894 | **0.966** | 0.952 | **+0.014** ★ |
+| Recall@10 | 0.942 | **0.984** | 0.986 | -0.002 |
+| MRR | 0.799 | **0.902** | 0.882 | **+0.020** ★ |
+
+Reproduce: `python tests/bench_longmemeval.py --retrieval-only`. Full methodology, experiment-by-experiment deltas (1 KEEP, 2 REVERT, 3 NULL), and the architectural findings that surfaced along the way live in [`docs/longmemeval-results.md`](docs/longmemeval-results.md) and [`docs/v315-experiments/`](docs/v315-experiments/). QA-accuracy pass (with judge) is deferred until provider quotas allow.
+
 ## Prerequisites
 
 **Required (the package won't function without these)**

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

@@ -10,6 +10,7 @@ import json
 import logging
 import sqlite3
 from datetime import datetime, timedelta, timezone
+from typing import TYPE_CHECKING, Any
 
 from memorymaster.embeddings import EmbeddingProvider, cosine_similarity
 from memorymaster.models import (
@@ -33,6 +34,27 @@ logger = logging.getLogger(__name__)
 
 
 class _LifecycleMixin:
+    if TYPE_CHECKING:
+        def connect(self) -> sqlite3.Connection: ...
+
+        def get_claim(self, claim_id: int, include_citations: bool = True) -> Claim | None: ...
+
+        def _ensure_event_integrity_schema(self, conn: sqlite3.Connection) -> None: ...
+
+        def _ensure_embeddings_schema(self, conn: sqlite3.Connection) -> None: ...
+
+        def _insert_event_row(
+            self,
+            conn: sqlite3.Connection,
+            *,
+            claim_id: int | None,
+            event_type: str,
+            from_status: str | None,
+            to_status: str | None,
+            details: str | None,
+            payload_json: str | None,
+            created_at: str,
+        ) -> int: ...
 
     def apply_status_transition(
         self,
@@ -167,8 +189,8 @@ class _LifecycleMixin:
         return 0
 
 
-    def reconcile_integrity(self, *, fix: bool = False, limit: int = 500) -> dict[str, object]:
-        report: dict[str, object] = {
+    def reconcile_integrity(self, *, fix: bool = False, limit: int = 500) -> dict[str, Any]:
+        report: dict[str, Any] = {
             "checked_at": utc_now(),
             "fix_mode": bool(fix),
             "issues": {},

{memorymaster-3.14.0 → memorymaster-3.15.1}/memorymaster/_storage_read.py

@@ -9,6 +9,7 @@ from __future__ import annotations
 import logging
 import sqlite3
 from datetime import datetime, timedelta, timezone
+from typing import TYPE_CHECKING
 
 from memorymaster.models import (
     Citation,
@@ -22,6 +23,10 @@ logger = logging.getLogger(__name__)
 
 
 class _ReadMixin:
+    if TYPE_CHECKING:
+        def connect(self) -> sqlite3.Connection: ...
+
+        def init_db(self) -> None: ...
 
     def _check_idempotency(self, conn: sqlite3.Connection, idempotency_key: str | None) -> Claim | None:
         """Check if a claim with this idempotency key already exists. Returns existing claim or None."""

{memorymaster-3.14.0 → memorymaster-3.15.1}/memorymaster/_storage_schema.py

@@ -338,7 +338,8 @@ class _SchemaMixin:
                 predicate,
                 object_value,
                 content='claims',
-                content_rowid='id'
+                content_rowid='id',
+                tokenize='porter unicode61'
             )
             """
         )

{memorymaster-3.14.0 → memorymaster-3.15.1}/memorymaster/_storage_sources.py

@@ -8,7 +8,7 @@ from __future__ import annotations
 
 import json
 import sqlite3
-from typing import Any
+from typing import TYPE_CHECKING, Any
 
 from memorymaster._storage_shared import utc_now
 from memorymaster.models import (
@@ -51,6 +51,22 @@ def _bounded_confidence(confidence: float | None) -> float | None:
 
 
 class _SourceItemsMixin:
+    if TYPE_CHECKING:
+        def connect(self) -> sqlite3.Connection: ...
+
+        def _insert_event_row(
+            self,
+            conn: sqlite3.Connection,
+            *,
+            claim_id: int | None,
+            event_type: str,
+            from_status: str | None,
+            to_status: str | None,
+            details: str | None,
+            payload_json: str | None,
+            created_at: str,
+        ) -> int: ...
+
     def upsert_external_source(
         self,
         *,

{memorymaster-3.14.0 → memorymaster-3.15.1}/memorymaster/_storage_write_claims.py

@@ -9,21 +9,42 @@ from __future__ import annotations
 import json
 import logging
 import sqlite3
+from typing import TYPE_CHECKING
 
 from memorymaster.models import (
     CitationInput,
     Claim,
     validate_event_payload,
 )
-
-logger = logging.getLogger(__name__)
-
 from memorymaster._storage_shared import (
     utc_now,
 )
 
+logger = logging.getLogger(__name__)
+
 
 class _WriteClaimsMixin:
+    if TYPE_CHECKING:
+        def connect(self) -> sqlite3.Connection: ...
+
+        def _check_idempotency(self, conn: sqlite3.Connection, idempotency_key: str | None) -> Claim | None: ...
+
+        def get_claim(self, claim_id: int, include_citations: bool = True) -> Claim | None: ...
+
+        def _allocate_human_id(self, conn: sqlite3.Connection, subject: str | None, text: str, claim_id: int) -> str: ...
+
+        def _insert_event_row(
+            self,
+            conn: sqlite3.Connection,
+            *,
+            claim_id: int | None,
+            event_type: str,
+            from_status: str | None,
+            to_status: str | None,
+            details: str | None,
+            payload_json: str | None,
+            created_at: str,
+        ) -> int: ...
 
     def create_claim(
         self,

{memorymaster-3.14.0 → memorymaster-3.15.1}/memorymaster/config.py

@@ -46,6 +46,15 @@ MEMORYMASTER_PINNED_BONUS
     Score bonus applied to pinned claims during ranking.
     Default: ``0.03``
 
+MEMORYMASTER_SESSION_DIVERSITY_CAP
+    Maximum ranked results to keep per source session before applying the
+    final query limit. Set to ``0`` to disable.
+    Default: ``3``
+
+MEMORYMASTER_LLM_RERANK
+    Enable Gemini cross-encoder reranking over the top retrieval candidates.
+    Default: ``0``
+
 MEMORYMASTER_CONFIG_FILE
     Path to a JSON config file. Keys match attribute names on ``Config``.
 """
@@ -186,6 +195,8 @@ class Config:
     stale_threshold: float = 0.35
     conflict_margin: float = 0.08
     pinned_bonus: float = 0.03
+    session_diversity_cap: int = 3
+    llm_rerank: bool = False
 
     # --- Initial confidence priors calibrated from validator outcomes ---
     default_initial_confidence: float = DEFAULT_INITIAL_CONFIDENCE
@@ -330,6 +341,8 @@ def load_config(config_path: str | Path | None = None) -> Config:
     _apply_env_float(overrides, "MEMORYMASTER_STALE_THRESHOLD", "stale_threshold")
     _apply_env_float(overrides, "MEMORYMASTER_CONFLICT_MARGIN", "conflict_margin")
     _apply_env_float(overrides, "MEMORYMASTER_PINNED_BONUS", "pinned_bonus")
+    _apply_env_int(overrides, "MEMORYMASTER_SESSION_DIVERSITY_CAP", "session_diversity_cap")
+    _apply_env_bool(overrides, "MEMORYMASTER_LLM_RERANK", "llm_rerank")
 
     # Filter to only valid Config fields
     valid_fields = {f.name for f in Config.__dataclass_fields__.values()}
@@ -357,3 +370,17 @@ def _apply_env_float(overrides: dict[str, object], env_var: str, key: str) -> No
     if not raw:
         return
     overrides[key] = float(raw)
+
+
+def _apply_env_int(overrides: dict[str, object], env_var: str, key: str) -> None:
+    raw = os.environ.get(env_var, "").strip()
+    if not raw:
+        return
+    overrides[key] = int(raw)
+
+
+def _apply_env_bool(overrides: dict[str, object], env_var: str, key: str) -> None:
+    raw = os.environ.get(env_var, "").strip().lower()
+    if not raw:
+        return
+    overrides[key] = raw in {"1", "true", "yes", "on"}

memorymaster-3.15.1/memorymaster/llm_rerank.py

@@ -0,0 +1,216 @@
+"""LLM cross-encoder reranking for retrieval candidates."""
+
+from __future__ import annotations
+
+import logging
+import os
+import threading
+import time
+from collections.abc import Sequence
+from contextlib import contextmanager
+from typing import Any
+
+from tenacity import retry, retry_if_exception_type, stop_after_attempt, wait_exponential
+
+from memorymaster.llm_provider import call_llm, parse_json_response
+
+logger = logging.getLogger(__name__)
+
+_MAX_SNIPPET_CHARS = 300
+_LAST_CALL_AT = 0.0
+_RATE_LOCK = threading.Lock()
+_CONSECUTIVE_FAILURES = 0
+_DISABLED = False
+_STATS: dict[str, int] = {"attempts": 0, "successes": 0, "failures": 0, "disabled_fallbacks": 0}
+_PROMPT = """Score how relevant each candidate is to the question.
+
+Return STRICT JSON only: an array of [candidate_index, relevance_score] pairs.
+candidate_index must match the numbered candidate. relevance_score must be an integer from 0 to 100.
+Do not include prose or markdown."""
+
+
+class LLMRerankError(RuntimeError):
+    """Raised for retryable rerank judge failures."""
+
+
+@contextmanager
+def _temporary_llm_env(judge_model: str):
+    saved_provider = os.environ.get("MEMORYMASTER_LLM_PROVIDER")
+    saved_model = os.environ.get("MEMORYMASTER_LLM_MODEL")
+    saved_key_file = os.environ.get("MEMORYMASTER_KEY_FILE")
+    saved_key_rotation = os.environ.get("MEMORYMASTER_LLM_KEY_ROTATION")
+    try:
+        from memorymaster.key_rotator import clear_cache
+
+        clear_cache()
+        os.environ["MEMORYMASTER_LLM_PROVIDER"] = "google"
+        os.environ["MEMORYMASTER_LLM_MODEL"] = judge_model
+        os.environ["MEMORYMASTER_KEY_FILE"] = "__memorymaster_llm_rerank_no_key_file__"
+        os.environ["MEMORYMASTER_LLM_KEY_ROTATION"] = "0"
+        yield
+    finally:
+        if saved_provider is None:
+            os.environ.pop("MEMORYMASTER_LLM_PROVIDER", None)
+        else:
+            os.environ["MEMORYMASTER_LLM_PROVIDER"] = saved_provider
+        if saved_model is None:
+            os.environ.pop("MEMORYMASTER_LLM_MODEL", None)
+        else:
+            os.environ["MEMORYMASTER_LLM_MODEL"] = saved_model
+        if saved_key_file is None:
+            os.environ.pop("MEMORYMASTER_KEY_FILE", None)
+        else:
+            os.environ["MEMORYMASTER_KEY_FILE"] = saved_key_file
+        if saved_key_rotation is None:
+            os.environ.pop("MEMORYMASTER_LLM_KEY_ROTATION", None)
+        else:
+            os.environ["MEMORYMASTER_LLM_KEY_ROTATION"] = saved_key_rotation
+        clear_cache()
+
+
+def _min_interval_seconds() -> float:
+    raw = os.environ.get("MEMORYMASTER_LLM_RERANK_MIN_INTERVAL_SECONDS", "3.1").strip()
+    try:
+        return max(0.0, float(raw))
+    except ValueError:
+        return 3.1
+
+
+def _max_failures_before_disable() -> int:
+    raw = os.environ.get("MEMORYMASTER_LLM_RERANK_MAX_FAILURES", "1").strip()
+    try:
+        return max(1, int(raw))
+    except ValueError:
+        return 1
+
+
+def _pace_judge_call() -> None:
+    global _LAST_CALL_AT
+    min_interval = _min_interval_seconds()
+    if min_interval <= 0:
+        return
+    with _RATE_LOCK:
+        now = time.monotonic()
+        sleep_for = max(0.0, min_interval - (now - _LAST_CALL_AT))
+        if sleep_for > 0:
+            time.sleep(sleep_for)
+        _LAST_CALL_AT = time.monotonic()
+
+
+def _candidate_text(candidate: Any) -> str:
+    if isinstance(candidate, str):
+        return candidate
+    if isinstance(candidate, dict):
+        claim = candidate.get("claim")
+        if claim is not None:
+            return str(getattr(claim, "text", "") or "")
+        return str(candidate.get("text", "") or "")
+    return str(getattr(candidate, "text", "") or candidate)
+
+
+def _build_rerank_input(query: str, candidates: Sequence[Any]) -> str:
+    lines = [f"Question: {query.strip()}", "", "Candidates:"]
+    for idx, candidate in enumerate(candidates, start=1):
+        snippet = " ".join(_candidate_text(candidate).split())[:_MAX_SNIPPET_CHARS]
+        lines.append(f"{idx}. {snippet}")
+    return "\n".join(lines)
+
+
+@retry(
+    stop=stop_after_attempt(3),
+    wait=wait_exponential(min=10, max=60),
+    retry=retry_if_exception_type(LLMRerankError),
+    reraise=True,
+)
+def _call_rerank_judge(query: str, candidates: Sequence[Any], judge_model: str) -> str:
+    _pace_judge_call()
+    with _temporary_llm_env(judge_model):
+        response = call_llm(_PROMPT, _build_rerank_input(query, candidates))
+    if not response.strip():
+        raise LLMRerankError("empty rerank judge response")
+    return response
+
+
+def _score_entry(entry: Any) -> tuple[int, float] | None:
+    if isinstance(entry, dict):
+        raw_index = entry.get("candidate_index", entry.get("index"))
+        raw_score = entry.get("relevance_score", entry.get("score"))
+    elif isinstance(entry, (list, tuple)) and len(entry) >= 2:
+        raw_index, raw_score = entry[0], entry[1]
+    else:
+        return None
+    try:
+        index = int(raw_index)
+        score = float(raw_score)
+    except (TypeError, ValueError):
+        return None
+    return index, max(0.0, min(100.0, score))
+
+
+def _parse_scores(response: str, candidate_count: int) -> dict[int, float]:
+    scores: dict[int, float] = {}
+    for entry in parse_json_response(response):
+        parsed = _score_entry(entry)
+        if parsed is None:
+            continue
+        index, score = parsed
+        if 1 <= index <= candidate_count:
+            scores[index - 1] = score
+    return scores
+
+
+def get_rerank_stats() -> dict[str, int]:
+    return {**_STATS, "disabled": int(_DISABLED)}
+
+
+def rerank_temporarily_disabled() -> bool:
+    return _DISABLED
+
+
+def rerank_with_llm(
+    query: str,
+    candidates: list[Any],
+    top_k: int = 5,
+    judge_model: str = "gemini-2.5-flash",
+) -> list[Any]:
+    """Rerank candidates with a batched Gemini relevance judge.
+
+    Any judge failure returns the original ordering truncated to ``top_k``.
+    """
+    if top_k <= 0:
+        return []
+    if not query.strip() or not candidates:
+        return candidates[:top_k]
+
+    global _CONSECUTIVE_FAILURES, _DISABLED
+    if _DISABLED:
+        _STATS["disabled_fallbacks"] += 1
+        return candidates[:top_k]
+
+    _STATS["attempts"] += 1
+    try:
+        response = _call_rerank_judge(query, candidates, judge_model)
+        scores = _parse_scores(response, len(candidates))
+    except Exception as exc:
+        _STATS["failures"] += 1
+        _CONSECUTIVE_FAILURES += 1
+        if _CONSECUTIVE_FAILURES >= _max_failures_before_disable():
+            _DISABLED = True
+        logger.warning("LLM rerank failed; using input order: %s", exc)
+        return candidates[:top_k]
+
+    if not scores:
+        _STATS["failures"] += 1
+        _CONSECUTIVE_FAILURES += 1
+        if _CONSECUTIVE_FAILURES >= _max_failures_before_disable():
+            _DISABLED = True
+        logger.warning("LLM rerank returned no parseable scores; using input order")
+        return candidates[:top_k]
+
+    _STATS["successes"] += 1
+    _CONSECUTIVE_FAILURES = 0
+    ranked = sorted(
+        enumerate(candidates),
+        key=lambda item: (-scores.get(item[0], -1.0), item[0]),
+    )
+    return [candidate for _, candidate in ranked[:top_k]]

{memorymaster-3.14.0 → memorymaster-3.15.1}/memorymaster/llm_steward.py

@@ -22,6 +22,7 @@ import time
 import urllib.request
 import urllib.error
 from dataclasses import dataclass, field
+from typing import Any
 
 log = logging.getLogger(__name__)
 
@@ -524,7 +525,7 @@ def run_steward(
     cooldown_seconds: float = DEFAULT_COOLDOWN_SECONDS,
     auto_validate: bool = True,
     workspace_root: str = "",
-) -> dict:
+) -> dict[str, Any]:
     """Process candidate claims through LLM extraction and curation.
 
     Args:
@@ -570,7 +571,7 @@ def run_steward(
     dedupe_on = _dedupe_enabled()
     dedupe_shadow = _dedupe_shadow()
 
-    stats = {
+    stats: dict[str, Any] = {
         "total": len(candidates),
         "confirmed": 0,
         "archived": 0,
@@ -766,6 +767,8 @@ def run_steward(
                                     (text[:200], subj, pred, obj_val, conf, scope),
                                 )
                                 new_id = cursor.lastrowid
+                                if new_id is None:
+                                    raise RuntimeError("SQLite did not return a claim id.")
                                 conn.execute(
                                     "INSERT INTO events (claim_id, event_type, details, created_at) "
                                     "VALUES (?, 'transition', ?, datetime('now'))",

{memorymaster-3.14.0 → memorymaster-3.15.1}/memorymaster/operator.py

@@ -226,12 +226,12 @@ def _extract_generic_claims(raw: str, add_claim) -> None:
 
 
 class HeuristicClaimExtractor:
-    def extract(self, text: str) -> list[dict[str, object]]:
+    def extract(self, text: str) -> list[dict[str, Any]]:
         raw = text.strip()
         if not raw:
             return []
 
-        claims: list[dict[str, object]] = []
+        claims: list[dict[str, Any]] = []
         seen: set[tuple[str, str, str]] = set()
 
         def add_claim(
@@ -287,7 +287,7 @@ class MemoryOperator:
         self.extractor = extractor or HeuristicClaimExtractor()
         self._reconcile_counter = 0
 
-    def process_turn(self, turn: TurnInput) -> dict[str, object]:
+    def process_turn(self, turn: TurnInput) -> dict[str, Any]:
         if self.config.progressive_retrieval:
             tier1 = self.service.query(
                 turn.user_text,
@@ -533,9 +533,9 @@ class MemoryOperator:
             if not (queue_inbox and queue_inbox == canonical_inbox):
                 return start_offset, read_offset, acked_offset, persisted_seen_events, persisted_processed_events, pending_queue, queue_state_loaded
 
-            start_offset = max(0, int(raw_queue_state.get("read_offset", raw_queue_state.get("offset", 0))))
+            start_offset = max(0, int(raw_queue_state.get("read_offset") or raw_queue_state.get("offset") or 0))
             read_offset = start_offset
-            acked_offset = max(0, int(raw_queue_state.get("acked_offset", raw_queue_state.get("offset", read_offset))))
+            acked_offset = max(0, int(raw_queue_state.get("acked_offset") or raw_queue_state.get("offset") or read_offset))
             persisted_seen_events = max(0, int(raw_queue_state.get("seen_events", 0)))
             persisted_processed_events = max(0, int(raw_queue_state.get("processed_events", 0)))
             next_queue_id = max(1, int(raw_queue_state.get("next_queue_id", 1)))
@@ -684,7 +684,7 @@ class MemoryOperator:
     def _record_turn_processed(
         self,
         turn,
-        summary: dict[str, object],
+        summary: dict[str, Any],
         entry_id: int,
         entry_offset: int,
         seen_events: int,
@@ -848,10 +848,10 @@ class MemoryOperator:
             queue_journal_path = Path(str(self.config.queue_journal_jsonl_path).strip())
             queue_journal_path.parent.mkdir(parents=True, exist_ok=True)
 
-        def emit(event: str, payload: dict[str, object] | None = None) -> None:
+        def emit(event: str, payload: dict[str, Any] | None = None) -> None:
             if log_path is None:
                 return
-            record = {"ts": _utc_now_iso(), "event": event}
+            record: dict[str, Any] = {"ts": _utc_now_iso(), "event": event}
             if payload:
                 record.update(payload)
             with log_path.open("a", encoding="utf-8") as out:
@@ -1160,10 +1160,10 @@ class MemoryOperator:
             log_path = Path(self.config.log_jsonl_path)
             log_path.parent.mkdir(parents=True, exist_ok=True)
 
-        def emit(event: str, payload: dict[str, object] | None = None) -> None:
+        def emit(event: str, payload: dict[str, Any] | None = None) -> None:
             if log_path is None:
                 return
-            record = {"ts": _utc_now_iso(), "event": event}
+            record: dict[str, Any] = {"ts": _utc_now_iso(), "event": event}
             if payload:
                 record.update(payload)
             with log_path.open("a", encoding="utf-8") as out: