Skip to content

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.rs
index 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.rs
new file mode 100644
index 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.rs
index 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.rs
index 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.rs
index 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",