Skip to content

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.md
index 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.0
missing, so a generic OKF consumer sees both §4.1-recommended keys. The
backfill 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-25
diff --git a/crates/ai-memory-mcp/src/admin.rs b/crates/ai-memory-mcp/src/admin.rs
index 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 are
diff --git a/crates/ai-memory-wiki/src/lib.rs b/crates/ai-memory-wiki/src/lib.rs
index 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.rs
index 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");
+ }
+ }
}