Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors
Rust
Rewrite local wikilinks to bundle-relative Markdown links on export
Maxsuel Einsteinc0c6c1852f1f
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 64558451..ffe69bdc 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -170,6 +170,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0missing, so a generic OKF consumer sees both §4.1-recommended keys. Thebackfill only ever changes the bundle's copy, never the on-disk wiki file.(#960)+- `export-okf` now rewrites a page's local `[[wikilink]]`s to bundle-relative+ standard Markdown links, since a generic OKF consumer has no idea what+ `[[decisions/b.md]]` means. A cross-project or cross-workspace wikilink has+ no Markdown equivalent and ships untouched, as literal `[[...]]` text.+ (#960)## [2.4.1] - 2026-09-25diff --git a/crates/ai-memory-mcp/src/admin.rs b/crates/ai-memory-mcp/src/admin.rsindex 453d1f5e..c9cd2400 100644--- a/crates/ai-memory-mcp/src/admin.rs+++ b/crates/ai-memory-mcp/src/admin.rs@@ -887,7 +887,7 @@ async fn handle_export_okf(Ok(ids) => ids,Err((status, body)) => return (status, body).into_response(),};- match build_okf_bundle_file(&state, ids.0, ids.1).await {+ match build_okf_bundle_file(&state, ids.0, ids.1, q.project.trim()).await {Ok(file) => Response::builder().status(StatusCode::OK).header(header::CONTENT_TYPE, "application/gzip")@@ -914,6 +914,7 @@ async fn build_okf_bundle_file(state: &AdminState,ws: ai_memory_core::WorkspaceId,proj: ai_memory_core::ProjectId,+ project_name: &str,) -> anyhow::Result<tokio::fs::File> {let bundle_dir = state.data_dir@@ -993,8 +994,9 @@ async fn build_okf_bundle_file(.iter().map(|f| format!("- [{f}/]({f}/)\n")).collect();- let index =- format!("---\nokf_version: \"0.2\"\n---\n\n# Bundle index — concept files by directory\n\n{listing}");+ let index = format!(+ "---\nokf_version: \"0.2\"\n---\n\n# Bundle index — concept files by directory\n\n{listing}"+ );let mut header = tar::Header::new_gnu();header.set_size(index.len() as u64);header.set_mode(0o644);@@ -1003,7 +1005,7 @@ async fn build_okf_bundle_file(for (path, raw) in files {let rel = path.strip_prefix(&bundle_dir).unwrap_or(&path);let rel_str = rel.to_string_lossy().replace('\\', "/");- let bytes = augment_page_for_export(&raw, &rel_str)?;+ let bytes = augment_page_for_export(&raw, &rel_str, project_name)?;let mut header = tar::Header::new_gnu();header.set_size(bytes.len() as u64);header.set_mode(0o644);@@ -1019,10 +1021,15 @@ async fn build_okf_bundle_file(}/// Export-only augmentation of one wiki page's bytes for the OKF bundle:-/// backfills `title`/`description` when derivable (issue #960 item 2).+/// backfills `title`/`description` when derivable and rewrites local+/// wikilinks to bundle-relative Markdown links (issue #960 items 2 and 3)./// Never touches the on-disk wiki file — the caller tars the returned/// bytes instead of the source file.-fn augment_page_for_export(raw: &str, rel_path: &str) -> anyhow::Result<Vec<u8>> {+fn augment_page_for_export(+ raw: &str,+ rel_path: &str,+ project_name: &str,+) -> anyhow::Result<Vec<u8>> {let page_path = ai_memory_core::PagePath::new(rel_path.to_string())?;let mut md = ai_memory_wiki::parse(raw)?;@@ -1066,12 +1073,11 @@ fn augment_page_for_export(raw: &str, rel_path: &str) -> anyhow::Result<Vec<u8>>map.insert("title".into(), serde_json::Value::String(title));}if let Some(description) = description {- map.insert(- "description".into(),- serde_json::Value::String(description),- );+ map.insert("description".into(), serde_json::Value::String(description));}+ md.body = ai_memory_wiki::rewrite_local_wikilinks(&md.body, &page_path, project_name);+Ok(ai_memory_wiki::emit(&md)?.into_bytes())}@@ -8619,7 +8625,14 @@ mod tests {#[tokio::test]async fn export_okf_index_has_no_prose_outside_the_list() {let (_tmp, router) = read_page_test_router();- post_write_page(&router, "default", "scratch", "gotchas/build.md", "watch out").await;+ post_write_page(+ &router,+ "default",+ "scratch",+ "gotchas/build.md",+ "watch out",+ )+ .await;let resp = router.clone()@@ -8749,6 +8762,70 @@ mod tests {assert!(on_disk_fm.get("title").is_none(), "{on_disk_fm:?}");}+ /// Issue #960 item 3: a generic OKF consumer has no idea what+ /// `[[decisions/b.md]]` means. Local wikilinks become bundle-relative+ /// Markdown links at export; a cross-project wikilink has no Markdown+ /// equivalent and ships untouched.+ #[tokio::test]+ async fn export_okf_rewrites_local_wikilinks_to_relative_markdown_links() {+ let (tmp, router) = read_page_test_router();+ post_write_page(&router, "default", "scratch", "notes/seed.md", "seed").await;+ let proj_dir = scratch_project_dir(tmp.path());+ std::fs::create_dir_all(proj_dir.join("concepts")).unwrap();+ std::fs::create_dir_all(proj_dir.join("decisions")).unwrap();+ std::fs::write(+ proj_dir.join("decisions/b.md"),+ "---\ntype: Decision\n---\n\nB.\n",+ )+ .unwrap();+ std::fs::write(+ proj_dir.join("concepts/a.md"),+ "---\ntype: Concept\n---\n\nSee [[decisions/b.md]] and [[other-project:x.md]].\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 mut a_body = String::new();+ for entry in ar.entries().unwrap() {+ let mut entry = entry.unwrap();+ if entry.path().unwrap().display().to_string() == "concepts/a.md" {+ use std::io::Read as _;+ entry.read_to_string(&mut a_body).unwrap();+ }+ }+ let parsed = ai_memory_wiki::parse(&a_body).unwrap();+ assert!(+ parsed.body.contains("[decisions/b.md](../decisions/b.md)"),+ "{}",+ parsed.body+ );+ assert!(+ parsed.body.contains("[[other-project:x.md]]"),+ "cross-project wikilink must ship untouched: {}",+ parsed.body+ );++ // Never mutated on disk.+ let on_disk = std::fs::read_to_string(proj_dir.join("concepts/a.md")).unwrap();+ assert!(on_disk.contains("[[decisions/b.md]]"));+ }+/// Post-audit regression: the things a REAL deployment's tree holds/// beside concept pages — typed scope manifests and _pending/// proposal sidecars — must not block the export. Sidecars arediff --git a/crates/ai-memory-wiki/src/lib.rs b/crates/ai-memory-wiki/src/lib.rsindex 6d20ca1e..ef50f6d3 100644--- a/crates/ai-memory-wiki/src/lib.rs+++ b/crates/ai-memory-wiki/src/lib.rs@@ -24,7 +24,7 @@ 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 markdown::{Markdown, derive_title, emit, parse, rewrite_local_wikilinks};pub use migrations::run_pending as run_wiki_migrations;pub use watcher::{DEBOUNCE_WINDOW, RECONCILE_INTERVAL, WatcherHandle};pub use wiki::{MoveSessionOutcome, PurgeSessionOutcome, SessionPageFile, Wiki, WritePageRequest};diff --git a/crates/ai-memory-wiki/src/markdown.rs b/crates/ai-memory-wiki/src/markdown.rsindex 1839c093..dff16889 100644--- a/crates/ai-memory-wiki/src/markdown.rs+++ b/crates/ai-memory-wiki/src/markdown.rs@@ -7,6 +7,7 @@//! round-trip predictable.use std::collections::BTreeSet;+use std::ops::Range;use ai_memory_core::{LinkTarget, PagePath};use serde::{Deserialize, Serialize};@@ -176,13 +177,34 @@ pub fn extract_links(body: &str, page_path: &PagePath) -> Vec<LinkTarget> {/// A span that continues onto the next line is not seen, as the line-based/// fence check above does not see an indented code block either.fn blank_inline_code(line: &str) -> std::borrow::Cow<'_, str> {- if !line.contains('`') {+ let spans = inline_code_spans(line);+ if spans.is_empty() {return std::borrow::Cow::Borrowed(line);}- let bytes = line.as_bytes();- let run_at = |i: usize| bytes[i..].iter().take_while(|&&b| b == b'`').count();let mut out = String::with_capacity(line.len());let mut copied = 0;+ for span in spans {+ out.push_str(&line[copied..span.start]);+ out.extend(std::iter::repeat_n(' ', line[span.clone()].chars().count()));+ copied = span.end;+ }+ out.push_str(&line[copied..]);+ std::borrow::Cow::Owned(out)+}++/// Byte ranges of inline code spans in `line`, in document order and+/// without overlap. A run of `open` backticks opens a span; only a run of+/// the same length closes it (CommonMark 6.1). A run with no matching+/// closer on the line is literal text, not a span. Shared by+/// [`blank_inline_code`] (link extraction) and the wikilink-to-Markdown+/// rewriter so both treat "what the renderer shows as code" identically.+fn inline_code_spans(line: &str) -> Vec<Range<usize>> {+ if !line.contains('`') {+ return Vec::new();+ }+ let bytes = line.as_bytes();+ let run_at = |i: usize| bytes[i..].iter().take_while(|&&b| b == b'`').count();+ let mut spans = Vec::new();let mut i = 0;while i < bytes.len() {if bytes[i] != b'`' {@@ -205,17 +227,15 @@ fn blank_inline_code(line: &str) -> std::borrow::Cow<'_, str> {j += 1;}};- let Some(end) = close else {- i += open;- continue;- };- out.push_str(&line[copied..i]);- out.extend(std::iter::repeat_n(' ', line[i..end].chars().count()));- copied = end;- i = end;+ match close {+ Some(end) => {+ spans.push(i..end);+ i = end;+ }+ None => i += open,+ }}- out.push_str(&line[copied..]);- std::borrow::Cow::Owned(out)+ spans}/// Body wikilinks plus typed `relations:` frontmatter edges — the full@@ -359,6 +379,180 @@ fn split_scope(target: &str) -> LinkKey {(None, None, target.to_string())}+/// Rewrite `body`'s LOCAL wikilinks (`[[target]]`, `[[target|label]]`, no+/// scope prefix, or an explicit scope prefix naming `own_project`) into+/// bundle-relative standard Markdown links (`[label](relative/path.md)`),+/// computed from `page_path`'s own directory depth. A cross-project+/// (`[[project:path]]`) or cross-workspace (`[[workspace/project:path]]`)+/// wikilink that does not resolve to `own_project` is left as literal+/// `[[...]]` text — no bundle-relative equivalent exists across bundle+/// boundaries. Export-only: this never runs on the write path, so it never+/// touches an on-disk wiki file.+///+/// Skips fenced code blocks and inline code spans exactly like+/// [`extract_links`] does, reusing the same fence/inline-code detection so+/// the two never disagree about what counts as code. Malformed or empty+/// targets are left untouched, mirroring [`extract_links`]'s own leniency;+/// this never panics on any body content.+#[must_use]+pub fn rewrite_local_wikilinks(body: &str, page_path: &PagePath, own_project: &str) -> String {+ let mut out = String::with_capacity(body.len() + 64);+ let mut in_fence = false;+ for raw_line in body.split_inclusive('\n') {+ let (line, terminator) = split_line_terminator(raw_line);+ let trimmed = line.trim_start();+ if trimmed.starts_with("```") || trimmed.starts_with("~~~") {+ in_fence = !in_fence;+ out.push_str(line);+ out.push_str(terminator);+ continue;+ }+ if in_fence {+ out.push_str(line);+ out.push_str(terminator);+ continue;+ }+ rewrite_wikilinks_in_line(line, page_path, own_project, &mut out);+ out.push_str(terminator);+ }+ out+}++/// Split a `split_inclusive('\n')` line into its content and line-ending,+/// so a rewrite can copy the ending back verbatim (LF or CRLF).+fn split_line_terminator(raw: &str) -> (&str, &str) {+ if let Some(stripped) = raw.strip_suffix("\r\n") {+ (stripped, "\r\n")+ } else if let Some(stripped) = raw.strip_suffix('\n') {+ (stripped, "\n")+ } else {+ (raw, "")+ }+}++fn rewrite_wikilinks_in_line(+ line: &str,+ page_path: &PagePath,+ own_project: &str,+ out: &mut String,+) {+ let code_spans = inline_code_spans(line);+ let mut pos = 0;+ for span in &code_spans {+ rewrite_wikilinks_in_segment(&line[pos..span.start], page_path, own_project, out);+ out.push_str(&line[span.clone()]);+ pos = span.end;+ }+ rewrite_wikilinks_in_segment(&line[pos..], page_path, own_project, out);+}++fn rewrite_wikilinks_in_segment(+ seg: &str,+ page_path: &PagePath,+ own_project: &str,+ out: &mut String,+) {+ let mut rest = seg;+ loop {+ let Some(start) = rest.find("[[") else {+ out.push_str(rest);+ return;+ };+ out.push_str(&rest[..start]);+ let after_start = &rest[start + 2..];+ let Some(end) = after_start.find("]]") else {+ out.push_str(&rest[start..]);+ return;+ };+ let raw = &after_start[..end];+ match resolve_local_wikilink(raw, page_path, own_project) {+ Some((href, label)) => {+ out.push('[');+ out.push_str(&escape_markdown_link_label(&label));+ out.push_str("](");+ out.push_str(&href);+ out.push(')');+ }+ None => {+ out.push_str("[[");+ out.push_str(raw);+ out.push_str("]]");+ }+ }+ rest = &after_start[end + 2..];+ }+}++/// Resolve a local `[[...]]` wikilink target into `(bundle-relative href,+/// display label)`. Returns `None` when the target is cross-project,+/// cross-workspace, empty, or otherwise not a page — the caller then keeps+/// the literal `[[...]]`.+fn resolve_local_wikilink(+ raw: &str,+ page_path: &PagePath,+ own_project: &str,+) -> Option<(String, String)> {+ let (target_part, label) = raw+ .split_once('|')+ .map_or((raw, None), |(t, l)| (t, Some(l)));+ let target_part = target_part.trim();+ let (workspace, project, path_part) = split_scope(target_part);+ if workspace.is_some() {+ return None; // no cross-workspace Markdown equivalent+ }+ if let Some(project) = &project+ && project != own_project+ {+ return None; // no cross-project Markdown equivalent+ }+ // Resolve exactly as `extract_wikilinks` would: root-project-relative+ // (wikilink targets are project-root-relative, not relative to the+ // source page — `page_path` is unused on this branch of+ // `normalize_link_target`/`resolve_relative`), `.md` appended,+ // traversal collapsed.+ let target = normalize_link_target(&path_part, page_path, true)?;+ let page_dir: Vec<&str> = page_path+ .as_str()+ .rsplit_once('/')+ .map_or_else(Vec::new, |(dir, _)| {+ dir.split('/').filter(|s| !s.is_empty()).collect()+ });+ let href = relative_href(&page_dir, &target);+ let display = label.map_or(target_part, str::trim).to_string();+ Some((href, display))+}++/// Compute a relative path from `page_dir` (a page's own directory,+/// components only, no filename) to `target` (a root-project-relative+/// page path, e.g. `decisions/b.md`), the way a `.md` link on disk in the+/// exported bundle needs it.+fn relative_href(page_dir: &[&str], target: &str) -> String {+ let target_components: Vec<&str> = target.split('/').collect();+ let target_dir = &target_components[..target_components.len().saturating_sub(1)];+ let common = page_dir+ .iter()+ .zip(target_dir.iter())+ .take_while(|(a, b)| a == b)+ .count();+ let ups = page_dir.len() - common;+ let mut parts: Vec<&str> = Vec::with_capacity(ups + target_components.len() - common);+ parts.extend(std::iter::repeat_n("..", ups));+ parts.extend(&target_components[common..]);+ parts.join("/")+}++/// Escape characters that would prematurely close a Markdown link label+/// (`[<label>](<href>)`): brackets, the backslash, and parentheses — an+/// unescaped `)` inside the label closes the link early.+fn escape_markdown_link_label(label: &str) -> String {+ label+ .replace('\\', r"\\")+ .replace('[', r"\[")+ .replace(']', r"\]")+ .replace('(', r"\(")+ .replace(')', r"\)")+}+fn extract_wikilinks(line: &str, page_path: &PagePath, out: &mut BTreeSet<LinkKey>) {let mut rest = line;while let Some(start) = rest.find("[[") {@@ -818,4 +1012,101 @@ mod tests {]);}++ #[test]+ fn rewrite_local_wikilinks_resolves_at_various_depths() {+ // concepts/a.md -> decisions/b.md: up one, then into decisions/.+ let a = PagePath::new("concepts/a.md").unwrap();+ assert_eq!(+ rewrite_local_wikilinks("See [[decisions/b.md]].", &a, "proj"),+ "See [decisions/b.md](../decisions/b.md)."+ );++ // Bundle root -> a nested page: no "../" needed.+ let root = PagePath::new("a.md").unwrap();+ assert_eq!(+ rewrite_local_wikilinks("[[concepts/c.md]]", &root, "proj"),+ "[concepts/c.md](concepts/c.md)"+ );++ // Same directory: no "../" and no shared-prefix repetition.+ assert_eq!(+ rewrite_local_wikilinks("[[concepts/c.md]]", &a, "proj"),+ "[concepts/c.md](c.md)"+ );++ // Two levels deep.+ let nested = PagePath::new("a/b/c.md").unwrap();+ assert_eq!(+ rewrite_local_wikilinks("[[decisions/d.md]]", &nested, "proj"),+ "[decisions/d.md](../../decisions/d.md)"+ );+ }++ #[test]+ fn rewrite_local_wikilinks_preserves_explicit_label() {+ let path = PagePath::new("concepts/a.md").unwrap();+ assert_eq!(+ rewrite_local_wikilinks("[[decisions/b.md|the decision]]", &path, "proj"),+ "[the decision](../decisions/b.md)"+ );+ }++ #[test]+ fn rewrite_local_wikilinks_leaves_cross_project_untouched() {+ let path = PagePath::new("concepts/a.md").unwrap();+ assert_eq!(+ rewrite_local_wikilinks("[[other-project:decisions/b.md]]", &path, "proj"),+ "[[other-project:decisions/b.md]]"+ );+ assert_eq!(+ rewrite_local_wikilinks("[[ws/other-project:decisions/b.md]]", &path, "proj"),+ "[[ws/other-project:decisions/b.md]]"+ );+ }++ #[test]+ fn rewrite_local_wikilinks_resolves_explicit_own_project_scope() {+ let path = PagePath::new("concepts/a.md").unwrap();+ assert_eq!(+ rewrite_local_wikilinks("[[proj:decisions/b.md]]", &path, "proj"),+ "[proj:decisions/b.md](../decisions/b.md)"+ );+ }++ #[test]+ fn rewrite_local_wikilinks_skips_fenced_and_inline_code() {+ let path = PagePath::new("concepts/a.md").unwrap();+ let body = "```\n[[decisions/ignored.md]]\n```\n\+ Use `[[decisions/also-ignored.md]]` inline.\n\+ [[decisions/kept.md]]\n";+ let rewritten = rewrite_local_wikilinks(body, &path, "proj");+ assert!(rewritten.contains("[[decisions/ignored.md]]"));+ assert!(rewritten.contains("`[[decisions/also-ignored.md]]`"));+ assert!(rewritten.contains("[decisions/kept.md](../decisions/kept.md)"));+ }++ #[test]+ fn rewrite_local_wikilinks_leaves_malformed_or_empty_targets_untouched() {+ let path = PagePath::new("concepts/a.md").unwrap();+ for body in ["[[]]", "[[ ]]", "[[unterminated", "no links here at all"] {+ assert_eq!(rewrite_local_wikilinks(body, &path, "proj"), body);+ }+ }++ #[test]+ fn rewrite_local_wikilinks_does_not_panic_on_arbitrary_bodies() {+ let path = PagePath::new("concepts/a.md").unwrap();+ for body in [+ "[[",+ "]]",+ "[[|]]",+ "[[a|b|c]]",+ "``` [[unterminated fence",+ "`[[dangling backtick",+ "[[../../escape.md]]",+ ] {+ let _ = rewrite_local_wikilinks(body, &path, "proj");+ }+ }}