feat: retrieval-utility logging + history-based deletion (Closes #1480)

[Lexus2016]

Automated evolution PR for issue #1480 (child of #1270).

Summary

Add structured retrieval-utility logging on the existing memory retrieval infrastructure and a history-based deletion function that removes records retrieved ≥n times with average downstream utility below a threshold. The ACL 2026 memory-management paper proves selective addition + history-based deletion beats add-all by 22-25 points.

Changes

• agent/retrieval_utility.py (new): Sidecar JSON log module with:

  • record_retrieval() — log when memory/skill context is retrieved
  • record_outcome() — log downstream outcome (helpful/neutral/harmful) derived from friction signals
  • compute_utility() — aggregate avg downstream utility per record
  • delete_low_utility_records() — identify records eligible for history-based deletion (retrieved ≥n times, avg utility < floor)
  • Atomic writes, cross-process file locking, cap at 5000 entries

• agent/memory_manager.py: Wire retrieval logging into existing infrastructure:

  • prefetch_all() calls _record_retrieval_utility() when a provider returns context
  • sync_all() calls _record_retrieval_outcomes() after scoring friction signals
  • Per-turn tracking via _pending_retrievals list

• hermes_cli/config.py: Add memory.retrieval_utility config section (enabled, min_retrievals, utility_floor)

• Tests: 25 unit tests + 7 MemoryManager integration tests (all passing)

Design notes

• Sidecar pattern mirrors tools/skill_usage.py — operational telemetry stays out of user-authored content
• Best-effort: failures log at DEBUG and return silently; broken sidecar never breaks memory
• Profile-aware via get_hermes_home()
• No prompt caching impact: logging is a side effect in the background worker path, not in the system prompt

Closes #1480

[Lexus2016]

Reviewed and pushed two privacy fixes to this branch (8b8409ea8). Both are small, and neither costs the feature anything.

1. record_retrieval persisted retrieval_context[:500] — up to 500 characters of the user's query, on disk, per retrieval.

It was write-only: compute_utility scores outcomes alone and never reads it, so the text served no downstream purpose at all. Now accepted but not stored. The parameter stays in the signature so callers need no change, and a future consumer can opt into a redacted form deliberately rather than by default.

2. retrieval_utility.enabled defaulted True — every memory/skill hit in every ordinary session wrote a record to disk unasked. Now False, matching the HERMES_EVOLUTION_CAPTURE precedent from #1363, where the same question came up and was settled the same way.

The existing test asserted the stored context, so it now pins the new behaviour, plus a test that the query text appears nowhere in the persisted entry.

---

On the other PR

#1482 closes the same issue with a different approach — it logs retrieval utility for ERL heuristics (scripts/evolution_retrieval_utility.py, plus backfill through the funnel), where this one covers memory/skill records in the runtime.

#1480 asks for memory/skill retrieval specifically, so this PR is the one that matches. Merging both would create two parallel utility stores — one under agent/, one under scripts/ — recording the same kind of signal for different subsystems, with no shared identity or schema.

Merging this one; closing #1482 with the suggestion that if heuristic-retrieval utility is wanted, it should write to this store rather than a second one.

26 passing in test_retrieval_utility.py, 31 with the memory-manager suite. Ruff clean.