Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors
Rust
feat(okf): conform every page write to OKF v0.2 at the store choke point
AkitaOnRailsf821413d115a
diff --git a/crates/ai-memory-core/src/lib.rs b/crates/ai-memory-core/src/lib.rsindex 33402ec4..56c20a56 100644--- a/crates/ai-memory-core/src/lib.rs+++ b/crates/ai-memory-core/src/lib.rs@@ -13,6 +13,7 @@ pub mod ingest_metrics;pub use ingest_metrics::{IngestMetrics, IngestMetricsSnapshot};pub mod ids;pub mod observation;+pub mod okf;pub mod page;pub mod routing_skills;pub mod scaffolding;diff --git a/crates/ai-memory-core/src/okf.rs b/crates/ai-memory-core/src/okf.rsnew file mode 100644index 00000000..fe3dc18a--- /dev/null+++ b/crates/ai-memory-core/src/okf.rs@@ -0,0 +1,282 @@+//! Open Knowledge Format (OKF) v0.2 conformance.+//!+//! From 2.0 on, every wiki page is natively an OKF concept file: YAML+//! frontmatter with a non-empty `type`, trust/provenance keys following+//! the spec's actor convention, and ai-memory's own fields riding along+//! as spec-safe extensions ("consumers MUST NOT reject documents with+//! unrecognized fields"). Design: `docs/okf.md`. Spec:+//! `GoogleCloudPlatform/knowledge-catalog`, `okf/SPEC.md`.+//!+//! Split matters here:+//!+//! - [`conform_frontmatter`] fills only keys that are **deterministic**+//! for a given (path, frontmatter) — `type`, `generated.by`,+//! `sources`, `stale_after`, `description`. Calling it twice yields+//! identical bytes, so the store's identical-content idempotency+//! check keeps working.+//! - `generated.at` is deliberately NOT set here: it changes per+//! version, so the store stamps it only when content actually+//! changed (see `upsert_page_in_tx`), comparing idempotency modulo+//! [`strip_generated_at`].++use serde_json::{Map, Value, json};++/// OKF version this build writes and understands.+pub const OKF_VERSION: &str = "0.2";++/// `generated.by` for pages produced by ai-memory itself (the zero-LLM+/// consolidator, scaffolding, sweeps) — the spec's `process:<id>` actor+/// form, versioned so a bundle records which build wrote what.+#[must_use]+pub fn process_actor() -> String {+ format!("process:ai-memory/{}", env!("CARGO_PKG_VERSION"))+}++/// Derive the required OKF `type` from the page's path family, with an+/// explicit `kind`/`slot_kind` frontmatter value taking precedence over+/// the path default.+#[must_use]+pub fn derive_type(path: &str, frontmatter: &Value) -> String {+ if let Some(kind) = frontmatter.get("kind").and_then(Value::as_str) {+ match kind {+ "fact" => return "Fact".into(),+ "note" => return "Note".into(),+ "procedure" => return "Procedure".into(),+ "decision" => return "Decision".into(),+ _ => {}+ }+ }+ if let Some(slot) = frontmatter.get("slot_kind").and_then(Value::as_str) {+ match slot {+ "invariant" => return "Invariant".into(),+ "state" => return "State".into(),+ _ => {}+ }+ }+ let family = path.split('/').next().unwrap_or("");+ match family {+ "sessions" => "Session Summary",+ "_rules" => "Rule",+ "gotchas" => "Gotcha",+ "decisions" => "Decision",+ "procedures" => "Procedure",+ "concepts" => "Concept",+ "notes" => "Note",+ "runbooks" => "Runbook",+ "_slots" => "State",+ "_lint" => "Lint Report",+ "_pending" => "Pending Note",+ _ => "Note",+ }+ .into()+}++/// Fill the deterministic OKF keys into `frontmatter`, touching nothing+/// already present and inventing nothing non-derivable. Idempotent:+/// conforming conformed frontmatter is a no-op.+pub fn conform_frontmatter(path: &str, frontmatter: &mut Value) {+ if !frontmatter.is_object() {+ *frontmatter = Value::Object(Map::new());+ }+ let derived_type = derive_type(path, frontmatter);+ let map = frontmatter.as_object_mut().expect("object ensured above");++ if map+ .get("type")+ .and_then(Value::as_str)+ .is_none_or(|t| t.trim().is_empty())+ {+ map.insert("type".into(), Value::String(derived_type));+ }++ // description ← existing summary (recommended key; only when we+ // actually have one).+ if !map.contains_key("description")+ && let Some(summary) = map.get("summary").and_then(Value::as_str)+ && !summary.trim().is_empty()+ {+ map.insert("description".into(), Value::String(summary.to_string()));+ }++ // stale_after ← existing TTL. `expires_at` is stored as an ISO-8601+ // string by the TTL machinery; carry it verbatim.+ if !map.contains_key("stale_after")+ && let Some(expires) = map.get("expires_at").and_then(Value::as_str)+ {+ map.insert("stale_after".into(), Value::String(expires.to_string()));+ }++ // sources ← session provenance already stamped by the consolidator.+ if !map.contains_key("sources")+ && let Some(session) = map.get("session_id").and_then(Value::as_str)+ {+ let mut entry = Map::new();+ entry.insert(+ "resource".into(),+ Value::String(format!("ai-memory://session/{session}")),+ );+ if let Some(agent) = map.get("agent").and_then(Value::as_str) {+ entry.insert("author".into(), Value::String(agent.to_string()));+ }+ map.insert("sources".into(), Value::Array(vec![Value::Object(entry)]));+ }++ // generated.by — the actor that produced the content. LLM-written+ // pages carry a model identity in `generated_by_model` (when the+ // consolidator knows it); everything else is this process.+ let by = map+ .get("generated_by_model")+ .and_then(Value::as_str)+ .map(str::to_string)+ .unwrap_or_else(process_actor);+ match map.get_mut("generated") {+ Some(Value::Object(generated)) => {+ generated+ .entry("by".to_string())+ .or_insert(Value::String(by));+ }+ _ => {+ map.insert("generated".into(), json!({ "by": by }));+ }+ }+}++/// Clone `frontmatter` with `generated.at` removed — the store compares+/// idempotency on this projection so an unchanged page never supersedes+/// itself over a timestamp.+#[must_use]+pub fn strip_generated_at(frontmatter: &Value) -> Value {+ let mut out = frontmatter.clone();+ if let Some(generated) = out.get_mut("generated").and_then(Value::as_object_mut) {+ generated.remove("at");+ }+ out+}++/// Stamp `generated.at` (ISO-8601, UTC seconds) onto conformed+/// frontmatter. Called only when the store decided content changed.+pub fn stamp_generated_at(frontmatter: &mut Value, at_iso8601: &str) {+ if let Some(generated) = frontmatter+ .get_mut("generated")+ .and_then(Value::as_object_mut)+ {+ generated.insert("at".into(), Value::String(at_iso8601.to_string()));+ }+}++/// A file-level conformance verdict for one page's frontmatter.+#[must_use]+pub fn is_conformant(frontmatter: &Value) -> bool {+ frontmatter+ .get("type")+ .and_then(Value::as_str)+ .is_some_and(|t| !t.trim().is_empty())+}++#[cfg(test)]+mod tests {+ use super::*;++ #[test]+ fn path_families_map_to_types() {+ for (path, expected) in [+ ("sessions/0192.md", "Session Summary"),+ ("_rules/deploy.md", "Rule"),+ ("gotchas/build.md", "Gotcha"),+ ("decisions/arch.md", "Decision"),+ ("procedures/release.md", "Procedure"),+ ("concepts/writer.md", "Concept"),+ ("notes/misc.md", "Note"),+ ("runbooks/oncall.md", "Runbook"),+ ("_lint/report.md", "Lint Report"),+ ("_pending/queue.md", "Pending Note"),+ ("unknown/where.md", "Note"),+ ] {+ assert_eq!(derive_type(path, &json!({})), expected, "{path}");+ }+ }++ #[test]+ fn kind_and_slot_kind_win_over_the_path_default() {+ assert_eq!(derive_type("notes/x.md", &json!({"kind": "fact"})), "Fact");+ assert_eq!(+ derive_type("_slots/current.md", &json!({"slot_kind": "invariant"})),+ "Invariant"+ );+ assert_eq!(+ derive_type("_slots/current.md", &json!({"slot_kind": "state"})),+ "State"+ );+ }++ #[test]+ fn conform_is_idempotent_and_preserves_existing_keys() {+ let mut fm = json!({+ "title": "T",+ "tier": "episodic",+ "session_id": "0192aaaa-0000-7000-8000-000000000000",+ "agent": "claude-code",+ "summary": "what happened",+ "expires_at": "2027-01-01T00:00:00Z",+ });+ conform_frontmatter("sessions/0192.md", &mut fm);+ let once = fm.clone();+ conform_frontmatter("sessions/0192.md", &mut fm);+ assert_eq!(once, fm, "second conform changed bytes");++ assert_eq!(fm["type"], "Session Summary");+ assert_eq!(fm["description"], "what happened");+ assert_eq!(fm["stale_after"], "2027-01-01T00:00:00Z");+ assert_eq!(+ fm["sources"][0]["resource"],+ "ai-memory://session/0192aaaa-0000-7000-8000-000000000000"+ );+ assert_eq!(fm["sources"][0]["author"], "claude-code");+ assert!(+ fm["generated"]["by"]+ .as_str()+ .unwrap()+ .starts_with("process:ai-memory/")+ );+ // extensions untouched+ assert_eq!(fm["tier"], "episodic");+ }++ #[test]+ fn an_explicit_type_is_never_overwritten() {+ let mut fm = json!({"type": "Custom Thing"});+ conform_frontmatter("notes/x.md", &mut fm);+ assert_eq!(fm["type"], "Custom Thing");+ }++ #[test]+ fn an_empty_type_is_repaired() {+ let mut fm = json!({"type": " "});+ conform_frontmatter("gotchas/x.md", &mut fm);+ assert_eq!(fm["type"], "Gotcha");+ }++ #[test]+ fn generated_at_round_trip_is_invisible_to_the_idempotency_projection() {+ let mut fm = json!({"title": "T"});+ conform_frontmatter("notes/x.md", &mut fm);+ let before = strip_generated_at(&fm);+ stamp_generated_at(&mut fm, "2026-09-01T12:00:00Z");+ assert_eq!(fm["generated"]["at"], "2026-09-01T12:00:00Z");+ assert_eq!(strip_generated_at(&fm), before);+ }++ #[test]+ fn an_llm_model_identity_becomes_generated_by() {+ let mut fm = json!({"generated_by_model": "openai-compat/qwen3:32b"});+ conform_frontmatter("sessions/x.md", &mut fm);+ assert_eq!(fm["generated"]["by"], "openai-compat/qwen3:32b");+ }++ #[test]+ fn conformance_verdict_requires_a_non_empty_type() {+ assert!(!is_conformant(&json!({})));+ assert!(!is_conformant(&json!({"type": ""})));+ assert!(is_conformant(&json!({"type": "Note"})));+ }+}diff --git a/crates/ai-memory-store/src/ops.rs b/crates/ai-memory-store/src/ops.rsindex c7b81345..091b84b6 100644--- a/crates/ai-memory-store/src/ops.rs+++ b/crates/ai-memory-store/src/ops.rs@@ -598,6 +598,19 @@ pub(crate) fn path_search_text(path: &str) -> String {format!("{segments} {words}")}+/// Stamp the per-version `generated.at` (write time, UTC) onto conformed+/// frontmatter and serialize it. Runs only on the paths that create a new+/// 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);+ Ok(serde_json::to_string(&conformed)?)+}+pub(crate) fn upsert_page_in_tx(tx: &rusqlite::Transaction<'_>,page: &NewPage,@@ -609,7 +622,12 @@ pub(crate) fn upsert_page_in_tx(hasher.update(page.body.as_bytes());hasher.finalize().into()};- let frontmatter_str = serde_json::to_string(&page.frontmatter_json)?;+ // OKF conformance at the single write choke point (docs/okf.md):+ // fill the deterministic keys, compare idempotency modulo the+ // per-version `generated.at`, and stamp `at` only when content+ // actually changed (below).+ let mut conformed = page.frontmatter_json.clone();+ ai_memory_core::okf::conform_frontmatter(page.path.as_str(), &mut conformed);let tier_str = page.tier.as_str();let existing: Option<ExistingPageVersion> = tx@@ -635,14 +653,18 @@ pub(crate) fn upsert_page_in_tx(.optional()?;if let Some(existing) = existing {+ let existing_fm: serde_json::Value =+ serde_json::from_str(&existing.frontmatter_json).unwrap_or_default();if existing.body_sha256 == body_sha256- && existing.frontmatter_json == frontmatter_str+ && ai_memory_core::okf::strip_generated_at(&existing_fm)+ == ai_memory_core::okf::strip_generated_at(&conformed)&& existing.title == page.title&& existing.tier == tier_str&& existing.pinned == i64::from(page.pinned){return PageId::from_slice(&existing.id).map_err(StoreError::from);}+ let frontmatter_str = stamped_frontmatter(conformed, now)?;let new_id = PageId::new();tx.execute("UPDATE pages SET is_latest = 0 WHERE id = ?1",@@ -688,6 +710,7 @@ pub(crate) fn upsert_page_in_tx()?;return Ok(new_id);}+ let frontmatter_str = stamped_frontmatter(conformed, now)?;let new_id = PageId::new();tx.execute("INSERT INTO pages \@@ -5927,6 +5950,91 @@ pub(crate) mod tests {assert_eq!(total, 1, "no duplicate row for unchanged content");}+ /// OKF conformance happens at this choke point for every writer+ /// (docs/okf.md): a page stored with bare frontmatter comes back+ /// with the required `type`, a `generated {by, at}` stanza, and+ /// provenance derived from the session stamp. Breaking the+ /// conform call fails this test.+ #[test]+ fn stored_pages_are_okf_conformant() {+ let (_tmp, mut conn, ws, proj) = fresh_db();+ let mut p = page(ws, proj, "gotchas/build.md", "watch out");+ p.frontmatter_json = serde_json::json!({+ "title": "Build gotcha",+ "session_id": "0192aaaa-0000-7000-8000-000000000000",+ "agent": "claude-code",+ });+ let id = upsert_page(&mut conn, &p).unwrap();+ let fm: String = conn+ .query_row(+ "SELECT frontmatter_json FROM pages WHERE id = ?1",+ params![id.as_bytes()],+ |r| r.get(0),+ )+ .unwrap();+ let fm: serde_json::Value = serde_json::from_str(&fm).unwrap();+ assert_eq!(fm["type"], "Gotcha");+ assert!(+ fm["generated"]["by"]+ .as_str()+ .unwrap()+ .starts_with("process:ai-memory/")+ );+ assert!(+ fm["generated"]["at"].as_str().unwrap().ends_with('Z'),+ "generated.at stamped on the new version"+ );+ assert_eq!(+ fm["sources"][0]["resource"],+ "ai-memory://session/0192aaaa-0000-7000-8000-000000000000"+ );+ // producer keys survive as extensions+ assert_eq!(fm["agent"], "claude-code");+ }++ /// The critical interaction: conformance adds `generated.at`, which+ /// differs per write — an unchanged page must STILL be a noop, or+ /// every rewrite would supersede itself over a timestamp.+ #[test]+ fn conformance_does_not_break_idempotent_rewrites() {+ let (_tmp, mut conn, ws, proj) = fresh_db();+ let mut p = page(ws, proj, "notes/idem.md", "stable body");+ p.frontmatter_json = serde_json::json!({"title": "Idem"});+ let id1 = upsert_page(&mut conn, &p).unwrap();+ let id2 = upsert_page(&mut conn, &p).unwrap();+ assert_eq!(+ id1, id2,+ "conformed rewrite of identical content superseded"+ );+ let versions: i64 = conn+ .query_row(+ "SELECT COUNT(*) FROM pages WHERE path = ?1",+ params!["notes/idem.md"],+ |r| r.get(0),+ )+ .unwrap();+ assert_eq!(versions, 1);+ }++ /// A producer that already writes a `type` keeps it verbatim — the+ /// choke point repairs, it never overrules.+ #[test]+ fn an_explicit_producer_type_survives_the_choke_point() {+ let (_tmp, mut conn, ws, proj) = fresh_db();+ let mut p = page(ws, proj, "notes/custom.md", "body");+ p.frontmatter_json = serde_json::json!({"type": "Custom Kind"});+ let id = upsert_page(&mut conn, &p).unwrap();+ let fm: String = conn+ .query_row(+ "SELECT frontmatter_json FROM pages WHERE id = ?1",+ params![id.as_bytes()],+ |r| r.get(0),+ )+ .unwrap();+ let fm: serde_json::Value = serde_json::from_str(&fm).unwrap();+ assert_eq!(fm["type"], "Custom Kind");+ }+#[test]fn upsert_page_supersedes_on_frontmatter_change() {let (_tmp, mut conn, ws, proj) = fresh_db();