feat(salience): per-session entity-salience retrieval reflex

[dripsmvcp]

feat(salience): per-session entity-salience reflex (#223)

What

Adds a server-side entity-salience retrieval reflex. Each session keeps an
in-memory ring buffer of the caller's recent query strings. On every read, a
zero-LLM entity pass (substring match on entity name/aliases + FTS via the
existing index) runs over the buffered queries and attaches the top-K matched
entities — with the claims that reference them — as _meta.vouch_salience on
the read response.

New module src/vouch/salience.py:

• record_query(session_id, query, *, window=8) — append to the session's
  bounded deque ring buffer (in-memory only, never written to disk).
• compute_salience(store, session_id, *, top_k=3) — rank entities by how many
  buffered queries match (substring + FTS), returning
  {"entity_id", "claim_count", "top_claim_id"} per top-K entity.
• attach_salience(result, store, session_id, cfg) — sets
  result["_meta"]["vouch_salience"] when the reflex is enabled, a
  session_id is present, and the buffer is non-empty; otherwise no-op.
• reset_session(session_id) — clear a session's buffer.
• Buffers expire after 30 minutes of inactivity (checked on access).

Wiring:

• _h_context (JSONL) and kb_context (MCP) now accept session_id; when
  given, they record_query(...) then attach_salience(...) before returning.
• sessions.session_end calls reset_session(...) so per-session state is
  dropped on session close.

Config (read defensively from .vouch/config.yaml, no pydantic model):
retrieval.reflex.enabled (default True), retrieval.reflex.window
(default 8), retrieval.reflex.top_k (default 3).

Why

Agents repeatedly re-derive the same context across a session. A cheap,
substring/FTS-only reflex surfaces the claim candidates the caller is most
likely about to need — no extra LLM calls, no disk writes, scoped strictly
per session. It rides the existing read path so callers get it for free by
passing session_id.

Test plan

New tests/test_salience.py covers: record-then-compute highlights the entity;
attach_salience adds _meta.vouch_salience when enabled; the JSONL handler
attaches salience on a subsequent context call; retrieval.reflex.enabled: false omits the field; a stateless call (no session_id) omits the field;
reset_session and session_end clear the buffer; the window bounds the
buffer.

Constraints verified: zero LLM calls; per-session only; buffer never persisted.

$ ./.venv/bin/ruff check src tests
All checks passed!

$ ./.venv/bin/mypy src
Success: no issues found in 30 source files

$ ./.venv/bin/python -m pytest -q
94 passed, 6 skipped in 2.03s

Closes #223

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 7f1aeec5-44a4-4b30-a77c-ed2d52b24249

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}