Skip to content

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

Rust

fix(consolidate): project observations under budget

AkitaOnRailsef8e8e7aa284
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 658cd9de..fc3c16f0 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -8,6 +8,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
## [Unreleased]
### Fixed
+- Internal consolidation and auto-improvement prompts now use a deterministic,
+ budgeted observation projection that preserves high-signal anchors instead of
+ suffix-only observation windows. Manual handoff fields and item lists are
+ capped after sanitizer scrub with visible truncation markers so oversized
+ handoffs do not overwhelm the next agent context; raw observations remain
+ unchanged.
- `project_strategy = "repo-root"` no longer falls back to `basename(cwd)` for
git worktrees whose directory lives outside the main repo tree when the server
runs in a container. The server resolves repo-root via libgit2 on the incoming
diff --git a/crates/ai-memory-consolidate/src/auto_improve.rs b/crates/ai-memory-consolidate/src/auto_improve.rs
index db0132bf..a0778ebc 100644
--- a/crates/ai-memory-consolidate/src/auto_improve.rs
+++ b/crates/ai-memory-consolidate/src/auto_improve.rs
@@ -7,22 +7,23 @@
use std::collections::BTreeSet;
-use ai_memory_core::{Observation, ObservationKind, PagePath, ProjectId, SessionId, WorkspaceId};
+use ai_memory_core::{Observation, PagePath, ProjectId, SessionId, WorkspaceId};
use ai_memory_llm::{ChatMessage, ChatRequest, LlmError, LlmProvider, Role, complete_structured};
use ai_memory_store::{BriefingPage, ReaderPool, StoredPageBody};
use schemars::JsonSchema;
use serde::{Deserialize, Serialize, de};
use thiserror::Error;
+use crate::projection::{ObservationProjectionConfig, project_observations};
+
const CHARS_PER_TOKEN: usize = 4;
const PROMPT_RESERVE_TOKENS: usize = 1_000;
const MAX_PROPOSAL_BODY_CHARS: usize = 32_000;
const DEFAULT_REVIEW_MAX_TOKENS: u32 = 16_000;
const MAX_SESSION_PAGE_CHARS: usize = 32_000;
-const MAX_OBSERVATION_BODY_CHARS: usize = 1_500;
const SAMPLE_LIMIT_WITH_SESSION_PAGE: usize = 48;
const SAMPLE_LIMIT_WITHOUT_SESSION_PAGE: usize = 72;
-const EVEN_SAMPLE_BUCKETS: usize = 16;
+const MAX_OBSERVATION_BODY_CHARS: usize = 1_500;
const PROMPT_SCAFFOLD_RESERVE_CHARS: usize = 4_000;
/// Default confidence floor for staged auto-improvement proposals.
@@ -381,12 +382,23 @@ fn build_prompt_input(
.saturating_sub(recent.len())
.saturating_sub(session_page_section.len())
.saturating_sub(PROMPT_SCAFFOLD_RESERVE_CHARS);
- let (rendered_observations, selected_count) = render_sampled_observations(
+ let selected_limit = if session_page.is_some() {
+ SAMPLE_LIMIT_WITH_SESSION_PAGE
+ } else {
+ SAMPLE_LIMIT_WITHOUT_SESSION_PAGE
+ };
+ let projected_observations = project_observations(
observations,
- session_page.is_some(),
- observation_budget,
- &mut warnings,
+ &ObservationProjectionConfig::new(
+ observation_budget,
+ selected_limit,
+ MAX_OBSERVATION_BODY_CHARS,
+ )
+ .with_context_label("auto-improve"),
);
+ warnings.extend(projected_observations.warnings.iter().cloned());
+ let rendered_observations = projected_observations.text;
+ let selected_count = projected_observations.selected_count;
if selected_count < observations.len() {
rejected_candidates.push(AutoImproveRejectedCandidate {
@@ -449,155 +461,6 @@ fn render_session_page(
)
}
-fn render_sampled_observations(
- observations: &[Observation],
- has_session_page: bool,
- max_chars: usize,
- warnings: &mut Vec<String>,
-) -> (String, usize) {
- if observations.is_empty() {
- return ("(none)".into(), 0);
- }
- if max_chars == 0 {
- warnings.push("observation sample omitted because session page and page index filled the input budget".into());
- return ("(omitted by input budget)".into(), 0);
- }
-
- let limit = if has_session_page {
- SAMPLE_LIMIT_WITH_SESSION_PAGE
- } else {
- SAMPLE_LIMIT_WITHOUT_SESSION_PAGE
- };
- let indices = select_observation_indices(observations, limit);
- let mut rendered = String::new();
- let mut kept = 0usize;
-
- for idx in indices {
- let Some(obs) = observations.get(idx) else {
- continue;
- };
- let chunk = render_observation(idx, observations.len(), obs);
- if !rendered.is_empty() && rendered.len().saturating_add(chunk.len()) > max_chars {
- warnings.push(format!(
- "observation sample stopped after {kept} selected observations to stay under max_input_tokens"
- ));
- break;
- }
- rendered.push_str(&chunk);
- kept += 1;
- }
-
- if kept < observations.len() {
- warnings.push(format!(
- "observation input sampled {kept} of {} observations for scalable review",
- observations.len()
- ));
- }
-
- if rendered.is_empty() {
- rendered.push_str("(none fit the input budget)");
- }
- (rendered, kept)
-}
-
-fn select_observation_indices(observations: &[Observation], limit: usize) -> Vec<usize> {
- if observations.len() <= limit {
- return (0..observations.len()).collect();
- }
- let even = even_sample_indices(observations.len());
- let mut scored: Vec<(i32, usize)> = observations
- .iter()
- .enumerate()
- .map(|(idx, obs)| {
- let mut score = observation_score(obs, idx, observations.len());
- if even.contains(&idx) {
- score += 40;
- }
- (score, idx)
- })
- .collect();
- scored.sort_by(|a, b| b.0.cmp(&a.0).then_with(|| a.1.cmp(&b.1)));
-
- let selected: BTreeSet<usize> = scored.into_iter().take(limit).map(|(_, idx)| idx).collect();
- selected.into_iter().collect()
-}
-
-fn even_sample_indices(total: usize) -> BTreeSet<usize> {
- let mut out = BTreeSet::new();
- if total == 0 {
- return out;
- }
- if total == 1 {
- out.insert(0);
- return out;
- }
- let buckets = EVEN_SAMPLE_BUCKETS.min(total);
- for bucket in 0..buckets {
- let idx = bucket.saturating_mul(total - 1) / (buckets - 1).max(1);
- out.insert(idx);
- }
- out
-}
-
-fn observation_score(obs: &Observation, idx: usize, total: usize) -> i32 {
- let mut score = i32::from(obs.importance);
- score += match obs.kind {
- ObservationKind::UserPrompt => 80,
- ObservationKind::SessionEnd => 70,
- ObservationKind::Stop => 55,
- ObservationKind::PreCompact => 45,
- ObservationKind::PostToolUse => 30,
- ObservationKind::Notification => 25,
- ObservationKind::SessionStart => 20,
- ObservationKind::Other => 15,
- ObservationKind::PreToolUse => 5,
- };
- if idx == 0 || idx + 1 == total {
- score += 100;
- }
-
- let body_prefix = obs.body.chars().take(4_000).collect::<String>();
- let text = format!("{}\n{}", obs.title, body_prefix).to_ascii_lowercase();
- for keyword in [
- "root cause",
- "fix",
- "fixed",
- "failed",
- "failure",
- "error",
- "bug",
- "regression",
- "decision",
- "decided",
- "gotcha",
- "rule",
- "always",
- "never",
- "migration",
- "scope",
- "workspace",
- "project",
- "auth",
- "test",
- "clippy",
- "release",
- ] {
- if text.contains(keyword) {
- score += 15;
- }
- }
- if obs.body.contains("```") {
- score += 8;
- }
- if text.contains("long-term memory (ai-memory)")
- || text.contains("install ai-memory routing")
- || text.contains("memory_query searches only one project")
- {
- score -= 80;
- }
- score
-}
-
fn render_recent_pages(pages: &[BriefingPage]) -> String {
if pages.is_empty() {
return "(none)".into();
@@ -612,25 +475,6 @@ fn render_recent_pages(pages: &[BriefingPage]) -> String {
out
}
-fn render_observation(idx: usize, total: usize, obs: &Observation) -> String {
- let (body, _) = truncate_with_marker(
- &obs.body,
- MAX_OBSERVATION_BODY_CHARS,
- "[observation truncated]",
- );
- format!(
- "\n--- observation {}/{} {} ---\nkind: {}\ntitle: {}\nimportance: {}\ncreated_at: {}\nbody:\n{}\n",
- idx + 1,
- total,
- obs.id,
- obs.kind.as_str(),
- obs.title,
- obs.importance,
- obs.created_at,
- body
- )
-}
-
fn truncate_with_marker(input: &str, max_bytes: usize, marker: &str) -> (String, bool) {
if input.len() <= max_bytes {
return (input.to_string(), false);
diff --git a/crates/ai-memory-consolidate/src/consolidator.rs b/crates/ai-memory-consolidate/src/consolidator.rs
index fa630c8d..9607141a 100644
--- a/crates/ai-memory-consolidate/src/consolidator.rs
+++ b/crates/ai-memory-consolidate/src/consolidator.rs
@@ -14,6 +14,7 @@ use ai_memory_wiki::{AdmissionContext, AdmissionOp, Wiki, WritePageRequest};
use thiserror::Error;
use tracing::{debug, info};
+use crate::projection::{ObservationProjectionConfig, project_observations};
use crate::types::{ConsolidatedBatch, ConsolidatedPage, ConsolidationOutcome, SlotKind};
/// Errors raised by the consolidator.
@@ -478,26 +479,16 @@ fn build_batch_request_with_slots(
buf.push_str("Session id: ");
buf.push_str(&session_id.to_string());
buf.push_str("\n\nObservations:\n");
- let (windowed, skipped) = window_observations_to_budget(observations, OBSERVATION_BUDGET_CHARS);
- if skipped > 0 {
- buf.push_str(&format!(
- "(showing {} most recent observations; {} older observations omitted \
- because they exceeded the context budget — PreCompact / earlier \
- consolidation runs should have already captured them)\n",
- windowed.len(),
- skipped,
- ));
- }
- for o in windowed {
- buf.push_str(&format!(
- "- {} | {}\n",
- observation_label(o),
- one_line(&o.title)
- ));
- if !o.body.trim().is_empty() {
- buf.push_str(&format!(" body: {}\n", one_line(&o.body)));
- }
- }
+ let projected = project_observations(
+ observations,
+ &ObservationProjectionConfig::new(
+ OBSERVATION_BUDGET_CHARS,
+ MAX_PROJECTED_OBSERVATIONS,
+ MAX_PROJECTED_OBSERVATION_BODY_CHARS,
+ )
+ .with_context_label("batch consolidation"),
+ );
+ buf.push_str(&projected.text);
if !slots.is_empty() {
buf.push_str("\nCurrent `_slots/` pages (for write-regime decisions):\n");
for slot in slots {
@@ -596,26 +587,16 @@ fn build_request(
buf.push_str("Session id: ");
buf.push_str(&session_id.to_string());
buf.push_str("\nObservations (in order):\n\n");
- let (windowed, skipped) = window_observations_to_budget(observations, OBSERVATION_BUDGET_CHARS);
- if skipped > 0 {
- buf.push_str(&format!(
- "(showing {} most recent observations; {} older observations omitted \
- because they exceeded the context budget — PreCompact / earlier \
- consolidation runs should have already captured them)\n\n",
- windowed.len(),
- skipped,
- ));
- }
- for o in windowed {
- buf.push_str(&format!(
- "- {} | {}\n",
- observation_label(o),
- one_line(&o.title)
- ));
- if !o.body.trim().is_empty() {
- buf.push_str(&format!(" body: {}\n", one_line(&o.body)));
- }
- }
+ let projected = project_observations(
+ observations,
+ &ObservationProjectionConfig::new(
+ OBSERVATION_BUDGET_CHARS,
+ MAX_PROJECTED_OBSERVATIONS,
+ MAX_PROJECTED_OBSERVATION_BODY_CHARS,
+ )
+ .with_context_label("single-page consolidation"),
+ );
+ buf.push_str(&projected.text);
if !current_body.trim().is_empty() {
let current_body = prepare_current_body_for_prompt(current_body);
buf.push_str("\nCurrent (heuristic) page body:\n\n```\n");
@@ -651,64 +632,10 @@ fn build_request(
/// differently; under-shooting the budget loses some context but never
/// causes a 400 from the provider.
const OBSERVATION_BUDGET_CHARS: usize = 400_000;
+const MAX_PROJECTED_OBSERVATIONS: usize = 256;
+const MAX_PROJECTED_OBSERVATION_BODY_CHARS: usize = 3_000;
const CURRENT_BODY_BUDGET_CHARS: usize = 20_000;
-/// Per-observation char-cost estimate used by [`window_observations_to_budget`]
-/// to predict how much each entry will add to the prompt buffer. Matches
-/// the rendered `"- {label} | {one-line title}\n body: {one-line body}\n"`
-/// shape used by both `build_request` and `build_batch_request_with_slots`.
-fn observation_render_cost(o: &Observation) -> usize {
- // "- " + label + " | " + title + "\n" plus optional " body: " + body + "\n"
- let label = observation_label(o).len();
- let title = o.title.chars().count();
- let body = if o.body.trim().is_empty() {
- 0
- } else {
- // " body: " (10) + one-line body + "\n"
- 10 + o.body.chars().count() + 1
- };
- 2 + label + 3 + title + 1 + body
-}
-
-/// Take observations from most-recent backward, accumulating into the
-/// budget. Returns the included slice (in original chronological order)
-/// and the count of observations skipped. When everything fits, returns
-/// the input unchanged and `skipped = 0`.
-///
-/// This is the long-session fallback for super-long agent runs that
-/// would otherwise exceed the model's context window (the failure mode
-/// sabadell's 7,234-observation 16-hour session hit pre-v0.8.1). The
-/// truncation note prepended by callers tells the LLM that older
-/// observations were omitted, so its output should not pretend to cover
-/// the early session. Earlier observations should already have been
-/// captured by intra-session PreCompact runs; if they weren't, they're
-/// preserved in the raw `observations` table for future
-/// `memory_consolidate` calls.
-fn window_observations_to_budget(
- observations: &[Observation],
- budget: usize,
-) -> (&[Observation], usize) {
- if observations.is_empty() {
- return (observations, 0);
- }
- let mut total = 0usize;
- // Walk from most recent backward; include each whole entry whose
- // cost still fits. The first observation that pushes us over the
- // budget is excluded along with everything older than it.
- let mut keep_from = observations.len();
- for (i, o) in observations.iter().enumerate().rev() {
- let cost = observation_render_cost(o);
- if total + cost > budget {
- keep_from = i + 1;
- break;
- }
- total += cost;
- keep_from = i;
- }
- let skipped = keep_from;
- (&observations[keep_from..], skipped)
-}
-
fn prepare_current_body_for_prompt(current_body: &str) -> String {
let without_raw = elide_raw_observations_section(current_body);
clip_current_body_for_prompt(&without_raw, CURRENT_BODY_BUDGET_CHARS)
@@ -749,15 +676,6 @@ fn clip_current_body_for_prompt(s: &str, max_chars: usize) -> String {
out
}
-fn observation_label(obs: &Observation) -> String {
- match (&obs.extension, &obs.source_event) {
- (Some(extension), Some(source_event)) => {
- format!("{} [{}:{}]", obs.kind.as_str(), extension, source_event)
- }
- _ => obs.kind.as_str().to_string(),
- }
-}
-
fn build_frontmatter(page: &ConsolidatedPage) -> serde_json::Value {
let mut map = serde_json::Map::new();
map.insert(
@@ -853,9 +771,7 @@ mod tests {
use ai_memory_core::{ObservationId, ObservationKind, ProjectId, SessionId, WorkspaceId};
use jiff::Timestamp;
- /// Helper for windowing tests — produces an Observation with the
- /// given body length, all other fields filled with cheap defaults
- /// so observation_render_cost is dominated by the body size.
+ /// Helper for prompt construction tests.
fn obs_of_size(body_len: usize) -> Observation {
Observation {
id: ObservationId::new(),
@@ -872,80 +788,15 @@ mod tests {
}
}
- /// Tiny input that fits in any budget returns unchanged with skipped=0.
- #[test]
- fn window_observations_returns_all_when_under_budget() {
- let obs = vec![obs_of_size(10), obs_of_size(20), obs_of_size(30)];
- let (kept, skipped) = window_observations_to_budget(&obs, 10_000);
- assert_eq!(kept.len(), 3);
- assert_eq!(skipped, 0);
- }
-
- /// Empty input returns empty + skipped=0 — the early-return guard.
- #[test]
- fn window_observations_empty_input_is_empty_output() {
- let obs: Vec<Observation> = vec![];
- let (kept, skipped) = window_observations_to_budget(&obs, 10_000);
- assert_eq!(kept.len(), 0);
- assert_eq!(skipped, 0);
- }
-
- /// Tight budget keeps only the most recent observations. Critical
- /// behaviour: the LATEST entries are preserved (most useful for the
- /// LLM); older ones get dropped. Mirrors the sabadell failure mode.
- #[test]
- fn window_observations_keeps_most_recent_within_budget() {
- // 100 observations of ~1k chars each → ~100k chars total.
- // Budget of 30k chars should keep ~30 most recent.
- let obs: Vec<Observation> = (0..100).map(|_| obs_of_size(1_000)).collect();
- let (kept, skipped) = window_observations_to_budget(&obs, 30_000);
-
- assert!(
- skipped > 0,
- "with 100k of input + 30k budget some must drop"
- );
- assert_eq!(
- kept.len() + skipped,
- 100,
- "kept + skipped must equal total — no double-counting"
- );
- // The kept slice must be the suffix of the input — i.e. the
- // most recent entries, not the oldest.
- let first_kept_id = kept.first().unwrap().id;
- let expected_first = obs[skipped].id;
- assert_eq!(
- first_kept_id, expected_first,
- "kept window must start at obs[skipped], not from the beginning"
- );
- }
-
- /// One observation that already exceeds the budget: keep zero,
- /// skip everything. Caller's prepended "(showing 0 most recent …)"
- /// message still fires, signalling to the LLM that the session was
- /// too big to summarise.
#[test]
- fn window_observations_drops_everything_when_single_obs_exceeds_budget() {
- let obs = vec![obs_of_size(50_000)];
- let (kept, skipped) = window_observations_to_budget(&obs, 1_000);
- assert_eq!(kept.len(), 0);
- assert_eq!(skipped, 1);
- }
-
- /// Budget granularity: drops are at observation boundaries, never
- /// mid-observation. Two equal-cost obs with a budget that fits
- /// exactly one → keep the most recent one, drop the older one.
- #[test]
- fn window_observations_drops_at_observation_boundary() {
- let a = obs_of_size(100);
- let b = obs_of_size(100);
- let cost_each = observation_render_cost(&a);
- let obs = vec![a, b];
- // Budget exactly fits one observation.
- let (kept, skipped) = window_observations_to_budget(&obs, cost_each);
- assert_eq!(kept.len(), 1);
- assert_eq!(skipped, 1);
- // Most-recent (index 1) is the one kept.
- assert_eq!(kept[0].id, obs[1].id);
+ fn build_request_uses_projected_observation_metadata() {
+ let observations = vec![obs_of_size(10), obs_of_size(20)];
+ let request = build_request(SessionId::new(), &observations, "");
+ let prompt = &request.messages[0].content;
+ assert!(prompt.contains("--- observation 1/2 ---"));
+ assert!(prompt.contains("id:"));
+ assert!(prompt.contains("created_at:"));
+ assert!(prompt.contains("importance:"));
}
#[test]
diff --git a/crates/ai-memory-consolidate/src/lib.rs b/crates/ai-memory-consolidate/src/lib.rs
index 1e4d501a..f0929197 100644
--- a/crates/ai-memory-consolidate/src/lib.rs
+++ b/crates/ai-memory-consolidate/src/lib.rs
@@ -13,6 +13,7 @@ pub mod bootstrap;
pub mod consolidator;
pub mod curator;
pub mod lint;
+pub mod projection;
pub mod sweep;
pub mod types;
diff --git a/crates/ai-memory-consolidate/src/projection.rs b/crates/ai-memory-consolidate/src/projection.rs
new file mode 100644
index 00000000..cd262aa9
--- /dev/null
+++ b/crates/ai-memory-consolidate/src/projection.rs
@@ -0,0 +1,604 @@
+//! Deterministic observation projection for bounded internal LLM prompts.
+
+use std::collections::BTreeSet;
+
+use ai_memory_core::{Observation, ObservationKind};
+
+const DEFAULT_EVEN_SAMPLE_BUCKETS: usize = 16;
+const MAX_RENDERED_TITLE_CHARS: usize = 500;
+const MAX_RENDERED_SOURCE_CHARS: usize = 128;
+
+/// Budget and rendering controls for observation projection.
+#[derive(Debug, Clone)]
+pub struct ObservationProjectionConfig {
+ /// Target maximum rendered characters. If ordinary pruning cannot fit the
+ /// text, the final projection is clipped with a visible fallback marker.
+ pub max_total_chars: usize,
+ /// Maximum number of observations selected before character-budget pruning.
+ pub max_selected_observations: usize,
+ /// Maximum body excerpt characters per selected observation.
+ pub per_body_excerpt_chars: usize,
+ /// Optional label included in omission warnings/markers.
+ pub context_label: Option<String>,
+}
+
+impl ObservationProjectionConfig {
+ /// Construct a projection config.
+ #[must_use]
+ pub fn new(
+ max_total_chars: usize,
+ max_selected_observations: usize,
+ per_body_excerpt_chars: usize,
+ ) -> Self {
+ Self {
+ max_total_chars,
+ max_selected_observations,
+ per_body_excerpt_chars,
+ context_label: None,
+ }
+ }
+
+ /// Attach a context label for human-readable warnings.
+ #[must_use]
+ pub fn with_context_label(mut self, label: impl Into<String>) -> Self {
+ self.context_label = Some(label.into());
+ self
+ }
+}
+
+/// Rendered observation projection plus accounting useful to callers.
+#[derive(Debug, Clone)]
+pub struct ProjectedObservations {
+ /// Prompt-ready text.
+ pub text: String,
+ /// Total observations considered.
+ pub total_count: usize,
+ /// Number of observations rendered.
+ pub selected_count: usize,
+ /// Number of observations not rendered.
+ pub omitted_count: usize,
+ /// Number of selected observation bodies truncated.
+ pub truncated_bodies: usize,
+ /// Selected observation indices in chronological order.
+ pub selected_indices: Vec<usize>,
+ /// Non-fatal budget and truncation notes.
+ pub warnings: Vec<String>,
+}
+
+/// Cap one user-visible string with a visible marker.
+#[must_use]
+pub fn cap_text_with_marker(input: &str, max_chars: usize, label: &str) -> String {
+ if input.chars().count() <= max_chars {
+ return input.to_string();
+ }
+ let mut out: String = input.chars().take(max_chars).collect();
+ let omitted = input.chars().count().saturating_sub(max_chars);
+ out.push_str(&format!("\n[{label} truncated; {omitted} chars omitted]"));
+ out
+}
+
+/// Project raw observations into deterministic, budgeted prompt text without
+/// mutating or compressing the raw observations in SQLite.
+#[must_use]
+pub fn project_observations(
+ observations: &[Observation],
+ cfg: &ObservationProjectionConfig,
+) -> ProjectedObservations {
+ if observations.is_empty() {
+ return ProjectedObservations {
+ text: "(none)".into(),
+ total_count: 0,
+ selected_count: 0,
+ omitted_count: 0,
+ truncated_bodies: 0,
+ selected_indices: Vec::new(),
+ warnings: Vec::new(),
+ };
+ }
+
+ if cfg.max_selected_observations == 0 || cfg.max_total_chars == 0 {
+ let text = format!(
+ "[{} observations omitted: no projection budget; full originals remain in SQLite by observation id]\n",
+ observations.len()
+ );
+ return ProjectedObservations {
+ text,
+ total_count: observations.len(),
+ selected_count: 0,
+ omitted_count: observations.len(),
+ truncated_bodies: 0,
+ selected_indices: Vec::new(),
+ warnings: vec![format!(
+ "{} observation projection omitted by input budget",
+ context_label(cfg)
+ )],
+ };
+ }
+
+ let mut selected = select_observation_indices(observations, cfg.max_selected_observations);
+ let mut rendered = render_projection(observations, &selected, cfg.per_body_excerpt_chars);
+
+ while rendered.text.chars().count() > cfg.max_total_chars && selected.len() > 1 {
+ let Some(remove_idx) = lowest_prunable_index(observations, &selected) else {
+ break;
+ };
+ selected.retain(|idx| *idx != remove_idx);
+ rendered = render_projection(observations, &selected, cfg.per_body_excerpt_chars);
+ }
+
+ let omitted_count = observations.len().saturating_sub(selected.len());
+ let mut text = rendered.text;
+ let mut warnings = Vec::new();
+ if omitted_count > 0 {
+ let marker = format!(
+ "\n[{} observations omitted from {} projection due to sample/count/character budget; selected {} of {}; full originals remain in SQLite by observation id]\n",
+ omitted_count,
+ context_label(cfg),
+ selected.len(),
+ observations.len()
+ );
+ text.push_str(&marker);
+ warnings.push(format!(
+ "{} observation input sampled {} of {} observations",
+ context_label(cfg),
+ selected.len(),
+ observations.len()
+ ));
+ }
+ if rendered.truncated_bodies > 0 {
+ warnings.push(format!(
+ "{} truncated {} observation bod{} to {} chars",
+ context_label(cfg),
+ rendered.truncated_bodies,
+ if rendered.truncated_bodies == 1 {
+ "y"
+ } else {
+ "ies"
+ },
+ cfg.per_body_excerpt_chars
+ ));
+ }
+ if text.chars().count() > cfg.max_total_chars {
+ warnings.push(format!(
+ "{} projection exceeded max_total_chars after mandatory markers/anchors ({} > {})",
+ context_label(cfg),
+ text.chars().count(),
+ cfg.max_total_chars
+ ));
+ text = fit_text_to_budget(
+ &text,
+ cfg.max_total_chars,
+ "[projection text truncated to budget; full originals remain in SQLite by observation id]",
+ );
+ }
+
+ ProjectedObservations {
+ text,
+ total_count: observations.len(),
+ selected_count: selected.len(),
+ omitted_count,
+ truncated_bodies: rendered.truncated_bodies,
+ selected_indices: selected,
+ warnings,
+ }
+}
+
+fn context_label(cfg: &ObservationProjectionConfig) -> &str {
+ cfg.context_label
+ .as_deref()
+ .filter(|label| !label.trim().is_empty())
+ .unwrap_or("observation")
+}
+
+struct RenderedProjection {
+ text: String,
+ truncated_bodies: usize,
+}
+
+fn render_projection(
+ observations: &[Observation],
+ selected: &[usize],
+ per_body_excerpt_chars: usize,
+) -> RenderedProjection {
+ let mut text = String::new();
+ let mut truncated_bodies = 0usize;
+ for idx in selected {
+ let Some(obs) = observations.get(*idx) else {
+ continue;
+ };
+ let (body, truncated, omitted) = excerpt_body(&obs.body, per_body_excerpt_chars);
+ if truncated {
+ truncated_bodies += 1;
+ }
+ let title = cap_text_with_marker(&obs.title, MAX_RENDERED_TITLE_CHARS, "observation title");
+ text.push_str(&format!(
+ "\n--- observation {}/{} ---\nid: {}\nkind: {}\ntitle: {}\nimportance: {}\ncreated_at: {}\n",
+ idx + 1,
+ observations.len(),
+ obs.id,
+ obs.kind.as_str(),
+ title,
+ obs.importance,
+ obs.created_at,
+ ));
+ if let Some(extension) = obs.extension.as_deref().filter(|s| !s.trim().is_empty()) {
+ let extension = cap_text_with_marker(extension, MAX_RENDERED_SOURCE_CHARS, "extension");
+ text.push_str(&format!("extension: {extension}\n"));
+ }
+ if let Some(source_event) = obs.source_event.as_deref().filter(|s| !s.trim().is_empty()) {
+ let source_event =
+ cap_text_with_marker(source_event, MAX_RENDERED_SOURCE_CHARS, "source event");
+ text.push_str(&format!("source_event: {source_event}\n"));
+ }
+ text.push_str(&format!("body:\n{body}"));
+ if truncated {
+ text.push_str(&format!(
+ "\n[observation body truncated; {omitted} chars omitted; full original remains in SQLite as observation id {}]",
+ obs.id
+ ));
+ }
+ text.push('\n');
+ }
+ RenderedProjection {
+ text,
+ truncated_bodies,
+ }
+}
+
+fn excerpt_body(body: &str, max_chars: usize) -> (String, bool, usize) {
+ let total = body.chars().count();
+ if total <= max_chars {
+ return (body.to_string(), false, 0);
+ }
+ let excerpt: String = body.chars().take(max_chars).collect();
+ (excerpt, true, total.saturating_sub(max_chars))
+}
+
+fn fit_text_to_budget(text: &str, max_chars: usize, marker: &str) -> String {
+ if text.chars().count() <= max_chars {
+ return text.to_string();
+ }
+ if max_chars == 0 {
+ return String::new();
+ }
+ let marker = format!("\n{marker}");
+ let marker_len = marker.chars().count();
+ if marker_len >= max_chars {
+ return marker.chars().take(max_chars).collect();
+ }
+ let keep = max_chars.saturating_sub(marker_len);
+ let mut out: String = text.chars().take(keep).collect();
+ out.push_str(&marker);
+ out
+}
+
+fn select_observation_indices(observations: &[Observation], limit: usize) -> Vec<usize> {
+ if observations.len() <= limit {
+ return (0..observations.len()).collect();
+ }
+ let mut selected: BTreeSet<usize> = BTreeSet::new();
+ if limit == 1 {
+ selected.insert(observations.len() - 1);
+ return selected.into_iter().collect();
+ }
+ selected.insert(0);
+ selected.insert(observations.len() - 1);
+ let even = even_sample_indices(observations.len());
+ let mut scored: Vec<(i32, usize)> = observations
+ .iter()
+ .enumerate()
+ .filter(|(idx, _)| !selected.contains(idx))
+ .map(|(idx, obs)| {
+ let mut score = observation_score(obs, idx, observations.len());
+ if even.contains(&idx) {
+ score += 40;
+ }
+ (score, idx)
+ })
+ .collect();
+ scored.sort_by(|a, b| b.0.cmp(&a.0).then_with(|| b.1.cmp(&a.1)));
+
+ for (_, idx) in scored {
+ if selected.len() >= limit {
+ break;
+ }
+ selected.insert(idx);
+ }
+ selected.into_iter().collect()
+}
+
+fn even_sample_indices(total: usize) -> BTreeSet<usize> {
+ let mut out = BTreeSet::new();
+ if total == 0 {
+ return out;
+ }
+ if total == 1 {
+ out.insert(0);
+ return out;
+ }
+ let buckets = DEFAULT_EVEN_SAMPLE_BUCKETS.min(total);
+ for bucket in 0..buckets {
+ let idx = bucket.saturating_mul(total - 1) / (buckets - 1).max(1);
+ out.insert(idx);
+ }
+ out
+}
+
+fn lowest_prunable_index(observations: &[Observation], selected: &[usize]) -> Option<usize> {
+ selected
+ .iter()
+ .copied()
+ .filter(|idx| !is_hard_anchor(observations, *idx))
+ .map(|idx| {
+ (
+ observation_score(&observations[idx], idx, observations.len()),
+ idx,
+ )
+ })
+ .min_by(|a, b| a.0.cmp(&b.0).then_with(|| a.1.cmp(&b.1)))
+ .map(|(_, idx)| idx)
+}
+
+fn is_hard_anchor(observations: &[Observation], idx: usize) -> bool {
+ idx == 0 || idx + 1 == observations.len()
+}
+
+fn observation_score(obs: &Observation, idx: usize, total: usize) -> i32 {
+ let mut score = i32::from(obs.importance);
+ score += match obs.kind {
+ ObservationKind::UserPrompt => 100,
+ ObservationKind::SessionEnd => 95,
+ ObservationKind::Stop => 55,
+ ObservationKind::PreCompact => 90,
+ ObservationKind::PostToolUse => 30,
+ ObservationKind::Notification => 25,
+ ObservationKind::SessionStart => 20,
+ ObservationKind::Other => 15,
+ ObservationKind::PreToolUse => 5,
+ };
+ if idx == 0 || idx + 1 == total {
+ score += 100;
+ }
+ if has_high_signal_terms(obs) {
+ score += 45;
+ }
+ if obs.importance >= 9 {
+ score += 45;
+ }
+ if obs.body.contains("```") {
+ score += 8;
+ }
+ let body_prefix = obs.body.chars().take(4_000).collect::<String>();
+ let text = format!("{}\n{}", obs.title, body_prefix).to_ascii_lowercase();
+ if text.contains("long-term memory (ai-memory)")
+ || text.contains("install ai-memory routing")
+ || text.contains("memory_query searches only one project")
+ {
+ score -= 80;
+ }
+ score
+}
+
+fn has_high_signal_terms(obs: &Observation) -> bool {
+ let body_prefix = obs.body.chars().take(4_000).collect::<String>();
+ let text = format!("{}\n{}", obs.title, body_prefix).to_ascii_lowercase();
+ [
+ "root cause",
+ "fix",
+ "fixed",
+ "failed",
+ "failure",
+ "error",
+ "bug",
+ "regression",
+ "decision",
+ "decided",
+ "gotcha",
+ "rule",
+ "always",
+ "never",
+ "migration",
+ "scope",
+ "workspace",
+ "project",
+ "auth",
+ "test",
+ "clippy",
+ "release",
+ ]
+ .iter()
+ .any(|keyword| text.contains(keyword))
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+ use ai_memory_core::{ObservationId, ProjectId, SessionId, WorkspaceId};
+ use jiff::Timestamp;
+
+ fn obs(
+ idx: usize,
+ kind: ObservationKind,
+ title: &str,
+ body: &str,
+ importance: u8,
+ ) -> Observation {
+ Observation {
+ id: ObservationId::new(),
+ workspace_id: WorkspaceId::new(),
+ project_id: ProjectId::new(),
+ session_id: SessionId::new(),
+ kind,
+ title: format!("{title} {idx}"),
+ body: body.into(),
+ created_at: Timestamp::UNIX_EPOCH,
+ importance,
+ extension: None,
+ source_event: None,
+ }
+ }
+
+ #[test]
+ fn small_sessions_render_all_observations() {
+ let observations = vec![
+ obs(0, ObservationKind::SessionStart, "start", "cwd", 5),
+ obs(1, ObservationKind::UserPrompt, "prompt", "do work", 7),
+ obs(2, ObservationKind::SessionEnd, "end", "done", 5),
+ ];
+ let projected = project_observations(
+ &observations,
+ &ObservationProjectionConfig::new(10_000, 10, 1_000),
+ );
+ assert_eq!(projected.selected_count, 3);
+ assert_eq!(projected.omitted_count, 0);
+ assert!(projected.text.contains("observation 1/3"));
+ assert!(projected.text.contains("observation 3/3"));
+ assert!(projected.warnings.is_empty());
+ }
+
+ #[test]
+ fn long_sessions_preserve_anchors_and_mark_omissions() {
+ let mut observations: Vec<_> = (0..80)
+ .map(|idx| obs(idx, ObservationKind::PostToolUse, "routine", "boring", 3))
+ .collect();
+ observations[5] = obs(
+ 5,
+ ObservationKind::UserPrompt,
+ "user prompt",
+ "important request",
+ 5,
+ );
+ observations[20] = obs(
+ 20,
+ ObservationKind::PreCompact,
+ "pre compact",
+ "context pressure",
+ 5,
+ );
+ observations[35] = obs(
+ 35,
+ ObservationKind::PostToolUse,
+ "error",
+ "failed with regression",
+ 5,
+ );
+ observations[50] = obs(
+ 50,
+ ObservationKind::Other,
+ "high importance",
+ "key decision",
+ 10,
+ );
+ observations[79] = obs(79, ObservationKind::SessionEnd, "session end", "done", 5);
+
+ let projected = project_observations(
+ &observations,
+ &ObservationProjectionConfig::new(20_000, 12, 200),
+ );
+ assert!(projected.selected_indices.contains(&0));
+ assert!(projected.selected_indices.contains(&79));
+ assert!(projected.selected_indices.contains(&5));
+ assert!(projected.selected_indices.contains(&20));
+ assert!(projected.selected_indices.contains(&35));
+ assert!(projected.selected_indices.contains(&50));
+ assert!(projected.text.contains("observations omitted"));
+ }
+
+ #[test]
+ fn many_high_signal_observations_still_respect_selection_cap() {
+ let observations: Vec<_> = (0..40)
+ .map(|idx| {
+ obs(
+ idx,
+ ObservationKind::UserPrompt,
+ "user prompt",
+ "fix failed error regression decision",
+ 9,
+ )
+ })
+ .collect();
+ let projected = project_observations(
+ &observations,
+ &ObservationProjectionConfig::new(20_000, 8, 200),
+ );
+ assert_eq!(projected.selected_count, 8);
+ assert_eq!(projected.selected_indices.first().copied(), Some(0));
+ assert_eq!(projected.selected_indices.last().copied(), Some(39));
+ assert!(projected.text.contains("observations omitted"));
+ }
+
+ #[test]
+ fn body_truncation_marker_includes_omitted_chars_and_id() {
+ let observations = vec![obs(
+ 0,
+ ObservationKind::UserPrompt,
+ "prompt",
+ &"x".repeat(30),
+ 5,
+ )];
+ let id = observations[0].id.to_string();
+ let projected = project_observations(
+ &observations,
+ &ObservationProjectionConfig::new(10_000, 10, 10),
+ );
+ assert!(projected.text.contains("20 chars omitted"));
+ assert!(projected.text.contains(&id));
+ assert!(projected.text.contains("full original remains in SQLite"));
+ assert_eq!(projected.truncated_bodies, 1);
+ }
+
+ #[test]
+ fn huge_title_is_capped_and_projection_respects_budget() {
+ let mut observations = vec![obs(
+ 0,
+ ObservationKind::Notification,
+ &"title".repeat(1_000),
+ "small body",
+ 5,
+ )];
+ observations[0].extension = Some("ext".into());
+ observations[0].source_event = Some("source".into());
+ let projected = project_observations(
+ &observations,
+ &ObservationProjectionConfig::new(900, 10, 100),
+ );
+ assert!(projected.text.chars().count() <= 900);
+ assert!(projected.text.contains("observation title truncated"));
+ assert!(projected.text.contains("extension: ext"));
+ assert!(projected.text.contains("source_event: source"));
+ }
+
+ #[test]
+ fn tiny_budget_uses_hard_fallback_marker() {
+ let observations = vec![obs(
+ 0,
+ ObservationKind::UserPrompt,
+ "prompt",
+ &"x".repeat(1_000),
+ 5,
+ )];
+ let cfg = ObservationProjectionConfig::new(80, 10, 500);
+ let projected = project_observations(&observations, &cfg);
+ assert!(projected.text.chars().count() <= cfg.max_total_chars);
+ assert!(projected.text.contains("projection text truncated"));
+ }
+
+ #[test]
+ fn output_respects_max_chars_except_marker_overhead() {
+ let observations: Vec<_> = (0..40)
+ .map(|idx| {
+ obs(
+ idx,
+ ObservationKind::PostToolUse,
+ "routine",
+ &"x".repeat(200),
+ 3,
+ )
+ })
+ .collect();
+ let cfg = ObservationProjectionConfig::new(3_000, 10, 50);
+ let projected = project_observations(&observations, &cfg);
+ assert!(projected.text.chars().count() <= cfg.max_total_chars);
+ assert!(projected.text.contains("observations omitted"));
+ }
+}
diff --git a/crates/ai-memory-mcp/src/server.rs b/crates/ai-memory-mcp/src/server.rs
index 7f25d903..cd1592db 100644
--- a/crates/ai-memory-mcp/src/server.rs
+++ b/crates/ai-memory-mcp/src/server.rs
@@ -5,7 +5,8 @@ use std::str::FromStr;
use std::sync::Arc;
use ai_memory_consolidate::{
- AutoImproveReviewConfig, Consolidator, run_auto_improve_review, run_lint, run_sweep,
+ AutoImproveReviewConfig, Consolidator, projection::cap_text_with_marker,
+ run_auto_improve_review, run_lint, run_sweep,
};
use ai_memory_core::{
ActiveProject, AgentKind, HandoffId, HandoffState, NewHandoff, PageId, PagePath, ProjectId,
@@ -24,6 +25,90 @@ use rmcp::model::{
use rmcp::{ErrorData as McpError, ServerHandler, schemars, tool, tool_handler, tool_router};
use serde::{Deserialize, Serialize};
+const HANDOFF_SUMMARY_MAX_CHARS: usize = 3_000;
+const HANDOFF_ITEM_MAX_CHARS: usize = 1_500;
+const HANDOFF_FILE_MAX_CHARS: usize = 512;
+const HANDOFF_TEXT_LIST_MAX_CHARS: usize = 6_000;
+const HANDOFF_FILE_LIST_MAX_CHARS: usize = 4_096;
+const HANDOFF_LIST_MAX_ITEMS: usize = 20;
+
+fn cap_handoff_list<I>(
+ items: I,
+ item_max_chars: usize,
+ total_max_chars: usize,
+ item_label: &str,
+ list_label: &str,
+) -> Vec<String>
+where
+ I: IntoIterator<Item = String>,
+{
+ let capped: Vec<String> = items
+ .into_iter()
+ .map(|item| cap_text_with_marker(&item, item_max_chars, item_label))
+ .collect();
+ let total_items = capped.len();
+ let mut out = Vec::new();
+ let mut used_chars = 0usize;
+
+ for (idx, item) in capped.into_iter().enumerate() {
+ if out.len() >= HANDOFF_LIST_MAX_ITEMS {
+ push_handoff_omission_marker(
+ &mut out,
+ &mut used_chars,
+ total_max_chars,
+ list_label,
+ total_items.saturating_sub(idx),
+ );
+ break;
+ }
+ let item_len = item.chars().count();
+ let separator = usize::from(!out.is_empty());
+ if !out.is_empty()
+ && used_chars
+ .saturating_add(separator)
+ .saturating_add(item_len)
+ > total_max_chars
+ {
+ push_handoff_omission_marker(
+ &mut out,
+ &mut used_chars,
+ total_max_chars,
+ list_label,
+ total_items.saturating_sub(idx),
+ );
+ break;
+ }
+ used_chars = used_chars
+ .saturating_add(separator)
+ .saturating_add(item_len);
+ out.push(item);
+ }
+ out
+}
+
+fn push_handoff_omission_marker(
+ out: &mut Vec<String>,
+ used_chars: &mut usize,
+ total_max_chars: usize,
+ label: &str,
+ omitted: usize,
+) {
+ if omitted == 0 {
+ return;
+ }
+ let separator = usize::from(!out.is_empty());
+ let available = total_max_chars.saturating_sub(used_chars.saturating_add(separator));
+ if available == 0 {
+ return;
+ }
+ let marker = format!("[{label} truncated; {omitted} additional item(s) omitted]");
+ let marker: String = marker.chars().take(available).collect();
+ *used_chars = used_chars
+ .saturating_add(separator)
+ .saturating_add(marker.chars().count());
+ out.push(marker);
+}
+
/// Instructions surfaced to clients via `ServerInfo`. Sent on every
/// MCP handshake so Claude Code / Codex / OpenCode see this in their
/// session preamble. Maps conversational triggers to tool names so
@@ -1695,6 +1780,27 @@ impl AiMemoryServer {
&aps_actor,
)
.await?;
+ let open_questions = cap_handoff_list(
+ args.open_questions.iter().map(|q| s.scrub(q)),
+ HANDOFF_ITEM_MAX_CHARS,
+ HANDOFF_TEXT_LIST_MAX_CHARS,
+ "handoff item",
+ "handoff open_questions",
+ );
+ let next_steps = cap_handoff_list(
+ args.next_steps.iter().map(|n| s.scrub(n)),
+ HANDOFF_ITEM_MAX_CHARS,
+ HANDOFF_TEXT_LIST_MAX_CHARS,
+ "handoff item",
+ "handoff next_steps",
+ );
+ let files_touched = cap_handoff_list(
+ args.files_touched.iter().map(|f| s.scrub(f)),
+ HANDOFF_FILE_MAX_CHARS,
+ HANDOFF_FILE_LIST_MAX_CHARS,
+ "handoff file",
+ "handoff files_touched",
+ );
let handoff = NewHandoff {
workspace_id: ws,
project_id: proj,
@@ -1702,10 +1808,14 @@ impl AiMemoryServer {
from_agent: AgentKind::Other,
to_agent: None,
cwd: args.cwd.map(std::path::PathBuf::from),
- summary: s.scrub(&args.summary),
- open_questions: args.open_questions.iter().map(|q| s.scrub(q)).collect(),
- next_steps: args.next_steps.iter().map(|n| s.scrub(n)).collect(),
- files_touched: args.files_touched.iter().map(|f| s.scrub(f)).collect(),
+ summary: cap_text_with_marker(
+ &s.scrub(&args.summary),
+ HANDOFF_SUMMARY_MAX_CHARS,
+ "handoff summary",
+ ),
+ open_questions,
+ next_steps,
+ files_touched,
};
let id = self
.writer
@@ -4109,6 +4219,103 @@ mod tests {
assert!(again_text.contains("\"handoff\": null"));
}
+ #[tokio::test]
+ async fn handoff_begin_caps_manual_text_after_scrub() {
+ let (_tmp, _store, server, _ws, _pj) = setup_server().await;
+ server
+ .memory_handoff_begin(
+ Parameters(HandoffBeginArgs {
+ summary: "s".repeat(HANDOFF_SUMMARY_MAX_CHARS + 20),
+ open_questions: vec!["q".repeat(HANDOFF_ITEM_MAX_CHARS + 20)],
+ next_steps: vec!["n".repeat(HANDOFF_ITEM_MAX_CHARS + 20)],
+ files_touched: vec!["f".repeat(HANDOFF_FILE_MAX_CHARS + 20)],
+ cwd: Some("/tmp/aim".into()),
+ project: None,
+ workspace: None,
+ }),
+ rmcp::handler::server::tool::Extension(test_parts_default()),
+ )
+ .await
+ .unwrap();
+
+ let accept = server
+ .memory_handoff_accept(
+ Parameters(HandoffAcceptArgs {
+ cwd: Some("/tmp/aim".into()),
+ project: None,
+ workspace: None,
+ }),
+ rmcp::handler::server::tool::Extension(test_parts_default()),
+ )
+ .await
+ .unwrap();
+ let text = accept
+ .content
+ .first()
+ .and_then(|c| c.as_text())
+ .map(|t| t.text.clone())
+ .unwrap();
+ assert!(text.contains("handoff summary truncated"));
+ assert!(text.contains("handoff item truncated"));
+ assert!(text.contains("handoff file truncated"));
+ }
+
+ #[tokio::test]
+ async fn handoff_begin_caps_manual_lists_in_aggregate() {
+ let (_tmp, _store, server, _ws, _pj) = setup_server().await;
+ let open_questions = (0..100)
+ .map(|idx| format!("question-{idx}: {}", "q".repeat(400)))
+ .collect();
+ server
+ .memory_handoff_begin(
+ Parameters(HandoffBeginArgs {
+ summary: "contains sk-testsecret12345678901234567890 before cap".into(),
+ open_questions,
+ next_steps: vec![],
+ files_touched: vec![],
+ cwd: Some("/tmp/aim".into()),
+ project: None,
+ workspace: None,
+ }),
+ rmcp::handler::server::tool::Extension(test_parts_default()),
+ )
+ .await
+ .unwrap();
+
+ let accept = server
+ .memory_handoff_accept(
+ Parameters(HandoffAcceptArgs {
+ cwd: Some("/tmp/aim".into()),
+ project: None,
+ workspace: None,
+ }),
+ rmcp::handler::server::tool::Extension(test_parts_default()),
+ )
+ .await
+ .unwrap();
+ let text = accept
+ .content
+ .first()
+ .and_then(|c| c.as_text())
+ .map(|t| t.text.clone())
+ .unwrap();
+ assert!(text.contains("handoff open_questions truncated"));
+ assert!(!text.contains("sk-testsecret"));
+ }
+
+ #[test]
+ fn handoff_list_cap_keeps_marker_inside_total_budget() {
+ let items = (0..10).map(|idx| format!("item-{idx}: {}", "x".repeat(80)));
+ let capped = cap_handoff_list(items, 100, 220, "item", "list");
+ let rendered_len = capped
+ .iter()
+ .map(|item| item.chars().count())
+ .sum::<usize>()
+ .saturating_add(capped.len().saturating_sub(1));
+ assert!(rendered_len <= 220);
+ assert!(capped.iter().any(|item| item.contains("list truncated")));
+ }
+
#[tokio::test]
async fn handoff_begin_accept_honour_explicit_workspace() {
// Regression for the scope-bleed facet: memory_handoff_begin/accept used