Skip to content

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.md
index 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.0
unchanged — 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 rmcp
above a quieter `log_level`. A target directive beats the global level
either way, so with `log_level = "error"` or `"off"` the cap re-enabled the
diff --git a/crates/ai-memory-core/src/lib.rs b/crates/ai-memory-core/src/lib.rs
index 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.rs
index 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.rs
index 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's
diff --git a/crates/ai-memory-wiki/src/wiki.rs b/crates/ai-memory-wiki/src/wiki.rs
index 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.md
index 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`,