Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors
Rust
feat(okf): emit conformant files from the wiki, not just conformant rows
AkitaOnRails15271f267036
diff --git a/crates/ai-memory-core/src/okf.rs b/crates/ai-memory-core/src/okf.rsindex fe3dc18a..a4566d72 100644--- a/crates/ai-memory-core/src/okf.rs+++ b/crates/ai-memory-core/src/okf.rs@@ -164,6 +164,12 @@ pub fn stamp_generated_at(frontmatter: &mut Value, at_iso8601: &str) {}}+/// The `generated.at` value, when present.+#[must_use]+pub fn generated_at(frontmatter: &Value) -> Option<&str> {+ frontmatter.get("generated")?.get("at")?.as_str()+}+/// A file-level conformance verdict for one page's frontmatter.#[must_use]pub fn is_conformant(frontmatter: &Value) -> bool {diff --git a/crates/ai-memory-store/src/ops.rs b/crates/ai-memory-store/src/ops.rsindex 091b84b6..def06169 100644--- a/crates/ai-memory-store/src/ops.rs+++ b/crates/ai-memory-store/src/ops.rs@@ -603,11 +603,16 @@ pub(crate) fn path_search_text(path: &str) -> String {/// version row — the idempotent short-circuit above never reaches it, so/// an unchanged page keeps its original timestamp.fn stamped_frontmatter(mut conformed: serde_json::Value, now_us: i64) -> StoreResult<String> {- let ts = jiff::Timestamp::from_microsecond(now_us)- .unwrap_or(jiff::Timestamp::UNIX_EPOCH)- .strftime("%Y-%m-%dT%H:%M:%SZ")- .to_string();- ai_memory_core::okf::stamp_generated_at(&mut conformed, &ts);+ // The wiki layer stamps (or inherits) `generated.at` before the file+ // is emitted; keep that value so file and row stay byte-aligned. The+ // stamp here covers writers that reach the store without a wiki file.+ if ai_memory_core::okf::generated_at(&conformed).is_none() {+ let ts = jiff::Timestamp::from_microsecond(now_us)+ .unwrap_or(jiff::Timestamp::UNIX_EPOCH)+ .strftime("%Y-%m-%dT%H:%M:%SZ")+ .to_string();+ ai_memory_core::okf::stamp_generated_at(&mut conformed, &ts);+ }Ok(serde_json::to_string(&conformed)?)}diff --git a/crates/ai-memory-wiki/src/wiki.rs b/crates/ai-memory-wiki/src/wiki.rsindex 6042746f..d0a53354 100644--- a/crates/ai-memory-wiki/src/wiki.rs+++ b/crates/ai-memory-wiki/src/wiki.rs@@ -1544,6 +1544,11 @@ impl Wiki {.unwrap_or(false);markdown.frontmatter =canonicalize_index_frontmatter(markdown.frontmatter, req.tier, req.pinned);+ conform_frontmatter_for_disk(+ &self.abs_path(req.workspace_id, req.project_id, &req.path),+ req.path.as_str(),+ &mut markdown,+ );let title = req.title@@ -1727,6 +1732,11 @@ impl Wiki {.and_then(|v| v.as_bool()).unwrap_or(false);markdown.frontmatter = canonicalize_index_frontmatter(markdown.frontmatter, tier, pinned);+ conform_frontmatter_for_disk(+ &self.abs_path(workspace_id, project_id, &path),+ path.as_str(),+ &mut markdown,+ );// Re-derive title + links from the (possibly mutated) markdown.// We do this after the chain so explicit title overrides survive@@ -2003,6 +2013,30 @@ pub(crate) fn parse_expires_at()))}+/// OKF conformance for the on-disk file (docs/okf.md): fill the+/// deterministic keys, then stamp `generated.at` — inheriting the+/// current file's value when nothing but the timestamp would change, so+/// an idempotent rewrite emits byte-identical markdown (no git churn,+/// and the store's modulo-`generated.at` comparison keeps the row).+fn conform_frontmatter_for_disk(abs: &Path, page_path: &str, markdown: &mut Markdown) {+ ai_memory_core::okf::conform_frontmatter(page_path, &mut markdown.frontmatter);+ let inherited = std::fs::read_to_string(abs)+ .ok()+ .and_then(|s| crate::markdown::parse(&s).ok())+ .filter(|cur| {+ ai_memory_core::okf::strip_generated_at(&cur.frontmatter)+ == ai_memory_core::okf::strip_generated_at(&markdown.frontmatter)+ && cur.body == markdown.body+ })+ .and_then(|cur| ai_memory_core::okf::generated_at(&cur.frontmatter).map(str::to_string));+ let at = inherited.unwrap_or_else(|| {+ jiff::Timestamp::now()+ .strftime("%Y-%m-%dT%H:%M:%SZ")+ .to_string()+ });+ ai_memory_core::okf::stamp_generated_at(&mut markdown.frontmatter, &at);+}+fn canonicalize_index_frontmatter(frontmatter: serde_json::Value,tier: Tier,@@ -2326,6 +2360,139 @@ mod tests {);}+ /// The file a consumer reads off disk is the OKF concept file+ /// (docs/okf.md): required `type`, a `generated {by, at}` stanza,+ /// provenance — emitted by the wiki, not just stored in the index.+ #[tokio::test]+ async fn written_files_are_okf_conformant_on_disk() {+ let tmp = TempDir::new().unwrap();+ let store = Store::open(tmp.path()).unwrap();+ let ws = store.writer.get_or_create_workspace("w").await.unwrap();+ let proj = store+ .writer+ .get_or_create_project(ws, "p", None)+ .await+ .unwrap();+ let wiki = Wiki::new(tmp.path(), store.writer.clone()).unwrap();++ wiki.write_page(req(+ ws,+ proj,+ "gotchas/linker.md",+ "mind the linker",+ serde_json::json!({"title": "Linker gotcha"}),+ ))+ .await+ .unwrap();++ let raw =+ std::fs::read_to_string(wiki.project_root(ws, proj).join("gotchas/linker.md")).unwrap();+ let parsed = crate::markdown::parse(&raw).unwrap();+ assert_eq!(parsed.frontmatter["type"], "Gotcha");+ assert!(+ parsed.frontmatter["generated"]["by"]+ .as_str()+ .unwrap()+ .starts_with("process:ai-memory/")+ );+ assert!(+ parsed.frontmatter["generated"]["at"]+ .as_str()+ .unwrap()+ .ends_with('Z')+ );+ assert!(ai_memory_core::okf::is_conformant(&parsed.frontmatter));+ }++ /// An unchanged rewrite must emit byte-identical markdown: the+ /// `generated.at` inheritance keeps the timestamp, so neither git+ /// nor the store sees a phantom new version.+ #[tokio::test]+ async fn an_idempotent_rewrite_keeps_the_file_bytes_and_the_row() {+ let tmp = TempDir::new().unwrap();+ let store = Store::open(tmp.path()).unwrap();+ let ws = store.writer.get_or_create_workspace("w").await.unwrap();+ let proj = store+ .writer+ .get_or_create_project(ws, "p", None)+ .await+ .unwrap();+ let wiki = Wiki::new(tmp.path(), store.writer.clone()).unwrap();++ let request = || {+ req(+ ws,+ proj,+ "notes/idem.md",+ "stable body",+ serde_json::json!({"title": "Idem"}),+ )+ };+ let id1 = wiki.write_page(request()).await.unwrap();+ let abs = wiki.project_root(ws, proj).join("notes/idem.md");+ let bytes1 = std::fs::read(&abs).unwrap();++ // Far enough apart that a re-stamped `generated.at` would differ.+ tokio::time::sleep(std::time::Duration::from_millis(1100)).await;+ let id2 = wiki.write_page(request()).await.unwrap();+ let bytes2 = std::fs::read(&abs).unwrap();++ assert_eq!(id1, id2, "identical rewrite superseded the page");+ assert_eq!(bytes1, bytes2, "identical rewrite changed the file bytes");+ }++ /// A real content change updates `generated.at` — inheritance only+ /// covers the unchanged case.+ #[tokio::test]+ async fn a_content_change_updates_generated_at() {+ let tmp = TempDir::new().unwrap();+ let store = Store::open(tmp.path()).unwrap();+ let ws = store.writer.get_or_create_workspace("w").await.unwrap();+ let proj = store+ .writer+ .get_or_create_project(ws, "p", None)+ .await+ .unwrap();+ let wiki = Wiki::new(tmp.path(), store.writer.clone()).unwrap();++ wiki.write_page(req(+ ws,+ proj,+ "notes/evolving.md",+ "v1",+ serde_json::json!({"title": "Evolving"}),+ ))+ .await+ .unwrap();+ let abs = wiki.project_root(ws, proj).join("notes/evolving.md");+ let at1 = ai_memory_core::okf::generated_at(+ &crate::markdown::parse(&std::fs::read_to_string(&abs).unwrap())+ .unwrap()+ .frontmatter,+ )+ .unwrap()+ .to_string();++ tokio::time::sleep(std::time::Duration::from_millis(1100)).await;+ wiki.write_page(req(+ ws,+ proj,+ "notes/evolving.md",+ "v2 - changed",+ serde_json::json!({"title": "Evolving"}),+ ))+ .await+ .unwrap();+ let at2 = ai_memory_core::okf::generated_at(+ &crate::markdown::parse(&std::fs::read_to_string(&abs).unwrap())+ .unwrap()+ .frontmatter,+ )+ .unwrap()+ .to_string();+ assert_ne!(at1, at2, "content change kept the old generated.at");+ }+#[tokio::test]async fn upgrade_baseline_checkpoint_commits_existing_uncommitted_tree_once() {let tmp = TempDir::new().unwrap();