Skip to content

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.md
index 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 routing
skills 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.rs
index 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.rs
index 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.rs
index 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 overwrite
if 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 write
diff --git a/crates/ai-memory-cli/tests/suite/backup_agents.rs b/crates/ai-memory-cli/tests/suite/backup_agents.rs
index 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 / Gemini
let 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-agents
let 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.md
index 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 backup
ai-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 atomically
ai-memory restore-agents -i backup.tar.gz --apply
@@ -101,14 +107,15 @@ Stored in the root of the generated tarball:
## 5. Security & Invariants
1. **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.md
index 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