Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors
Rust
feat(briefing): opt-in settled-knowledge boot surfacing (P4)
AkitaOnRailsaaffd5406bca
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 048cfeda..6598d3ce 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -110,6 +110,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0this release, not a ranking input. The confidence-into-`PageAuthority`step described in the design doc is deferred behind the planned R2retrieval eval.+- Standing-answer boot surfacing (P4, `docs/design-hindsight-borrowings.md`+ §5): `memory_briefing` accepts an opt-in `settled_first: bool` (default+ `false`, unchanged briefing shape). When `true`, the snapshot's new+ `settled` array leads with the project's highest-standing `rule`/`decision`+ pages — up to 8, ordered by `page_evidence` count (P2) then recency — so an+ agent can boot from settled answers instead of re-deriving them. Pure SQL,+ no LLM call; every other briefing field, and the default `settled_first:+ false` path, are byte-for-byte unchanged.### Changed- The privacy sanitizer now redacts to a **typed marker** — `[REDACTED:<kind>]`diff --git a/crates/ai-memory-consolidate/src/auto_improve.rs b/crates/ai-memory-consolidate/src/auto_improve.rsindex 48590319..166b824e 100644--- a/crates/ai-memory-consolidate/src/auto_improve.rs+++ b/crates/ai-memory-consolidate/src/auto_improve.rs@@ -473,6 +473,7 @@ pub async fn run_auto_improve_review(100,// Internal review pass: the pending-handoff count is not surfaced.ai_memory_core::OwnerFilter::Any,+ false,).await?;let session_page_path = format!("sessions/{session_id}.md");diff --git a/crates/ai-memory-consolidate/src/consolidator.rs b/crates/ai-memory-consolidate/src/consolidator.rsindex 85f621b7..21c648b8 100644--- a/crates/ai-memory-consolidate/src/consolidator.rs+++ b/crates/ai-memory-consolidate/src/consolidator.rs@@ -408,6 +408,7 @@ impl Consolidator {// surfaced from here, so no owner scoping applies.ai_memory_core::OwnerFilter::Any,&visibility,+ false,).await?;let mut slots = Vec::with_capacity(briefing.slots.len());diff --git a/crates/ai-memory-consolidate/src/experience.rs b/crates/ai-memory-consolidate/src/experience.rsindex 7a66fee5..d901e628 100644--- a/crates/ai-memory-consolidate/src/experience.rs+++ b/crates/ai-memory-consolidate/src/experience.rs@@ -120,6 +120,7 @@ pub async fn run_experience_review(project_id,100,ai_memory_core::OwnerFilter::Any,+ false,).await?;let patchable_pages = load_patchable_pages(diff --git a/crates/ai-memory-hooks/src/router.rs b/crates/ai-memory-hooks/src/router.rsindex cae2a3de..0f91a606 100644--- a/crates/ai-memory-hooks/src/router.rs+++ b/crates/ai-memory-hooks/src/router.rs@@ -4857,7 +4857,7 @@ mod tests {let briefing = state.reader- .briefing_for_project(ws, proj, 1, ai_memory_core::OwnerFilter::Any)+ .briefing_for_project(ws, proj, 1, ai_memory_core::OwnerFilter::Any, false).await.unwrap();assert_eq!(@@ -7422,6 +7422,7 @@ mod tests {state.project_id,1,ai_memory_core::OwnerFilter::Any,+ false,).await.unwrap()@@ -7469,7 +7470,8 @@ mod tests {state.workspace_id,state.project_id,1,- ai_memory_core::OwnerFilter::Any+ ai_memory_core::OwnerFilter::Any,+ false).await.unwrap()@@ -9636,6 +9638,7 @@ mod tests {project_id,1,ai_memory_core::OwnerFilter::Any,+ false,).await.unwrap();diff --git a/crates/ai-memory-mcp/src/server.rs b/crates/ai-memory-mcp/src/server.rsindex 34ef4df1..0cb15c58 100644--- a/crates/ai-memory-mcp/src/server.rs+++ b/crates/ai-memory-mcp/src/server.rs@@ -1105,6 +1105,11 @@ struct BriefingArgs {/// omit both for the current project; static MCP clients must pass both.#[serde(default)]workspace: Option<String>,+ /// Lead the briefing with the project's settled rule/decision pages+ /// (highest-standing, ordered by evidence then recency). Default `false`+ /// leaves the briefing shape unchanged.+ #[serde(default)]+ settled_first: Option<bool>,}#[derive(Debug, Serialize, Deserialize, schemars::JsonSchema)]@@ -3875,7 +3880,9 @@ impl AiMemoryServer {deterministic, and READ-ONLY: it never creates handoffs or mutates \project state. Use this when you want a programmatic view of \project state; use `memory_explore` if you want an LLM-composed \- prose summary on top of the same data.")]+ prose summary on top of the same data. Pass `settled_first: true` \+ to also lead the briefing with the project's settled rule/decision \+ pages (highest-standing, ordered by evidence then recency).")]async fn memory_briefing(&self,Parameters(args): Parameters<BriefingArgs>,@@ -3883,6 +3890,7 @@ impl AiMemoryServer {) -> Result<CallToolResult, McpError> {let aps_actor = Self::actor_key_from_parts(Some(&parts));let limit = args.recent_pages_limit.unwrap_or(10);+ let settled_first = args.settled_first.unwrap_or(false);let (ws, proj) = self.effective_ids_for_read_args_with_actor(args.workspace.as_deref(),@@ -3900,6 +3908,7 @@ impl AiMemoryServer {limit,ai_memory_core::OwnerFilter::for_actor_context(&actor),&visibility,+ settled_first,).await.map_err(|e| McpError::internal_error(e.to_string(), None))?;@@ -3944,6 +3953,7 @@ impl AiMemoryServer {limit,ai_memory_core::OwnerFilter::for_actor_context(&actor),&visibility,+ false,).await.map_err(|e| McpError::internal_error(e.to_string(), None))?;@@ -9063,6 +9073,7 @@ mod tests {recent_pages_limit: Some(5),project: None,workspace: None,+ settled_first: None,}),OptionalParts(test_parts_default()),)@@ -9094,6 +9105,67 @@ mod tests {text.contains("\"sessions\": 0"),"expected lifetime sessions: 0\n{text}");+ // settled_first defaults to false: `settled` stays empty and is+ // therefore omitted from the JSON entirely (P4,+ // docs/design-hindsight-borrowings.md §5).+ assert!(+ !text.contains("\"settled\""),+ "settled must be omitted by default:\n{text}"+ );+ }++ /// P4 (docs/design-hindsight-borrowings.md §5): `settled_first: true`+ /// leads the briefing with the project's `rule`/`decision` pages.+ /// Tool-level companion to the reader-level ordering test.+ #[tokio::test]+ async fn memory_briefing_settled_first_surfaces_rule_and_decision_pages() {+ let (_tmp, store, server, ws, proj) = setup_server().await;+ store+ .writer+ .upsert_page(NewPage {+ workspace_id: ws,+ project_id: proj,+ path: PagePath::new("decisions/pick-rust.md").unwrap(),+ title: "Pick Rust".into(),+ body: "we chose rust".into(),+ tier: Tier::Semantic,+ frontmatter_json: serde_json::json!({}),+ pinned: false,+ links: Vec::new(),+ author_id: None,+ expires_at: None,+ entities: Vec::new(),+ evidence: Vec::new(),+ })+ .await+ .unwrap();++ let result = server+ .memory_briefing(+ Parameters(BriefingArgs {+ recent_pages_limit: Some(5),+ project: None,+ workspace: None,+ settled_first: Some(true),+ }),+ OptionalParts(test_parts_default()),+ )+ .await+ .unwrap();+ let text = result+ .content+ .first()+ .and_then(|c| c.as_text())+ .map(|t| t.text.clone())+ .unwrap();+ assert!(+ text.contains("\"settled\":"),+ "settled_first=true must include settled:\n{text}"+ );+ assert!(+ text.contains("decisions/pick-rust.md"),+ "settled must surface the decision page:\n{text}"+ );}/// `memory_explore` without an LLM provider configured must@@ -10187,6 +10259,7 @@ mod tests {recent_pages_limit: Some(5),project: None,workspace: None,+ settled_first: None,}),OptionalParts(test_parts_default()),)@@ -10919,6 +10992,7 @@ mod tests {recent_pages_limit: Some(5),project: None,workspace: None,+ settled_first: None,}),OptionalParts(test_parts_default()),)@@ -10959,6 +11033,7 @@ mod tests {recent_pages_limit: Some(5),project: None,workspace: None,+ settled_first: None,}),OptionalParts(test_parts_default()),)diff --git a/crates/ai-memory-store/src/lib.rs b/crates/ai-memory-store/src/lib.rsindex 44530b72..39bb574d 100644--- a/crates/ai-memory-store/src/lib.rs+++ b/crates/ai-memory-store/src/lib.rs@@ -64,9 +64,9 @@ pub use reader::{ObservationHit, ObservationOrder, ObservationPage, ObservationPageResult, ObservationRecord,OpenSession, PageAuthor, PageHit, PageHitWithMeta, PageLinks, PageMeta, PageSummary,ProjectSummary, ReaderPool, ReindexTargetStatus, RelatedPage, RrfContributions, ScopeRow,- SearchExplain, SessionDependentRows, SessionEndDisposition, SessionSummary, StatusCounts,- StorageStatus, StoredEmbedding, StoredPageBody, WorkspaceScopeRow, WorkspaceSummary,- f32_vec_to_bytes,+ SearchExplain, SessionDependentRows, SessionEndDisposition, SessionSummary, SettledPage,+ StatusCounts, StorageStatus, StoredEmbedding, StoredPageBody, WorkspaceScopeRow,+ WorkspaceSummary, f32_vec_to_bytes,};pub use retrieval_tuning::{RetrievalTuning, is_session_recall_query};pub use scope::{@@ -1925,14 +1925,14 @@ mod tests {// Briefing degree: app depends on 1 project; infra has 1 dependent.let app_brief = store.reader- .briefing_for_project(ws, app, 5, ai_memory_core::OwnerFilter::Any)+ .briefing_for_project(ws, app, 5, ai_memory_core::OwnerFilter::Any, false).await.unwrap();assert_eq!(app_brief.cross_project_dependencies, 1);assert_eq!(app_brief.cross_project_dependents, 0);let infra_brief = store.reader- .briefing_for_project(ws, infra, 5, ai_memory_core::OwnerFilter::Any)+ .briefing_for_project(ws, infra, 5, ai_memory_core::OwnerFilter::Any, false).await.unwrap();assert_eq!(infra_brief.cross_project_dependents, 1);@@ -4436,7 +4436,7 @@ mod tests {);let project_briefing = store.reader- .briefing_for_project(ws, proj, 100, ai_memory_core::OwnerFilter::Any)+ .briefing_for_project(ws, proj, 100, ai_memory_core::OwnerFilter::Any, false).await.unwrap();assert_briefing_kinds(&project_briefing.recent_pages);@@ -4510,6 +4510,112 @@ mod tests {);}+ /// P4 (docs/design-hindsight-borrowings.md §5): `settled_first` is+ /// opt-in and additive. `false` (the default) leaves `settled` empty+ /// and every other field of the snapshot untouched; `true` populates+ /// it with the project's `rule`/`decision` pages, ordered by evidence+ /// count then recency, and excludes every other kind.+ #[tokio::test]+ async fn briefing_settled_first_orders_by_evidence_then_recency() {+ let tmp = TempDir::new().unwrap();+ let store = Store::open(tmp.path()).unwrap();+ let ws = store+ .writer+ .get_or_create_workspace("default")+ .await+ .unwrap();+ let proj = store+ .writer+ .get_or_create_project(ws, "settled-test", None)+ .await+ .unwrap();++ let mut decision_a = sample_page(ws, proj, "decisions/decision-a.md", "body a");+ decision_a.evidence = vec![+ PageEvidence {+ kind: PageEvidenceKind::Session,+ source_id: "session-1".into(),+ },+ PageEvidence {+ kind: PageEvidenceKind::Session,+ source_id: "session-2".into(),+ },+ ];+ store.writer.upsert_page(decision_a).await.unwrap();+ tokio::time::sleep(std::time::Duration::from_millis(2)).await;++ store+ .writer+ .upsert_page(sample_page(ws, proj, "_rules/rule-a.md", "body rule"))+ .await+ .unwrap();+ tokio::time::sleep(std::time::Duration::from_millis(2)).await;++ // Written last (and with zero evidence), so among the two+ // zero-evidence pages this one must sort first on recency.+ store+ .writer+ .upsert_page(sample_page(ws, proj, "decisions/decision-b.md", "body b"))+ .await+ .unwrap();+ tokio::time::sleep(std::time::Duration::from_millis(2)).await;++ store+ .writer+ .upsert_page(sample_page(ws, proj, "notes/plain-note.md", "body note"))+ .await+ .unwrap();++ let unchanged = store+ .reader+ .briefing_for_project(ws, proj, 10, ai_memory_core::OwnerFilter::Any, false)+ .await+ .unwrap();+ assert!(+ unchanged.settled.is_empty(),+ "settled_first=false must leave settled empty"+ );+ assert_eq!(unchanged.recent_pages.len(), 4);++ let settled_first = store+ .reader+ .briefing_for_project(ws, proj, 10, ai_memory_core::OwnerFilter::Any, true)+ .await+ .unwrap();+ let settled_paths: Vec<&str> = settled_first+ .settled+ .iter()+ .map(|p| p.path.as_str())+ .collect();+ assert_eq!(+ settled_paths,+ vec![+ "decisions/decision-a.md",+ "decisions/decision-b.md",+ "_rules/rule-a.md",+ ],+ "expected evidence-count-then-recency order: {settled_paths:?}"+ );+ assert!(+ !settled_paths.contains(&"notes/plain-note.md"),+ "a plain note must not appear in settled"+ );+ assert_eq!(settled_first.settled[0].evidence_count, 2);+ assert_eq!(settled_first.settled[1].evidence_count, 0);+ assert_eq!(settled_first.settled[2].evidence_count, 0);+ assert_eq!(settled_first.settled[0].kind, "decision");+ assert_eq!(settled_first.settled[2].kind, "rule");+ // Every other field is identical to the settled_first=false snapshot.+ assert_eq!(+ settled_first.recent_pages.len(),+ unchanged.recent_pages.len()+ );+ assert_eq!(+ settled_first.counts.pages_latest,+ unchanged.counts.pages_latest+ );+ }+#[tokio::test]async fn page_meta_returns_metadata_for_existing_page() {let tmp = TempDir::new().unwrap();diff --git a/crates/ai-memory-store/src/reader.rs b/crates/ai-memory-store/src/reader.rsindex 536af8ee..cde2d46d 100644--- a/crates/ai-memory-store/src/reader.rs+++ b/crates/ai-memory-store/src/reader.rs@@ -1173,6 +1173,14 @@ pub struct BriefingSnapshot {/// Distinct other projects this project's pages link OUT to (what we/// depend on). Project-scoped briefings only; `0` otherwise.pub cross_project_dependencies: u64,+ /// The project's highest-standing `rule`/`decision` pages, ordered by+ /// evidence count then recency. Populated only when the caller opts+ /// in via `settled_first: true` on `memory_briefing` /+ /// `briefing_for_project(_with_slot_visibility)` (P4,+ /// docs/design-hindsight-borrowings.md §5); empty and omitted from+ /// JSON otherwise so the default briefing shape is unchanged.+ #[serde(default, skip_serializing_if = "Vec::is_empty")]+ pub settled: Vec<SettledPage>,}/// Trimmed page view for the briefing — path, title, kind, updated_at@@ -1191,6 +1199,24 @@ pub struct BriefingPage {pub updated_at: String,}+/// One of a project's highest-standing `rule`/`decision` pages, surfaced+/// by [`ReaderPool::briefing_for_project_with_slot_visibility`] only when+/// the caller opts in via `settled_first: true` (P4,+/// docs/design-hindsight-borrowings.md §5) — a bounded list an agent can+/// boot from instead of re-deriving settled answers from scratch.+#[derive(Debug, Clone, Serialize)]+pub struct SettledPage {+ /// Relative wiki path.+ pub path: String,+ /// Page title (first H1 / frontmatter title).+ pub title: String,+ /// Semantic classification — always `rule` or `decision` here.+ pub kind: String,+ /// Number of `page_evidence` rows citing this page version (0 when+ /// none have accrued yet).+ pub evidence_count: u32,+}+/// One core page of the session-start project brief — body included,/// because the brief is injected as agent context and the whole point is/// sparing the agent a re-exploration round-trip. Returned by@@ -5269,6 +5295,7 @@ impl ReaderPool {recent_pages,cross_project_dependents: 0,cross_project_dependencies: 0,+ settled: Vec::new(),};filter_briefing_slots(&mut snapshot, &slot_visibility);Ok(snapshot)@@ -5278,6 +5305,11 @@ impl ReaderPool {/// Assemble a project-scoped [`BriefingSnapshot`].///+ /// `settled_first` opts into populating [`BriefingSnapshot::settled`]+ /// with the project's highest-standing `rule`/`decision` pages (P4,+ /// docs/design-hindsight-borrowings.md §5); `false` leaves the+ /// snapshot byte-for-byte as before.+ ////// # Errors/// Propagates any SQL or pool error.#[allow(clippy::too_many_lines)]@@ -5287,6 +5319,7 @@ impl ReaderPool {project_id: ProjectId,recent_pages_limit: usize,owner_filter: OwnerFilter,+ settled_first: bool,) -> StoreResult<BriefingSnapshot> {self.briefing_for_project_with_slot_visibility(workspace_id,@@ -5294,11 +5327,13 @@ impl ReaderPool {recent_pages_limit,owner_filter,&ai_memory_core::SlotVisibility::All,+ settled_first,).await}- /// Assemble a project briefing while filtering operator-owned slot pages.+ /// Assemble a project briefing while filtering operator-owned slot+ /// pages. See [`ReaderPool::briefing_for_project`] for `settled_first`.pub async fn briefing_for_project_with_slot_visibility(&self,workspace_id: WorkspaceId,@@ -5306,6 +5341,7 @@ impl ReaderPool {recent_pages_limit: usize,owner_filter: OwnerFilter,slot_visibility: &ai_memory_core::SlotVisibility,+ settled_first: bool,) -> StoreResult<BriefingSnapshot> {let recent_limit = recent_pages_limit.clamp(1, 100) as i64;let slot_visibility = slot_visibility.clone();@@ -5440,6 +5476,32 @@ impl ReaderPool {let (cross_project_dependents, cross_project_dependencies) =cross_project_degree(conn, workspace_id, project_id)?;++ let settled: Vec<SettledPage> = if settled_first {+ let settled_kind_expr = page_kind_expr("pages.path", "pages.frontmatter_json");+ let mut settled_stmt = conn.prepare_cached(&format!(+ "SELECT pages.path, pages.title, {settled_kind_expr} AS kind, \+ COUNT(page_evidence.source_id) AS evidence_count \+ FROM pages \+ LEFT JOIN page_evidence ON page_evidence.page_id = pages.id \+ WHERE pages.workspace_id = ?1 AND pages.project_id = ?2 \+ AND pages.is_latest = 1 \+ AND ({settled_kind_expr}) IN ('rule', 'decision'){not_expired} \+ GROUP BY pages.id \+ ORDER BY evidence_count DESC, pages.updated_at DESC \+ LIMIT 8",+ not_expired = not_expired("pages", "?3"),+ ))?;+ settled_stmt+ .query_map(+ params![workspace_id.as_bytes(), project_id.as_bytes(), now_us],+ settled_page_from_row,+ )?+ .collect::<Result<Vec<_>, _>>()?+ } else {+ Vec::new()+ };+let mut snapshot = BriefingSnapshot {counts,activity_7d,@@ -5451,6 +5513,7 @@ impl ReaderPool {recent_pages,cross_project_dependents,cross_project_dependencies,+ settled,};filter_briefing_slots(&mut snapshot, &slot_visibility);Ok(snapshot)@@ -5862,6 +5925,7 @@ impl ReaderPool {recent_pages,cross_project_dependents: 0,cross_project_dependencies: 0,+ settled: Vec::new(),};filter_briefing_slots(&mut snapshot, &slot_visibility);Ok(snapshot)@@ -9090,6 +9154,22 @@ fn briefing_page_from_row(row: &rusqlite::Row<'_>) -> rusqlite::Result<StoreResu}))}+/// Materialise one row from the briefing's `settled_first` query into a+/// [`SettledPage`]. The row shape is `(path, title, kind,+/// evidence_count)`.+fn settled_page_from_row(row: &rusqlite::Row<'_>) -> rusqlite::Result<SettledPage> {+ let path: String = row.get(0)?;+ let title: String = row.get(1)?;+ let kind: String = row.get(2)?;+ let evidence_count: i64 = row.get(3)?;+ Ok(SettledPage {+ path,+ title,+ kind,+ evidence_count: u32::try_from(evidence_count).unwrap_or(u32::MAX),+ })+}+/// Reject cwds that can't safely participate in a `repo_path` prefix/// match. Trailing slash is already trimmed by the caller; this catches:/// empty / single-slash / dot-segments (a `/foo/../bar` resolved-by-LIKEdiff --git a/crates/ai-memory-store/tests/suite/handoff_ownership.rs b/crates/ai-memory-store/tests/suite/handoff_ownership.rsindex ab8110e6..e83a2b37 100644--- a/crates/ai-memory-store/tests/suite/handoff_ownership.rs+++ b/crates/ai-memory-store/tests/suite/handoff_ownership.rs@@ -715,7 +715,7 @@ async fn an_owner_name_with_a_quote_filters_like_any_other() {.pending_handoff_count,store.reader- .briefing_for_project(ws, proj, 5, filter())+ .briefing_for_project(ws, proj, 5, filter(), false).await.unwrap().pending_handoff_count,diff --git a/crates/ai-memory-store/tests/suite/slot_visibility.rs b/crates/ai-memory-store/tests/suite/slot_visibility.rsindex 4c903039..2eabbe04 100644--- a/crates/ai-memory-store/tests/suite/slot_visibility.rs+++ b/crates/ai-memory-store/tests/suite/slot_visibility.rs@@ -308,6 +308,7 @@ async fn briefing_slots_follow_the_same_visibility_rule() {10,ai_memory_core::OwnerFilter::Any,&SlotVisibility::default(),+ false,).await.unwrap(),@@ -328,6 +329,7 @@ async fn briefing_slots_follow_the_same_visibility_rule() {10,ai_memory_core::OwnerFilter::Any,&mine,+ false,).await.unwrap(),@@ -398,6 +400,7 @@ async fn recent_pages_hide_other_operators_personal_slots() {100,ai_memory_core::OwnerFilter::Any,&mine,+ false,).await.unwrap()@@ -477,6 +480,7 @@ async fn foreign_slots_do_not_consume_the_viewers_query_limit() {1,ai_memory_core::OwnerFilter::Any,&visibility,+ false,).await.unwrap();diff --git a/crates/ai-memory-web/src/routes/api.rs b/crates/ai-memory-web/src/routes/api.rsindex ba7c393f..ec9900ca 100644--- a/crates/ai-memory-web/src/routes/api.rs+++ b/crates/ai-memory-web/src/routes/api.rs@@ -454,6 +454,7 @@ async fn briefing_handler(project_id,query.limit.clamp(1, 100),owner_filter_for(actor),+ false,).await.map_err(internal_error)?;@@ -800,7 +801,7 @@ async fn project_overview_handler(let briefing = state.reader- .briefing_for_project(workspace_id, project_id, limit, owner_filter)+ .briefing_for_project(workspace_id, project_id, limit, owner_filter, false).await.map_err(internal_error)?;