Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors
Rust
fix(okf): give a date-only expires_at an offset-bearing stale_after (#917)
Felipe Neves Ricardoeaee8357825f
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 4a28b987..1a0baf49 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -48,6 +48,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0unchanged — this only makes the existing warning reliably visible. (#903)### Fixed+- A page whose `expires_at` is a bare date (`2026-10-01`) now gets an OKF+ `stale_after` that names the instant the TTL expires it+ (`2026-10-01T23:59:59.999999Z`) instead of the date copied verbatim. OKF+ v0.2 requires every timestamp to carry an explicit UTC offset, and read a+ bare date as the start of that day, a day earlier than ai-memory's+ end-of-day TTL. An RFC 3339 `expires_at` is still carried unchanged. (#917)- The default log filter's `rmcp=warn` cap (#894) no longer raises rmcpabove a quieter `log_level`. A target directive beats the global leveleither way, so with `log_level = "error"` or `"off"` the cap re-enabled thediff --git a/crates/ai-memory-core/src/lib.rs b/crates/ai-memory-core/src/lib.rsindex 6d320bc5..5293a1d6 100644--- a/crates/ai-memory-core/src/lib.rs+++ b/crates/ai-memory-core/src/lib.rs@@ -68,7 +68,7 @@ pub use observation::{NewObservation, NewSession, Observation, ObservationKind};pub use page::{FeedbackKind, LinkTarget, MAX_ENTITIES_PER_PAGE, MAX_ENTITY_LEN, NewPage, Page, PageEvidence,PageEvidenceKind, Relation, Tier, frontmatter_entity_names, normalize_entities,- normalize_entity,+ normalize_entity, parse_expires_at_instant,};pub use routing_snippet::{COMPACT_SNIPPET_BODY, MARKER_END, MARKER_START, SNIPPET_BODY, compact_block, find_marker_line,diff --git a/crates/ai-memory-core/src/okf.rs b/crates/ai-memory-core/src/okf.rsindex a4566d72..42bef86e 100644--- a/crates/ai-memory-core/src/okf.rs+++ b/crates/ai-memory-core/src/okf.rs@@ -98,12 +98,21 @@ pub fn conform_frontmatter(path: &str, frontmatter: &mut Value) {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.+ // stale_after ← existing TTL. OKF timestamps must carry an explicit+ // UTC offset, but `expires_at` also accepts a bare `YYYY-MM-DD`+ // (end of that day, UTC): render that as the instant it names. An+ // RFC 3339 value already conforms and is carried verbatim, so pages+ // written before this rule keep byte-identical frontmatter.if !map.contains_key("stale_after")&& let Some(expires) = map.get("expires_at").and_then(Value::as_str)+ && let Some(instant) = crate::page::parse_expires_at_instant(expires){- map.insert("stale_after".into(), Value::String(expires.to_string()));+ let stale_after = if expires.trim().parse::<jiff::Timestamp>().is_ok() {+ expires.to_string()+ } else {+ instant.to_string()+ };+ map.insert("stale_after".into(), Value::String(stale_after));}// sources ← session provenance already stamped by the consolidator.@@ -248,6 +257,32 @@ mod tests {assert_eq!(fm["tier"], "episodic");}+ #[test]+ fn a_date_only_ttl_becomes_an_offset_bearing_stale_after() {+ let mut fm = json!({"expires_at": "2026-10-01"});+ conform_frontmatter("notes/x.md", &mut fm);+ let once = fm.clone();+ conform_frontmatter("notes/x.md", &mut fm);+ assert_eq!(once, fm, "second conform changed bytes");+ // The TTL's own reading of a bare date: the end of that day, UTC.+ assert_eq!(fm["stale_after"], "2026-10-01T23:59:59.999999Z");+ assert_eq!(fm["expires_at"], "2026-10-01");+ }++ #[test]+ fn an_rfc3339_ttl_is_carried_into_stale_after_verbatim() {+ let mut fm = json!({"expires_at": "2026-10-01T12:00:00-03:00"});+ conform_frontmatter("notes/x.md", &mut fm);+ assert_eq!(fm["stale_after"], "2026-10-01T12:00:00-03:00");+ }++ #[test]+ fn an_unparseable_ttl_derives_no_stale_after() {+ let mut fm = json!({"expires_at": "soon"});+ conform_frontmatter("notes/x.md", &mut fm);+ assert!(fm.get("stale_after").is_none());+ }+#[test]fn an_explicit_type_is_never_overwritten() {let mut fm = json!({"type": "Custom Thing"});diff --git a/crates/ai-memory-core/src/page.rs b/crates/ai-memory-core/src/page.rsindex 6b97c966..16b7c580 100644--- a/crates/ai-memory-core/src/page.rs+++ b/crates/ai-memory-core/src/page.rs@@ -248,6 +248,24 @@ pub fn frontmatter_entity_names(frontmatter: &serde_json::Value) -> Vec<String>normalize_entities(merged)}+/// The instant a frontmatter `expires_at` value names: an RFC 3339+/// timestamp, or a bare `YYYY-MM-DD` meaning the end of that day in UTC.+/// `None` when the value is neither. The wiki's TTL validation and the+/// OKF `stale_after` derivation both read it, so the two cannot disagree+/// on when a page expires.+#[must_use]+pub fn parse_expires_at_instant(raw: &str) -> Option<Timestamp> {+ let raw = raw.trim();+ if let Ok(ts) = raw.parse::<Timestamp>() {+ return Some(ts);+ }+ let date = raw.parse::<jiff::civil::Date>().ok()?;+ date.at(23, 59, 59, 999_999_000)+ .to_zoned(jiff::tz::TimeZone::UTC)+ .ok()+ .map(|zoned| zoned.timestamp())+}+/// A link target discovered in a page body.////// A bare `[[path]]` / `[label](path)` resolves within the source page'sdiff --git a/crates/ai-memory-wiki/src/wiki.rs b/crates/ai-memory-wiki/src/wiki.rsindex 0c4c4efb..1fedcd16 100644--- a/crates/ai-memory-wiki/src/wiki.rs+++ b/crates/ai-memory-wiki/src/wiki.rs@@ -2454,20 +2454,7 @@ pub(crate) fn parse_expires_at(if raw.is_empty() {return Ok(None);}- if let Ok(ts) = raw.parse::<jiff::Timestamp>() {- return Ok(Some(ts));- }- if let Ok(date) = raw.parse::<jiff::civil::Date>() {- let ts = date- .at(23, 59, 59, 999_999_000)- .to_zoned(jiff::tz::TimeZone::UTC)- .map_err(|e| {- ai_memory_wiki_error(&format!(- "invalid expires_at date in frontmatter for {}: {e}",- path.as_str()- ))- })?- .timestamp();+ if let Some(ts) = ai_memory_core::parse_expires_at_instant(raw) {return Ok(Some(ts));}Err(ai_memory_wiki_error(&format!(@@ -2884,6 +2871,52 @@ mod tests {assert!(ai_memory_core::okf::is_conformant(&parsed.frontmatter));}+ /// OKF requires every timestamp to carry an explicit UTC offset, while+ /// the TTL key also accepts a bare date. The file on disk must name the+ /// instant the TTL machinery hides the page, not the date as typed.+ #[tokio::test]+ async fn a_date_only_ttl_lands_on_disk_as_an_okf_stale_after_instant() {+ 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 frontmatter = serde_json::json!({"title": "Freeze", "expires_at": "2099-08-01"});+ wiki.write_page(req(+ ws,+ proj,+ "notes/freeze.md",+ "release freeze",+ frontmatter.clone(),+ ))+ .await+ .unwrap();++ let raw =+ std::fs::read_to_string(wiki.project_root(ws, proj).join("notes/freeze.md")).unwrap();+ let parsed = crate::markdown::parse(&raw).unwrap();+ assert_eq!(parsed.frontmatter["expires_at"], "2099-08-01");+ assert_eq!(+ parsed.frontmatter["stale_after"],+ "2099-08-01T23:59:59.999999Z"+ );+ let path = PagePath::new("notes/freeze.md").unwrap();+ let ttl = parse_expires_at(&path, &frontmatter).unwrap().unwrap();+ assert_eq!(+ parsed.frontmatter["stale_after"]+ .as_str()+ .unwrap()+ .parse::<jiff::Timestamp>()+ .unwrap(),+ ttl+ );+ }+/// Refused on every platform, not only the case-insensitive ones: the/// wiki is synced between them, so what it accepts cannot depend on the/// filesystem underneath.diff --git a/docs/okf.md b/docs/okf.mdindex f8285e5d..8344e74f 100644--- a/docs/okf.md+++ b/docs/okf.md@@ -58,7 +58,7 @@ families. Summary of what conformance requires:| `generated.by` | actor convention: `process:ai-memory/<version>` for the zero-LLM consolidator and system writers; `<provider-model>` (e.g. `openai-compat/qwen3:32b`) for LLM-written pages; `human:<user>` for wiki edits attributed via the watcher || `generated.at` | the page version's `updated_at` || `sources` | session provenance: pages already stamped with `session_id`/`agent` get `[{resource: "ai-memory://session/<uuid>", author: "<agent>"}]` |-| `stale_after` | existing `expires_at` (TTL), when present |+| `stale_after` | existing `expires_at` (TTL), when present: an RFC 3339 value verbatim, a bare `YYYY-MM-DD` as the end of that day in UTC (`2026-10-01T23:59:59.999999Z`), since OKF timestamps carry an explicit offset || `status` | `deprecated` when TTL-expired but retained; otherwise omitted (spec default `stable`) |Extension fields kept verbatim (unknown keys are conformant): `tier`,