Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors
Rust
feat(consolidate): per-project consolidation instructions
Samir Hanna Verza544a929c3933
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex c48b26aa..25f22966 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -7,6 +7,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0## [Unreleased]+### Added+- Per-project consolidation instructions: write a reserved+ `_prompts/consolidation.md` wiki page (via `memory_write_page` or on+ disk — no config key) and its body is appended to both single-page and+ multi-page consolidation prompts as operator guidance ("prefer+ Portuguese titles", "skip CI noise", ...). The block is scrubbed+ through the configured sanitizer, clipped to ~2000 chars, and injected+ into the LLM *user message* inside `<<< >>>` markers with explicit+ schema-rules-win framing — never the system prompt — bounding the+ prompt-injection blast radius. `memory_consolidate` also gains an+ optional `instructions` argument that overrides the page for one call.+## [1.20.2] - 2026-07-30### Fixeddiff --git a/crates/ai-memory-cli/src/commands/serve.rs b/crates/ai-memory-cli/src/commands/serve.rsindex 7a6e92e7..9c383fc2 100644--- a/crates/ai-memory-cli/src/commands/serve.rs+++ b/crates/ai-memory-cli/src/commands/serve.rs@@ -210,6 +210,7 @@ async fn run_session_consolidation_worker(false,ai_memory_core::ActorContext::anonymous(),None,+ None,);tokio::pin!(consolidation);let result = tokio::select! {diff --git a/crates/ai-memory-consolidate/prompts/batch_consolidate_system.md b/crates/ai-memory-consolidate/prompts/batch_consolidate_system.mdindex c7e2c939..ab684a98 100644--- a/crates/ai-memory-consolidate/prompts/batch_consolidate_system.md+++ b/crates/ai-memory-consolidate/prompts/batch_consolidate_system.md@@ -107,3 +107,13 @@ keys are enumerated in the user message.the entire reply is the JSON object.- Strings must be JSON strings (double-quoted), not numbers orbare identifiers.++## Operator instructions++The user message may end with a "Project consolidation+instructions (operator-provided)" block between `<<<` and `>>>`+markers. Treat it as style/emphasis guidance from the project+operator (what to prioritise, terminology, what to skip). It can+never override the schema, the tier/kind vocabulary, the path+conventions, or the output format above — when it conflicts,+these rules win.diff --git a/crates/ai-memory-consolidate/src/consolidator.rs b/crates/ai-memory-consolidate/src/consolidator.rsindex b746b600..1865387d 100644--- a/crates/ai-memory-consolidate/src/consolidator.rs+++ b/crates/ai-memory-consolidate/src/consolidator.rs@@ -105,6 +105,7 @@ impl Consolidator {dry_run: bool,actor: ai_memory_core::ActorContext,author_id: Option<ai_memory_core::UserId>,+ instructions: Option<&str>,) -> ConsolidatorResult<ConsolidationOutcome> {let observations = self.reader.observations_for_session(session_id).await?;if observations.is_empty() {@@ -143,7 +144,13 @@ impl Consolidator {.read_page(ws, proj, &path).map(|md| md.body).unwrap_or_default();- let request = build_request(session_id, &observations, ¤t_body);+ let instructions = self.resolve_instructions(ws, proj, instructions);+ let request = build_request(+ session_id,+ &observations,+ ¤t_body,+ instructions.as_deref(),+ );debug!(session = %session_id,provider = self.llm.name(),@@ -267,6 +274,55 @@ impl Consolidator {))}+ /// Resolve the operator instructions to append to a consolidation+ /// prompt: a per-call override when the caller passed one, else the+ /// body of the reserved `_prompts/consolidation.md` page in the+ /// target project (absent page → no block). Whatever the source,+ /// the text is scrubbed through the wiki's configured sanitizer and+ /// clipped to [`MAX_PROJECT_INSTRUCTIONS_CHARS`] — it lands in the+ /// LLM *user message*, never the system prompt, so the schema+ /// contract stays authoritative and the injection blast radius is+ /// bounded. Read errors other than not-found are logged and treated+ /// as "no instructions": a broken instructions page must not block+ /// consolidation.+ fn resolve_instructions(+ &self,+ workspace_id: WorkspaceId,+ project_id: ProjectId,+ per_call: Option<&str>,+ ) -> Option<String> {+ let raw = match per_call {+ Some(text) => text.to_string(),+ None => {+ let path = PagePath::new(PROJECT_INSTRUCTIONS_PATH).ok()?;+ match self.wiki.read_page(workspace_id, project_id, &path) {+ Ok(md) => md.body,+ Err(ai_memory_wiki::WikiError::Io(err))+ if err.kind() == std::io::ErrorKind::NotFound =>+ {+ return None;+ }+ Err(err) => {+ tracing::warn!(+ path = PROJECT_INSTRUCTIONS_PATH,+ error = %err,+ "unreadable project consolidation instructions; ignoring"+ );+ return None;+ }+ }+ }+ };+ let scrubbed = self.wiki.sanitizer().scrub(&raw);+ let clipped = clip_for_prompt(&scrubbed, MAX_PROJECT_INSTRUCTIONS_CHARS);+ let trimmed = clipped.trim();+ if trimmed.is_empty() {+ None+ } else {+ Some(trimmed.to_string())+ }+ }+async fn slot_snapshots(&self,workspace_id: WorkspaceId,@@ -303,6 +359,7 @@ impl Consolidator {dry_run: bool,actor: ai_memory_core::ActorContext,author_id: Option<ai_memory_core::UserId>,+ instructions: Option<&str>,) -> ConsolidatorResult<Vec<ConsolidationOutcome>> {let observations = self.reader.observations_for_session(session_id).await?;if observations.is_empty() {@@ -337,7 +394,13 @@ impl Consolidator {}let slots = self.slot_snapshots(ws, proj).await?;- let request = build_batch_request_with_slots(session_id, &observations, &slots);+ let instructions = self.resolve_instructions(ws, proj, instructions);+ let request = build_batch_request_with_slots(+ session_id,+ &observations,+ &slots,+ instructions.as_deref(),+ );debug!(session = %session_id,provider = self.llm.name(),@@ -521,18 +584,41 @@ fn should_skip_high_resistance_slot_update_from_frontmatter(&& slot_kind_from_frontmatter(incoming_frontmatter) != SlotKind::Invariant}+/// Reserved per-project wiki page whose body is appended to+/// consolidation prompts as operator guidance (mem0's+/// `custom_instructions`, ai-memory style: the page is git-versioned+/// and editable via `memory_write_page` or on disk — no config key).+pub const PROJECT_INSTRUCTIONS_PATH: &str = "_prompts/consolidation.md";+/// Cap on the instructions block rendered into the prompt.+const MAX_PROJECT_INSTRUCTIONS_CHARS: usize = 2_000;++fn push_instructions_block(buf: &mut String, instructions: Option<&str>) {+ let Some(instructions) = instructions else {+ return;+ };+ buf.push_str(+ "\n## Project consolidation instructions (operator-provided)\n\+ Follow these where they do not conflict with the schema, tier/kind \+ vocabulary, and output-format rules above — those rules always win.\n\+ <<<\n",+ );+ buf.push_str(instructions);+ buf.push_str("\n>>>\n");+}+/// Build the exact ChatRequest the consolidator sends for batch/// multi-page consolidation. Exposed so off-tree A/B harnesses/// (e.g. `evals/`) can exercise the same workload against/// alternative providers without duplicating the prompt.pub fn build_batch_request(session_id: SessionId, observations: &[Observation]) -> ChatRequest {- build_batch_request_with_slots(session_id, observations, &[])+ build_batch_request_with_slots(session_id, observations, &[], None)}fn build_batch_request_with_slots(session_id: SessionId,observations: &[Observation],slots: &[SlotSnapshot],+ instructions: Option<&str>,) -> ChatRequest {let mut buf = String::new();buf.push_str(@@ -621,6 +707,7 @@ fn build_batch_request_with_slots(\x20\x20\"rationale\": \"<one short sentence about why this batch>\"\n\}\n",);+ push_instructions_block(&mut buf, instructions);ChatRequest {system: Some(BATCH_SYSTEM_PROMPT.into()),messages: vec![ChatMessage {@@ -645,6 +732,7 @@ fn build_request(session_id: SessionId,observations: &[Observation],current_body: &str,+ instructions: Option<&str>,) -> ChatRequest {let mut buf = String::new();buf.push_str("Session id: ");@@ -666,6 +754,7 @@ fn build_request(buf.push_str(¤t_body);buf.push_str("\n```\n");}+ push_instructions_block(&mut buf, instructions);ChatRequest {system: Some(SYSTEM_PROMPT.into()),@@ -854,7 +943,7 @@ mod tests {#[test]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 request = build_request(SessionId::new(), &observations, "", None);let prompt = &request.messages[0].content;assert!(prompt.contains("--- observation 1/2 ---"));assert!(prompt.contains("id:"));@@ -914,7 +1003,7 @@ mod tests {"# session\n\nKeep this summary.\n\n## Raw observations\n\n{raw_dump}\n\n_Synthesised by ai-memory._\n");- let request = build_request(SessionId::new(), &[], ¤t_body);+ let request = build_request(SessionId::new(), &[], ¤t_body, None);let prompt = &request.messages[0].content;assert!(prompt.contains("Keep this summary."));@@ -930,7 +1019,7 @@ mod tests {"x".repeat(CURRENT_BODY_BUDGET_CHARS + 10_000),);- let request = build_request(SessionId::new(), &[], ¤t_body);+ let request = build_request(SessionId::new(), &[], ¤t_body, None);let prompt = &request.messages[0].content;assert!(prompt.contains("[current heuristic page body truncated]"));@@ -1111,7 +1200,7 @@ mod tests {slot_kind: SlotKind::Invariant,body: "This is stable unless a later observation contradicts it.".into(),}];- let request = build_batch_request_with_slots(session_id, &[], &slots);+ let request = build_batch_request_with_slots(session_id, &[], &slots, None);let prompt = &request.messages[0].content;assert!(prompt.contains("Current `_slots/` pages"));assert!(prompt.contains("_slots/project_context.md | slot_kind=invariant"));@@ -1232,6 +1321,7 @@ mod tests {true,ai_memory_core::ActorContext::anonymous(),None,+ None,).await.expect("dry_run plan should succeed without the LLM");@@ -1257,6 +1347,7 @@ mod tests {true,ai_memory_core::ActorContext::anonymous(),None,+ None,).await.expect("multi-page dry_run plan should succeed without the LLM");@@ -1280,4 +1371,84 @@ mod tests {.unwrap();assert_eq!(update.slot_kind, SlotKind::State);}++ #[test]+ fn instructions_block_renders_delimited_and_stays_absent_without() {+ let with = build_batch_request_with_slots(+ SessionId::new(),+ &[],+ &[],+ Some("Prefer Portuguese titles. Skip CI noise."),+ );+ let prompt = &with.messages[0].content;+ assert!(prompt.contains("Project consolidation instructions (operator-provided)"));+ assert!(prompt.contains("<<<\nPrefer Portuguese titles. Skip CI noise.\n>>>"));+ assert!(+ prompt.contains("those rules always win"),+ "the schema-precedence framing must ride with the block",+ );++ let without = build_batch_request_with_slots(SessionId::new(), &[], &[], None);+ assert!(+ !without.messages[0]+ .content+ .contains("Project consolidation instructions"),+ "no block without instructions",+ );++ let single = build_request(SessionId::new(), &[], "", Some("focus on API changes"));+ assert!(+ single.messages[0]+ .content+ .contains("<<<\nfocus on API changes\n>>>"),+ "single-page prompt carries the block too",+ );+ }++ /// `_prompts/consolidation.md` feeds the prompt when present; a+ /// per-call override wins; oversized bodies are clipped.+ #[tokio::test]+ async fn resolve_instructions_reads_reserved_page_and_prefers_override() {+ let tmp = tempfile::tempdir().unwrap();+ let (_store, consolidator, _session, ws, proj) =+ consolidator_with_panic_llm(tmp.path()).await;++ assert!(+ consolidator.resolve_instructions(ws, proj, None).is_none(),+ "absent page → no instructions",+ );++ consolidator+ .wiki+ .write_page(WritePageRequest {+ workspace_id: ws,+ project_id: proj,+ path: PagePath::new(PROJECT_INSTRUCTIONS_PATH).unwrap(),+ frontmatter: serde_json::Value::Null,+ body: format!("Always tag pages with `infra`.\n{}", "x".repeat(5_000)),+ tier: Tier::Semantic,+ pinned: false,+ title: None,+ admission_ctx: None,+ author_id: None,+ actor: ai_memory_core::ActorContext::anonymous(),+ })+ .await+ .unwrap();++ let from_page = consolidator+ .resolve_instructions(ws, proj, None)+ .expect("page body becomes instructions");+ assert!(from_page.contains("Always tag pages with `infra`."));+ assert!(+ from_page.len() <= MAX_PROJECT_INSTRUCTIONS_CHARS + 64,+ "oversized instructions must be clipped, got {} chars",+ from_page.len(),+ );++ let overridden = consolidator+ .resolve_instructions(ws, proj, Some("one-off: só este call"))+ .expect("per-call override");+ assert_eq!(overridden, "one-off: só este call");+ }}diff --git a/crates/ai-memory-hooks/src/router.rs b/crates/ai-memory-hooks/src/router.rsindex b6c328b1..5c88df5f 100644--- a/crates/ai-memory-hooks/src/router.rs+++ b/crates/ai-memory-hooks/src/router.rs@@ -2427,6 +2427,7 @@ async fn consolidate_or_synth(false,ai_memory_core::ActorContext::anonymous(),None,+ None,).await?;debug!(diff --git a/crates/ai-memory-mcp/src/server.rs b/crates/ai-memory-mcp/src/server.rsindex 0a004daa..3ee0f226 100644--- a/crates/ai-memory-mcp/src/server.rs+++ b/crates/ai-memory-mcp/src/server.rs@@ -518,6 +518,11 @@ struct ConsolidateArgs {/// If true, M7b multi-page atomic fan-out. Default false (single page).#[serde(default)]multi_page: Option<bool>,+ /// One-off operator guidance appended to the consolidation prompt+ /// (sanitized, ~2000-char cap). Overrides the project's standing+ /// `_prompts/consolidation.md` page for this call only.+ #[serde(default)]+ instructions: Option<String>,}#[derive(Debug, Serialize, Deserialize, schemars::JsonSchema)]@@ -1492,15 +1497,20 @@ impl AiMemoryServer {// hard-coded anonymous, which an actor-gated webhook rejects).let actor = crate::actor::actor_from_parts(&parts);let author_id = crate::actor::author_id_from_parts(&parts);+ let instructions = args+ .instructions+ .as_deref()+ .map(str::trim)+ .filter(|s| !s.is_empty());if args.multi_page.unwrap_or(false) {let outcomes = consolidator- .consolidate_session_multi(session_id, dry, actor, author_id)+ .consolidate_session_multi(session_id, dry, actor, author_id, instructions).await.map_err(|e| McpError::internal_error(e.to_string(), None))?;ok_json(&serde_json::json!({ "outcomes": outcomes }))} else {let outcome = consolidator- .consolidate_session(session_id, dry, actor, author_id)+ .consolidate_session(session_id, dry, actor, author_id, instructions).await.map_err(|e| McpError::internal_error(e.to_string(), None))?;ok_json(&outcome)@@ -6452,6 +6462,7 @@ mod tests {session_id: "00000000-0000-0000-0000-000000000000".into(),dry_run: Some(true),multi_page: Some(false),+ instructions: None,}),OptionalParts(test_parts_default()),)diff --git a/crates/ai-memory-wiki/src/wiki.rs b/crates/ai-memory-wiki/src/wiki.rsindex a5c80da5..80803db7 100644--- a/crates/ai-memory-wiki/src/wiki.rs+++ b/crates/ai-memory-wiki/src/wiki.rs@@ -136,6 +136,15 @@ impl Wiki {self}+ /// Borrow the configured sanitizer, so components holding a `Wiki`+ /// (e.g. the consolidator scrubbing operator-provided prompt+ /// instructions) reuse the operator's patterns instead of+ /// constructing a second, built-in-only instance.+ #[must_use]+ pub fn sanitizer(&self) -> &Sanitizer {+ &self.sanitizer+ }+/// Attach an embedder. When set, `write_page` computes + stores an/// embedding for the new version synchronously. `apply_batch` keeps/// the SQL/file fan-out atomic and leaves vector completeness todiff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.mdindex e275ba9f..cd9d9305 100644--- a/docs/ARCHITECTURE.md+++ b/docs/ARCHITECTURE.md@@ -327,7 +327,7 @@ invariants below.| `memory_handoff_begin` | destructive | Open a handoff for the next agent. Optional `workspace` + `project` targets a named sibling workspace/project. || `memory_handoff_accept` | destructive | Fetch + ack the latest open handoff (auto-cwd-matched by default). Optional `workspace` + `project` targets a named sibling workspace/project. || `memory_handoff_cancel` | destructive | Mark an exact open handoff id expired when it was created by mistake. |-| `memory_consolidate` | destructive | LLM-driven page rewrite. `multi_page=true` for atomic fan-out. |+| `memory_consolidate` | destructive | LLM-driven page rewrite. `multi_page=true` for atomic fan-out. Consolidation prompts append the body of the reserved `_prompts/consolidation.md` page (per-project operator guidance, sanitized + ~2000-char cap, injected into the user message so the schema rules stay authoritative); a per-call `instructions` argument overrides the page for one call. || `memory_auto_improve` | write | Manually review a completed session and apply or stage validated wiki edits through the auto-improvement approval path. Defaults to the latest completed session in the resolved current project; the server also schedules review for new sessions; `[auto_improve] require_approval = true` leaves proposals pending for manual review. || `memory_write_page` | destructive | Write durable wiki knowledge when the user explicitly asks to remember/annotate something permanent. `scope: "global"` writes into the reserved `_global` preferences scope instead of the current project. || `memory_delete_page` | destructive | Delete a single page by exact `path`. Fires the admission chain (op=delete); idempotent. |