Skip to content

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.rs
index 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.rs
index 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.rs
index 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();