Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors
Rust
feat(hooks): complete short bodies and place cheapest bodies first
Victor Alencarec3dc7c1318f
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex ac9eeb40..fb6ae93a 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -15,16 +15,19 @@ version in [`docs/changelog/`](docs/changelog/):- Changed how the opt-in session-start brief (`[briefing]inject_on_session_start`) spends `max_chars`. Every pinned, `_rules/` and`_slots/` page now gets a short excerpt first, taken from its frontmatter- `abstract:` or `summary:` or else the prose it opens with, and the budget left- deepens pages to a longer excerpt and then the whole body, pinned and- `_slots/` pages first. Before, the brief printed whole bodies in order, so one- long `_rules/` page was cut with a `[truncated by ...]` note and every page- after it was reduced to an "omitted" path. Bodies are no longer cut: a body- that does not fit whole shows its excerpt. Four or more unpinned excerpts from- one folder share a heading, and the omitted list and the closing note now- point at `memory_read_page`. Small wikis whose pages fit still get every body- whole; pin a page to have it shown in full first. The change needs no new- marker key and no migration. (#1264)+ `abstract:` or `summary:`, or else from the prose it opens with (read on+ into its first list items). The budget left deepens pages to a longer+ excerpt and then the whole body: pinned and `_slots/` pages first, then+ pages a few bytes short of whole, then the cheapest bodies. Before, the+ brief printed whole bodies in order, so one long `_rules/` page was cut with+ a `[truncated by ...]` note and every page after it became an "omitted"+ path. Bodies are no longer cut: a body that does not fit whole shows its+ excerpt. Four or more unpinned excerpts from one folder share a heading,+ and the omitted list and the closing note point at `memory_read_page`.+ Small wikis whose pages fit still get every body whole. A project with many+ standing pages now sees all of them, fewer in full: pin a page, or give it+ an `abstract:`, to control what it shows. The change adds no marker key+ and no migration. (#1264)## [3.0.0] - 2026-10-13diff --git a/crates/ai-memory-hooks/src/brief_tiers.rs b/crates/ai-memory-hooks/src/brief_tiers.rsindex 7bd86e37..fe69a419 100644--- a/crates/ai-memory-hooks/src/brief_tiers.rs+++ b/crates/ai-memory-hooks/src/brief_tiers.rs@@ -11,6 +11,11 @@//! This module only does the arithmetic over rendered byte costs; the hook//! router owns the strings and the security scaffold around them.+/// A body at most this many bytes longer than what its page already shows+/// is completed even while other pages still wait for their L1: the rest of+/// such a page costs about what a second heading would.+const SHORT_BODY_SLACK: usize = 128;+/// How deep a core page renders in the brief. Ordered by depth.#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]pub(crate) enum BriefTier {@@ -142,34 +147,44 @@ pub(crate) fn assign_tiers(let mut room = remaining.saturating_sub(omitted_reserve + recent_reserve);let included = &pages[..omitted_from];- let mut promote = |tiers: &mut [BriefTier], privileged: bool, target: BriefTier| {- for (idx, page) in included.iter().enumerate() {- let current = tiers[idx];- if page.privileged != privileged- || page.tiers.is_none()- || current >= target- || current == BriefTier::TitleOnly- {- continue;- }- let (from, to) = (page.cost(current), page.cost(target));- if to > from && to - from <= room {- tiers[idx] = target;- room -= to - from;- }+ let (privileged, unprivileged): (Vec<usize>, Vec<usize>) =+ (0..omitted_from).partition(|&idx| pages[idx].privileged);+ let delta = |tiers: &[BriefTier], idx: usize, target: BriefTier| {+ let page = &pages[idx];+ match (page.tiers, tiers[idx]) {+ (Some(_), current) if current != BriefTier::TitleOnly && current < target => page+ .cost(target)+ .checked_sub(page.cost(current))+ .filter(|d| *d > 0),+ _ => None,}};- promote(&mut tiers, true, BriefTier::L1);- promote(&mut tiers, true, BriefTier::L2);- promote(&mut tiers, false, BriefTier::L1);+ let mut promote =+ |tiers: &mut [BriefTier], order: &[usize], target: BriefTier, max_delta: usize| {+ for &idx in order {+ if let Some(d) = delta(tiers, idx, target)+ && d <= room.min(max_delta)+ {+ tiers[idx] = target;+ room -= d;+ }+ }+ };+ promote(&mut tiers, &privileged, BriefTier::L1, usize::MAX);+ promote(&mut tiers, &privileged, BriefTier::L2, usize::MAX);+ promote(&mut tiers, &unprivileged, BriefTier::L1, usize::MAX);+ promote(&mut tiers, &unprivileged, BriefTier::L2, SHORT_BODY_SLACK);// Full bodies for the remaining pages only once every included page// shows as much as its L1 can: a long body must not outbid a summary.+ // Cheapest first, so the room left shows as many whole pages as it can.let every_page_at_l1 = included.iter().zip(&tiers).all(|(page, tier)| *tier >= BriefTier::L1 || !page.l1_adds());if every_page_at_l1 {- promote(&mut tiers, false, BriefTier::L2);+ let mut cheapest = unprivileged;+ cheapest.sort_by_key(|&idx| (delta(&tiers, idx, BriefTier::L2), idx));+ promote(&mut tiers, &cheapest, BriefTier::L2, usize::MAX);}BriefPlan {@@ -265,8 +280,9 @@ mod tests {// Room for both L1s but not for a body on top of them.let plan = assign(&pages, 100 + 800 + 40, 0);assert_eq!(plan.tiers, vec![L1, L1]);- // One L1 does not fit: no unprivileged body may jump the queue.- let pages = [page(false, 100, 900, 950), page(false, 100, 150, 160)];+ // One L1 does not fit: no long unprivileged body may jump the queue+ // (a body within `SHORT_BODY_SLACK` of its excerpt is the exception).+ let pages = [page(false, 100, 900, 950), page(false, 100, 150, 600)];let plan = assign(&pages, 100 + 200 + 100, 0);assert_eq!(plan.tiers, vec![L0, L1]);}@@ -326,6 +342,28 @@ mod tests {);}+ #[test]+ fn a_body_almost_shown_is_completed_even_when_a_summary_did_not_fit() {+ // The first page's L1 does not fit, which holds back every other+ // unprivileged body; the second page is 60 bytes from whole.+ let pages = [page(false, 100, 900, 950), page(false, 100, 100, 160)];+ let plan = assign(&pages, 100 + 200 + 200, 0);+ assert_eq!(plan.tiers, vec![L0, L2]);+ }++ #[test]+ fn cheaper_bodies_go_first_so_more_pages_show_whole() {+ // Room for 400 bytes of bodies: the first page alone, or both of+ // the others.+ let pages = [+ page(false, 100, 100, 500),+ page(false, 100, 100, 300),+ page(false, 100, 100, 300),+ ];+ let plan = assign(&pages, 100 + 300 + 400, 0);+ assert_eq!(plan.tiers, vec![L0, L2, L2]);+ }+#[test]fn no_pages_is_an_empty_plan() {let plan = assign(&[], 4_000, 100);diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.mdindex 5311f665..6dfe60fb 100644--- a/docs/ARCHITECTURE.md+++ b/docs/ARCHITECTURE.md@@ -228,7 +228,7 @@ extractive L0 excerpt (`ai_memory_core::excerpt`: frontmatter `abstract`, elsebytes); the bytes left deepenpages to an L1 excerpt (`summary` first, 500 bytes, the same clip as A2compaction) and then to the whole body, pinned and `_slots/` pages before the-rest (`ai_memory_hooks::brief_tiers`). A body is included whole or not at all.+rest, other bodies cheapest first (`ai_memory_hooks::brief_tiers`). A body is included whole or not at all.Four or more unpinned excerpts of one family share a heading. Pages that do notfit are listed by path for `memory_read_page`, and the count of them isreserved before any page is deepened. The security notice, thediff --git a/docs/design-tiered-session-brief.md b/docs/design-tiered-session-brief.mdindex 1ae89e4c..ee7ff206 100644--- a/docs/design-tiered-session-brief.md+++ b/docs/design-tiered-session-brief.md@@ -586,11 +586,23 @@ first call" policy after coverage without eating the recent share.truncate an L2 in this pass. Truncation of one body is what starveslater pages today. If L2 does not fit, the page stays at L1.4. **Unprivileged L1.** Same as (2) for the remaining included pages.-5. **Unprivileged L2.** Same as (3), only after every included page is+5. **Short bodies.** In store order, complete any unprivileged page whose+ whole body is at most `SHORT_BODY_SLACK` (128) bytes more than what it+ already shows. This runs before the gate in (6), so one page whose L1+ did not fit cannot hold back bodies that cost about a heading.+6. **Unprivileged L2.** Same as (3), only after every included page isat its max useful depth: L1 (or L0 when L1 is a zero-delta no-op),or TitleOnly. Title-only and zero-delta pages count as already at- max depth. They do not block L2 of siblings. Remaining budget then- deepens already-included pages.+ max depth. They do not block L2 of siblings. Pages go cheapest delta+ first (store order breaks ties), so the room left shows as many+ whole pages as it can.++The risk review (old vs new renderer on the same fixtures) measured the+trade-off this ordering makes: with 24 rules of 300-800 bytes at 8000+bytes, the old renderer showed 12 whole bodies and omitted 11 pages; the+coverage-first packer shows all 24, and fewer of them whole. Steps 5+and 6 recover whole bodies only from bytes coverage did not need; they+never take a page out of the brief to make room for another's body.**No L2 truncation during assignment.** The only remaining cut of pagetext is (a) the L0/L1 clips themselves, (b) the post-escape clamp on thediff --git a/docs/marker-file.md b/docs/marker-file.mdindex 8cb2e3ef..e71810f0 100644--- a/docs/marker-file.md+++ b/docs/marker-file.md@@ -180,7 +180,8 @@ inject_on_session_start = "true"# and footers included. Every core page first gets a short excerpt (its# frontmatter `abstract:` or `summary:`, else the prose it opens with); what is# left deepens pages to longer excerpts and then whole bodies, pinned and-# `_slots/` pages first. A body is shown whole or not at all.+# `_slots/` pages first, then the cheapest bodies. A body is shown whole or+# not at all.# Four or more unpinned excerpts from one folder (`_rules/`, `gotchas/`,# `decisions/`, `procedures/`) share a heading. Pages the budget cannot# cover are listed by path so the agent can `memory_read_page` them,