memorymaster 3.10.0__tar.gz → 3.12.0__tar.gz

{memorymaster-3.10.0 → memorymaster-3.12.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: memorymaster
-Version: 3.10.0
+Version: 3.12.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

{memorymaster-3.10.0 → memorymaster-3.12.0}/memorymaster/claim_edges.py

@@ -39,6 +39,7 @@ __all__ = [
 
 MENTION_KIND = "mentions"
 SUPERSEDES_KIND = "supersedes"
+SHARES_ENTITY_KIND = "shares_entity"  # v3.11 P3 — claim_a and claim_b have the same primary entity_id
 
 
 _CLAIM_NUM_RE = re.compile(r"\bclaims?\s+(\d{1,6})\b", re.IGNORECASE)
@@ -112,14 +113,31 @@ def extract_edges_for_claim(
     return edges
 
 
-def rebuild_edges(db_path: str | Path, *, batch_size: int = 500) -> dict[str, int]:
+def rebuild_edges(
+    db_path: str | Path,
+    *,
+    batch_size: int = 500,
+    include_shares_entity: bool = True,
+    shares_entity_max_per_pivot: int = 50,
+) -> dict[str, int]:
     """Walk the entire claims table and rebuild the claim_edges index.
 
-    Returns counters: ``{"claims_scanned": N, "edges_written": M, "supersession_edges": K}``.
+    Returns counters: ``{"claims_scanned": N, "edges_written": M, "supersession_edges": K, "shares_entity_edges": L}``.
 
     Idempotent: ``INSERT OR IGNORE`` against the composite primary key.
+
+    v3.11 P3 — when ``include_shares_entity`` (default True), also writes
+    ``shares_entity`` edges between any two claims that share their primary
+    ``entity_id``. Capped at ``shares_entity_max_per_pivot`` neighbors per
+    entity to bound the explosion: a popular entity (say, "claim") with 200
+    referencing claims would otherwise produce 200×199/2 = 19,900 edges.
     """
-    counters = {"claims_scanned": 0, "edges_written": 0, "supersession_edges": 0}
+    counters = {
+        "claims_scanned": 0,
+        "edges_written": 0,
+        "supersession_edges": 0,
+        "shares_entity_edges": 0,
+    }
     conn = sqlite3.connect(str(db_path))
     try:
         ensure_claim_edges_schema(conn)
@@ -151,6 +169,39 @@ def rebuild_edges(db_path: str | Path, *, batch_size: int = 500) -> dict[str, in
             if counters["claims_scanned"] % batch_size == 0:
                 conn.commit()
         conn.commit()
+
+        # v3.11 P3 — shares_entity edges. One pass over claims-grouped-by-
+        # entity_id; for each non-trivial group emit pairwise edges (capped).
+        if include_shares_entity:
+            try:
+                groups = conn.execute(
+                    """
+                    SELECT entity_id, GROUP_CONCAT(id) AS ids
+                    FROM claims
+                    WHERE entity_id IS NOT NULL
+                    GROUP BY entity_id
+                    HAVING COUNT(*) BETWEEN 2 AND ?
+                    """,
+                    (shares_entity_max_per_pivot,),
+                ).fetchall()
+            except sqlite3.OperationalError:
+                groups = []
+            for _eid, ids_str in groups:
+                ids = [int(x) for x in (ids_str or "").split(",") if x.strip().isdigit()]
+                # Pairwise edges (a, b) with a < b only — keeps it bidirectional
+                # via a single canonical row.
+                for i, a in enumerate(ids):
+                    for b in ids[i + 1:]:
+                        cur = conn.execute(
+                            "INSERT OR IGNORE INTO claim_edges "
+                            "(src_claim_id, dst_claim_id, edge_kind, created_at) "
+                            "VALUES (?, ?, ?, ?)",
+                            (a, b, SHARES_ENTITY_KIND, now),
+                        )
+                        if cur.rowcount:
+                            counters["edges_written"] += 1
+                            counters["shares_entity_edges"] += 1
+            conn.commit()
     finally:
         conn.close()
     return counters

{memorymaster-3.10.0 → memorymaster-3.12.0}/memorymaster/closets.py

@@ -186,10 +186,21 @@ def rebuild_closets(
 
 
 def search_closets(
-    db_path: str | Path, query: str, *, limit: int = 5
-) -> list[tuple[str, list[int]]]:
+    db_path: str | Path, query: str, *, limit: int = 5, with_scores: bool = False
+) -> list[tuple[str, list[int]]] | list[tuple[str, list[int], float]]:
     """Return ``[(slug, claim_ids), ...]`` ranked by FTS5 BM25.
 
+    When ``with_scores=True`` (v3.11 P1), returns ``[(slug, claim_ids, score)]``
+    where ``score`` is the FTS5 BM25 score normalised to [0, 1] across this
+    result set. The recall hook uses this to weight closet hits proportional
+    to how well the query matched, instead of the v3.10 constant 1.0 that
+    flooded the top-5 with article-membership noise.
+
+    BM25 from SQLite's FTS5 returns NEGATIVE values where 0 = no match and
+    more-negative = better match (`ORDER BY bm25(...) ASC` puts best first).
+    We normalise: ``score = best_bm25 / row_bm25`` so the best match scores
+    1.0 and weaker matches scale below.
+
     Defensive: if the table doesn't exist or the query is malformed, returns
     an empty list rather than raising.
     """
@@ -197,9 +208,6 @@ def search_closets(
         return []
     conn = sqlite3.connect(str(db_path))
     try:
-        # Sanitize query: FTS5 MATCH treats most punctuation as syntax. The
-        # safest path for LLM-shaped queries is to extract bare alphanumeric
-        # tokens and OR them together.
         tokens = [t for t in re.findall(r"[A-Za-z0-9_]{3,}", query) if t]
         if not tokens:
             return []
@@ -207,26 +215,39 @@ def search_closets(
         try:
             rows = conn.execute(
                 """
-                SELECT c.article_slug, c.claim_ids_json
+                SELECT c.article_slug, c.claim_ids_json, bm25(closets_fts) AS bm25_score
                 FROM closets_fts ft
                 JOIN closets c ON c.article_slug = ft.article_slug
                 WHERE closets_fts MATCH ?
-                ORDER BY bm25(closets_fts)
+                ORDER BY bm25_score
                 LIMIT ?
                 """,
                 (fts_query, limit),
             ).fetchall()
         except sqlite3.OperationalError:
             return []
-        out: list[tuple[str, list[int]]] = []
-        for slug, ids_json in rows:
+        if not rows:
+            return []
+        # FTS5 BM25 returns negative numbers; lower (more negative) = better.
+        # The first row is the best. Normalise so best=1.0, others scale below.
+        best = abs(rows[0][2]) if rows[0][2] else 1.0
+        if best == 0.0:
+            best = 1.0
+        out: list[tuple] = []
+        for slug, ids_json, bm25_score in rows:
             try:
                 ids = json.loads(ids_json or "[]")
                 if not isinstance(ids, list):
                     ids = []
             except (json.JSONDecodeError, ValueError):
                 ids = []
-            out.append((str(slug), [int(i) for i in ids if isinstance(i, int)]))
+            normalised = abs(bm25_score) / best if bm25_score else 0.0
+            normalised = max(0.0, min(1.0, normalised))
+            cleaned_ids = [int(i) for i in ids if isinstance(i, int)]
+            if with_scores:
+                out.append((str(slug), cleaned_ids, normalised))
+            else:
+                out.append((str(slug), cleaned_ids))
         return out
     finally:
         conn.close()

{memorymaster-3.10.0 → memorymaster-3.12.0}/memorymaster/context_hook.py

@@ -426,6 +426,18 @@ def _closets_enabled() -> bool:
     return raw not in ("0", "false", "False", "no", "off", "")
 
 
+def _closets_boost_only() -> bool:
+    """v3.11 P1b — when set, closets only BOOST already-recalled rows.
+
+    The default is OFF (legacy v3.10 behaviour: hydrate new candidates AND
+    boost). Boost-only mode is MemPalace's stricter "boost signal, never
+    gate" interpretation — it can't displace real lexical matches because
+    it never adds new candidates, only re-ranks the existing set.
+    """
+    raw = os.environ.get("MEMORYMASTER_RECALL_CLOSETS_BOOST_ONLY", "0").strip()
+    return raw not in ("0", "false", "False", "no", "off", "")
+
+
 def _two_pass_max_neighbors() -> int:
     """Cap neighbors discovered per recall call (default 20)."""
     raw = os.environ.get("MEMORYMASTER_RECALL_TWO_PASS_MAX", "20").strip()
@@ -1305,7 +1317,10 @@ def _recall_impl(
                 _search_closets = None
             if _search_closets is not None:
                 try:
-                    closet_hits = _search_closets(db, query, limit=5)
+                    # v3.11 P1 fix: cap to 3 articles (was 5) to bound the
+                    # candidate flood, and request BM25-normalised scores so
+                    # weaker matches don't dominate ranking with constant 1.0.
+                    closet_hits = _search_closets(db, query, limit=3, with_scores=True)
                 except Exception as exc:  # noqa: BLE001
                     logger.debug("closets stream skipped (search): %s", exc)
                     closet_hits = []
@@ -1315,11 +1330,22 @@ def _recall_impl(
                         c = row.get("claim")
                         if c is not None and getattr(c, "id", None) is not None:
                             existing_by_id[int(c.id)] = row
-                    for _slug, claim_ids in closet_hits:
+                    boost_only = _closets_boost_only()
+                    for hit in closet_hits:
+                        if len(hit) == 3:
+                            _slug, claim_ids, score = hit
+                        else:
+                            _slug, claim_ids = hit
+                            score = 1.0
                         for cid in claim_ids:
                             if cid in existing_by_id:
-                                # Boost: closet_score=1.0 is the constant signal
-                                existing_by_id[cid]["closet_score"] = 1.0
+                                prev = float(existing_by_id[cid].get("closet_score") or 0.0)
+                                existing_by_id[cid]["closet_score"] = max(prev, float(score))
+                                continue
+                            if boost_only:
+                                # v3.11 P1b — never hydrate new candidates;
+                                # closets are pure re-ranking. Skip cids not
+                                # already in the candidate set.
                                 continue
                             try:
                                 claim = svc.store.get_claim(cid)
@@ -1335,7 +1361,7 @@ def _recall_impl(
                                     "confidence_score": float(getattr(claim, "confidence", 0.0) or 0.0),
                                     "vector_score": 0.0,
                                     "entity_score": 0.0,
-                                    "closet_score": 1.0,
+                                    "closet_score": float(score),
                                     "source": "closets",
                                 }
                             )
@@ -1414,7 +1440,27 @@ def _recall_impl(
     # at the end of _relevance. Default 0.0 → query_type stays None and the
     # boost is a no-op, preserving bit-identical ranking.
     w_claim_type = _recall_weight("W_CLAIM_TYPE")
-    query_claim_type = classify_observation(query) if w_claim_type > 0.0 else None
+    # v3.11 P2 — derive query intent from query_classifier (sharper than the
+    # 6-pattern classify_observation which matched "preference" too greedily).
+    # Map query_type → claim_type so the boost compares apples to apples.
+    if w_claim_type > 0.0:
+        try:
+            from memorymaster.query_classifier import classify_query
+            qt = classify_query(query)
+            _query_to_claim_type = {
+                "constraint_check": "constraint",
+                "preference": "preference",
+                "fact_lookup": "fact",
+                "verification": "fact",
+                "temporal": "event",
+                "relational": "fact",
+                "open_ended": None,  # too vague to bias
+            }
+            query_claim_type = _query_to_claim_type.get(qt)
+        except Exception:  # noqa: BLE001
+            query_claim_type = classify_observation(query)
+    else:
+        query_claim_type = None
     # Scope-aware retrieval boost (roadmap 1.2). Multiplier applied to the
     # final _relevance score for claims whose scope matches the current
     # project scope. 0.0 (default) → no boost, ranking bit-identical to legacy.

{memorymaster-3.10.0 → memorymaster-3.12.0}/memorymaster.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: memorymaster
-Version: 3.10.0
+Version: 3.12.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

{memorymaster-3.10.0 → memorymaster-3.12.0}/memorymaster.egg-info/SOURCES.txt

@@ -278,6 +278,7 @@ tests/test_store_factory.py
 tests/test_tenant_isolation.py
 tests/test_turn_schema.py
 tests/test_two_pass_recall.py
+tests/test_v311_fixes.py
 tests/test_v390_e2e.py
 tests/test_v391_strict_warnings.py
 tests/test_vault_exporter.py

{memorymaster-3.10.0 → memorymaster-3.12.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "memorymaster"
-version = "3.10.0"
+version = "3.12.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.12.0/tests/test_v311_fixes.py

@@ -0,0 +1,172 @@
+"""Tests for v3.11.0 P1 + P2 + P3 fixes."""
+from __future__ import annotations
+
+import sqlite3
+from pathlib import Path
+
+import pytest
+
+from memorymaster import context_hook
+from memorymaster.claim_edges import (
+    SHARES_ENTITY_KIND,
+    rebuild_edges,
+)
+from memorymaster.closets import (
+    ensure_closets_schema,
+    rebuild_closets,
+    search_closets,
+)
+
+
+# --- P1 — F6 BM25-scaled scoring + boost-only mode -------------------------
+
+
+def test_p1_search_closets_with_scores_returns_normalised(tmp_path):
+    """search_closets(with_scores=True) returns 3-tuples with score in [0, 1]."""
+    vault = tmp_path / "vault" / "wiki"
+    vault.mkdir(parents=True)
+    (vault / "alpha.md").write_text(
+        "---\ntitle: a\ndescription: a\ntype: x\nscope: y\ntags: []\ndate: 2026-04-27\nclaims: [1]\n---\n\nMemPalace closets MemPalace pattern.\n",
+        encoding="utf-8",
+    )
+    (vault / "beta.md").write_text(
+        "---\ntitle: b\ndescription: b\ntype: x\nscope: y\ntags: []\ndate: 2026-04-27\nclaims: [2]\n---\n\nMemPalace mentioned briefly.\n",
+        encoding="utf-8",
+    )
+    db = tmp_path / "test.db"
+    rebuild_closets(db, vault)
+    hits = search_closets(db, "MemPalace closets", limit=5, with_scores=True)
+    assert len(hits) >= 1
+    for hit in hits:
+        assert len(hit) == 3
+        slug, claim_ids, score = hit
+        assert 0.0 <= score <= 1.0
+    # First hit should have score=1.0 (best match normalised to 1.0)
+    assert hits[0][2] == pytest.approx(1.0)
+
+
+def test_p1_legacy_search_closets_still_returns_2_tuples(tmp_path):
+    """Backwards-compat: search_closets() without with_scores still returns 2-tuples."""
+    vault = tmp_path / "vault" / "wiki"
+    vault.mkdir(parents=True)
+    (vault / "x.md").write_text(
+        "---\ntitle: x\ndescription: x\ntype: t\nscope: s\ntags: []\ndate: 2026-04-27\nclaims: [1]\n---\n\nMemPalace.\n",
+        encoding="utf-8",
+    )
+    db = tmp_path / "test.db"
+    rebuild_closets(db, vault)
+    hits = search_closets(db, "MemPalace")
+    assert len(hits) >= 1
+    for hit in hits:
+        assert len(hit) == 2  # not 3
+
+
+def test_p1_closets_boost_only_default_off():
+    assert context_hook._closets_boost_only() is False
+
+
+def test_p1_closets_boost_only_via_env(monkeypatch):
+    monkeypatch.setenv("MEMORYMASTER_RECALL_CLOSETS_BOOST_ONLY", "1")
+    assert context_hook._closets_boost_only() is True
+
+
+# --- P2 — F1 swap to query_classifier --------------------------------------
+
+
+def test_p2_query_classifier_recognised_in_recall():
+    """The query_classifier module's classify_query is callable."""
+    from memorymaster.query_classifier import classify_query
+
+    assert classify_query("what database does this use?") == "fact_lookup"
+    assert classify_query("we must use postgres") == "constraint_check"
+    assert classify_query("when was that changed?") == "temporal"
+
+
+# --- P3 — F8 shares_entity edges -------------------------------------------
+
+
+def _make_db_with_entities(tmp_path: Path) -> Path:
+    db = tmp_path / "test.db"
+    conn = sqlite3.connect(str(db))
+    try:
+        conn.executescript(
+            """
+            CREATE TABLE claims (
+                id INTEGER PRIMARY KEY,
+                text TEXT,
+                human_id TEXT,
+                replaced_by_claim_id INTEGER,
+                entity_id INTEGER
+            );
+            INSERT INTO claims (id, text, human_id, replaced_by_claim_id, entity_id) VALUES
+              (1, 'Mentions FastAPI', 'mm-1111', NULL, 100),
+              (2, 'Also mentions FastAPI', 'mm-2222', NULL, 100),
+              (3, 'Third claim about FastAPI', 'mm-3333', NULL, 100),
+              (4, 'About a different entity', 'mm-4444', NULL, 200),
+              (5, 'No entity at all', 'mm-5555', NULL, NULL);
+            """
+        )
+        conn.commit()
+    finally:
+        conn.close()
+    return db
+
+
+def test_p3_shares_entity_edges_written(tmp_path):
+    """Three claims share entity_id=100 → 3 pairwise edges (1-2, 1-3, 2-3)."""
+    db = _make_db_with_entities(tmp_path)
+    counters = rebuild_edges(db, include_shares_entity=True)
+    assert counters["shares_entity_edges"] == 3
+    # Verify in table
+    conn = sqlite3.connect(str(db))
+    try:
+        rows = conn.execute(
+            "SELECT src_claim_id, dst_claim_id FROM claim_edges WHERE edge_kind = ?",
+            (SHARES_ENTITY_KIND,),
+        ).fetchall()
+    finally:
+        conn.close()
+    pairs = {(min(s, d), max(s, d)) for s, d in rows}
+    assert pairs == {(1, 2), (1, 3), (2, 3)}
+
+
+def test_p3_singleton_entity_produces_no_edges(tmp_path):
+    """Claim 4 is the only one with entity_id=200; no shares_entity edges."""
+    db = _make_db_with_entities(tmp_path)
+    rebuild_edges(db, include_shares_entity=True)
+    conn = sqlite3.connect(str(db))
+    try:
+        rows = conn.execute(
+            "SELECT * FROM claim_edges WHERE edge_kind = ? AND (src_claim_id = 4 OR dst_claim_id = 4)",
+            (SHARES_ENTITY_KIND,),
+        ).fetchall()
+    finally:
+        conn.close()
+    assert rows == []
+
+
+def test_p3_max_per_pivot_caps_explosion(tmp_path):
+    """When >max claims share an entity, the entire group is skipped (overflow guard)."""
+    db = tmp_path / "many.db"
+    conn = sqlite3.connect(str(db))
+    try:
+        conn.executescript(
+            "CREATE TABLE claims (id INTEGER PRIMARY KEY, text TEXT, human_id TEXT, replaced_by_claim_id INTEGER, entity_id INTEGER);"
+        )
+        for i in range(1, 11):
+            conn.execute(
+                "INSERT INTO claims VALUES (?, ?, ?, NULL, 999)",
+                (i, f"claim {i}", f"mm-{i:04d}"),
+            )
+        conn.commit()
+    finally:
+        conn.close()
+    # Cap at 5 — group of 10 won't qualify (HAVING COUNT(*) BETWEEN 2 AND 5)
+    counters = rebuild_edges(db, shares_entity_max_per_pivot=5)
+    assert counters["shares_entity_edges"] == 0
+
+
+def test_p3_shares_entity_disabled_when_flag_off(tmp_path):
+    db = _make_db_with_entities(tmp_path)
+    counters = rebuild_edges(db, include_shares_entity=False)
+    assert counters["shares_entity_edges"] == 0