# Windows Support Windows support has two modes. Pick the mode that matches where your agent CLI actually runs. ## Rule Of Thumb Run `install-mcp` and `install-hooks` from the same environment that launches Claude Code, Codex, Command Code, Devin CLI, Cursor, Gemini CLI, Kimi Code, Kiro CLI, Antigravity CLI, or another agent. - If the agent runs inside WSL2, install ai-memory inside WSL2. - If the agent runs as a native Windows process, install ai-memory from PowerShell on Windows. - Do not mix the Windows wrapper with WSL2-launched agents unless you deliberately override every config and hook path. - To keep the server running across logoff and reboot on native Windows, use a service wrapper (see [Scenario E](#scenario-e-keep-the-server-running-native-windows-service)). Do not launch it from a Scheduled Task via `Start-Process`: the server appears to start and is silently killed at the next reboot. The difference matters because hook configs contain executable paths. WSL2 agents need Linux paths and POSIX `.sh` hooks. Native Windows agents need Windows paths, but the hook runner is agent-specific: local supported profiles default to host-native commands. Claude Code may use its supported direct exec form (`command: "…ai-memory.exe"`, `args: ["hook", "--event", …]`) with no shell; see [Native Hook Command](#native-hook-command-claude-code-on-windows). Other agents use native single command strings matching their hook schema. PowerShell/Git Bash script bundles are compatibility fallbacks and do not enforce capture-policy v1. ## Scenario A: Everything Inside WSL2 This is the most Linux-like Windows setup. Use it when your agent CLI is installed and launched inside a WSL2 distro. ```bash # Inside WSL2. mkdir -p ~/.local/bin wrapper_base=https://github.com/akitaonrails/ai-memory/releases/latest/download/ai-memory-wrapper wrapper_tmp="$(mktemp -d)" trap 'rm -rf "$wrapper_tmp"' EXIT curl -fsSL "$wrapper_base" -o "$wrapper_tmp/ai-memory-wrapper" curl -fsSL "$wrapper_base.sha256" -o "$wrapper_tmp/ai-memory-wrapper.sha256" (cd "$wrapper_tmp" && sha256sum -c ai-memory-wrapper.sha256) install -m 0755 "$wrapper_tmp/ai-memory-wrapper" ~/.local/bin/ai-memory rm -rf "$wrapper_tmp" trap - EXIT export PATH="$HOME/.local/bin:$PATH" docker run -d --name ai-memory \ --restart unless-stopped \ -p 127.0.0.1:49374:49374 \ -v ai-memory-data:/data \ akitaonrails/ai-memory:latest ai-memory install-mcp --client claude-code --apply ai-memory install-hooks --agent claude-code --apply ``` In this mode, ai-memory behaves like Linux: - Config files are written under your WSL2 home directory. - Hook scripts are staged under `~/.local/share/ai-memory/hooks/`. - Hook commands point at `.sh` scripts. - The agent should also be launched from WSL2 so it can execute those WSL paths. If Docker Desktop provides the Docker engine to WSL2, enable WSL integration for the distro first. If you run a native Docker engine inside WSL2, no Windows wrapper is involved. ## Scenario B: Native Windows With Docker Desktop Use this when the agent CLI runs as a native Windows process and you want the ai-memory server to run from the Docker image. The wrapper renders host-side agent config with `http://127.0.0.1:49374`, but its own thin-client commands reach the server from inside a helper container via Docker Desktop's `host.docker.internal` alias, because Docker Desktop gives Linux containers no host networking on Windows. Set `AI_MEMORY_SERVER_URL` only when the server lives somewhere else (a homelab or remote host); the wrapper honours it and skips the alias. ```powershell # Install the Windows Docker wrapper. $UserBin = "$HOME\bin" New-Item -ItemType Directory -Force $UserBin | Out-Null $ReleaseBase = "https://github.com/akitaonrails/ai-memory/releases/latest/download" $WrapperAssets = @{ "ai-memory.ps1" = "ai-memory-wrapper.ps1" "ai-memory.cmd" = "ai-memory-wrapper.cmd" } foreach ($Entry in $WrapperAssets.GetEnumerator()) { $File = $Entry.Key $Asset = $Entry.Value Invoke-WebRequest ` -Uri "$ReleaseBase/$Asset" ` -OutFile "$UserBin\$File" Invoke-WebRequest ` -Uri "$ReleaseBase/$Asset.sha256" ` -OutFile "$UserBin\$File.sha256" $Expected = ((Get-Content "$UserBin\$File.sha256" -Raw) -split '\s+')[0] $Actual = (Get-FileHash "$UserBin\$File" -Algorithm SHA256).Hash.ToLower() if ($Actual -ne $Expected.ToLower()) { throw "Checksum mismatch for $Asset" } Remove-Item "$UserBin\$File.sha256" } Get-ChildItem "$UserBin\ai-memory.*" | Unblock-File # Put the wrapper directory on your user PATH for future terminals. Read and # write the registry value as is: [Environment]::GetEnvironmentVariable expands # its %VAR% entries, and SetEnvironmentVariable would save them expanded, as # REG_SZ. $EnvKey = [Microsoft.Win32.Registry]::CurrentUser.CreateSubKey("Environment") $UserPath = $EnvKey.GetValue("Path", "", "DoNotExpandEnvironmentNames") if (($UserPath -split ';' | ForEach-Object { [Environment]::ExpandEnvironmentVariables($_) }) -notcontains $UserBin) { $NewUserPath = (($UserPath, $UserBin) | Where-Object { $_ }) -join ";" $EnvKey.SetValue("Path", $NewUserPath, "ExpandString") # Removing a variable that does not exist broadcasts the change to Explorer. [Environment]::SetEnvironmentVariable("ai-memory-path-notify", [NullString]::Value, "User") $env:Path = "$env:Path;$UserBin" } $EnvKey.Dispose() # Start the server with Docker Desktop. The image default allowlist includes # host.docker.internal so wrapper thin-client commands (status, search, …) are # not rejected with 403. docker run -d --name ai-memory ` --restart unless-stopped ` -p 127.0.0.1:49374:49374 ` -v ai-memory-data:/data ` akitaonrails/ai-memory:latest # Do not also run `ai-memory serve`; the long-lived container above is the server. # Verify the wrapper can reach the server. ai-memory status # Wire MCP and lifecycle hooks for a native Windows agent. ai-memory install-mcp --client claude-code --apply ai-memory install-hooks --agent claude-code --apply ``` In this mode, the PowerShell wrapper runs the Linux container but tells the CLI to render hook commands for the native Windows agent: - Config files are written through the mounted Windows home directory. - Hook scripts are staged under `$HOME\.local\share\ai-memory\hooks\`. - Local supported profiles default to host-native commands. Claude Code may use its exec form (`command` executable + `args` argv array), while other agents use native single command strings matching their hook schema. The wrapper renders those `.ps1` fallback commands with PowerShell `-EncodedCommand` so a hook runner cannot expand their `$env:` setup before the inner PowerShell process receives it. Those commands force text output and suppress progress records so nested PowerShell runners do not emit `CLIXML` hook stderr. PowerShell/Git Bash script bundles are compatibility fallbacks and do not enforce capture-policy v1. After upgrading the wrapper/image, rerun `install-hooks --agent --apply` for each native Windows agent so existing hook entries receive the current command form. ### Managed launches (`run`, `continue`, `show`, …) use the native client `ai-memory run `, `continue`, `resume`, `show`, `workstreams` and `rename-workstream` execute on the host: the helper container cannot see your checkouts, your `claude` or `codex` CLIs, or their native session stores. The wrapper intercepts those subcommands and runs the native Windows client instead of the container (the same interception the Linux/macOS wrapper performs), so managed launches work while the server stays in Docker. The Docker image and the wrapper do not install that client. Install it once from the release zip ([Scenario C](#scenario-c-prebuilt-release-binary-no-toolchain)): ```powershell irm https://github.com/akitaonrails/ai-memory/releases/latest/download/install.ps1 | iex ``` `install.ps1` unpacks `ai-memory.exe` to `%LOCALAPPDATA%\Programs\ai-memory` and puts that directory on your `PATH`; the wrapper finds it there, or wherever `AI_MEMORY_NATIVE_BIN` points. Without it the intercepted commands stop with a message naming that installer. They never fall back into the container, which has no host CLIs. - The native client inherits `AI_MEMORY_SERVER_URL`. Leave it unset and it talks to `http://127.0.0.1:49374`, the port the container publishes on the host; a remote-server URL wins, as with every other wrapper command. - When the container server has auth enabled (a fresh install mints a root bearer into the volume), run `install-hooks --agent --apply` once. The wrapper refreshes a host copy at `%LOCALAPPDATA%\ai-memory\server-token`; later managed launches reuse it without starting a helper container. An explicit `AI_MEMORY_AUTH_TOKEN`, `AI_MEMORY_AUTH__BEARER_TOKEN_FILE`, or bind-mounted `AI_MEMORY_DATA_DIR` still wins. Rerun `install-hooks` after rotating the volume token. - A managed launch does not rewire hooks or MCP: what `install-hooks` and `install-mcp` rendered through the container stays in place (the wrapper sets `AI_MEMORY_RUN_AUTOWIRE=false` for the intercepted commands unless you set the variable yourself). Export `AI_MEMORY_RUN_AUTOWIRE=true` to let `run` rewire a harness around the native client instead. - Upgrading in this scenario: `ai-memory upgrade` pulls the image only, including when `--config` or `--data-dir` precedes `upgrade`. It does not refresh the wrapper or install a native client. Refresh the wrapper scripts by re-running the install block at the top of this scenario, and the native client with its own `ai-memory.exe upgrade` ([Scenario C](#scenario-c-prebuilt-release-binary-no-toolchain)). Then rerun `install-hooks --agent --apply` as noted above. Use the matching `--client` / `--agent` values for other clients, for example `codex`, `command-code`, `devin`, `kimi-code`, `kiro-cli`, `cursor`, or `gemini-cli`. For Devin, `install-mcp --client devin --apply` writes MCP config to `%USERPROFILE%\.devin\config.json`. `install-hooks --agent devin --apply` writes lifecycle hooks to `%USERPROFILE%\.devin\hooks.v1.json` by default; pass `--config-file "%USERPROFILE%\.devin\config.json"` if you want hooks under the `hooks` key in Devin's main config file. For Kiro CLI, `install-mcp --client kiro-cli --apply` writes `%USERPROFILE%\.kiro\settings\mcp.json` unless `$env:KIRO_HOME` overrides the root. `install-hooks --agent kiro-cli --apply` updates existing v2 agent files under `.kiro\agents`; use `--config-file` for a project-local agent. Kiro v3 hook capture remains unsupported pending sanitized live lifecycle and built-in tool payload fixtures for its documented standalone schema. Run these commands from the same native Windows environment that launches Kiro so generated executable paths remain valid. ## Scenario C: Prebuilt Release Binary (No Toolchain) Use this when the agent CLI runs as a native Windows process and you want the fast native hook path **without** installing a Rust toolchain or Docker. Each tagged release publishes `ai-memory-windows-x86_64.zip` (see the repo's Releases page). The quickest path is two commands in PowerShell, neither needing administrator rights: ```powershell irm https://github.com/akitaonrails/ai-memory/releases/latest/download/install.ps1 | iex ai-memory setup ``` `install.ps1` downloads the zip and its `.sha256` from the release, refuses a missing or mismatched checksum and any archive entry that is absolute or holds `..`, unpacks the release to `%LOCALAPPDATA%\Programs\ai-memory` and adds that directory to your user `PATH` (set `AI_MEMORY_NO_MODIFY_PATH=1` to skip that). The destination must not exist, even as an empty directory or a link. Remove it if it is empty or left over from a failed install, or use `ai-memory upgrade` for an existing installation. Failed copy/publication attempts leave the destination alone and report their staging directory for inspection; see the [native installer details](install.md#one-step-native-install-installsh--ai-memory-setup). `ai-memory setup` then initialises the data dir (`%LOCALAPPDATA%\ai-memory`), registers the server to start at logon (see [Scenario E](#scenario-e-keep-the-server-running-native-windows-service)), wires the agents it finds, and checks the result. Inside WSL2 the Linux `install.sh` and `setup` path works unchanged. ### With Scoop Releases from 3.4.0 on are also published to the maintainer's [Scoop](https://scoop.sh) bucket: ```powershell scoop bucket add akitaonrails https://github.com/akitaonrails/scoop-bucket scoop install ai-memory ai-memory setup ``` Scoop checks the zip against the release's published SHA-256, unpacks it to `\apps\ai-memory\` and points the `\apps\ai-memory\current` junction at it. The `ai-memory` shim on `PATH` runs the binary through `current`. `ai-memory setup` records that `current` path in the logon entry, the hook commands and the MCP entries, never the version directory, so they keep working after `scoop update ai-memory` installs the next version and `scoop cleanup` deletes the old one. Update with `scoop update ai-memory`: `ai-memory upgrade` refuses a Scoop install, because the bucket owns the version. To do the same by hand: ```powershell # First-time install: download + extract into a stable per-user directory # (any stable path works; the native hook exec-form command is rendered from # wherever ai-memory.exe lives). $Dest = "$env:LOCALAPPDATA\Programs\ai-memory" New-Item -ItemType Directory -Force $Dest | Out-Null Invoke-WebRequest ` -Uri "https://github.com/akitaonrails/ai-memory/releases/latest/download/ai-memory-windows-x86_64.zip" ` -OutFile "$env:TEMP\ai-memory.zip" Expand-Archive "$env:TEMP\ai-memory.zip" -DestinationPath $Dest -Force Get-ChildItem "$Dest\ai-memory.exe" | Unblock-File # Put it on PATH for future terminals (optional but convenient). The registry # value is read and written as is, so its %VAR% entries stay unexpanded. $EnvKey = [Microsoft.Win32.Registry]::CurrentUser.CreateSubKey("Environment") $UserPath = $EnvKey.GetValue("Path", "", "DoNotExpandEnvironmentNames") if (($UserPath -split ';' | ForEach-Object { [Environment]::ExpandEnvironmentVariables($_) }) -notcontains $Dest) { $EnvKey.SetValue("Path", "$UserPath;$Dest", "ExpandString") # Removing a variable that does not exist broadcasts the change to Explorer. [Environment]::SetEnvironmentVariable("ai-memory-path-notify", [NullString]::Value, "User") $env:Path = "$env:Path;$Dest" } $EnvKey.Dispose() # Wire MCP + lifecycle hooks against your server. & "$Dest\ai-memory.exe" install-mcp --client claude-code --apply & "$Dest\ai-memory.exe" install-hooks --agent claude-code --apply ` --server-url "https://memory.example.com" --auth-token "" ``` Later updates for this install (not a Scoop one, which updates with `scoop update ai-memory`) 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. It also re-renders existing ai-memory-owned OpenCode, OpenCode 2, OMP, Pi, and OpenClaw TypeScript integrations from the newly installed binary's templates at their default or active-profile paths; absent and user-owned files are left untouched. 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`, `LICENSE`, and `docs/{install,windows}.md`. Because `install-hooks` reads the `ai-memory.exe` path from the running binary, keep the extracted `.exe` at a stable location (re-run `install-hooks` if you move it). Without `ai-memory setup`, the server runs only while a terminal is open. To keep it up, run `setup` or continue to [Scenario E](#scenario-e-keep-the-server-running-native-windows-service). ## Scenario D: Native Windows Source Build Use this when developing ai-memory itself on Windows or when you do not want the Docker wrapper for CLI commands. ```powershell git clone https://github.com/akitaonrails/ai-memory .\ai-memory Set-Location .\ai-memory cargo build --workspace cargo test --workspace target\debug\ai-memory.exe init target\debug\ai-memory.exe serve --transport http --bind 127.0.0.1:49374 ``` That last command holds the terminal. For a persistent server, see [Scenario E](#scenario-e-keep-the-server-running-native-windows-service). ### If the build fails with `os error 4551` On a machine with **Smart App Control** or **App Control for Business** enforced, `cargo build` can fail before compiling anything of ours: ``` error: failed to run custom build command for `proc-macro2` An Application Control policy has blocked this file. (os error 4551) ``` Re-installing Rust will not fix it, because the toolchain is fine. Cargo compiles each crate's `build.rs` into an unsigned executable under `target\debug\build\`, and those policies block unsigned binaries from running out of user-writable directories. `proc-macro2` and `icu_properties_data` are usually the first to hit it because they build early. Add a path exclusion for the checkout's `target` directory (or build inside a location your policy already trusts). Reported by @CaioCoelhoChaves while running the measurements in #478. For release validation from Git Bash on native Windows, use the same checkout with the Rust MSVC toolchain active: ```bash cargo test --workspace cargo build --locked --release -p ai-memory-cli ./target/release/ai-memory.exe --version ``` The version output should match the package version for the checkout. Normal builds use the vendored stylesheet and download nothing. Regenerating it (`TAILWIND_BUILD=1 cargo build -p ai-memory-web`) supports the pinned `tailwindcss-windows-x64.exe` binary and falls back to PowerShell `Invoke-WebRequest` when `curl`/`wget` are unavailable. Keep Git for Windows' `git.exe` on `PATH` for native builds and hook runs. When libgit2 hits a Windows path-resolution error while opening a newly initialized wiki repository, ai-memory falls back to the Git CLI instead of treating that specific condition as fatal. From another PowerShell window in the repo: ```powershell target\debug\ai-memory.exe install-mcp --client claude-code --apply target\debug\ai-memory.exe install-hooks --agent claude-code --apply ``` Native Windows builds render agent-specific host-native lifecycle commands. Claude Code may use its supported binary exec form (see below); other agents use native single command strings matching their hook schema. The bundled `.sh` and `.ps1` event scripts are compatibility fallbacks and do not enforce capture-policy v1; tests enforce one-to-one event/agent parity between them. ### Capture-policy support Native `ai-memory.exe hook` commands enforce the nearest-marker `[capture] ignore_paths` policy before spool or network delivery. The legacy `.ps1` and `.sh` paths do not. After upgrading, rerun `install-hooks --agent --apply` to refresh native hook entries; selected-install capability output says whether enforcement is active. See [Capture exclusions](marker-file.md#capture-exclusions). ## Scenario E: Keep The Server Running (Native Windows Service) Scenarios C and D both end at `ai-memory serve` in a foreground terminal. That works for a trial but not for daily use: when you close the window, log off, or reboot, the server stops. ### The logon entry `ai-memory setup` installs `ai-memory setup` keeps the server running for as long as you are signed in, with no administrator rights and no password stored anywhere: 1. It writes an `ai-memory` value under `HKCU\Software\Microsoft\Windows\CurrentVersion\Run`, the per-user key Windows runs at every logon: `"\ai-memory.exe" --data-dir "" --config "" service-host`. 2. It starts that command once right away, so the server answers before your next logon. 3. `service-host` starts a copy of itself detached from any console and exits, so the logon console closes at once. The copy runs `serve --transport http --enable-web` with a hidden console, which the Git CLI fallback and any provider CLI the server starts inherit instead of opening windows of their own. 4. When the server exits with an error, the host starts it again after five seconds, the way the Linux unit's `Restart=on-failure` does. After five failures within ten seconds of starting (another server already on the port, a broken config) it stops trying; run `ai-memory serve --transport http` in a terminal to see the error. The host records its own process id and the server's in `\service-host.json`. A second `setup` leaves a current entry with a running host alone; a changed entry is rewritten and the host restarted. `ai-memory uninstall --apply` stops the host and deletes the value, but only when the value still has the shape `setup` writes (a quoted `ai-memory.exe` ending in `service-host`) and its `--data-dir` is the data dir being uninstalled; a value someone else put under the same name, or the entry of another install, is left in place. `setup` and `uninstall` read and write the value through the registry API rather than running `reg.exe`. Endpoint protection that watches for persistence (Bitdefender's Advanced Threat Control, for one) treats an unsigned program running `reg.exe add` on the `Run` key as malicious and quarantines it (#1280). Stopping the host avoids `taskkill` for the same reason. `setup` and `uninstall` write `\service-host.stop`; the host checks for it four times a second, kills the server through the process handle it already holds, and exits. Only when the host has not exited after ten seconds (a host started by an older binary, or a hung one), or when the server outlived its host, do they fall back to `taskkill /T /F` on the recorded process ids, after checking that each id still belongs to the same ai-memory process. The cooperative stop (`Child::kill`) terminates only the server process itself, not its process tree, so a subprocess the server started (a CLI-based LLM provider in the middle of a consolidation, for one) can linger until it finishes on its own. The logon entry runs only while you are signed in, which matches a systemd user unit without lingering and a macOS LaunchAgent. For a server that runs before anyone signs in, or for other users of the machine, use a real Windows service through WinSW, below, and pass `--no-service` to `setup`. ### Antivirus / EDR Behaviour-based endpoint protection watches for programs that make themselves start at logon, and `ai-memory.exe` is unsigned. Bitdefender's Advanced Threat Control has quarantined it after `setup` wrote the logon entry ([#1280](https://github.com/akitaonrails/ai-memory/issues/1280)). `setup` avoids the signals known to weigh in that decision: - It writes and reads the `Run` value through the registry API. It never runs `reg.exe add` on the `Run` key. - The value holds plain paths, without the `\\?\` prefix a canonical path carries. - Stopping the host is cooperative (#1300): the host stops the server through a request file in the data dir, as described above, and `taskkill` runs only as the fallback for a host that does not answer. That lowers the odds but guarantees nothing; a product can still flag an unsigned binary on its own rules. **How to tell.** A quarantine removes `ai-memory.exe` and leaves the `Run` value behind. The server then never starts at logon, and the hooks keep calling a path that is gone. `ai-memory doctor` and `ai-memory status` (from any copy of the binary that still exists) check the entry `setup` wrote for their data dir and warn with `logon_binary_missing` when the `ai-memory.exe` it names is no longer there. The warning is also in their `--json` output, and `status` prints it even when it cannot reach the server, which is the usual state once the binary is gone. Your antivirus console or quarantine list shows the detection itself. **What to do.** Restore the binary from quarantine, or put it back by reinstalling, and ask whoever runs the antivirus to allow it (on a managed machine that is an administrator change). Then re-run `ai-memory setup`, which points the entry at the binary you ran it from and starts the host. To stop using the logon entry instead, remove it: `ai-memory uninstall --apply` removes it along with the rest of ai-memory's wiring, or delete only the value: ```powershell Remove-ItemProperty -Path HKCU:\Software\Microsoft\Windows\CurrentVersion\Run -Name ai-memory ``` `setup --no-service` skips writing the entry but does not remove one that already exists. Without the entry, run `ai-memory serve --transport http` in a terminal or use the WinSW service below. #### Security suites that rewrite AI-tool traffic Some consumer security suites intercept the network traffic of programs they classify as AI tools, and of the processes those tools start. This covers plain `http://` traffic too, not only HTTPS. A product that re-frames the server's response on the way back hands the client a malformed body, and the bridge and hooks fail while the server itself is healthy. This was seen with the Safe AI feature of Norton 360 Deluxe 26.10, on processes started by Antigravity talking to an `http://` server URL. Avast and AVG come from the same vendor and may behave the same way. Only the applications the product recognizes are affected. On the machine above, Safe AI listed Claude, Claude Code, Google Antigravity IDE and Visual Studio Code; DeepSeek Harness and Hermes Agent were not on the list, and their bridge and hooks to the same server kept working. The list grows with product updates, so an agent that works today can start failing after one. One agent failing while another on the same machine works points at this cause rather than at the server. **Symptoms.** `ai-memory mcp-bridge` or `ai-memory hook` fails with an HTTP decoding error such as `Invalid chunk size line: missing size digit`. The response arrives with `Transfer-Encoding: chunked` in place of `Content-Length`, but the body is not chunk-encoded. The same request from a terminal you opened yourself succeeds. MCP tools and hook capture stop together, and only for the agent the product protects. **How to tell.** Look for the agent in the product's list of protected AI tools (in Norton: Safe AI, the tab listing your AI tools). If the error goes away after you turn the feature off and restart the agent, the product was the cause. **What to do.** Turn the feature off (in Norton, switch off Safe AI), then restart the agent so the bridge reconnects. This is a different problem from the untrusted interception root in [HTTPS via a reverse proxy](https-via-proxy.md#outbound-llm-calls-fail-behind-a-tls-inspecting-firewall): it happens on plain HTTP as well, and installing the product's root certificate does not fix it. ### A real Windows service A Windows service, unlike the logon entry, runs without anyone signed in. It needs a **service wrapper**, because ai-memory does not implement a Windows Service control-code dispatcher, so `sc create` or `New-Service` pointed straight at `ai-memory.exe` will not work: the SCM starts the process, waits for it to report in, never hears from it, and kills it. ### ⚠️ Do not launch the server from a Scheduled Task with `Start-Process` **Symptoms: `LastTaskResult = 0` reports success forever, the server is gone after every reboot, and there is no crash dialog, no Application Error event, and no further line in the server log after its startup line.** This warning exists because the only visible status is a green one. The broken shape is a task whose action is `powershell.exe -File start-server.ps1`, where the script calls `Start-Process` to launch `ai-memory.exe`: 1. The task fires and `powershell.exe` runs the script. 2. `Start-Process` launches `ai-memory.exe` and returns **immediately**; it does not wait for the child. 3. The script has nothing left to do, so `powershell.exe` exits. Task Scheduler records the instance as completed with return code 0 (operational-log events 201/102). 4. Task Scheduler runs each task instance inside a **job object**. When the action process exits, the job is torn down and every process still assigned to it is terminated. `ai-memory.exe` was started as a child of the task's PowerShell and never broke away from the job, so it dies with it, in the same second it started. The server's log therefore contains exactly one line, its own startup line, and nothing after it. **If you specifically want Task Scheduler**, remove the wrapper: point the task action at `ai-memory.exe` directly, with `serve` in the arguments, so the process Task Scheduler monitors *is* the server and stays in the job for as long as it runs. Then also: - run the task **whether the user is logged on or not**, so it survives logoff and starts without an interactive session; - clear the default **3-day execution time limit** (`-ExecutionTimeLimit ([TimeSpan]::Zero)`), which otherwise stops a healthy long-running server; - set restart-on-failure explicitly (`-RestartCount`, `-RestartInterval`). A task has no `Restart=on-failure` unless asked. Even with those fixes it is still a task standing in for a service, so prefer the wrapper below. ### WinSW [WinSW](https://github.com/winsw/winsw) wraps any console binary as a real Windows Service. Its config is a single XML file that sits beside the executable, and it needs no separate service-manager install. WinSW derives its config filename from its own, so **rename the downloaded executable and give the XML the same base name**: ```powershell $Dest = "$env:LOCALAPPDATA\ai-memory" # Download the WinSW release matching your runtime (.NET Framework 4.6.1+ # or the self-contained .NET build) from https://github.com/winsw/winsw/releases # Pin a specific release tag rather than "latest", and keep a note of which # one you installed — it is a third-party binary running as a service. Move-Item .\WinSW-x64.exe "$Dest\ai-memory-service.exe" ``` `ai-memory-service.xml`, beside it. Substitute your own expanded `$Dest` for `C:\Users\you\AppData\Local\ai-memory`, and spell it out rather than leaving a variable in the file: ```xml ai-memory ai-memory MCP server Long-term memory server for AI coding agents. C:\Users\you\AppData\Local\ai-memory\ai-memory.exe --data-dir "C:\Users\you\AppData\Local\ai-memory" serve --transport http --bind 127.0.0.1:49374 Automatic ``` `` is the SCM recovery action that mirrors the units' `Restart=on-failure` + `RestartSec=5s`. **Use absolute paths here, not `%LOCALAPPDATA%`.** A Windows service runs as `LocalSystem` unless you say otherwise, and `%LOCALAPPDATA%` expands against *that* account (`C:\Windows\System32\config\systemprofile\AppData\Local`), so the service would serve an empty data directory somewhere you never look while your real wiki sits untouched in your profile. Either write the path out in full as above, or add a `` block so the service runs as your user. Install and start it: ```powershell & "$Dest\ai-memory-service.exe" install & "$Dest\ai-memory-service.exe" start & "$Dest\ai-memory-service.exe" status # Verify the server is actually answering, not merely "Running". Get-Service ai-memory ai-memory status ``` `stop`, `restart`, and `uninstall` are the remaining commands. Because the bind is loopback, the service account does not affect reachability: agents running as your user still reach `127.0.0.1:49374`. ### ⚠️ Run the service as the owning user when the data dir is in a profile The absolute `--data-dir` above stops the *empty-directory* trap, but it does **not** make a `LocalSystem` service safe over a data directory that lives under your user profile (`C:\Users\you\AppData\Local\ai-memory`). The data directory is account-sensitive, and so is the **wiki's git repository inside it**. libgit2 enforces the same dubious-ownership guard as Git itself (CVE-2022-24765): when the process account is not the owner of the repository, every commit fails with `code=Owner (-36)`. The server still starts, capture still works, and search still answers, but the wiki git history silently stops advancing because a wiki commit failure is not fatal. As of ai-memory 2.4.x the server logs this at **ERROR** on startup with the same remedy below; on older builds it was a WARN that was easy to miss. **Whenever the data directory lives under a user profile, run the service as that user** rather than as `LocalSystem`. In the WinSW XML add a `` block: ```xml . you your-account-password true ``` (or set it from the service's **Log On** tab in `services.msc` after install, then `restart`). This is the WinSW v2.12.0 XML shape used by this guide. For a local account, keep `.`; for a domain account, put the domain in `` and the account name in ``. WinSW v3 uses the combined `DOMAIN\you` form instead, so follow the schema for the release you pinned. Add the block before the first `install`. If the service is already installed, stop and uninstall it, update the XML, then install and start it again. Verify the account recorded by the Service Control Manager rather than relying only on the wrapper's running state: ```powershell Get-CimInstance Win32_Service -Filter "Name='ai-memory'" | Select-Object Name, StartName, State ``` `StartName` must name the intended account, not `LocalSystem`. `LocalSystem` is only appropriate when the data directory is in a location that account owns outright (e.g. a dedicated `C:\ProgramData\ai-memory` created and owned by the service account). > **WinSW error 1069 / stale password.** If `start` fails with *"The > service did not start due to a logon failure"* (error 1069), the > `` credentials are wrong or stale. This bites > **Microsoft-account, PIN, and Windows Hello** users especially: the > WinSW `` must be your *account password*, which for a > Microsoft account is your online Microsoft password (not your PIN or > Hello gesture), and it must be updated in the service config whenever > that password changes, because Windows does not roll it forward. Consider a > local account, or a dedicated service account with a non-expiring > password, for an unattended service. Keep running `install-mcp` and `install-hooks` **as your own user**, not as the service. They write per-user agent config, and the rule at the top of this page still applies. > Verified from the WinSW project documentation and the ai-memory CLI > surface, then run end to end on real hardware by the reporter of > [#530](https://github.com/akitaonrails/ai-memory/issues/530), who also > root-caused the job-object failure mode above from the Task Scheduler > event IDs. > > **Validated on** Windows 11 25H2 (build 26200.9168) with WinSW v2.12.0 > (`WinSW-x64.exe`) and ai-memory v1.38.0, from an elevated PowerShell > session, against a throwaway service id, port and data directory. > Confirmed: `install`; `start`; the service `Running` as `LocalSystem` > with `StartType Automatic`; an MCP `initialize` answered over the bound > port; the absolute `--data-dir` honoured, with no > `systemprofile\AppData\Local\ai-memory` created; crash recovery (the > wrapped `ai-memory.exe` was force-killed and a new process was answering > 8s later), consistent with the 5-second `` delay plus startup; > and a clean `stop` + `uninstall`. The service was configured with > `StartType Automatic`; actual boot-time startup was not independently > exercised. At the time of this validation (2026-08-31), v2.12.0 was the > latest stable WinSW release; the published 3.x releases were > prereleases. Corrections from anyone running a different Windows or > WinSW version are welcome. ## Native Hook Command (Claude Code on Windows) By default on native Windows, Claude Code hooks are rendered using Claude's exec form: `command` is the real `ai-memory.exe` path and `args` is an argv array. This directly spawns the binary instead of sending one quoted string to a shell or using a `bash -c` wrapper around a `.sh` script: ```json { "type": "command", "command": "C:\\Users\\you\\.cargo\\bin\\ai-memory.exe", "args": ["hook", "--event", "pre-tool-use", "--agent", "claude-code", "--server-url", "http://host:49374", "--auth-token", "..."] } ``` This avoids spawning Git Bash plus `cat`/`sed`/`curl` child processes on every tool call. Process spawning is expensive on Windows, so the native path is roughly 3-5× faster per hook (measured ~735 ms shell → ~150-205 ms native on an i7-6700HQ). Notes: - The binary path comes from the `ai-memory` that runs `install-hooks`, so `cargo install --locked --path crates/ai-memory-cli` puts it on a stable `~/.cargo/bin` path. - Exec form requires a real executable path (`.exe`). It does not run `.cmd` or `.bat` shims through a shell. `install-hooks` uses the path of the running `ai-memory.exe`, so release binaries and Cargo-built binaries work directly. - The `.sh`/`.ps1` scripts stay bundled as a fallback: the Docker / `setup-agent` flow (no local binary) keeps emitting the shell command. For outage parity with the native hooks, both script bundles spool an undeliverable event (connection failure, timeout, 5xx) to the same `/hook-spool/` contract `ai-memory hook-drain` reads, and flush the backlog after the next successful delivery; a terminal 4xx is not retried. - `AI_MEMORY_HOOK_PLATFORM` accepts five values: - `windows-native`: Claude exec-form direct binary call (default on native Windows). - `windows`: PowerShell `-EncodedCommand` + staged `.ps1` script. This is the native Windows Docker-wrapper default because the helper container cannot install its Linux binary into a host hook entry. - `windows-bash`: `bash -c` + `.sh` through Git Bash (the previous default; set this to opt back in, or as a fallback for older Claude Code builds that do not support exec form). - `posix`: POSIX `.sh`. An explicit Linux/macOS Docker-wrapper compatibility fallback; set it to opt a native install back into the scripts. - `posix-native`: direct binary call on macOS / Linux (` hook --event …`) instead of the `.sh` script, so the hook uses the local event spool + OIDC-token fallback. The **default for native macOS / Linux Claude Code installs** (cargo / release binary), mirroring `windows-native`. The Linux/macOS Docker wrapper uses its checksum-verified native host client by default; set `posix` explicitly to keep the `.sh` scripts. Set the env var before running `install-hooks` so the chosen platform is baked into the rendered hook commands. Project auto-scope treats Windows backslashes and POSIX slashes as the same path separator when comparing hook `cwd`, stored `repo_path`, and the home-directory catch-all guard. Wrappers or tests that need a host home different from the process `HOME` can set `AI_MEMORY_HOME`; it is normalized through the same path boundary before startup healing or cwd-prefix matching. ### Tuning the spool timings (high-latency instances) The native hook spools events locally. Session start does a short bounded cleanup drain before fetching a handoff; session end starts a detached `hook-drain` helper so Claude Code and other agents are not kept open by a large backlog. The built-in timings stay short on agent-facing paths, but high-latency or large-backlog instances can raise them with whole-minute overrides. Unlike `AI_MEMORY_HOOK_PLATFORM`, these are read by the hook **at runtime**, so they apply to the agent's environment (no re-`install-hooks` needed): Native hooks accept well-formed JSON with or without one leading UTF-8 BOM, as some PowerShell pipelines add that marker when writing to a native process. The server's `/hook` ingress skips the same marker, so a shell-bundle hook that forwards it unchanged is still stored. Any other malformed stdin is not spooled or sent; the hook prints a fixed warning to stderr, returns `{}` on stdout, and exits successfully so it cannot break the host agent. The warning never includes payload contents. | Env var | Built-in default | Max override | What it caps | |---|---:|---:|---| | `AI_MEMORY_HOOK_DRAIN_TIMEOUT_MINUTES` | 3 seconds | 60 minutes | each event POST during a drain | | `AI_MEMORY_HOOK_HANDOFF_TIMEOUT_MINUTES` | 3 seconds | 60 minutes | the synchronous `session-start` handoff GET | | `AI_MEMORY_HOOK_START_BUDGET_MINUTES` | 3 seconds | 60 minutes | total time `session-start` may spend waiting for the drain lock and cleanup draining | | `AI_MEMORY_HOOK_BACKGROUND_DRAIN_BUDGET_MINUTES` | 5 minutes | 60 minutes | total time the detached `hook-drain` helper may spend after `session-end` | | `AI_MEMORY_HOOK_INCREMENTAL_THRESHOLD` | 32 events | positive integer | spool backlog size that triggers a 250 ms `post-tool-use` catch-up drain | | `AI_MEMORY_HOOK_SPOOL_MAX_ATTEMPTS` | 8 failed passes | non-negative integer | failed drain passes before dropping an event; `0` disables only attempt-count drops | The retry setting can also be written as `max_attempts` under `[hook_spool]` in `/config.toml`; the runtime environment wins when both are set. A zero value still leaves the 7-day age limit and 10,000-file spool cap active. Timing values must be positive whole minutes. Missing, empty, non-numeric, or zero values fall back to the built-in defaults; values above 60 are clamped. The incremental threshold is a positive event count; invalid values fall back to 32. The session-start budget caps how long the hook may block before handoff fetch; the background budget caps detached cleanup after session-end and does not keep the agent waiting. On Windows, a contended drain lock can be reported as the native `ERROR_LOCK_VIOLATION` code instead of Rust's `WouldBlock` error kind. ai-memory treats both as normal lock-busy states, so concurrent drains wait, skip, or expire according to the same spool timing rules instead of failing the hook. ## Support Tier: Experimental → Supported Exit Criteria Native Windows is currently an **Experimental** tier. This is the checklist a maintainer uses to decide whether it can be promoted to **Supported**. It records status only; the tier has not changed. Each item is marked **done**, **in-progress**, or **deferred-pending-policy**, from what the repository actually ships today. - **CI trigger coverage: done.** `.github/workflows/windows.yml` runs on a nightly `schedule`, on `workflow_dispatch`, and on pull requests. A pull request that touches platform-sensitive code (path handling, file locking, git plumbing, the hook bundle: `crates/ai-memory-{wiki,store,hooks}/**`, `crates/ai-memory-cli/src/commands/install_hooks.rs`, `hooks/**`, `tests/hooks/**`, and the workflow itself) now opts in automatically via the workflow's leading `changes` job (`dorny/paths-filter`, SHA-pinned); the `windows` label remains a manual override for PRs outside those paths, so coverage does not depend on someone remembering the label. - **Hook-bundle Windows job: done.** The `hooks` job in `windows.yml` runs `tests/hooks/test_lib.sh` on `windows-latest`. That suite drives `hooks/lib/ai-memory-hook.ps1`, whose PowerShell branch only ever executes natively on Windows, so CI now exercises that PowerShell code on the platform it targets instead of leaving it to a contributor's machine. - **`#[cfg(windows)]` regression coverage: in-progress.** The Windows-only regression tests that no Linux/macOS leg can compile run here: the drain-lock `ERROR_LOCK_VIOLATION` busy-state handling, the libgit2 path-resolution fallback to the Git CLI when opening a freshly initialized wiki repository, and verbatim (`\\?\`) path handling (see the header of `windows.yml` and Scenario D above). This coverage exists for the platform code that has hit a documented bug. The current tests exist; the item stays **in-progress** because each new Windows path-, lock-, or git-touching change is expected to add its own `#[cfg(windows)]` regression before promotion. - **`.exe` code-signing: deferred-pending-policy.** Release binaries and the `build.rs` helper executables Cargo emits are unsigned. On machines enforcing **App Control for Business** or **Smart App Control**, unsigned binaries run from user-writable directories are blocked. This is the `os error 4551` build failure documented in Scenario D, and it can equally block an unsigned released `ai-memory.exe`. Signing needs a code-signing certificate and a decision on how its private material is held as a CI secret (and rotated). Both are maintainer/policy calls, so this item is deferred until that decision is made; it is a blocker for a frictionless Supported experience on Application-Control-enforced fleets. - **Native `ai-memory upgrade` path: done.** `ai-memory upgrade` upgrades a writable native install in place (#801, #802): it verifies the `ai-memory-windows-x86_64.zip` checksum, replaces `ai-memory.exe` by rename-aside, refreshes a sibling `hooks/` tree, and re-stages installed hooks (see Scenario C). A non-writable prefix (for example under Program Files) still upgrades through the manual download/extract sequence. Promotion to Supported is the maintainer's decision once the in-progress items are closed and the deferred code-signing policy is resolved (or explicitly accepted as out of scope for the tier). ## Current Harness Caveats Windows hook support is new and needs real-world testing against native Windows agent builds. - There is no Windows Service dispatcher in `ai-memory.exe`; persistence comes from a wrapper ([Scenario E](#scenario-e-keep-the-server-running-native-windows-service)), the same way it comes from systemd on Linux. - Claude Code may be used natively on Windows or from inside WSL2. Native Claude Code invokes hooks as a direct binary call (no shell) by default; `AI_MEMORY_HOOK_PLATFORM=windows-bash` restores the Git Bash `bash -c` path. WSL2 Claude Code uses normal WSL `.sh` paths. - Codex, Command Code, Devin CLI, OpenCode, Cursor, Gemini CLI, Antigravity CLI, Grok Build CLI, Zero, Kimi Code, and OpenClaw may each choose different Windows config locations or shell execution behavior. ai-memory uses the current best-known defaults, but they need validation on real installations. - MCP over HTTP should be less path-sensitive than hooks, but `install-mcp --apply` still writes to a client-specific config file; confirm the agent actually loads it. - OpenClaw, OpenCode (V1 `ai-memory.ts` or V2 `ai-memory-opencode2.ts`, selected from the resolved executable major), OMP / Oh My Pi, and Pi use generated TypeScript integrations rather than the shell hook bundle, so their Windows behavior depends on the host runtime loading those files correctly. Pi's generated extension also bridges MCP tools because Pi has no native `mcp.json` install surface. ## Suggested Test Checklist For WSL2: 1. Run all install commands inside WSL2. 2. Confirm generated hook commands reference `.sh` files under WSL paths. 3. Launch the agent from WSL2. 4. Call `memory_status` from the agent. 5. Record `ai-memory status`, send a prompt, then confirm its `sessions` or `observations` count increased. For native Windows: 1. Run all install commands from PowerShell or `cmd.exe` using `ai-memory` / `ai-memory.ps1`. 2. Confirm generated hook commands match the agent: Claude Code should use the native `"…ai-memory.exe" hook --event …` command (or `bash -c` + `.sh` when `AI_MEMORY_HOOK_PLATFORM=windows-bash`); other script-hook agents should use `powershell.exe ... -EncodedCommand ` entries for the generated `.ps1` hooks under your Windows home directory. 3. Launch the native Windows agent. 4. Call `memory_status` from the agent. 5. Record `ai-memory status`, send a prompt, then confirm its `sessions` or `observations` count increased. Report which mode you tested, which agent and version you used, and whether the hook command executed or failed with a path/shell error. The built-in `/web` browser lists compiled wiki pages; zero pages there does not mean the raw hook observations were missed.