Module retained 

Budgeted evidence retention for recall (EMBER, arXiv:2606.05894).

The default recall path returns whole memory records. For an LLM caller that must keep evidence resident in a bounded context window, dumping raw chunks burns the budget fast: a handful of full records and the window is full, even though most of each record is filler around one salient fact.

EMBER (Efficient Memory By Evidence Retention, arXiv:2606.05894) frames this as a writer problem: under a fixed retained-token budget, learn to keep compact, recoverable evidence rather than raw text. This module is a v0 stand-in for that learned writer:

• Instead of dumping raw chunks, it emits verbatim evidence capsules — a short verbatim excerpt of the record plus a retrieval key (the record id) so the caller can re-fetch the full chunk on demand. A capsule costs a fraction of the raw chunk, so many more distinct facts survive the same budget.
• Capsules are packed greedily under the budget, ranked by a simple recoverability heuristic — recency × retrieval-hit-rate — the v0 stand-in for EMBER’s learned retention score. Recently written and frequently-retrieved records are the cheapest to keep resident because they are the most likely to be needed again.

Wiring

RecallRequest::retained_token_budget carries the optional cap. When Some(budget), the engine builds a RetentionReport from the final recall result and returns it in RecallResponse::retained_evidence. It is purely additive: the memories list is unchanged, so every existing caller is unaffected; the capsule view is an extra, opt-in projection of the same hits.

What this is NOT

• Not EMBER’s learned writer. The recoverability score is a hand-rolled recency × hit-rate heuristic, not a trained model. The arXiv:2606.05894 reference is a framing anchor, not a reproduction claim.
• Not lossy on the store. Capsules are a read-side projection; nothing is mutated or deleted. The retrieval key recovers the full record verbatim from the backend.
• Not a tokenizer. Token counts are the standard ceil(chars/4) rough-cut estimate; absolute counts are approximate, the budget-vs-naive comparison is the signal.

Structs

EvidenceCapsule

A verbatim evidence capsule: a short excerpt plus the retrieval key that recovers the full record.

RetentionCandidate

One candidate record handed to retain_within_budget.

RetentionReport

Diagnostics + capsules produced under a retained-token budget.

Constants

DEFAULT_EXCERPT_TOKENS

Default verbatim excerpt cap per capsule, in estimated tokens.

Functions

est_tokens

Rough-cut token estimate: ceil(chars / 4). There is no tokenizer in the core, so this is a deliberate approximation (see the module-level “what this is NOT”).

recoverability

recency × retrieval-hit-rate — the v0 recoverability stand-in for EMBER’s learned retention score.

retain_within_budget

Pack the highest-recoverability evidence into budget_tokens, preferring compact capsules over raw chunk dumps.