echo-mem 0.5.1__tar.gz → 0.5.2__tar.gz

{echo_mem-0.5.1/src/echo_mem.egg-info → echo_mem-0.5.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: echo-mem
-Version: 0.5.1
+Version: 0.5.2
 Summary: A long-horizon memory architecture for AI agents
 License-Expression: BUSL-1.1
 Requires-Python: >=3.11

{echo_mem-0.5.1 → echo_mem-0.5.2}/pyproject.toml

@@ -6,7 +6,7 @@
 # (`-m echo_memory.server`) and every existing install reference it, and
 # renaming the module would break live configuration to fix a cosmetic mismatch.
 name = "echo-mem"
-version = "0.5.1"
+version = "0.5.2"
 description = "A long-horizon memory architecture for AI agents"
 readme = "README.md"
 # BUSL-1.1 is the SPDX identifier for the Business Source License 1.1, so

{echo_mem-0.5.1 → echo_mem-0.5.2/src/echo_mem.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: echo-mem
-Version: 0.5.1
+Version: 0.5.2
 Summary: A long-horizon memory architecture for AI agents
 License-Expression: BUSL-1.1
 Requires-Python: >=3.11

{echo_mem-0.5.1 → echo_mem-0.5.2}/src/echo_memory/retrieval/query_memory.py

@@ -562,33 +562,68 @@ def _provenance(raw, agent_id, project) -> dict | None:
     return out
 
 
+def _missing_similarity(
+    conn, group_id: str, embedding: list[float], edge_ids: list[str]
+) -> dict[str, float]:
+    """Cosine for facts the vector channel never scored.
+
+    The lexical channel computes no similarity, so a fact only it found
+    arrived with score null. That is an implementation detail - which channel
+    happened to retrieve it - leaking into a field callers read as relevance.
+
+    Fixed by computing the number instead of omitting it. At most top_k rows,
+    by primary key, with the query embedding already in hand.
+    """
+    if not edge_ids:
+        return {}
+    rows = conn.execute(
+        """SELECT fe.edge_id::text, -(fe.embedding <#> %s::vector)
+             FROM public.fact_embedding fe
+            WHERE fe.group_id = %s
+              AND fe.edge_id = ANY(SELECT unnest(%s::text[])::graphid)""",
+        (embedding, group_id, list(edge_ids)),
+    ).fetchall()
+    return {str(edge_id): float(score) for edge_id, score in rows}
+
+
 def _annotate(
     facts: list[dict], similarity: dict[str, float],
     vector_ids: set[str], lexical_ids: set[str],
 ) -> None:
     """Say why each fact is in the answer, in place.
 
-    Retrieval returned a bare ordered list and nothing else, so a caller who
-    wanted "only use this if it is actually about my question" had no number
-    to test. The first customer to hit it wrote relevance filters at four
-    call sites to reconstruct, from the fact text, something this function
-    already knew.
-
-    Three fields, each chosen because a caller can act on it:
-
-    rank        position in this answer, 1 first. Cheap, and enough for
-                "only consider the top three".
-    score       cosine similarity to the query, or null when the fact came
-                only from the lexical channel and no similarity was computed.
-                This is the number to threshold on: unlike a fusion score it
-                means the same thing from one query to the next, and it is
-                the same quantity the adaptive floor already trusts.
-    matched     which channels found it. A fact both channels found is a
-                different kind of answer from one only the vector channel
-                reached, and that distinction is free here and impossible to
-                recover afterwards.
-
-    Absent on a digest, which ranks nothing.
+    rank        position in this answer, 1 first. THIS is the ordering to
+                trust and the one to truncate by. It is the fused result of
+                every channel, which is the system's whole opinion; score is
+                one input to it, and re-sorting by a single input discards
+                the fusion.
+    score       cosine similarity to the query. Present on every fact of
+                every answer the MCP surface can ask for, and it means the
+                same thing for every fact whatever channel found it.
+                Diagnostic, NOT a correctness gate: a fact found by exact
+                keyword match can be the right answer at a low semantic
+                score.
+
+                Absent in exactly one place, and not one a tool caller can
+                reach: the UserPromptSubmit hook runs lexical_only in a fresh
+                process precisely to avoid a 6.2 second model load, so there
+                is no embedding to compare against and no honest number to
+                give. Omitted rather than faked.
+    matched     which channels found it, as information rather than quality.
+
+    The null that used to appear here caused real harm and the shape of it is
+    worth keeping. score was omitted for lexical-only facts, a customer sorted
+    by score with nulls last, and every fact full text search had found went
+    to the back of the list - where a character budget truncated it and the
+    model filled the gap by inventing something. The fact it dropped was
+    correct and was in the store.
+
+    Their own calibration says why that is backwards. Over ten questions with
+    every fact judged against every question: lexical-only scored R@3 0.640
+    against vector-only's 0.460, and beat the fused ranking outright on two of
+    the ten. The channel that was being demoted has the better recall.
+
+    Absent on a digest too, which ranks nothing against nothing.
     """
     for position, fact in enumerate(facts, start=1):
         edge_id = fact["fact_id"]
@@ -599,7 +634,8 @@ def _annotate(
         if not matched:
             continue
         fact["rank"] = position
-        fact["score"] = round(similarity[edge_id], 4) if edge_id in similarity else None
+        if edge_id in similarity:
+            fact["score"] = round(similarity[edge_id], 4)
         fact["matched"] = matched
 
 
@@ -653,6 +689,7 @@ def query_memory(
         return {"error": str(e)}
 
     similarity: dict[str, float] = {}
+    query_embedding: list[float] | None = None
     if digest:
         ranked_ids = _digest_candidates(conn, group_id, top_k)
         vector_ids, lexical_ids = [], []
@@ -661,7 +698,7 @@ def query_memory(
         lexical_ids = _lexical_any_candidates(conn, group_id, query, LIST_DEPTH)
         ranked_ids = lexical_ids[:top_k]
     else:
-        embedding = embedder.embed(query)
+        embedding = query_embedding = embedder.embed(query)
         vector_ids = _vector_candidates(
             conn, group_id, embedding, LIST_DEPTH, floor=floor, scores=similarity
         )
@@ -732,6 +769,14 @@ def query_memory(
 
     facts_by_id = _fetch_facts(conn, ranked_ids)
     facts = [facts_by_id[edge_id] for edge_id in ranked_ids if edge_id in facts_by_id]
+    # Score whatever the vector channel did not, so every returned fact has
+    # one. Only on the query path: a digest ranks nothing and has no query to
+    # be similar to.
+    if query_embedding is not None:
+        unscored = [f["fact_id"] for f in facts if f["fact_id"] not in similarity]
+        similarity.update(
+            _missing_similarity(conn, group_id, query_embedding, unscored)
+        )
     _annotate(facts, similarity, set(vector_ids), set(lexical_ids))
 
     log_query_memory(

{echo_mem-0.5.1 → echo_mem-0.5.2}/src/echo_memory/server.py

@@ -5,6 +5,7 @@ Runs over stdio by default (mcp.server.mcpserver's MCPServer.run default),
 not a network listener at all, let alone one bound beyond localhost; see
 the design doc's Constraints ("v1 is single-user, local-only")."""
 
+import atexit
 import inspect
 import json
 import threading
@@ -106,6 +107,30 @@ def startup(config: Config | None = None, embedder: Embedder | None = None) -> N
         # a background task turns into confusing output somewhere else.
         _state.warming = threading.Thread(target=_warm, args=(warm,), daemon=True)
         _state.warming.start()
+        # Wait for it at exit, briefly, rather than letting the interpreter
+        # tear down underneath it.
+        #
+        # A daemon thread is killed abruptly at shutdown. This one is inside
+        # torch when that happens, and killing a thread mid C++ produces
+        # "terminate called without an active exception" and SIGABRT - exit
+        # code 134, after every test has already passed. CI saw exactly that:
+        # 771 passed, 5 skipped, then aborted. It is timing dependent, so it
+        # is rare on a machine with the model cached and common on one
+        # downloading it, which is the wrong way round for a release gate.
+        #
+        # Bounded, because the point of loading in the background is that
+        # nothing waits for it. A load still running after this long is one
+        # the process was never going to benefit from anyway.
+        atexit.register(_finish_warming)
+
+
+WARM_SHUTDOWN_GRACE_SECONDS = 10.0
+
+
+def _finish_warming() -> None:
+    warming = getattr(_state, "warming", None)
+    if warming is not None and warming.is_alive():
+        warming.join(timeout=WARM_SHUTDOWN_GRACE_SECONDS)
 
 
 def _warm(warm) -> None:
@@ -119,8 +144,16 @@ def _warm(warm) -> None:
             "embedder_warm",
             extra={"duration_ms": (time.perf_counter() - started) * 1000},
         )
-    except Exception:  # see docstring
-        _logger.warning("embedder_warm_failed", exc_info=True)
+    except Exception:  # noqa: BLE001 - see docstring
+        # Logging can itself fail here, and does: a thread still running while
+        # the interpreter shuts down finds the log stream closed and atexit
+        # refusing new registrations, so reporting the first failure raises a
+        # second one out of a thread with nowhere to put it. The report is
+        # best effort; the swallow is the contract in the docstring.
+        try:
+            _logger.warning("embedder_warm_failed", exc_info=True)
+        except Exception:  # noqa: BLE001, S110 - nowhere left to report to
+            pass
 
 
 def _tool(fn):
@@ -254,11 +287,17 @@ def query_memory(scope: str, query: str | None = None, top_k: int = 10, digest:
     facts instead, as an opt-in "catch me up" convenience; call it
     explicitly at session start if you want one, it's never automatic.
 
-    Each fact carries rank (1 first), score and matched. score is cosine
-    similarity to your query, comparable across queries, and null when only
-    the lexical channel found the fact. matched names the channels that did:
-    a fact both found is a stronger answer than one only one reached. Use
-    them instead of writing your own relevance filter over the text.
+    Each fact carries rank (1 first), score and matched.
+
+    If you must drop facts to fit a budget, drop by rank. It is the fused
+    result of every channel, which is this server's whole opinion; score is
+    one input to it, and re-sorting by a single input throws the rest away.
+
+    score is cosine similarity to your query, present on every fact and
+    comparable across queries. It is diagnostic, not a correctness test: a
+    fact found by exact keyword match can be the right answer at a low
+    score. matched names the channels that found it, as information - full
+    text search is not the weaker one, it has the better recall here.
 
     A pending_ingest field appears when memory files have been written that
     the graph hasn't heard about yet. Read each listed file and call