Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors
Rust
cli: add list-projects, a plain read-only project listing
Maxsuel Einsteinfd23a649ca82
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 4ce62d08..4dba9acc 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0## [Unreleased]+### Added+- Added `ai-memory list-projects [--workspace] [--json]`: a plain, scriptable+ listing of every workspace/project pair the server knows about, sorted by+ workspace then project. Previously the only way to see this from outside+ an interactive `show` session was to call `GET /api/v1/projects` directly.+## [2.5.2] - 2026-10-01### Addeddiff --git a/crates/ai-memory-cli/src/cli.rs b/crates/ai-memory-cli/src/cli.rsindex d2705980..78807c63 100644--- a/crates/ai-memory-cli/src/cli.rs+++ b/crates/ai-memory-cli/src/cli.rs@@ -33,6 +33,11 @@ pub enum Command {Init(InitArgs),/// Print runtime status (counts, paths, version).Status(StatusArgs),+ /// List every workspace/project pair the server knows about (plain,+ /// scriptable output — the read-only equivalent of hitting+ /// `GET /api/v1/projects` directly, which was previously the only way to+ /// see this from outside an interactive `show` session).+ ListProjects(ListProjectsArgs),/// Check capture coverage: compare local harness session stores for this/// project against what the server captured, and warn when a harness ran/// here recently but has no captured sessions (its hook is likely missing).@@ -1712,6 +1717,17 @@ pub struct StatusArgs {pub json: bool,}+/// Arguments for `list-projects`.+#[derive(Debug, Args)]+pub struct ListProjectsArgs {+ /// Only list projects in this workspace. Omit to list every workspace.+ #[arg(long)]+ pub workspace: Option<String>,+ /// Emit JSON instead of a plain table.+ #[arg(long)]+ pub json: bool,+}+/// Arguments for `backfill`.#[derive(Debug, Args)]pub struct BackfillArgs {diff --git a/crates/ai-memory-cli/src/commands/list_projects.rs b/crates/ai-memory-cli/src/commands/list_projects.rsnew file mode 100644index 00000000..e39cbc34--- /dev/null+++ b/crates/ai-memory-cli/src/commands/list_projects.rs@@ -0,0 +1,161 @@+//! `ai-memory list-projects` — plain read-only listing of every+//! workspace/project pair the server knows about.+//!+//! Before this command, the only way to see this from the client was to hit+//! `GET /api/v1/projects` directly with curl/Invoke-RestMethod. `show`'s own+//! use of that endpoint is folded into an interactive picker and silently+//! falls back to client-local scan results when the server call fails, so it+//! was never a plain, scriptable listing on its own.++use anyhow::Result;++use crate::cli::ListProjectsArgs;+use crate::commands::show::ProjectRow;+use crate::config::Config;+use crate::http_client::{ServerEndpoint, get_json};++pub async fn run(config: &Config, args: ListProjectsArgs) -> Result<()> {+ let endpoint = ServerEndpoint::from_config_resolving_auth(config).await;+ let rows = fetch_sorted(&endpoint, args.workspace.as_deref()).await?;++ if args.json {+ println!("{}", serde_json::to_string_pretty(&rows)?);+ return Ok(());+ }++ print!("{}", render_human(&rows));+ Ok(())+}++async fn fetch_sorted(+ endpoint: &ServerEndpoint,+ workspace: Option<&str>,+) -> Result<Vec<ProjectRow>> {+ let query = workspace+ .filter(|value| !value.is_empty())+ .map_or_else(Vec::new, |workspace| vec![("workspace", workspace)]);+ let mut rows: Vec<ProjectRow> = get_json(endpoint, "/api/v1/projects", &query).await?;+ rows.sort_by(|a, b| {+ a.workspace_name+ .cmp(&b.workspace_name)+ .then_with(|| a.project_name.cmp(&b.project_name))+ });+ Ok(rows)+}++fn render_human(rows: &[ProjectRow]) -> String {+ if rows.is_empty() {+ return "No projects found.\n".to_owned();+ }++ let workspace_width = rows+ .iter()+ .map(|row| row.workspace_name.len())+ .max()+ .unwrap_or(0)+ .max("WORKSPACE".len());+ let project_width = rows+ .iter()+ .map(|row| row.project_name.len())+ .max()+ .unwrap_or(0)+ .max("PROJECT".len());++ let mut out = format!(+ "{:workspace_width$} {:project_width$} {:>6} LAST UPDATED\n",+ "WORKSPACE", "PROJECT", "PAGES"+ );+ for row in rows {+ out += &format!(+ "{:workspace_width$} {:project_width$} {:>6} {}\n",+ row.workspace_name,+ row.project_name,+ row.page_count,+ row.last_updated.as_deref().unwrap_or("-")+ );+ }+ out+}++#[cfg(test)]+mod tests {+ use super::*;++ fn row(workspace: &str, project: &str, pages: u64, last_updated: Option<&str>) -> ProjectRow {+ ProjectRow {+ workspace_name: workspace.to_owned(),+ project_name: project.to_owned(),+ page_count: pages,+ last_updated: last_updated.map(str::to_owned),+ }+ }++ #[test]+ fn render_human_reports_an_empty_server() {+ assert_eq!(render_human(&[]), "No projects found.\n");+ }++ #[test]+ fn render_human_prints_a_header_and_one_row_per_project() {+ let rows = vec![row("default", "acme-api", 12, Some("2026-09-30T00:00:00Z"))];+ let out = render_human(&rows);+ assert!(out.starts_with("WORKSPACE"), "{out}");+ assert!(out.contains("default"), "{out}");+ assert!(out.contains("acme-api"), "{out}");+ assert!(out.contains("12"), "{out}");+ assert!(out.contains("2026-09-30T00:00:00Z"), "{out}");+ }++ #[test]+ fn render_human_shows_a_dash_for_a_project_with_no_pages_yet() {+ let rows = vec![row("default", "empty-project", 0, None)];+ let out = render_human(&rows);+ let data_line = out.lines().nth(1).expect("one data line");+ assert!(data_line.contains("empty-project"), "{data_line}");+ assert!(data_line.trim_end().ends_with('-'), "{data_line}");+ }++ #[test]+ fn render_human_columns_widen_to_the_longest_name() {+ let rows = vec![+ row("default", "a", 1, None),+ row(+ "a-much-longer-workspace-name",+ "a-much-longer-project-name",+ 2,+ None,+ ),+ ];+ let out = render_human(&rows);+ // Every data line must be at least as wide as the longest name in its+ // column, i.e. the short names are padded, not truncated.+ for line in out.lines().skip(1) {+ assert!(+ line.len() >= "a-much-longer-workspace-name".len(),+ "line not padded to the widest workspace name: {line:?}"+ );+ }+ }++ #[test]+ fn sort_orders_by_workspace_then_project() {+ let mut rows = [+ row("default", "zeta", 1, None),+ row("alpha", "zeta", 1, None),+ row("default", "alpha", 1, None),+ ];+ rows.sort_by(|a, b| {+ a.workspace_name+ .cmp(&b.workspace_name)+ .then_with(|| a.project_name.cmp(&b.project_name))+ });+ let ordered: Vec<(&str, &str)> = rows+ .iter()+ .map(|r| (r.workspace_name.as_str(), r.project_name.as_str()))+ .collect();+ assert_eq!(+ ordered,+ vec![("alpha", "zeta"), ("default", "alpha"), ("default", "zeta")]+ );+ }+}diff --git a/crates/ai-memory-cli/src/commands/mod.rs b/crates/ai-memory-cli/src/commands/mod.rsindex fd53a4d0..40de2e28 100644--- a/crates/ai-memory-cli/src/commands/mod.rs+++ b/crates/ai-memory-cli/src/commands/mod.rs@@ -52,6 +52,7 @@ pub mod install_instructions;pub mod install_mcp;pub mod install_skills;pub mod lint;+pub mod list_projects;pub mod llm_test;pub mod mcp_bridge;pub mod message;diff --git a/crates/ai-memory-cli/src/commands/show.rs b/crates/ai-memory-cli/src/commands/show.rsindex e64b664b..eed58467 100644--- a/crates/ai-memory-cli/src/commands/show.rs+++ b/crates/ai-memory-cli/src/commands/show.rs@@ -50,12 +50,12 @@ const SKIPPED_DIRS: [&str; 8] = [const MAX_SCAN_ENTRIES: usize = 4096;const NEW_PROJECT_LABEL: &str = "+ New project";-#[derive(Debug, Clone, Deserialize)]-struct ProjectRow {- workspace_name: String,- project_name: String,- page_count: u64,- last_updated: Option<String>,+#[derive(Debug, Clone, Serialize, Deserialize)]+pub(crate) struct ProjectRow {+ pub(crate) workspace_name: String,+ pub(crate) project_name: String,+ pub(crate) page_count: u64,+ pub(crate) last_updated: Option<String>,}#[derive(Debug, Clone, Copy, PartialEq, Eq)]diff --git a/crates/ai-memory-cli/src/lib.rs b/crates/ai-memory-cli/src/lib.rsindex 972abfeb..960def97 100644--- a/crates/ai-memory-cli/src/lib.rs+++ b/crates/ai-memory-cli/src/lib.rs@@ -86,6 +86,7 @@ pub async fn run() -> Result<()> {match command {Command::Init(args) => commands::init::run(&config, args, config_path.as_deref()),Command::Status(args) => commands::status::run(&config, args).await,+ Command::ListProjects(args) => commands::list_projects::run(&config, args).await,Command::Doctor(args) => commands::doctor::run(&config, args).await,Command::Backfill(args) => commands::backfill::run(&config, args).await,Command::RepairBackfillTimestamps(args) => {diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.mdindex 05fd1c36..ee36d490 100644--- a/docs/ARCHITECTURE.md+++ b/docs/ARCHITECTURE.md@@ -544,27 +544,27 @@ wiki browser and JSON APIs stay behind the route class above.## CLI subcommand surface```-init status run-show continue resume-workstreams rename-workstream workstream-search-audit-contamination search read-page-write-page delete-page serve-reset backup restore-reindex install-hooks hook-install-mcp commit checkpoints-restore-page llm-test forget-sweep-lint curator auto-improve-report-auto-improve finalize-session pending-writes-embed generate-auth-token setup-agent-bootstrap install-instructions install-skills-reorg purge-project rename-project-move-project move-session uninstall-upgrade auth user-completions handoffs purge-session-compact api-key export-okf-message doctor backfill-project reclaim-ledger-versions repair-backfill-timestamps-server+init status list-projects+run show continue+resume workstreams rename-workstream+workstream-search audit-contamination search+read-page write-page delete-page+serve reset backup+restore reindex install-hooks+hook install-mcp commit+checkpoints restore-page llm-test+forget-sweep lint curator+auto-improve-report auto-improve finalize-session+pending-writes embed generate-auth-token+setup-agent bootstrap install-instructions+install-skills reorg purge-project+rename-project move-project move-session+uninstall upgrade auth+user completions handoffs+purge-session compact api-key+export-okf message doctor+backfill project reclaim-ledger-versions+repair-backfill-timestamps server```Run `ai-memory --help` for the full tree.diff --git a/docs/cookbook.md b/docs/cookbook.mdindex 69e3b7cc..a6c31c94 100644--- a/docs/cookbook.md+++ b/docs/cookbook.md@@ -289,6 +289,7 @@ ai-memory run <harness> # launch a harness, hooks + MCP auto-wiredai-memory continue # resume the newest managed checkoutai-memory workstreams # list this checkout's managed workstreamsai-memory status # counts, paths, health+ai-memory list-projects # every workspace/project the server knows aboutai-memory doctor # is every harness that ran here captured?ai-memory backfill # import prior local history into an empty storeai-memory write-page … # save a durable page