Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors
Rust
feat(setup): explain each detected agent, pick a subset, print the plan as JSON
AkitaOnRailse8e698cb5bac
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex ea4e8d10..4389819c 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -32,6 +32,23 @@ version in [`docs/changelog/`](docs/changelog/):and tier both ignore case, a nonstandard kind is flagged on an emptyresult, and "Search all projects" keeps the filters. An unknown `tier` isa 400. (#1248)+- Added `ai-memory setup --plan`, which prints the plan and changes nothing,+ and `--plan --json`, which prints it as a JSON document with a `format`+ version for a script or front end to render. The plan now says what each+ detected agent was found by (its session store, its MCP config, or Muse's+ directory), numbers the agents, and lists the other agents `--agent`+ accepts. At the prompt you can type the numbers of the agents to wire+ instead of `y`; a number outside the plan changes nothing. (#1270)++### Changed+- `ai-memory setup` now ends by naming the agents to restart and the question+ to ask one of them, "What do you remember about this project?", instead of+ a generic restart line. `install.sh` names the link's full path in its+ `next:` line when `~/.local/bin` is not on `PATH`, so the suggested command+ no longer fails with "command not found". The AUR install and upgrade+ messages, and the README Fedora, Arch and macOS app steps, point to+ `ai-memory setup` instead of the manual `init`, `systemctl` and+ `install-*` commands. (#1270)### Fixed- Fixed Windows capture dropping the body of file and shell tool eventsdiff --git a/README.md b/README.mdindex 65c4a6f4..2337a411 100644--- a/README.md+++ b/README.md@@ -211,8 +211,11 @@ and links `~/.local/bin/ai-memory`. `ai-memory setup` then creates the datadirectory with a bearer token in an owner-only file, starts a per-user service(systemd `--user` or a launchd LaunchAgent), and wires MCP, hooks and AgentSkills for every agent it finds, or the ones you name with `--agent`. It shows-the plan and asks first; `--yes` skips the question, and running it again-changes nothing. Restart your agents afterwards. Details, the environment+the plan, with where it found each agent, and asks first: answer `y`, or type+the numbers of the agents to wire. `--plan` prints the plan and changes+nothing, `--yes` skips the question, and running it again changes nothing.+Afterwards, restart your agents and ask one of them "What do you remember+about this project?" to see it answer through ai-memory. Details, the environmentvariables and how to verify the script before running it are in[`docs/install.md`](docs/install.md#one-step-native-install-installsh--ai-memory-setup).An AI agent installing ai-memory for you can follow@@ -238,6 +241,7 @@ user-level systemd units.```bashyay -S ai-memory-bin # prebuilt Linux x86_64/aarch64 binaryyay -S ai-memory # builds from source+ai-memory setup # data dir, user service, agents, self-check```### Fedora (RPM)@@ -250,17 +254,12 @@ then install it:sudo dnf install ./ai-memory-*.rpm```-Then follow the native Linux service instructions in [`docs/install.md`](docs/install.md).--Single-user workstation:+On a single-user workstation, `ai-memory setup` then does the rest, as on the+two-command path above: data dir and token, a user service, the agents it+finds, and a self-check.```bash-mkdir -p ~/.config/ai-memory ~/.local/share/ai-memory-ai-memory --data-dir ~/.local/share/ai-memory \- --config ~/.config/ai-memory/config.toml init-systemctl --user enable --now ai-memory.service-ai-memory install-mcp --client claude-code --apply-ai-memory install-hooks --agent claude-code --apply+ai-memory setup```System service installs use `/var/lib/ai-memory` and `/etc/ai-memory/` via the@@ -287,12 +286,12 @@ open "companions/ai-memory-macos/dist/AI Memory.app"Drag **AI Memory.app** to `/Applications`, then **Install & Start Server**from the menu extra (no Dock icon). The app reads the bearer token `init`wrote into its data dir, so the status item turns green on its own. Then wire-an agent with the bundled binary:+your agents with the bundled binary; `--no-service` leaves the app's+LaunchAgent in charge:```bashBIN="/Applications/AI Memory.app/Contents/Resources/runtime/ai-memory"-"$BIN" install-mcp --client claude-code --apply-"$BIN" install-hooks --agent claude-code --apply+"$BIN" setup --no-service```Prebuilt tarball and launchd-without-the-app paths:diff --git a/crates/ai-memory-cli/src/cli.rs b/crates/ai-memory-cli/src/cli.rsindex 66232bd4..b787cdda 100644--- a/crates/ai-memory-cli/src/cli.rs+++ b/crates/ai-memory-cli/src/cli.rs@@ -1975,6 +1975,15 @@ pub struct SetupArgs {/// already runs some other way (Docker, a packaged system unit).#[arg(long)]pub no_service: bool,+ /// Print the plan and change nothing: what would be created, which+ /// agents would be wired and why each was detected, and which supported+ /// agents are not in the plan.+ #[arg(long, conflicts_with = "yes")]+ pub plan: bool,+ /// With `--plan`, print the plan as a JSON document (its `format` field+ /// names the layout version) for a script or front end to render.+ #[arg(long, requires = "plan")]+ pub json: bool,}/// Arguments for `status`.diff --git a/crates/ai-memory-cli/src/commands/setup.rs b/crates/ai-memory-cli/src/commands/setup.rsindex d9bf6ce1..95d4676a 100644--- a/crates/ai-memory-cli/src/commands/setup.rs+++ b/crates/ai-memory-cli/src/commands/setup.rs@@ -21,8 +21,11 @@//! they do when run by hand.//!//! Every step is idempotent, so a second `setup` changes nothing. Without-//! `--yes` the plan is shown first and confirmed on a terminal; with no-//! terminal to ask on, `setup` changes nothing and exits non-zero.+//! `--yes` the plan is shown first and confirmed on a terminal, where the+//! operator can also pick which of the planned agents to wire; with no+//! terminal to ask on, `setup` changes nothing and exits non-zero. `--plan`+//! prints the plan (as JSON with `--json`, for a front end to render) and+//! changes nothing.use std::collections::BTreeSet;use std::ffi::OsString;@@ -50,6 +53,14 @@ const SERVICE_READY_TIMEOUT: Duration = Duration::from_secs(30);/// The MCP entry name every installer writes by default.const ENTRY_NAME: &str = "ai-memory";+/// What `setup` tells the operator to ask a restarted agent: answering it+/// takes a call to ai-memory's tools, so the reply shows the wiring works.+const FIRST_QUESTION: &str = "What do you remember about this project?";++/// Bumped when a field of the `--plan --json` document changes meaning or+/// goes away; adding a field does not bump it.+const PLAN_FORMAT: u32 = 1;+/// Harnesses that share a native store with another one, so finding the store/// cannot tell them apart: OpenCode 2 shares OpenCode's, and the Kiro CLI v3/// engine's store contains the v2 engine's. Wiring both would write two@@ -77,9 +88,12 @@ enum ServicePlan {Skip(String),}-#[derive(Debug, Clone, Copy, PartialEq, Eq)]+#[derive(Debug, Clone, PartialEq, Eq)]struct AgentPlan {agent: AgentChoice,+ /// Where detection found the agent; `None` when it was named with+ /// `--agent`.+ found: Option<Found>,mcp: Option<McpClient>,skills: InstallSkillsAgent,/// The ai-memory marketplace plugin is enabled for this agent: it carries@@ -87,10 +101,31 @@ struct AgentPlan {plugin: bool,}+/// The evidence detection found an agent by, shown in the plan so the+/// operator can tell why an agent is listed before agreeing to wire it.+#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize)]+#[serde(tag = "kind", content = "path", rename_all = "snake_case")]+enum Found {+ SessionStore(PathBuf),+ McpConfig(PathBuf),+ ConfigDir(PathBuf),+}++impl Found {+ fn describe(&self) -> String {+ match self {+ Self::SessionStore(path) => format!("found its session store at {}", path.display()),+ Self::McpConfig(path) => format!("found its MCP config at {}", path.display()),+ Self::ConfigDir(path) => format!("found its directory at {}", path.display()),+ }+ }+}+impl AgentPlan {- fn new(agent: AgentChoice) -> Self {+ fn new(agent: AgentChoice, found: Option<Found>) -> Self {Self {agent,+ found,mcp: install_hooks::mcp_client_for_agent(agent),skills: skills_for(agent),plugin: false,@@ -98,7 +133,12 @@ impl AgentPlan {}/// [`Self::new`], with the plugin state of `agent` under `home`.- fn detect(agent: AgentChoice, home: &Path, env: &dyn Fn(&str) -> Option<OsString>) -> Self {+ fn detect(+ agent: AgentChoice,+ found: Option<Found>,+ home: &Path,+ env: &dyn Fn(&str) -> Option<OsString>,+ ) -> Self {let harness = match agent {AgentChoice::ClaudeCode => Some(agent_plugins::PluginHarness::ClaudeCode),AgentChoice::Codex => Some(agent_plugins::PluginHarness::Codex),@@ -107,9 +147,26 @@ impl AgentPlan {Self {plugin: harness.is_some_and(|harness| agent_plugins::enabled(harness, home, env).is_some()),- ..Self::new(agent)+ ..Self::new(agent, found)}}++ fn wiring(&self) -> &'static str {+ match (self.plugin, self.mcp.is_some()) {+ (true, _) => "plugin",+ (false, true) => "mcp+hooks+skills",+ (false, false) => "hooks+skills",+ }+ }+}++/// The `--agent` spelling of an agent, as `--help` lists it.+fn agent_name(agent: AgentChoice) -> String {+ use clap::ValueEnum as _;+ agent.to_possible_value().map_or_else(+ || agent.kind().as_str().to_owned(),+ |value| value.get_name().to_owned(),+ )}/// The skill directory family an agent reads; agents without one of their@@ -154,18 +211,24 @@ pub async fn run(config: &Config, args: SetupArgs, config_path: Option<&Path>) -let exe = service_exe(&exe, &env);let written_config = init_config_path(config, config_path);- let agents = if args.agents.is_empty() {+ let agents: Vec<(AgentChoice, Option<Found>)> = if args.agents.is_empty() {let mut found = detect_agents(&home,&|harness| doctor::relocated_session_dir_with(harness, &env),&|client| install_mcp::mcp_config_path_with(client, &env).ok(),);- if muse_detected(&home, &env) {- found.push(AgentChoice::Muse);+ if let Some(dir) = muse_detected(&home, &env) {+ found.push((AgentChoice::Muse, Found::ConfigDir(dir)));}found+ .into_iter()+ .map(|(agent, found)| (agent, Some(found)))+ .collect()} else {dedup(args.agents.iter().copied())+ .into_iter()+ .map(|agent| (agent, None))+ .collect()};let service = if args.no_service {ServicePlan::Skip("skipped (--no-service)".to_owned())@@ -188,21 +251,28 @@ pub async fn run(config: &Config, args: SetupArgs, config_path: Option<&Path>) -reachable,)};- let plan = SetupPlan {+ let mut plan = SetupPlan {data_dir: config.data_dir.clone(),fresh: !written_config.exists(),config_path: written_config,service,agents: agents.into_iter()- .map(|agent| AgentPlan::detect(agent, &home, &env))+ .map(|(agent, found)| AgentPlan::detect(agent, found, &home, &env)).collect(),detected: args.agents.is_empty(),};+ if args.json {+ println!("{}", serde_json::to_string_pretty(&plan_document(&plan))?);+ return Ok(());+ }print_plan(&plan);+ if args.plan {+ return Ok(());+ }if !args.yes {- confirm()?;+ plan.agents = choose_agents(confirm(plan.agents.len())?, plan.agents);}execute(config,@@ -218,7 +288,7 @@ fn init_config_path(config: &Config, explicit: Option<&Path>) -> PathBuf {explicit.map_or_else(|| config.data_dir.join("config.toml"), Path::to_path_buf)}-fn dedup(agents: impl Iterator<Item = AgentChoice>) -> Vec<AgentChoice> {+fn dedup<T: PartialEq>(agents: impl Iterator<Item = T>) -> Vec<T> {let mut seen = Vec::new();for agent in agents {if !seen.contains(&agent) {@@ -229,25 +299,51 @@ fn dedup(agents: impl Iterator<Item = AgentChoice>) -> Vec<AgentChoice> {}/// The agents to wire when none was named: every harness `doctor` scans whose-/// session store exists, or whose MCP config file does, under `home`.+/// session store exists, or whose MCP config file does, under `home`, each+/// with the evidence it was found by (the store when both exist).fn detect_agents(home: &Path,session_dir_for: &dyn Fn(ManagedHarness) -> Option<PathBuf>,mcp_config_for: &dyn Fn(McpClient) -> Option<PathBuf>,-) -> Vec<AgentChoice> {- let found = doctor::SCANNED_HARNESSES+) -> Vec<(AgentChoice, Found)> {+ let mut found: Vec<(AgentChoice, Found)> = Vec::new();+ for harness in doctor::SCANNED_HARNESSES.iter().copied().filter(|harness| !EXPLICIT_ONLY.contains(harness))- .filter_map(|harness| {- let agent = run_autowire::agent_choice_for_harness(harness)?;- let store = native_store_root(harness, home, session_dir_for(harness).as_deref());- let config = install_hooks::mcp_client_for_agent(agent)+ {+ let Some(agent) = run_autowire::agent_choice_for_harness(harness) else {+ continue;+ };+ if found.iter().any(|(seen, _)| *seen == agent) {+ continue;+ }+ let store = native_store_root(harness, home, session_dir_for(harness).as_deref());+ let evidence = if store.is_dir() {+ Some(Found::SessionStore(store))+ } else {+ install_hooks::mcp_client_for_agent(agent).and_then(mcp_config_for)- .is_some_and(|path| path.is_file());- (store.is_dir() || config).then_some(agent)- });- dedup(found)+ .filter(|path| path.is_file())+ .map(Found::McpConfig)+ };+ if let Some(evidence) = evidence {+ found.push((agent, evidence));+ }+ }+ found+}++/// Every agent `setup --agent` accepts that is not in the plan, so an agent+/// detection cannot find (no session store or MCP config to look for) is+/// still one name away.+fn other_agents(planned: &[AgentPlan]) -> Vec<String> {+ use clap::ValueEnum as _;+ AgentChoice::value_variants()+ .iter()+ .filter(|agent| !planned.iter().any(|plan| plan.agent == **agent))+ .map(|agent| agent_name(*agent))+ .collect()}/// Whether Meta Muse Code has run for this user: its config directory@@ -256,7 +352,7 @@ fn detect_agents(/// Muse has no native-session adapter, so it is found by these directories/// rather than by [`detect_agents`]. Each XDG variable counts only when it is/// an absolute path, lexically.-fn muse_detected(home: &Path, env: &dyn Fn(&str) -> Option<OsString>) -> bool {+fn muse_detected(home: &Path, env: &dyn Fn(&str) -> Option<OsString>) -> Option<PathBuf> {let xdg = |name: &str, fallback: &[&str]| {super::path_util::agent_config_home(env(name)).filter(|dir| dir.is_absolute())@@ -267,8 +363,12 @@ fn muse_detected(home: &Path, env: &dyn Fn(&str) -> Option<OsString>) -> bool {}).join("muse")};- xdg("XDG_CONFIG_HOME", &[".config"]).is_dir()- || xdg("XDG_DATA_HOME", &[".local", "share"]).is_dir()+ [+ xdg("XDG_CONFIG_HOME", &[".config"]),+ xdg("XDG_DATA_HOME", &[".local", "share"]),+ ]+ .into_iter()+ .find(|dir| dir.is_dir())}/// The binary path the service unit runs. A package manager's versioned@@ -399,13 +499,16 @@ fn print_plan(plan: &SetupPlan) {"was named"});+ } else {+ println!(" - wire these agents:");}- for agent in &plan.agents {+ for (number, agent) in plan.agents.iter().enumerate() {let name = agent.agent.kind().as_str();+ let number = number + 1;if agent.plugin {println!(- " - leave {name} to its enabled ai-memory plugin ({}), which carries the \- hooks, MCP entry and skills",+ " {number}. {name}: leave it to its enabled ai-memory plugin ({}), which \+ carries the hooks, MCP entry and skills",agent_plugins::PLUGIN_ID);continue;@@ -415,33 +518,179 @@ fn print_plan(plan: &SetupPlan) {} else {"hooks"};+ let why = agent+ .found+ .as_ref()+ .map_or_else(|| "named with --agent".to_owned(), Found::describe);+ println!(" {number}. {name}: {mcp} + skills ({why})");+ }+ println!(" - check /healthz, memory_status and doctor (read-only)");+ let others = other_agents(&plan.agents);+ if !others.is_empty() {println!(- " - wire {name}{}: {mcp} + skills",- if plan.detected { " (detected)" } else { "" }+ "Also supported, not in this plan (add with --agent <name>): {}",+ others.join(", "));}- println!(" - check /healthz, memory_status and doctor (read-only)");}-/// Ask on a terminal; refuse without one.-fn confirm() -> Result<()> {+/// What the operator answered at the prompt.+#[derive(Debug, PartialEq, Eq)]+enum Answer {+ /// Apply the whole plan.+ All,+ /// Apply it with only these agents, as 1-based plan numbers in order.+ Only(Vec<usize>),+}++/// Ask on a terminal; refuse without one. With more than one planned agent+/// the operator may answer with the numbers of the agents to wire.+fn confirm(agents: usize) -> Result<Answer> {if !std::io::stdin().is_terminal() {bail!("nothing was changed: there is no terminal to confirm this plan on. Re-run \`ai-memory setup --yes` to apply it.");}- print!("Proceed? [y/N] ");+ if agents > 1 {+ print!("Proceed? [y/N], or type the numbers of the agents to wire (e.g. 1 3): ");+ } else {+ print!("Proceed? [y/N] ");+ }std::io::stdout().flush().ok();let mut answer = String::new();std::io::stdin().lock().read_line(&mut answer).context("reading the answer")?;- if matches!(answer.trim(), "y" | "Y" | "yes" | "YES" | "Yes") {- Ok(())- } else {- bail!("nothing was changed")+ parse_answer(&answer, agents)+}++/// Read a prompt answer: yes, or (with more than one agent) a list of agent+/// numbers separated by spaces or commas. Anything else declines, and so does+/// a number outside the plan, so a typo never wires an agent nobody chose.+fn parse_answer(answer: &str, agents: usize) -> Result<Answer> {+ let answer = answer.trim();+ if matches!(answer, "y" | "Y" | "yes" | "YES" | "Yes") {+ return Ok(Answer::All);+ }+ let numbers: Vec<&str> = answer+ .split(|c: char| c == ',' || c.is_whitespace())+ .filter(|part| !part.is_empty())+ .collect();+ if agents < 2 || numbers.is_empty() {+ bail!("nothing was changed");+ }+ let mut chosen = Vec::new();+ for part in numbers {+ match part.parse::<usize>() {+ Ok(number) if (1..=agents).contains(&number) => chosen.push(number),+ _ => bail!("nothing was changed: {part} is not an agent number from 1 to {agents}"),+ }+ }+ chosen.sort_unstable();+ Ok(Answer::Only(dedup(chosen.into_iter())))+}++/// The planned agents the answer kept, in plan order.+fn choose_agents(answer: Answer, agents: Vec<AgentPlan>) -> Vec<AgentPlan> {+ match answer {+ Answer::All => agents,+ Answer::Only(numbers) => agents+ .into_iter()+ .enumerate()+ .filter(|(index, _)| numbers.contains(&(index + 1)))+ .map(|(_, agent)| agent)+ .collect(),+ }+}++/// The plan as `setup --plan --json` prints it.+#[derive(Debug, serde::Serialize)]+struct PlanDocument {+ format: u32,+ data_dir: PathBuf,+ config_path: PathBuf,+ fresh: bool,+ service: ServiceDocument,+ agents: Vec<AgentDocument>,+ /// `--agent` names accepted but not in the plan.+ other_agents: Vec<String>,+ checks: [&'static str; 3],+ first_question: &'static str,+}++#[derive(Debug, serde::Serialize)]+#[serde(tag = "action", rename_all = "snake_case")]+enum ServiceDocument {+ Install {+ manager: &'static str,+ path: PathBuf,+ },+ Skip {+ reason: String,+ },+}++#[derive(Debug, serde::Serialize)]+struct AgentDocument {+ agent: String,+ /// `null` when the agent was named with `--agent`.+ found: Option<Found>,+ wiring: &'static str,+}++fn plan_document(plan: &SetupPlan) -> PlanDocument {+ PlanDocument {+ format: PLAN_FORMAT,+ data_dir: plan.data_dir.clone(),+ config_path: plan.config_path.clone(),+ fresh: plan.fresh,+ service: match &plan.service {+ ServicePlan::Install(unit) => ServiceDocument::Install {+ manager: unit.manager.describe(),+ path: unit.path.clone(),+ },+ ServicePlan::Skip(reason) => ServiceDocument::Skip {+ reason: reason.clone(),+ },+ },+ agents: plan+ .agents+ .iter()+ .map(|agent| AgentDocument {+ agent: agent_name(agent.agent),+ found: agent.found.clone(),+ wiring: agent.wiring(),+ })+ .collect(),+ other_agents: other_agents(&plan.agents),+ checks: ["healthz", "memory_status", "doctor"],+ first_question: FIRST_QUESTION,+ }+}++/// The closing line once every step passed: restart the wired agents, then+/// ask one of them something only ai-memory can answer.+fn next_step(agents: &[AgentPlan]) -> String {+ let names: Vec<&str> = agents+ .iter()+ .map(|agent| agent.agent.kind().as_str())+ .collect();+ match names.as_slice() {+ [] => "ai-memory is set up, but no agent is wired; run `ai-memory setup --agent <name>`."+ .to_owned(),+ [one] => format!(+ "ai-memory is set up. Restart {one} so it loads the new hooks and MCP entry, then \+ ask it: \"{FIRST_QUESTION}\" It answers through ai-memory's tools; a new install \+ remembers nothing yet, and every session from now on is captured."+ ),+ many => format!(+ "ai-memory is set up. Restart {} so they load the new hooks and MCP entry, then ask \+ one of them: \"{FIRST_QUESTION}\" It answers through ai-memory's tools; a new \+ install remembers nothing yet, and every session from now on is captured.",+ many.join(", ")+ ),}}@@ -510,7 +759,7 @@ async fn execute(let mut skills_done = BTreeSet::new();for agent in &plan.agents {println!("\n== {}", agent.agent.kind().as_str());- for problem in wire_agent(&config, *agent, &mut skills_done) {+ for problem in wire_agent(&config, agent, &mut skills_done) {problems.push(format!("{}: {problem}", agent.agent.kind().as_str()));}}@@ -530,9 +779,7 @@ async fn execute(println!("{hint}");}if problems.is_empty() {- println!(- "ai-memory is set up. Restart your agents so they load the new hooks and MCP entry."- );+ println!("{}", next_step(&plan.agents));return Ok(());}for problem in &problems {@@ -575,7 +822,11 @@ async fn wait_until_reachable(endpoint: &ServerEndpoint, timeout: Duration) -> b/// first so an OpenCode major-version move has one entry before the hook/// installer reads it (the order `ai-memory run` auto-wire uses). Returns the/// failures.-fn wire_agent(config: &Config, plan: AgentPlan, skills_done: &mut BTreeSet<String>) -> Vec<String> {+fn wire_agent(+ config: &Config,+ plan: &AgentPlan,+ skills_done: &mut BTreeSet<String>,+) -> Vec<String> {let mut problems = Vec::new();if plan.plugin {// Writing the settings-file wiring as well would load every skill@@ -721,22 +972,34 @@ mod tests {fn muse_is_detected_by_its_config_or_data_directory() {let none = |_: &str| -> Option<OsString> { None };let home = tempfile::tempdir().unwrap();- assert!(!muse_detected(home.path(), &none));+ assert_eq!(muse_detected(home.path(), &none), None);std::fs::create_dir_all(home.path().join(".local/share/muse/sessions")).unwrap();- assert!(muse_detected(home.path(), &none));+ assert_eq!(+ muse_detected(home.path(), &none),+ Some(home.path().join(".local/share/muse"))+ );let home = tempfile::tempdir().unwrap();std::fs::create_dir_all(home.path().join(".config/muse")).unwrap();- assert!(muse_detected(home.path(), &none));+ assert_eq!(+ muse_detected(home.path(), &none),+ Some(home.path().join(".config/muse"))+ );let home = tempfile::tempdir().unwrap();let xdg = tempfile::tempdir().unwrap();std::fs::create_dir_all(xdg.path().join("muse")).unwrap();let xdg_path = xdg.path().as_os_str().to_owned();let env = move |name: &str| (name == "XDG_CONFIG_HOME").then(|| xdg_path.clone());- assert!(muse_detected(home.path(), &env));+ assert_eq!(+ muse_detected(home.path(), &env),+ Some(xdg.path().join("muse"))+ );assert_eq!(skills_for(AgentChoice::Muse), InstallSkillsAgent::Agents);- assert_eq!(AgentPlan::new(AgentChoice::Muse).mcp, Some(McpClient::Muse));+ assert_eq!(+ AgentPlan::new(AgentChoice::Muse, None).mcp,+ Some(McpClient::Muse)+ );}/// A versioned Homebrew binary is recorded through the `opt/<formula>`@@ -842,17 +1105,17 @@ mod tests {};let home = tempfile::tempdir().unwrap();let env = |_: &str| None;- assert!(!AgentPlan::detect(AgentChoice::ClaudeCode, home.path(), &env).plugin);+ assert!(!AgentPlan::detect(AgentChoice::ClaudeCode, None, home.path(), &env).plugin);install_claude_plugin(home.path(), "3.0.0", false);- assert!(!AgentPlan::detect(AgentChoice::ClaudeCode, home.path(), &env).plugin);+ assert!(!AgentPlan::detect(AgentChoice::ClaudeCode, None, home.path(), &env).plugin);install_claude_plugin(home.path(), "3.0.0", true);- assert!(AgentPlan::detect(AgentChoice::ClaudeCode, home.path(), &env).plugin);- assert!(!AgentPlan::detect(AgentChoice::Codex, home.path(), &env).plugin);- assert!(!AgentPlan::detect(AgentChoice::Grok, home.path(), &env).plugin);+ assert!(AgentPlan::detect(AgentChoice::ClaudeCode, None, home.path(), &env).plugin);+ assert!(!AgentPlan::detect(AgentChoice::Codex, None, home.path(), &env).plugin);+ assert!(!AgentPlan::detect(AgentChoice::Grok, None, home.path(), &env).plugin);install_codex_plugin(home.path());- assert!(AgentPlan::detect(AgentChoice::Codex, home.path(), &env).plugin);+ assert!(AgentPlan::detect(AgentChoice::Codex, None, home.path(), &env).plugin);}/// A token-file install learns how to open the web UI: the URL and the@@ -876,6 +1139,141 @@ mod tests {assert!(!hint.contains("file-root-token"), "{hint}");}+ fn agents_of(found: &[(AgentChoice, Found)]) -> Vec<AgentChoice> {+ found.iter().map(|(agent, _)| *agent).collect()+ }++ fn plan_with(agents: Vec<AgentPlan>) -> SetupPlan {+ SetupPlan {+ data_dir: PathBuf::from("/data"),+ config_path: PathBuf::from("/data/config.toml"),+ fresh: true,+ service: ServicePlan::Skip("skipped (--no-service)".to_owned()),+ agents,+ detected: true,+ }+ }++ /// Yes applies everything; numbers keep only those agents, in plan+ /// order and once each. A number outside the plan, a stray word, a blank+ /// line, and numbers offered for a single agent all decline, so a typo+ /// never wires an agent nobody chose.+ #[test]+ fn the_prompt_answer_picks_all_some_or_none_of_the_agents() {+ assert_eq!(parse_answer("y\n", 3).unwrap(), Answer::All);+ assert_eq!(parse_answer("Yes", 1).unwrap(), Answer::All);+ assert_eq!(+ parse_answer("3, 1 3\n", 3).unwrap(),+ Answer::Only(vec![1, 3])+ );+ assert_eq!(parse_answer("2", 2).unwrap(), Answer::Only(vec![2]));+ for declined in ["", "\n", "n", "no", "4", "0", "1 x", "-1"] {+ let error = parse_answer(declined, 3).unwrap_err().to_string();+ assert!(+ error.starts_with("nothing was changed"),+ "{declined:?}: {error}"+ );+ }+ assert!(+ parse_answer("1", 1).is_err(),+ "numbers need two agents to pick from"+ );+ }++ #[test]+ fn chosen_numbers_keep_those_agents_in_plan_order() {+ let agents = vec![+ AgentPlan::new(AgentChoice::ClaudeCode, None),+ AgentPlan::new(AgentChoice::Codex, None),+ AgentPlan::new(AgentChoice::Grok, None),+ ];+ let kept = choose_agents(Answer::Only(vec![1, 3]), agents.clone());+ assert_eq!(+ kept.iter().map(|plan| plan.agent).collect::<Vec<_>>(),+ vec![AgentChoice::ClaudeCode, AgentChoice::Grok]+ );+ assert_eq!(choose_agents(Answer::All, agents.clone()), agents);+ }++ /// The JSON plan names each agent by its `--agent` spelling with the+ /// evidence it was found by, lists every other accepted agent, and+ /// carries the layout version a front end checks.+ #[test]+ fn the_json_plan_carries_agents_evidence_and_the_rest() {+ let store = PathBuf::from("/home/u/.claude/projects");+ let mut codex = AgentPlan::new(AgentChoice::Codex, None);+ codex.plugin = true;+ let plan = plan_with(vec![+ AgentPlan::new(+ AgentChoice::ClaudeCode,+ Some(Found::SessionStore(store.clone())),+ ),+ codex,+ AgentPlan::new(AgentChoice::OpenCode2, None),+ ]);+ let json = serde_json::to_value(plan_document(&plan)).unwrap();+ assert_eq!(json["format"], PLAN_FORMAT);+ assert_eq!(json["service"]["action"], "skip");+ assert_eq!(json["agents"][0]["agent"], "claude-code");+ assert_eq!(json["agents"][0]["found"]["kind"], "session_store");+ assert_eq!(+ json["agents"][0]["found"]["path"],+ store.display().to_string()+ );+ assert_eq!(json["agents"][0]["wiring"], "mcp+hooks+skills");+ assert_eq!(json["agents"][1]["wiring"], "plugin");+ assert_eq!(json["agents"][2]["agent"], "opencode2");+ assert!(json["agents"][2]["found"].is_null());+ assert_eq!(json["first_question"], FIRST_QUESTION);+ let others: Vec<&str> = json["other_agents"]+ .as_array()+ .unwrap()+ .iter()+ .map(|name| name.as_str().unwrap())+ .collect();+ assert!(+ others.contains(&"cursor") && others.contains(&"gemini-cli"),+ "{others:?}"+ );+ assert!(!others.contains(&"claude-code") && !others.contains(&"opencode2"));+ {+ use clap::ValueEnum as _;+ assert_eq!(others.len() + 3, AgentChoice::value_variants().len());+ }+ }++ /// Every accepted `--agent` value round-trips through the name the plan+ /// prints, so a name copied from the plan always parses.+ #[test]+ fn every_listed_agent_name_parses_back() {+ use clap::ValueEnum as _;+ for agent in AgentChoice::value_variants() {+ assert_eq!(+ AgentChoice::from_str(&agent_name(*agent), false).ok(),+ Some(*agent)+ );+ }+ }++ #[test]+ fn the_closing_line_names_the_agents_and_the_question() {+ let one = next_step(&[AgentPlan::new(AgentChoice::ClaudeCode, None)]);+ assert!(one.contains("Restart claude-code so it loads"), "{one}");+ assert!(one.contains(FIRST_QUESTION), "{one}");+ let two = next_step(&[+ AgentPlan::new(AgentChoice::ClaudeCode, None),+ AgentPlan::new(AgentChoice::Codex, None),+ ]);+ assert!(+ two.contains("Restart claude-code, codex so they load"),+ "{two}"+ );+ assert!(two.contains("ask one of them"), "{two}");+ let none = next_step(&[]);+ assert!(none.contains("no agent is wired"), "{none}");+ assert!(!none.contains(FIRST_QUESTION), "{none}");+ }+fn spec(home: &Path) -> user_service::ServiceSpec {user_service::ServiceSpec {exe: PathBuf::from("/opt/ai-memory/ai-memory"),@@ -896,7 +1294,16 @@ mod tests {std::fs::write(&codex_config, "").unwrap();let mcp = |client: McpClient| (client == McpClient::Codex).then(|| codex_config.clone());let found = detect_agents(home, &|_| None, &mcp);- assert_eq!(found, vec![AgentChoice::ClaudeCode, AgentChoice::Codex]);+ assert_eq!(+ found,+ vec![+ (+ AgentChoice::ClaudeCode,+ Found::SessionStore(home.join(".claude").join("projects"))+ ),+ (AgentChoice::Codex, Found::McpConfig(codex_config.clone())),+ ]+ );}/// Control: an empty home detects nothing, and a named-but-missing MCP@@ -918,7 +1325,10 @@ mod tests {std::fs::create_dir_all(home.join(".local/share/opencode")).unwrap();std::fs::create_dir_all(home.join(".kiro/sessions/cli")).unwrap();let found = detect_agents(home, &|_| None, &|_| None);- assert_eq!(found, vec![AgentChoice::OpenCode, AgentChoice::KiroCli]);+ assert_eq!(+ agents_of(&found),+ vec![AgentChoice::OpenCode, AgentChoice::KiroCli]+ );}/// A relocated store (`CLAUDE_CONFIG_DIR`, `CODEX_HOME`, …) is looked for@@ -932,7 +1342,13 @@ mod tests {(harness == ManagedHarness::Claude).then(|| elsewhere.clone())};let found = detect_agents(&tmp.path().join("home"), &relocate, &|_| None);- assert_eq!(found, vec![AgentChoice::ClaudeCode]);+ assert_eq!(+ found,+ vec![(+ AgentChoice::ClaudeCode,+ Found::SessionStore(elsewhere.clone())+ )]+ );}#[test]diff --git a/crates/ai-memory-cli/tests/suite/setup_e2e.rs b/crates/ai-memory-cli/tests/suite/setup_e2e.rsindex 7f9abff8..6bdb8f9e 100644--- a/crates/ai-memory-cli/tests/suite/setup_e2e.rs+++ b/crates/ai-memory-cli/tests/suite/setup_e2e.rs@@ -114,7 +114,12 @@ fn setup_without_yes_and_without_a_terminal_changes_nothing() {let stdout = String::from_utf8_lossy(&out.stdout);assert!(stdout.contains("ai-memory setup will:"), "{}", text(&out));assert!(- stdout.contains("wire claude-code (detected)"),+ stdout.contains("1. claude-code: MCP + hooks + skills (found its session store at"),+ "{}",+ text(&out)+ );+ assert!(+ stdout.contains("not in this plan (add with --agent <name>):") && stdout.contains("cursor"),"{}",text(&out));@@ -129,6 +134,45 @@ fn setup_without_yes_and_without_a_terminal_changes_nothing() {assert_eq!(sandbox.snapshot(), before, "setup wrote without --yes");}+/// `--plan --json` prints a parseable plan naming the detected agent and its+/// evidence, exits zero, and writes nothing, with no terminal and no `--yes`.+#[test]+fn setup_plan_json_prints_the_plan_and_changes_nothing() {+ let sandbox = Sandbox::new();+ let store = sandbox.home.join(".claude/projects");+ std::fs::create_dir_all(&store).unwrap();+ let before = sandbox.snapshot();+ let port = crate::e2e_support::free_port();+ let out = sandbox+ .cmd(Some(port))+ .args(["setup", "--plan", "--json"])+ .output()+ .unwrap();+ assert!(out.status.success(), "{}", text(&out));+ let plan: serde_json::Value = serde_json::from_slice(&out.stdout).expect("JSON plan");+ assert_eq!(plan["format"], 1, "{plan}");+ assert_eq!(plan["fresh"], true, "{plan}");+ assert_eq!(plan["agents"][0]["agent"], "claude-code", "{plan}");+ assert_eq!(+ plan["agents"][0]["found"]["kind"], "session_store",+ "{plan}"+ );+ assert_eq!(+ plan["agents"][0]["found"]["path"],+ store.display().to_string(),+ "{plan}"+ );+ assert!(!sandbox.data_dir().join("config.toml").exists());+ assert_eq!(sandbox.snapshot(), before, "setup --plan wrote");++ // `--plan` cannot be combined with `--yes`, and `--json` needs `--plan`.+ for args in [&["setup", "--plan", "--yes"][..], &["setup", "--json"][..]] {+ let refused = sandbox.cmd(Some(port)).args(args).output().unwrap();+ assert!(!refused.status.success(), "{args:?}: {}", text(&refused));+ }+ assert_eq!(sandbox.snapshot(), before, "a refused setup wrote");+}+/// Spawns a server through the fake service manager: the slow tier.#[cfg(target_os = "linux")]mod slow {@@ -270,6 +314,11 @@ esaclet stdout = String::from_utf8_lossy(&first.stdout);assert!(stdout.contains("healthz: ok"), "{}", text(&first));assert!(stdout.contains("memory_status: ok"), "{}", text(&first));+ assert!(+ stdout.contains("What do you remember about this project?"),+ "{}",+ text(&first)+ );let data_dir = sandbox.data_dir();let token = std::fs::read_to_string(data_dir.join("auth-tokens/default"))diff --git a/docs/install.md b/docs/install.mdindex b7ff9d97..d2f39cb3 100644--- a/docs/install.md+++ b/docs/install.md@@ -99,8 +99,8 @@ sh install.shWindows is not covered by the script; use the zip in[`docs/windows.md`](windows.md).-`ai-memory setup [--yes] [--agent <name>]... [--no-service]` runs, in order,-the commands a native install otherwise needs one by one:+`ai-memory setup [--yes] [--agent <name>]... [--no-service] [--plan [--json]]`+runs, in order, the commands a native install otherwise needs one by one:1. `init`. On a fresh data dir this mints the root bearer token into`<data_dir>/auth-tokens/default` (owner-only) and records@@ -127,17 +127,29 @@ the commands a native install otherwise needs one by one:`install-skills --scope global`. With no `--agent`, `setup` wires everyharness whose session store or MCP config exists under your home, using thesame store locations as `doctor` (including `CLAUDE_CONFIG_DIR`,- `CODEX_HOME` and similar relocations). OpenCode 2 and the Kiro CLI v3- engine share a store with OpenCode and Kiro CLI, so they are wired only- when named, for example `--agent opencode2`.+ `CODEX_HOME` and similar relocations). The plan numbers each agent and+ says what it was found by (its session store, its MCP config, or for Muse+ its directory), then lists the other agents `--agent` accepts. Cursor,+ Gemini CLI, Droid and the other agents with no store to look for are+ wired by naming them. OpenCode 2 and the Kiro CLI v3 engine share a store+ with OpenCode and Kiro CLI, so they are wired only when named, for example+ `--agent opencode2`.4. A self-check that writes nothing: `GET /healthz`, a `memory_status` callover MCP with the install's credential, and `doctor`.-Without `--yes`, `setup` prints this plan and asks on a terminal; with no-terminal (a script, an agent's tool call) it changes nothing and exits-non-zero, asking for `--yes`. Each step is idempotent: a second run rewrites no+Without `--yes`, `setup` prints this plan and asks on a terminal. `y` applies+it. With more than one agent in the plan you can instead type the numbers of+the agents to wire (`1 3` or `1,3`); every other step still runs, and an answer+naming a number outside the plan changes nothing. With no terminal (a script,+an agent's tool call) it changes nothing and exits non-zero, asking for+`--yes`. `--plan` prints the plan and exits without changing anything;+`--plan --json` prints it as a JSON document for a script or front end, with a+`format` field that is bumped only when a field changes meaning or is removed. Each step is idempotent: a second run rewrites nofile and leaves a running service alone. A step that fails does not stop the-others; `setup` lists each `problem:` at the end and exits non-zero. The token+others; `setup` lists each `problem:` at the end and exits non-zero. When every step+passed it ends by naming the agents to restart and the question to ask one of+them, "What do you remember about this project?": answering it takes a call+to ai-memory's tools, so the reply shows the wiring works. The tokenis never printed or passed on a command line, and no harness config holds it:hooks read the credential files `init` writes, and MCP clients reach theserver through `ai-memory mcp-bridge`.@@ -501,8 +513,10 @@ Download the `x86_64` or `aarch64` RPM from the[latest GitHub release](https://github.com/akitaonrails/ai-memory/releases/latest)and install it with `sudo dnf install ./ai-memory-*.rpm`. The package includesthe binary, hook sources, system and user systemd units, and system service-configuration. Follow the [user-level service](#user-level-service) or-[system service](#system-service) steps below to initialize and start it.+configuration. On a single-user machine, run `ai-memory setup`, as in the+[one-step native install](#one-step-native-install-installsh--ai-memory-setup).+For the manual route, follow the [user-level service](#user-level-service) or+[system service](#system-service) steps below.## Arch Linux native packages (AUR)@@ -547,6 +561,14 @@ only one can listen on `127.0.0.1:49374` unless you change `bind` in one config.Use this on a single-user workstation. It needs no sudo after package install andkeeps all state in your home directory.+The short route is `ai-memory setup`, which does everything below and wires+your agents too (see the+[one-step native install](#one-step-native-install-installsh--ai-memory-setup)).+It writes its own unit to `~/.config/systemd/user/ai-memory.service`, which+takes precedence over the packaged one of the same name, with the config at+`~/.local/share/ai-memory/config.toml`. The manual steps below use the packaged+unit and its paths instead.+```bashmkdir -p ~/.config/ai-memory ~/.local/share/ai-memoryai-memory \diff --git a/install.sh b/install.shindex 9b9dfa2a..52168f6a 100755--- a/install.sh+++ b/install.sh@@ -217,11 +217,15 @@ main() {say "installed $("$link" --version 2>/dev/null || echo ai-memory) to $lib_dir"say "linked $link"+ # Off PATH, a bare `ai-memory setup` would fail with "command not found",+ # so the next step names the link itself.case ":${PATH:-}:" in- *":$bin_dir:"*) ;;- *) say "$bin_dir is not on PATH; add it, e.g. export PATH=\"$bin_dir:\$PATH\"" ;;+ *":$bin_dir:"*) say "next: ai-memory setup" ;;+ *)+ say "$bin_dir is not on PATH; add it, e.g. export PATH=\"$bin_dir:\$PATH\""+ say "next: $link setup"+ ;;esac- say "next: ai-memory setup"}main "$@"diff --git a/packaging/aur/README.md b/packaging/aur/README.mdindex 22c0bfce..d2fd7346 100644--- a/packaging/aur/README.md+++ b/packaging/aur/README.md@@ -19,7 +19,8 @@ yay -S ai-memory-bin # prebuilt binary, fastest on x86_64/aarch64yay -S ai-memory # builds from source, supports x86_64/aarch64```-Then follow the native Linux service instructions in `docs/install.md`.+Then run `ai-memory setup` on a single-user machine, or follow the system+service instructions in `docs/install.md`.## Local Integration Testdiff --git a/packaging/aur/ai-memory.install b/packaging/aur/ai-memory.installindex 02217d4d..3a91d5a9 100644--- a/packaging/aur/ai-memory.install+++ b/packaging/aur/ai-memory.install@@ -2,9 +2,11 @@ post_install() {cat <<'EOF'ai-memory is installed.-User service:- ai-memory --data-dir "$HOME/.local/share/ai-memory" --config "$HOME/.config/ai-memory/config.toml" init- systemctl --user enable --now ai-memory.service+Single user: run+ ai-memory setup+It creates the data dir and its bearer token, installs and starts a user+service, wires the agents it finds (it shows the plan and asks first), and+checks the result.System service:sudo systemd-sysusers /usr/lib/sysusers.d/ai-memory.conf@@ -21,7 +23,9 @@ post_upgrade() {cat <<'EOF'ai-memory was upgraded.-If you use lifecycle hooks, refresh staged hook scripts for each agent:- ai-memory install-hooks --agent claude-code --apply+If you use lifecycle hooks, refresh the staged hook scripts: re-run+ ai-memory setup+(it shows the plan and asks first), or, for one agent,+ ai-memory install-hooks --agent <name> --applyEOF}diff --git a/scripts/onboarding-acceptance.sh b/scripts/onboarding-acceptance.shindex a1964f4f..cf11880a 100755--- a/scripts/onboarding-acceptance.sh+++ b/scripts/onboarding-acceptance.sh@@ -6,7 +6,8 @@# from a local binary and served over local HTTP;# 2. `ai-memory setup --yes`, with a stand-in service manager first on PATH# (`systemctl` on Linux, `launchctl` on macOS) that runs the rendered-# unit's command in the background and never reaches a real session;+# unit's command in the background and never reaches a real session; its+# output must end on the question to ask the restarted agent;# 3. one synthetic hook event, as the installed Claude Code hook sends it;# 4. `memory_query` over `ai-memory mcp-bridge` until it returns the event.#@@ -166,8 +167,12 @@ clean sh -c "curl -fsSL '$base/latest/download/install.sh' | sh"echo "== 2. ai-memory setup --yes"commands=$((commands + 1))-(cd "$home" && clean ai-memory setup --yes)+setup_log="$work/setup.log"+(cd "$home" && clean ai-memory setup --yes) | tee "$setup_log"installed="$(now)"+# setup ends on the question to ask the restarted agent, not a health check.+grep -Fq "What do you remember about this project?" "$setup_log" ||+ { echo "setup did not end with the question for the restarted agent" >&2; exit 1; }echo "== hook event + memory_query"marker="onboarding-acceptance-$(date +%s)-$$"diff --git a/tests/install_sh.sh b/tests/install_sh.shindex 8f506c8c..b841c5bf 100755--- a/tests/install_sh.sh+++ b/tests/install_sh.sh@@ -59,6 +59,15 @@ plain_tree "${TMP_ROOT}/plain-tree"base="$(publish plain "${TMP_ROOT}/plain-tree")"run_install plain "file://${base}" || fail "plain release refused: $(cat "${TMP_ROOT}/plain/out.log")"[ -x "${TMP_ROOT}/plain/home/.local/lib/ai-memory/ai-memory" ] || fail "plain release not unpacked"+# The test PATH lacks ~/.local/bin, so the next step names the link by its full+# path; with the bin dir on PATH it is the bare command.+grep -Fq "next: ${TMP_ROOT}/plain/home/.local/bin/ai-memory setup" "${TMP_ROOT}/plain/out.log" \+ || fail "off-PATH next step not absolute: $(cat "${TMP_ROOT}/plain/out.log")"+base_on_path="$(publish on-path "${TMP_ROOT}/plain-tree")"+run_install on-path "file://${base_on_path}" PATH="${TMP_ROOT}/on-path/home/.local/bin:${PATH}" \+ || fail "on-PATH install refused: $(cat "${TMP_ROOT}/on-path/out.log")"+grep -Fxq "next: ai-memory setup" <(sed 's/^[^:]*: //' "${TMP_ROOT}/on-path/out.log") \+ || fail "on-PATH next step not the bare command: $(cat "${TMP_ROOT}/on-path/out.log")"# A symlink member pointing outside the tree is refused, and nothing lands.plain_tree "${TMP_ROOT}/symlink-tree"