Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors
Rust
fix(cli): address backup-agents review
Barba2k2493e1718b69a
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 27de62c7..2479a23e 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -8,12 +8,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0## [Unreleased]### Added-- `ai-memory backup-agents` and `ai-memory restore-agents` now snapshot, export,- and restore host AI agent configurations, skills, plugins, and project- instructions across supported harnesses. Backups sanitize secrets by default,- include deterministic manifests with SHA-256 checksums, support dry-run- previews and agent/scope filters, and restore through path-guarded atomic writes.- (#962)+- Added `ai-memory backup-agents` and `ai-memory restore-agents` commands for+ host AI agent configurations, skills, plugins, and project instructions.+ Backups sanitized MCP config text by default; other assets were copied+ verbatim and could contain secrets. Archives included deterministic manifests+ with SHA-256 checksums, dry-run previews, agent/scope filters, and path-guarded+ atomic restores. (#962)- `install-skills --agent hermes` (and the `hermes` entry in`memory_install_self_routing`'s `target_hints`) installs the managed routingskills into Hermes Agent's `.hermes/skills` (project) or `~/.hermes/skills`diff --git a/crates/ai-memory-cli/src/cli.rs b/crates/ai-memory-cli/src/cli.rsindex 4b872569..57283847 100644--- a/crates/ai-memory-cli/src/cli.rs+++ b/crates/ai-memory-cli/src/cli.rs@@ -1775,7 +1775,8 @@ pub struct BackupAgentsArgs {/// Scope of assets to collect: `global`, `project`, or `both`.#[arg(long, default_value = "both")]pub scope: AgentBackupScope,- /// Include raw un-redacted credentials and tokens in MCP configs (sets file mode 0600 on archive).+ /// Skip MCP-config redaction; other assets are always copied verbatim.+ /// Sets archive mode to 0600 on Unix.#[arg(long)]pub include_secrets: bool,/// Preview assets that would be backed up without creating an archive.diff --git a/crates/ai-memory-cli/src/commands/backup_agents.rs b/crates/ai-memory-cli/src/commands/backup_agents.rsindex f14dbf6b..64d900f7 100644--- a/crates/ai-memory-cli/src/commands/backup_agents.rs+++ b/crates/ai-memory-cli/src/commands/backup_agents.rs@@ -1,7 +1,7 @@//! `ai-memory backup-agents` — snapshot AI agent configurations,//! skills, plugins, and instructions into a portable archive.-use std::fs::{self, File};+use std::fs::{self, File, OpenOptions};use std::io::Cursor;use std::path::{Path, PathBuf};@@ -17,7 +17,7 @@ use sha2::{Digest, Sha256};use tar::{Builder, Header};use tracing::info;-use crate::cli::{AgentBackupScope, BackupAgentsArgs};+use crate::cli::{AgentBackupScope, BackupAgentsArgs, McpClient};use crate::commands::path_util::{claude_config_dir, home_dir};use crate::config::Config;@@ -67,21 +67,26 @@ pub fn run(_config: &Config, args: BackupAgentsArgs) -> Result<()> {.with_context(|| format!("creating parent dir for {}", dest.display()))?;}- #[cfg(unix)]let file = {- use std::os::unix::fs::OpenOptionsExt;- let mut opts = fs::OpenOptions::new();- opts.write(true).create(true).truncate(true);+ let mut opts = OpenOptions::new();+ opts.write(true).create(true);+ #[cfg(unix)]if args.include_secrets {+ use std::os::unix::fs::OpenOptionsExt;opts.mode(0o600);}opts.open(dest).with_context(|| format!("creating output archive at {}", dest.display()))?};- #[cfg(not(unix))]- let file = File::create(dest)- .with_context(|| format!("creating output archive at {}", dest.display()))?;+ #[cfg(unix)]+ if args.include_secrets {+ use std::os::unix::fs::PermissionsExt;+ file.set_permissions(fs::Permissions::from_mode(0o600))+ .with_context(|| format!("securing output archive {}", dest.display()))?;+ }+ file.set_len(0)+ .with_context(|| format!("truncating output archive {}", dest.display()))?;let count = build_archive(file, &discovered, args.include_secrets, &home)?;@@ -97,7 +102,7 @@ pub fn run(_config: &Config, args: BackupAgentsArgs) -> Result<()> {if args.include_secrets {eprintln!(- "⚠️ Warning: Secrets were included without sanitization. Archive permissions set to 0600."+ "⚠️ Warning: Secrets were included without sanitization. Archive mode is 0600 on Unix; protect the file on other platforms.");}@@ -215,38 +220,23 @@ pub fn discover_assets(}}- // Claude Desktop+ // Reuse the installer path so platform-specific Claude Desktop configs+ // are backed up and restored at the same location.if filter_agent(AgentKind::ClaudeDesktop) && want_global {- #[cfg(target_os = "macos")]- let desktop_cfg = home- .join("Library")- .join("Application Support")- .join("Claude")- .join("claude_desktop_config.json");- #[cfg(target_os = "windows")]- let desktop_cfg = dirs::config_dir()- .map(|d| d.join("Claude").join("claude_desktop_config.json"))- .unwrap_or_else(|| {- home.join("AppData")- .join("Roaming")- .join("Claude")- .join("claude_desktop_config.json")- });- #[cfg(not(any(target_os = "macos", target_os = "windows")))]- let desktop_cfg = home- .join(".config")- .join("Claude")- .join("claude_desktop_config.json");-- push_if_file(- &mut assets,- AgentKind::ClaudeDesktop,- AgentAssetKind::McpConfig,- AgentAssetScope::Global,- desktop_cfg,- ".claude/claude_desktop_config.json",- "claude-desktop/claude_desktop_config.json",- );+ #[cfg(any(target_os = "macos", target_os = "windows"))]+ {+ let desktop_cfg =+ crate::commands::install_mcp::mcp_config_path(McpClient::ClaudeDesktop)?;+ push_if_file(+ &mut assets,+ AgentKind::ClaudeDesktop,+ AgentAssetKind::McpConfig,+ AgentAssetScope::Global,+ desktop_cfg,+ ".claude/claude_desktop_config.json",+ "claude-desktop/claude_desktop_config.json",+ );+ }}// 2. OpenAI Codex CLI@@ -458,13 +448,18 @@ pub fn discover_assets(// 5. OpenCode (v1 / v2)if filter_agent(AgentKind::OpenCode) {if want_global {- let opencode_dir = home.join(".config").join("opencode");+ let opencode_config =+ crate::commands::install_mcp::mcp_config_path(McpClient::OpenCode)?;+ let opencode_dir = opencode_config+ .parent()+ .map(Path::to_path_buf)+ .context("OpenCode config path has no parent directory")?;push_if_file(&mut assets,AgentKind::OpenCode,AgentAssetKind::McpConfig,AgentAssetScope::Global,- opencode_dir.join("opencode.json"),+ opencode_config,".config/opencode/opencode.json","opencode/opencode.json",);diff --git a/crates/ai-memory-cli/src/commands/restore_agents.rs b/crates/ai-memory-cli/src/commands/restore_agents.rsindex 592d9ac2..0f0b8206 100644--- a/crates/ai-memory-cli/src/commands/restore_agents.rs+++ b/crates/ai-memory-cli/src/commands/restore_agents.rs@@ -16,7 +16,7 @@ use sha2::{Digest, Sha256};use tar::Archive;use tracing::info;-use crate::cli::{AgentBackupScope, RestoreAgentsArgs};+use crate::cli::{AgentBackupScope, McpClient, RestoreAgentsArgs};use crate::commands::backup_agents::matches_agent_filter;use crate::commands::path_util::{claude_config_dir, home_dir};use crate::config::Config;@@ -102,7 +102,18 @@ pub fn run(_config: &Config, args: RestoreAgentsArgs) -> Result<()> {let target_path = match entry.scope {AgentAssetScope::Global => {- if entry.agent == AgentKind::ClaudeCode+ if entry.agent == AgentKind::ClaudeDesktop {+ crate::commands::install_mcp::mcp_config_path(McpClient::ClaudeDesktop)?+ } else if entry.agent == AgentKind::OpenCode+ && let Some(rel) = entry.target_relative.strip_prefix(".config/opencode/")+ {+ let config =+ crate::commands::install_mcp::mcp_config_path(McpClient::OpenCode)?;+ config+ .parent()+ .context("OpenCode config path has no parent directory")?+ .join(rel)+ } else if entry.agent == AgentKind::ClaudeCode&& let Some(ref custom_dir) = claude_override&& let Some(rel) = entry.target_relative.strip_prefix(".claude/"){@@ -186,11 +197,17 @@ pub fn run(_config: &Config, args: RestoreAgentsArgs) -> Result<()> {// Keep backup copy of pre-existing file on overwriteif exists {- let stamp = jiff::Timestamp::now().as_second();+ let stamp = jiff::Timestamp::now().as_microsecond();let mut bak = target_path.as_os_str().to_owned();bak.push(format!(".bak-{stamp}"));let backup_path = PathBuf::from(bak);- let _ = fs::copy(&target_path, &backup_path);+ fs::copy(&target_path, &backup_path).with_context(|| {+ format!(+ "backing up {} to {}",+ target_path.display(),+ backup_path.display()+ )+ })?;}// Binary-safe atomic writediff --git a/crates/ai-memory-cli/tests/suite/backup_agents.rs b/crates/ai-memory-cli/tests/suite/backup_agents.rsindex a14a612c..26a8d9c1 100644--- a/crates/ai-memory-cli/tests/suite/backup_agents.rs+++ b/crates/ai-memory-cli/tests/suite/backup_agents.rs@@ -1,7 +1,7 @@//! Integration tests for `ai-memory backup-agents` and `ai-memory restore-agents`.use std::fs;-use std::path::Path;+use std::path::{Path, PathBuf};use std::process::Command;use std::sync::{Mutex, MutexGuard};@@ -36,7 +36,27 @@ fn command_with_env(home: &Path, cwd: &Path) -> Command {.env_remove("CLAUDE_CONFIG_DIR").env_remove("KIMI_CODE_HOME").env_remove("KIRO_HOME");+ #[cfg(windows)]command+ .env("APPDATA", home.join("AppData/Roaming"))+ .env("LOCALAPPDATA", home.join("AppData/Local"));+ command+}++fn claude_desktop_config_in(home: &Path) -> Option<PathBuf> {+ #[cfg(target_os = "macos")]+ {+ Some(home.join("Library/Application Support/Claude/claude_desktop_config.json"))+ }+ #[cfg(target_os = "windows")]+ {+ Some(home.join("AppData/Roaming/Claude/claude_desktop_config.json"))+ }+ #[cfg(not(any(target_os = "macos", target_os = "windows")))]+ {+ let _ = home;+ None+ }}#[test]@@ -74,6 +94,16 @@ fn backup_and_restore_agents_round_trip() {let agents_md = project.path().join("AGENTS.md");fs::write(&agents_md, "# Project Rules\nCodex rules").unwrap();+ let opencode_config = home.path().join(".config/opencode/opencode.json");+ fs::create_dir_all(opencode_config.parent().unwrap()).unwrap();+ fs::write(&opencode_config, r#"{"mcp":{}}"#).unwrap();++ let desktop_config = claude_desktop_config_in(home.path());+ if let Some(path) = &desktop_config {+ fs::create_dir_all(path.parent().unwrap()).unwrap();+ fs::write(path, r#"{"mcpServers":{"desktop":{}}}"#).unwrap();+ }+// Antigravity / Geminilet agy_mcp = home.path().join(".gemini/config/mcp_config.json");fs::create_dir_all(agy_mcp.parent().unwrap()).unwrap();@@ -84,6 +114,7 @@ fn backup_and_restore_agents_round_trip() {.unwrap();let backup_tar = project.path().join("backup.tar.gz");+ fs::write(&backup_tar, "previous archive").unwrap();// 2. Run backup-agentslet output = command_with_env(home.path(), project.path())@@ -101,6 +132,15 @@ fn backup_and_restore_agents_round_trip() {"backup-agents failed: {}",String::from_utf8_lossy(&output.stderr));+ #[cfg(unix)]+ {+ use std::os::unix::fs::PermissionsExt;+ assert_eq!(+ fs::metadata(&backup_tar).unwrap().permissions().mode() & 0o777,+ 0o600,+ "archives containing secrets must be private before writing"+ );+ }assert!(backup_tar.exists(), "backup tarball was not created");// 3. Restore into clean sandbox@@ -168,6 +208,19 @@ fn backup_and_restore_agents_round_trip() {restored_agy,r#"{"mcpServers":{"agy":{"url":"http://127.0.0.1"}}}"#);+ assert!(+ restore_home+ .path()+ .join(".config/opencode/opencode.json")+ .exists()+ );+ if desktop_config.is_some() {+ assert!(+ claude_desktop_config_in(restore_home.path())+ .unwrap()+ .exists()+ );+ }}#[test]@@ -542,3 +595,61 @@ fn backup_and_restore_kebab_case_agent_filter() {assert!(restore_home.path().join(".claude/settings.json").exists());assert!(!restore_home.path().join(".codex/config.toml").exists());}++#[test]+fn restore_agents_force_keeps_previous_file_backup() {+ let _guard = cli_test_lock();+ let home = tempfile::tempdir().unwrap();+ let project = tempfile::tempdir().unwrap();+ let source = home.path().join(".claude/settings.json");+ fs::create_dir_all(source.parent().unwrap()).unwrap();+ fs::write(&source, "restored config").unwrap();++ let archive = project.path().join("backup.tar.gz");+ let backup = command_with_env(home.path(), project.path())+ .args([+ "backup-agents",+ "-o",+ archive.to_str().unwrap(),+ "--agents",+ "claude-code",+ "--include-secrets",+ ])+ .output()+ .unwrap();+ assert!(backup.status.success());++ let restore_home = tempfile::tempdir().unwrap();+ let restore_project = tempfile::tempdir().unwrap();+ let existing = restore_home.path().join(".claude/settings.json");+ fs::create_dir_all(existing.parent().unwrap()).unwrap();+ fs::write(&existing, "previous config").unwrap();++ let restore = command_with_env(restore_home.path(), restore_project.path())+ .args([+ "restore-agents",+ "-i",+ archive.to_str().unwrap(),+ "--apply",+ "--force",+ ])+ .output()+ .unwrap();+ assert!(+ restore.status.success(),+ "restore failed: {}",+ String::from_utf8_lossy(&restore.stderr)+ );+ assert_eq!(fs::read(&existing).unwrap(), b"restored config");++ let backup_path = fs::read_dir(existing.parent().unwrap())+ .unwrap()+ .map(|entry| entry.unwrap().path())+ .find(|path| {+ path.file_name()+ .and_then(|name| name.to_str())+ .is_some_and(|name| name.starts_with("settings.json.bak-"))+ })+ .expect("overwrite must keep a backup copy");+ assert_eq!(fs::read(backup_path).unwrap(), b"previous config");+}diff --git a/docs/design-backup-agent-assets.md b/docs/design-backup-agent-assets.mdindex 4f50c3bf..39d1ec98 100644--- a/docs/design-backup-agent-assets.md+++ b/docs/design-backup-agent-assets.md@@ -26,6 +26,12 @@ Currently:| **OpenClaw** | `~/.openclaw/config.json` | — | `~/.openclaw/extensions/` | — || **VS Code Copilot** | `.vscode/mcp.json` | — | Extensions | Copilot instructions |+Claude Desktop config paths use the same platform-aware resolver as+`install-mcp`, including packaged Windows installs. OpenCode uses+`%USERPROFILE%\.config\opencode` on Windows too, as its+[official troubleshooting guide](https://dev.opencode.ai/docs/troubleshooting/)+documents.+---## 3. Architecture & CLI Design@@ -47,7 +53,7 @@ ai-memory backup-agents --agents claude,codex,antigravity --scope both -o backupai-memory backup-agents -o backup.tar.gz --include-secrets# Dry-run inspection of an archive before restoring-ai-memory restore-agents -i backup.tar.gz --dry-run+ai-memory restore-agents -i backup.tar.gz# Apply restoration atomicallyai-memory restore-agents -i backup.tar.gz --apply@@ -101,14 +107,15 @@ Stored in the root of the generated tarball:## 5. Security & Invariants1. **Secret Redaction:**- - By default, known tokens, bearer headers, and environment keys (`*_TOKEN`, `*_KEY`, `*_SECRET`) in MCP configs are sanitized using `ai-memory-hooks::sanitizer`.- - Passing `--include-secrets` bypasses redaction; the resulting `.tar.gz` is created with `0600` permissions and a warning is logged.+ - By default, known tokens, bearer headers, and environment keys (`*_TOKEN`, `*_KEY`, `*_SECRET`) in UTF-8 MCP config files are sanitized using `ai-memory-hooks::sanitizer`.+ - Skills, plugins, and instruction files are copied verbatim and may contain secrets.+ - Passing `--include-secrets` bypasses MCP redaction; on Unix the archive is set to mode `0600` before writing, and a warning is logged.2. **Symlink Safety:**- Archives do not traverse or include external symlinks (`follow_symlinks(false)`).3. **Path Traversal Protection:**- - Restoring validates that every target path resolves strictly inside the intended destination directory (`home_dir()` or project cwd).+ - Restoring rejects traversal and permits only allowlisted agent destinations. Claude Desktop uses the same platform-specific path resolver as `install-mcp`.4. **Atomic Restores:**- - Target files are written using temporary files + rename + sync (`apply_atomic`), avoiding partial or corrupted configurations.+ - Target files are written using temporary files + rename + sync (`ai_memory_wiki::write_atomic`), avoiding partial or corrupted configurations.- Non-managed custom files are never overwritten without explicit `--force`.---diff --git a/docs/security-boundaries.md b/docs/security-boundaries.mdindex 87455a96..cbd79fc0 100644--- a/docs/security-boundaries.md+++ b/docs/security-boundaries.md@@ -51,6 +51,8 @@ boundary not yet built.| 13 | Managed-run transcript attribution (concurrent launches in one checkout, invariant #16) | `ai-memory-store/src/workstream.rs` `link_native_session` stamps `native_session_linked_at` on its own run only, both `finish` updates drop the stamp when the session changes, `run_status` reports it; `ai-memory-cli/src/commands/run.rs` `resolve_native_session_after_run` takes a linked session only when `ai-memory-workstream` `native_session_in_checkout` holds it for this checkout (OpenCode by recorded directory), never falls back to a link it set aside, and turns an `AmbiguousNativeSession` into a warning with nothing imported; `ai-memory-workstream/src/transcript.rs` `discover_crush` claims only the one top-level session created (or, with `--continue`, touched) during the run, and in a data directory outside the project only one that edited a file in it | `multi_session.rs` `a_session_linked_by_one_managed_run_is_not_another_runs`; `run.rs` `a_session_linked_during_the_run_wins_over_discovery` (concurrent newer session, another checkout's link refused, no fallback to it, unlinked control); `transcript.rs` `native_session_in_checkout_checks_the_opencode_directory`; `store/src/lib.rs` `managed_run_status_reports_a_link_made_during_the_run`; `run.rs` `ambiguous_crush_discovery_keeps_the_run`; `transcript.rs` `crush_discovery_claims_only_the_session_the_run_created`, `crush_discovery_in_a_shared_store_claims_only_an_edit_here` | PARTIAL: a run whose child links nothing still falls back to discovering the newest session in the checkout; Crush, which has no hooks, relies on that discovery alone and claims nothing when it is ambiguous || 14 | Per-project authorization (#708) | `ai-memory-store/src/project_authz.rs` `authorize_project` / `ProjectAuthz::authorize` choke point (V68 `project_grants` + `projects.access_mode`, default `open`; V69 `projects.created_by` feeds `is_creator`); `scope.rs` `ScopeResolver::with_project_authz` (reader pool for reads, writer actor for writes) and its free forms `authorize_scope_for` / `*_guarded`, attached for every DB user by `ai-memory-mcp` `scope_resolver_as`, `ai-memory-web` `authorize_read` / `lookup_project`, and `ai-memory-hooks` (`grants.rs` `authorize_resolved` for run/workstream ids, the capture check in `router.rs`); read-shaped mutations resolve at `ProjectAccess::Write` (`resolve_existing_args(.., need)`); unscoped reads filtered before `LIMIT` by `reader.rs` `readable_repository_sql`; `WriterHandle::authorize_project` as defense in depth. Page ids are never taken from a caller (only derived from already-authorized hits), so there is no page-id entry point to guard | `tests/suite/project_authz.rs` (decision matrix, ship-inert, resolver gate); `tests/suite/access_mode.rs` `every_caller_against_both_modes`, `a_restricted_project_admits_the_team_and_refuses_the_outsider`, `new_projects_follow_the_server_default_and_admit_their_creator`; `scope.rs` `the_argument_shape_does_not_decide_the_level`, `a_user_reaches_only_what_they_were_granted`, `creating_authorizes_against_a_project_that_already_exists`, `a_refused_scope_fails_the_search_instead_of_shortening_it`; `grants.rs` `search_finds_only_what_the_viewer_may_read`, `the_limit_counts_only_what_the_viewer_may_see`, `the_workspace_handoff_comes_only_from_readable_repositories`; `ai-memory-mcp` `server.rs` `a_reader_may_read_everything_and_change_nothing`, `bob_cannot_read_alices_page_in_a_restricted_project`, `bob_cannot_find_alices_page_by_searching_in_a_restricted_project`, `bob_cannot_consolidate_a_session_in_alices_repository`, `a_restricted_projects_queues_need_write`; `ai-memory-hooks` `a_capture_needs_writer_on_the_repository_it_lands_in`, `session_start_delivers_nothing_from_a_repository_the_viewer_cannot_read`, `run_and_workstream_ids_only_answer_someone_who_may_reach_the_repository`; `ai-memory-web` `web_reads_honour_grants_in_a_restricted_project`, `metadata_shows_only_what_the_viewer_may_read` — each with a granted or open-project control, and proven to fail with the choke point (18 tests) or the SQL filter (9 tests) neutralized | STRONG — slice 3 closed both bypass classes (unscoped reads, raw-id entry points) and added the root-only management surface. Out of scope by design: per-project administrators (granting/restricting is root-only), and access modes, creators and grants live only in SQLite, so `reindex` resets them |+| 15 | Agent-archive restore path confinement and integrity | `ai-memory-cli/src/commands/restore_agents.rs` validates archive paths, allowlists destination paths by scope, verifies provided SHA-256 hashes, and writes atomically | `backup_agents.rs` `restore_agents_rejects_path_traversal`, `restore_agents_rejects_unauthorized_destination_path`, `restore_agents_verifies_sha256_integrity`; `backup_and_restore_agents_round_trip` is the valid-path control | STRONG |+## Keeping this current (the standing protocol)1. **Touch a guard, add/extend its adversarial test.** Any change to code in the