Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors
Rust
admin: audit cleanup — dry-run, status codes, dedupe handlers
AkitaOnRails89e3e96726cf
diff --git a/crates/ai-memory-cli/src/cli.rs b/crates/ai-memory-cli/src/cli.rsindex e6d45a9a..8d021ace 100644--- a/crates/ai-memory-cli/src/cli.rs+++ b/crates/ai-memory-cli/src/cli.rs@@ -116,10 +116,10 @@ pub struct InstallInstructionsArgs {/// Arguments for `bootstrap`.#[derive(Debug, Args)]pub struct BootstrapArgs {- /// Path of the project repo whose history we should ingest.- /// Defaults to `git rev-parse --show-toplevel` resolved from the- /// current directory (so running bootstrap from any subdir of the- /// project works).+ /// Path on this client whose history to collect (server never+ /// sees this path). Defaults to `git rev-parse --show-toplevel`+ /// resolved from the current directory (so running bootstrap from+ /// any subdir of the project works).#[arg(long)]pub repo_path: Option<PathBuf>,/// Workspace + project labels stamped on the generated pages.@@ -375,6 +375,12 @@ pub struct ForgetSweepArgs {/// Report what would be evicted without actually mutating.#[arg(long)]pub dry_run: bool,+ /// Workspace name (auto-created if absent).+ #[arg(long, default_value = "default")]+ pub workspace: String,+ /// Project name within the workspace (auto-created if absent).+ #[arg(long, default_value = "scratch")]+ pub project: String,}/// Arguments for `lint`.diff --git a/crates/ai-memory-cli/src/commands/embed.rs b/crates/ai-memory-cli/src/commands/embed.rsindex 5a9847e5..eb141bb2 100644--- a/crates/ai-memory-cli/src/commands/embed.rs+++ b/crates/ai-memory-cli/src/commands/embed.rs@@ -13,10 +13,15 @@ struct EmbedRequest {workspace: String,project: String,reembed: bool,+ dry_run: bool,}/// Run the `embed` subcommand.///+/// Sends the request to the server over HTTP and prints the JSON+/// response. In dry-run mode the server counts pages that would be+/// embedded without calling the embedder or writing anything.+////// # Errors/// Returns an error if the server is unreachable or returns a non-2xx/// response.@@ -31,9 +36,17 @@ pub async fn run(_config: &Config, args: EmbedArgs) -> Result<()> {// The CLI flag was historically named `force`; the server// field is `reembed` — map them here.reembed: args.force,+ dry_run: args.dry_run,},).await?;- println!("{}", serde_json::to_string_pretty(&report)?);++ if args.dry_run {+ let would = report["would_embed"].as_u64().unwrap_or(0);+ let skipped = report["skipped"].as_u64().unwrap_or(0);+ println!("dry-run: would embed {would} page(s), {skipped} already up-to-date");+ } else {+ println!("{}", serde_json::to_string_pretty(&report)?);+ }Ok(())}diff --git a/crates/ai-memory-cli/src/commands/forget_sweep.rs b/crates/ai-memory-cli/src/commands/forget_sweep.rsindex b08c2404..afa42e3e 100644--- a/crates/ai-memory-cli/src/commands/forget_sweep.rs+++ b/crates/ai-memory-cli/src/commands/forget_sweep.rs@@ -17,6 +17,9 @@ struct ForgetSweepRequest {/// Run the `forget-sweep` subcommand.///+/// Sends the retention-sweep request to the server over HTTP and+/// prints the JSON response.+////// # Errors/// Returns an error if the server is unreachable or returns a non-2xx/// response.@@ -26,8 +29,8 @@ pub async fn run(_config: &Config, args: ForgetSweepArgs) -> Result<()> {&endpoint,"/admin/forget-sweep",&ForgetSweepRequest {- workspace: "default".to_string(),- project: "scratch".to_string(),+ workspace: args.workspace,+ project: args.project,dry_run: args.dry_run,},)diff --git a/crates/ai-memory-cli/src/http_client.rs b/crates/ai-memory-cli/src/http_client.rsindex d61dda82..225d7cbb 100644--- a/crates/ai-memory-cli/src/http_client.rs+++ b/crates/ai-memory-cli/src/http_client.rs@@ -34,15 +34,26 @@ impl ServerEndpoint {/// loopback, the token defaults to unset.#[must_use]pub fn from_env() -> Self {- let url = std::env::var("AI_MEMORY_SERVER_URL")- .ok()+ Self::from_pair(+ std::env::var("AI_MEMORY_SERVER_URL").ok(),+ std::env::var("AI_MEMORY_AUTH_TOKEN").ok(),+ )+ }++ /// Build from an explicit URL + token pair (useful for tests that+ /// cannot safely mutate the process environment).+ ///+ /// `url` defaults to `http://127.0.0.1:49374` when `None` or empty;+ /// trailing slashes are stripped. `token` is treated as absent when+ /// `None` or empty.+ #[must_use]+ pub(crate) fn from_pair(url: Option<String>, token: Option<String>) -> Self {+ let url = url.filter(|s| !s.is_empty()).unwrap_or_else(|| "http://127.0.0.1:49374".to_string()).trim_end_matches('/').to_string();- let auth_token = std::env::var("AI_MEMORY_AUTH_TOKEN")- .ok()- .filter(|s| !s.is_empty());+ let auth_token = token.filter(|s| !s.is_empty());Self { url, auth_token }}@@ -111,3 +122,86 @@ pub async fn post_json<B: Serialize, T: DeserializeOwned>(.await.with_context(|| format!("parsing JSON body from POST {url}"))}++#[cfg(test)]+mod tests {+ use super::*;++ // ----------------------------------------------------------------+ // ServerEndpoint::from_pair+ // ----------------------------------------------------------------++ #[test]+ fn from_pair_defaults_to_loopback_when_none() {+ let ep = ServerEndpoint::from_pair(None, None);+ assert_eq!(ep.url, "http://127.0.0.1:49374");+ assert!(ep.auth_token.is_none());+ }++ #[test]+ fn from_pair_defaults_to_loopback_when_empty() {+ let ep = ServerEndpoint::from_pair(Some(String::new()), None);+ assert_eq!(ep.url, "http://127.0.0.1:49374");+ }++ #[test]+ fn from_pair_strips_trailing_slash() {+ let ep = ServerEndpoint::from_pair(Some("http://10.0.0.1:8080/".to_string()), None);+ assert_eq!(ep.url, "http://10.0.0.1:8080");+ }++ #[test]+ fn from_pair_strips_multiple_trailing_slashes() {+ let ep = ServerEndpoint::from_pair(Some("http://10.0.0.1:8080///".to_string()), None);+ assert_eq!(ep.url, "http://10.0.0.1:8080");+ }++ #[test]+ fn from_pair_empty_token_treated_as_none() {+ let ep = ServerEndpoint::from_pair(None, Some(String::new()));+ assert!(ep.auth_token.is_none());+ }++ #[test]+ fn from_pair_non_empty_token_preserved() {+ let ep = ServerEndpoint::from_pair(None, Some("secret".to_string()));+ assert_eq!(ep.auth_token.as_deref(), Some("secret"));+ }++ // ----------------------------------------------------------------+ // ServerEndpoint::authenticate+ // ----------------------------------------------------------------++ #[test]+ fn authenticate_no_token_leaves_request_unchanged() {+ let ep = ServerEndpoint::from_pair(None, None);+ let client = reqwest::Client::new();+ // Build a request, authenticate it, then build to inspect.+ let req = ep+ .authenticate(client.get("http://localhost"))+ .build()+ .unwrap();+ // No Authorization header should be present.+ assert!(+ req.headers().get("authorization").is_none(),+ "no Authorization header expected"+ );+ }++ #[test]+ fn authenticate_with_token_sets_bearer_header() {+ let ep = ServerEndpoint::from_pair(None, Some("tok123".to_string()));+ let client = reqwest::Client::new();+ let req = ep+ .authenticate(client.get("http://localhost"))+ .build()+ .unwrap();+ let auth = req+ .headers()+ .get("authorization")+ .expect("Authorization header must be set")+ .to_str()+ .unwrap();+ assert_eq!(auth, "Bearer tok123");+ }+}diff --git a/crates/ai-memory-consolidate/src/bootstrap.rs b/crates/ai-memory-consolidate/src/bootstrap.rsindex aefdadc7..c6665eb8 100644--- a/crates/ai-memory-consolidate/src/bootstrap.rs+++ b/crates/ai-memory-consolidate/src/bootstrap.rs@@ -227,7 +227,10 @@ pub struct BootstrapOutcome {/// to concrete values.#[derive(Debug, Clone)]pub struct BootstrapConfig {- /// Project repo root. Sources are read relative to here.+ /// Project repo root on the client's filesystem. Used by+ /// [`Bootstrap::run`]'s client-side [`collect_sources`] call.+ /// Ignored by [`Bootstrap::process_sources`] — sources arrive+ /// pre-collected on the server-side path.pub repo_path: PathBuf,/// Workspace identifier the generated pages belong to.pub workspace_id: WorkspaceId,diff --git a/crates/ai-memory-mcp/src/admin.rs b/crates/ai-memory-mcp/src/admin.rsindex 5b01a833..ddb787d8 100644--- a/crates/ai-memory-mcp/src/admin.rs+++ b/crates/ai-memory-mcp/src/admin.rs@@ -179,12 +179,44 @@ async fn handle_search(Json(serde_json::to_value(&hits).unwrap_or_else(|_| serde_json::json!([]))),),Err(e) => (- StatusCode::UNPROCESSABLE_ENTITY,+ StatusCode::INTERNAL_SERVER_ERROR,Json(serde_json::json!({ "error": e.to_string() })),),}}+// ---------------------------------------------------------------------+// Internal helpers+// ---------------------------------------------------------------------++/// Build a 500 response carrying the given message.+fn internal_err(msg: impl Into<String>) -> (StatusCode, Json<serde_json::Value>) {+ (+ StatusCode::INTERNAL_SERVER_ERROR,+ Json(serde_json::json!({ "error": msg.into() })),+ )+}++/// Resolve workspace + project IDs, creating them if absent. Returns+/// either the IDs or a ready-to-return error response.+async fn resolve_ws_proj(+ state: &AdminState,+ workspace: &str,+ project: &str,+) -> Result<(WorkspaceId, ProjectId), (StatusCode, Json<serde_json::Value>)> {+ let ws = state+ .writer+ .get_or_create_workspace(workspace.to_string())+ .await+ .map_err(|e| internal_err(format!("workspace: {e}")))?;+ let proj = state+ .writer+ .get_or_create_project(ws, project.to_string(), None)+ .await+ .map_err(|e| internal_err(format!("project: {e}")))?;+ Ok((ws, proj))+}+// ---------------------------------------------------------------------// bootstrap// ---------------------------------------------------------------------@@ -192,41 +224,20 @@ async fn handle_search(async fn handle_bootstrap(State(state): State<Arc<AdminState>>,Json(req): Json<BootstrapRequest>,-) -> impl IntoResponse {+) -> Result<impl IntoResponse, (StatusCode, Json<serde_json::Value>)> {// LLM is required only for live runs. Dry-runs never call the LLM// so we handle them directly here without constructing Bootstrap.if !req.dry_run && state.llm.is_none() {- return (+ return Err((StatusCode::SERVICE_UNAVAILABLE,Json(serde_json::json!({"error": "LLM provider not configured on server"})),- );+ ));}// Resolve workspace + project — create if absent.- let ws = match state.writer.get_or_create_workspace(req.workspace).await {- Ok(id) => id,- Err(e) => {- return (- StatusCode::INTERNAL_SERVER_ERROR,- Json(serde_json::json!({ "error": format!("workspace: {e}") })),- );- }- };- let proj = match state- .writer- .get_or_create_project(ws, req.project, None)- .await- {- Ok(id) => id,- Err(e) => {- return (- StatusCode::INTERNAL_SERVER_ERROR,- Json(serde_json::json!({ "error": format!("project: {e}") })),- );- }- };+ let (ws, proj) = resolve_ws_proj(&state, &req.workspace, &req.project).await?;// Dry-run with no LLM: compute the budget-pruned source counts and// return early without constructing Bootstrap (which requires an LLM).@@ -266,31 +277,49 @@ async fn handle_bootstrap(};match bootstrap.process_sources(&cfg, req.sources).await {- Ok(outcome) => (+ Ok(outcome) => Ok((StatusCode::OK,Json(serde_json::to_value(&outcome).unwrap_or_else(|_| serde_json::json!({}))),- ),- Err(e) => (- StatusCode::UNPROCESSABLE_ENTITY,- Json(serde_json::json!({ "error": e.to_string() })),- ),+ )),+ Err(e) => Err(bootstrap_error_response(e)),}}+/// Build a dry-run [`BootstrapOutcome`] without an LLM by applying the+/// same budget-pruning logic that `Bootstrap::process_sources` would use.+/// Map a [`BootstrapError`] to the appropriate HTTP status code.+///+/// - `NoSources` / `AlreadyBootstrapped` → 422 (validation failures).+/// - `Llm` → 502 (upstream provider failure).+/// - Everything else → 500 (unexpected server-side error).+fn bootstrap_error_response(+ e: ai_memory_consolidate::BootstrapError,+) -> (StatusCode, Json<serde_json::Value>) {+ use ai_memory_consolidate::BootstrapError;+ let status = match &e {+ BootstrapError::NoSources | BootstrapError::AlreadyBootstrapped => {+ StatusCode::UNPROCESSABLE_ENTITY+ }+ BootstrapError::Llm(_) => StatusCode::BAD_GATEWAY,+ _ => StatusCode::INTERNAL_SERVER_ERROR,+ };+ (status, Json(serde_json::json!({ "error": e.to_string() })))+}+/// Build a dry-run [`BootstrapOutcome`] without an LLM by applying the/// same budget-pruning logic that `Bootstrap::process_sources` would use.fn dry_run_outcome(sources: Vec<BootstrapSource>,max_input_tokens: usize,-) -> (StatusCode, Json<serde_json::Value>) {+) -> Result<(StatusCode, Json<serde_json::Value>), (StatusCode, Json<serde_json::Value>)> {use ai_memory_consolidate::BootstrapError;if sources.is_empty() {- return (+ return Err((StatusCode::UNPROCESSABLE_ENTITY,Json(serde_json::json!({"error": BootstrapError::NoSources.to_string()})),- );+ ));}// Mirror the prune logic: sort by drop_priority desc, drop until// under budget. We replicate the constants here rather than@@ -324,10 +353,10 @@ fn dry_run_outcome(rationale: "(dry-run; LLM not invoked)".to_string(),dry_run: true,};- (+ Ok((StatusCode::OK,Json(serde_json::to_value(&outcome).unwrap_or_else(|_| serde_json::json!({}))),- )+ ))}// ---------------------------------------------------------------------@@ -567,31 +596,10 @@ fn default_project() -> String {async fn handle_lint(State(state): State<Arc<AdminState>>,Json(req): Json<LintRequest>,-) -> impl IntoResponse {- let ws = match state.writer.get_or_create_workspace(req.workspace).await {- Ok(id) => id,- Err(e) => {- return (- StatusCode::INTERNAL_SERVER_ERROR,- Json(serde_json::json!({ "error": format!("workspace: {e}") })),- );- }- };- let proj = match state- .writer- .get_or_create_project(ws, req.project, None)- .await- {- Ok(id) => id,- Err(e) => {- return (- StatusCode::INTERNAL_SERVER_ERROR,- Json(serde_json::json!({ "error": format!("project: {e}") })),- );- }- };+) -> Result<impl IntoResponse, (StatusCode, Json<serde_json::Value>)> {+ let (ws, proj) = resolve_ws_proj(&state, &req.workspace, &req.project).await?;- match run_lint(+ run_lint(&state.reader,&state.wiki,state.llm.as_ref(),@@ -600,16 +608,13 @@ async fn handle_lint(req.dry_run,).await- {- Ok(report) => (+ .map(|report| {+ (StatusCode::OK,Json(serde_json::to_value(&report).unwrap_or_else(|_| serde_json::json!({}))),- ),- Err(e) => (- StatusCode::INTERNAL_SERVER_ERROR,- Json(serde_json::json!({ "error": e.to_string() })),- ),- }+ )+ })+ .map_err(|e| internal_err(e.to_string()))}// ---------------------------------------------------------------------@@ -633,31 +638,10 @@ struct ForgetSweepRequest {async fn handle_forget_sweep(State(state): State<Arc<AdminState>>,Json(req): Json<ForgetSweepRequest>,-) -> impl IntoResponse {- let ws = match state.writer.get_or_create_workspace(req.workspace).await {- Ok(id) => id,- Err(e) => {- return (- StatusCode::INTERNAL_SERVER_ERROR,- Json(serde_json::json!({ "error": format!("workspace: {e}") })),- );- }- };- let proj = match state- .writer- .get_or_create_project(ws, req.project, None)- .await- {- Ok(id) => id,- Err(e) => {- return (- StatusCode::INTERNAL_SERVER_ERROR,- Json(serde_json::json!({ "error": format!("project: {e}") })),- );- }- };+) -> Result<impl IntoResponse, (StatusCode, Json<serde_json::Value>)> {+ let (ws, proj) = resolve_ws_proj(&state, &req.workspace, &req.project).await?;- match run_sweep(+ run_sweep(&state.reader,&state.writer,ws,@@ -666,16 +650,13 @@ async fn handle_forget_sweep(req.dry_run,).await- {- Ok(report) => (+ .map(|report| {+ (StatusCode::OK,Json(serde_json::to_value(&report).unwrap_or_else(|_| serde_json::json!({}))),- ),- Err(e) => (- StatusCode::INTERNAL_SERVER_ERROR,- Json(serde_json::json!({ "error": e.to_string() })),- ),- }+ )+ })+ .map_err(|e| internal_err(e.to_string()))}// ---------------------------------------------------------------------@@ -695,17 +676,24 @@ struct EmbedRequest {/// have one matching the current (provider, model, dim).#[serde(default)]reembed: bool,+ /// When true, count pages that would be embedded/skipped without+ /// calling the embedder or writing anything.+ #[serde(default)]+ dry_run: bool,}/// Summary response from `POST /admin/embed`.#[derive(Debug, Serialize)]pub struct EmbedReport {- /// Total pages that were embedded (or would be, in dry-run mode).+ /// Pages that were actually embedded (zero in dry-run).pub embedded: usize,/// Pages skipped because a matching embedding already existed.pub skipped: usize,/// Pages that failed to embed (read error or provider error).pub failed: usize,+ /// Pages that would be embedded in a live run (only meaningful+ /// when `dry_run` was requested).+ pub would_embed: usize,/// Provider name.pub provider: String,/// Model identifier.@@ -717,16 +705,16 @@ pub struct EmbedReport {async fn handle_embed(State(state): State<Arc<AdminState>>,Json(req): Json<EmbedRequest>,-) -> impl IntoResponse {+) -> Result<impl IntoResponse, (StatusCode, Json<serde_json::Value>)> {let embedder = match state.embedder.clone() {Some(e) => e,None => {- return (+ return Err((StatusCode::SERVICE_UNAVAILABLE,Json(serde_json::json!({"error": "embedder not configured on server"})),- );+ ));}};@@ -734,67 +722,42 @@ async fn handle_embed(let model = embedder.model().to_string();let dim = embedder.dim();- let ws = match state.writer.get_or_create_workspace(req.workspace).await {- Ok(id) => id,- Err(e) => {- return (- StatusCode::INTERNAL_SERVER_ERROR,- Json(serde_json::json!({ "error": format!("workspace: {e}") })),- );- }- };- let proj = match state- .writer- .get_or_create_project(ws, req.project, None)- .await- {- Ok(id) => id,- Err(e) => {- return (- StatusCode::INTERNAL_SERVER_ERROR,- Json(serde_json::json!({ "error": format!("project: {e}") })),- );- }- };+ let (ws, proj) = resolve_ws_proj(&state, &req.workspace, &req.project).await?;- let candidates = match state.reader.decay_candidates(ws, proj).await {- Ok(c) => c,- Err(e) => {- return (- StatusCode::INTERNAL_SERVER_ERROR,- Json(serde_json::json!({ "error": e.to_string() })),- );- }- };+ let candidates = state+ .reader+ .decay_candidates(ws, proj)+ .await+ .map_err(|e| internal_err(e.to_string()))?;// Build the set of page ids that already have a matching embedding.let already: std::collections::HashSet<_> = if req.reembed {std::collections::HashSet::new()} else {- match state+ state.reader.load_embeddings(ws, proj, provider.clone(), model.clone(), dim).await- {- Ok(embeddings) => embeddings.into_iter().map(|s| s.id).collect(),- Err(e) => {- return (- StatusCode::INTERNAL_SERVER_ERROR,- Json(serde_json::json!({ "error": e.to_string() })),- );- }- }+ .map_err(|e| internal_err(e.to_string()))?+ .into_iter()+ .map(|s| s.id)+ .collect()};let mut embedded = 0_usize;let mut skipped = 0_usize;let mut failed = 0_usize;+ let mut would_embed = 0_usize;for cand in candidates {if !req.reembed && already.contains(&cand.id) {skipped += 1;continue;}+ if req.dry_run {+ would_embed += 1;+ continue;+ }let md = match state.wiki.read_page(&cand.path) {Ok(m) => m,Err(e) => {@@ -828,14 +791,15 @@ async fn handle_embed(embedded,skipped,failed,+ would_embed,provider,model,dim,};- (+ Ok((StatusCode::OK,Json(serde_json::to_value(&report).unwrap_or_else(|_| serde_json::json!({}))),- )+ ))}// ---------------------------------------------------------------------diff --git a/crates/ai-memory-mcp/tests/admin_phase3.rs b/crates/ai-memory-mcp/tests/admin_phase3.rsindex 48b33407..b4a34999 100644--- a/crates/ai-memory-mcp/tests/admin_phase3.rs+++ b/crates/ai-memory-mcp/tests/admin_phase3.rs@@ -13,6 +13,7 @@ use ai_memory_core::{use ai_memory_mcp::{AdminState, admin_router};use ai_memory_store::{DecayParams, Store};use ai_memory_wiki::Wiki;+use ai_memory_wiki::WritePageRequest;use axum::body::Body;use axum::http::{Request, StatusCode};use serde_json::json;@@ -341,3 +342,50 @@ async fn commit_clean_wiki_returns_not_committed() {// (first commit of an empty tree). Both are acceptable; we just// verify the route doesn't panic.}++#[tokio::test]+async fn commit_with_new_page_returns_committed_true_and_40char_oid() {+ let tmp = TempDir::new().unwrap();+ let (state, store) = make_state(&tmp).await;++ // Write a page through the wiki so it lands on disk (git can see it).+ let ws = store+ .writer+ .get_or_create_workspace("default")+ .await+ .unwrap();+ let proj = store+ .writer+ .get_or_create_project(ws, "scratch", None)+ .await+ .unwrap();+ state+ .wiki+ .write_page(WritePageRequest {+ workspace_id: ws,+ project_id: proj,+ path: PagePath::new("notes/commit-test.md").unwrap(),+ frontmatter: serde_json::json!({"title": "Commit test", "tier": "semantic"}),+ body: "Content for the commit test.".into(),+ tier: Tier::Semantic,+ pinned: false,+ title: Some("Commit test".into()),+ })+ .await+ .unwrap();++ let resp = post(state, "/admin/commit", json!({ "message": "test commit" })).await;+ assert_eq!(resp.status(), StatusCode::OK);++ let body = body_json(resp).await;+ assert!(+ body["committed"].as_bool().unwrap_or(false),+ "expected committed=true after writing a page: {body}"+ );+ let oid = body["oid"].as_str().expect("oid field must be present");+ assert_eq!(oid.len(), 40, "oid must be a 40-char hex SHA: {oid}");+ assert!(+ oid.chars().all(|c| c.is_ascii_hexdigit()),+ "oid must be all hex digits: {oid}"+ );+}