feat(memory): recall category breadcrumbs + drill-down tool

[pufit]

Summary

memU is hierarchical: an item is one atomic fact, a category is a rolled-up topic document (5–20KB) that indexes many items. recall() returned category hits with their full summary inlined, so a handful of category hits ballooned the tool output past the harness's inline-output limit — it got silently persisted to a file (Output too large (54.9KB)) instead of reaching the model. The same fat summaries also bloated every new session's pre-recall system prompt (engine.py), and duplicated the items recall() already returns.

This reframes a category as an index entry, not a payload: recall surfaces it as a one-line breadcrumb you can drill into on demand.

What changed

• recall() now returns items first (atomic, full content) followed by category breadcrumbs — the curated description (or first content line of the summary, with [ref:] markers stripped), capped to 200 chars. Items and categories are capped independently (limit, category_limit).
• New memory_expand_category tool drills a cat:<id> breadcrumb into its constituent items via the memu_category_items membership table — most-recent-first, optional keyword filter, bounded.
• Hard byte-budget backstop (_clip_to_budget) on the recall handler output, so it can never trip the persister again regardless of content.
• All three recall() consumers (recall tool, session_context, engine pre-recall) benefit automatically — the fix is at the bridge layer.

Impact (measured on real data)

The 5 fattest categories dumped verbatim = 80,964 bytes. As breadcrumbs = 384 bytes — a 99.5% reduction. Verified live: the query that previously returned Output too large (54.9KB) now returns 5 memories + 5 related topics, and memory_expand_category drills a category of 858 items down to a bounded, filtered list.

Test plan

• tests/test_recall_breadcrumbs.py — 14 tests: breadcrumb extraction (description / summary fallback / truncation), byte-budget clipping, recall item/category split + caps, expand_category recency ordering / keyword filter / unknown-id, both handlers.
• Full suite: 844 passed.
• Backend-only — no frontend build needed.
• Verified live against the production memU DB.

Generated by Nerve