Skip to content

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

Rust

feat(run): add named launch environment profiles

AkitaOnRails1614306c2f32
diff --git a/CHANGELOG.md b/CHANGELOG.md
index fd4bbeca..0df9a167 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -8,6 +8,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
## [Unreleased]
### Added
+- Added env-only named launch profiles for `ai-memory run --profile NAME` via
+ `[run.profiles.<name>.env]` in `config.toml`. Profile values feed the same
+ native-session, auto-wire, and child-process environment path as `--env`;
+ precedence is profile, then `--env-file`, then repeated `--env`. Unknown or
+ invalid profiles fail before a workstream lease or child process. (#922)
- Added cross-project attribution for native lifecycle file-tool events whose
harness keeps reporting the parent session's cwd. A bounded, recognized
absolute target reroutes only when every path proves the same repository or
diff --git a/README.md b/README.md
index 2b294e38..8812b74c 100644
--- a/README.md
+++ b/README.md
@@ -364,6 +364,7 @@ config home.
```bash
ai-memory run claude
ai-memory run codex --yolo # later: same workstream, different harness
+ai-memory run --profile work claude # reusable config.toml env/account preset
ai-memory continue # resume the newest managed checkout
```
diff --git a/crates/ai-memory-cli/src/cli.rs b/crates/ai-memory-cli/src/cli.rs
index 7ca8b3c0..44ca8a6f 100644
--- a/crates/ai-memory-cli/src/cli.rs
+++ b/crates/ai-memory-cli/src/cli.rs
@@ -6,6 +6,88 @@ use std::path::PathBuf;
use clap::{Args, Parser, Subcommand};
use clap_complete::Shell;
+/// Parse the process argv while making the documented `run` boundary real:
+/// once the harness positional appears, every later token is native argv.
+///
+/// Clap normally keeps recognizing known wrapper flags after a positional,
+/// even with `trailing_var_arg`. That would steal OMP's native `--profile`
+/// as the launch-profile selector. Inserting clap's ordinary `--` delimiter
+/// after the harness keeps the public no-delimiter UX and makes all existing
+/// wrapper-after-harness recovery (`--yolo`, `--fresh`, etc.) explicit in the
+/// run command rather than dependent on clap's option-name knowledge.
+pub(crate) fn parse_process() -> Cli {
+ try_parse_from(std::env::args_os()).unwrap_or_else(|error| error.exit())
+}
+
+pub(crate) fn try_parse_from<I, T>(args: I) -> Result<Cli, clap::Error>
+where
+ I: IntoIterator<Item = T>,
+ T: Into<OsString> + Clone,
+{
+ let mut args = args.into_iter().map(Into::into).collect::<Vec<_>>();
+ delimit_run_native_args(&mut args);
+ Cli::try_parse_from(args)
+}
+
+fn delimit_run_native_args(args: &mut Vec<OsString>) {
+ let mut index = 1;
+ let run_index = loop {
+ let Some(raw) = args.get(index).and_then(|arg| arg.to_str()) else {
+ return;
+ };
+ if matches!(raw, "--data-dir" | "--config") {
+ index += 2;
+ continue;
+ }
+ if raw.starts_with("--data-dir=") || raw.starts_with("--config=") {
+ index += 1;
+ continue;
+ }
+ if raw == "run" {
+ break index;
+ }
+ return;
+ };
+
+ index = run_index + 1;
+ while index < args.len() {
+ let Some(raw) = args[index].to_str() else {
+ return;
+ };
+ if raw == "--" {
+ return;
+ }
+ let key = raw.split_once('=').map_or(raw, |(key, _)| key);
+ let takes_separate_value = matches!(
+ key,
+ "--workspace"
+ | "--project"
+ | "--workstream"
+ | "--new"
+ | "--executable"
+ | "--profile"
+ | "--env"
+ | "--env-file"
+ | "--data-dir"
+ | "--config"
+ ) && !raw.contains('=');
+ if takes_separate_value {
+ index += 2;
+ continue;
+ }
+ if raw.starts_with('-') {
+ index += 1;
+ continue;
+ }
+
+ // No trailing tokens means there is nothing for clap to steal.
+ if index + 1 < args.len() {
+ args.insert(index + 1, OsString::from("--"));
+ }
+ return;
+ }
+}
+
/// Top-level CLI for the `ai-memory` binary.
#[derive(Debug, Parser)]
#[command(name = "ai-memory", version, about, long_about = None)]
@@ -343,6 +425,11 @@ pub struct RunArgs {
/// `AI_MEMORY_RUN_AUTOWIRE=false`) to launch without touching harness config.
#[arg(long)]
pub no_autowire: bool,
+ /// Apply a named env-only launch profile from
+ /// `[run.profiles.<name>.env]` in config.toml. Must precede `harness`;
+ /// a later `--env-file` or `--env` entry wins on the same key.
+ #[arg(long, value_name = "NAME")]
+ pub profile: Option<String>,
/// Extra environment variable for the spawned harness, `KEY=VALUE`.
/// Repeatable; wrapper-owned like `--yolo`/`--executable`, so it must
/// precede `harness`. Reaches the spawned process, ai-memory's own
diff --git a/crates/ai-memory-cli/src/commands/continue_session.rs b/crates/ai-memory-cli/src/commands/continue_session.rs
index f5a75533..8dbfae81 100644
--- a/crates/ai-memory-cli/src/commands/continue_session.rs
+++ b/crates/ai-memory-cli/src/commands/continue_session.rs
@@ -77,6 +77,7 @@ pub async fn run(config: &Config, args: ContinueArgs) -> Result<i32> {
no_jail: false,
fresh: args.fresh,
no_autowire: false,
+ profile: None,
env: Vec::new(),
env_file: None,
// Bare mode: `run` resolves the harness that owns the newest
diff --git a/crates/ai-memory-cli/src/commands/resume.rs b/crates/ai-memory-cli/src/commands/resume.rs
index be4d5612..263d31a2 100644
--- a/crates/ai-memory-cli/src/commands/resume.rs
+++ b/crates/ai-memory-cli/src/commands/resume.rs
@@ -166,6 +166,7 @@ pub async fn run(config: &Config, args: ResumeArgs) -> Result<i32> {
no_jail: false,
fresh: args.fresh,
no_autowire: false,
+ profile: None,
env: Vec::new(),
env_file: None,
harness,
diff --git a/crates/ai-memory-cli/src/commands/run.rs b/crates/ai-memory-cli/src/commands/run.rs
index 82155294..d6796878 100644
--- a/crates/ai-memory-cli/src/commands/run.rs
+++ b/crates/ai-memory-cli/src/commands/run.rs
@@ -330,8 +330,19 @@ async fn run_once_with_wiring(
let yolo_requested = yolo_modes.yolo;
let force_fresh = args.fresh || trailing_fresh;
let no_autowire = args.no_autowire || trailing_no_autowire;
- let run_env = resolve_run_env(args.env_file.as_deref(), &args.env)
- .context("resolving --env/--env-file for the managed run")?;
+ let profile = args
+ .profile
+ .as_deref()
+ .map(|name| {
+ config
+ .run
+ .profiles
+ .get(name)
+ .ok_or_else(|| anyhow!("unknown run profile {name:?}"))
+ })
+ .transpose()?;
+ let run_env = resolve_run_env(profile, args.env_file.as_deref(), &args.env)
+ .context("resolving --profile/--env-file/--env for the managed run")?;
if automatic_harness && !native_args.is_empty() {
return Err(anyhow!(
"native harness arguments require an explicit harness; try `ai-memory run codex ...`"
@@ -1829,10 +1840,16 @@ fn remove_wrapper_no_autowire(args: &mut Vec<OsString>) -> bool {
/// `--env` entry override a same-key `--env-file` line. Values are taken
/// literally; neither source is expanded or interpreted.
fn resolve_run_env(
+ profile: Option<&crate::config::RunProfile>,
env_file: Option<&Path>,
env_args: &[(String, String)],
) -> Result<Vec<(String, String)>> {
let mut merged: Vec<(String, String)> = Vec::new();
+ if let Some(profile) = profile {
+ for (key, value) in &profile.env {
+ upsert_env(&mut merged, key.clone(), value.clone());
+ }
+ }
if let Some(path) = env_file {
let contents = std::fs::read_to_string(path)
.with_context(|| format!("reading --env-file {}", path.display()))?;
@@ -2842,7 +2859,7 @@ mod tests {
}
fn parse_run(argv: &[&str]) -> RunArgs {
- let CliCommand::Run(args) = Cli::try_parse_from(argv).unwrap().command else {
+ let CliCommand::Run(args) = crate::cli::try_parse_from(argv).unwrap().command else {
panic!("expected run command");
};
args
@@ -3169,6 +3186,7 @@ mod tests {
no_jail: true,
fresh: true,
no_autowire: true,
+ profile: Some("work".into()),
env: vec![("MODEL_HOME".into(), "custom".into())],
env_file: None,
harness: Some(RunHarnessChoice::Claude),
@@ -4344,27 +4362,92 @@ mod tests {
}
#[test]
- fn resolve_run_env_merges_file_then_overrides_with_cli_pairs() {
+ fn resolve_run_env_merges_profile_file_then_cli_pairs() {
let dir = tempfile::tempdir().unwrap();
let path = dir.path().join("vars.env");
std::fs::write(&path, "# a comment\n\n \nFOO=from-file\nBAR=keep\n").unwrap();
+ let profile = crate::config::RunProfile {
+ env: [
+ ("FOO".to_string(), "from-profile".to_string()),
+ ("PROFILE_ONLY".to_string(), "present".to_string()),
+ ]
+ .into(),
+ };
let cli_pairs = vec![("FOO".to_string(), "from-cli".to_string())];
- let merged = resolve_run_env(Some(&path), &cli_pairs).unwrap();
+ let merged = resolve_run_env(Some(&profile), Some(&path), &cli_pairs).unwrap();
assert_eq!(
merged,
vec![
("FOO".to_string(), "from-cli".to_string()),
+ ("PROFILE_ONLY".to_string(), "present".to_string()),
("BAR".to_string(), "keep".to_string()),
]
);
}
+ #[test]
+ fn wrapper_profile_parses_before_harness_without_stealing_native_profile() {
+ let wrapper = parse_run(&[
+ "ai-memory",
+ "run",
+ "--profile",
+ "work",
+ "claude",
+ "--model",
+ "opus",
+ ]);
+ assert_eq!(wrapper.profile.as_deref(), Some("work"));
+ assert_eq!(wrapper.native_args, ["--model", "opus"].map(OsString::from));
+
+ let native = parse_run(&["ai-memory", "run", "omp", "--profile", "omp-work"]);
+ assert_eq!(native.profile, None);
+ assert_eq!(
+ native.native_args,
+ ["--profile", "omp-work"].map(OsString::from)
+ );
+ }
+
+ #[tokio::test]
+ async fn unknown_run_profile_fails_before_server_or_child_work() {
+ let tmp = tempfile::tempdir().unwrap();
+ let mut config = Config::load(None, Some(tmp.path().join("data"))).unwrap();
+ config.server_url = "http://127.0.0.1:1".into();
+ let args = RunArgs {
+ workspace: None,
+ project: None,
+ workstream: None,
+ new_workstream: None,
+ executable: Some(PathBuf::from("definitely-not-a-harness")),
+ yolo: false,
+ true_yolo: false,
+ jail: None,
+ no_jail: true,
+ fresh: false,
+ no_autowire: true,
+ profile: Some("missing".into()),
+ env: Vec::new(),
+ env_file: None,
+ harness: Some(RunHarnessChoice::Claude),
+ native_args: Vec::new(),
+ };
+
+ let error = run_from_with_wiring(
+ &config,
+ args,
+ tmp.path(),
+ &super::super::run_autowire::WireOverrides::default(),
+ )
+ .await
+ .unwrap_err();
+ assert_eq!(error.to_string(), "unknown run profile \"missing\"");
+ }
+
#[test]
fn resolve_run_env_without_a_file_returns_only_cli_pairs() {
let cli_pairs = vec![("A".to_string(), "1".to_string())];
- let merged = resolve_run_env(None, &cli_pairs).unwrap();
+ let merged = resolve_run_env(None, None, &cli_pairs).unwrap();
assert_eq!(merged, vec![("A".to_string(), "1".to_string())]);
}
@@ -4373,7 +4456,7 @@ mod tests {
let dir = tempfile::tempdir().unwrap();
let path = dir.path().join("bad.env");
std::fs::write(&path, "NOVALUE\n").unwrap();
- let error = resolve_run_env(Some(&path), &[]).unwrap_err();
+ let error = resolve_run_env(None, Some(&path), &[]).unwrap_err();
assert!(
error.to_string().contains("expected KEY=VALUE"),
"unexpected error: {error}"
@@ -4453,7 +4536,7 @@ mod tests {
std::fs::write(
&script,
format!(
- "#!/bin/sh\nprintf 'FOO=%s\\nCLAUDE_CONFIG_DIR=%s\\n' \"$FOO\" \"$CLAUDE_CONFIG_DIR\" > {}\nexit 0\n",
+ "#!/bin/sh\nprintf 'FOO=%s\\nPROFILE_ONLY=%s\\nCLAUDE_CONFIG_DIR=%s\\n' \"$FOO\" \"$PROFILE_ONLY\" \"$CLAUDE_CONFIG_DIR\" > {}\nexit 0\n",
captured.display()
),
)
@@ -4472,6 +4555,17 @@ mod tests {
config.home_dir = Some(home.path().to_string_lossy().into_owned());
config.server_url = format!("http://{address}");
config.run_autowire = false;
+ config.run.profiles.insert(
+ "work".into(),
+ crate::config::RunProfile {
+ env: [
+ ("FOO".into(), "from-profile".into()),
+ ("PROFILE_ONLY".into(), "from-profile".into()),
+ ("CLAUDE_CONFIG_DIR".into(), "/from/profile".into()),
+ ]
+ .into(),
+ },
+ );
let args = RunArgs {
workspace: Some("ws".into()),
@@ -4485,6 +4579,7 @@ mod tests {
no_jail: false,
fresh: false,
no_autowire: true,
+ profile: Some("work".into()),
env: vec![("CLAUDE_CONFIG_DIR".to_string(), "/from/cli".to_string())],
env_file: Some(env_file.clone()),
harness: Some(RunHarnessChoice::Claude),
@@ -4500,7 +4595,11 @@ mod tests {
let captured_env = std::fs::read_to_string(&captured).unwrap();
assert!(
captured_env.contains("FOO=from-file"),
- "an --env-file entry not overridden by --env must reach the spawned child: {captured_env}"
+ "--env-file must override the profile and reach the spawned child: {captured_env}"
+ );
+ assert!(
+ captured_env.contains("PROFILE_ONLY=from-profile"),
+ "a profile-only entry must reach the spawned child: {captured_env}"
);
assert!(
captured_env.contains("CLAUDE_CONFIG_DIR=/from/cli"),
@@ -4973,6 +5072,7 @@ mod tests {
no_jail: false,
fresh: false,
no_autowire: false,
+ profile: None,
env: Vec::new(),
env_file: None,
harness: Some(RunHarnessChoice::Claude),
@@ -5128,6 +5228,7 @@ mod tests {
no_jail: false,
fresh: false,
no_autowire: false,
+ profile: None,
env,
env_file: None,
harness: Some(harness),
diff --git a/crates/ai-memory-cli/src/commands/show.rs b/crates/ai-memory-cli/src/commands/show.rs
index eed58467..6e949e81 100644
--- a/crates/ai-memory-cli/src/commands/show.rs
+++ b/crates/ai-memory-cli/src/commands/show.rs
@@ -230,6 +230,7 @@ pub async fn run(config: &Config, args: ShowArgs) -> Result<i32> {
no_jail: false,
fresh: args.fresh,
no_autowire: false,
+ profile: None,
env: Vec::new(),
env_file: None,
harness: Some(harness),
diff --git a/crates/ai-memory-cli/src/config.rs b/crates/ai-memory-cli/src/config.rs
index 5717ba4a..84b78cc6 100644
--- a/crates/ai-memory-cli/src/config.rs
+++ b/crates/ai-memory-cli/src/config.rs
@@ -6,6 +6,7 @@
//! guard read `process.env` while the rest of the codebase used
//! `getMergedEnv()`, masking the bug for weeks).
+use std::collections::{BTreeMap, HashSet};
use std::path::{Path, PathBuf};
use std::sync::Arc;
@@ -406,6 +407,11 @@ pub struct Config {
/// per harness and config home. Turn off with `AI_MEMORY_RUN_AUTOWIRE=false` /
/// `run_autowire = false`, or per launch with `ai-memory run --no-autowire`.
pub run_autowire: bool,
+ /// Named, env-only presets for `ai-memory run --profile NAME`.
+ /// Profiles deliberately do not carry executable paths, native argv, or
+ /// permission-bypass flags. Configure them under `[run.profiles.<name>.env]`.
+ #[serde(default)]
+ pub run: RunSettings,
/// Off by default. When true, a Claude `ai-memory run --yolo` additionally
/// applies [`apply_claude_true_yolo`](ai_memory_workstream::apply_claude_true_yolo),
/// injecting `--settings` that forces `bypassPermissions` over any
@@ -971,6 +977,7 @@ impl Default for Config {
capture_assistant: false,
backfill_on_start: true,
run_autowire: true,
+ run: RunSettings::default(),
claude_true_yolo: false,
strip_root_combinators: false,
gemini_safe_schemas: false,
@@ -1006,6 +1013,68 @@ impl Default for Config {
}
}
+/// `[run]` settings for the managed harness launcher.
+#[derive(Debug, Clone, Default, Serialize, Deserialize)]
+#[serde(default, deny_unknown_fields)]
+pub struct RunSettings {
+ /// Persisted env-only launch profiles, selected with `run --profile`.
+ pub profiles: BTreeMap<String, RunProfile>,
+}
+
+/// One named managed-launch preset.
+#[derive(Debug, Clone, Default, Serialize, Deserialize)]
+#[serde(default, deny_unknown_fields)]
+pub struct RunProfile {
+ /// Environment overrides applied before `--env-file` and `--env`.
+ pub env: BTreeMap<String, String>,
+}
+
+fn validate_run_profiles(run: &RunSettings) -> Result<()> {
+ const MAX_PROFILES: usize = 128;
+ const MAX_PROFILE_NAME: usize = 64;
+ const MAX_ENV_PER_PROFILE: usize = 128;
+ const MAX_ENV_KEY: usize = 256;
+ const MAX_ENV_VALUE: usize = 64 * 1024;
+
+ if run.profiles.len() > MAX_PROFILES {
+ anyhow::bail!("run.profiles may contain at most {MAX_PROFILES} profiles");
+ }
+ for (name, profile) in &run.profiles {
+ if name.is_empty()
+ || name.len() > MAX_PROFILE_NAME
+ || !name
+ .bytes()
+ .all(|byte| byte.is_ascii_alphanumeric() || matches!(byte, b'.' | b'_' | b'-'))
+ {
+ anyhow::bail!(
+ "invalid run profile name {name:?}; use 1-{MAX_PROFILE_NAME} ASCII letters, digits, '.', '_' or '-'"
+ );
+ }
+ if profile.env.len() > MAX_ENV_PER_PROFILE {
+ anyhow::bail!(
+ "run profile {name:?} may contain at most {MAX_ENV_PER_PROFILE} environment entries"
+ );
+ }
+ let mut folded = HashSet::with_capacity(profile.env.len());
+ for (key, value) in &profile.env {
+ if key.is_empty() || key.len() > MAX_ENV_KEY || key.contains(['=', '\0']) {
+ anyhow::bail!("run profile {name:?} has invalid environment key {key:?}");
+ }
+ if value.len() > MAX_ENV_VALUE || value.contains('\0') {
+ anyhow::bail!(
+ "run profile {name:?} environment value for {key:?} is invalid or exceeds {MAX_ENV_VALUE} bytes"
+ );
+ }
+ if !folded.insert(key.to_ascii_uppercase()) {
+ anyhow::bail!(
+ "run profile {name:?} repeats environment key {key:?} with different ASCII case"
+ );
+ }
+ }
+ }
+ Ok(())
+}
+
/// `[consolidation]` LLM consolidation prompt sizing.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(default)]
@@ -1746,6 +1815,8 @@ impl Config {
config.data_dir = canonicalise_or_keep(&config.data_dir);
config.runtime_env = runtime_env;
+ validate_run_profiles(&config.run)?;
+
if !config.decay.breadth_weight.is_finite() || config.decay.breadth_weight < 0.0 {
anyhow::bail!(
"decay.breadth_weight must be a finite number greater than or equal to zero"
@@ -4916,6 +4987,34 @@ mod tests {
assert!(Config::default().llm_provider_chain().unwrap().is_none());
}
+ #[test]
+ fn run_profiles_parse_from_config_and_reject_ambiguous_names_and_keys() {
+ let tmp = TempDir::new().unwrap();
+ let config_path = tmp.path().join("config.toml");
+ std::fs::write(
+ &config_path,
+ "[run.profiles.work.env]\nCLAUDE_CONFIG_DIR = '/accounts/work'\nMODEL = 'opus'\n",
+ )
+ .unwrap();
+ let config = Config::load(Some(&config_path), Some(tmp.path().join("data"))).unwrap();
+ assert_eq!(
+ config.run.profiles["work"].env["CLAUDE_CONFIG_DIR"],
+ "/accounts/work"
+ );
+
+ std::fs::write(&config_path, "[run.profiles.'bad name'.env]\nFOO = 'bar'\n").unwrap();
+ let error = Config::load(Some(&config_path), Some(tmp.path().join("data"))).unwrap_err();
+ assert!(error.to_string().contains("invalid run profile name"));
+
+ std::fs::write(
+ &config_path,
+ "[run.profiles.work.env]\nPATH = '/one'\nPath = '/two'\n",
+ )
+ .unwrap();
+ let error = Config::load(Some(&config_path), Some(tmp.path().join("data"))).unwrap_err();
+ assert!(error.to_string().contains("different ASCII case"));
+ }
+
#[test]
fn anthropic_oauth_provider_underscore_alias_also_resolves() {
let cfg = Config {
diff --git a/crates/ai-memory-cli/src/lib.rs b/crates/ai-memory-cli/src/lib.rs
index 1fe1d9dd..f90ad8b5 100644
--- a/crates/ai-memory-cli/src/lib.rs
+++ b/crates/ai-memory-cli/src/lib.rs
@@ -16,7 +16,6 @@
use std::sync::Arc;
use anyhow::Result;
-use clap::Parser;
use tracing::info;
mod auth_bearer;
@@ -43,7 +42,7 @@ pub async fn run() -> Result<()> {
data_dir,
config: config_path,
command,
- } = Cli::parse();
+ } = cli::parse_process();
// Hooks fire on every tool call: they must be cheap and must emit ONLY
// their JSON object to stdout. Short-circuit before config load and
diff --git a/crates/ai-memory-cli/templates/config.default.toml b/crates/ai-memory-cli/templates/config.default.toml
index 32b01ab6..b367110e 100644
--- a/crates/ai-memory-cli/templates/config.default.toml
+++ b/crates/ai-memory-cli/templates/config.default.toml
@@ -18,6 +18,14 @@ allowed_hosts = ["localhost", "127.0.0.1", "::1"]
# Default tracing filter (overridable by RUST_LOG).
log_level = "info"
+# Optional env-only presets for managed harness launches. Select one with
+# `ai-memory run --profile work claude`. `--env-file` overrides the profile,
+# and repeated `--env` entries override both. Keep executable paths, native
+# argv, and permission-bypass choices on the command line.
+# [run.profiles.work.env]
+# CLAUDE_CONFIG_DIR = "/home/me/.claude-work"
+# ANTHROPIC_BASE_URL = "https://api.anthropic.com"
+
# Optional server-side hook ingest limiter for shared/remote installs. The rate
# is tokens per second per actor/session source; 0 or unset disables it. Burst
# defaults to the rate (minimum one token when enabled). Env equivalents:
diff --git a/docs/managed-workstreams.md b/docs/managed-workstreams.md
index 0560195c..96eac8f5 100644
--- a/docs/managed-workstreams.md
+++ b/docs/managed-workstreams.md
@@ -32,6 +32,37 @@ accounts by alias, put a same-named script or shim earlier on `PATH` instead
(or pass `--executable PATH`, which also resolves a bare name through
`PATH`), so the resolved `claude` process actually is the one you meant.
+**Named launch profiles.** Persist repeated per-account environment overrides
+in the same `config.toml` the client loads:
+
+```toml
+[run.profiles.work.env]
+CLAUDE_CONFIG_DIR = "/home/me/.claude-work"
+ANTHROPIC_BASE_URL = "https://api.anthropic.com"
+```
+
+```bash
+ai-memory run --profile work claude --model opus
+```
+
+Profiles are env-only by design; executable paths, native arguments, `--yolo`,
+and auto-wire choices stay explicit on the command line. The child inherits
+the normal process environment, then profile values override it,
+`--env-file` overrides the profile, and repeated `--env` entries win last.
+The resolved values also drive native-session discovery and auto-wire, so all
+three use the same account/config home. An unknown or invalid profile fails
+before ai-memory takes a workstream lease or starts a harness. Profile names
+use up to 64 ASCII letters, digits, `.`, `_`, or `-`; each profile may contain
+up to 128 environment entries. Because values are literal and may include
+credentials, protect `config.toml` like any other local secret-bearing config.
+
+`--profile` is wrapper-owned only before the harness name. A later flag remains
+native argv, which keeps OMP's own profile selector unambiguous:
+
+```bash
+ai-memory run --profile work omp --profile omp-work
+```
+
**Multiple Claude accounts (e.g. Corporate and Personal).** Any harness name
starting with `claude` is accepted (`claude-corp`, `claude-personal`, ...)
and always selects the Claude harness — the exact spelling never changes
@@ -101,7 +132,8 @@ file, and the current checkout remain authoritative.
```text
ai-memory run [--workspace NAME] [--project NAME]
[--workstream NAME | --new NAME] [--executable PATH]
- [--yolo] [--fresh] [--env KEY=VALUE]... [--env-file PATH]
+ [--yolo] [--fresh] [--profile NAME]
+ [--env KEY=VALUE]... [--env-file PATH]
[claude|claude*|codex|opencode|opencode2|pi|crush|omp|kimi|command-code|kiro|grok|antigravity]
[native arguments...]
```