loop-memory 0.4.14__tar.gz → 0.4.15__tar.gz

{loop_memory-0.4.14 → loop_memory-0.4.15}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: loop-memory
-Version: 0.4.14
+Version: 0.4.15
 Summary: A general-purpose, local memory system for every AI agent you run. Loop Memory auto-captures conversations from Codex / Claude / Hermes / OpenClaw, scores them by importance × recency × usage × feedback, distils them into a curated wiki, and serves everything from a single web UI.
 Author: Loop Memory contributors <loop-memory@users.noreply.github.com>
 License-Expression: MIT
@@ -66,6 +66,7 @@ Dynamic: license-file
 
 ---
 
+> **What's new in 0.4.15** — **content-hash dedup + bi-temporal validity window + evidence chain + `@agent_memory` decorator** (audit 2026-10-18, weekly ecosystem sync). Three new columns on `memories`: `content_hash` (SHA-256 of normalised text, indexed), `valid_at` (epoch the memory becomes active), `invalid_at` (epoch it expires — NULL means still open-ended). The schema migration bumps `SCHEMA_VERSION` 11 → 12 with an idempotent backfill so legacy DBs upgrade in-place. New `upsert_memory(valid_at=, invalid_at=, dedup=)` parameters let callers schedule future-dated or expiring memories and opt out of content-hash dedup for episodic event streams. `recall()` and `recall_hybrid()` now accept an optional `as_of_ts` (float epoch or ISO-8601) — when set, both methods drop memories whose `valid_at > as_of` or `invalid_at <= as_of`, complementing the existing `recall_as_of()` supersession-chain walk. Every recall hit now carries an `evidence: [{field, value, weight}]` array — BM25 / semantic / entity / rrf_total / high_importance channels are exposed individually so a UI can render "this hit because ... [bm25 1.0] [entity 0.7]" instead of a black-box score (Cognee 1.0 / Mem0 v2 evidence-citation pattern, zero-dep). New `loop_memory.decorators` exposes `@agent_memory(store, agent_id=, limit=)` — a one-line wrapper that recalls the top-k relevant memories before the body runs and writes a fresh `kind="interaction"` memory after. Strings returned from the wrapped function are stored verbatim; dict/list returns are JSON-serialised; the recall list is injected as a `memory_context` keyword when the function declares it, otherwise attached to dict results under `memories`. Sister `remember(store, text, ...)` helper for seeding. The BM25 `_like_fallback` now falls through to per-token OR-LIKE when the whole-string match returns nothing — natural-language questions like "What is the deploy process?" now hit stored facts even when FTS5 trigram can't match quoted exact phrases. Source: Cognee 1.0 ECL pipeline + Mem0 v2 hybrid fusion + Zep/Graphiti bi-temporal validity fields + Letta block-memory (pattern only, no code copied). 59 new regression cases. [Full CHANGELOG →](./CHANGELOG.md#0415---2026-10-18)
 > **What's new in 0.4.14** — **`loop-memory doctor` deep store-health check** (audit 2026-10-12). Ten diagnostic checks — `db_exists`, `db_integrity`, `schema_version`, `audit_triggers`, `audit_log_writable`, `audit_log_size`, `hooks_installed`, `version_consistent`, `wiki_no_orphans`, `recall_paths_works` — report `ok`/`info`/`warn`/`error` for the live `MemoryStore`. `--fix` auto-repairs the `audit_triggers` check. `--json` emits a stable shape for CI. `--list` prints the check function names without touching the store. `--verbose` shows `info`-level checks. Exit code `1` on any `error` status, `0` otherwise. Source: `cortexkit/magic-context doctor` auto-diagnostic pattern (MIT, 2026-10-12) + `dsh-memento` write-approval-gate pattern (Apache-2.0, 2026-10-12). Stdlib-only — we re-implement from scratch against our own `MemoryStore`. Also fixed a Python 3.14 bug: chained `store._conn().__enter__()` immediately triggers the contextmanager's `finally` and closes the connection mid-query — both call sites in `doctor.py` now use explicit `with` form. 27 new regression cases. [Full CHANGELOG →](./CHANGELOG.md#0414---2026-10-12)
 
 > **What's new in 0.4.13** — **recall token / char budget cap** + **unified `level=0|1|2` tiered-loader knob** (audit 2026-10-05). New `max_chars` parameter on `MemoryStore.recall()` / `recall_paths()` / `recall_hybrid()` / `recall_as_of()` caps the *total* payload across all returned hits — when the budget is exceeded the lowest-ranked hit shrinks first so the top-scoring hits always keep their full body. `recall()` / `recall_paths()` / `recall_as_of()` now also accept `level=0|1|2` so a caller can ask for the L0 abstract ladder rung inline (titles + tags + abstract only, never the full `text` / `body`) without routing through `recall_paths()` separately. Both knobs are wired through the HTTP routes (`GET /api/recall?max_chars=&level=`, `GET /api/recall/outline?max_chars=`), the CLI (`loop-memory recall --max-chars N --level 0|1|2`, `recall-paths --max-chars N`), the SDK (`LoopMemoryClient.recall(max_chars=, level=)`), and the MCP `tool_recall` server. Source: `vectorize-io/hindsight v0.10.2` "concise extraction by default" (Apache-2.0, 2026-09-29) + `aiming-lab/SimpleMem` ICML'26 semantic-lossless-compression (Apache-2.0, 2026-10-04) + `volcengine/OpenViking` tiered-loader (AGPLv3, 2026-10-02 — *pattern only, no code copied*). 26 new regression cases. [Full CHANGELOG →](./CHANGELOG.md#0413---2026-10-05)

{loop_memory-0.4.14 → loop_memory-0.4.15}/README.md

@@ -22,6 +22,7 @@
 
 ---
 
+> **What's new in 0.4.15** — **content-hash dedup + bi-temporal validity window + evidence chain + `@agent_memory` decorator** (audit 2026-10-18, weekly ecosystem sync). Three new columns on `memories`: `content_hash` (SHA-256 of normalised text, indexed), `valid_at` (epoch the memory becomes active), `invalid_at` (epoch it expires — NULL means still open-ended). The schema migration bumps `SCHEMA_VERSION` 11 → 12 with an idempotent backfill so legacy DBs upgrade in-place. New `upsert_memory(valid_at=, invalid_at=, dedup=)` parameters let callers schedule future-dated or expiring memories and opt out of content-hash dedup for episodic event streams. `recall()` and `recall_hybrid()` now accept an optional `as_of_ts` (float epoch or ISO-8601) — when set, both methods drop memories whose `valid_at > as_of` or `invalid_at <= as_of`, complementing the existing `recall_as_of()` supersession-chain walk. Every recall hit now carries an `evidence: [{field, value, weight}]` array — BM25 / semantic / entity / rrf_total / high_importance channels are exposed individually so a UI can render "this hit because ... [bm25 1.0] [entity 0.7]" instead of a black-box score (Cognee 1.0 / Mem0 v2 evidence-citation pattern, zero-dep). New `loop_memory.decorators` exposes `@agent_memory(store, agent_id=, limit=)` — a one-line wrapper that recalls the top-k relevant memories before the body runs and writes a fresh `kind="interaction"` memory after. Strings returned from the wrapped function are stored verbatim; dict/list returns are JSON-serialised; the recall list is injected as a `memory_context` keyword when the function declares it, otherwise attached to dict results under `memories`. Sister `remember(store, text, ...)` helper for seeding. The BM25 `_like_fallback` now falls through to per-token OR-LIKE when the whole-string match returns nothing — natural-language questions like "What is the deploy process?" now hit stored facts even when FTS5 trigram can't match quoted exact phrases. Source: Cognee 1.0 ECL pipeline + Mem0 v2 hybrid fusion + Zep/Graphiti bi-temporal validity fields + Letta block-memory (pattern only, no code copied). 59 new regression cases. [Full CHANGELOG →](./CHANGELOG.md#0415---2026-10-18)
 > **What's new in 0.4.14** — **`loop-memory doctor` deep store-health check** (audit 2026-10-12). Ten diagnostic checks — `db_exists`, `db_integrity`, `schema_version`, `audit_triggers`, `audit_log_writable`, `audit_log_size`, `hooks_installed`, `version_consistent`, `wiki_no_orphans`, `recall_paths_works` — report `ok`/`info`/`warn`/`error` for the live `MemoryStore`. `--fix` auto-repairs the `audit_triggers` check. `--json` emits a stable shape for CI. `--list` prints the check function names without touching the store. `--verbose` shows `info`-level checks. Exit code `1` on any `error` status, `0` otherwise. Source: `cortexkit/magic-context doctor` auto-diagnostic pattern (MIT, 2026-10-12) + `dsh-memento` write-approval-gate pattern (Apache-2.0, 2026-10-12). Stdlib-only — we re-implement from scratch against our own `MemoryStore`. Also fixed a Python 3.14 bug: chained `store._conn().__enter__()` immediately triggers the contextmanager's `finally` and closes the connection mid-query — both call sites in `doctor.py` now use explicit `with` form. 27 new regression cases. [Full CHANGELOG →](./CHANGELOG.md#0414---2026-10-12)
 
 > **What's new in 0.4.13** — **recall token / char budget cap** + **unified `level=0|1|2` tiered-loader knob** (audit 2026-10-05). New `max_chars` parameter on `MemoryStore.recall()` / `recall_paths()` / `recall_hybrid()` / `recall_as_of()` caps the *total* payload across all returned hits — when the budget is exceeded the lowest-ranked hit shrinks first so the top-scoring hits always keep their full body. `recall()` / `recall_paths()` / `recall_as_of()` now also accept `level=0|1|2` so a caller can ask for the L0 abstract ladder rung inline (titles + tags + abstract only, never the full `text` / `body`) without routing through `recall_paths()` separately. Both knobs are wired through the HTTP routes (`GET /api/recall?max_chars=&level=`, `GET /api/recall/outline?max_chars=`), the CLI (`loop-memory recall --max-chars N --level 0|1|2`, `recall-paths --max-chars N`), the SDK (`LoopMemoryClient.recall(max_chars=, level=)`), and the MCP `tool_recall` server. Source: `vectorize-io/hindsight v0.10.2` "concise extraction by default" (Apache-2.0, 2026-09-29) + `aiming-lab/SimpleMem` ICML'26 semantic-lossless-compression (Apache-2.0, 2026-10-04) + `volcengine/OpenViking` tiered-loader (AGPLv3, 2026-10-02 — *pattern only, no code copied*). 26 new regression cases. [Full CHANGELOG →](./CHANGELOG.md#0413---2026-10-05)

{loop_memory-0.4.14 → loop_memory-0.4.15}/loop_memory/cli/commands/read.py

@@ -73,6 +73,9 @@ def run_recall(args) -> int:
     outline = False
     limit = 10
     as_of: float | None = None
+    # Audit 2026-10-18: bi-temporal *validity* window (distinct
+    # from ``as_of`` which routes through the supersession chain).
+    validity_at: float | None = None
     max_chars: int | None = None
     level = 1
     qargs: list[str] = []
@@ -106,6 +109,24 @@ def run_recall(args) -> int:
                         f"--as-of must be float epoch or ISO-8601; got {raw!r}"
                     )
             i += 2
+        elif a == "--validity-at" and i + 1 < len(args):
+            # Audit 2026-10-18 (loop-memory 0.4.15) -- cheaper
+            # validity-window filter (vs --as-of which walks the
+            # supersession chain). Accepts the same float-or-ISO.
+            raw = args[i + 1].strip()
+            try:
+                validity_at = float(raw)
+            except ValueError:
+                try:
+                    from datetime import datetime
+                    validity_at = datetime.fromisoformat(
+                        raw.replace("Z", "+00:00")
+                    ).timestamp()
+                except Exception:
+                    return die(
+                        f"--validity-at must be float epoch or ISO-8601; got {raw!r}"
+                    )
+            i += 2
         elif a == "--max-chars" and i + 1 < len(args):
             # Audit 2026-10-05 (vectorize-io/hindsight v0.10.2 +
             # aiming-lab/SimpleMem ICML'26) — cap the total payload
@@ -154,7 +175,12 @@ def run_recall(args) -> int:
         r = store.recall_paths(query, limit=limit, max_chars=max_chars)
     else:
         r = store.recall(query, limit=limit,
-                          max_chars=max_chars, level=level)
+                          max_chars=max_chars, level=level,
+                          # Audit 2026-10-18: pass validity_at through
+                          # to recall() so the new bi-temporal window
+                          # filter applies. ``None`` keeps the legacy
+                          # "everything" semantics.
+                          as_of_ts=validity_at)
     has = False
     if r["wiki"]:
         has = True

loop_memory-0.4.15/loop_memory/decorators.py

@@ -0,0 +1,243 @@
+"""Lightweight decorators for one-line agent memory integration.
+
+Audit 2026-10-18 (loop-memory 0.4.15): the decorator pattern is the
+adoption-shortcut inspired by LangChain ``@tool`` / Mem0 v2's
+``@remember`` -- a single line of boilerplate turns any plain Python
+function into an "agent-callable" that reads from long-term memory
+before it runs and writes a fresh memory after it returns.
+
+Two decorators ship here:
+
+* :func:`agent_memory` -- wraps a callable so every invocation:
+  - **recalls** the top-k relevant memories for the function's first
+    string argument (the "query") *before* running the body, and
+    - either exposes the recall as a ``memory_context`` keyword
+      argument (when the wrapped function's signature declares it),
+      OR surfaces it on the return value as ``result["memories"]``;
+  - **stores** the (query, return-value) pair as a single
+    ``kind="interaction"`` memory row *after* the body finishes, so
+    the next invocation can recall it.
+
+* :func:`remember` -- a tiny sugar that just calls
+  ``store.upsert_memory(kind="fact", text=text, ...)`` once at
+  definition time. Useful for facts the agent wants to hard-code into
+  memory at import time ("I am a code assistant", "My user prefers
+  dark mode", etc.).
+
+Both decorators are intentionally zero-dep and free of any LLM/agent
+framework dependency -- they sit on top of the public
+``MemoryStore`` API only.
+"""
+from __future__ import annotations
+
+import functools
+import inspect
+import json
+from collections.abc import Callable
+from typing import Any, ParamSpec, TypeVar
+
+from .storage.sqlite_store import MemoryStore
+
+P = ParamSpec("P")
+R = TypeVar("R")
+
+
+def _stringify(value: Any, *, max_len: int = 2000) -> str:
+    """Coerce a Python return value to a memory-friendly string.
+
+    * ``str``  -> as-is (truncated to ``max_len``).
+    * ``dict`` / ``list`` -> JSON-serialised then truncated.
+    * ``bytes``-> hex preview.
+    * everything else -> ``repr(value)``.
+
+    The truncation is the only place this helper swallows information;
+    downstream recall still works because the original ``text`` is on
+    the row, and the full structured payload is also stored verbatim
+    in ``tags`` when the caller passes a dict/list.
+    """
+    if isinstance(value, str):
+        return value if len(value) <= max_len else value[: max_len - 1] + "\u2026"
+    if isinstance(value, (dict, list)):
+        s = json.dumps(value, ensure_ascii=False, default=str)
+        return s if len(s) <= max_len else s[: max_len - 1] + "\u2026"
+    if isinstance(value, bytes):
+        return value[:64].hex() + (f" (len={len(value)})" if len(value) > 64 else "")
+    return repr(value)
+
+
+def _first_string_arg(
+    args: tuple, kwargs: dict, signature: inspect.Signature
+) -> str | None:
+    """Return the first positional str argument from the call.
+
+    Falls back to ``None`` when the call carries no string-y input
+    (e.g. ``@agent_memory`` wrapping an internal ``tick()`` that
+    takes only objects).
+    """
+    if args:
+        first = args[0]
+        if isinstance(first, str) and first.strip():
+            return first
+        return None
+    for name, p in signature.parameters.items():
+        if name in kwargs:
+            v = kwargs[name]
+            if isinstance(v, str) and v.strip():
+                return v
+            return None
+    return None
+
+
+def agent_memory(
+    store: MemoryStore,
+    *,
+    agent_id: str | None = None,
+    user_id: str | None = None,
+    kind: str = "interaction",
+    limit: int = 5,
+    recall_kwargs_name: str = "memory_context",
+) -> Callable[[Callable[P, R]], Callable[P, R]]:
+    """Wrap ``fn`` so every call reads + writes persistent memory.
+
+    Parameters
+    ----------
+    store:
+        An open :class:`~loop_memory.storage.sqlite_store.MemoryStore`.
+        Required -- the decorator has nowhere to put memory otherwise.
+    agent_id, user_id:
+        Optional identity columns. When ``None`` the wrapped call
+        pushes a memory that is global to the store (the same scope
+        that pre-0.4.15 callers used).
+    kind:
+        Memory row kind. Default ``"interaction"`` matches the
+        dashboard's existing tag.
+    limit:
+        Number of top-k memories to recall *before* the body runs.
+        Capped at 50 to keep the prompt tiny.
+    recall_kwargs_name:
+        Name of the optional kwarg the wrapped function can declare to
+        receive the recall as a string. Defaults to ``"memory_context"``.
+        If the function does NOT declare that kwarg the recall is
+        silently dropped (the body still runs) but the row is still
+        stored after the call returns.
+
+    Example
+    -------
+    >>> store = MemoryStore("loop.db")
+    >>> @agent_memory(store, agent_id="codex")
+    ... def ask(question: str, memory_context: str = "") -> str:
+    ...     # memory_context arrives pre-formatted from the recall
+    ...     return f"{question} -> {memory_context[:40]}"
+    >>> ask("What is the deploy process?")
+    """
+    if not isinstance(store, MemoryStore):
+        raise TypeError(
+            f"@agent_memory requires a MemoryStore, got {type(store).__name__}"
+        )
+    if limit <= 0 or limit > 50:
+        raise ValueError(f"limit must be in [1, 50], got {limit}")
+
+    def _decorator(fn: Callable[P, R]) -> Callable[P, R]:
+        sig = inspect.signature(fn)
+        _ = sig  # pre-bound for _first_string_arg
+        recall_kw = recall_kwargs_name
+
+        @functools.wraps(fn)
+        def _wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
+            query = _first_string_arg(args, kwargs, sig)
+            # --- pre-call: recall ---------------------------------
+            recall_hits: list[dict] = []
+            context_text = ""
+            if query:
+                try:
+                    res = store.recall_hybrid(
+                        query, limit=limit, as_of_ts=None,
+                    )
+                    recall_hits = list(res.get("memories", []))
+                except Exception:
+                    recall_hits = []
+                if recall_hits:
+                    lines = []
+                    for h in recall_hits:
+                        prev = (h.get("text") or h.get("preview") or "").strip()
+                        if prev:
+                            lines.append(f"- {prev[:240]}")
+                    context_text = "\n".join(lines)
+
+            # Inject memory_context only when the function actually
+            # declares the kwarg -- otherwise the decorator stays
+            # invisible to legacy callables that don't know about it.
+            injected = False
+            if recall_kw in sig.parameters and context_text:
+                kwargs = {**kwargs, recall_kw: context_text}
+                injected = True
+
+            # --- body ----------------------------------------------
+            result = fn(*args, **kwargs)
+
+            # --- post-call: store ----------------------------------
+            if query:
+                try:
+                    text = _stringify(result)
+                    tags = ["agent_memory"]
+                    if isinstance(result, (dict, list)):
+                        tags.append("structured")
+                    store.upsert_memory(
+                        kind=kind,
+                        text=text,
+                        importance=0.6,
+                        agent_id=agent_id,
+                        user_id=user_id,
+                        tags=tags,
+                        source=f"agent_memory:{fn.__name__}",
+                    )
+                except Exception:
+                    # Never let a store failure break the wrapped call.
+                    pass
+
+            # Attach the recall to a dict result so callers can
+            # surface "I knew this because ..." in the UI. Plain
+            # string/int/float returns stay untouched.
+            if isinstance(result, dict) and recall_hits and not injected:
+                result.setdefault("memories", recall_hits)
+            return result
+
+        # Friendly metadata on the wrapper so ``help()`` is useful.
+        _wrapper.__wrapped_agent_memory__ = True  # type: ignore[attr-defined]
+        return _wrapper
+
+    return _decorator
+
+
+def remember(
+    store: MemoryStore,
+    text: str,
+    *,
+    kind: str = "fact",
+    importance: float = 0.7,
+    tags: list[str] | None = None,
+    agent_id: str | None = None,
+    user_id: str | None = None,
+) -> str:
+    """Insert ``text`` into the store as a single memory and return its id.
+
+    Sugar for callers that want to seed memory at import time without
+    having to instantiate ``StoredMemory`` / ``upsert_memory``:
+
+    >>> store = MemoryStore("loop.db")
+    >>> remember(store, "User prefers dark mode",
+    ...          tags=["ui", "preference"], agent_id="codex")
+    """
+    if not isinstance(store, MemoryStore):
+        raise TypeError(
+            f"remember() requires a MemoryStore, got {type(store).__name__}"
+        )
+    item = store.upsert_memory(
+        kind=kind, text=text, importance=importance,
+        tags=tags or ["remember"], agent_id=agent_id, user_id=user_id,
+        source="remember",
+    )
+    return item.id
+
+
+__all__ = ["agent_memory", "remember"]

{loop_memory-0.4.14 → loop_memory-0.4.15}/loop_memory/serve/routes/system.py

@@ -387,6 +387,15 @@ def register(app: FastAPI, store: MemoryStore, scheduler: Optional[Any] = None,
               bump: int = 1, source: str | None = None,
               mode: str = "hybrid", level: int = 1,
               as_of: str | None = None,
+              # Audit 2026-10-18: bi-temporal *validity-window* filter
+              # -- distinct from ``as_of`` (which routes through the
+              # supersession-chain ``recall_as_of()``). When set, the
+              # standard ``recall()`` / ``recall_hybrid()`` path drops
+              # memories whose ``valid_at > validity_at`` or
+              # ``invalid_at <= validity_at``. Complements ``as_of`` for
+              # callers that want "show me what's currently in its
+              # validity window" without walking the supersession chain.
+              validity_at: str | None = None,
               max_chars: int | None = None):
         """Unified recall — wiki + memories + entities in one ranked stream.
 
@@ -450,24 +459,38 @@ def register(app: FastAPI, store: MemoryStore, scheduler: Optional[Any] = None,
             except ValueError as e:
                 raise HTTPException(400, str(e))
         elif mode == "legacy" or not hasattr(store, "recall_hybrid"):
-            r = store.recall(
-                query,
-                limit=limit,
-                include=wanted,
-                bump_signals=bool(bump),
-                source=source,
-                max_chars=max_chars,
-                level=level,
-            )
+            try:
+                r = store.recall(
+                    query,
+                    limit=limit,
+                    include=wanted,
+                    bump_signals=bool(bump),
+                    source=source,
+                    max_chars=max_chars,
+                    level=level,
+                    # Audit 2026-10-18: only pass when caller
+                    # supplied something so the default-None legacy
+                    # contract holds.
+                    as_of_ts=(validity_at if (validity_at and str(validity_at).strip()) else None),
+                )
+            except ValueError as e:
+                # Invalid ``validity_at`` -> 400 (audit 2026-10-18)
+                # so the HTTP surface mirrors ``as_of``'s contract.
+                raise HTTPException(400, str(e))
             recall_mode = mode
         else:
-            r = store.recall_hybrid(
-                query, limit=limit, include=wanted,
-                bump_signals=bool(bump), source=source, level=level,
-                max_chars=max_chars,
-            )
+            try:
+                r = store.recall_hybrid(
+                    query, limit=limit, include=wanted,
+                    bump_signals=bool(bump), source=source, level=level,
+                    max_chars=max_chars,
+                    as_of_ts=(validity_at if (validity_at and str(validity_at).strip()) else None),
+                )
+            except ValueError as e:
+                raise HTTPException(400, str(e))
             recall_mode = mode
         return {
+            "validity_at": validity_at,
             "query": query,
             "tokens": r.get("tokens", []),
             "memories": r.get("memories", []),

{loop_memory-0.4.14 → loop_memory-0.4.15}/loop_memory/storage/retrieval.py

@@ -169,12 +169,25 @@ def _like_fallback(
     source_filter: str | None = None,
 ) -> list:
     """Brute-force LIKE fallback used when FTS5 trigram can't index
-    short CJK queries. Searches <substr> against the source table
-    directly. Returns rows in the same shape as bm25_search.
+    a query -- short strings, all-CJK with <3 chars, or the FTS5
+    ``MATCH`` returned 0 rows because quoted exact-phrase tokens
+    don't exist in the trigram index.
+
+    Audit 2026-10-18: now tokenises the query and OR-LIKEs every
+    token. The legacy whole-string LIKE is still tried first so
+    existing callers that depend on ``"%deploy process%"`` semantics
+    (e.g. ``recall_paths`` callers) get byte-identical results. When
+    the whole-string LIKE returns nothing we fall through to the
+    per-token OR pass which is strictly more lenient -- a multi-word
+    question like "What is the deploy process?" now matches the
+    stored fact "Deploy process uses blue/green" because "deploy"
+    appears, even though the exact substring "What is the deploy
+    process" does not.
     """
-    pat = f"%{(query or '').strip()}%"
-    if not query.strip():
+    q = (query or "").strip()
+    if not q:
         return []
+    pat = f"%{q}%"
     with store._conn() as c:
         if kind == "memories":
             sql = (
@@ -182,7 +195,22 @@ def _like_fallback(
                 "FROM memories m WHERE LOWER(text) LIKE LOWER(?) "
                 "ORDER BY m.importance DESC, m.created_at DESC LIMIT ?"
             )
-            return [dict(r) for r in c.execute(sql, (pat, limit)).fetchall()]
+            whole = [dict(r) for r in c.execute(sql, (pat, limit)).fetchall()]
+            if whole:
+                return whole
+            # Per-token OR pass -- at least one query word must hit.
+            import re as _re
+            tokens = [t for t in _re.findall(r"[A-Za-z0-9]+", q.lower()) if len(t) >= 2]
+            if not tokens:
+                return whole
+            placeholders = " OR ".join("LOWER(text) LIKE LOWER(?)" for _ in tokens)
+            params = [f"%{t}%" for t in tokens]
+            sql_t = (
+                "SELECT m.id AS id, m.importance AS importance "
+                f"FROM memories m WHERE {placeholders} "
+                "ORDER BY m.importance DESC, m.created_at DESC LIMIT ?"
+            )
+            return [dict(r) for r in c.execute(sql_t, (*params, limit)).fetchall()]
         sql = (
             "SELECT w.id AS id, w.importance AS importance, w.scope AS scope "
             "FROM wiki_pages w "
@@ -190,7 +218,24 @@ def _like_fallback(
             "ORDER BY w.importance DESC, w.updated_at DESC LIMIT ?"
         )
         rows = list(c.execute(sql, (pat, pat, limit * 3)).fetchall())
-        return _filter_wiki_scope(rows, source_filter)[:limit]
+        rows = _filter_wiki_scope(rows, source_filter)[:limit]
+        if rows:
+            return rows
+        import re as _re
+        tokens = [t for t in _re.findall(r"[A-Za-z0-9]+", q.lower()) if len(t) >= 2]
+        if not tokens:
+            return rows
+        title_parts = " OR ".join("LOWER(w.title) LIKE LOWER(?)" for _ in tokens)
+        body_parts = " OR ".join("LOWER(w.body) LIKE LOWER(?)" for _ in tokens)
+        params = [f"%{t}%" for t in tokens] * 2
+        sql_t = (
+            "SELECT w.id AS id, w.importance AS importance, w.scope AS scope "
+            "FROM wiki_pages w "
+            f"WHERE ({title_parts}) OR ({body_parts}) "
+            "ORDER BY w.importance DESC, w.updated_at DESC LIMIT ?"
+        )
+        rows_t = [dict(r) for r in c.execute(sql_t, (*params, limit * 3)).fetchall()]
+        return _filter_wiki_scope(rows_t, source_filter)[:limit]
 
 
 def _filter_wiki_scope(rows: Iterable, source: str | None) -> list:
@@ -238,6 +283,50 @@ def fuse_rrf(
     return [{"id": i, "_rrf": s} for i, s in sorted(fused.items(), key=lambda kv: -kv[1])]
 
 
+def fuse_rrf_with_channels(
+    ranked_lists_with_labels: list[tuple[str, list[dict]]],
+    k: int = DEFAULT_RRF_K,
+) -> list[dict]:
+    """Reciprocal Rank Fusion that also returns a per-channel score
+    breakdown (audit 2026-10-18).
+
+    ``ranked_lists_with_labels`` is a list of ``(channel, list)``
+    pairs -- e.g. ``[("bm25", bm25_mem), ("semantic", sem_mem),
+    ("entity", ent_mem)]``. Each ``list`` is a ranked list of
+    ``{"id": ..., "_score": ...}`` already sorted by descending
+    score.
+
+    The returned list carries one dict per distinct document::
+
+        {"id": id, "_rrf": float, "_channel_scores": {channel: float}}
+
+    ``_channel_scores`` is the raw score each channel assigned to the
+    document (None when the channel did not surface it). It powers the
+    evidence chain that the rest of loop-memory attaches to each
+    recall hit -- so a UI can render "this hit because BM25 (1.0)
+    + entity (0.7)" instead of a black-box RRF total.
+
+    RRF semantics are identical to ``fuse_rrf``: this is the same
+    algorithm with extra metadata. The 0-dep property is preserved
+    (pure Python).
+    """
+    fused: dict[str, float] = {}
+    raw_scores: dict[str, dict[str, float]] = {}
+    for channel, lst in ranked_lists_with_labels:
+        for rank, item in enumerate(lst, start=1):
+            doc_id = item["id"]
+            fused[doc_id] = fused.get(doc_id, 0.0) + 1.0 / (k + rank)
+            raw_scores.setdefault(doc_id, {})[channel] = float(item.get("_score") or 0.0)
+    out = []
+    for doc_id, total in sorted(fused.items(), key=lambda kv: -kv[1]):
+        out.append({
+            "id": doc_id,
+            "_rrf": total,
+            "_channel_scores": raw_scores.get(doc_id, {}),
+        })
+    return out
+
+
 # ----------------------------------------------------------------------
 # Temporal reasoning layer
 # ----------------------------------------------------------------------