Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors
Rust
feat(okf): export-okf command streaming a validated bundle tarball
AkitaOnRails4d4eb6a659de
diff --git a/crates/ai-memory-cli/src/cli.rs b/crates/ai-memory-cli/src/cli.rsindex 5fb97d91..9eb746ea 100644--- a/crates/ai-memory-cli/src/cli.rs+++ b/crates/ai-memory-cli/src/cli.rs@@ -86,6 +86,8 @@ pub enum Command {Compact(CompactArgs),/// Snapshot wiki/, db/, and config.toml into a gzipped tarball.Backup(BackupArgs),+ /// Export one project's wiki as an OKF v0.2 bundle tarball.+ ExportOkf(ExportOkfArgs),/// Restore a backup tarball into the data directory.Restore(RestoreArgs),/// Rebuild the SQLite index from the wiki/ markdown (the "DB is@@ -1295,6 +1297,20 @@ pub struct BackupArgs {pub to: PathBuf,}+/// Arguments for `export-okf`.+#[derive(Debug, Args)]+pub struct ExportOkfArgs {+ /// Workspace the project lives in.+ #[arg(long, default_value = "default")]+ pub workspace: String,+ /// Project to export.+ #[arg(long)]+ pub project: String,+ /// Destination tarball (`.tar.gz`).+ #[arg(long, short = 'o')]+ pub to: PathBuf,+}+/// Arguments for `restore`.#[derive(Debug, Args)]pub struct RestoreArgs {diff --git a/crates/ai-memory-cli/src/commands/export_okf.rs b/crates/ai-memory-cli/src/commands/export_okf.rsnew file mode 100644index 00000000..643271fa--- /dev/null+++ b/crates/ai-memory-cli/src/commands/export_okf.rs@@ -0,0 +1,51 @@+//! `ai-memory export-okf --project <name> --to <tarball>` — download one+//! project's wiki as an OKF v0.2 bundle from the server's+//! `/admin/export-okf` endpoint (docs/okf.md).+//!+//! The wiki files ARE the bundle (native conformance); the server ships+//! a validated copy with a freshly generated `index.md`. The reverse+//! direction needs no dedicated command: unpack a bundle's concept files+//! into a project's wiki directory and the watcher (or `reindex`)+//! ingests them.++use anyhow::{Context, Result};+use tracing::info;++use crate::cli::ExportOkfArgs;+use crate::commands::hook_capture::url_encode;+use crate::config::Config;+use crate::http_client::{ServerEndpoint, post_to_file};++/// Run the `export-okf` subcommand.+///+/// # Errors+/// Returns an error if the POST fails, the server rejects the export+/// (e.g. a non-conformant page pre-migration), or the file cannot be+/// written.+pub async fn run(config: &Config, args: ExportOkfArgs) -> Result<()> {+ let endpoint = ServerEndpoint::from_config_resolving_auth(config).await;+ if let Some(parent) = args.to.parent()+ && !parent.as_os_str().is_empty()+ {+ std::fs::create_dir_all(parent)+ .with_context(|| format!("creating parent dir for {}", args.to.display()))?;+ }+ let path = format!(+ "/admin/export-okf?workspace={}&project={}",+ url_encode(&args.workspace),+ url_encode(&args.project),+ );+ let size = post_to_file(&endpoint, &path, &args.to)+ .await+ .context("requesting OKF bundle from server")?;+ info!(+ dest = %args.to.display(),+ bytes = size,+ "OKF bundle exported"+ );+ println!(+ "exported OKF bundle to {} ({size} bytes)",+ args.to.display()+ );+ Ok(())+}diff --git a/crates/ai-memory-cli/src/commands/mod.rs b/crates/ai-memory-cli/src/commands/mod.rsindex a52de397..88cdbf50 100644--- a/crates/ai-memory-cli/src/commands/mod.rs+++ b/crates/ai-memory-cli/src/commands/mod.rs@@ -21,6 +21,7 @@ pub mod curator;pub mod data_purge;pub mod delete_page;pub mod embed;+pub mod export_okf;pub mod finalize_session;pub mod forget_sweep;pub mod generate_auth_token;diff --git a/crates/ai-memory-cli/src/main.rs b/crates/ai-memory-cli/src/main.rsindex 837196b4..04087421 100644--- a/crates/ai-memory-cli/src/main.rs+++ b/crates/ai-memory-cli/src/main.rs@@ -117,6 +117,7 @@ async fn main() -> Result<()> {Command::Reset(args) => commands::reset::run(&config, args),Command::Compact(args) => commands::compact::run(&config, args).await,Command::Backup(args) => commands::backup::run(&config, args).await,+ Command::ExportOkf(args) => commands::export_okf::run(&config, args).await,Command::Restore(args) => commands::restore::run(&config, args),Command::Reindex(args) => commands::reindex::run(&config, args).await,Command::InstallHooks(args) => commands::install_hooks::run(&config, args),diff --git a/crates/ai-memory-mcp/src/admin.rs b/crates/ai-memory-mcp/src/admin.rsindex 3c7b7f4e..daa94dc9 100644--- a/crates/ai-memory-mcp/src/admin.rs+++ b/crates/ai-memory-mcp/src/admin.rs@@ -578,6 +578,7 @@ pub fn admin_router_with_sweep_tuning(let state = Arc::new(state);let operational = Router::new().route("/admin/backup", post(handle_backup))+ .route("/admin/export-okf", post(handle_export_okf)).route("/admin/bootstrap", post(handle_bootstrap)).route("/admin/auto-improve", post(handle_auto_improve)).route(@@ -816,6 +817,135 @@ async fn build_backup_tarball_file(state: &AdminState) -> anyhow::Result<tokio::Ok(tokio::fs::File::from_std(tar_file))}+// ---------------------------------------------------------------------+// export-okf+// ---------------------------------------------------------------------++/// Query for `POST /admin/export-okf`: the one project bundle to export.+#[derive(Deserialize)]+struct ExportOkfQuery {+ workspace: String,+ project: String,+}++/// `POST /admin/export-okf?workspace=…&project=…` — stream the project+/// directory as an OKF v0.2 bundle tarball (docs/okf.md). The wiki files+/// ARE the bundle (native conformance), so this is a validated copy with+/// a freshly generated `index.md` (full listing + `okf_version`). Any+/// non-conformant page file fails the export rather than shipping a+/// bundle a strict reader would reject.+async fn handle_export_okf(+ State(state): State<Arc<AdminState>>,+ Query(q): Query<ExportOkfQuery>,+) -> Response {+ let ids = match lookup_ws_proj_no_create(&state, q.workspace.trim(), q.project.trim()).await {+ Ok(ids) => ids,+ Err((status, body)) => return (status, body).into_response(),+ };+ match build_okf_bundle_file(&state, ids.0, ids.1).await {+ Ok(file) => Response::builder()+ .status(StatusCode::OK)+ .header(header::CONTENT_TYPE, "application/gzip")+ .header(+ header::CONTENT_DISPOSITION,+ "attachment; filename=\"okf-bundle.tar.gz\"",+ )+ .body(Body::from_stream(ReaderStream::new(file)))+ .unwrap_or_else(|_| StatusCode::INTERNAL_SERVER_ERROR.into_response()),+ Err(e) => {+ warn!(error = %e, "okf export failed");+ let body = serde_json::to_vec(&serde_json::json!({ "error": e.to_string() }))+ .unwrap_or_default();+ Response::builder()+ .status(StatusCode::UNPROCESSABLE_ENTITY)+ .header(header::CONTENT_TYPE, "application/json")+ .body(Body::from(body))+ .unwrap_or_else(|_| StatusCode::INTERNAL_SERVER_ERROR.into_response())+ }+ }+}++async fn build_okf_bundle_file(+ state: &AdminState,+ ws: ai_memory_core::WorkspaceId,+ proj: ai_memory_core::ProjectId,+) -> anyhow::Result<tokio::fs::File> {+ let bundle_dir = state+ .data_dir+ .join("wiki")+ .join(ws.to_string())+ .join(proj.to_string());+ if !bundle_dir.is_dir() {+ anyhow::bail!("project has no wiki directory yet");+ }++ // Validate + collect: every non-reserved .md must be conformant.+ let mut files: Vec<std::path::PathBuf> = Vec::new();+ let mut families: Vec<String> = Vec::new();+ let mut stack = vec![bundle_dir.clone()];+ while let Some(dir) = stack.pop() {+ for entry in std::fs::read_dir(&dir)? {+ let entry = entry?;+ let path = entry.path();+ let ft = entry.file_type()?;+ if ft.is_dir() {+ if dir == bundle_dir {+ families.push(entry.file_name().to_string_lossy().into_owned());+ }+ stack.push(path);+ } else if ft.is_file() && path.extension().is_some_and(|e| e == "md") {+ let name = path.file_name().and_then(|n| n.to_str()).unwrap_or("");+ if name == "index.md" || name == "log.md" {+ continue; // regenerated / not adopted+ }+ let raw = std::fs::read_to_string(&path)?;+ let fm = ai_memory_wiki::parse(&raw)+ .map(|m| m.frontmatter)+ .unwrap_or_default();+ if !ai_memory_core::okf::is_conformant(&fm) {+ anyhow::bail!(+ "page {} is not OKF-conformant; run the server once to migrate \+ before exporting",+ path.strip_prefix(&bundle_dir).unwrap_or(&path).display()+ );+ }+ files.push(path);+ }+ }+ }++ let mut tar_file = tempfile::tempfile()?;+ {+ let encoder = GzEncoder::new(&mut tar_file, Compression::default());+ let mut tar = tar::Builder::new(encoder);+ tar.mode(tar::HeaderMode::Deterministic);+ tar.follow_symlinks(false);+ // Fresh bundle-root index.md: okf_version + full listing.+ families.sort();+ let listing: String = families+ .iter()+ .map(|f| format!("- [{f}/]({f}/)\n"))+ .collect();+ let index = format!(+ "---\nokf_version: \"0.2\"\n---\n\n# Bundle index\n\nConcept files live in these directories:\n\n{listing}"+ );+ let mut header = tar::Header::new_gnu();+ header.set_size(index.len() as u64);+ header.set_mode(0o644);+ header.set_cksum();+ tar.append_data(&mut header, "index.md", index.as_bytes())?;+ for path in files {+ let rel = path.strip_prefix(&bundle_dir).unwrap_or(&path);+ tar.append_path_with_name(&path, rel)?;+ }+ let encoder = tar.into_inner()?;+ encoder.finish()?;+ }+ tar_file.sync_data()?;+ tar_file.rewind()?;+ Ok(tokio::fs::File::from_std(tar_file))+}+// ---------------------------------------------------------------------// status// ---------------------------------------------------------------------@@ -7841,6 +7971,102 @@ mod tests {(tmp, router)}+ /// The exported tarball is a valid OKF v0.2 bundle: fresh index.md+ /// with okf_version, every concept file conformant (docs/okf.md).+ #[tokio::test]+ async fn export_okf_streams_a_conformant_bundle() {+ let (_tmp, router) = read_page_test_router();+ post_write_page(+ &router,+ "default",+ "scratch",+ "gotchas/build.md",+ "watch out",+ )+ .await;++ let resp = router+ .clone()+ .oneshot(+ Request::builder()+ .method("POST")+ .uri("/admin/export-okf?workspace=default&project=scratch")+ .body(Body::empty())+ .unwrap(),+ )+ .await+ .unwrap();+ assert_eq!(resp.status(), StatusCode::OK);+ let bytes = axum::body::to_bytes(resp.into_body(), usize::MAX)+ .await+ .unwrap();++ let dec = flate2::read::GzDecoder::new(std::io::Cursor::new(bytes.to_vec()));+ let mut ar = tar::Archive::new(dec);+ let mut names = Vec::new();+ let mut index_body = String::new();+ let mut page_body = String::new();+ for entry in ar.entries().unwrap() {+ let mut entry = entry.unwrap();+ let name = entry.path().unwrap().display().to_string();+ use std::io::Read as _;+ let mut content = String::new();+ entry.read_to_string(&mut content).unwrap();+ if name == "index.md" {+ index_body = content.clone();+ }+ if name == "gotchas/build.md" {+ page_body = content.clone();+ }+ names.push(name);+ }+ assert!(names.contains(&"index.md".to_string()), "{names:?}");+ assert!(names.contains(&"gotchas/build.md".to_string()), "{names:?}");+ assert!(index_body.contains("okf_version: \"0.2\""));+ let fm = ai_memory_wiki::parse(&page_body).unwrap().frontmatter;+ assert!(ai_memory_core::okf::is_conformant(&fm));+ assert_eq!(fm["type"], "Gotcha");+ }++ /// A bundle with a non-conformant page must fail the export rather+ /// than ship something a strict reader rejects.+ #[tokio::test]+ async fn export_okf_refuses_a_nonconformant_page() {+ let (tmp, router) = read_page_test_router();+ post_write_page(&router, "default", "scratch", "notes/a.md", "fine").await;+ // Fabricate a pre-migration file next to it.+ let ws_dir = std::fs::read_dir(tmp.path().join("wiki"))+ .unwrap()+ .next()+ .unwrap()+ .unwrap()+ .path();+ let proj_dir = std::fs::read_dir(&ws_dir)+ .unwrap()+ .next()+ .unwrap()+ .unwrap()+ .path();+ std::fs::write(+ proj_dir.join("notes/legacy.md"),+ "---\ntitle: Legacy\n---\nno type here",+ )+ .unwrap();++ let resp = router+ .clone()+ .oneshot(+ Request::builder()+ .method("POST")+ .uri("/admin/export-okf?workspace=default&project=scratch")+ .body(Body::empty())+ .unwrap(),+ )+ .await+ .unwrap();+ assert_eq!(resp.status(), StatusCode::UNPROCESSABLE_ENTITY);+ }+fn admin_state_for_store(tmp: &TempDir, store: &Store, wiki: Wiki) -> AdminState {admin_state_for_store_with_llm(tmp, store, wiki, None)}@@ -10355,6 +10581,11 @@ mod tests {fn admin_route_samples() -> Vec<(&'static str, &'static str, serde_json::Value)> {vec![("POST", "/admin/backup", serde_json::Value::Null),+ (+ "POST",+ "/admin/export-okf?workspace=default&project=scratch",+ serde_json::Value::Null,+ ),("POST","/admin/bootstrap",