Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors
Rust
feat(cli): support native Windows zip self-upgrade
Test335424b742d7
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 49939fe2..560eb27e 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -8,17 +8,19 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0## [Unreleased]### Added-- Native `ai-memory upgrade` for GitHub-release Unix installs (Linux/macOS):- downloads the matching release tarball, verifies the `.sha256` sidecar,- atomically replaces the on-disk binary (and a sibling `hooks/` tree when- present), then re-runs `install-hooks --apply` for staged agents. Refuses- package-managed paths (Homebrew/AUR/`/usr`), containers, and Windows- self-replace; the Docker wrapper's `upgrade` path is unchanged. Pin with- `--version` / force a re-download with `--force`. Optional+- Native `ai-memory upgrade` for GitHub-release installs (Linux/macOS+ tarballs and Windows x86_64 zip): downloads the matching release archive,+ verifies the `.sha256` sidecar, replaces the on-disk binary (and a sibling+ `hooks/` tree when present), then re-runs `install-hooks --apply` for staged+ agents. Windows uses rename-aside self-replace (running `.exe` → `.old`,+ promote `.new`) because the mapped image cannot be overwritten in place.+ Refuses package-managed paths (Homebrew/AUR/`/usr`), containers, and+ unwritable prefixes; the Docker wrapper's `upgrade` path is unchanged. Pin+ with `--version` / force a re-download with `--force`. Optional`AI_MEMORY_RELEASE_BASE_URL` / `release_base_url` overrides the Releasesbase for mirrors and hermetic tests (loaded via `Config`, not ad-hoc env).Downloads refuse bodies over 128 MiB (Content-Length and streamed cap).- (#801)+ (#801, #802)- `ai-memory run` accepts a repeatable `--env KEY=VALUE` and an `--env-file<path>` (blank lines and `#` comments skipped) to pass extra environmentinto the spawned harness — e.g. a per-account `CLAUDE_CONFIG_DIR` fordiff --git a/Cargo.lock b/Cargo.lockindex 8c08bbf3..5e1c4dd4 100644--- a/Cargo.lock+++ b/Cargo.lock@@ -8,6 +8,17 @@ version = "2.0.1"source = "registry+https://github.com/rust-lang/crates.io-index"checksum = "320119579fcad9c21884f5c4861d16174d0e06250625266f50fe6898340abefa"+[[package]]+name = "aes"+version = "0.9.3"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "35f0f96ce78e38c3dc6d8948aa8163d06385be74000f3c7a95bf1eef35d3ea32"+dependencies = [+ "cipher",+ "cpubits",+ "cpufeatures 0.3.0",+]+[[package]]name = "ahash"version = "0.8.12"@@ -64,7 +75,7 @@ dependencies = ["secrecy","serde","serde_json",- "sha2",+ "sha2 0.10.9","socket2","sysinfo","tar",@@ -78,6 +89,7 @@ dependencies = ["tracing-appender","tracing-subscriber","uuid",+ "zip",][[package]]@@ -98,7 +110,7 @@ dependencies = ["schemars","serde","serde_json",- "sha2",+ "sha2 0.10.9","tempfile","thiserror 2.0.18","tokio",@@ -137,7 +149,7 @@ dependencies = ["secrecy","serde","serde_json",- "sha2",+ "sha2 0.10.9","tempfile","tokio","tracing",@@ -163,7 +175,7 @@ dependencies = ["serde","serde_json","serde_urlencoded",- "sha2",+ "sha2 0.10.9","tempfile","tokio","tracing",@@ -189,7 +201,7 @@ dependencies = ["secrecy","serde","serde_json",- "sha2",+ "sha2 0.10.9","tempfile","thiserror 2.0.18","tokenizers",@@ -249,7 +261,7 @@ dependencies = ["rusqlite","serde","serde_json",- "sha2",+ "sha2 0.10.9","subtle","tempfile","thiserror 2.0.18",@@ -277,7 +289,7 @@ dependencies = ["pulldown-cmark","serde","serde_json",- "sha2",+ "sha2 0.10.9","tempfile","thiserror 2.0.18","tokio",@@ -328,7 +340,7 @@ dependencies = ["rusqlite","serde","serde_json",- "sha2",+ "sha2 0.10.9","tempfile","tokio","uuid",@@ -609,7 +621,7 @@ version = "0.10.6"source = "registry+https://github.com/rust-lang/crates.io-index"checksum = "46502ad458c9a52b69d4d4d32775c788b7a1b85e8bc9d482d92250fc0e3f8efe"dependencies = [- "digest",+ "digest 0.10.7",][[package]]@@ -621,6 +633,16 @@ dependencies = ["generic-array",]+[[package]]+name = "block-buffer"+version = "0.12.1"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "d2f6c7dbe95a6ed67ad9f18e57daf93a2f034c524b99fd2b76d18fdfeb6660aa"+dependencies = [+ "hybrid-array",+ "zeroize",+]+[[package]]name = "bumpalo"version = "3.20.2"@@ -659,6 +681,15 @@ version = "1.11.1"source = "registry+https://github.com/rust-lang/crates.io-index"checksum = "1e748733b7cbc798e1434b6ac524f0c1ff2ab456fe201501e6497c8417a4fc33"+[[package]]+name = "bzip2"+version = "0.6.1"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "f3a53fac24f34a81bc9954b5d6cfce0c21e18ec6959f44f56e8e90e4bb7c346c"+dependencies = [+ "libbz2-rs-sys",+]+[[package]]name = "candle-core"version = "0.11.0"@@ -776,6 +807,16 @@ dependencies = ["windows-link",]+[[package]]+name = "cipher"+version = "0.5.2"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "e8cf2a2c93cd704877c0858356ed03480ff301ee950b43f1cbe4573b088bfa6c"+dependencies = [+ "crypto-common 0.2.2",+ "inout",+]+[[package]]name = "clap"version = "4.6.1"@@ -825,6 +866,12 @@ version = "1.1.0"source = "registry+https://github.com/rust-lang/crates.io-index"checksum = "c8d4a3bb8b1e0c1050499d1815f5ab16d04f0959b233085fb31653fbfc9d98f9"+[[package]]+name = "cmov"+version = "0.5.4"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "0c9ea0ac24bc397ab3c98583a3c9ba74fa56b09a4449bbe172b9b1ddb016027a"+[[package]]name = "colorchoice"version = "1.0.5"@@ -856,6 +903,18 @@ dependencies = ["static_assertions",]+[[package]]+name = "const-oid"+version = "0.10.2"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "a6ef517f0926dd24a1582492c791b6a4818a4d94e789a334894aa15b0d12f55c"++[[package]]+name = "constant_time_eq"+version = "0.4.2"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "3d52eff69cd5e647efe296129160853a42795992097e8af39800e1060caeea9b"+[[package]]name = "convert_case"version = "0.10.0"@@ -881,6 +940,12 @@ version = "0.8.7"source = "registry+https://github.com/rust-lang/crates.io-index"checksum = "773648b94d0e5d620f64f280777445740e61fe701025087ec8b57f45c791888b"+[[package]]+name = "cpubits"+version = "0.1.1"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "15b85f9c39137c3a891689859392b1bd49812121d0d61c9caf00d46ed5ce06ae"+[[package]]name = "cpufeatures"version = "0.2.17"@@ -985,6 +1050,24 @@ dependencies = ["typenum",]+[[package]]+name = "crypto-common"+version = "0.2.2"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "ce6e4c961d6cd6c9a86db418387425e8bdeaf05b3c8bc1411e6dca4c252f1453"+dependencies = [+ "hybrid-array",+]++[[package]]+name = "ctutils"+version = "0.4.2"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "7d5515a3834141de9eafb9717ad39eea8247b5674e6066c404e8c4b365d2a29e"+dependencies = [+ "cmov",+]+[[package]]name = "darling"version = "0.20.11"@@ -1081,6 +1164,12 @@ version = "0.1.4"source = "registry+https://github.com/rust-lang/crates.io-index"checksum = "092966b41edc516079bdf31ec78a2e0588d1d0c08f78b91d8307215928642b2b"+[[package]]+name = "deflate64"+version = "0.1.12"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "ac6b926516df9c60bfa16e107b21086399f8285a44ca9711344b9e553c5146e2"+[[package]]name = "deranged"version = "0.5.8"@@ -1149,11 +1238,24 @@ version = "0.10.7"source = "registry+https://github.com/rust-lang/crates.io-index"checksum = "9ed9a281f7bc9b7576e61468ba615a66a5c8cfdff42420a70aa82701a3b1e292"dependencies = [- "block-buffer",- "crypto-common",+ "block-buffer 0.10.4",+ "crypto-common 0.1.7","subtle",]+[[package]]+name = "digest"+version = "0.11.3"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "f1dd6dbb5841937940781866fa1281a1ff7bd3bf827091440879f9994983d5c2"+dependencies = [+ "block-buffer 0.12.1",+ "const-oid",+ "crypto-common 0.2.2",+ "ctutils",+ "zeroize",+]+[[package]]name = "dirs"version = "5.0.1"@@ -1344,6 +1446,7 @@ checksum = "843fba2746e448b37e26a819579957415c8cef339bf08564fe8b7ddbd959573c"dependencies = ["crc32fast","miniz_oxide",+ "zlib-rs",][[package]]@@ -1661,11 +1764,13 @@ source = "registry+https://github.com/rust-lang/crates.io-index"checksum = "0de51e6874e94e7bf76d726fc5d13ba782deca734ff60d5bb2fb2607c7406555"dependencies = ["cfg-if",+ "js-sys","libc","r-efi 6.0.0","rand_core 0.10.1","wasip2","wasip3",+ "wasm-bindgen",][[package]]@@ -1778,6 +1883,15 @@ version = "0.5.2"source = "registry+https://github.com/rust-lang/crates.io-index"checksum = "fc0fef456e4baa96da950455cd02c081ca953b141298e41db3fc7e36b1da849c"+[[package]]+name = "hmac"+version = "0.13.0"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "6303bc9732ae41b04cb554b844a762b4115a61bfaa81e3e83050991eeb56863f"+dependencies = [+ "digest 0.11.3",+]+[[package]]name = "http"version = "1.4.0"@@ -1838,6 +1952,15 @@ dependencies = ["libm",]+[[package]]+name = "hybrid-array"+version = "0.4.12"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "9155a582abd142abc056962c29e3ce5ff2ad5469f4246b537ed42c5deba857da"+dependencies = [+ "typenum",+]+[[package]]name = "hyper"version = "1.9.0"@@ -2079,6 +2202,15 @@ dependencies = ["libc",]+[[package]]+name = "inout"+version = "0.2.2"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "4250ce6452e92010fdf7268ccc5d14faa80bb12fc741938534c58f16804e03c7"+dependencies = [+ "hybrid-array",+]+[[package]]name = "ipnet"version = "2.12.0"@@ -2259,6 +2391,12 @@ version = "0.1.0"source = "registry+https://github.com/rust-lang/crates.io-index"checksum = "09edd9e8b54e49e587e4f6295a7d29c3ea94d469cb40ab8ca70b288248a81db2"+[[package]]+name = "libbz2-rs-sys"+version = "0.2.5"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "34b357333733e8260735ba5894eb928c02ecc69c78715f01a8019e7fa7f2db4c"+[[package]]name = "libc"version = "0.2.186"@@ -2354,6 +2492,15 @@ version = "0.1.2"source = "registry+https://github.com/rust-lang/crates.io-index"checksum = "112b39cec0b298b6c1999fee3e31427f74f676e4cb9879ed1a121b43661a4154"+[[package]]+name = "lzma-rust2"+version = "0.16.5"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "ca93e534d1142d1d0dcca6d25fe302508a5dfb40b302802904577725ea0b695b"+dependencies = [+ "sha2 0.11.0",+]+[[package]]name = "macro_rules_attribute"version = "0.2.3"@@ -2663,6 +2810,16 @@ version = "0.2.3"source = "registry+https://github.com/rust-lang/crates.io-index"checksum = "2ee67f1008b1ba2321834326597b8e186293b049a023cdef258527550b9935b4"+[[package]]+name = "pbkdf2"+version = "0.13.0"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "112d82ceb8c5bf524d9af484d4e4970c9fd5a0cc15ba14ad93dccd28873b0629"+dependencies = [+ "digest 0.11.3",+ "hmac",+]+[[package]]name = "pear"version = "0.2.9"@@ -2734,6 +2891,12 @@ version = "0.2.0"source = "registry+https://github.com/rust-lang/crates.io-index"checksum = "439ee305def115ba05938db6eb1644ff94165c5ab5e9420d1c1bcedbba909391"+[[package]]+name = "ppmd-rust"+version = "1.5.0"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "196a7c80b9a7652aba7cc070827516c2abe4ccdf53d128e1944003cf5726cff1"+[[package]]name = "ppv-lite86"version = "0.2.21"@@ -3645,6 +3808,17 @@ dependencies = ["unsafe-libyaml",]+[[package]]+name = "sha1"+version = "0.11.0"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "aacc4cc499359472b4abe1bf11d0b12e688af9a805fa5e3016f9a386dc2d0214"+dependencies = [+ "cfg-if",+ "cpufeatures 0.3.0",+ "digest 0.11.3",+]+[[package]]name = "sha1_smol"version = "1.0.1"@@ -3659,7 +3833,18 @@ checksum = "a7507d819769d01a365ab707794a4084392c824f54a7a6a7862f8c3d0892b283"dependencies = ["cfg-if","cpufeatures 0.2.17",- "digest",+ "digest 0.10.7",+]++[[package]]+name = "sha2"+version = "0.11.0"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "446ba717509524cb3f22f17ecc096f10f4822d76ab5c0b9822c5f9c284e825f4"+dependencies = [+ "cfg-if",+ "cpufeatures 0.3.0",+ "digest 0.11.3",][[package]]@@ -3964,6 +4149,7 @@ checksum = "743bd48c283afc0388f9b8827b976905fb217ad9e647fae3a379a9283c4def2c"dependencies = ["deranged","itoa",+ "js-sys","num-conv","powerfmt","serde_core",@@ -5233,14 +5419,75 @@ version = "8.6.0"source = "registry+https://github.com/rust-lang/crates.io-index"checksum = "2d04a6b5381502aa6087c94c669499eb1602eb9c5e8198e534de571f7154809b"dependencies = [+ "aes",+ "bzip2",+ "constant_time_eq","crc32fast",+ "deflate64",+ "flate2",+ "getrandom 0.4.2",+ "hmac","indexmap",+ "lzma-rust2","memchr",+ "pbkdf2",+ "ppmd-rust",+ "sha1",+ "time","typed-path",+ "zeroize",+ "zopfli",+ "zstd",]+[[package]]+name = "zlib-rs"+version = "0.6.3"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "3be3d40e40a133f9c916ee3f9f4fa2d9d63435b5fbe1bfc6d9dae0aa0ada1513"+[[package]]name = "zmij"version = "1.0.21"source = "registry+https://github.com/rust-lang/crates.io-index"checksum = "b8848ee67ecc8aedbaf3e4122217aff892639231befc6a1b58d29fff4c2cabaa"++[[package]]+name = "zopfli"+version = "0.8.3"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "f05cd8797d63865425ff89b5c4a48804f35ba0ce8d125800027ad6017d2b5249"+dependencies = [+ "bumpalo",+ "crc32fast",+ "log",+ "simd-adler32",+]++[[package]]+name = "zstd"+version = "0.13.3"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "e91ee311a569c327171651566e07972200e76fcfe2242a4fa446149a3881c08a"+dependencies = [+ "zstd-safe",+]++[[package]]+name = "zstd-safe"+version = "7.3.0"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "64d80649ab6db9d9f6f9c80a40becd948eda4714a0a5ac8c4d157a32231c7882"+dependencies = [+ "zstd-sys",+]++[[package]]+name = "zstd-sys"+version = "2.1.0+zstd.1.5.7"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "0ef0a8027ec3ee71300ab3bcbcd0393f434aa72b91ca6d635a39941deae8eea0"+dependencies = [+ "cc",+ "pkg-config",+]diff --git a/Cargo.toml b/Cargo.tomlindex f9844c6f..ec36aa12 100644--- a/Cargo.toml+++ b/Cargo.toml@@ -149,6 +149,11 @@ tower-http = { version = "0.6", features = ["fs", "cors"] }# Backup / restore archive format.tar = "0.4"flate2 = "1"+# Native Windows release zip extract/write for `ai-memory upgrade` (#801).+# Already in the lockfile via candle-core; pin the same major here so the CLI+# can enable default deflate (PowerShell Compress-Archive) without relying on+# candle's feature set.+zip = "8.6"# Text munging / hook payload sanitisation.regex = "1"diff --git a/README.md b/README.mdindex 9a4cf031..7a3dc2e1 100644--- a/README.md+++ b/README.md@@ -331,6 +331,8 @@ Docker — either the [menu bar app](#macos-menu-bar-app) above or apath use `ai-memory upgrade` (checksum-verified GitHub release replace + hookrefresh) — see[`docs/install.md#keeping-ai-memory-up-to-date`](docs/install.md#keeping-ai-memory-up-to-date).+The same native upgrade path covers Windows x86_64 zip installs under a+writable prefix (see [`docs/windows.md`](docs/windows.md) Scenario C).Wiring another agent is the same two commands with a different name —`--client codex`, `--agent codex`, and so on for every row of the supportdiff --git a/crates/ai-memory-cli/Cargo.toml b/crates/ai-memory-cli/Cargo.tomlindex 0bb989a9..b2859925 100644--- a/crates/ai-memory-cli/Cargo.toml+++ b/crates/ai-memory-cli/Cargo.toml@@ -76,6 +76,7 @@ serde_json.workspace = truetoml_edit.workspace = truesysinfo.workspace = truetar.workspace = true+zip.workspace = truejiff.workspace = truejsonc-parser.workspace = truetokio.workspace = truediff --git a/crates/ai-memory-cli/src/commands/upgrade.rs b/crates/ai-memory-cli/src/commands/upgrade.rsindex 5e0fc300..af0f53f0 100644--- a/crates/ai-memory-cli/src/commands/upgrade.rs+++ b/crates/ai-memory-cli/src/commands/upgrade.rs@@ -2,21 +2,23 @@//!//! Docker-wrapper installs never reach this path: [`bin/ai-memory`] intercepts//! `upgrade` and pulls the container image. This command covers the release-//! binary laid down under a writable user prefix (the macOS happy path in-//! `docs/macos.md`): download the matching tarball + `.sha256`, verify,-//! atomically replace the on-disk binary (and sibling `hooks/` when present),-//! then re-run `install-hooks --apply` for every staged agent.+//! binary laid down under a writable user prefix (macOS/Linux tarball in+//! `docs/macos.md`, Windows zip in `docs/windows.md` Scenario C): download the+//! matching archive + `.sha256`, verify, replace the on-disk binary (and sibling+//! `hooks/` when present), then re-run `install-hooks --apply` for every staged+//! agent.//!//! Client-only: never claims to upgrade a remote/homelab server.//!//! Ownership (live CLI command — kept in one module by convention)://! - install classification (container / package-managed / writable)//! - release fetch + checksum-//! - archive extract + path allowlist-//! - atomic binary/dir replace+//! - archive extract + path allowlist (`.tar.gz` or `.zip`)+//! - atomic binary/dir replace (Unix rename-over; Windows rename-aside)//! - staged hook refreshuse std::fs;+use std::io::Cursor;use std::path::{Component, Path, PathBuf};use std::time::Duration;@@ -29,7 +31,7 @@ use tracing::info;use crate::cli::{AgentChoice, InstallHooksArgs, UpgradeArgs};use crate::commands::install_hooks;use crate::config::Config;-use crate::install_layout::{BINARY_NAME, HOOKS_DIR_NAME};+use crate::install_layout::{HOOKS_DIR_NAME, shipped_binary_name};const RELEASE_OWNER_REPO: &str = "akitaonrails/ai-memory";const USER_AGENT: &str = concat!("ai-memory-cli/", env!("CARGO_PKG_VERSION"));@@ -47,25 +49,6 @@ type StagedAgentList = Vec<(String, AgentChoice)>;/// Run the `upgrade` subcommand.pub async fn run(config: &Config, args: UpgradeArgs) -> Result<()> {- #[cfg(windows)]- {- let _ = (config, args);- bail!(- "native `ai-memory upgrade` does not yet support Windows self-replace; \- download the release zip from \- https://github.com/{RELEASE_OWNER_REPO}/releases/latest \- and re-run `install-hooks --apply` for each agent"- );- }-- #[cfg(not(windows))]- {- run_unix(config, args).await- }-}--#[cfg(not(windows))]-async fn run_unix(config: &Config, args: UpgradeArgs) -> Result<()> {let exe = resolve_current_exe()?;ensure_supported_install(&exe)?;@@ -87,13 +70,11 @@ async fn run_unix(config: &Config, args: UpgradeArgs) -> Result<()> {Ok(())}-#[cfg(not(windows))]fn resolve_current_exe() -> Result<PathBuf> {let exe = std::env::current_exe().context("resolving current executable path")?;Ok(fs::canonicalize(&exe).unwrap_or(exe))}-#[cfg(not(windows))]fn ensure_supported_install(exe: &Path) -> Result<()> {match classify_install(exe)? {InstallClass::Supported => Ok(()),@@ -101,7 +82,6 @@ fn ensure_supported_install(exe: &Path) -> Result<()> {}}-#[cfg(not(windows))]fn skip_when_current(tag: &str, force: bool) -> bool {let current = env!("CARGO_PKG_VERSION");if !force && versions_match(tag, current) {@@ -111,7 +91,6 @@ fn skip_when_current(tag: &str, force: bool) -> bool {false}-#[cfg(not(windows))]async fn download_and_extract_release(fetcher: &ReqwestFetcher,base: &str,@@ -120,13 +99,12 @@ async fn download_and_extract_release(let asset = release_asset_name().context("no GitHub release asset for this OS/arch")?;let archive_bytes = fetch_verified_archive(fetcher, base, tag, asset).await?;let extract_root = tempfile::tempdir().context("creating extract temp dir")?;- extract_release_archive(&archive_bytes, extract_root.path())+ extract_release_archive(&archive_bytes, extract_root.path(), asset).context("extracting release archive")?;ensure_extracted_binary(extract_root.path())?;Ok(extract_root)}-#[cfg(not(windows))]async fn fetch_verified_archive(fetcher: &ReqwestFetcher,base: &str,@@ -149,10 +127,11 @@ async fn fetch_verified_archive(}fn ensure_extracted_binary(extract_root: &Path) -> Result<()> {- if extract_root.join(BINARY_NAME).is_file() {+ let name = shipped_binary_name();+ if extract_root.join(name).is_file() {return Ok(());}- bail!("release archive is missing the {BINARY_NAME} binary");+ bail!("release archive is missing the {name} binary");}fn verify_archive_checksum(archive_bytes: &[u8], checksum_text: &str, asset: &str) -> Result<()> {@@ -166,7 +145,6 @@ fn verify_archive_checksum(archive_bytes: &[u8], checksum_text: &str, asset: &stOk(())}-#[cfg(not(windows))]fn apply_extracted_release(extract_root: &Path, exe: &Path) -> Result<()> {let install_dir = exe.parent()@@ -177,13 +155,13 @@ fn apply_extracted_release(extract_root: &Path, exe: &Path) -> Result<()> {Ok(())}-#[cfg(not(windows))]fn replace_binary(extract_root: &Path, exe: &Path) -> Result<()> {- let new_binary = extract_root.join(BINARY_NAME);+ let new_binary = extract_root.join(shipped_binary_name());println!("→ replacing {}", exe.display());replace_file_atomic(&new_binary, exe).with_context(|| {format!(- "replacing {}; if this fails mid-way look for {}.new",+ "replacing {}; if this fails mid-way look for {}.new / {}.old",+ exe.display(),exe.display(),exe.display())@@ -304,17 +282,18 @@ fn release_asset_name() -> Option<&'static str> {release_asset_name_for(std::env::consts::OS, std::env::consts::ARCH)}-/// Map an OS/arch pair to the GitHub release tarball name.+/// Map an OS/arch pair to the GitHub release archive name.///-/// Pure so every CI host can assert the full Unix matrix (and Windows →-/// `None`) without cross-compiling. Callers use [`release_asset_name`] for-/// the running host.+/// Pure so every CI host can assert the full matrix (Unix tarballs + Windows+/// x86_64 zip; Windows aarch64 stays `None` — no release asset) without+/// cross-compiling. Callers use [`release_asset_name`] for the running host.fn release_asset_name_for(os: &str, arch: &str) -> Option<&'static str> {match (os, arch) {("linux", "x86_64") => Some("ai-memory-linux-x86_64.tar.gz"),("linux", "aarch64") => Some("ai-memory-linux-aarch64.tar.gz"),("macos", "aarch64") => Some("ai-memory-macos-aarch64.tar.gz"),("macos", "x86_64") => Some("ai-memory-macos-x86_64.tar.gz"),+ ("windows", "x86_64") => Some("ai-memory-windows-x86_64.zip"),_ => None,}}@@ -405,7 +384,17 @@ fn sha256_hex(bytes: &[u8]) -> String {format!("{:x}", Sha256::digest(bytes))}-fn extract_release_archive(bytes: &[u8], dest: &Path) -> Result<()> {+fn extract_release_archive(bytes: &[u8], dest: &Path, asset: &str) -> Result<()> {+ if asset.ends_with(".zip") {+ extract_release_zip(bytes, dest)+ } else if asset.ends_with(".tar.gz") || asset.ends_with(".tgz") {+ extract_release_tar_gz(bytes, dest)+ } else {+ bail!("unsupported release archive format for asset {asset}");+ }+}++fn extract_release_tar_gz(bytes: &[u8], dest: &Path) -> Result<()> {let decoder = GzDecoder::new(bytes);let mut archive = tar::Archive::new(decoder);archive.set_preserve_permissions(false);@@ -413,7 +402,7 @@ fn extract_release_archive(bytes: &[u8], dest: &Path) -> Result<()> {let mut entry = entry?;let path = entry.path()?.into_owned();let entry_type = entry.header().entry_type();- validate_release_entry(&path, entry_type)?;+ validate_release_tar_entry(&path, entry_type)?;entry.unpack_in(dest).with_context(|| format!("extracting {}", path.display()))?;@@ -421,12 +410,46 @@ fn extract_release_archive(bytes: &[u8], dest: &Path) -> Result<()> {Ok(())}+fn extract_release_zip(bytes: &[u8], dest: &Path) -> Result<()> {+ let cursor = Cursor::new(bytes);+ let mut archive = zip::ZipArchive::new(cursor).context("opening release zip")?;+ for i in 0..archive.len() {+ let mut file = archive+ .by_index(i)+ .with_context(|| format!("reading zip entry {i}"))?;+ let Some(enclosed) = file.enclosed_name() else {+ bail!("release archive contains unsafe path: {}", file.name());+ };+ if file.is_symlink() {+ bail!(+ "release archive contains unsupported link entry: {}",+ enclosed.display()+ );+ }+ validate_release_path(&enclosed, file.is_dir())?;+ let out_path = dest.join(&enclosed);+ if file.is_dir() {+ fs::create_dir_all(&out_path)+ .with_context(|| format!("creating {}", out_path.display()))?;+ continue;+ }+ if let Some(parent) = out_path.parent() {+ fs::create_dir_all(parent)+ .with_context(|| format!("creating {}", parent.display()))?;+ }+ let mut out = fs::File::create(&out_path)+ .with_context(|| format!("creating {}", out_path.display()))?;+ std::io::copy(&mut file, &mut out)+ .with_context(|| format!("extracting {}", enclosed.display()))?;+ }+ Ok(())+}+fn is_regular_file(entry_type: tar::EntryType) -> bool {entry_type.is_file() || entry_type == tar::EntryType::GNUSparse}-fn validate_release_entry(path: &Path, entry_type: tar::EntryType) -> Result<()> {- let normalized = normalize_release_entry_path(path)?;+fn validate_release_tar_entry(path: &Path, entry_type: tar::EntryType) -> Result<()> {if entry_type.is_symlink() || entry_type.is_hard_link() {bail!("release archive contains unsupported link entry: {}",@@ -439,10 +462,16 @@ fn validate_release_entry(path: &Path, entry_type: tar::EntryType) -> Result<()>path.display());}+ validate_release_path(path, entry_type.is_dir())+}++/// Shared path gates for tar and zip entries (allowlist + traversal).+fn validate_release_path(path: &Path, is_dir: bool) -> Result<()> {+ let normalized = normalize_release_entry_path(path)?;// `tar -C dist/$artifact -czf … .` (release.yml) emits `./` as the// archive root — empty after stripping CurDir; allow that directory only.if normalized.as_os_str().is_empty() {- if entry_type.is_dir() {+ if is_dir {return Ok(());}bail!("release archive contains unsafe path: {}", path.display());@@ -470,9 +499,24 @@ fn normalize_release_entry_path(path: &Path) -> Result<PathBuf> {Ok(out)}+/// Portable forward-slash key so Windows `Path` separators do not break+/// the allowlist string checks.+fn release_path_key(path: &Path) -> String {+ path.components()+ .filter_map(|c| match c {+ Component::Normal(part) => Some(part.to_string_lossy()),+ _ => None,+ })+ .collect::<Vec<_>>()+ .join("/")+}+fn is_allowed_release_path(path: &Path) -> bool {- let path_str = path.to_string_lossy();- path_str == BINARY_NAME+ let path_str = release_path_key(path);+ // Accept both release basenames so the zip extractor can be unit-tested+ // on Unix CI (archive root is always `ai-memory.exe` per release.yml).+ path_str == "ai-memory"+ || path_str == "ai-memory.exe"|| path_str == HOOKS_DIR_NAME|| path_str.strip_prefix(HOOKS_DIR_NAME)@@ -495,14 +539,57 @@ fn replace_file_atomic(src: &Path, dest: &Path) -> Result<()> {fs::set_permissions(&tmp, fs::Permissions::from_mode(UNIX_EXECUTABLE_MODE)).with_context(|| format!("chmod +x {}", tmp.display()))?;}- fs::rename(&tmp, dest).with_context(|| {- format!(- "renaming {} -> {} (left {} in place on failure)",- tmp.display(),- dest.display(),- tmp.display()- )- })?;+ #[cfg(windows)]+ {+ replace_file_windows_rename_aside(&tmp, dest)+ }+ #[cfg(not(windows))]+ {+ fs::rename(&tmp, dest).with_context(|| {+ format!(+ "renaming {} -> {} (left {} in place on failure)",+ tmp.display(),+ dest.display(),+ tmp.display()+ )+ })?;+ Ok(())+ }+}++/// Windows allows renaming a running image aside, but not overwriting it.+/// Stage to `.new`, move live `dest` → `.old`, promote `.new` → `dest`, then+/// best-effort delete `.old` (often fails while this process still maps it).+#[cfg(windows)]+fn replace_file_windows_rename_aside(tmp: &Path, dest: &Path) -> Result<()> {+ let old = dest.with_extension("old");+ if old.exists() {+ let _ = fs::remove_file(&old);+ }+ let had_dest = dest.exists();+ if had_dest {+ fs::rename(dest, &old).with_context(|| {+ format!(+ "moving running binary aside {} -> {}",+ dest.display(),+ old.display()+ )+ })?;+ }+ if let Err(err) = fs::rename(tmp, dest) {+ if had_dest {+ let _ = fs::rename(&old, dest);+ }+ return Err(err).with_context(|| {+ format!(+ "renaming {} -> {} (attempted rollback of {})",+ tmp.display(),+ dest.display(),+ old.display()+ )+ });+ }+ let _ = fs::remove_file(&old);Ok(())}@@ -817,17 +904,20 @@ fn content_length_exceeds_limit(content_length: u64, max_bytes: usize) -> bool {#[cfg(test)]mod tests {use super::*;+ use std::io::Write as _;use tar::Header;+ use zip::ZipWriter;+ use zip::write::SimpleFileOptions;#[test]- fn release_asset_name_for_covers_unix_matrix_and_refusals() {- // Table-driven so Linux CI still guards macos-* and windows → None.+ fn release_asset_name_for_covers_unix_and_windows_matrix() {+ // Table-driven so Linux CI still guards macos-* and windows mapping.let cases: &[(&str, &str, Option<&str>)] = &[("linux", "x86_64", Some("ai-memory-linux-x86_64.tar.gz")),("linux", "aarch64", Some("ai-memory-linux-aarch64.tar.gz")),("macos", "aarch64", Some("ai-memory-macos-aarch64.tar.gz")),("macos", "x86_64", Some("ai-memory-macos-x86_64.tar.gz")),- ("windows", "x86_64", None),+ ("windows", "x86_64", Some("ai-memory-windows-x86_64.zip")),("windows", "aarch64", None),("linux", "arm", None),("freebsd", "x86_64", None),@@ -847,6 +937,20 @@ mod tests {);}+ #[test]+ fn shipped_binary_name_matches_host() {+ #[cfg(windows)]+ assert_eq!(shipped_binary_name(), "ai-memory.exe");+ #[cfg(not(windows))]+ assert_eq!(shipped_binary_name(), "ai-memory");+ }++ #[test]+ fn allowlist_accepts_shipped_binary_basename() {+ assert!(is_allowed_release_path(Path::new(shipped_binary_name())));+ assert!(is_allowed_release_path(Path::new("hooks/claude-code/x.sh")));+ }+#[test]fn parse_sha256_sidecar_accepts_sha256sum_format() -> Result<()> {let text = "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef ai-memory-macos-aarch64.tar.gz\n";@@ -914,7 +1018,7 @@ mod tests {#[test]fn classify_accepts_writable_user_prefix() -> Result<()> {let dir = tempfile::tempdir()?;- let exe = dir.path().join("ai-memory");+ let exe = dir.path().join(shipped_binary_name());fs::write(&exe, b"fake")?;#[cfg(unix)]{@@ -934,7 +1038,7 @@ mod tests {#[test]fn validate_rejects_path_traversal() -> Result<()> {- match validate_release_entry(Path::new("../evil"), tar::EntryType::Regular) {+ match validate_release_tar_entry(Path::new("../evil"), tar::EntryType::Regular) {Ok(()) => bail!("path traversal must fail"),Err(err) => assert!(err.to_string().contains("unsafe"), "{err}"),}@@ -943,7 +1047,7 @@ mod tests {#[test]fn validate_rejects_unexpected_paths() -> Result<()> {- match validate_release_entry(Path::new("etc/passwd"), tar::EntryType::Regular) {+ match validate_release_tar_entry(Path::new("etc/passwd"), tar::EntryType::Regular) {Ok(()) => bail!("unexpected path must fail"),Err(err) => assert!(err.to_string().contains("unexpected"), "{err}"),}@@ -952,15 +1056,15 @@ mod tests {#[test]fn validate_accepts_dot_slash_prefixed_binary() -> Result<()> {- validate_release_entry(Path::new("./ai-memory"), tar::EntryType::Regular)?;- validate_release_entry(Path::new("./"), tar::EntryType::Directory)?;+ validate_release_tar_entry(Path::new("./ai-memory"), tar::EntryType::Regular)?;+ validate_release_tar_entry(Path::new("./"), tar::EntryType::Directory)?;Ok(())}#[test]fn extracts_archive_built_like_release_yml() -> Result<()> {let src = tempfile::tempdir()?;- fs::write(src.path().join(BINARY_NAME), b"bin")?;+ fs::write(src.path().join(shipped_binary_name()), b"bin")?;fs::create_dir_all(src.path().join("hooks/claude-code"))?;fs::write(src.path().join("hooks/claude-code/x.sh"), b"#!/bin/sh")?;let out = tempfile::tempdir()?;@@ -978,8 +1082,12 @@ mod tests {.status()?;assert!(status.success());let dest = tempfile::tempdir()?;- extract_release_archive(&fs::read(&archive)?, dest.path())?;- assert!(dest.path().join(BINARY_NAME).is_file());+ extract_release_archive(+ &fs::read(&archive)?,+ dest.path(),+ "ai-memory-macos-aarch64.tar.gz",+ )?;+ assert!(dest.path().join(shipped_binary_name()).is_file());Ok(())}@@ -1012,21 +1120,102 @@ mod tests {hash);let dest = tempfile::tempdir()?;- extract_release_archive(&gz_bytes, dest.path())?;+ extract_release_archive(&gz_bytes, dest.path(), "ai-memory-macos-aarch64.tar.gz")?;assert_eq!(fs::read(dest.path().join("ai-memory"))?, b"hello-world");Ok(())}+ fn build_test_zip(entries: &[(&str, &[u8])]) -> Result<Vec<u8>> {+ let mut cursor = Cursor::new(Vec::new());+ {+ let mut zip = ZipWriter::new(&mut cursor);+ let options =+ SimpleFileOptions::default().compression_method(zip::CompressionMethod::Stored);+ for &(path, body) in entries {+ if path.ends_with('/') {+ zip.add_directory(path, options)?;+ } else {+ zip.start_file(path, options)?;+ zip.write_all(body)?;+ }+ }+ zip.finish()?;+ }+ Ok(cursor.into_inner())+ }++ #[test]+ fn extracts_zip_happy_path_with_hooks() -> Result<()> {+ let bytes = build_test_zip(&[+ ("ai-memory.exe", b"win-bin"),+ ("hooks/", b""),+ ("hooks/claude-code/x.ps1", b"hook"),+ ])?;+ let dest = tempfile::tempdir()?;+ extract_release_archive(&bytes, dest.path(), "ai-memory-windows-x86_64.zip")?;+ assert_eq!(fs::read(dest.path().join("ai-memory.exe"))?, b"win-bin");+ assert_eq!(+ fs::read(dest.path().join("hooks/claude-code/x.ps1"))?,+ b"hook"+ );+ Ok(())+ }++ #[test]+ fn zip_extract_rejects_path_traversal() -> Result<()> {+ let bytes = build_test_zip(&[("../evil.exe", b"nope")])?;+ let dest = tempfile::tempdir()?;+ match extract_release_archive(&bytes, dest.path(), "ai-memory-windows-x86_64.zip") {+ Ok(()) => bail!("path traversal must fail"),+ Err(err) => assert!(+ err.to_string().contains("unsafe") || err.to_string().contains("unexpected"),+ "{err}"+ ),+ }+ Ok(())+ }++ #[test]+ fn zip_extract_rejects_unexpected_paths() -> Result<()> {+ let bytes = build_test_zip(&[("etc/passwd", b"nope")])?;+ let dest = tempfile::tempdir()?;+ match extract_release_archive(&bytes, dest.path(), "ai-memory-windows-x86_64.zip") {+ Ok(()) => bail!("unexpected path must fail"),+ Err(err) => assert!(err.to_string().contains("unexpected"), "{err}"),+ }+ Ok(())+ }+#[test]fn replace_file_atomic_swaps_contents() -> Result<()> {let dir = tempfile::tempdir()?;- let dest = dir.path().join("ai-memory");+ let dest = dir.path().join(shipped_binary_name());let src = dir.path().join("fresh");fs::write(&dest, b"old")?;fs::write(&src, b"new")?;replace_file_atomic(&src, &dest)?;assert_eq!(fs::read(&dest)?, b"new");assert!(!dest.with_extension("new").exists());+ // Windows may leave `.old` while a process still maps it; unit test+ // has no live mapping so it should be gone, but tolerate leftovers.+ let old = dest.with_extension("old");+ if old.exists() {+ assert_eq!(fs::read(&old)?, b"old");+ }+ Ok(())+ }++ #[test]+ fn replace_file_atomic_cleans_stale_old_before_swap() -> Result<()> {+ let dir = tempfile::tempdir()?;+ let dest = dir.path().join(shipped_binary_name());+ let src = dir.path().join("fresh");+ let old = dest.with_extension("old");+ fs::write(&dest, b"current")?;+ fs::write(&old, b"stale-old")?;+ fs::write(&src, b"new")?;+ replace_file_atomic(&src, &dest)?;+ assert_eq!(fs::read(&dest)?, b"new");Ok(())}diff --git a/crates/ai-memory-cli/src/install_layout.rs b/crates/ai-memory-cli/src/install_layout.rsindex ec3fffba..bb91cd05 100644--- a/crates/ai-memory-cli/src/install_layout.rs+++ b/crates/ai-memory-cli/src/install_layout.rs@@ -1,11 +1,29 @@//! Release and install path basenames shared by packaging-aware CLI commands.//!-//! These names match the shipped binary (`[[bin]] name`), release tarball+//! These names match the shipped binary (`[[bin]] name`), release archive//! entries, and the binary-sibling hooks bundle. They are not domain//! constants — keep them in the CLI crate, not `ai-memory-core`.-/// Shipped binary basename (`[[bin]] name`, `/proc/*/comm`, release tarball entry).+/// Shipped binary basename (`[[bin]] name`, `/proc/*/comm`).+///+/// Release archives use [`shipped_binary_name`] instead — Windows zips ship+/// `ai-memory.exe`.pub const BINARY_NAME: &str = "ai-memory";/// Sibling hooks bundle dir in release archives and install prefixes.pub const HOOKS_DIR_NAME: &str = "hooks";++/// On-disk / archive basename for the release binary on this host.+///+/// Matches `release.yml`: Unix tarballs ship `ai-memory`; the Windows zip+/// ships `ai-memory.exe`.+pub fn shipped_binary_name() -> &'static str {+ #[cfg(windows)]+ {+ "ai-memory.exe"+ }+ #[cfg(not(windows))]+ {+ BINARY_NAME+ }+}diff --git a/crates/ai-memory-cli/tests/suite/upgrade_e2e.rs b/crates/ai-memory-cli/tests/suite/upgrade_e2e.rsindex ca5e6059..e26a8d73 100644--- a/crates/ai-memory-cli/tests/suite/upgrade_e2e.rs+++ b/crates/ai-memory-cli/tests/suite/upgrade_e2e.rs@@ -6,16 +6,13 @@//! replace the on-disk exe → refresh a sibling `hooks/` tree. No real//! GitHub, no Docker.//!-//! Unix-only: Windows self-replace is refused by design.--#![cfg(unix)]+//! Covers Unix `.tar.gz` and Windows `.zip` release layouts./// Spawns a loopback release fixture and a real CLI subprocess: seconds,/// not milliseconds — slow tier (`cargo tf` / CI), not the everyday loop.mod slow {use std::fs;- use std::io::Write as _;- use std::os::unix::fs::PermissionsExt as _;+ use std::io::{Cursor, Write as _};use std::path::{Path, PathBuf};use std::sync::Arc;@@ -29,6 +26,8 @@ mod slow {use flate2::write::GzEncoder;use sha2::{Digest as _, Sha256};use tar::Header;+ use zip::ZipWriter;+ use zip::write::SimpleFileOptions;use crate::e2e_support::hermetic;@@ -52,10 +51,27 @@ mod slow {("linux", "aarch64") => "ai-memory-linux-aarch64.tar.gz",("macos", "aarch64") => "ai-memory-macos-aarch64.tar.gz",("macos", "x86_64") => "ai-memory-macos-x86_64.tar.gz",+ ("windows", "x86_64") => "ai-memory-windows-x86_64.zip",other => panic!("native upgrade e2e unsupported on {other:?}"),}}+ fn shipped_binary_name() -> &'static str {+ if cfg!(windows) {+ "ai-memory.exe"+ } else {+ "ai-memory"+ }+ }++ fn build_release_archive() -> Vec<u8> {+ if cfg!(windows) {+ build_release_zip()+ } else {+ build_release_tarball()+ }+ }+fn build_release_tarball() -> Vec<u8> {let mut tar_bytes = Vec::new();{@@ -73,6 +89,24 @@ mod slow {gz_bytes}+ fn build_release_zip() -> Vec<u8> {+ let mut cursor = Cursor::new(Vec::new());+ {+ let mut zip = ZipWriter::new(&mut cursor);+ let options =+ SimpleFileOptions::default().compression_method(zip::CompressionMethod::Stored);+ zip.start_file("ai-memory.exe", options)+ .expect("start exe");+ zip.write_all(NEW_BINARY).expect("write exe");+ zip.add_directory("hooks/", options).expect("hooks dir");+ zip.start_file("hooks/claude-code/new.sh", options)+ .expect("start hook");+ zip.write_all(NEW_HOOK).expect("write hook");+ zip.finish().expect("finish zip");+ }+ cursor.into_inner()+ }+fn append_regular(builder: &mut tar::Builder<&mut Vec<u8>>,path: &str,@@ -109,9 +143,14 @@ mod slow {.into_response();}if name == fx.asset {+ let content_type = if fx.asset.ends_with(".zip") {+ "application/zip"+ } else {+ "application/gzip"+ };return Response::builder().status(StatusCode::OK)- .header(header::CONTENT_TYPE, "application/gzip")+ .header(header::CONTENT_TYPE, content_type).body(Body::from(fx.archive.as_ref().clone())).expect("build archive response");}@@ -121,9 +160,13 @@ mod slow {fn install_writable_prefix(prefix: &Path) -> PathBuf {let bin_dir = prefix.join("bin");fs::create_dir_all(&bin_dir).expect("bin dir");- let exe = bin_dir.join("ai-memory");+ let exe = bin_dir.join(shipped_binary_name());fs::copy(BIN, &exe).expect("copy built binary into writable prefix");- fs::set_permissions(&exe, fs::Permissions::from_mode(0o755)).expect("chmod +x");+ #[cfg(unix)]+ {+ use std::os::unix::fs::PermissionsExt as _;+ fs::set_permissions(&exe, fs::Permissions::from_mode(0o755)).expect("chmod +x");+ }// Sibling hooks tree: upgrade refreshes it when the archive ships hooks/.let hooks = bin_dir.join("hooks/claude-code");@@ -135,7 +178,7 @@ mod slow {#[tokio::test]async fn native_upgrade_replaces_binary_and_sibling_hooks_from_fixture() {let asset = host_asset_name().to_string();- let archive = Arc::new(build_release_tarball());+ let archive = Arc::new(build_release_archive());let hash = format!("{:x}", Sha256::digest(archive.as_ref()));let checksum_body = format!("{hash} {asset}\n");let fixture = ReleaseFixture {diff --git a/docs/install.md b/docs/install.mdindex 19458a50..b449fa4b 100644--- a/docs/install.md+++ b/docs/install.md@@ -2441,11 +2441,11 @@ self-upgrades to a fork or tagged release, set `AI_MEMORY_WRAPPER_URL=<url>`;the wrapper requires `<url>.sha256` unless`AI_MEMORY_WRAPPER_SHA256_URL=<checksum-url>` is also set.-### Native release binary (Linux / macOS)+### Native release binary (Linux / macOS / Windows x86_64)When `PATH` points at a GitHub-release `ai-memory` binary under a writable-user prefix (for example `~/.local/bin`), the same command upgrades the-binary itself:+user prefix (for example `~/.local/bin`, or `%LOCALAPPDATA%\ai-memory` on+Windows), the same command upgrades the binary itself:```bashai-memory upgrade@@ -2454,18 +2454,22 @@ ai-memory upgrade --version v2.3.2ai-memory upgrade --force```-The native path downloads the matching `ai-memory-<os>-<arch>.tar.gz` and-its `.sha256` sidecar from GitHub Releases, verifies the checksum, replaces-the on-disk binary (and a sibling `hooks/` directory when present), then-re-stages hooks for agents already under the data-dir hooks tree. It refuses-Homebrew/AUR/`/usr` installs (use the package manager), Windows self-replace-(download the zip manually), and in-container binaries (upgrade the host-wrapper/image instead). For mirrors or hermetic tests, set-`AI_MEMORY_RELEASE_BASE_URL` (or `release_base_url` in config.toml) to a-Releases-compatible base that serves `{base}/latest/tag` and-`{base}/download/<tag>/<asset>` (+ `.sha256`). That override is a trust-boundary: archive and checksum are fetched from the same base, so point it-only at origins you control. Each response body is capped at 128 MiB.+The native path downloads the matching release archive+(`ai-memory-<os>-<arch>.tar.gz` on Unix, `ai-memory-windows-x86_64.zip` on+Windows) and its `.sha256` sidecar from GitHub Releases, verifies the+checksum, replaces the on-disk binary (and a sibling `hooks/` directory when+present), then re-stages hooks for agents already under the data-dir hooks+tree. Windows uses rename-aside (`.exe` → `.old`, then promote `.new`) because+a running image cannot be overwritten in place. It refuses Homebrew/AUR/`/usr`+installs (use the package manager), unwritable prefixes (for example Program+Files — download the zip manually), and in-container binaries (upgrade the+host wrapper/image instead). Windows aarch64 has no release asset yet. For+mirrors or hermetic tests, set `AI_MEMORY_RELEASE_BASE_URL` (or+`release_base_url` in config.toml) to a Releases-compatible base that serves+`{base}/latest/tag` and `{base}/download/<tag>/<asset>` (+ `.sha256`). That+override is a trust boundary: archive and checksum are fetched from the same+base, so point it only at origins you control. Each response body is capped+at 128 MiB.### Shared notesdiff --git a/docs/support-matrix.md b/docs/support-matrix.mdindex 62e23acd..720fb4de 100644--- a/docs/support-matrix.md+++ b/docs/support-matrix.md@@ -9,7 +9,7 @@| Linux | Supported | Primary Docker/server target and CI platform. Published Docker images support `linux/amd64` and `linux/arm64`. Native Arch/AUR packages include system and user systemd units. || macOS | Supported | Workspace tests run in CI; tagged releases publish native `ai-memory-macos-aarch64.tar.gz` and `ai-memory-macos-x86_64.tar.gz` binaries, which include a per-user launchd agent. The native binary is the recommended path on Apple Silicon. A source-built menu bar app (`companions/ai-memory-macos`) bundles that binary, starts the LaunchAgent, and opens `/web` and `ai-memory status` — README quick-start and [`docs/macos.md`](macos.md) Scenario D. || Windows via WSL2 | Supported | Use the Linux install path inside WSL2 when the agent runs there. |-| Native Windows | Experimental | Tagged releases publish `ai-memory-windows-x86_64.zip` with `ai-memory.exe`; Docker Desktop wrapper and source builds are also available. Local supported profiles default to host-native hook commands; Claude Code may use its Windows exec form, while other agents use native single command strings matching their hook schema. PowerShell/Git Bash scripts are compatibility fallbacks. See [`docs/windows.md`](windows.md). |+| Native Windows | Experimental | Tagged releases publish `ai-memory-windows-x86_64.zip` with `ai-memory.exe`; Docker Desktop wrapper and source builds are also available. Native `ai-memory upgrade` is supported for writable x86_64 zip installs (checksum-verified zip + rename-aside self-replace + sibling `hooks/` refresh). Local supported profiles default to host-native hook commands; Claude Code may use its Windows exec form, while other agents use native single command strings matching their hook schema. PowerShell/Git Bash scripts are compatibility fallbacks. See [`docs/windows.md`](windows.md). || Claude Code | Supported | MCP config + lifecycle hooks; native commands enforce capture exclusions. `install-mcp --session-aware` optionally enables per-session auto-scope isolation through a local stdio bridge. Optionally captures the assistant's final turn on `Stop` when installed with `--capture-assistant` and the server enables `capture_assistant` (double opt-in, off by default). || Codex | Supported | MCP config + lifecycle hooks; native commands enforce capture exclusions. `SessionEnd` is wired since Codex CLI 0.145.0 (openai/codex#33895), so finished sessions get an automatic end-of-session summary/handoff; on older Codex the event is inert and `ai-memory finalize-session --agent codex` is the fallback. Optionally captures the assistant's final turn on `Stop` when installed with `--capture-assistant` and the server enables `capture_assistant` (double opt-in, off by default) — Codex's `Stop` payload carries `last_assistant_message`, same as Claude Code. || Command Code | Supported | MCP config (`~/.commandcode/mcp.json`) + its four stable lifecycle-hook events (`~/.commandcode/settings.json`); native commands enforce capture exclusions and `SessionStart` injects handoffs. `Stop` is only a turn boundary, so use `ai-memory finalize-session --agent command-code` after the final turn. `ai-memory run command-code` adds exact v3 native-session resume and visible-event import; experimental unsandboxed Mods remain excluded. |diff --git a/docs/windows.md b/docs/windows.mdindex 8f2e144c..5f3f689d 100644--- a/docs/windows.md+++ b/docs/windows.md@@ -181,8 +181,9 @@ Docker. Each tagged release publishes`ai-memory-windows-x86_64.zip` (see the repo's Releases page).```powershell-# Download + extract into your user data dir (any stable path works; the-# native hook exec-form command is rendered from wherever ai-memory.exe lives).+# First-time install: download + extract into your user data dir (any stable+# path works; the native hook exec-form command is rendered from wherever+# ai-memory.exe lives).$Dest = "$env:LOCALAPPDATA\ai-memory"New-Item -ItemType Directory -Force $Dest | Out-NullInvoke-WebRequest `@@ -204,6 +205,24 @@ if (($UserPath -split ';') -notcontains $Dest) {--server-url "https://memory.example.com" --auth-token "<token>"```+Later updates for this install use the same command as Linux/macOS release+binaries. From a writable prefix (for example `%LOCALAPPDATA%\ai-memory`),+run:++```powershell+ai-memory upgrade+# optional: pin a tag, or force a re-download of the current tag+ai-memory upgrade --version v2.3.2+ai-memory upgrade --force+```++That downloads `ai-memory-windows-x86_64.zip` + `.sha256`, verifies the+checksum, replaces `ai-memory.exe` via rename-aside (Windows cannot overwrite+a running image), refreshes a sibling `hooks/` tree when present, then+re-stages hooks for agents already under the data-dir hooks tree. Keep the+manual zip download above as a fallback if the install directory is not+writable (for example under Program Files).+The zip mirrors the Linux release tarball, minus the Linux-only serviceassets: it contains `ai-memory.exe`, the full `hooks/` bundle (`.ps1` +`.sh`), `crates/ai-memory-cli/templates/config.default.toml`, `README.md`,