Merge pull request #52 from nickroci/feat/retrieval-cue-learning

feat(curator): retrieval-cue learning + decay-time-bomb test fix + CI security audit

Author: nickroci

.github/workflows/ci.yml

@@ -77,6 +77,35 @@ jobs:
       - name: Check version coherence
         run: bash scripts/check-version-coherence.sh
 
+  security-audit:
+    # Scan third-party dependencies for known vulnerabilities (PyPI Advisory
+    # DB / OSV) via pip-audit. `uv sync --all-packages` installs every
+    # workspace member's deps into one env; pip-audit audits that env directly
+    # (environment mode — no resolver venv, which is robust across runners).
+    # Local workspace packages (ultan, agent-mem-daemon, …) aren't on PyPI and
+    # are skipped automatically.
+    #
+    # Required, blocking gate (wired into `ci-success` below): a new advisory
+    # in any dependency fails this and blocks merges until the dep is bumped
+    # or the advisory is explicitly ignored here. Keep the ignore list curated
+    # — each entry must carry a reason and a revisit trigger.
+    #
+    # Ignored advisories:
+    #   - CVE-2025-3000 (torch 2.12.0): no patched torch release exists yet.
+    #     Drop this ignore once upstream ships a fixed version.
+    name: security-audit
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+          cache-dependency-glob: uv.lock
+      - name: Install the full workspace
+        run: uv sync --locked --all-packages
+      - name: Audit dependencies (pip-audit)
+        run: uv run --with pip-audit pip-audit --ignore-vuln CVE-2025-3000
+
   ci-success:
     # Single required check for branch protection. It goes green only when
     # every job above has succeeded, so protection on `main` can require
@@ -86,11 +115,12 @@ jobs:
     # skipped past a failing matrix.
     name: ci-success
     if: always()
-    needs: [build, version-coherence]
+    needs: [build, version-coherence, security-audit]
     runs-on: ubuntu-latest
     steps:
       - name: Require all CI jobs to have passed
         run: |
-          echo "build=${{ needs.build.result }} version-coherence=${{ needs.version-coherence.result }}"
+          echo "build=${{ needs.build.result }} version-coherence=${{ needs.version-coherence.result }} security-audit=${{ needs.security-audit.result }}"
           test "${{ needs.build.result }}" = "success"
           test "${{ needs.version-coherence.result }}" = "success"
+          test "${{ needs.security-audit.result }}" = "success"

daemon/agent_mem_daemon/ingest.py

@@ -71,6 +71,7 @@ class _OffsetState(TypedDict, total=False):
     "SessionEnd",
     "UserPromptSubmit",
     "SessionStart",
+    "Surfaced",
 }
 
 

daemon/agent_mem_daemon/librarian_prompt.py

@@ -756,6 +756,30 @@ def _slugify(s: str) -> str:
 ``used_helpfully`` (that only counts the hit; ``drift`` actually edits the \
 entry) — you may emit both for the same entry in one scan.
 
+  **RECALL-GAP — sharpen an entry's retrieval triggers** (mutate in place, \
+sparingly)
+    Each turn may carry a ``[recall]`` line — ``instant-recall surfaced: \
+[[…]], [[…]]`` — listing what the fast trigger tier actually showed the \
+assistant for that turn. When the turn's query clearly needed a library \
+entry that is NOT in that ``[recall]`` line, the entry exists but its \
+triggers missed the query's vocabulary. Confirm with ``bm25_search`` / \
+``embedding_search`` that such an entry exists and genuinely answers the \
+query — never infer a gap from the recall line alone.
+    Action: propose ``update_entry`` with ``salience_signal: "drift"``, \
+adding the query's distinctive term(s) to that entry's ``paraphrases`` \
+(preferred — query-shaped phrasings BM25 indexes) and/or ``keywords``. The \
+load-bearing claim and body stay INTACT; you are only widening how the \
+entry is FOUND, not what it says. E.g. a "you can't reliably profit from \
+crypto" entry that missed a "how do I make money from BTC" query gains the \
+paraphrase "make money from BTC / bitcoin".
+    PRECISION GATE (critical): add a trigger ONLY when the entry is \
+genuinely THE right recall for that class of query, not merely adjacent. A \
+loose addition makes the entry fire as NOISE on unrelated future queries — \
+polluting the instant tier for every session, which is worse than an \
+occasional miss. When in doubt, DON'T; never pad with near-synonyms the \
+entry already matches. The embedding tier already catches paraphrases, so \
+reserve this for genuine lexical/cue gaps the fast path keeps missing.
+
   **REDUNDANT / no signal** (skip silently — no proposal)
     Things every competent assistant would already produce or that don't carry information:
       - Code-as-code: "added a for loop", "created a class", "fixed indentation"

