Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors
Rust
fix: close post-merge audit gaps
AkitaOnRailse63fa16476b7
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 376cd949..89542dea 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -25,6 +25,9 @@ version in [`docs/changelog/`](docs/changelog/):Argon2id verifier. A restored database with existing keys now refuses toserve under a different `[auth].token_pepper` instead of silently makingevery key return 401; pepper rotation remains allowed while no keys exist.+ A pre-verifier backup containing keys fails restore until the operator+ supplies the original pepper and explicitly confirms it with+ `--accept-legacy-api-key-pepper`.([#1495](https://github.com/akitaonrails/ai-memory/issues/1495))- Defined `ai-memory backup` as an online data snapshot rather than a complete@@ -36,12 +39,15 @@ version in [`docs/changelog/`](docs/changelog/):- Accepted the exact CRLF migration checksums written by Windows-nativereleases before v3.1.2 and replaced them transactionally with the currentLF checksums before strict migration validation. Unknown migration changes- still fail closed. ([#1499](https://github.com/akitaonrails/ai-memory/issues/1499))+ still fail closed. Bare hook reinstallation also preserves the Windows+ exec-form `--capture-assistant` opt-in instead of looking only inside the+ command string. ([#1499](https://github.com/akitaonrails/ai-memory/issues/1499))- Held `ai-memory run` heartbeat notices while the harness owns the terminaland printed them after it exits, so a server outage no longer writes into theharness TUI. Only the first and latest notices are replayed, with a count of- the rest.+ the rest. A transport outage that changes into a server-side lease rejection+ is reported as a new state instead of being hidden as the same failure.([#1500](https://github.com/akitaonrails/ai-memory/issues/1500))- Dropped stopwords from the quoted bag of words a search falls back to when@@ -55,7 +61,7 @@ version in [`docs/changelog/`](docs/changelog/):drops everything the source project owns, the same set `purge-project`deletes. This includes managed workstreams, cross-project messages,auto-improvement and profile-harvest state, consolidation jobs, ingest keys,- entities, page feedback, purge tombstones and project grants as well as+ entities, page feedback, per-session purge tombstones and project grants as well assessions, observations and handoffs. The `400` for sending both a projectname and an id, or neither, applies to the admin endpoints; the CLI resolvesa missing project from the marker, the git remote, then the directory name.@@ -80,6 +86,11 @@ version in [`docs/changelog/`](docs/changelog/):entries keep working. `uninstall --only hooks` keeps the stored key whilesuch a bridge entry remains. ([#1490](https://github.com/akitaonrails/ai-memory/issues/1490))+- Scoped implicit bridge credentials to their configured endpoint, rejected a+ malformed stored user key instead of falling through to root, made failed+ installs roll back newly stored credentials, and included the absolute data+ dir in Claude Code's printed session-aware command as well as its JSON entry.+## [3.1.2] - 2026-10-20### Fixeddiff --git a/crates/ai-memory-cli/src/cli.rs b/crates/ai-memory-cli/src/cli.rsindex 6095512e..a3a63d4e 100644--- a/crates/ai-memory-cli/src/cli.rs+++ b/crates/ai-memory-cli/src/cli.rs@@ -2308,6 +2308,10 @@ pub struct RestoreArgs {/// Overwrite an existing non-empty data dir.#[arg(long)]pub force: bool,+ /// Confirm that the configured token pepper is the original one for a+ /// pre-verifier backup that already contains native API keys.+ #[arg(long)]+ pub accept_legacy_api_key_pepper: bool,}/// Arguments for `restore-agents`.diff --git a/crates/ai-memory-cli/src/commands/install_hooks.rs b/crates/ai-memory-cli/src/commands/install_hooks.rsindex 2f07f4ad..76dd47cc 100644--- a/crates/ai-memory-cli/src/commands/install_hooks.rs+++ b/crates/ai-memory-cli/src/commands/install_hooks.rs@@ -1301,21 +1301,33 @@ fn baked_capture_assistant(existing: &str) -> Option<bool> {for entry in entries {// Nested (`hooks:[{command}]`) or flat (`{command}`) shape.let nested = entry.get("hooks").and_then(serde_json::Value::as_array);- let commands: Vec<&str> = match nested {- Some(inner) => inner- .iter()- .filter_map(|e| e.get("command").and_then(|c| c.as_str()))- .collect(),- None => entry- .get("command")- .and_then(|c| c.as_str())- .into_iter()- .collect(),+ let hook_entries: Vec<&serde_json::Value> = match nested {+ Some(inner) => inner.iter().collect(),+ None => vec![entry],};- for command in commands {- if hook_command_is_ours(command) {+ for hook_entry in hook_entries {+ let Some(command) = hook_entry.get("command").and_then(|c| c.as_str()) else {+ continue;+ };+ let args = hook_entry.get("args").and_then(serde_json::Value::as_array);+ let recognizer = args.map_or_else(+ || command.to_owned(),+ |args| {+ let suffix = args+ .iter()+ .filter_map(serde_json::Value::as_str)+ .collect::<Vec<_>>()+ .join(" ");+ format!("{command} {suffix}")+ },+ );+ if hook_command_is_ours(&recognizer) {saw_ai_memory = true;- if command.contains("--capture-assistant") {+ let args_have_marker = args.is_some_and(|args| {+ args.iter()+ .any(|arg| arg.as_str() == Some("--capture-assistant"))+ });+ if command.contains("--capture-assistant") || args_have_marker {has_marker = true;}}@@ -11183,11 +11195,8 @@ model = "gpt-5"/// auto-wire issues — must PRESERVE a user's existing assistant-capture/// opt-in, not silently strip it.///- /// Unix-gated: `--capture-assistant` is baked onto the native Stop command on- /// POSIX-native platforms; the Windows Claude command form does not carry the- /// flag in its rendered JSON, so there is nothing to drop or preserve there.- /// The preserve logic itself (`baked_capture_assistant`) has no platform- /// branch.+ /// Unix-gated because this end-to-end render uses the host platform. The+ /// parser itself has a platform-independent Windows exec-form regression.#[cfg(unix)]#[test]fn a_bare_reapply_preserves_an_existing_capture_assistant_opt_in() {@@ -11216,6 +11225,25 @@ model = "gpt-5");}+ #[test]+ fn windows_exec_form_preserves_capture_assistant_from_args() {+ let settings = serde_json::json!({+ "hooks": {+ "Stop": [{+ "hooks": [{+ "type": "command",+ "command": r"C:\Program Files\ai-memory\ai-memory.exe",+ "args": ["hook", "--event", "stop", "--agent", "claude-code", "--server-url", "http://127.0.0.1:49374", "--capture-assistant"]+ }]+ }]+ }+ });+ assert_eq!(+ baked_capture_assistant(&serde_json::to_string(&settings).unwrap()),+ Some(true)+ );+ }+/// The preserve logic must not false-positive: a fresh install without the/// flag stays off.#[test]diff --git a/crates/ai-memory-cli/src/commands/install_mcp.rs b/crates/ai-memory-cli/src/commands/install_mcp.rsindex 4d5385a1..2d51cc2f 100644--- a/crates/ai-memory-cli/src/commands/install_mcp.rs+++ b/crates/ai-memory-cli/src/commands/install_mcp.rs@@ -159,19 +159,36 @@ pub(crate) fn run_with_opencode_dialect(// open.let bridge_carries_token = matches!(args.client, McpClient::Muse)|| (args.client == McpClient::ClaudeCode && args.session_aware);- if args.apply+ let may_store_bridge_key = args.apply&& token_given&& bridge_carries_token&& config.auth.configured_bearer_token().is_none()&& config.runtime_env.host_cwd().is_none()- && let Some(token) = args.auth_token.as_deref()- && store_bridge_key(&config.data_dir, token)- {- args.auth_token = None;- args.bridge_data_dir = Some(config.data_dir.clone());- }+ && same_mcp_endpoint(+ &config.server_url,+ args.server_url.as_deref().unwrap_or(DEFAULT_MCP_URL),+ );validate_args(&args)?;if args.apply {+ if may_store_bridge_key+ && let Some(token) = args.auth_token.clone()+ && let Some(stored) = store_bridge_key(&config.data_dir, &token)+ {+ args.auth_token = None;+ args.bridge_data_dir = Some(config.data_dir.clone());+ if let Err(error) = apply_to_config_file(&args) {+ if stored == HookCredential::Seeded+ && crate::config::read_hook_auth_token(&config.data_dir).as_deref()+ == Some(token.as_str())+ {+ crate::config::clear_hook_auth_token(&config.data_dir).with_context(+ || "rolling back the bridge credential after MCP config update failed",+ )?;+ }+ return Err(error);+ }+ return Ok(());+ }return apply_to_config_file(&args);}let snippet = match args.client {@@ -243,11 +260,10 @@ fn route_file_token(args: &mut InstallMcpArgs, token_file: &Path) -> Result<()>}/// Store `token` in `<data_dir>/auth-token` for the bridge, the file and-/// format `install-hooks --apply` uses. `false` when the bridge would not read-/// this key from there: a different key is already stored (it belongs to the-/// install's hooks and is left alone), the hooks sign in with OIDC, or the-/// write failed. The caller then keeps the key in the entry.-fn store_bridge_key(data_dir: &Path, token: &str) -> bool {+/// format `install-hooks --apply` uses. Returns whether this call created the+/// files or found the same key; `None` means the caller must keep the key in+/// the entry.+fn store_bridge_key(data_dir: &Path, token: &str) -> Option<HookCredential> {// The hooks present an OIDC `auth.json` only while no key is stored, so// storing one here would quietly switch them to this key.if crate::config::read_hook_auth_token(data_dir).is_none()@@ -260,15 +276,15 @@ fn store_bridge_key(data_dir: &Path, token: &str) -> bool {"[ai-memory] this install's hooks sign in with OIDC; keeping the --auth-token key \in the MCP entry, as before, so they keep doing so");- return false;+ return None;}match crate::local_auth::seed_hook_credential(data_dir, token) {- Ok(HookCredential::Seeded | HookCredential::Current) => {+ Ok(outcome @ (HookCredential::Seeded | HookCredential::Current)) => {eprintln!("[ai-memory] stored the bridge's key in {}; the MCP entry carries no token",crate::config::hook_auth_token_path_in(data_dir).display());- true+ Some(outcome)}Ok(HookCredential::KeptOther) => {eprintln!(@@ -276,7 +292,7 @@ fn store_bridge_key(data_dir: &Path, token: &str) -> bool {hooks; keeping the --auth-token key in the MCP entry, as before",crate::config::hook_auth_token_path_in(data_dir).display());- false+ None}Err(e) => {eprintln!(@@ -284,7 +300,7 @@ fn store_bridge_key(data_dir: &Path, token: &str) -> bool {the MCP entry, as before",data_dir.display());- false+ None}}}@@ -552,6 +568,16 @@ pub(crate) fn mcp_server_url_from_base(server_url: &str) -> String {}}+pub(crate) fn same_mcp_endpoint(left: &str, right: &str) -> bool {+ fn normalized(url: &str) -> String {+ mcp_server_url_from_base(url).split_once('?').map_or_else(+ || mcp_server_url_from_base(url),+ |(base, _)| base.to_owned(),+ )+ }+ normalized(left) == normalized(right)+}+fn validate_args(args: &InstallMcpArgs) -> Result<()> {if args.session_aware && !matches!(args.client, McpClient::ClaudeCode) {bail!("--session-aware is supported only for --client claude-code");@@ -2156,11 +2182,18 @@ fn render_claude_code(args: &InstallMcpArgs, config_path: &Path) -> Result<Strin.as_deref().map(|token| format!(" --env \"AI_MEMORY_AUTH_TOKEN={token}\"")).unwrap_or_default();+ let data_dir = args+ .bridge_data_dir+ .as_ref()+ .map_or_else(String::new, |path| {+ format!(" --data-dir {}", shell_quote(&path.to_string_lossy()))+ });format!(- "claude mcp add --transport stdio{env} {name} -- \\\n {command} mcp-bridge --server-url {url}",+ "claude mcp add --transport stdio{env} {name} -- \\\n {command} mcp-bridge --server-url {url}{data_dir}",name = args.name,command = shell_quote(&bridge_command()),url = args.server_url.as_deref().unwrap_or(DEFAULT_MCP_URL),+ data_dir = data_dir,)} else if let Some(b) = &bearer {format!(@@ -4008,6 +4041,7 @@ mod tests {let mut args = args_with_token(McpClient::ClaudeCode);args.server_url = Some("https://memory.example/mcp".into());args.session_aware = true;+ args.bridge_data_dir = Some(PathBuf::from("/srv/AI Memory/data"));let entry = build_mcp_entry(&args).unwrap();@@ -4015,7 +4049,13 @@ mod tests {assert_eq!(entry["command"], bridge_command());assert_eq!(entry["args"],- json!(["mcp-bridge", "--server-url", "https://memory.example/mcp"])+ json!([+ "mcp-bridge",+ "--server-url",+ "https://memory.example/mcp",+ "--data-dir",+ "/srv/AI Memory/data"+ ]));assert_eq!(entry["env"]["AI_MEMORY_AUTH_TOKEN"], "test-token-deadbeef");assert!(entry.get("url").is_none());@@ -4027,6 +4067,7 @@ mod tests {"{} mcp-bridge --server-url",shell_quote(&bridge_command()))));+ assert!(rendered.contains("--data-dir '/srv/AI Memory/data'"));}#[test]@@ -4526,6 +4567,23 @@ mod tests {assert!(install(&configured, McpClient::ClaudeCode, true).contains(KEY));assert_eq!(stored(&configured), None);+ let remote = config_in("different-endpoint");+ let remote_file = remote.data_dir.with_extension("remote.json");+ let mut remote_args = args_for(McpClient::ClaudeCode);+ remote_args.apply = true;+ remote_args.session_aware = true;+ remote_args.config_file = Some(remote_file.clone());+ remote_args.server_url = Some("https://other.example/mcp".into());+ remote_args.auth_token = Some(KEY.into());+ run_with_opencode_dialect(&remote, remote_args, None).unwrap();+ let remote_text = std::fs::read_to_string(remote_file).unwrap();+ assert!(remote_text.contains(KEY));+ assert_eq!(+ stored(&remote),+ None,+ "a key for another server is not hook auth"+ );+let other = config_in("other");crate::config::store_hook_auth_token(&other.data_dir, "aim_hooks_key").unwrap();assert!(install(&other, McpClient::ClaudeCode, true).contains(KEY));@@ -4559,6 +4617,27 @@ mod tests {assert_eq!(stored(&http), None);}+ #[test]+ fn failed_bridge_apply_rolls_back_a_newly_stored_key() {+ let tmp = tempfile::tempdir().unwrap();+ let config = Config {+ data_dir: tmp.path().join("data"),+ ..Config::default()+ };+ let config_file = tmp.path().join("broken.json");+ std::fs::write(&config_file, "[]").unwrap();+ let mut args = args_for(McpClient::ClaudeCode);+ args.apply = true;+ args.session_aware = true;+ args.config_file = Some(config_file);+ args.auth_token = Some("aim_must_rollback".into());++ let error = run_with_opencode_dialect(&config, args, None).unwrap_err();+ assert!(error.to_string().contains("object"), "{error:#}");+ assert_eq!(crate::config::read_hook_auth_token(&config.data_dir), None);+ assert!(!crate::config::hook_auth_header_path_in(&config.data_dir).exists());+ }+#[test]fn mcp_server_url_defaults_to_configured_server_url() {let config = Config {diff --git a/crates/ai-memory-cli/src/commands/mcp_bridge.rs b/crates/ai-memory-cli/src/commands/mcp_bridge.rsindex e10b8b82..8107a30d 100644--- a/crates/ai-memory-cli/src/commands/mcp_bridge.rs+++ b/crates/ai-memory-cli/src/commands/mcp_bridge.rs@@ -51,7 +51,7 @@ use rmcp::transport::{StreamableHttpClientTransport, Transport, stdio};use rmcp::{ErrorData as McpError, Peer, ServerHandler, ServiceExt};use crate::cli::{BridgeAgent, McpBridgeArgs};-use crate::commands::install_mcp::mcp_server_url_from_base;+use crate::commands::install_mcp::{mcp_server_url_from_base, same_mcp_endpoint};use crate::config::Config;const ACTOR_SESSION_HEADER: HeaderName = HeaderName::from_static("x-memory-actor-session-id");@@ -260,27 +260,53 @@ fn bridge_base_url<'a>(flag: Option<&'a str>, configured: &'a str) -> &'a str {.unwrap_or(configured)}-/// The bearer the bridge sends: a configured one (`AI_MEMORY_AUTH_TOKEN`,-/// `[auth].bearer_token`, `[auth].bearer_token_file`), else the key stored for-/// this install's hooks in `<data_dir>/auth-token`, else the root token-/// `Config::load` discovered on a loopback install. The stored key outranks-/// discovery so a host that runs the server and a client sends the user's key-/// rather than root.-fn bridge_bearer(config: &Config) -> Option<String> {+/// The bearer the bridge sends. Configured credentials may intentionally+/// follow an explicit remote URL. Implicit install-local credentials may not:+/// both the stored hook key and a discovered root key are scoped to the+/// configured endpoint that caused them to be found.+fn bridge_bearer(config: &Config, server_url: &str) -> Result<Option<String>> {let usable = |token: &str| !token.trim().is_empty();- config+ if let Some(token) = config.auth.configured_bearer_token().filter(|token| usable(token)).map(str::to_owned)- .or_else(|| crate::config::read_hook_auth_token(&config.data_dir))- .or_else(|| {- config- .auth- .bearer_token- .clone()- .filter(|token| usable(token))- })+ {+ return Ok(Some(token));+ }++ if !same_mcp_endpoint(&config.server_url, server_url) {+ return Ok(None);+ }++ let stored_path = crate::config::hook_auth_token_path_in(&config.data_dir);+ match std::fs::read_to_string(&stored_path) {+ Ok(raw) => {+ let token = raw.trim();+ if token.is_empty() {+ anyhow::bail!(+ "stored bridge credential {} is blank; repair or remove it instead of falling back to root",+ stored_path.display()+ );+ }+ return Ok(Some(token.to_owned()));+ }+ Err(error) if error.kind() == std::io::ErrorKind::NotFound => {}+ Err(error) => {+ return Err(error).with_context(|| {+ format!("reading stored bridge credential {}", stored_path.display())+ });+ }+ }++ if crate::commands::hook_spool::is_loopback_url(server_url) {+ return Ok(config+ .auth+ .bearer_token+ .clone()+ .filter(|token| usable(token)));+ }+ Ok(None)}/// Run the stdio bridge, session-aware or session-less (see the module docs).@@ -296,7 +322,7 @@ pub async fn run(config: &Config, args: McpBridgeArgs) -> Result<()> {args.server_url.as_deref(),&config.server_url,));- let bearer = bridge_bearer(config);+ let bearer = bridge_bearer(config, &server_url)?;let transport = StreamableHttpClientTransport::from_config(upstream_config(&server_url,session_id,@@ -661,16 +687,31 @@ mod tests {data_dir: tmp.path().to_path_buf(),..Config::default()};- assert_eq!(bridge_bearer(&config), None);+ assert_eq!(bridge_bearer(&config, &config.server_url).unwrap(), None);crate::config::store_hook_auth_token(tmp.path(), "aim_stored").unwrap();- assert_eq!(bridge_bearer(&config).as_deref(), Some("aim_stored"));+ assert_eq!(+ bridge_bearer(&config, &config.server_url)+ .unwrap()+ .as_deref(),+ Some("aim_stored")+ );config.auth.bearer_token = Some("configured".into());- assert_eq!(bridge_bearer(&config).as_deref(), Some("configured"));+ assert_eq!(+ bridge_bearer(&config, &config.server_url)+ .unwrap()+ .as_deref(),+ Some("configured")+ );config.auth.bearer_token = Some(" ".into());- assert_eq!(bridge_bearer(&config).as_deref(), Some("aim_stored"));+ assert_eq!(+ bridge_bearer(&config, &config.server_url)+ .unwrap()+ .as_deref(),+ Some("aim_stored")+ );}/// Adversarial: on a host that runs the server and a client from one data@@ -696,11 +737,69 @@ mod tests {let discovered = discovered_root();assert_eq!(discovered.auth.bearer_token.as_deref(), Some("root-token"));- assert_eq!(bridge_bearer(&discovered).as_deref(), Some("root-token"));+ assert_eq!(+ bridge_bearer(&discovered, &discovered.server_url)+ .unwrap()+ .as_deref(),+ Some("root-token")+ );crate::config::store_hook_auth_token(tmp.path(), "aim_user_key").unwrap();let both = discovered_root();assert_eq!(both.auth.bearer_token.as_deref(), Some("root-token"));- assert_eq!(bridge_bearer(&both).as_deref(), Some("aim_user_key"));+ assert_eq!(+ bridge_bearer(&both, &both.server_url).unwrap().as_deref(),+ Some("aim_user_key")+ );+ }++ #[test]+ fn implicit_local_credentials_never_follow_a_server_url_override() {+ let tmp = tempfile::tempdir().unwrap();+ let mut config = Config {+ data_dir: tmp.path().to_path_buf(),+ server_url: "http://127.0.0.1:49374".into(),+ ..Config::default()+ };+ config.auth.bearer_token = Some("discovered-root".into());+ config.auth.token_file = Some(crate::config::ResolvedTokenFile {+ path: tmp.path().join("auth-tokens/default"),+ loaded: true,+ discovered: true,+ });+ crate::config::store_hook_auth_token(tmp.path(), "stored-user").unwrap();++ assert_eq!(+ bridge_bearer(&config, "https://remote.example/mcp").unwrap(),+ None+ );++ config.auth.token_file = None;+ assert_eq!(+ bridge_bearer(&config, "https://remote.example/mcp")+ .unwrap()+ .as_deref(),+ Some("discovered-root"),+ "an explicitly configured credential remains remote-capable"+ );+ }++ #[test]+ fn malformed_stored_credential_fails_instead_of_escalating_to_root() {+ let tmp = tempfile::tempdir().unwrap();+ let mut config = Config {+ data_dir: tmp.path().to_path_buf(),+ ..Config::default()+ };+ config.auth.bearer_token = Some("discovered-root".into());+ config.auth.token_file = Some(crate::config::ResolvedTokenFile {+ path: tmp.path().join("auth-tokens/default"),+ loaded: true,+ discovered: true,+ });+ std::fs::write(crate::config::hook_auth_token_path_in(tmp.path()), " \n").unwrap();++ let error = bridge_bearer(&config, &config.server_url).unwrap_err();+ assert!(error.to_string().contains("is blank"), "{error:#}");}}diff --git a/crates/ai-memory-cli/src/commands/restore.rs b/crates/ai-memory-cli/src/commands/restore.rsindex 804a5cbf..0574e33d 100644--- a/crates/ai-memory-cli/src/commands/restore.rs+++ b/crates/ai-memory-cli/src/commands/restore.rs@@ -49,7 +49,7 @@ const CONFIG_FILE: &str = "config.toml";/// data dir is non-empty without `--force`, the tarball cannot be/// extracted, or the restored store fails to open. In every one of those/// cases the live data dir is left as it was.-pub fn run(config: &Config, args: RestoreArgs) -> Result<()> {+pub async fn run(config: &Config, args: RestoreArgs) -> Result<()> {let siblings = sibling_processes();if !siblings.is_empty() {bail!(busy_message("restore", &siblings));@@ -59,7 +59,14 @@ pub fn run(config: &Config, args: RestoreArgs) -> Result<()> {bail!("source tarball {} not found", args.from.display());}- restore_data_dir(&config.data_dir, &args.from, args.force)?;+ restore_data_dir_with_legacy_pepper(+ &config.data_dir,+ &args.from,+ args.force,+ config.auth.token_pepper.as_deref(),+ args.accept_legacy_api_key_pepper,+ )+ .await?;info!("restore complete");println!("restored {} -> {}",@@ -74,7 +81,18 @@ pub fn run(config: &Config, args: RestoreArgs) -> Result<()> {/// staged store has opened; the live `wiki/`, `db/` and (when the archive/// carries one) `config.toml` are then exchanged for the staged copies by/// rename and rolled back if any step of the exchange fails.-fn restore_data_dir(data_dir: &Path, from: &Path, force: bool) -> Result<()> {+#[cfg(test)]+async fn restore_data_dir(data_dir: &Path, from: &Path, force: bool) -> Result<()> {+ restore_data_dir_with_legacy_pepper(data_dir, from, force, None, false).await+}++async fn restore_data_dir_with_legacy_pepper(+ data_dir: &Path,+ from: &Path,+ force: bool,+ token_pepper: Option<&str>,+ accept_legacy_api_key_pepper: bool,+) -> Result<()> {let wiki = data_dir.join("wiki");let db = data_dir.join("db").join("memory.sqlite");let occupied = (wiki.is_dir() && std::fs::read_dir(&wiki)?.next().is_some()) || db.is_file();@@ -96,7 +114,15 @@ fn restore_data_dir(data_dir: &Path, from: &Path, force: bool) -> Result<()> {let staging = data_dir.join(format!(".restore-staging-{stamp}"));let previous = data_dir.join(format!(".restore-previous-{stamp}"));- let outcome = stage_then_swap(data_dir, from, &staging, &previous);+ let outcome = stage_then_swap(+ data_dir,+ from,+ &staging,+ &previous,+ token_pepper,+ accept_legacy_api_key_pepper,+ )+ .await;// The staging dir is scratch in every outcome: on success its contents// were moved into place, on failure the live data was never touched.if staging.exists()@@ -111,7 +137,14 @@ fn restore_data_dir(data_dir: &Path, from: &Path, force: bool) -> Result<()> {outcome}-fn stage_then_swap(data_dir: &Path, from: &Path, staging: &Path, previous: &Path) -> Result<()> {+async fn stage_then_swap(+ data_dir: &Path,+ from: &Path,+ staging: &Path,+ previous: &Path,+ token_pepper: Option<&str>,+ accept_legacy_api_key_pepper: bool,+) -> Result<()> {std::fs::create_dir(staging).with_context(|| format!("creating staging dir {}", staging.display()))?;@@ -130,7 +163,36 @@ fn stage_then_swap(data_dir: &Path, from: &Path, staging: &Path, previous: &Path// live is touched. Dropping the store joins the writer thread and// closes every connection, so the directory can be renamed afterwards// on Windows as well.- drop(Store::open(staging).context("opening restored store")?);+ let store = Store::open(staging).context("opening restored store")?;+ let has_api_credentials = store.reader.api_credentials_exist().await?;+ let has_pepper_verifier = store+ .reader+ .api_credential_pepper_verifier()+ .await?+ .is_some();+ if has_api_credentials && !has_pepper_verifier {+ if !accept_legacy_api_key_pepper {+ bail!(+ "the backup contains API keys but predates token-pepper verification; restore the original [auth].token_pepper and rerun with --accept-legacy-api-key-pepper to confirm it (the live data was not changed)"+ );+ }+ let pepper = token_pepper+ .filter(|value| !value.trim().is_empty())+ .context(+ "--accept-legacy-api-key-pepper requires the original non-blank [auth].token_pepper",+ )?;+ let verifier = ai_memory_store::password::hash_password(pepper.to_owned())+ .await+ .context("binding the confirmed legacy API-key pepper")?;+ if !store+ .writer+ .bind_api_credential_pepper_verifier(verifier)+ .await?+ {+ bail!("the restored API-key pepper verifier could not be bound");+ }+ }+ drop(store);// 3. Exchange the live directories for the staged ones.swap_into_place(data_dir, staging, previous)?;@@ -286,6 +348,7 @@ fn validate_restore_entry(path: &Path, entry_type: tar::EntryType) -> Result<()>#[cfg(test)]mod tests {use super::*;+ use ai_memory_core::{ApiCredentialId, NewUser, UserRole};fn archive_with_entry(path: &str, entry_type: tar::EntryType) -> Vec<u8> {let mut bytes = Vec::new();@@ -567,6 +630,48 @@ mod tests {std::fs::read(tmp.path().join("db/memory.sqlite")).unwrap()}+ async fn legacy_api_key_sqlite_bytes() -> Vec<u8> {+ let tmp = tempfile::TempDir::new().unwrap();+ let store = Store::open(tmp.path()).unwrap();+ let user_id = store+ .writer+ .create_human_user(+ NewUser {+ username: "legacy-restore-user".into(),+ name: None,+ email: None,+ },+ UserRole::User,+ None,+ false,+ )+ .await+ .unwrap();+ store+ .writer+ .create_api_credential(+ ApiCredentialId::new(),+ user_id,+ "legacy-key".into(),+ [0xA5; 32],+ Some("...test".into()),+ )+ .await+ .unwrap();+ assert!(+ store+ .reader+ .api_credential_pepper_verifier()+ .await+ .unwrap()+ .is_none()+ );+ let snapshot = tmp.path().join("legacy-snapshot.sqlite");+ store.reader.snapshot_to(snapshot.clone()).await.unwrap();+ drop(store);+ std::fs::read(snapshot).unwrap()+ }+/// A gzipped tarball holding the given regular files.fn gz_tarball(entries: &[(&str, &[u8])]) -> Vec<u8> {use std::io::Write as _;@@ -604,14 +709,16 @@ mod tests {path}- #[test]- fn restore_force_keeps_live_data_when_the_tarball_is_not_a_gzip_stream() {+ #[tokio::test]+ async fn restore_force_keeps_live_data_when_the_tarball_is_not_a_gzip_stream() {let data = tempfile::TempDir::new().unwrap();seed_live_data(data.path());let scratch = tempfile::TempDir::new().unwrap();let from = write_tarball(scratch.path(), "bad.tar.gz", b"this is not a gzip stream");- let err = restore_data_dir(data.path(), &from, true).unwrap_err();+ let err = restore_data_dir(data.path(), &from, true)+ .await+ .unwrap_err();assert!(format!("{err:#}").contains("extracting"),@@ -620,15 +727,17 @@ mod tests {assert_live_data_untouched(data.path());}- #[test]- fn restore_force_keeps_live_data_when_the_tarball_is_truncated() {+ #[tokio::test]+ async fn restore_force_keeps_live_data_when_the_tarball_is_truncated() {let data = tempfile::TempDir::new().unwrap();seed_live_data(data.path());let scratch = tempfile::TempDir::new().unwrap();let whole = good_archive();let from = write_tarball(scratch.path(), "cut.tar.gz", &whole[..whole.len() / 2]);- let err = restore_data_dir(data.path(), &from, true).unwrap_err();+ let err = restore_data_dir(data.path(), &from, true)+ .await+ .unwrap_err();assert!(format!("{err:#}").contains("extracting"),@@ -637,8 +746,8 @@ mod tests {assert_live_data_untouched(data.path());}- #[test]- fn restore_force_keeps_live_data_when_an_entry_is_outside_the_allowed_layout() {+ #[tokio::test]+ async fn restore_force_keeps_live_data_when_an_entry_is_outside_the_allowed_layout() {let data = tempfile::TempDir::new().unwrap();seed_live_data(data.path());let scratch = tempfile::TempDir::new().unwrap();@@ -655,7 +764,9 @@ mod tests {]),);- let err = restore_data_dir(data.path(), &from, true).unwrap_err();+ let err = restore_data_dir(data.path(), &from, true)+ .await+ .unwrap_err();assert!(format!("{err:#}").contains("unexpected path"),@@ -664,8 +775,8 @@ mod tests {assert_live_data_untouched(data.path());}- #[test]- fn restore_force_keeps_live_data_when_the_restored_store_cannot_open() {+ #[tokio::test]+ async fn restore_force_keeps_live_data_when_the_restored_store_cannot_open() {let data = tempfile::TempDir::new().unwrap();seed_live_data(data.path());let scratch = tempfile::TempDir::new().unwrap();@@ -678,7 +789,9 @@ mod tests {]),);- let err = restore_data_dir(data.path(), &from, true).unwrap_err();+ let err = restore_data_dir(data.path(), &from, true)+ .await+ .unwrap_err();assert!(format!("{err:#}").contains("opening restored store"),@@ -687,14 +800,16 @@ mod tests {assert_live_data_untouched(data.path());}- #[test]- fn restore_refuses_a_populated_data_dir_without_force() {+ #[tokio::test]+ async fn restore_refuses_a_populated_data_dir_without_force() {let data = tempfile::TempDir::new().unwrap();seed_live_data(data.path());let scratch = tempfile::TempDir::new().unwrap();let from = write_tarball(scratch.path(), "good.tar.gz", &good_archive());- let err = restore_data_dir(data.path(), &from, false).unwrap_err();+ let err = restore_data_dir(data.path(), &from, false)+ .await+ .unwrap_err();assert!(err.to_string().contains("pass --force"),@@ -703,14 +818,14 @@ mod tests {assert_live_data_untouched(data.path());}- #[test]- fn restore_force_replaces_the_live_data_with_the_archive() {+ #[tokio::test]+ async fn restore_force_replaces_the_live_data_with_the_archive() {let data = tempfile::TempDir::new().unwrap();seed_live_data(data.path());let scratch = tempfile::TempDir::new().unwrap();let from = write_tarball(scratch.path(), "good.tar.gz", &good_archive());- restore_data_dir(data.path(), &from, true).unwrap();+ restore_data_dir(data.path(), &from, true).await.unwrap();assert_eq!(std::fs::read(data.path().join("wiki/default/project/notes/new.md")).unwrap(),@@ -744,8 +859,8 @@ mod tests {drop(Store::open(data.path()).unwrap());}- #[test]- fn restore_keeps_the_live_config_when_the_archive_carries_none() {+ #[tokio::test]+ async fn restore_keeps_the_live_config_when_the_archive_carries_none() {let data = tempfile::TempDir::new().unwrap();seed_live_data(data.path());let scratch = tempfile::TempDir::new().unwrap();@@ -759,7 +874,7 @@ mod tests {]),);- restore_data_dir(data.path(), &from, true).unwrap();+ restore_data_dir(data.path(), &from, true).await.unwrap();assert_eq!(std::fs::read(data.path().join("config.toml")).unwrap(),@@ -772,13 +887,13 @@ mod tests {assert!(restore_scratch_dirs(data.path()).is_empty());}- #[test]- fn restore_into_an_empty_data_dir_needs_no_force() {+ #[tokio::test]+ async fn restore_into_an_empty_data_dir_needs_no_force() {let data = tempfile::TempDir::new().unwrap();let scratch = tempfile::TempDir::new().unwrap();let from = write_tarball(scratch.path(), "good.tar.gz", &good_archive());- restore_data_dir(data.path(), &from, false).unwrap();+ restore_data_dir(data.path(), &from, false).await.unwrap();assert_eq!(std::fs::read(data.path().join("wiki/default/project/notes/new.md")).unwrap(),@@ -787,4 +902,56 @@ mod tests {assert!(data.path().join("db/memory.sqlite").is_file());assert!(restore_scratch_dirs(data.path()).is_empty());}++ #[tokio::test]+ async fn legacy_api_key_restore_requires_original_pepper_confirmation() {+ let data = tempfile::TempDir::new().unwrap();+ seed_live_data(data.path());+ let scratch = tempfile::TempDir::new().unwrap();+ let db = legacy_api_key_sqlite_bytes().await;+ let from = write_tarball(+ scratch.path(),+ "legacy.tar.gz",+ &gz_tarball(&[("db/memory.sqlite", db.as_slice())]),+ );++ let refused = restore_data_dir_with_legacy_pepper(+ data.path(),+ &from,+ true,+ Some("original-pepper"),+ false,+ )+ .await+ .unwrap_err();+ assert!(+ refused+ .to_string()+ .contains("--accept-legacy-api-key-pepper"),+ "unexpected error: {refused:#}"+ );+ assert_live_data_untouched(data.path());++ restore_data_dir_with_legacy_pepper(+ data.path(),+ &from,+ true,+ Some("original-pepper"),+ true,+ )+ .await+ .unwrap();+ let restored = Store::open(data.path()).unwrap();+ let verifier = restored+ .reader+ .api_credential_pepper_verifier()+ .await+ .unwrap()+ .expect("confirmed pepper must be sealed into the restored database");+ assert!(+ ai_memory_store::password::verify_password("original-pepper".into(), verifier)+ .await+ .unwrap()+ );+ }}diff --git a/crates/ai-memory-cli/src/commands/run.rs b/crates/ai-memory-cli/src/commands/run.rsindex ea20193f..7445f72e 100644--- a/crates/ai-memory-cli/src/commands/run.rs+++ b/crates/ai-memory-cli/src/commands/run.rs@@ -188,6 +188,7 @@ struct AutoSessionCandidate {#[derive(Debug, Default)]struct HeartbeatHealth {consecutive_failures: u64,+ last_failure_kind: Option<HeartbeatFailureKind>,/// Set while the harness owns the terminal: a line written to stderr then/// lands inside its TUI (the prompt box, mid-render), so notices are held/// until the harness exits.@@ -232,19 +233,27 @@ impl HeartbeatHealth {lines}- fn record_failure(&mut self) -> bool {- let first = self.consecutive_failures == 0;+ fn record_failure(&mut self, kind: HeartbeatFailureKind) -> bool {+ let changed = self.last_failure_kind != Some(kind);self.consecutive_failures = self.consecutive_failures.saturating_add(1);- first+ self.last_failure_kind = Some(kind);+ changed}fn record_success(&mut self) -> bool {let recovered = self.consecutive_failures > 0;self.consecutive_failures = 0;+ self.last_failure_kind = None;recovered}}+#[derive(Debug, Clone, Copy, PartialEq, Eq)]+enum HeartbeatFailureKind {+ Unreachable,+ Rejected,+}+fn resolve_opencode_for_launch(requested: Option<RunHarnessChoice>,executable: Option<&OsStr>,@@ -2134,13 +2143,21 @@ async fn capture_interrupts(interrupted: CancellationToken) {/// finished, cancelled, or expired by a later prepare. Reporting it as an/// outage sends the operator looking for a server that never went away.fn heartbeat_failure_notice(error: &anyhow::Error) -> String {+ if heartbeat_failure_kind(error) == HeartbeatFailureKind::Rejected {+ format!("ai-memory: managed workstream heartbeat rejected: {error:#}; retrying quietly")+ } else {+ "ai-memory: server unavailable; managed workstream heartbeat will retry quietly".to_string()+ }+}++fn heartbeat_failure_kind(error: &anyhow::Error) -> HeartbeatFailureKind {if error.chain().any(|cause| cause.downcast_ref::<ServerResponseError>().is_some()){- format!("ai-memory: managed workstream heartbeat rejected: {error:#}; retrying quietly")+ HeartbeatFailureKind::Rejected} else {- "ai-memory: server unavailable; managed workstream heartbeat will retry quietly".to_string()+ HeartbeatFailureKind::Unreachable}}@@ -2171,7 +2188,7 @@ async fn send_managed_heartbeat_with_timeout();}Ok(()) => {}- Err(error) if health.record_failure() => {+ Err(error) if health.record_failure(heartbeat_failure_kind(error)) => {tracing::debug!(error = %error, "managed workstream heartbeat became unavailable");health.notify(heartbeat_failure_notice(error));}@@ -5861,12 +5878,13 @@ mod tests {fn heartbeat_health_reports_each_outage_and_recovery_once() {let mut health = HeartbeatHealth::default();- assert!(health.record_failure());- assert!(!health.record_failure());- assert!(!health.record_failure());+ assert!(health.record_failure(HeartbeatFailureKind::Unreachable));+ assert!(!health.record_failure(HeartbeatFailureKind::Unreachable));+ assert!(health.record_failure(HeartbeatFailureKind::Rejected));+ assert!(!health.record_failure(HeartbeatFailureKind::Rejected));assert!(health.record_success());assert!(!health.record_success());- assert!(health.record_failure());+ assert!(health.record_failure(HeartbeatFailureKind::Unreachable));}#[test]diff --git a/crates/ai-memory-cli/src/commands/serve.rs b/crates/ai-memory-cli/src/commands/serve.rsindex 215963ca..89467b16 100644--- a/crates/ai-memory-cli/src/commands/serve.rs+++ b/crates/ai-memory-cli/src/commands/serve.rs@@ -352,10 +352,16 @@ async fn validate_api_credential_pepper_binding(let verifier = ai_memory_store::password::hash_password(pepper.to_owned()).await.context("binding the configured API credential pepper")?;- store+ let bound = store.writer- .set_api_credential_pepper_verifier(verifier)+ .bind_api_credential_pepper_verifier(verifier).await?;+ if !bound {+ anyhow::bail!(+ "API credentials were added while binding [auth].token_pepper; restart so the \+ server can verify the final credential state"+ );+ }Ok(())}diff --git a/crates/ai-memory-cli/src/config.rs b/crates/ai-memory-cli/src/config.rsindex 77b92eae..3cc8f53e 100644--- a/crates/ai-memory-cli/src/config.rs+++ b/crates/ai-memory-cli/src/config.rs@@ -3416,11 +3416,42 @@ pub fn hook_auth_header_path_in(data_dir: &Path) -> PathBuf {/// Propagates IO failures from creating the data dir or writing either file.pub fn store_hook_auth_token(data_dir: &Path, token: &str) -> std::io::Result<()> {std::fs::create_dir_all(data_dir)?;- write_secret(&hook_auth_token_path_in(data_dir), token)?;- write_secret(- &hook_auth_header_path_in(data_dir),- &format!("Authorization: Bearer {token}\n"),- )+ let token_path = hook_auth_token_path_in(data_dir);+ let header_path = hook_auth_header_path_in(data_dir);+ let previous_token = read_optional_secret_bytes(&token_path)?;+ let previous_header = read_optional_secret_bytes(&header_path)?;++ write_secret(&token_path, token)?;+ if let Err(error) = write_secret(&header_path, &format!("Authorization: Bearer {token}\n")) {+ let token_rollback = restore_secret_bytes(&token_path, previous_token.as_deref());+ let header_rollback = restore_secret_bytes(&header_path, previous_header.as_deref());+ if let Err(rollback) = token_rollback.and(header_rollback) {+ return Err(std::io::Error::other(format!(+ "writing hook credential pair failed ({error}); rollback also failed ({rollback})"+ )));+ }+ return Err(error);+ }+ Ok(())+}++fn read_optional_secret_bytes(path: &Path) -> std::io::Result<Option<Vec<u8>>> {+ match std::fs::read(path) {+ Ok(bytes) => Ok(Some(bytes)),+ Err(error) if error.kind() == std::io::ErrorKind::NotFound => Ok(None),+ Err(error) => Err(error),+ }+}++fn restore_secret_bytes(path: &Path, previous: Option<&[u8]>) -> std::io::Result<()> {+ match previous {+ Some(bytes) => write_secret_bytes(path, bytes),+ None => match std::fs::remove_file(path) {+ Ok(()) => Ok(()),+ Err(error) if error.kind() == std::io::ErrorKind::NotFound => Ok(()),+ Err(error) => Err(error),+ },+ }}/// Remove a persisted bearer pair. Absent files are not an error.@@ -3460,6 +3491,10 @@ pub(crate) fn read_trimmed_secret(path: &Path) -> Option<String> {/// The mode is set on the handle before any bytes are written on Unix, so the/// secret is never briefly world-readable between `create` and `set_permissions`.fn write_secret(path: &Path, contents: &str) -> std::io::Result<()> {+ write_secret_bytes(path, contents.as_bytes())+}++fn write_secret_bytes(path: &Path, contents: &[u8]) -> std::io::Result<()> {#[cfg(unix)]{use std::io::Write as _;@@ -3470,7 +3505,7 @@ fn write_secret(path: &Path, contents: &str) -> std::io::Result<()> {.truncate(true).mode(0o600).open(path)?;- file.write_all(contents.as_bytes())+ file.write_all(contents)}#[cfg(not(unix))]{@@ -3505,7 +3540,15 @@ fn canonicalise_or_keep(p: &Path) -> PathBuf {{return canon_parent.join(name);}- p.to_path_buf()+ if p.is_absolute() {+ return p.to_path_buf();+ }+ // A nested path may have no existing ancestor beyond the current+ // directory yet. Keep the invocation-time meaning when this path is later+ // embedded in an MCP entry launched from an unrelated project directory.+ std::env::current_dir()+ .map(|cwd| cwd.join(p))+ .unwrap_or_else(|_| p.to_path_buf())}/// Normalize home for prefix-match comparisons: accept either slash spelling,@@ -3606,6 +3649,25 @@ mod tests {);}+ #[test]+ fn an_invalid_header_target_cannot_partially_replace_the_token() {+ let tmp = TempDir::new().unwrap();+ let dd = tmp.path().join("data");+ std::fs::create_dir_all(hook_auth_header_path_in(&dd)).unwrap();++ let error = store_hook_auth_token(&dd, "must-not-stick").unwrap_err();+ assert_ne!(error.kind(), std::io::ErrorKind::NotFound);+ assert!(!hook_auth_token_path_in(&dd).exists());+ }++ #[test]+ fn a_nested_nonexistent_relative_data_dir_becomes_absolute() {+ let relative = Path::new("target/nonexistent-ai-memory-test/data");+ let resolved = canonicalise_or_keep(relative);+ assert!(resolved.is_absolute(), "{}", resolved.display());+ assert!(resolved.ends_with(relative));+ }+/// Absent, empty, and whitespace-only files all read as "no token" rather/// than as an empty bearer, which would send `Authorization: Bearer `.#[test]diff --git a/crates/ai-memory-cli/src/lib.rs b/crates/ai-memory-cli/src/lib.rsindex ed5dbf88..df30de1b 100644--- a/crates/ai-memory-cli/src/lib.rs+++ b/crates/ai-memory-cli/src/lib.rs@@ -148,7 +148,7 @@ pub async fn run() -> Result<()> {Command::Backup(args) => commands::backup::run(&config, args).await,Command::BackupAgents(args) => commands::backup_agents::run(&config, args),Command::ExportOkf(args) => commands::export_okf::run(&config, args).await,- Command::Restore(args) => commands::restore::run(&config, args),+ Command::Restore(args) => commands::restore::run(&config, args).await,Command::RestoreAgents(args) => commands::restore_agents::run(&config, args),Command::Reindex(args) => commands::reindex::run(&config, args).await,Command::InstallHooks(args) => commands::install_hooks::run(&config, args),diff --git a/crates/ai-memory-store/src/api_credentials.rs b/crates/ai-memory-store/src/api_credentials.rsindex bc7048fa..8d16c175 100644--- a/crates/ai-memory-store/src/api_credentials.rs+++ b/crates/ai-memory-store/src/api_credentials.rs@@ -275,24 +275,26 @@ pub fn api_credential_pepper_verifier(conn: &Connection) -> StoreResult<Option<S.map_err(StoreError::from)}-/// Insert or replace the verifier for the configured native-key pepper.+/// Bind the verifier for the configured native-key pepper.///-/// The caller decides whether replacement is allowed after checking whether-/// any credentials exist. Keeping that policy above this storage primitive-/// lets startup perform the expensive Argon2id verification off the writer-/// thread.+/// An upgraded database may have credentials but no verifier yet, so the+/// initial insert is always allowed. Once a verifier exists, replacement is+/// allowed only while `api_credentials` is empty. Enforcing that condition in+/// this writer-thread statement keeps a future caller from rotating the+/// verifier out from under existing hashes.////// # Errors/// SQL failures.-pub fn set_api_credential_pepper_verifier(conn: &Connection, verifier: &str) -> StoreResult<()> {- conn.execute(+pub fn bind_api_credential_pepper_verifier(conn: &Connection, verifier: &str) -> StoreResult<bool> {+ let changed = conn.execute("INSERT INTO api_credential_pepper_state (singleton, verifier, updated_at) \VALUES (1, ?1, ?2) \ON CONFLICT(singleton) DO UPDATE SET \- verifier = excluded.verifier, updated_at = excluded.updated_at",+ verifier = excluded.verifier, updated_at = excluded.updated_at \+ WHERE NOT EXISTS (SELECT 1 FROM api_credentials)",params![verifier, Timestamp::now().as_microsecond()],)?;- Ok(())+ Ok(changed == 1)}fn row_to_credential(row: &rusqlite::Row<'_>) -> rusqlite::Result<ApiCredential> {@@ -480,6 +482,45 @@ mod tests {assert_eq!(cols, 0, "V79 drops the 1.x token columns");}+ #[test]+ fn pepper_verifier_can_bind_legacy_keys_but_cannot_rotate_under_keys() {+ let mut conn = Connection::open_in_memory().unwrap();+ conn.pragma_update(None, "foreign_keys", "ON").unwrap();+ crate::migrations::run(&mut conn).unwrap();+ let mut user = NewUser {+ username: "pepper-owner".into(),+ name: None,+ email: None,+ };+ user.validate().unwrap();+ let user_id =+ users::insert_human_user(&conn, &user, UserRole::User, Some("phc"), false).unwrap();+ let credential_id = ApiCredentialId::new();+ insert_api_credential(+ &conn,+ credential_id,+ user_id,+ "legacy",+ &[7_u8; TOKEN_HASH_LEN],+ None,+ )+ .unwrap();++ assert!(bind_api_credential_pepper_verifier(&conn, "original-phc").unwrap());+ assert!(!bind_api_credential_pepper_verifier(&conn, "replacement-phc").unwrap());+ assert_eq!(+ api_credential_pepper_verifier(&conn).unwrap().as_deref(),+ Some("original-phc")+ );++ conn.execute("DELETE FROM api_credentials", []).unwrap();+ assert!(bind_api_credential_pepper_verifier(&conn, "replacement-phc").unwrap());+ assert_eq!(+ api_credential_pepper_verifier(&conn).unwrap().as_deref(),+ Some("replacement-phc")+ );+ }+fn column_count(conn: &Connection, table: &str, column: &str) -> i64 {conn.query_row("SELECT COUNT(*) FROM pragma_table_info(?1) WHERE name = ?2",diff --git a/crates/ai-memory-store/src/writer.rs b/crates/ai-memory-store/src/writer.rsindex d56783c7..d90ebee0 100644--- a/crates/ai-memory-store/src/writer.rs+++ b/crates/ai-memory-store/src/writer.rs@@ -719,9 +719,9 @@ pub(crate) enum WriteCmd {id: ApiCredentialId,reply: oneshot::Sender<StoreResult<bool>>,},- SetApiCredentialPepperVerifier {+ BindApiCredentialPepperVerifier {verifier: String,- reply: oneshot::Sender<StoreResult<()>>,+ reply: oneshot::Sender<StoreResult<bool>>,},TouchUserLastSeen {user_id: UserId,@@ -3245,9 +3245,9 @@ impl WriterHandle {////// # Errors/// Writer closed / SQL.- pub async fn set_api_credential_pepper_verifier(&self, verifier: String) -> StoreResult<()> {+ pub async fn bind_api_credential_pepper_verifier(&self, verifier: String) -> StoreResult<bool> {let (tx, rx) = oneshot::channel();- self.send(WriteCmd::SetApiCredentialPepperVerifier {+ self.send(WriteCmd::BindApiCredentialPepperVerifier {verifier,reply: tx,})@@ -4783,9 +4783,9 @@ fn worker_loop(mut conn: Connection, mut rx: mpsc::Receiver<WriteCmd>) {let result = api_credentials::touch_api_credential(&conn, id);send_or_warn(reply, result, "touch_api_credential");}- WriteCmd::SetApiCredentialPepperVerifier { verifier, reply } => {- let result = api_credentials::set_api_credential_pepper_verifier(&conn, &verifier);- send_or_warn(reply, result, "set_api_credential_pepper_verifier");+ WriteCmd::BindApiCredentialPepperVerifier { verifier, reply } => {+ let result = api_credentials::bind_api_credential_pepper_verifier(&conn, &verifier);+ send_or_warn(reply, result, "bind_api_credential_pepper_verifier");}WriteCmd::TouchUserLastSeen { user_id, reply } => {let result = users::touch_user_last_seen(&conn, user_id);diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.mdindex afd52f16..0b943138 100644--- a/docs/ARCHITECTURE.md+++ b/docs/ARCHITECTURE.md@@ -731,9 +731,11 @@ cwd parameters use their canonical names.`ai-memory mcp-bridge` is a transport adapter, not a second toolimplementation. It serves the upstream tool catalogue over local stdio anddelegates tool calls to the configured HTTP server through rmcp's client-transport, authenticating with the bearer `Config::load` resolved, so the-server keeps the same auth, scope resolver, and tool handlers as direct HTTP-clients. It has two modes, chosen by the entry that launches it:+transport. It uses the bearer `Config::load` resolved, or the install's stored+hook key before a loopback-only discovered root key. Implicit install-local+keys are accepted only for that install's configured endpoint. The server+therefore keeps the same auth, scope resolver, and tool handlers as direct+HTTP clients. It has two modes, chosen by the entry that launches it:- session-aware (Claude Code, `install-mcp --client claude-code--session-aware`, and every Claude Code entry on a token-file install; anddiff --git a/docs/backup.md b/docs/backup.mdindex 80409bf4..02ef3ee2 100644--- a/docs/backup.md+++ b/docs/backup.md@@ -150,24 +150,25 @@ Two caveats:synthesized. Treat the remote the same way you treat any project source:private repository, restrictive access controls.-## Backing up the whole data dir (mirror + push)+## Backing up a wiki/config mirror plus SQLite snapshot-For a full-install backup (wiki, raw ledger, sanitized config), the-supported pattern is a scheduled rsync into a mirror git repository, followed-by a git push. This avoids running git operations against the live wiki-repository (which the server writes to) while still giving you a single-remote with the full recoverable state.+For a scheduled off-site copy, mirror the wiki and selected config into a+private git repository, then ask the running server for a separate consistent+SQLite snapshot. The mirror is intentionally incomplete; the snapshot carries+the DB-only state that `reindex` cannot reconstruct. Either copy may contain+secrets or private memory and must be protected accordingly.A worked example lives at[`docs/examples/backup/`](examples/backup/README.md) and consists of:- `ai-memory-snapshot.sh`: an idempotent rsync + `git commit && git push` +- tarball script driven by six environment variables.+ online `ai-memory backup` script driven by environment variables.- `ai-memory-backup.service`: a `systemd --user` oneshot unit that runs it.- `ai-memory-backup.timer`: a daily user timer with a randomised delay and`Persistent=true` so a missed run after a reboot still fires.- `.gitignore`: an exclusion list to drop into the root of the mirror- repository so derived state and secrets never land in commits.+ repository so derived state and common standalone secret files do not land+ in commits. It cannot remove secrets stored inline in `config.toml`.The high-level flow, one invocation per day (adjust the timer for a differentcadence):@@ -182,9 +183,10 @@ cadence):changed; skip if there is no delta.4. `git push origin main` with a timeout so a hung network does not block thenext run.-5. `tar czf $TARBALL_DIR/ai-memory-$(date +%F).tar.gz` a copy of the same- tree, so the DB and models can be recovered without a `reindex` after a- catastrophic disk loss.+5. Run `ai-memory backup --to+ $TARBALL_DIR/ai-memory-$(date +%F).tar.gz` so SQLite is copied through its+ online backup API rather than racing the live WAL. Models are not included;+ redownload them after recovery.6. Rotate old tarballs and old script logs on a retention window (30 days bydefault).@@ -219,11 +221,14 @@ out-of-scope for v1). What that means in practice:- **Least-privilege push credential.** Prefer an SSH deploy key or afine-grained personal-access token scoped to the mirror repository only.Rotate on the same cadence you rotate other long-lived push credentials.-- **Explicit secret exclusion.** The example script rejects any file matching+- **Explicit secret exclusion.** The example script excludes files matching`SECRET_EXCLUDES` (`*.env`, `auth.json`, `.secrets`, `*.pem`, `*.key`, `*.crt` by default), and thesuggested mirror-repo `.gitignore` matches the same set. Add anything elseinstall-specific (private CA bundles, host-side certificates, cloud- credential files) to both lists.+ credential files) to both lists. These path rules do not inspect TOML:+ `[auth]` tokens, `token_pepper`, or sensitive LLM headers stored inline in+ `config.toml` will be committed. Remove them from the mirror or encrypt and+ access-control the repository as a secret store.- **Encryption at rest is out of scope for ai-memory.** If your threat modelrequires it, either put the mirror on an encrypted remote (`git-crypt`,GitLab's group-level encryption, a self-hosted Gitea over TLS with diskdiff --git a/docs/design-marketplace-plugins.md b/docs/design-marketplace-plugins.mdindex b94527f9..30e639d8 100644--- a/docs/design-marketplace-plugins.md+++ b/docs/design-marketplace-plugins.md@@ -326,7 +326,7 @@ install.| Server URL | `userConfig.server_url` (string) | empty (shipped; proposed `http://127.0.0.1:49374`) | Read by the launcher from `CLAUDE_PLUGIN_OPTION_SERVER_URL`; MCP gets `${user_config.server_url}`. Empty means the `server_url` of the ai-memory config, for hooks and MCP alike || Binary path | `userConfig.ai_memory_bin` (string) | `ai-memory` | For installs off `PATH` || Data dir | `userConfig.data_dir` (string) | empty | Only for a non-default data dir |-| Token | **none in the plugin** | — | Hooks read `<data_dir>/auth-token`, the OIDC `auth.json` or a server profile; `mcp-bridge` reads the bearer `Config::load` resolves. Same files `setup`, `install-hooks --auth-token` and `auth login` already write |+| Token | **none in the plugin** | — | Hooks read `<data_dir>/auth-token`, the OIDC `auth.json` or a server profile; `mcp-bridge` uses configured auth, then the same stored hook key, then loopback-only discovered root auth. Implicit install-local keys never follow an endpoint override. Same files `setup`, `install-hooks --auth-token` and `auth login` already write || Project override, capture mode, `ignore_paths`, briefing, server routing | `.ai-memory.toml` marker, persisted capture mode, `servers.toml` profiles | as today | The native hook already enforces all of these. Nothing is duplicated into plugin settings |Keeping the token out of the plugin keeps one credential store for hooks, MCPdiff --git a/docs/examples/backup/.gitignore b/docs/examples/backup/.gitignoreindex 4c3cde78..50ef0796 100644--- a/docs/examples/backup/.gitignore+++ b/docs/examples/backup/.gitignore@@ -7,10 +7,11 @@# _prompts pages, since those are irreplaceable.# - Keep raw/ if you want the untouched observation ledger, drop it if you# want a small repository.-# - Never commit derived state (db/) or downloaded weights (models/), and-# never commit secrets.+# - Never commit derived state (db/) or downloaded weights (models/).+# - Exclude common standalone secret files. This cannot redact credentials+# stored inline in config.toml; omit that file or encrypt the repository.-# Secrets — belt and braces alongside the rsync SECRET_EXCLUDES list.+# Common standalone secrets — belt and braces alongside SECRET_EXCLUDES.config/*.envconfig/**/*.envconfig/auth.jsondiff --git a/docs/examples/backup/README.md b/docs/examples/backup/README.mdindex fc58ad27..d4903c70 100644--- a/docs/examples/backup/README.md+++ b/docs/examples/backup/README.md@@ -1,8 +1,9 @@# Remote git backup exampleSample scripts + unit files that push an ai-memory install to a remote git-repository on a daily cadence, keeping a tarball on a second location for the-SQLite index and models cache that the mirror repo deliberately excludes.+repository on a daily cadence, keeping an online `ai-memory backup` snapshot+on a second location for the SQLite state that the mirror repo deliberately+excludes. Models remain redownloadable and are not backed up.See [`docs/backup.md`](../../backup.md) for the walkthrough. The pieces in thisdirectory are:@@ -77,4 +78,9 @@ private repository, a fine-grained token scoped to that one repo (or an SSHdeploy key), and rotate credentials the same way you rotate any otherlong-lived push credential. The script never commits files matched by`SECRET_EXCLUDES` (default: `*.env`, `auth.json`, `.secrets`, `*.pem`, `*.key`, `*.crt`); the mirror-repo's `.gitignore` catches anything the rsync exclude missed.+repo's `.gitignore` catches anything the rsync exclude missed. The separate+online snapshot may include `<data_dir>/config.toml`, including secrets stored+inline there, and always contains private memory data. The git mirror can also+include inline secrets from the copied config directory because filename globs+cannot redact TOML values. Inspect or encrypt both outputs and protect them as+secret-bearing artifacts.diff --git a/docs/examples/backup/ai-memory-snapshot.sh b/docs/examples/backup/ai-memory-snapshot.shindex f7d7f09b..8480d803 100644--- a/docs/examples/backup/ai-memory-snapshot.sh+++ b/docs/examples/backup/ai-memory-snapshot.sh@@ -6,10 +6,8 @@# excluding derived state and secrets (see .gitignore in this dir).# 2. commit + push the mirror to a remote git repository when anything# changed.-# 3. write a compressed tarball of the same tree to a second location-# (a mounted external disk, a network share, or on WSL2 the Windows-side-# filesystem) so the SQLite index can be recovered from disk even if the-# remote repository is unreachable.+# 3. ask the running server for a consistent online backup (wiki + SQLite ++# data-dir config.toml) and write it to a second location.## Assumptions:# - You already ran `git init && git remote add origin <url>` inside@@ -19,7 +17,7 @@# - $DATA_SRC is the ai-memory data dir (`ai-memory status` prints it) and# $CFG_SRC is where your provider env-file lives.#-# Configure these four variables for your host, or export them from the+# Configure these variables for your host, or export them from the# systemd unit's Environment= lines. Sample values are commented out.: "${REPO_DIR:=$HOME/ai-memory-backup}" # local mirror checkout, `git init`'d and pointed at a remote: "${DATA_SRC:=$HOME/.local/share/ai-memory}" # ai-memory data dir@@ -87,23 +85,9 @@ elsetimeout 180 git push origin "$(git rev-parse --abbrev-ref HEAD)" 2>&1 | tail -10fi-echo "--- tarball to second location ---"+echo "--- online data snapshot to second location ---"tarball="$TARBALL_DIR/ai-memory-$stamp.tar.gz"-tar_excludes=(- --exclude=.git- --exclude=models- --exclude=db- --exclude=logs- --exclude=.serve.lock-)-for glob in $SECRET_EXCLUDES; do- tar_excludes+=(--exclude="$glob")-done-# Use paths relative to $HOME so the archive is portable across usernames.-tar czf "$tarball" "${tar_excludes[@]}" \- -C "$HOME" \- "${DATA_SRC#$HOME/}" \- "${CFG_SRC#$HOME/}"+ai-memory --data-dir "$DATA_SRC" backup --to "$tarball"echo "tarball: $(ls -lh "$tarball" | awk '{print $5, $9}')"echo "--- rotate tarballs (retention: ${TARBALL_RETENTION_DAYS}d) ---"diff --git a/docs/install.md b/docs/install.mdindex 4733d71a..74ae8731 100644--- a/docs/install.md+++ b/docs/install.md@@ -1025,8 +1025,9 @@ opt-in**: enable the server first, then the client:The client sanitizes (built-in patterns) and truncates the excerpt before ittouches the spool or wire; the server re-scrubs with its `[sanitize]` patternsbefore storing. If either side is off, or the marker is malformed, the Stop-stays empty. Re-running `install-hooks` without `--capture-assistant` removes-the flag (idempotent). `--capture-assistant` is Claude Code, Codex and+stays empty. Re-running `install-hooks` without `--capture-assistant` preserves+an existing opt-in. To remove it, run `ai-memory uninstall --only hooks+--apply --yes`, then reinstall without the flag. `--capture-assistant` is Claude Code, Codex andOpenCode 2 (`--agent opencode2`) on a native hook platform only; on any other agent or the script fallback theinstaller refuses it rather than enabling something that cannot take effect. Assistant text isprivacy-sensitive. Read the `SECURITY.md` notes on what it can contain and wherediff --git a/docs/lifecycle-ops.md b/docs/lifecycle-ops.mdindex 962066ce..bc8d1c73 100644--- a/docs/lifecycle-ops.md+++ b/docs/lifecycle-ops.md@@ -624,7 +624,7 @@ deletes: its `sessions`, `observations`, and `handoffs` (the raw episodiccapture log), its managed workstreams with their native sessions, runs,events and `raw/workstreams/` segments, the cross-project messages it sentor received, auto-improvement and profile-harvest state, session-consolidation-jobs, ingest deduplication keys, entities, page feedback, purge tombstones and+jobs, ingest deduplication keys, entities, page feedback, per-session purge tombstones andproject grants. The moved pages start a fresh supersession chain (the realpage history lives in the wiki's git mirror). The append-only audit trailremains, with references to the removed source ids. The `true-move` path has@@ -1142,10 +1142,13 @@ move: `ai-memory backup` first, then proceed.This tarball is an online **data snapshot**, not a complete host image. Itintentionally excludes `auth-tokens/`, the hook-side `auth-token` and`auth-header` files, `raw/`, logs, models, and a config passed from outside the-data dir with `--config`. That keeps bearer credentials out of an archive that-is commonly copied between machines, and avoids racing the actively appended+data dir with `--config`. The included `<data_dir>/config.toml` is archived+verbatim and may itself contain inline root/proxy/recovery credentials, the+API-key pepper, or sensitive LLM headers. Always protect the snapshot as a+secret-bearing artifact. Excluding the separate credential files limits the+copied auth material; omitting `raw/` avoids racing the actively appendedmanaged-workstream ledger. The SQLite snapshot still contains the searchable-managed-workstream events; omitting `raw/` loses their immutable source copy.+managed-workstream events, but loses their immutable source copy.For a move to another host, carry these beside the snapshot through aseparately encrypted or otherwise access-controlled backup:@@ -1167,7 +1170,10 @@ restored database contains native API credentials but the destination loads adifferent pepper, `serve` refuses instead of starting with keys that can neverauthenticate. A database first opened by a version that predates this verifiercannot prove which pepper created its existing hashes; for those older-snapshots, restoring the original external config remains mandatory.+snapshots, restoring the original external config remains mandatory. Restore+refuses such a database until the operator supplies that original pepper and+adds `--accept-legacy-api-key-pepper`, which seals a verifier into the staged+database before the live data is changed.Restoring a backup follows the inverse:@@ -1199,7 +1205,9 @@ Order of operations:2. Extract the tarball into a staging directory beside the live data(`<data_dir>/.restore-staging-<stamp>/`), validating every entry.3. Open the staged store so pending migrations run and the SQLite- snapshot is verified, still without touching the live data.+ snapshot is verified, still without touching the live data. A legacy+ database with API keys but no pepper verifier stops here unless the original+ pepper is configured and `--accept-legacy-api-key-pepper` was passed.4. Swap: rename the live `wiki/` and `db/` (and `config.toml`, when thearchive carries one) aside, rename the staged copies into place, thendelete the previous data. Each move is a same-filesystem rename; if@@ -1221,6 +1229,10 @@ Failure modes:a snapshot the current binary cannot open** (for example a backup takenby a newer release) → exits with the error; the existing `wiki/` and`db/` are left as they were.+- **Legacy backup has API keys but no pepper verifier** → restore the original+ `[auth].token_pepper` through the current config/environment and rerun with+ `--accept-legacy-api-key-pepper`. This flag confirms provenance; it cannot+ determine whether an unknown pepper is correct.- **A rename in the swap fails and cannot be reversed** → exits with an`INCONSISTENT STATE` message naming the`<data_dir>/.restore-previous-<stamp>/` directory that still holds thediff --git a/docs/users.md b/docs/users.mdindex 44de5870..52696cf3 100644--- a/docs/users.md+++ b/docs/users.md@@ -424,8 +424,10 @@ a different pepper instead of starting with keys that can only return 401.Restore the original pepper from a separately protected configuration backuprather than deleting identities or keys: `ai-memory backup` includes only a`config.toml` inside the data dir, while packaged systemd units load one from-outside it. Snapshots created before the verifier existed cannot be checked-and still require the original config.+outside it. A restore of a snapshot created before the verifier existed fails+closed when keys are present. Load the original pepper and explicitly confirm+it with `ai-memory restore --accept-legacy-api-key-pepper`; the staged database+is sealed before it replaces live data.### 2. Add another human