Skip to content

Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors

Rust

docs: design for tiered L0/L1/L2 SessionStart brief (R7)

Victor Alencar9bc5a1377c6f
diff --git a/docs/design-tiered-session-brief.md b/docs/design-tiered-session-brief.md
new file mode 100644
index 00000000..b72dafc6
--- /dev/null
+++ b/docs/design-tiered-session-brief.md
@@ -0,0 +1,1290 @@
+# Design: tiered L0/L1/L2 SessionStart brief
+
+**Status:** Draft (2026-10-13). Open questions resolved. Eventual path:
+[`docs/design-tiered-session-brief.md`](design-tiered-session-brief.md).
+
+This is the remaining landscape R7 work: consume extractive L0/L1/L2
+tiers on the opted-in SessionStart project brief. Additive rendering on
+the next minor after 3.0.0. Verified against `main` at `dbe928e3`
+(`release: v3.0.0`).
+
+Ideas only from OpenViking's progressive-disclosure tiers and Letta-code
+MemFS directory deferral. Do not vendor either tree (OpenViking is AGPLv3).
+No `viking://` URI scheme, no VLM sidecar, no TrieHI index, no on-disk
+`MEMORY.md` convention.
+
+---
+
+## Problem
+
+`render_session_brief` in `crates/ai-memory-hooks/src/router.rs` (around
+line 2391) spends `[briefing] max_chars` (default 4000, clamp 1500-20000)
+on full L2 bodies of up to 24 core pages (pinned / `_rules/` /
+`_slots/`), then titles-only for up to 10 recent pages, then an omitted
+suffix.
+
+The packing is greedy and suffix-cutting. It writes each core page as
+`## {title} (`{path}`)` plus `page.body.trim()`. The first body that does
+not fit is truncated with `BRIEF_TRUNCATED_NOTICE` and every later core
+page is omitted as a path pointer. One long `_rules/` page therefore eats
+the budget; later standing pages become omitted pointers even when a
+one-sentence abstract of each would have fit.
+
+OpenViking's reported 34-91% input-token cut is almost entirely from
+deferring full content. Letta-code MemFS v2 compiles root `*.md` every
+turn and defers child directories behind index files. Landscape R7
+(`docs/research-2026-landscape.md`, around lines 592-615) already named
+this gap. 2.4 partly realized it by *persisting* extractive tiers for cold
+episodic pages (A2 in `docs/design-memory-aging.md`). Remaining R7 is
+*consuming* those tiers (and the same extractive fallbacks on never-compacted
+pages) on the on-start brief.
+
+This is a token-efficiency change on the hot path: every opted-in session
+start, synchronously, inside the `GET /handoff` budget (shell hooks
+`curl --max-time 1.0` in `hooks/_lib.sh`; native
+`DEFAULT_HANDOFF_TIMEOUT` is 3s in
+`crates/ai-memory-cli/src/commands/hook.rs`).
+
+---
+
+## What already exists (do not rebuild)
+
+### SessionStart brief renderer
+
+Verified in `crates/ai-memory-hooks/src/router.rs`:
+
+- `BRIEF_BUDGET_DEFAULT = 4_000`, `BRIEF_BUDGET_MIN = 1_500`,
+ `BRIEF_BUDGET_MAX = 20_000` (UTF-8 bytes, truncated on a code-point
+ boundary via `truncate_at_char_boundary`; the marker key is named
+ `max_chars`).
+- `BRIEF_CORE_PAGES_LIMIT = 24`, `BRIEF_RECENT_PAGES_LIMIT = 10`.
+- `render_requested_session_brief` (around 2051) runs only when the
+ query flag `briefing` is truthy. It clamps `briefing_budget`, fetches
+ via `session_brief_pages_with_slot_visibility`, and calls
+ `render_session_brief`.
+- Packing priority today, highest first: closing untrusted fence + agent
+ footer (reserved via `brief_tail_len`) → security preamble +
+ `UNTRUSTED_MEMORY_NOTICE` → full page bodies → omitted pointers →
+ recent titles. A third of the variable region is reserved for pointer
+ sections before bodies are packed, then given back if unused.
+- Once one core page does not fit, every later one is omitted. The omitted
+ set is always a suffix of `core`.
+- Fence markers inside untrusted bodies are HTML-escaped
+ (`escape_untrusted_history_tail`); escape only lengthens the text, so a
+ final clamp of the untrusted region (never the preamble, never the
+ closing fence) enforces the budget after escape.
+- Tests: `render_session_brief_enforces_budget`,
+ `render_session_brief_never_exceeds_budget`,
+ `brief_budget_floor_clears_the_mandatory_scaffold` (around 16281). The
+ floor must exceed the scaffold and still leave ≥500 bytes for page
+ content. Recomputed `brief_scaffold_len` from the current constants is
+ 816 bytes (`BRIEF_PREAMBLE_TITLE` is 85 UTF-8 bytes: compass emoji
+ U+1F9ED is four bytes; the title's U+2014 is three). Leftover at
+ `BRIEF_BUDGET_MIN` is 684. Adding ` or `memory_read_page`` to the
+ footer is 22 bytes (leftover 662), still ≥500. commit 4 re-measures from
+ `brief_scaffold_len()` at that SHA.
+- The security notice, both untrusted-history markers, and
+ `BRIEF_AGENT_FOOTER` are budget-non-negotiable.
+
+### Store fetch
+
+`BriefPageBody` in `crates/ai-memory-store/src/reader.rs` (around 1720) is
+`{path, title, body, pinned, updated_at}`. Full body only. No abstract,
+summary, frontmatter, or compacted flag.
+
+`session_brief_pages` / `session_brief_pages_with_slot_visibility`
+(around 7703-7760):
+
+```sql
+SELECT path, title, body, pinned, updated_at
+FROM pages
+WHERE workspace_id = ?1 AND project_id = ?2 AND is_latest = 1
+ AND not-expired
+ AND (path GLOB '_rules/*'
+ OR (pinned = 1 AND path NOT GLOB '_slots/*')
+ OR slot-visibility-sql)
+ORDER BY pinned DESC, path ASC
+LIMIT ?3
+```
+
+Core is pinned (any path except the slot branch, which has its own
+predicate), everything under `_rules/`, and visible `_slots/`. Unpinned
+`gotchas/`, `decisions/`, and `procedures/` pages are not in this set
+unless they are pinned. Recent rows are titles only, newest first,
+slot-filtered, whole project.
+
+Isolation: sibling projects never leak
+(`session_brief_pages_selects_core_pages_and_isolates_projects` in
+`crates/ai-memory-store/src/lib.rs`). Slot visibility:
+`SlotVisibility::for_viewer` in `crates/ai-memory-core/src/slots.rs`,
+applied in SQL (`slot_visibility.rs`).
+
+`pages.body` is markdown excluding YAML frontmatter (`NewPage.body`
+in `crates/ai-memory-core/src/page.rs`). Abstracts live in
+`pages.frontmatter_json`. The current SELECT cannot see `abstract:` or
+`summary:`.
+
+Wiki writes auto-pin slots. `Wiki::write_page` does
+`pinned = pinned || is_slot_path(&path)` (`wiki.rs` ~2683) and reindex
+`IndexMetadata` ORs the same (`wiki.rs` ~2995-2999). Production `_slots/`
+rows therefore sit in the `ORDER BY pinned DESC` prefix. Unpinned slots
+exist in store-only fixtures (`sample_page` in
+`session_brief_pages_selects_core_pages_and_isolates_projects` does not
+go through that OR). The brief still treats `is_slot_path` as privileged
+so a fixture or a raw upsert cannot lose a slot behind unpinned
+`_rules/` L1/L2. Production SessionStart does not omit a slot behind
+`_rules/` L0s unless 24 pinned pages already fill
+`BRIEF_CORE_PAGES_LIMIT` (the pre-existing fetch cap).
+
+### Extractive L0/L1 already in three places
+
+They do not agree on clip size or prose granularity.
+
+| Site | Order | Prose fallback | Clip |
+|---|---|---|---|
+| Profile digest `ProfileEntry::from_page` (`profile.rs` ~452-475) | `summary` then `abstract` then first prose **line** (then title) | `first_prose_line`: skips headings, `---`, ADR metadata fields | 240 **bytes**, no ellipsis (`ENTRY_STATEMENT_MAX_BYTES`) |
+| A2 compaction `summary_line` (`crates/ai-memory-consolidate/src/compaction.rs` ~68-91) | `summary` then `abstract` then first non-empty, non-heading **paragraph** | collapse whitespace | `MAX_SUMMARY_LEN = 500` bytes, ellipsis |
+| V61 / wiki `frontmatter_abstract` (`wiki.rs` ~3099, duplicated in `embed.rs`) | `abstract` only | none | store cap `MAX_PAGE_ABSTRACT_LEN = 1024` (`page.rs` ~166) |
+
+A2 compact (`build_compacted_markdown`): keeps the L0 `abstract:`
+frontmatter untouched, writes an L1 summary line at the top of the new
+body, mines regex keep-tokens as L2 identifiers, drops trailing prose,
+sets `compacted: true`. V65 `pages.compacted_at` is derived at the
+upsert choke point (`ops.rs` ~1719-1729) from that frontmatter mirror.
+Opt-in via `[decay] compact_cold_episodic` (default false). Reversible
+through supersession / `restore-page`.
+
+Reuse the profile order for L1 and the A2 500-byte paragraph clip as
+the brief's L1 budget. OpenViking's L1 overview of 4000 characters is
+this project's entire default brief, so it is too large for a per-page
+L1 here.
+
+### Marker and once-per-session gate
+
+`.ai-memory.toml`:
+
+```toml
+[briefing]
+inject_on_session_start = true
+max_chars = 4000
+```
+
+Opt-in, off when absent (`HandoffQuery.briefing`, forwarded by
+`marker_query_suffix_impl_from_selection` in
+`crates/ai-memory-cli/src/commands/hook_capture.rs` ~650-720). Truthiness
+and the clamp are server-side. `inject_on_session_start` and `max_chars`
+are already in the marker boundary key list (`marker.rs`
+`declares_more_than_capture`).
+
+Once-per-session is a client gate: Claude-class SessionStart injects
+once; Kimi (SessionStart stdout discarded) sends `&briefing=` only on
+the first user-prompt (`hook.rs` ~1072-1130, `briefed/<key>` sentinel).
+The server recomposes whenever the flag is truthy. `/clear` re-briefs on
+Claude; Kimi v1 does not; this design does not change that.
+
+### Other surfaces that look like L0/L2
+
+- `memory_query` snippets: FTS5 `snippet(..., 24)` (~24 words). Landscape
+ called this L0. That snippet is a search-hit window around matched
+ terms. The page abstract lives in frontmatter.
+- `memory_read_page`: full body (L2), optional `include_related`.
+- `memory_briefing`: structured JSON snapshot (counts, `rules`/`slots`/
+ `recent` titles, opt-in `pinned` list of 10, opt-in `settled_first`).
+ Empty `pinned` omitted; `settled_first` default off. Different code
+ path from `render_session_brief`. Keep its JSON shape unchanged in v1.
+- `memory_explore`: LLM prose over that snapshot; degrades to JSON with
+ no provider. Do not put the SessionStart brief on this path.
+- MCP tools: frozen at 23 (`MCP_TOOL_NAMES` in
+ `crates/ai-memory-mcp/src/server.rs` ~7940). Footer already tells the
+ agent to call `memory_query` for detail.
+
+### What R7 already spent
+
+A2 persisted the L0/L1/L2 *shape* for cold episodic pages. V61
+`page_abstract_embeddings` plus `[retrieval] abstract_vectors` (default
+off) is a retrieval-ranking stream over `abstract:` text. Neither is a
+SessionStart brief. Abstract embeddings are not required for this work.
+
+Latest migration on disk is V76. A new table would be V77 and
+backup-gated. This design adds none.
+
+---
+
+## Invariants this design must hold
+
+Restated from `AGENTS.md` because they bound the packing:
+
+1. **One config-read path (#1).** Marker `[briefing]` is forwarded on the
+ request. Server clamps with the existing constants. No new env re-read
+ inside the renderer.
+2. **Hooks bounded (#5).** `POST /hook` stays fire-and-forget (≤200 ms
+ script timeout, 202/429). The brief is compiled on `GET /handoff`,
+ which is already a synchronous SessionStart read (1s shell / 3s
+ native). Keep it cheap: no LLM, no extra network, no VLM, no new
+ SQL table, same 24-body fetch. Extraction is string ops on memory the
+ fetch already returns.
+3. **Sanitizer is the only ingress (#6).** Brief output is untrusted
+ historical data. The security notice, both fence markers, the escape
+ pass, and the footer stay budget-non-negotiable. Retrieved memory is
+ never instructions.
+4. **Zero-LLM default (#13).** Capture, search, and this brief work with
+ no provider. Extractive L0/L1 only.
+5. **Pages shared, batons owned (#16).** The brief does not filter pages
+ by `author_id`. Slot visibility stays the existing
+ `SlotVisibility::for_viewer` SQL predicate.
+6. **MCP tool count frozen at 23.** No `memory_brief_expand`. Footer
+ already points at follow-up tools.
+7. **Wiki mutations stay on `Wiki::write_page` / `apply_batch`.** This
+ design does not write wiki files. It only reads latest rows.
+
+---
+
+## Goals and non-goals
+
+### Goals
+
+- More standing pages in the same `max_chars`, fewer omitted `_rules/`
+ and pinned pages, still zero-LLM.
+- Lead with per-page L0 (and L1 where it fits); expand to L2 bodies only
+ while budget remains, with a defined privileged set that gets depth
+ first.
+- One extractive helper so the brief, the profile digest's frontmatter
+ order, and A2's L1 clip stay consistent.
+- Directory-index *presentation* for crowded unprivileged families,
+ renderer-only.
+- Rollback by reverting the renderer. No data migration.
+
+### Non-goals
+
+- A new MCP tool, or any change that moves `MCP_TOOL_NAMES.len()` off 23.
+- `memory_query detail=` / `path_prefix=` SQL LIKE (OpenViking TrieHI
+ half of R7). Follow-up after this lands. The last section of this
+ design is a pointer, with no query schema.
+- Generating L0/L1 with an LLM or VLM sidecar.
+- Vendoring OpenViking or Letta code; `viking://` URIs; TrieHI; a VLM.
+- Changing `memory_briefing` JSON in v1 (empty `pinned` omitted,
+ `settled_first` default off).
+- memU procedure-evolve, Hindsight `is_stale` / delta, Graphiti
+ window-close.
+- Raising `MAX_PAGE_ABSTRACT_LEN` (1024) or `BRIEF_CORE_PAGES_LIMIT`
+ (24).
+- A new on-disk `MEMORY.md` / `.abstract.md` / `.overview.md` convention.
+- Expanding the core fetch to unpinned `gotchas/` / `decisions/` /
+ `procedures/` in v1.
+- Version bump / release tag.
+
+---
+
+## Key Decisions
+
+1. **L0/L1 extractive source and clips.** L0: frontmatter `abstract:` if
+ nonempty, else `summary:` if nonempty, else first prose paragraph,
+ clipped to **256 UTF-8 bytes** with `truncate_utf8_bytes` (ellipsis
+ inside the cap). L1: `summary:` then `abstract:` then first prose
+ paragraph, clipped to **500 UTF-8 bytes**, matching A2
+ `MAX_SUMMARY_LEN`. Do not raise `MAX_PAGE_ABSTRACT_LEN`. Brief-side
+ clip only. L2: current `pages.body` (already frontmatter-stripped).
+ Rationale: OpenViking L0 is the abstract; the operator `summary:` is
+ the natural fallback when `abstract:` is missing. Putting the first
+ paragraph ahead of `summary:` would make L0 worse than L1 on pages
+ the operator already summarized. Our stored abstract may be 1024,
+ which would spend the whole default brief on four pages. OpenViking
+ L1 of 4000 is our entire default budget. A short summary used for
+ both L0 and L1 is a zero-delta upgrade (no-op).
+
+2. **Privileged for L2 promotion.** A page is privileged when
+ `pinned == true` or `is_slot_path(path)` (`_slots/…`). Unpinned
+ `_rules/` pages are coverage-first: they all get L0 before anyone
+ other than the privileged set takes L1/L2. Rationale: pin is the
+ operator's depth signal; slots are standing hot-context by
+ construction (and wiki writes auto-pin them). Unpinned `_rules/` are
+ the pages that starve each other today. `is_slot_path` stays in the
+ predicate as defence in depth for store-only fixtures.
+
+3. **Directory indexes are render-only compression.** No new wiki file.
+ Assignment costs **standalone** `## {title} (`{path}`)` headings plus
+ tier text. After all five assignment steps, if ≥4 unprivileged
+ included pages in the same first path segment of `{_rules, gotchas,
+ decisions, procedures}` remain at L0, render them as one compact
+ `path + L0` list. Do not re-promote from those savings (no fixpoint).
+ Leftover bytes go to the omitted helper, then recent. In v1 the only
+ crowded family that actually appears unprivileged is `_rules/`.
+ Privileged and L1/L2 siblings keep their own headings at their
+ store-order positions.
+
+4. **`BriefPageBody` grows the raw materials the helper needs.** Add
+ `frontmatter_json: serde_json::Value` and `compacted: bool`
+ (`compacted_at IS NOT NULL`). The renderer calls a core helper. The
+ store stays a fetch. Rationale: extraction has to live in one place;
+ `ai-memory-store` should not own clip policy.
+
+5. **Tiering is on whenever briefing is on.** No `[briefing] tiered`
+ flag. Briefing is already the opt-in for spending tokens on every
+ session start. Small wikis still get full bodies: privileged L2
+ promotion fills the budget when few pages compete. Pin and
+ `max_chars` remain the depth knobs. The marker-file and cookbook
+ sentences that today promise L2-first ship in the same commit as the
+ packer (see commit 4).
+
+6. **No new MCP tool.** Extend `BRIEF_AGENT_FOOTER` to name
+ `memory_read_page` beside `memory_query`. Point omitted headers at
+ `memory_read_page` (the caller already has the path). Keep
+ `memory_query` on the recent/search chrome. Follow-up cues stay in
+ trusted chrome (preamble, notice, footer, omitted/recent headers).
+ Directory-index headings carry no tool instruction. Tool count stays
+ 23.
+
+7. **No schema migration.** Frontmatter plus body already hold the text.
+ V61 embeddings are for ranking. A2 already persisted compacted bodies
+ in git. Latest migration is V76; we do not need V77.
+
+8. **Semver: minor (3.1).** CHANGELOG `### Changed` (the opted-in
+ brief packs differently). The work targets the next minor's
+ `release/3.1` once it exists; until then the PR is opened against
+ `main` for the maintainer to retarget.
+
+9. **Omitted standing-rule pointers stay reserved after the L0 pass.**
+ Today's renderer gives omitted first call because a crowded-out
+ `_rules/` page is a standing rule the agent did not receive. L0-first
+ still omits a suffix at max clip (heading plus 256-byte L0 is
+ ~330-360 bytes; a 4000-byte brief holds on the order of 8-9 max-size
+ L0s of 24 fetched pages). After the L0 pass, reserve the omitted
+ section for that suffix, at least the count-only line, before any
+ L1/L2 promotion. Promotions must not eat the omitted section down to
+ nothing. Named formulas (`recent_cap`, `count_only_floor`,
+ `remaining`, walk-back that recomputes each step) live in §3.
+
+10. **Title-only pages render as a path line.** Empty body and empty
+ frontmatter: a single `- `{path}`` line, the same grammar as the
+ omitted list. Cost that line. Reject a blank `##` heading. The page
+ counts as already at max depth, so it does not block L2 of siblings.
+
+---
+
+## Proposed design
+
+### 1. Extractive helper in `ai-memory-core`
+
+New module `crates/ai-memory-core/src/excerpt.rs`, IO-free, exported
+from `lib.rs`. Same frontmatter keys and prose skip list as the profile
+digest, with brief-specific clips.
+
+```rust
+pub const BRIEF_L0_MAX_BYTES: usize = 256;
+pub const BRIEF_L1_MAX_BYTES: usize = 500; // A2 MAX_SUMMARY_LEN
+
+pub struct PageExcerpt {
+ pub l0: Option<String>,
+ pub l1: Option<String>,
+}
+
+pub fn excerpt_from_page(
+ frontmatter: &serde_json::Value,
+ body: &str,
+) -> PageExcerpt { /* … */ }
+
+pub fn first_prose_paragraph(body: &str) -> Option<String> { /* … */ }
+
+pub fn frontmatter_nonempty<'a>(
+ frontmatter: &'a serde_json::Value,
+ key: &str,
+) -> Option<&'a str> { /* trim, reject empty */ }
+```
+
+**L0:** `abstract` if nonempty, else `summary` if nonempty, else
+`first_prose_paragraph(body)`. Clip with `truncate_utf8_bytes(..., 256)`.
+
+**L1:** `summary` if nonempty, else `abstract` if nonempty, else
+`first_prose_paragraph(body)`. Clip with `truncate_utf8_bytes(..., 500)`.
+
+`first_prose_paragraph` walks every `\n\n` block, like A2 `summary_line`
+(`compaction.rs` ~79-89). Inside a block it skips *leading* lines that
+are `#` headings, a lone `---`, or `is_metadata_field` (already `pub` in
+`profile.rs`; call it, do not relocate `ADR_METADATA_LABELS`). Collapse
+the remainder the way A2 already does (`split_whitespace` joined by
+spaces). If that remainder is empty, **continue to the next block**.
+The first nonempty remainder is the excerpt: `# Title\n\nUse nextest.`
+yields `Use nextest.`
+
+Also skip a block whose trimmed text starts with
+`_Extractively compacted from a cold episodic page` (the A2 footer
+prefix) and continue. Do not import `COMPACTION_FOOTER` into
+`ai-memory-core`. A compacted body that is only that footer then has no
+prose and falls through to title-only.
+
+Required walker tests (all with empty frontmatter so L0/L1 come from
+the body):
+
+- `# Title\n\nUse nextest.` → L0 and L1 are `Use nextest.`
+- The ADR template in `profile.rs` ~1066-1072 (`# Title`, status field
+ with the HTML comment, `## Context`, then `Readers blocked the writer
+ under load.`) → L0/L1 are `Readers blocked the writer under load.`
+- No-blank-line ADR: `**Status:** Accepted` and the decision sentence
+ in one `\n\n` block → L0/L1 are the decision.
+
+Empty abstract/summary must not produce a blank `Some("")`. Whitespace-
+only is absent.
+
+**Do not change profile digest output in the helper PR.**
+`ProfileEntry::from_page` may call `frontmatter_nonempty` for the
+`summary` then `abstract` lookup and keep `first_prose_line` plus the
+240-byte clip. The digest is a one-line statement; the brief is a
+paragraph. Sharing the key order is the contract. Switching the digest
+to paragraphs would change every profile SessionStart and is out of
+scope.
+
+**A2 compaction** may switch `summary_line` to `excerpt_from_page().l1`
+in a later PR if the suite stays green. Do not block the brief on that
+migration. A2 already matches L1 order and the 500-byte clip. The
+brief walker also skips ADR metadata lines and continues when a
+block's remainder is empty.
+
+**Compacted pages.** `excerpt_from_page` takes only frontmatter and
+body. It does not read `BriefPageBody.compacted`. Packing must not
+require that flag for nonempty L0/L1. A2 left `abstract:` in
+frontmatter and put the L1 line at the top of the body, then
+keep-tokens, then `COMPACTION_FOOTER`. Typical result: L0 from abstract
+(or summary, or the L1 line clipped to 256), L1 from
+summary/abstract/first paragraph (the A2 line), L2 the whole compacted
+body including keep-tokens. Promoting to L2 is how keep-tokens reach
+the agent. Never treat `compacted == true` as "skip extraction" (that
+is how a page becomes an empty section). The flag is a hint that L2
+is still useful when the body is already short.
+
+If L0 and L1 would be identical strings, both fields may hold that
+string; the packer treats a zero-delta upgrade as a no-op. Same for L1
+versus L2 when the body is already ≤500 bytes (short rules, compacted
+pages with no keep-token tail).
+
+### 2. Store fetch
+
+Extend the core SELECT:
+
+```sql
+SELECT path, title, body, pinned, updated_at, frontmatter_json, compacted_at
+```
+
+Map `compacted_at IS NOT NULL` to `BriefPageBody.compacted`. Parse
+`frontmatter_json` to `serde_json::Value`; on parse failure use `{}` and
+still return the row so one bad page cannot fail SessionStart.
+
+Keep limits, order, expiry, slot SQL, and project isolation. Limits stay
+24 / 10. Do not fetch `page_abstract_embeddings`.
+
+`BriefPageBody` remains in-process (the `Serialize` derive is unused on
+the wire). Adding fields does not change `memory_briefing` JSON
+(`BriefingPage` / `BriefingSnapshot` are the snapshot types).
+
+commit 3 lands the fields and the SELECT while the renderer still reads only
+`path`, `title`, `body`, `pinned`. Existing brief tests stay
+byte-identical until commit 4.
+
+### 3. Packing algorithm
+
+Replace the stream-into-buf L2 loop. Assign a tier per core page, then
+render once.
+
+Tiers: `Omitted | TitleOnly | L0 | L1 | L2`.
+
+**Cost model (authoritative).** Assignment costs **standalone** headings
+plus tier text against the budget. Each included L0/L1/L2 page is costed
+as:
+
+```text
+\n## {title}{pin} (`{path}`)\n{tier text}\n
+```
+
+Title-only pages cost a single `- `{path}`` line. The directory index
+is not in this cost model. `rendered_len` used during assignment
+therefore over-approximates when an index will later compress a family:
+it never assumes an index, so a later render cannot exceed the budget
+because a promotion dissolved a group. Index savings are leftover bytes
+and are not spent on further promotions (no fixpoint). After
+assignment, leftover goes to `render_brief_omitted_section`, then
+`render_brief_recent_section`.
+
+Fence escape remains the one unpredictable growth; the existing
+post-escape clamp handles it. `rendered_len` is pre-escape.
+
+**Reserves.** Named quantities, computed from the existing helpers.
+
+```text
+prefix_len = BRIEF_PREAMBLE_TITLE.len()
+ + BRIEF_PREAMBLE_BOUNDARY.len()
+ + UNTRUSTED_MEMORY_NOTICE.len()
+ + "\n\n".len()
+ + UNTRUSTED_HISTORY_START.len()
+ + 1
+ // 475 at dbe928e3; equals brief_scaffold_len() - brief_tail_len()
+
+content_ceiling = budget.saturating_sub(brief_tail_len())
+variable_region = content_ceiling.saturating_sub(prefix_len)
+
+recent_full = render_brief_recent_section(recent, usize::MAX).len()
+recent_cap = min(recent_full, variable_region / 4)
+
+count_only_line(n) = format!(
+ "\n**{n} core page(s) omitted by budget** (read via `memory_read_page`)\n"
+)
+count_only_floor = count_only_line(24).len()
+ // 69 bytes after the header swap. 2-digit n because the
+ // L0 pass does not yet know suffix length (n=1..=9 is 68).
+ // 0 when core is empty.
+
+l0_spent = prefix_len + sum of standalone costs of assigned pages
+remaining = content_ceiling.saturating_sub(l0_spent)
+full_omitted = render_brief_omitted_section(suffix, usize::MAX).len()
+
+omitted_reserve =
+ 0 if suffix is empty
+ min(full_omitted, remaining / 4)
+ .max(count_only_line(suffix.len()).len())
+ .min(remaining) otherwise
+
+recent_reserve = min(recent_full, remaining.saturating_sub(omitted_reserve) / 4)
+```
+
+Closing fence + footer stay first (`content_ceiling`). `recent_cap` is
+the L0-pass hold-back (full variable region / 4). `recent_reserve` is
+the post-L0 value (leftover after the omitted floor / 4). L1/L2
+promotions compete only against
+`content_ceiling - omitted_reserve - recent_reserve - l0_spent`.
+
+At render, omitted is given leftover first (it may grow from count-only
+to a path list if promotions left room), then recent. That keeps
+today's "omitted has first call" policy after coverage.
+
+**Assignment, in order.**
+
+1. **L0 coverage.** Walk `core` in store order (`pinned DESC, path ASC`).
+ For each page, compute L0 text. If `l0` is `None`, the candidate is
+ a TitleOnly path line. Greedy-fit against
+ `l0_ceiling = content_ceiling - recent_cap - count_only_floor`
+ (a candidate fits when `l0_spent + cost(candidate) <= l0_ceiling`).
+ If the candidate does not fit, stop. Every later page is `Omitted`.
+ The omitted set remains a well-defined **suffix of `core`**, now at
+ L0 granularity.
+
+ Then compute `remaining`, `omitted_reserve`, and `recent_reserve`
+ from the formulas above. If the suffix is empty, `omitted_reserve`
+ is 0 and the unused `count_only_floor` sits in `remaining` for
+ promotions.
+
+ **Walk-back.** While the suffix is nonempty and
+ `l0_spent + omitted_reserve + recent_reserve > content_ceiling`,
+ move **only the last assigned page** onto the omitted suffix
+ (suffix invariant) and **recompute** `l0_spent`, `remaining`,
+ `omitted_reserve`, and `recent_reserve` from the formulas above
+ (full omitted grows as `l0_spent` shrinks). Stop when
+ `l0_spent + omitted_reserve + recent_reserve <= content_ceiling`
+ or no assigned page remains. A max-size last L0 plus a long omitted
+ path list is the case that needs this.
+2. **Privileged L1.** For included privileged pages, in order: upgrade
+ L0→L1 when `l1` is longer than `l0` and the delta fits in the
+ post-reserve remainder.
+3. **Privileged L2.** For included privileged pages, in order: upgrade
+ to full `body.trim()` only when the *entire* L2 fits. Do not
+ truncate an L2 in this pass. Truncation of one body is what starves
+ later 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
+ at 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.
+
+**No L2 truncation during assignment.** The only remaining cut of page
+text is (a) the L0/L1 clips themselves, (b) the post-escape clamp on the
+untrusted region, identical to today: a silent
+`truncate_at_char_boundary` with **no** notice. Today's
+`BRIEF_TRUNCATED_NOTICE` is emitted only in the in-loop L2 truncation
+path (`router.rs` ~2447-2454). That path goes away, so delete the
+constant in the packer PR (or `#[allow(dead_code)]` only if a same-PR
+cleanup would enlarge the diff). Do not hang the notice on the clamp:
+the clamp must never eat the closing fence, and the current clamp is
+silent. Rewrite `render_session_brief_enforces_budget` so a 2000-byte
+first body at `BRIEF_BUDGET_MIN` is an L0 and later `_rules/` pages
+appear at L0; drop the `[truncated by `[briefing] max_chars`]`
+assertion.
+
+**Empty project.** `core.is_empty() && recent.is_empty()` still returns
+`None` (inject nothing).
+
+Worked example at the default 4000-byte budget, 816-byte scaffold,
+`variable_region` 3184, `count_only_floor` 69, `recent_cap` =
+`min(recent_full, 796)`:
+
+- Today: one 3500-byte `_rules/architecture.md` is truncated;
+ `_rules/testing.md` is omitted.
+- Tiered, short abstracts: 12 `_rules/` pages with 80-byte abstracts
+ fit at L0 (~150 bytes each with heading ≈ 1800 bytes). A pinned
+ `_slots/focus.md` of 400 bytes upgrades to L2. Two pinned ADRs
+ upgrade to L1 (500). Leftover may promote one unpinned rule to L1.
+ Twelve standing pages in context from the same 4000-byte budget.
+- Tiered, max L0: 24 `_rules/` pages with 256-byte L0s. About 8-9 fit
+ as standalone L0; the suffix is omitted. The omitted section still
+ emits at least the count-only line. L1/L2 promotions, if any, run
+ only in bytes above that floor.
+
+At `BRIEF_BUDGET_MIN` (1500, 684 leftover after scaffold; 662 after the
+footer gains `memory_read_page`): a handful of L0s still beat one
+truncated L2. The floor test stays: scaffold plus ≥500 bytes of page
+room.
+
+**Directory-index example (costing vs render).** Five unprivileged
+`_rules/` pages, path order `a.md` … `e.md`. Assignment costs five
+standalone H2+L0 blocks. One (`b.md`) promotes to L1; four stay L0.
+Render walk in store order:
+
+- `a.md` is the first index member of `_rules/` (four L0 siblings):
+ emit the whole `### `_rules/`` group (`a`, `c`, `d`, `e` as
+ `- `{path}`: {l0}`).
+- `b.md` is L1: keep its `##` heading at this store-order position.
+- `c.md` / `d.md` / `e.md`: skip, already in the group.
+
+Index savings are leftover for omitted then recent. Do not promote a
+fifth page from those savings.
+
+### 4. Render shape
+
+Keep the preamble, security notice, fences, and footer. Inside the
+untrusted region:
+
+**Heading for L1/L2 (and for L0 pages that are not in an index):**
+
+```markdown
+## {title}{pin} (`{path}`)
+{tier text}
+```
+
+`{pin}` is ` 📌` when `pinned`, as today. No `L0`/`L1`/`L2` labels in
+the injected text (those names are maintainer vocabulary). The footer
+is the follow-up cue.
+
+**Title-only** (empty body, empty frontmatter, no extractable L0):
+
+```markdown
+- `{path}`
+```
+
+Same bullet grammar as the omitted list. Never `## {title}` with a
+blank following line.
+
+**Directory index** (unprivileged, same family, ≥4 members, all still
+L0, applied after assignment):
+
+```markdown
+### `{family}/`
+- `{path}`: {l0}
+- `{path}`: {l0}
+```
+
+No tool name in this heading. Follow-up lives in the footer, outside
+the untrusted fence. Preamble, notice, omitted/recent headers, and
+footer are trusted chrome; mixing a tool cue into the untrusted region
+next to page abstracts would teach agents to treat that region as
+system text.
+
+Emit the group once, at the position of its first L0 member in store
+order. Skip later L0 members of that group. Privileged and L1/L2
+siblings keep standalone headings at their store-order positions and
+are not listed in the index. Threshold 4: three short rules as
+ordinary L0 headings are readable; a dozen `_rules/` H2s waste heading
+bytes.
+
+**Omitted section.** Same helper, same degradation (full path list →
+partial + remainder → count-only). Paths only. Change both the full
+header (`BRIEF_OMITTED_HEADER`) and the count-only variant from
+`memory_query` to `memory_read_page`: omitted pages are exactly the
+ones whose path is already known. Keep a nonempty omitted section
+whenever the suffix is nonempty and the reserved floor fits (the
+count-only line). Do not degrade to an empty string while that floor
+was reserved. Attaching L0 abstracts to omitted rows would cost the
+same as including them.
+
+**Recent section.** Unchanged header (`memory_query` is the right
+follow-up for "titles you may search").
+
+**Footer.** Change the last clause to:
+
+```text
+call `memory_query` or `memory_read_page` for detail beyond this brief.
+```
+
+`memory_query` remains the search path (L0 snippets). `memory_read_page`
+is the L2 path for a deferred body. Re-measure `brief_scaffold_len` so
+`BRIEF_BUDGET_MIN` still clears the floor with ≥500 bytes of page room.
+The extra 22 bytes leave 662, still ≥500.
+
+**Escape and clamp.** Unchanged: `escape_untrusted_history_tail` from
+`history_start`, then if `buf.len() > content_ceiling` truncate the
+untrusted region on a char boundary, then append the closing fence and
+footer.
+
+```mermaid
+flowchart TD
+ start[GET /handoff briefing=1] --> fetch["session_brief_pages_with_slot_visibility<br/>24 core + 10 recent"]
+ fetch --> excerpt["excerpt_from_page<br/>frontmatter + body"]
+ excerpt --> l0["Assign L0 / TitleOnly prefix of core<br/>suffix = omitted"]
+ l0 --> reserves["omitted_reserve + recent_reserve; walk-back last L0 if overflow"]
+ reserves --> privL1[Upgrade privileged to L1]
+ privL1 --> privL2["Upgrade privileged to full L2<br/>only if entire body fits"]
+ privL2 --> restL1[Upgrade remaining to L1]
+ restL1 --> restL2[Upgrade remaining to L2]
+ restL2 --> render["Render standalone headings<br/>index compresses leftover L0 families<br/>omitted then recent"]
+ render --> fence[Escape fence markers in untrusted region]
+ fence --> clamp[Silent clamp of untrusted region to content_ceiling]
+ clamp --> tail[Append closing fence + footer]
+```
+
+```mermaid
+sequenceDiagram
+ participant Hook as SessionStart hook
+ participant Handoff as GET /handoff
+ participant Store as ReaderPool
+ participant Core as excerpt_from_page
+ participant Out as Agent context
+ Hook->>Handoff: briefing=1, briefing_budget=N
+ Note over Hook,Handoff: 1s shell / 3s native. No LLM.
+ Handoff->>Store: session_brief_pages_with_slot_visibility
+ Store-->>Handoff: BriefPageBody + frontmatter_json + compacted
+ Handoff->>Core: extract L0/L1 per page
+ Core-->>Handoff: PageExcerpt
+ Handoff-->>Out: fenced brief (untrusted historical data)
+ Note over Out: memory_query / memory_read_page for deferred L2
+```
+
+### 5. Default behavior and rollout
+
+Tiering runs for every request that already opted into briefing. No new
+marker key. Operators who want the old "dump L2 until it breaks" shape
+pin the pages that must appear in full and raise `max_chars` (still
+clamped to 20000). That is the same knob they have now; it starts
+working for more pages.
+
+CHANGELOG bucket: `### Changed` under `[Unreleased]`. This is a
+user-visible change to an existing opt-in. Semver: minor, additive
+rendering for the 3.1 line. Patches stay on `main`.
+
+Rollback: revert the renderer (and, if needed, the extra SELECT
+columns). Wiki and SQLite rows are untouched. Compacted A2 pages stay
+valid either way.
+
+Feature flag: none. Briefing itself is the flag.
+
+### 6. Latency and load
+
+- Fetch: one existing read-pool query, 24 bodies plus a JSON column
+ already on the row. No extra round-trip.
+- CPU: extract + pack over ≤24 pages, each body already in memory for
+ L2. Target: well under 50 ms added, so the whole `GET /handoff`
+ (handoff + brief + profile digest) stays inside the 1s shell budget.
+- Storage: zero new bytes on disk.
+- Tokens: default 4000 bytes remains ~1k tokens at the project's ~4
+ chars/token heuristic. Those tokens hold many L0s, with L2 only while
+ the budget remains. Operators who raise `max_chars` still hit the 20k
+ ceiling.
+
+Do not add tracing on the per-page hot path beyond the existing
+SessionStart debug events. A single `tracing::debug!` with
+`included_l0`, `included_l1`, `included_l2`, `omitted` counts is enough
+to diagnose packing without logging page bodies (bodies are untrusted
+and can contain secrets that sanitization already stripped at ingress,
+but the brief should not become a second log of them).
+
+---
+
+## API / interface changes
+
+**Marker.** No new keys. `[briefing] inject_on_session_start` and
+`max_chars` stay the contract. `declares_more_than_capture` does not
+grow.
+
+**HTTP.** `GET /handoff?briefing=&briefing_budget=` unchanged.
+
+**MCP.** 23 tools. `memory_briefing` JSON unchanged. `memory_query` /
+`memory_read_page` schemas unchanged.
+
+**Rust (internal).**
+
+- `ai_memory_core::excerpt::{excerpt_from_page, PageExcerpt, BRIEF_L0_MAX_BYTES, BRIEF_L1_MAX_BYTES}`
+- `BriefPageBody { frontmatter_json, compacted, …existing }`
+- `render_session_brief` signature can stay
+ `(core, recent, budget) -> Option<String>`. It will read the new
+ fields.
+
+**Footer copy.** Additive mention of `memory_read_page`. Omitted headers
+switch to `memory_read_page`. Re-run the scaffold-floor test.
+
+**Prompt surfaces.** `SNIPPET_BODY` / `MEMORY_INSTRUCTIONS` already treat
+briefing as untrusted historical data. They do not describe L2 packing.
+No tool-count assertion changes. Do not touch those strings unless a
+regression test starts requiring the new footer (it should not; the
+footer is hook-injected).
+
+---
+
+## Data model changes
+
+None. No V77. No new column, table, or wiki path.
+
+Read `frontmatter_json` and `compacted_at` that already exist (frontmatter
+since V01-era pages; `compacted_at` since V65).
+
+If a future follow-up wanted stored L0/L1 *columns* to skip shipping
+bodies on the brief fetch, that would be a backup-gated migration with
+a documented reason that frontmatter is insufficient. It is insufficient
+only for a performance optimization we do not need at 24 rows.
+
+---
+
+## Alternatives considered
+
+### A. Keep dumping L2 bodies; raise `max_chars`
+
+Cheap to document, expensive every session. The default 4000 exists
+because the brief is injected into every opted-in start (comment on
+`BRIEF_BUDGET_MAX`: an unbounded budget would let one marker line burn
+five figures of tokens per `/clear`). Raising the default to fit 24
+full `_rules/` pages would regularly land in the 10k-20k range. The
+OpenViking number is a deferral win: same window, more pages. Rejected
+as the primary fix. Raising `max_chars` remains the operator knob for
+depth *after* coverage-first packing.
+
+### B. Always-L0 brief (no L2 promotion)
+
+Maximizes coverage and is simple. It starves agents of standing rules
+they currently receive in full when the wiki is small (a few short
+`_rules/` pages plus a slot, which *do* fit at 4000 today). Privileged
+L2 promotion preserves that small-wiki behavior while fixing the large-
+wiki starvation. Rejected as the default packing. Unprivileged pages *start* at L0 and
+still promote when budget remains.
+
+### C. LLM-summarize the brief (`memory_explore` already exists)
+
+Violates invariant #13 on the default path. Adds provider latency
+inside a 1s GET. `memory_explore` is the opt-in LLM digest over the
+JSON snapshot, and it already degrades without a provider. SessionStart
+must not call it.
+
+### D. New MCP tool `memory_brief_expand`
+
+Breaks the 23-tool freeze. Duplicates `memory_read_page` (by path) and
+`memory_query` (by search). The footer already names follow-up. Rejected.
+
+### E. Persist compiled L0/L1 sidecar files (OpenViking `.abstract.md` / `.overview.md`)
+
+Duplicates git source of truth. Frontmatter `abstract:` / `summary:`
+plus extractive fallback already are the sidecars, in the page the
+operator edits. A2 compaction rewrites the body in place through the
+wiki layer (supersession). Another file per page would double watcher
+events and confuse hand-edits. Rejected.
+
+### F. New marker flag `[briefing] tiered = true`
+
+Preserves today's L2-first packing for existing opt-ins at the cost of
+shipping coverage-first packing off by default. Almost no one would
+turn it on. Briefing is already the consent to spend tokens at session
+start. Small wikis still L2-fit via privileged promotion. Rejected for
+v1 (listed under Open questions as confirm-or-override).
+
+### G. Expand core fetch to unpinned `gotchas/` / `decisions/` / `procedures/`
+
+Tempting once L0 is cheap. It changes *which* pages the brief considers
+as well as how they pack, and it competes with the 24-row cap. Pinned
+pages in those families already appear and are privileged. Leave
+expansion as a follow-up after omitted-rate evidence.
+
+---
+
+## Security and privacy
+
+**Threat model (unchanged).** Wiki pages and hook-captured text are
+untrusted historical data. A malicious page can try to close the
+untrusted fence, inject instructions, or crowd the brief so a standing
+rule disappears.
+
+**Mitigations this design keeps.**
+
+- `UNTRUSTED_MEMORY_NOTICE` precedes the fence
+ (`ai_memory_core::UNTRUSTED_MEMORY_NOTICE`).
+- Untrusted region is wrapped in
+ `<!-- ai-memory:untrusted-history:start/end -->`.
+- Fence marker strings inside bodies are escaped before the closing
+ fence is written; tests already assert a single real pair of markers
+ (`router.rs` ~6464).
+- Footer sits *after* the closing fence, so a page cannot overwrite the
+ instruction to verify against the checkout and to treat the brief as
+ context.
+- Clamp after escape, never by dropping the scaffold.
+- Sanitizer remains the only path *into* the store. This work only
+ reads latest pages.
+
+**New residual risk.** Coverage-first packing shows *more* untrusted
+pages per session (abstracts of many `_rules/`, with full bodies only
+while budget remains). That is more surface for prompt injection, with
+less surrounding prose for a human skimming the brief. Severity: medium.
+Mitigation: the fence and notice still wrap the whole untrusted region;
+abstracts are short; the footer still requires verification against
+canonical instructions. A denser brief stays untrusted historical data.
+
+**Auth.** Same `authorize_resolved(..., ProjectAccess::Read)` already
+on `GET /handoff`. No new route.
+
+**Slot privacy.** `per_user` slots stay SQL-filtered. Do not re-filter
+in the renderer.
+
+**Do not log page bodies** in the new debug counters.
+
+`docs/security-boundaries.md`: no new isolation dimension. Extend the
+existing brief budget/fence tests (they are the tests that bite if the
+scaffold is dropped). No inventory row change unless an implementation
+PR weakens the fence (it must not).
+
+---
+
+## Observability
+
+- One `debug` event on a rendered brief: budget, used bytes, counts per
+ tier, omitted count, whether a directory index was emitted. No paths
+ required; path-level trace belongs in tests.
+- Existing SessionStart warn paths (scope, slot, profile) stay.
+- No metric cardinality by page path. If a future counter is added, it
+ is server-wide: `session_brief_render_bytes`, `session_brief_omitted`.
+ Not required for v1.
+- Alerting: none. A packing bug shows up as omitted standing rules,
+ which the omitted section already reports to the agent.
+
+---
+
+## Rollout plan
+
+1. Land this design (commit 1, docs only, no CHANGELOG).
+2. Helper (commit 2) and store fields (commit 3) with no hook behavior change.
+3. Renderer plus merge-gate docs (commit 4): packing flip, CHANGELOG
+ `### Changed`, and every user-facing briefing sentence
+ (`docs/marker-file.md`, `docs/cookbook.md` / `docs/usage.md`, a
+ SessionStart-brief subsection in `docs/ARCHITECTURE.md`). AGENTS.md requires those in the same commit as the
+ behavior change.
+4. Landscape R7 sentence, `docs/competitive-parity.md`, and
+ `docs/comparison.md` (commit 5) follow. They are competitor-research
+ bookkeeping, not the merge-gate contract for the opted-in brief.
+
+No staged percentage rollout (single-binary, per-repo opt-in). Rollback
+is git revert of the renderer. No backup step (no migration).
+
+After merge, a maintainer smoke: a fixture wiki with one 8k `_rules/`
+page plus ten short `_rules/` pages plus a slot, `inject_on_session_start
+= true`, `max_chars = 4000`. Expect the ten shorts at L0 (or a `_rules/`
+index), the slot at L1/L2, and the 8k page at L0/L1, with the shorts
+still present.
+
+---
+
+## Tests the implementation PRs must add
+
+Hook renderer (`crates/ai-memory-hooks/src/router.rs` tests, next to the
+existing three):
+
+- Budget never exceeded: extend
+ `render_session_brief_never_exceeds_budget` with mixed L0/L1/L2
+ assignments, a directory index, and fence-bearing bodies. Still
+ `out.len() <= budget`, still valid UTF-8, still both fence markers and
+ the notice.
+- Scaffold still non-negotiable versus `BRIEF_BUDGET_MIN` after the
+ footer gains `memory_read_page`. Re-measure from `brief_scaffold_len()`.
+- A long L2 body no longer starves later `_rules/` pages: they appear at
+ least as L0 (heading or directory-index line) and their path is not
+ only in the omitted list. Drop the `[truncated by `[briefing]
+ max_chars`]` assertion; that notice goes away with in-loop L2
+ truncation.
+- 24 max-size L0 `_rules/` pages at `BRIEF_BUDGET_DEFAULT` still emit
+ at least the count-only omitted line, and still fit the budget.
+ Walk-back, when it runs, recomputes `omitted_reserve` from the new
+ suffix after each move (stale reserve is a bug).
+- Extractive fallbacks: abstract present (L0 uses it even when summary
+ exists); summary present and abstract absent (L0 and L1 both use
+ summary; zero-delta if it is ≤256 bytes); neither (first paragraph);
+ empty / whitespace abstract and summary do not inject blank sections.
+- Compacted A2 body (L1 line + keep-tokens + footer, `compacted: true`)
+ still yields nonempty L0/L1 and, when promoted to L2, still contains
+ the keep-token section. A compacted body that is only the A2 footer
+ (no summary, no keep-tokens, no abstract) is title-only, not that
+ footer as L0. Nonempty L0/L1 must not require the `compacted` flag.
+- Fence-escape still lengthens untrusted text and still clamps. Include
+ a fence marker in `abstract:` / `frontmatter_json`, not only in
+ `body`: L0 text is what long pages actually inject.
+- Title-only page (empty body, empty frontmatter) emits `- `{path}``
+ (or is omitted). Never a blank `##` section.
+- Directory index: ≥4 unprivileged `_rules/` at L0 render as one
+ `### `_rules/`` list with no tool name in the heading; a pinned
+ `_rules/` sibling keeps its H2 and is absent from that list. Three
+ unprivileged `_rules/` stay ordinary L0 headings. Five unprivileged
+ `_rules/` of which one promoted to L1: index of the four L0s plus one
+ H2 at the L1 page's store-order position; leftover index savings do
+ not fund another promotion.
+- Privileged promotion: a pinned page and a `_slots/` page upgrade
+ toward L2 before an unpinned `_rules/` page does. Keep a synthetic
+ unpinned-slot fixture (`pinned: false`, `is_slot_path`) so the
+ predicate is tested; do not claim production SessionStart will omit a
+ wiki-written slot behind `_rules/` L0s (wiki auto-pins slots).
+- Zero-delta upgrade: a 40-byte body is a single section of full text.
+ Title-only and zero-delta pages do not block L2 of siblings.
+- UTF-8: 4-byte emoji bodies still cut on a char boundary (existing
+ assertion).
+- Empty project still `None`.
+
+Store (`session_brief_pages_*`):
+
+- `frontmatter_json` round-trip (abstract/summary present).
+- `compacted` true when `compacted_at` is set, false otherwise.
+- Slot visibility and cross-project isolation unchanged
+ (`slot_visibility.rs`, `session_brief_pages_selects_core_pages_and_isolates_projects`).
+- Malformed `frontmatter_json` yields `{}` and does not fail the fetch.
+
+Core helper (`excerpt.rs` unit tests):
+
+- Table-driven L0/L1 order and clips (256 / 500), ellipsis, char
+ boundary, empty keys, heading skip, ADR metadata skip, whitespace
+ collapse.
+- `# Title\n\nUse nextest.` with empty frontmatter: L0 and L1 are
+ `Use nextest.` (continue past a heading-only first block).
+- ADR template from `profile.rs` ~1066-1072 (`# Title`, status field
+ with HTML comment, `## Context`, then the load sentence): L0/L1 are
+ `Readers blocked the writer under load.`
+- No-blank-line ADR: `**Status:** Accepted` and the decision sentence
+ in one paragraph; L0/L1 are the decision.
+- Footer-only compacted body: skip the A2 footer prefix, yield no
+ prose (title-only at the packer).
+- Does not raise or depend on changing `MAX_PAGE_ABSTRACT_LEN`.
+
+Client / MCP:
+
+- Once-per-session gate unchanged (existing Kimi/Claude tests; do not
+ drop `&briefing=` after the first delivery).
+- `MCP_TOOL_NAMES.len() == 23` still holds. No new name.
+
+Do not add a security-boundaries row. Do extend the fence/budget tests
+that already guard that row's "brief is untrusted" claim.
+
+---
+
+## Docs to update in implementation PRs
+
+Same change as the renderer, per AGENTS.md:
+
+Merge-gate docs, **same commit as the packer** (commit 4):
+
+- `CHANGELOG.md` `[Unreleased]` → `### Changed`, past tense, `(#NNN)`.
+- `docs/ARCHITECTURE.md`: add a short SessionStart-brief subsection
+ (opt-in, extractive L0/L1 then L2 promotion, fences non-negotiable).
+ Line ~204 is the **profile digest** paragraph ("after the project
+ brief"); do not retarget that. Passing mentions (for example ~139)
+ can stay as they are if they only say briefs are fenced.
+- `docs/marker-file.md` `[briefing]` comment block (around 139-165): it
+ currently says "Page bodies are served first". Update to coverage-first
+ L0/L1 then L2 promotion. Keep clamp numbers.
+- `docs/usage.md` / `docs/cookbook.md`: the recipe "if the project's
+ `.ai-memory.toml` opts into the on-start brief, rules are prepended"
+ (`cookbook.md` ~51) should say abstracts of standing pages are
+ prepended, with full bodies when they fit, and `memory_read_page` for
+ the rest. Pin a rule to keep it privileged.
+- `docs/agent-messaging.md` on-start hot-context sentence (~168):
+ "compiled project brief of pinned / `_rules/` / `_slots/` pages"
+ still true; add that bodies are tiered.
+
+Follow-up, not merge-gate (commit 5):
+
+- `docs/research-2026-landscape.md` R7 remaining-work sentence (around
+ 607-615): the tiered on-start brief is no longer "still a design doc
+ before code" once commit 4 merges. Leave TrieHI / `path_prefix` as the
+ remaining half.
+- `docs/competitive-parity.md` borrowed-ideas table: add a row for
+ progressive-disclosure on-start brief (OpenViking L0/L1/L2 + Letta
+ MemFS directory deferral), verdict along the lines of **BETTER on the
+ default path** (zero-LLM, file-first, reversible A2 substrate, no
+ AGPL vendor). `docs/comparison.md` "From Hindsight / OpenViking"
+ paragraph currently maps L0/L1/L2 only onto extractive *tier-down*;
+ extend it to the on-start brief once shipped.
+
+This design file is the design-doc-before-code. Implementation must not
+precede commit 1.
+
+New and rewritten prose in those docs goes through the humanizer skill.
+Released CHANGELOG sections stay frozen.
+
+---
+
+## Risks
+
+| Risk | Severity | Mitigation |
+|---|---|---|
+| Agents that relied on a full first `_rules/` page now see its L0/L1 | Medium | Pin that page (privileged L2). Raise `max_chars`. Footer names `memory_read_page`. Small wikis still L2-fit. |
+| L0 of 256 × 24 plus headings still omits a tail at 4000 bytes | Medium | Expected as coverage math. After the L0 pass, reserve at least the count-only omitted line so those standing rules still appear as a count. Test at `BRIEF_BUDGET_DEFAULT` with 24 max-size L0s. Typical abstracts are <120 bytes (~15-20 pages). Raising the 24-row fetch limit is a follow-up. |
+| Denser brief = more injection surface | Medium | Fence, notice, footer, escape, clamp unchanged. Abstracts are short. |
+| Extractive first paragraph is a useless heading-like sentence | Low | Skip `#` headings and ADR metadata. Operators can set `abstract:`. |
+| A2 compacted page double-summarized to empty | High if shipped | Explicit test; `compacted` is a hint for L2 usefulness (keep-tokens), never a skip. |
+| Footer growth breaks `BRIEF_BUDGET_MIN` | Low | Scaffold is 816 bytes today, leftover 684; +22 for `memory_read_page` leaves 662, still ≥500. Re-measure from `brief_scaffold_len()` in commit 4. |
+| `BriefPageBody` struct-literal tests fail to compile | Low | commit 3 updates every literal (hooks tests around 6465 and 16216+). |
+| GET /handoff exceeds 1s | Low | Same 24-body fetch as today; extraction is microseconds. No LLM. |
+| Profile digest accidentally changes | Medium | commit 2 must not switch it to paragraphs; share keys only. Snapshot tests in `profile.rs` (`entry_from_page_prefers_summary_then_first_prose_line`). |
+
+---
+
+## Follow-up after this lands (not specified here)
+
+**Directory-scoped `memory_query`.** OpenViking's TrieHI half of R7: a
+bounded `path_prefix` (and maybe a `detail=l0|l1|l2`) filter on
+`memory_query` inside one project. Useful once the brief teaches agents
+that `_rules/` is an index they can query. It needs its own design: SQL
+`GLOB` versus FTS, interaction with `scopes` / `global=true`, and
+whether `detail` would be the first MCP schema addition of 3.1. Do not
+start it in the brief PRs.
+
+Possible later brief tweaks, each a separate decision: raise
+`BRIEF_CORE_PAGES_LIMIT` above 24; include unpinned `gotchas/` /
+`decisions/` / `procedures/` at L0-only; let A2 call `excerpt_from_page`
+for `summary_line`.
+
+---
+
+## Open questions
+
+Operator confirmed all four recommended defaults on 2026-10-13.
+
+1. **Tiering on whenever briefing is on** (recommended), versus a new
+ `[briefing] tiered = true` defaulting off. Override only if existing
+ opt-in repos must keep L2-until-break packing until they flip a key.
+ Marker-file and cookbook L2-first sentences ship in the same commit
+ as the packer either way.
+ **Resolved 2026-10-13:** tiering is on whenever briefing is on. No
+ `[briefing] tiered` flag.
+2. **Unpinned `_rules/` are coverage-first** (recommended): they get L0
+ for everyone, then L1, then L2 only after privileged pages have had
+ their chance at depth. Override if standing rules must still dump
+ full bodies before slots do. (Pinned rules are already privileged.)
+ **Resolved 2026-10-13:** unpinned `_rules/` are coverage-first.
+ Privileged = pinned or `_slots/`.
+3. **L1 clip 500 bytes, matching A2** (recommended), versus 400 or 800.
+ 800 fits fewer promotions at default 4000; 400 is harsher than the
+ compaction pass we already ship.
+ **Resolved 2026-10-13:** L1 clip is 500 UTF-8 bytes (A2
+ `MAX_SUMMARY_LEN`).
+4. **Directory-index threshold 4** (recommended). Override with 3 or 6
+ if the first smoke looks noisy.
+ **Resolved 2026-10-13:** directory-index threshold is 4.
+
+No remaining blocker that needs a new fact from the codebase.
+
+---
+
+## References
+
+- `docs/research-2026-landscape.md` §R7 (around 592-615) and OpenViking
+ camp entry (around 173-206)
+- `docs/design-memory-aging.md` §A2 extractive tier-down
+- `docs/design-hindsight-borrowings.md` (MCP freeze, invariants)
+- `docs/design-boot-backfill.md` (house style: Status, Problem, What
+ already exists)
+- `docs/competitive-parity.md`, `docs/comparison.md` (OpenViking / Letta
+ positioning)
+- `docs/marker-file.md` `[briefing]`
+- `docs/ARCHITECTURE.md` SessionStart brief, `memory_briefing`,
+ `memory_read_page`
+- `crates/ai-memory-hooks/src/router.rs` `render_session_brief`
+- `crates/ai-memory-store/src/reader.rs` `BriefPageBody`,
+ `session_brief_pages_with_slot_visibility`
+- `crates/ai-memory-core/src/page.rs` `MAX_PAGE_ABSTRACT_LEN`,
+ `NewPage.body`
+- `crates/ai-memory-core/src/profile.rs` `ProfileEntry::from_page`
+- `crates/ai-memory-consolidate/src/compaction.rs` `MAX_SUMMARY_LEN`,
+ `summary_line`
+- `crates/ai-memory-mcp/src/server.rs` `MCP_TOOL_NAMES` (23)
+
+---
+
+## PR Plan
+
+One pull request, five commits, each green on its own so the series
+bisects and reviews commit by commit. Commit 4 is the behavior change.
+Base: `main`, for the maintainer to retarget to `release/3.1` once that
+branch exists.
+
+### Commit 1: Land the design doc
+
+- **Title:** `docs: design for tiered L0/L1/L2 SessionStart brief (R7)`
+- **Files:** `docs/design-tiered-session-brief.md` (this document). Skip
+ CHANGELOG until the renderer ships.
+- **Dependencies:** none.
+- **Description:** Design-doc-before-code for remaining landscape R7
+ consumption of extractive tiers on the opted-in project brief. No code.
+
+### Commit 2: Extractive L0/L1 helper in `ai-memory-core`
+
+- **Title:** `feat(core): extractive L0/L1 page excerpts for the session brief`
+- **Files:** `crates/ai-memory-core/src/excerpt.rs` (new),
+ `crates/ai-memory-core/src/lib.rs` (mod + re-export), optionally
+ `profile.rs` calling `frontmatter_nonempty` without changing digest
+ clips. Unit tests in `excerpt.rs`.
+- **Dependencies:** commit 1.
+- **Description:** Pure helper: L0 256 (`abstract` then `summary` then
+ paragraph) / L1 500 (`summary` then `abstract` then paragraph),
+ `first_prose_paragraph` skipping leading metadata / `#` / `---` lines
+ inside a block via `is_metadata_field` and continuing to the next
+ `\n\n` block when the remainder is empty (A2's loop). Tests for
+ `# Title\n\nUse nextest.` and the `profile.rs` ~1066 ADR template.
+ Empty-key handling, UTF-8 ellipsis via `truncate_utf8_bytes`. Skip
+ the A2 footer prefix without importing `COMPACTION_FOOTER`. No hook
+ behavior change. Profile digest statements stay 240-byte first lines.
+ CHANGELOG: omit until commit 4 so `[Unreleased]` does not advertise
+ a user-invisible type.
+
+### Commit 3: Carry frontmatter and compacted on `BriefPageBody`
+
+- **Title:** `feat(store): session brief rows include frontmatter and compacted`
+- **Files:** `crates/ai-memory-store/src/reader.rs` (`BriefPageBody`,
+ `session_brief_pages_with_slot_visibility` SELECT/mapper),
+ `crates/ai-memory-store/src/lib.rs` isolation test, slot tests if they
+ construct rows, `crates/ai-memory-hooks/src/router.rs` struct
+ literals in existing tests (fill `frontmatter_json: Default::default()`,
+ `compacted: false`) with **no packing change**.
+- **Dependencies:** commit 2 not strictly required (fields are raw), but
+ land after commit 2 to avoid a hooks compile that later grows a helper
+ import. Prefer commit 2 then commit 3.
+- **Description:** Same 24/10 limits, order, expiry, slot SQL. Parse
+ failure of `frontmatter_json` becomes `{}`. Renderer still uses
+ `body` only, so existing brief tests remain byte-identical. Store
+ tests for the new fields and for isolation/slots.
+
+### Commit 4: Rewrite packing, CHANGELOG, and merge-gate briefing docs
+
+- **Title:** `feat(hooks): pack the session brief as L0/L1 with L2 promotion`
+- **Files:** `crates/ai-memory-hooks/src/router.rs` (`render_session_brief`,
+ omitted/recent helpers, `BRIEF_AGENT_FOOTER`, delete
+ `BRIEF_TRUNCATED_NOTICE`, new tests). Possibly a tiny packer module in
+ the same crate if the function grows past the surrounding style.
+ `CHANGELOG.md` `### Changed`. `docs/marker-file.md` `[briefing]`
+ comment. `docs/cookbook.md` / `docs/usage.md` on-start brief recipe.
+ `docs/ARCHITECTURE.md` new SessionStart-brief subsection (do not
+ retarget the profile paragraph at ~204). `docs/agent-messaging.md`
+ hot-context sentence.
+- **Dependencies:** commit 2, commit 3, commit 1.
+- **Description:** Coverage-first assignment, omitted floor after L0,
+ privileged depth, directory index as render-only compression, footer
+ and omitted headers name `memory_read_page`, silent post-escape clamp.
+ Tests listed in "Tests the implementation PRs must add". This is the
+ user-visible flip. AGENTS.md merge-gate docs ship in this commit.
+
+### Commit 5: Landscape R7 sentence and competitive-parity note
+
+- **Title:** `docs: record R7 on-start brief in landscape and parity`
+- **Files:** `docs/research-2026-landscape.md` R7 remaining-work
+ sentence, `docs/competitive-parity.md` borrowed-ideas row,
+ `docs/comparison.md` OpenViking paragraph.
+- **Dependencies:** commit 4.
+- **Description:** Competitor-research bookkeeping after the packer
+ ships. Not the merge-gate contract for opted-in SessionStart text.
+ Humanizer on new prose. No version bump.
+
+Commit 4 carries `### Changed`. No crate
+version bump without explicit operator approval.