Skip to content

Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors

Rust

docs(windows): add Scenario E, a persistent-server story for native Windows (#530) (#545)

Fabio Akita6ed84bcb240d
diff --git a/CHANGELOG.md b/CHANGELOG.md
index b5cfaa4b..dfb062b4 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -126,6 +126,28 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
drain honouring `AI_MEMORY_SERVER_URL` would send captured events to whatever
address happened to be exported into the process that ran it.
+### Docs
+
+- `docs/windows.md` gains **Scenario E**, a persistent-server story for native
+ Windows. Scenarios C and D both ended at `ai-memory serve` in a foreground
+ terminal, while Linux got `Restart=on-failure` from the packaged systemd
+ units; WinSW is now documented as the equivalent supervisor (#530).
+
+ It leads with the trap rather than the recipe. A Scheduled Task whose action
+ is a PowerShell script calling `Start-Process` looks correct and is silently
+ killed at the next reboot: `Start-Process` returns immediately, the script
+ exits, and Task Scheduler tears down the job object the still-running server
+ was never detached from. The only symptom is a permanently green
+ `LastTaskResult = 0`, which is why it costs hours. Reported and root-caused
+ with event-log evidence by @gabrielscharb.
+
+ Also documented: `sc create` against `ai-memory.exe` cannot work (no SCM
+ control-code dispatcher, and none is planned — the resiliency belongs in the
+ supervisor, as it does on Linux); the corrected Task Scheduler shape for
+ anyone who wants one anyway; and why the WinSW config must use absolute paths
+ — a service runs as `LocalSystem`, so `%LOCALAPPDATA%` would resolve to the
+ system profile and quietly serve an empty data directory.
+
## [1.38.0] - 2026-08-30
### Added
diff --git a/docs/windows.md b/docs/windows.md
index f568578e..38424e29 100644
--- a/docs/windows.md
+++ b/docs/windows.md
@@ -14,6 +14,11 @@ Antigravity CLI, or another agent.
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`; that looks like it
+ works 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
@@ -206,6 +211,10 @@ assets: it contains `ai-memory.exe`, the full `hooks/` bundle (`.ps1` +
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).
+This leaves the server running only while a terminal is open. To keep it
+up across logoff and reboot, 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
@@ -221,6 +230,9 @@ 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**
@@ -284,6 +296,142 @@ ignore_paths` policy before spool or network delivery. The legacy `.ps1` and
--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 is fine for a trial and wrong for daily use: close the window, log
+off, or reboot, and the server is gone.
+
+On Linux the packaged units in `packaging/systemd/` supply
+`Restart=on-failure` and `RestartSec=5s`. Note where that resiliency
+lives — systemd performs the restarts, not ai-memory. Native Windows
+gets the same bargain through a **service wrapper**. 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.** A failure whose only symptom is a green status is why this
+warning exists.
+
+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
+ perfectly healthy long-running server;
+- set restart-on-failure explicitly (`-RestartCount`,
+ `-RestartInterval`). A task has no `Restart=on-failure` unless asked.
+
+Even corrected, that is a task pretending to be a service. 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` — spell it out rather than
+leaving a variable in the file:
+
+```xml
+<service>
+ <id>ai-memory</id>
+ <name>ai-memory MCP server</name>
+ <description>Long-term memory server for AI coding agents.</description>
+ <executable>C:\Users\you\AppData\Local\ai-memory\ai-memory.exe</executable>
+ <arguments>--data-dir "C:\Users\you\AppData\Local\ai-memory" serve --transport http --bind 127.0.0.1:49374</arguments>
+ <startmode>Automatic</startmode>
+ <onfailure action="restart" delay="5 sec"/>
+ <log mode="roll"/>
+</service>
+```
+
+`<onfailure action="restart" delay="5 sec"/>` 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 quietly 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 `<serviceaccount>` 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`. Only the data
+directory is account-sensitive, which is what the absolute path above
+settles.
+
+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 (3.x; requires .NET
+> Framework 4.6.1+ or the self-contained .NET build) and from the
+> ai-memory CLI surface. The job-object failure mode was root-caused on a
+> real Windows install by the reporter of
+> [#530](https://github.com/akitaonrails/ai-memory/issues/530), including
+> the Task Scheduler event IDs above. The WinSW steps themselves have not
+> been executed by a maintainer on Windows hardware — corrections from
+> anyone who runs them, especially the Windows and WinSW versions they
+> were true for, are welcome.
+
## Native Hook Command (Claude Code on Windows)
By default on native Windows, Claude Code hooks are rendered using Claude's
@@ -381,6 +529,11 @@ hook.
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`