Skip to content

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.md
index 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 Releases
base 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 environment
into the spawned harness — e.g. a per-account `CLAUDE_CONFIG_DIR` for
diff --git a/Cargo.lock b/Cargo.lock
index 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.toml
index 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.md
index 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 a
path use `ai-memory upgrade` (checksum-verified GitHub release replace + hook
refresh) — 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 support
diff --git a/crates/ai-memory-cli/Cargo.toml b/crates/ai-memory-cli/Cargo.toml
index 0bb989a9..b2859925 100644
--- a/crates/ai-memory-cli/Cargo.toml
+++ b/crates/ai-memory-cli/Cargo.toml
@@ -76,6 +76,7 @@ serde_json.workspace = true
toml_edit.workspace = true
sysinfo.workspace = true
tar.workspace = true
+zip.workspace = true
jiff.workspace = true
jsonc-parser.workspace = true
tokio.workspace = true
diff --git a/crates/ai-memory-cli/src/commands/upgrade.rs b/crates/ai-memory-cli/src/commands/upgrade.rs
index 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 refresh
use 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: &st
Ok(())
}
-#[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.rs
index 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.rs
index 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.md
index 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:
```bash
ai-memory upgrade
@@ -2454,18 +2454,22 @@ ai-memory upgrade --version v2.3.2
ai-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 notes
diff --git a/docs/support-matrix.md b/docs/support-matrix.md
index 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.md
index 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-Null
Invoke-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 service
assets: it contains `ai-memory.exe`, the full `hooks/` bundle (`.ps1` +
`.sh`), `crates/ai-memory-cli/templates/config.default.toml`, `README.md`,