Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors
Rust
//! Path helpers shared by command renderers and hook capture.
use std::borrow::Cow;
use std::path::{Path, PathBuf};
/// Create `dir` (and its parents) `0700` on Unix. On non-Unix the mode is a
/// no-op (falls back to `create_dir_all`). Idempotent: an existing
/// directory's mode is left untouched (never widened, never narrowed) to
/// avoid churning a path an operator may have set deliberately.
pub(crate) fn create_private_dir(dir: &Path) -> std::io::Result<()> {
#[cfg(unix)]
{
use std::os::unix::fs::DirBuilderExt as _;
if dir.is_dir() {
return Ok(());
}
match std::fs::DirBuilder::new()
.recursive(true)
.mode(0o700)
.create(dir)
{
Ok(()) => Ok(()),
// A concurrent caller may have created it between the check and
// the call; treat an existing directory as success.
Err(_) if dir.is_dir() => Ok(()),
Err(e) => Err(e),
}
}
#[cfg(not(unix))]
{
std::fs::create_dir_all(dir)
}
}
/// Resolve the user home used for agent configuration paths.
///
/// Tests and scripted wrappers can set `AI_MEMORY_HOME` to exercise the
/// platform-specific config layout without touching the real user profile.
pub(crate) fn home_dir() -> Option<PathBuf> {
if let Some(home) = std::env::var_os("AI_MEMORY_HOME").filter(|value| !value.is_empty()) {
return Some(PathBuf::from(home));
}
dirs::home_dir()
}
/// An agent's relocated config root from its own home variable, when that
/// variable is set to a non-empty, non-whitespace value; else `None`, and the
/// caller falls back to the agent's `~/...` default.
///
/// Blank is treated as unset on purpose: an exported-but-empty variable is far
/// more often an unset shell expansion than a deliberate request to install
/// into the filesystem root. The rule lives in
/// [`ai_memory_workstream::env_dir_override`] so native session import applies
/// the same one and never reads a store the installers did not wire.
///
/// The env value comes in as a parameter so tests can exercise both branches
/// without mutating process env — which is not merely inconvenient here but
/// forbidden: `std::env::set_var` is `unsafe` under edition 2024 and this
/// workspace forbids `unsafe_code`.
pub(crate) fn agent_config_home(env_override: Option<std::ffi::OsString>) -> Option<PathBuf> {
ai_memory_workstream::env_dir_override(env_override)
}
/// Hermes profile ids follow `^[a-z0-9][a-z0-9_-]{0,63}$`.
pub(crate) fn is_hermes_profile_id(name: &str) -> bool {
let bytes = name.as_bytes();
bytes.len() <= 64
&& bytes
.first()
.is_some_and(|first| first.is_ascii_lowercase() || first.is_ascii_digit())
&& bytes
.iter()
.all(|b| b.is_ascii_lowercase() || b.is_ascii_digit() || *b == b'_' || *b == b'-')
}
/// Claude Code's relocated config root: `$CLAUDE_CONFIG_DIR` when set, else
/// `None`. Named alias kept so Claude call sites read for what they resolve.
pub(crate) fn claude_config_dir(env_override: Option<std::ffi::OsString>) -> Option<PathBuf> {
agent_config_home(env_override)
}
/// 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
}
/// `path` as shown to the operator: without a safe `\\?\` verbatim prefix,
/// which the canonical data dir carries on Windows and which `cmd` and most
/// scripts cannot use when the path is copied out of a message.
pub(crate) fn display_path(path: &Path) -> String {
strip_windows_verbatim_prefix(&path.to_string_lossy())
.chars()
.map(|character| {
if character.is_control() {
'?'
} else {
character
}
})
.collect()
}
/// 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> {
let Some(rest) = path.strip_prefix(r"\\?\") else {
return Cow::Borrowed(path);
};
if rest.len() >= 3
&& rest.as_bytes()[0].is_ascii_alphabetic()
&& rest.as_bytes()[1] == b':'
&& rest.as_bytes()[2] == b'\\'
{
return Cow::Borrowed(rest);
}
let bytes = rest.as_bytes();
if bytes.len() >= 4
&& bytes[0].eq_ignore_ascii_case(&b'U')
&& bytes[1].eq_ignore_ascii_case(&b'N')
&& bytes[2].eq_ignore_ascii_case(&b'C')
&& bytes[3] == b'\\'
{
return Cow::Owned(format!(r"\\{}", &rest[4..]));
}
Cow::Borrowed(path)
}
#[cfg(test)]
mod tests {
use super::*;
use std::ffi::OsString;
#[test]
fn claude_config_dir_honours_non_empty_value() {
assert_eq!(
claude_config_dir(Some(OsString::from("/stores/claude"))),
Some(PathBuf::from("/stores/claude"))
);
}
#[test]
fn claude_config_dir_treats_unset_empty_and_whitespace_as_unset() {
for env in [None, Some(OsString::new()), Some(OsString::from(" "))] {
assert_eq!(claude_config_dir(env.clone()), None, "env {env:?}");
}
}
#[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 display_path_drops_the_verbatim_prefix() {
assert_eq!(
display_path(Path::new(
r"\\?\C:\Users\me\AppData\Local\ai-memory\auth.json"
)),
r"C:\Users\me\AppData\Local\ai-memory\auth.json"
);
assert_eq!(
display_path(Path::new(r"\\?\UNC\server\share\ai-memory")),
r"\\server\share\ai-memory"
);
assert_eq!(
display_path(Path::new("/home/alice/.local/share/ai-memory")),
"/home/alice/.local/share/ai-memory"
);
assert_eq!(
display_path(Path::new("/tmp/line\nbreak")),
"/tmp/line?break"
);
}
#[test]
fn strip_windows_verbatim_prefix_handles_drive_paths() {
assert_eq!(
&*strip_windows_verbatim_prefix(r"\\?\C:\Users\me\AppData\Local\ai-memory"),
r"C:\Users\me\AppData\Local\ai-memory"
);
assert_eq!(
&*strip_windows_verbatim_prefix(r"\\?\c:\Users\me\AppData\Local\ai-memory"),
r"c:\Users\me\AppData\Local\ai-memory"
);
}
#[test]
fn strip_windows_verbatim_prefix_handles_unc_case_insensitively() {
assert_eq!(
&*strip_windows_verbatim_prefix(r"\\?\UNC\server\share\m"),
r"\\server\share\m"
);
assert_eq!(
&*strip_windows_verbatim_prefix(r"\\?\unc\Server\Share\m"),
r"\\Server\Share\m"
);
}
#[test]
fn strip_windows_verbatim_prefix_leaves_non_verbatim_paths_untouched() {
assert_eq!(
&*strip_windows_verbatim_prefix(r"C:\Users\me\ai-memory"),
r"C:\Users\me\ai-memory"
);
assert_eq!(
&*strip_windows_verbatim_prefix("/home/alice/.local/share/ai-memory"),
"/home/alice/.local/share/ai-memory"
);
}
#[test]
fn strip_windows_verbatim_prefix_leaves_unknown_forms_untouched() {
assert_eq!(
&*strip_windows_verbatim_prefix(r"\\?\Volume{01234567-89ab-cdef-0123-456789abcdef}\m"),
r"\\?\Volume{01234567-89ab-cdef-0123-456789abcdef}\m"
);
assert_eq!(
&*strip_windows_verbatim_prefix(r"\\?\GLOBALROOT\Device\HarddiskVolume1\m"),
r"\\?\GLOBALROOT\Device\HarddiskVolume1\m"
);
assert_eq!(
&*strip_windows_verbatim_prefix(r"\\.\PhysicalDrive0"),
r"\\.\PhysicalDrive0"
);
assert_eq!(
&*strip_windows_verbatim_prefix(r"\\?\C:relative\m"),
r"\\?\C:relative\m"
);
}
}