Skip to content

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

Rust

fix(bootstrap): harden chunked bootstrap

AkitaOnRails4c6e6b6e6294
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 9810800d..81fa1214 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -7,6 +7,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
## [Unreleased]
### Added
+- `ai-memory bootstrap` now prunes collected sources before POSTing to the
+ server and supports `--chunk-input-tokens` to process large repositories via
+ sequential LLM calls instead of one oversized prompt.
- `.ai-memory.toml` marker file lets a directory tree declare its
`workspace` (required) and `project` (optional) without depending on
`basename($cwd)`. Lifecycle hook scripts walk up from `cwd` to find
diff --git a/crates/ai-memory-cli/src/commands/bootstrap.rs b/crates/ai-memory-cli/src/commands/bootstrap.rs
index b269e738..3a69f74c 100644
--- a/crates/ai-memory-cli/src/commands/bootstrap.rs
+++ b/crates/ai-memory-cli/src/commands/bootstrap.rs
@@ -86,8 +86,7 @@ pub async fn run(config: &Config, args: BootstrapArgs) -> Result<()> {
!args.exclude_code,
)?;
let collected = sources.len();
- let (sources, dropped, est_tokens) =
- prune_sources_to_budget(sources, args.max_input_tokens);
+ let (sources, dropped, est_tokens) = prune_sources_to_budget(sources, args.max_input_tokens);
let chunk_budget = ai_memory_consolidate::effective_chunk_budget(
args.chunk_input_tokens,
args.max_input_tokens,
@@ -119,6 +118,7 @@ pub async fn run(config: &Config, args: BootstrapArgs) -> Result<()> {
ensure_sources_for_dry_run(&sources)?;
let outcome = local_dry_run(
sources,
+ collected,
args.max_input_tokens,
args.chunk_input_tokens,
);
@@ -171,20 +171,19 @@ fn ensure_sources_for_dry_run(sources: &[BootstrapSource]) -> Result<()> {
/// preview of what would be sent.
fn local_dry_run(
sources: Vec<BootstrapSource>,
+ sources_collected: usize,
max_input_tokens: usize,
chunk_input_tokens: usize,
) -> BootstrapOutcome {
- let collected = sources.len();
- let (kept, dropped, est_tokens) = prune_sources_to_budget(sources, max_input_tokens);
+ let (kept, _dropped, est_tokens) = prune_sources_to_budget(sources, max_input_tokens);
let kept_counts = SourceCounts::from_sources(&kept);
let chunk_budget =
ai_memory_consolidate::effective_chunk_budget(chunk_input_tokens, max_input_tokens);
- let llm_chunks =
- ai_memory_consolidate::plan_bootstrap_chunks(kept.clone(), chunk_budget).len();
+ let llm_chunks = ai_memory_consolidate::plan_bootstrap_chunks(kept.clone(), chunk_budget).len();
BootstrapOutcome {
- sources_collected: collected,
+ sources_collected,
sources_sent: kept.len(),
- sources_dropped: dropped,
+ sources_dropped: sources_collected.saturating_sub(kept.len()),
sources_by_kind: kept_counts,
estimated_input_tokens: est_tokens,
pages_written: Vec::new(),
@@ -257,7 +256,11 @@ fn print_human_report(outcome: &BootstrapOutcome, workspace: &str, project: &str
}
);
if outcome.llm_chunks > 1 {
- println!(" -> {} sequential LLM chunk{}", outcome.llm_chunks, if outcome.llm_chunks == 1 { "" } else { "s" });
+ println!(
+ " -> {} sequential LLM chunk{}",
+ outcome.llm_chunks,
+ if outcome.llm_chunks == 1 { "" } else { "s" }
+ );
}
if outcome.dry_run {
@@ -310,6 +313,7 @@ mod tests {
// so the lowest input we can hand the helper is one source.
let outcome = local_dry_run(
vec![source(SourceKind::Readme, "README", 50)],
+ 1,
150_000,
ai_memory_consolidate::DEFAULT_CHUNK_INPUT_TOKENS,
);
@@ -330,6 +334,7 @@ mod tests {
];
let outcome = local_dry_run(
sources,
+ 4,
150_000,
ai_memory_consolidate::DEFAULT_CHUNK_INPUT_TOKENS,
);
@@ -375,6 +380,7 @@ mod tests {
.collect();
let outcome = local_dry_run(
sources,
+ 30,
2_000,
ai_memory_consolidate::DEFAULT_CHUNK_INPUT_TOKENS,
);
@@ -388,4 +394,17 @@ mod tests {
);
assert!(outcome.dry_run);
}
+
+ #[test]
+ fn local_dry_run_preserves_pre_prune_collected_count() {
+ let outcome = local_dry_run(
+ vec![source(SourceKind::Readme, "README", 50)],
+ 10,
+ 150_000,
+ ai_memory_consolidate::DEFAULT_CHUNK_INPUT_TOKENS,
+ );
+ assert_eq!(outcome.sources_collected, 10);
+ assert_eq!(outcome.sources_sent, 1);
+ assert_eq!(outcome.sources_dropped, 9);
+ }
}
diff --git a/crates/ai-memory-cli/src/commands/serve.rs b/crates/ai-memory-cli/src/commands/serve.rs
index 344213d1..08d3124a 100644
--- a/crates/ai-memory-cli/src/commands/serve.rs
+++ b/crates/ai-memory-cli/src/commands/serve.rs
@@ -194,9 +194,7 @@ pub async fn run(config: &Config, args: ServeArgs) -> Result<()> {
.nest_service("/mcp", mcp_service)
.merge(hooks)
.layer(DefaultBodyLimit::max(MAX_BODY_BYTES))
- .merge(
- admin.layer(DefaultBodyLimit::max(BOOTSTRAP_MAX_BODY_BYTES)),
- );
+ .merge(admin.layer(DefaultBodyLimit::max(BOOTSTRAP_MAX_BODY_BYTES)));
let router =
mount_web_router(router, args.enable_web, store.reader.clone(), wiki.clone());
let router = apply_http_layers(router, auth_state, config.allowed_hosts.clone());
diff --git a/crates/ai-memory-consolidate/src/bootstrap.rs b/crates/ai-memory-consolidate/src/bootstrap.rs
index 3b1ba55d..3f2e3c51 100644
--- a/crates/ai-memory-consolidate/src/bootstrap.rs
+++ b/crates/ai-memory-consolidate/src/bootstrap.rs
@@ -347,14 +347,9 @@ impl Bootstrap {
// ---- LLM call(s) — chunked when over chunk_input_tokens ----
let chunks = plan_bootstrap_chunks(kept, chunk_budget);
let llm_chunks = chunks.len();
- info!(
- llm_chunks,
- chunk_budget,
- "bootstrap LLM chunk plan",
- );
+ info!(llm_chunks, chunk_budget, "bootstrap LLM chunk plan",);
- let mut pages_by_path: std::collections::HashMap<String, BootstrapPage> =
- std::collections::HashMap::new();
+ let mut pages_by_path = std::collections::BTreeMap::new();
let mut rationales = Vec::with_capacity(llm_chunks);
for (idx, chunk) in chunks.iter().enumerate() {
@@ -366,18 +361,20 @@ impl Bootstrap {
chunk = idx + 1,
total = llm_chunks,
sources = chunk.len(),
- est_tokens = chunk.iter().map(BootstrapSource::estimated_tokens).sum::<usize>(),
+ est_tokens = chunk
+ .iter()
+ .map(BootstrapSource::estimated_tokens)
+ .sum::<usize>(),
"bootstrap LLM chunk",
);
let batch: BootstrapBatch = complete_structured(&*self.llm, request).await?;
rationales.push(batch.rationale);
for page in batch.pages {
- pages_by_path.insert(page.path.clone(), page);
+ insert_bootstrap_page(&mut pages_by_path, page, idx + 1);
}
}
- let mut merged_pages: Vec<BootstrapPage> = pages_by_path.into_values().collect();
- merged_pages.sort_by(|a, b| a.path.cmp(&b.path));
+ let merged_pages: Vec<BootstrapPage> = pages_by_path.into_values().collect();
let rationale = if rationales.len() == 1 {
rationales.pop().unwrap_or_default()
} else {
@@ -412,16 +409,16 @@ impl Bootstrap {
});
}
// Plus the manifest itself.
- let manifest_body = render_manifest_body(
+ let manifest_body = render_manifest_body(ManifestRender {
now,
- collected,
+ sources_collected: collected,
sources_sent,
sources_dropped,
est_tokens,
- &rationale,
- &written_paths,
+ rationale: &rationale,
+ pages: &written_paths,
llm_chunks,
- );
+ });
requests.push(WritePageRequest {
workspace_id: cfg.workspace_id,
project_id: cfg.project_id,
@@ -849,17 +846,18 @@ pub fn plan_bootstrap_chunks(
}
/// Pack sources into chunks ≤ `usable` estimated tokens (best sources first).
-fn chunk_sources_greedy(
- sources: Vec<BootstrapSource>,
- usable: usize,
-) -> Vec<Vec<BootstrapSource>> {
+fn chunk_sources_greedy(sources: Vec<BootstrapSource>, usable: usize) -> Vec<Vec<BootstrapSource>> {
let mut chunks: Vec<Vec<BootstrapSource>> = Vec::new();
let mut current: Vec<BootstrapSource> = Vec::new();
let mut current_tokens = 0usize;
// After prune, low drop_priority (README, rules) sit at the end — process
// those first so early chunks carry the highest-signal material.
- for src in sources.into_iter().rev() {
+ for src in sources
+ .into_iter()
+ .rev()
+ .flat_map(|src| split_oversized_source(src, usable))
+ {
let t = src.estimated_tokens();
if !current.is_empty() && current_tokens.saturating_add(t) > usable {
chunks.push(current);
@@ -875,6 +873,40 @@ fn chunk_sources_greedy(
chunks
}
+fn split_oversized_source(source: BootstrapSource, usable: usize) -> Vec<BootstrapSource> {
+ if usable == 0 || source.estimated_tokens() <= usable {
+ return vec![source];
+ }
+
+ let BootstrapSource { kind, label, text } = source;
+ let max_text_chars = usable
+ .saturating_mul(CHARS_PER_TOKEN)
+ .saturating_sub(label.len().saturating_add(64))
+ .max(CHARS_PER_TOKEN);
+ let mut parts = Vec::new();
+ let mut start = 0usize;
+ while start < text.len() {
+ let mut end = start.saturating_add(max_text_chars).min(text.len());
+ while end > start && !text.is_char_boundary(end) {
+ end -= 1;
+ }
+ if end == start {
+ end = text[start..]
+ .char_indices()
+ .nth(1)
+ .map_or(text.len(), |(idx, _)| start + idx);
+ }
+ let part_no = parts.len() + 1;
+ parts.push(BootstrapSource {
+ kind,
+ label: format!("{label} (part {part_no})"),
+ text: text[start..end].to_string(),
+ });
+ start = end;
+ }
+ parts
+}
+
// --------------------------------------------------------------------
// LLM prompt
// --------------------------------------------------------------------
@@ -956,6 +988,22 @@ fn parse_decision_serial(path: &str) -> Option<u32> {
digits.parse().ok()
}
+fn insert_bootstrap_page(
+ pages_by_path: &mut std::collections::BTreeMap<String, BootstrapPage>,
+ page: BootstrapPage,
+ chunk_index: usize,
+) {
+ if pages_by_path.contains_key(&page.path) {
+ warn!(
+ path = %page.path,
+ chunk = chunk_index,
+ "skipping duplicate bootstrap page path from later chunk"
+ );
+ return;
+ }
+ pages_by_path.insert(page.path.clone(), page);
+}
+
// --------------------------------------------------------------------
// Manifest rendering
// --------------------------------------------------------------------
@@ -969,16 +1017,28 @@ fn build_frontmatter(title: &str, tags: &[String], now: Timestamp) -> serde_json
})
}
-fn render_manifest_body(
+struct ManifestRender<'a> {
now: Timestamp,
sources_collected: usize,
sources_sent: usize,
sources_dropped: usize,
est_tokens: usize,
- rationale: &str,
- pages: &[String],
+ rationale: &'a str,
+ pages: &'a [String],
llm_chunks: usize,
-) -> String {
+}
+
+fn render_manifest_body(input: ManifestRender<'_>) -> String {
+ let ManifestRender {
+ now,
+ sources_collected,
+ sources_sent,
+ sources_dropped,
+ est_tokens,
+ rationale,
+ pages,
+ llm_chunks,
+ } = input;
let mut buf = String::with_capacity(1024);
buf.push_str("# Bootstrap manifest\n\n");
buf.push_str(&format!(
@@ -1183,6 +1243,28 @@ mod tests {
}
}
+ #[test]
+ fn plan_chunks_splits_single_oversized_source() {
+ let source = BootstrapSource {
+ kind: SourceKind::DocFile,
+ label: "docs/huge.md".into(),
+ text: "x".repeat(100_000),
+ };
+ let chunks = plan_bootstrap_chunks(vec![source], 8_000);
+ assert!(chunks.len() > 1, "one large file should be split");
+ for chunk in &chunks {
+ let t: usize = chunk.iter().map(BootstrapSource::estimated_tokens).sum();
+ assert!(t <= 8_000, "chunk should respect budget; got {t}");
+ }
+ assert!(
+ chunks
+ .iter()
+ .flatten()
+ .any(|source| source.label.contains("(part 2)")),
+ "split labels should identify later parts"
+ );
+ }
+
#[test]
fn plan_chunks_zero_disables() {
let s = BootstrapSource {
@@ -1207,6 +1289,34 @@ mod tests {
assert_eq!(dropped, 27_872);
}
+ #[test]
+ fn duplicate_page_paths_keep_first_page() {
+ let mut pages = std::collections::BTreeMap::new();
+ insert_bootstrap_page(
+ &mut pages,
+ BootstrapPage {
+ path: "concepts/runtime.md".into(),
+ title: "Runtime".into(),
+ body_markdown: "first".into(),
+ tags: vec![],
+ },
+ 1,
+ );
+ insert_bootstrap_page(
+ &mut pages,
+ BootstrapPage {
+ path: "concepts/runtime.md".into(),
+ title: "Runtime duplicate".into(),
+ body_markdown: "second".into(),
+ tags: vec![],
+ },
+ 2,
+ );
+
+ assert_eq!(pages.len(), 1);
+ assert_eq!(pages["concepts/runtime.md"].body_markdown, "first");
+ }
+
#[test]
fn effective_chunk_budget_clamps_to_max() {
assert_eq!(effective_chunk_budget(50_000, 24_000), 24_000);
@@ -1215,7 +1325,11 @@ mod tests {
#[test]
fn next_decision_serial_continues_across_chunks() {
- let paths = ["concepts/foo.md", "decisions/0003-old.md", "decisions/0001-first.md"];
+ let paths = [
+ "concepts/foo.md",
+ "decisions/0003-old.md",
+ "decisions/0001-first.md",
+ ];
assert_eq!(next_decision_serial(&paths), 4);
assert_eq!(next_decision_serial(&[]), 1);
}
diff --git a/crates/ai-memory-consolidate/src/lib.rs b/crates/ai-memory-consolidate/src/lib.rs
index 7e1e11dc..f026881f 100644
--- a/crates/ai-memory-consolidate/src/lib.rs
+++ b/crates/ai-memory-consolidate/src/lib.rs
@@ -15,8 +15,8 @@ pub mod sweep;
pub mod types;
pub use bootstrap::{
- Bootstrap, BootstrapConfig, BootstrapError, BootstrapOutcome, BootstrapSource, SourceCounts,
- SourceKind, DEFAULT_CHUNK_INPUT_TOKENS, collect_sources, discover_repo_root,
+ Bootstrap, BootstrapConfig, BootstrapError, BootstrapOutcome, BootstrapSource,
+ DEFAULT_CHUNK_INPUT_TOKENS, SourceCounts, SourceKind, collect_sources, discover_repo_root,
effective_chunk_budget, plan_bootstrap_chunks, prune_sources_to_budget,
};
pub use consolidator::{
diff --git a/crates/ai-memory-mcp/src/admin.rs b/crates/ai-memory-mcp/src/admin.rs
index edd4c6b9..af4558eb 100644
--- a/crates/ai-memory-mcp/src/admin.rs
+++ b/crates/ai-memory-mcp/src/admin.rs
@@ -536,12 +536,9 @@ fn dry_run_outcome(
let sources_sent = kept.len();
let sources_dropped = collected.saturating_sub(sources_sent);
let counts = SourceCounts::from_sources(&kept);
- let chunk_budget = ai_memory_consolidate::effective_chunk_budget(
- chunk_input_tokens,
- max_input_tokens,
- );
- let llm_chunks =
- ai_memory_consolidate::plan_bootstrap_chunks(kept.clone(), chunk_budget).len();
+ let chunk_budget =
+ ai_memory_consolidate::effective_chunk_budget(chunk_input_tokens, max_input_tokens);
+ let llm_chunks = ai_memory_consolidate::plan_bootstrap_chunks(kept.clone(), chunk_budget).len();
let outcome = BootstrapOutcome {
sources_collected: collected,
sources_sent,