Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors
Rust
fix: post-audit findings across the 2.0 range
AkitaOnRailse26293606538
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex ce902bcf..98f2a3d4 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -97,6 +97,23 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0is correct and stays; the torn write that triggered it is gone. Now routedthrough the same `write_atomic` (tmp + fsync + rename) the rest of the CLIalready uses, per the project's atomic-writes invariant.+||||||| parent of f14775e5 (fix: post-audit findings across the 2.0 range)+- The 2.0 pre-release audit findings (post-merge adversarial review of+ the whole range): `export-okf` no longer fails on real deployments —+ scope manifests are OKF-typed at their writer (ending a startup+ tug-of-war that reverted the migration's typing on the same boot and+ self-healing manifests reverted by pre-fix binaries), approved+ auto-improve pages land conformant like every other write (also+ preventing phantom supersedes on the first reindex after a binary+ upgrade), and `_pending/` proposal sidecars are excluded from the+ export walk. Pages retired WITHOUT a successor (decay tombstones,+ purge-regenerate, workspace merges) now close their entity-link+ validity windows so `as_of` cannot resurrect retired knowledge, with+ a V58 backfill for previously retired rows. The experience pass no+ longer burns its cadence window or stages an empty run when a scope+ has too few session pages. Backup destination guards canonicalize+ paths; `as_of` parse errors return invalid-params; the FTS5 probe+ connection is cached per thread.- `status` no longer overstates missing embeddings: empty-body pages —which no embedder can ever cover and the backfill skips by rule — areexcluded from the "latest pages missing" figure and reported on theirdiff --git a/crates/ai-memory-cli/tests/removal.rs b/crates/ai-memory-cli/tests/removal.rsindex 3c8c20e8..12c4f6d0 100644--- a/crates/ai-memory-cli/tests/removal.rs+++ b/crates/ai-memory-cli/tests/removal.rs@@ -35,6 +35,7 @@ fn command_with_home(home: &Path) -> Command {.env("LOCALAPPDATA", local_app_data).env("AI_MEMORY_HOME", home).env("AI_MEMORY_DATA_DIR", home.join(".ai-memory-data"))+ .env("AI_MEMORY_EMBEDDING_PROVIDER", "none").env_remove("AI_MEMORY_SERVER_URL").env_remove("AI_MEMORY_AUTH_TOKEN")// A host-level KIMI_CODE_HOME would pull uninstall's kimi-codediff --git a/crates/ai-memory-consolidate/src/auto_improve_schedule.rs b/crates/ai-memory-consolidate/src/auto_improve_schedule.rsindex fe5f4d92..5f21e072 100644--- a/crates/ai-memory-consolidate/src/auto_improve_schedule.rs+++ b/crates/ai-memory-consolidate/src/auto_improve_schedule.rs@@ -196,7 +196,15 @@ pub async fn run_auto_improve_scheduler_tick({Ok((newer, _)) if newer >= experience.min_new_sessions => {match run_scheduled_experience(&ctx, experience).await {- Ok(run) => {+ Ok(None) => {+ tracing::debug!(+ workspace = %scope.workspace_name,+ project = %scope.project_name,+ "experience pass skipped (too few session pages); \+ cadence anchor kept"+ );+ }+ Ok(Some(run)) => {outcome.experience_runs += 1;outcome.skipped += run.skipped.len();if let Err(e) = writer@@ -354,7 +362,7 @@ async fn run_scheduled_auto_improve(async fn run_scheduled_experience(ctx: &ScheduledAutoImproveContext<'_>,experience: &crate::ExperienceConfig,-) -> Result<ScheduledAutoImproveOutcome> {+) -> Result<Option<ScheduledAutoImproveOutcome>> {let cfg = ctx.settings.review.clone();let report = crate::run_experience_review(ctx.reader,@@ -365,7 +373,16 @@ async fn run_scheduled_experience(experience,).await?;- stage_and_apply(ctx, None, &report, "experience-scheduler").await+ // A preflight skip (enough ENDED sessions but too few summary+ // pages — consolidation lag, purges) must not stage an empty run or+ // burn the cadence window (post-audit finding): report it as+ // not-run so the anchor stays put and the next tick retries.+ if report.provider == "none" {+ return Ok(None);+ }+ stage_and_apply(ctx, None, &report, "experience-scheduler")+ .await+ .map(Some)}/// Stage a report's proposals and (unless approval is required) apply@@ -843,6 +860,32 @@ mod tests {.await.unwrap();assert_eq!(outcome2.experience_runs, 0, "{outcome2:?}");++ // Post-audit regression: approving the proposal must land an+ // OKF-conformant FILE (type + generated), like every other write+ // path — the approve emit used to skip disk conformance, which+ // blocked export-okf and phantom-superseded on the next reindex+ // after a binary upgrade.+ wiki.approve_auto_improve_proposal(+ ws,+ project,+ pending[0].id,+ ActorContext::anonymous(),+ None,+ None,+ )+ .await+ .unwrap();+ let approved = std::fs::read_to_string(+ tmp.path()+ .join("wiki")+ .join(ws.to_string())+ .join(project.to_string())+ .join("procedures/cross-session-release.md"),+ )+ .unwrap();+ assert!(approved.contains("type: Procedure"), "{approved}");+ assert!(approved.contains("generated:"), "{approved}");}/// Below the cadence floor nothing runs at all — no LLM call, nodiff --git a/crates/ai-memory-mcp/src/admin.rs b/crates/ai-memory-mcp/src/admin.rsindex 61831bb9..d94c7630 100644--- a/crates/ai-memory-mcp/src/admin.rs+++ b/crates/ai-memory-mcp/src/admin.rs@@ -889,6 +889,13 @@ async fn build_okf_bundle_file(let path = entry.path();let ft = entry.file_type()?;if ft.is_dir() {+ // `_pending/` is the auto-improve staging area — proposal+ // sidecars, not concept files; a strict OKF reader has no+ // business seeing them (post-audit finding: an unresolved+ // pending proposal blocked every export).+ if entry.file_name() == "_pending" {+ continue;+ }if dir == bundle_dir {families.push(entry.file_name().to_string_lossy().into_owned());}@@ -8068,6 +8075,69 @@ mod tests {assert_eq!(fm["type"], "Gotcha");}+ /// Post-audit regression: the things a REAL deployment's tree holds+ /// beside concept pages — typed scope manifests and _pending+ /// proposal sidecars — must not block the export. Sidecars are+ /// excluded; manifests ship typed.+ #[tokio::test]+ async fn export_okf_tolerates_manifests_and_skips_pending() {+ let (tmp, router) = read_page_test_router();+ post_write_page(&router, "default", "scratch", "notes/a.md", "fine").await;+ let ws_dir = std::fs::read_dir(tmp.path().join("wiki"))+ .unwrap()+ .flatten()+ .map(|e| e.path())+ .find(|p| p.is_dir() && p.file_name().is_none_or(|n| n != ".git"))+ .unwrap();+ let proj_dir = std::fs::read_dir(&ws_dir)+ .unwrap()+ .flatten()+ .map(|e| e.path())+ .find(|p| p.is_dir())+ .unwrap();+ // Typed manifest (what the fixed backfill writes) + a pending+ // sidecar with no frontmatter (what staging writes).+ std::fs::write(+ proj_dir.join("_meta.md"),+ "---\nproject: scratch\ntype: Scope Manifest\n---\n",+ )+ .unwrap();+ std::fs::create_dir_all(proj_dir.join("_pending/auto-improve")).unwrap();+ std::fs::write(+ proj_dir.join("_pending/auto-improve/proposal.md"),+ "# A staged proposal\n\nno frontmatter at all",+ )+ .unwrap();++ let resp = router+ .clone()+ .oneshot(+ Request::builder()+ .method("POST")+ .uri("/admin/export-okf?workspace=default&project=scratch")+ .body(Body::empty())+ .unwrap(),+ )+ .await+ .unwrap();+ assert_eq!(resp.status(), StatusCode::OK);+ let bytes = axum::body::to_bytes(resp.into_body(), usize::MAX)+ .await+ .unwrap();+ let dec = flate2::read::GzDecoder::new(std::io::Cursor::new(bytes.to_vec()));+ let mut ar = tar::Archive::new(dec);+ let names: Vec<String> = ar+ .entries()+ .unwrap()+ .map(|e| e.unwrap().path().unwrap().display().to_string())+ .collect();+ assert!(names.iter().any(|n| n == "_meta.md"), "{names:?}");+ assert!(+ !names.iter().any(|n| n.starts_with("_pending")),+ "pending sidecars must not ship: {names:?}"+ );+ }+/// A bundle with a non-conformant page must fail the export rather/// than ship something a strict reader rejects.#[tokio::test]diff --git a/crates/ai-memory-mcp/tests/admin_move.rs b/crates/ai-memory-mcp/tests/admin_move.rsindex 9e1bcdd8..310bcccb 100644--- a/crates/ai-memory-mcp/tests/admin_move.rs+++ b/crates/ai-memory-mcp/tests/admin_move.rs@@ -1812,7 +1812,19 @@ async fn copy_purge_rerun_is_idempotent() {json!({ "from_workspace": "src", "project": "proj", "to_workspace": "dst", "confirm": true }),).await;- assert_eq!(r2.status(), StatusCode::OK);+ // Flaky under heavy parallel load / on Windows (observed in the 2.0+ // full-matrix run); keep the body in the failure so the next+ // occurrence is diagnosable instead of a bare status assert.+ let r2_status = r2.status();+ if r2_status != StatusCode::OK {+ let body = axum::body::to_bytes(r2.into_body(), usize::MAX)+ .await+ .unwrap();+ panic!(+ "second move-project failed: {r2_status} {}",+ String::from_utf8_lossy(&body)+ );+ }// Destination still holds exactly one of each path — no duplicates.let mut paths: Vec<String> = storediff --git a/crates/ai-memory-store/migrations/V58__close_retired_entity_windows.sql b/crates/ai-memory-store/migrations/V58__close_retired_entity_windows.sqlnew file mode 100644index 00000000..59dd4728--- /dev/null+++ b/crates/ai-memory-store/migrations/V58__close_retired_entity_windows.sql@@ -0,0 +1,14 @@+-- Post-audit fix (docs/temporal.md): pages retired WITHOUT a+-- superseding version (decay tombstones, purge-regenerate, graveyard+-- merges) left their entity-link windows open, so `as_of` resurrected+-- retired knowledge for every later instant. Close them retroactively+-- at the page's own updated_at (the best available retirement instant).+-- The runtime paths now close windows at retire time.+UPDATE entity_page_links+SET superseded_at = (SELECT p.updated_at FROM pages p WHERE p.id = page_id)+WHERE superseded_at IS NULL+ AND page_id IN (+ SELECT p.id FROM pages p+ WHERE p.is_latest = 0+ AND NOT EXISTS (SELECT 1 FROM pages s WHERE s.supersedes = p.id)+ );diff --git a/crates/ai-memory-store/src/api_credentials.rs b/crates/ai-memory-store/src/api_credentials.rsindex 2843fa72..d1d90786 100644--- a/crates/ai-memory-store/src/api_credentials.rs+++ b/crates/ai-memory-store/src/api_credentials.rs@@ -411,7 +411,7 @@ mod tests {|row| row.get(0),).unwrap();- assert_eq!(version, 57, "update the pin when adding a migration");+ assert_eq!(version, 58, "update the pin when adding a migration");let cols: i64 = conn.query_row("SELECT COUNT(*) FROM pragma_table_info('users') WHERE name = 'token_hash'",diff --git a/crates/ai-memory-store/src/fts_query.rs b/crates/ai-memory-store/src/fts_query.rsindex 1b5f9c06..94b906db 100644--- a/crates/ai-memory-store/src/fts_query.rs+++ b/crates/ai-memory-store/src/fts_query.rs@@ -83,21 +83,32 @@ pub fn prepare_fts5_query(raw: &str) -> String {/// table (microseconds; search-path frequency, not ingest-path) so the/// judgement is the engine's, not a re-implementation of its grammar.fn fts5_query_parses(query: &str) -> bool {- let Ok(conn) = rusqlite::Connection::open_in_memory() else {- return false;- };- if conn- .execute_batch("CREATE VIRTUAL TABLE fts_probe USING fts5(title, body)")- .is_err()- {- return false;+ thread_local! {+ // One probe connection per thread: opening a fresh in-memory+ // database per search query was measurable overhead on the+ // read-pool hot path (post-audit nit).+ static PROBE: Option<rusqlite::Connection> = {+ let conn = rusqlite::Connection::open_in_memory().ok();+ if let Some(c) = &conn+ && c.execute_batch("CREATE VIRTUAL TABLE fts_probe USING fts5(title, body)")+ .is_err()+ {+ None+ } else {+ conn+ }+ };}- conn.query_row(- "SELECT count(*) FROM fts_probe WHERE fts_probe MATCH ?1",- [query],- |row| row.get::<_, i64>(0),- )- .is_ok()+ PROBE.with(|probe| {+ probe.as_ref().is_some_and(|conn| {+ conn.query_row(+ "SELECT count(*) FROM fts_probe WHERE fts_probe MATCH ?1",+ [query],+ |row| row.get::<_, i64>(0),+ )+ .is_ok()+ })+ })}/// English stopwords excluded from bare-query OR-joins. Deliberatelydiff --git a/crates/ai-memory-store/src/lib.rs b/crates/ai-memory-store/src/lib.rsindex d3ea8628..31a90c0f 100644--- a/crates/ai-memory-store/src/lib.rs+++ b/crates/ai-memory-store/src/lib.rs@@ -6404,6 +6404,62 @@ mod tests {assert!(before.is_empty(), "{before:?}");}+ /// Post-audit regression: retirement WITHOUT a successor (a decay+ /// tombstone) closes the entity-link window too — `as_of` instants+ /// after retirement must not resurrect the page.+ #[tokio::test]+ async fn decay_tombstone_closes_the_entity_window() {+ 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, "t", None)+ .await+ .unwrap();+ let mut page = sample_page(ws, proj, "notes/old.md", "we use postgres");+ page.entities = vec!["postgres".into()];+ let id = store.writer.upsert_page(page).await.unwrap();+ tokio::time::sleep(std::time::Duration::from_millis(5)).await;+ let retired_at = jiff::Timestamp::now().as_microsecond();+ store+ .writer+ .soft_delete_for_decay_if_latest(+ ws,+ proj,+ ai_memory_core::PagePath::new("notes/old.md").unwrap(),+ id,+ )+ .await+ .unwrap();++ // Before retirement: visible.+ let before = store+ .reader+ .entity_hits_for_project_at(ws, proj, "postgres", 10, None, Some(retired_at - 1000))+ .await+ .unwrap();+ assert_eq!(before.len(), 1, "{before:?}");+ // After retirement: gone.+ let after = store+ .reader+ .entity_hits_for_project_at(+ ws,+ proj,+ "postgres",+ 10,+ None,+ Some(jiff::Timestamp::now().as_microsecond()),+ )+ .await+ .unwrap();+ assert!(after.is_empty(), "retired page resurrected: {after:?}");+ }+/// The windows themselves: insert opens at the version's/// `created_at`; supersession closes the old version's links.#[tokio::test]diff --git a/crates/ai-memory-store/src/ops.rs b/crates/ai-memory-store/src/ops.rsindex 3707c840..65a6c07c 100644--- a/crates/ai-memory-store/src/ops.rs+++ b/crates/ai-memory-store/src/ops.rs@@ -1990,6 +1990,14 @@ pub fn soft_delete_for_decay_if_latest(],)?;if affected != 0 {+ // Retirement is supersession for the entity timeline too: an+ // open window on a tombstoned page made `as_of` resurrect+ // retired knowledge forever (post-audit finding).+ tx.execute(+ "UPDATE entity_page_links SET superseded_at = ?1 \+ WHERE page_id = ?2 AND superseded_at IS NULL",+ params![now, expected_latest_id.as_bytes()],+ )?;audit(&tx,"soft_delete_for_decay",@@ -2992,6 +3000,12 @@ pub fn reorg_sessions(}// Graveyard only this workspace's latest pages; sibling workspaces may// have already-consolidated pages that must remain current.+ tx.execute(+ "UPDATE entity_page_links SET superseded_at = ?2 \+ WHERE superseded_at IS NULL AND page_id IN ( \+ SELECT id FROM pages WHERE workspace_id = ?1 AND is_latest = 1)",+ params![workspace_id.as_bytes(), Timestamp::now().as_microsecond()],+ )?;let pages_graveyarded: usize = tx.execute("UPDATE pages SET is_latest = 0 WHERE workspace_id = ?1 AND is_latest = 1",params![workspace_id.as_bytes()],@@ -4211,6 +4225,22 @@ pub fn move_session()? as u64;}PagesMode::Regenerate => {+ // Close the retiring page's entity windows first (the+ // predicate needs is_latest = 1, flipped just below).+ tx.execute(+ &format!(+ "UPDATE entity_page_links SET superseded_at = ?4 \+ WHERE superseded_at IS NULL AND page_id IN ( \+ SELECT id FROM pages \+ WHERE {page_scope_sql} AND path = ?3 AND is_latest = 1)"+ ),+ params![+ page_scope_params.0,+ page_scope_params.1,+ page_path.as_str(),+ Timestamp::now().as_microsecond(),+ ],+ )?;summary.pages_regenerated = tx.execute(&format!("UPDATE pages SET is_latest = 0 \diff --git a/crates/ai-memory-wiki/src/backup.rs b/crates/ai-memory-wiki/src/backup.rsindex 72d39ed6..e90b171a 100644--- a/crates/ai-memory-wiki/src/backup.rs+++ b/crates/ai-memory-wiki/src/backup.rs@@ -90,13 +90,24 @@ fn destination_dir())})?};- if dest == data_dir {+ // Canonicalize both sides before comparing: `<data_dir>/.` or a+ // symlinked spelling must not defeat the root guard (or the walk's+ // self-exclusion, which compares against the path returned here).+ let canonical_data = data_dir+ .canonicalize()+ .unwrap_or_else(|_| data_dir.to_path_buf());+ let canonical_dest = if dest.exists() {+ dest.canonicalize().unwrap_or_else(|_| dest.clone())+ } else {+ dest.clone()+ };+ if canonical_dest == canonical_data {return Err(WikiError::Io(std::io::Error::other("the backup destination must not be the data dir root itself; \use a subdirectory (e.g. <data_dir>/backups) or a path outside it",)));}- Ok(dest)+ Ok(canonical_dest)}/// Compress `data_dir` into a timestamped tar.gz in the destination dir,diff --git a/crates/ai-memory-wiki/src/migrations/m2026_09_okf_conformance.rs b/crates/ai-memory-wiki/src/migrations/m2026_09_okf_conformance.rsindex 74dd16dc..30f22c54 100644--- a/crates/ai-memory-wiki/src/migrations/m2026_09_okf_conformance.rs+++ b/crates/ai-memory-wiki/src/migrations/m2026_09_okf_conformance.rs@@ -6,8 +6,11 @@//! 3. DB pass: conform every latest page row IN PLACE (same id, same//! version row, `updated_at` untouched);//! 4. file pass: conform every wiki `.md` in place (body untouched),-//! `generated.at` from the row's `updated_at` when the page is-//! indexed, else the file's mtime; scope `_meta.md` manifests get+//! `generated.at` from the row's `updated_at` when the DB pass+//! rewrote that row, else the file's mtime (already-conformant rows+//! are skipped by the DB pass, so their files fall back to mtime —+//! the strip-comparison keeps row and file in agreement either+//! way); scope `_meta.md` manifests get//! their `type` only; each project bundle root gains an `index.md`//! declaring `okf_version` when absent;//! 5. single "okf-migration" git commit.diff --git a/crates/ai-memory-wiki/src/wiki.rs b/crates/ai-memory-wiki/src/wiki.rsindex 907a77c3..7d8096c6 100644--- a/crates/ai-memory-wiki/src/wiki.rs+++ b/crates/ai-memory-wiki/src/wiki.rs@@ -1201,6 +1201,17 @@ impl Wiki {}markdown.body = self.sanitizer.scrub(&markdown.body);scrub_frontmatter_strings(&mut markdown.frontmatter, &self.sanitizer);+ // Approved pages must land conformant like every other write —+ // this emit skipped the disk conformance seam, leaving files+ // without type/generated that blocked export-okf and, worse,+ // phantom-superseded on the first reindex after a binary upgrade+ // (the row was conformed with the approving binary's version, the+ // file with the reindexing one's). Post-audit finding.+ conform_frontmatter_for_disk(+ &self.abs_path(workspace_id, project_id, &path),+ path.as_str(),+ &mut markdown,+ );let title = self.sanitizer.scrub(&detail.summary.title);let links =crate::markdown::extract_all_links(&markdown.frontmatter, &markdown.body, &path);@@ -1434,7 +1445,18 @@ impl Wiki {/// Write a `_meta.md` scope manifest under `dir` from `frontmatter`,/// idempotently — unchanged content is left untouched so a startup/// backfill never churns the wiki git history. Returns `true` if written.- fn write_scope_manifest(dir: &Path, frontmatter: serde_json::Value) -> WikiResult<bool> {+ fn write_scope_manifest(dir: &Path, mut frontmatter: serde_json::Value) -> WikiResult<bool> {+ // OKF conformance at the manifest choke point: every non-reserved+ // .md needs a `type`, and the startup backfill's byte-compare must+ // agree with what the OKF migration writes — a typeless emit here+ // silently reverted migrated manifests on the same boot+ // (post-audit finding). `type` is appended last, matching the+ // migration's entry-insertion order, so the two emitters converge+ // on identical bytes.+ if let Some(map) = frontmatter.as_object_mut() {+ map.entry("type".to_string())+ .or_insert(serde_json::Value::String("Scope Manifest".into()));+ }let content = emit(&Markdown {frontmatter,body: String::new(),@@ -4334,6 +4356,38 @@ mod tests {assert!(meta.contains("workspace: empty-ws"));}+ /// Post-audit regression: manifests are OKF-typed at the writer+ /// choke point, and a typeless manifest (the tug-of-war era, or a+ /// hand edit) is HEALED by the next backfill instead of reverting+ /// the migration's typing.+ #[tokio::test]+ async fn backfill_types_manifests_and_heals_typeless_ones() {+ let tmp = TempDir::new().unwrap();+ let store = Store::open(tmp.path()).unwrap();+ let ws = store.writer.get_or_create_workspace("w").await.unwrap();+ let wiki = Wiki::new(tmp.path(), store.writer.clone())+ .unwrap()+ .with_store_reader(store.reader.clone());++ wiki.backfill_scope_manifests().await.unwrap();+ let meta_path = tmp+ .path()+ .join("wiki")+ .join(ws.to_string())+ .join("_meta.md");+ let meta = std::fs::read_to_string(&meta_path).unwrap();+ assert!(meta.contains("type: Scope Manifest"), "{meta}");++ // Second backfill: byte-stable, no churn.+ assert_eq!(wiki.backfill_scope_manifests().await.unwrap(), 0);++ // A typeless manifest (pre-fix state) is healed, not preserved.+ std::fs::write(&meta_path, "---\nworkspace: w\n---\n").unwrap();+ assert_eq!(wiki.backfill_scope_manifests().await.unwrap(), 1);+ let healed = std::fs::read_to_string(&meta_path).unwrap();+ assert!(healed.contains("type: Scope Manifest"), "{healed}");+ }+#[cfg(any(unix, windows))]#[tokio::test]async fn reindex_rejects_symlinked_scope_manifest() {diff --git a/evals/src/retrieval/server.rs b/evals/src/retrieval/server.rsindex f3aeb192..34af935c 100644--- a/evals/src/retrieval/server.rs+++ b/evals/src/retrieval/server.rs@@ -87,7 +87,10 @@ impl EvalServer {.env_remove("LLM_API_KEY");match embeddings {EvalEmbeddings::None => {- cmd.env_remove("AI_MEMORY_EMBEDDING_PROVIDER");+ // Explicit: with 2.0's default-on local embeddings, an+ // UNSET provider would start a background model download+ // per spawned server. The baseline must be hermetic.+ cmd.env("AI_MEMORY_EMBEDDING_PROVIDER", "none");}EvalEmbeddings::Local => {cmd.env("AI_MEMORY_EMBEDDING_PROVIDER", "local");