daemon/tests/conftest.py

@@ -17,6 +17,7 @@
 
 from __future__ import annotations
 
+from datetime import date
 from pathlib import Path
 from typing import List, Optional
 
@@ -39,14 +40,25 @@ def render_entry(
     fired_helpful: int = 0,
     body: str = "",
     scope: str = "global",
+    created: Optional[str] = None,
+    updated: Optional[str] = None,
     default_body_template: str = DEFAULT_BODY_TEMPLATE,
 ) -> str:
     """Render a valid library entry as a YAML-frontmattered markdown
     string. Matches the schema enforced by
     ``scholar_prompt._REQUIRED_FRONTMATTER_FIELDS``.
 
     When ``body`` is the empty string the body is synthesised from
-    ``default_body_template`` (which sees ``id_`` and ``applies_when``)."""
+    ``default_body_template`` (which sees ``id_`` and ``applies_when``).
+
+    ``created``/``updated`` default to TODAY (ISO) rather than a fixed date:
+    a hardcoded date silently ages past the decay window (``DECAY_AGE_DAYS``),
+    after which the Scholar review's opportunistic decay sweep archives the
+    fixture entry mid-test — a calendar time-bomb. Pass an explicit date only
+    when a test deliberately needs a stale (or specific-dated) entry."""
+    _today = date.today().isoformat()
+    created = created or _today
+    updated = updated or created
     lines = [
         "---",
         f"id: {id_}",
@@ -60,8 +72,8 @@ def render_entry(
         lines.append(f"  {line}")
     lines.append("keywords: [" + ", ".join(keywords) + "]")
     lines.append(f'title: "{title}"')
-    lines.append("created: 2026-05-19")
-    lines.append("updated: 2026-05-19")
+    lines.append(f"created: {created}")
+    lines.append(f"updated: {updated}")
     lines.append(f"fired: {fired}")
     lines.append(f"fired-helpful: {fired_helpful}")
     if reinforced is not None:

daemon/tests/test_librarian_prompt.py

@@ -79,6 +79,34 @@ def test_flatten_buffer_user_asserted_flag_propagates():
     assert flat[0][4] is True
 
 
+def test_flatten_buffer_renders_recall_surfaced_event():
+    # The hook emits a `Surfaced` event (role="recall") recording what the
+    # instant triggers showed; the Librarian must see it inline with the turn
+    # so it can spot recall gaps. It renders like any text-bearing turn line.
+    snap = _snap(
+        [
+            [
+                _ev("UserPromptSubmit", {"text": "how do I make money from BTC"}),
+                _ev(
+                    "Surfaced",
+                    {"role": "recall", "content": "instant-recall surfaced: [[a/b]], [[c/d]]"},
+                ),
+            ]
+        ]
+    )
+    flat = lp.flatten_buffer(snap)
+    roles = [r for _id, _seq, r, _t, _u in flat]
+    assert "recall" in roles
+    recall_text = next(t for _id, _seq, r, t, _u in flat if r == "recall")
+    assert "[[a/b]]" in recall_text and "[[c/d]]" in recall_text
+
+
+def test_system_prompt_includes_recall_gap_signal():
+    s = lp.librarian_system_prompt()
+    assert "RECALL-GAP" in s
+    assert "PRECISION GATE" in s  # the keyword-pollution safeguard must survive
+
+
 def test_flatten_buffer_empty_when_no_turns():
     assert lp.flatten_buffer({"turns": []}) == []
     assert lp.flatten_buffer({}) == []

daemon/tests/test_priming.py

@@ -450,6 +450,11 @@ def test_bullet_format_includes_title_hook_and_count(tmp_path):
             applies_when="writing a Dockerfile or docker-compose service",
             keywords=["docker", "image", "version", "pin"],
             reinforced=4,
+            # Fixed old date: this test pins the title/(×N)/hook wire-shape, not
+            # the freshness ★ marker (entries updated within 7 days get a star).
+            # render_entry now defaults to today, which would add the star here.
+            created="2026-01-01",
+            updated="2026-01-01",
         ),
     )
     plain_path = k / "global" / "use-ripgrep.md"
@@ -460,6 +465,8 @@ def test_bullet_format_includes_title_hook_and_count(tmp_path):
             title="Prefer ripgrep over grep",
             applies_when="searching through a code repository",
             keywords=["ripgrep", "grep", "search"],
+            created="2026-01-01",
+            updated="2026-01-01",
         ),
     )
 

daemon/tests/test_scholar.py

@@ -21,6 +21,7 @@
 
 import json
 import logging
+from datetime import date
 from pathlib import Path
 from typing import Any, Dict, List, Optional
 
@@ -34,6 +35,12 @@
 
 from .conftest import scholar_entry_body
 
+# Inline seed entries must be dated TODAY, not a fixed calendar date: a
+# hardcoded date ages past DECAY_AGE_DAYS, after which the Scholar review's
+# opportunistic decay sweep archives the seed entry mid-test (a time-bomb that
+# broke these tests on 2026-06-19, 31 days after the old 2026-05-19 literal).
+_TODAY = date.today().isoformat()
+
 
 @pytest.fixture(autouse=True)
 def _isolated_home(tmp_path: Path, monkeypatch: pytest.MonkeyPatch):
@@ -354,7 +361,7 @@ def test_review_repairs_phantom_index_row(monkeypatch, tmp_path):
     (k / "global" / "python" / "use-uv.md").write_text(
         "---\nid: use-uv\ntype: lesson\nscope: global\nstatus: provisional\n"
         "confidence: 0.7\napplies-when: |\n  x\nkeywords: [a, b, c]\n"
-        'title: "use-uv"\ncreated: 2026-05-19\nupdated: 2026-05-19\n'
+        f'title: "use-uv"\ncreated: {_TODAY}\nupdated: {_TODAY}\n'
         "fired: 0\nfired-helpful: 0\nsources:\n  - manual\n---\n\n# uv\n\nUse uv always for python.\n",
         encoding="utf-8",
     )
@@ -729,7 +736,7 @@ def test_end_to_end_proposal_approved_writes_entry_to_knowledge_dir(
         "applies-when: |\n  testing a service with a factory\n"
         "keywords: [test, stub, factory]\n"
         'title: "Stub the factory"\n'
-        "created: 2026-05-19\nupdated: 2026-05-19\n"
+        f"created: {_TODAY}\nupdated: {_TODAY}\n"
         "fired: 0\nfired-helpful: 0\nsources:\n  - manual\n"
         "---\n\n# Stub the factory\n\nBody sentence long enough to pass.\n"
     )
@@ -795,7 +802,7 @@ def _seed_library_with_broken_link(k: Path, *, broken: str = "global/ghost/never
     entry.write_text(
         "---\nid: narr\ntype: lesson\nscope: global\nstatus: provisional\n"
         "confidence: 0.7\napplies-when: |\n  x\nkeywords: [a, b, c]\n"
-        'title: "narr"\ncreated: 2026-05-19\nupdated: 2026-05-19\n'
+        f'title: "narr"\ncreated: {_TODAY}\nupdated: {_TODAY}\n'
         "fired: 0\nfired-helpful: 0\nsources:\n  - manual\n---\n\n"
         f"# narr\n\nThis references [[{broken}]] in a sentence we keep.\n",
         encoding="utf-8",
@@ -950,7 +957,7 @@ def _entry_frontmatter(id_: str) -> str:
     return (
         f"---\nid: {id_}\ntype: lesson\nscope: global\nstatus: provisional\n"
         "confidence: 0.7\napplies-when: |\n  x\nkeywords: [a, b, c]\n"
-        f'title: "{id_}"\ncreated: 2026-05-19\nupdated: 2026-05-19\n'
+        f'title: "{id_}"\ncreated: {_TODAY}\nupdated: {_TODAY}\n'
         "fired: 0\nfired-helpful: 0\nsources:\n  - manual\n---\n\n"
         f"# {id_}\n\nA real body sentence that is clearly long enough.\n"
     )

tests/test_capture.py

@@ -92,6 +92,55 @@ def test_post_tool_use_marks_failure(_isolated_store: Path) -> None:
     assert ev["payload"]["summary"].endswith("FAILED")
 
 
+# ── user-prompt-submit → Surfaced (what the instant triggers showed) ─────────
+
+
+def test_extract_surfaced_links_dedups_and_handles_empty() -> None:
+    from ultan import _priming
+
+    md = "## Ultan says\n- [[projects/x/foo]] ★ — a\n- [[global/y/bar]] — b\n- [[projects/x/foo]] dup\n"
+    assert _priming.extract_surfaced_links(md) == ["projects/x/foo", "global/y/bar"]
+    assert _priming.extract_surfaced_links("") == []
+    assert _priming.extract_surfaced_links("no links here") == []
+
+
+def _stub_priming(monkeypatch: pytest.MonkeyPatch, md: str) -> None:
+    # Don't spawn a daemon or hit the socket; pin the priming output.
+    monkeypatch.setattr(_hooks._daemon, "ensure_running", lambda: None)
+    monkeypatch.setattr(_hooks._daemon, "status", lambda: "ready")
+    monkeypatch.setattr(_hooks._priming, "get_priming", lambda *a, **k: md)
+
+
+def test_user_prompt_submit_emits_surfaced_event(
+    _isolated_store: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    _stub_priming(
+        monkeypatch,
+        "## Ultan says\n- [[projects/x/crypto-no-profit]] — you can't profit from crypto\n",
+    )
+    rc = _hooks.dispatch(
+        "user-prompt-submit",
+        {"session_id": "s1", "cwd": "/w", "prompt": "how do I make money from BTC"},
+    )
+    assert rc == 0
+    by_type = {e["type"]: e for e in _read_events(_isolated_store)}
+    assert "UserPromptSubmit" in by_type  # the prompt itself still captured
+    assert "Surfaced" in by_type  # and what the instant triggers surfaced
+    surfaced = by_type["Surfaced"]
+    _assert_valid_event(surfaced, expected_type="Surfaced")
+    assert surfaced["payload"]["role"] == "recall"
+    assert "[[projects/x/crypto-no-profit]]" in surfaced["payload"]["content"]
+
+
+def test_user_prompt_submit_no_surfaced_event_when_nothing_primed(
+    _isolated_store: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    _stub_priming(monkeypatch, "")  # daemon found nothing → no Surfaced line
+    _hooks.dispatch("user-prompt-submit", {"session_id": "s1", "prompt": "hi"})
+    types = {e["type"] for e in _read_events(_isolated_store)}
+    assert "Surfaced" not in types
+
+
 # ── stop / session-end → turn-sealing events (the Librarian triggers) ────────
 
 

ultan/_hooks.py

@@ -112,6 +112,24 @@ def _user_prompt_submit(payload: dict[str, Any]) -> int:
             "minute or two.*\n"
         )
 
+    # Record WHAT priming surfaced this turn so the daemon's Librarian can spot
+    # recall gaps — an entry relevant to the turn that did NOT surface — and
+    # sharpen its retrieval triggers (retrieval-cue learning). File write only,
+    # independent of the stdout priming below; a cheap regex over the rendered
+    # markdown, so it stays within the per-turn hook budget.
+    if sid:
+        surfaced = _priming.extract_surfaced_links(md)
+        if surfaced:
+            _events.append_event(
+                "Surfaced",
+                payload,
+                payload={
+                    "role": "recall",
+                    "content": "instant-recall surfaced: "
+                    + ", ".join(f"[[{t}]]" for t in surfaced),
+                },
+            )
+
     # G3: consume + render any pending nudges for this turn (budget-gated,
     # cross-project filtered). Needs a session_id to key the per-session budget;
     # take_and_render no-ops to "" without one.

ultan/_priming.py

@@ -218,6 +218,38 @@ def _tokenize(text: str) -> List[str]:
     return [t for t in _TOKEN_SPLIT_RE.split(text.lower()) if len(t) >= 2]
 
 
+_WIKILINK_RE = re.compile(r"\[\[([^\]\n|]+)(?:\|[^\]\n]*)?\]\]")
+
+
+def extract_surfaced_links(md: str) -> List[str]:
+    """Pull the entry wikilink targets out of a rendered priming block.
+
+    The priming markdown lists each surfaced entry as ``- [[<target>]] …``;
+    this returns those ``<target>`` paths (deduped, order preserved) so the
+    hook can record WHAT the instant triggers surfaced this turn. The daemon's
+    Librarian uses that to spot recall gaps — an entry that was relevant to the
+    turn but did NOT surface — and sharpen its retrieval triggers. Pure stdlib;
+    safe on the per-turn hook hot path. Returns ``[]`` for empty input.
+
+    Grounding (retrieval-cue learning): retrieval reopens a trace for re-storage
+    with altered associations (Bridge & Paller 2012, J Neurosci,
+    doi:10.1523/JNEUROSCI.1378-12.2012); fast recall misses when the query's
+    terms were not encoded as cues (encoding specificity — Tulving & Thomson
+    1973, Psychol Rev, doi:10.1037/h0020071); the deliberative tier links the
+    missed memory to the new cue (memory integration — Schlichting & Preston
+    2015, Curr Opin Behav Sci, doi:10.1016/j.cobeha.2014.07.005)."""
+    if not md:
+        return []
+    seen: set[str] = set()
+    out: List[str] = []
+    for target in _WIKILINK_RE.findall(md):
+        t = target.strip()
+        if t and t not in seen:
+            seen.add(t)
+            out.append(t)
+    return out
+
+
 def _parse_yaml_lite(fm_block: str) -> Frontmatter:
     """Just enough YAML to pull ``reinforced``, ``title``, ``applies-when``,
     ``keywords``. Pure stdlib — no PyYAML dep.