memstack-skill-loader 4.16.0__tar.gz → 4.17.0__tar.gz

{memstack_skill_loader-4.16.0/src/memstack_skill_loader.egg-info → memstack_skill_loader-4.17.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: memstack-skill-loader
-Version: 4.16.0
+Version: 4.17.0
 Summary: MCP server that vector-indexes MemStack Pro skills for on-demand loading
 Project-URL: Homepage, https://memstack.pro
 Project-URL: Documentation, https://memstack.pro/docs

{memstack_skill_loader-4.16.0 → memstack_skill_loader-4.17.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "memstack-skill-loader"
-version = "4.16.0"
+version = "4.17.0"
 description = "MCP server that vector-indexes MemStack Pro skills for on-demand loading"
 readme = "README.md"
 requires-python = ">=3.10"

{memstack_skill_loader-4.16.0 → memstack_skill_loader-4.17.0}/src/memstack_skill_loader/__init__.py

@@ -1,3 +1,3 @@
 """MemStack Skill Loader — MCP server for semantic skill search."""
 
-__version__ = "4.16.0"
+__version__ = "4.17.0"

{memstack_skill_loader-4.16.0 → memstack_skill_loader-4.17.0}/src/memstack_skill_loader/__main__.py

@@ -161,6 +161,12 @@ def main():
     elif len(sys.argv) > 2 and sys.argv[1] == "run":
         task = " ".join(sys.argv[2:])
         _run_agents(task)
+    elif len(sys.argv) > 1 and sys.argv[1] == "memory-migrate":
+        # Data migrations over the Memory Engine fact store. Dispatched here and
+        # nowhere else: no import-time hook, no call from MemoryStore, so a
+        # migration can only run because someone typed it.
+        from .memory_migrations import main as migrate_main
+        sys.exit(migrate_main(sys.argv[2:]))
     elif len(sys.argv) > 1 and sys.argv[1] == "proxy":
         import argparse
         parser = argparse.ArgumentParser(prog="memstack proxy")

{memstack_skill_loader-4.16.0 → memstack_skill_loader-4.17.0}/src/memstack_skill_loader/memory_engine.py

@@ -185,17 +185,87 @@ def _sql_math_available(conn: sqlite3.Connection) -> bool:
     return _SQL_MATH_AVAILABLE
 
 
+#: Source types whose ``method`` is filled in BULK rather than chosen per fact.
+#: See :func:`display_method` for why the line is drawn on deliberation and not
+#: on who authored the claim.
+#:
+#: This frozenset is the SINGLE definition of that scope. It gates two things
+#: that must move together: how a fact's ``method`` is RENDERED
+#: (:func:`display_method`) and how much retention that word BUYS
+#: (:meth:`MemoryStore._resolve_confidence`). Widening it is a one-line change
+#: that widens both; splitting them would let a source render as qualified
+#: while still being weighted as if it were not.
+_SELF_REPORT_SOURCES = frozenset({"diary"})
+
+#: Confidence auto-assigned per method when the caller supplies none. A
+#: hand-set value never consults this table.
+_METHOD_BASE_CONFIDENCE = {
+    "verified": 0.85,
+    "reported": 0.7,
+    "inferred": 0.7,
+    "assumed": 0.5,
+}
+
+#: Ceiling on the AUTO-ASSIGNED confidence of a fact whose ``source_type`` is in
+#: :data:`_SELF_REPORT_SOURCES`. See
+#: :meth:`MemoryStore._resolve_confidence` for why 0.75 and not 0.70.
+_SELF_REPORT_CONFIDENCE_CEILING = 0.75
+
+
+def display_method(fact: dict) -> str:
+    """Render ``method`` for a reader, qualifying a bulk-declared 'verified'.
+
+    ``method`` is the ONLY field on a fact that nothing external ever checks.
+    ``source_type`` and ``source_ref`` are machine-set by the ingest path from
+    the file it read, so they cannot misstate where a fact came from; ``method``
+    is a word the writing session chose about its own claim.
+
+    WHY THE SCOPE IS ``diary`` AND NOT "everything self-authored"
+    ------------------------------------------------------------
+    ``session`` and ``correction`` facts are self-authored too. Nothing checks
+    them either, and NOTHING HERE SHOULD BE READ AS CLAIMING OTHERWISE: a
+    ``mem_store`` call carrying ``verified`` is the same session asserting the
+    same thing about its own work, and its tag renders unqualified only because
+    of where the line is drawn, not because anyone confirmed it.
+
+    The line is drawn on DELIBERATION, not on authorship or on trust. A diary's
+    ``method`` is a template field in a pipe-delimited FACTS block, filled for
+    every row of the block at end of session, when the evidence that would
+    settle it has already left the writer's context. A ``mem_store`` or
+    ``mem_correct`` call is one deliberate act about one fact, made while the
+    thing it describes is still in view. Those differ in the ATTENTION each word
+    receives, which is what the qualification is about.
+
+    Do not re-derive this scope from how the values happen to be distributed
+    today. That distribution is evidence the split is real, not the reason for
+    it, and it can change without the underlying difference changing.
+
+    This is a RENDERING transform over the stored (source_type, method) pair.
+    No new method value is stored, nothing is relabelled, and the stored word is
+    unchanged: ``fact['method']`` still reads ``verified``. Any other pair
+    renders exactly as before, so the tag degrades to its old output everywhere
+    the qualification does not apply.
+    """
+    method = fact["method"]
+    if method == "verified" and fact.get("source_type") in _SELF_REPORT_SOURCES:
+        return "self-verified"
+    return method
+
+
 def provenance_tag(fact: dict) -> str:
     """Inline provenance tag for a fact, e.g.
-    ``[verified · diary memory/sessions/2026-07-23-demo.md · recalled 3x]``.
+    ``[self-verified · diary memory/sessions/2026-07-23-demo.md · recalled 3x]``.
 
     Single source of truth for how a fact's origin is rendered, shared by the
-    MCP server and the SessionStart living-memory block so the two can't drift.
+    MCP server, the dashboard Inspector and the SessionStart living-memory block
+    so the three can't drift. The leading token comes from
+    :func:`display_method`; see there for why a diary's ``verified`` renders
+    qualified and a session's does not.
     """
     src = fact["source_type"]
     if fact.get("source_ref"):
         src = f"{src} {fact['source_ref']}"
-    return f"[{fact['method']} · {src} · recalled {fact.get('recall_count', 0)}x]"
+    return f"[{display_method(fact)} · {src} · recalled {fact.get('recall_count', 0)}x]"
 
 
 # ---------------------------------------------------------------------------
@@ -368,20 +438,65 @@ class MemoryStore:
             )
 
     @staticmethod
-    def _resolve_confidence(method: str, confidence: float | None) -> float:
-        if confidence is None:
-            if method == "verified":
-                return 0.85
-            if method == "assumed":
-                return 0.5
-            return 0.7  # reported / inferred -> column default
-        if not isinstance(confidence, (int, float)) or not (0 < confidence <= 1):
-            raise InvalidFieldError(
-                f"confidence must be in (0, 1], got {confidence!r}"
-            )
-        if method == "assumed" and confidence > 0.5:
-            return 0.5  # assumed caps at 0.5 (cap only lowers)
-        return float(confidence)
+    def _resolve_confidence(
+        method: str, confidence: float | None, source_type: str
+    ) -> float:
+        """Confidence for a new fact: a hand-set value, or the method's base
+        with the self-report ceiling applied.
+
+        A HAND-SET value passes through unchanged, subject only to the
+        long-standing ``assumed`` cap (which never raises). The ceiling below is
+        a claim about what a writer's own WORD is worth when nothing chose a
+        number per fact, so it applies only where the number was auto-assigned.
+        A caller who deliberately passes ``confidence=0.85`` on a diary fact
+        keeps 0.85; the ceiling has nothing to say about a value someone chose.
+
+        WHY A CEILING EXISTS AT ALL
+        ---------------------------
+        ``confidence`` is the ONLY route by which ``method`` reaches recall
+        ranking: :func:`recall_score` reads confidence, age, recall count and
+        status, and never reads ``method``. So the word a session picks for its
+        own claim is, by itself, what decides whether that claim is recited back
+        at the top of the next session. For a source whose ``method`` is filled
+        in bulk (:data:`_SELF_REPORT_SOURCES`), that is a self-declared word
+        buying a self-declared retention advantage.
+
+        WHY 0.75 AND NOT 0.70
+        ---------------------
+        0.70 is the base for ``reported`` and ``inferred``, so a ceiling of 0.70
+        would make a diary's ``verified`` numerically identical to a diary's
+        ``reported`` and erase the one distinction the method vocabulary draws
+        well. It also over-corrects: measured against this repo's store, 0.70
+        removed EVERY diary fact from the session-start injection window
+        (9 of 13 slots before, 0 of 15 after), replacing a window dominated by
+        one source with one that excludes it. 0.75 keeps the ordering
+        ``verified`` > ``reported`` inside a diary while ending the automatic
+        sweep of the window: the same measurement puts diary facts at 6 of 13
+        slots.
+
+        WHY ``min`` AND NOT ASSIGNMENT
+        ------------------------------
+        The ceiling only ever LOWERS. Today ``verified`` (0.85) is the sole base
+        above it, so it is the only method the ceiling touches. Writing this as
+        ``base = 0.75`` would look equivalent and would silently RAISE
+        ``reported``, ``inferred`` and ``assumed`` the moment
+        :data:`_SELF_REPORT_SOURCES` is widened to a source that uses them.
+        """
+        if confidence is not None:
+            if not isinstance(confidence, (int, float)) or not (0 < confidence <= 1):
+                raise InvalidFieldError(
+                    f"confidence must be in (0, 1], got {confidence!r}"
+                )
+            if method == "assumed" and confidence > 0.5:
+                return 0.5  # assumed caps at 0.5 (cap only lowers)
+            return float(confidence)
+
+        # method is already validated against _VALID_METHODS by
+        # _validate_common, which every insert path calls first.
+        base = _METHOD_BASE_CONFIDENCE[method]
+        if source_type in _SELF_REPORT_SOURCES:
+            base = min(base, _SELF_REPORT_CONFIDENCE_CEILING)
+        return base
 
     @classmethod
     def _validate_common(
@@ -418,7 +533,7 @@ class MemoryStore:
         _test_created_at: str | None,
     ) -> int:
         self._validate_common(project, subject, source_type, method)
-        conf = self._resolve_confidence(method, confidence)
+        conf = self._resolve_confidence(method, confidence, source_type)
 
         cols = [
             "project", "subject", "claim", "detail", "supersedes",
@@ -503,14 +618,27 @@ class MemoryStore:
         confidence: float | None = None,
         source_ref: str | None = None,
         entities: Iterable[str] | None = None,
+        subject: str | None = None,
         _test_created_at: str | None = None,
     ) -> int:
         """Supersede ``old_id`` with a new fact; return the new id.
 
-        The correction inherits ``project`` and ``subject`` from the fact being
-        corrected. Refused if ``old_id`` is not the live tip — the error names
-        the current tip. The insert of the new fact and the status flip of the
-        old fact happen in a single transaction.
+        The correction always inherits ``project``. It inherits ``subject`` too
+        unless ``subject`` is given, which re-files the corrected fact under a
+        new dotted-path, for the case where the correction disproves the very
+        thing the old subject named. The new subject is validated like any
+        other; the OLD row keeps its original subject forever, because identity
+        columns are immutable once written.
+
+        Renaming leaves the chain intact (``_find_tip`` walks ``supersedes``,
+        never ``subject``) but does strand callers who query the old subject.
+        :meth:`renamed_subjects` is the forward pointer that resolves them, and
+        :meth:`list_facts` / :meth:`recall` consult it rather than returning a
+        silent empty.
+
+        Refused if ``old_id`` is not the live tip. The error names the current
+        tip. The insert of the new fact and the status flip of the old fact
+        happen in a single transaction.
         """
         conn = self._connect()
         try:
@@ -535,7 +663,7 @@ class MemoryStore:
             new_id = self._insert_fact(
                 conn,
                 project=old["project"],
-                subject=old["subject"],
+                subject=old["subject"] if subject is None else subject,
                 claim=claim,
                 source_type=source_type,
                 method=method,
@@ -694,6 +822,48 @@ class MemoryStore:
         finally:
             conn.close()
 
+    def renamed_subjects(self, project: str, subject: str) -> list[str]:
+        """Subjects that chains once filed under ``subject`` now live under.
+
+        The forward pointer for a subject rename. A correction may re-file a
+        fact (see :meth:`correct_fact`), which strands anything querying the old
+        dotted-path: the superseded row still carries it, but a live-status
+        filter drops that row and the query returns empty with no error: the
+        same wrong-input-looks-like-no-data failure the subject filter has
+        always been able to produce.
+
+        Returns the DISTINCT live subjects reached by following each superseded
+        row with this subject to its chain tip, excluding ``subject`` itself.
+        Empty when nothing was renamed, which is every chain written before
+        renaming existed, so this is inert on any store that predates it.
+        """
+        conn = self._connect()
+        try:
+            return self._renamed_subjects(conn, project, subject)
+        finally:
+            conn.close()
+
+    def _renamed_subjects(
+        self, conn: sqlite3.Connection, project: str, subject: str
+    ) -> list[str]:
+        """:meth:`renamed_subjects` on a caller-owned connection."""
+        rows = conn.execute(
+            "SELECT id FROM memory_facts "
+            "WHERE project=? AND subject=? AND status='superseded'",
+            (project, subject),
+        ).fetchall()
+        out: list[str] = []
+        for row in rows:
+            tip = conn.execute(
+                "SELECT subject, status FROM memory_facts WHERE id=?",
+                (self._find_tip(conn, row["id"]),),
+            ).fetchone()
+            if tip is None or tip["status"] != "live":
+                continue
+            if tip["subject"] != subject and tip["subject"] not in out:
+                out.append(tip["subject"])
+        return out
+
     def list_facts(
         self,
         project: str,
@@ -707,22 +877,45 @@ class MemoryStore:
         Ordered by insertion (``id DESC``), so a ``limit`` below the project's
         live count truncates by *recency of insertion*, not by relevance. Use
         :meth:`recall` when you want the highest-scoring facts.
+
+        A live-status subject query that matches nothing falls back to
+        :meth:`renamed_subjects`, so a subject that a correction re-filed
+        resolves forward to its tip instead of returning a silent empty. The
+        fallback runs ONLY when the direct match is empty: if the old subject
+        still has live facts of its own the query is answerable as asked, and
+        second-guessing it would surface rows the caller did not ask for.
         """
         if limit > _MAX_ROWS:
             limit = _MAX_ROWS
         conn = self._connect()
         try:
-            sql = "SELECT * FROM memory_facts WHERE project=? AND status=?"
-            params: list[Any] = [project, status]
-            if subject is not None:
-                sql += " AND subject=?"
-                params.append(subject)
-            sql += " ORDER BY id DESC LIMIT ?"
-            params.append(limit)
-            return [dict(r) for r in conn.execute(sql, params).fetchall()]
+            rows = self._list_facts(conn, project, subject, status, limit)
+            if rows or subject is None or status != "live":
+                return rows
+            for renamed in self._renamed_subjects(conn, project, subject):
+                rows += self._list_facts(conn, project, renamed, status, limit)
+            return rows[:limit]
         finally:
             conn.close()
 
+    @staticmethod
+    def _list_facts(
+        conn: sqlite3.Connection,
+        project: str,
+        subject: str | None,
+        status: str,
+        limit: int,
+    ) -> list[dict]:
+        """One direct :meth:`list_facts` query, with no rename fallback."""
+        sql = "SELECT * FROM memory_facts WHERE project=? AND status=?"
+        params: list[Any] = [project, status]
+        if subject is not None:
+            sql += " AND subject=?"
+            params.append(subject)
+        sql += " ORDER BY id DESC LIMIT ?"
+        params.append(limit)
+        return [dict(r) for r in conn.execute(sql, params).fetchall()]
+
     def count_live(self, project: str) -> int:
         """Number of live facts for ``project``.
 
@@ -862,12 +1055,40 @@ class MemoryStore:
         functions this falls back to scoring every candidate in Python, which
         returns identical rows for more wall-clock. Either way the result is the
         true top-``limit`` by score, never a slice of the most recently inserted.
+
+        A ``subject`` that matches nothing resolves forward through
+        :meth:`renamed_subjects`, exactly as in :meth:`list_facts`, so a
+        re-filed fact is still reachable by the dotted-path it used to carry.
+        The retry happens at most once: :meth:`_find_tip` already walks a chain
+        to its END, so one hop covers a subject renamed any number of times.
         """
         if now is None:
             now = datetime.now(timezone.utc)
         if limit > _MAX_ROWS:
             limit = _MAX_ROWS
 
+        hits = self._recall_once(project, query, subject, deep, limit, now)
+        if hits or subject is None or query is not None:
+            return hits
+        conn = self._connect()
+        try:
+            renamed = self._renamed_subjects(conn, project, subject)
+        finally:
+            conn.close()
+        for name in renamed:
+            hits += self._recall_once(project, query, name, deep, limit, now)
+        return hits[:limit]
+
+    def _recall_once(
+        self,
+        project: str,
+        query: str | None,
+        subject: str | None,
+        deep: bool,
+        limit: int,
+        now: datetime,
+    ) -> list[dict]:
+        """One scored :meth:`recall` pass, with no rename fallback."""
         conn = self._connect()
         try:
             if _sql_math_available(conn):
@@ -931,13 +1152,23 @@ class MemoryStore:
         limit: int,
         now: datetime,
     ) -> list[dict]:
-        """Score-ordered recall computed in Python (fallback; see :meth:`recall`)."""
+        """Score-ordered recall computed in Python (fallback; see :meth:`recall`).
+
+        Candidates come from :meth:`_list_facts`, NOT :meth:`list_facts`: the
+        rename fallback lives in :meth:`recall` and must fire once for both
+        paths. Going through the public method would resolve a second time here
+        and return the tip twice on this path only.
+        """
         if query is not None:
             candidates = self.search_live(query, project=project, limit=_MAX_ROWS)
         else:
-            candidates = self.list_facts(
-                project=project, subject=subject, limit=_MAX_ROWS
-            )
+            conn = self._connect()
+            try:
+                candidates = self._list_facts(
+                    conn, project, subject, "live", _MAX_ROWS
+                )
+            finally:
+                conn.close()
 
         scored = []
         for fact in candidates: