Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors
Rust
feat(web): serve the HTTP surface under a configurable base path
Djalma Júnior31ea1f0d6d3e
diff --git a/crates/ai-memory-cli/src/cli.rs b/crates/ai-memory-cli/src/cli.rsindex dfdc1cdd..1d2e4dd5 100644--- a/crates/ai-memory-cli/src/cli.rs+++ b/crates/ai-memory-cli/src/cli.rs@@ -902,6 +902,23 @@ pub struct ServeArgs {/// --enable-web is set.#[arg(long)]pub web_ui_dir: Option<PathBuf>,+ /// Base path the whole HTTP surface is served under. Empty (default)+ /// keeps every route at the host root — byte-identical to previous+ /// behaviour. Set e.g. `/wiki` to host ai-memory under a URL subpath+ /// behind a reverse proxy that preserves the prefix; then `/mcp`,+ /// `/api/v1`, `/hook` and the web UI all live under it (`/wiki/mcp`,+ /// `/wiki/api/v1`, …). The value is normalised to `/<core>` (leading+ /// slash, no trailing); `/` and `` both mean root.+ #[arg(long, env = "AI_MEMORY_BASE_PATH", default_value = "")]+ pub base_path: String,+ /// Slug the web UI is mounted at, WITHIN `--base-path`. Default `/web`+ /// (the read-only `/api/v1` API always stays at `<base>/api/v1`). Set+ /// `/` to serve the UI at the base root itself (e.g. `/wiki` instead of+ /// `/wiki/web`). The server injects a normalised `<base href>` into the+ /// served HTML so the built-in UI and a custom `--web-ui-dir` SPA both+ /// resolve their assets under the prefix without a rebuild.+ #[arg(long, env = "AI_MEMORY_WEB_SLUG", default_value = "/web")]+ pub web_slug: String,/// Run the HTTP transport in stateful (session) mode: the server/// issues an `Mcp-Session-Id` on `initialize` and requires it on/// every later request, with SSE-framed responses. Off by default —diff --git a/crates/ai-memory-cli/src/commands/serve.rs b/crates/ai-memory-cli/src/commands/serve.rsindex a9e2e7d7..ec64d7db 100644--- a/crates/ai-memory-cli/src/commands/serve.rs+++ b/crates/ai-memory-cli/src/commands/serve.rs@@ -25,7 +25,7 @@ use rmcp::transport::streamable_http_server::{};use tokio_util::sync::CancellationToken;use tower_http::cors::CorsLayer;-use tower_http::services::{ServeDir, ServeFile};+use tower_http::services::ServeDir;use tracing::info;use crate::auth::{AuthState, require_bearer};@@ -279,6 +279,14 @@ pub async fn run(config: &Config, args: ServeArgs) -> Result<()> {.merge(hooks).layer(DefaultBodyLimit::max(MAX_BODY_BYTES)).merge(admin.layer(DefaultBodyLimit::max(BOOTSTRAP_MAX_BODY_BYTES)));+ let base_path = normalize_prefix(&args.base_path);+ if base_path.is_empty() && !args.base_path.trim_matches('/').trim().is_empty() {+ tracing::warn!(+ raw = %args.base_path,+ "AI_MEMORY_BASE_PATH is not a safe path prefix; serving at root instead",+ );+ }+ let base_href = web_base_href(&args.base_path, &args.web_slug);let router = mount_web_router(router,args.enable_web,@@ -286,8 +294,18 @@ pub async fn run(config: &Config, args: ServeArgs) -> Result<()> {wiki.clone(),args.web_ui_dir.as_deref(),&cors_origins,+ &args.web_slug,+ &base_href,);let router = apply_http_layers(router, auth_state, config.allowed_hosts.clone());+ // Host the entire surface under the configured base path. Empty+ // base = root (unchanged). The auth/host layers are already+ // attached to `router`, so they run for every nested route.+ let router = if base_path.is_empty() {+ router+ } else {+ axum::Router::new().nest(&base_path, router)+ };let listener = tokio::net::TcpListener::bind(&bind).await.with_context(|| format!("binding {bind}"))?;@@ -712,6 +730,123 @@ fn llm_retry_hint(provider: &str, model: &str, base_url: Option<&str>) -> Stringcommand}+/// Normalise an operator-supplied path prefix into either `""` (root) or+/// `/<core>` — exactly one leading slash, no trailing slash, internal+/// empty/`//` segments collapsed. Segments are restricted to a safe path+/// charset; anything outside it falls back to root so a malformed env var+/// can never inject markup or a protocol-relative `//` into served HTML.+pub(crate) fn normalize_prefix(raw: &str) -> String {+ let segs: Vec<&str> = raw.trim().split('/').filter(|s| !s.is_empty()).collect();+ if segs.is_empty() {+ return String::new();+ }+ let safe = segs.iter().all(|s| {+ s.chars()+ .all(|c| c.is_ascii_alphanumeric() || matches!(c, '-' | '_' | '.' | '~'))+ });+ if !safe {+ return String::new();+ }+ format!("/{}", segs.join("/"))+}++/// Build the `<base href>` value (always trailing-slash-terminated, never+/// the protocol-relative `//`) for the web UI mounted at `base_path` ++/// `web_slug`.+pub(crate) fn web_base_href(base_path: &str, web_slug: &str) -> String {+ let combined = format!(+ "{}{}",+ normalize_prefix(base_path),+ normalize_prefix(web_slug)+ );+ if combined.is_empty() {+ "/".to_string()+ } else {+ format!("{combined}/")+ }+}++/// Escape a string for safe inclusion inside a double-quoted HTML attribute.+fn escape_attr(s: &str) -> String {+ s.replace('&', "&")+ .replace('"', """)+ .replace('<', "<")+ .replace('>', ">")+}++/// Inject `<base href="{href}">` immediately after the first `<head…>` tag+/// (or prepend it when there is no head) so the served SPA's relative+/// asset/router URLs resolve under the configured prefix.+pub(crate) fn inject_base_href(html: &str, href: &str) -> String {+ let tag = format!("<base href=\"{}\">", escape_attr(href));+ if let Some(start) = html.find("<head")+ && let Some(gt) = html[start..].find('>')+ {+ let pos = start + gt + 1;+ let mut out = String::with_capacity(html.len() + tag.len());+ out.push_str(&html[..pos]);+ out.push_str(&tag);+ out.push_str(&html[pos..]);+ return out;+ }+ format!("{tag}{html}")+}++#[cfg(test)]+mod web_base_tests {+ use super::{inject_base_href, normalize_prefix, web_base_href};++ #[test]+ fn normalize_prefix_edge_cases() {+ assert_eq!(normalize_prefix(""), "");+ assert_eq!(normalize_prefix("/"), "");+ assert_eq!(normalize_prefix("//"), "");+ assert_eq!(normalize_prefix(" / "), "");+ assert_eq!(normalize_prefix("wiki"), "/wiki");+ assert_eq!(normalize_prefix("/wiki"), "/wiki");+ assert_eq!(normalize_prefix("/wiki/"), "/wiki");+ assert_eq!(normalize_prefix("//wiki//"), "/wiki");+ assert_eq!(normalize_prefix("/wiki/sub"), "/wiki/sub");+ // Unsafe chars fall back to root — never inject markup or `//`.+ assert_eq!(normalize_prefix("/wi\"ki"), "");+ assert_eq!(normalize_prefix("/wiki space"), "");+ assert_eq!(normalize_prefix("/<script>"), "");+ }++ #[test]+ fn web_base_href_never_protocol_relative() {+ assert_eq!(web_base_href("", "/web"), "/web/");+ assert_eq!(web_base_href("/wiki", "/web"), "/wiki/web/");+ assert_eq!(web_base_href("/wiki", "/"), "/wiki/");+ assert_eq!(web_base_href("", "/"), "/");+ assert_eq!(web_base_href("/", "/"), "/");+ assert_eq!(web_base_href("/wiki/", "web"), "/wiki/web/");+ for (b, s) in [("", "/"), ("/", "/"), ("//", "//")] {+ assert!(!web_base_href(b, s).starts_with("//"));+ }+ }++ #[test]+ fn inject_base_href_after_head() {+ let html = "<!doctype html><html><head><meta charset=\"utf-8\"></head><body></body></html>";+ let out = inject_base_href(html, "/wiki/web/");+ assert!(out.contains("<head><base href=\"/wiki/web/\"><meta"));+ }++ #[test]+ fn inject_base_href_no_head_prepends() {+ let out = inject_base_href("<html></html>", "/x/");+ assert!(out.starts_with("<base href=\"/x/\"><html>"));+ }++ #[test]+ fn inject_base_href_escapes_attr() {+ let out = inject_base_href("<head></head>", "/a\"b/");+ assert!(out.contains("<base href=\"/a"b/\">"));+ }+}++#[allow(clippy::too_many_arguments)]fn mount_web_router(router: axum::Router,enable_web: bool,@@ -719,6 +854,8 @@ fn mount_web_router(wiki: Wiki,web_ui_dir: Option<&Path>,cors_origins: &[String],+ web_slug: &str,+ base_href: &str,) -> axum::Router {if !enable_web {return router;@@ -751,25 +888,55 @@ fn mount_web_router(};let router = router.nest("/api/v1", api);+ // Where the UI is mounted WITHIN the (already-applied) base path.+ // Empty slug => the UI is the root of the base path itself.+ let slug = normalize_prefix(web_slug);+ let mount = if slug.is_empty() { "/" } else { slug.as_str() };+// Custom SPA via --web-ui-dir (SPA fallback to index.html), otherwise- // the built-in server-side wiki browser.+ // the built-in server-side wiki browser. In both cases the served+ // index carries an injected `<base href>` so relative asset/router+ // URLs resolve under `{base_path}{web_slug}`.if let Some(dir) = web_ui_dir {let dir = dir.to_path_buf();- let index = dir.join("index.html");- info!(dir = %dir.display(), "custom web UI mounted at /web");- // ServeDir already answers /web and /web/ (SPA fallback to index.html);- // an explicit /web/ route here would conflict with the nest_service.- return router.nest_service("/web", ServeDir::new(dir).fallback(ServeFile::new(index)));+ let injected = inject_base_href(+ &std::fs::read_to_string(dir.join("index.html")).unwrap_or_default(),+ base_href,+ );+ info!(mount, base_href, "custom web UI mounted");+ // Assets are served as files; any unmatched path (SPA client route)+ // falls back to the injected index. `append_index_html_on_directories`+ // is off so the directory index also flows through the injecting+ // fallback rather than serving the raw on-disk index.html.+ let spa = ServeDir::new(dir)+ .append_index_html_on_directories(false)+ .fallback(axum::routing::get(move || {+ let body = injected.clone();+ async move { axum::response::Html(body) }+ }));+ return if slug.is_empty() {+ router.fallback_service(spa)+ } else {+ router.nest_service(&slug, spa)+ };}let web_router = ai_memory_web::router(reader, wiki);- info!("read-only wiki browser mounted at /web");- router- .route(- "/web/",- axum::routing::get(|| async { axum::response::Redirect::permanent("/web") }),- )- .nest("/web", web_router)+ info!(mount, "read-only wiki browser mounted");+ if slug.is_empty() {+ router.merge(web_router)+ } else {+ let redirect_to = slug.clone();+ router+ .route(+ &format!("{slug}/"),+ axum::routing::get(move || {+ let to = redirect_to.clone();+ async move { axum::response::Redirect::permanent(&to) }+ }),+ )+ .nest(&slug, web_router)+ }}fn apply_http_layers(@@ -913,6 +1080,8 @@ mod tests {wiki,None,&[],+ "/web",+ "/web/",);let router = apply_http_layers(router,@@ -1074,6 +1243,8 @@ mod tests {wiki,None,&cors_origins,+ "/web",+ "/web/",);// No auth layer so we can reach /api/v1 directly.let resp = router@@ -1123,6 +1294,8 @@ mod tests {wiki,None,&cors_origins,+ "/web",+ "/web/",);let resp = router.oneshot(@@ -1161,6 +1334,8 @@ mod tests {wiki,None,&cors_origins,+ "/web",+ "/web/",);// /web is a non-api route; sending an Origin header must not trigger CORS.let resp = router