Skip to content

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.md
index 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
### Added
diff --git a/crates/ai-memory-mcp/src/admin.rs b/crates/ai-memory-mcp/src/admin.rs
index 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.rs
index 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.rs
index 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.md
index 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). The
existing `_meta.md` scope manifest is unchanged — it is ai-memory's
identity 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