Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors
Rust
//! Extractive L0/L1 excerpts of a wiki page for the SessionStart brief.
//!
//! The brief leads with a short excerpt of every standing page and spends
//! what budget is left on full bodies, so it needs a cheap, deterministic
//! way to shrink a page. Everything here is string work over the frontmatter
//! and body the store already returns: no LLM, no I/O.
//!
//! L0 prefers the frontmatter `abstract:` (the page's own one-line pointer),
//! L1 prefers `summary:` (the longer operator summary). Both fall back to the
//! prose the page opens with, read across paragraphs and lists up to the clip,
//! skipping headings and the ADR metadata fields the profile digest skips. A
//! rules page often opens with a sentence about itself; reading on is what
//! puts its first rules in the excerpt.
use crate::profile::is_metadata_field;
use crate::sanitize::truncate_utf8_bytes;
/// Longest L0 excerpt, in UTF-8 bytes (ellipsis included).
pub const BRIEF_L0_MAX_BYTES: usize = 256;
/// Longest L1 excerpt, in UTF-8 bytes (ellipsis included). Matches the L1
/// line A2 compaction writes, so a compacted page's L1 is never re-clipped.
pub const BRIEF_L1_MAX_BYTES: usize = 500;
/// How much of a body the prose walk looks at. An excerpt is at most
/// [`BRIEF_L1_MAX_BYTES`] long, so the walk never needs the rest of a large
/// page, and bounding it keeps every session start cheap however big the
/// standing pages grow.
const PROSE_SCAN_MAX_BYTES: usize = 16 * 1024;
/// Prefix of the footer A2 compaction stamps on a compacted body. It is
/// chrome about the page, not the page's prose, so the walk skips it.
const COMPACTION_FOOTER_PREFIX: &str = "_Extractively compacted from a cold episodic page";
/// The L0 and L1 excerpts of one page. Either is `None` when the page has
/// no frontmatter pointer and no prose to fall back on.
#[derive(Debug, Clone, PartialEq, Eq, Default)]
pub struct PageExcerpt {
/// Short pointer: `abstract`, else `summary`, else the leading prose,
/// clipped to [`BRIEF_L0_MAX_BYTES`].
pub l0: Option<String>,
/// Longer pointer: `summary`, else `abstract`, else the leading prose,
/// clipped to [`BRIEF_L1_MAX_BYTES`].
pub l1: Option<String>,
}
/// Build the L0/L1 excerpts of a page from its frontmatter JSON and its
/// (frontmatter-stripped) markdown body.
#[must_use]
pub fn excerpt_from_page(frontmatter: &serde_json::Value, body: &str) -> PageExcerpt {
let abstract_ = frontmatter_nonempty(frontmatter, "abstract");
let summary = frontmatter_nonempty(frontmatter, "summary");
let paragraph = || leading_prose(body);
let l0 = abstract_
.or(summary)
.map(str::to_owned)
.or_else(paragraph)
.map(|text| truncate_utf8_bytes(&collapse_whitespace(&text), BRIEF_L0_MAX_BYTES));
let l1 = summary
.or(abstract_)
.map(str::to_owned)
.or_else(paragraph)
.map(|text| truncate_utf8_bytes(&collapse_whitespace(&text), BRIEF_L1_MAX_BYTES));
PageExcerpt { l0, l1 }
}
/// The prose `body` opens with, whitespace collapsed to single spaces and
/// read across paragraphs and list items. Headings, lone `---` rules and ADR
/// metadata fields (`**Status:** Accepted`) are skipped wherever they sit, and
/// so is the A2 compaction footer. Only the first [`PROSE_SCAN_MAX_BYTES`]
/// are read, and reading stops once there is more than the longest clip can
/// carry.
#[must_use]
pub fn leading_prose(body: &str) -> Option<String> {
let mut end = body.len().min(PROSE_SCAN_MAX_BYTES);
while !body.is_char_boundary(end) {
end -= 1;
}
let mut prose = String::new();
for block in body[..end]
.split("\n\n")
.flat_map(|block| block.split("\n\r\n"))
{
let block = block.trim();
if block.starts_with(COMPACTION_FOOTER_PREFIX) {
continue;
}
for line in block.lines().map(str::trim) {
if line.is_empty()
|| line.starts_with('#')
|| line == "---"
|| is_metadata_field(line_head(line))
{
continue;
}
// Collapse whitespace while copying, and stop one byte past the
// longest clip: the clip only needs to know there is more.
let mut space = !prose.is_empty();
for ch in line.chars() {
if ch.is_whitespace() {
space = !prose.is_empty();
continue;
}
if space {
prose.push(' ');
space = false;
}
prose.push(ch);
if prose.len() > BRIEF_L1_MAX_BYTES {
return Some(prose);
}
}
}
}
(!prose.is_empty()).then_some(prose)
}
/// The start of a line, long enough for any metadata label: whether a line
/// is `**Status:** …` is decided by its first few words, and checking a
/// whole multi-kilobyte line would cost more than the excerpt.
fn line_head(line: &str) -> &str {
let mut end = line.len().min(256);
while !line.is_char_boundary(end) {
end -= 1;
}
&line[..end]
}
/// A frontmatter string value, trimmed, or `None` when the key is absent,
/// not a string, or blank.
#[must_use]
pub fn frontmatter_nonempty<'a>(frontmatter: &'a serde_json::Value, key: &str) -> Option<&'a str> {
frontmatter
.get(key)
.and_then(serde_json::Value::as_str)
.map(str::trim)
.filter(|value| !value.is_empty())
}
fn collapse_whitespace(text: &str) -> String {
text.split_whitespace().collect::<Vec<_>>().join(" ")
}
#[cfg(test)]
mod tests {
use super::*;
use serde_json::json;
fn excerpt(frontmatter: serde_json::Value, body: &str) -> PageExcerpt {
excerpt_from_page(&frontmatter, body)
}
#[test]
fn l0_prefers_abstract_and_l1_prefers_summary() {
let e = excerpt(
json!({"abstract": "short pointer", "summary": "longer summary"}),
"Body prose.",
);
assert_eq!(e.l0.as_deref(), Some("short pointer"));
assert_eq!(e.l1.as_deref(), Some("longer summary"));
}
#[test]
fn a_lone_summary_serves_both_tiers() {
let e = excerpt(json!({"summary": "only summary"}), "Body prose.");
assert_eq!(e.l0.as_deref(), Some("only summary"));
assert_eq!(e.l1.as_deref(), Some("only summary"));
}
#[test]
fn a_lone_abstract_serves_both_tiers() {
let e = excerpt(json!({"abstract": "only abstract"}), "Body prose.");
assert_eq!(e.l0.as_deref(), Some("only abstract"));
assert_eq!(e.l1.as_deref(), Some("only abstract"));
}
#[test]
fn blank_or_non_string_keys_fall_back_to_the_body() {
for frontmatter in [
json!({"abstract": "", "summary": " \n\t"}),
json!({"abstract": 7, "summary": null}),
serde_json::Value::Null,
json!({}),
] {
let e = excerpt(frontmatter.clone(), "Body prose.");
assert_eq!(e.l0.as_deref(), Some("Body prose."), "{frontmatter}");
assert_eq!(e.l1.as_deref(), Some("Body prose."), "{frontmatter}");
}
}
#[test]
fn a_page_with_nothing_to_say_has_no_excerpt() {
for body in ["", " \n\n ", "# Only a heading\n", "---\n\n## Context\n"] {
assert_eq!(excerpt(json!({}), body), PageExcerpt::default(), "{body:?}");
}
}
#[test]
fn the_walk_continues_past_a_heading_only_block() {
let e = excerpt(json!({}), "# Title\n\nUse nextest.");
assert_eq!(e.l0.as_deref(), Some("Use nextest."));
assert_eq!(e.l1.as_deref(), Some("Use nextest."));
}
#[test]
fn the_adr_template_yields_its_context_sentence() {
// ai-memory's own ADR template, as the profile digest tests it.
let body = "# Use WAL mode\n\n**Status:** accepted \
<!-- proposed | accepted | superseded by [[decisions/other]] -->\n\n\
## Context\n\nReaders blocked the writer under load.\n";
let e = excerpt(json!({}), body);
assert_eq!(
e.l0.as_deref(),
Some("Readers blocked the writer under load.")
);
assert_eq!(
e.l1.as_deref(),
Some("Readers blocked the writer under load.")
);
}
#[test]
fn metadata_without_a_blank_line_is_skipped_inside_the_block() {
let body =
"**Status:** Accepted\n**Date:** 2026-10-01\nEvery store opens SQLite in WAL mode.";
let e = excerpt(json!({}), body);
assert_eq!(
e.l0.as_deref(),
Some("Every store opens SQLite in WAL mode.")
);
}
#[test]
fn a_terse_labelled_rule_is_prose_not_metadata() {
let e = excerpt(json!({}), "**Package manager:** pnpm");
assert_eq!(e.l0.as_deref(), Some("**Package manager:** pnpm"));
}
#[test]
fn a_wrapped_paragraph_collapses_to_one_line() {
let e = excerpt(
json!({}),
"First line\n wraps here.\n\nSecond paragraph.",
);
assert_eq!(
e.l0.as_deref(),
Some("First line wraps here. Second paragraph.")
);
}
#[test]
fn rules_after_a_preface_reach_the_excerpt() {
// A rules page that opens with a sentence about itself: the rules
// are what an agent needs, so the excerpt runs on into the list.
let body = "# Security\n\nThis page collects the security rules.\n\n\
- NEVER commit secrets to git\n- Rotate tokens monthly\n";
let e = excerpt(json!({}), body);
assert_eq!(
e.l0.as_deref(),
Some(
"This page collects the security rules. \
- NEVER commit secrets to git - Rotate tokens monthly"
)
);
}
#[test]
fn headings_and_metadata_inside_the_page_are_not_prose() {
let body = "Intro sentence.\n\n## Rules\n\n**Status:** Accepted\n- keep it boring";
let e = excerpt(json!({}), body);
assert_eq!(e.l0.as_deref(), Some("Intro sentence. - keep it boring"));
}
#[test]
fn l1_carries_more_of_a_long_page_than_l0() {
let body = (0..60)
.map(|i| format!("Sentence number {i}."))
.collect::<Vec<_>>()
.join("\n\n");
let e = excerpt(json!({}), &body);
let (l0, l1) = (e.l0.unwrap(), e.l1.unwrap());
assert!(l1.len() > l0.len() + 200, "L1 must add depth: {l0} / {l1}");
assert!(l1.starts_with(l0.trim_end_matches('…')));
}
#[test]
fn frontmatter_whitespace_collapses_too() {
let e = excerpt(json!({"abstract": " two\n lines "}), "");
assert_eq!(e.l0.as_deref(), Some("two lines"));
}
#[test]
fn clips_are_byte_bounded_with_an_ellipsis() {
let long = "word ".repeat(200);
let e = excerpt(json!({}), &long);
let l0 = e.l0.unwrap();
let l1 = e.l1.unwrap();
assert!(l0.len() <= BRIEF_L0_MAX_BYTES && l0.ends_with('…'), "{l0}");
assert!(l1.len() <= BRIEF_L1_MAX_BYTES && l1.ends_with('…'), "{l1}");
assert!(l1.len() > l0.len());
}
#[test]
fn clips_never_split_a_code_point() {
let e = excerpt(json!({"abstract": "🦀".repeat(200)}), "");
let l0 = e.l0.unwrap();
assert!(l0.len() <= BRIEF_L0_MAX_BYTES);
assert!(l0.trim_end_matches('…').chars().all(|c| c == '🦀'));
}
#[test]
fn text_at_the_cap_is_kept_whole() {
let exact = "a".repeat(BRIEF_L0_MAX_BYTES);
let e = excerpt(json!({"abstract": exact.clone()}), "");
assert_eq!(e.l0.as_deref(), Some(exact.as_str()));
}
#[test]
fn a_huge_page_costs_no_more_than_its_clip() {
// Excerpting runs on every session start, for every core page; a
// multi-megabyte line must not be copied and collapsed in full only
// to be cut to 500 bytes. Reading the whole line takes about half a
// second in a debug build; the bounded walk takes microseconds, so
// the bound below leaves slow CI runners plenty of slack.
let body = format!("Lead.\n\n{}", "z".repeat(5_000_000));
let started = std::time::Instant::now();
let e = excerpt(json!({}), &body);
assert!(
started.elapsed() < std::time::Duration::from_millis(100),
"{:?}",
started.elapsed()
);
assert!(e.l1.unwrap().len() <= BRIEF_L1_MAX_BYTES);
}
#[test]
fn leading_prose_returns_no_more_than_the_longest_clip_needs() {
let long_word = "z".repeat(50_000);
let prose = leading_prose(&format!("Lead.\n\n{long_word}")).unwrap();
assert!(prose.len() <= BRIEF_L1_MAX_BYTES + 4, "{}", prose.len());
assert!(prose.starts_with("Lead. zzz"));
}
#[test]
fn the_a2_footer_is_not_prose() {
let footer_only = "_Extractively compacted from a cold episodic page (A2 tier-down). The full \
pre-compaction body is retained in git history._\n";
assert_eq!(excerpt(json!({}), footer_only), PageExcerpt::default());
let compacted = format!(
"The writer actor owns every SQLite write.\n\n## Retained facts\n\n- `WriterHandle`\n\n{footer_only}"
);
let e = excerpt(json!({"compacted": true}), &compacted);
// The retained facts are prose to the excerpt; the footer is not.
assert_eq!(
e.l0.as_deref(),
Some("The writer actor owns every SQLite write. - `WriterHandle`")
);
}
#[test]
fn the_a2_footer_is_not_prose_with_crlf() {
let body = "The writer actor owns every SQLite write.\n\n## Retained facts\n\n- `WriterHandle`\n\n_Extractively compacted from a cold episodic page (A2 tier-down). The full pre-compaction body is retained in git history._\n";
let expected = "The writer actor owns every SQLite write. - `WriterHandle`";
let lf = excerpt(json!({"compacted": true}), body);
assert_eq!(lf.l0.as_deref(), Some(expected));
assert_eq!(lf.l1.as_deref(), Some(expected));
for body in [body.replace('\n', "\r\n"), body.replace("\n\n", "\n\r\n")] {
let crlf = excerpt(json!({"compacted": true}), &body);
assert_eq!(crlf, lf, "CRLF excerpts must omit the same A2 footer as LF");
}
}
}