Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors
Rust
feat(admin): add a root-only, content-free GET /admin/metrics
AkitaOnRails0832025e2aab
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 6337dde6..436b688d 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -42,6 +42,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0`explain=true` reports an `observation` stream with the matched observationids. Hits are still pages and nothing is written; sessions without a pagekeep the `raw_hits` fallback, and `global=true` search is unchanged.+- Added a root-only `GET /admin/metrics` endpoint in Prometheus text format.+ It exposes the hook admission and delivery counters, MCP tool calls split+ into reads and writes, and fixed-bucket latency histograms for `POST /hook`+ and `memory_query`. Every label comes from a fixed set: no query text, page+ body, prompt, client or project name, scope or token appears in the output.+ On a multi-user server only root can read it, like every `/admin/*` route.- Added a `timings` object to `memory_query` responses with `explain=true`:each retrieval stream's wall time in milliseconds (`fts_ms`, `entity_ms`,`vector_ms`, `graph_ms`, `observation_ms`, `rerank_ms`), summed over `scopes`.diff --git a/crates/ai-memory-cli/src/commands/serve.rs b/crates/ai-memory-cli/src/commands/serve.rsindex fc174335..a1b59bcd 100644--- a/crates/ai-memory-cli/src/commands/serve.rs+++ b/crates/ai-memory-cli/src/commands/serve.rs@@ -1566,6 +1566,9 @@ pub async fn run(config: &Config, args: ServeArgs) -> Result<()> {let admin = admin_router_with_sweep_tuning(AdminState {ingest_metrics: ingest_metrics.clone(),+ // The tool server's own instance, so /admin/metrics reads+ // what memory_query records.+ mcp_metrics: server.mcp_metrics(),writer: store.writer.clone(),reader: store.reader.clone(),wiki: wiki.clone(),diff --git a/crates/ai-memory-core/src/ingest_metrics.rs b/crates/ai-memory-core/src/ingest_metrics.rsindex 07f97301..35095783 100644--- a/crates/ai-memory-core/src/ingest_metrics.rs+++ b/crates/ai-memory-core/src/ingest_metrics.rs@@ -10,6 +10,8 @@ use std::sync::atomic::{AtomicU64, Ordering};use serde::Serialize;+use crate::LatencyHistogram;+/// Process-lifetime counters for the hook ingestion pipeline.////// Deliberately a fixed set of scalars, never a map. #428 asked for@@ -64,6 +66,9 @@ pub struct IngestMetrics {/// Unix milliseconds of the last newly persisted observation or effect, or 0/// when none has since this process started.last_persisted_ms: AtomicU64,+ /// Time `POST /hook` took to answer (admission, not the spawned+ /// processing). Counts only; never in [`IngestMetricsSnapshot`].+ hook_latency: LatencyHistogram,}impl IngestMetrics {@@ -120,6 +125,12 @@ impl IngestMetrics {self.last_persisted_ms.store(unix_ms, Ordering::Relaxed);}+ /// The `POST /hook` response-time histogram.+ #[must_use]+ pub fn hook_latency(&self) -> &LatencyHistogram {+ &self.hook_latency+ }+/// Read every counter for status reporting.#[must_use]pub fn snapshot(&self) -> IngestMetricsSnapshot {diff --git a/crates/ai-memory-core/src/latency.rs b/crates/ai-memory-core/src/latency.rsnew file mode 100644index 00000000..734d4cda--- /dev/null+++ b/crates/ai-memory-core/src/latency.rs@@ -0,0 +1,192 @@+//! Fixed-bucket latency histogram for the `/admin/metrics` endpoint.+//!+//! One observation is a bounded scan over a fixed bucket table plus three+//! relaxed atomic adds: no lock, no allocation, nothing keyed on request data.+//! The histogram holds counts only, so it cannot carry a query, a prompt or a+//! scope name, and its memory never grows.++use std::fmt::Write as _;+use std::sync::atomic::{AtomicU64, Ordering};+use std::time::{Duration, Instant};++/// Upper bounds of the finite buckets, in microseconds (Prometheus `le`,+/// inclusive). The last bucket, `+Inf`, is implicit. The range covers a+/// sub-millisecond hook admission up to a slow reranked query.+pub const LATENCY_BUCKET_BOUNDS_US: [u64; 13] = [+ 1_000, 2_500, 5_000, 10_000, 25_000, 50_000, 100_000, 250_000, 500_000, 1_000_000, 2_500_000,+ 5_000_000, 10_000_000,+];++const BUCKETS: usize = LATENCY_BUCKET_BOUNDS_US.len() + 1;++/// Process-lifetime latency histogram with fixed buckets.+///+/// Relaxed ordering, as in [`crate::IngestMetrics`]: a scrape that sees a+/// bucket a few observations stale is fine; a fence on the hot path is not.+#[derive(Debug, Default)]+pub struct LatencyHistogram {+ /// Per-bucket counts, not cumulative. Rendering accumulates them.+ buckets: [AtomicU64; BUCKETS],+ /// Total observed time, in microseconds.+ sum_us: AtomicU64,+}++impl LatencyHistogram {+ /// Record one observation.+ pub fn observe(&self, elapsed: Duration) {+ let us = u64::try_from(elapsed.as_micros()).unwrap_or(u64::MAX);+ let idx = LATENCY_BUCKET_BOUNDS_US+ .iter()+ .position(|bound| us <= *bound)+ .unwrap_or(BUCKETS - 1);+ self.buckets[idx].fetch_add(1, Ordering::Relaxed);+ self.sum_us.fetch_add(us, Ordering::Relaxed);+ }++ /// Start a timer that records into this histogram when dropped, so every+ /// return path of the measured call is counted, errors included.+ #[must_use]+ pub fn start(&self) -> LatencyTimer<'_> {+ LatencyTimer {+ histogram: self,+ started: Instant::now(),+ }+ }++ /// Read the histogram: per-bucket counts (non-cumulative, `+Inf` last)+ /// and the total observed microseconds.+ #[must_use]+ pub fn snapshot(&self) -> LatencySnapshot {+ let mut buckets = [0_u64; BUCKETS];+ for (slot, bucket) in buckets.iter_mut().zip(&self.buckets) {+ *slot = bucket.load(Ordering::Relaxed);+ }+ LatencySnapshot {+ buckets,+ sum_us: self.sum_us.load(Ordering::Relaxed),+ }+ }+}++/// Records the time since [`LatencyHistogram::start`] when dropped.+#[derive(Debug)]+pub struct LatencyTimer<'a> {+ histogram: &'a LatencyHistogram,+ started: Instant,+}++impl Drop for LatencyTimer<'_> {+ fn drop(&mut self) {+ self.histogram.observe(self.started.elapsed());+ }+}++/// A read of a [`LatencyHistogram`].+#[derive(Debug, Clone, Copy, PartialEq, Eq)]+pub struct LatencySnapshot {+ /// Per-bucket counts in [`LATENCY_BUCKET_BOUNDS_US`] order, `+Inf` last.+ pub buckets: [u64; BUCKETS],+ /// Total observed microseconds.+ pub sum_us: u64,+}++impl LatencySnapshot {+ /// Number of observations.+ #[must_use]+ pub fn count(&self) -> u64 {+ self.buckets.iter().copied().fold(0, u64::saturating_add)+ }++ /// Append this histogram in the Prometheus text exposition format, in+ /// seconds. `name` and `help` are compile-time constants chosen by the+ /// caller, never request data. `_count` is derived from the buckets so+ /// the cumulative series always ends at `_count`, even if a scrape races+ /// an observation.+ pub fn write_prometheus(&self, out: &mut String, name: &str, help: &str) {+ let _ = writeln!(out, "# HELP {name} {help}");+ let _ = writeln!(out, "# TYPE {name} histogram");+ let mut cumulative = 0_u64;+ for (bound, count) in LATENCY_BUCKET_BOUNDS_US.iter().zip(&self.buckets) {+ cumulative = cumulative.saturating_add(*count);+ let le = seconds(*bound);+ let _ = writeln!(out, "{name}_bucket{{le=\"{le}\"}} {cumulative}");+ }+ let total = self.count();+ let _ = writeln!(out, "{name}_bucket{{le=\"+Inf\"}} {total}");+ let _ = writeln!(out, "{name}_sum {}", seconds(self.sum_us));+ let _ = writeln!(out, "{name}_count {total}");+ }+}++/// Microseconds as a Prometheus float of seconds.+#[allow(clippy::cast_precision_loss)]+fn seconds(us: u64) -> f64 {+ us as f64 / 1_000_000.0+}++#[cfg(test)]+mod tests {+ use super::*;++ #[test]+ fn observations_land_in_the_inclusive_bucket() {+ let h = LatencyHistogram::default();+ h.observe(Duration::from_micros(1_000));+ h.observe(Duration::from_micros(1_001));+ h.observe(Duration::from_secs(60));+ let s = h.snapshot();+ assert_eq!(s.buckets[0], 1, "le=0.001 is inclusive");+ assert_eq!(s.buckets[1], 1);+ assert_eq!(s.buckets[BUCKETS - 1], 1, "past the last bound is +Inf");+ assert_eq!(s.count(), 3);+ assert_eq!(s.sum_us, 1_000 + 1_001 + 60_000_000);+ }++ #[test]+ fn a_timer_records_once_when_dropped() {+ let h = LatencyHistogram::default();+ {+ let _timer = h.start();+ }+ assert_eq!(h.snapshot().count(), 1);+ }++ #[test]+ fn prometheus_buckets_are_cumulative_and_end_at_the_count() {+ let h = LatencyHistogram::default();+ h.observe(Duration::from_micros(500));+ h.observe(Duration::from_millis(30));+ h.observe(Duration::from_secs(30));+ let mut out = String::new();+ h.snapshot()+ .write_prometheus(&mut out, "x_seconds", "Test histogram.");+ assert!(out.starts_with("# HELP x_seconds Test histogram.\n# TYPE x_seconds histogram\n"));+ assert!(out.contains("x_seconds_bucket{le=\"0.001\"} 1\n"), "{out}");+ assert!(out.contains("x_seconds_bucket{le=\"0.025\"} 1\n"), "{out}");+ assert!(out.contains("x_seconds_bucket{le=\"0.05\"} 2\n"), "{out}");+ assert!(out.contains("x_seconds_bucket{le=\"10\"} 2\n"), "{out}");+ assert!(out.contains("x_seconds_bucket{le=\"+Inf\"} 3\n"), "{out}");+ assert!(out.contains("x_seconds_count 3\n"), "{out}");+ assert!(out.contains("x_seconds_sum 30.0305\n"), "{out}");+ }++ #[test]+ fn concurrent_observations_are_not_lost() {+ use std::sync::Arc;+ let h = Arc::new(LatencyHistogram::default());+ let handles: Vec<_> = (0..8)+ .map(|_| {+ let h = Arc::clone(&h);+ std::thread::spawn(move || {+ for _ in 0..1000 {+ h.observe(Duration::from_micros(7));+ }+ })+ })+ .collect();+ for handle in handles {+ handle.join().expect("thread");+ }+ assert_eq!(h.snapshot().count(), 8000);+ }+}diff --git a/crates/ai-memory-core/src/lib.rs b/crates/ai-memory-core/src/lib.rsindex f0efb63b..a5a60c9d 100644--- a/crates/ai-memory-core/src/lib.rs+++ b/crates/ai-memory-core/src/lib.rs@@ -13,6 +13,8 @@ pub mod handoff;pub mod ingest_metrics;pub use ingest_metrics::{IngestMetrics, IngestMetricsSnapshot};pub mod ids;+pub mod latency;+pub use latency::{LatencyHistogram, LatencySnapshot, LatencyTimer};pub mod log_ledger;pub mod message;pub mod observation;diff --git a/crates/ai-memory-hooks/src/router.rs b/crates/ai-memory-hooks/src/router.rsindex e923a57b..b5887829 100644--- a/crates/ai-memory-hooks/src/router.rs+++ b/crates/ai-memory-hooks/src/router.rs@@ -638,6 +638,8 @@ fn now_unix_ms() -> u64 {.map_or(0, |d| u64::try_from(d.as_millis()).unwrap_or(u64::MAX))}+/// `POST /hook`: [`admit_hook`] timed into the `/admin/metrics` histogram.+/// The timer covers the response, not the spawned processing.async fn handle_hook(State(state): State<Arc<HookState>>,Query(query): Query<HookQuery>,@@ -645,8 +647,25 @@ async fn handle_hook(level_ext: Option<axum::Extension<ai_memory_core::AuthLevel>>,viewer_ext: Option<axum::Extension<ai_memory_core::AuthorizedViewer>>,headers: HeaderMap,- Json(mut body): Json<serde_json::Value>,+ Json(body): Json<serde_json::Value>,) -> impl IntoResponse {+ let metrics = state.ingest_metrics.clone();+ let _timer = metrics.hook_latency().start();+ admit_hook(+ state, query, actor_ext, level_ext, viewer_ext, headers, body,+ )+ .await+}++async fn admit_hook(+ state: Arc<HookState>,+ query: HookQuery,+ actor_ext: Option<axum::Extension<ai_memory_core::ActorContext>>,+ level_ext: Option<axum::Extension<ai_memory_core::AuthLevel>>,+ viewer_ext: Option<axum::Extension<ai_memory_core::AuthorizedViewer>>,+ headers: HeaderMap,+ mut body: serde_json::Value,+) -> (StatusCode, &'static str) {// Unconditional backstop (#196): drop any raw assistant-message field on the// `Value` before it becomes a `HookEnvelope`, so the field can never reach// `body_excerpt`, tracing, or the store — regardless of client version.@@ -8343,6 +8362,45 @@ mod tests {assert_eq!(response.status(), StatusCode::TOO_MANY_REQUESTS);}+ /// Every `/hook` answer, queued or shed, lands in the latency histogram+ /// that `/admin/metrics` exposes, and nothing else does.+ #[tokio::test]+ async fn handle_hook_times_every_answer_into_the_latency_histogram() {+ let tmp = TempDir::new().unwrap();+ let state = Arc::new(make_state(&tmp).await);+ let call = |state: Arc<HookState>| async move {+ handle_hook(+ State(state),+ Query(HookQuery {+ event: "session-start".into(),+ agent: Some("claude-code".into()),+ ..Default::default()+ }),+ None,+ None,+ None,+ HeaderMap::new(),+ Json(serde_json::json!({ "session_id": "latency-s1" })),+ )+ .await+ .into_response()+ .status()+ };+ assert_eq!(state.ingest_metrics.hook_latency().snapshot().count(), 0);+ assert_eq!(call(state.clone()).await, StatusCode::ACCEPTED);+ assert_eq!(state.ingest_metrics.hook_latency().snapshot().count(), 1);++ let tmp2 = TempDir::new().unwrap();+ let mut saturated = make_state(&tmp2).await;+ saturated.ingest_semaphore = Arc::new(tokio::sync::Semaphore::new(0));+ saturated.ingest_metrics = state.ingest_metrics.clone();+ assert_eq!(+ call(Arc::new(saturated)).await,+ StatusCode::TOO_MANY_REQUESTS+ );+ assert_eq!(state.ingest_metrics.hook_latency().snapshot().count(), 2);+ }+#[tokio::test]async fn handle_hook_does_not_debit_source_token_when_globally_saturated() {let tmp = TempDir::new().unwrap();diff --git a/crates/ai-memory-mcp/src/admin.rs b/crates/ai-memory-mcp/src/admin.rsindex cc8d9ca8..5d850bb0 100644--- a/crates/ai-memory-mcp/src/admin.rs+++ b/crates/ai-memory-mcp/src/admin.rs@@ -8,6 +8,7 @@//! - `POST /admin/auto-improve/report` — read-only auto-improve telemetry report.//! - `POST /admin/curator` — dry-run or stage a rule-based curator report.//! - `GET /admin/status` — lifetime counts + server data-dir info.+//! - `GET /admin/metrics` — content-free Prometheus counters and latency histograms.//! - `GET /admin/projects` — authoritative `(workspace, project)` list.//! - `GET /admin/project-coordinate` — read-only exact/compatibility diagnosis.//! - `GET /admin/open-sessions` — open (not yet ended) sessions for one scope + agent@@ -130,6 +131,9 @@ pub struct AdminState {/// Shared hook-ingestion counters, written by the hook path and read/// here for status reporting.pub ingest_metrics: std::sync::Arc<ai_memory_core::IngestMetrics>,+ /// The MCP server's own counters ([`crate::AiMemoryServer::mcp_metrics`]),+ /// read by `GET /admin/metrics`. A fresh instance reports zeros.+ pub mcp_metrics: std::sync::Arc<crate::McpMetrics>,/// Retention-decay parameters forwarded from server config.pub decay_params: DecayParams,/// Lower edge of `memory_lint`'s A5 zero-LLM contradiction-similarity@@ -584,6 +588,7 @@ fn hex_to_sha256(hex: &str) -> Result<[u8; 32], String> {/// - `POST /admin/auto-improve/report`/// - `POST /admin/curator`/// - `GET /admin/status`+/// - `GET /admin/metrics`/// - `GET /admin/projects`/// - `GET /admin/project-coordinate`/// - `GET /admin/open-sessions`@@ -666,6 +671,7 @@ pub fn admin_router_with_sweep_tuning(post(handle_pending_write_reject),).route("/admin/status", get(handle_status))+ .route("/admin/metrics", get(handle_metrics)).route("/admin/projects", get(handle_list_projects)).route("/admin/project-coordinate", get(handle_project_coordinate)).route("/admin/open-sessions", get(handle_open_sessions))@@ -1227,6 +1233,21 @@ async fn handle_audit_log(}}+/// Handler for `GET /admin/metrics`: process counters and latency+/// histograms in the Prometheus text format. Root-only on a multi-user server+/// through the same gate as every `/admin/*` route. Content-free by+/// construction: see [`crate::metrics`].+async fn handle_metrics(State(state): State<Arc<AdminState>>) -> Response {+ (+ [(+ header::CONTENT_TYPE,+ crate::metrics::PROMETHEUS_CONTENT_TYPE,+ )],+ crate::metrics::render_prometheus(&state.ingest_metrics, &state.mcp_metrics),+ )+ .into_response()+}+/// JSON response body for `GET /admin/status`. The CLI's `status`/// subcommand renders this either as JSON (`--json`) or as a small/// human-friendly text block.@@ -9330,6 +9351,7 @@ mod tests {.with_store_reader(store.reader.clone());let router = admin_router(AdminState {ingest_metrics: std::sync::Arc::new(ai_memory_core::IngestMetrics::default()),+ mcp_metrics: std::sync::Arc::new(crate::McpMetrics::default()),writer: store.writer.clone(),reader: store.reader.clone(),wiki,@@ -9399,6 +9421,7 @@ mod tests {let router = admin_router(AdminState {ingest_metrics: std::sync::Arc::new(ai_memory_core::IngestMetrics::default()),+ mcp_metrics: std::sync::Arc::new(crate::McpMetrics::default()),writer: store.writer.clone(),reader: store.reader.clone(),wiki,@@ -9526,6 +9549,7 @@ mod tests {let router = admin_router(AdminState {ingest_metrics: std::sync::Arc::new(ai_memory_core::IngestMetrics::default()),+ mcp_metrics: std::sync::Arc::new(crate::McpMetrics::default()),writer: store.writer.clone(),reader: store.reader.clone(),wiki,@@ -9764,6 +9788,7 @@ mod tests {let router = admin_router(AdminState {ingest_metrics: std::sync::Arc::new(ai_memory_core::IngestMetrics::default()),+ mcp_metrics: std::sync::Arc::new(crate::McpMetrics::default()),writer: store.writer.clone(),reader: store.reader.clone(),wiki,@@ -9961,6 +9986,7 @@ mod tests {let router = admin_router(AdminState {ingest_metrics: std::sync::Arc::new(ai_memory_core::IngestMetrics::default()),+ mcp_metrics: std::sync::Arc::new(crate::McpMetrics::default()),writer: store.writer.clone(),reader: store.reader.clone(),wiki,@@ -10184,6 +10210,7 @@ mod tests {.with_store_reader(store.reader.clone());let router = admin_router(AdminState {ingest_metrics: std::sync::Arc::new(ai_memory_core::IngestMetrics::default()),+ mcp_metrics: std::sync::Arc::new(crate::McpMetrics::default()),writer: store.writer.clone(),reader: store.reader.clone(),wiki,@@ -10751,6 +10778,7 @@ mod tests {) -> AdminState {AdminState {ingest_metrics: std::sync::Arc::new(ai_memory_core::IngestMetrics::default()),+ mcp_metrics: std::sync::Arc::new(crate::McpMetrics::default()),writer: store.writer.clone(),reader: store.reader.clone(),wiki,@@ -12557,6 +12585,7 @@ mod tests {.with_store_reader(store.reader.clone());let router = admin_router(AdminState {ingest_metrics: std::sync::Arc::new(ai_memory_core::IngestMetrics::default()),+ mcp_metrics: std::sync::Arc::new(crate::McpMetrics::default()),writer: store.writer.clone(),reader: store.reader.clone(),wiki,@@ -12669,6 +12698,7 @@ mod tests {.with_store_reader(store.reader.clone());let router = admin_router(AdminState {ingest_metrics: std::sync::Arc::new(ai_memory_core::IngestMetrics::default()),+ mcp_metrics: std::sync::Arc::new(crate::McpMetrics::default()),writer: store.writer.clone(),reader: store.reader.clone(),wiki,@@ -12774,6 +12804,7 @@ mod tests {.with_store_reader(store.reader.clone());let router = admin_router(AdminState {ingest_metrics: std::sync::Arc::new(ai_memory_core::IngestMetrics::default()),+ mcp_metrics: std::sync::Arc::new(crate::McpMetrics::default()),writer: store.writer.clone(),reader: store.reader.clone(),wiki,@@ -12885,6 +12916,7 @@ mod tests {.with_store_reader(store.reader.clone());let router = admin_router(AdminState {ingest_metrics: std::sync::Arc::new(ai_memory_core::IngestMetrics::default()),+ mcp_metrics: std::sync::Arc::new(crate::McpMetrics::default()),writer: store.writer.clone(),reader: store.reader.clone(),wiki,@@ -13435,6 +13467,7 @@ mod tests {let pepper = ai_memory_store::TokenPepper::new("test-pepper-admin");let router = admin_router(AdminState {ingest_metrics: std::sync::Arc::new(ai_memory_core::IngestMetrics::default()),+ mcp_metrics: std::sync::Arc::new(crate::McpMetrics::default()),writer: store.writer.clone(),reader: store.reader.clone(),wiki,@@ -13494,6 +13527,7 @@ mod tests {let pepper = ai_memory_store::TokenPepper::new("test-pepper-admin");let router = admin_router(AdminState {ingest_metrics: std::sync::Arc::new(ai_memory_core::IngestMetrics::default()),+ mcp_metrics: std::sync::Arc::new(crate::McpMetrics::default()),writer: store.writer.clone(),reader: store.reader.clone(),wiki,@@ -13658,6 +13692,7 @@ mod tests {serde_json::json!({"workspace": "default", "project": "scratch"}),),("GET", "/admin/status", serde_json::Value::Null),+ ("GET", "/admin/metrics", serde_json::Value::Null),("GET","/admin/project-coordinate?workspace=default&project=scratch",@@ -14162,6 +14197,23 @@ mod tests {.unwrap();assert_eq!(resp.status(), StatusCode::OK);+ let resp = router+ .clone()+ .oneshot(+ Request::builder()+ .uri("/admin/metrics")+ .header("authorization", "Bearer root-token")+ .body(Body::empty())+ .unwrap(),+ )+ .await+ .unwrap();+ assert_eq!(resp.status(), StatusCode::OK);+ assert_eq!(+ resp.headers()[axum::http::header::CONTENT_TYPE],+ crate::metrics::PROMETHEUS_CONTENT_TYPE+ );+let resp = router.clone().oneshot(@@ -14199,6 +14251,7 @@ mod tests {let wiki = Wiki::new(tmp.path(), store.writer.clone()).unwrap();let router = admin_router(AdminState {ingest_metrics: std::sync::Arc::new(ai_memory_core::IngestMetrics::default()),+ mcp_metrics: std::sync::Arc::new(crate::McpMetrics::default()),writer: store.writer.clone(),reader: store.reader.clone(),wiki,@@ -14333,6 +14386,7 @@ mod tests {ai_memory_store::ReaderPool::new(&tmp.path().join("missing.sqlite"), 1).unwrap();let router = admin_router(AdminState {ingest_metrics: std::sync::Arc::new(ai_memory_core::IngestMetrics::default()),+ mcp_metrics: std::sync::Arc::new(crate::McpMetrics::default()),writer: store.writer.clone(),reader: missing_db_reader,wiki,@@ -15182,6 +15236,7 @@ mod tests {let wiki = Wiki::new(tmp.path(), store.writer.clone()).unwrap();let router = admin_router(AdminState {ingest_metrics: std::sync::Arc::new(ai_memory_core::IngestMetrics::default()),+ mcp_metrics: std::sync::Arc::new(crate::McpMetrics::default()),writer: store.writer.clone(),reader: store.reader.clone(),wiki,diff --git a/crates/ai-memory-mcp/src/lib.rs b/crates/ai-memory-mcp/src/lib.rsindex b4f6c115..7a4c3295 100644--- a/crates/ai-memory-mcp/src/lib.rs+++ b/crates/ai-memory-mcp/src/lib.rs@@ -14,6 +14,7 @@ pub mod admin_profile;pub mod auth;pub mod human_auth;pub mod identity;+pub mod metrics;mod server;pub use actor::actor_from_headers;@@ -25,6 +26,7 @@ pub use human_auth::{HumanAuthRuntime, expire_legacy_cookie_mw, internal_auth_router, public_auth_router,require_dual_auth, session_auth_router,};+pub use metrics::McpMetrics;pub use server::{AiMemoryServer, MEMORY_INSTRUCTIONS};// Integration tests compile into this crate's test harness instead of adiff --git a/crates/ai-memory-mcp/src/metrics.rs b/crates/ai-memory-mcp/src/metrics.rsnew file mode 100644index 00000000..7f7ce57b--- /dev/null+++ b/crates/ai-memory-mcp/src/metrics.rs@@ -0,0 +1,211 @@+//! Process-lifetime MCP counters and the `GET /admin/metrics` renderer.+//!+//! Everything exposed here is a count or a duration with a label drawn from a+//! closed, compile-time set. Nothing is keyed on request data: no query text,+//! page body, prompt, client name, scope or project name, and no token can+//! reach a metric name, a label or a value. Scope is never a label, so the+//! series set is fixed and a scrape cannot enumerate projects.++use std::fmt::Write as _;+use std::sync::atomic::{AtomicU64, Ordering};++use ai_memory_core::{IngestMetrics, LatencyHistogram};++/// Prometheus text exposition content type served by `/admin/metrics`.+pub const PROMETHEUS_CONTENT_TYPE: &str = "text/plain; version=0.0.4; charset=utf-8";++/// MCP-side counters shared by the tool server (writer) and the admin router+/// (reader). One instance per process: [`crate::AiMemoryServer::mcp_metrics`]+/// hands out the server's own so the admin route reads what the tools record.+#[derive(Debug, Default)]+pub struct McpMetrics {+ /// Wall time of every `memory_query` call, errors included.+ query_latency: LatencyHistogram,+ /// Read-shaped tool calls (the same split as `client_activity`).+ tool_reads: AtomicU64,+ /// Write-shaped tool calls.+ tool_writes: AtomicU64,+}++impl McpMetrics {+ /// The `memory_query` latency histogram.+ #[must_use]+ pub fn query_latency(&self) -> &LatencyHistogram {+ &self.query_latency+ }++ /// Count one tool call. The client it came from is deliberately not+ /// recorded: a client name is caller-supplied text.+ pub fn record_tool_call(&self, is_write: bool) {+ let counter = if is_write {+ &self.tool_writes+ } else {+ &self.tool_reads+ };+ counter.fetch_add(1, Ordering::Relaxed);+ }++ /// `(reads, writes)` tool calls since this process started.+ #[must_use]+ pub fn tool_calls(&self) -> (u64, u64) {+ (+ self.tool_reads.load(Ordering::Relaxed),+ self.tool_writes.load(Ordering::Relaxed),+ )+ }+}++/// Render every metric in the Prometheus text format.+#[must_use]+pub fn render_prometheus(ingest: &IngestMetrics, mcp: &McpMetrics) -> String {+ let mut out = String::with_capacity(4096);+ let snap = ingest.snapshot();++ counter_family(+ &mut out,+ "ai_memory_hook_admissions_total",+ "Hook events by admission result since the server started.",+ "result",+ &[+ ("accepted", snap.accepted),+ ("dropped_by_policy", snap.dropped_by_policy),+ ("dropped_unauthorized", snap.dropped_unauthorized),+ ("dropped_invalid", snap.dropped_invalid),+ ("shed_saturated", snap.shed_saturated),+ ("shed_rate_limited", snap.shed_rate_limited),+ ],+ );+ counter_family(+ &mut out,+ "ai_memory_hook_deliveries_total",+ "Completed hook deliveries by outcome since the server started.",+ "outcome",+ &[+ ("stored", snap.stored),+ ("replayed", snap.replayed),+ ("resumed", snap.resumed),+ ("ignored_end", snap.ignored_end),+ ("dropped_collision", snap.dropped_collision),+ ("failed", snap.failed),+ ],+ );+ if let Some(ms) = snap.last_persisted_ms {+ let _ = writeln!(+ out,+ "# HELP ai_memory_hook_last_persisted_timestamp_seconds Unix time of the last newly persisted observation or effect."+ );+ let _ = writeln!(+ out,+ "# TYPE ai_memory_hook_last_persisted_timestamp_seconds gauge"+ );+ let _ = writeln!(+ out,+ "ai_memory_hook_last_persisted_timestamp_seconds {}",+ ms / 1000+ );+ }+ let (reads, writes) = mcp.tool_calls();+ counter_family(+ &mut out,+ "ai_memory_mcp_tool_calls_total",+ "MCP tool calls by kind since the server started.",+ "kind",+ &[("read", reads), ("write", writes)],+ );+ ingest.hook_latency().snapshot().write_prometheus(+ &mut out,+ "ai_memory_hook_request_duration_seconds",+ "Time POST /hook took to answer.",+ );+ mcp.query_latency().snapshot().write_prometheus(+ &mut out,+ "ai_memory_query_duration_seconds",+ "Wall time of memory_query calls.",+ );+ out+}++fn counter_family(+ out: &mut String,+ name: &str,+ help: &str,+ label: &str,+ values: &[(&'static str, u64)],+) {+ let _ = writeln!(out, "# HELP {name} {help}");+ let _ = writeln!(out, "# TYPE {name} counter");+ for (value, count) in values {+ let _ = writeln!(out, "{name}{{{label}=\"{value}\"}} {count}");+ }+}++#[cfg(test)]+mod tests {+ use super::*;+ use std::time::Duration;++ #[test]+ fn tool_calls_split_reads_from_writes() {+ let m = McpMetrics::default();+ m.record_tool_call(false);+ m.record_tool_call(false);+ m.record_tool_call(true);+ assert_eq!(m.tool_calls(), (2, 1));+ }++ #[test]+ fn rendering_is_well_formed_and_covers_every_family() {+ let ingest = IngestMetrics::default();+ ingest.record_accepted();+ ingest.record_stored();+ ingest.record_persisted(1_700_000_000_123);+ ingest.hook_latency().observe(Duration::from_millis(3));+ let mcp = McpMetrics::default();+ mcp.record_tool_call(false);+ mcp.query_latency().observe(Duration::from_millis(40));++ let text = render_prometheus(&ingest, &mcp);+ for line in [+ "ai_memory_hook_admissions_total{result=\"accepted\"} 1",+ "ai_memory_hook_admissions_total{result=\"shed_saturated\"} 0",+ "ai_memory_hook_deliveries_total{outcome=\"stored\"} 1",+ "ai_memory_hook_last_persisted_timestamp_seconds 1700000000",+ "ai_memory_mcp_tool_calls_total{kind=\"read\"} 1",+ "ai_memory_mcp_tool_calls_total{kind=\"write\"} 0",+ "ai_memory_hook_request_duration_seconds_bucket{le=\"0.005\"} 1",+ "ai_memory_hook_request_duration_seconds_count 1",+ "ai_memory_query_duration_seconds_bucket{le=\"0.025\"} 0",+ "ai_memory_query_duration_seconds_bucket{le=\"0.05\"} 1",+ "ai_memory_query_duration_seconds_count 1",+ ] {+ assert!(text.lines().any(|l| l == line), "missing {line}:\n{text}");+ }+ // Every sample line is `name{labels} value` or `name value` with a+ // numeric value; every family is announced by HELP and TYPE first.+ let mut announced = std::collections::HashSet::new();+ for line in text.lines() {+ if let Some(rest) = line.strip_prefix("# TYPE ") {+ announced.insert(rest.split(' ').next().unwrap().to_string());+ continue;+ }+ if line.starts_with("# HELP ") {+ continue;+ }+ let (series, value) = line.rsplit_once(' ').expect("sample line");+ assert!(value.parse::<f64>().is_ok(), "{line}");+ let name = series.split('{').next().unwrap();+ let family = ["_bucket", "_sum", "_count"]+ .iter()+ .find_map(|s| name.strip_suffix(s))+ .filter(|base| announced.contains(*base))+ .unwrap_or(name);+ assert!(announced.contains(family), "unannounced series {line}");+ }+ }++ #[test]+ fn no_write_yet_means_no_last_persisted_gauge() {+ let text = render_prometheus(&IngestMetrics::default(), &McpMetrics::default());+ assert!(!text.contains("last_persisted"), "{text}");+ }+}diff --git a/crates/ai-memory-mcp/src/server.rs b/crates/ai-memory-mcp/src/server.rsindex c223ca97..d8e5c235 100644--- a/crates/ai-memory-mcp/src/server.rs+++ b/crates/ai-memory-mcp/src/server.rs@@ -518,6 +518,9 @@ pub struct AiMemoryServer {/// burst costs the writer one tiny upsert batch, not one write per/// call (same reasoning as the M8 access-bump throttle).client_activity: Arc<std::sync::Mutex<ClientActivityBuffer>>,+ /// Content-free process counters read by `GET /admin/metrics`: the+ /// `memory_query` latency histogram and read/write tool-call totals.+ mcp_metrics: Arc<crate::McpMetrics>,/// Shared "last client activity" clock (microseconds), bumped on every tool/// call. The B3 dream scheduler reads it to detect idle and to cancel a/// running pass the moment the operator returns — consolidation must never@@ -1805,6 +1808,7 @@ impl AiMemoryServer {embedder: None,reranker: None,client_activity: Arc::new(std::sync::Mutex::new(ClientActivityBuffer::new())),+ mcp_metrics: Arc::new(crate::McpMetrics::default()),activity_clock: ai_memory_consolidate::ActivityClock::new(jiff::Timestamp::now().as_microsecond(),),@@ -2589,6 +2593,13 @@ impl AiMemoryServer {out}+ /// The process counters this server records into. `serve` hands the same+ /// instance to the admin router so `GET /admin/metrics` reads them.+ #[must_use]+ pub fn mcp_metrics(&self) -> Arc<crate::McpMetrics> {+ Arc::clone(&self.mcp_metrics)+ }+/// Attach a reranker. Without one, `memory_query` keeps its/// RRF-only, zero-LLM behaviour.#[must_use]@@ -2732,6 +2743,8 @@ impl AiMemoryServer {Parameters(args): Parameters<QueryArgs>,OptionalParts(parts): OptionalParts,) -> Result<CallToolResult, McpError> {+ // Dropped on every return path, so errors are timed too.+ let _latency = self.mcp_metrics.query_latency().start();let aps_actor = Self::actor_key_from_parts(Some(&parts));let limit = args.limit.unwrap_or(self.default_limit).clamp(1, 100);let include_expired = args.include_expired.unwrap_or(false);@@ -6973,6 +6986,7 @@ impl AiMemoryServer {self.activity_clock.mark(now_us);let day = now_us.div_euclid(US_PER_DAY);let is_write = tool_call_is_write(tool);+ self.mcp_metrics.record_tool_call(is_write);let schedule_flush = {let mut buffer = self.client_activitydiff --git a/crates/ai-memory-mcp/tests/suite/admin_audit_log.rs b/crates/ai-memory-mcp/tests/suite/admin_audit_log.rsindex 9e89f06d..03353e04 100644--- a/crates/ai-memory-mcp/tests/suite/admin_audit_log.rs+++ b/crates/ai-memory-mcp/tests/suite/admin_audit_log.rs@@ -15,6 +15,7 @@ async fn make_admin_state(tmp: &TempDir) -> (AdminState, Store) {let db_path = store.db_path().to_path_buf();let state = AdminState {ingest_metrics: std::sync::Arc::new(ai_memory_core::IngestMetrics::default()),+ mcp_metrics: std::sync::Arc::new(ai_memory_mcp::McpMetrics::default()),writer: store.writer.clone(),reader: store.reader.clone(),wiki,diff --git a/crates/ai-memory-mcp/tests/suite/admin_backup.rs b/crates/ai-memory-mcp/tests/suite/admin_backup.rsindex abc8941e..df463e38 100644--- a/crates/ai-memory-mcp/tests/suite/admin_backup.rs+++ b/crates/ai-memory-mcp/tests/suite/admin_backup.rs@@ -25,6 +25,7 @@ async fn make_state(tmp: &TempDir) -> (AdminState, Store) {let db_path = store.db_path().to_path_buf();let state = AdminState {ingest_metrics: std::sync::Arc::new(ai_memory_core::IngestMetrics::default()),+ mcp_metrics: std::sync::Arc::new(ai_memory_mcp::McpMetrics::default()),writer: store.writer.clone(),reader: store.reader.clone(),wiki,diff --git a/crates/ai-memory-mcp/tests/suite/admin_bootstrap.rs b/crates/ai-memory-mcp/tests/suite/admin_bootstrap.rsindex fb8e65a5..03143d0f 100644--- a/crates/ai-memory-mcp/tests/suite/admin_bootstrap.rs+++ b/crates/ai-memory-mcp/tests/suite/admin_bootstrap.rs@@ -52,6 +52,7 @@ async fn make_admin_state(tmp: &TempDir) -> AdminState {let db_path = store.db_path().to_path_buf();AdminState {ingest_metrics: std::sync::Arc::new(ai_memory_core::IngestMetrics::default()),+ mcp_metrics: std::sync::Arc::new(ai_memory_mcp::McpMetrics::default()),writer: store.writer.clone(),reader: store.reader.clone(),wiki,diff --git a/crates/ai-memory-mcp/tests/suite/admin_metrics.rs b/crates/ai-memory-mcp/tests/suite/admin_metrics.rsnew file mode 100644index 00000000..8feb834b--- /dev/null+++ b/crates/ai-memory-mcp/tests/suite/admin_metrics.rs@@ -0,0 +1,363 @@+//! `GET /admin/metrics` end to end, behind the production dual-auth+//! middleware, on one router that also serves `/mcp` and `/hook` with shared+//! counters, the way `serve` assembles them.+//!+//! The endpoint is content-free: counts and durations only, labels from a+//! closed set, scope never a label. The adversarial test plants+//! secret-shaped text in a query, a hook body and a project name and proves+//! none of it reaches the scrape, while the counters still move (control).+//! On a multi-user server the route is root-only.++use std::sync::Arc;++use ai_memory_core::{ActiveProject, IngestMetrics, Sanitizer};+use ai_memory_hooks::{HookState, ProjectCacheStore, SubagentSessionSet, hook_router};+use ai_memory_llm::ProviderHealth;+use ai_memory_mcp::auth::AuthState;+use ai_memory_mcp::{AdminState, AiMemoryServer, admin_router, require_dual_auth};+use ai_memory_store::{DecayParams, Store, TokenPepper};+use ai_memory_wiki::Wiki;+use axum::Router;+use axum::body::Body;+use axum::http::{Request, StatusCode};+use rmcp::transport::streamable_http_server::session::local::LocalSessionManager;+use rmcp::transport::streamable_http_server::{StreamableHttpServerConfig, StreamableHttpService};+use serde_json::{Value, json};+use tempfile::TempDir;+use tower::ServiceExt;++const ROOT: &str = "root-token-for-metrics";+const SECRET_QUERY: &str = "sk-ant-api03-QUERYplanted0123456789abcdefXYZ";+const SECRET_HOOK: &str = "ghp_HOOKplanted0123456789abcdefghijklmnop";+const SECRET_PROJECT: &str = "proj-AKIAPROJECTPLANTED7777";++struct Harness {+ _tmp: TempDir,+ router: Router,+ ingest_semaphore: Arc<tokio::sync::Semaphore>,+}++async fn harness() -> Harness {+ let tmp = TempDir::new().expect("tempdir");+ let store = Store::open(tmp.path()).expect("store");+ let wiki = Wiki::new(tmp.path(), store.writer.clone()).expect("wiki");+ let ws = store+ .writer+ .get_or_create_workspace("default")+ .await+ .expect("ws");+ let proj = store+ .writer+ .get_or_create_project(ws, SECRET_PROJECT, None)+ .await+ .expect("proj");+ let pepper = TokenPepper::new("metrics-test-pepper");++ let server = AiMemoryServer::new(store.reader.clone(), store.writer.clone(), ws, proj)+ .with_wiki(wiki.clone());+ let mcp_metrics = server.mcp_metrics();+ let mcp_service = StreamableHttpService::new(+ move || Ok(server.clone()),+ LocalSessionManager::default().into(),+ StreamableHttpServerConfig::default()+ .with_stateful_mode(false)+ .with_json_response(true),+ );++ let ingest_metrics = Arc::new(IngestMetrics::default());+ let active_project = ActiveProject::new();+ let ingest_semaphore = Arc::new(tokio::sync::Semaphore::new(1));+ let hooks = hook_router(HookState {+ ingest_metrics: ingest_metrics.clone(),+ workspace_id: ws,+ project_id: proj,+ writer: store.writer.clone(),+ reader: store.reader.clone(),+ wiki: wiki.clone(),+ consolidator: None,+ sanitizer: Sanitizer::default(),+ project_cache: Arc::new(tokio::sync::Mutex::new(ProjectCacheStore::default())),+ active_project: active_project.clone(),+ ingest_semaphore: ingest_semaphore.clone(),+ ingest_gates: ai_memory_hooks::IngestGates::default(),+ consolidate_on_session_end: false,+ session_consolidation_notify: None,+ profile_notify: None,+ capture_assistant_enabled: false,+ claim_handoff_on_session_start: false,+ create_handoff_on_session_end: false,+ per_user_slots: false,+ mid_session_routing: ai_memory_core::MidSessionRouting::default(),+ profile: ai_memory_core::profile::ProfileSettings::default(),+ subagent_sessions: Arc::new(tokio::sync::Mutex::new(SubagentSessionSet::default())),+ ingest_rate: Arc::new(tokio::sync::Mutex::new(+ ai_memory_hooks::IngestRateLimiter::disabled(),+ )),+ home_dir: None,+ trusted_proxy_identity: false,+ });++ let admin = admin_router(AdminState {+ ingest_metrics,+ mcp_metrics,+ writer: store.writer.clone(),+ reader: store.reader.clone(),+ wiki,+ llm: None,+ auto_improve_require_approval: false,+ auto_improve_review_config: Default::default(),+ embedder: None,+ provider_health: ProviderHealth::default(),+ decay_params: DecayParams::default(),+ contradiction_band_min: ai_memory_consolidate::DEFAULT_CONTRADICTION_SIM_LOW,+ contradiction_band_max: ai_memory_consolidate::DEFAULT_CONTRADICTION_SIM_HIGH,+ data_dir: tmp.path().to_path_buf(),+ db_path: store.db_path().to_path_buf(),+ bind: "127.0.0.1:49374".to_string(),+ home_dir: None,+ bootstrap_lock: Arc::new(tokio::sync::Mutex::new(())),+ token_pepper: Some(pepper.clone()),+ active_project,+ scope_invalidator: None,+ trusted_proxy_identity: false,+ });++ let auth_state = Arc::new(AuthState::new(Some(ROOT.to_string())).with_multiuser(+ pepper,+ store.reader.clone(),+ store.writer.clone(),+ ));+ let router = Router::new()+ .nest_service("/mcp", mcp_service)+ .merge(hooks)+ .merge(admin)+ .layer(axum::middleware::from_fn_with_state(+ auth_state,+ require_dual_auth,+ ));+ Harness {+ _tmp: tmp,+ router,+ ingest_semaphore,+ }+}++async fn send(router: &Router, req: Request<Body>) -> (StatusCode, String) {+ let resp = router.clone().oneshot(req).await.expect("oneshot");+ let status = resp.status();+ let bytes = axum::body::to_bytes(resp.into_body(), 8_000_000)+ .await+ .expect("body");+ (status, String::from_utf8_lossy(&bytes).into_owned())+}++async fn scrape(router: &Router, bearer: Option<&str>) -> (StatusCode, String) {+ let mut req = Request::builder().uri("/admin/metrics");+ if let Some(token) = bearer {+ req = req.header("authorization", format!("Bearer {token}"));+ }+ send(router, req.body(Body::empty()).unwrap()).await+}++/// The value of one exact series line, e.g. `name{label="x"}`.+fn sample(text: &str, series: &str) -> f64 {+ text.lines()+ .find_map(|line| {+ line.strip_prefix(series)+ .and_then(|rest| rest.strip_prefix(' '))+ })+ .unwrap_or_else(|| panic!("series {series} missing:\n{text}"))+ .parse()+ .expect("numeric sample")+}++async fn memory_query(router: &Router) {+ let body = json!({+ "jsonrpc": "2.0",+ "id": 1,+ "method": "tools/call",+ "params": {+ "name": "memory_query",+ "arguments": {+ "query": format!("where did we leave {SECRET_QUERY}"),+ "workspace": "default",+ "project": SECRET_PROJECT,+ "explain": true,+ },+ },+ });+ let req = Request::builder()+ .method("POST")+ .uri("/mcp")+ .header("host", "localhost")+ .header("authorization", format!("Bearer {ROOT}"))+ .header("content-type", "application/json")+ .header("accept", "application/json, text/event-stream")+ .body(Body::from(body.to_string()))+ .unwrap();+ let (status, text) = send(router, req).await;+ assert_eq!(status, StatusCode::OK, "{text}");+ let v: Value = serde_json::from_str(&text).expect("json-rpc");+ assert!(v.get("error").is_none(), "JSON-RPC error: {v}");+ assert_ne!(+ v.pointer("/result/isError"),+ Some(&json!(true)),+ "tool error: {v}"+ );+}++async fn hook(h: &Harness, event: &str, body: Value) {+ let req = Request::builder()+ .method("POST")+ .uri(format!(+ "/hook?event={event}&agent=claude-code&workspace=default&project={SECRET_PROJECT}"+ ))+ .header("authorization", format!("Bearer {ROOT}"))+ .header("content-type", "application/json")+ .body(Body::from(body.to_string()))+ .unwrap();+ let (status, text) = send(&h.router, req).await;+ assert_eq!(status, StatusCode::ACCEPTED, "{text}");+ // One permit: it is back once the spawned processing finished, so the+ // next event never races this one for capacity.+ drop(+ h.ingest_semaphore+ .acquire()+ .await+ .expect("semaphore stays open"),+ );+}++#[tokio::test]+async fn metrics_count_queries_and_hooks_without_leaking_any_content() {+ let h = harness().await;+ let (status, before) = scrape(&h.router, Some(ROOT)).await;+ assert_eq!(status, StatusCode::OK, "{before}");+ assert_eq!(+ sample(&before, "ai_memory_query_duration_seconds_count"),+ 0.0+ );+ assert_eq!(+ sample(&before, "ai_memory_hook_request_duration_seconds_count"),+ 0.0+ );++ memory_query(&h.router).await;+ let session = "11111111-2222-7333-8444-555555555555";+ hook(+ &h,+ "session-start",+ json!({ "session_id": session, "cwd": format!("/work/{SECRET_PROJECT}") }),+ )+ .await;+ hook(+ &h,+ "user-prompt-submit",+ json!({+ "session_id": session,+ "cwd": format!("/work/{SECRET_PROJECT}"),+ "prompt": format!("deploy with token {SECRET_HOOK} and {SECRET_QUERY}"),+ }),+ )+ .await;++ let (status, after) = scrape(&h.router, Some(ROOT)).await;+ assert_eq!(status, StatusCode::OK, "{after}");+ // Control: the counters moved.+ assert_eq!(+ sample(&after, "ai_memory_query_duration_seconds_count"),+ 1.0+ );+ assert_eq!(+ sample(+ &after,+ "ai_memory_query_duration_seconds_bucket{le=\"+Inf\"}"+ ),+ 1.0+ );+ assert_eq!(+ sample(&after, "ai_memory_hook_request_duration_seconds_count"),+ 2.0+ );+ assert_eq!(+ sample(+ &after,+ "ai_memory_hook_admissions_total{result=\"accepted\"}"+ ),+ 2.0+ );+ assert_eq!(+ sample(&after, "ai_memory_mcp_tool_calls_total{kind=\"read\"}"),+ 1.0+ );+ assert_eq!(+ sample(&after, "ai_memory_mcp_tool_calls_total{kind=\"write\"}"),+ 0.0+ );++ // Adversarial: nothing the callers sent reaches the scrape.+ for planted in [+ SECRET_QUERY,+ SECRET_HOOK,+ SECRET_PROJECT,+ "QUERYplanted",+ "HOOKplanted",+ "PROJECTPLANTED",+ "sk-ant",+ "ghp_",+ "AKIA",+ "where did we leave",+ "deploy with token",+ "/work/",+ "default",+ session,+ ROOT,+ ] {+ assert!(+ !after.contains(planted),+ "/admin/metrics leaked {planted:?}:\n{after}"+ );+ }+ // Every label is one of the fixed, compile-time label names.+ for line in after.lines().filter(|l| !l.starts_with('#')) {+ if let Some((_, labels)) = line.split_once('{') {+ let key = labels.split('=').next().unwrap();+ assert!(+ ["result", "outcome", "kind", "le"].contains(&key),+ "unexpected label in {line}"+ );+ }+ }+}++#[tokio::test]+async fn metrics_are_root_only_on_a_multi_user_server() {+ let h = harness().await;+ let create = Request::builder()+ .method("POST")+ .uri("/admin/users")+ .header("authorization", format!("Bearer {ROOT}"))+ .header("content-type", "application/json")+ .body(Body::from(json!({ "username": "alice" }).to_string()))+ .unwrap();+ let (status, created) = send(&h.router, create).await;+ assert_eq!(status, StatusCode::OK, "{created}");+ let alice: Value = serde_json::from_str(&created).unwrap();+ let alice_token = alice["token"].as_str().expect("DB-user token").to_string();++ let (status, body) = scrape(&h.router, None).await;+ assert_eq!(status, StatusCode::UNAUTHORIZED, "anonymous: {body}");+ assert!(!body.contains("ai_memory_"), "{body}");++ let (status, body) = scrape(&h.router, Some(&alice_token)).await;+ assert_eq!(status, StatusCode::FORBIDDEN, "DB user: {body}");+ assert!(!body.contains("ai_memory_"), "{body}");++ let (status, body) = scrape(&h.router, Some("not-a-real-token")).await;+ assert_eq!(status, StatusCode::UNAUTHORIZED, "unknown bearer: {body}");++ // Control: root still reads the metrics.+ let (status, body) = scrape(&h.router, Some(ROOT)).await;+ assert_eq!(status, StatusCode::OK);+ assert!(body.contains("# TYPE ai_memory_query_duration_seconds histogram"));+}diff --git a/crates/ai-memory-mcp/tests/suite/admin_move.rs b/crates/ai-memory-mcp/tests/suite/admin_move.rsindex ffa442cb..6364a6d5 100644--- a/crates/ai-memory-mcp/tests/suite/admin_move.rs+++ b/crates/ai-memory-mcp/tests/suite/admin_move.rs@@ -44,6 +44,7 @@ async fn make_state(tmp: &TempDir) -> (AdminState, Store) {let db_path = store.db_path().to_path_buf();let state = AdminState {ingest_metrics: std::sync::Arc::new(ai_memory_core::IngestMetrics::default()),+ mcp_metrics: std::sync::Arc::new(ai_memory_mcp::McpMetrics::default()),writer: store.writer.clone(),reader: store.reader.clone(),wiki,@@ -77,6 +78,7 @@ async fn make_state_with_chain(tmp: &TempDir, chain: AdmissionChain) -> (AdminStlet db_path = store.db_path().to_path_buf();let state = AdminState {ingest_metrics: std::sync::Arc::new(ai_memory_core::IngestMetrics::default()),+ mcp_metrics: std::sync::Arc::new(ai_memory_mcp::McpMetrics::default()),writer: store.writer.clone(),reader: store.reader.clone(),wiki,@@ -531,6 +533,7 @@ async fn move_project_carries_source_embedding() {let db_path = store.db_path().to_path_buf();let state = AdminState {ingest_metrics: std::sync::Arc::new(ai_memory_core::IngestMetrics::default()),+ mcp_metrics: std::sync::Arc::new(ai_memory_mcp::McpMetrics::default()),writer: store.writer.clone(),reader: store.reader.clone(),wiki,@@ -826,6 +829,7 @@ async fn true_move_notifies_admission_with_destination_names() {.with_store_reader(store.reader.clone());let state = AdminState {ingest_metrics: std::sync::Arc::new(ai_memory_core::IngestMetrics::default()),+ mcp_metrics: std::sync::Arc::new(ai_memory_mcp::McpMetrics::default()),writer: store.writer.clone(),reader: store.reader.clone(),wiki,@@ -884,6 +888,7 @@ async fn make_state_with_embedder(tmp: &TempDir) -> (AdminState, Store) {let db_path = store.db_path().to_path_buf();let state = AdminState {ingest_metrics: std::sync::Arc::new(ai_memory_core::IngestMetrics::default()),+ mcp_metrics: std::sync::Arc::new(ai_memory_mcp::McpMetrics::default()),writer: store.writer.clone(),reader: store.reader.clone(),wiki,@@ -1113,6 +1118,7 @@ async fn copy_purge_force_never_deletes_a_live_managed_workstream() {fn build_state(store: &Store, tmp: &TempDir) -> AdminState {AdminState {ingest_metrics: std::sync::Arc::new(ai_memory_core::IngestMetrics::default()),+ mcp_metrics: std::sync::Arc::new(ai_memory_mcp::McpMetrics::default()),writer: store.writer.clone(),reader: store.reader.clone(),wiki: Wiki::new(tmp.path(), store.writer.clone()).unwrap(),@@ -1613,6 +1619,7 @@ async fn true_move_aborts_when_admission_rejects() {.with_store_reader(store.reader.clone());let state = AdminState {ingest_metrics: std::sync::Arc::new(ai_memory_core::IngestMetrics::default()),+ mcp_metrics: std::sync::Arc::new(ai_memory_mcp::McpMetrics::default()),writer: store.writer.clone(),reader: store.reader.clone(),wiki,@@ -1712,6 +1719,7 @@ async fn copy_purge_purge_admission_runs_before_db_destruction() {.with_store_reader(store.reader.clone());let state = AdminState {ingest_metrics: std::sync::Arc::new(ai_memory_core::IngestMetrics::default()),+ mcp_metrics: std::sync::Arc::new(ai_memory_mcp::McpMetrics::default()),writer: store.writer.clone(),reader: store.reader.clone(),wiki,@@ -1828,6 +1836,7 @@ async fn move_copy_skips_contributors_webhook_but_runs_others() {.with_store_reader(store.reader.clone());let state = AdminState {ingest_metrics: std::sync::Arc::new(ai_memory_core::IngestMetrics::default()),+ mcp_metrics: std::sync::Arc::new(ai_memory_mcp::McpMetrics::default()),writer: store.writer.clone(),reader: store.reader.clone(),wiki,diff --git a/crates/ai-memory-mcp/tests/suite/admin_move_session.rs b/crates/ai-memory-mcp/tests/suite/admin_move_session.rsindex 29bbfa5f..5af6894f 100644--- a/crates/ai-memory-mcp/tests/suite/admin_move_session.rs+++ b/crates/ai-memory-mcp/tests/suite/admin_move_session.rs@@ -33,6 +33,7 @@ async fn make_state(tmp: &TempDir) -> (AdminState, Store) {let db_path = store.db_path().to_path_buf();let state = AdminState {ingest_metrics: std::sync::Arc::new(ai_memory_core::IngestMetrics::default()),+ mcp_metrics: std::sync::Arc::new(ai_memory_mcp::McpMetrics::default()),writer: store.writer.clone(),reader: store.reader.clone(),wiki,diff --git a/crates/ai-memory-mcp/tests/suite/admin_pending_writes_session.rs b/crates/ai-memory-mcp/tests/suite/admin_pending_writes_session.rsindex a680d0d8..5c161c67 100644--- a/crates/ai-memory-mcp/tests/suite/admin_pending_writes_session.rs+++ b/crates/ai-memory-mcp/tests/suite/admin_pending_writes_session.rs@@ -166,6 +166,7 @@ async fn stage(store: &Store) -> (WorkspaceId, ProjectId, AutoImproveProposalId)fn admin_state(tmp: &TempDir, store: &Store, wiki: Wiki) -> AdminState {AdminState {ingest_metrics: Arc::new(ai_memory_core::IngestMetrics::default()),+ mcp_metrics: std::sync::Arc::new(ai_memory_mcp::McpMetrics::default()),writer: store.writer.clone(),reader: store.reader.clone(),wiki,diff --git a/crates/ai-memory-mcp/tests/suite/admin_phase3.rs b/crates/ai-memory-mcp/tests/suite/admin_phase3.rsindex aa42f1b5..792d8b6e 100644--- a/crates/ai-memory-mcp/tests/suite/admin_phase3.rs+++ b/crates/ai-memory-mcp/tests/suite/admin_phase3.rs@@ -38,6 +38,7 @@ async fn make_state(tmp: &TempDir) -> (AdminState, Store) {let db_path = store.db_path().to_path_buf();let state = AdminState {ingest_metrics: std::sync::Arc::new(ai_memory_core::IngestMetrics::default()),+ mcp_metrics: std::sync::Arc::new(ai_memory_mcp::McpMetrics::default()),writer: store.writer.clone(),reader: store.reader.clone(),wiki,diff --git a/crates/ai-memory-mcp/tests/suite/admin_provider_error_logging.rs b/crates/ai-memory-mcp/tests/suite/admin_provider_error_logging.rsindex d807a19a..df2c0d6d 100644--- a/crates/ai-memory-mcp/tests/suite/admin_provider_error_logging.rs+++ b/crates/ai-memory-mcp/tests/suite/admin_provider_error_logging.rs@@ -93,6 +93,7 @@ async fn make_admin_state(tmp: &TempDir, llm: Option<Arc<dyn LlmProvider>>) -> Alet db_path = store.db_path().to_path_buf();AdminState {ingest_metrics: Arc::new(ai_memory_core::IngestMetrics::default()),+ mcp_metrics: std::sync::Arc::new(ai_memory_mcp::McpMetrics::default()),writer: store.writer.clone(),reader: store.reader.clone(),wiki,diff --git a/crates/ai-memory-mcp/tests/suite/admin_purge.rs b/crates/ai-memory-mcp/tests/suite/admin_purge.rsindex 289ec859..388c775c 100644--- a/crates/ai-memory-mcp/tests/suite/admin_purge.rs+++ b/crates/ai-memory-mcp/tests/suite/admin_purge.rs@@ -41,6 +41,7 @@ async fn make_state_with_chain(let db_path = store.db_path().to_path_buf();let state = AdminState {ingest_metrics: std::sync::Arc::new(ai_memory_core::IngestMetrics::default()),+ mcp_metrics: std::sync::Arc::new(ai_memory_mcp::McpMetrics::default()),writer: store.writer.clone(),reader: store.reader.clone(),wiki,@@ -1182,6 +1183,7 @@ async fn purge_project_rejecting_admission_leaves_source_intact() {.with_store_reader(store.reader.clone());let state = AdminState {ingest_metrics: std::sync::Arc::new(ai_memory_core::IngestMetrics::default()),+ mcp_metrics: std::sync::Arc::new(ai_memory_mcp::McpMetrics::default()),writer: store.writer.clone(),reader: store.reader.clone(),wiki,@@ -1287,6 +1289,7 @@ async fn purge_project_idempotent_second_call_is_404() {let (state_a, store) = make_state(&tmp).await;let state_b = AdminState {ingest_metrics: std::sync::Arc::new(ai_memory_core::IngestMetrics::default()),+ mcp_metrics: std::sync::Arc::new(ai_memory_mcp::McpMetrics::default()),writer: store.writer.clone(),reader: store.reader.clone(),wiki: state_a.wiki.clone(),diff --git a/crates/ai-memory-mcp/tests/suite/admin_read_page.rs b/crates/ai-memory-mcp/tests/suite/admin_read_page.rsindex f5553922..da182a85 100644--- a/crates/ai-memory-mcp/tests/suite/admin_read_page.rs+++ b/crates/ai-memory-mcp/tests/suite/admin_read_page.rs@@ -17,6 +17,7 @@ async fn make_state(tmp: &TempDir) -> (AdminState, Store) {let db_path = store.db_path().to_path_buf();let state = AdminState {ingest_metrics: std::sync::Arc::new(ai_memory_core::IngestMetrics::default()),+ mcp_metrics: std::sync::Arc::new(ai_memory_mcp::McpMetrics::default()),writer: store.writer.clone(),reader: store.reader.clone(),wiki,diff --git a/crates/ai-memory-mcp/tests/suite/admin_reclaim_ledger_versions.rs b/crates/ai-memory-mcp/tests/suite/admin_reclaim_ledger_versions.rsindex 887234d5..94575ce9 100644--- a/crates/ai-memory-mcp/tests/suite/admin_reclaim_ledger_versions.rs+++ b/crates/ai-memory-mcp/tests/suite/admin_reclaim_ledger_versions.rs@@ -25,6 +25,7 @@ async fn make_state(tmp: &TempDir) -> (AdminState, Store) {let db_path = store.db_path().to_path_buf();let state = AdminState {ingest_metrics: std::sync::Arc::new(ai_memory_core::IngestMetrics::default()),+ mcp_metrics: std::sync::Arc::new(ai_memory_mcp::McpMetrics::default()),writer: store.writer.clone(),reader: store.reader.clone(),wiki,diff --git a/crates/ai-memory-mcp/tests/suite/admin_rename.rs b/crates/ai-memory-mcp/tests/suite/admin_rename.rsindex 6bf7c33c..c936df4b 100644--- a/crates/ai-memory-mcp/tests/suite/admin_rename.rs+++ b/crates/ai-memory-mcp/tests/suite/admin_rename.rs@@ -27,6 +27,7 @@ async fn make_state(tmp: &TempDir) -> (AdminState, Store) {let db_path = store.db_path().to_path_buf();let state = AdminState {ingest_metrics: std::sync::Arc::new(ai_memory_core::IngestMetrics::default()),+ mcp_metrics: std::sync::Arc::new(ai_memory_mcp::McpMetrics::default()),writer: store.writer.clone(),reader: store.reader.clone(),wiki,@@ -374,6 +375,7 @@ async fn rename_project_pages_still_searchable() {// axum's `oneshot` consumes the router.let state2 = AdminState {ingest_metrics: std::sync::Arc::new(ai_memory_core::IngestMetrics::default()),+ mcp_metrics: std::sync::Arc::new(ai_memory_mcp::McpMetrics::default()),writer: store.writer.clone(),reader: store.reader.clone(),wiki: state.wiki.clone(),@@ -450,6 +452,7 @@ async fn rename_project_after_purge_returns_404_not_silent_200() {// Purge the row out from under any in-flight rename.let purge_state = AdminState {ingest_metrics: std::sync::Arc::new(ai_memory_core::IngestMetrics::default()),+ mcp_metrics: std::sync::Arc::new(ai_memory_mcp::McpMetrics::default()),writer: state.writer.clone(),reader: state.reader.clone(),wiki: state.wiki.clone(),diff --git a/crates/ai-memory-mcp/tests/suite/admin_repair_session_times.rs b/crates/ai-memory-mcp/tests/suite/admin_repair_session_times.rsindex 9db96f23..19415496 100644--- a/crates/ai-memory-mcp/tests/suite/admin_repair_session_times.rs+++ b/crates/ai-memory-mcp/tests/suite/admin_repair_session_times.rs@@ -26,6 +26,7 @@ async fn make_state(tmp: &TempDir) -> (AdminState, Store) {let db_path = store.db_path().to_path_buf();let state = AdminState {ingest_metrics: std::sync::Arc::new(ai_memory_core::IngestMetrics::default()),+ mcp_metrics: std::sync::Arc::new(ai_memory_mcp::McpMetrics::default()),writer: store.writer.clone(),reader: store.reader.clone(),wiki,diff --git a/crates/ai-memory-mcp/tests/suite/admin_status_search.rs b/crates/ai-memory-mcp/tests/suite/admin_status_search.rsindex 86c84b4b..12a843a7 100644--- a/crates/ai-memory-mcp/tests/suite/admin_status_search.rs+++ b/crates/ai-memory-mcp/tests/suite/admin_status_search.rs@@ -20,6 +20,7 @@ async fn make_admin_state(tmp: &TempDir) -> (AdminState, Store) {let db_path = store.db_path().to_path_buf();let state = AdminState {ingest_metrics: std::sync::Arc::new(ai_memory_core::IngestMetrics::default()),+ mcp_metrics: std::sync::Arc::new(ai_memory_mcp::McpMetrics::default()),writer: store.writer.clone(),reader: store.reader.clone(),wiki,diff --git a/crates/ai-memory-mcp/tests/suite/admin_write_page.rs b/crates/ai-memory-mcp/tests/suite/admin_write_page.rsindex 35c0985b..3e8493c6 100644--- a/crates/ai-memory-mcp/tests/suite/admin_write_page.rs+++ b/crates/ai-memory-mcp/tests/suite/admin_write_page.rs@@ -22,6 +22,7 @@ async fn make_state(tmp: &TempDir) -> AdminState {let db_path = store.db_path().to_path_buf();AdminState {ingest_metrics: std::sync::Arc::new(ai_memory_core::IngestMetrics::default()),+ mcp_metrics: std::sync::Arc::new(ai_memory_mcp::McpMetrics::default()),writer: store.writer.clone(),reader: store.reader.clone(),wiki,diff --git a/crates/ai-memory-mcp/tests/suite/mod.rs b/crates/ai-memory-mcp/tests/suite/mod.rsindex ac49e32d..ede91b10 100644--- a/crates/ai-memory-mcp/tests/suite/mod.rs+++ b/crates/ai-memory-mcp/tests/suite/mod.rs@@ -8,6 +8,7 @@ mod access_reinforcement;mod admin_audit_log;mod admin_backup;mod admin_bootstrap;+mod admin_metrics;mod admin_move;mod admin_move_session;mod admin_pending_writes_session;diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.mdindex fde0f6bf..8a73d793 100644--- a/docs/ARCHITECTURE.md+++ b/docs/ARCHITECTURE.md@@ -686,6 +686,22 @@ The deprecated Basic/cookie path stops immediately when human auth becomesactive; restart is not required. `/web` SPA HTML is public static; the builtinwiki browser and JSON APIs stay behind the route class above.+### `GET /admin/metrics`++A Prometheus text-format scrape (`text/plain; version=0.0.4`) of process+lifetime counters: hook admissions by result and completed deliveries by+outcome (the `IngestMetrics` atomics `/admin/status` already reports), the+last-persisted timestamp, MCP tool calls split into `read` and `write`, and+fixed-bucket latency histograms for `POST /hook` (time to answer, not the+spawned processing) and `memory_query` (wall time, errors included). Buckets+run from 1 ms to 10 s plus `+Inf`. Each observation is a bounded bucket scan and+relaxed atomic adds, with no lock and no allocation. Every label comes from a+closed, compile-time set (`result`, `outcome`, `kind`, `le`), so no query text,+page body, prompt, client name, scope or project name, or token can appear in a+series, and scope is never a label. The route sits behind the same+`require_root_for_multiuser_admin` gate as every `/admin/*` route: root-only once+the deployment distinguishes operators. Counters reset on restart.+## CLI subcommand surface```diff --git a/docs/security-boundaries.md b/docs/security-boundaries.mdindex 2ed58885..e0a40dae 100644--- a/docs/security-boundaries.md+++ b/docs/security-boundaries.md@@ -35,6 +35,7 @@ means the boundary is not built yet.| 3 | Multi-user auth ladder | `ai-memory-core/src/actor.rs` `AuthLevel::authorize`; `ai-memory-mcp/src/auth.rs` middleware; `admin.rs` `require_root_for_multiuser_admin` / `require_root`; `identity.rs` authorizes `NormalRead` behind the same machine bearer middleware as MCP; `serve.rs` mounts API-only and web+API protected routers behind `require_dual_auth` | `admin.rs` `multiuser_admin_routes_reject_db_user_tier` / `…reject_anonymous` / `create_user_as_user_tier_returns_403`; `auth.rs` unknown-bearer 401; `actor.rs` `skip_admission_chain_rejects_db_users`; `identity.rs` `identity_real_auth_isolates_users_root_and_revoked_keys`, `identity_anonymous_ignores_forged_headers_and_proxy_qualifies_oidc` (distinct users and root, invalid/revoked keys, forged headers, anonymous control); `serve.rs` `api_only_mode_keeps_data_authenticated_and_web_absent` (anonymous API read refused, authenticated control admitted, browser route absent; #986) | STRONG || 3b | Browser triage of pending writes (#855) | `ai-memory-web/src/routes/pending.rs` `require_admin` (`AuthLevel::authorize(Capability::Admin, distinguishes_operators)`, trusted-proxy flag from `WebMountSpec`) gates `GET {web_slug}/pending`; `html_auth.rs` `AdminRequired` keeps a non-root 403 off the change-password redirect; decisions post to the existing `/admin/pending-writes/{id}/approve\|reject` behind `require_dual_auth` (session + CSRF) and `require_root_for_multiuser_admin`. `ai-memory-web` has no write route | `ai-memory-web` `tests/suite/pending.rs` — anonymous refused (401, login redirect), DB user refused (403, no proposal text, no redirect), trusted-proxy flag reaches the gate, single-operator control admits, POSTs to `/pending*` refused, project filter keys do not collide on `/` in names, projects past the 500-row read cap stay counted and reachable; `ai-memory-mcp` `tests/suite/admin_pending_writes_session.rs` — anonymous and DB-user sessions refused, root session without a matching CSRF header refused (each leaves the proposal pending and no file), root approval keeps `auto_improve_proposal_id`/`auto_improve_run_id` and records the approver, root reject writes no file (each proven to fail with its guard removed); `ai-memory-mcp` `admin.rs` `pending_write_approve_foreign_scope_returns_404` and `pending_write_reject_foreign_scope_returns_404` — an id staged in workspace `alpha` requested through an existing `default` scope is 404 (never approved or rejected across the boundary), with the in-scope reject as the legitimate control (each proven to fail with 500 with the `pending_detail` guard removed, #1205) | STRONG || 3c | Public human-auth routes refuse bodies a foreign page can send without a preflight (login CSRF, password guessing, root recovery) | `ai-memory-mcp/src/human_auth.rs` `handle_login` / `handle_recovery` read their bodies by hand (to rate-limit first), so each checks `declares_json_body` before reading: a `Content-Type` other than `application/json` or `application/*+json` (parameters and case ignored), or none, → 415 before any password or recovery-token check and without charging the per-IP failure budget. `text/plain`, form-urlencoded and multipart are the only bodies a cross-site page can `POST` without a preflight, and `/auth/*` carries no CORS layer. The built-in login page, the `docs/frontend-api.md` examples and the recovery `curl` in `docs/install.md` send `application/json` | `human_auth.rs` `public_auth_routes_refuse_preflight_free_browser_bodies`: valid root credentials and a valid recovery token, sent from a foreign origin as `text/plain`, form-urlencoded, multipart and with no content type, more times than the per-IP failure budget → 415, no session cookie; controls: a same-origin JSON login then succeeds (password unchanged, budget untouched) and a JSON recovery returns 204. `json_body_declaration` (header table) | STRONG. Bite check: with the check removed, the `text/plain` login returns 200 with the session cookie (the pre-fix behaviour) and the test fails. `/auth/password` and `/auth/logout` were already closed: they run behind `require_session`, whose unsafe methods need the `x-csrf-token` header (a custom header, so preflighted), and `/auth/password` also uses axum `Json` |+| 3d | `GET /admin/metrics` is root-only on a multi-user server and content-free | `ai-memory-mcp/src/admin.rs` mounts `/admin/metrics` inside the operational router under `require_root_for_multiuser_admin` (`AuthLevel::authorize(Capability::Admin, distinguishes_operators)`); `ai-memory-mcp/src/metrics.rs` `render_prometheus` writes only counts and durations under compile-time metric names and the closed label set `result` / `outcome` / `kind` / `le`; `McpMetrics::record_tool_call` takes only a read/write bit (no client name); `ai-memory-core/src/latency.rs` `LatencyHistogram` holds bucket counts and a sum, nothing keyed on a request; scope is never a label | mcp `integration::admin_metrics` `metrics_count_queries_and_hooks_without_leaking_any_content` (secret-shaped strings planted in a `memory_query` query, a `/hook` prompt and the project name never appear in the scrape, nor do the session id, workspace name or root token; every label key is from the closed set; control: the query and hook histograms, the accepted-hook counter and the read tool-call counter move by exactly what was sent), `metrics_are_root_only_on_a_multi_user_server` (production `require_dual_auth` with a real DB-user key: anonymous 401, DB user 403, unknown bearer 401, root control 200); `admin.rs` `multiuser_admin_routes_reject_db_user_tier` / `…reject_anonymous` include the route, `multiuser_operational_admin_routes_allow_root` admits root | STRONG. Bite checks: with the route mounted outside the gate the three refusal tests fail; with the query, the project name or the hook body rendered as a label value the leak test fails on each || 4 | Handoff single-claim / no-steal | `ai-memory-store/src/ops.rs` `accept_handoff_in_transaction` (metadata `state='open'` guard + atomic CAS; the receiver-session check, which requires the receiving session to exist in the claim's own workspace, project and agent kind and refuses with `InvalidState` before the handoff row is touched; an ended receiver is final EXCEPT for the agents where `AgentKind::reuses_session_id_after_end()` holds — Grok and Kimi Code, whose harnesses reuse the native session id across SessionEnd→resume, so accepting reopens `ended_at` only after the claim-once guard) | `multi_session.rs` `a_second_accept_cannot_steal_an_accepted_handoff`; `handoff_ownership.rs` `another_operator_cannot_claim_the_handoff`; `multi_session.rs` `handoff_accept_rejects_foreign_or_missing_receiver_session` (receivers from a sibling project, another workspace, a different agent kind, and a nonexistent session are each refused as `InvalidState` with the handoff left open and every `accepted_*` column NULL; the matching receiver claims it; the same receiver retrying and a second matching session get `false` with the first claim intact; fails with the `project_id` or `agent_kind` predicate, or the missing-session refusal, removed. The `workspace_id` predicate is redundant defence in depth: project ids are globally unique, so the cross-workspace receiver is already caught by `project_id`); `multi_session.rs` `accept_reopens_an_ended_receiver_session_but_keeps_claim_once` (Grok reopen + no-steal) and `accept_reopens_an_ended_kimi_receiver_but_keeps_every_guard` (Kimi Code resume claims and reopens `ended_at`; adversarial controls: an ended claude-code receiver stays refused, a kimi-code receiver in another project stays refused, and the already-claimed guard still refuses the resumed kimi session a second baton) | STRONG || 4b | Handoff owner-scoped recovery (`any_owner` admin gate) | `ai-memory-mcp/src/server.rs` `require_admin_capability` on `memory_handoff_accept`/`_cancel` `any_owner` | `handoff_admission.rs` — cancel gate + **accept gate** (adversarial: non-admin `any_owner` accept refused) | STRONG || 4c | Turn-checkpoint baton is owner+scope-bound | `ai-memory-store/src/ops.rs` `checkpoint_session_handoff` — reads the session's own `(workspace, project, owner_user)` from `sessions WHERE id=?1 AND ended_at IS NULL`, refuses on scope/owner mismatch, refreshes only that session's own `state='open'` baton (id preserved), returns `None` when the session already ended | `ops.rs` `checkpoint_session_handoff_refreshes_only_the_live_sessions_own_baton` (#865) | STRONG |diff --git a/docs/users.md b/docs/users.mdindex 4ae6844a..0b86563e 100644--- a/docs/users.md+++ b/docs/users.md@@ -262,6 +262,13 @@ no workspace or project because many MCP-only clients do not provide reliableper-call scope. Like every `/admin/*` route, it is root-only when the deploymentdistinguishes operators.+`GET /admin/metrics` exposes the same read/write split as process-lifetime+totals in Prometheus text format (`ai_memory_mcp_tool_calls_total{kind=...}`),+next to the hook counters and the `/hook` and `memory_query` latency+histograms. It carries no client name: a client label is caller-supplied text,+and no metric label is ever drawn from a request. It is root-only under the same+rule.+## Per-operator memory slotsThe "absent means shared" rule extends to memory slots, so a single-operator