Skip to content

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.rs
index 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.rs
new file mode 100644
index 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.rs
index 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();