feat(server): extend _meta.vouch_hot_memory to all read-side kb.* tools

[jsdevninja]

What changed

Every primary read-side kb.* tool now attaches _meta.vouch_hot_memory — a TTL-cached sidebar of recently approved claims — when the KB has recent activity. Coverage extends from kb.search / kb.context / kb.read_claim to kb.read_page, kb.read_entity, kb.read_relation, and all kb.list_* methods. kb.list_* responses are wrapped in {"items": [...], "_meta": {...}} with a deprecation note for clients that expected a flat list. kb.capabilities advertises the contract under hot_memory.

Closes #225

Why

Gbrain attaches its hot-memory sidebar to every MCP read response; vouch only covered three tools after the initial hot-memory work. Agents calling kb.read_entity or kb.list_pending had to make a second round-trip to learn what just changed. This is the cheap follow-up that fully closes that gap.

What might break

Breaking (JSONL / MCP): kb.list_pages, kb.list_claims, kb.list_entities, kb.list_relations, kb.list_sources, and kb.list_pending no longer return a bare list. They return a dict envelope with an items key. _meta.deprecation documents the migration (result.items instead of result). No on-disk .vouch/ layout changes; no new write paths; the review gate is untouched.

Non-breaking: Dict-returning read tools (kb.read_*, kb.search, kb.context) keep their existing top-level shape; _meta.vouch_hot_memory is additive and omitted when the sidebar would be empty.

VEP

Not required — read-side response decoration only; no object model, on-disk layout, bundle format, or audit-log shape changes.

Tests

• make check passes locally (lint + mypy + ruff)
• New / changed behaviour has a test (tests/test_hot_memory.py, including test_hot_memory_universal_coverage)
• CHANGELOG.md updated under ## [Unreleased]

[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: eaf0895d-763e-4ccc-a169-b4ed1ec34571

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.}

[plind-junior]

Fix the conflict

[jsdevninja]

@plind-junior Fixed conflicts

[jsdevninja]

@plind-junior please check

[plind-junior]

this does what #225 asked, and does it carefully — _meta.vouch_hot_memory now reaches every read-side tool with the per-tool query bias the issue specced (entity name+aliases, page title+tags in src/vouch/hot_memory.py, recency-only for kb.list_pending), the kb.list_* envelope carries the _meta.deprecation note, kb.capabilities advertises the contract, and test_hot_memory_universal_coverage enforces the covered-or-explicitly-excluded acceptance over capabilities.METHODS. tests are genuine (unit + jsonl integration + a parametrized smoke per covered method) and ci is green on py3.11–3.13. three things need fixing before merge.

blocking: the second CHANGELOG.md hunk inserts the feature's "added" bullet under ## [1.0.0] — 2026-06-26 → ### Added (merge-base line 309, section header at 279), not under [Unreleased]. released sections are immutable history — move the bullet up into [Unreleased] → ### Added. the pr checklist says the changelog was updated under [Unreleased], but only the changed/fixed hunk is.

blocking: LIST_ENVELOPE_DEPRECATION says "remove_in": "0.3.0" (src/vouch/hot_memory.py:145), but the repo is at 1.3.0 — a client reading this would conclude the flat-list shape was removed long ago. the issue asked for one release cycle, so "1.4.0".

blocking: the repo's own jsonl clients still read the flat shape and none of them run in ci. adapters/jsonl-shell/example-pipeline.sh:36 (jq '.result[] | …'), adapters/jsonl-shell/README.md:35 and :53, and examples/browse-and-read/run.sh:60 (row["result"][0][key] in first_field) all break against the new envelope — .result[] on a dict iterates its values, and ["result"][0] is a KeyError. update to .result.items[] / row["result"]["items"][0][key], and grep for any other .result[] consumers while at it.

non-blocking: _SIDEBAR_CACHE (src/vouch/hot_memory.py:236) never evicts — kb.read_claim keys the cache by full claim text and kb.search by raw user query, so a long-running mcp server accumulates one entry per distinct query forever; a small size cap or prune-expired-on-insert would close it (the unlocked access is a benign race, but a comment saying so would help). separately, the host_compat description backfill (src/vouch/models.py:510, schemas/capabilities.schema.json, the changelog "fixed" entry) documents a fix that already exists on the base branch — a drive-by that belongs in its own docs pr. and #225 asked to "bump capabilities version"; since Capabilities.version mirrors __version__ and is bumped at release time, deferring to the 1.3.0 release seems right, but worth one line in the pr body saying so.

verdict: request changes — the feature and tests are solid and fully answer #225, but the misplaced changelog entry, the impossible remove_in version, and the broken in-repo jsonl examples should be fixed first.

[jsdevninja]

@plind-junior updated