Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors
Rust
fix(export-okf): skip the rotated hook ledger instead of failing the bundle
Samir Hanna Verza6dc2091dd48d
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 32bf6924..b8c55845 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -7,6 +7,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0## [Unreleased]+### Fixed+- `export-okf` no longer refuses to export any project that has captured an+ observation. The bundle walk skipped the reserved names `index.md` and+ `log.md`, but not the rotated hook ledger `log-YYYY-MM.md` the server itself+ appends to — which carries no frontmatter, so `okf::is_conformant` failed it+ and aborted the whole export with `422 page log-YYYY-MM.md is not+ OKF-conformant; run the server once to migrate before exporting`. Migrating+ could not help: the OKF migration deliberately skips ledgers (#669), so the+ file the export demanded be conformed stays frontmatter-less forever. The+ ledger is raw capture rather than a concept file, so it is now dropped from+ the bundle exactly as `log.md` already was, sharing the migration scan's+ content gate — a prose page that happens to be named `log-2026-09.md` still+ ships and still has to declare a `type`. (#748)+## [2.3.0] - 2026-09-16### Addeddiff --git a/crates/ai-memory-mcp/src/admin.rs b/crates/ai-memory-mcp/src/admin.rsindex bd519502..09f638f8 100644--- a/crates/ai-memory-mcp/src/admin.rs+++ b/crates/ai-memory-mcp/src/admin.rs@@ -940,6 +940,16 @@ async fn build_okf_bundle_file(if name == "index.md" || name == "log.md" {continue; // regenerated / not adopted}+ // A rotated event ledger is the same raw hook capture as the+ // `log.md` above, only past a month boundary — it carries no+ // frontmatter, so the conformance gate below failed the whole+ // export for every project that ever captured an observation+ // (#748). The check is content-gated exactly like the+ // migration scan's (#669), so a prose page that happens to be+ // named `log-2026-09.md` still ships and still has to conform.+ if ai_memory_wiki::is_rotated_event_ledger(&path) {+ continue;+ }let raw = std::fs::read_to_string(&path)?;let fm = ai_memory_wiki::parse(&raw).map(|m| m.frontmatter)@@ -8566,15 +8576,89 @@ mod tests {);}- /// A bundle with a non-conformant page must fail the export rather- /// than ship something a strict reader rejects.+ /// The project root of any store that ever captured an observation+ /// holds a rotated hook ledger (`log-YYYY-MM.md`, no frontmatter).+ /// It is raw capture, not a concept file: the export drops it the+ /// way it already drops `log.md`, instead of failing the whole+ /// bundle on the conformance gate (#748). Both shapes are covered —+ /// a bare ledger and one the OKF migration stamped frontmatter onto.#[tokio::test]- async fn export_okf_refuses_a_nonconformant_page() {+ async fn export_okf_skips_the_rotated_event_ledger() {let (tmp, router) = read_page_test_router();post_write_page(&router, "default", "scratch", "notes/a.md", "fine").await;- // Fabricate a pre-migration file next to it. The wiki root also- // holds `.git`; read_dir order is arbitrary, so select the- // UUID-named scope dirs explicitly.+ let proj_dir = scratch_project_dir(tmp.path());+ std::fs::write(+ proj_dir.join("log-2026-08.md"),+ "## [2026-08-01T00:00:00Z] session_start | opened scratch\n",+ )+ .unwrap();+ std::fs::write(+ proj_dir.join("log-2026-07.md"),+ "---\ntype: Note\n---\n\n## [2026-07-01T00:00:00Z] session_start | opened scratch\n",+ )+ .unwrap();++ let resp = router+ .clone()+ .oneshot(+ Request::builder()+ .method("POST")+ .uri("/admin/export-okf?workspace=default&project=scratch")+ .body(Body::empty())+ .unwrap(),+ )+ .await+ .unwrap();+ assert_eq!(resp.status(), StatusCode::OK);+ let bytes = axum::body::to_bytes(resp.into_body(), usize::MAX)+ .await+ .unwrap();+ let dec = flate2::read::GzDecoder::new(std::io::Cursor::new(bytes.to_vec()));+ let mut ar = tar::Archive::new(dec);+ let names: Vec<String> = ar+ .entries()+ .unwrap()+ .map(|e| e.unwrap().path().unwrap().display().to_string())+ .collect();+ assert!(names.iter().any(|n| n == "notes/a.md"), "{names:?}");+ assert!(+ !names.iter().any(|n| n.starts_with("log-")),+ "raw event ledgers must not ship: {names:?}"+ );+ }++ /// Content gate control for #748: the ledger carve-out keys off the+ /// body, so an ordinary page named like a ledger is still a page —+ /// it ships in the bundle, and it still has to declare a `type`.+ #[tokio::test]+ async fn export_okf_still_conforms_a_prose_page_named_like_a_ledger() {+ let (tmp, router) = read_page_test_router();+ post_write_page(&router, "default", "scratch", "notes/a.md", "fine").await;+ let proj_dir = scratch_project_dir(tmp.path());+ std::fs::write(+ proj_dir.join("log-2026-09.md"),+ "---\ntitle: September log\n---\n\nProse about last month, not hook output.\n",+ )+ .unwrap();++ let resp = router+ .clone()+ .oneshot(+ Request::builder()+ .method("POST")+ .uri("/admin/export-okf?workspace=default&project=scratch")+ .body(Body::empty())+ .unwrap(),+ )+ .await+ .unwrap();+ assert_eq!(resp.status(), StatusCode::UNPROCESSABLE_ENTITY);+ }++ /// The single project scope dir under a freshly seeded `scratch`+ /// store. The wiki root also holds `.git`, and `read_dir` order is+ /// arbitrary, so the UUID-named scope dirs are selected explicitly.+ fn scratch_project_dir(data_dir: &std::path::Path) -> std::path::PathBuf {let uuid_dir = |parent: &std::path::Path| {std::fs::read_dir(parent).unwrap()@@ -8583,8 +8667,17 @@ mod tests {.find(|p| p.is_dir() && p.file_name().is_none_or(|n| n != ".git")).expect("scope dir")};- let ws_dir = uuid_dir(&tmp.path().join("wiki"));- let proj_dir = uuid_dir(&ws_dir);+ uuid_dir(&uuid_dir(&data_dir.join("wiki")))+ }++ /// A bundle with a non-conformant page must fail the export rather+ /// than ship something a strict reader rejects.+ #[tokio::test]+ async fn export_okf_refuses_a_nonconformant_page() {+ let (tmp, router) = read_page_test_router();+ post_write_page(&router, "default", "scratch", "notes/a.md", "fine").await;+ // Fabricate a pre-migration file next to it.+ let proj_dir = scratch_project_dir(tmp.path());std::fs::write(proj_dir.join("notes/legacy.md"),"---\ntitle: Legacy\n---\nno type here",diff --git a/crates/ai-memory-wiki/src/ledger.rs b/crates/ai-memory-wiki/src/ledger.rsindex b388467c..3b09dec4 100644--- a/crates/ai-memory-wiki/src/ledger.rs+++ b/crates/ai-memory-wiki/src/ledger.rs@@ -1,10 +1,11 @@//! Shared helpers for recognizing the raw hook event ledger//! (`log.md` / `log-YYYY-MM.md`) by filename shape and by content.//!-//! Both the watcher's indexer (#660) and the OKF conformance migration-//! (#669) must treat these files identically: a reserved-looking filename-//! is only a ledger when its content opens with a hook log entry, never on-//! filename alone (an ordinary page can be named `log-2026-09.md`).+//! The watcher's indexer (#660), the OKF conformance migration (#669) and+//! the OKF bundle export (#748) must treat these files identically: a+//! reserved-looking filename is only a ledger when its content opens with a+//! hook log entry, never on filename alone (an ordinary page can be named+//! `log-2026-09.md`).use std::path::Path;@@ -81,6 +82,21 @@ pub(crate) fn opens_with_log_ledger(abs: &Path) -> bool {}}+/// True when `abs` is a **rotated** event ledger (`log-YYYY-MM.md`) and not an+/// ordinary page that merely carries that name: the filename shape and the+/// body's opening line have to agree, the same content gate the migration scan+/// applies (#669).+///+/// `log.md` is left to the caller: OKF reserves that name, so a consumer of+/// this crate already excludes it by reserved name, with or without ledger+/// content. Only the rotated form needs ai-memory-specific knowledge.+pub fn is_rotated_event_ledger(abs: &Path) -> bool {+ abs.file_name()+ .and_then(|n| n.to_str())+ .is_some_and(is_rotated_log_filename)+ && opens_with_log_ledger(abs)+}+/// Upper bound on frontmatter lines scanned by [`opens_with_log_ledger`]./// Conformant OKF frontmatter is a handful of keys; this is slack, not a/// format limit.diff --git a/crates/ai-memory-wiki/src/lib.rs b/crates/ai-memory-wiki/src/lib.rsindex 3a3978c0..6d20ca1e 100644--- a/crates/ai-memory-wiki/src/lib.rs+++ b/crates/ai-memory-wiki/src/lib.rs@@ -23,6 +23,7 @@ pub use admission::{pub use atomic::write_atomic;pub use error::{WikiError, WikiResult};pub use git::{COMMIT_AUTHOR_EMAIL, COMMIT_AUTHOR_NAME, GitAdapter};+pub use ledger::is_rotated_event_ledger;pub use markdown::{Markdown, derive_title, emit, parse};pub use migrations::run_pending as run_wiki_migrations;pub use watcher::{DEBOUNCE_WINDOW, RECONCILE_INTERVAL, WatcherHandle};diff --git a/docs/okf.md b/docs/okf.mdindex dcd6d37c..f8285e5d 100644--- a/docs/okf.md+++ b/docs/okf.md@@ -72,8 +72,16 @@ knowledge is a project. Each project dir gets a generated `index.md`(frontmatter `okf_version: "0.2"`, body = directory listing). Theexisting `_meta.md` scope manifest is unchanged — it is ai-memory'sidentity record; `index.md` is the OKF-facing description. Nothing in-the current tree writes `index.md` or `log.md` (verified), so the-reserved names are free. `log.md` is not adopted: git is the log.+the current tree writes `index.md`, so that reserved name is free.+`log.md` is not adopted: git is the log.++The hooks *do* write a raw per-month event ledger at the project root+(`log-YYYY-MM.md` — `## [ts] event | title` lines, no frontmatter). It+is capture, not a concept file, so the export drops it exactly as it+drops `log.md`, and the conformance gate never sees it (#748). The+exclusion is content-gated, the same way the migration scan's is+(#669): an ordinary page that happens to be named `log-2026-09.md`+still ships in the bundle and still has to declare a `type`.## Enforcement: one choke point