Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors
Rust
fix(okf): encode directory links in generated bundle indexes
Rudy Celeklid49407a391bb
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex da1fca12..3a64c9b1 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -114,6 +114,8 @@ version in [`docs/changelog/`](docs/changelog/):page, aligning belief input aggregation with the lint's resolved/stale split.([#1386](https://github.com/akitaonrails/ai-memory/pull/1386))- Kept the previous backup or OKF export intact when an archive download is interrupted, and publish completed downloads atomically. Successful downloads replace destination symlinks with private files rather than changing their targets or inheriting their permissions. ([#1381](https://github.com/akitaonrails/ai-memory/pull/1381))+- Fixed generated OKF directory indexes so names containing spaces, Markdown punctuation, literal URL delimiters, or Unicode remain readable, clickable links in exports and newly generated migration indexes.+## [3.1.1] - 2026-10-17diff --git a/crates/ai-memory-mcp/src/admin.rs b/crates/ai-memory-mcp/src/admin.rsindex e74963bc..4625c888 100644--- a/crates/ai-memory-mcp/src/admin.rs+++ b/crates/ai-memory-mcp/src/admin.rs@@ -1027,10 +1027,7 @@ async fn build_okf_bundle_file(// prose outside the list structure (some strict OKF validators// read §11.3 as rejecting a stray sentence — issue #960 item 1).families.sort();- let listing: String = families- .iter()- .map(|f| format!("- [{f}/]({f}/)\n"))- .collect();+ let listing = ai_memory_wiki::okf_directory_listing(&families);let index = format!("---\nokf_version: \"0.2\"\n---\n\n# Bundle index — concept files by directory\n\n{listing}");@@ -10340,6 +10337,7 @@ mod tests {let wiki = Wiki::new(tmp.path(), store.writer.clone()).unwrap().with_store_reader(store.reader.clone());+ let web = ai_memory_web::router(store.reader.clone(), wiki.clone());let router = admin_router(AdminState {ingest_metrics: std::sync::Arc::new(ai_memory_core::IngestMetrics::default()),mcp_metrics: std::sync::Arc::new(crate::McpMetrics::default()),@@ -10364,7 +10362,7 @@ mod tests {scope_invalidator: None,trusted_proxy_identity: false,});- (tmp, router)+ (tmp, router.nest("/web", web))}/// The exported tarball is a valid OKF v0.2 bundle: fresh index.md@@ -10424,6 +10422,87 @@ mod tests {assert_eq!(fm["type"], "Gotcha");}+ #[tokio::test]+ async fn export_okf_directory_index_links_are_clickable() {+ let (_tmp, router) = read_page_test_router();+ let cases = [+ ("notes", "notes", "notes/"),+ ("team notes", "team%20notes", "team notes/"),+ ("notes [draft", "notes%20%5Bdraft", "notes [draft/"),+ ("c# 50%", "c%23%2050%25", "c# 50%/"),+ ("日本語", "%E6%97%A5%E6%9C%AC%E8%AA%9E", "日本語/"),+ ("©", "%26copy%3B", "&copy;/"),+ ("`draft`", "%60draft%60", "`draft`/"),+ ("_draft_", "_draft_", "_draft_/"),+ ];+ for (family, _, _) in cases {+ post_write_page(+ &router,+ "default",+ "scratch",+ &format!("{family}/seed.md"),+ "# Seed",+ )+ .await;+ }+ let response = router+ .clone()+ .oneshot(+ Request::builder()+ .method("POST")+ .uri("/admin/export-okf?workspace=default&project=scratch")+ .body(Body::empty())+ .unwrap(),+ )+ .await+ .unwrap();+ assert_eq!(response.status(), StatusCode::OK);+ let bytes = axum::body::to_bytes(response.into_body(), usize::MAX)+ .await+ .unwrap();+ let mut archive =+ tar::Archive::new(flate2::read::GzDecoder::new(std::io::Cursor::new(bytes)));+ let mut index = String::new();+ for entry in archive.entries().unwrap() {+ let mut entry = entry.unwrap();+ if entry.path().unwrap().as_ref() == std::path::Path::new("index.md") {+ use std::io::Read as _;+ entry.read_to_string(&mut index).unwrap();+ }+ }+ assert!(+ index.contains("- [notes/](notes/)\n"),+ "ordinary listing changed: {index}"+ );+ let body = ai_memory_wiki::parse(&index).unwrap().body;+ post_write_page(&router, "default", "scratch", "export-index.md", &body).await;+ let response = router+ .oneshot(+ Request::builder()+ .uri("/web/w/default/scratch/p/export-index.md")+ .body(Body::empty())+ .unwrap(),+ )+ .await+ .unwrap();+ assert_eq!(response.status(), StatusCode::OK);+ let html = String::from_utf8(+ axum::body::to_bytes(response.into_body(), usize::MAX)+ .await+ .unwrap()+ .to_vec(),+ )+ .unwrap();+ for (family, encoded, label) in cases {+ assert!(+ html.contains(&format!(+ "<a href=\"w/default/scratch/p/{encoded}\">{label}</a>"+ )),+ "rendered directory link missing or changed: {family}: {html}"+ );+ }+ }+/// Issue #960 item 1: strict OKF validators read §11.3 ("follows the/// structure in §8") as rejecting prose outside the list structure. The/// generated `index.md` body, once its heading line is stripped, mustdiff --git a/crates/ai-memory-wiki/src/lib.rs b/crates/ai-memory-wiki/src/lib.rsindex e859004b..af1c322d 100644--- a/crates/ai-memory-wiki/src/lib.rs+++ b/crates/ai-memory-wiki/src/lib.rs@@ -15,6 +15,7 @@ mod git;mod ledger;mod markdown;pub mod migrations;+mod okf_index;mod watcher;mod wiki;@@ -32,6 +33,7 @@ pub use markdown::{extract_links, extract_relation_links, parse, rewrite_local_wikilinks,};pub use migrations::run_pending as run_wiki_migrations;+pub use okf_index::okf_directory_listing;pub use watcher::{DEBOUNCE_WINDOW, RECONCILE_INTERVAL, WatcherHandle};pub use wiki::{ConditionalWrite, EventLedgerFile, MoveSessionOutcome, PAGE_CHECKPOINT_WALK_LIMIT,diff --git a/crates/ai-memory-wiki/src/migrations/m2026_09_okf_conformance.rs b/crates/ai-memory-wiki/src/migrations/m2026_09_okf_conformance.rsindex 54fa8be2..ab9afea1 100644--- a/crates/ai-memory-wiki/src/migrations/m2026_09_okf_conformance.rs+++ b/crates/ai-memory-wiki/src/migrations/m2026_09_okf_conformance.rs@@ -374,10 +374,7 @@ fn ensure_bundle_indexes(git: &crate::git::GitAdapter) -> WikiResult<()> {}).unwrap_or_default();families.sort();- let listing = families- .iter()- .map(|f| format!("- [{f}/]({f}/)\n"))- .collect::<String>();+ let listing = crate::okf_directory_listing(&families);let body =format!("# Bundle index\n\nConcept files live in these directories:\n\n{listing}");let content = format!("---\nokf_version: \"0.2\"\n---\n\n{body}");@@ -646,6 +643,33 @@ mod tests {);}+ #[test]+ fn bundle_index_escapes_directory_links_and_preserves_existing_index() {+ let tmp = TempDir::new().unwrap();+ for family in ["notes", "team notes", "c# 50%"] {+ std::fs::create_dir_all(tmp.path().join("w/p").join(family)).unwrap();+ }+ let git = crate::git::GitAdapter::open_or_init(tmp.path()).unwrap();+ ensure_bundle_indexes(&git).unwrap();+ let index = tmp.path().join("w/p/index.md");+ let content = std::fs::read_to_string(&index).unwrap();+ assert!(content.contains("- [notes/](notes/)\n"), "{content}");+ assert!(+ content.contains("(team%20notes/)"),+ "migration directory destination must be URL encoded: {content}"+ );+ assert!(+ content.contains("(c%23%2050%25/)"),+ "literal URL delimiters must stay in the directory name: {content}"+ );+ git.write_atomic(&index, b"operator-owned index\n").unwrap();+ ensure_bundle_indexes(&git).unwrap();+ assert_eq!(+ std::fs::read_to_string(index).unwrap(),+ "operator-owned index\n"+ );+ }+// ---- #633: the safety archive must be taken BEFORE the DB migration ----/// The core assertion for #633: the pre-open snapshot captures the DB as itdiff --git a/crates/ai-memory-wiki/src/okf_index.rs b/crates/ai-memory-wiki/src/okf_index.rsnew file mode 100644index 00000000..903e2a62--- /dev/null+++ b/crates/ai-memory-wiki/src/okf_index.rs@@ -0,0 +1,40 @@+//! Literal directory labels and URL destinations for both OKF index writers.++use std::fmt::Write as _;++/// Render the already-ordered top-level directories of an OKF bundle.+///+/// Directory names are filesystem text, not Markdown or pre-encoded URLs.+/// Encoding each segment before adding the separator keeps literal percent+/// signs and fragment delimiters in the name when a reader follows the link.+#[must_use]+pub fn okf_directory_listing(families: &[String]) -> String {+ let mut listing = String::new();+ for family in families {+ let mut destination = String::new();+ for byte in family.bytes() {+ match byte {+ b'A'..=b'Z' | b'a'..=b'z' | b'0'..=b'9' | b'-' | b'.' | b'_' | b'~' => {+ destination.push(char::from(byte));+ }+ _ => {+ let _ = write!(destination, "%{byte:02X}");+ }+ }+ }+ let mut label = String::new();+ let paired_underscores = family.matches('_').count() > 1;+ for character in family.chars() {+ if matches!(+ character,+ '\\' | '[' | ']' | '(' | ')' | '`' | '*' | '&' | '<' | '>' | '~'+ ) || (character == '_' && paired_underscores)+ {+ label.push('\\');+ }+ label.push(character);+ }+ let _ = writeln!(listing, "- [{label}/]({destination}/)");+ }+ listing+}