feat(hermes): preserve recall freshness and add budgeted task-specific memory inspection

[joshyorko]

Existing-corpus recall amendment — September 8, 2026

Both existing/imported memories and newly written records must pass this issue. Use #234's core legacy/reconciliation contract and #231's stable identity mappings; no adapter-local migration or replacement retrieval framework.

Core guarantees to consume: preserve source evidence independently from current claim status. Old records with missing optional provenance, timestamps, lineage or a broad other type remain usable under policy, with unknowns visible. No invented author/date/verification and no implicit trust upgrade for an imported assistant summary. Retention/searchability, relevance/budget selection and admission as current truth are separate decisions.

Adapter behavior: support documented legacy response shapes. Missing freshness, origin or lineage is not equivalent to fresh/verified, unsafe, withdrawn or empty; render a bounded 'unknown/legacy-limited' indication without dropping every otherwise valid result. Preserve current/uncertain/corrected/withdrawn/superseded dispositions supplied by core; never render a known superseded statement as an unqualified current fact. Show source time and claim-status time separately when available; as_of cannot claim an exact historical perspective unsupported by available timestamps. Do not use import/migration time as observation or verification time.

Task packs may prioritize typed/current evidence, but must not hard-exclude useful historical/imported/other material solely because it lacks new classification fields. Use bounded relevance/diversity/fallback behavior through existing core seams, explicit historical/evidence drill-down and omission/withheld diagnostics. Unknown legacy currentness does not require blanket removal from ordinary recall; qualify admitted evidence. Known withdrawal and scope/privacy policy still take precedence. Budget labels/provenance as well as text; no all-history prompt dump to compensate for weak metadata.

Consumer rollout: benchmark the real upgrade shape on sanitized pre-change data before replacing the provider. Keep the same store, namespaces and source handles; explain compatibility limits and pending reconciliation. Read/inspect/prefetch must not reclassify or backfill the corpus. Invalidate stale cached projections when core corrections/migrations change admission; preserve source identities and compatible existing mirror ownership.

Additional acceptance gates

• Mixed old/new fixture corpus includes retained Codex files, Hermes turns/assistant notes, transferred MemoryD origins, other records, partial/missing timestamps and both corrected and uncertain claims.
• Compare permitted useful recall before/after upgrade at the same total budget. Report regressions by legacy shape/source class rather than celebrating improved clean-new-record scores alone.
• An old safe useful other record can be found; an old imported summary is labeled as such; missing metadata neither disappears silently nor becomes user-confirmed. Unknown scope remains withheld with a reason.
• Migration preview/cancel/apply, old-source reimport and restored snapshots keep stable citations and correctly separated source statements/current dispositions. Known withdrawn matches are not reintroduced; ambiguous equivalence remains visible.
• Tiny-budget and distractor-heavy tests preserve bounded useful breadth without fixed-lane starvation or flooding. Missing-history/time basis is disclosed on historical questions; malformed envelopes still fail safely.

---

Outcome

The native Hermes adapter returns useful task-scoped context without dropping MemoryD's uncertainty/freshness semantics, starving later workspaces, or making an LLM call merely to choose a pack.

Priority: P1 for semantic preservation; task-specific read tools are the following independently reviewable slice. Lifecycle recovery is #230.

Verified baseline

At 25d617b5f08593c76d336f90b8ffd1e78f77afbd, prefetch() requests four workspaces sequentially in a fixed order under one deadline/token budget. Every request uses active_task; repo/files are not supplied. It renders fact content and provenance but not fact.policy.freshness; get_tool_schemas() returns an empty list.

src/protocol.rs already has RecallFreshness, admission/provenance and withheld metadata. src/recall.rs already implements seven pack modes and temporal filtering. Reuse those contracts.

Slices

A. Preserve the response contract

• Render stale/age, temporal perspective, source/trust and recall-not-authority faithfully; unknown metadata must stay unknown.
• Do not treat a malformed envelope, incomplete retrieval, withheld result, or outage as proof that no memory exists.
• Validate nested response shapes and bound bytes, items, metadata, and final model-visible output including provenance overhead.
• Avoid claiming a character heuristic is a hard tokenizer-exact limit; document the estimator and include multilingual/code-heavy tests.
• Preserve all useful existing metadata without dumping policy internals or sensitive source paths into every prompt.

B. Deliberate task-scoped reads

• Add a small native provider read surface for status, recall/search, selected pack and as-of inspection. Use existing service methods and the Hermes tool contract, not an MCP hop in the main conversation loop.
• Accept only configured scopes. The model may narrow a grant but cannot invent a broader profile/workspace.
• Prefer explicit task/repo context and a deterministic transparent selection policy. Unknown tasks retain a conservative default. No classifier-model spend by default.
• Personal/self/relationship context must not consume the entire work budget by order alone. Allocate/reclaim bounded per-lane shares or choose only relevant configured lanes. Preserve one total deadline and one total budget.
• Report why a lane/record was used, withheld or not queried through an explicit diagnostic path, not a full trace every turn.
• Parameterize display/persona/producer configuration while preserving current consumer defaults; do not silently rename/migrate their workspaces.

Acceptance

• Stale record returned by core stays visibly stale in final injected context.
• Tiny budget plus verbose early lane still follows documented work-lane fairness; no hard-coded last-lane starvation.
• Debugging/review/planning/onboarding/personal queries request the intended pack under explicit policy, and irrelevant queries may return no context.
• Exact repo/branch/file hints never widen scope; cross-profile denial, ambiguous repo, session switch and late responses are covered.
• Search/as-of distinguish historical from current truth; metadata contains source and time basis.
• CJK, emoji, long opaque handles, giant source-reference lists and malformed facts cannot overflow bounds or crash a turn.
• Read tools perform no writes, provider/model calls, implicit imports, or promotion.
• Compare retrieval quality and token cost with the current fixed-four-lane baseline using the same fixtures, model and total budget.

Primary reference: Hermes native memory tools and lifecycle. #228 owns fast episodic intake; this issue does not create another evidence store or ranking engine.