Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors
Rust
fix(hooks): exclude the model id by kind, not by identifier shape (#490)
Samir Hanna Verza0b32a81fde0f
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 92b3b2e5..869a3b04 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -7,6 +7,28 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0## [Unreleased]+### Fixed+- Stopped the scaffolding filter discarding terse prompts. The identifier+ branch added in #484 fired on any single token carrying a digit and a+ hyphen, underscore or bracket, which is the shape of a bare model id and+ equally the shape of `pr-477`, `issue-484` or `commit-a0bc43d`: measured+ against the two populations, it matched 10 of 10 model ids and 7 of 11+ plausible terse references, so a page could lose a real title. The class is+ now excluded at its source instead — `derive_title` skips `SessionStart`+ outright, the only kind whose title `best_title_hint` fills from the+ harness's `model` field — and the branch is gone. That also excludes the+ router's default `title_hint.unwrap_or(kind)`, the literal `session-start`+ written whenever a harness sends neither `model` nor `title`. The trade is+ narrower than a shape rule and stated as such: a model id a user *typed* is+ now kept, because at that point it is what they wrote. Where the prompts+ are unusable a page falls to the next observation title, which the router+ defaults to the observation's own kind, so `Session {id}` is reached only+ by a session carrying nothing else at all — measured over 332 real sessions+ it never was, and 5 of them landed on `tool file` / `tool non-file` against+ 327 keeping a real title. `looks_like_scaffolding` is re-exported from+ `ai-memory-core`, so its narrowing is a public-API behaviour change even+ though `derive_title` is its only caller in tree. (#484)+### Docs- Documented why registering ai-memory through Kimi Code's own`kimi mcp add` breaks every model turn: that command writes the plaindiff --git a/crates/ai-memory-core/src/scaffolding.rs b/crates/ai-memory-core/src/scaffolding.rsindex fab3a80d..82403881 100644--- a/crates/ai-memory-core/src/scaffolding.rs+++ b/crates/ai-memory-core/src/scaffolding.rs@@ -14,6 +14,17 @@//! silently, because a bad title just looks like a title. `transcript.rs`//! already carries a narrower version of this idea for `<system-reminder>`//! and `<user_info>` on the workstream path.+//!+//! **A bare model id is not tested for here, on purpose.** It has the same+//! shape as a terse human reference — `gpt-5` and `pr-477` differ only in+//! meaning — so any lexical rule that catches one catches the other, and this+//! predicate errs toward keeping text. Every model id that reached a title+//! in the surveyed corpus arrived on a `SessionStart` observation, which is+//! the only kind whose title `best_title_hint` fills from the harness's+//! `model` field, so `derive_title` skips that kind outright instead.+//!+//! That is narrower than a shape rule, deliberately: a model id somebody+//! *typed* is now kept, because at that point it is what the user wrote./// Characters that open a decorated shell prompt rather than prose./// Box-drawing and the powerline separators commonly echoed into a paste.@@ -61,19 +72,6 @@ pub fn looks_like_scaffolding(candidate: &str) -> bool {return true;}- // A bare identifier rather than a sentence: no whitespace anywhere, and- // carrying identifier punctuation. Real prompts essentially always- // contain a space; requiring the punctuation too keeps a one-word prompt- // like "help" or "continue" as a legitimate title.- if !trimmed.contains(char::is_whitespace)- && trimmed- .chars()- .any(|c| c.is_ascii_digit() || c == '[' || c == ']')- && trimmed.chars().any(|c| c == '-' || c == '_' || c == '[')- {- return true;- }-false}@@ -82,16 +80,40 @@ mod tests {use super::*;#[test]- fn the_three_observed_classes_are_scaffolding() {- // From the #484 corpus survey: 16 IDE blocks, 4 prompt echoes, 1- // model id across 330 real session pages.+ fn the_two_shape_classes_are_scaffolding() {+ // From the #484 corpus survey: 16 IDE blocks and 4 prompt echoes+ // across 330 real session pages. The survey's third class, a bare+ // model id, is excluded at its source instead — see below.assert!(looks_like_scaffolding("<ide_opened_file>The user opened the file /home/samir/x/main.rs"));assert!(looks_like_scaffolding("┌─[samir@samirb3 12:56:36] ~/x/ai-usagebar/gnome-extension"));- assert!(looks_like_scaffolding("claude-opus-5[1m]"));+ }++ #[test]+ fn a_bare_identifier_is_not_judged_by_shape() {+ // A model id and a terse human reference are the same string shape,+ // so a rule catching `claude-opus-5[1m]` also catches every entry+ // below. Measured against the corpus survey's two populations, one+ // such rule matched 10 of 10 model ids and 7 of 11 references.+ // Keeping text is the cheaper error: `derive_title` excludes model+ // ids by observation kind, and nothing excludes a lost title.+ for reference in [+ "pr-477",+ "issue-484",+ "fix-484",+ "commit-a0bc43d",+ "main-2.rs",+ "step-1",+ "task_7",+ ] {+ assert!(+ !looks_like_scaffolding(reference),+ "{reference:?} is a plausible terse prompt and must survive"+ );+ }}#[test]diff --git a/crates/ai-memory-hooks/src/synth.rs b/crates/ai-memory-hooks/src/synth.rsindex 65700532..c8b55aca 100644--- a/crates/ai-memory-hooks/src/synth.rs+++ b/crates/ai-memory-hooks/src/synth.rs@@ -68,13 +68,33 @@ pub fn synthesize_session_page(////// Prefers the first user prompt that reads as something a person wrote./// A prompt payload is whatever the harness put there, so IDE context-/// blocks, an echoed shell prompt, or a bare model id can arrive in the-/// same field (#484) — those are skipped rather than becoming the title the-/// page is indexed and displayed under.+/// blocks and an echoed shell prompt can arrive in the same field (#484) —+/// those are skipped rather than becoming the title the page is indexed and+/// displayed under.+///+/// A `SessionStart` is skipped as a source outright. `best_title_hint`+/// fills its title from `model` before `title` (`payload.rs`), so a bare+/// model id became the page title whenever the prompts were unusable — and+/// by the time it is a string it is indistinguishable from a terse human+/// reference like `pr-477`, so it is excluded here by kind instead.+///+/// The skipped field is `["model", "title"]`, so this drops more than a+/// model id: OpenCode's `session.created` puts `info.title` in the same+/// slot. Its plugin subscribes to `created`/`idle`/`deleted`/`compacted`+/// and never `session.updated`, and starts a session once per id, so the+/// only value that can arrive is the creation-time name — in practice the+/// shared literal "New session", never a rename. **That last part is an+/// assumption about an external component, not an invariant:** it is read+/// off OpenCode's subscription list as of v1.32.1, and if a future release+/// surfaces a renamed session here, this would discard a good title with+/// nothing in the tree failing. What a `SessionStart` carries is whatever+/// the harness *named the session*, and no harness names it with something+/// a person typed.////// Falls through in decreasing order of confidence: a usable prompt, then-/// any usable observation title, then the session's own path. The literal-/// "session" remains only for the case where there is nothing else at all.+/// any other usable observation title, then the session's own path. The+/// literal "session" remains only for the case where there is nothing else+/// at all.fn derive_title(observations: &[Observation], session_id: SessionId) -> String {for obs in observations {if obs.kind == ObservationKind::UserPrompt@@ -85,6 +105,9 @@ fn derive_title(observations: &[Observation], session_id: SessionId) -> String {}}for obs in observations {+ if obs.kind == ObservationKind::SessionStart {+ continue;+ }if !obs.title.is_empty() && !looks_like_scaffolding(&obs.title) {return obs.title.clone();}@@ -541,9 +564,8 @@ mod tests {for scaffold in ["<ide_opened_file>The user opened the file /home/samir/x/main.rs","\u{250c}\u{2500}[samir@samirb3 12:56:36] ~/x/ai-usagebar",- "claude-opus-5[1m]",] {- let obs = vec![+ let candidates = vec![obs(ObservationKind::UserPrompt, scaffold),obs(ObservationKind::UserPrompt,@@ -551,7 +573,7 @@ mod tests {),];assert_eq!(- derive_title(&obs, test_session_id()),+ derive_title(&candidates, test_session_id()),"Make the backpressure test deterministic","{scaffold:?} must be skipped in favour of the next real prompt");@@ -563,15 +585,79 @@ mod tests {#[test]fn an_all_scaffolding_session_falls_back_to_its_identity() {let sid = test_session_id();- let obs = vec![+ // The model id arrives on the `SessionStart`, which is where+ // `best_title_hint` puts the harness's `model` field — not as a+ // prompt somebody typed.+ let candidates = vec![+ obs(ObservationKind::SessionStart, "claude-opus-5[1m]"),obs(ObservationKind::UserPrompt, "<ide_opened_file>x"),- obs(ObservationKind::UserPrompt, "claude-opus-5[1m]"),];- let title = derive_title(&obs, sid);+ let title = derive_title(&candidates, sid);assert_eq!(title, format!("Session {sid}"));assert_ne!(title, "session", "must not collapse to a shared literal");}+ /// The shape measured in production on 2026-08-21: a 17-observation+ /// session whose `UserPrompt` carried an **empty** title, so the fallback+ /// loop reached the `SessionStart` and the harness's model id became the+ /// page title. The prompt was never scaffolding — it was absent, which is+ /// why no filter on the string could have caught this.+ #[test]+ fn a_model_id_on_session_start_never_becomes_the_title() {+ let sid = test_session_id();+ let with_a_later_title = vec![+ obs(ObservationKind::SessionStart, "claude-opus-5[1m]"),+ obs(ObservationKind::UserPrompt, ""),+ obs(ObservationKind::PostToolUse, "tool non-file"),+ ];+ assert_eq!(derive_title(&with_a_later_title, sid), "tool non-file");++ let nothing_else = vec![+ obs(ObservationKind::SessionStart, "claude-opus-5[1m]"),+ obs(ObservationKind::UserPrompt, ""),+ ];+ assert_eq!(+ derive_title(¬hing_else, sid),+ format!("Session {sid}"),+ "the session's identity, never the model it ran on"+ );+ }++ /// Skipping the kind also excludes what the router writes when a harness+ /// sends neither `model` nor `title`: `title_hint.unwrap_or(kind)`, i.e.+ /// the literal "session-start". The shape predicate never caught that,+ /// and it is a string every such page would share.+ #[test]+ fn the_routers_default_session_start_title_is_not_a_page_title() {+ let sid = test_session_id();+ for stored in ["session-start", "New session"] {+ let candidates = vec![+ obs(ObservationKind::SessionStart, stored),+ obs(ObservationKind::UserPrompt, ""),+ ];+ assert_eq!(+ derive_title(&candidates, sid),+ format!("Session {sid}"),+ "{stored:?} is what the harness named the session, not a title"+ );+ }+ }++ /// The cost of the rule this replaces: a terse reference is the same+ /// string shape as a model id, so filtering one filtered the other.+ #[test]+ fn a_terse_reference_is_still_a_usable_title() {+ let sid = test_session_id();+ for prompt in ["pr-477", "issue-484", "commit-a0bc43d"] {+ let candidates = vec![obs(ObservationKind::UserPrompt, prompt)];+ assert_eq!(+ derive_title(&candidates, sid),+ prompt,+ "{prompt:?} is a plausible prompt and must survive as a title"+ );+ }+ }+/// The title is also what `page_descriptor` filters against — a body line/// equal to it is dropped as a repeat. Changing which string becomes the/// title therefore changes which body lines survive, so a filtered page