Merge pull request #23 from nickroci/feat/usefulness-tiebreaker

feat(daemon): usefulness tiebreaker in priming rank

Author: nickroci

README.md

@@ -318,6 +318,25 @@ def _last_activity_date(fm: Dict[str, Any]) -> Optional[date]:
     return max(valid)
 
 
+# TODO(decay): couple decay to USEFUL surfacing, not bare surfacing.
+# `_last_activity_date` counts any `last_surfaced` as activity, and
+# `record_surface` stamps it on EVERY surface — so an entry surfaced often but
+# never relied on (high `fired`, low `fired-helpful` — the "ignored" /
+# prefrontal-inhibition case) resists decay exactly as much as a genuinely
+# useful one. That's backwards: those are the entries we most want to fade.
+# Two directions to explore:
+#   1. Reset/extend the half-life on a HELPFUL surface (`fired-helpful` bump)
+#      rather than on every surface — reset on real *use*, not mere exposure.
+#      Closes the hole above and implements the design's "surfaced but not
+#      relevant -> decay" leg.
+#   2. Tier the half-life off our real counters instead of one DECAY_AGE_DAYS
+#      + a binary reinforced-floor cliff: more-proven entries (reinforced /
+#      fired-helpful) earn a smoothly longer life, rather than the current
+#      immune/not cliff.
+# When a merge path lands, SUM the reinforced/fired/fired-helpful counters
+# across sources rather than taking the max — max() silently destroys
+# accumulated evidence. See knowledge/projects/agent-mem/concepts/
+# forgetting-ltd-decay-design.
 def _is_eligible_for_archive(
     fm: Dict[str, Any],
     *,

daemon/agent_mem_daemon/decay.py

@@ -129,8 +129,11 @@ def _shorten(text: str, *, max_chars: int = 80) -> str:
     return text[: max_chars - 1].rstrip() + "…"
 
 
-def _reinforced_count(fm: Dict[str, Any]) -> int:
-    raw = fm.get("reinforced")
+def _nonneg_int_field(fm: Dict[str, Any], key: str) -> int:
+    """A frontmatter integer counter as a non-negative int (0 when absent
+    or unparseable). Shared by the reinforced / fired / fired-helpful
+    readers so the coercion lives in one place."""
+    raw = fm.get(key)
     if raw is None:
         return 0
     try:
@@ -140,6 +143,57 @@ def _reinforced_count(fm: Dict[str, Any]) -> int:
     return n if n > 0 else 0
 
 
+def _reinforced_count(fm: Dict[str, Any]) -> int:
+    return _nonneg_int_field(fm, "reinforced")
+
+
+# ── Usefulness tiebreaker (fired-helpful / fired) ─────────────────────
+#
+# ``fired`` counts how often an entry was surfaced in priming; ``fired-
+# helpful`` counts how often a surfaced entry was actually relied on (the
+# Librarian's used_helpfully signal). Their ratio is a quality prior: "when
+# this entry shows up, how often does it earn its place?" We fold it into
+# ranking as a SMALL additive nudge — a tiebreaker among candidates the
+# cross-encoder reranker already considers comparable, never a primary
+# ranking term. Keeping it gentle is deliberate: the design's own warning
+# is that ranking by usefulness creates a self-reinforcing surfacing loop
+# (surface -> accrue helpful -> rank higher -> surface more), so usefulness
+# must not be able to override a real applicability difference.
+# See knowledge/projects/agent-mem/concepts/forgetting-ltd-decay-design.
+#
+# The estimate is Beta-smoothed and centered on the prior mean: a raw ratio
+# is unusable at low counts (1/1 = "100% useful" beats 5/20), and centering
+# makes a zero-data entry contribute EXACTLY 0 — new entries are judged on
+# the reranker alone (clean cold-start), proven entries float up a hair,
+# chronically-surfaced-but-ignored entries sink a hair.
+_USEFULNESS_PRIOR_ALPHA = 1.0  # prior "helpful" pseudo-count
+_USEFULNESS_PRIOR_BETA = 4.0  # prior "ignored" pseudo-count -> prior mean 0.2
+# Provisional and uncalibrated: fired-helpful is ~0 across the library until
+# the capture (shipped 2026-06) accrues weeks of data, so this weight cannot
+# be tuned against the real distribution yet. Set small so the centered score
+# (range ~[-0.2, +0.8]) swings the boosted score by at most ~+0.08 / -0.02
+# logits — bigger than the scope bonus (0.02), far smaller than one
+# reinforcement (0.5) or a meaningful rerank gap.
+_USEFULNESS_TIEBREAK_WEIGHT = 0.1
+
+
+def _usefulness_score(fm: Dict[str, Any]) -> float:
+    """Beta-smoothed, prior-centered usefulness in roughly [-0.2, +0.8].
+
+    Returns 0.0 when the entry has never been surfaced (``fired`` absent or
+    0) so untracked entries are neutral. Above the prior mean -> positive
+    (rank nudge up); below -> negative (nudge down)."""
+    fired = _nonneg_int_field(fm, "fired")
+    if fired <= 0:
+        return 0.0
+    helpful = _nonneg_int_field(fm, "fired-helpful")
+    a = _USEFULNESS_PRIOR_ALPHA
+    b = _USEFULNESS_PRIOR_BETA
+    smoothed = (helpful + a) / (fired + a + b)
+    prior_mean = a / (a + b)
+    return smoothed - prior_mean
+
+
 def _entry_title(fm: Dict[str, Any], path: Path) -> str:
     """Punchy human-readable title for the entry. Falls back to the
     slug (de-kebabed) if no ``title:`` frontmatter is present."""
@@ -580,7 +634,12 @@ def _boost_with_reinforcement(
     knowledge_dir: Optional[Path] = None,
     current_project_slug: Optional[str] = None,
 ) -> List[Tuple[Path, float, int]]:
-    """Re-rank by ``score + reinforced * 0.5 + scope_bonus``.
+    """Re-rank by ``score + reinforced*0.5 + scope_bonus + usefulness_tiebreak``.
+
+    The usefulness term is a small, prior-centered nudge from the
+    fired-helpful/fired ratio (see ``_usefulness_score``) — a tiebreaker
+    among comparable candidates, never a primary ranking signal. Untracked
+    entries contribute exactly 0.
 
     The reinforcement multiplier is gentle on purpose: reinforced is an
     integer counter the user has driven up by repetition, and BM25 scores
@@ -622,7 +681,38 @@ def _boost_with_reinforcement(
                 current_project_slug,
                 aliases,
             )
-        boosted = score + reinforced * 0.5 + scope
+        usefulness = _usefulness_score(fm)
+        # TODO(usefulness): this is a deliberately gentle TIEBREAKER. Grow it
+        # into a real signal once fired-helpful has weeks of data to calibrate
+        # against (it is ~0 library-wide until the 2026-06 capture accrues).
+        # Ideas, roughly in order of value:
+        #   1. Evidence-gate the weight: scale by fired/(fired+K) so low-count
+        #      entries barely move. Smoothing fixes the point estimate; gating
+        #      fixes the weight magnitude — distinct jobs, do both.
+        #   2. Asymmetric "ignored" penalty (the prefrontal-inhibition analog):
+        #      high fired + low fired-helpful is strong evidence an entry is
+        #      noise in the contexts where it keeps surfacing. Don't inflate the
+        #      RANKING penalty (that feeds the self-reinforcing surfacing loop) —
+        #      route the negative leg into DECAY (decay.py sweep) so ignored
+        #      entries lose half-life. That's where the design says it belongs
+        #      and where the loop self-damps. We already have the sweep; it just
+        #      doesn't read fired-helpful yet.
+        #   3. RIF / near-duplicate negative ticks: when the top entry fires-
+        #      and-helps, give near-competitors that also fired a small negative
+        #      tick so monotonic-up counters don't entrench duplicates.
+        #   4. Put all four boost terms on a COMMON SCALE. Rerank logits are
+        #      ~[-3, +10], scope is ±0.02, reinforced is 0.5/unit, usefulness is
+        #      ~[-0.02, +0.08]: incommensurable today (see the NOTE on _SCOPE_*).
+        #      Normalise (e.g. squash the rerank logit to a bounded range) so
+        #      each weight means something comparable, then re-tune all three.
+        #   5. Telemetry: surface usefulness alongside the boosted score in the
+        #      run record so the weight can be calibrated from real data instead
+        #      of guessed.
+        # Design rationale: knowledge/projects/agent-mem/concepts/forgetting-
+        #   ltd-decay-design (decay-with-reinforcement, encoding-strength-as-
+        #   rank-modifier, RIF, archive-not-delete). The usefulness-into-decay
+        #   direction (idea 2) is tracked as a TODO in decay.py's sweep.
+        boosted = score + reinforced * 0.5 + scope + _USEFULNESS_TIEBREAK_WEIGHT * usefulness
         enriched.append((path, boosted, reinforced, score))
     enriched.sort(key=lambda t: (-t[1], str(t[0])))
     return [(p, ranked, reinforced) for p, ranked, reinforced, _orig in enriched]

daemon/agent_mem_daemon/priming.py

@@ -381,19 +381,38 @@ def _handle_fetch_entry(req: RpcRequest) -> RpcResponse:
     if raw.startswith("[[") and raw.endswith("]]"):
         raw = raw[2:-2].strip()
     raw = raw.strip("/")
-    target_rel = raw if raw.endswith(".md") else raw + ".md"
+    if not raw:
+        return {"ok": False, "error": "path must name an entry or folder"}
 
     kdir = knowledge_dir()
     if not kdir.exists():
         return {"ok": False, "error": "knowledge dir not found"}
     kroot = kdir.resolve()
-    target = (kroot / target_rel).resolve()
-    try:
-        target.relative_to(kroot)
-    except ValueError:
-        return {"ok": False, "error": "path escapes knowledge dir"}
-    if not target.is_file():
-        return {"ok": False, "error": f"entry not found: {target_rel}"}
+
+    # Resolve to a concrete .md file. A bare folder path (with or without a
+    # trailing slash) resolves to that folder's README.md — so `projects/foo`
+    # and `projects/foo/` browse the folder instead of 404-ing on the
+    # non-existent `projects/foo.md`. An explicit `.md` suffix is always an
+    # entry; otherwise try the entry first, then fall back to the folder README.
+    rels = [raw] if raw.endswith(".md") else [f"{raw}.md", f"{raw}/README.md"]
+    target: Optional[Path] = None
+    for rel in rels:
+        cand = (kroot / rel).resolve()
+        try:
+            cand.relative_to(kroot)
+        except ValueError:
+            return {"ok": False, "error": "path escapes knowledge dir"}
+        if cand.is_file():
+            target = cand
+            break
+    if target is None:
+        return {
+            "ok": False,
+            "error": (
+                f"entry not found: {raw} (tried {', '.join(rels)}). "
+                "If you meant a topic rather than a path, re-run as a free-text query."
+            ),
+        }
 
     content = target.read_text(encoding="utf-8")
     parent = target.parent

daemon/agent_mem_daemon/priming_rpc.py

@@ -35,6 +35,8 @@ def render_entry(
     applies_when: str,
     keywords: List[str],
     reinforced: Optional[int] = None,
+    fired: int = 0,
+    fired_helpful: int = 0,
     body: str = "",
     scope: str = "global",
     default_body_template: str = DEFAULT_BODY_TEMPLATE,
@@ -60,8 +62,8 @@ def render_entry(
     lines.append(f'title: "{title}"')
     lines.append("created: 2026-05-19")
     lines.append("updated: 2026-05-19")
-    lines.append("fired: 0")
-    lines.append("fired-helpful: 0")
+    lines.append(f"fired: {fired}")
+    lines.append(f"fired-helpful: {fired_helpful}")
     if reinforced is not None:
         lines.append(f"reinforced: {reinforced}")
     lines.append("sources:")

daemon/tests/conftest.py

@@ -225,6 +225,64 @@ def test_refresh_reinforced_counter_boosts_rank(tmp_path):
     assert "(×" not in lines[1]
 
 
+def _write_useful_pair(k: Path) -> None:
+    """Two entries identical except for their fired / fired-helpful counts:
+    ``proven`` was relied on 8/10 surfaces, ``ignored`` 0/10."""
+    (k / "global").mkdir(parents=True, exist_ok=True)
+    _write(
+        k / "global" / "proven.md",
+        _entry(
+            id_="proven",
+            title="Proven entry",
+            applies_when="working with foo",
+            keywords=["foo"],
+            fired=10,
+            fired_helpful=8,
+        ),
+    )
+    _write(
+        k / "global" / "ignored.md",
+        _entry(
+            id_="ignored",
+            title="Ignored entry",
+            applies_when="working with foo",
+            keywords=["foo"],
+            fired=10,
+            fired_helpful=0,
+        ),
+    )
+
+
+def test_usefulness_breaks_tie_between_equal_rerank_candidates(tmp_path):
+    """When two candidates score identically, the one actually relied on
+    (higher fired-helpful/fired) wins the tiebreak."""
+    k = tmp_path / "knowledge"
+    _write_useful_pair(k)
+    # Identical rerank scores — only the usefulness tiebreaker can order them.
+    hits = [
+        (k / "global" / "ignored.md", 3.0),
+        (k / "global" / "proven.md", 3.0),
+    ]
+    ranked = priming._boost_with_reinforcement(hits)
+    order = [p.stem for p, _score, _r in ranked]
+    assert order == ["proven", "ignored"]
+
+
+def test_usefulness_does_not_override_a_clear_rerank_gap(tmp_path):
+    """The tiebreaker is gentle: a clearly stronger rerank score wins even
+    when that entry is chronically ignored and the weaker one is maximally
+    useful. Usefulness can only break near-ties, not flip real relevance."""
+    k = tmp_path / "knowledge"
+    _write_useful_pair(k)
+    # proven (useful) gets the weak rerank score; ignored gets a strong one.
+    hits = [
+        (k / "global" / "proven.md", 2.0),
+        (k / "global" / "ignored.md", 5.0),
+    ]
+    ranked = priming._boost_with_reinforcement(hits)
+    assert ranked[0][0].stem == "ignored"
+
+
 def test_refresh_idempotent(tmp_path):
     k = _seed_library(tmp_path)
     out = tmp_path / "hot-context.md"

daemon/tests/test_priming.py

@@ -101,6 +101,31 @@ def test_reinforced_count_passes_through_positive() -> None:
     assert priming._reinforced_count({"reinforced": 4}) == 4
 
 
+# ── _usefulness_score (fired-helpful / fired tiebreaker) ──────────────
+
+
+def test_usefulness_score_zero_when_never_fired() -> None:
+    # No track record -> exactly neutral, so cold-start entries rank on the
+    # reranker alone.
+    assert priming._usefulness_score({}) == 0.0
+    assert priming._usefulness_score({"fired": 0, "fired-helpful": 0}) == 0.0
+
+
+def test_usefulness_score_positive_when_mostly_helpful() -> None:
+    # 8/10 helpful sits well above the 0.2 prior mean.
+    assert priming._usefulness_score({"fired": 10, "fired-helpful": 8}) > 0.0
+
+
+def test_usefulness_score_negative_when_surfaced_but_ignored() -> None:
+    # 0/20 helpful -> below the prior mean -> a gentle demotion.
+    assert priming._usefulness_score({"fired": 20, "fired-helpful": 0}) < 0.0
+
+
+def test_usefulness_score_handles_garbage() -> None:
+    assert priming._usefulness_score({"fired": "x", "fired-helpful": "y"}) == 0.0
+    assert priming._usefulness_score({"fired": 5, "fired-helpful": None}) < 0.0
+
+
 # ── _entry_title fallback ────────────────────────────────────────────
 
 

daemon/tests/test_priming_internals.py

@@ -498,6 +498,28 @@ def test_fetch_entry_rejects_missing_entry(tmp_path, rpc_server):
     assert "not found" in resp["error"]
 
 
+def test_fetch_entry_resolves_folder_to_readme(tmp_path, rpc_server):
+    """A bare folder path (no trailing slash) resolves to that folder's
+    README — so `global/python` browses the folder instead of 404-ing on
+    the non-existent `global/python.md`."""
+    _seed_library(tmp_path)
+    _thread, socket_path = rpc_server
+    resp = _send_request(socket_path, {"op": "fetch_entry", "path": "global/python"})
+    assert resp["ok"] is True
+    assert resp["path"].endswith("global/python/README.md")
+    assert "# python" in resp["content"]
+    # Siblings are the folder's entries (the README itself is excluded).
+    assert any("use-uv" in s for s in resp["siblings"])
+
+
+def test_fetch_entry_folder_trailing_slash_also_resolves_readme(tmp_path, rpc_server):
+    _seed_library(tmp_path)
+    _thread, socket_path = rpc_server
+    resp = _send_request(socket_path, {"op": "fetch_entry", "path": "global/python/"})
+    assert resp["ok"] is True
+    assert resp["path"].endswith("global/python/README.md")
+
+
 def test_fetch_entry_rejects_empty_path(rpc_server):
     _thread, socket_path = rpc_server
     resp = _send_request(socket_path, {"op": "fetch_entry", "path": "  "})