Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors
Rust
feat(admin): add read-only GET /admin/audit-log (#531)
Djalma Júniorc22777e6bafa
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 95130e6d..09f75866 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -7,6 +7,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0## [Unreleased]+### Added+- Added `GET /admin/audit-log`, a read-only paginated reader for the existing+ `audit_log` table. Events resolve workspace, project, page path, and author+ username through LEFT JOINs (orphans stay `null` — the log has no foreign+ keys by design), page by keyset (`before_id`) so a live trail cannot skip or+ duplicate rows, and clamp `limit` to 1..=200 (default 50). The `detail`+ column is returned for schema fidelity; the only writer still stores the+ literal `{}`. (#531)+### Fixed- Stopped a session summary spending its characters on tool family labels. Thesummary #477 added names the busiest tools, but for the seven agents that godiff --git a/crates/ai-memory-mcp/src/admin.rs b/crates/ai-memory-mcp/src/admin.rsindex 2f05f4a6..e50ed8cc 100644--- a/crates/ai-memory-mcp/src/admin.rs+++ b/crates/ai-memory-mcp/src/admin.rs@@ -12,6 +12,7 @@//! - `GET /admin/open-sessions` — open (not yet ended) sessions for one scope + agent.//! - `GET /admin/sessions/by-agent` — session counts per agent CLI for one scope.//! - `GET /admin/activity/by-client` — MCP tool-call counts per client (server-wide).+//! - `GET /admin/audit-log` — paginated read of the append-only `audit_log`.//! - `GET /admin/search?q=` — FTS5 hits against the wiki index.//! - `POST /admin/reorg` — retro-fit sessions to per-cwd projects.//! - `POST /admin/lint` — run the M8 lint pass.@@ -57,10 +58,11 @@ use ai_memory_core::{};use ai_memory_llm::{Embedder, LlmProvider, ProviderHealth, ProviderHealthSnapshot};use ai_memory_store::{- ApproveAutoImproveProposalResult, AutoImproveProposalOperation, AutoImproveProposalStatus,- DecayParams, NewAutoImproveProposal, PagesMode, ReaderPool, RejectAutoImproveProposal,- ScopeResolutionError, SkippedProposal, StageAutoImproveRun, StoreError, WriterHandle,- create_explicit_scope, f32_vec_to_bytes, lookup_existing_scope, lookup_existing_workspace,+ ApproveAutoImproveProposalResult, AuditLogFilter, AutoImproveProposalOperation,+ AutoImproveProposalStatus, DecayParams, NewAutoImproveProposal, PagesMode, ReaderPool,+ RejectAutoImproveProposal, ScopeResolutionError, SkippedProposal, StageAutoImproveRun,+ StoreError, WriterHandle, create_explicit_scope, f32_vec_to_bytes, lookup_existing_scope,+ lookup_existing_workspace,};use ai_memory_wiki::{AdmissionContext, AdmissionOp, Markdown, SessionPageFile, Wiki, WikiError, WritePageRequest,@@ -606,6 +608,7 @@ pub fn admin_router_with_sweep_tuning("/admin/audit-contamination",get(handle_audit_contamination),)+ .route("/admin/audit-log", get(handle_audit_log)).route("/admin/search", get(handle_search)).route("/admin/read-page", get(handle_read_page)).route("/admin/reorg", post(handle_reorg))@@ -842,6 +845,62 @@ async fn handle_audit_contamination(}}+/// Query string for `GET /admin/audit-log`. Names are optional independent+/// filters; when both workspace and project are present they are resolved+/// through [`lookup_existing_scope`] so a typo fails closed (404) instead of+/// looking like an empty log.+#[derive(Debug, Deserialize)]+struct AuditLogQuery {+ workspace: Option<String>,+ project: Option<String>,+ op: Option<String>,+ before_id: Option<i64>,+ #[serde(default = "default_audit_log_limit")]+ limit: usize,+}++fn default_audit_log_limit() -> usize {+ 50+}++/// `GET /admin/audit-log` — read-only paginated trail of the existing+/// `audit_log` table. `detail` is returned for schema fidelity; it is not a+/// payload (the only writer stores the literal `{}`).+async fn handle_audit_log(+ State(state): State<Arc<AdminState>>,+ Query(q): Query<AuditLogQuery>,+) -> impl IntoResponse {+ let workspace = trimmed_opt(q.workspace.as_deref()).map(str::to_owned);+ let project = trimmed_opt(q.project.as_deref()).map(str::to_owned);+ if let (Some(ws), Some(proj)) = (workspace.as_deref(), project.as_deref()) {+ match lookup_ws_proj_no_create(&state, ws, proj).await {+ Ok(_) => {}+ Err(e) => return e,+ }+ }+ let filter = AuditLogFilter {+ workspace,+ project,+ op: trimmed_opt(q.op.as_deref()).map(str::to_owned),+ before_id: q.before_id,+ limit: q.limit,+ };+ match state.reader.list_audit_events(filter).await {+ Ok(events) => (+ StatusCode::OK,+ Json(+ serde_json::to_value(&events)+ .map(|list| serde_json::json!({ "events": list }))+ .unwrap_or_else(|_| serde_json::json!({ "events": [] })),+ ),+ ),+ Err(e) => (+ StatusCode::INTERNAL_SERVER_ERROR,+ Json(serde_json::json!({ "error": e.to_string() })),+ ),+ }+}+/// 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.@@ -9565,6 +9624,7 @@ mod tests {serde_json::Value::Null,),("GET", "/admin/audit-contamination", serde_json::Value::Null),+ ("GET", "/admin/audit-log", serde_json::Value::Null),("GET", "/admin/search?q=test", serde_json::Value::Null),("GET",diff --git a/crates/ai-memory-mcp/tests/admin_audit_log.rs b/crates/ai-memory-mcp/tests/admin_audit_log.rsnew file mode 100644index 00000000..ebd12471--- /dev/null+++ b/crates/ai-memory-mcp/tests/admin_audit_log.rs@@ -0,0 +1,127 @@+//! Integration tests for `GET /admin/audit-log`.++use ai_memory_core::{NewPage, PagePath, Tier};+use ai_memory_mcp::{AdminState, admin_router};+use ai_memory_store::{DecayParams, Store};+use ai_memory_wiki::Wiki;+use axum::body::Body;+use axum::http::{Request, StatusCode};+use tempfile::TempDir;+use tower::ServiceExt;++async fn make_admin_state(tmp: &TempDir) -> (AdminState, Store) {+ let store = Store::open(tmp.path()).unwrap();+ let wiki = Wiki::new(tmp.path(), store.writer.clone()).unwrap();+ let db_path = store.db_path().to_path_buf();+ let state = AdminState {+ ingest_metrics: std::sync::Arc::new(ai_memory_core::IngestMetrics::default()),+ 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: ai_memory_llm::ProviderHealth::default(),+ decay_params: DecayParams::default(),+ data_dir: tmp.path().to_path_buf(),+ db_path,+ bind: "127.0.0.1:49374".to_string(),+ home_dir: None,+ bootstrap_lock: std::sync::Arc::new(tokio::sync::Mutex::new(())),+ token_pepper: None,+ active_project: ai_memory_core::ActiveProject::new(),+ scope_invalidator: None,+ trusted_proxy_identity: false,+ };+ (state, store)+}++async fn seed_page(store: &Store, workspace: &str, project: &str, path: &str, body: &str) {+ let ws = store+ .writer+ .get_or_create_workspace(workspace.to_string())+ .await+ .unwrap();+ let proj = store+ .writer+ .get_or_create_project(ws, project.to_string(), None)+ .await+ .unwrap();+ store+ .writer+ .upsert_page(NewPage {+ workspace_id: ws,+ project_id: proj,+ path: PagePath::new(path).unwrap(),+ title: path.to_string(),+ body: body.to_string(),+ tier: Tier::Semantic,+ frontmatter_json: serde_json::json!({}),+ pinned: false,+ links: Vec::new(),+ author_id: None,+ expires_at: None,+ entities: Vec::new(),+ })+ .await+ .unwrap();+}++async fn body_json(resp: axum::response::Response) -> serde_json::Value {+ use axum::body::to_bytes;+ let bytes = to_bytes(resp.into_body(), 1_000_000).await.unwrap();+ serde_json::from_slice(&bytes).unwrap()+}++#[tokio::test]+async fn audit_log_returns_event_shape_and_honours_scope_filter() {+ let tmp = TempDir::new().unwrap();+ let (state, store) = make_admin_state(&tmp).await;+ seed_page(&store, "default", "scratch", "notes/a.md", "in default").await;+ seed_page(&store, "acme", "infra", "notes/b.md", "in acme").await;+ let app = admin_router(state);++ let resp = app+ .clone()+ .oneshot(+ Request::builder()+ .method("GET")+ .uri("/admin/audit-log")+ .body(Body::empty())+ .unwrap(),+ )+ .await+ .unwrap();+ assert_eq!(resp.status(), StatusCode::OK);+ let body = body_json(resp).await;+ let events = body["events"].as_array().expect("events array");+ assert!(events.len() >= 2, "seeded two page writes");+ let sample = &events[0];+ assert!(sample["id"].is_i64() || sample["id"].is_u64());+ assert!(sample["at"].is_i64() || sample["at"].is_u64());+ assert!(sample["op"].is_string());+ assert!(sample.get("workspace").is_some());+ assert!(sample.get("project").is_some());+ assert!(sample.get("page_path").is_some());+ assert!(sample.get("author_username").is_some());+ assert_eq!(sample["detail"], "{}");++ let resp = app+ .oneshot(+ Request::builder()+ .method("GET")+ .uri("/admin/audit-log?workspace=default&project=scratch")+ .body(Body::empty())+ .unwrap(),+ )+ .await+ .unwrap();+ assert_eq!(resp.status(), StatusCode::OK);+ let body = body_json(resp).await;+ let events = body["events"].as_array().expect("events array");+ assert!(!events.is_empty());+ assert!(events.iter().all(|e| {+ e["workspace"] == "default" && e["project"] == "scratch" && e["page_path"] != "notes/b.md"+ }));+}diff --git a/crates/ai-memory-store/src/lib.rs b/crates/ai-memory-store/src/lib.rsindex c1ee768f..dea405b4 100644--- a/crates/ai-memory-store/src/lib.rs+++ b/crates/ai-memory-store/src/lib.rs@@ -50,13 +50,13 @@ pub use ops::{ObservationPruneOutcome, PagesMode, PurgeSummary, ReorgSummary,};pub use reader::{- ActivityWindow, AgentSessionCount, AutoImproveCandidateSession, BriefPageBody, BriefingPage,- BriefingSnapshot, ClientActivity, ContaminationFinding, ContaminationReport,- ContaminationSummary, DecayCandidate, DecayTombstone, DerivedIndexStatus, EmbeddingTripleCount,- FeedbackFinding, GraphVia, HealthDetail, HealthPage, ObservationHit, ObservationOrder,- ObservationPage, ObservationPageResult, ObservationRecord, OpenSession, PageAuthor, PageHit,- PageHitWithMeta, PageLinks, PageMeta, PageSummary, ProjectSummary, ReaderPool,- ReindexTargetStatus, RelatedPage, RrfContributions, ScopeRow, SearchExplain,+ ActivityWindow, AgentSessionCount, AuditEvent, AuditLogFilter, AutoImproveCandidateSession,+ BriefPageBody, BriefingPage, BriefingSnapshot, ClientActivity, ContaminationFinding,+ ContaminationReport, ContaminationSummary, DecayCandidate, DecayTombstone, DerivedIndexStatus,+ EmbeddingTripleCount, FeedbackFinding, GraphVia, HealthDetail, HealthPage, ObservationHit,+ ObservationOrder, ObservationPage, ObservationPageResult, ObservationRecord, OpenSession,+ PageAuthor, PageHit, PageHitWithMeta, PageLinks, PageMeta, PageSummary, ProjectSummary,+ ReaderPool, ReindexTargetStatus, RelatedPage, RrfContributions, ScopeRow, SearchExplain,SessionDependentRows, SessionEndDisposition, SessionSummary, StatusCounts, StoredEmbedding,StoredPageBody, WorkspaceScopeRow, WorkspaceSummary, f32_vec_to_bytes,};diff --git a/crates/ai-memory-store/src/reader.rs b/crates/ai-memory-store/src/reader.rsindex eeb013b6..2a6c45b1 100644--- a/crates/ai-memory-store/src/reader.rs+++ b/crates/ai-memory-store/src/reader.rs@@ -817,6 +817,57 @@ pub struct ContaminationReport {pub findings: Vec<ContaminationFinding>,}+/// One `audit_log` row with names resolved through LEFT JOINs.+///+/// Workspace, project, page, and author are `Option` because the log has+/// no foreign keys (V05: append-only; orphan rows are expected).+#[derive(Debug, Clone, PartialEq, Eq, Serialize)]+pub struct AuditEvent {+ /// Auto-increment primary key; also the keyset pagination cursor.+ pub id: i64,+ /// Event time in microseconds since Unix epoch (V01 convention).+ pub at: i64,+ /// Writer-assigned op (`create_page`, `supersede_page`, `purge_project`, …).+ pub op: String,+ /// Workspace name, or `None` when the id no longer resolves.+ pub workspace: Option<String>,+ /// Project name, or `None` when the id no longer resolves.+ pub project: Option<String>,+ /// Page path, or `None` when the id no longer resolves.+ pub page_path: Option<String>,+ /// Username, or `None` for anonymous writes and deleted users.+ pub author_username: Option<String>,+ /// Schema column. The only writer stores the literal `{}`; not a payload.+ pub detail: String,+}++/// Filters for [`ReaderPool::list_audit_events`].+#[derive(Debug, Clone)]+pub struct AuditLogFilter {+ /// Restrict to this workspace **name**.+ pub workspace: Option<String>,+ /// Restrict to this project **name**.+ pub project: Option<String>,+ /// Restrict to this op string.+ pub op: Option<String>,+ /// Keyset cursor: return rows with `id` strictly less than this value.+ pub before_id: Option<i64>,+ /// Page size. Clamped to `1..=200`; [`Default`] is 50.+ pub limit: usize,+}++impl Default for AuditLogFilter {+ fn default() -> Self {+ Self {+ workspace: None,+ project: None,+ op: None,+ before_id: None,+ limit: 50,+ }+ }+}+/// Counts that must all be zero before `ai-memory reindex` rebuilds the/// derived SQLite store from wiki files.#[derive(Debug, Clone, Default, Serialize)]@@ -6676,6 +6727,88 @@ impl ReaderPool {Ok(ContaminationReport { summary, findings })}+ /// List `audit_log` rows newest-first, resolving names through LEFT JOINs.+ ///+ /// Workspace/project filters match on **name** (the same convention as+ /// [`Self::list_pages`]). `before_id` is a keyset cursor (`id < ?` under+ /// `ORDER BY id DESC`): new events get higher ids, so they land on later+ /// first pages instead of shifting this window and duplicating or skipping+ /// rows already seen. `limit` is clamped to `1..=200`.+ ///+ /// `detail` is the schema column; the only writer currently stores the+ /// literal `{}`.+ ///+ /// # Errors+ /// Propagates any SQL or pool error.+ pub async fn list_audit_events(&self, filter: AuditLogFilter) -> StoreResult<Vec<AuditEvent>> {+ let limit = filter.limit.clamp(1, 200);+ let workspace = filter.workspace.filter(|s| !s.is_empty());+ let project = filter.project.filter(|s| !s.is_empty());+ let op = filter.op.filter(|s| !s.is_empty());+ let before_id = filter.before_id;+ self.with_conn(move |conn| {+ let mut sql = String::from(+ "SELECT a.id, a.at, a.op, w.name, p.name, pg.path, u.username, a.detail \+ FROM audit_log a \+ LEFT JOIN workspaces w ON w.id = a.workspace_id \+ LEFT JOIN projects p ON p.id = a.project_id \+ LEFT JOIN pages pg ON pg.id = a.page_id \+ LEFT JOIN users u ON u.id = a.author_id",+ );+ let mut binds: Vec<Value> = Vec::new();+ let mut clauses: Vec<&str> = Vec::new();+ if workspace.is_some() {+ clauses.push("w.name = ?");+ }+ if project.is_some() {+ clauses.push("p.name = ?");+ }+ if op.is_some() {+ clauses.push("a.op = ?");+ }+ if before_id.is_some() {+ clauses.push("a.id < ?");+ }+ if !clauses.is_empty() {+ sql.push_str(" WHERE ");+ sql.push_str(&clauses.join(" AND "));+ }+ sql.push_str(" ORDER BY a.id DESC LIMIT ?");+ if let Some(ws) = &workspace {+ binds.push(Value::Text(ws.clone()));+ }+ if let Some(proj) = &project {+ binds.push(Value::Text(proj.clone()));+ }+ if let Some(op) = &op {+ binds.push(Value::Text(op.clone()));+ }+ if let Some(before) = before_id {+ binds.push(Value::Integer(before));+ }+ binds.push(Value::Integer(i64::try_from(limit).unwrap_or(200)));+ let mut stmt = conn.prepare(&sql)?;+ let rows = stmt.query_map(params_from_iter(binds.iter()), |row| {+ Ok(AuditEvent {+ id: row.get(0)?,+ at: row.get(1)?,+ op: row.get(2)?,+ workspace: row.get(3)?,+ project: row.get(4)?,+ page_path: row.get(5)?,+ author_username: row.get(6)?,+ detail: row.get(7)?,+ })+ })?;+ let mut out = Vec::new();+ for row in rows {+ out.push(row?);+ }+ Ok(out)+ })+ .await+ }+/// Return aggregate counts for the `status` view.////// # Errorsdiff --git a/crates/ai-memory-store/tests/audit_log.rs b/crates/ai-memory-store/tests/audit_log.rsnew file mode 100644index 00000000..009cbb9b--- /dev/null+++ b/crates/ai-memory-store/tests/audit_log.rs@@ -0,0 +1,219 @@+//! Reader for the append-only `audit_log` table.++use ai_memory_core::{NewPage, NewUser, PagePath, ProjectId, Tier, UserId, WorkspaceId};+use ai_memory_store::{AuditLogFilter, Store, TOKEN_HASH_LEN};++async fn seed_page(+ store: &Store,+ ws: WorkspaceId,+ proj: ProjectId,+ path: &str,+ body: &str,+ author_id: Option<UserId>,+) {+ store+ .writer+ .upsert_page(NewPage {+ workspace_id: ws,+ project_id: proj,+ path: PagePath::new(path).unwrap(),+ title: path.to_string(),+ body: body.to_string(),+ tier: Tier::Semantic,+ frontmatter_json: serde_json::json!({}),+ pinned: false,+ links: Vec::new(),+ author_id,+ expires_at: None,+ entities: Vec::new(),+ })+ .await+ .unwrap();+}++#[tokio::test]+async fn list_audit_events_resolves_names_pages_and_clamps_limit() {+ let tmp = tempfile::tempdir().unwrap();+ let store = Store::open(tmp.path()).unwrap();++ let alice = store+ .writer+ .create_user(+ NewUser {+ username: "alice".to_string(),+ name: None,+ email: None,+ },+ [7u8; TOKEN_HASH_LEN],+ )+ .await+ .unwrap();++ let default_ws = store+ .writer+ .get_or_create_workspace("default".to_string())+ .await+ .unwrap();+ let scratch = store+ .writer+ .get_or_create_project(default_ws, "scratch".to_string(), None)+ .await+ .unwrap();+ let other_ws = store+ .writer+ .get_or_create_workspace("other".to_string())+ .await+ .unwrap();+ let other_proj = store+ .writer+ .get_or_create_project(other_ws, "labs".to_string(), None)+ .await+ .unwrap();++ seed_page(+ &store,+ default_ws,+ scratch,+ "notes/alice.md",+ "attributed",+ Some(alice),+ )+ .await;+ seed_page(+ &store,+ default_ws,+ scratch,+ "notes/anon.md",+ "anonymous",+ None,+ )+ .await;+ seed_page(+ &store,+ other_ws,+ other_proj,+ "notes/elsewhere.md",+ "other scope",+ Some(alice),+ )+ .await;+ // Second write of the same path produces `supersede_page`.+ seed_page(+ &store,+ default_ws,+ scratch,+ "notes/alice.md",+ "attributed v2",+ Some(alice),+ )+ .await;++ let all = store+ .reader+ .list_audit_events(AuditLogFilter::default())+ .await+ .unwrap();+ assert!(all.len() >= 4, "create ×3 + supersede, got {}", all.len());+ assert!(+ all.windows(2).all(|w| w[0].id > w[1].id),+ "newest-first by id"+ );++ let alice_write = all+ .iter()+ .find(|e| e.page_path.as_deref() == Some("notes/alice.md") && e.op == "create_page")+ .expect("attributed create_page");+ assert_eq!(alice_write.workspace.as_deref(), Some("default"));+ assert_eq!(alice_write.project.as_deref(), Some("scratch"));+ assert_eq!(alice_write.author_username.as_deref(), Some("alice"));+ assert_eq!(alice_write.detail, "{}");+ assert!(alice_write.at > 0);++ let anon = all+ .iter()+ .find(|e| e.page_path.as_deref() == Some("notes/anon.md"))+ .expect("anonymous write");+ assert_eq!(anon.author_username, None, "anonymous write yields None");++ let scoped = store+ .reader+ .list_audit_events(AuditLogFilter {+ workspace: Some("default".to_string()),+ project: Some("scratch".to_string()),+ ..AuditLogFilter::default()+ })+ .await+ .unwrap();+ assert!(!scoped.is_empty());+ assert!(scoped.iter().all(|e| {+ e.workspace.as_deref() == Some("default") && e.project.as_deref() == Some("scratch")+ }));+ assert!(+ scoped+ .iter()+ .all(|e| e.page_path.as_deref() != Some("notes/elsewhere.md")),+ "scope filter must not leak the other workspace"+ );++ let supersedes = store+ .reader+ .list_audit_events(AuditLogFilter {+ op: Some("supersede_page".to_string()),+ ..AuditLogFilter::default()+ })+ .await+ .unwrap();+ assert_eq!(supersedes.len(), 1);+ assert_eq!(supersedes[0].op, "supersede_page");++ let first = store+ .reader+ .list_audit_events(AuditLogFilter {+ limit: 2,+ ..AuditLogFilter::default()+ })+ .await+ .unwrap();+ assert_eq!(first.len(), 2);+ let next = store+ .reader+ .list_audit_events(AuditLogFilter {+ before_id: Some(first[1].id),+ limit: 200,+ ..AuditLogFilter::default()+ })+ .await+ .unwrap();+ assert!(!next.is_empty());+ let first_ids: Vec<i64> = first.iter().map(|e| e.id).collect();+ assert!(+ next.iter()+ .all(|e| e.id < first[1].id && !first_ids.contains(&e.id)),+ "keyset must not skip or duplicate the first page"+ );++ let clamped_low = store+ .reader+ .list_audit_events(AuditLogFilter {+ limit: 0,+ ..AuditLogFilter::default()+ })+ .await+ .unwrap();+ assert_eq!(clamped_low.len(), 1, "limit 0 clamps to 1");++ let clamped_high = store+ .reader+ .list_audit_events(AuditLogFilter {+ limit: 10_000,+ ..AuditLogFilter::default()+ })+ .await+ .unwrap();+ assert_eq!(+ clamped_high.len(),+ all.len(),+ "limit 10000 clamps to 200 but we have fewer rows"+ );+ assert!(clamped_high.len() <= 200);+}