memorymaster 3.15.0__tar.gz → 3.16.0__tar.gz

{memorymaster-3.15.0/memorymaster.egg-info → memorymaster-3.16.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: memorymaster
-Version: 3.15.0
+Version: 3.16.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
@@ -98,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.15.0 → memorymaster-3.16.0}/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.15.0 → memorymaster-3.16.0}/memorymaster/config.py

@@ -8,7 +8,11 @@ Environment variables
 ---------------------
 MEMORYMASTER_RETRIEVAL_WEIGHTS
     Comma-separated floats for hybrid ranking: lexical,confidence,freshness,vector.
-    Default: ``0.45,0.30,0.15,0.10``
+    Default: ``0.30,0.20,0.10,0.40``
+
+MEMORYMASTER_W_LEX, MEMORYMASTER_W_CONF, MEMORYMASTER_W_FRESH, MEMORYMASTER_W_VEC
+    Individual overrides for the four hybrid ranking weights. These take
+    precedence over ``MEMORYMASTER_RETRIEVAL_WEIGHTS`` when set.
 
 MEMORYMASTER_RETRIEVAL_WEIGHTS_NO_VECTOR
     Weights when vector search is disabled: lexical,confidence,freshness.
@@ -55,6 +59,14 @@ MEMORYMASTER_LLM_RERANK
     Enable Gemini cross-encoder reranking over the top retrieval candidates.
     Default: ``0``
 
