AI search engine and MCP server for bots and agents. One Rust binary indexes code, docs, logs, JSONL/CSV and PDFs for BM25 full-text, vector and hybrid search, code search without grep, agent memory and RAG. Elasticsearch-compatible API; Corpus Hub serves hundreds of reference memory corpora.
Rust agent-memoryai-agentsbm25claude-codeclicode-searchcursordatabaseelasticsearchfull-text-searchhybrid-searchjsonllocal-firstmcpmcp-servermodel-context-protocolragrustsearch-enginevector-search
feat(memory): add GET /_memory endpoint to list agent-memory namespaces (#2022)
Ravi Arnan Irianto0598f4268b37
diff --git a/engine/crates/xerj-api/src/authz.rs b/engine/crates/xerj-api/src/authz.rsindex 0bb364292..ef5d686f5 100644--- a/engine/crates/xerj-api/src/authz.rs+++ b/engine/crates/xerj-api/src/authz.rs@@ -384,6 +384,8 @@ enum Target {Brain(String),/// `/_memory/{namespace}[/…]`Memory(String),+ /// `/_memory` (namespace listing)+ MemoryRoot,/// One or more index expressions, plus where the op segment starts.Indices(Vec<String>, usize),/// A cluster/global endpoint whose path names no index: `/_cat/*`,@@ -520,7 +522,7 @@ fn classify(path: &str) -> Target {},"_memory" => match segs.get(1) {Some(ns) => Target::Memory(ns.clone()),- None => Target::Exempt,+ None => Target::MemoryRoot,},// Native router (`build_native_router`, :8080). Same engine, same// indices, different spelling — and therefore the same boundary:@@ -1448,7 +1450,7 @@ fn guest_route_allowed(let is_read_verb = is_get || method == Method::POST;match target {Target::Exempt => true,- Target::Cluster | Target::Memory(_) => false,+ Target::Cluster | Target::Memory(_) | Target::MemoryRoot => false,Target::Brain(_) => {is_get&& segs.len() == 3@@ -1565,6 +1567,7 @@ fn decide(Target::Memory(ns) => {authorize_memory_namespace(principal, ns, reserved_api_privilege(method, segs))}+ Target::MemoryRoot => Ok(()),Target::Indices(expressions, op_start) => {let privilege = required_privilege(method, segs, *op_start);for expr in expressions {@@ -2374,6 +2377,7 @@ mod tests {classify("/_memory/alice/_recall"),Target::Memory("alice".into()));+ assert_eq!(classify("/_memory"), Target::MemoryRoot);assert_eq!(classify("/_search"), Target::Cluster);assert_eq!(classify("/_bulk"), Target::Cluster);assert_eq!(classify("/_mapping"), Target::Cluster);diff --git a/engine/crates/xerj-api/src/memory_api.rs b/engine/crates/xerj-api/src/memory_api.rsindex 6751714b2..22f67c4e0 100644--- a/engine/crates/xerj-api/src/memory_api.rs+++ b/engine/crates/xerj-api/src/memory_api.rs@@ -8,6 +8,7 @@//!//! Endpoints (mounted on the ES-compat router)://! ```text+//! GET /_memory?from&size list_ns — {count, namespaces:[{namespace, count, graph}], from, size, next}//! POST /_memory/{namespace} store — {text, metadata?, vector?, id?, dedup?, dedup_threshold?} → {id, created} | {id, created:false, deduplicated:true}//! POST /_memory/{namespace}/_recall recall — {query?, vector?, semantic?, hybrid?, fusion?, k?, filter?, recency_weight?} → {hits:[…]}//! GET /_memory/{namespace}?from&size list — {count, entries:[…], next} (paged, recent first)@@ -1346,6 +1347,97 @@ pub async fn list(.into_response()}+/// `GET /_memory` — list agent-memory namespaces.+///+/// Enumerates all memory namespaces (indices named `.xerj-memory-{namespace}`),+/// returning their active document count and whether a corresponding graph+/// edges index (`.xerj-memory-{namespace}-edges`) exists.+///+/// Filtered to only the namespaces the calling principal holds+/// `Privilege::ReadIndex` on.+pub async fn list_namespaces(+ State(state): State<AppState>,+ principal: Principal,+ axum::extract::Query(params): axum::extract::Query<ListParams>,+) -> Response {+ let from = params.from.or(params.after).unwrap_or(0);+ let size = params.size.unwrap_or(LIST_LIMIT).clamp(1, MAX_LIST_SIZE);++ let all_indices = state.engine.list_indices().await;++ // Collect all edges indices so we can flag `graph: true` in O(1).+ let mut edges = std::collections::HashSet::new();+ for idx in &all_indices {+ if let Some(rest) = idx.name.strip_prefix(MEMORY_PREFIX) {+ if let Some(brain) = rest.strip_suffix("-edges") {+ edges.insert(brain.to_string());+ }+ }+ }++ let mut namespaces = Vec::new();+ for idx in &all_indices {+ if let Some(ns) = idx.name.strip_prefix(MEMORY_PREFIX) {+ // Edges indices are graph metadata, not memory namespaces.+ if ns.ends_with("-edges") {+ continue;+ }+ if validate_namespace(ns).is_err() {+ continue;+ }+ if authz::authorize_memory_namespace(&principal, ns, Privilege::ReadIndex).is_err() {+ continue;+ }+ let has_graph = edges.contains(ns);+ namespaces.push(json!({+ "namespace": ns,+ "count": idx.doc_count,+ "graph": has_graph,+ }));+ }+ }++ // Sort deterministically by namespace name.+ namespaces.sort_by(|a, b| {+ let a_ns = a.get("namespace").and_then(Value::as_str).unwrap_or("");+ let b_ns = b.get("namespace").and_then(Value::as_str).unwrap_or("");+ a_ns.cmp(b_ns)+ });++ let total = namespaces.len();+ let paged: Vec<Value> = namespaces.into_iter().skip(from).take(size).collect();+ let next = if from + paged.len() < total {+ json!({ "from": from + paged.len(), "size": size })+ } else {+ Value::Null+ };++ Json(json!({+ "count": total,+ "namespaces": paged,+ "from": from,+ "size": size,+ "next": next,+ }))+ .into_response()+}++/// JSON `405` for unsupported mutating verbs on bare `/_memory`.+pub async fn unsupported_memory_bare() -> Response {+ let reason = "/_memory only supports GET to list namespaces. \+ Specify a namespace in the path (e.g. POST /_memory/{namespace}) \+ to store, recall, list, or drop memories.";+ (+ StatusCode::METHOD_NOT_ALLOWED,+ [(header::ALLOW, HeaderValue::from_static("GET"))],+ Json(json!({+ "error": { "type": "memory_error", "reason": reason },+ "status": 405,+ })),+ )+ .into_response()+}+// ─────────────────────────────────────────────────────────────────────────────// Forget// ─────────────────────────────────────────────────────────────────────────────@@ -2437,4 +2529,117 @@ mod tests {assert_eq!(body["forgotten"], false);assert_eq!(body["id"], "_doc");}++ #[tokio::test]+ async fn list_namespaces_empty_and_populated() {+ let state = test_state();++ // 1. Initially empty: no memory namespaces exist.+ let resp = list_namespaces(+ State(state.clone()),+ Principal::Superuser,+ axum::extract::Query(ListParams::default()),+ )+ .await;+ let (s, body) = drain_json(resp).await;+ assert_eq!(s, StatusCode::OK);+ assert_eq!(body["count"], 0);+ assert_eq!(body["namespaces"].as_array().unwrap().len(), 0);+ assert!(body["next"].is_null());++ // 2. Populate two namespaces: `agent-a` (2 docs) and `support-bot` (1 doc).+ store_mem(&state, "agent-a", json!({"text":"first memory"})).await;+ store_mem(&state, "agent-a", json!({"text":"second memory"})).await;+ store_mem(&state, "support-bot", json!({"text":"bot memory"})).await;++ // Add a graph edge for `support-bot` using graph_api::link.+ let link_body: crate::graph_api::LinkBody = serde_json::from_value(json!({+ "src": "m1",+ "dst": "m2",+ "type": "relates_to",+ }))+ .unwrap();+ let link_resp = crate::graph_api::link(+ State(state.clone()),+ Path("support-bot".to_string()),+ Principal::Superuser,+ OptionalJson(Some(link_body)),+ )+ .await;+ assert_eq!(link_resp.into_response().status(), StatusCode::CREATED);++ // 3. List namespaces: should return both sorted alphabetically.+ let resp = list_namespaces(+ State(state.clone()),+ Principal::Superuser,+ axum::extract::Query(ListParams::default()),+ )+ .await;+ let (s, body) = drain_json(resp).await;+ assert_eq!(s, StatusCode::OK);+ assert_eq!(body["count"], 2);+ let list = body["namespaces"].as_array().unwrap();+ assert_eq!(list.len(), 2);++ // `agent-a`: count=2, graph=false+ assert_eq!(list[0]["namespace"], "agent-a");+ assert_eq!(list[0]["count"], 2);+ assert_eq!(list[0]["graph"], false);++ // `support-bot`: count=1, graph=true+ assert_eq!(list[1]["namespace"], "support-bot");+ assert_eq!(list[1]["count"], 1);+ assert_eq!(list[1]["graph"], true);++ // 4. Pagination: from=0, size=1 -> returns agent-a, next={from:1, size:1}+ let resp = list_namespaces(+ State(state.clone()),+ Principal::Superuser,+ axum::extract::Query(ListParams {+ from: Some(0),+ size: Some(1),+ ..Default::default()+ }),+ )+ .await;+ let (_, p1) = drain_json(resp).await;+ assert_eq!(p1["count"], 2);+ assert_eq!(p1["namespaces"].as_array().unwrap().len(), 1);+ assert_eq!(p1["namespaces"][0]["namespace"], "agent-a");+ assert_eq!(p1["next"], json!({ "from": 1, "size": 1 }));++ // Page 2: from=1, size=1 -> returns support-bot, next=null+ let resp = list_namespaces(+ State(state.clone()),+ Principal::Superuser,+ axum::extract::Query(ListParams {+ from: Some(1),+ size: Some(1),+ ..Default::default()+ }),+ )+ .await;+ let (_, p2) = drain_json(resp).await;+ assert_eq!(p2["count"], 2);+ assert_eq!(p2["namespaces"].as_array().unwrap().len(), 1);+ assert_eq!(p2["namespaces"][0]["namespace"], "support-bot");+ assert!(p2["next"].is_null());+ }++ #[tokio::test]+ async fn bare_memory_unsupported_verbs() {+ let resp = unsupported_memory_bare().await;+ assert_eq!(resp.status(), StatusCode::METHOD_NOT_ALLOWED);+ assert_eq!(+ resp.headers().get("allow").and_then(|v| v.to_str().ok()),+ Some("GET")+ );+ let (_, body) = drain_json(resp).await;+ assert_eq!(body["status"], 405);+ assert_eq!(body["error"]["type"], "memory_error");+ assert!(body["error"]["reason"]+ .as_str()+ .unwrap()+ .contains("/_memory only supports GET"));+ }}diff --git a/engine/crates/xerj-api/src/router.rs b/engine/crates/xerj-api/src/router.rsindex a2372042a..d499f2465 100644--- a/engine/crates/xerj-api/src/router.rs+++ b/engine/crates/xerj-api/src/router.rs@@ -926,6 +926,13 @@ pub fn build_es_compat_router_with_hub(// Namespaced semantic memory for AI agents, backed by reserved// `.xerj-memory-{namespace}` indices (reuses the doc/dense_vector/BM25// machinery). See `memory_api.rs`.+ .route(+ "/_memory",+ get(memory_api::list_namespaces)+ .post(memory_api::unsupported_memory_bare)+ .delete(memory_api::unsupported_memory_bare)+ .put(memory_api::unsupported_memory_bare),+ ).route("/_memory/:namespace",post(memory_api::store)