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

{echo_mem-0.5.0/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.0
+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.0 → 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.0"
+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.0 → 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.0
+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.2/src/echo_memory/infra/db.py

@@ -0,0 +1,83 @@
+"""Connection helper: every AGE-aware connection needs the extension loaded
+and ag_catalog on the search_path before any Cypher call (see PR0a's spike
+notes in the design doc's Foundational spike section)."""
+
+import os
+
+import psycopg
+from pgvector.psycopg import register_vector
+
+from echo_memory.infra.logging import get_logger
+
+GRAPH_NAME = "echo_memory"
+
+_logger = get_logger("db")
+
+# How hard HNSW looks before answering. Set per connection rather than per
+# query because every connection from the pool wants the same behaviour, and
+# because autocommit is on: SET LOCAL would expire at the end of the single
+# statement it was issued in and reach nothing.
+#
+# 200 is measured, not guessed. Against a real 38,169 fact scope, 20 probe
+# vectors, recall of the exact top 50 and the cost of getting it:
+#
+#     ef_search   mean recall   worst   top 10 identical   mean ms
+#     40 (dflt)         0.817    0.24          10 of 20       1.85
+#     100               0.944    0.74          13 of 20       1.72
+#     200               0.980    0.86          17 of 20       3.85
+#     400               0.985    0.90          19 of 20       8.26
+#     exact             1.000    1.00          20 of 20      52.47
+#
+# The default of 40 is below LIST_DEPTH, which is the specific reason it is
+# bad: asking an index for 50 neighbours while it keeps a candidate list of
+# 40 cannot go well, and 0.24 recall on the worst probe is what that looks
+# like. 200 buys 98% recall for 7% of the exact scan's time, and the exact
+# scan is O(n) - at ten times this scope it is half a second, per query.
+HNSW_EF_SEARCH = int(os.environ.get("ECHO_MEMORY_HNSW_EF_SEARCH", "200"))
+
+_warned_no_iterative_scan = False
+
+
+def configure_connection(conn: psycopg.Connection) -> None:
+    with conn.cursor() as cur:
+        cur.execute("LOAD 'age'")
+        cur.execute('SET search_path = ag_catalog, "$user", public')
+        _configure_vector_search(cur)
+    register_vector(conn)
+
+
+def _configure_vector_search(cur) -> None:
+    """HNSW settings, on a database that may be too old to have them.
+
+    iterative_scan is pgvector 0.8. Without it an index scan under a filter
+    stops at the first candidate batch and returns FEWER rows than the LIMIT
+    asked for - measured at 25 of 50 on the scope above, which is a silent
+    recall cut rather than an error. With it the scan continues until the
+    limit is met.
+
+    A 0.7 database has no such setting and errors on SET. That is not a
+    reason to refuse to start: the queries still work there, just exactly and
+    slowly, which is what every version of this code did until now. Warned
+    once, not per connection, because a pool opening ten of them would
+    otherwise say it ten times.
+    """
+    global _warned_no_iterative_scan
+    try:
+        cur.execute("SET hnsw.iterative_scan = strict_order")
+        # An int, interpolated: SET takes no parameters, and the value is
+        # coerced rather than passed through so the environment cannot put
+        # anything but a number into the statement.
+        cur.execute(f"SET hnsw.ef_search = {int(HNSW_EF_SEARCH)}")
+    except psycopg.errors.UndefinedObject:
+        if not _warned_no_iterative_scan:
+            _warned_no_iterative_scan = True
+            _logger.warning(
+                "hnsw_iterative_scan_unavailable",
+                extra={"detail": "pgvector < 0.8; vector search stays exact and O(n)"},
+            )
+
+
+def connect(database_url: str) -> psycopg.Connection:
+    conn = psycopg.connect(database_url, autocommit=True)
+    configure_connection(conn)
+    return conn

{echo_mem-0.5.0 → echo_mem-0.5.2}/src/echo_memory/retrieval/causality.py

@@ -83,22 +83,27 @@ def _anchor_nodes(conn, group_id: str, subject: str, embedder, anchors: int) ->
     question and part of the answer.
     """
     embedding = embedder.embed(subject)
+    # Distance only in the ORDER BY, for the reason spelled out in
+    # query_memory._vector_candidates: a second sort key costs the HNSW index
+    # and turns this into a scan of every entity in the scope. This function
+    # shipped with that mistake in it earlier today. The tiebreak it wanted is
+    # applied below instead, where it is free.
     rows = conn.execute(
         """SELECT ne.node_id::text, -(ne.embedding <#> %s::vector) AS similarity
             FROM public.node_embedding ne
             WHERE ne.group_id = %s
-            -- A stated tiebreak, so two entities at an identical distance
-            -- always resolve the same way and the same store answers the same
-            -- question the same way twice.
-            ORDER BY ne.embedding <#> %s::vector, ne.node_id
+            ORDER BY ne.embedding <#> %s::vector
             LIMIT %s""",
         (embedding, group_id, embedding, anchors),
     ).fetchall()
     if not rows:
         return []
 
-    best = float(rows[0][1])
-    kept = [(nid, float(sim)) for nid, sim in rows if float(sim) >= best - ANCHOR_MARGIN]
+    ordered = sorted(
+        ((nid, float(sim)) for nid, sim in rows), key=lambda row: (-row[1], row[0])
+    )
+    best = ordered[0][1]
+    kept = [(nid, sim) for nid, sim in ordered if sim >= best - ANCHOR_MARGIN]
     names = _node_names(conn, group_id, [nid for nid, _ in kept])
     return [
         {"node_id": nid, "name": names.get(nid, "?"), "similarity": round(sim, 4)}

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

@@ -282,26 +282,53 @@ def adaptive_cosine_floor(conn, group_id: str) -> float:
     return floor
 
 
-def _vector_candidates(
-    conn, group_id: str, embedding: list[float], limit: int, floor: float | None = None
-) -> list[str]:
-    rows = conn.execute(
-        f"""
+# Held as a constant so the test that checks this query is still indexable
+# runs EXPLAIN on the same text the function executes, rather than on a copy
+# that can drift away from it. See tests/integration/test_vector_index.py.
+VECTOR_CANDIDATE_SQL = f"""
         SELECT fe.edge_id::text, -(fe.embedding <#> %s::vector) AS score
         FROM public.fact_embedding fe
         JOIN {GRAPH}."FACT" f ON f.id = fe.edge_id
         WHERE fe.group_id = %s
           AND (f.properties ->> '"t_invalid"'::agtype) IS NULL
-        -- Same reason as the lexical channel below: a stated tiebreak, so two
-        -- facts at an identical distance always resolve the same way.
-        ORDER BY fe.embedding <#> %s::vector, fe.edge_id
+        ORDER BY fe.embedding <#> %s::vector
         LIMIT %s
-        """,
-        (embedding, group_id, embedding, limit),
-    ).fetchall()
+        """
+
+
+def _vector_candidates(
+    conn, group_id: str, embedding: list[float], limit: int, floor: float | None = None,
+    scores: dict[str, float] | None = None,
+) -> list[str]:
+    """Ids, best first. Pass `scores` to also collect the cosine similarity
+    this already computed and then threw away - the one number in this system
+    a caller can threshold on, because unlike a fusion score it means the same
+    thing from one query to the next."""
+    # ORDER BY the distance and NOTHING else. pgvector's HNSW index can only
+    # answer `ORDER BY <distance> LIMIT n`; a second sort key makes the whole
+    # clause unindexable, and the planner falls back to reading every
+    # embedding in the scope and sorting them.
+    #
+    # There WAS a second key here - `, fe.edge_id`, added so two facts at an
+    # identical distance always resolved the same way. It cost the index.
+    # Measured on a real 38,169 fact scope: 52.47ms doing the full scan
+    # against 3.85ms using the index, and the scan is O(n), so ten times the
+    # facts is half a second on every query. The determinism it bought is
+    # still wanted and is now applied below, where it costs nothing.
+    rows = conn.execute(VECTOR_CANDIDATE_SQL, (embedding, group_id, embedding, limit)).fetchall()
     if floor is None:
         floor = adaptive_cosine_floor(conn, group_id)
-    return [edge_id for edge_id, score in rows if score >= floor]
+    # The tiebreak, moved out of SQL. Sorting by (-score, edge_id) reproduces
+    # what the old ORDER BY produced - best first, ties resolved by id - on a
+    # list of at most LIST_DEPTH rows, which is free. Python's sort is stable,
+    # so rows that were already ordered by the index keep that order.
+    ranked = sorted(
+        ((edge_id, float(score)) for edge_id, score in rows if score >= floor),
+        key=lambda row: (-row[1], row[0]),
+    )
+    if scores is not None:
+        scores.update(dict(ranked))
+    return [edge_id for edge_id, _ in ranked]
 
 
 
@@ -535,6 +562,83 @@ 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.
+
+    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"]
+        matched = [
+            name for name, ids in (("vector", vector_ids), ("lexical", lexical_ids))
+            if edge_id in ids
+        ]
+        if not matched:
+            continue
+        fact["rank"] = position
+        if edge_id in similarity:
+            fact["score"] = round(similarity[edge_id], 4)
+        fact["matched"] = matched
+
+
 def query_memory(
     conn, group_id: str, query: str | None, top_k: int, embedder,
     digest: bool = False, lexical_only: bool = False,
@@ -584,6 +688,8 @@ 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 = [], []
@@ -592,8 +698,10 @@ 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)
-        vector_ids = _vector_candidates(conn, group_id, embedding, LIST_DEPTH, floor=floor)
+        embedding = query_embedding = embedder.embed(query)
+        vector_ids = _vector_candidates(
+            conn, group_id, embedding, LIST_DEPTH, floor=floor, scores=similarity
+        )
         # ANY-term, not websearch_to_tsquery's implicit AND.
         #
         # The AND form requires every non-stopword term of the query to appear
@@ -661,6 +769,15 @@ 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(
         _logger,

{echo_mem-0.5.0 → 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,6 +287,18 @@ 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.
+
+    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
     write_episode with the entities and facts it states, then mark it done

echo_mem-0.5.0/src/echo_memory/infra/db.py

@@ -1,21 +0,0 @@
-"""Connection helper: every AGE-aware connection needs the extension loaded
-and ag_catalog on the search_path before any Cypher call (see PR0a's spike
-notes in the design doc's Foundational spike section)."""
-
-import psycopg
-from pgvector.psycopg import register_vector
-
-GRAPH_NAME = "echo_memory"
-
-
-def configure_connection(conn: psycopg.Connection) -> None:
-    with conn.cursor() as cur:
-        cur.execute("LOAD 'age'")
-        cur.execute('SET search_path = ag_catalog, "$user", public')
-    register_vector(conn)
-
-
-def connect(database_url: str) -> psycopg.Connection:
-    conn = psycopg.connect(database_url, autocommit=True)
-    configure_connection(conn)
-    return conn