Skip to content

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.md
index 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
### Added
diff --git a/crates/ai-memory-cli/src/cli.rs b/crates/ai-memory-cli/src/cli.rs
index 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.rs
new file mode 100644
index 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.rs
index 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.rs
index 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.rs
index 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.md
index 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.md
index 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-wired
ai-memory continue # resume the newest managed checkout
ai-memory workstreams # list this checkout's managed workstreams
ai-memory status # counts, paths, health
+ai-memory list-projects # every workspace/project the server knows about
ai-memory doctor # is every harness that ran here captured?
ai-memory backfill # import prior local history into an empty store
ai-memory write-page … # save a durable page