Skip to content

Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors

Rust

fix(cli): complete Claude config relocation support

AkitaOnRails2d699f7a5a60
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 49783e88..f21aa2e6 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -27,16 +27,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
- `install-mcp --client claude-code` and `uninstall` now honour
`CLAUDE_CONFIG_DIR`: MCP registrations go to
`$CLAUDE_CONFIG_DIR/.claude.json` when the variable is set (non-empty),
- falling back to `~/.claude.json` otherwise. The dry-run output prints the
- resolved config path instead of a hardcoded `~/.claude.json`.
+ falling back to `~/.claude.json` otherwise. Uninstall checks both the active
+ relocated path and the home default so enabling the variable does not orphan
+ a prior default-path registration. The
+ dry-run output prints the resolved config path instead of a hardcoded path.
- `install-hooks --agent claude-code` and `setup-agent` follow the same
resolution for the hooks settings file: `$CLAUDE_CONFIG_DIR/settings.json`
- when set, else `~/.claude/settings.json`. Rendered output and the
- chmod-600 warning show the resolved path.
+ when set, else `~/.claude/settings.json`. Uninstall checks both locations;
+ rendered output and the chmod-600 warning show the resolved path.
- `install-skills --scope global` (claude-code root) installs to
`$CLAUDE_CONFIG_DIR/skills` when the variable is set, else
`~/.claude/skills`. `uninstall` sweeps the relocated root alongside the
home default so installs that predate the env var are still removed.
+- The Docker CLI wrapper forwards `CLAUDE_CONFIG_DIR` into its helper
+ container for relocated Claude Code configs beneath the existing home bind.
## [1.17.1] - 2026-07-20
diff --git a/README.md b/README.md
index aad3ad4c..9adf3ced 100644
--- a/README.md
+++ b/README.md
@@ -308,7 +308,7 @@ docker run -d --name ai-memory \
akitaonrails/ai-memory:latest
# 3. Wire your agent CLI in two commands. The wrapper takes care of
-# mounts + auto-detecting ~/.claude/settings.json. Re-run with
+# mounts and each client's config-path detection. Re-run with
# `--agent codex`, `--agent devin`, `--agent opencode`, `--agent gemini-cli`,
# `--agent grok`, `--agent kimi-code`, `--agent omp`, `--agent oh-my-pi`, `--client cursor`,
# `--client gemini-cli`, `--client grok`, etc.
@@ -338,6 +338,14 @@ other server / hook you have configured, and write a timestamped
scripts are staged into `~/.local/share/ai-memory/hooks/<agent>/`
automatically; re-running overwrites them so future image updates ship
updated hooks. Drop `--apply` to print the snippet instead of mutating.
+For Claude Code, `CLAUDE_CONFIG_DIR` relocates MCP registration to
+`$CLAUDE_CONFIG_DIR/.claude.json`, hooks to
+`$CLAUDE_CONFIG_DIR/settings.json`, and global managed skills to
+`$CLAUDE_CONFIG_DIR/skills`. The Docker wrapper forwards this variable when
+the directory is under its existing `$HOME` bind mount. Use the native binary
+when the Claude config root is outside `$HOME`. Uninstall checks both the
+active relocated paths and Claude's home defaults, so enabling the variable
+does not leave an older default-path ai-memory installation behind.
If your agent often starts inside repository subdirectories or linked
worktrees, add `--project-strategy repo-root` to `install-hooks` so captures
collapse to the main git repo name; see [`docs/install.md`](docs/install.md)
diff --git a/bin/ai-memory b/bin/ai-memory
index 7f64d6ce..65b0b1a1 100755
--- a/bin/ai-memory
+++ b/bin/ai-memory
@@ -23,6 +23,8 @@
# AI_MEMORY_NO_TTY=1 force non-interactive even on a real tty
# AI_MEMORY_NO_VERSION_CHECK=1 skip the once-per-day update check
# AI_MEMORY_NATIVE_BIN native ai-memory binary used for `run` (optional)
+# CLAUDE_CONFIG_DIR Claude Code config root (forwarded to the helper;
+# paths under $HOME are covered by the home bind mount)
set -euo pipefail
IMAGE="${AI_MEMORY_IMAGE:-akitaonrails/ai-memory:latest}"
@@ -330,6 +332,7 @@ for var in \
AI_MEMORY_WORKSTREAM_ID \
AI_MEMORY_HOOK_PLATFORM \
AI_MEMORY_HOOKS_HOST_ROOT \
+ CLAUDE_CONFIG_DIR \
ANTHROPIC_API_KEY \
OPENAI_API_KEY \
COPILOT_GITHUB_TOKEN \
@@ -470,8 +473,8 @@ else
fi
# Mount $HOME at the same path inside the container so:
-# - dirs::home_dir() resolves identically (~/.claude/settings.json
-# auto-detect works without --config-file)
+# - dirs::home_dir() resolves identically (Claude's default paths and any
+# CLAUDE_CONFIG_DIR beneath $HOME work without extra path flags)
# - install-hooks stages scripts into ~/.local/share/ai-memory/hooks/
#
# Mount $PWD at /work and set the container workdir there. This
diff --git a/crates/ai-memory-cli/src/cli.rs b/crates/ai-memory-cli/src/cli.rs
index dad4a3f8..6d6bb822 100644
--- a/crates/ai-memory-cli/src/cli.rs
+++ b/crates/ai-memory-cli/src/cli.rs
@@ -1434,7 +1434,7 @@ pub struct InstallMcpArgs {
#[arg(long)]
pub apply: bool,
/// Override the config-file path. Auto-detected per client when
- /// absent (e.g. `~/.claude/settings.json` for Claude Code).
+ /// absent (e.g. `~/.claude.json` for Claude Code).
#[arg(long)]
pub config_file: Option<PathBuf>,
}
diff --git a/crates/ai-memory-cli/src/commands/path_util.rs b/crates/ai-memory-cli/src/commands/path_util.rs
index 9a085c41..9bec4ff5 100644
--- a/crates/ai-memory-cli/src/commands/path_util.rs
+++ b/crates/ai-memory-cli/src/commands/path_util.rs
@@ -1,7 +1,7 @@
//! Path helpers shared by command renderers and hook capture.
use std::borrow::Cow;
-use std::path::PathBuf;
+use std::path::{Path, PathBuf};
/// Resolve the user home used for agent configuration paths.
///
@@ -26,6 +26,27 @@ pub(crate) fn claude_config_dir(env_override: Option<std::ffi::OsString>) -> Opt
Some(PathBuf::from(value))
}
+/// Candidate Claude Code paths for uninstall. The active relocated path comes
+/// first, followed by the legacy home path, with exact duplicates removed.
+pub(crate) fn claude_config_paths(
+ home: Option<&Path>,
+ relocated: Option<&Path>,
+ legacy_relative: &Path,
+ relocated_relative: &Path,
+) -> Vec<PathBuf> {
+ let mut paths = Vec::with_capacity(2);
+ if let Some(root) = relocated {
+ paths.push(root.join(relocated_relative));
+ }
+ if let Some(root) = home {
+ let legacy = root.join(legacy_relative);
+ if !paths.contains(&legacy) {
+ paths.push(legacy);
+ }
+ }
+ paths
+}
+
/// Strip only Windows verbatim path prefixes that are safe to render as plain
/// paths. Unknown verbatim forms are left unchanged.
pub(crate) fn strip_windows_verbatim_prefix(path: &str) -> Cow<'_, str> {
@@ -74,6 +95,31 @@ mod tests {
}
}
+ #[test]
+ fn claude_config_paths_put_relocated_first_and_deduplicate() {
+ assert_eq!(
+ claude_config_paths(
+ Some(Path::new("/home/alice")),
+ Some(Path::new("/stores/claude")),
+ Path::new(".claude/settings.json"),
+ Path::new("settings.json"),
+ ),
+ [
+ PathBuf::from("/stores/claude/settings.json"),
+ PathBuf::from("/home/alice/.claude/settings.json"),
+ ]
+ );
+ assert_eq!(
+ claude_config_paths(
+ Some(Path::new("/home/alice")),
+ Some(Path::new("/home/alice/.claude")),
+ Path::new(".claude/settings.json"),
+ Path::new("settings.json"),
+ ),
+ [PathBuf::from("/home/alice/.claude/settings.json")]
+ );
+ }
+
#[test]
fn strip_windows_verbatim_prefix_handles_drive_paths() {
assert_eq!(
diff --git a/crates/ai-memory-cli/src/commands/uninstall.rs b/crates/ai-memory-cli/src/commands/uninstall.rs
index d9f77947..686ff038 100644
--- a/crates/ai-memory-cli/src/commands/uninstall.rs
+++ b/crates/ai-memory-cli/src/commands/uninstall.rs
@@ -11,7 +11,7 @@ use crate::cli::UninstallArgs;
use crate::commands::apply_shared::apply_atomic;
use crate::commands::apply_shared::mutate_json;
use crate::commands::apply_shared::mutate_toml;
-use crate::commands::path_util::home_dir;
+use crate::commands::path_util::{claude_config_dir, claude_config_paths, home_dir};
use crate::commands::{data_purge, install_hooks, install_mcp, openclaw_plugin};
use crate::config::Config;
use ai_memory_core::routing_skills::{
@@ -136,14 +136,21 @@ fn build_plan(args: &UninstallArgs) -> anyhow::Result<Vec<PlannedChange>> {
let want = |k: crate::cli::UninstallOnly| args.only.is_none() || args.only == Some(k);
let name = args.mcp_name.as_deref();
let url = args.mcp_url.as_str();
+ let home = home_dir();
+ let claude_config_dir = claude_config_dir(std::env::var_os("CLAUDE_CONFIG_DIR"));
// ---- Hooks (JSON configs) ----
if want(crate::cli::UninstallOnly::Hooks) {
- let hook_files = [
- (
- install_hooks::claude_settings_path()?,
- HookConfigShape::NestedHooksKey,
- ),
+ let mut hook_files: Vec<_> = claude_config_paths(
+ home.as_deref(),
+ claude_config_dir.as_deref(),
+ Path::new(".claude/settings.json"),
+ Path::new("settings.json"),
+ )
+ .into_iter()
+ .map(|path| (path, HookConfigShape::NestedHooksKey))
+ .collect();
+ hook_files.extend([
(
install_hooks::codex_hooks_path()?,
HookConfigShape::NestedHooksKey,
@@ -173,7 +180,7 @@ fn build_plan(args: &UninstallArgs) -> anyhow::Result<Vec<PlannedChange>> {
install_hooks::devin_config_path()?,
HookConfigShape::NestedHooksKey,
),
- ];
+ ]);
for (path, shape) in hook_files {
if !path.exists() {
continue;
@@ -277,25 +284,37 @@ fn build_plan(args: &UninstallArgs) -> anyhow::Result<Vec<PlannedChange>> {
Devin,
KimiCode,
] {
- let Ok(path) = install_mcp::mcp_config_path(client) else {
- continue;
- };
- if !path.exists() {
- continue;
- }
- let content = std::fs::read_to_string(&path)
- .with_context(|| format!("reading {}", path.display()))?;
- let (_new, removed) = if matches!(client, Codex | Grok) {
- strip_mcp_toml(&content, name, url)?
- } else {
- strip_mcp_json_client(&content, client, name, url)?
- };
- let op = if matches!(client, Codex | Grok) {
- RewriteOp::McpToml
+ let paths = if matches!(client, ClaudeCode) {
+ claude_config_paths(
+ home.as_deref(),
+ claude_config_dir.as_deref(),
+ Path::new(".claude.json"),
+ Path::new(".claude.json"),
+ )
} else {
- RewriteOp::McpJson(client)
+ let Ok(path) = install_mcp::mcp_config_path(client) else {
+ continue;
+ };
+ vec![path]
};
- push_rewrite(&mut plan, path, removed, op);
+ for path in paths {
+ if !path.exists() {
+ continue;
+ }
+ let content = std::fs::read_to_string(&path)
+ .with_context(|| format!("reading {}", path.display()))?;
+ let (_new, removed) = if matches!(client, Codex | Grok) {
+ strip_mcp_toml(&content, name, url)?
+ } else {
+ strip_mcp_json_client(&content, client, name, url)?
+ };
+ let op = if matches!(client, Codex | Grok) {
+ RewriteOp::McpToml
+ } else {
+ RewriteOp::McpJson(client)
+ };
+ push_rewrite(&mut plan, path, removed, op);
+ }
}
}
@@ -324,11 +343,8 @@ fn build_plan(args: &UninstallArgs) -> anyhow::Result<Vec<PlannedChange>> {
// ---- Managed Agent Skills (project + global roots) ----
if want(crate::cli::UninstallOnly::Skills) {
let cwd = std::env::current_dir().context("getting CWD for skill removal")?;
- let home = home_dir();
let appdata = std::env::var_os("APPDATA").map(PathBuf::from);
let grok_home = install_mcp::grok_home().ok();
- let claude_config_dir =
- crate::commands::path_util::claude_config_dir(std::env::var_os("CLAUDE_CONFIG_DIR"));
for root in skill_roots(
&cwd,
home.as_deref(),
diff --git a/crates/ai-memory-cli/tests/packaging.rs b/crates/ai-memory-cli/tests/packaging.rs
index bf0fbe38..41eac98c 100644
--- a/crates/ai-memory-cli/tests/packaging.rs
+++ b/crates/ai-memory-cli/tests/packaging.rs
@@ -72,6 +72,7 @@ fn run_wrapper_on_fake_macos(args: &[&str]) -> String {
.env("AI_MEMORY_DATA_VOLUME", "test-ai-memory-data")
.env("HOME", shell_path(tmp.path()))
.env_remove("AI_MEMORY_SERVER_URL")
+ .env_remove("CLAUDE_CONFIG_DIR")
.output()
.unwrap();
assert!(
@@ -281,6 +282,15 @@ fn run_wrapper_with_fake_docker(args: &[&str], docker_info_stdout: &str) -> Stri
run_wrapper_with_fake_docker_and_uname(args, docker_info_stdout, None)
}
+#[cfg(unix)]
+fn run_wrapper_with_fake_docker_and_claude_config(
+ args: &[&str],
+ docker_info_stdout: &str,
+ claude_config_dir: &str,
+) -> String {
+ run_wrapper_with_fake_docker_env(args, docker_info_stdout, None, Some(claude_config_dir))
+}
+
// The wrapper also shells out to `id -u` / `id -g` when choosing its default
// Docker uid mapping. Arch container tests often run as root, which would make
// the default mapping `-u 0:0` and produce a false positive in the assertions
@@ -293,6 +303,16 @@ fn run_wrapper_with_fake_docker_and_uname(
args: &[&str],
docker_info_stdout: &str,
uname_stdout: Option<&str>,
+) -> String {
+ run_wrapper_with_fake_docker_env(args, docker_info_stdout, uname_stdout, None)
+}
+
+#[cfg(unix)]
+fn run_wrapper_with_fake_docker_env(
+ args: &[&str],
+ docker_info_stdout: &str,
+ uname_stdout: Option<&str>,
+ claude_config_dir: Option<&str>,
) -> String {
let tmp = tempfile::tempdir().unwrap();
let docker_args = tmp.path().join("docker-args.txt");
@@ -354,7 +374,11 @@ fn run_wrapper_with_fake_docker_and_uname(
.env("AI_MEMORY_NO_VERSION_CHECK", "1")
.env("AI_MEMORY_DATA_VOLUME", "test-ai-memory-data")
.env("HOME", shell_path(tmp.path()))
- .env_remove("AI_MEMORY_SERVER_URL");
+ .env_remove("AI_MEMORY_SERVER_URL")
+ .env_remove("CLAUDE_CONFIG_DIR");
+ if let Some(claude_config_dir) = claude_config_dir {
+ command.env("CLAUDE_CONFIG_DIR", claude_config_dir);
+ }
let output = command.output().unwrap();
assert!(
output.status.success(),
@@ -365,6 +389,20 @@ fn run_wrapper_with_fake_docker_and_uname(
std::fs::read_to_string(docker_args).unwrap()
}
+#[cfg(unix)]
+#[test]
+fn wrapper_forwards_claude_config_dir_to_helper_container() {
+ let args = run_wrapper_with_fake_docker_and_claude_config(
+ &["install-hooks", "--agent", "claude-code", "--apply"],
+ "[name=seccomp,profile=default]",
+ "/home/alice/.config/claude",
+ );
+ assert!(
+ args.contains("-e\nCLAUDE_CONFIG_DIR"),
+ "wrapper must forward Claude's config root; got {args}"
+ );
+}
+
#[cfg(unix)]
fn run_wrapper_with_fake_rootless_docker_on_fake_macos(args: &[&str]) -> String {
run_wrapper_with_fake_docker_and_uname(
diff --git a/crates/ai-memory-cli/tests/removal.rs b/crates/ai-memory-cli/tests/removal.rs
index 0c2d3ece..6af0fe9a 100644
--- a/crates/ai-memory-cli/tests/removal.rs
+++ b/crates/ai-memory-cli/tests/removal.rs
@@ -35,9 +35,14 @@ fn command_with_home(home: &Path) -> Command {
.env("LOCALAPPDATA", local_app_data)
.env("AI_MEMORY_HOME", home)
.env("AI_MEMORY_DATA_DIR", home.join(".ai-memory-data"))
+ .env_remove("AI_MEMORY_SERVER_URL")
+ .env_remove("AI_MEMORY_AUTH_TOKEN")
// A host-level KIMI_CODE_HOME would pull uninstall's kimi-code
// config sweep out of the sandbox; tests opt back in explicitly.
- .env_remove("KIMI_CODE_HOME");
+ .env_remove("KIMI_CODE_HOME")
+ // Keep Claude installer/removal tests inside their temp HOME unless a
+ // test explicitly opts into a relocated config root.
+ .env_remove("CLAUDE_CONFIG_DIR");
command
}
@@ -118,6 +123,103 @@ fn install_then_uninstall_round_trip_claude_hooks() {
}
}
+#[test]
+fn relocated_claude_uninstall_sweeps_active_and_legacy_installs() {
+ let _guard = cli_test_lock();
+ let project = tempfile::tempdir().unwrap();
+ let home = tempfile::tempdir().unwrap();
+ let relocated = home.path().join("claude-work");
+
+ let run = |relocate: bool, args: &[&str]| {
+ let mut command = command_with_home(home.path());
+ if relocate {
+ command.env("CLAUDE_CONFIG_DIR", &relocated);
+ }
+ command
+ .args(args)
+ .current_dir(project.path())
+ .output()
+ .unwrap()
+ };
+
+ for relocate in [false, true] {
+ for args in [
+ &["install-hooks", "--agent", "claude-code", "--apply"][..],
+ &["install-mcp", "--client", "claude-code", "--apply"][..],
+ &[
+ "install-skills",
+ "--agent",
+ "claude-code",
+ "--scope",
+ "global",
+ ][..],
+ ] {
+ let output = run(relocate, args);
+ assert!(
+ output.status.success(),
+ "install failed: {}",
+ String::from_utf8_lossy(&output.stderr)
+ );
+ }
+ }
+
+ let legacy_settings = home.path().join(".claude/settings.json");
+ let legacy_mcp = home.path().join(".claude.json");
+ let legacy_skills = home.path().join(".claude/skills");
+ let relocated_settings = relocated.join("settings.json");
+ let relocated_mcp = relocated.join(".claude.json");
+ let relocated_skills = relocated.join("skills");
+ for path in [
+ &legacy_settings,
+ &legacy_mcp,
+ &relocated_settings,
+ &relocated_mcp,
+ ] {
+ assert!(path.exists(), "installer did not create {}", path.display());
+ }
+ for root in [&legacy_skills, &relocated_skills] {
+ assert!(
+ root.join(MANAGED_SKILLS[0].relative_path).exists(),
+ "installer did not create managed skills under {}",
+ root.display()
+ );
+ }
+
+ let output = run(true, &["uninstall", "--apply", "--yes"]);
+ assert!(
+ output.status.success(),
+ "uninstall failed: {}",
+ String::from_utf8_lossy(&output.stderr)
+ );
+
+ for path in [&legacy_settings, &relocated_settings] {
+ let content = std::fs::read_to_string(path).unwrap();
+ assert!(
+ !content.contains("AI_MEMORY_HOOK_URL"),
+ "Claude hooks survived in {}",
+ path.display()
+ );
+ }
+ for path in [&legacy_mcp, &relocated_mcp] {
+ let content = std::fs::read_to_string(path).unwrap();
+ let config: serde_json::Value = serde_json::from_str(&content).unwrap();
+ assert!(
+ config["mcpServers"].get("ai-memory").is_none(),
+ "Claude MCP entry survived in {}: {content}",
+ path.display(),
+ );
+ }
+ for root in [&legacy_skills, &relocated_skills] {
+ for skill in MANAGED_SKILLS {
+ assert!(
+ !root.join(skill.relative_path).exists(),
+ "managed skill survived under {}",
+ root.display()
+ );
+ }
+ }
+}
+
#[test]
fn uninstall_apply_is_idempotent() {
let _guard = cli_test_lock();
diff --git a/docs/install.md b/docs/install.md
index 3f95f0c0..7fe111c1 100644
--- a/docs/install.md
+++ b/docs/install.md
@@ -74,7 +74,11 @@ own config resolution: `install-mcp` writes the MCP registration to
`install-hooks` / `setup-agent` target `$CLAUDE_CONFIG_DIR/settings.json`
(instead of `~/.claude/settings.json`), and `install-skills --scope global`
uses `$CLAUDE_CONFIG_DIR/skills` (instead of `~/.claude/skills`). `uninstall`
-sweeps the relocated paths alongside the defaults.
+sweeps the active relocated paths alongside the home defaults. It cannot
+discover an older arbitrary `CLAUDE_CONFIG_DIR` that is no longer set. The
+Docker wrapper forwards the variable for config roots under its existing
+`$HOME` bind mount; use the native binary when the relocated root is outside
+`$HOME`.
The CLI commands (`bootstrap`, `status`, `search`, `lint`, `auto-improve`,
`curator`, `pending-writes`, etc.) inherit the two env vars automatically. So do