Skip to content

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.md
index 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 observation
ids. Hits are still pages and nothing is written; sessions without a page
keep 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.rs
index 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.rs
index 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.rs
new file mode 100644
index 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.rs
index 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.rs
index 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.rs
index 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.rs
index 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 a
diff --git a/crates/ai-memory-mcp/src/metrics.rs b/crates/ai-memory-mcp/src/metrics.rs
new file mode 100644
index 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.rs
index 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_activity
diff --git a/crates/ai-memory-mcp/tests/suite/admin_audit_log.rs b/crates/ai-memory-mcp/tests/suite/admin_audit_log.rs
index 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.rs
index 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.rs
index 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.rs
new file mode 100644
index 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.rs
index 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) -> (AdminSt
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,
@@ -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.rs
index 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.rs
index 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.rs
index 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.rs
index 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>>) -> A
let 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.rs
index 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.rs
index 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.rs
index 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.rs
index 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.rs
index 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.rs
index 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.rs
index 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.rs
index 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.md
index 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 becomes
active; restart is not required. `/web` SPA HTML is public static; the builtin
wiki 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.md
index 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.md
index 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 reliable
per-call scope. Like every `/admin/*` route, it is root-only when the deployment
distinguishes 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 slots
The "absent means shared" rule extends to memory slots, so a single-operator