Skip to content

Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors

Rust

feat(web): render [[wikilinks]] as clickable internal links

Djalma Júniord1a59ef7f9da
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 78ee6301..a7943b55 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
## [Unreleased]
### Added
+- The read-only web browser now renders `[[wiki links]]` as clickable internal
+ links to the target page. Supports `[[path]]`, `[[path|label]]`,
+ `[[project:path]]`, and `[[workspace/project:path]]`, resolved against the
+ current page's project unless the target carries its own scope; bare targets
+ get a `.md` suffix. External schemes, path traversal, and links inside fenced
+ or inline code are left as literal text ([#68]).
- `ai-memory move-project` can move projects across workspaces via the admin
API. Fresh destinations use a lossless true move that keeps the same
`project_id`, sessions, observations, handoffs, embeddings, and page history;
diff --git a/crates/ai-memory-web/src/markdown.rs b/crates/ai-memory-web/src/markdown.rs
index c3554ed2..358a82cb 100644
--- a/crates/ai-memory-web/src/markdown.rs
+++ b/crates/ai-memory-web/src/markdown.rs
@@ -9,20 +9,183 @@ use pulldown_cmark::{CowStr, Event, Options, Parser, Tag, html};
/// Raw HTML is escaped and unsafe link/image schemes are neutralised.
/// Wiki content can be derived from prompts, hooks, or LLM output, so
/// the browser surface must treat it as untrusted.
+///
+/// `[[wiki links]]` (with the `[[target|label]]`, `[[project:path]]`, and
+/// `[[workspace/project:path]]` variants the engine's link extractor
+/// understands) are rendered as clickable internal links resolved against
+/// the page's own `workspace`/`project` unless the target carries its own
+/// scope. Wikilinks inside fenced code blocks and inline code are left as
+/// literal text.
#[must_use]
-pub fn render(body: &str) -> String {
+pub fn render(body: &str, workspace: &str, project: &str) -> String {
let mut opts = Options::empty();
opts.insert(Options::ENABLE_TABLES);
opts.insert(Options::ENABLE_FOOTNOTES);
opts.insert(Options::ENABLE_STRIKETHROUGH);
opts.insert(Options::ENABLE_TASKLISTS);
opts.insert(Options::ENABLE_SMART_PUNCTUATION);
- let parser = Parser::new_ext(body, opts).map(sanitize_event);
+
+ // Rewrite `[[wikilinks]]` into ordinary markdown links BEFORE parsing.
+ // pulldown-cmark consumes `[...]` as reference-link syntax, so the brackets
+ // never survive as a single text node — preprocessing the source is the
+ // robust hook. Code (fenced + inline) is skipped so `[[…]]` stays literal
+ // there, mirroring the engine's link extractor.
+ let body = preprocess_wikilinks(body, workspace, project);
+
+ let parser = Parser::new_ext(&body, opts).map(sanitize_event);
let mut out = String::with_capacity(body.len() + body.len() / 4);
html::push_html(&mut out, parser);
out
}
+/// Convert `[[target]]` / `[[target|label]]` spans into `[label](href)`
+/// markdown links, skipping fenced code blocks and inline-code spans. Targets
+/// that aren't internal pages (external schemes, traversal, empty) are left as
+/// literal `[[…]]`.
+fn preprocess_wikilinks(body: &str, workspace: &str, project: &str) -> String {
+ let mut out = String::with_capacity(body.len() + 64);
+ let mut in_fence = false;
+ for line in body.split_inclusive('\n') {
+ let trimmed = line.trim_start();
+ if trimmed.starts_with("```") || trimmed.starts_with("~~~") {
+ in_fence = !in_fence;
+ out.push_str(line);
+ continue;
+ }
+ if in_fence {
+ out.push_str(line);
+ continue;
+ }
+ // Split on backticks: even segments are outside inline code, odd ones
+ // are inside it (left verbatim). Unbalanced backticks degrade safely.
+ for (i, seg) in line.split('`').enumerate() {
+ if i > 0 {
+ out.push('`');
+ }
+ if i % 2 == 0 {
+ rewrite_wikilinks_in_text(seg, workspace, project, &mut out);
+ } else {
+ out.push_str(seg);
+ }
+ }
+ }
+ out
+}
+
+/// Rewrite every `[[…]]` in a non-code text run into a markdown link.
+fn rewrite_wikilinks_in_text(seg: &str, workspace: &str, project: &str, out: &mut String) {
+ let mut rest = seg;
+ loop {
+ let Some(open) = rest.find("[[") else {
+ out.push_str(rest);
+ break;
+ };
+ let after = &rest[open + 2..];
+ let Some(close) = after.find("]]") else {
+ out.push_str(rest); // unterminated → literal
+ break;
+ };
+ out.push_str(&rest[..open]);
+ let raw = &after[..close];
+ match wikilink_href_label(raw, workspace, project) {
+ Some((href, label)) => {
+ out.push('[');
+ out.push_str(&escape_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[close + 2..];
+ }
+}
+
+/// Escape the characters that would prematurely close a markdown link label.
+fn escape_link_label(label: &str) -> String {
+ label
+ .replace('\\', r"\\")
+ .replace('[', r"\[")
+ .replace(']', r"\]")
+}
+
+/// Resolve a `[[…]]` target (inner text, no brackets) into a relative page
+/// href + display label. Returns `None` for empty/external/malformed targets
+/// (callers then keep the literal `[[…]]`).
+fn wikilink_href_label(raw: &str, workspace: &str, project: &str) -> Option<(String, String)> {
+ let (target, label) = match raw.split_once('|') {
+ Some((t, l)) => (t.trim(), Some(l.trim())),
+ None => (raw.trim(), None),
+ };
+ if target.is_empty() {
+ return None;
+ }
+ // External / scheme-qualified targets are not internal wiki pages.
+ let lower = target.to_ascii_lowercase();
+ if target.contains("://")
+ || lower.starts_with("mailto:")
+ || lower.starts_with("data:")
+ || lower.starts_with("javascript:")
+ || lower.starts_with("tel:")
+ || target.starts_with('#')
+ {
+ return None;
+ }
+
+ // Optional `[workspace/]project:` scope qualifier.
+ let (ws, proj, path_part) = split_scope(target, workspace, project);
+
+ // Strip anchor/query, reject traversal, normalise the `.md` suffix.
+ let path = path_part.split(['#', '?']).next().unwrap_or("").trim();
+ if path.is_empty() || path.contains('\\') || path.contains("..") {
+ return None;
+ }
+ let path = if path.rsplit('/').next().is_some_and(|seg| seg.contains('.')) {
+ path.to_string()
+ } else {
+ format!("{path}.md")
+ };
+
+ let href = crate::templates::page_href(ws, proj, &path);
+ let display = label
+ .filter(|l| !l.is_empty())
+ .unwrap_or(target)
+ .to_string();
+ Some((href, display))
+}
+
+/// Peel an optional `[workspace/]project:` scope off a wikilink target,
+/// defaulting to the current page's `workspace`/`project`. A `scope` made of
+/// anything other than `[-_/.alnum]` is treated as part of the path (so a
+/// stray colon in a filename doesn't masquerade as a scope).
+fn split_scope<'a>(
+ target: &'a str,
+ cur_ws: &'a str,
+ cur_proj: &'a str,
+) -> (&'a str, &'a str, &'a str) {
+ if let Some((scope, rest)) = target.split_once(':') {
+ let scope = scope.trim();
+ let scope_ok = !scope.is_empty()
+ && scope
+ .chars()
+ .all(|c| c.is_alphanumeric() || matches!(c, '-' | '_' | '/' | '.'));
+ if scope_ok {
+ return match scope.split_once('/') {
+ Some((ws, proj)) if !proj.trim().is_empty() => {
+ (ws.trim(), proj.trim(), rest.trim())
+ }
+ Some(_) => (cur_ws, cur_proj, target), // malformed `ws/`
+ None => (cur_ws, scope, rest.trim()),
+ };
+ }
+ }
+ (cur_ws, cur_proj, target)
+}
+
fn sanitize_event(event: Event<'_>) -> Event<'_> {
match event {
Event::Html(s) | Event::InlineHtml(s) => Event::Text(s),
@@ -125,7 +288,7 @@ mod tests {
#[test]
fn renders_basic_markdown() {
- let html = render("# Hello\n\nworld");
+ let html = render("# Hello\n\nworld", "default", "scratch");
assert!(html.contains("<h1>Hello</h1>"));
assert!(html.contains("<p>world</p>"));
}
@@ -133,21 +296,21 @@ mod tests {
#[test]
fn renders_tables() {
let md = "| a | b |\n|---|---|\n| 1 | 2 |";
- let html = render(md);
+ let html = render(md, "default", "scratch");
assert!(html.contains("<table>"));
assert!(html.contains("<td>1</td>"));
}
#[test]
fn escapes_raw_html() {
- let html = render("<script>alert(1)</script>");
+ let html = render("<script>alert(1)</script>", "default", "scratch");
assert!(html.contains("&lt;script&gt;alert(1)&lt;/script&gt;"));
assert!(!html.contains("<script>"));
}
#[test]
fn neutralises_javascript_links() {
- let html = render("[x](javascript:alert(1))");
+ let html = render("[x](javascript:alert(1))", "default", "scratch");
assert!(html.contains("href=\"#\""));
assert!(!html.contains("javascript:"));
}
@@ -195,4 +358,68 @@ mod tests {
let out = strip_leading_h1("Title\n----\n\nbody\n");
assert_eq!(out, "Title\n----\n\nbody\n");
}
+
+ #[test]
+ fn wikilink_resolves_against_current_project() {
+ let html = render("see [[notes/foo]] here", "default", "scratch");
+ assert!(
+ html.contains(r#"<a href="/web/w/default/scratch/p/notes/foo.md">notes/foo</a>"#),
+ "got: {html}"
+ );
+ }
+
+ #[test]
+ fn wikilink_label_and_md_suffix() {
+ // explicit label wins; `.md` appended when the last segment is bare.
+ let html = render("[[notes/foo|the foo]] and [[bar.md]]", "default", "scratch");
+ assert!(html.contains(r#">the foo</a>"#), "label: {html}");
+ assert!(
+ html.contains(r#"href="/web/w/default/scratch/p/notes/foo.md""#),
+ "suffix add: {html}"
+ );
+ assert!(
+ html.contains(r#"href="/web/w/default/scratch/p/bar.md""#),
+ "suffix keep: {html}"
+ );
+ }
+
+ #[test]
+ fn wikilink_cross_project_and_cross_workspace_scope() {
+ let html = render(
+ "[[otherproj:notes/x]] [[ws2/proj2:y]]",
+ "default",
+ "scratch",
+ );
+ assert!(
+ html.contains(r#"href="/web/w/default/otherproj/p/notes/x.md""#),
+ "project scope: {html}"
+ );
+ assert!(
+ html.contains(r#"href="/web/w/ws2/proj2/p/y.md""#),
+ "workspace/project scope: {html}"
+ );
+ }
+
+ #[test]
+ fn wikilink_not_linkified_in_code() {
+ let fenced = render("```\n[[notes/foo]]\n```", "default", "scratch");
+ assert!(!fenced.contains("<a href"), "fenced: {fenced}");
+ assert!(fenced.contains("[[notes/foo]]"), "fenced literal: {fenced}");
+
+ let inline = render("use `[[notes/foo]]` literally", "default", "scratch");
+ assert!(!inline.contains("<a href"), "inline code: {inline}");
+ }
+
+ #[test]
+ fn malformed_or_external_wikilink_kept_literal() {
+ // unterminated
+ let a = render("text [[notes/foo without close", "default", "scratch");
+ assert!(a.contains("[[notes/foo without close"), "unterminated: {a}");
+ // external scheme inside [[ ]] is not an internal page → literal
+ let b = render("[[https://example.com]]", "default", "scratch");
+ assert!(!b.contains("<a href"), "external: {b}");
+ // path traversal rejected
+ let c = render("[[../etc/passwd]]", "default", "scratch");
+ assert!(!c.contains("<a href"), "traversal: {c}");
+ }
}
diff --git a/crates/ai-memory-web/src/routes/page.rs b/crates/ai-memory-web/src/routes/page.rs
index 112f575d..5f6eede8 100644
--- a/crates/ai-memory-web/src/routes/page.rs
+++ b/crates/ai-memory-web/src/routes/page.rs
@@ -38,7 +38,11 @@ pub(crate) async fn handler(
// Drop the leading H1 — the template already renders the title
// in its header, so leaving it in the body duplicates it.
- let body_html = markdown::render(markdown::strip_leading_h1(&markdown_doc.body));
+ let body_html = markdown::render(
+ markdown::strip_leading_h1(&markdown_doc.body),
+ &workspace,
+ &project,
+ );
let project_href = project_href(&workspace, &project);
let supersedes_path = meta.supersedes.unwrap_or_default();
diff --git a/docs/usage.md b/docs/usage.md
index 2c9f6b7f..a16c7794 100644
--- a/docs/usage.md
+++ b/docs/usage.md
@@ -136,7 +136,11 @@ command: ["serve", "--transport", "http", "--bind", "0.0.0.0:49374", "--enable-w
```
The web UI is read-only: project list, per-project page tree,
-breadcrumbs, rendered markdown, metadata, and FTS5 search. If the
+breadcrumbs, rendered markdown, metadata, and FTS5 search. In rendered
+pages, `[[wiki links]]` become clickable links to the target page —
+`[[path]]`, `[[path|label]]`, `[[project:path]]`, and
+`[[workspace/project:path]]` are all supported (resolved against the
+current page's project unless the target carries its own scope). If the
server has `AI_MEMORY_AUTH_TOKEN` set, the browser uses HTTP Basic auth:
leave the username blank and paste the token as the password. MCP and
hook clients continue to use `Authorization: Bearer <token>`.