+MEMORYMASTER_RRF_TIEBREAKER
+    Enable RRF near-tie reordering after linear retrieval ranking.
+    Default: ``0``
+
+MEMORYMASTER_RRF_TIEBREAKER_THRESHOLD
+    Maximum adjacent score gap considered a near tie.
+    Default: ``0.01``
+
 MEMORYMASTER_CONFIG_FILE
     Path to a JSON config file. Keys match attribute names on ``Config``.
 """
@@ -159,10 +171,10 @@ class Config:
     """Immutable configuration for tunable MemoryMaster constants."""
 
     # --- Retrieval ranking weights (hybrid mode with vector) ---
-    retrieval_weight_lexical: float = 0.45
-    retrieval_weight_confidence: float = 0.30
-    retrieval_weight_freshness: float = 0.15
-    retrieval_weight_vector: float = 0.10
+    retrieval_weight_lexical: float = 0.30
+    retrieval_weight_confidence: float = 0.20
+    retrieval_weight_freshness: float = 0.10
+    retrieval_weight_vector: float = 0.40
 
     # --- Retrieval ranking weights (hybrid mode without vector) ---
     retrieval_weight_lexical_no_vector: float = 0.55
@@ -197,6 +209,8 @@ class Config:
     pinned_bonus: float = 0.03
     session_diversity_cap: int = 3
     llm_rerank: bool = False
+    rrf_tiebreaker_enabled: bool = False
+    rrf_tiebreaker_threshold: float = 0.01
 
     # --- Initial confidence priors calibrated from validator outcomes ---
     default_initial_confidence: float = DEFAULT_INITIAL_CONFIDENCE
@@ -310,6 +324,10 @@ def load_config(config_path: str | Path | None = None) -> Config:
         "retrieval_weight_freshness",
         "retrieval_weight_vector",
     ])
+    _apply_env_float(overrides, "MEMORYMASTER_W_LEX", "retrieval_weight_lexical")
+    _apply_env_float(overrides, "MEMORYMASTER_W_CONF", "retrieval_weight_confidence")
+    _apply_env_float(overrides, "MEMORYMASTER_W_FRESH", "retrieval_weight_freshness")
+    _apply_env_float(overrides, "MEMORYMASTER_W_VEC", "retrieval_weight_vector")
     _apply_env_floats(overrides, "MEMORYMASTER_RETRIEVAL_WEIGHTS_NO_VECTOR", 3, [
         "retrieval_weight_lexical_no_vector",
         "retrieval_weight_confidence_no_vector",
@@ -343,6 +361,8 @@ def load_config(config_path: str | Path | None = None) -> Config:
     _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")
+    _apply_env_bool(overrides, "MEMORYMASTER_RRF_TIEBREAKER", "rrf_tiebreaker_enabled")
+    _apply_env_float(overrides, "MEMORYMASTER_RRF_TIEBREAKER_THRESHOLD", "rrf_tiebreaker_threshold")
 
     # Filter to only valid Config fields
     valid_fields = {f.name for f in Config.__dataclass_fields__.values()}

{memorymaster-3.15.0 → memorymaster-3.16.0}/memorymaster/retrieval.py

@@ -8,6 +8,7 @@ from typing import Callable, Mapping
 
 from memorymaster.config import get_config
 from memorymaster.models import Claim
+from memorymaster.recall_fusion import RRF_K_DEFAULT, rrf_fuse
 
 RETRIEVAL_MODES = ("legacy", "hybrid")
 
@@ -136,12 +137,12 @@ def rank_claims(
 def _compute_claim_score(claim: Claim, lexical: float, confidence: float, freshness: float, vector: float, vector_enabled: bool, semantic_vectors: bool) -> float:
     """Compute relevance score for a claim."""
     cfg = get_config()
+    w_l, w_c, w_f, w_v = cfg.retrieval_weights
     if vector_enabled and semantic_vectors:
-        # Real semantic embeddings: vector is the primary relevance signal
-        score = (0.30 * lexical) + (0.20 * confidence) + (0.10 * freshness) + (0.40 * vector)
+        # Real semantic embeddings use the same configurable blend as other
+        # vector-enabled ranking so env sweeps affect both paths.
+        score = (w_l * lexical) + (w_c * confidence) + (w_f * freshness) + (w_v * vector)
     elif vector_enabled:
-        # Hash-based vectors: limited semantic value, keep lexical dominant
-        w_l, w_c, w_f, w_v = cfg.retrieval_weights
         score = (w_l * lexical) + (w_c * confidence) + (w_f * freshness) + (w_v * vector)
     else:
         w_l, w_c, w_f = cfg.retrieval_weights_no_vector
@@ -180,6 +181,69 @@ def apply_session_diversity_cap(ranked: list[RankedClaim], cap: int) -> list[Ran
     return result
 
 
+def _component_rankings(rows: list[RankedClaim]) -> dict[str, list[int]]:
+    original_positions = {row.claim.id: index for index, row in enumerate(rows)}
+
+    def ranked_ids(score_attr: str) -> list[int]:
+        ordered = sorted(
+            rows,
+            key=lambda row: (
+                -float(getattr(row, score_attr)),
+                original_positions[row.claim.id],
+            ),
+        )
+        return [row.claim.id for row in ordered]
+
+    return {
+        "lexical": ranked_ids("lexical_score"),
+        "vector": ranked_ids("vector_score"),
+        "confidence": ranked_ids("confidence_score"),
+        "freshness": ranked_ids("freshness_score"),
+    }
+
+
+def apply_rrf_tiebreaker(
+    ranked: list[RankedClaim],
+    *,
+    threshold: float = 0.01,
+    k: int = RRF_K_DEFAULT,
+    enabled: bool = True,
+) -> list[RankedClaim]:
+    if not enabled or len(ranked) < 2:
+        return ranked
+
+    threshold = max(0.0, threshold)
+    threshold_epsilon = 1e-12
+    head_count = min(10, len(ranked))
+    result = list(ranked)
+    index = 0
+
+    while index < head_count:
+        group_end = index + 1
+        while (
+            group_end < head_count
+            and abs(ranked[group_end - 1].score - ranked[group_end].score)
+            <= threshold + threshold_epsilon
+        ):
+            group_end += 1
+
+        if group_end - index > 1:
+            group = ranked[index:group_end]
+            original_positions = {row.claim.id: offset for offset, row in enumerate(group)}
+            rrf_scores = rrf_fuse(_component_rankings(group), k=k)
+            result[index:group_end] = sorted(
+                group,
+                key=lambda row: (
+                    -rrf_scores.get(row.claim.id, 0.0),
+                    original_positions[row.claim.id],
+                ),
+            )
+
+        index = group_end
+
+    return result
+
+
 def rank_claim_rows(
     query_text: str,
     claims: list[Claim],
@@ -262,5 +326,11 @@ def rank_claim_rows(
         ),
         reverse=True,
     )
+    cfg = get_config()
+    ranked = apply_rrf_tiebreaker(
+        ranked,
+        threshold=cfg.rrf_tiebreaker_threshold,
+        enabled=cfg.rrf_tiebreaker_enabled,
+    )
     ranked = apply_session_diversity_cap(ranked, get_config().session_diversity_cap)
     return ranked[:limit]

{memorymaster-3.15.0 → memorymaster-3.16.0/memorymaster.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: memorymaster
-Version: 3.15.0
+Version: 3.16.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
@@ -98,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.15.0 → memorymaster-3.16.0}/memorymaster.egg-info/SOURCES.txt

@@ -306,6 +306,8 @@ tests/test_recall_vector_fallback.py
 tests/test_reliability_hardening.py
 tests/test_resolvers_concurrent_supersede.py
 tests/test_retrieval_profile.py
+tests/test_retrieval_rrf_tiebreaker.py
+tests/test_retrieval_weights.py
 tests/test_review.py
 tests/test_rl_trainer.py
 tests/test_rrf_auto_gate.py

{memorymaster-3.15.0 → memorymaster-3.16.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "memorymaster"
-version = "3.15.0"
+version = "3.16.0"
 description = "Production-grade memory reliability system for AI coding agents. Lifecycle-managed claims with citations, conflict detection, steward governance, and MCP integration."
 license = {text = "MIT"}
 authors = [{name = "wolverin0"}]

{memorymaster-3.15.0 → memorymaster-3.16.0}/tests/test_config.py

@@ -22,7 +22,7 @@ def _reset():
 class TestConfigDefaults:
     def test_default_retrieval_weights(self):
         cfg = Config()
-        assert cfg.retrieval_weights == (0.45, 0.30, 0.15, 0.10)
+        assert cfg.retrieval_weights == (0.30, 0.20, 0.10, 0.40)
 
     def test_default_no_vector_weights(self):
         cfg = Config()
@@ -58,6 +58,12 @@ class TestConfigEnvOverrides:
         cfg = load_config()
         assert cfg.retrieval_weights == (0.40, 0.25, 0.20, 0.15)
 
+    def test_individual_retrieval_weight_env(self, monkeypatch):
+        monkeypatch.setenv("MEMORYMASTER_RETRIEVAL_WEIGHTS", "0.40,0.25,0.20,0.15")
+        monkeypatch.setenv("MEMORYMASTER_W_LEX", "0.55")
+        cfg = load_config()
+        assert cfg.retrieval_weights == (0.55, 0.25, 0.20, 0.15)
+
     def test_retrieval_weights_no_vector_env(self, monkeypatch):
         monkeypatch.setenv("MEMORYMASTER_RETRIEVAL_WEIGHTS_NO_VECTOR", "0.60,0.25,0.15")
         cfg = load_config()

memorymaster-3.16.0/tests/test_retrieval_rrf_tiebreaker.py

@@ -0,0 +1,84 @@
+from __future__ import annotations
+
+from memorymaster.config import get_config, reset_config
+from memorymaster.models import Claim
+from memorymaster.retrieval import RankedClaim, apply_rrf_tiebreaker
+
+
+def _claim(claim_id: int) -> Claim:
+    return Claim(
+        id=claim_id,
+        text=f"claim {claim_id}",
+        idempotency_key=None,
+        normalized_text=None,
+        claim_type=None,
+        subject=None,
+        predicate=None,
+        object_value=None,
+        scope="project",
+        volatility="medium",
+        status="confirmed",
+        confidence=0.8,
+        pinned=False,
+        supersedes_claim_id=None,
+        replaced_by_claim_id=None,
+        created_at="2026-03-01T00:00:00+00:00",
+        updated_at="2026-03-08T00:00:00+00:00",
+        last_validated_at=None,
+        archived_at=None,
+    )
+
+
+def _row(
+    claim_id: int,
+    *,
+    score: float,
+    lexical: float,
+    vector: float,
+    confidence: float,
+    freshness: float,
+) -> RankedClaim:
+    return RankedClaim(
+        claim=_claim(claim_id),
+        score=score,
+        lexical_score=lexical,
+        vector_score=vector,
+        confidence_score=confidence,
+        freshness_score=freshness,
+    )
+
+
+def test_clear_winner_pair_unchanged() -> None:
+    rows = [
+        _row(1, score=0.8, lexical=0.1, vector=0.1, confidence=0.1, freshness=0.1),
+        _row(2, score=0.5, lexical=1.0, vector=1.0, confidence=1.0, freshness=1.0),
+    ]
+
+    result = apply_rrf_tiebreaker(rows, threshold=0.01, enabled=True)
+
+    assert [row.claim.id for row in result] == [1, 2]
+
+
+def test_near_tie_reordered_by_rrf() -> None:
+    rows = [
+        _row(1, score=0.81, lexical=1.0, vector=0.0, confidence=0.0, freshness=0.0),
+        _row(2, score=0.80, lexical=0.9, vector=1.0, confidence=1.0, freshness=1.0),
+    ]
+
+    result = apply_rrf_tiebreaker(rows, threshold=0.01, enabled=True)
+
+    assert [row.claim.id for row in result] == [2, 1]
+
+
+def test_disabled_flag_no_op(monkeypatch) -> None:
+    monkeypatch.setenv("MEMORYMASTER_RRF_TIEBREAKER", "0")
+    reset_config()
+    rows = [
+        _row(1, score=0.81, lexical=1.0, vector=0.0, confidence=0.0, freshness=0.0),
+        _row(2, score=0.80, lexical=0.9, vector=1.0, confidence=1.0, freshness=1.0),
+    ]
+
+    result = apply_rrf_tiebreaker(rows, threshold=0.01, enabled=get_config().rrf_tiebreaker_enabled)
+
+    assert [row.claim.id for row in result] == [1, 2]
+    reset_config()

memorymaster-3.16.0/tests/test_retrieval_weights.py

@@ -0,0 +1,69 @@
+from __future__ import annotations
+
+import pytest
+
+from memorymaster.config import reset_config
+from memorymaster.models import Claim
+from memorymaster.retrieval import rank_claim_rows
+
+
+@pytest.fixture(autouse=True)
+def _reset_config():
+    reset_config()
+    yield
+    reset_config()
+
+
+def _claim() -> Claim:
+    return Claim(
+        id=1,
+        text="alpha beta retrieval target",
+        idempotency_key=None,
+        normalized_text=None,
+        claim_type=None,
+        subject=None,
+        predicate=None,
+        object_value=None,
+        scope="project",
+        volatility="medium",
+        status="confirmed",
+        confidence=0.8,
+        pinned=False,
+        supersedes_claim_id=None,
+        replaced_by_claim_id=None,
+        created_at="2999-01-01T00:00:00+00:00",
+        updated_at="2999-01-01T00:00:00+00:00",
+        last_validated_at=None,
+        archived_at=None,
+    )
+
+
+def _row(*, semantic_vectors: bool):
+    def vector_hook(query, claims):
+        return {claim.id: 0.6 for claim in claims}
+
+    return rank_claim_rows(
+        "alpha beta",
+        [_claim()],
+        mode="hybrid",
+        limit=1,
+        vector_hook=vector_hook,
+        semantic_vectors=semantic_vectors,
+    )[0]
+
+
+def test_memorymaster_w_lex_affects_vector_enabled_ranking_paths(monkeypatch):
+    default_lexical = _row(semantic_vectors=False)
+    default_semantic = _row(semantic_vectors=True)
+
+    monkeypatch.setenv("MEMORYMASTER_W_LEX", "0.55")
+    reset_config()
+
+    override_lexical = _row(semantic_vectors=False)
+    override_semantic = _row(semantic_vectors=True)
+    expected_delta = (0.55 - 0.30) * default_lexical.lexical_score
+
+    assert override_lexical.score - default_lexical.score == pytest.approx(expected_delta)
+    assert override_semantic.score - default_semantic.score == pytest.approx(expected_delta)
+    assert override_lexical.score != default_lexical.score
+    assert override_semantic.score != default_semantic.score